vexp-cli 2.2.2 → 2.2.4

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, VEXP_OPENCODE_GUARD } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -291,8 +291,20 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         // Write MCP config for agents with mcpConfigFile (project-level JSON)
         if (detector.mcpConfigFile) {
             const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
-            const alwaysAllow = detector.agent === "Windsurf" ? VEXP_TOOLS : undefined;
-            if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot)) {
+            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);
             }
         }
@@ -345,10 +357,47 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            // 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).
+            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)));
+        }
+        // Cursor: preToolUse hook matching Grep. Text search only - Cursor's native
+        // semantic search is not hookable.
+        if (detector.agent === "Cursor") {
+            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"));
         }
-        // Opencode: install the guard plugin that blocks grep/glob while the daemon
-        // is up (opencode's analogue of the Claude Code PreToolUse hook).
+        // 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);
+            if (wroteMcp)
+                mcpConfigs.push(wroteMcp);
             const pluginResult = installOpencodePlugin(workspaceRoot);
             if (pluginResult) {
                 results.push({
@@ -492,8 +541,14 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
         }
         if (detector.mcpConfigFile) {
             const mcpConfigPath = path.join(workspaceRoot, detector.mcpConfigFile);
-            const alwaysAllow = detector.agent === "Windsurf" ? VEXP_TOOLS : undefined;
-            if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot))
+            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 (detector.agent === "Claude Code") {
@@ -523,8 +578,24 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
                 mcpConfigs.push(".zed/settings.json");
         }
         if (detector.agent === "Opencode") {
+            const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
+            if (wrote)
+                mcpConfigs.push(wrote);
             installOpencodePlugin(workspaceRoot);
         }
+        if (detector.agent === "Cursor") {
+            installCursorHook(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);
+            installKiloPlugin(workspaceRoot);
+        }
         results.push({ agent: detector.agent, configFile: detector.configFile, content, alreadyExists, action });
     }
     return { agents: results, mcpConfigs };
@@ -808,7 +879,10 @@ export function configureAntigravityGlobal(binaryPath, mcpServerPath) {
     }
     return writeMcpConfig(path.join(cfgDir, "mcp_config.json"), binaryPath, undefined, mcpServerPath, undefined);
 }
