vexp-cli 2.1.7 → 2.2.1

package/dist/agent-config.js

@@ -10,7 +10,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import * as crypto from "crypto";
-import { VEXP_GUARD_HOOK } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -47,7 +47,11 @@ function workspaceHash(workspaceRoot) {
         hash ^= BigInt(byte);
         hash = (hash * prime) & mask;
     }
-    return hash.toString(16).padStart(16, "0").slice(0, 8);
+    // NOT zero-padded — see doctor.ts:socketForWorkspace. Rust renders the u64
+    // with `format!("{:x}")` and slices [..8]; padding to 16 first shifts every
+    // digit right whenever the hash has a leading zero nibble (~6% of paths),
+    // which silently breaks the lockstep this comment demands.
+    return hash.toString(16).slice(0, 8);
 }
 /**
  * Remove every legacy vexp entry from a JSON-shaped MCP config object.
@@ -150,15 +154,27 @@ const AGENT_DETECTORS = [
     {
         agent: "Opencode",
         detectPath: "opencode.json",
+        // opencode also reads `opencode.jsonc` (and a global ~/.config/opencode/),
+        // so `opencode.json` alone missed the many users who keep a commented config.
+        detectPaths: ["opencode.jsonc"],
         configFile: "AGENTS.md",
         templateName: "agents-md",
+        // Enforcement (block grep/glob when the daemon is up) is installed as an
+        // opencode plugin at .opencode/plugins/vexp-guard.js — see installOpencodePlugin().
     },
     {
         agent: "Kilo Code",
         detectPath: ".kilocode",
-        configFile: ".kilocode/rules.md",
+        // Current Kilo Code (kilo.ai) uses `.kilo/` + `kilo.jsonc`; keep `.kilocode`
+        // for older installs. Any one marker counts as detected.
+        detectPaths: [".kilo", "kilo.jsonc", "kilo.json"],
+        // Rules: a `.kilocode/rules/` DIRECTORY is auto-included for backward
+        // compatibility; a bare `.kilocode/rules.md` file is NOT (the old target,
+        // which silently never loaded). Write into the directory instead.
+        configFile: ".kilocode/rules/vexp.md",
         templateName: "generic",
-        mcpConfigFile: ".kilocode/mcp.json",
+        // MCP is NOT a separate .kilocode/mcp.json anymore — it lives under the
+        // `mcp` key in kilo.jsonc. Handled by configureKiloMcp() below.
     },
     {
         agent: "Kiro",
@@ -323,6 +339,27 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
                 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);
+        }
+        // Opencode: install the guard plugin that blocks grep/glob while the daemon
+        // is up (opencode's analogue of the Claude Code PreToolUse hook).
+        if (detector.agent === "Opencode") {
+            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,
+                });
+            }
+        }
         results.push({
             agent: detector.agent,
             configFile: detector.configFile,
@@ -431,6 +468,9 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (writeZedMcpConfig(zedPath, binaryPath, mcpServerPath, workspaceRoot))
                 mcpConfigs.push(".zed/settings.json");
         }
+        if (detector.agent === "Opencode") {
+            installOpencodePlugin(workspaceRoot);
+        }
         results.push({ agent: detector.agent, configFile: detector.configFile, content, alreadyExists, action });
     }
     return { agents: results, mcpConfigs };
@@ -523,6 +563,65 @@ export function readJsonConfigSafe(filePath) {
     return { data: {}, ok: false, existed: true };
 }
 /** Copy an existing config to <file>.vexp-bak before overwriting it. */
