vexp-cli 3.0.1 → 3.1.0

package/dist/agent-config.js

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

package/dist/cli.js

@@ -42,6 +42,11 @@ if (isTraceEnabled()) {
 const AUTOSTART_SKIP = new Set([
     "setup", "daemon-cmd", "activate", "deactivate", "license", "version",
     "serve", "autostart", "use", "doctor",
+    // Lifecycle commands: `vexp daemons` LISTS daemons and `vexp stop` ENDS
+    // one — spawning a daemon for the current directory first made `stop`
+    // followed by `daemons` bring the stopped daemon straight back
+    // (3.1 e2e, 2026-08).
+    "daemons", "stop",
 ]);
 program.hook("preAction", async (_thisCmd, actionCmd) => {
     // One-shot config migration for the multi-session fix — de-pins a legacy
@@ -456,7 +461,7 @@ program
 });
 program
     .command("search <query>")
-    .description("Exhaustive index search: every matching node (code and docs), no top-K. Built for rename sweeps and zero-reference audits")
+    .description("Exhaustive index search: every symbol matching the query (code and docs) plus every line in indexed symbol bodies that references it, no top-K. Built for rename sweeps and zero-reference audits")
     .option("--substring", "Substring match (LIKE) instead of token search — partial identifiers, punctuation")
     .option("--files-only", "Print only the distinct file paths")
     .option("--json", "Machine-readable JSON with a stable shape")
@@ -828,7 +833,15 @@ program
     // the daemon already cold-starts on the first `vexp` invocation, so this is
     // purely a convenience for post-reboot warm-up. Skip entirely when the user
     // opted out via env or when stdin is not a TTY (non-interactive install).
-    if (process.env.VEXP_NO_AUTOSTART_INSTALL === "1") {
+    //
+    // A dry run must not reach this step at all: the prompt was asked even
+    // under --dry-run and answering Yes rewrote the Startup-folder .vbs while
+    // the summary still claimed nothing was written (field report, Peiyuan,
+    // 3.0.1 on Windows). Persistence is a write like any other.
+    if (opts.dryRun) {
+        console.log(chalk.dim("  --dry-run: would ask about login autostart (writes a Startup entry only if you accept)."));
+    }
+    else if (process.env.VEXP_NO_AUTOSTART_INSTALL === "1") {
         // Explicit opt-out — do nothing.
     }
     else if (!process.stdin.isTTY) {
@@ -1108,6 +1121,9 @@ program
     console.log(`  Max nodes: ${limits.maxNodes === 0 ? "unlimited" : limits.maxNodes.toLocaleString()}`);
     console.log(`  Max repos: ${limits.maxRepos === 0 ? "unlimited" : limits.maxRepos}`);
     console.log(`  All tools: ${limits.allTools ? "yes" : "no (7/10)"}`);
+    if (limits.allTools) {
+        console.log(`             (the MCP tool list shows 4 by default to keep the catalog small; every tool stays callable — VEXP_ALL_TOOLS=1 lists them all)`);
+    }
     if (limits.renewsAt) {
         console.log(ltd
             ? `  Renewal:   none — lifetime licence (local token auto-refreshes, ` +
@@ -1749,6 +1765,9 @@ async function executeCommand(label, rl, outCtl) {
                 console.log(`    Max nodes: ${limits.maxNodes === 0 ? "unlimited" : limits.maxNodes.toLocaleString()}`);
                 console.log(`    Max repos: ${limits.maxRepos === 0 ? "unlimited" : limits.maxRepos}`);
                 console.log(`    All tools: ${limits.allTools ? "yes" : "no (7/10)"}`);
+                if (limits.allTools) {
+                    console.log(`               (the MCP tool list shows 4 by default to keep the catalog small; every tool stays callable — VEXP_ALL_TOOLS=1 lists them all)`);
+                }
                 if (limits.renewsAt) {
                     console.log(ltd
                         ? `    Renewal:   none — lifetime licence (token auto-refreshes, valid to ${limits.renewsAt.toLocaleDateString()})`

package/dist/doctor.js

@@ -5,6 +5,7 @@ import * as net from "net";
 import { spawnSync } from "child_process";
 import chalk from "chalk";
 import { socketPathFor } from "./socket-path.js";
+import { parseJsonc } from "./agent-config.js";
 // `vexp doctor` — audit the vexp MCP/daemon state WITHOUT connecting to a daemon.
 // Surfaces the failure modes behind the Codex drift report: stale daemons.json
 // entries, wrong-workspace resolution, mixed Codex transport (url+stdio),
@@ -191,6 +192,80 @@ export function gitHooksVerdict(hooksPath, repoRoot, installedCount) {
             `        the hooks only make that immediate — if you want them and a tool manages this directory (moon, husky, lefthook), add 'vexp index --finalize || true' through ITS config, not the generated file.`,
     };
 }
+/**
+ * The size-skip verdict, from `.vexp/coverage.json` (3.1 shape), as data.
+ *
+ * Files over `max_file_size_kb` are left out of the index by the walk. Until
+ * 3.1 the only trace was an INFO line in the daemon log: doctor, the
+ * `index_status` tool and coverage.json all reported a healthy index while a
+ * tier-4 user was missing five hand-written Dart files — 21% of the bytes of
+ * his lib/ — from every impact, search and pipeline answer (field report,
+ * 2026-08). Raising the cap only moved the cliff, so the cliff is reported
+ * wherever it stands. Null when nothing was skipped for size, or when the
+ * file predates 3.1 and has no skip keys.
+ */
+export function coverageVerdict(cov) {
+    if (!cov || typeof cov !== "object")
+        return null;
+    const c = cov;
+    const oversized = Number(c.skipped_oversized) || 0;
+    if (oversized === 0)
+        return null;
+    const cap = Number(c.max_file_size_kb) || 0;
+    const files = Array.isArray(c.skipped_files) ? c.skipped_files : [];
+    const examples = files
+        .filter((f) => f.reason === "oversized")
+        .slice(0, 5)
+        .map((f) => `${f.path} (${Number(f.size_kb) || 0} KB)`);
+    const more = oversized - examples.length;
+    return {
+        level: WARN,
+        message: `${oversized} file(s) over max_file_size_kb = ${cap} are NOT indexed — their symbols and callers are invisible to impact, search and run_pipeline:\n` +
+            examples.map((e) => `        - ${e}`).join("\n") +
+            (more > 0 ? `\n        … +${more} more (full list: .vexp/coverage.json)` : "") +
+            `\n        raise max_file_size_kb in .vexp/vexp.toml (0 = no cap) to include them, or exclude them on purpose with exclude_patterns.`,
+    };
+}
+/**
+ * The `.vscode/mcp.json` verdict for GitHub Copilot, as data.
+ *
+ * A Copilot user who "set up the vexp agent" and sees neither a vexp server in
+ * VS Code nor vexp tools in chat has, in our experience, one of three things:
+ * the file is not where VS Code looks (the folder open in VS Code is not the
+ * one that was set up), the server entry cannot start (a bare `node` that the
+ * GUI-launched editor cannot find on its PATH, or a bundle path an extension
+ * upgrade removed), or Chat is not in Agent mode — the only mode that offers
+ * MCP tools. doctor can prove the first two; it can only say the third.
+ */
+export function vsCodeMcpVerdict(cfg, wsRoot, exists = (p) => fs.existsSync(p)) {
+    if (!cfg || typeof cfg !== "object")
+        return { level: WARN, message: ".vscode/mcp.json is present but not valid JSON — VS Code will ignore every server in it; fix the syntax and re-run 'vexp setup'" };
+    const servers = cfg.servers;
+    const vexp = servers?.vexp;
+    if (!vexp)
+        return { level: WARN, message: ".vscode/mcp.json has no 'vexp' server — run: vexp setup --agents \"GitHub Copilot\"" };
+    const command = typeof vexp.command === "string" ? vexp.command : "";
+    const args = Array.isArray(vexp.args) ? vexp.args.filter((a) => typeof a === "string") : [];
+    const script = args.find((a) => /\.[cm]?js$/.test(a));
+    if (!command)
+        return { level: WARN, message: ".vscode/mcp.json vexp server has no 'command' — re-run 'vexp setup'" };
+    if (!/[\\/]/.test(command)) {
+        return {
+            level: WARN,
+            message: `.vscode/mcp.json starts the vexp server with a bare '${command}' — resolved through the editor's PATH, which a VS Code launched from the Dock/Start menu usually lacks (symptom: 'spawn ${command} ENOENT' in Output › MCP: vexp, no vexp tools in chat).\n` +
+                `        re-run 'vexp setup' — 3.1 pins the absolute node path.`,
+        };
+    }
+    if (!exists(command))
+        return { level: WARN, message: `.vscode/mcp.json vexp command does not exist: ${command} — re-run 'vexp setup' to repin it` };
+    if (script && !exists(script))
+        return { level: WARN, message: `.vscode/mcp.json vexp server bundle is missing: ${script} (an editor upgrade removed the old extension folder?) — re-run 'vexp setup'` };
+    const pinned = typeof vexp.env?.VEXP_WORKSPACE === "string" ? vexp.env.VEXP_WORKSPACE : undefined;
+    if (pinned && path.resolve(pinned).toLowerCase() !== path.resolve(wsRoot).toLowerCase()) {
+        return { level: WARN, message: `.vscode/mcp.json vexp server is pinned to ${pinned}, but this workspace is ${wsRoot} — re-run 'vexp setup' here` };
+    }
+    return { level: OK, message: `.vscode/mcp.json vexp server: ${command} ${script ?? args.join(" ")}` };
+}
 export async function runDoctor() {
     const home = vexpHome();
     let warns = 0;
@@ -310,6 +385,16 @@ export async function runDoctor() {
             }
         }
     }
+    // 3.1 — coverage gaps only the daemon log used to witness. Read from disk,
+    // not from the daemon: the index that skipped the files may have been
+    // built by a daemon that is no longer running.
+    try {
+        const cov = JSON.parse(fs.readFileSync(path.join(ws.root, ".vexp", "coverage.json"), "utf-8"));
+        const v = coverageVerdict(cov);
+        if (v)
+            line(v.level, v.message);
+    }
+    catch { /* no coverage.json: never indexed here, or an index older than 2.7 */ }
     // 2) Daemon registry (~/.vexp/daemons.json) — stale entries are a drift source.
     console.log(chalk.bold("\nDaemon registry (~/.vexp/daemons.json)"));
     const regPath = path.join(home, ".vexp", "daemons.json");
@@ -434,6 +519,27 @@ export async function runDoctor() {
     catch {
         line(OK, "no ~/.claude.json");
     }
+    // 5a) GitHub Copilot — VS Code reads MCP servers from <folder>/.vscode/mcp.json.
+    console.log(chalk.bold("\nGitHub Copilot / VS Code (.vscode/mcp.json)"));
+    {
+        const mcpPath = path.join(ws.root, ".vscode", "mcp.json");
+        if (!fs.existsSync(mcpPath)) {
+            line(OK, "no .vscode/mcp.json (Copilot MCP not configured in this folder — 'vexp setup --agents \"GitHub Copilot\"' writes it)");
+        }
+        else {
+            let cfg = null;
+            try {
+                cfg = parseJsonc(fs.readFileSync(mcpPath, "utf-8"));
+            }
+            catch {
+                cfg = null;
+            }
+            const v = vsCodeMcpVerdict(cfg, ws.root);
+            line(v.level, v.message);
+            console.log(chalk.dim("        VS Code shows it under Extensions → MCP SERVERS - INSTALLED; vexp tools appear only in Copilot Chat AGENT mode (tools picker → 'MCP Server: vexp')."));
+            console.log(chalk.dim("        server log: Command Palette → 'MCP: List Servers' → vexp → Show Output (channel 'MCP: vexp'); daemon log: .vexp/daemon.log"));
+        }
+    }
     // 5b) Claude Code guard hook — EXECUTE it the way Claude Code would, don't
     // just check presence. A shell-form command that word-splits on a project
     // path containing a space fails non-blocking on every call: the guard never

package/dist/license.js

@@ -206,10 +206,10 @@ export async function tryOnlineRefresh(longJwt) {
             // Only save if the freshToken itself verifies locally
             if (verifyAndDecode(data.freshToken)) {
                 saveFreshToken(data.freshToken);
-                // The server re-issued a 30-day long token (entitlement changed:
-                // AppSumo tier up/downgrade, or a Stripe resub migration). Overwrite
-                // the on-disk long JWT so the new entitlement survives even fully
-                // offline and the previous one stops working — without the user
+                // The server re-issued the 30-day long token (rolled forward on every
+                // refresh since vexp-web 3.1; also on entitlement change). Overwrite
+                // the on-disk long JWT so the current entitlement survives even fully
+                // offline and a superseded one stops working — without the user
                 // re-pasting a key. Only persist if it verifies locally.
                 if (data.newLongToken && verifyAndDecode(data.newLongToken)) {
                     try {

package/mcp/mcp-server.cjs

@@ -119,7 +119,7 @@ To lift the limit now, upgrade to Pro or Team: https://vexp.dev/#pricing`)}var V
 
 `)),e.push("```"),e.push("");return e.join(`
 `)}var aF=S.object({}),Y$={name:"index_status",description:"Get the current status of the vexp index, including indexed repos, node/edge counts, cross-repo edges, daemon uptime, and indexing progress. Use this to verify vexp is working correctly before making queries.",inputSchema:{type:"object",properties:{},required:[]}};async function Q$(t,e){aF.parse(t);let r=Xa(),n=await e.call("index_status",{});return iF(n,r)}function J$(t){return t.replace(/[\\/]+$/,"").toLowerCase()}function iF(t,e){let r=[],n={healthy:"\u2713",indexing:"\u27F3",error:"\u2717",not_initialized:"\u25CB"}[t.status]??"?";if(r.push("# vexp Index Status"),r.push(`> ${n} ${t.status.toUpperCase()} | v${t.daemon_version} | uptime ${oF(t.daemon_uptime_s)}`),r.push(""),e||t.workspace_root){let a=e?.workspaceRoot,i=t.workspace_root;if(r.push("## Targeting"),e&&(r.push(`- This MCP resolved to: \`${a}\` (via ${e.source})`),e.socket&&r.push(`- Socket/pipe: \`${e.socket}\` (${e.socketOrigin})`)),i){let s=t.served_aliases?.length?` \u2014 repos: ${t.served_aliases.join(", ")}`:"";r.push(`- Daemon serving: \`${i}\`${s}`)}a&&i&&J$(a)!==J$(i)&&r.push(`- \u26A0\uFE0F MISMATCH: this session resolved a different workspace than the daemon it reached. Likely a parallel-session mis-target \u2014 set VEXP_WORKSPACE for this session, or launch \`claude\` from \`${a}\`.`);let o=t.other_daemons??[];r.push(o.length>0?`- Other live daemons: ${o.map(s=>`\`${s.root}\``).join(", ")}`:"- Other live daemons: none"),r.push("")}if(t.status==="error"&&t.error&&(r.push(`**Error:** ${t.error}`),r.push("")),t.status==="not_initialized")return r.push('*vexp is not initialized. Run `vexp index` or use the VS Code command "Setup Workspace".*'),r.join(`
-`);if(r.push("## Overview"),r.push(""),r.push("| Metric | Value |"),r.push("|--------|-------|"),r.push(`| Repos indexed | ${t.repos.length} |`),r.push(`| Total nodes | ${t.total_nodes.toLocaleString()} |`),r.push(`| Total edges | ${t.total_edges.toLocaleString()} |`),r.push(`| Total files | ${t.total_files.toLocaleString()} |`),r.push(`| Cross-repo edges | ${t.cross_repo_edges.toLocaleString()} |`),r.push(`| Index DB size | ${X$(t.db_size_bytes)} |`),r.push(`| Daemon memory | ${X$(t.memory_rss_bytes)} |`),t.compressor){let a=t.compressor==="llm"?`llm (${t.llm_model??"?"}, ${t.llm_inference??"?"})`:"rule";r.push(`| Compressor | ${a} |`)}if(t.last_query_time_ms!==void 0&&r.push(`| Last query time | ${t.last_query_time_ms}ms |`),r.push(""),t.llm_configured_but_inactive&&(r.push("\u26A0\uFE0F A local LLM model is installed and enabled in config, but this daemon is running the rule compressor. Restart the daemon (`vexp daemon-cmd restart`) or re-run `vexp setup-llm` \u2014 until then, results are NOT LLM-compressed."),r.push("")),t.ledger){let a=t.ledger;r.push(`## Savings Ledger (last ${a.period_days??7} days)`),r.push(""),(a.prompts_analyzed??0)>0&&r.push(`- Activity: ${a.prompts_analyzed} prompt(s) analyzed \u2014 ${a.silences} silence(s) (task already oriented), ${a.hints_served} orientation hint(s) served${(a.held_out??0)>0?`, ${a.held_out} held out (randomized measurement)`:""}`),(a.measured_calls??0)>0&&r.push(`- Measured: ${a.measured_calls} tool call(s), ~${(a.measured_tokens_saved??0).toLocaleString()} tokens saved (full-read baseline minus served)`),(a.prompts_analyzed??0)===0&&(a.measured_calls??0)===0&&r.push("- No classified prompts or tool calls in this window."),r.push("")}if(t.sessions&&t.sessions.length>0){r.push("## Active sessions (last 4h)"),r.push("");for(let a of t.sessions){let i=a.idle_s<60?`${a.idle_s}s`:`${Math.floor(a.idle_s/60)}m`;r.push(`- \`${a.session}\u2026\` \u2014 ${a.pipeline_calls} pipeline, ${a.skeleton_calls} skeleton, ${a.other_calls} other (idle ${i})`)}r.push("")}if(t.repos.length>0){r.push("## Repos"),r.push("");for(let a of t.repos){let i=a.is_indexing?` *(indexing ${a.indexing_progress?.toFixed(0)??"?"}%)*`:"";if(r.push(`### \`${a.alias}\`${i}`),r.push(`*${a.path}*`),r.push(""),r.push(`- Nodes: ${a.node_count.toLocaleString()}`),r.push(`- Edges: ${a.edge_count.toLocaleString()}`),r.push(`- Files: ${a.file_count.toLocaleString()}`),r.push(`- Last indexed: ${a.last_indexed_at}`),Object.keys(a.languages).length>0){let o=Object.entries(a.languages).sort(([,s],[,c])=>c-s).map(([s,c])=>`${s}: ${c}`).join(", ");r.push(`- Languages: ${o}`)}r.push("")}}return r.join(`
+`);if(r.push("## Overview"),r.push(""),r.push("| Metric | Value |"),r.push("|--------|-------|"),r.push(`| Repos indexed | ${t.repos.length} |`),r.push(`| Total nodes | ${t.total_nodes.toLocaleString()} |`),r.push(`| Total edges | ${t.total_edges.toLocaleString()} |`),r.push(`| Total files | ${t.total_files.toLocaleString()} |`),r.push(`| Cross-repo edges | ${t.cross_repo_edges.toLocaleString()} |`),r.push(`| Index DB size | ${X$(t.db_size_bytes)} |`),r.push(`| Daemon memory | ${X$(t.memory_rss_bytes)} |`),t.compressor){let a=t.compressor==="llm"?`llm (${t.llm_model??"?"}, ${t.llm_inference??"?"})`:"rule";r.push(`| Compressor | ${a} |`)}if(t.last_query_time_ms!==void 0&&r.push(`| Last query time | ${t.last_query_time_ms}ms |`),r.push(""),t.llm_configured_but_inactive&&(r.push("\u26A0\uFE0F A local LLM model is installed and enabled in config, but this daemon is running the rule compressor. Restart the daemon (`vexp daemon-cmd restart`) or re-run `vexp setup-llm` \u2014 until then, results are NOT LLM-compressed."),r.push("")),t.coverage){let a=t.coverage,i=[];if((a.skipped_oversized??0)>0){let o=a.skipped_examples?.length?` \u2014 e.g. ${a.skipped_examples.join(", ")}`:"";i.push(`- \u26A0\uFE0F ${a.skipped_oversized} file(s) over max_file_size_kb = ${a.max_file_size_kb??"?"} are NOT indexed${o}. Their symbols and callers are invisible to impact, search and run_pipeline. Full list: .vexp/coverage.json; raise the cap in .vexp/vexp.toml to include them.`)}a.unparsed_code_files?.length&&i.push(`- Unparsed file types (no parser yet): ${a.unparsed_code_files.map(o=>`${o.count} .${o.ext}`).join(", ")}`),i.length>0&&(r.push("## Coverage gaps"),r.push(""),r.push(...i),r.push(""))}if(t.ledger){let a=t.ledger;r.push(`## Savings Ledger (last ${a.period_days??7} days)`),r.push(""),(a.prompts_analyzed??0)>0&&r.push(`- Activity: ${a.prompts_analyzed} prompt(s) analyzed \u2014 ${a.silences} silence(s) (task already oriented), ${a.hints_served} orientation hint(s) served${(a.held_out??0)>0?`, ${a.held_out} held out (randomized measurement)`:""}`),(a.measured_calls??0)>0&&r.push(`- Measured: ${a.measured_calls} tool call(s), ~${(a.measured_tokens_saved??0).toLocaleString()} tokens saved (full-read baseline minus served)`),(a.prompts_analyzed??0)===0&&(a.measured_calls??0)===0&&r.push("- No classified prompts or tool calls in this window."),r.push("")}if(t.sessions&&t.sessions.length>0){r.push("## Active sessions (last 4h)"),r.push("");for(let a of t.sessions){let i=a.idle_s<60?`${a.idle_s}s`:`${Math.floor(a.idle_s/60)}m`;r.push(`- \`${a.session}\u2026\` \u2014 ${a.pipeline_calls} pipeline, ${a.skeleton_calls} skeleton, ${a.other_calls} other (idle ${i})`)}r.push("")}if(t.repos.length>0){r.push("## Repos"),r.push("");for(let a of t.repos){let i=a.is_indexing?` *(indexing ${a.indexing_progress?.toFixed(0)??"?"}%)*`:"";if(r.push(`### \`${a.alias}\`${i}`),r.push(`*${a.path}*`),r.push(""),r.push(`- Nodes: ${a.node_count.toLocaleString()}`),r.push(`- Edges: ${a.edge_count.toLocaleString()}`),r.push(`- Files: ${a.file_count.toLocaleString()}`),r.push(`- Last indexed: ${a.last_indexed_at}`),Object.keys(a.languages).length>0){let o=Object.entries(a.languages).sort(([,s],[,c])=>c-s).map(([s,c])=>`${s}: ${c}`).join(", ");r.push(`- Languages: ${o}`)}r.push("")}}return r.join(`
 `)}function oF(t){if(t<60)return`${t}s`;if(t<3600)return`${Math.floor(t/60)}m ${t%60}s`;let e=Math.floor(t/3600),r=Math.floor(t%3600/60);return`${e}h ${r}m`}function X$(t){return t<1024?`${t} B`:t<1024*1024?`${(t/1024).toFixed(1)} KB`:t<1024*1024*1024?`${(t/1024/1024).toFixed(1)} MB`:`${(t/1024/1024/1024).toFixed(2)} GB`}var sF=S.object({workspace_root:S.string().optional().describe("Workspace root path (default: CWD)"),detect_agents:S.boolean().optional().default(!0).describe("Auto-detect AI agents")}),e4={name:"workspace_setup",description:"Set up vexp for the current workspace. Generates configuration files, detects AI coding agents (Claude Code, Cursor, Windsurf, Continue), and provides setup instructions. Run this once when starting to work on a new project.",inputSchema:{type:"object",properties:{workspace_root:{type:"string",description:"Workspace root path (default: current directory)"},detect_agents:{type:"boolean",description:"Auto-detect installed AI agents (default: true)"}},required:[]}};async function t4(t,e){let r=sF.parse(t),n=await e.call("workspace_setup",r);return cF(n)}function cF(t){let e=[];if(e.push("# vexp Workspace Setup"),e.push(`> v${t.vexp_version} | \`${t.workspace_root}\``),e.push(""),t.generated_files.length>0){e.push("## Generated Files"),e.push("");for(let r of t.generated_files)e.push(`- \`${r}\``);e.push("")}if(t.workspace_json&&(e.push("## workspace.json"),e.push(""),e.push("```json"),e.push(t.workspace_json),e.push("```"),e.push("")),t.detected_agents.length>0){e.push("## Detected AI Agents"),e.push("");for(let r of t.detected_agents)e.push(`- **${r}**`);e.push("")}if(t.agent_configs.length>0){e.push("## Agent Configuration Files"),e.push("");for(let r of t.agent_configs){let n=r.already_exists?" *(already exists \u2014 merge manually)*":" *(created)*";e.push(`### ${r.agent} \u2014 \`${r.config_file}\`${n}`),e.push(""),e.push("```"),e.push(r.content),e.push("```"),e.push("")}}if(t.git_hooks_installed&&(e.push("## Git Hooks"),e.push(""),e.push("\u2713 Git hooks installed: `pre-commit`, `post-merge`, `post-checkout`"),e.push("\u2713 Merge driver configured for `index.db`"),e.push("")),t.suggested_gitignore_additions.length>0){e.push("## Suggested .gitignore Additions"),e.push(""),e.push("Add these to your `.gitignore`:"),e.push("```gitignore");for(let r of t.suggested_gitignore_additions)e.push(r);e.push("```"),e.push("")}if(t.index_started&&(e.push("## Indexing"),e.push(""),e.push("\u2713 Initial indexing started in background. Use `index_status` to check progress."),e.push("")),t.setup_instructions.length>0){e.push("## Next Steps"),e.push("");for(let r=0;r<t.setup_instructions.length;r++)e.push(`${r+1}. ${t.setup_instructions[r]}`);e.push("")}return e.join(`
 `)}var uF=S.object({include_previous:S.preprocess(ft,S.boolean().optional().default(!1)).describe("Include observations from previous sessions"),max_results:S.preprocess(pt,S.number().optional().default(20)).describe("Max observations to return"),types:S.preprocess(or,S.array(S.string()).optional()).describe("Filter by observation type")}),r4={name:"get_session_context",description:"Get observations from the current and optionally previous sessions. Observations are automatically captured from every vexp tool call and include what code was explored, decisions made, and insights discovered. Use this to recall what you worked on earlier or in prior sessions. Observations linked to code symbols are automatically marked stale when that code changes.",inputSchema:{type:"object",properties:{include_previous:{type:"boolean",description:"Include observations from previous sessions (default: false)"},max_results:{type:"number",description:"Max observations to return (default: 20)"},types:{type:"array",items:{type:"string",enum:["tool_call","insight","decision","error","manual"]},description:"Filter by observation type"}},required:[]}};async function n4(t,e){let r=uF.parse(t),n=await e.call("get_session_context",r);return pF(n)}function pF(t){let e=[];if(e.push("# Session Context"),e.push(`> Session: ${t.session_id} | ${t.count} observations`),e.push(""),t.observations.length===0)return e.push("*No observations yet in this session.*"),e.join(`
 `);for(let r of t.observations){let n=new Date(r.created_at*1e3),a=`${String(n.getMonth()+1).padStart(2,"0")}-${String(n.getDate()).padStart(2,"0")} ${String(n.getHours()).padStart(2,"0")}:${String(n.getMinutes()).padStart(2,"0")}`,i=r.stale?" ~stale~":"",o=r.current_session===!1?` [prev: ${r.session_id?.slice(0,8)}]`:"";e.push(`- [${a}${i}] (${r.type}) ${r.content}${o}`)}return e.join(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexp-cli",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Local-first context engine for AI coding agents. Pre-indexes your codebase into a dependency graph and feeds any MCP agent only the code that matters — 87% fewer tokens per call. New in 2.5: mechanical work verification and a PII/secret scanner. Works with Claude Code, Cursor, Codex, Copilot, Windsurf, Cline, Aider and 14 agents. Your code never leaves your machine.",
   "type": "module",
   "bin": {
@@ -105,10 +105,10 @@
   },
   "homepage": "https://vexp.dev",
   "optionalDependencies": {
-    "@vexp/core-linux-x64": "3.0.1",
-    "@vexp/core-linux-arm64": "3.0.1",
-    "@vexp/core-darwin-x64": "3.0.1",
-    "@vexp/core-darwin-arm64": "3.0.1",
-    "@vexp/core-win32-x64": "3.0.1"
+    "@vexp/core-linux-x64": "3.1.0",
+    "@vexp/core-linux-arm64": "3.1.0",
+    "@vexp/core-darwin-x64": "3.1.0",
+    "@vexp/core-darwin-arm64": "3.1.0",
+    "@vexp/core-win32-x64": "3.1.0"
   }
 }