-export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServerPath, workspaceRoot) {
+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") {
     const read = readJsonConfigSafe(mcpConfigPath);
     if (!read.ok) {
         warnUnparseable(mcpConfigPath);
@@ -847,7 +921,7 @@ export function writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpServer
         command: targetCmd,
         args: targetArgs,
         ...(targetEnv ? { env: targetEnv } : {}),
-        ...(alwaysAllow && alwaysAllow.length > 0 ? { alwaysAllow } : {}),
+        ...(alwaysAllow && alwaysAllow.length > 0 ? { [approveKey]: alwaysAllow } : {}),
     };
     existing.mcpServers = servers;
     fs.mkdirSync(path.dirname(mcpConfigPath), { recursive: true });
@@ -1124,14 +1198,93 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
  * 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) {
+/**
+ * The kilo.jsonc that Kilo will actually read: `.kilo/kilo.jsonc` wins over a
+ * root `kilo.jsonc` when both exist, and a fresh setup gets the cleaner `.kilo/`
+ * location. Shared by the MCP writer and the guard-plugin installer so the two
+ * can never disagree about which file is live.
+ */
+export function kiloConfigTarget(workspaceRoot) {
     const dotKilo = path.join(workspaceRoot, ".kilo", "kilo.jsonc");
     const rootKilo = path.join(workspaceRoot, "kilo.jsonc");
-    const target = fs.existsSync(dotKilo)
+    return fs.existsSync(dotKilo)
         ? dotKilo
         : fs.existsSync(rootKilo)
             ? rootKilo
-            : dotKilo; // fresh setup → the recommended cleaner location
+            : dotKilo;
+}
+/**
+ * The opencode config file that opencode will actually read for `mcp`:
+ * `opencode.jsonc` wins over `opencode.json` when both exist (jsonc is the
+ * variant users keep when they want comments, and it is the one they edit),
+ * and a fresh setup gets plain `opencode.json` — opencode's documented default.
+ * Project-scope only: we never touch the machine-global
+ * `~/.config/opencode/opencode.json`, because a per-workspace VEXP_WORKSPACE pin
+ * in a global file would mis-target every other project on the machine.
+ */
+export function opencodeConfigTarget(workspaceRoot) {
+    const jsonc = path.join(workspaceRoot, "opencode.jsonc");
+    const json = path.join(workspaceRoot, "opencode.json");
+    return fs.existsSync(jsonc) ? jsonc : json;
+}
+/**
+ * Opencode MCP setup. Opencode reads MCP servers from the top-level `mcp` key
+ * of `opencode.json` / `opencode.jsonc` — the same shape Kilo Code uses, because
+ * Kilo v7 vendors opencode wholesale: `{type:"local", command:[…], enabled:true}`.
+ *
+ * Until this existed, picking Opencode in `vexp setup` wrote AGENTS.md and the
+ * guard plugin and NOTHING else — the worst possible end state, because the
+ * guard blocks grep/glob whenever the daemon is healthy while `run_pipeline` was
+ * never registered: the agent lost search and gained no replacement. Reported by
+ * an AppSumo user who had to add the `mcp` block by hand.
+ *
+ * Other `mcp` entries and unrelated 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 configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath) {
+    const target = opencodeConfigTarget(workspaceRoot);
+    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;
+    // A working entry is already here — either another vexp install, or the user's
+    // own hand-written block (this bug made several people write one). Don't fight
+    // it: only the install path may differ, and `envMatches` still gates on the
+    // VEXP_WORKSPACE pin so a moved project is repinned normally.
+    if (envMatches && prev?.["enabled"] === true && vexpEntryStillResolves(prev))
+        return null;
+    mcp["vexp"] = { type: "local", command, env, enabled: true };
+    cfg.mcp = mcp;
+    // `$schema` first if opencode's own key is absent — a fresh file we author
+    // should look like the one opencode's docs tell users to write.
+    if (cfg.$schema === undefined) {
+        cfg.$schema = "https://opencode.ai/config.json";
+    }
+    if (read.existed)
+        backupConfig(target);
+    // A .jsonc target loses its comments here (we reserialize parsed JSON), which
+    // is why the pre-write backup is not optional for this writer.
+    fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+    return path.relative(workspaceRoot, target);
+}
+export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
+    const target = kiloConfigTarget(workspaceRoot);
     const read = readJsonConfigSafe(target);
     if (!read.ok) {
         warnUnparseable(target);
@@ -1403,14 +1556,13 @@ export function installClaudeCodeHook(workspaceRoot) {
  * 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 });
+function writeGuardScript(scriptPath, content) {
+    const pluginPath = scriptPath;
+    fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
     const existed = fs.existsSync(pluginPath);
     if (existed) {
         const current = fs.readFileSync(pluginPath, "utf-8");
-        if (current === VEXP_OPENCODE_GUARD)
+        if (current === content)
             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
@@ -1418,9 +1570,118 @@ export function installOpencodePlugin(workspaceRoot) {
         // recoverable at vexp-guard.js.vexp-bak instead of being silently discarded.
         backupConfig(pluginPath);
     }
-    fs.writeFileSync(pluginPath, VEXP_OPENCODE_GUARD, "utf-8");
+    fs.writeFileSync(pluginPath, content, "utf-8");
     return existed ? "updated" : "created";
 }
+export function installOpencodePlugin(workspaceRoot) {
+    return writeGuardScript(path.join(workspaceRoot, ".opencode", "plugins", "vexp-guard.js"), VEXP_OPENCODE_GUARD);
+}
+/**
+ * Cursor enforcement — `preToolUse` hook with matcher `Grep`.
+ *
+ * Cursor is the only VS Code fork where this is possible: Windsurf's hooks are
+ * action-category based (twelve fixed events, no matcher, no tool names) and
+ * expose NO search event at all, so there is nothing there to redirect. Cursor
+ * exposes `Grep` as a matchable tool and feeds `agent_message` back to the model,
+ * which is the whole mechanism.
+ *
+ * Scope of the claim, deliberately narrow: this covers TEXT search. Cursor's
+ * native semantic codebase search has no documented tool identifier, so it is not
+ * hookable and not covered. Do not describe this as "Cursor is enforced".
+ *
+ * `command` is `node`, not a shell script: Cursor documents no PowerShell variant
+ * and never says which shell runs `command` on Windows. A bash guard would repeat
+ * the Claude Code hook's Windows bug (silently enforced nothing for releases).
+ * The path is project-root-relative because Cursor runs PROJECT hooks from the
+ * project root — `./hooks/x` there would resolve to `<project>/hooks/x`.
+ *
+ * `failClosed` is left at its default (false): a crashing guard must let the
+ * agent work, not lock it out.
+ */
+export function installCursorHook(workspaceRoot) {
+    const rel = path.join(".cursor", "hooks", "vexp-guard.js");
+    const hookPath = path.join(workspaceRoot, rel);
+    const hook = writeGuardScript(hookPath, VEXP_CURSOR_GUARD);
+    const cfgPath = path.join(workspaceRoot, ".cursor", "hooks.json");
+    const command = `node ${rel.split(path.sep).join("/")}`;
+    const read = readJsonConfigSafe(cfgPath);
+    if (!read.ok) {
+        warnUnparseable(cfgPath);
+        return { hook, registered: false };
+    }
+    const cfg = read.data;
+    const hooks = cfg.hooks ?? {};
+    const preToolUse = Array.isArray(hooks.preToolUse) ? [...hooks.preToolUse] : [];
+    // Idempotent by COMMAND, not by array position: re-running setup must not
+    // append a second copy, and a user's own preToolUse hooks must survive.
+    const ours = (e) => !!e && typeof e === "object" && e.command === command;
+    const existing = preToolUse.findIndex(ours);
+    const entry = { command, matcher: "Grep" };
+    if (existing >= 0 && JSON.stringify(preToolUse[existing]) === JSON.stringify(entry)) {
+        return { hook, registered: false }; // already exactly right
+    }
+    if (existing >= 0)
+        preToolUse[existing] = entry;
+    else
+        preToolUse.push(entry);
+    hooks.preToolUse = preToolUse;
+    cfg.hooks = hooks;
+    if (cfg.version === undefined)
+        cfg.version = 1;
+    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+    if (read.existed)
+        backupConfig(cfgPath);
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2), "utf-8");
+    return { hook, registered: true };
+}
+/**
+ * Kilo Code enforcement — the same plugin, because Kilo v7 IS opencode: the
+ * rewrite vendors it wholesale (the loader lives at packages/opencode/src/ inside
+ * Kilo-Org/kilocode), so `tool.execute.before`, the `input.tool` ids and the
+ * grep/glob arg schemas are the same code, not merely a similar API.
+ *
+ * Loading is by auto-discovery: the loader globs `{plugin,plugins}/*.{ts,js}`
+ * with cwd = the directory of the kilo.jsonc it read, and every match is
+ * registered at startup with no config entry. So `.kilo/plugins/vexp-guard.js`
+ * is picked up for free — and we prefer that to an explicit `plugin` array entry
+ * because it leaves the user's config untouched.
+ *
+ * The one case auto-discovery misses: a project whose config is the ROOT
+ * `kilo.jsonc`, where cwd is the repo root and the scanned directory would be
+ * `<root>/plugins/` — we will not create a top-level `plugins/` dir in someone's
+ * repo just to be found. There we keep the file in `.kilo/plugins/` and register
+ * it explicitly, with the path relative to the config file (the loader resolves
+ * path specs against the declaring config's own directory, NOT the project root).
+ *
+ * The glob is non-recursive, so the file must sit flat in that directory.
+ *
+ * NOTE: `KILO_PURE=1` skips all external plugins. A CI run with it set gets no
+ * guard — correctly so, but it means "the guard is installed" is not the same
+ * claim as "the guard ran".
+ */
+export function installKiloPlugin(workspaceRoot) {
+    const pluginPath = path.join(workspaceRoot, ".kilo", "plugins", "vexp-guard.js");
+    const plugin = writeGuardScript(pluginPath, VEXP_OPENCODE_GUARD);
+    // `.kilo/kilo.jsonc` (the common case) → auto-discovery already covers us.
+    const target = kiloConfigTarget(workspaceRoot);
+    if (path.dirname(target) !== workspaceRoot)
+        return { plugin, registered: false };
+    const rel = "./" + path.relative(workspaceRoot, pluginPath).split(path.sep).join("/");
+    const read = readJsonConfigSafe(target);
+    if (!read.ok) {
+        warnUnparseable(target);
+        return { plugin, registered: false };
+    }
+    const cfg = read.data;
+    const list = Array.isArray(cfg.plugin) ? cfg.plugin : [];
+    if (list.includes(rel))
+        return { plugin, registered: false }; // already declared
+    cfg.plugin = [...list, rel];
+    if (read.existed)
+        backupConfig(target);
+    fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+    return { plugin, registered: true };
+}
 /**
  * The single highest-leverage instruction we ship, and for a long time the one
  * most agents never saw.
@@ -1802,34 +2063,65 @@ Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
 <!-- /vexp -->`;
 }
 function genericTemplate(vars) {
-    return `## vexp <!-- vexp v${vars.version} -->
+    return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
 
-**MANDATORY: use \`run_pipeline\` - do NOT grep or glob the codebase.**
-vexp returns pre-indexed, graph-ranked context in a single call.
+### MANDATORY: call run_pipeline FIRST - do NOT grep, glob, or read to explore
+For every task - bug fixes, features, refactors, questions about the code:
+**call \`run_pipeline\` before any other tool**. It runs context search + impact
+analysis + memory recall in a single call and returns compressed, graph-ranked
+results.
+
+This holds even when you already know the file path. The pipeline returns the
+callers, the blast radius and the co-changed files that opening the file cannot.
+No tool here will stop you from searching manually, so honouring this rule is on
+you: "I already knew where to look" is not an exception, it is the exact case the
+rule exists for.
+
+Do NOT use grep, glob, built-in codebase search, or shell commands to explore.
+Do NOT open files one by one to find your way around: use \`get_skeleton\`
+(detail: minimal/standard/detailed, 70-90% fewer tokens than reading the file).
+Read raw file content only when you need it to edit a specific line.
+
+vexp indexes source inside the workspace and nothing else. Runtime logs, build
+output (dist/, .vite/, node_modules/) and files outside the repo are NOT indexed -
+read those directly, this rule does not cover them.
+
+### Primary tool
+- \`run_pipeline\` - **USE THIS FOR EVERYTHING**. Auto-detects intent
+  (debug/modify/refactor/explore) from your task. Includes file content for pivots.
+  - \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
+  - \`run_pipeline({ "task": "refactor db layer", "preset": "refactor" })\`
+  - \`run_pipeline({ "task": "add auth", "observation": "using JWT" })\` - saves an insight in the same call
+
+### Other MCP tools (only when run_pipeline is not enough)
+- \`get_skeleton\` - **preferred over reading a file**: signatures and structure, 3 detail levels
+- \`index_status\` - indexing status and health check
+- \`expand_vexp_ref\` - expand V-REF hash placeholders in v2 compact output
 
-### Workflow
-1. \`run_pipeline\` with your task description - ALWAYS FIRST (replaces all other tools)
-2. Make targeted changes based on the context returned
-3. \`run_pipeline\` again only if you need more context
+${QUERY_SHAPE}
 
-### Available MCP tools
-- \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  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
+### Workflow
+1. \`run_pipeline("your task")\` - ALWAYS FIRST. Returns pivots + impact + memories in 1 call
+2. Need more on a file? \`get_skeleton({ files: [...], detail: "detailed" })\` - not a raw read
+3. Make targeted changes based on the context returned
+4. \`run_pipeline\` again ONLY if you need more context while implementing
+5. Do NOT chain vexp calls - one \`run_pipeline\` replaces capsule + impact + memory + observation
 
-${QUERY_SHAPE}
+### Sub-agents and background tasks
+- Sub-agents CAN and MUST call \`run_pipeline\` - always give them the task description
+- Do NOT spawn an agent to search freely: call \`run_pipeline\` first, then pass the
+  returned context into the agent prompt
 
-### 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
+### Fallback
+If \`run_pipeline\` returns \`status: "degraded"\` or 0 pivots with an INDEX EMPTY warning,
+the index is empty or still building. Use the built-in search and read tools directly
+until it is ready - do not stall waiting for vexp.
 
-### Smart Features
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
+### Smart features (automatic - no action needed)
+Intent detection, hybrid keyword+semantic+graph ranking, session memory,
+change coupling, auto-expanding budget.
 
-### Multi-Repo
+### Multi-repo
 \`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope. Run \`index_status\` to see aliases.
 <!-- /vexp -->`;
 }

package/dist/cli.js

@@ -18,6 +18,7 @@ import { runServe } from "./serve.js";
 import { runDoctor } from "./doctor.js";
 import { socketPathFor } from "./socket-path.js";
 import { isTraceEnabled } from "./trace.js";
+import { resolveParentWorkspace, listWorkspaceRepos, addRepoToWorkspace, } from "./workspace-repos.js";
 const program = new Command();
 program
     .name("vexp")
@@ -54,8 +55,11 @@ program.hook("preAction", async (_thisCmd, actionCmd) => {
         return;
     if (AUTOSTART_SKIP.has(actionCmd.name()))
         return;
-    const workspaceRoot = findConfiguredWorkspace();
-    if (!workspaceRoot)
+    // Effective workspace: inside a connected secondary repo this resolves to
+    // the parent, so we boot (or reuse) the parent daemon instead of spawning
+    // a conflicting one for the child.
+    const eff = findEffectiveWorkspace();
+    if (!eff)
         return;
     let binaryPath;
     try {
@@ -66,7 +70,7 @@ program.hook("preAction", async (_thisCmd, actionCmd) => {
     }
     // Full bootstrap: daemon + MCP + autostart-if-needed. All three steps are
     // internally idempotent — no duplicate processes across invocations.
-    await ensureBootstrap(workspaceRoot, binaryPath);
+    await ensureBootstrap(eff.root, binaryPath);
 });
 // ────────────────────────────────────────────────────
 // Resolve the platform binary (no network — bundled via npm)
@@ -83,7 +87,7 @@ function ensureBinary() {
 // Tier limits are now enforced directly by the Rust daemon via license.jwt verification.
 // Track whether we're in interactive REPL mode (don't call process.exit)
 let replMode = false;
-function runBinary(binaryPath, args) {
+function runBinary(binaryPath, args, options) {
     if (replMode) {
         // In REPL mode, run synchronously and don't exit the process.
         // CRITICAL: stdin must be "ignore" (not "inherit") — inheriting stdin
@@ -94,6 +98,7 @@ function runBinary(binaryPath, args) {
         // CLI, never stdin, so ignoring it is safe.
         const result = spawnSync(binaryPath, args, {
             stdio: ["ignore", "inherit", "inherit"],
+            cwd: options?.cwd,
             env: binaryEnv(binaryPath),
         });
         if (result.error) {
@@ -103,6 +108,7 @@ function runBinary(binaryPath, args) {
     }
     const child = spawn(binaryPath, args, {
         stdio: "inherit",
+        cwd: options?.cwd,
         env: binaryEnv(binaryPath),
     });
     child.on("exit", (code) => {
@@ -143,12 +149,16 @@ function runBinaryAsync(binaryPath, args, options) {
 // ────────────────────────────────────────────────────
 /**
  * Walk up from cwd looking for `.vexp/manifest.json` — the marker that
- * `vexp setup` has been run on this tree. Returns null if none found.
+ * `vexp setup` has been run on this tree. A `.vexp/parent_workspace.json`
+ * counts too: a freshly-connected secondary repo has the parent link before
+ * its first index writes a manifest, and it must already resolve to the
+ * parent workspace instead of looking unconfigured. Returns null if none found.
  */
 function findConfiguredWorkspace(startDir = process.cwd()) {
     let current = path.resolve(startDir);
     while (true) {
-        if (fs.existsSync(path.join(current, ".vexp", "manifest.json")))
+        if (fs.existsSync(path.join(current, ".vexp", "manifest.json")) ||
+            fs.existsSync(path.join(current, ".vexp", "parent_workspace.json")))
             return current;
         const parent = path.dirname(current);
         if (parent === current)
@@ -156,6 +166,22 @@ function findConfiguredWorkspace(startDir = process.cwd()) {
         current = parent;
     }
 }
+/**
+ * Workspace the CLI should actually operate on. When cwd is inside a
+ * secondary repo of a multi-repo workspace (it carries a valid
+ * `.vexp/parent_workspace.json`), every daemon interaction targets the PARENT:
+ * spawning a second daemon in the child made both fight over the same repo
+ * DBs (double watchers, duplicate LLM in VRAM) until the user killed
+ * everything. `parent` is set only when redirected, so callers can tell the
+ * user what happened.
+ */
+function findEffectiveWorkspace(startDir = process.cwd()) {
+    const ws = findConfiguredWorkspace(startDir);
+    if (!ws)
+        return null;
+    const parent = resolveParentWorkspace(ws);
+    return parent ? { root: parent.parentRoot, parent } : { root: ws };
+}
 /** True if the Unix socket at `socketPath` accepts a connection within `timeoutMs`. */
 function isSocketAlive(socketPath, timeoutMs = 300) {
     return new Promise((resolve) => {
@@ -486,7 +512,13 @@ program
     const args = ["daemon-cmd", action];
     if (opts.follow)
         args.push("--follow");
-    runBinary(binaryPath, args);
+    // Inside a connected secondary repo, daemon commands target the PARENT
+    // workspace daemon — the child must never run its own competing daemon.
+    const eff = findEffectiveWorkspace();
+    if (eff?.parent) {
+        console.log(chalk.cyan(`This repo is part of workspace "${eff.parent.workspaceName}" — targeting the parent daemon (${shortPath(eff.root)})`));
+    }
+    runBinary(binaryPath, args, eff?.parent ? { cwd: eff.root } : undefined);
 });
 program
     .command("doctor")
@@ -997,10 +1029,10 @@ await checkForUpdate();
 // ── Sub-menu: Setup & Config ──
 const MENU_CONFIG = [
     { key: "1", label: "init", hint: "Create .vexp/ and run first index", description: "Creates .vexp/ directory, runs a full index, installs git hooks.\n    Run once when adding vexp to a new project." },
-    { key: "2", label: "index", hint: "Re-index the repository", description: "Scans all source files, builds the AST graph (nodes + edges),\n    and saves it to .vexp/index.db.\n    Output: file count, node count, edge count, time elapsed." },
+    { key: "2", label: "index", hint: "Re-index the workspace (all connected repos)", description: "Scans all source files, builds the AST graph (nodes + edges),\n    and saves it to .vexp/index.db. In a multi-repo workspace every\n    connected repo is re-indexed, not just the current one.\n    Output: file count, node count, edge count, time elapsed." },
     { key: "3", label: "setup", hint: "Full setup (index + agents + hooks)", description: "One-command bootstrap: indexes the codebase, detects AI agents,\n    writes MCP configs, installs git hooks." },
     { key: "4", label: "setup-agents", hint: "Choose which AI agents to configure", description: "Select agents (Claude, Cursor, Windsurf, Copilot, …) to configure.\n    Creates config directories and writes MCP settings for each." },
-    { key: "5", label: "daemon-cmd", hint: "Manage daemon (start/stop/status/logs)", description: "Controls the background daemon:\n    start  → launches the daemon (indexes + watches for changes)\n    stop   → stops the running daemon\n    status → shows node/edge/file counts\n    logs   → prints .vexp/vexp.log" },
+    { key: "5", label: "daemon-cmd", hint: "Manage daemon (start/stop/restart/status/logs)", description: "Controls the background daemon:\n    start   → launches the daemon (indexes + watches for changes)\n    stop    → stops the running daemon\n    restart → stop + start (reloads workspace.json, indexes new repos)\n    status  → shows node/edge/file counts\n    logs    → prints .vexp/vexp.log" },
     { key: "6", label: "setup-llm", hint: "Configure local LLM compression (vexp-devmind)", description: "Install, update, or disable the optional local LLM (vexp-devmind).\n    Runs entirely on your machine (~3.5 GB download).\n    Enables smart prompt preprocessing and higher-quality memory compression." },
 ];
 // ── Sub-menu: Explore & Analyze ──
@@ -1015,6 +1047,11 @@ const MENU_SAVINGS = [
     { key: "1", label: "summary", hint: "View savings summary", description: "Shows total tokens saved, average saving %, and breakdown by tool.\n    Choose a period: 7 / 14 / 30 / 60 / 90 days." },
     { key: "2", label: "export", hint: "Export report to .vexp/token-savings-report.md", description: "Generates a markdown report with breakdown by tool and daily trend,\n    then saves it to .vexp/token-savings-report.md." },
 ];
+// ── Sub-menu: Repos & Workspace ──
+const MENU_REPOS = [
+    { key: "1", label: "list", hint: "Show repos connected to this workspace", description: "Lists the repositories of this multi-repo workspace\n    (.vexp/workspace.json): alias, path, primary marker." },
+    { key: "2", label: "add", hint: "Connect another repository to this workspace", description: "Adds a repository to .vexp/workspace.json and links it back via\n    .vexp/parent_workspace.json — same writes as the VS Code\n    \"vexp: Add Repository\" command. Restart the daemon to index it." },
+];
 // ── Sub-menu: License ──
 const MENU_LICENSE = [
     { key: "1", label: "status", hint: "Show current license plan and limits", description: "Displays your current plan (free / pro / team), node limits,\n    repo limits, and license expiry." },
@@ -1056,12 +1093,18 @@ async function printBanner() {
     // banner says "not running", but the Rust daemon-cmd status probes the
     // socket and reports "running". Using the socket here makes the banner
     // agree with status.
-    const ws = findConfiguredWorkspace();
-    if (!ws) {
+    const eff = findEffectiveWorkspace();
+    if (!eff) {
         console.log(chalk.dim("  ○ Daemon: no workspace configured here"));
         console.log(chalk.dim("    → type '1 > 3' to run full setup, or `vexp setup`"));
     }
     else {
+        // Connected secondary repo: every daemon interaction targets the parent
+        // workspace — say so up front, since the status below is the PARENT's.
+        if (eff.parent) {
+            console.log(chalk.cyan(`  ◆ Workspace: this repo is part of "${eff.parent.workspaceName}" — using the parent daemon (${shortPath(eff.root)})`));
+        }
+        const ws = eff.root;
         const socketAlive = await isSocketAlive(socketPathFor(ws));
         if (socketAlive) {
             // Display PID + uptime when we can read them; otherwise a plain "running".
@@ -1097,7 +1140,7 @@ async function printBanner() {
         }
         else if (installed) {
             console.log(chalk.yellow("  ○ LLM: installed but not active"));
-            console.log(chalk.dim("    → type '1 > 6 > start' to start it, or `vexp setup-llm --start`"));
+            console.log(chalk.dim("    → type '1 > 6 > start' to start it, or `vexp setup-llm --enable`"));
         }
         else {
             console.log(chalk.dim("  ○ LLM: not installed"));
@@ -1114,6 +1157,7 @@ function printMainMenu() {
     console.log(`   ${chalk.cyan.bold("2")}  ${chalk.green("Explore & Analyze".padEnd(20))} ${chalk.dim("Query context, skeletons, impact, flow")}`);
     console.log(`   ${chalk.cyan.bold("3")}  ${chalk.green("Token Savings".padEnd(20))} ${chalk.dim("View savings stats, export report")}`);
     console.log(`   ${chalk.cyan.bold("4")}  ${chalk.green("License".padEnd(20))} ${chalk.dim("View or activate your license")}`);
+    console.log(`   ${chalk.cyan.bold("5")}  ${chalk.green("Repos & Workspace".padEnd(20))} ${chalk.dim("List / connect workspace repositories")}`);
     console.log(`   ${chalk.cyan.bold("q")}  ${chalk.red("Exit".padEnd(20))} ${chalk.dim("Quit")}`);
     console.log("");
 }
@@ -1136,11 +1180,13 @@ async function interactiveMode() {
     // `vexp setup` still get a working state (daemon + MCP :7821 up, OS
     // autostart installed for the next reboot). All steps are idempotent so
     // running this alongside `vexp setup` never creates duplicates.
-    const workspaceRoot = findConfiguredWorkspace();
-    if (workspaceRoot) {
+    const eff = findEffectiveWorkspace();
+    if (eff) {
         try {
             const binaryPath = getBinaryPath();
-            await ensureBootstrap(workspaceRoot, binaryPath);
+            // Effective root: in a connected secondary repo this boots the PARENT
+            // daemon (which serves this repo too) instead of a conflicting child one.
+            await ensureBootstrap(eff.root, binaryPath);
         }
         catch { /* banner will reflect actual state */ }
     }
@@ -1155,6 +1201,7 @@ async function interactiveMode() {
         explore: chalk.cyan.bold("  vexp/explore> "),
         savings: chalk.cyan.bold("  vexp/savings> "),
         license: chalk.cyan.bold("  vexp/license> "),
+        repos: chalk.cyan.bold("  vexp/repos> "),
     };
     while (true) {
         const input = (await ask(rl, prompts[currentMenu])).trim().toLowerCase();
@@ -1190,8 +1237,13 @@ async function interactiveMode() {
                 printSubMenu("License", MENU_LICENSE);
                 continue;
             }
+            if (input === "5" || input === "repos") {
+                currentMenu = "repos";
+                printSubMenu("Repos & Workspace", MENU_REPOS);
+                continue;
+            }
             // Allow direct command names from any sub-menu
-            const allItems = [...MENU_CONFIG, ...MENU_EXPLORE, ...MENU_SAVINGS, ...MENU_LICENSE];
+            const allItems = [...MENU_CONFIG, ...MENU_EXPLORE, ...MENU_SAVINGS, ...MENU_LICENSE, ...MENU_REPOS];
             const direct = allItems.find((m) => m.label === input);
             if (direct) {
                 await executeCommand(direct.label, rl);
@@ -1199,12 +1251,12 @@ async function interactiveMode() {
                 printMainMenu();
                 continue;
             }
-            console.log(chalk.dim("  Choose 1-4 or type a command name. 'q' to exit.\n"));
+            console.log(chalk.dim("  Choose 1-5 or type a command name. 'q' to exit.\n"));
             continue;
         }
         // ── Sub-menus ──
-        const menuMap = { config: MENU_CONFIG, explore: MENU_EXPLORE, savings: MENU_SAVINGS, license: MENU_LICENSE };
-        const titles = { config: "Setup & Config", explore: "Explore & Analyze", savings: "Token Savings", license: "License" };
+        const menuMap = { config: MENU_CONFIG, explore: MENU_EXPLORE, savings: MENU_SAVINGS, license: MENU_LICENSE, repos: MENU_REPOS };
+        const titles = { config: "Setup & Config", explore: "Explore & Analyze", savings: "Token Savings", license: "License", repos: "Repos & Workspace" };
         if (input === "b" || input === "back") {
             currentMenu = "main";
             printMainMenu();
@@ -1241,7 +1293,27 @@ async function executeCommand(label, rl) {
             }
             case "index": {
                 const binaryPath = ensureBinary();
-                runBinary(binaryPath, ["index"]);
+                // Workspace-aware: re-index every connected repo, not just the cwd
+                // one. From a connected child this targets the parent workspace, so
+                // the result matches what the daemon serves.
+                const eff = findEffectiveWorkspace();
+                const repos = eff ? listWorkspaceRepos(eff.root) : [];
+                if (!eff || repos.length === 0) {
+                    runBinary(binaryPath, ["index"]);
+                    break;
+                }
+                if (eff.parent) {
+                    console.log(chalk.cyan(`    This repo is part of workspace "${eff.parent.workspaceName}" — indexing all its repos`));
+                }
+                console.log(chalk.dim(`    Indexing ${repos.length} workspace repo(s)…\n`));
+                for (const r of repos) {
+                    if (!r.exists) {
+                        console.log(chalk.yellow(`    ⚠ Skipping "${r.alias}" — directory not found: ${shortPath(r.resolvedPath)}`));
+                        continue;
+                    }
+                    console.log(chalk.bold(`    ● ${r.alias}`));
+                    runBinary(binaryPath, ["index", r.resolvedPath]);
+                }
                 break;
             }
             case "setup": {
@@ -1255,15 +1327,23 @@ async function executeCommand(label, rl) {
             case "daemon-cmd": {
                 // Sticky sub-sub-menu: stay here until user types 'b' (back).
                 const binaryPath = ensureBinary();
-                const valid = new Set(["start", "stop", "status", "logs"]);
+                const valid = new Set(["start", "stop", "restart", "status", "logs"]);
+                // Inside a connected secondary repo every action targets the parent
+                // workspace daemon — running one here would fight over the same DBs.
+                const eff = findEffectiveWorkspace();
+                if (eff?.parent) {
+                    console.log(chalk.cyan(`    This repo is part of workspace "${eff.parent.workspaceName}" — daemon commands target the parent (${shortPath(eff.root)})`));
+                }
+                const daemonCwd = eff?.parent ? { cwd: eff.root } : undefined;
                 const printDaemonMenu = () => {
                     console.log("");
                     console.log(chalk.cyan("    ── Daemon ──"));
-                    console.log(`      ${chalk.bold("start")}   ${chalk.dim("Launch the daemon for this workspace")}`);
-                    console.log(`      ${chalk.bold("stop")}    ${chalk.dim("Stop the running daemon")}`);
-                    console.log(`      ${chalk.bold("status")}  ${chalk.dim("Show node/edge/file counts and uptime")}`);
-                    console.log(`      ${chalk.bold("logs")}    ${chalk.dim("Tail .vexp/vexp.log")}`);
-                    console.log(`      ${chalk.dim("b")}       ${chalk.dim("Back to Setup & Config")}`);
+                    console.log(`      ${chalk.bold("start")}    ${chalk.dim("Launch the daemon for this workspace")}`);
+                    console.log(`      ${chalk.bold("stop")}     ${chalk.dim("Stop the running daemon")}`);
+                    console.log(`      ${chalk.bold("restart")}  ${chalk.dim("Stop + start (reloads workspace.json, indexes new repos)")}`);
+                    console.log(`      ${chalk.bold("status")}   ${chalk.dim("Show node/edge/file counts and uptime")}`);
+                    console.log(`      ${chalk.bold("logs")}     ${chalk.dim("Tail .vexp/vexp.log")}`);
+                    console.log(`      ${chalk.dim("b")}        ${chalk.dim("Back to Setup & Config")}`);
                     console.log("");
                 };
                 printDaemonMenu();
@@ -1274,11 +1354,11 @@ async function executeCommand(label, rl) {
                     if (action === "b" || action === "back")
                         break;
                     if (valid.has(action)) {
-                        runBinary(binaryPath, ["daemon-cmd", action]);
+                        runBinary(binaryPath, ["daemon-cmd", action], daemonCwd);
                         printDaemonMenu();
                         continue;
                     }
-                    console.log(chalk.dim("    Unknown action. Use start, stop, status, logs, or 'b' to go back."));
+                    console.log(chalk.dim("    Unknown action. Use start, stop, restart, status, logs, or 'b' to go back."));
                 }
                 break;
             }
@@ -1399,6 +1479,79 @@ async function executeCommand(label, rl) {
                 }
                 break;
             }
+            // ── Repos & Workspace commands ──
+            case "list": {
+                const eff = findEffectiveWorkspace();
+                if (!eff) {
+                    console.log(chalk.yellow("    No configured workspace here — run setup first (1 > 3, or `vexp setup`)."));
+                    break;
+                }
+                if (eff.parent) {
+                    console.log(chalk.cyan(`    This repo is part of workspace "${eff.parent.workspaceName}" — showing the repos of ${shortPath(eff.root)}`));
+                }
+                const repos = listWorkspaceRepos(eff.root);
+                if (repos.length === 0) {
+                    console.log(chalk.dim("    Single-repo workspace (no .vexp/workspace.json yet)."));
+                    console.log(chalk.dim("    Use 'add' to connect another repository."));
+                    break;
+                }
+                console.log("");
+                for (const r of repos) {
+                    const marker = r.isPrimary ? chalk.cyan(" (primary)") : "";
+                    const missing = r.exists ? "" : chalk.red(" [missing]");
+                    console.log(`    ${chalk.green("●")} ${chalk.bold(r.alias.padEnd(20))} ${chalk.dim(shortPath(r.resolvedPath))}${marker}${missing}`);
+                }
+                console.log(chalk.dim(`\n    ${repos.length} repo(s) in workspace "${path.basename(eff.root)}"`));
+                break;
+            }
+            case "add": {
+                const eff = findEffectiveWorkspace();
+                if (!eff) {
+                    console.log(chalk.yellow("    No configured workspace here — run setup first (1 > 3, or `vexp setup`)."));
+                    break;
+                }
+                if (eff.parent) {
+                    console.log(chalk.cyan(`    This repo is part of workspace "${eff.parent.workspaceName}" — the repository will be added to ${shortPath(eff.root)}`));
+                }
+                const repoPath = (await ask(rl, chalk.cyan("    Path of the repository to connect: "))).trim();
+                if (!repoPath)
+                    break;
+                const limits = readLicenseLimits();
+                const result = addRepoToWorkspace(eff.root, repoPath, limits.maxRepos);
+                if (result.status === "invalid") {
+                    console.log(chalk.red(`    ✗ ${result.reason}`));
+                    break;
+                }
+                if (result.status === "limit") {
+                    console.log(chalk.yellow(`    Your ${limits.plan} plan supports up to ${result.maxRepos} repo${result.maxRepos === 1 ? "" : "s"}.`));
+                    console.log(chalk.dim("    Upgrade at https://vexp.dev/#pricing to add more repositories."));
+                    break;
+                }
+                if (result.status === "exists") {
+                    console.log(chalk.dim(`    "${result.alias}" is already part of this workspace.`));
+                    break;
+                }
+                console.log(chalk.green(`    ✓ Added "${result.alias}" to workspace "${path.basename(eff.root)}"`));
+                // A live 2.2.3+ daemon hot-reloads workspace.json (2s poll): the new
+                // repo is indexed and watched automatically, no restart needed. Only
+                // when the daemon is down do we offer to start it.
+                if (await isSocketAlive(socketPathFor(eff.root))) {
+                    console.log(chalk.dim(`    The running daemon will detect the change and index "${result.alias}" automatically within seconds.`));
+                }
+                else {
+                    const yn = (await ask(rl, chalk.cyan(`    Start the daemon now to index "${result.alias}"? [Y/n]: `))).trim().toLowerCase();
+                    if (yn === "" || yn === "y" || yn === "yes") {
+                        const binaryPath = ensureBinary();
+                        console.log(chalk.dim("    Starting vexp daemon…\n"));
+                        runBinary(binaryPath, ["daemon-cmd", "start"], { cwd: eff.root });
+                        console.log(chalk.green(`    ✓ Now indexing "${result.alias}".`));
+                    }
+                    else {
+                        console.log(chalk.dim(`    Run 'vexp daemon-cmd start' in ${shortPath(eff.root)} later to index it.`));
+                    }
+                }
+                break;
+            }
             // ── License commands ──
             case "status": {
                 const limits = readLicenseLimits();

package/dist/hook-template.js

@@ -58,6 +58,12 @@ esac
  * Error aborts the tool call. Written to `.opencode/plugins/vexp-guard.js` by
  * `vexp setup-agents` (opencode auto-loads that directory at startup).
  *
+ * The SAME file is installed for Kilo Code at `.kilo/plugins/vexp-guard.js`
+ * (installKiloPlugin), because Kilo v7 is opencode vendored — its plugin loader
+ * lives at packages/opencode/src/config/plugin.ts inside Kilo-Org/kilocode, so
+ * the hook name, the `input.tool` ids and the grep/glob arg schemas are the same
+ * code and not merely a compatible API.
+ *
  * 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
@@ -66,11 +72,14 @@ esac
  * 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
+ * test in packages/vexp-cli/test/guard-lockstep.test.ts — which is where that
+ * guarantee actually lives; this comment used to point at hook-template.test.ts,
+ * which only ever compared the CLI constant with itself). 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'; it is rewritten
-// on every setup, and a modified copy is saved to vexp-guard.js.vexp-bak first).
+export const VEXP_OPENCODE_GUARD = `// vexp-guard - opencode / Kilo Code plugin (generated by 'vexp setup-agents'; it is
+// rewritten on every setup, and a modified copy is saved to vexp-guard.js.vexp-bak
+// first). Kilo v7 vendors opencode, so one plugin serves both unchanged.
 //
 // Blocks opencode's native grep/glob ONLY where vexp has a better answer: indexed
 // source inside the workspace, while the daemon is healthy. Two deliberate limits:
@@ -192,3 +201,176 @@ export const VexpGuard = async ({ directory, worktree }) => {
   };
 };
 `;
+/**
+ * Cursor `preToolUse` hook. Same policy as the Claude Code hook and the
+ * opencode/Kilo plugin — block text search while the vexp daemon is healthy,
+ * never touch the shell, never block a target vexp did not index — expressed in
+ * the third dialect we now have to speak.
+ *
+ * Written in NODE, not bash, and that is deliberate. The Claude Code guard is a
+ * bash script and it silently enforced NOTHING on Windows for several releases
+ * (`[ -S "$SOCK" ]` can never match a named pipe), which is the single most
+ * expensive bug this file has produced. Cursor documents no PowerShell variant
+ * of `command` and does not say which shell runs it on Windows, so a bash guard
+ * here would be that bug again by construction. Anyone who installed vexp has
+ * node on PATH; a node script is the one interpreter we can count on everywhere.
+ *
+ * Denial is emitted on BOTH documented channels — the stdout verdict object and
+ * exit code 2 — because Cursor's docs describe both and we cannot test which one
+ * this build actually honours. Belt and braces on a schema we are trusting on
+ * documentation alone.
+ *
+ * Fails OPEN in every uncertain case: daemon down, unparseable input, an unknown
+ * payload shape. An over-eager guard strands the agent with no way to look at
+ * anything; an under-eager one costs tokens. Those are not symmetric.
+ *
+ * ASCII-only, no backticks and no ${...}: it is embedded verbatim in a TS
+ * template literal in two packages (lockstep test in test/guard-lockstep.test.ts).
+ */
+export const VEXP_CURSOR_GUARD = `#!/usr/bin/env node
+// vexp-guard - Cursor preToolUse hook (generated by 'vexp setup-agents'; rewritten
+// on every setup, and a modified copy is saved to vexp-guard.js.vexp-bak first).
+//
+// Blocks Cursor's Grep tool ONLY where vexp has a better answer: indexed source
+// inside the workspace, while the daemon is healthy. Never blocks Shell - that
+// valve is what keeps the agent able to reach logs, build output and anything
+// outside the repo, and blocking it teaches evasion instead of redirection.
+//
+// NOTE: Cursor's native semantic codebase search is NOT exposed to hooks, so it
+// cannot be redirected. This guard covers text search only.
+const fs = require("node:fs");
+const path = require("node:path");
+
+function findVexpDir(start) {
+  let dir = start;
+  for (;;) {
+    if (fs.existsSync(path.join(dir, ".vexp"))) return path.join(dir, ".vexp");
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function pidAlive(pidFile) {
+  let pid = 0;
+  try { pid = parseInt(fs.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 requires a live socket AND a live pid: healthy + socket both linger
+// after a kill -9, so the pid check is what makes fail-open actually work.
+// Windows has no socket file, so the daemon drops .vexp/daemon.pipe instead.
+function daemonHealthy(vexpDir) {
+  if (!vexpDir || !fs.existsSync(path.join(vexpDir, "healthy"))) return false;
+  if (process.platform === "win32") return fs.existsSync(path.join(vexpDir, "daemon.pipe"));
+  return fs.existsSync(path.join(vexpDir, "daemon.sock")) && pidAlive(path.join(vexpDir, "daemon.pid"));
+}
+
+const NON_INDEXED_DIRS = [
+  "node_modules", "dist", "build", "out", "coverage", "target", "vendor",
+  ".vite", ".next", ".nuxt", ".output", ".turbo", ".cache", ".git", ".vexp"
+];
+const NON_INDEXED_HINTS = [".log", ".lock", "-lock.", ".map", ".min.js"];
+
+// Is this search target inside what vexp indexed? Only then is "call
+// run_pipeline instead" real advice rather than a dead end. Anything that cannot
+// be resolved confidently returns false (allow).
+function isIndexedTarget(root, target) {
+  if (!target) return true; // no path given: a whole-workspace search is vexp's job
+  const s = String(target);
+  const low = s.toLowerCase();
+  for (const h of NON_INDEXED_HINTS) if (low.indexOf(h) !== -1) return false;
+  let rel;
+  try {
+    rel = path.relative(root, path.isAbsolute(s) ? s : path.join(root, s));
+  } catch (e) {
+    return false;
+  }
+  if (rel === "..") return false;
+  if (rel.indexOf(".." + path.sep) === 0) return false; // escapes the workspace
+  if (path.isAbsolute(rel)) return false; // different root or drive
+  const segs = rel.split(path.sep);
+  for (const g of segs) if (NON_INDEXED_DIRS.indexOf(g) !== -1) return false;
+  return true;
+}
+
+function allow() {
+  process.stdout.write(JSON.stringify({ permission: "allow" }));
+  process.exit(0);
+}
+
+function deny(toolName) {
+  const reason =
+    "vexp daemon is running. AGENT INSTRUCTION: call run_pipeline instead of " +
+    toolName + " - it returns pre-indexed, graph-ranked context in one call." +
+    " This is policy, not a transient failure: do NOT work around it with shell" +
+    " search or by writing a script.";
+  // Both documented channels: the verdict object AND exit 2.
+  process.stdout.write(JSON.stringify({
+    permission: "deny",
+    agent_message: reason,
+    user_message: "vexp blocked a text search; the agent was told to use run_pipeline."
+  }));
+  process.stderr.write(reason);
+  process.exit(2);
+}
+
+// Cursor documents tool_input for Shell only; the payload shape for a Grep call
+// appears NOWHERE in its docs. Rather than guess key names - a guess that fires,
+// reads undefined and then blocks everything or nothing - we do not read keys at
+// all. We scan the VALUES of tool_input for anything path-shaped. That is immune
+// to whatever the keys turn out to be called, and to them being renamed later.
+//
+// The search pattern itself is one of those values and may look like a path. It
+// can only ever push us toward ALLOW (a pattern mentioning node_modules reads as
+// a non-indexed target), never toward a wrongful block - which is the direction
+// we want to be wrong in.
+function candidateTargets(toolInput) {
+  if (!toolInput) return [];
+  // MCP hooks receive tool_input as a JSON *string*, so the type is not uniform.
+  let obj = toolInput;
+  if (typeof obj === "string") {
+    try { obj = JSON.parse(obj); } catch (e) { return []; }
+  }
+  if (typeof obj !== "object") return [];
+  // EVERY string value, with no "does this look like a path" pre-filter. An
+  // earlier version required a separator or a dot and therefore missed bare
+  // directory names - "dist", "build", "node_modules" - which are exactly the
+  // targets the carve-out exists to protect. Handing the search pattern itself
+  // to isIndexedTarget is harmless: a pattern that reads as non-indexed only
+  // ever produces an ALLOW, and a pattern that reads as indexed changes nothing.
+  const out = [];
+  for (const v of Object.values(obj)) {
+    if (typeof v === "string" && v) out.push(v);
+  }
+  return out;
+}
+
+function main(input) {
+  const toolName = input && input.tool_name;
+  // Grep only. Shell is never blocked - it is the valve for everything vexp
+  // cannot index - and Read is never blocked because an agent must read to edit.
+  if (toolName !== "Grep") return allow();
+
+  const roots = (input && input.workspace_roots) || [];
+  const start = roots[0] || (input && input.cwd) || process.cwd();
+  const vexpDir = findVexpDir(start);
+  if (!daemonHealthy(vexpDir)) return allow(); // no live index -> allow
+  const root = path.dirname(vexpDir);
+
+  for (const t of candidateTargets(input.tool_input)) {
+    if (!isIndexedTarget(root, t)) return allow(); // vexp has no answer here
+  }
+  deny(toolName);
+}
+
+let raw = "";
+process.stdin.on("data", (c) => { raw += c; });
+process.stdin.on("end", () => {
+  let input;
+  try { input = JSON.parse(raw); } catch (e) { return allow(); }
+  try { main(input); } catch (e) { allow(); } // any surprise -> fail open
+});
+`;

package/dist/workspace-repos.js

@@ -0,0 +1,166 @@
+import * as path from "path";
+import * as fs from "fs";
+import * as os from "os";
+/** Expand a leading `~` — readline input arrives unexpanded, unlike a shell arg. */
+export function expandHome(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\")) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+/**
+ * Resolve a `repos[].path` entry like vexp-core's `resolve_repo_path`:
+ * absolute paths are preserved, relative paths resolve against the workspace
+ * ROOT. Configs written before 2.2.1 stored paths relative to `.vexp/`, so
+ * when the root-relative answer is not a directory we fall back to the legacy
+ * base — same order as the Rust resolver, so list/add agree with the daemon.
+ */
+export function resolveRepoEntryPath(workspaceRoot, raw) {
+    if (path.isAbsolute(raw))
+        return path.normalize(raw);
+    const fromRoot = path.resolve(workspaceRoot, raw);
+    if (fs.existsSync(fromRoot))
+        return fromRoot;
+    const fromLegacy = path.resolve(workspaceRoot, ".vexp", raw);
+    if (fs.existsSync(fromLegacy))
+        return fromLegacy;
+    return fromRoot;
+}
+function readWorkspaceConfig(configPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        if (!parsed || !Array.isArray(parsed.repos))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * If `childRoot` is a secondary repo of a multi-repo workspace, return the
+ * parent workspace info. The link is `.vexp/parent_workspace.json` (written on
+ * add, both by the VS Code plugin and by `addRepoToWorkspace` below).
+ *
+ * Returns null — i.e. "treat this repo as standalone" — unless the parent
+ * config still exists AND still lists this repo: a stale parent_workspace.json
+ * left behind after the repo was disconnected must not hijack the CLI.
+ */
+export function resolveParentWorkspace(childRoot) {
+    let configPath;
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(childRoot, ".vexp", "parent_workspace.json"), "utf-8"));
+        if (typeof raw?.workspace_config !== "string")
+            return null;
+        configPath = raw.workspace_config;
+    }
+    catch {
+        return null;
+    }
+    if (!fs.existsSync(configPath))
+        return null;
+    // workspace.json lives in <parentRoot>/.vexp/
+    const parentRoot = path.dirname(path.dirname(configPath));
+    if (path.resolve(parentRoot) === path.resolve(childRoot))
+        return null;
+    const config = readWorkspaceConfig(configPath);
+    if (!config)
+        return null;
+    const childResolved = path.resolve(childRoot);
+    const listed = config.repos.some((r) => {
+        if (typeof r?.path !== "string")
+            return false;
+        return path.resolve(resolveRepoEntryPath(parentRoot, r.path)) === childResolved;
+    });
+    if (!listed)
+        return null;
+    return {
+        parentRoot,
+        workspaceName: config.name ?? path.basename(parentRoot),
+        configPath,
+    };
+}
+/**
+ * Repos connected to the workspace at `workspaceRoot`. Empty array when there
+ * is no workspace.json (single-repo workspace).
+ */
+export function listWorkspaceRepos(workspaceRoot) {
+    const configPath = path.join(workspaceRoot, ".vexp", "workspace.json");
+    const config = readWorkspaceConfig(configPath);
+    if (!config)
+        return [];
+    const rootResolved = path.resolve(workspaceRoot);
+    return config.repos
+        .filter((r) => typeof r?.path === "string" && typeof r?.alias === "string")
+        .map((r) => {
+        const resolvedPath = resolveRepoEntryPath(workspaceRoot, r.path);
+        return {
+            alias: r.alias,
+            rawPath: r.path,
+            resolvedPath,
+            isPrimary: path.resolve(resolvedPath) === rootResolved,
+            exists: fs.existsSync(resolvedPath),
+        };
+    });
+}
+/**
+ * Connect `newRepoPath` to the workspace at `workspaceRoot` — the exact write
+ * sequence of the VS Code `vexp.setupMultiRepo` command:
+ *   1. plan-limit guard BEFORE writing anything (maxRepos, 0 = unlimited)
+ *   2. read-or-create workspace.json (primary entry is `"."` — the 2.2.1+
+ *      root-relative convention)
+ *   3. append `{ alias, path: <absolute> }` unless already present
+ *   4. write `.vexp/parent_workspace.json` in the child so opening the child
+ *      resolves back to this workspace
+ *
+ * Indexing is NOT triggered here — the caller decides whether to restart the
+ * daemon (mirrors the plugin's "Restart / Later" prompt).
+ */
+export function addRepoToWorkspace(workspaceRoot, newRepoPath, maxRepos) {
+    const resolved = path.resolve(expandHome(newRepoPath.trim()));
+    let stat;
+    try {
+        stat = fs.statSync(resolved);
+    }
+    catch {
+        return { status: "invalid", reason: `Directory not found: ${resolved}` };
+    }
+    if (!stat.isDirectory()) {
+        return { status: "invalid", reason: `Not a directory: ${resolved}` };
+    }
+    if (path.resolve(workspaceRoot) === resolved) {
+        return { status: "invalid", reason: "That is the workspace root itself — it is already the primary repo." };
+    }
+    const configPath = path.join(workspaceRoot, ".vexp", "workspace.json");
+    const alias = path.basename(resolved);
+    // Plan-limit guard: same semantics as the plugin — count existing entries,
+    // block only genuinely-new repos, never after a partial write.
+    let config = readWorkspaceConfig(configPath);
+    const currentCount = config ? config.repos.length : 1; // primary always exists
+    const alreadyExists = config?.repos.some((r) => r.alias === alias ||
+        r.path === resolved ||
+        path.resolve(resolveRepoEntryPath(workspaceRoot, r.path)) === resolved) ?? false;
+    if (alreadyExists) {
+        return { status: "exists", alias };
+    }
+    if (maxRepos > 0 && currentCount >= maxRepos) {
+        return { status: "limit", maxRepos, current: currentCount };
+    }
+    if (!config) {
+        config = {
+            name: path.basename(workspaceRoot),
+            repos: [{ alias: path.basename(workspaceRoot), path: "." }],
+        };
+    }
+    config.repos.push({ alias, path: resolved });
+    fs.mkdirSync(path.join(workspaceRoot, ".vexp"), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    // Bidirectional link in the child, so `vexp` run there targets this
+    // workspace's daemon instead of spawning a conflicting one.
+    const childVexpDir = path.join(resolved, ".vexp");
+    fs.mkdirSync(childVexpDir, { recursive: true });
+    fs.writeFileSync(path.join(childVexpDir, "parent_workspace.json"), JSON.stringify({ workspace_config: configPath }, null, 2));
+    return { status: "added", alias, configPath };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexp-cli",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "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.2.2",
-    "@vexp/core-linux-arm64": "2.2.2",
-    "@vexp/core-darwin-x64": "2.2.2",
-    "@vexp/core-darwin-arm64": "2.2.2",
-    "@vexp/core-win32-x64": "2.2.2"
+    "@vexp/core-linux-x64": "2.2.4",
+    "@vexp/core-linux-arm64": "2.2.4",
+    "@vexp/core-darwin-x64": "2.2.4",
+    "@vexp/core-darwin-arm64": "2.2.4",
+    "@vexp/core-win32-x64": "2.2.4"
   }
 }