vexp-cli 2.2.0 → 2.2.2

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,8 +154,13 @@ 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",
@@ -337,6 +346,20 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             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,
@@ -353,6 +376,60 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
 export function getAgentList() {
     return [...AGENT_DETECTORS];
 }
+/** Fold a name to its comparable form: case, spaces, dots and dashes carry no
+ *  meaning here ("claude-code", "Claude Code" and "claudecode" are one agent). */
+function foldAgentName(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/**
+ * Canonicalize a name given to `--agents`, or null if it names no agent.
+ *
+ * `configureSelectedAgents` matches with `Array.includes` on the exact string,
+ * so "opencode" silently configured nothing while "Opencode" worked — nobody
+ * can be expected to know the capitalization, and the failure was invisible.
+ */
+export function resolveAgentName(input) {
+    const want = foldAgentName(input);
+    if (!want)
+        return null;
+    return AGENT_DETECTORS.find((d) => foldAgentName(d.agent) === want)?.agent ?? null;
+}
+/** Levenshtein distance, for "did you mean" on an unknown --agents name. */
+function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    const cur = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev.splice(0, prev.length, ...cur);
+    }
+    return prev[b.length];
+}
+/**
+ * The known agent an unknown name most likely meant, or null when nothing is
+ * close enough to be worth suggesting. Substring hits win (a bare "copilot"
+ * means "GitHub Copilot"); otherwise allow a couple of typos.
+ */
+export function suggestAgentName(input) {
+    const want = foldAgentName(input);
+    if (!want)
+        return null;
+    const contained = AGENT_DETECTORS.find((d) => {
+        const f = foldAgentName(d.agent);
+        return f.includes(want) || want.includes(f);
+    });
+    if (contained)
+        return contained.agent;
+    let best = null;
+    for (const d of AGENT_DETECTORS) {
+        const dist = editDistance(want, foldAgentName(d.agent));
+        if (!best || dist < best.d)
+            best = { name: d.agent, d: dist };
+    }
+    return best && best.d <= 3 ? best.name : null;
+}
 /**
  * Configure specific agents selected by the user.
  * Unlike configureAgents which auto-detects, this forces configuration
@@ -445,6 +522,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 };
@@ -537,6 +617,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))
@@ -685,10 +824,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.
@@ -697,6 +837,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,
@@ -765,6 +910,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") : "";
@@ -839,7 +1012,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");
@@ -861,6 +1034,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
@@ -898,14 +1080,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",
@@ -953,13 +1143,20 @@ export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
     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) &&
-        JSON.stringify(prev["env"]) === JSON.stringify(env);
+        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 });
@@ -982,14 +1179,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: {
@@ -1050,6 +1254,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,
@@ -1180,6 +1391,59 @@ 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
+        // Content differs: either an older vexp guard, or a copy the user tuned by
+        // hand. We refresh either way — refusing to touch a hand-edited plugin would
+        // freeze that user on a stale guard forever — but their version stays
+        // recoverable at vexp-guard.js.vexp-bak instead of being silently discarded.
+        backupConfig(pluginPath);
+    }
+    fs.writeFileSync(pluginPath, VEXP_OPENCODE_GUARD, "utf-8");
+    return existed ? "updated" : "created";
+}
+/**
+ * The single highest-leverage instruction we ship, and for a long time the one
+ * most agents never saw.
+ *
+ * vexp retrieval is identifier/path-first: FTS supplies the candidate pool and
+ * the semantic layer only RE-RANKS it, so a symbol that no query token reaches
+ * never enters the running at all. A task written as prose ("why does the proxy
+ * fail?") therefore ranks far worse than the same task anchored on the symbols
+ * and paths it is actually about — the difference between a useful pivot set and
+ * "the vexp result wasn't relevant".
+ *
+ * This shipped only in the Claude Code and Cursor templates, while the AGENTS.md
+ * example (`"task": "fix auth bug"`) actively modelled the weak mode — so two
+ * independent field reports ("the index seems not very useful") came from users
+ * whose instructions never told them the one thing that makes retrieval land.
+ * Shared by every prose template so the wording cannot drift again. ASCII only
+ * (these land in files that get read on Windows).
+ */
+const QUERY_SHAPE = `### Query shape (do this)
+- Anchor the task on real identifiers (ClassName, functionName) or file paths:
+  \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
+- A pure natural-language question ("why does login fail?") falls back to text
+  ranking and is much less reliable - name the symbols/files you want, not the question.`;
 function generateAgentConfig(template, vars) {
     switch (template) {
         case "claude-code":
@@ -1221,6 +1485,12 @@ uses fewer tokens than manual searching. Prefer \`get_skeleton\` over Read to
 inspect files (detail: minimal/standard/detailed, 70-90% token savings).
 Only use Read when you need exact raw content to edit a specific line.
 
+The hook denies Grep/Glob while the daemon is up. That is policy, not a transient
+failure: call \`run_pipeline\` instead - do NOT work around it by shelling out or
+writing a script. vexp only covers indexed source inside the workspace: for runtime
+logs, build output (dist/, .vite/, node_modules/) or files outside the repo it has
+no answer - use Bash/Read there, those are never blocked.
+
 ### Primary Tool
 - \`run_pipeline\` - **USE THIS FOR EVERYTHING**. Single call that runs
   capsule + impact + memory server-side. Returns compressed results.
@@ -1236,6 +1506,8 @@ Only use Read when you need exact raw content to edit a specific line.
 - \`index_status\` - indexing status and health check
 - \`expand_vexp_ref\` - expand V-REF hash placeholders in v2 compact output
 
+${QUERY_SHAPE}
+
 ### Workflow
 1. \`run_pipeline("your task")\` - ALWAYS FIRST. Returns pivots + impact + memories in 1 call
 2. Need more detail on a file? Use \`get_skeleton({ files: [...], detail: "detailed" })\` - avoid Read unless editing
@@ -1256,9 +1528,6 @@ 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)
@@ -1289,19 +1558,19 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
   rather than letting them search the codebase independently
 
 ### Tips
-- 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
 
@@ -1329,11 +1598,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1378,11 +1649,13 @@ When working on this codebase:
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - token-efficient file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1408,11 +1681,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1438,11 +1713,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1468,13 +1745,20 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
+- If a search tool is denied, that is policy, not a transient failure: call \`run_pipeline\`
+  instead. Do NOT work around it with shell search or by writing a script.
+- vexp only covers indexed source inside the workspace. For runtime logs, build output
+  (dist/, .vite/, node_modules/) or files outside the repo it has no answer - use your
+  normal tools there; those searches are never blocked.
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
   rather than letting them search the codebase independently
 
@@ -1498,11 +1782,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ## Available vexp tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ## Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1528,11 +1814,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`

package/dist/cli.js

@@ -8,7 +8,7 @@ import * as fs from "fs";
 import * as net from "net";
 import { checkbox, confirm } from "@inquirer/prompts";
 import { getBinaryPath, getInstalledVersion, getMcpServerPath, binaryEnv } from "./binary.js";
-import { detectAgents, getAgentList, configureSelectedAgents } from "./agent-config.js";
+import { detectAgents, getAgentList, configureSelectedAgents, resolveAgentName, suggestAgentName } from "./agent-config.js";
 import { CLI_VERSION } from "./version.js";
 import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocked, } from "./license.js";
 import { checkForUpdate } from "./update-check.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 {
@@ -552,8 +555,24 @@ program
         const detectedNames = new Set(detected.map((a) => a.agent));
         let selectedNames;
         if (typeof opts.agents === "string") {
-            // Explicit list from --agents flag
-            selectedNames = opts.agents.split(",").map((s) => s.trim());
+            // Explicit list from --agents flag. Resolve every name BEFORE writing
+            // anything: matching is exact downstream, so an unrecognised name used
+            // to configure nothing while setup still reported success — the worst
+            // possible outcome for the flag whose whole point is automation.
+            const requested = opts.agents.split(",").map((s) => s.trim()).filter(Boolean);
+            const unknown = requested.filter((n) => resolveAgentName(n) === null);
+            if (unknown.length > 0 || requested.length === 0) {
+                console.error(chalk.red(`\n✖ Unknown agent: ${unknown.map((u) => `"${u}"`).join(", ") || "(empty --agents list)"}`));
+                for (const u of unknown) {
+                    const hint = suggestAgentName(u);
+                    if (hint)
+                        console.error(chalk.yellow(`  Did you mean: ${hint}?`));
+                }
+                console.error(chalk.dim(`  Valid agents: ${allAgents.map((a) => a.agent).join(", ")}`));
+                console.error(chalk.dim("  Names are matched ignoring case and punctuation.\n"));
+                process.exit(1);
+            }
+            selectedNames = requested.map((n) => resolveAgentName(n));
             console.log(chalk.dim(`  Agents (from flag): ${selectedNames.join(", ")}`));
         }
         else {
@@ -1043,8 +1062,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);