vexp-cli 3.3.9 → 3.4.0

package/dist/agent-config.js

@@ -2,9 +2,10 @@
  * Agent auto-detection and configuration for the vexp CLI.
  *
  * Ported from packages/vexp-vscode/src/providers/agent-auto-config.ts
- * with VS Code dependencies removed. Uses the Rust binary path
- * (`~/.vexp/bin/vexp-core mcp`) as the MCP command instead of
- * `node <mcp-server.cjs>`.
+ * with VS Code dependencies removed. The MCP command is the npm package's
+ * own binary (`<npm>/@vexp/core-<platform>/bin/vexp-core mcp`, the
+ * version-free path getBinaryPath returns) or `node <mcp-server.cjs>` when
+ * the bundle ships; nothing creates a `~/.vexp/bin` launcher.
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -12,8 +13,10 @@ import * as os from "os";
 import { spawnSync } from "child_process";
 import * as crypto from "crypto";
 import { canonicalWorkspaceRoot } from "./socket-path.js";
-import { readAgentConsent, consentKey, decisionForKey } from "./agent-consent.js";
+import { readAgentConsent, decisionsFor } from "./agent-consent.js";
+import { linkedWorktreeMain, sameRepositoryCheckout } from "./git-worktree.js";
 import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSubagentHookScript, vexpSearchHookScript, vexpHintHookCmdScript, codexWindowsHookCommand, opencodeFamilyAgent, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin, vexpOpencodeCompressPlugin, bakeEditHintHook, bakeReadHintHook, bakeBashCapHook, upperDriveLetter } from "./hook-template.js";
+import { committedHookScriptLine, committedHookScriptStays, readHookScript } from "./hook-scripts.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -149,6 +152,36 @@ function windsurfOnThisMachine() {
         }
     });
 }