+/**
+ * True when the vexp entry already in a config still resolves to something
+ * runnable — even if it points at a DIFFERENT vexp install than ours.
+ *
+ * Mirrors `vexpEntryStillResolves` in
+ * packages/vexp-vscode/src/providers/agent-auto-config.ts; duplicated because
+ * the CLI cannot depend on the extension at runtime.
+ *
+ * `mcp-server.cjs` is a standalone script that reaches the daemon over its
+ * socket; it does not care which install it was launched from. So an entry
+ * naming another install is not stale, it is just someone else's path — and
+ * rewriting it starts a fight the user sees as "my MCP config gets
+ * overwritten every time I open a different IDE". Every VS Code fork carries
+ * the extension and writes these same files with its own absolute extension
+ * path, while the CLI writes `command: "node"` plus its npm-global path — a
+ * third shape — so `vexp setup` and any IDE activation also undid each other.
+ * The old value-equality check could never settle it: a different path is
+ * never identical, so whoever ran last won.
+ *
+ * Staleness is handled by the check rather than by rewriting: editors reap the
+ * previous extension directory on upgrade (and the path embeds the version),
+ * so an entry left by an uninstalled build fails here and is rewritten.
+ *
+ * Accepts every shape we emit:
+ *   {command: "node", args: ["…/mcp-server.cjs"]}   most JSON configs
+ *   {command: "…/vexp-core", args: ["mcp"]}         binary-subcommand
+ *   {command: {path, args}}                         Zed
+ *   {command: ["node", "…/mcp-server.cjs"]}         Kilo Code
+ */
+function vexpEntryStillResolves(entry) {
+    if (!entry || typeof entry !== "object")
+        return false;
+    const e = entry;
+    let command;
+    let rawArgs;
+    if (Array.isArray(e.command)) {
+        command = e.command[0];
+        rawArgs = e.command.slice(1);
+    }
+    else if (e.command !== null && typeof e.command === "object") {
+        const nested = e.command;
+        command = nested.path;
+        rawArgs = nested.args;
+    }
+    else {
+        command = e.command;
+        rawArgs = e.args;
+    }
+    if (typeof command !== "string" || command.length === 0)
+        return false;
+    // An interpreter pinned by absolute path must still exist. A bare "node" is
+    // resolved via PATH at spawn time, so there is nothing to verify here.
+    if (path.isAbsolute(command) && !fs.existsSync(command))
+        return false;
+    // The script it runs, when the entry names one. `args: ["mcp"]` names a
+    // subcommand of the binary in `command`, already checked above.
+    const script = (Array.isArray(rawArgs) ? rawArgs : []).find((a) => typeof a === "string" && path.isAbsolute(a) && /\.[cm]?js$/.test(a));
+    return script === undefined || fs.existsSync(script);
+}
 function backupConfig(filePath) {
     try {
         if (fs.existsSync(filePath))
@@ -671,10 +770,11 @@ export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServer
     const currentCmd = previousVexp?.["command"];
     const prevArgs = Array.isArray(previousVexp?.["args"]) ? previousVexp?.["args"] : undefined;
     const prevEnv = previousVexp?.env;
+    const envMatches = JSON.stringify(prevEnv) === JSON.stringify(targetEnv);
     const identical = currentCmd === targetCmd &&
         prevArgs !== undefined &&
         JSON.stringify(prevArgs) === JSON.stringify(targetArgs) &&
-        JSON.stringify(prevEnv) === JSON.stringify(targetEnv);
+        envMatches;
     // Legacy cleanup: remove any vexp/vexp-* keys; if the canonical 'vexp'
     // entry points at a command path that no longer exists on disk, drop it
     // too so we don't keep a stale pointer.
@@ -683,6 +783,11 @@ export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServer
     if (identical && removed.length === 0) {
         return false; // Already up to date and no legacy to clean
     }
+    // Another vexp install already left a working entry here — don't fight it.
+    // Only the install path may differ: `envMatches` still gates on the
+    // VEXP_WORKSPACE pin, so a moved or renamed project is repinned normally.
+    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+        return false;
     const servers = existing.mcpServers ?? {};
     servers["vexp"] = {
         command: targetCmd,
@@ -751,6 +856,34 @@ function tomlString(value) {
     return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 /** Extract the existing canonical [mcp_servers.vexp] block (incl. subsections). */
+/** Inverse of `tomlString` for the two forms it emits: a literal `'…'` (no
+ *  escapes) or a basic `"…"` with `\\` / `\"` escaped. */
+function parseTomlString(raw) {
+    const literal = /^'([^']*)'$/.exec(raw);
+    if (literal)
+        return literal[1];
+    const basic = /^"((?:[^"\\]|\\.)*)"$/.exec(raw);
+    if (basic)
+        return basic[1].replace(/\\(["\\])/g, "$1");
+    return undefined;
+}
+/**
+ * The binary an existing managed *direct* section points at, when it is still
+ * on disk. Undefined for an http section, a malformed one, or one naming a
+ * binary that is gone — each of which must be rebuilt from our own path.
+ *
+ * Mirrors `codexDirectBinary` in
+ * packages/vexp-vscode/src/providers/agent-auto-config.ts.
+ */
+function codexDirectBinary(section) {
+    const m = /^\s*command\s*=\s*(.+?)\s*$/m.exec(section);
+    if (!m)
+        return undefined;
+    const cmd = parseTomlString(m[1]);
+    if (!cmd || !path.isAbsolute(cmd) || !fs.existsSync(cmd))
+        return undefined;
+    return cmd;
+}
 function extractCodexVexpSection(content) {
     const m = content.match(CANONICAL_VEXP_TOML_SECTION_RE);
     return m ? m.join("\n") : "";
@@ -825,7 +958,7 @@ export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot)
     // stanza Codex can cache → "url is not supported for stdio". Pass the binary only
     // when it exists; buildCodexSection(direct, undefined) returns null → we then
     // PRESERVE the existing managed section instead of clobbering it with a url.
-    const coreBinaryPath = binaryPath && fs.existsSync(binaryPath) ? binaryPath : undefined;
+    const ourCoreBinary = binaryPath && fs.existsSync(binaryPath) ? binaryPath : undefined;
     let content = "";
     if (fs.existsSync(configPath))
         content = fs.readFileSync(configPath, "utf-8");
@@ -847,6 +980,15 @@ export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot)
         }
         return false;
     }