+/**
+ * Does this machine show Antigravity? What Antigravity itself leaves under
+ * ~/.gemini (measured with agy 1.5.3, 2026-11-07): anything in
+ * ~/.gemini/antigravity beside mcp_config.json and its backup (vexp up to
+ * 3.3.9 created that folder and that file itself, on machines that never
+ * had Antigravity, so they prove nothing); the agy CLI's app data,
+ * ~/.gemini/antigravity-cli; the marker every Antigravity surface writes at
+ * its first start, ~/.gemini/config/.migrated; or the agy binary the VS Code
+ * extension downloads to ~/.gemini/bin. The same test as
+ * windsurfOnThisMachine: vexp's own leftover folder made every project on
+ * the machine offer Antigravity, and GEMINI.md set it up unasked. Lockstep
+ * with the extension, which can also ask the editor it runs in; a terminal
+ * has no editor to ask, and `--agents Antigravity` is there for that case.
+ */
+export function antigravityOnThisMachine() {
+    const gemini = path.join(os.homedir(), ".gemini");
+    try {
+        if (fs.readdirSync(path.join(gemini, "antigravity")).some((e) => e !== "mcp_config.json" && e !== "mcp_config.json.vexp-bak")) {
+            return true;
+        }
+    }
+    catch {
+        /* no such folder */
+    }
+    if (isDirectory(path.join(gemini, "antigravity-cli")))
+        return true;
+    if (fs.existsSync(path.join(gemini, "config", ".migrated")))
+        return true;
+    return ["agy", "agy.exe"].some((bin) => fs.existsSync(path.join(gemini, "bin", bin)));
+}
 const AGENT_DETECTORS = [
     {
         agent: "Claude Code",
@@ -311,14 +344,26 @@ const AGENT_DETECTORS = [
         agent: "Antigravity",
         // Antigravity keeps NO workspace marker dir of its own: it reads the
         // cross-tool AGENTS.md (v1.20.3+), GEMINI.md, and .agent/rules/ from
-        // the workspace, and stores its global state under ~/.gemini/antigravity.
+        // the workspace, and keeps its app data under ~/.gemini/antigravity.
+        // `.agents` is no marker: ZCode's .agents/mcp.json, Agent Skills and
+        // vexp's own .agents/mcp_config.json live there too.
+        //
+        // GEMINI.md and .agent are committed for the teammates who use
+        // Antigravity, so, as for Windsurf, they set it up without a question
+        // only where the machine shows Antigravity (antigravityOnThisMachine);
+        // elsewhere they are a hint and the user is asked. The machine-only
+        // marker is the same evidence, not the bare ~/.gemini/antigravity
+        // folder, which vexp itself created up to 3.3.9. Lockstep with the
+        // extension.
         detectPath: "GEMINI.md",
         detectPaths: [".agent"],
-        detectHome: ".gemini/antigravity",
+        onThisMachine: antigravityOnThisMachine,
+        detectMachine: antigravityOnThisMachine,
         configFile: "AGENTS.md",
         templateName: "agents-md",
-        // MCP is machine-global (~/.gemini/antigravity/mcp_config.json) — handled
-        // by configureAntigravityGlobal(), not via mcpConfigFile.
+        // MCP: the project file <root>/.agents/mcp_config.json, pinned to this
+        // project - written by configureAntigravityProject(), not via
+        // mcpConfigFile (the entry is the binary, never node).
     },
     {
         // ZCode (zcode.z.ai), Z.ai's desktop agentic IDE. It reads the
@@ -445,6 +490,8 @@ export function classifyAgent(d, workspaceRoot) {
         return "project";
     if (d.detectHome && isDirectory(path.join(os.homedir(), d.detectHome)))
         return "machine";
+    if (d.detectMachine && d.detectMachine())
+        return "machine";
     if (d.detectAbsPaths && d.detectAbsPaths().some((p) => fs.existsSync(p)))
         return "machine";
     if (projectHint(d, workspaceRoot))
@@ -464,7 +511,7 @@ export function classifyAgents(workspaceRoot) {
 /**
  * What a setup does without asking. Project markers and earlier "yes"
  * answers are configured as they always were; traces on the machine alone
- * (Codex's login, Antigravity's folder, Cline's storage, ~/.claude) and a
+ * (Codex's login, Antigravity's own files, Cline's storage, ~/.claude) and a
  * hint in the project (a bare `.github`, a `.windsurf` folder) wait for the
  * user. Nothing vexp wrote counts as an answer: a 3.2.5 user whose Codex
  * setup came from AGENTS.md is asked once, like everyone else, and so is a
@@ -472,7 +519,13 @@ export function classifyAgents(workspaceRoot) {
  */
 export function planAgentSetup(workspaceRoot, consent = readAgentConsent()) {
     const plan = { configure: [], offer: [], declined: [], kinds: {} };
-    const key = consentKey(workspaceRoot);
+    // A linked git worktree with no answer of its own for an agent takes the
+    // main checkout's (decisionsFor): it is the same project, and every new
+    // worktree asked every question again (field report, 2026-11-07). The
+    // writers that then run there leave the files committed to the
+    // repository as they are where only this checkout's path would change
+    // (committedPin, committedCleanupBlocked). Lockstep with the extension.
+    const decisionOf = decisionsFor(consent, workspaceRoot);
     // The extension asks one question after another, and one left open keeps
     // the rest from being seen: a tool the machine shows goes before one the
     // project only hints at. The same order here, so the two plans compare.
@@ -481,7 +534,7 @@ export function planAgentSetup(workspaceRoot, consent = readAgentConsent()) {
         const kind = classifyAgent(d, workspaceRoot);
         if (kind)
             plan.kinds[d.agent] = kind;
-        const decision = decisionForKey(consent, key, d.agent);
+        const decision = decisionOf(d.agent);
         if (kind === "project" || decision === "yes")
             plan.configure.push(d.agent);
         else if (decision === "no" || decision === "never") {
@@ -592,7 +645,11 @@ export function plannedWrites(agent, guard = guardMode(), interventions = interv
                 out.push(".kilo/plugins/vexp-guard.js  (guard, opt-in)");
             break;
         case "Antigravity":
-            out.push("~/.gemini/antigravity MCP config  (user scope)");
+            out.push(".agents/mcp_config.json  (MCP server entry, pinned to this project; kept out of git in .git/info/exclude)");
+            // Setup also takes vexp's old unpinned entry out of a machine-wide file
+            // (removeDeadAntigravityEntries): named only where there is one.
+            for (const file of deadAntigravityEntryFiles())
+                out.push(`${file}  (vexp's old unpinned entry removed)`);
             break;
         case "Windsurf":
             out.push("~/.codeium/windsurf/mcp_config.json  (MCP server entry, user scope — Cascade)");
@@ -646,311 +703,338 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
     }
     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
-        // Windsurf rules went to `.windsurf/rules.md`, which Cascade does not
-        // read: its rules are `.windsurf/rules/*.md`, `.devin/rules/*.md`, or the
-        // legacy root `.windsurfrules`. Upgrading users would otherwise keep a
-        // stale, unread copy of our instructions beside the live one.
-        if (detector.agent === "Windsurf") {
-            removeVexpSection(path.join(workspaceRoot, ".windsurf", "rules.md"));
-        }
-        const content = generateAgentConfig(detector.templateName, {
-            workspaceRoot,
-            binaryPath,
-            configFile: detector.configFile,
-            version,
-        });
-        // Write instruction file (deduplicated by configFile path)
-        let action = "skipped";
-        if (!writtenConfigFiles.has(detector.configFile)) {
-            if (detector.templateName === "continue") {
-                const continuePayload = {
-                    customCommands: [
-                        {
-                            name: "vexp-context",
-                            description: "Get vexp context for current task",
-                            prompt: "{{{ input }}}\n\nFirst, call run_pipeline with the above task description.",
-                        },
-                    ],
-                    contextProviders: [
-                        {
-                            name: "vexp",
-                            params: {},
-                        },
-                    ],
-                    mcpServers: [
-                        {
-                            name: "vexp",
-                            command: binaryPath,
-                            args: ["mcp"],
-                            type: "stdio",
-                        },
-                    ],
-                };
-                const mergeResult = mergeJsonConfig(configFilePath, continuePayload, version);
-                action = mergeResult === "merged" ? "updated" : "skipped";
-            }
-            else {
-                action = appendOrCreate(configFilePath, content, version);
-            }
-            writtenConfigFiles.add(detector.configFile);
+        // A folder of the agent's that is a link to nothing (danglingAgentFolder):
+        // mkdirSync and writeFileSync both throw ENOENT there, and the exception
+        // left this loop, so the setup failed for every agent, not only for the
+        // one whose folder it was (bug at 3.3.9). That agent alone is skipped,
+        // and the end of setup says why (takeUnreachableTargets).
+        const dangling = danglingAgentFolder(detector, workspaceRoot);
+        if (dangling) {
+            noteDanglingAgentFolder(dangling);
+            continue;
         }
-        // Write MCP config for agents with mcpConfigFile (project-level JSON)
-        if (detector.mcpConfigFile) {
-            const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
-            const isKiro = detector.agent === "Kiro";
-            // Windsurf and Kiro auto-approve vexp's tools so the agent isn't prompted
-            // on every run_pipeline call. Kiro's field is `autoApprove`; others use
-            // `alwaysAllow`.
-            const alwaysAllow = (detector.agent === "Windsurf" || isKiro) ? VEXP_TOOLS : undefined;
-            const approveKey = isKiro ? "autoApprove" : "alwaysAllow";
-            // Kiro resolves the MCP `command` via PATH, and a macOS GUI launch has no
-            // `node` on PATH — so the `node <mcp-server.cjs>` transport silently fails
-            // to start and run_pipeline never appears (the agent then falls back to
-            // grep/sed). Point Kiro straight at the vexp binary (`vexp-core mcp`, which
-            // reads VEXP_WORKSPACE from env) by withholding mcpServerPath — no `node`
-            // needed, an absolute path that always resolves.
-            const mcpSrv = isKiro ? undefined : mcpServerPath;
-            if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpSrv, workspaceRoot, approveKey)) {
-                mcpConfigs.push(detector.mcpConfigFile);
+        // Anything else that throws for one agent stops that agent only, and
+        // the end of setup says so (noteAgentSetupStopped): the agents after
+        // it are set up all the same.
+        try {
+            const configFilePath = path.join(workspaceRoot, detector.configFile);
+            const alreadyExists = fs.existsSync(configFilePath);
+            // Sweep the location we used to write to. For several releases the
+            // Windsurf rules went to `.windsurf/rules.md`, which Cascade does not
+            // read: its rules are `.windsurf/rules/*.md`, `.devin/rules/*.md`, or the
+            // legacy root `.windsurfrules`. Upgrading users would otherwise keep a
+            // stale, unread copy of our instructions beside the live one.
+            if (detector.agent === "Windsurf") {
+                removeVexpSection(path.join(workspaceRoot, ".windsurf", "rules.md"), "Windsurf");
             }
-        }
-        // 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, version);
-            if (wrote)
-                mcpConfigs.push("~/.claude.json");
-            // Event-driven hint hook: default-on (non-blocking, fail-open — the
-            // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
-            const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
-            installClaudeCodeSubagentHook(workspaceRoot, binaryPath);
-            installClaudeCodeSearchHook(workspaceRoot, binaryPath);
-            // Both doors. Bounding either alone measured as no change at all: the
-            // work simply moves to the other one.
-            if (interventionMode() === "on") {
-                installClaudeCodeReadHint(workspaceRoot, binaryPath);
-                installClaudeCodeBashCap(workspaceRoot, binaryPath);
+            const content = generateAgentConfig(detector.templateName, {
+                workspaceRoot,
+                binaryPath,
+                configFile: detector.configFile,
+                version,
+            });
+            // Write instruction file (deduplicated by configFile path)
+            let action = "skipped";
+            if (!writtenConfigFiles.has(detector.configFile)) {
+                if (detector.templateName === "continue") {
+                    const continuePayload = {
+                        customCommands: [
+                            {
+                                name: "vexp-context",
+                                description: "Get vexp context for current task",
+                                prompt: "{{{ input }}}\n\nFirst, call run_pipeline with the above task description.",
+                            },
+                        ],
+                        contextProviders: [
+                            {
+                                name: "vexp",
+                                params: {},
+                            },
+                        ],
+                        mcpServers: [
+                            {
+                                name: "vexp",
+                                command: binaryPath,
+                                args: ["mcp"],
+                                type: "stdio",
+                            },
+                        ],
+                    };
+                    const mergeResult = mergeJsonConfig(configFilePath, continuePayload, version);
+                    action = mergeResult === "merged" ? "updated" : "skipped";
+                }
+                else {
+                    action = appendOrCreate(configFilePath, content, version);
+                }
+                writtenConfigFiles.add(detector.configFile);
             }
-            else {
-                removeClaudeCodePreToolHooks(workspaceRoot);
+            // Write MCP config for agents with mcpConfigFile (project-level JSON)
+            if (detector.mcpConfigFile) {
+                const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
+                const isKiro = detector.agent === "Kiro";
+                // Windsurf and Kiro auto-approve vexp's tools so the agent isn't prompted
+                // on every run_pipeline call. Kiro's field is `autoApprove`; others use
+                // `alwaysAllow`.
+                const alwaysAllow = (detector.agent === "Windsurf" || isKiro) ? VEXP_TOOLS : undefined;
+                const approveKey = isKiro ? "autoApprove" : "alwaysAllow";
+                // Kiro resolves the MCP `command` via PATH, and a macOS GUI launch has no
+                // `node` on PATH — so the `node <mcp-server.cjs>` transport silently fails
+                // to start and run_pipeline never appears (the agent then falls back to
+                // grep/sed). Point Kiro straight at the vexp binary (`vexp-core mcp`, which
+                // reads VEXP_WORKSPACE from env) by withholding mcpServerPath — no `node`
+                // needed, an absolute path that always resolves.
+                const mcpSrv = isKiro ? undefined : mcpServerPath;
+                if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpSrv, workspaceRoot, approveKey)) {
+                    mcpConfigs.push(detector.mcpConfigFile);
+                }
             }
-            installClaudeCodeStopGate(workspaceRoot, binaryPath);
-            installClaudeCodeSessionContext(workspaceRoot, binaryPath);
-            if (hintResult) {
-                results.push({
-                    agent: "Claude Code Hint",
-                    configFile: ".claude/hooks/vexp-hint.sh",
-                    content: vexpHintHookScript(binaryPath),
-                    alreadyExists: false,
-                    action: hintResult,
-                });
+            // 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);
             }
-            // Guard is OPT-IN from 2.3 (see GuardMode): strict installs the
-            // PreToolUse deny hook; default removes any previously installed one.
-            if (guardMode() === "strict") {
-                const hookResult = installClaudeCodeHook(workspaceRoot);
-                if (hookResult) {
+            // Claude Code: configure MCP in ~/.claude.json (user-scope, stdio)
+            if (detector.agent === "Claude Code") {
+                const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot, version);
+                if (wrote)
+                    mcpConfigs.push("~/.claude.json");
+                // Event-driven hint hook: default-on (non-blocking, fail-open — the
+                // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
+                const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
+                installClaudeCodeSubagentHook(workspaceRoot, binaryPath);
+                installClaudeCodeSearchHook(workspaceRoot, binaryPath);
+                // Both doors. Bounding either alone measured as no change at all: the
+                // work simply moves to the other one.
+                if (interventionMode() === "on") {
+                    installClaudeCodeReadHint(workspaceRoot, binaryPath);
+                    installClaudeCodeBashCap(workspaceRoot, binaryPath);
+                }
+                else {
+                    removeClaudeCodePreToolHooks(workspaceRoot);
+                }
+                installClaudeCodeStopGate(workspaceRoot, binaryPath);
+                installClaudeCodeSessionContext(workspaceRoot, binaryPath);
+                if (hintResult) {
+                    results.push({
+                        agent: "Claude Code Hint",
+                        // A committed script left as it is (K1) was not written: what
+                        // changed is its registration.
+                        configFile: hookScriptLeft(path.join(workspaceRoot, ".claude", "hooks", "vexp-hint.sh"))
+                            ? ".claude/settings.json"
+                            : ".claude/hooks/vexp-hint.sh",
+                        content: vexpHintHookScript(binaryPath),
+                        alreadyExists: false,
+                        action: hintResult,
+                    });
+                }
+                // Guard is OPT-IN from 2.3 (see GuardMode): strict installs the
+                // PreToolUse deny hook; default removes any previously installed one.
+                if (guardMode() === "strict") {
+                    const hookResult = installClaudeCodeHook(workspaceRoot);
+                    if (hookResult) {
+                        results.push({
+                            agent: "Claude Code Hook",
+                            configFile: ".claude/hooks/vexp-guard.sh",
+                            content: VEXP_GUARD_HOOK,
+                            alreadyExists: false,
+                            action: hookResult,
+                        });
+                    }
+                }
+                else if (uninstallClaudeCodeHook(workspaceRoot)) {
                     results.push({
                         agent: "Claude Code Hook",
                         configFile: ".claude/hooks/vexp-guard.sh",
-                        content: VEXP_GUARD_HOOK,
+                        content: "",
                         alreadyExists: false,
-                        action: hookResult,
+                        action: "removed",
                     });
                 }
             }
-            else if (uninstallClaudeCodeHook(workspaceRoot)) {
-                results.push({
-                    agent: "Claude Code Hook",
-                    configFile: ".claude/hooks/vexp-guard.sh",
-                    content: "",
-                    alreadyExists: false,
-                    action: "removed",
-                });
+            // Codex: configure MCP in ~/.codex/config.toml (global, HTTP + bearer token)
+            if (detector.agent === "Codex") {
+                const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
+                if (wrote)
+                    mcpConfigs.push("~/.codex/config.toml");
+                installCodexHintHook(workspaceRoot, binaryPath);
             }
-        }
-        // Codex: configure MCP in ~/.codex/config.toml (global, HTTP + bearer token)
-        if (detector.agent === "Codex") {
-            const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
-            if (wrote)
-                mcpConfigs.push("~/.codex/config.toml");
-            installCodexHintHook(workspaceRoot, binaryPath);
-        }
-        // Antigravity: machine-global MCP config (~/.gemini/antigravity/mcp_config.json)
-        if (detector.agent === "Antigravity") {
-            const wrote = configureAntigravityGlobal(binaryPath, mcpServerPath);
-            if (wrote)
-                mcpConfigs.push("~/.gemini/antigravity/mcp_config.json");
-        }
-        // ZCode: `mcp.servers` in .zcode/config.json (or the .agents/mcp.json
-        // compatibility file when that is what the project uses) + the
-        // orientation hook in ZCode's USER config — see configureZcodeMcp.
-        if (detector.agent === "ZCode") {
-            const wrote = configureZcodeMcp(workspaceRoot, binaryPath);
-            if (wrote)
-                mcpConfigs.push(wrote);
-            const hint = installZcodeHintHook(binaryPath);
-            if (hint) {
-                results.push({
-                    agent: "ZCode Hint",
-                    configFile: "~/.zcode/cli/config.json",
-                    content: "",
-                    alreadyExists: hint === "updated",
-                    action: hint,
-                });
+            // Antigravity: the project's .agents/mcp_config.json, pinned to this
+            // project (configureAntigravityProject). The dead machine-wide entries
+            // older setups left go at the end, whichever agents are set up.
+            if (detector.agent === "Antigravity") {
+                if (configureAntigravityProject(workspaceRoot, binaryPath))
+                    mcpConfigs.push(ANTIGRAVITY_PROJECT_MCP);
             }
-        }
-        // GitHub Copilot: VS Code format (.vscode/mcp.json with "servers" key)
-        if (detector.agent === "GitHub Copilot") {
-            const mcpPath = path.join(workspaceRoot, ".vscode/mcp.json");
-            if (writeVsCodeMcpConfig(mcpPath, binaryPath, mcpServerPath, workspaceRoot)) {
-                mcpConfigs.push(".vscode/mcp.json");
+            // ZCode: `mcp.servers` in .zcode/config.json (or the .agents/mcp.json
+            // compatibility file when that is what the project uses) + the
+            // orientation hook in ZCode's USER config — see configureZcodeMcp.
+            if (detector.agent === "ZCode") {
+                const wrote = configureZcodeMcp(workspaceRoot, binaryPath);
+                if (wrote)
+                    mcpConfigs.push(wrote);
+                const hint = installZcodeHintHook(binaryPath);
+                if (hint) {
+                    results.push({
+                        agent: "ZCode Hint",
+                        configFile: "~/.zcode/cli/config.json",
+                        content: "",
+                        alreadyExists: hint === "updated",
+                        action: hint,
+                    });
+                }
             }
-        }
-        // Zed: context_servers in .zed/settings.json
-        if (detector.agent === "Zed") {
-            const zedPath = path.join(workspaceRoot, ".zed/settings.json");
-            if (writeZedMcpConfig(zedPath, binaryPath, mcpServerPath, workspaceRoot)) {
-                mcpConfigs.push(".zed/settings.json");
+            // GitHub Copilot: VS Code format (.vscode/mcp.json with "servers" key)
+            // `.mcp.json` at the root is kept runnable, and when it defines vexp
+            // `.vscode/mcp.json` gets no entry of its own (configureCopilotMcp).
+            if (detector.agent === "GitHub Copilot") {
+                mcpConfigs.push(...configureCopilotMcp(workspaceRoot, binaryPath, mcpServerPath));
             }
-        }
-        // Kilo Code: MCP lives under the `mcp` key in kilo.jsonc (root or .kilo/),
-        // not a separate mcp.json (that file is no longer read).
-        if (detector.agent === "Kilo Code") {
-            const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
-            if (wrote)
-                mcpConfigs.push(wrote);
-            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
-            installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
-            // Kilo v7 vendors opencode, so it takes the same guard plugin — the rules
-            // markdown alone was demonstrably not enough (a reported session loaded
-            // vexp.md, quoted it back, and still read five files by hand).
-            if (guardMode() === "strict") {
-                const kilo = installKiloPlugin(workspaceRoot);
-                if (kilo.plugin) {
+            // Zed: context_servers in .zed/settings.json
+            if (detector.agent === "Zed") {
+                const zedPath = path.join(workspaceRoot, ".zed/settings.json");
+                if (writeZedMcpConfig(zedPath, binaryPath, mcpServerPath, workspaceRoot)) {
+                    mcpConfigs.push(".zed/settings.json");
+                }
+            }
+            // Kilo Code: MCP lives under the `mcp` key in kilo.jsonc (root or .kilo/),
+            // not a separate mcp.json (that file is no longer read).
+            if (detector.agent === "Kilo Code") {
+                const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
+                if (wrote)
+                    mcpConfigs.push(wrote);
+                installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
+                installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
+                // Kilo v7 vendors opencode, so it takes the same guard plugin — the rules
+                // markdown alone was demonstrably not enough (a reported session loaded
+                // vexp.md, quoted it back, and still read five files by hand).
+                if (guardMode() === "strict") {
+                    const kilo = installKiloPlugin(workspaceRoot);
+                    if (kilo.plugin) {
+                        results.push({
+                            agent: "Kilo Code Guard",
+                            configFile: path.join(".kilo", "plugins", "vexp-guard.js"),
+                            content: VEXP_OPENCODE_GUARD,
+                            alreadyExists: kilo.plugin === "updated",
+                            action: kilo.plugin,
+                        });
+                    }
+                    if (kilo.registered)
+                        mcpConfigs.push(path.relative(workspaceRoot, kiloConfigTarget(workspaceRoot)));
+                }
+                else if (uninstallKiloPlugin(workspaceRoot)) {
                     results.push({
                         agent: "Kilo Code Guard",
                         configFile: path.join(".kilo", "plugins", "vexp-guard.js"),
-                        content: VEXP_OPENCODE_GUARD,
-                        alreadyExists: kilo.plugin === "updated",
-                        action: kilo.plugin,
+                        content: "",
+                        alreadyExists: false,
+                        action: "removed",
                     });
                 }
-                if (kilo.registered)
-                    mcpConfigs.push(path.relative(workspaceRoot, kiloConfigTarget(workspaceRoot)));
-            }
-            else if (uninstallKiloPlugin(workspaceRoot)) {
-                results.push({
-                    agent: "Kilo Code Guard",
-                    configFile: path.join(".kilo", "plugins", "vexp-guard.js"),
-                    content: "",
-                    alreadyExists: false,
-                    action: "removed",
-                });
             }
-        }
-        // Cursor: preToolUse hook matching Grep. Text search only - Cursor's native
-        // semantic search is not hookable.
-        if (detector.agent === "Cursor") {
-            if (guardMode() === "strict") {
-                const cur = installCursorHook(workspaceRoot);
-                if (cur.hook) {
+            // Cursor: preToolUse hook matching Grep. Text search only - Cursor's native
+            // semantic search is not hookable.
+            if (detector.agent === "Cursor") {
+                if (guardMode() === "strict") {
+                    const cur = installCursorHook(workspaceRoot);
+                    if (cur.hook) {
+                        results.push({
+                            agent: "Cursor Guard",
+                            configFile: path.join(".cursor", "hooks", "vexp-guard.js"),
+                            content: VEXP_CURSOR_GUARD,
+                            alreadyExists: cur.hook === "updated",
+                            action: cur.hook,
+                        });
+                    }
+                    if (cur.registered)
+                        mcpConfigs.push(path.join(".cursor", "hooks.json"));
+                }
+                else if (uninstallCursorHook(workspaceRoot)) {
                     results.push({
                         agent: "Cursor Guard",
                         configFile: path.join(".cursor", "hooks", "vexp-guard.js"),
-                        content: VEXP_CURSOR_GUARD,
-                        alreadyExists: cur.hook === "updated",
-                        action: cur.hook,
+                        content: "",
+                        alreadyExists: false,
+                        action: "removed",
+                    });
+                }
+                // v5: the coupling on edit. Default-ON and independent of the guard —
+                // it blocks nothing, so there is no reason to make it opt-in.
+                const edit = installCursorEditHint(workspaceRoot, binaryPath);
+                if (edit) {
+                    results.push({
+                        agent: "Cursor Edit Hint",
+                        // A committed script left as it is (K1) was not written: what
+                        // changed is its registration.
+                        configFile: hookScriptLeft(path.join(workspaceRoot, ".cursor", "hooks", "vexp-edit-hint.sh"))
+                            ? path.join(".cursor", "hooks.json")
+                            : path.join(".cursor", "hooks", "vexp-edit-hint.sh"),
+                        content: "",
+                        alreadyExists: edit === "updated",
+                        action: edit,
                     });
                 }
-                if (cur.registered)
-                    mcpConfigs.push(path.join(".cursor", "hooks.json"));
-            }
-            else if (uninstallCursorHook(workspaceRoot)) {
-                results.push({
-                    agent: "Cursor Guard",
-                    configFile: path.join(".cursor", "hooks", "vexp-guard.js"),
-                    content: "",
-                    alreadyExists: false,
-                    action: "removed",
-                });
-            }
-            // v5: the coupling on edit. Default-ON and independent of the guard —
-            // it blocks nothing, so there is no reason to make it opt-in.
-            const edit = installCursorEditHint(workspaceRoot, binaryPath);
-            if (edit) {
-                results.push({
-                    agent: "Cursor Edit Hint",
-                    configFile: path.join(".cursor", "hooks", "vexp-edit-hint.sh"),
-                    content: "",
-                    alreadyExists: edit === "updated",
-                    action: edit,
-                });
             }
-        }
-        // Cline: rules in .clinerules (generic template, handled by the writer
-        // above); MCP registry is machine-global VS Code storage.
-        if (detector.agent === "Cline") {
-            const wrote = configureClineMcp(workspaceRoot, binaryPath);
-            for (const w of wrote) {
-                mcpConfigs.push(w);
+            // Cline: rules in .clinerules (generic template, handled by the writer
+            // above); MCP registry is machine-global VS Code storage.
+            if (detector.agent === "Cline") {
+                const wrote = configureClineMcp(workspaceRoot, binaryPath);
+                for (const w of wrote) {
+                    mcpConfigs.push(w);
+                }
+                if (wrote.length === 0 && !clineInstalled())
+                    noteClineMcpUnreachable();
             }
-            if (wrote.length === 0)
-                noteClineMcpUnreachable();
-        }
-        // Opencode: MCP lives under the `mcp` key in opencode.json(c) — opencode
-        // carries no `mcpConfigFile`, so without this call the generic writer above
-        // skips it and setup registers no tool at all. Plus the guard plugin that
-        // blocks grep/glob while the daemon is up (opencode's analogue of the
-        // Claude Code PreToolUse hook) — which is only safe once MCP is registered.
-        if (detector.agent === "Opencode") {
-            const wroteMcp = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
-            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
-            installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
-            if (wroteMcp)
-                mcpConfigs.push(wroteMcp);
-            if (guardMode() === "strict") {
-                const pluginResult = installOpencodePlugin(workspaceRoot);
-                if (pluginResult) {
+            // Opencode: MCP lives under the `mcp` key in opencode.json(c) — opencode
+            // carries no `mcpConfigFile`, so without this call the generic writer above
+            // skips it and setup registers no tool at all. Plus the guard plugin that
+            // blocks grep/glob while the daemon is up (opencode's analogue of the
+            // Claude Code PreToolUse hook) — which is only safe once MCP is registered.
+            if (detector.agent === "Opencode") {
+                const wroteMcp = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
+                installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
+                installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
+                if (wroteMcp)
+                    mcpConfigs.push(wroteMcp);
+                if (guardMode() === "strict") {
+                    const pluginResult = installOpencodePlugin(workspaceRoot);
+                    if (pluginResult) {
+                        results.push({
+                            agent: "Opencode Guard",
+                            configFile: ".opencode/plugins/vexp-guard.js",
+                            content: VEXP_OPENCODE_GUARD,
+                            alreadyExists: pluginResult === "updated",
+                            action: pluginResult,
+                        });
+                    }
+                }
+                else if (uninstallOpencodePlugin(workspaceRoot)) {
                     results.push({
                         agent: "Opencode Guard",
                         configFile: ".opencode/plugins/vexp-guard.js",
-                        content: VEXP_OPENCODE_GUARD,
-                        alreadyExists: pluginResult === "updated",
-                        action: pluginResult,
+                        content: "",
+                        alreadyExists: false,
+                        action: "removed",
                     });
                 }
             }
-            else if (uninstallOpencodePlugin(workspaceRoot)) {
-                results.push({
-                    agent: "Opencode Guard",
-                    configFile: ".opencode/plugins/vexp-guard.js",
-                    content: "",
-                    alreadyExists: false,
-                    action: "removed",
-                });
-            }
+            results.push({
+                agent: detector.agent,
+                configFile: detector.configFile,
+                content,
+                alreadyExists,
+                action,
+            });
+        }
+        catch (err) {
+            noteAgentSetupStopped(detector.agent, err);
         }
-        results.push({
-            agent: detector.agent,
-            configFile: detector.configFile,
-            content,
-            alreadyExists,
-            action,
-        });
     }
+    removeDeadAntigravityEntriesAtSetup();
     return { agents: results, mcpConfigs };
 }
 /**
@@ -1026,178 +1110,197 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
         const detector = withCursorTarget(detected, workspaceRoot);
         if (!selectedAgentNames.includes(detector.agent))
             continue;
-        // Create agent directory if it doesn't exist. Skip for file-based
-        // detectPaths: extension-bearing markers (AGENTS.md) and extensionless
-        // file markers where the marker IS the config file (.clinerules) —
-        // mkdir-ing those creates a directory where a file must go (EISDIR).
-        const detectAbsPath = path.join(workspaceRoot, detector.detectPath);
-        if (!fs.existsSync(detectAbsPath) &&
-            !path.extname(detector.detectPath) &&
-            detector.detectPath !== detector.configFile) {
-            fs.mkdirSync(detectAbsPath, { recursive: true });
-        }
-        // Create parent directory for configFile (handles nested paths like .kiro/steering/vexp.md)
-        const configFilePath = path.join(workspaceRoot, detector.configFile);
-        const configDir = path.dirname(configFilePath);
-        if (!fs.existsSync(configDir)) {
-            fs.mkdirSync(configDir, { recursive: true });
+        // A folder of the agent's that is a link to nothing (danglingAgentFolder):
+        // mkdirSync and writeFileSync both throw ENOENT there, and the exception
+        // left this loop, so the setup failed for every agent, not only for the
+        // one whose folder it was (bug at 3.3.9). That agent alone is skipped,
+        // and the end of setup says why (takeUnreachableTargets).
+        const dangling = danglingAgentFolder(detector, workspaceRoot);
+        if (dangling) {
+            noteDanglingAgentFolder(dangling);
+            continue;
         }
-        // Create parent directory for MCP config (handles .codex/, .kiro/settings/, etc.)
-        if (detector.mcpConfigFile) {
-            const mcpDir = path.dirname(path.join(workspaceRoot, detector.mcpConfigFile));
-            if (!fs.existsSync(mcpDir)) {
-                fs.mkdirSync(mcpDir, { recursive: true });
+        // Anything else that throws for one agent stops that agent only, and
+        // the end of setup says so (noteAgentSetupStopped): the agents after
+        // it are set up all the same.
+        try {
+            // Create agent directory if it doesn't exist. Skip for file-based
+            // detectPaths: extension-bearing markers (AGENTS.md) and extensionless
+            // file markers where the marker IS the config file (.clinerules) —
+            // mkdir-ing those creates a directory where a file must go (EISDIR).
+            const detectAbsPath = path.join(workspaceRoot, detector.detectPath);
+            if (!fs.existsSync(detectAbsPath) &&
+                !path.extname(detector.detectPath) &&
+                detector.detectPath !== detector.configFile) {
+                fs.mkdirSync(detectAbsPath, { recursive: true });
             }
-        }
-        // Same sweep as the other writer: the Windsurf rules moved out of
-        // `.windsurf/rules.md`, which Cascade never read.
-        if (detector.agent === "Windsurf") {
-            removeVexpSection(path.join(workspaceRoot, ".windsurf", "rules.md"));
-        }
-        const alreadyExists = fs.existsSync(configFilePath);
-        const content = generateAgentConfig(detector.templateName, {
-            workspaceRoot,
-            binaryPath,
-            configFile: detector.configFile,
-            version,
-        });
-        let action = "skipped";
-        if (!writtenConfigFiles.has(detector.configFile)) {
-            if (detector.templateName === "continue") {
-                const continuePayload = {
-                    customCommands: [
-                        {
-                            name: "vexp-context",
-                            description: "Get vexp context for current task",
-                            prompt: "{{{ input }}}\n\nFirst, call run_pipeline with the above task description.",
-                        },
-                    ],
-                    mcpServers: [
-                        { name: "vexp", command: binaryPath, args: ["mcp"], type: "stdio" },
-                    ],
-                };
-                const mergeResult = mergeJsonConfig(configFilePath, continuePayload, version);
-                action = mergeResult === "merged" ? "updated" : "skipped";
+            // Create parent directory for configFile (handles nested paths like .kiro/steering/vexp.md)
+            const configFilePath = path.join(workspaceRoot, detector.configFile);
+            const configDir = path.dirname(configFilePath);
+            if (!fs.existsSync(configDir)) {
+                fs.mkdirSync(configDir, { recursive: true });
             }
-            else {
-                action = appendOrCreate(configFilePath, content, version);
+            // Create parent directory for MCP config (handles .codex/, .kiro/settings/, etc.)
+            // Not through a link out of the project: the writer leaves that file
+            // alone and says so (projectWriteLanding), and creates nothing there.
+            if (detector.mcpConfigFile) {
+                const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
+                const mcpDir = path.dirname(mcpConfigPath);
+                if (!fs.existsSync(mcpDir) && projectWriteLanding(mcpConfigPath, workspaceRoot).ok) {
+                    fs.mkdirSync(mcpDir, { recursive: true });
+                }
             }
-            writtenConfigFiles.add(detector.configFile);
-        }
-        if (detector.mcpConfigFile) {
-            const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
-            const isKiro = detector.agent === "Kiro";
-            // See configureAgents(): Kiro auto-approves under `autoApprove` and is
-            // pointed at the vexp binary (no `node` on macOS GUI PATH) by withholding
-            // mcpServerPath.
-            const alwaysAllow = (detector.agent === "Windsurf" || isKiro) ? VEXP_TOOLS : undefined;
-            const approveKey = isKiro ? "autoApprove" : "alwaysAllow";
-            const mcpSrv = isKiro ? undefined : mcpServerPath;
-            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, version);
-            if (wrote)
-                mcpConfigs.push("~/.claude.json");
-            installClaudeCodeHintHook(workspaceRoot, binaryPath);
-            installClaudeCodeSubagentHook(workspaceRoot, binaryPath);
-            if (interventionMode() === "on") {
-                installClaudeCodeReadHint(workspaceRoot, binaryPath);
-                installClaudeCodeBashCap(workspaceRoot, binaryPath);
+            // Same sweep as the other writer: the Windsurf rules moved out of
+            // `.windsurf/rules.md`, which Cascade never read.
+            if (detector.agent === "Windsurf") {
+                removeVexpSection(path.join(workspaceRoot, ".windsurf", "rules.md"), "Windsurf");
             }
-            else {
-                removeClaudeCodePreToolHooks(workspaceRoot);
+            const alreadyExists = fs.existsSync(configFilePath);
+            const content = generateAgentConfig(detector.templateName, {
+                workspaceRoot,
+                binaryPath,
+                configFile: detector.configFile,
+                version,
+            });
+            let action = "skipped";
+            if (!writtenConfigFiles.has(detector.configFile)) {
+                if (detector.templateName === "continue") {
+                    const continuePayload = {
+                        customCommands: [
+                            {
+                                name: "vexp-context",
+                                description: "Get vexp context for current task",
+                                prompt: "{{{ input }}}\n\nFirst, call run_pipeline with the above task description.",
+                            },
+                        ],
+                        mcpServers: [
+                            { name: "vexp", command: binaryPath, args: ["mcp"], type: "stdio" },
+                        ],
+                    };
+                    const mergeResult = mergeJsonConfig(configFilePath, continuePayload, version);
+                    action = mergeResult === "merged" ? "updated" : "skipped";
+                }
+                else {
+                    action = appendOrCreate(configFilePath, content, version);
+                }
+                writtenConfigFiles.add(detector.configFile);
             }
-            installClaudeCodeStopGate(workspaceRoot, binaryPath);
-            installClaudeCodeSessionContext(workspaceRoot, binaryPath);
-            if (guardMode() === "strict")
-                installClaudeCodeHook(workspaceRoot);
-            else
-                uninstallClaudeCodeHook(workspaceRoot);
-        }
-        if (detector.agent === "Codex") {
-            const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
-            if (wrote)
-                mcpConfigs.push("~/.codex/config.toml");
-            installCodexHintHook(workspaceRoot, binaryPath);
-        }
-        if (detector.agent === "Antigravity") {
-            const wrote = configureAntigravityGlobal(binaryPath, mcpServerPath);
-            if (wrote)
-                mcpConfigs.push("~/.gemini/antigravity/mcp_config.json");
-        }
-        if (detector.agent === "ZCode") {
-            const wrote = configureZcodeMcp(workspaceRoot, binaryPath);
-            if (wrote)
-                mcpConfigs.push(wrote);
-            installZcodeHintHook(binaryPath);
-        }
-        if (detector.agent === "GitHub Copilot") {
-            const mcpPath = path.join(workspaceRoot, ".vscode/mcp.json");
-            if (writeVsCodeMcpConfig(mcpPath, binaryPath, mcpServerPath, workspaceRoot))
-                mcpConfigs.push(".vscode/mcp.json");
-        }
-        if (detector.agent === "Zed") {
-            const zedPath = path.join(workspaceRoot, ".zed/settings.json");
-            if (writeZedMcpConfig(zedPath, binaryPath, mcpServerPath, workspaceRoot))
-                mcpConfigs.push(".zed/settings.json");
-        }
-        if (detector.agent === "Cline") {
-            const wrote = configureClineMcp(workspaceRoot, binaryPath);
-            for (const w of wrote)
-                mcpConfigs.push(w);
-            if (wrote.length === 0)
-                noteClineMcpUnreachable();
-        }
-        if (detector.agent === "Opencode") {
-            const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
-            if (wrote)
-                mcpConfigs.push(wrote);
-            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
-            installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
-            if (guardMode() === "strict")
-                installOpencodePlugin(workspaceRoot);
-            else
-                uninstallOpencodePlugin(workspaceRoot);
-        }
-        if (detector.agent === "Cursor") {
-            if (interventionMode() === "on") {
-                installCursorReadHint(workspaceRoot, binaryPath);
-                installCursorBashCap(workspaceRoot, binaryPath);
+            if (detector.mcpConfigFile) {
+                const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
+                const isKiro = detector.agent === "Kiro";
+                // See configureAgents(): Kiro auto-approves under `autoApprove` and is
+                // pointed at the vexp binary (no `node` on macOS GUI PATH) by withholding
+                // mcpServerPath.
+                const alwaysAllow = (detector.agent === "Windsurf" || isKiro) ? VEXP_TOOLS : undefined;
+                const approveKey = isKiro ? "autoApprove" : "alwaysAllow";
+                const mcpSrv = isKiro ? undefined : mcpServerPath;
+                if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpSrv, workspaceRoot, approveKey))
+                    mcpConfigs.push(detector.mcpConfigFile);
             }
-            if (guardMode() === "strict")
-                installCursorHook(workspaceRoot);
-            else
-                uninstallCursorHook(workspaceRoot);
+            // 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, version);
+                if (wrote)
+                    mcpConfigs.push("~/.claude.json");
+                installClaudeCodeHintHook(workspaceRoot, binaryPath);
+                installClaudeCodeSubagentHook(workspaceRoot, binaryPath);
+                if (interventionMode() === "on") {
+                    installClaudeCodeReadHint(workspaceRoot, binaryPath);
+                    installClaudeCodeBashCap(workspaceRoot, binaryPath);
+                }
+                else {
+                    removeClaudeCodePreToolHooks(workspaceRoot);
+                }
+                installClaudeCodeStopGate(workspaceRoot, binaryPath);
+                installClaudeCodeSessionContext(workspaceRoot, binaryPath);
+                if (guardMode() === "strict")
+                    installClaudeCodeHook(workspaceRoot);
+                else
+                    uninstallClaudeCodeHook(workspaceRoot);
+            }
+            if (detector.agent === "Codex") {
+                const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
+                if (wrote)
+                    mcpConfigs.push("~/.codex/config.toml");
+                installCodexHintHook(workspaceRoot, binaryPath);
+            }
+            if (detector.agent === "Antigravity") {
+                if (configureAntigravityProject(workspaceRoot, binaryPath))
+                    mcpConfigs.push(ANTIGRAVITY_PROJECT_MCP);
+            }
+            if (detector.agent === "ZCode") {
+                const wrote = configureZcodeMcp(workspaceRoot, binaryPath);
+                if (wrote)
+                    mcpConfigs.push(wrote);
+                installZcodeHintHook(binaryPath);
+            }
+            if (detector.agent === "GitHub Copilot") {
+                mcpConfigs.push(...configureCopilotMcp(workspaceRoot, binaryPath, mcpServerPath));
+            }
+            if (detector.agent === "Zed") {
+                const zedPath = path.join(workspaceRoot, ".zed/settings.json");
+                if (writeZedMcpConfig(zedPath, binaryPath, mcpServerPath, workspaceRoot))
+                    mcpConfigs.push(".zed/settings.json");
+            }
+            if (detector.agent === "Cline") {
+                const wrote = configureClineMcp(workspaceRoot, binaryPath);
+                for (const w of wrote)
+                    mcpConfigs.push(w);
+                if (wrote.length === 0 && !clineInstalled())
+                    noteClineMcpUnreachable();
+            }
+            if (detector.agent === "Opencode") {
+                const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
+                if (wrote)
+                    mcpConfigs.push(wrote);
+                installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
+                installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
+                if (guardMode() === "strict")
+                    installOpencodePlugin(workspaceRoot);
+                else
+                    uninstallOpencodePlugin(workspaceRoot);
+            }
+            if (detector.agent === "Cursor") {
+                if (interventionMode() === "on") {
+                    installCursorReadHint(workspaceRoot, binaryPath);
+                    installCursorBashCap(workspaceRoot, binaryPath);
+                }
+                if (guardMode() === "strict")
+                    installCursorHook(workspaceRoot);
+                else
+                    uninstallCursorHook(workspaceRoot);
+            }
+            // Kilo carries no `mcpConfigFile` (its MCP lives under the `mcp` key inside
+            // kilo.jsonc), so without this branch the generic writer above skips it and
+            // picking Kilo explicitly used to write the rules file and NOTHING else — an
+            // agent told "always call run_pipeline" while the tool was never registered.
+            if (detector.agent === "Kilo Code") {
+                const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
+                if (wrote)
+                    mcpConfigs.push(wrote);
+                installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
+                installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
+                if (guardMode() === "strict")
+                    installKiloPlugin(workspaceRoot);
+                else
+                    uninstallKiloPlugin(workspaceRoot);
+            }
+            results.push({ agent: detector.agent, configFile: detector.configFile, content, alreadyExists, action });
         }
-        // Kilo carries no `mcpConfigFile` (its MCP lives under the `mcp` key inside
-        // kilo.jsonc), so without this branch the generic writer above skips it and
-        // picking Kilo explicitly used to write the rules file and NOTHING else — an
-        // agent told "always call run_pipeline" while the tool was never registered.
-        if (detector.agent === "Kilo Code") {
-            const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
-            if (wrote)
-                mcpConfigs.push(wrote);
-            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
-            installOpencodeCompressPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
-            if (guardMode() === "strict")
-                installKiloPlugin(workspaceRoot);
-            else
-                uninstallKiloPlugin(workspaceRoot);
+        catch (err) {
+            noteAgentSetupStopped(detector.agent, err);
         }
-        results.push({ agent: detector.agent, configFile: detector.configFile, content, alreadyExists, action });
     }
+    removeDeadAntigravityEntriesAtSetup();
     return { agents: results, mcpConfigs };
 }
 // ---------------------------------------------------------------------------
@@ -1263,8 +1366,42 @@ export function parseJsonc(text) {
         }
         out += c;
     }
-    out = out.replace(/,(\s*[}\]])/g, "$1");
-    return JSON.parse(out);
+    return JSON.parse(stripTrailingCommas(out));
+}
+/**
+ * Drop each `,` that only whitespace separates from a closing `}` or `]`,
+ * outside string literals: a `,]` inside another server's argument is the
+ * user's text and stays (a regex over the whole text took it out, and the
+ * rewrite saved the changed string). Comments are gone by now. Lockstep
+ * with the CLI/extension twin and with vexp-core's strip_trailing_commas.
+ */
+function stripTrailingCommas(text) {
+    let out = "";
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inString) {
+            out += c;
+            if (c === "\\") {
+                out += text[i + 1] ?? "";
+                i++;
+            }
+            else if (c === '"')
+                inString = false;
+            continue;
+        }
+        if (c === '"')
+            inString = true;
+        else if (c === ",") {
+            let j = i + 1;
+            while (j < text.length && /\s/.test(text[j]))
+                j++;
+            if (text[j] === "}" || text[j] === "]")
+                continue;
+        }
+        out += c;
+    }
+    return out;
 }
 /**
  * Read a JSON/JSONC config file without ever risking user data. When the file
@@ -1283,13 +1420,24 @@ export function readJsonConfigSafe(filePath) {
     }
     if (raw.trim() === "")
         return { data: {}, ok: true, existed: true };
+    // Strict JSON first, and the JSONC walk only for a file that needs it:
+    // what JSON.parse reads is what the file says, and a JSONC pass may only
+    // ever widen that. Lockstep with the extension's readJsonConfigSafe.
+    let parsed;
     try {
-        const parsed = parseJsonc(raw);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return { data: parsed, ok: true, existed: true };
+        parsed = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+    }
+    catch {
+        try {
+            parsed = parseJsonc(raw);
+        }
+        catch {
+            return { data: {}, ok: false, existed: true };
         }
     }
-    catch { /* fall through to ok:false */ }
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return { data: parsed, ok: true, existed: true };
+    }
     return { data: {}, ok: false, existed: true };
 }
 /**
@@ -1665,8 +1813,10 @@ function backupConfig(filePath) {
         // 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/.
+        // One committed to the repository stays (committedCleanupBlocked's rule;
+        // no agent to name for a backup).
         const legacy = path.resolve(`${filePath}.vexp-bak`);
-        if (legacy !== dest && fs.existsSync(legacy))
+        if (legacy !== dest && fs.existsSync(legacy) && !isGitTracked(legacy))
             fs.unlinkSync(legacy);
     }
     catch { /* non-fatal */ }
@@ -1679,10 +1829,47 @@ function backupConfig(filePath) {
  * global config files where cross-process races are possible.
  */
 function atomicWriteFileSync(filePath, content) {
-    const tmp = `${filePath}.vexp-tmp-${process.pid}`;
+    // A path that is a link to a file is written where the link leads: the
+    // temp file goes next to the real target and is renamed onto it, so the
+    // link stays and its target gets the new content, with the permissions it
+    // had. Renamed over the path itself, the link was replaced by a regular
+    // file, and a dotfile manager's repository (stow, chezmoi and home-manager
+    // link ~/.claude.json, ~/.codex/config.toml and the like into it) silently
+    // stopped receiving the user's updates. A link to nothing is replaced by
+    // the new regular file, as before: there is no target to keep, and
+    // creating one wherever the link points is not vexp's to do.
+    //
+    // A link whose target cannot be written is replaced too, as up to 3.3.9:
+    // home-manager links ~/.codex/config.toml into the read-only Nix store,
+    // so the write there fails (EACCES, EROFS) where the rename over the link
+    // worked, and the agent lost its setup (review, 2026-11-07, round 5). The
+    // new file takes the target's permissions with the owner's write bit, so
+    // it is never more open than the target was. Lockstep with the
+    // extension's atomicWriteFileSync.
+    const linked = linkedFileTarget(filePath);
+    let mode;
+    if (linked) {
+        try {
+            // The temp file is created with the default mode; the link's target
+            // keeps the one it had (a 0600 file stays private).
+            mode = fs.statSync(linked).mode & 0o7777;
+            writeThroughTemp(linked, content, mode);
+            return;
+        }
+        catch {
+            /* the target cannot be written: the link is replaced, below */
+        }
+    }
+    writeThroughTemp(filePath, content, mode === undefined ? undefined : mode | 0o200);
+}
+/** Temp file beside `target`, renamed onto it; a direct write when the rename cannot be done. */
+function writeThroughTemp(target, content, mode) {
+    const tmp = `${target}.vexp-tmp-${process.pid}`;
     try {
         fs.writeFileSync(tmp, content, "utf-8");
-        fs.renameSync(tmp, filePath);
+        if (mode !== undefined)
+            fs.chmodSync(tmp, mode);
+        fs.renameSync(tmp, target);
     }
     catch {
         // Cross-device rename or a Windows edge — fall back to a direct write.
@@ -1690,7 +1877,24 @@ function atomicWriteFileSync(filePath, content) {
             fs.unlinkSync(tmp);
         }
         catch { /* ignore */ }
-        fs.writeFileSync(filePath, content, "utf-8");
+        fs.writeFileSync(target, content, "utf-8");
+    }
+}
+/**
+ * The real path of the file `p` leads to when `p` is a link (or a chain of
+ * links) to a file; undefined when `p` is no link, a link to nothing, or a
+ * link to something other than a file, which atomicWriteFileSync replaces
+ * as it always did. Lockstep with the extension's linkedFileTarget.
+ */
+function linkedFileTarget(p) {
+    try {
+        if (!fs.lstatSync(p).isSymbolicLink())
+            return undefined;
+        const real = fs.realpathSync(p);
+        return fs.statSync(real).isFile() ? real : undefined;
+    }
+    catch {
+        return undefined;
     }
 }
 /** Warn that we refused to touch an unparseable config file. */
@@ -1769,6 +1973,223 @@ function warnUnparseable(filePath) {
     }
     process.stderr.write(`  [!] ${filePath} could not be parsed - leaving it untouched. Fix the file or add vexp manually, then re-run setup.\n`);
 }
+/**
+ * Is the key an MCP writer puts vexp's entry under there, and not an object
+ * (an array, a string, a number, null)? vexp's entry cannot go in without
+ * replacing the user's value: an array took it as a property that
+ * JSON.stringify drops, so the file was rewritten without it and setup
+ * reported an entry it had not written; a string threw; null was replaced.
+ * Every JSON MCP writer leaves such a file byte for byte and says so
+ * (leftUntouched). Lockstep with the extension and vexp-core.
+ */
+function containerMisshapen(data, key) {
+    if (!Object.prototype.hasOwnProperty.call(data, key))
+        return false;
+    return !asPlainObject(data[key]);
+}
+/** A JSON object, not an array or null. */
+function asPlainObject(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+/**
+ * Report a file a writer left untouched because the key vexp's entry goes
+ * under is not an object (containerMisshapen), at the end of setup
+ * (takeUnreachableTargets), in the words the extension's setup report
+ * shows. `key` is the path of the key in the file (`mcp.servers`). Returns
+ * false: nothing was written.
+ */
+function leftUntouched(filePath, key, shape = "an object") {
+    const msg = `${filePath} has an ${key} that is not ${shape} - left untouched`;
+    if (!unreachableTargets.includes(msg))
+        unreachableTargets.push(msg);
+    return false;
+}
+/**
+ * Where a path really is: its real path when it is there, else the real
+ * path of its nearest ancestor that is there, joined with the rest. A write
+ * lands there, since writeFileSync and mkdirSync follow every link on the
+ * way. undefined when the way goes through a link to nothing (or a loop):
+ * a write there would create the link's target, wherever that is.
+ * Lockstep with the extension's landingOf.
+ */
+function landingOf(p) {
+    // On macOS the system's realpath(3) (fs.realpathSync.native): its file
+    // systems are case-insensitive and normalization-insensitive by default,
+    // and realpath(3) returns each name as it is on disk, while the JS walk
+    // keeps a link's target as written. Compared byte for byte, a link that
+    // stays in the project but spells its folder in another letter case (or
+    // the other Unicode form) read as leading out of it (review, 2026-11-07,
+    // round 4); vexp-core's canonicalize is realpath(3) too. Elsewhere the JS
+    // walk, as before: Linux file systems are case-sensitive, and on Windows
+    // path.relative folds case. A native call that fails leaves it to the JS
+    // walk, which throws the same for a link to nothing.
+    const realpath = (q) => {
+        if (process.platform === "darwin") {
+            try {
+                return fs.realpathSync.native(q);
+            }
+            catch {
+                /* the JS walk decides */
+            }
+        }
+        return fs.realpathSync(q);
+    };
+    const rest = [];
+    let at = path.resolve(p);
+    for (;;) {
+        let st;
+        try {
+            st = fs.lstatSync(at);
+        }
+        catch {
+            st = undefined; // not there: its parent decides
+        }
+        if (st) {
+            try {
+                return path.join(realpath(at), ...rest);
+            }
+            catch {
+                // lstat found it, so only a link can fail to resolve; anything
+                // else (a folder that cannot be read) is compared as written.
+                return st.isSymbolicLink() ? undefined : path.join(at, ...rest);
+            }
+        }
+        const parent = path.dirname(at);
+        if (parent === at)
+            return path.join(at, ...rest);
+        rest.unshift(path.basename(at));
+        at = parent;
+    }
+}
+/**
+ * Where a write to `file`, a file inside `workspaceRoot`, would land
+ * (landingOf), checked against the root's own real path. Inside: ok, and
+ * the writer writes as before, through an inner link, which stays a link
+ * (a repository that keeps one MCP file and links it where each tool reads
+ * it). Outside the project, through a link of the file or of a folder on
+ * its way: refused. Through a link to nothing: refused, since a write
+ * would create its target. Reads nothing but the file system's links.
+ * ASCII texts, word for word the extension's (projectWriteLanding) and
+ * vexp-core's.
+ */
+export function projectWriteLanding(file, workspaceRoot) {
+    const landing = landingOf(file);
+    if (landing === undefined)
+        return { ok: false, refuse: `${file} is a link to a file that does not exist - left untouched` };
+    const root = landingOf(workspaceRoot) ?? path.resolve(workspaceRoot);
+    // path.relative folds letter case on Windows, as the file system does.
+    const rel = path.relative(root, landing);
+    if (rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel))
+        return { ok: true, landing };
+    return { ok: false, refuse: `${file} leads outside this project through a link (${landing}) - left untouched` };
+}
+export function projectFileLink(file, workspaceRoot) {
+    if (projectWriteLanding(file, workspaceRoot).ok)
+        return undefined;
+    const landing = landingOf(file);
+    return landing === undefined ? { dangling: true } : { outside: landing };
+}
+/**
+ * Is `file` a project file a pinned writer must check first: a root was
+ * given (the entry is pinned to it) and the file is inside it as spelled?
+ * A writer handed a file elsewhere writes it as it did before.
+ */
+function pinnedProjectFile(file, workspaceRoot) {
+    if (!workspaceRoot)
+        return false;
+    const rel = path.relative(path.resolve(workspaceRoot), path.resolve(file));
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+/**
+ * True when the write to `file` must not happen (projectWriteLanding); the
+ * reason goes to the end of setup (takeUnreachableTargets). Called at the
+ * top of each pinned project writer, before it reads the file.
+ */
+function projectWriteRefused(file, workspaceRoot) {
+    const l = projectWriteLanding(file, workspaceRoot);
+    if (l.ok)
+        return false;
+    if (!unreachableTargets.includes(l.refuse))
+        unreachableTargets.push(l.refuse);
+    return true;
+}
+/**
+ * The first link to nothing among the folders of `rel` under `root`,
+ * walking down from the root, as an absolute path; undefined when there is
+ * none. A folder that is not there ends the walk: nothing under it is
+ * there either. A loop counts as a link to nothing, as in landingOf.
+ * Lockstep with the extension.
+ */
+function danglingFolderOnWay(root, rel) {
+    let at = path.resolve(root);
+    for (const part of rel.split(/[\\/]/)) {
+        if (part === "" || part === ".")
+            continue;
+        at = path.join(at, part);
+        let st;
+        try {
+            st = fs.lstatSync(at);
+        }
+        catch {
+            return undefined;
+        }
+        if (!st.isSymbolicLink())
+            continue;
+        try {
+            fs.statSync(at);
+        }
+        catch {
+            return at;
+        }
+    }
+    return undefined;
+}
+/**
+ * The agent's folder in the workspace (`.cursor`), or a folder on the way
+ * to its instruction file or its project MCP file, that is a link to
+ * nothing: a dotfile manager's link whose checkout is not on this machine,
+ * a folder moved away. mkdirSync throws ENOENT there even with
+ * `recursive`, and so does a write under it, and the exception left the
+ * setup loop: `vexp setup` failed for every agent selected, not only for
+ * the one whose folder it was (bug at 3.3.9). Setup skips that agent,
+ * writes nothing for it and creates nothing, the link's target included:
+ * where it leads is the user's. Lockstep with the extension's
+ * danglingAgentFolder and vexp-core's dangling_folder_on_way.
+ */
+export function danglingAgentFolder(d, workspaceRoot) {
+    // A folder marker is the agent's folder; a file marker's folder is the
+    // one it sits in (.codex for .codex/config.toml, the root for AGENTS.md).
+    const folderMarker = !path.extname(d.detectPath) && d.detectPath !== d.configFile;
+    const rels = [folderMarker ? d.detectPath : path.dirname(d.detectPath), path.dirname(d.configFile)];
+    if (d.mcpConfigFile)
+        rels.push(path.dirname(d.mcpConfigFile));
+    for (const rel of rels) {
+        const dangling = danglingFolderOnWay(workspaceRoot, rel);
+        if (dangling)
+            return dangling;
+    }
+    return undefined;
+}
+/** The words for a folder danglingAgentFolder found: the extension's setup report's, word for word. ASCII only. */
+export function danglingFolderLine(folder) {
+    return `${folder} is a link to a folder that does not exist - left untouched`;
+}
+/** Say at the end of setup (takeUnreachableTargets) that an agent was skipped over a link to nothing. */
+function noteDanglingAgentFolder(folder) {
+    const msg = danglingFolderLine(folder);
+    if (!unreachableTargets.includes(msg))
+        unreachableTargets.push(msg);
+}
+/** The words for an agent whose setup threw part way: the extension's, word for word. */
+export function agentSetupStopped(agent, err) {
+    return `${agent} setup stopped - ${err instanceof Error ? err.message : String(err)}`;
+}
+/** Say at the end of setup (takeUnreachableTargets) that one agent's setup threw part way; the others went on. */
+function noteAgentSetupStopped(agent, err) {
+    const msg = agentSetupStopped(agent, err);
+    if (!unreachableTargets.includes(msg))
+        unreachableTargets.push(msg);
+}
 /**
  * Remove a vexp section from a file we no longer write to, and delete the file
  * when nothing of the user's is left in it.
@@ -1779,7 +2200,7 @@ function warnUnparseable(filePath) {
  * Leaving the old file behind would put a stale, unread copy of our
  * instructions next to the live one.
  */
-export function removeVexpSection(filePath) {
+export function removeVexpSection(filePath, agent) {
     if (!fs.existsSync(filePath))
         return "absent";
     let existing;
@@ -1793,6 +2214,10 @@ export function removeVexpSection(filePath) {
     const endIdx = existing.indexOf(VEXP_MARKER_END);
     if (!marker || endIdx === -1)
         return "absent";
+    // A cleanup for `agent` leaves a file committed to the repository alone
+    // (committedCleanupBlocked): nothing was removed.
+    if (agent !== undefined && committedCleanupBlocked([filePath], agent))
+        return "absent";
     const markerIdx = existing.indexOf(marker[0]);
     let startIdx = markerIdx;
     while (startIdx > 0 && existing[startIdx - 1] !== "\n")
@@ -1840,7 +2265,7 @@ export function cursorRulesTarget(workspaceRoot) {
         /* absent, or a directory */
     }
     if (isFile) {
-        removeVexpSection(legacy);
+        removeVexpSection(legacy, "Cursor");
         if (fs.existsSync(legacy))
             return ".cursorrules";
     }
@@ -1863,12 +2288,26 @@ export function appendOrCreate(filePath, content, version) {
         fs.writeFileSync(filePath, content, "utf-8");
         return "created";
     }
-    let existing = fs.readFileSync(filePath, "utf-8");
+    const original = fs.readFileSync(filePath, "utf-8");
+    let existing = original;
+    // A BOM the file starts with stays in front of it (Visual Studio with
+    // charset = utf-8-bom, Windows PowerShell 5.1's Set-Content -Encoding
+    // UTF8). A section on the first line, or the front matter above it, took
+    // the BOM along in the splice, so a rewrite dropped the user's encoding
+    // mark and a committed file showed one more changed line (review,
+    // 2026-11-08). vexp-core's wizard splices after it and always kept it.
+    // Lockstep with the extension.
+    const bom = original.startsWith("") ? "" : "";
+    const keepBom = (text) => (bom && !text.startsWith(bom) ? bom + text : text);
     // Front matter has to stay the FIRST thing in the file, and the splice below
     // preserves whatever sits above our marker — so a rewrite would leave the
     // old block above and insert a second one. One rule file, one front matter.
+    // A BOM or CRLF line ends (a Windows checkout with core.autocrlf, an
+    // editor that saves CRLF) hid the block from an LF-only match, so every
+    // run added one more (review, 2026-11-08). A BOM in front of the block
+    // goes back in front of the file (keepBom). The template itself is LF.
     if (content.startsWith("---\n")) {
-        const lead = existing.match(/^---\n[\s\S]*?\n---\n/);
+        const lead = existing.match(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---\r?\n/);
         if (lead) {
             existing = existing.slice(lead[0].length).replace(/^\s*\n/, "");
         }
@@ -1888,19 +2327,79 @@ export function appendOrCreate(filePath, content, version) {
     }
     const endIdx = existing.indexOf(VEXP_MARKER_END);
     if (endIdx !== -1) {
-        const existingSection = existing.substring(startIdx, endIdx + VEXP_MARKER_END.length);
-        if (existingSection === content)
-            return "skipped"; // truly identical -> no write
         const before = existing.substring(0, startIdx);
         const after = existing.substring(endIdx + VEXP_MARKER_END.length);
-        fs.writeFileSync(filePath, before + content + after, "utf-8");
+        const next = keepBom(before + content + after);
+        // The same bytes: nothing to write, and not "updated". A rule file with
+        // front matter (Cursor .mdc, Windsurf) never matched a section check,
+        // since the template starts with the front matter and the section with
+        // the marker line, so every run at the same version rewrote it and said
+        // "(updated)", while the same committed file at another version (M1)
+        // said "(up to date)" (review, 2026-11-08). Lockstep with the extension.
+        if (next === original)
+            return "skipped";
+        if (committedMarkerOnly(filePath, original, next))
+            return "skipped";
+        fs.writeFileSync(filePath, next, "utf-8");
     }
     else {
-        const before = existing.substring(0, startIdx);
-        fs.writeFileSync(filePath, before + content, "utf-8");
+        const next = keepBom(existing.substring(0, startIdx) + content);
+        if (committedMarkerOnly(filePath, original, next))
+            return "skipped";
+        fs.writeFileSync(filePath, next, "utf-8");
     }
     return "updated";
 }
+/**
+ * `text` as git compares it in a checkout with core.autocrlf or eol=crlf:
+ * no leading BOM, LF line ends. The section vexp writes is LF, so in such a
+ * checkout a committed file read as CRLF differed from it in every line,
+ * M1 never applied, and each update moved the marker all the same
+ * (review, 2026-11-08). Only compared, never written. Lockstep with the
+ * extension and vexp-core (as_committed).
+ */
+function asCommitted(text) {
+    return text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+}
+/** `text` with the version taken out of every vexp marker, as committed (asCommitted): two texts equal under it differ in nothing but the versions their markers name. */
+function withoutMarkerVersions(text) {
+    return asCommitted(text).replace(/<!-- vexp(?:\s+v[\d.]+)? -->/g, "<!-- vexp -->");
+}
+/**
+ * M1: is rewriting the instruction file `file` from `original` to `next`
+ * a change of the version in vexp's marker and nothing else, in a file git
+ * tracks? Then the file is left as it is and said once (committedMarkerOnlyLine).
+ * Every update moved `<!-- vexp v... -->` in the committed CLAUDE.md,
+ * AGENTS.md and copilot-instructions.md, so every checkout showed them
+ * modified after an update, and teammates on different versions flipped
+ * them back and forth in their commits (field report, 2026-11-07). Any
+ * other version, older or newer, counts: the text the agents read is the
+ * same. git runs last, only for such a file, so a normal project runs none;
+ * an untracked file is rewritten as before. Lockstep with the extension.
+ */
+function committedMarkerOnly(file, original, next) {
+    if (next === original || withoutMarkerVersions(next) !== withoutMarkerVersions(original))
+        return false;
+    if (!isGitTracked(file))
+        return false;
+    // The same version, only a BOM or CRLF line ends differ: this vexp's
+    // section is there already, so the file is left with no word ("differs
+    // only in the version marker" would be untrue).
+    if (asCommitted(next) !== asCommitted(original))
+        noteSetup(committedMarkerOnlyLine(file));
+    return true;
+}
+/**
+ * Merge vexp's keys into a JSON config (Continue.dev's config.json): an
+ * object key by key, an array by name. A key the payload fills that is
+ * there in another shape (Continue's mcpServers as an object, a string,
+ * null) leaves the whole file byte for byte and says so (leftUntouched):
+ * vexp's array replaced it, the user's servers were gone, and setup said
+ * "updated". An element whose name is one of vexp's own is replaced where
+ * it stands, and copies of it after the first go: every run appended
+ * another vexp server and another vexp-context command, so the file never
+ * settled (review, 2026-11-07). Lockstep with the extension.
+ */
 export function mergeJsonConfig(filePath, mergePayload, version) {
     const read = readJsonConfigSafe(filePath);
     if (!read.ok) {
@@ -1908,6 +2407,11 @@ export function mergeJsonConfig(filePath, mergePayload, version) {
         return "skipped";
     }
     const existing = read.data;
+    const misfit = mergeMisfit(existing, mergePayload);
+    if (misfit) {
+        leftUntouched(filePath, misfit.key, misfit.shape);
+        return "skipped";
+    }
     // Build the merged result first, then compare to avoid unnecessary writes.
     const merged = { ...existing };
     for (const [key, value] of Object.entries(mergePayload)) {
@@ -1918,7 +2422,7 @@ export function mergeJsonConfig(filePath, mergePayload, version) {
             };
         }
         else if (Array.isArray(value) && Array.isArray(merged[key])) {
-            merged[key] = [...merged[key], ...value];
+            merged[key] = mergeNamed(merged[key], value);
         }
         else {
             merged[key] = value;
@@ -1931,37 +2435,79 @@ export function mergeJsonConfig(filePath, mergePayload, version) {
     const existingStr = JSON.stringify(existing, null, 2);
     if (mergedStr === existingStr)
         return "skipped";
+    if (committedSentinelOnly(filePath, existing, merged))
+        return "skipped";
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     if (read.existed)
         backupConfig(filePath);
     fs.writeFileSync(filePath, mergedStr, "utf-8");
     return "merged";
 }
-// ---------------------------------------------------------------------------
-// MCP config writers - adapted for Rust binary path
-// ---------------------------------------------------------------------------
-/**
- * Write MCP config JSON for agents that use mcpServers format (Cursor, Windsurf).
- * Returns true if a new entry was written.
- */
 /**
- * Antigravity reads MCP servers from a MACHINE-GLOBAL file:
- * `~/.gemini/antigravity/mcp_config.json` (same schema as the workspace
- * mcp.json files: top-level `mcpServers`, stdio `command`/`args`/`env`;
- * note Antigravity uses `serverUrl` — not `url` — for HTTP servers, which
- * is why we register the stdio transport here).
- *
- * Deliberately NO `VEXP_WORKSPACE` env pin: the file is global, and pinning
- * one workspace breaks every other project (the 2.0.32 multi-session
- * lesson). `vexp-core mcp` resolves the workspace from its spawn cwd.
+ * M1 for Continue's config.json: is the merge a change of `__vexp_version`
+ * and nothing else, in a file git tracks? Then the file is left as it is,
+ * said once in M1's words (committedMarkerOnlyLine): the sentinel is the
+ * marker of a JSON file, and a team that commits .continue/config.json saw
+ * it modified after every update, as with the Markdown files (review,
+ * 2026-11-08). The spread keeps the key where it stands (merged starts as
+ * a copy of existing). git runs last, only for such a merge, so a normal
+ * project runs none; an untracked file is written as before. Lockstep
+ * with the extension.
  */
-/** 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");
+function committedSentinelOnly(file, existing, merged) {
+    if (typeof existing.__vexp_version !== "string")
+        return false;
+    if (JSON.stringify({ ...merged, __vexp_version: existing.__vexp_version }, null, 2) !== JSON.stringify(existing, null, 2))
+        return false;
+    if (!isGitTracked(file))
+        return false;
+    noteSetup(committedMarkerOnlyLine(file));
+    return true;
 }
-/**
- * Devin Desktop Next — the beta channel, formerly Windsurf Next — is a separate
- * install with its own Cascade config under `~/.codeium/windsurf-next/`
+/** The first key of `payload` that `existing` holds in another shape: an array where vexp merges an array, a non-object where an object. */
+function mergeMisfit(existing, payload) {
+    for (const [key, value] of Object.entries(payload)) {
+        if (!Object.prototype.hasOwnProperty.call(existing, key))
+            continue;
+        if (Array.isArray(value) && !Array.isArray(existing[key]))
+            return { key, shape: "an array" };
+        if (asPlainObject(value) && !asPlainObject(existing[key]))
+            return { key, shape: "an object" };
+    }
+    return undefined;
+}
+/** `ours` merged into `theirs` by name: each of ours replaces the first element of that name, later ones of it go, and the rest are appended. */
+function mergeNamed(theirs, ours) {
+    const nameOf = (v) => {
+        const n = asPlainObject(v) ? v.name : undefined;
+        return typeof n === "string" ? n : undefined;
+    };
+    const out = [...theirs];
+    const tail = [];
+    for (const el of ours) {
+        const name = nameOf(el);
+        const at = name === undefined ? -1 : out.findIndex((x) => nameOf(x) === name);
+        if (at < 0) {
+            tail.push(el);
+            continue;
+        }
+        out[at] = el;
+        for (let k = out.length - 1; k > at; k--)
+            if (nameOf(out[k]) === name)
+                out.splice(k, 1);
+    }
+    return [...out, ...tail];
+}
+// ---------------------------------------------------------------------------
+// MCP config writers - adapted for Rust binary path
+// ---------------------------------------------------------------------------
+/** 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,
@@ -1976,7 +2522,8 @@ export function windsurfNextInstalled() {
 export function configureWindsurfNextGlobal(binaryPath, mcpServerPath, workspaceRoot) {
     if (!windsurfNextInstalled())
         return false;
-    return writeMcpConfig(windsurfNextGlobalMcpPath(), binaryPath, VEXP_TOOLS, mcpServerPath, workspaceRoot);
+    // Machine-wide: written through a dotfile manager's link, never checked against the project.
+    return writeMcpServersFile(windsurfNextGlobalMcpPath(), binaryPath, VEXP_TOOLS, mcpServerPath, workspaceRoot, "alwaysAllow");
 }
 /**
  * Windsurf (Cascade) reads MCP servers from ~/.codeium/windsurf/mcp_config.json
@@ -1996,109 +2543,1881 @@ export function configureWindsurfGlobal(binaryPath, mcpServerPath, workspaceRoot
     catch {
         return false;
     }
-    return writeMcpConfig(p, binaryPath, VEXP_TOOLS, mcpServerPath, workspaceRoot);
+    // Machine-wide: written through a dotfile manager's link, never checked against the project.
+    return writeMcpServersFile(p, binaryPath, VEXP_TOOLS, mcpServerPath, workspaceRoot, "alwaysAllow");
 }
 /**
  * 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.
+ * A file that is a link is never deleted nor written over: vexp's member
+ * goes from its target when that is inside the project, and nothing is
+ * touched when it is not (removeProjectMcpEntryThroughLink).
  */
 export function removeDeadWindsurfMcpJson(workspaceRoot) {
     const p = path.join(workspaceRoot, ".windsurf", "mcp.json");
+    let link = false;
+    try {
+        link = fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return "absent";
+    }
+    if (link)
+        return removeProjectMcpEntryThroughLink(p, "mcpServers", workspaceRoot, "Windsurf") === "edited" ? "stripped" : "absent";
     const read = readJsonConfigSafe(p);
     if (!read.existed || !read.ok)
         return "absent";
     const servers = read.data.mcpServers;
     if (!servers || !("vexp" in servers))
         return "absent";
+    if (committedCleanupBlocked([p], "Windsurf"))
+        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";
+        catch { /* best effort */ }
+        return "deleted";
+    }
+    try {
+        fs.writeFileSync(p, JSON.stringify(read.data, null, 2), "utf-8");
+    }
+    catch { /* best effort */ }
+    return "stripped";
+}
+/**
+ * Take vexp's server out of a project MCP file that is a symlink (a
+ * repository that keeps one MCP file and links it where each tool reads
+ * it): such a file is not vexp's to delete. A removal unlinked the link, or
+ * wrote a regular file over it, and a link to a file outside the project
+ * edited a file of the user's elsewhere. So a link whose real path is
+ * inside `workspaceRoot` loses vexp's member in its target, cut out of the
+ * text when that is not strict JSON (removeJsoncMember), and the link and
+ * the target both stay, even with nothing left in it; a link out of the
+ * project, or to nothing, is left as it is, with one line said. Never a
+ * link removed. Lockstep with the extension's twin.
+ */
+export function removeProjectMcpEntryThroughLink(file, key, workspaceRoot, agent) {
+    try {
+        let real;
+        try {
+            real = fs.realpathSync(file);
+        }
+        catch {
+            process.stdout.write(`  - ${file} is a link to a file that does not exist: left as it is\n`);
+            return undefined;
+        }
+        let rootReal = path.resolve(workspaceRoot);
+        try {
+            rootReal = fs.realpathSync(workspaceRoot);
+        }
+        catch {
+            /* compared as written */
+        }
+        const rel = path.relative(rootReal, real);
+        if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) {
+            process.stdout.write(`  - ${file} is a link to ${real}, outside this project: vexp's entry there is left as it is\n`);
+            return undefined;
+        }
+        const read = readJsonConfigSafe(real);
+        if (!read.ok)
+            return undefined;
+        const servers = read.data[key];
+        if (!asPlainObject(servers) || !isVexpWrittenEntry(servers["vexp"]))
+            return undefined;
+        // The link and its target are both the repository's when git tracks either.
+        if (agent !== undefined && committedCleanupBlocked([file, real], agent))
+            return undefined;
+        const raw = fs.readFileSync(real, "utf-8");
+        let next;
+        try {
+            const data = JSON.parse(raw);
+            delete data[key]["vexp"];
+            if (Object.keys(data[key]).length === 0)
+                delete data[key];
+            next = JSON.stringify(data, null, 2) + "\n";
+        }
+        catch {
+            next = removeJsoncMember(raw, key, "vexp");
+        }
+        if (next === undefined) {
+            process.stdout.write(`  - vexp's entry in ${real} (linked from ${file}) could not be cut out of the text: left as it is\n`);
+            return undefined;
+        }
+        backupConfig(file);
+        fs.writeFileSync(real, next, "utf-8");
+        return "edited";
+    }
+    catch {
+        /* best-effort: what could not be removed stays, and is harmless */
+        return undefined;
+    }
+}
+/**
+ * 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");
+}
+// ---------------------------------------------------------------------------
+// Antigravity (Google). Lockstep with packages/vexp-vscode/src/providers/
+// agent-auto-config.ts (configureAntigravityProject,
+// removeDeadAntigravityEntries, isDeadAntigravityEntry).
+//
+// Every current Antigravity build (App 2.x, IDE 2.6, the agy CLI and the
+// VS Code extension) reads MCP servers from ~/.gemini/config/mcp_config.json
+// and from <workspace>/.agents/mcp_config.json. The 1.x file vexp used to
+// write, ~/.gemini/antigravity/mcp_config.json, is read by none of them, and
+// its entry named no project. Measured with agy 1.5.3 (2026-11-07): an MCP
+// server starts in the agy process's own folder (the window's first folder
+// in VS Code, often the home folder in the Antigravity app) and gets no
+// workspace variable, so `vexp-core mcp` with no pin serves whatever folder
+// that is, and from the home folder an empty tool list (field report,
+// 2026-11-07).
+//
+// So the entry goes in the project file, pinned with VEXP_WORKSPACE. The
+// files take no ${VAR} expansion, so the pin is the literal path. Nothing
+// is written machine-wide: a pinned global entry serves one project (the
+// 2.0.32 multi-session rule), an unpinned one serves the wrong folder, and
+// a global `vexp` starts with Antigravity, before any conversation, so it
+// keeps the name and the project's entry, loaded per conversation, is not
+// used. A file that holds only vexp's entry is kept out of git
+// (excludeFromGit).
+// ---------------------------------------------------------------------------
+/** Antigravity's project MCP file, relative to the project root. */
+export const ANTIGRAVITY_PROJECT_MCP = ".agents/mcp_config.json";
+/** Keys of vexp's entry the user may set and Antigravity reads: a rewrite keeps them. */
+export const ANTIGRAVITY_USER_KEYS = ["disabled", "disabledTools", "enabledTools", "tools", "timeoutSeconds"];
+export function antigravityProjectMcpPath(workspaceRoot) {
+    return path.join(workspaceRoot, ".agents", "mcp_config.json");
+}
+/**
+ * Register vexp with Antigravity for this project: `mcpServers.vexp` in
+ * <root>/.agents/mcp_config.json = the binary, `mcp`, and
+ * env.VEXP_WORKSPACE = the root. The binary and never `node`: Antigravity
+ * is a GUI app, and a dock-launched app has no shell PATH (the Kiro lesson).
+ * The file is read as JSONC (comments, trailing commas, a BOM); one that
+ * will not parse is left untouched and reported (takeSkippedConfigs), and
+ * so is one that is not UTF-8 text (takeUnreachableTargets). Only
+ * `mcpServers.vexp` is vexp's: the project's other servers stay, a
+ * `vexp-dev` of the user's among them (no vexp build ever wrote a legacy
+ * `vexp-*` key here), and so do the keys of ANTIGRAVITY_USER_KEYS the user
+ * set inside vexp's entry, and the pin's spelling when it names this
+ * folder already (antigravityPin). An entry of another vexp install that
+ * works and is pinned here is kept (adoptableEntry). A file whose
+ * mcpServers is not an object, or that cannot be written, is left alone
+ * and reported (takeUnreachableTargets), never thrown: `vexp setup` goes
+ * on with the other agents, as the extension and vexp-core do. A file that
+ * leads out of the project through a link, or to nothing, is left as it is
+ * and reported (projectWriteLanding); one that lands on Antigravity's
+ * machine-wide files is refused in its own words first
+ * (antigravityProjectFileBlocked). ZCode's .agents/mcp.json is another file
+ * and is never touched here. Same bytes as the extension's writer. Returns
+ * true when the file was written.
+ */
+export function configureAntigravityProject(workspaceRoot, binaryPath) {
+    const target = antigravityProjectMcpPath(workspaceRoot);
+    const refuse = (reason) => {
+        const msg = `${target} NOT written: it ${reason}`;
+        if (!unreachableTargets.includes(msg))
+            unreachableTargets.push(msg);
+        return false;
+    };
+    const blocked = antigravityProjectFileBlocked(workspaceRoot);
+    if (blocked)
+        return refuse(blocked);
+    if (projectWriteRefused(target, workspaceRoot))
+        return false;
+    const read = readAntigravityProjectFile(target);
+    if (read.notUtf8)
+        return refuse(ANTIGRAVITY_NOT_UTF8);
+    if (!read.ok) {
+        warnUnparseable(target);
+        return false;
+    }
+    const cfg = read.data;
+    if (antigravityServersMisshapen(cfg))
+        return refuse(ANTIGRAVITY_SERVERS_NOT_AN_OBJECT);
+    // The file holds this machine's paths (the binary, this folder), and each
+    // machine's vexp rewrites it with its own. A file that holds only vexp's
+    // entry is vexp's and is never meant for git: it goes into the
+    // repository's own exclude file once the file is settled (written,
+    // already identical, adopted), whether this write created it or found it.
+    // Found matters: the doctor tells a user whose file is committed to run
+    // `git rm --cached`, which leaves it untracked and not ignored, and the
+    // next `git add -A` committed it again. One with other servers or keys is
+    // the project's business (it may be committed on purpose: the doctor says
+    // what that costs), and no git command runs for it, so a start stays
+    // cheap. excludeFromGit's own guards (no repository, no git, ignored
+    // already, tracked, the line there) still decide.
+    const settled = (wrote) => {
+        if (!read.existed || holdsOnlyVexp(cfg))
+            excludeFromGit(workspaceRoot, ANTIGRAVITY_PROJECT_MCP);
+        return wrote;
+    };
+    const targetArgs = ["mcp"];
+    const prev = cfg.mcpServers?.["vexp"];
+    // Committed and pinned by another checkout: see committedPin. A file that
+    // holds this machine's paths is not meant for git (the doctor says how to
+    // take it out), but while it is committed a setup in a worktree must not
+    // repin it either.
+    const committed = committedPin(target, workspaceRoot, envPin(prev?.env));
+    if (committed) {
+        if (!staleVexpInstall(prev))
+            return settled(noteCommittedPin(target, committed));
+        cfg.mcpServers["vexp"] = { ...prev, command: binaryPath, args: targetArgs };
+        try {
+            backupConfig(target);
+            fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+        }
+        catch (e) {
+            return refuse(`could not be written (${e instanceof Error ? e.message : String(e)})`);
+        }
+        return settled(true);
+    }
+    const targetEnv = { VEXP_WORKSPACE: antigravityPin(prev, workspaceRoot) };
+    const envMatches = JSON.stringify(prev?.env) === JSON.stringify(targetEnv);
+    const identical = prev?.command === binaryPath &&
+        Array.isArray(prev?.args) &&
+        JSON.stringify(prev?.args) === JSON.stringify(targetArgs) &&
+        envMatches;
+    if (identical)
+        return settled(false);
+    // Another vexp install already left a working entry here: don't fight it.
+    // The VEXP_WORKSPACE pin still gates, so a moved project is repinned.
+    if (envMatches && adoptableEntry(prev))
+        return settled(false);
+    const servers = cfg.mcpServers ?? {};
+    const kept = {};
+    if (prev && typeof prev === "object") {
+        for (const k of ANTIGRAVITY_USER_KEYS)
+            if (k in prev)
+                kept[k] = prev[k];
+    }
+    servers["vexp"] = { command: binaryPath, args: targetArgs, env: targetEnv, ...kept };
+    cfg.mcpServers = servers;
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        // An empty file, or one of only a BOM and whitespace, holds nothing of
+        // the user's: no backup of it, as in vexp-core.
+        if (read.existed && !read.blank)
+            backupConfig(target);
+        fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+    }
+    catch (e) {
+        return refuse(`could not be written (${e instanceof Error ? e.message : String(e)})`);
+    }
+    return settled(true);
+}
+/**
+ * Does the project file hold nothing but vexp's server: no top-level key
+ * but `mcpServers`, and no server in it but `vexp`? Such a file is vexp's
+ * (settled in configureAntigravityProject) and is kept out of git; the
+ * doctor advises `git rm --cached` only for such a file (doctor.ts,
+ * agOnlyVexp). Lockstep with the extension and vexp-core.
+ */
+export function holdsOnlyVexp(cfg) {
+    if (!Object.keys(cfg).every((k) => k === "mcpServers"))
+        return false;
+    const servers = cfg.mcpServers;
+    return asPlainObject(servers) && Object.keys(servers).every((k) => k === "vexp");
+}
+/** Why a project file whose mcpServers is not an object is left alone. Lockstep with the extension and vexp-core. */
+export const ANTIGRAVITY_SERVERS_NOT_AN_OBJECT = "has an mcpServers that is not an object - left untouched";
+/** Why a project file that is not UTF-8 text is left alone. Lockstep with the extension and vexp-core. */
+export const ANTIGRAVITY_NOT_UTF8 = "is not UTF-8 text - left untouched";
+/**
+ * The project file as the Antigravity writers read it: readJsonConfigSafe's
+ * verdict, but bytes that are not UTF-8 (an ANSI file PowerShell 5.1's
+ * Set-Content writes) are `notUtf8` and never rewritten, as in vexp-core.
+ * Decoded with replacement characters, such a file parsed, and the rewrite
+ * saved another server's `jos\xe9` as `jos\ufffd` (review, 2026-11-07).
+ * `blank` is a file with nothing of the user's in it: absent, empty, or a
+ * BOM and whitespace. Lockstep with the extension.
+ */
+export function readAntigravityProjectFile(target) {
+    if (!fs.existsSync(target))
+        return { data: {}, ok: true, existed: false, blank: true };
+    let raw;
+    try {
+        const bytes = fs.readFileSync(target);
+        try {
+            raw = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        }
+        catch {
+            return { data: {}, ok: false, existed: true, blank: false, notUtf8: true };
+        }
+    }
+    catch {
+        return { data: {}, ok: false, existed: true, blank: false };
+    }
+    if (raw.replace(/^\uFEFF/, "").trim() === "")
+        return { data: {}, ok: true, existed: true, blank: true };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+    }
+    catch {
+        try {
+            parsed = parseJsonc(raw);
+        }
+        catch {
+            return { data: {}, ok: false, existed: true, blank: false };
+        }
+    }
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return { data: parsed, ok: true, existed: true, blank: false };
+    }
+    return { data: {}, ok: false, existed: true, blank: false };
+}
+/** An mcpServers that is there and is not an object (containerMisshapen). vexp-core's writer skips the same files. */
+function antigravityServersMisshapen(data) {
+    return containerMisshapen(data, "mcpServers");
+}
+/**
+ * Do two absolute spellings name one folder: the same path, the same real
+ * path behind a link, or the same Windows path in another letter case? A
+ * relative pin, or one that does not resolve, is only itself.
+ */
+function sameFolder(a, b) {
+    if (a === b)
+        return true;
+    if (!path.isAbsolute(a) || !path.isAbsolute(b))
+        return false;
+    if (process.platform === "win32" && path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase())
+        return true;
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The VEXP_WORKSPACE to write: the root, or the pin vexp's entry already
+ * has when that names the same folder in another spelling. The CLI pins
+ * the shell's path, the extension VS Code's (a lower-case drive letter on
+ * Windows), vexp-core its canonical one, and a project opened through a
+ * link has two; compared as text, each writer rewrote the others' entry,
+ * with a backup, at its next run. Lockstep with the extension and vexp-core.
+ */
+export function antigravityPin(prev, workspaceRoot) {
+    const env = prev && typeof prev === "object" ? prev.env : undefined;
+    const pin = env && typeof env === "object" ? env.VEXP_WORKSPACE : undefined;
+    return typeof pin === "string" && sameFolder(pin, workspaceRoot) ? pin : workspaceRoot;
+}
+/**
+ * Why the project file must not be written, when it must not: `.agents` is
+ * a file, or a link to nothing; the file is a link to nothing (a write
+ * would create its target, wherever that is); or the file, by a link of its
+ * own or through a linked `.agents` folder, is one of Antigravity's
+ * machine-wide files, and writing it would put a pinned entry there for
+ * every project. Lockstep with the extension (and with vexp-core's
+ * register_antigravity_project).
+ */
+export function antigravityProjectFileBlocked(workspaceRoot) {
+    const dir = path.join(workspaceRoot, ".agents");
+    let dirReal;
+    try {
+        if (!fs.statSync(dir).isDirectory())
+            return `cannot be created - ${dir} is a file, not a folder`;
+        dirReal = fs.realpathSync(dir);
+    }
+    catch {
+        try {
+            if (fs.lstatSync(dir).isSymbolicLink())
+                return `cannot be created - ${dir} is a link to a folder that does not exist`;
+        }
+        catch {
+            /* no folder yet: created on write */
+        }
+        return undefined;
+    }
+    const target = antigravityProjectMcpPath(workspaceRoot);
+    let link = false;
+    try {
+        link = fs.lstatSync(target).isSymbolicLink();
+    }
+    catch {
+        /* absent: written in the folder's real place */
+    }
+    let lands = path.join(dirReal, path.basename(target));
+    if (link) {
+        try {
+            lands = fs.realpathSync(target);
+        }
+        catch {
+            return "is a link to a file that does not exist";
+        }
+    }
+    if (!antigravityMachineMcpLocations().includes(lands))
+        return undefined;
+    return link
+        ? "is a link to Antigravity's machine-wide mcp_config.json - vexp registers per project only"
+        : "is in a folder linked to Antigravity's machine-wide config folder - vexp registers per project only";
+}
+/**
+ * An MCP entry vexp wrote: the core binary or the bundled mcp-server.cjs,
+ * named by its path. A bare `vexp-core` looked up on PATH is an entry
+ * someone wrote by hand. Lockstep with the extension's isVexpWrittenEntry.
+ */
+function isVexpWrittenEntry(entry) {
+    const cmd = entryCommand(entry);
+    if (!cmd)
+        return false;
+    const base = (cmd.split(/[\\/]/).pop() ?? "").toLowerCase();
+    if (base.startsWith("vexp-core"))
+        return /[\\/]/.test(cmd);
+    const args = entry.args;
+    return Array.isArray(args) && args.some((a) => typeof a === "string" && /vexp/i.test(a) && /mcp-server\.cjs$/.test(a));
+}
+/**
+ * Does an entry run what a vexp install put on disk: a file in an extension
+ * folder (vexp.vexp-vscode-<ver>), the npm package's binary
+ * (@vexp/core-<platform>), or a bundled mcp-server.cjs? A vexp-core built
+ * or copied anywhere else is the user's own. Lockstep with the extension.
+ */
+function namesVexpInstall(entry) {
+    if (vexpInstallVersion(entry) !== undefined)
+        return true;
+    if (/[\\/]@vexp[\\/]core-[^\\/]+[\\/]/.test(entryCommand(entry) ?? ""))
+        return true;
+    const args = entry.args;
+    return Array.isArray(args) && args.some((a) => typeof a === "string" && /vexp/i.test(a) && /mcp-server\.cjs$/.test(a));
+}
+/**
+ * A machine-wide Antigravity entry that vexp wrote and that names no
+ * project: none of what vexp-core takes a project from (`--workspace`, in
+ * either spelling clap accepts, env VEXP_WORKSPACE or CLAUDE_PROJECT_DIR,
+ * a `cwd`). Such an entry serves whatever folder Antigravity starts it from
+ * (the agy process's own: the window's first folder in VS Code, often the
+ * home folder in the Antigravity app, where it lists no tools), and as it
+ * starts with Antigravity, before any conversation, it keeps the name and
+ * the project's pinned entry is not used (measured with agy 1.5.3,
+ * 2026-11-07). A pinned entry or one the user made is never this. Lockstep
+ * with the extension.
+ */
+export function isDeadAntigravityEntry(entry) {
+    if (!isVexpWrittenEntry(entry) || !namesVexpInstall(entry))
+        return false;
+    const e = entry;
+    const env = e.env;
+    if (env && typeof env === "object" && (typeof env.VEXP_WORKSPACE === "string" || typeof env.CLAUDE_PROJECT_DIR === "string"))
+        return false;
+    if (Array.isArray(e.args) && e.args.some((a) => a === "--workspace" || (typeof a === "string" && a.startsWith("--workspace="))))
+        return false;
+    return !(typeof e.cwd === "string" && e.cwd.trim() !== "");
+}
+/** The 1.x file and today's global one, as named under the home folder. */
+function antigravityMachineMcpNames() {
+    return [antigravityLegacyMcpPath(os.homedir()), antigravityGlobalMcpPath(os.homedir())];
+}
+export function antigravityLegacyMcpPath(home) {
+    return path.join(home, ".gemini", "antigravity", "mcp_config.json");
+}
+export function antigravityGlobalMcpPath(home) {
+    return path.join(home, ".gemini", "config", "mcp_config.json");
+}
+/**
+ * The machine-wide files vexp may take its own dead entry out of: the 1.x
+ * file when it is a regular file, or the file the 1.x name links to (agy's
+ * migration link). Nothing else, and nothing that does not exist. Lockstep
+ * with the extension.
+ */
+export function antigravityFilesVexpCleans(home) {
+    const legacy = antigravityLegacyMcpPath(home);
+    let st;
+    try {
+        st = fs.lstatSync(legacy);
+    }
+    catch {
+        return [];
+    }
+    try {
+        if (st.isFile())
+            return [{ file: fs.realpathSync(legacy), viaLink: false }];
+        if (!st.isSymbolicLink())
+            return [];
+        const real = fs.realpathSync(legacy);
+        return fs.statSync(real).isFile() ? [{ file: real, viaLink: true }] : [];
+    }
+    catch {
+        return []; // a link to nothing
+    }
+}
+/** Does `file` name the same file as one vexp may clean (antigravityFilesVexpCleans)? */
+export function vexpCleansAntigravityFile(home, file) {
+    let real;
+    try {
+        real = fs.realpathSync(file);
+    }
+    catch {
+        return false;
+    }
+    return antigravityFilesVexpCleans(home).some((c) => c.file === real);
+}
+// ---------------------------------------------------------------------------
+// Keeping the project file out of git. <root>/.agents/mcp_config.json holds
+// the absolute path of this machine's vexp binary and of this folder, and
+// every machine's vexp rewrites it with its own: committed, it moves between
+// machines as a diff nobody wants. When a setup creates it, or settles one
+// that holds only vexp's entry, its anchored path goes into the
+// repository's own exclude file, never into .gitignore.
+// Lockstep with the extension (antigravity-files.ts) and vexp-core
+// (agent_mcp.rs): the same two lines.
+// ---------------------------------------------------------------------------
+/** The comment vexp writes above the project file's line in the repository's exclude file. Lockstep with the extension and vexp-core. */
+export const ANTIGRAVITY_EXCLUDE_COMMENT = "# vexp: Antigravity MCP entry with this machine's paths";
+/** How long one git command may take: a setup or a doctor never waits on git for longer. */
+const GIT_TIMEOUT_MS = 3000;
+/**
+ * The variables a git hook, `git --git-dir=... <alias>` or a dotfile
+ * manager's shell hands down, which would make git answer for another
+ * repository than the folder's. Lockstep with the extension and vexp-core
+ * (agent_mcp.rs, GIT_REPO_VARS).
+ */
+const GIT_REPO_VARS = [
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_COMMON_DIR",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    "GIT_NAMESPACE",
+    "GIT_PREFIX",
+];
+/** git run in `cwd`, no shell, bounded; undefined when it could not run at all (not on PATH, timed out). */
+export function gitIn(cwd, args) {
+    // The folder decides the repository, not a GIT_DIR the shell was started with.
+    const env = { ...process.env };
+    for (const k of GIT_REPO_VARS)
+        delete env[k];
+    try {
+        const r = spawnSync("git", args, {
+            cwd,
+            env,
+            encoding: "utf-8",
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (r.error || r.status === null)
+            return undefined;
+        return { status: r.status, stdout: r.stdout ?? "" };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Where `root` sits in its repository: the exclude file git reads for it, and `root` relative to the top level. */
+function repoOf(root) {
+    const r = gitIn(root, ["rev-parse", "--is-inside-work-tree", "--show-prefix", "--git-path", "info/exclude"]);
+    if (!r || r.status !== 0)
+        return undefined;
+    const lines = r.stdout.split(/\r?\n/);
+    if (lines[0] !== "true" || lines.length < 3 || !lines[2])
+        return undefined;
+    return { exclude: path.resolve(root, lines[2]), prefix: lines[1] };
+}
+/** A path as a gitignore pattern matches it literally: the wildcard characters escaped, anchored at the top level. */
+function anchoredPattern(prefix, rel) {
+    return "/" + `${prefix}${rel}`.replace(/[\\*?[]/g, "\\$&");
+}
+function readLines(file) {
+    try {
+        return fs.readFileSync(file, "utf-8").split("\n");
+    }
+    catch (e) {
+        return e.code === "ENOENT" ? [] : undefined;
+    }
+}
+/**
+ * Put the project file (`rel`, relative to `root`) into the repository's
+ * local exclude file (`git rev-parse --git-path info/exclude`: right for a
+ * worktree and a submodule too), as two lines: ANTIGRAVITY_EXCLUDE_COMMENT
+ * and the file's path anchored at the top level. Nothing when `root` is not
+ * in a git work tree, git cannot be run, the file is ignored already or
+ * tracked, or the line is there. Never .gitignore, never thrown: a setup
+ * never fails on it. Returns true when the lines were added. Lockstep with
+ * the extension.
+ */
+export function excludeFromGit(root, rel = ANTIGRAVITY_PROJECT_MCP) {
+    try {
+        const repo = repoOf(root);
+        if (!repo)
+            return false;
+        // Exit 1 is "not ignored" and "not tracked"; 0 is the opposite, and
+        // anything else (a path beyond a symlink, a broken repository) is no
+        // answer: nothing is written then either.
+        const ignored = gitIn(root, ["check-ignore", "-q", "--", rel]);
+        if (!ignored || ignored.status !== 1)
+            return false;
+        const tracked = gitIn(root, ["ls-files", "--error-unmatch", "--", rel]);
+        if (!tracked || tracked.status !== 1)
+            return false;
+        const line = anchoredPattern(repo.prefix, rel);
+        const lines = readLines(repo.exclude);
+        if (!lines || lines.some((l) => l.replace(/\r$/, "") === line))
+            return false;
+        const text = lines.join("\n");
+        const lead = text === "" || text.endsWith("\n") ? "" : "\n";
+        fs.mkdirSync(path.dirname(repo.exclude), { recursive: true });
+        fs.appendFileSync(repo.exclude, `${lead}${ANTIGRAVITY_EXCLUDE_COMMENT}\n${line}\n`);
+        return true;
+    }
+    catch (err) {
+        process.stderr.write(`  [!] could not keep ${rel} out of git: ${err instanceof Error ? err.message : String(err)}\n`);
+        return false;
+    }
+}
+/**
+ * The project file's path relative to the repository's top level when git
+ * tracks it (committed or staged); undefined when it does not, when it is
+ * not on disk, or when git cannot say. The name is git's, in git's letter
+ * case (a committed agents.md asked as AGENTS.md is "agents.md" where
+ * core.ignorecase is true). What the doctor names in its `git rm --cached`
+ * line. Lockstep with the extension.
+ */
+export function gitTrackedPath(root, rel = ANTIGRAVITY_PROJECT_MCP) {
+    try {
+        if (!fs.existsSync(path.join(root, rel)))
+            return undefined;
+        // git matches a pathspec by case even with core.ignorecase: on a
+        // case-insensitive filesystem a committed agents.md, read here as
+        // vexp's AGENTS.md, counted as untracked, and "Not here" edited or
+        // deleted it (review, 2026-11-07). So git is asked case-blind
+        // (`literal` also keeps glob characters in a name from being read as a
+        // pattern), and a name in another case counts only where git itself
+        // folds case, core.ignorecase=true, the rule git status follows. Never
+        // decided by the OS: a Windows folder mounted in a Linux container is
+        // case-insensitive too. A git too old for the magic exits 128: not
+        // tracked, as before. -z: the name as it is, not C-quoted (core.quotePath).
+        const want = rel.split(path.sep).join("/");
+        const r = gitIn(root, ["ls-files", "-z", "--full-name", "--", `:(literal,icase)${want}`]);
+        if (!r || r.status !== 0)
+            return undefined;
+        const names = r.stdout.split("\0").filter((n) => n !== "");
+        const exact = names.find((n) => n === want || n.endsWith(`/${want}`));
+        if (exact !== undefined)
+            return exact;
+        const lower = want.toLowerCase();
+        const folded = names.find((n) => n.toLowerCase() === lower || n.toLowerCase().endsWith(`/${lower}`));
+        if (folded === undefined)
+            return undefined;
+        const ic = gitIn(root, ["config", "--bool", "core.ignorecase"]);
+        return ic?.status === 0 && ic.stdout.trim() === "true" ? folded : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// Files committed to the repository (field report, 2026-11-07). A file git
+// tracks is checked out unchanged in every clone and every linked worktree:
+// a setup run in a worktree that rewrote it with its own path, or a cleanup
+// that deleted it, showed up as a change on that branch, and an agent's
+// `git add -A` carried it back to the main checkout on merge. So a writer
+// never rewrites a tracked project file only to point it at this checkout
+// (committedPin), and a cleanup never deletes or edits a tracked file
+// (committedCleanupBlocked). Both say so at the end of setup
+// (takeSetupNotes), in the words the extension logs. Lockstep with the
+// extension (agent-auto-config.ts).
+// ---------------------------------------------------------------------------
+/**
+ * Is `file` tracked by git (`git ls-files --error-unmatch`, through
+ * gitTrackedPath: no shell, the file's own folder as cwd, 3 s, the
+ * GIT_DIR family removed)? Not in a repository, git missing, or the file
+ * not on disk: not tracked.
+ */
+export function isGitTracked(file) {
+    return gitTrackedPath(path.dirname(file), path.basename(file)) !== undefined;
+}
+/** What a setup left as it is on purpose, said at its end. ASCII only. */
+const setupNotes = [];
+/** Drain the notes (call after a setup run to print them). */
+export function takeSetupNotes() {
+    return setupNotes.splice(0, setupNotes.length);
+}
+/** Note a line once per run. */
+function noteSetup(line) {
+    if (!setupNotes.includes(line))
+        setupNotes.push(line);
+}
+/** Why a cleanup left a committed file alone. Word for word the extension's. */
+export function committedCleanupLine(file, agent) {
+    return `${file} is committed to this repository, so vexp left it as it is - remove vexp's part from it in a commit if this project no longer uses ${agent}`;
+}
+/** Why a writer left a committed file pinned to another checkout alone. Word for word the extension's. */
+export function committedPinLine(file, other) {
+    return `${file} is committed to this repository and names ${other}; vexp left it as it is`;
+}
+/**
+ * Why a committed instruction file was left with the marker of another
+ * vexp version (M1): its vexp section is, but for the version inside
+ * `<!-- vexp v... -->`, what this vexp writes. Word for word the extension's.
+ */
+export function committedMarkerOnlyLine(file) {
+    return `${file} is committed to this repository and its vexp section differs only in the version marker; vexp left it as it is`;
+}
+/** Why .vscode/mcp.json gets no vexp entry (W4). Word for word the extension's. */
+export const MCP_JSON_DEFINES_VEXP = ".mcp.json already defines vexp, so vexp left it out of .vscode/mcp.json (VS Code would use that one and turn the .mcp.json entry off)";
+/**
+ * The folder an MCP entry pins vexp to by name, read as the server the
+ * entry runs reads it, or undefined for an entry that pins nothing.
+ * vexp-core (`mcp`) lets `--workspace <dir>` / `--workspace=<dir>` win over
+ * env VEXP_WORKSPACE (cmd_mcp reads the env only with no flag); the Node
+ * server, an entry that runs a bundled mcp-server.cjs, parses no
+ * --workspace and reads env only. Here, not in the doctor, because the
+ * Copilot writer applies the same .mcp.json condition (dotMcpJsonMiss);
+ * doctor.ts re-exports it. Lockstep with the extension's vexpPinOf.
+ */
+export function vexpPinOf(entry) {
+    if (!asPlainObject(entry))
+        return undefined;
+    const e = entry;
+    const env = asPlainObject(e.env) ? e.env : undefined;
+    const fromEnv = typeof env?.VEXP_WORKSPACE === "string" && env.VEXP_WORKSPACE.trim() ? { pin: env.VEXP_WORKSPACE, from: "env" } : undefined;
+    const args = Array.isArray(e.args) ? e.args : [];
+    if (args.some((a) => typeof a === "string" && /mcp-server\.cjs$/i.test(a)))
+        return fromEnv;
+    const i = args.indexOf("--workspace");
+    if (i >= 0 && typeof args[i + 1] === "string" && args[i + 1].trim())
+        return { pin: args[i + 1], from: "args" };
+    const eq = args.find((a) => typeof a === "string" && a.startsWith("--workspace=") && a.length > 12);
+    return eq ? { pin: eq.slice(12), from: "args" } : fromEnv;
+}
+/**
+ * Do two spellings name one folder, by the extension's rule (mcp-folder.ts
+ * samePath): the same spelling once resolved and without a trailing
+ * separator, case-folded on Windows only, else the same folder once links
+ * are resolved. The CLI's samePath folds case on every OS and resolves
+ * links only on Windows, so these findings warned for a root spelled
+ * through a link (/home -> /var/home, /tmp -> /private/tmp on macOS) that
+ * the extension read as this workspace, and read /app/WT as /app/wt on
+ * Linux (review, 2026-11-07). Not on darwin either: macOS realpath already
+ * returns the case on disk, and folding would be wrong on a case-sensitive
+ * APFS volume. The doctors' rule, used by the writer's .mcp.json condition
+ * too (dotMcpJsonMiss). Lockstep with the extension.
+ */
+export function sameFolderAsExtension(a, b) {
+    const key = (p) => {
+        const r = path.resolve(p).replace(/[\\/]+$/, "");
+        const k = r.length > 0 ? r : path.resolve(p);
+        return process.platform === "win32" ? k.toLowerCase() : k;
+    };
+    if (key(a) === key(b))
+        return true;
+    try {
+        return key(fs.realpathSync.native(a)) === key(fs.realpathSync.native(b));
+    }
+    catch {
+        return false; // one of them is not there: only the spelling can match
+    }
+}
+/**
+ * M2: would `entry`, the vexp server of `<root>/.mcp.json`, serve this
+ * root when VS Code starts it? undefined when it would, else why not. Only
+ * then may vexp leave its own entry out of .vscode/mcp.json (W4): VS Code
+ * turns the .mcp.json server off as soon as .vscode/mcp.json defines one by
+ * the same name, so leaving ours out hands Copilot the .mcp.json one, and a
+ * committed .mcp.json pinned to the main checkout, or running a `vexp-core`
+ * that is not on PATH (the npm CLI puts only `vexp` there), gave a worktree
+ * window the main checkout's index or no vexp at all (field report,
+ * 2026-11-07).
+ *   (a) the pin, as VS Code expands it in .mcp.json (dotMcpJsonPin): none,
+ *       this root (sameFolderAsExtension; a relative pin is read against
+ *       the root, the folder VS Code starts the server in), or an env
+ *       VEXP_WORKSPACE that still holds `${` or is blank (VS Code expands no
+ *       ${workspaceFolder} in .mcp.json, and both servers then fall back to
+ *       that folder, E3). A --workspace in args that names no folder fails:
+ *       vexp-core exits on it;
+ *   (b) the command: a stdio entry (an http or sse one fails) whose command,
+ *       expanded as VS Code does, is an absolute path to an executable file
+ *       or a bare name found on this process's PATH (with PATHEXT on
+ *       Windows), and, when it runs node or vexp's bundle, whose absolute
+ *       script paths in args exist.
+ * The pin is asked first, so a line names the pin when both fail. Read only
+ * the file system, never git. Lockstep with the extension's dotMcpJsonMiss.
+ */
+export function dotMcpJsonMiss(entry, root, env = process.env, platform = process.platform) {
+    // A --workspace that vexp-core cannot take (no value after it, or
+    // `--workspace=` alone) stops it before it reads anything else.
+    if (workspaceFlagWithoutValue(entry))
+        return { pin: NO_WORKSPACE_VALUE };
+    const p = vexpPinOf(entry);
+    if (p !== undefined) {
+        // The pin as VS Code hands it over from .mcp.json (dotMcpJsonPin), so
+        // this line and D2 name the same folder for one entry.
+        const folder = dotMcpJsonPin(p.pin, root, env, platform);
+        if (folder !== undefined && !sameFolderAsExtension(folder, root))
+            return { pin: folder };
+        // Only an env pin that names no folder falls back to the folder: both
+        // servers drop such a VEXP_WORKSPACE (utils::workspace_env_value,
+        // workspaceEnv), while vexp-core canonicalizes a --workspace value and
+        // exits on one that names no folder ("Cannot resolve workspace path").
+        // A `--workspace ${workspaceFolder}` that VS Code moved verbatim from
+        // .vscode/mcp.json into .mcp.json passed here, and vexp's working entry
+        // was removed for a server that dies at start (review, 2026-11-08).
+        if (folder === undefined && p.from === "args") {
+            const text = dotMcpJsonExpand(p.pin, env, platform);
+            return { pin: text.trim() === "" ? NO_WORKSPACE_VALUE : text };
+        }
+    }
+    const command = dotMcpJsonCommandMissing(entry, env, platform);
+    return command === undefined ? undefined : { command };
+}
+/** What the (a) line names for a --workspace with no usable value. ASCII, the extension's words. */
+export const NO_WORKSPACE_VALUE = "(none: --workspace has no value)";
+/**
+ * Does `entry` (not one that runs vexp's Node bundle, which parses no
+ * --workspace) hand vexp-core a --workspace it cannot take: the last arg,
+ * one followed by a blank or a non-string, or `--workspace=` alone?
+ * vexpPinOf reads no pin there and falls back to env, but vexp-core exits
+ * on it first. Lockstep with the extension.
+ */
+function workspaceFlagWithoutValue(entry) {
+    if (!asPlainObject(entry) || !Array.isArray(entry.args))
+        return false;
+    const args = entry.args;
+    if (args.some((a) => typeof a === "string" && /mcp-server\.cjs$/i.test(a)))
+        return false;
+    const i = args.indexOf("--workspace");
+    if (i >= 0)
+        return !(typeof args[i + 1] === "string" && args[i + 1].trim() !== "");
+    return args.includes("--workspace=");
+}
+/** dotMcpJsonMiss (b): undefined when the entry would start here, else the command text its line names. */
+function dotMcpJsonCommandMissing(entry, env, platform) {
+    const e = asPlainObject(entry) ? entry : {};
+    if (typeof e.type === "string" && e.type.toLowerCase() !== "stdio")
+        return `(none: a ${e.type} server)`;
+    if (typeof e.command !== "string" || e.command.trim() === "")
+        return "(none)";
+    // VS Code expands the command and every arg of a .mcp.json entry from its
+    // environment before it starts the server (dotMcpJsonExpand): what is
+    // looked for here is what it runs.
+    const command = dotMcpJsonExpand(e.command, env, platform);
+    if (!commandFoundHere(command, env, platform))
+        return command;
+    const p = platform === "win32" ? path.win32 : path.posix;
+    const args = Array.isArray(e.args) ? e.args.filter((a) => typeof a === "string").map((a) => dotMcpJsonExpand(a, env, platform)) : [];
+    const base = p.basename(command).toLowerCase().replace(/\.exe$/, "");
+    if (base === "node" || base === "nodejs" || args.some((a) => /mcp-server\.cjs$/i.test(a))) {
+        // A script needs to be there, not executable: node reads it.
+        const missing = args.find((a) => p.isAbsolute(a) && /\.[cm]?js$/i.test(a) && !isPlainFile(a));
+        if (missing !== undefined)
+            return `${command} ${missing}`;
+    }
+    return undefined;
+}
+/** A command VS Code could start: an absolute path to an executable file, or a bare name on PATH (PATHEXT on Windows). A relative path names neither. */
+function commandFoundHere(command, env, platform) {
+    const win = platform === "win32";
+    if ((win ? path.win32 : path.posix).isAbsolute(command))
+        return runnableFile(command, platform);
+    if (/[\\/]/.test(command))
+        return false;
+    // Windows keeps the variable as Path; the lookup is case-blind there.
+    const pathVar = win ? Object.entries(env).find(([k]) => k.toUpperCase() === "PATH")?.[1] : env.PATH;
+    const pathExt = win ? Object.entries(env).find(([k]) => k.toUpperCase() === "PATHEXT")?.[1] : undefined;
+    const exts = (pathExt ?? ".COM;.EXE;.BAT;.CMD").split(";").filter((x) => x !== "");
+    const names = !win ? [command] : exts.some((x) => command.toLowerCase().endsWith(x.toLowerCase())) ? [command] : exts.map((x) => command + x);
+    for (const dir of (pathVar ?? "").split(win ? ";" : ":")) {
+        if (dir === "")
+            continue;
+        if (names.some((n) => runnableFile(path.join(dir, n), platform)))
+            return true;
+    }
+    return false;
+}
+function isPlainFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** A file, executable for this user except on Windows (where a file is enough). */
+function runnableFile(p, platform) {
+    try {
+        if (!fs.statSync(p).isFile())
+            return false;
+        if (platform !== "win32")
+            fs.accessSync(p, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why vexp writes its own entry into .vscode/mcp.json although
+ * `<root>/.mcp.json` defines vexp (M2): a setup note and the doctor's INFO
+ * line, word for word the extension's. ASCII.
+ */
+export function dotMcpJsonKeptLine(root, miss) {
+    const file = path.join(root, ".mcp.json");
+    return miss.pin !== undefined
+        ? `${file} has a vexp server pinned to ${miss.pin}, so vexp keeps its own entry in .vscode/mcp.json, which VS Code uses here instead`
+        : `${file} has a vexp server whose command ${miss.command} is not found here, so vexp keeps its own entry in .vscode/mcp.json, which VS Code uses here instead`;
+}
+/**
+ * A linked worktree's .vscode/mcp.json that holds vexp alone, without the
+ * servers of the main checkout's copy, which git does not track and so `git
+ * worktree add` did not check out (W5). Word for word the extension's
+ * worktreeMcpJsonLine. ASCII.
+ */
+export function worktreeMcpJsonLine(file, mainFile, names) {
+    return `${file} was created with vexp only: ${mainFile} is not tracked by git, so its other servers (${names.join(", ")}) are not in this worktree - copy them here, or move them to your user mcp.json so every window has them`;
+}
+/**
+ * The W5 line for `file`, a .vscode/mcp.json inside the linked worktree
+ * `workspaceRoot` that holds vexp alone, while the main checkout's copy at
+ * the same place is untracked and holds other servers; undefined anywhere
+ * else. What
+ * `vexp doctor` says (D4): `git worktree add` checks out only what git
+ * tracks, so a repository whose .gitignore leaves .vscode/* out gave the
+ * worktree no copy, and a setup made one with vexp alone (field report,
+ * 2026-11-07: "dropped teamdocs"). vexp never copies another server. Lockstep
+ * with the extension's worktreeMcpJsonNote.
+ */
+export function worktreeMcpJsonNote(workspaceRoot, file) {
+    const main = linkedWorktreeMain(workspaceRoot);
+    if (!main)
+        return undefined;
+    const rel = path.relative(workspaceRoot, file);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return undefined;
+    const mainFile = path.join(main, rel);
+    if (!fs.existsSync(mainFile) || !fs.existsSync(file) || isGitTracked(mainFile))
+        return undefined;
+    const theirs = readJsonConfigSafe(mainFile);
+    const servers = theirs.ok ? theirs.data.servers : undefined;
+    if (!asPlainObject(servers))
+        return undefined;
+    const here = readJsonConfigSafe(file);
+    const ours = here.ok && asPlainObject(here.data.servers) ? Object.keys(here.data.servers) : [];
+    // The line says the file "was created with vexp only" (W5): true only
+    // while it holds vexp alone. A file with a server of the user's, or none,
+    // or one that does not parse, was made or changed by hand, and the doctor,
+    // which asks at every run, misstated it (review, 2026-11-07).
+    if (ours.length === 0 || ours.some((n) => n.toLowerCase() !== "vexp"))
+        return undefined;
+    const names = Object.keys(servers).filter((n) => n.toLowerCase() !== "vexp");
+    return names.length > 0 ? worktreeMcpJsonLine(file, mainFile, names) : undefined;
+}
+/**
+ * True when a cleanup for `agent` must not run: one of `files` (those that
+ * exist) is committed to this repository. Each such file gets
+ * committedCleanupLine. The caller then changes none of them, so a hook
+ * script and the entry that runs it stay together.
+ */
+function committedCleanupBlocked(files, agent) {
+    let blocked = false;
+    for (const f of files) {
+        if (!f || !fs.existsSync(f) || !isGitTracked(f))
+            continue;
+        noteSetup(committedCleanupLine(f, agent));
+        blocked = true;
+    }
+    return blocked;
+}
+/** The hook scripts the latest hookScriptCurrent call for each left as committed (K1): what the setup report must not call written. */
+const hookScriptsLeft = new Set();
+/** Did the latest setup leave the committed hook script `file` as it was (hookScriptCurrent)? */
+export function hookScriptLeft(file) {
+    return hookScriptsLeft.has(file);
+}
+/**
+ * Does the hook script at `file` need no write: it holds `wanted` already,
+ * or it is committed to the repository, holds exactly what this vexp writes
+ * for the engine path it bakes (`plainFor`, in this CLI's form or with the
+ * extension's upgrade fallback) and that path still finds a working engine
+ * here (K1, hook-scripts.ts committedHookScriptStays)? The second case is
+ * said at the end of setup (committedHookScriptLine). Every writer of a
+ * script with a baked engine path asks here first: another machine, an
+ * extension update or the extension's own copy rewrote the committed
+ * .claude/hooks and .codex scripts in every checkout, and `git add -A`
+ * committed the churn (field report, 2026-11-07). git runs only for a
+ * script that differs from `wanted` and is this vexp's text for another
+ * engine path. Lockstep with the extension's hookScriptCurrent.
+ */
+function hookScriptCurrent(file, wanted, plainFor) {
+    hookScriptsLeft.delete(file);
+    const text = readHookScript(file);
+    if (text === undefined)
+        return false;
+    if (text === wanted)
+        return true;
+    if (!committedHookScriptStays(text, plainFor, () => isGitTracked(file)))
+        return false;
+    noteSetup(committedHookScriptLine(file));
+    hookScriptsLeft.add(file);
+    return true;
+}
+/**
+ * The folder a vexp pin names once VS Code has expanded it: `root` for
+ * "${workspaceFolder}" or "${workspaceFolder:<name>}" alone (optionally
+ * followed by one separator); ${userHome} becomes the home folder and
+ * ${env:NAME} the variable's value. undefined when a variable is left that
+ * cannot be expanded here (${input:...}, ${config:...},
+ * ${workspaceFolder}/sub, an unset ${env:NAME}): such a pin is not
+ * compared. "Any pin with ${ is this root" let a committed
+ * "${userHome}/src/app", which VS Code expands to one folder in every
+ * checkout, serve that folder's index to each worktree with no word from
+ * either doctor (review, 2026-11-07). Lockstep with the extension's.
+ */
+export function expandedPin(pin, root, env = process.env, home = os.homedir()) {
+    if (/^\$\{workspaceFolder(?::[^}]*)?\}[\\/]?$/.test(pin))
+        return root;
+    let unresolved = false;
+    const out = pin.replace(/\$\{(userHome|env:([^}]+))\}/g, (_m, v, name) => {
+        if (v === "userHome")
+            return home;
+        const val = name === undefined ? undefined : env[name];
+        if (!val)
+            unresolved = true;
+        return val ?? "";
+    });
+    return unresolved || out.includes("${") ? undefined : out;
+}
+/**
+ * A value of <root>/.mcp.json as VS Code (1.142+) hands it to the server,
+ * by the Copilot CLI's rules it follows there (mcpEnvironmentVariableExpansion,
+ * envVarResolution): `${NAME}` and `${NAME:-default}` take NAME
+ * (`[A-Za-z_][A-Za-z0-9_]*`) from `env`, case-blind on Windows; a variable
+ * set to "" gives "", and a default is put in as it is, never expanded
+ * again. An unset name with no default, a bare `$NAME`, and the variables
+ * of .vscode/mcp.json (`${userHome}`, `${env:X}`, `${workspaceFolder}`,
+ * `${input:x}`) stay verbatim; a value over 1000 characters is left whole.
+ * A default ends at its first `}` here: VS Code also balances `${...}` and
+ * `$(...)` inside one, which a vexp pin or command has no use for. Read
+ * with expandedPin, .vscode/mcp.json's rules, "${userHome}/elsewhere" got
+ * a D2 warning beside D4's [OK] for one entry, and "${HOME}", which VS Code
+ * does expand, passed M2 (review, 2026-11-08). Lockstep with the
+ * extension's.
+ */
+export function dotMcpJsonExpand(value, env = process.env, platform = process.platform) {
+    if (value.length > 1000)
+        return value;
+    const lookup = (name) => {
+        if (env[name] !== undefined || platform !== "win32")
+            return env[name];
+        const key = Object.keys(env).find((k) => k.toUpperCase() === name.toUpperCase());
+        return key === undefined ? undefined : env[key];
+    };
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (whole, name, fallback) => {
+        const v = lookup(name);
+        if (v !== undefined)
+            return v;
+        return fallback ?? whole;
+    });
+}
+/**
+ * The folder a vexp pin of <root>/.mcp.json names once VS Code has
+ * expanded it (dotMcpJsonExpand), read against `root`, the folder VS Code
+ * starts the server in; undefined when it names none: what is left still
+ * holds `${`, or is blank. Both servers drop such a VEXP_WORKSPACE and
+ * serve that folder (E3). M2 (a) and D2 read .mcp.json through it, so the
+ * two lines agree on one entry; .vscode/mcp.json is read with expandedPin.
+ * Lockstep with the extension's.
+ */
+export function dotMcpJsonPin(pin, root, env = process.env, platform = process.platform) {
+    const value = dotMcpJsonExpand(pin, env, platform);
+    if (value.trim() === "" || value.includes("${"))
+        return undefined;
+    return path.resolve(root, value);
+}
+/** The VEXP_WORKSPACE of an entry's env, if it has one. */
+function envPin(env) {
+    return asPlainObject(env) ? env.VEXP_WORKSPACE : undefined;
+}
+/**
+ * The pin a writer keeps in a committed project file: `file` is inside
+ * `workspaceRoot` and tracked by git, and vexp's entry there is pinned
+ * (`prevPin`) to a folder other than this one (another checkout's absolute
+ * path, `other`), or by a variable the agent expands (`${workspaceFolder}`,
+ * the same text in every checkout). The writer then leaves the pin as it
+ * is, and touches the entry only when the vexp install it runs is gone
+ * (staleVexpInstall). undefined when the writer pins as before: no pin, a
+ * relative one, this folder in any spelling, a machine-wide file, an
+ * untracked one. git runs only for an entry pinned so. Lockstep with the
+ * extension's committedPinElsewhere.
+ */
+function committedPin(file, workspaceRoot, prevPin) {
+    if (!pinnedProjectFile(file, workspaceRoot))
+        return undefined;
+    if (typeof prevPin !== "string" || prevPin === "")
+        return undefined;
+    const variable = prevPin.includes("${");
+    if (!variable && (!path.isAbsolute(prevPin) || sameFolder(prevPin, workspaceRoot)))
+        return undefined;
+    // Another checkout of this repository on this machine only: a pin a
+    // teammate's clone, a moved folder or a removed worktree left names a
+    // folder that is not a checkout of this repository here, and the writer
+    // pins as before (sameRepositoryCheckout).
+    if (!variable && !sameRepositoryCheckout(prevPin, workspaceRoot))
+        return undefined;
+    if (!isGitTracked(file))
+        return undefined;
+    if (!variable)
+        return { pin: prevPin, other: prevPin };
+    // A variable that VS Code expands to one folder in every checkout
+    // (${userHome}/..., ${env:NAME}) is kept as before, and named when that
+    // folder is not this one (expandedPin).
+    const folder = expandedPin(prevPin, workspaceRoot);
+    return folder !== undefined && path.isAbsolute(folder) && !sameFolder(folder, workspaceRoot)
+        ? { pin: prevPin, other: folder }
+        : { pin: prevPin };
+}
+/** Say why a committed file pinned elsewhere was left alone; false, for the writers' return. */
+function noteCommittedPin(file, kept) {
+    if (kept.other)
+        noteSetup(committedPinLine(file, kept.other));
+    return false;
+}
+/**
+ * Does `entry` run a vexp install that is gone? Its command or a script it
+ * names lies in a vexp install (namesVexpInstall: an extension folder, the
+ * npm package's binary, a bundled mcp-server.cjs) and does not resolve any
+ * more. In every shape the writers read (Kilo's command array, Zed's nested
+ * command). The only reason to touch an entry in a committed file another
+ * checkout pinned, or a `.mcp.json` the user keeps: a bare `node` or another
+ * install's working path is the same on every checkout. The CLI's own entry
+ * names no versioned folder, so "older than this install" never applies
+ * here; the extension's twin also moves one into an older extension folder.
+ */
+function staleVexpInstall(entry) {
+    if (!asPlainObject(entry))
+        return false;
+    let command = entry.command;
+    let args = entry.args;
+    if (Array.isArray(command)) {
+        args = command.slice(1);
+        command = command[0];
+    }
+    else if (asPlainObject(command)) {
+        args = command.args;
+        command = command.path;
+    }
+    const flat = { command, args };
+    return namesVexpInstall(flat) && !vexpEntryStillResolves(entry);
+}
+/**
+ * The layout of a JSON(C) text whose top level is an object: comments,
+ * trailing commas and a BOM allowed, by the rules removeJsoncMember reads
+ * them. undefined when the text is not shaped so.
+ */
+function jsoncLayout(text) {
+    const n = text.length;
+    const skip = (i) => {
+        for (;;) {
+            while (i < n && /\s/.test(text[i]))
+                i++; // \s takes a BOM too
+            if (text[i] === "/" && text[i + 1] === "/") {
+                while (i < n && text[i] !== "\n")
+                    i++;
+            }
+            else if (text[i] === "/" && text[i + 1] === "*") {
+                const close = text.indexOf("*/", i + 2);
+                if (close < 0)
+                    throw new Error("open comment");
+                i = close + 2;
+            }
+            else {
+                return i;
+            }
+        }
+    };
+    const str = (i) => {
+        for (i++; i < n; i++) {
+            if (text[i] === "\\")
+                i++;
+            else if (text[i] === '"')
+                return i + 1;
+        }
+        throw new Error("open string");
+    };
+    const value = (i) => {
+        if (text[i] === '"')
+            return { start: i, end: str(i), kind: "other", members: [] };
+        if (text[i] === "{" || text[i] === "[") {
+            const close = text[i] === "{" ? "}" : "]";
+            const members = [];
+            let j = skip(i + 1);
+            while (text[j] !== close) {
+                if (j >= n)
+                    throw new Error("open container");
+                const start = j;
+                let key = "";
+                if (close === "}") {
+                    if (text[j] !== '"')
+                        throw new Error("key expected");
+                    const keyEnd = str(j);
+                    key = JSON.parse(text.slice(j, keyEnd));
+                    j = skip(keyEnd);
+                    if (text[j] !== ":")
+                        throw new Error(": expected");
+                    j = skip(j + 1);
+                }
+                const v = value(j);
+                const m = { key, start, end: v.end, value: v };
+                j = skip(v.end);
+                if (text[j] === ",") {
+                    m.comma = j;
+                    j = skip(j + 1);
+                }
+                else if (text[j] !== close) {
+                    throw new Error(", expected");
+                }
+                members.push(m);
+            }
+            return { start: i, end: j + 1, kind: close === "}" ? "object" : "array", members };
+        }
+        let end = i;
+        while (end < n && !/[\s,}\]\/]/.test(text[end]))
+            end++;
+        if (end === i)
+            throw new Error("value expected");
+        return { start: i, end, kind: "other", members: [] };
+    };
+    try {
+        const at = skip(0);
+        if (text[at] !== "{")
+            return undefined;
+        const top = value(at);
+        if (skip(top.end) !== n)
+            return undefined;
+        return top;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The blanks that open the line `pos` is on. */
+function lineIndent(text, pos) {
+    let s = pos;
+    while (s > 0 && text[s - 1] !== "\n")
+        s--;
+    let e = s;
+    while (e < pos && (text[e] === " " || text[e] === "\t"))
+        e++;
+    return text.slice(s, e);
+}
+/** Is `pos` the first thing on its line? */
+function startsLine(text, pos) {
+    let s = pos;
+    while (s > 0 && (text[s - 1] === " " || text[s - 1] === "\t"))
+        s--;
+    return s === 0 || text[s - 1] === "\n";
+}
+/**
+ * `value` set at `keys` (a path of object keys from the top level) in a
+ * JSON(C) text, and nothing else changed: the user's comments, BOM, key
+ * order, layout and last newline stay. A member that is there gets its
+ * value replaced where it stands; one that is not is added after the last
+ * member of its object (an object on the way that is missing is added the
+ * same way, holding the rest of the path). The new text is indented as the
+ * file is. undefined when the text is not shaped so, a key on the path is
+ * there twice or is not an object, or the result would not parse to
+ * exactly the same data with that value set: the caller then writes the
+ * file as it did before. The counterpart of removeJsoncMember. Lockstep
+ * with the extension.
+ */
+export function upsertJsoncMember(text, keys, value) {
+    if (keys.length === 0)
+        return undefined;
+    const top = jsoncLayout(text);
+    if (!top)
+        return undefined;
+    const nl = text.includes("\r\n") ? "\r\n" : "\n";
+    let unit = "  ";
+    const base = lineIndent(text, top.start);
+    for (const m of top.members) {
+        if (!startsLine(text, m.start))
+            continue;
+        const ind = lineIndent(text, m.start);
+        if (ind.startsWith(base) && ind.length > base.length)
+            unit = ind.slice(base.length);
+        break;
+    }
+    const render = (v, indent) => JSON.stringify(v, null, unit).split("\n").join(nl + indent);
+    let node = top;
+    let depth = 0;
+    for (; depth < keys.length - 1; depth++) {
+        const hits = node.members.filter((m) => m.key === keys[depth]);
+        if (hits.length > 1)
+            return undefined;
+        if (hits.length === 0)
+            break;
+        if (hits[0].value.kind !== "object")
+            return undefined;
+        node = hits[0].value;
+    }
+    const hits = node.members.filter((m) => m.key === keys[depth]);
+    if (hits.length > 1)
+        return undefined;
+    let out;
+    if (depth === keys.length - 1 && hits.length === 1) {
+        const m = hits[0];
+        // A list or a value that sat on one line stays on one line (the args of
+        // a one-line entry); an object is laid out as the file is, unless it
+        // shares its line with other members (a one-line file), where it stays
+        // on that line: laid out, it broke the line in two. The extension's
+        // twin keeps the same rule, so both write the same bytes.
+        const oneLine = !text.slice(m.value.start, m.value.end).includes("\n") && (!asPlainObject(value) || !startsLine(text, m.start));
+        out = text.slice(0, m.value.start) + (oneLine ? JSON.stringify(value) : render(value, lineIndent(text, m.start))) + text.slice(m.value.end);
+    }
+    else {
+        let v = value;
+        for (let k = keys.length - 1; k > depth; k--)
+            v = { [keys[k]]: v };
+        const key = JSON.stringify(keys[depth]);
+        const parentIndent = lineIndent(text, node.start);
+        if (node.members.length === 0) {
+            const indent = parentIndent + unit;
+            const open = node.start + 1;
+            const inner = text.slice(open, node.end - 1);
+            out =
+                inner.trim() === ""
+                    ? text.slice(0, open) + nl + indent + key + ": " + render(v, indent) + nl + parentIndent + text.slice(node.end - 1)
+                    : text.slice(0, open) + nl + indent + key + ": " + render(v, indent) + text.slice(open);
+        }
+        else {
+            const last = node.members[node.members.length - 1];
+            const after = last.comma !== undefined ? last.comma + 1 : last.end;
+            const close = node.end - 1;
+            const comma = last.comma === undefined ? "," : "";
+            // The rest of the last member's line: blanks and a // comment, which
+            // stay with it; the new member goes on the line after.
+            let q = after;
+            while (q < close && (text[q] === " " || text[q] === "\t"))
+                q++;
+            if (text[q] === "/" && text[q + 1] === "/")
+                while (q < close && text[q] !== "\n")
+                    q++;
+            if (text[q] === "\r" && text[q + 1] === "\n")
+                q++;
+            if (text[q] === "\n" && q < close) {
+                const at = q + 1;
+                const indent = startsLine(text, last.start) ? lineIndent(text, last.start) : parentIndent + unit;
+                out = text.slice(0, last.end) + comma + text.slice(last.end, at) + indent + key + ": " + render(v, indent) + nl + text.slice(at);
+            }
+            else {
+                // All on one line: the member goes right after the last one.
+                out = text.slice(0, after) + (comma ? ", " : " ") + key + ": " + JSON.stringify(v) + text.slice(after);
+            }
+        }
+    }
+    try {
+        const want = parseJsonc(text);
+        let o = want;
+        for (let k = 0; k < keys.length - 1; k++) {
+            if (!asPlainObject(o[keys[k]]))
+                o[keys[k]] = {};
+            o = o[keys[k]];
+        }
+        o[keys[keys.length - 1]] = value;
+        return JSON.stringify(parseJsonc(out)) === JSON.stringify(want) ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The text a JSON MCP writer saves, and the encoding to save it in: `want`,
+ * the data it means to write, which differs from the file's data only by
+ * vexp's member `key`.`inner` (set to `entry`) and the legacy members it
+ * took out (`removed`). A file that is absent or blank is written whole,
+ * as before; one in exactly the layout JSON.stringify(data, null, 2) gives
+ * (what vexp itself writes) gets the bytes the full rewrite gave before,
+ * its BOM and last newline kept; any other file gets only those members
+ * edited in its text (upsertJsoncMember, removeJsoncMember), so its
+ * comments, BOM, layout and last newline stay. Bytes that are not UTF-8
+ * are edited one latin1 character per byte when vexp's own value is ASCII,
+ * so a teammate's `jos\xe9` stays one byte: the full rewrite saved it as
+ * U+FFFD and dropped every comment. If the edit cannot be made safely, the
+ * whole file, as before. The same algorithm as the extension's
+ * memberEditedText, so both twins write the same bytes (worktree-lockstep).
+ */
+function memberEditedText(file, want, key, inner, entry, removed = []) {
+    const whole = { text: JSON.stringify(want, null, 2), encoding: "utf-8" };
+    let bytes;
+    try {
+        bytes = fs.readFileSync(file);
+    }
+    catch {
+        return whole;
+    }
+    let raw;
+    let encoding = "utf-8";
+    try {
+        raw = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        if (!/^[\x00-\x7f]*$/.test(JSON.stringify(entry)))
+            return whole;
+        raw = bytes.toString("latin1");
+        encoding = "latin1";
+    }
+    const bom = raw.charCodeAt(0) === 0xfeff ? "" : "";
+    const body = raw.slice(bom.length);
+    if (body.trim() === "")
+        return whole;
+    try {
+        const canon = JSON.stringify(JSON.parse(body), null, 2);
+        if (body.startsWith(canon) && body.slice(canon.length).trim() === "") {
+            return { text: bom + JSON.stringify(want, null, 2) + body.slice(canon.length), encoding };
+        }
+    }
+    catch {
+        /* JSONC: edited in its text */
+    }
+    let text = raw;
+    for (const k of removed) {
+        text = removeJsoncMember(text, key, k);
+        if (text === undefined)
+            return whole;
+    }
+    text = upsertJsoncMember(text, [key, inner], entry);
+    if (text === undefined)
+        return whole;
+    try {
+        return JSON.stringify(parseJsonc(text)) === JSON.stringify(want) ? { text, encoding } : whole;
+    }
+    catch {
+        return whole;
+    }
+}
+/**
+ * Every real path a write to one of Antigravity's machine-wide files lands
+ * on: each file's own, and its folder's real path joined with its name, so
+ * a link into a folder that holds no such file yet counts as well.
+ */
+function antigravityMachineMcpLocations() {
+    const out = [];
+    for (const p of antigravityMachineMcpNames()) {
+        for (const real of [() => fs.realpathSync(p), () => path.join(fs.realpathSync(path.dirname(p)), path.basename(p))]) {
+            try {
+                const r = real();
+                if (!out.includes(r))
+                    out.push(r);
+            }
+            catch {
+                /* absent */
+            }
+        }
+    }
+    return out;
+}
+/**
+ * `text` with the member `inner` of the top-level object's `outer` object
+ * cut out, and nothing else changed: the user's comments, trailing commas,
+ * BOM and layout stay. Undefined when the text is not shaped so, a key is
+ * there twice, or the cut would not leave exactly the same data less that
+ * member: the caller then leaves the file as it is. Lockstep with the
+ * extension.
+ */
+export function removeJsoncMember(text, outer, inner) {
+    const n = text.length;
+    const skip = (i) => {
+        for (;;) {
+            while (i < n && /\s/.test(text[i]))
+                i++; // \s takes a BOM too
+            if (text[i] === "/" && text[i + 1] === "/") {
+                while (i < n && text[i] !== "\n")
+                    i++;
+            }
+            else if (text[i] === "/" && text[i + 1] === "*") {
+                const close = text.indexOf("*/", i + 2);
+                if (close < 0)
+                    throw new Error("open comment");
+                i = close + 2;
+            }
+            else {
+                return i;
+            }
+        }
+    };
+    const str = (i) => {
+        for (i++; i < n; i++) {
+            if (text[i] === "\\")
+                i++;
+            else if (text[i] === '"')
+                return i + 1;
+        }
+        throw new Error("open string");
+    };
+    const container = (i) => {
+        const close = text[i] === "{" ? "}" : "]";
+        const members = [];
+        i = skip(i + 1);
+        while (text[i] !== close) {
+            if (i >= n)
+                throw new Error("open container");
+            const start = i;
+            let key = "";
+            if (close === "}") {
+                if (text[i] !== '"')
+                    throw new Error("key expected");
+                const keyEnd = str(i);
+                key = JSON.parse(text.slice(i, keyEnd));
+                i = skip(keyEnd);
+                if (text[i] !== ":")
+                    throw new Error(": expected");
+                i = skip(i + 1);
+            }
+            const valueStart = i;
+            let end;
+            if (text[i] === '"')
+                end = str(i);
+            else if (text[i] === "{" || text[i] === "[")
+                end = container(i).end;
+            else {
+                end = i;
+                while (end < n && !/[\s,}\]\/]/.test(text[end]))
+                    end++;
+                if (end === i)
+                    throw new Error("value expected");
+            }
+            const m = { key, start, valueStart, end };
+            i = skip(end);
+            if (text[i] === ",") {
+                m.comma = i;
+                i = skip(i + 1);
+            }
+            else if (text[i] !== close) {
+                throw new Error(", expected");
+            }
+            members.push(m);
+        }
+        return { end: i + 1, members };
+    };
+    try {
+        const at = skip(0);
+        if (text[at] !== "{")
+            return undefined;
+        const top = container(at);
+        if (skip(top.end) !== n)
+            return undefined;
+        const outers = top.members.filter((m) => m.key === outer);
+        if (outers.length !== 1 || text[outers[0].valueStart] !== "{")
+            return undefined;
+        const members = container(outers[0].valueStart).members;
+        const hits = members.filter((m) => m.key === inner);
+        if (hits.length !== 1)
+            return undefined;
+        const hit = hits[0];
+        const k = members.indexOf(hit);
+        // The member with its own comma; the last one without, and then the
+        // comma before it (only that byte: a comment after it is the user's).
+        const cuts = [];
+        let from = hit.start;
+        let to = hit.comma !== undefined ? hit.comma + 1 : hit.end;
+        let a = from;
+        while (a > 0 && (text[a - 1] === " " || text[a - 1] === "\t"))
+            a--;
+        let b = to;
+        while (b < n && (text[b] === " " || text[b] === "\t"))
+            b++;
+        if ((a === 0 || text[a - 1] === "\n") && (text[b] === "\n" || (text[b] === "\r" && text[b + 1] === "\n"))) {
+            // The member's own line: the whole line goes.
+            from = a;
+            to = b + (text[b] === "\r" ? 2 : 1);
+        }
+        else if (hit.comma !== undefined) {
+            to = b; // and the blanks after its comma
+        }
+        else {
+            from = a; // and the blanks before it
+        }
+        cuts.push([from, to]);
+        if (hit.comma === undefined && k > 0) {
+            const before = members[k - 1].comma;
+            cuts.unshift([before, before + 1]);
+        }
+        let out = text;
+        for (const [s, e] of [...cuts].reverse())
+            out = out.slice(0, s) + out.slice(e);
+        // Same data less that member, or nothing.
+        const want = parseJsonc(text);
+        delete want[outer][inner];
+        return JSON.stringify(parseJsonc(out)) === JSON.stringify(want) ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The machine-wide files vexp may take its dead entry out of
+ * (antigravityFilesVexpCleans: the 1.x file while it is a regular file, or
+ * the file the 1.x name links to) that hold one now, by real path.
+ */
+function deadAntigravityEntryCleanables() {
+    return antigravityFilesVexpCleans(os.homedir()).filter(({ file }) => {
+        const read = readJsonConfigSafe(file);
+        const servers = read.ok ? read.data.mcpServers : undefined;
+        return asPlainObject(servers) && isDeadAntigravityEntry(servers["vexp"]);
+    });
+}
+/** The files deadAntigravityEntryCleanables names, for the dry run. */
+export function deadAntigravityEntryFiles() {
+    return deadAntigravityEntryCleanables().map((c) => c.file);
+}
+/**
+ * Take out the machine-wide Antigravity entries earlier setups wrote
+ * (isDeadAntigravityEntry): up to 3.3.9 every start rewrote an unpinned one
+ * into the 1.x file, ~/.gemini/antigravity/mcp_config.json. A pinned entry
+ * and one the user made stay; so does the rest of each file: one that is
+ * not strict JSON (the user's comments, trailing commas, a BOM) loses only
+ * vexp's member (removeJsoncMember) and keeps its text, and one that cannot
+ * be cut so, or does not parse, is left as found.
+ *
+ * Only where vexp's entry can be (antigravityFilesVexpCleans): the 1.x file
+ * while it is a regular file, and the file the 1.x name links to. The first
+ * start of the Antigravity IDE or of its VS Code extension MOVES the 1.x
+ * file onto ~/.gemini/config/mcp_config.json, replacing the user's global
+ * servers, and leaves the 1.x name a link to it, through which 3.3.9 kept
+ * writing (agy 1.5.3, measured 2026-11-07). The global file reached any
+ * other way is the user's or Antigravity's: never edited, the doctor names
+ * what is in it.
+ *
+ * A regular 1.x file left with no server and no other key is deleted, not
+ * written empty, with no backup (it held only vexp's own entry), with an
+ * old mcp_config.json.vexp-bak beside it, and then ~/.gemini/antigravity
+ * when that is empty: a leftover file there is what Antigravity's first
+ * start moves over the user's global servers, and the empty folder vexp
+ * made looked like Antigravity on the machine (antigravityOnThisMachine).
+ * Through the link the target is never deleted, even when it is left with
+ * no servers: it is Antigravity's global file. Same bytes as the extension.
+ * Returns the files changed or deleted.
+ */
+export function removeDeadAntigravityEntries() {
+    const cleaned = [];
+    const deleted = [];
+    for (const { file, viaLink } of deadAntigravityEntryCleanables()) {
+        try {
+            const cut = withoutVexpMember(fs.readFileSync(file), "mcpServers");
+            if (cut === undefined) {
+                process.stdout.write(`  - vexp's old Antigravity entry (no VEXP_WORKSPACE) is still in ${file}: remove "vexp" from its mcpServers by hand\n`);
+                continue;
+            }
+            if (!viaLink && antigravityHoldsNothing(cut.text) && !globalFileIs(file)) {
+                fs.unlinkSync(file);
+                // The backup goes only when it is vexp's too: up to 3.3.9 the CLI
+                // backed the file up before each write that also dropped any server
+                // named vexp-*, so the copy can be the only one left of the user's
+                // own server (review, 2026-11-07, round 5).
+                const backup = `${file}.vexp-bak`;
+                if (holdsNothingButVexp(backup))
+                    fs.rmSync(backup, { force: true });
+                removeDirIfEmpty(path.dirname(file));
+                deleted.push(file);
+                continue;
+            }
+            backupConfig(file);
+            fs.writeFileSync(file, cut.text, cut.encoding);
+            cleaned.push(file);
+        }
+        catch {
+            /* best-effort: what is left there, the doctor names */
+        }
     }
-    try {
-        fs.writeFileSync(p, JSON.stringify(read.data, null, 2), "utf-8");
+    for (const file of cleaned) {
+        process.stdout.write(`  - Removed vexp's old Antigravity entry (no VEXP_WORKSPACE): ${file}\n`);
     }
-    catch { /* best effort */ }
-    return "stripped";
+    for (const file of deleted) {
+        process.stdout.write(`  - Deleted ${file}: it held only vexp's old Antigravity entry, ${antigravityLegacyHarm(os.homedir())}\n`);
+    }
+    return [...cleaned, ...deleted];
 }
 /**
- * True inside WSL. `procVersion` is injectable for tests; when given, it is
- * the only thing consulted.
+ * Why a 1.x file that held only vexp's entry is deleted, as the doctor's
+ * note on it says (agLegacyNote): once ~/.gemini/config/.migrated is there,
+ * Antigravity never moves the file again, and "its first start moves that
+ * file over the global one" contradicted the doctor run just before
+ * (review, 2026-11-07, round 5). Lockstep with the extension.
  */
-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;
+export function antigravityLegacyHarm(home) {
+    return fs.existsSync(path.join(home, ".gemini", "config", ".migrated"))
+        ? "in a file current Antigravity builds no longer read"
+        : "and Antigravity's first start moves that file over ~/.gemini/config/mcp_config.json, replacing the servers there";
+}
+/**
+ * The text of a JSON(C) file with vexp's member of `key` cut out, and the
+ * encoding to write it back in; undefined when it cannot be cut so.
+ * Strict UTF-8 JSON is rewritten as JSON; anything else loses only vexp's
+ * member (removeJsoncMember), so comments stay. A file that is not UTF-8
+ * (an ANSI file PowerShell 5.1's Set-Content writes) is read one latin1
+ * character per byte and written back the same way: decoded as UTF-8, the
+ * rewrite saved every non-ASCII byte of the user's other servers as U+FFFD
+ * (review, 2026-11-07, round 5). JSON's own syntax is ASCII, so the cut
+ * finds the same members, and every byte outside vexp's goes back as it
+ * was. `dropEmpty`: the key goes too when vexp was all it held (strict
+ * JSON only). Lockstep with the extension.
+ */
+export function withoutVexpMember(bytes, key, dropEmpty = false) {
+    let raw;
     try {
-        return /microsoft/i.test(fs.readFileSync("/proc/version", "utf-8"));
+        raw = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
     }
     catch {
-        return false;
+        const text = removeJsoncMember(bytes.toString("latin1"), key, "vexp");
+        return text === undefined ? undefined : { text, encoding: "latin1", strict: false };
+    }
+    try {
+        const data = JSON.parse(raw);
+        if (!asPlainObject(data) || !asPlainObject(data[key]))
+            return undefined;
+        delete data[key]["vexp"];
+        if (dropEmpty && Object.keys(data[key]).length === 0)
+            delete data[key];
+        return { text: JSON.stringify(data, null, 2) + "\n", encoding: "utf-8", strict: true };
+    }
+    catch {
+        const text = removeJsoncMember(raw, key, "vexp");
+        return text === undefined ? undefined : { text, encoding: "utf-8", strict: false };
     }
 }
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
+/** An MCP config that holds vexp's server and nothing else, or nothing at all. Lockstep with the extension's holdsNothingButVexp. */
+function holdsNothingButVexp(file) {
+    if (!fs.existsSync(file))
+        return false;
+    const read = readJsonConfigSafe(file);
+    if (!read.ok)
+        return false;
+    const servers = read.data.mcpServers;
+    if (Object.keys(read.data).some((k) => k !== "mcpServers"))
+        return false;
+    if (servers === undefined)
+        return true;
+    if (!asPlainObject(servers))
+        return false;
+    return Object.entries(servers).every(([name, entry]) => name === "vexp" && isVexpWrittenEntry(entry));
 }
 /**
- * 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.
+ * removeDeadAntigravityEntries at the end of every setup, whichever agents
+ * it sets up, as the extension does at every start (repairMachineEntries).
+ * Run only with Antigravity chosen, it left a CLI-only machine the 1.x file
+ * 3.3.9 wrote, which the first start of the Antigravity IDE or of its VS
+ * Code extension moves over the user's global servers, while the doctor
+ * called it harmless (review, 2026-11-07). The entries are vexp's own and
+ * named no project. Never thrown: setup never fails on it.
  */
-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");
+function removeDeadAntigravityEntriesAtSetup() {
+    try {
+        removeDeadAntigravityEntries();
+    }
+    catch {
+        /* best-effort: what is left there, the doctor names */
+    }
+}
+/** A JSON(C) text whose data is nothing: no key, or only an empty mcpServers. */
+function antigravityHoldsNothing(text) {
+    try {
+        const data = parseJsonc(text);
+        if (!asPlainObject(data))
+            return false;
+        return Object.keys(data).every((k) => k === "mcpServers") && (data.mcpServers === undefined || (asPlainObject(data.mcpServers) && Object.keys(data.mcpServers).length === 0));
+    }
+    catch {
+        return false;
+    }
 }
-export function configureAntigravityGlobal(binaryPath, mcpServerPath) {
-    const cfgDir = path.join(os.homedir(), ".gemini", "antigravity");
+/** Is ~/.gemini/config/mcp_config.json this file, by a link of its own? Then the file is not deleted from under it. */
+function globalFileIs(file) {
     try {
-        fs.mkdirSync(cfgDir, { recursive: true });
+        return fs.realpathSync(antigravityGlobalMcpPath(os.homedir())) === file;
     }
     catch {
         return false;
     }
-    return writeMcpConfig(path.join(cfgDir, "mcp_config.json"), binaryPath, undefined, mcpServerPath, undefined);
 }
+/** Remove `dir` when it is empty; anything else is left as it is. */
+function removeDirIfEmpty(dir) {
+    try {
+        if (fs.readdirSync(dir).length === 0)
+            fs.rmdirSync(dir);
+    }
+    catch {
+        /* absent, or not ours to remove */
+    }
+}
+/**
+ * Write vexp's entry into an `mcpServers` file. A file inside the workspace
+ * root, pinned to it (Cursor, Kiro, Trae, Firebase Studio, .devin, ZCode's
+ * compatibility file), is checked first: through a link out of the project,
+ * or to nothing, it is left as it is (projectWriteLanding). The machine-wide
+ * Windsurf files go through writeMcpServersFile, unchecked.
+ */
 export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot, 
 // Key under which the auto-approve tool list is written. Cursor/Windsurf use
 // `alwaysAllow`; Kiro uses `autoApprove` (a `.kiro/settings/mcp.json` field).
 approveKey = "alwaysAllow") {
+    if (pinnedProjectFile(mcpConfigPath, workspaceRoot) && projectWriteRefused(mcpConfigPath, workspaceRoot))
+        return false;
+    return writeMcpServersFile(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot, approveKey);
+}
+function writeMcpServersFile(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot, approveKey) {
     const read = readJsonConfigSafe(mcpConfigPath);
     if (!read.ok) {
         warnUnparseable(mcpConfigPath);
         return false;
     }
     const existing = read.data;
+    if (containerMisshapen(existing, "mcpServers"))
+        return leftUntouched(mcpConfigPath, "mcpServers");
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
@@ -2108,6 +4427,18 @@ approveKey = "alwaysAllow") {
     const currentCmd = previousVexp?.["command"];
     const prevArgs = Array.isArray(previousVexp?.["args"]) ? previousVexp?.["args"] : undefined;
     const prevEnv = previousVexp?.env;
+    // A project file committed to the repository, pinned by another checkout:
+    // the pin stays, and the command and args change only when the vexp
+    // install they name is gone (committedPin). Machine-wide files are never this.
+    const kept = committedPin(mcpConfigPath, workspaceRoot, envPin(prevEnv));
+    if (kept) {
+        if (!staleVexpInstall(previousVexp))
+            return noteCommittedPin(mcpConfigPath, kept);
+        beforeServers["vexp"] = { ...previousVexp, command: targetCmd, args: targetArgs };
+        backupConfig(mcpConfigPath);
+        fs.writeFileSync(mcpConfigPath, JSON.stringify(existing, null, 2), "utf-8");
+        return true;
+    }
     const envMatches = JSON.stringify(prevEnv) === JSON.stringify(targetEnv);
     const identical = currentCmd === targetCmd &&
         prevArgs !== undefined &&
@@ -2176,6 +4507,12 @@ export function zcodeMcpTarget(workspaceRoot) {
     if (fs.existsSync(native))
         return native;
     const compat = path.join(workspaceRoot, ".agents", "mcp.json");
+    // A compatibility file reached through a link out of the project is not
+    // read: nothing is read through such a link. It may hold the project's
+    // servers, so it is the target, which the writer leaves as it is and
+    // names, rather than a native file that would unplug them.
+    if (fs.existsSync(compat) && !projectWriteLanding(compat, workspaceRoot).ok)
+        return compat;
     const read = readJsonConfigSafe(compat);
     if (read.existed && read.ok) {
         const servers = read.data.mcpServers;
@@ -2195,20 +4532,43 @@ export function configureZcodeMcp(workspaceRoot, binaryPath) {
     const rel = path.relative(workspaceRoot, target).replace(/\\/g, "/");
     if (rel === ".agents/mcp.json") {
         // The compatibility file has the mcpServers shape the shared writer
-        // knows; withholding mcpServerPath selects the binary transport.
+        // knows; withholding mcpServerPath selects the binary transport. The
+        // shared writer checks where the write lands.
         return writeMcpConfig(target, binaryPath, undefined, undefined, workspaceRoot) ? rel : null;
     }
+    if (projectWriteRefused(target, workspaceRoot))
+        return null;
     const read = readJsonConfigSafe(target);
     if (!read.ok) {
         warnUnparseable(target);
         return null;
     }
     const cfg = read.data;
+    // The key the entry goes under is not an object: left untouched and
+    // reported (leftUntouched), as the shared writer does for the
+    // compatibility file above.
+    const misshapen = containerMisshapen(cfg, "mcp")
+        ? "mcp"
+        : asPlainObject(cfg.mcp) && containerMisshapen(cfg.mcp, "servers") && "mcp.servers";
+    if (misshapen) {
+        leftUntouched(target, misshapen);
+        return null;
+    }
     const mcp = (cfg.mcp && typeof cfg.mcp === "object" ? cfg.mcp : {});
     const servers = (mcp.servers && typeof mcp.servers === "object" ? mcp.servers : {});
     const targetArgs = ["mcp"];
     const targetEnv = { VEXP_WORKSPACE: workspaceRoot };
     const prev = servers["vexp"];
+    // Committed and pinned by another checkout: see committedPin.
+    const kept = committedPin(target, workspaceRoot, envPin(prev?.env));
+    if (kept) {
+        if (!staleVexpInstall(prev))
+            return noteCommittedPin(target, kept) || null;
+        servers["vexp"] = { ...prev, command: binaryPath, args: targetArgs };
+        backupConfig(target);
+        fs.writeFileSync(target, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+        return rel;
+    }
     const envMatches = JSON.stringify(prev?.env) === JSON.stringify(targetEnv);
     const identical = prev?.command === binaryPath &&
         JSON.stringify(prev?.args) === JSON.stringify(targetArgs) &&
@@ -2600,23 +4960,269 @@ export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot,
     atomicWriteFileSync(configPath, content);
     return true;
 }
+/**
+ * The VEXP_WORKSPACE vexp's .vscode/mcp.json entry gets. When the folder that
+ * holds `.vscode/mcp.json` is the workspace root, "${workspaceFolder}": every
+ * VS Code that reads the file (1.99+) expands it to that folder before it
+ * starts the server, or does not start it; where the literal reaches a
+ * server anyway (a .mcp.json entry, a client that expands nothing), both MCP
+ * servers take a value still holding "${" for no pin, and the session's
+ * folder decides. No "cwd" is written: VS Code 1.101.1+ starts the server
+ * in that folder already, 1.99-1.100 ignore the key, and 1.139+ refuses to
+ * migrate an entry that has one to .mcp.json. The absolute root went into a file teams commit, so
+ * every checkout and worktree that ran a setup repinned it to itself, and
+ * main repinned it back after the merge (field report, 2026-11-07). Only a
+ * file in a subfolder of the root (a multi-root window with the root not
+ * listed: the extension's case; the CLI writes at the root) keeps the
+ * absolute root, since the index lives there. Lockstep with the extension.
+ */
+export function vsCodeMcpPin(p, workspaceRoot) {
+    const holder = path.dirname(path.dirname(path.resolve(p)));
+    const atRoot = path.basename(path.dirname(path.resolve(p))) === ".vscode" && sameFolder(holder, path.resolve(workspaceRoot));
+    return atRoot ? "${workspaceFolder}" : workspaceRoot;
+}
+/**
+ * The server named vexp, in any letter case, in `<root>/.mcp.json`: the
+ * portable file VS Code 1.139+ migrates .vscode/mcp.json into and Claude
+ * Code reads as its project scope. Read as JSON, JSONC or with a BOM, and
+ * through a link, as VS Code and Claude Code read it: a .mcp.json linked
+ * from a shared folder still defines vexp for them, and a vexp entry added
+ * to .vscode/mcp.json would turn that one off. Writing through such a link
+ * is refused all the same (maintainProjectMcpJson). Nothing from a file
+ * whose mcpServers is not an object. undefined when there is no such
+ * server. Lockstep with the extension's dotMcpJsonVexp.
+ */
+export function projectMcpJsonVexp(workspaceRoot) {
+    const file = path.join(workspaceRoot, ".mcp.json");
+    if (!fs.existsSync(file))
+        return undefined;
+    const read = readJsonConfigSafe(file);
+    if (!read.ok)
+        return undefined;
+    const servers = read.data.mcpServers;
+    if (!asPlainObject(servers))
+        return undefined;
+    const name = Object.keys(servers).find((k) => k.toLowerCase() === "vexp");
+    return name === undefined ? undefined : { file, name, entry: servers[name] };
+}
+/**
+ * The command and args a vexp entry gets when the install it names is gone
+ * (staleVexpInstall), in the shape it has: an entry that runs a bundled
+ * mcp-server.cjs gets this node and this bundle in place of the old one,
+ * its other arguments kept; one that runs vexp-core gets this binary, its
+ * arguments (`mcp`, a `--workspace`) kept. undefined for any other shape.
+ */
+function repairedCommand(entry, binaryPath, mcpServerPath) {
+    if (!asPlainObject(entry) || typeof entry.command !== "string")
+        return undefined;
+    const args = Array.isArray(entry.args) ? entry.args : [];
+    const isBundle = (a) => typeof a === "string" && /mcp-server\.cjs$/.test(a);
+    if (args.some(isBundle)) {
+        if (!mcpServerPath || !fs.existsSync(mcpServerPath))
+            return { command: binaryPath, args: ["mcp"] };
+        return { command: resolveNodeCommand(), args: args.map((a) => (isBundle(a) ? mcpServerPath : a)) };
+    }
+    const base = (entry.command.split(/[\\/]/).pop() ?? "").toLowerCase();
+    if (base.startsWith("vexp-core"))
+        return { command: binaryPath, args };
+    return undefined;
+}
+/**
+ * W4: keep the vexp server of `<root>/.mcp.json` runnable. When its command
+ * or args point into a vexp install that is gone (staleVexpInstall), only
+ * those two are changed, in the text (upsertJsoncMember): its env, type,
+ * tools and everything else in the file stay as they are, and a pin is
+ * never touched. Never creates the file; a link out of the project or to
+ * nothing is left alone (projectWriteLanding), and so is a file that is
+ * not UTF-8. Returns true when the file was written.
+ */
+export function maintainProjectMcpJson(workspaceRoot, binaryPath, mcpServerPath) {
+    const found = projectMcpJsonVexp(workspaceRoot);
+    if (!found || !staleVexpInstall(found.entry))
+        return false;
+    const repaired = repairedCommand(found.entry, binaryPath, mcpServerPath);
+    if (!repaired)
+        return false;
+    const entry = found.entry;
+    if (entry.command === repaired.command && JSON.stringify(entry.args) === JSON.stringify(repaired.args))
+        return false;
+    if (projectWriteRefused(found.file, workspaceRoot))
+        return false;
+    let raw;
+    try {
+        raw = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(found.file));
+    }
+    catch {
+        return false;
+    }
+    let text = upsertJsoncMember(raw, ["mcpServers", found.name, "command"], repaired.command);
+    if (text !== undefined)
+        text = upsertJsoncMember(text, ["mcpServers", found.name, "args"], repaired.args);
+    if (text === undefined) {
+        // The text could not be edited safely: the whole file, as the writers
+        // here always did.
+        const data = parseJsonc(raw);
+        data.mcpServers[found.name] = { ...data.mcpServers[found.name], command: repaired.command, args: repaired.args };
+        text = JSON.stringify(data, null, 2) + "\n";
+    }
+    backupConfig(found.file);
+    fs.writeFileSync(found.file, text, "utf-8");
+    return true;
+}
+/**
+ * W4: `<root>/.mcp.json` defines vexp, so .vscode/mcp.json gets no vexp
+ * entry: VS Code would start that one and turn the .mcp.json entry off (a
+ * name in .vscode/mcp.json wins), and that is the one the user kept. vexp's
+ * own entry (isVexpWrittenEntry; never one the user wrote, never one pinned
+ * to another folder) goes from .vscode/mcp.json, cut out of its text
+ * (removeJsoncMember), and the file goes only when nothing at all is left
+ * in it, no comment either, and then its folder when that is empty. A file
+ * committed to the repository is left as it is (committedCleanupBlocked),
+ * and so is one that leads out of the project through a link
+ * (projectWriteLanding). Says MCP_JSON_DEFINES_VEXP once. Lockstep with
+ * the extension's leaveVexpOutOfVsCodeMcp.
+ */
+function leaveVexpOutOfVsCodeMcp(p, workspaceRoot) {
+    try {
+        // A .vscode/mcp.json that is itself a link loses vexp's member in its
+        // target, and the link stays (removeProjectMcpEntryThroughLink, the
+        // round-5 rule): unlinked when nothing was left, the repository's link
+        // was gone. The extension's removeProjectMcpEntry does the same.
+        let link = false;
+        try {
+            link = fs.lstatSync(p).isSymbolicLink();
+        }
+        catch {
+            return; // absent
+        }
+        if (link) {
+            removeProjectMcpEntryThroughLink(p, "servers", workspaceRoot, "GitHub Copilot");
+            return;
+        }
+        // Nothing is read through a folder that leads out of the project.
+        if (!fs.existsSync(p) || !projectWriteLanding(p, workspaceRoot).ok)
+            return;
+        const read = readJsonConfigSafe(p);
+        const servers = read.ok ? read.data.servers : undefined;
+        if (!asPlainObject(servers) || !isVexpWrittenEntry(servers["vexp"]))
+            return;
+        const pin = envPin(servers["vexp"].env);
+        // "${workspaceFolder}" names whichever checkout reads the file: this one.
+        if (typeof pin === "string" && !pin.includes("${") && !sameFolder(pin, workspaceRoot)) {
+            noteSetup(`the vexp entry in ${p} is pinned to ${pin}, not to this workspace: left as it is`);
+            return;
+        }
+        if (committedCleanupBlocked([p], "GitHub Copilot"))
+            return;
+        const bytes = fs.readFileSync(p);
+        let raw;
+        let encoding = "utf-8";
+        try {
+            raw = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        }
+        catch {
+            raw = bytes.toString("latin1");
+            encoding = "latin1";
+        }
+        const cut = removeJsoncMember(raw, "servers", "vexp");
+        if (cut === undefined) {
+            noteSetup(`vexp's entry in ${p} could not be cut out of the text: left as it is`);
+            return;
+        }
+        // Deleted with no backup when nothing is left, not even a comment: it
+        // held vexp's entry and nothing else.
+        const bare = cut.replace(/^\uFEFF/, "").replace(/\s+/g, "");
+        if (bare === "{}" || bare === '{"servers":{}}') {
+            fs.unlinkSync(p);
+            removeDirIfEmpty(path.dirname(p));
+        }
+        else {
+            backupConfig(p);
+            fs.writeFileSync(p, cut, encoding);
+        }
+    }
+    catch {
+        /* best-effort: what is left there, the doctor names */
+    }
+    finally {
+        noteSetup(MCP_JSON_DEFINES_VEXP);
+    }
+}
+/**
+ * GitHub Copilot's MCP setup, as `vexp setup` does it: `<root>/.mcp.json`'s
+ * vexp server kept runnable (maintainProjectMcpJson), and
+ * `<root>/.vscode/mcp.json` written (writeVsCodeMcpConfig), which gets no
+ * vexp entry when .mcp.json has one that would serve this root (M2). Returns
+ * the files written, relative to the root.
+ */
+export function configureCopilotMcp(workspaceRoot, binaryPath, mcpServerPath) {
+    const out = [];
+    if (maintainProjectMcpJson(workspaceRoot, binaryPath, mcpServerPath))
+        out.push(".mcp.json");
+    if (writeVsCodeMcpConfig(path.join(workspaceRoot, ".vscode", "mcp.json"), binaryPath, mcpServerPath, workspaceRoot))
+        out.push(".vscode/mcp.json");
+    return out;
+}
 /**
  * Write .vscode/mcp.json for GitHub Copilot.
  * VS Code uses "servers" (not "mcpServers") + "type": "stdio".
+ *
+ * Only vexp's member is edited (memberEditedText): the user's comments, BOM,
+ * key order, layout and last newline stay, where every write used to
+ * re-serialise the whole file. Pinned with vsCodeMcpPin. A file committed to
+ * the repository whose entry another checkout pinned keeps that pin
+ * (committedPin); its command and args change only when the vexp install
+ * they name is gone. Nothing is added when `<root>/.mcp.json` defines vexp
+ * and that entry would serve this root from VS Code (leaveVexpOutOfVsCodeMcp,
+ * dotMcpJsonMiss); otherwise vexp's entry is written as with no .mcp.json,
+ * and the reason is a setup note (dotMcpJsonKeptLine).
  */
 export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
+    // .mcp.json at the root already defines vexp: nothing is added here, and
+    // vexp's own entry goes (W4). Before the link check: the removal makes its own.
+    // Only when that entry would serve this root from VS Code (M2): one pinned
+    // to another folder, or whose command does not start here, would leave
+    // Copilot with another checkout's index or none, so vexp's entry is
+    // written as with no .mcp.json at all, and VS Code uses it instead.
+    const dot = workspaceRoot && path.resolve(path.dirname(path.dirname(p))) === path.resolve(workspaceRoot) ? projectMcpJsonVexp(workspaceRoot) : undefined;
+    if (dot && workspaceRoot) {
+        const miss = dotMcpJsonMiss(dot.entry, workspaceRoot);
+        if (!miss) {
+            leaveVexpOutOfVsCodeMcp(p, workspaceRoot);
+            return false;
+        }
+        noteSetup(dotMcpJsonKeptLine(workspaceRoot, miss));
+    }
+    // Pinned to the project: a link out of it, or to nothing, is left as it is.
+    if (pinnedProjectFile(p, workspaceRoot) && projectWriteRefused(p, workspaceRoot))
+        return false;
     const read = readJsonConfigSafe(p);
     if (!read.ok) {
         warnUnparseable(p);
         return false;
     }
     const existing = read.data;
+    if (containerMisshapen(existing, "servers"))
+        return leftUntouched(p, "servers");
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
-    const targetEnv = workspaceRoot ? { VEXP_WORKSPACE: workspaceRoot } : undefined;
+    const pin = workspaceRoot ? vsCodeMcpPin(p, workspaceRoot) : undefined;
+    const targetEnv = pin ? { VEXP_WORKSPACE: pin } : undefined;
     const beforeServers = existing.servers;
     const previousVexp = beforeServers?.["vexp"];
+    // Committed, and another checkout's pin: that pin stays (W3).
+    const kept = committedPin(p, workspaceRoot, envPin(previousVexp?.env));
+    if (kept) {
+        if (!staleVexpInstall(previousVexp))
+            return noteCommittedPin(p, kept);
+        const entry = { ...previousVexp, command: targetCmd, args: targetArgs };
+        beforeServers["vexp"] = entry;
+        backupConfig(p);
+        const edited = memberEditedText(p, existing, "servers", "vexp", entry);
+        fs.writeFileSync(p, edited.text, edited.encoding);
+        return true;
+    }
     const prevArgs = Array.isArray(previousVexp?.["args"]) ? previousVexp?.["args"] : undefined;
     const envMatches = JSON.stringify(previousVexp?.env) === JSON.stringify(targetEnv);
     const identical = previousVexp?.["command"] === targetCmd &&
@@ -2634,18 +5240,41 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
     // pin, so a moved or renamed project is repinned normally.
     if (removed.length === 0 && envMatches && adoptableEntry(previousVexp))
         return false;
+    // A working entry pinned to this folder's absolute path. vexp's own (any
+    // vexp install's, ours from before 3.4 included) moves its pin to
+    // "${workspaceFolder}", once, command and args kept, so this setup and the
+    // other install do not take the entry from each other. One the user wrote
+    // (their own launcher: isVexpWrittenEntry false) is theirs and is left as
+    // it is, as before 3.4: W1 moves vexp-written entries only, and the
+    // rewrite was a diff in a file vexp does not own (review, 2026-11-07).
+    const pinnedHere = removed.length === 0 &&
+        pin === "${workspaceFolder}" &&
+        typeof envPin(previousVexp?.env) === "string" &&
+        sameFolder(envPin(previousVexp?.env), workspaceRoot) &&
+        adoptableEntry(previousVexp);
+    if (pinnedHere && !isVexpWrittenEntry(previousVexp))
+        return false;
+    const movesPin = pinnedHere && isVexpWrittenEntry(previousVexp);
     const servers = existing.servers ?? {};
-    servers["vexp"] = {
-        type: "stdio",
-        command: targetCmd,
-        args: targetArgs,
-        ...(targetEnv ? { env: targetEnv } : {}),
-    };
+    const entry = movesPin
+        ? { ...previousVexp, env: targetEnv }
+        : {
+            type: "stdio",
+            command: targetCmd,
+            args: targetArgs,
+            ...(targetEnv ? { env: targetEnv } : {}),
+        };
+    servers["vexp"] = entry;
     existing.servers = servers;
     fs.mkdirSync(path.dirname(p), { recursive: true });
+    // stripLegacyVexpEntries names each key it took out as "servers.<key>".
+    const dropped = removed.map((r) => r.slice("servers.".length));
+    const edited = read.existed
+        ? memberEditedText(p, existing, "servers", "vexp", entry, dropped)
+        : { text: JSON.stringify(existing, null, 2), encoding: "utf-8" };
     if (read.existed)
         backupConfig(p);
-    fs.writeFileSync(p, JSON.stringify(existing, null, 2), "utf-8");
+    fs.writeFileSync(p, edited.text, edited.encoding);
     return true;
 }
 /**
@@ -2706,8 +5335,18 @@ export function opencodeConfigTarget(workspaceRoot) {
  * file is backed up before rewrite. Returns the workspace-relative path written,
  * or null on a no-op / unparseable file.
  */
-/** Cline's globalStorage dirs across OSes and VS Code variants: the marker
- * that Cline is installed, and the parent of its MCP settings file. */
+/**
+ * Cline's globalStorage dirs across OSes, VS Code variants and the forks
+ * Cline runs in: the marker that Cline is installed, and the parent of its
+ * MCP settings file. A remote window (Remote-WSL, SSH, Dev Containers) runs
+ * Cline on the remote side, whose editor server keeps its storage under
+ * <home>/.vscode-server/data/User (and the forks' servers under their own
+ * folder): with only the desktop folders listed, setup there wrote no
+ * registry and said "no Cline install found" beside a Cline that was
+ * installed, and so did one run in Cursor or Windsurf (review,
+ * 2026-11-07, round 4). The first three stay first, in their old order.
+ * Lockstep with the extension.
+ */
 function clineStorageDirs() {
     const home = os.homedir();
     const base = process.platform === "win32"
@@ -2715,7 +5354,19 @@ function clineStorageDirs() {
         : process.platform === "darwin"
             ? path.join(home, "Library", "Application Support")
             : path.join(home, ".config");
-    return ["Code", "Code - Insiders", "VSCodium"].map((variant) => path.join(base, variant, "User", "globalStorage", "saoudrizwan.claude-dev"));
+    const desktop = ["Code", "Code - Insiders", "VSCodium", "Cursor", "Windsurf"].map((variant) => path.join(base, variant, "User"));
+    const remote = [".vscode-server", ".vscode-server-insiders", ".vscodium-server", ".cursor-server", ".windsurf-server"].map((server) => path.join(home, server, "data", "User"));
+    return [...desktop, ...remote].map((user) => path.join(user, "globalStorage", "saoudrizwan.claude-dev"));
+}
+/**
+ * Is Cline installed in any VS Code variant (its globalStorage folder is
+ * there)? What noteClineMcpUnreachable is for: a registry left untouched,
+ * one that does not parse, or one that already holds vexp's entry gets no
+ * write either, and "no Cline install found" beside "left untouched"
+ * contradicted it (review, 2026-11-07).
+ */
+function clineInstalled() {
+    return clineStorageDirs().some((d) => fs.existsSync(d));
 }
 /**
  * Cline: MCP servers live in a MACHINE-GLOBAL file per VS Code variant
@@ -2740,6 +5391,10 @@ export function configureClineMcp(workspaceRoot, binaryPath) {
             continue;
         }
         const cfg = read.data;
+        if (containerMisshapen(cfg, "mcpServers")) {
+            leftUntouched(target, "mcpServers");
+            continue;
+        }
         const servers = cfg.mcpServers ?? {};
         const entry = {
             command: binaryPath,
@@ -2763,17 +5418,34 @@ export function configureClineMcp(workspaceRoot, binaryPath) {
 }
 export function configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath) {
     const target = opencodeConfigTarget(workspaceRoot);
+    // Pinned to the project: a link out of it, or to nothing, is left as it is.
+    if (projectWriteRefused(target, workspaceRoot))
+        return null;
     const read = readJsonConfigSafe(target);
     if (!read.ok) {
         warnUnparseable(target);
         return null;
     }
     const cfg = read.data;
+    if (containerMisshapen(cfg, "mcp")) {
+        leftUntouched(target, "mcp");
+        return null;
+    }
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const command = useNode ? [resolveNodeCommand(), mcpServerPath] : [binaryPath, "mcp"];
     const env = { VEXP_WORKSPACE: workspaceRoot };
     const mcp = cfg.mcp ?? {};
     const prev = mcp["vexp"];
+    // Committed and pinned by another checkout: see committedPin.
+    const kept = committedPin(target, workspaceRoot, envPin(prev?.["env"]));
+    if (kept) {
+        if (!staleVexpInstall(prev))
+            return noteCommittedPin(target, kept) || null;
+        mcp["vexp"] = { ...prev, command };
+        backupConfig(target);
+        fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+        return path.relative(workspaceRoot, target);
+    }
     const envMatches = JSON.stringify(prev?.["env"]) === JSON.stringify(env);
     const identical = prev?.["type"] === "local" &&
         prev?.["enabled"] === true &&
@@ -2805,17 +5477,34 @@ export function configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath) {
 }
 export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
     const target = kiloConfigTarget(workspaceRoot);
+    // Pinned to the project: a link out of it, or to nothing, is left as it is.
+    if (projectWriteRefused(target, workspaceRoot))
+        return null;
     const read = readJsonConfigSafe(target);
     if (!read.ok) {
         warnUnparseable(target);
         return null;
     }
     const cfg = read.data;
+    if (containerMisshapen(cfg, "mcp")) {
+        leftUntouched(target, "mcp");
+        return null;
+    }
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const command = useNode ? [resolveNodeCommand(), mcpServerPath] : [binaryPath, "mcp"];
     const env = { VEXP_WORKSPACE: workspaceRoot };
     const mcp = cfg.mcp ?? {};
     const prev = mcp["vexp"];
+    // Committed and pinned by another checkout: see committedPin.
+    const kept = committedPin(target, workspaceRoot, envPin(prev?.["env"]));
+    if (kept) {
+        if (!staleVexpInstall(prev))
+            return noteCommittedPin(target, kept) || null;
+        mcp["vexp"] = { ...prev, command };
+        backupConfig(target);
+        fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+        return path.relative(workspaceRoot, target);
+    }
     const envMatches = JSON.stringify(prev?.["env"]) === JSON.stringify(env);
     const identical = prev?.["type"] === "local" &&
         prev?.["enabled"] === true &&
@@ -2840,12 +5529,29 @@ export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
     return path.relative(workspaceRoot, target);
 }
 export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
+    // The CLI pins Zed's entry too (VEXP_WORKSPACE inside `command`): a link
+    // out of the project, or to nothing, is left as it is.
+    if (pinnedProjectFile(p, workspaceRoot) && projectWriteRefused(p, workspaceRoot))
+        return false;
     const read = readJsonConfigSafe(p);
     if (!read.ok) {
         warnUnparseable(p);
         return false;
     }
     const settings = read.data;
+    // context_servers takes the entry; agent.tool_permissions.tools takes the
+    // tools' approvals, and an array or a string there was spread into an
+    // object of its characters.
+    if (containerMisshapen(settings, "context_servers"))
+        return leftUntouched(p, "context_servers");
+    if (containerMisshapen(settings, "agent"))
+        return leftUntouched(p, "agent");
+    const agentIn = asPlainObject(settings.agent) ? settings.agent : {};
+    if (containerMisshapen(agentIn, "tool_permissions"))
+        return leftUntouched(p, "agent.tool_permissions");
+    const tpIn = asPlainObject(agentIn.tool_permissions) ? agentIn.tool_permissions : {};
+    if (containerMisshapen(tpIn, "tools"))
+        return leftUntouched(p, "agent.tool_permissions.tools");
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
@@ -2853,6 +5559,17 @@ export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     const beforeCs = settings.context_servers;
     const previousVexp = beforeCs?.["vexp"];
     const curCmd = previousVexp?.["command"];
+    // Committed and pinned by another checkout: see committedPin. Zed nests
+    // the env inside `command`, which keeps it.
+    const kept = committedPin(p, workspaceRoot, envPin(asPlainObject(curCmd) ? curCmd.env : undefined));
+    if (kept) {
+        if (!staleVexpInstall(previousVexp))
+            return noteCommittedPin(p, kept);
+        beforeCs["vexp"] = { ...previousVexp, command: { ...curCmd, path: targetCmd, args: targetArgs } };
+        backupConfig(p);
+        fs.writeFileSync(p, JSON.stringify(settings, null, 2), "utf-8");
+        return true;
+    }
     // Zed nests env inside `command`, unlike every other writer.
     const envMatches = JSON.stringify(curCmd?.["env"]) === JSON.stringify(targetEnv);
     const identical = curCmd?.["path"] === targetCmd &&
@@ -2908,6 +5625,8 @@ version) {
         return false;
     }
     const config = read.data;
+    if (containerMisshapen(config, "mcpServers"))
+        return leftUntouched(configPath, "mcpServers");
     const beforeServers = config.mcpServers;
     const existing = beforeServers?.["vexp"];
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
@@ -3049,8 +5768,17 @@ function isVexpGuardHookEntry(h) {
 export function uninstallClaudeCodeHook(workspaceRoot) {
     let removed = false;
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
-    for (const name of ["vexp-guard.sh", "vexp-guard.cmd"]) {
-        const p = path.join(hookDir, name);
+    const scripts = ["vexp-guard.sh", "vexp-guard.cmd"].map((name) => path.join(hookDir, name));
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const read = readJsonConfigSafe(settingsPath);
+    const hooksIn = read.ok && read.existed ? (read.data.hooks ?? {}) : {};
+    const preIn = Array.isArray(hooksIn.PreToolUse) ? hooksIn.PreToolUse : [];
+    const deregisters = read.ok && read.existed && JSON.stringify(placeVexpHook(preIn, isVexpGuardHookEntry, null)) !== JSON.stringify(preIn);
+    // A script or a settings.json committed to the repository: the guard
+    // stays whole, script and entry together (committedCleanupBlocked).
+    if (committedCleanupBlocked([...scripts, deregisters ? settingsPath : undefined], "Claude Code"))
+        return false;
+    for (const p of scripts) {
         if (fs.existsSync(p)) {
             try {
                 fs.unlinkSync(p);
@@ -3059,8 +5787,6 @@ export function uninstallClaudeCodeHook(workspaceRoot) {
             catch { /* leave in place */ }
         }
     }
-    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
-    const read = readJsonConfigSafe(settingsPath);
     if (read.ok && read.existed) {
         const settings = read.data;
         const hooks = (settings.hooks ?? {});
@@ -3242,7 +5968,8 @@ export function installClaudeCodeSessionContext(workspaceRoot, binaryPath) {
     fs.mkdirSync(hookDir, { recursive: true });
     const script = vexpSessionContextHookScript(binaryPath);
     const existed = fs.existsSync(hookPath);
-    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf8") === script;
+    // A committed script that bakes another live engine stays (K1).
+    const scriptIdentical = existed && hookScriptCurrent(hookPath, script, vexpSessionContextHookScript);
     if (!scriptIdentical) {
         fs.writeFileSync(hookPath, script, { mode: 0o755 });
     }
@@ -3290,7 +6017,9 @@ export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
     const gateOn = interventionMode() === "on";
     const existed = fs.existsSync(hookPath);
     const script = vexpStopGateHookScript(binaryPath);
-    const scriptIdentical = gateOn && existed && fs.readFileSync(hookPath, "utf8") === script;
+    const scriptIdentical = gateOn && existed && hookScriptCurrent(hookPath, script, vexpStopGateHookScript);
+    if (!gateOn && stopGateRemovalBlocked(hookPath, settingsPath))
+        return null;
     if (gateOn) {
         if (!scriptIdentical) {
             fs.writeFileSync(hookPath, script, { mode: 0o755 });
@@ -3338,6 +6067,26 @@ export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
     }
     return existed ? "updated" : "created";
 }
+/** The edit-time hook is off: is its script or its settings.json entry committed (see stopGateRemovalBlocked)? */
+function editHintRemovalBlocked(editHookPath, settingsPath) {
+    const read = readJsonConfigSafe(settingsPath);
+    const hooks = read.ok && read.existed ? (read.data.hooks ?? {}) : {};
+    const post = Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [];
+    const deregisters = post.some((h) => isVexpEditHintHookEntry(h));
+    return committedCleanupBlocked([editHookPath, deregisters ? settingsPath : undefined], "Claude Code");
+}
+/**
+ * The gate is off and its script or settings.json entry is committed to
+ * the repository: both stay (committedCleanupBlocked), so the entry never
+ * names a script that is gone.
+ */
+function stopGateRemovalBlocked(hookPath, settingsPath) {
+    const read = readJsonConfigSafe(settingsPath);
+    const hooks = read.ok && read.existed ? (read.data.hooks ?? {}) : {};
+    const stop = Array.isArray(hooks.Stop) ? hooks.Stop : [];
+    const deregisters = stop.some((h) => isVexpHookEntry(h, "vexp-verify"));
+    return committedCleanupBlocked([hookPath, deregisters ? settingsPath : undefined], "Claude Code");
+}
 function isVexpEditHintHookEntry(entry) {
     const cmds = JSON.stringify(entry ?? "");
     return cmds.includes("vexp-edit-hint");
@@ -3402,8 +6151,17 @@ function isVexpSearchHookEntry(h) {
  */
 function removeClaudeCodePreToolHooks(workspaceRoot) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
-    for (const name of ["read-hint", "bash-cap"]) {
-        const p = path.join(hookDir, `vexp-${name}.sh`);
+    const scripts = ["read-hint", "bash-cap"].map((name) => path.join(hookDir, `vexp-${name}.sh`));
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const read = readJsonConfigSafe(settingsPath);
+    const ours = (h) => /vexp-(read-hint|bash-cap)/.test(JSON.stringify(h ?? ""));
+    const hooksIn = read.ok && read.existed ? (read.data.hooks ?? {}) : {};
+    const preIn = Array.isArray(hooksIn.PreToolUse) ? hooksIn.PreToolUse : [];
+    const deregisters = read.ok && read.existed && JSON.stringify(placeVexpHook(preIn, ours, null)) !== JSON.stringify(preIn);
+    // Committed to the repository: the hooks stay whole (committedCleanupBlocked).
+    if (committedCleanupBlocked([...scripts, deregisters ? settingsPath : undefined], "Claude Code"))
+        return;
+    for (const p of scripts) {
         if (fs.existsSync(p)) {
             try {
                 fs.unlinkSync(p);
@@ -3413,14 +6171,12 @@ function removeClaudeCodePreToolHooks(workspaceRoot) {
             }
         }
     }
-    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
-    const read = readJsonConfigSafe(settingsPath);
     if (!read.ok || !read.existed)
         return;
     const settings = read.data;
     const hooks = (settings.hooks ?? {});
     const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-    const filtered = placeVexpHook(existing, (h) => /vexp-(read-hint|bash-cap)/.test(JSON.stringify(h ?? "")), null);
+    const filtered = placeVexpHook(existing, ours, null);
     if (JSON.stringify(filtered) === JSON.stringify(existing))
         return;
     const merged = { ...hooks, PreToolUse: filtered };
@@ -3430,13 +6186,15 @@ function removeClaudeCodePreToolHooks(workspaceRoot) {
     backupConfig(settingsPath);
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
 }
-function installClaudeCodePreToolHook(workspaceRoot, binaryPath, name, matcher, script) {
+function installClaudeCodePreToolHook(workspaceRoot, binaryPath, name, matcher, bake) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
     const hookPath = path.join(hookDir, `vexp-${name}.sh`);
     const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const script = bake(binaryPath);
     fs.mkdirSync(hookDir, { recursive: true });
     const existed = fs.existsSync(hookPath);
-    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    // A committed script that bakes another live engine stays (K1).
+    const scriptIdentical = existed && hookScriptCurrent(hookPath, script, bake);
     if (!scriptIdentical)
         fs.writeFileSync(hookPath, script, { mode: 0o755 });
     const read = readJsonConfigSafe(settingsPath);
@@ -3470,10 +6228,10 @@ function installClaudeCodePreToolHook(workspaceRoot, binaryPath, name, matcher,
     return existed ? "updated" : "created";
 }
 export function installClaudeCodeReadHint(workspaceRoot, binaryPath) {
-    return installClaudeCodePreToolHook(workspaceRoot, binaryPath, "read-hint", "Read", bakeReadHintHook(binaryPath));
+    return installClaudeCodePreToolHook(workspaceRoot, binaryPath, "read-hint", "Read", bakeReadHintHook);
 }
 export function installClaudeCodeBashCap(workspaceRoot, binaryPath) {
-    return installClaudeCodePreToolHook(workspaceRoot, binaryPath, "bash-cap", "Bash", bakeBashCapHook(binaryPath));
+    return installClaudeCodePreToolHook(workspaceRoot, binaryPath, "bash-cap", "Bash", bakeBashCapHook);
 }
 export function installClaudeCodeSearchHook(workspaceRoot, binaryPath) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
@@ -3482,7 +6240,8 @@ export function installClaudeCodeSearchHook(workspaceRoot, binaryPath) {
     const script = vexpSearchHookScript(binaryPath);
     fs.mkdirSync(hookDir, { recursive: true });
     const existed = fs.existsSync(hookPath);
-    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    // A committed script that bakes another live engine stays (K1).
+    const scriptIdentical = existed && hookScriptCurrent(hookPath, script, vexpSearchHookScript);
     if (!scriptIdentical)
         fs.writeFileSync(hookPath, script, { mode: 0o755 });
     const read = readJsonConfigSafe(settingsPath);
@@ -3531,20 +6290,26 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
     // InterventionMode above for the measurement.
     const editHookPath = path.join(hookDir, "vexp-edit-hint.sh");
     const couplingOn = interventionMode() === "on";
+    // Off, and the edit hook or its settings.json entry committed to the
+    // repository: both stay as they are (committedCleanupBlocked); the
+    // prompt hook below is set up all the same.
+    const keepEditHook = !couplingOn && editHintRemovalBlocked(editHookPath, settingsPath);
     if (couplingOn) {
         const editScript = bakeEditHintHook(binaryPath);
-        const editExisted = fs.existsSync(editHookPath);
-        if (!editExisted || fs.readFileSync(editHookPath, "utf-8") !== editScript) {
+        // A committed script that bakes another live engine stays (K1), its
+        // mode included: git tracks the exec bit.
+        if (!hookScriptCurrent(editHookPath, editScript, bakeEditHintHook)) {
             fs.writeFileSync(editHookPath, editScript, { mode: 0o755 });
         }
         try {
-            fs.chmodSync(editHookPath, 0o755);
+            if (!hookScriptLeft(editHookPath))
+                fs.chmodSync(editHookPath, 0o755);
         }
         catch {
             /* Windows has no exec bit; Git Bash runs it anyway. */
         }
     }
-    else if (fs.existsSync(editHookPath)) {
+    else if (!keepEditHook && fs.existsSync(editHookPath)) {
         // Converge an upgraded workspace without asking anyone to clean up.
         try {
             fs.unlinkSync(editHookPath);
@@ -3554,7 +6319,8 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
         }
     }
     const existed = fs.existsSync(hookPath);
-    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    // A committed script that bakes another live engine stays (K1).
+    const scriptIdentical = existed && hookScriptCurrent(hookPath, script, (bin) => vexpHintHookScript(bin, "claude-code"));
     if (!scriptIdentical) {
         fs.writeFileSync(hookPath, script, { mode: 0o755 });
     }
@@ -3589,7 +6355,7 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
     const existingPost = Array.isArray(hooks.PostToolUse)
         ? hooks.PostToolUse
         : [];
-    const filteredPost = placeVexpHook(existingPost, isVexpEditHintHookEntry, couplingOn
+    const filteredPost = keepEditHook ? existingPost : placeVexpHook(existingPost, isVexpEditHintHookEntry, couplingOn
         ? {
             matcher: "Edit|Write|NotebookEdit",
             hooks: [
@@ -3650,7 +6416,8 @@ export function installClaudeCodeSubagentHook(workspaceRoot, binaryPath) {
     }
     fs.mkdirSync(hookDir, { recursive: true });
     const existed = fs.existsSync(hookPath);
-    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    // A committed script that bakes another live engine stays (K1).
+    const scriptIdentical = existed && hookScriptCurrent(hookPath, script, vexpSubagentHookScript);
     if (!scriptIdentical)
         fs.writeFileSync(hookPath, script, { mode: 0o755 });
     const settings = read.data;
@@ -3695,7 +6462,8 @@ export function installOpencodeCompressPlugin(workspaceRoot, binaryPath, pluginD
     const content = vexpOpencodeCompressPlugin(binaryPath);
     fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
     const existed = fs.existsSync(pluginPath);
-    if (existed && fs.readFileSync(pluginPath, "utf-8") === content)
+    // A committed plugin that bakes another live engine stays (K1).
+    if (existed && hookScriptCurrent(pluginPath, content, vexpOpencodeCompressPlugin))
         return null;
     fs.writeFileSync(pluginPath, content);
     return existed ? "updated" : "created";
@@ -3705,7 +6473,8 @@ export function installOpencodeHintPlugin(workspaceRoot, binaryPath, pluginDir)
     const content = vexpOpencodeHintPlugin(binaryPath, opencodeFamilyAgent(pluginDir));
     fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
     const existed = fs.existsSync(pluginPath);
-    if (existed && fs.readFileSync(pluginPath, "utf-8") === content)
+    // A committed plugin that bakes another live engine stays (K1).
+    if (existed && hookScriptCurrent(pluginPath, content, (bin) => vexpOpencodeHintPlugin(bin, opencodeFamilyAgent(pluginDir))))
         return null;
     fs.writeFileSync(pluginPath, content);
     return existed ? "updated" : "created";
@@ -3727,7 +6496,9 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
     const script = vexpHintHookScript(binaryPath, "codex");
     fs.mkdirSync(dir, { recursive: true });
     const existed = fs.existsSync(hookPath);
-    let scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    // A committed script that bakes another live engine stays (K1), the
+    // batch twin below too.
+    let scriptIdentical = existed && hookScriptCurrent(hookPath, script, (bin) => vexpHintHookScript(bin, "codex"));
     if (!scriptIdentical) {
         fs.writeFileSync(hookPath, script, { mode: 0o755 });
     }
@@ -3738,19 +6509,14 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
     // ~0.131, months before the version that requires the nested `hooks` shape
     // we already write). Older builds ignore the field rather than reject the
     // file — the handler is not deny_unknown_fields, unlike the top level.
+    // The entry runs it through `cmd /d /c call` (codexHintEntry).
     const cmdPath = path.join(dir, "vexp-hint.cmd");
-    let cmdCommand;
     if (process.platform === "win32") {
         const cmdScript = vexpHintHookCmdScript(binaryPath);
-        const cmdExisted = fs.existsSync(cmdPath);
-        if (!cmdExisted || fs.readFileSync(cmdPath, "utf-8") !== cmdScript) {
+        if (!hookScriptCurrent(cmdPath, cmdScript, vexpHintHookCmdScript)) {
             fs.writeFileSync(cmdPath, cmdScript);
             scriptIdentical = false;
         }
-        // Through `cmd /d /c call`, not the bare path: Codex runs the line in
-        // PowerShell by default, where a quoted path is only a string to print
-        // (codexWindowsHookCommand has the details).
-        cmdCommand = codexWindowsHookCommand(cmdPath);
     }
     let root = {};
     if (fs.existsSync(hooksJsonPath)) {
@@ -3791,16 +6557,27 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
     // record over this line (codex-trust.ts codexHookHash), so a change would
     // make every Codex user approve the hook again. The script it runs is
     // POSIX sh all the same, and a new script needs no new approval.
-    const ours = {
-        hooks: [
-            {
-                type: "command",
-                command: `bash "${hookPath.replace(/\\/g, "/")}"`,
-                ...(cmdCommand ? { commandWindows: cmdCommand } : {}),
-                timeout: 5,
-            },
-        ],
-    };
+    const ours = codexHintEntry(workspaceRoot);
+    // Committed to the repository and written by another checkout: a vexp
+    // hook whose definition is ours but for that checkout's path is left as it
+    // is, and so is the file: a rewrite only pointed the committed file at
+    // this checkout and made Codex ask for approval again (field report,
+    // 2026-11-07). The hook runs the OTHER checkout's copy of the script, so
+    // it is kept only while that checkout is a checkout of this repository on
+    // this machine and its script is there (sameRepositoryCheckout): after a
+    // clone, a move or a removed worktree it failed at every prompt, and a
+    // rewrite costs one approval instead (review, 2026-11-07).
+    const other = codexHookCheckout(wrapped.find((h) => isVexpHintHookEntry(h)));
+    if (other !== undefined &&
+        !sameFolder(other, upperDriveLetter(workspaceRoot).replace(/\\/g, "/")) &&
+        legacyTopLevel.length === 0 &&
+        codexHookScriptsThere(other, workspaceRoot)) {
+        const theirs = wrapped.find((h) => isVexpHintHookEntry(h));
+        if (JSON.stringify(theirs) === JSON.stringify(codexHintEntry(other)) && isGitTracked(hooksJsonPath)) {
+            noteSetup(committedPinLine(hooksJsonPath, other));
+            return scriptIdentical ? null : existed ? "updated" : "created";
+        }
+    }
     const merged = placeCodexHintEntry(existing, ours);
     const before = JSON.stringify(root);
     codexHooks.UserPromptSubmit = merged;
@@ -3817,6 +6594,48 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
     }
     return existed ? "updated" : "created";
 }
+/**
+ * Is `other`, the checkout a committed Codex hook names, a checkout of this
+ * repository on this machine with the script the hook runs there
+ * (vexp-hint.sh, and on Windows the vexp-hint.cmd commandWindows names)?
+ * Lockstep with the extension's.
+ */
+function codexHookScriptsThere(other, workspaceRoot) {
+    if (!sameRepositoryCheckout(other, workspaceRoot))
+        return false;
+    const dir = path.join(other, ".codex");
+    return fs.existsSync(path.join(dir, "vexp-hint.sh")) && (process.platform !== "win32" || fs.existsSync(path.join(dir, "vexp-hint.cmd")));
+}
+/**
+ * vexp's UserPromptSubmit group in `<root>/.codex/hooks.json`, as
+ * installCodexHintHook writes it for `root` (the Windows `commandWindows`
+ * twin on Windows only).
+ */
+function codexHintEntry(root) {
+    const dir = path.join(upperDriveLetter(root), ".codex");
+    const hookPath = path.join(dir, "vexp-hint.sh");
+    // Through `cmd /d /c call`, not the bare path: Codex runs the line in
+    // PowerShell by default, where a quoted path is only a string to print
+    // (codexWindowsHookCommand has the details).
+    const cmdCommand = process.platform === "win32" ? codexWindowsHookCommand(path.join(dir, "vexp-hint.cmd")) : undefined;
+    return {
+        hooks: [
+            {
+                type: "command",
+                command: `bash "${hookPath.replace(/\\/g, "/")}"`,
+                ...(cmdCommand ? { commandWindows: cmdCommand } : {}),
+                timeout: 5,
+            },
+        ],
+    };
+}
+/** The checkout a vexp Codex hook group names (`bash "<checkout>/.codex/vexp-hint.sh"`), forward slashes; undefined for anything else. */
+function codexHookCheckout(group) {
+    const hooks = asPlainObject(group) && Array.isArray(group.hooks) ? group.hooks : [];
+    const command = hooks.length === 1 && asPlainObject(hooks[0]) ? hooks[0].command : undefined;
+    const m = typeof command === "string" ? /^bash "(.+)\/\.codex\/vexp-hint\.sh"$/.exec(command) : null;
+    return m ? m[1] : undefined;
+}
 /**
  * vexp's UserPromptSubmit group, put where the previous one was.
  *
@@ -3892,10 +6711,12 @@ function removeGuardScript(scriptPath) {
     }
 }
 /** Remove the opencode guard plugin (2.3 A2 default). Both directory
- *  spellings are checked — older builds wrote `.opencode/plugin/`. */
+ *  spellings are checked — older builds wrote `.opencode/plugin/`. One
+ *  committed to the repository stays (committedCleanupBlocked). */
 export function uninstallOpencodePlugin(workspaceRoot) {
-    const a = removeGuardScript(path.join(workspaceRoot, ".opencode", "plugins", "vexp-guard.js"));
-    const b = removeGuardScript(path.join(workspaceRoot, ".opencode", "plugin", "vexp-guard.js"));
+    const remove = (p) => !committedCleanupBlocked([p], "Opencode") && removeGuardScript(p);
+    const a = remove(path.join(workspaceRoot, ".opencode", "plugins", "vexp-guard.js"));
+    const b = remove(path.join(workspaceRoot, ".opencode", "plugin", "vexp-guard.js"));
     return a || b;
 }
 /**
@@ -4060,9 +6881,15 @@ export function installKiloPlugin(workspaceRoot) {
  *  the explicit `plugin` array entry from a root kilo.jsonc when present. */
 export function uninstallKiloPlugin(workspaceRoot) {
     const pluginPath = path.join(workspaceRoot, ".kilo", "plugins", "vexp-guard.js");
-    let removed = removeGuardScript(pluginPath);
     const target = kiloConfigTarget(workspaceRoot);
     const read = readJsonConfigSafe(target);
+    // The plugin or the kilo.jsonc that declares it committed to the
+    // repository: both stay (committedCleanupBlocked).
+    const declared = read.ok && read.existed && Array.isArray(read.data.plugin) &&
+        read.data.plugin.some((e) => typeof e === "string" && e.includes("vexp-guard"));
+    if (committedCleanupBlocked([pluginPath, declared ? target : undefined], "Kilo Code"))
+        return false;
+    let removed = removeGuardScript(pluginPath);
     if (read.ok && read.existed) {
         const cfg = read.data;
         const list = Array.isArray(cfg.plugin) ? cfg.plugin : [];
@@ -4097,11 +6924,14 @@ export function installCursorEditHint(workspaceRoot, binaryPath) {
     const script = bakeEditHintHook(binaryPath);
     fs.mkdirSync(dir, { recursive: true });
     const existed = fs.existsSync(scriptPath);
-    if (!existed || fs.readFileSync(scriptPath, "utf-8") !== script) {
+    // A committed script that bakes another live engine stays (K1), its mode
+    // included: git tracks the exec bit.
+    if (!hookScriptCurrent(scriptPath, script, bakeEditHintHook)) {
         fs.writeFileSync(scriptPath, script, { mode: 0o755 });
     }
     try {
-        fs.chmodSync(scriptPath, 0o755);
+        if (!hookScriptLeft(scriptPath))
+            fs.chmodSync(scriptPath, 0o755);
     }
     catch {
         /* no exec bit on Windows */
@@ -4115,6 +6945,21 @@ export function installCursorEditHint(workspaceRoot, binaryPath) {
     const cfg = read.data;
     const hooks = cfg.hooks ?? {};
     const post = Array.isArray(hooks.postToolUse) ? hooks.postToolUse : [];
+    // Committed to the repository and written by another checkout (the
+    // command names the script by its absolute path): left as it is, as the
+    // Codex hook is (committedPinLine), while that checkout is one of this
+    // repository on this machine and the script it runs is there.
+    const theirs = post.find((e) => asPlainObject(e) && typeof e.command === "string" && e.command.includes("vexp-edit-hint"));
+    const m = asPlainObject(theirs) && typeof theirs.command === "string" ? /^bash "(.+)[\\/]\.cursor[\\/]hooks[\\/]vexp-edit-hint\.sh"$/.exec(theirs.command) : null;
+    if (m &&
+        !sameFolder(m[1], workspaceRoot) &&
+        sameRepositoryCheckout(m[1], workspaceRoot) &&
+        fs.existsSync(path.join(m[1], ".cursor", "hooks", "vexp-edit-hint.sh")) &&
+        JSON.stringify(theirs) === JSON.stringify({ command: `bash "${path.join(m[1], ".cursor", "hooks", "vexp-edit-hint.sh")}"` }) &&
+        isGitTracked(cfgPath)) {
+        noteSetup(committedPinLine(cfgPath, m[1]));
+        return null;
+    }
     const filtered = post.filter((e) => {
         if (!e || typeof e !== "object")
             return true;
@@ -4135,9 +6980,16 @@ export function installCursorEditHint(workspaceRoot, binaryPath) {
  *  our preToolUse entry from .cursor/hooks.json. */
 export function uninstallCursorHook(workspaceRoot) {
     const rel = path.join(".cursor", "hooks", "vexp-guard.js");
-    let removed = removeGuardScript(path.join(workspaceRoot, rel));
     const cfgPath = path.join(workspaceRoot, ".cursor", "hooks.json");
     const read = readJsonConfigSafe(cfgPath);
+    // The guard or the hooks.json that runs it committed to the repository:
+    // both stay (committedCleanupBlocked).
+    const hooksIn = read.ok && read.existed && asPlainObject(read.data.hooks) ? read.data.hooks : {};
+    const registered = Array.isArray(hooksIn.preToolUse) &&
+        hooksIn.preToolUse.some((e) => asPlainObject(e) && typeof e.command === "string" && e.command.includes("vexp-guard"));
+    if (committedCleanupBlocked([path.join(workspaceRoot, rel), registered ? cfgPath : undefined], "Cursor"))
+        return false;
+    let removed = removeGuardScript(path.join(workspaceRoot, rel));
     if (read.ok && read.existed) {
         const cfg = read.data;
         const hooks = cfg.hooks ?? {};