+    // Step 2b: adopt the binary a previous install already pinned here, when it
+    // still exists. Our own sections are not "user-managed", so `vexp setup` and
+    // every IDE activation rewrote this file with their own binary path — and the
+    // file is machine-global while Codex is detected by AGENTS.md, so it churned
+    // for every project at once. Adopting rather than skipping is what keeps this
+    // safe: the binary is interchangeable, but the workspace pin below is not and
+    // must still follow the project being configured. See the twin comment in
+    // vexp-vscode/src/providers/agent-auto-config.ts.
+    const coreBinaryPath = (transport === "direct" ? codexDirectBinary(existingSection) : undefined) ?? ourCoreBinary;
     const newSection = buildCodexSection({ transport, coreBinaryPath, workspaceRoot, mcpPort, token, home });
     if (!newSection) {
         // direct requested but binary missing → preserve the existing section (only
@@ -884,14 +1026,22 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
     const beforeServers = existing.servers;
     const previousVexp = beforeServers?.["vexp"];
     const prevArgs = Array.isArray(previousVexp?.["args"]) ? previousVexp?.["args"] : undefined;
+    const envMatches = JSON.stringify(previousVexp?.env) === JSON.stringify(targetEnv);
     const identical = previousVexp?.["command"] === targetCmd &&
         prevArgs !== undefined &&
         JSON.stringify(prevArgs) === JSON.stringify(targetArgs) &&
-        JSON.stringify(previousVexp?.env) === JSON.stringify(targetEnv);
+        envMatches;
     const removed = stripLegacyVexpEntries(existing, "servers");
     logRemoval(removed);
     if (identical && removed.length === 0)
         return false;
+    // Another vexp install already left a working entry here — don't fight it.
+    // This file is the worst offender: every VS Code fork reaches it through the
+    // Copilot branch, which is gated only on `.github/` existing. Only the
+    // install path may differ — `envMatches` still gates on the VEXP_WORKSPACE
+    // pin, so a moved or renamed project is repinned normally.
+    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+        return false;
     const servers = existing.servers ?? {};
     servers["vexp"] = {
         type: "stdio",
@@ -909,6 +1059,58 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
 /**
  * Write context_servers in .zed/settings.json for Zed.
  */
+/**
+ * Kilo Code MCP setup. Current Kilo Code (kilo.ai) reads MCP servers from the
+ * top-level `mcp` key inside `kilo.jsonc` — NOT a separate `.kilocode/mcp.json`
+ * (that path is no longer read). The config file is `.kilo/kilo.jsonc`
+ * (preferred) or `kilo.jsonc` at the project root; `.kilo/` wins if both exist,
+ * so we merge into whichever is present and create the clean `.kilo/` location
+ * on a fresh setup. Kilo's local-server shape is `{type:"local", command:[…],
+ * enabled:true}`. Other `mcp` entries (and other top-level keys) are preserved;
+ * an existing file is backed up before rewrite. Returns the workspace-relative
+ * path written, or null on a no-op / unparseable file.
+ */
+export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
+    const dotKilo = path.join(workspaceRoot, ".kilo", "kilo.jsonc");
+    const rootKilo = path.join(workspaceRoot, "kilo.jsonc");
+    const target = fs.existsSync(dotKilo)
+        ? dotKilo
+        : fs.existsSync(rootKilo)
+            ? rootKilo
+            : dotKilo; // fresh setup → the recommended cleaner location
+    const read = readJsonConfigSafe(target);
+    if (!read.ok) {
+        warnUnparseable(target);
+        return null;
+    }
+    const cfg = read.data;
+    const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
+    const command = useNode ? ["node", mcpServerPath] : [binaryPath, "mcp"];
+    const env = { VEXP_WORKSPACE: workspaceRoot };
+    const mcp = cfg.mcp ?? {};
+    const prev = mcp["vexp"];
+    const envMatches = JSON.stringify(prev?.["env"]) === JSON.stringify(env);
+    const identical = prev?.["type"] === "local" &&
+        prev?.["enabled"] === true &&
+        Array.isArray(prev?.["command"]) &&
+        JSON.stringify(prev["command"]) === JSON.stringify(command) &&
+        envMatches;
+    if (identical)
+        return null;
+    // Another vexp install already left a working entry here — don't fight it.
+    // Kilo's shape is `command: ["node", "<script>"]`. Only the install path may
+    // differ: `envMatches` still gates on the VEXP_WORKSPACE pin, and `enabled`
+    // must be true or the user turned it off deliberately.
+    if (envMatches && prev?.["enabled"] === true && vexpEntryStillResolves(prev))
+        return null;
+    mcp["vexp"] = { type: "local", command, env, enabled: true };
+    cfg.mcp = mcp;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (read.existed)
+        backupConfig(target);
+    fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+    return path.relative(workspaceRoot, target);
+}
 export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     const read = readJsonConfigSafe(p);
     if (!read.ok) {
@@ -923,14 +1125,21 @@ export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     const beforeCs = settings.context_servers;
     const previousVexp = beforeCs?.["vexp"];
     const curCmd = previousVexp?.["command"];
+    // Zed nests env inside `command`, unlike every other writer.
+    const envMatches = JSON.stringify(curCmd?.["env"]) === JSON.stringify(targetEnv);
     const identical = curCmd?.["path"] === targetCmd &&
         Array.isArray(curCmd?.["args"]) &&
         JSON.stringify(curCmd["args"]) === JSON.stringify(targetArgs) &&
-        JSON.stringify(curCmd["env"]) === JSON.stringify(targetEnv);
+        envMatches;
     const removed = stripLegacyVexpEntries(settings, "context_servers");
     logRemoval(removed);
     if (identical && removed.length === 0)
         return false;
+    // Another vexp install already left a working entry here — don't fight it.
+    // Only the install path may differ: `envMatches` still gates on the
+    // VEXP_WORKSPACE pin, so a moved or renamed project is repinned normally.
+    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+        return false;
     const cs = settings.context_servers ?? {};
     cs["vexp"] = {
         command: {
@@ -991,6 +1200,13 @@ export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRo
     logRemoval(removed);
     if (identical && removed.length === 0)
         return false;
+    // Another vexp install already left a working entry here — don't fight it.
+    // `prevEnv === undefined` is load-bearing, not a nicety: an entry still
+    // pinning VEXP_WORKSPACE must be rewritten no matter whose it is, because
+    // this file applies to EVERY project and the pin forces all parallel
+    // sessions onto one daemon (the migration described above).
+    if (removed.length === 0 && prevEnv === undefined && vexpEntryStillResolves(existing))
+        return false;
     const servers = config.mcpServers ?? {};
     servers["vexp"] = {
         command: desiredCommand,
@@ -1121,6 +1337,31 @@ export function installClaudeCodeHook(workspaceRoot) {
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
     return existed ? "updated" : "created";
 }
+// ---------------------------------------------------------------------------
+// opencode plugin - blocks grep/glob (and shelled-out search) when the daemon
+// is healthy. opencode has no PreToolUse hook, but auto-loads plugins from
+// .opencode/plugins/ and lets a `tool.execute.before` hook abort a tool by
+// throwing — the same enforcement the Claude Code guard hook provides.
+// ---------------------------------------------------------------------------
+/**
+ * Install the vexp-guard plugin for opencode.
+ * Writes .opencode/plugins/vexp-guard.js (opencode auto-loads the directory at
+ * startup — no config-file merge required). Returns the action taken, or null
+ * when the file is already byte-identical.
+ */
+export function installOpencodePlugin(workspaceRoot) {
+    const pluginDir = path.join(workspaceRoot, ".opencode", "plugins");
+    const pluginPath = path.join(pluginDir, "vexp-guard.js");
+    fs.mkdirSync(pluginDir, { recursive: true });
+    const existed = fs.existsSync(pluginPath);
+    if (existed) {
+        const current = fs.readFileSync(pluginPath, "utf-8");
+        if (current === VEXP_OPENCODE_GUARD)
+            return null; // identical - skip
+    }
+    fs.writeFileSync(pluginPath, VEXP_OPENCODE_GUARD, "utf-8");
+    return existed ? "updated" : "created";
+}
 function generateAgentConfig(template, vars) {
     switch (template) {
         case "claude-code":
@@ -1197,6 +1438,9 @@ Only use Read when you need exact raw content to edit a specific line.
 - **Session Memory**: auto-captures observations; memories auto-surfaced in results
 - **LSP Bridge**: VS Code captures type-resolved call edges
 - **Change Coupling**: co-changed files included as related context
+- **Query tips**: include real identifiers (ClassName, function_name) or file paths
+  in the task for precise matches - pure natural-language phrasing falls back to
+  text ranking and is less reliable
 
 ### Advanced Parameters
 - \`preset: "debug"\` - forces debug mode (capsule+tests+impact+memory)
@@ -1238,7 +1482,8 @@ vexp returns pre-indexed, graph-ranked context in a single call.
   rather than letting them search the codebase independently
 
 ### Tips
-- Natural language queries work well - vexp uses hybrid search (keyword + semantic + graph)
+- Include real identifiers (class/function names) or file paths in the task - literal
+  matches rank best; pure natural-language phrasing falls back to text ranking
 - Add \`include_tests: true\` when debugging
 - Use \`preset: "refactor"\` for deep impact analysis
 

package/dist/cli.js

@@ -16,6 +16,7 @@ import { ensureMcpHttpServer, mcpHttpStatus } from "./mcp-supervisor.js";
 import { installAutostart, uninstallAutostart, autostartStatus, migrateClaudeUnpinIfNeeded } from "./autostart.js";
 import { runServe } from "./serve.js";
 import { runDoctor } from "./doctor.js";
+import { socketPathFor } from "./socket-path.js";
 import { isTraceEnabled } from "./trace.js";
 const program = new Command();
 program
@@ -158,7 +159,9 @@ function findConfiguredWorkspace(startDir = process.cwd()) {
 /** True if the Unix socket at `socketPath` accepts a connection within `timeoutMs`. */
 function isSocketAlive(socketPath, timeoutMs = 300) {
     return new Promise((resolve) => {
-        if (!fs.existsSync(socketPath)) {
+        // A Windows named pipe is not a filesystem entry, so the existsSync
+        // pre-check would reject every live daemon. Only unix sockets are files.
+        if (process.platform !== "win32" && !fs.existsSync(socketPath)) {
             resolve(false);
             return;
         }
@@ -198,8 +201,7 @@ function isDaemonPidAlive(workspaceRoot) {
 async function ensureDaemonRunning(workspaceRoot, binaryPath) {
     if (process.env.VEXP_NO_AUTOSTART === "1")
         return;
-    const socketPath = path.join(workspaceRoot, ".vexp", "daemon.sock");
-    if (await isSocketAlive(socketPath))
+    if (await isSocketAlive(socketPathFor(workspaceRoot)))
         return;
     try {
         await runBinaryAsync(binaryPath, ["daemon-cmd", "start"], {
@@ -252,8 +254,9 @@ async function startBackgroundServices(binaryPath, workspaceRoot) {
     const spinnerDaemon = ora("Starting vexp daemon...").start();
     try {
         await runBinaryAsync(binaryPath, ["daemon-cmd", "start"], { silent: true, cwd: workspaceRoot });
-        const socketPath = path.join(workspaceRoot, ".vexp", "daemon.sock");
-        if (fs.existsSync(socketPath)) {
+        // Connect rather than stat: on Windows the daemon binds a named pipe and
+        // there is no socket file to find, so this always reported failure.
+        if (await isSocketAlive(socketPathFor(workspaceRoot))) {
             spinnerDaemon.succeed("vexp daemon started");
         }
         else {
@@ -1043,8 +1046,7 @@ async function printBanner() {
         console.log(chalk.dim("    → type '1 > 3' to run full setup, or `vexp setup`"));
     }
     else {
-        const socketPath = path.join(ws, ".vexp", "daemon.sock");
-        const socketAlive = await isSocketAlive(socketPath);
+        const socketAlive = await isSocketAlive(socketPathFor(ws));
         if (socketAlive) {
             // Display PID + uptime when we can read them; otherwise a plain "running".
             const { pid } = isDaemonPidAlive(ws);

package/dist/doctor.js

@@ -3,6 +3,7 @@ import * as os from "os";
 import * as path from "path";
 import * as net from "net";
 import chalk from "chalk";
+import { socketPathFor } from "./socket-path.js";
 // `vexp doctor` — audit the vexp MCP/daemon state WITHOUT connecting to a daemon.
 // Surfaces the failure modes behind the Codex drift report: stale daemons.json
 // entries, wrong-workspace resolution, mixed Codex transport (url+stdio),
@@ -43,20 +44,10 @@ function resolveWorkspace() {
         return { root: process.env.CLAUDE_PROJECT_DIR, source: "CLAUDE_PROJECT_DIR" };
     return { root: discoverWorkspaceRoot(process.cwd()), source: "cwd-discovery" };
 }
-function socketForWorkspace(root) {
-    if (process.platform === "win32") {
-        // FNV-1a, lowercase — mirrors get_socket_path / fnvHash.
-        let hash = BigInt("0xcbf29ce484222325");
-        const prime = BigInt("0x100000001b3");
-        const mask = BigInt("0xffffffffffffffff");
-        for (const b of Buffer.from(root.toLowerCase(), "utf-8")) {
-            hash ^= BigInt(b);
-            hash = (hash * prime) & mask;
-        }
-        return `\\\\.\\pipe\\vexp-${hash.toString(16).padStart(16, "0").slice(0, 8)}`;
-    }
-    return path.join(root, ".vexp", "daemon.sock");
-}
+// Was a fifth hand-rolled copy of the hash, and one of the two that zero-padded
+// it — so doctor probed a pipe name the daemon never binds for ~6% of Windows
+// workspaces and declared a healthy daemon down.
+const socketForWorkspace = socketPathFor;
 function reachable(sock, timeoutMs = 600) {
     return new Promise((resolve) => {
         const c = process.platform === "win32" ? net.createConnection(sock) : net.createConnection({ path: sock });

package/dist/hook-template.js

@@ -51,3 +51,93 @@ case "$(uname -s 2>/dev/null)" in
     ;;
 esac
 `;
+/**
+ * opencode plugin that enforces the same "use run_pipeline, not grep/glob"
+ * policy the Claude Code PreToolUse hook applies — opencode has no hook system,
+ * but its plugin API exposes a `tool.execute.before` hook where throwing an
+ * Error aborts the tool call. Written to `.opencode/plugins/vexp-guard.js` by
+ * `vexp setup-agents` (opencode auto-loads that directory at startup).
+ *
+ * It blocks the native `grep`/`glob` tools AND shelled-out tree search
+ * (grep/rg/find/... via bash) WHILE the vexp daemon is healthy, and fails OPEN
+ * when the daemon is down so search still works without an index — mirroring
+ * VEXP_GUARD_HOOK's healthy-marker + live-endpoint gate.
+ *
+ * The literal body is deliberately ASCII-only and free of backticks, `${...}`
+ * and backslash escapes so it can be embedded verbatim in a TS template literal
+ * (the VS Code extension keeps a byte-identical copy, enforced by the lockstep
+ * test in packages/vexp-cli/test/hook-template.test.ts). Do NOT introduce any
+ * of those characters here without updating that test's un-escape logic.
+ */
+export const VEXP_OPENCODE_GUARD = `// vexp-guard - opencode plugin (generated by 'vexp setup-agents').
+// Forces the agent onto vexp's run_pipeline by blocking opencode's native
+// grep/glob (and shelled-out tree search) WHILE the vexp daemon is healthy.
+// Fails OPEN when the daemon is down, so native search still works with no index.
+// Mirrors vexp's Claude Code PreToolUse guard (.claude/hooks/vexp-guard.sh).
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+// Walk up from start to the first ancestor that owns a .vexp dir.
+function findVexpDir(start) {
+  let dir = start;
+  for (;;) {
+    if (existsSync(join(dir, ".vexp"))) return join(dir, ".vexp");
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Is the pid in .vexp/daemon.pid a live process? Guards stale files left after
+// a kill -9: healthy + socket can linger, so existence alone is not enough.
+function pidAlive(pidFile) {
+  let pid = 0;
+  try { pid = parseInt(readFileSync(pidFile, "utf-8").trim(), 10); } catch (e) { return false; }
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return !!(e && e.code === "EPERM"); }
+}
+
+// The daemon writes .vexp/healthy when up and removes it on graceful shutdown.
+// Unix: also require a live socket AND a live pid. Windows has no socket file,
+// so the daemon drops a .vexp/daemon.pipe marker instead. A dead daemon fails
+// open so native search still works.
+function daemonHealthy(vexpDir) {
+  if (!vexpDir || !existsSync(join(vexpDir, "healthy"))) return false;
+  if (process.platform === "win32") return existsSync(join(vexpDir, "daemon.pipe"));
+  return existsSync(join(vexpDir, "daemon.sock")) && pidAlive(join(vexpDir, "daemon.pid"));
+}
+
+const SEARCH_TOOLS = new Set(["grep", "glob"]);
+const SHELL_SEARCH_BINS = ["rg", "grep", "egrep", "fgrep", "ag", "ack", "find", "fd", "fdfind"];
+
+// True when a bash command's first token is a tree-search binary (grep/rg/find).
+function isShellSearch(command) {
+  const t = (command || "").trim();
+  for (const b of SHELL_SEARCH_BINS) {
+    if (t === b || t.indexOf(b + " ") === 0) return true;
+  }
+  return false;
+}
+
+export const VexpGuard = async ({ directory, worktree }) => {
+  const root = worktree || directory || ".";
+  let vexpDir = null;
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (!vexpDir) vexpDir = findVexpDir(root);
+      if (!daemonHealthy(vexpDir)) return;
+      if (SEARCH_TOOLS.has(input.tool)) {
+        throw new Error(
+          "vexp daemon is running - call run_pipeline instead of " + input.tool +
+          " (pre-indexed, graph-ranked, ~60% fewer tokens)."
+        );
+      }
+      if (input.tool === "bash" && isShellSearch(output && output.args && output.args.command)) {
+        throw new Error(
+          "vexp daemon is running - call run_pipeline instead of shell search (grep/rg/find)."
+        );
+      }
+    },
+  };
+};
+`;

package/dist/socket-path.js

@@ -0,0 +1,40 @@
+import * as path from "path";
+/**
+ * Where the daemon listens for a given workspace root.
+ *
+ * MUST stay in lockstep with `get_socket_path` in vexp-core/src/utils.rs.
+ * Duplicated rather than imported because the CLI cannot depend on the MCP
+ * package at runtime; `test/workspace-hash-lockstep.test.ts` pins the parts
+ * that silently drift.
+ *
+ * Two things here are easy to get wrong, and both were:
+ *
+ *  - Windows has no socket file. The daemon binds a named pipe whose name is
+ *    the FNV-1a hash of the LOWERCASED root (drive letters vary by caller).
+ *    Sites that hardcoded `.vexp/daemon.sock` probed a file that never exists
+ *    on Windows, so the CLI reported a healthy daemon as stopped.
+ *  - The hash is NOT zero-padded: Rust renders the u64 with `format!("{:x}")`
+ *    and slices [..8].
+ */
+export function socketPathFor(workspaceRoot) {
+    if (process.platform === "win32") {
+        return `\\\\.\\pipe\\vexp-${fnvHash(workspaceRoot.toLowerCase()).slice(0, 8)}`;
+    }
+    const candidate = path.join(workspaceRoot, ".vexp", "daemon.sock");
+    // macOS/BSD sockaddr_un caps the path at 104 bytes; vexp-core falls back to
+    // /tmp past 100 chars, so a deeply-nested workspace listens there instead.
+    if (candidate.length <= 100)
+        return candidate;
+    return `/tmp/vexp-${fnvHash(workspaceRoot).slice(0, 12)}.sock`;
+}
+/** FNV-1a 64-bit, hex, unpadded — mirrors md5_hash() in vexp-core/src/utils.rs. */
+export function fnvHash(input) {
+    let hash = BigInt("0xcbf29ce484222325");
+    const prime = BigInt("0x100000001b3");
+    const mask = BigInt("0xffffffffffffffff");
+    for (const byte of Buffer.from(input, "utf-8")) {
+        hash ^= BigInt(byte);
+        hash = (hash * prime) & mask;
+    }
+    return hash.toString(16);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexp-cli",
-  "version": "2.1.7",
+  "version": "2.2.1",
   "description": "Vexp — Context Engine for AI Coding Agents. Pre-indexes your codebase into a dependency graph and delivers ranked context to any MCP-compatible agent. 58% lower cost per task, 90% fewer tool calls (SWE-bench Verified). Works with Claude Code, Cursor, Copilot, Windsurf, Codex, Cline, Aider, and 12+ agents. Local-first. Your code never leaves your machine.",
   "type": "module",
   "bin": {
@@ -100,10 +100,10 @@
     "node": ">=20.0.0"
   },
   "optionalDependencies": {
-    "@vexp/core-linux-x64": "2.1.7",
-    "@vexp/core-linux-arm64": "2.1.7",
-    "@vexp/core-darwin-x64": "2.1.7",
-    "@vexp/core-darwin-arm64": "2.1.7",
-    "@vexp/core-win32-x64": "2.1.7"
+    "@vexp/core-linux-x64": "2.2.1",
+    "@vexp/core-linux-arm64": "2.2.1",
+    "@vexp/core-darwin-x64": "2.2.1",
+    "@vexp/core-darwin-arm64": "2.2.1",
+    "@vexp/core-win32-x64": "2.2.1"
   }
 }