vexp-cli 2.4.0 → 2.5.0

package/README.md

@@ -1,108 +1,78 @@
-# vexp — Context Engine for AI Coding Agents
+# vexp-cli — Context Engine for AI Coding Agents (Claude Code, Cursor, Codex)
 
-**58% Less Cost. 90% Fewer Tool Calls. 100% On Your Machine.**
+**Give your AI coding agent the right context, then verify its work — 100% on your machine.**
 
-vexp is a local-first context engine that gives AI coding agents the right code context — automatically. One install, and every agent gets smarter answers with fewer tokens.
+`vexp-cli` is a local-first [MCP server](https://modelcontextprotocol.io) that pre-indexes your codebase into a dependency graph and feeds any AI coding agent only the code that matters for the task — cutting **87% of the tokens** it would otherwise waste reading whole files. New in 2.5: it also checks the agent's work mechanically when it says it's done, and scans your code for PII and secrets before any model reads them. Your source never leaves your laptop.
 
-Works with **14+ AI coding agents** and **30 programming languages** out of the box.
+```bash
+npm install -g vexp-cli
+vexp setup      # auto-configures Claude Code, Cursor, Codex, and 14 agents
+vexp index      # builds the local graph — no login, no API key
+```
 
-→ [SWE-bench Verified: 73% pass@1 at $0.67/task](https://vexp.dev/benchmark)
+[![npm version](https://img.shields.io/npm/v/vexp-cli?color=CB3837)](https://www.npmjs.com/package/vexp-cli)
+[![downloads](https://img.shields.io/npm/dm/vexp-cli?color=CB3837)](https://www.npmjs.com/package/vexp-cli)
+![local-first](https://img.shields.io/badge/code-never%20leaves%20your%20machine-brightgreen)
 
-## Why vexp?
+---
 
-AI coding agents waste more than half their budget exploring codebases before writing a single line of code — 23 tool calls on average just to orient themselves. vexp pre-indexes your project into a dependency graph and delivers only the code that matters, ranked by relevance.
+## Why developers install vexp
 
-- **23 tool calls → 2** — the agent stops guessing and starts coding
-- **$0.78 → $0.33 per task** — measured on SWE-bench Verified
-- **117s → 74s per task** — less context to process = faster answers
-- **Local-first** — your code never leaves your machine
-- **Zero config** — auto-detects your agents and configures MCP
-- **Universal** — works with any agent that supports MCP or custom rules
-- **Optional local AI** — unlock +30% extra savings with `vexp-devmind`, a ~3.5 GB model that runs 100% on your machine. GPU-accelerated on NVIDIA (CUDA) and Apple Silicon (Metal). Opt in with one command.
+Your AI agent burns most of its budget exploring your repo before writing a line of code. It reads entire files, floods its context window, and still misses the one function that mattered. vexp fixes the input **and** the output:
 
-## Supported AI Coding Agents
+- **⚡ 87% fewer tokens per call.** vexp returns ranked pivot files with exact line ranges and blast radius — not whole files. Measured on real usage, not a synthetic benchmark.
+- **🔍 Verifies the work (new in 2.5).** When your agent declares a task done, `verify_done` reports what's provably broken or missing — broken imports, parse errors, dependents never updated — each with file and line. No model grades anything; it's git + tree-sitter + the code graph.
+- **🛡️ Shield scan (new in 2.5).** `vexp shield scan` shows the emails, API keys, tokens and private keys sitting in your comments and strings that every AI agent currently reads. Local, deterministic, masked.
+- **🔒 100% local.** Zero network calls, zero cloud indexing, no account, no API key. Your code stays yours.
+- **🤝 Works with everything.** One `vexp setup` configures Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, Zed, Cline, Aider, opencode, and more — 14 agents in total.
 
-| Agent | Auto-Configured |
-|-------|:-:|
-| Claude Code | ✓ |
-| Cursor | ✓ |
-| Windsurf | ✓ |
-| GitHub Copilot | ✓ |
-| Continue.dev | ✓ |
-| Augment | ✓ |
-| Zed | ✓ |
-| Codex (OpenAI) | ✓ |
-| Cline | ✓ |
-| Aider | ✓ |
-| Kilo Code | ✓ |
-| Kiro | ✓ |
-| Antigravity | ✓ |
-| Opencode | ✓ |
+## How it works
 
-Your agents don't compete with each other — they all share the same context layer.
+vexp parses **34 languages** with tree-sitter into a local SQLite dependency graph, then serves your agent through the Model Context Protocol:
 
-## Supported Languages (30)
+- `run_pipeline` — ranked pivot files + line ranges + blast radius, in one call
+- `get_skeleton` — file structure at 70-90% token savings
+- `verify_done` — mechanical completion check
+- `expand_vexp_ref` — full symbol bodies on demand
 
-TypeScript, JavaScript, Python, Go, Rust, Java, C#, C, C++, Ruby, Kotlin, Scala, Swift, Dart, Elixir, Haskell, OCaml, Lua, R, PHP, Zig, HCL/Terraform, Objective-C, Bash/Shell, Dockerfile, Clojure, F#, SQL, HTML/CSS, YAML/JSON
+You never call these yourself — `vexp setup` writes the agent config, and your agent calls them automatically. You don't even mention vexp in your prompts.
 
-## Quick Start
+## Quickstart
 
 ```bash
+# 1. Install
 npm install -g vexp-cli
-vexp
-```
-
-That's it. The interactive CLI guides you through setup, indexing, and agent configuration.
-
-## What You Get
-
-- **Semantic + graph-ranked context** — finds the right symbols even when keywords don't match
-- **Intent detection in 15 languages** — English, Italian, French, German, Spanish, Portuguese, Russian, Chinese, Japanese, Korean, Arabic, Hindi, Turkish, Dutch, Polish
-- **Cross-session memory** — your agent picks up exactly where it left off, even days later
-- **Stale-knowledge alerts** — when code changes, outdated memory is automatically flagged
-- **Pattern & anti-pattern detection** — recurring changes surface as guidelines; dead-end explorations get flagged early
-- **Change awareness** — files frequently modified together are automatically linked
-- **Security filter** — `.env`, credentials, and SSH keys are excluded automatically
 
-## Platforms
+# 2. Configure your agents (auto-detected) + build the graph
+cd your-project
+vexp setup
+vexp index
 
-Native binaries — no runtime dependencies:
+# 3. Use your agent normally. That's it.
+#    Check savings any time:
+vexp savings
 
-| Platform | Architecture | GPU Acceleration |
-|----------|:-:|:-:|
-| Linux | x64, ARM64 | CUDA (NVIDIA) |
-| macOS | x64, ARM64 (Apple Silicon) | Metal (built-in) |
-| Windows | x64 | CUDA (NVIDIA) |
+# 4. See what your code exposes to AI:
+vexp shield scan
 
-GPU acceleration applies to the optional local AI layer. Vexp's core context engine runs on any modern CPU.
-
-## VS Code Extension
-
-For the best experience, install the [vexp VS Code extension](https://marketplace.visualstudio.com/items?itemName=Vexp.vexp-vscode) — it manages the daemon automatically and adds a sidebar dashboard with token savings tracking.
-
-## Local AI — Optional +30% Savings
+# 5. Diagnose anything:
+vexp doctor
+```
 
-Turn on `vexp-devmind` — a code-specialised AI model that runs entirely on your machine — for an extra +30% token savings on top of the baseline.
+## Supported agents
 
-- **100% local** — the model never calls out. Your code stays on your hardware.
-- **GPU-accelerated** — Metal on Apple Silicon, CUDA on NVIDIA. Auto-detected.
-- **One-command install** — ~3.5 GB one-time download. Minimum 6 GB RAM.
-- **Always up to date** — `--check-updates` compares your local version to the published release without downloading anything.
+Claude Code · Cursor · Windsurf · GitHub Copilot · OpenAI Codex · Zed · Continue.dev · Cline · Aider · Kiro · Kilo Code · opencode · Augment · Antigravity
 
-Sharper context ranking, higher-quality session memory, smarter prompt preprocessing. All without sending a single byte to any server.
+## Supported languages
 
-```bash
-vexp setup-llm --install        # ~3.5 GB one-time download
-vexp setup-llm --check-updates  # no-op if already up to date
-vexp setup-llm --status         # show current config + hardware
-vexp setup-llm --disable        # turn it off any time
-```
+TypeScript, JavaScript, Python, Rust, Go, Java, Kotlin, Scala, C, C++, C#, Ruby, PHP, Swift, Objective-C, Lua, Dart, Elixir, Clojure, Haskell, OCaml, F#, Zig, Bash, SQL, and more — 34 in total.
 
 ## Links
 
-- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Vexp.vexp-vscode)
-- [Website](https://vexp.dev)
+- 🌐 Website & docs → [vexp.dev](https://vexp.dev)
+- 🧩 VS Code / Cursor extension → [Marketplace](https://marketplace.visualstudio.com/items?itemName=vexp.vexp-vscode) · [Open VSX](https://open-vsx.org/extension/vexp/vexp-vscode)
+- 🐛 Issues → [github.com/Vexp-ai/vexp/issues](https://github.com/Vexp-ai/vexp/issues)
 
-## License
+---
 
-MIT
+**Keywords:** ai context engine · mcp server · claude code context · cursor context · save tokens · reduce ai coding cost · code context · dependency graph · tree-sitter · local-first · token optimization · ai coding assistant · code intelligence · model context protocol

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, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpStopGateHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -323,6 +323,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             // Event-driven hint hook: default-on (non-blocking, fail-open — the
             // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
             const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            installClaudeCodeStopGate(workspaceRoot, binaryPath);
             if (hintResult) {
                 results.push({
                     agent: "Claude Code Hint",
@@ -623,6 +624,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
             installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            installClaudeCodeStopGate(workspaceRoot, binaryPath);
             if (guardMode() === "strict")
                 installClaudeCodeHook(workspaceRoot);
             else
@@ -1689,6 +1691,68 @@ export function installClaudeCodeHook(workspaceRoot) {
     }
     return existed ? "updated" : "created";
 }
+function isVexpHookEntry(h, needle) {
+    if (!h || typeof h !== "object")
+        return false;
+    const entry = h;
+    if (entry.command?.includes(needle))
+        return true;
+    const hks = entry.hooks;
+    return Array.isArray(hks) && hks.some((hook) => {
+        if (!hook || typeof hook !== "object")
+            return false;
+        return hook.command?.includes(needle) ?? false;
+    });
+}
+/**
+ * Horizon F2a: install the Stop-hook verification gate for Claude Code.
+ * Same fail-open family as the hint hook: the Rust `stop-gate` command
+ * blocks a stop at most once per session and only on mechanically broken
+ * references (parse errors, imports of removed names). No daemon = no
+ * gate = vanilla stop. Additive like the hint hook, so not guardMode-gated.
+ */
+export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, "vexp-verify.sh");
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    fs.mkdirSync(hookDir, { recursive: true });
+    const script = vexpStopGateHookScript(binaryPath);
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf8") === script;
+    if (!scriptIdentical) {
+        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    }
+    const read = readJsonConfigSafe(settingsPath);
+    if (!read.ok) {
+        warnUnparseable(settingsPath);
+        return scriptIdentical ? null : existed ? "updated" : "created";
+    }
+    const settings = read.data;
+    const hooks = (settings.hooks ?? {});
+    const existing = Array.isArray(hooks.Stop) ? hooks.Stop : [];
+    const filtered = existing.filter((h) => !isVexpHookEntry(h, "vexp-verify"));
+    // Cross-OS shape as everywhere: bash + QUOTED path; timeout in SECONDS.
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-verify.sh"',
+                timeout: 15,
+            },
+        ],
+    });
+    const merged = { ...hooks, Stop: filtered };
+    const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
+    if (scriptIdentical && settingsIdentical)
+        return null;
+    settings.hooks = merged;
+    if (!settingsIdentical) {
+        if (read.existed)
+            backupConfig(settingsPath);
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+    return existed ? "updated" : "created";
+}
 function isVexpHintHookEntry(h) {
     if (!h || typeof h !== "object")
         return false;
@@ -2096,6 +2160,9 @@ vexp runs entirely on this machine: local daemon, index in \`.vexp/\`.
   name the files/symbols to touch. If it does, SKIP vexp - use your normal tools.
 - \`get_skeleton\` - file structure at 70-90% token savings for files you only
   need to understand, not edit.
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  returns mechanically broken references (imports of removed names, parse
+  errors) and untouched dependents of the files you changed, with file:line.
 - vexp may append a one-line hint to a prompt when orientation would help;
   otherwise it stays silent.
 
@@ -2129,6 +2196,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2184,6 +2253,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2250,6 +2321,8 @@ When working on this codebase:
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - token-efficient file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2297,6 +2370,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2344,6 +2419,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`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
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2391,6 +2468,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
   Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2437,6 +2516,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`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
+- \`verify_done\` - call once BEFORE declaring a multi-file task complete:
+  mechanically broken references and untouched dependents, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2478,6 +2559,9 @@ Then implement with your normal tools:
   need to understand, not edit.
 - Do NOT open files one by one to find your way around - one good pipeline call
   beats five exploratory reads; every extra tool call costs a turn.
+- Before declaring a multi-file task complete, call \`verify_done\` once:
+  it returns mechanically broken references (imports of removed names,
+  parse errors) and untouched dependents of your changes, with file:line.
 
 vexp runs entirely on this machine: local daemon, local index stored inside the
 workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -

package/dist/cli.js

@@ -434,6 +434,21 @@ program
         args.push("--export");
     runBinary(binaryPath, args);
 });
+program
+    .command("shield <action>")
+    .description("PII/secret shield: 'scan' reports what comments and string literals would hand to any AI agent (free, read-only, local)")
+    .option("--json", "Emit machine-readable JSON")
+    .action(async (action, opts) => {
+    if (action !== "scan") {
+        console.error(`Unknown shield action '${action}'. Available: scan`);
+        process.exit(1);
+    }
+    const binaryPath = ensureBinary();
+    const args = ["shield", "scan"];
+    if (opts.json)
+        args.push("--json");
+    runBinary(binaryPath, args);
+});
 program
     .command("compress <file>")
     .description("Compress a markdown/text file using prose compression (backup to <name>.original.md)")

package/dist/hook-template.js

@@ -397,6 +397,24 @@ exit 0
 export function vexpHintHookScript(binaryPath) {
     return VEXP_HINT_HOOK.replace("__VEXP_BIN__", binaryPath.replace(/\\/g, "/"));
 }
+/**
+ * Horizon F2a: Stop-hook verification gate (Claude Code). All logic lives
+ * in the Rust binary (stop-gate): mechanical completion check via daemon,
+ * blocks at most once per session and ONLY on parse errors / broken
+ * imports. FAIL-OPEN by construction: no binary / no daemon / timeout =
+ * silent exit 0 = normal stop.
+ */
+export const VEXP_STOP_GATE_HOOK = `#!/bin/bash
+# vexp-verify: mechanical completion gate on Stop (Horizon). Fails open.
+VEXP_BIN="__VEXP_BIN__"
+[ -x "$VEXP_BIN" ] || exit 0
+"$VEXP_BIN" stop-gate 2>/dev/null
+exit 0
+`;
+/** Bake the binary path into the stop-gate hook script. */
+export function vexpStopGateHookScript(binaryPath) {
+    return VEXP_STOP_GATE_HOOK.replace("__VEXP_BIN__", binaryPath.replace(/\\/g, "/"));
+}
 /**
  * opencode/Kilo per-prompt hint plugin (2.4.0). The plugin API's
  * `chat.message` hook sees the user message before the LLM call and can
@@ -407,11 +425,17 @@ export function vexpHintHookScript(binaryPath) {
  * __VEXP_BIN__ is baked at install time. Keep in lockstep with the VS Code
  * extension copy.
  */
-export const VEXP_OPENCODE_HINT = `// vexp-hint: per-prompt orientation (fail-open). Managed by vexp.
+export const VEXP_OPENCODE_HINT = `// vexp-hint: per-prompt orientation + idle verification (fail-open). Managed by vexp.
 const VEXP_BIN = "__VEXP_BIN__";
-export const VexpHint = async ({ directory }) => {
+export const VexpHint = async ({ directory, client }) => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const taskFileFor = (sid) =>
+    path.join(directory, ".vexp", "task-" + String(sid || "unknown") + ".txt");
+  const gateMarker = (sid) =>
+    path.join(directory, ".vexp", "idle-gate-" + String(sid || "unknown") + ".done");
   return {
-    "chat.message": async (_input, output) => {
+    "chat.message": async (input, output) => {
       try {
         const { execFileSync } = await import("node:child_process");
         const text = (output.parts || [])
@@ -419,8 +443,17 @@ export const VexpHint = async ({ directory }) => {
           .map((p) => p.text)
           .join("\\n");
         if (!text || text.length < 40) return;
+        // First prompt of the session = the task spec for the idle gate.
+        const sid = (input && input.sessionID) || null;
+        try {
+          const tf = taskFileFor(sid);
+          if (!fs.existsSync(tf)) {
+            fs.mkdirSync(path.dirname(tf), { recursive: true });
+            fs.writeFileSync(tf, text);
+          }
+        } catch (e) { /* fail open */ }
         const out = execFileSync(VEXP_BIN, ["prompt-hint"], {
-          input: JSON.stringify({ prompt: text }),
+          input: JSON.stringify({ prompt: text, session_id: sid }),
           timeout: 4000,
           env: { ...process.env, CLAUDE_PROJECT_DIR: directory },
           encoding: "utf8",
@@ -430,6 +463,45 @@ export const VexpHint = async ({ directory }) => {
         if (hint) output.parts.push({ type: "text", text: hint });
       } catch (e) { /* fail open */ }
     },
+    event: async ({ event }) => {
+      // Idle gate: the opencode twin of the Claude Stop hook. Runs the
+      // mechanical completion check once per session; on gaps, sends ONE
+      // follow-up prompt with the exact list (best effort - any failure
+      // is silent and the session simply stays stopped).
+      try {
+        if (!event || event.type !== "session.idle") return;
+        const sid = event.properties && event.properties.sessionID;
+        if (!sid) return;
+        const marker = gateMarker(sid);
+        if (fs.existsSync(marker)) return;
+        const tf = taskFileFor(sid);
+        if (!fs.existsSync(tf)) return;
+        const { execFileSync } = await import("node:child_process");
+        const out = execFileSync(
+          VEXP_BIN,
+          ["verify", "--json", "--task-file", tf],
+          { timeout: 15000, cwd: directory, encoding: "utf8" }
+        );
+        const rep = JSON.parse(out);
+        const items = [];
+        for (const f of (rep.spec && rep.spec.forbidden_touched) || [])
+          items.push("- the task says NOT to modify \`" + f + "\` but it was changed - revert or justify");
+        for (const a of (rep.spec && rep.spec.artifacts_missing) || [])
+          items.push("- the task asks for \`" + a + "\` and it does not exist yet");
+        for (const b of (rep.broken_imports || []).slice(0, 8))
+          items.push("- " + b.file + ":" + b.line + " imports \`" + b.imports + "\` which no longer exists in " + b.from_changed_file);
+        if (!items.length) return;
+        fs.writeFileSync(marker, "1");
+        await client.session.prompt({
+          path: { id: sid },
+          body: {
+            parts: [{ type: "text", text:
+              "vexp verify found mechanically checkable gaps between the session's work and the task:\\n" +
+              items.join("\\n") + "\\nFix each item above. This check will not repeat." }],
+          },
+        });
+      } catch (e) { /* fail open */ }
+    },
   };
 };
 `;

package/dist/mcp-supervisor.js

@@ -1,4 +1,5 @@
 import * as fs from "fs";
+import { CLI_VERSION } from "./version.js";
 import * as net from "net";
 import * as os from "os";
 import * as path from "path";
@@ -95,11 +96,22 @@ export async function ensureMcpHttpServer(opts = {}) {
     const mcpPath = getMcpServerPath();
     if (!mcpPath)
         return null;
-    // Fast path: already alive and tracked.
+    // Fast path: already alive and tracked - but only if it is OUR version.
+    // Field report (Nathan): a 2.3.0 http server stayed authoritative for
+    // 9 days across extension upgrades because reuse never compared
+    // versions. On mismatch (or a legacy record without one) we take over:
+    // SIGTERM the old listener and spawn the current build.
     {
         const existing = readPidRecord();
         if (existing && existing.port === port && isPidAlive(existing.pid) && (await isPortInUse(port))) {
-            return { pid: existing.pid, port, started: false };
+            if (existing.version === CLI_VERSION) {
+                return { pid: existing.pid, port, started: false };
+            }
+            try {
+                process.kill(existing.pid, "SIGTERM");
+            }
+            catch { /* already gone */ }
+            await new Promise((r) => setTimeout(r, 500));
         }
     }
     // Slow path: we may need to spawn. Serialize across concurrent callers
@@ -164,7 +176,7 @@ export async function ensureMcpHttpServer(opts = {}) {
         const pid = child.pid;
         if (!pid)
             return null;
-        writePidRecord({ pid, port, startedAt: Date.now(), owner });
+        writePidRecord({ pid, port, startedAt: Date.now(), owner, version: CLI_VERSION });
         // Wait for the child to actually bind the port BEFORE releasing the
         // lock. Without this, a second caller arriving right after release
         // sees pidfile+live-pid but port-not-yet-bound → falsely concludes

package/dist/update-check.js

@@ -63,6 +63,19 @@ export async function checkForUpdate() {
         return;
     if (process.argv.includes("--skip-update-check"))
         return;
+    // Protocol and diagnostic commands are NEVER touched by update
+    // machinery. Field report (Nathan, 2.4.0): the old hard gate ran for
+    // every subcommand and exit(1)'d on any registry delta - publishing a
+    // release remotely disabled every installed CLI at the instant of
+    // publish. `vexp mcp` died at spawn (host saw zero tools, silently),
+    // and doctor/--help/--version were disabled by the exact condition
+    // they existed to diagnose.
+    const argv = process.argv.slice(2);
+    const cmd = argv.find((a) => !a.startsWith("-"));
+    if (cmd === "mcp" || cmd === "doctor" || cmd === "stop-gate" || cmd === "prompt-hint")
+        return;
+    if (argv.includes("--version") || argv.includes("-V") || argv.includes("--help") || argv.includes("-h"))
+        return;
     let latest = null;
     // Try cache first
     const cache = readCache();
@@ -76,14 +89,13 @@ export async function checkForUpdate() {
         writeCache(latest);
     }
     if (isOutdated(CLI_VERSION, latest)) {
+        // ADVISORY ONLY - never exit. A newer version on the registry is
+        // news, not an incompatibility: the daemon handshake is where real
+        // incompatibilities surface, with an actionable error.
         console.error("");
-        console.error(chalk.red.bold("  vexp update required!"));
-        console.error("");
-        console.error(`  Installed: ${chalk.dim(CLI_VERSION)}`);
-        console.error(`  Available: ${chalk.green(latest)}`);
-        console.error("");
+        console.error(chalk.yellow.bold("  vexp update available"));
+        console.error(`  Installed: ${chalk.dim(CLI_VERSION)}  ->  Available: ${chalk.green(latest)}`);
         console.error(`  Run:  ${chalk.cyan("npm install -g vexp-cli")}`);
         console.error("");
-        process.exit(1);
     }
 }

package/mcp/mcp-server.cjs

@@ -117,7 +117,7 @@ To lift the limit now, upgrade to Pro or Team: https://vexp.dev/#pricing`)}var V
 `))}var eF=S.object({files:S.preprocess(or,S.array(S.string())).describe("File paths to skeletonize (relative to repo root)"),detail:S.enum(["minimal","standard","detailed"]).optional().default("standard"),repo:S.string().optional().describe("Repo alias (default: current)")}),Hm={name:"get_skeleton",description:"Structural view of files you need to UNDERSTAND but not edit (70-90% smaller than Read): signatures, classes, types at detail minimal|standard|detailed. Use after run_pipeline to drill into a file; use Read only for files you are about to edit.",inputSchema:{type:"object",properties:{files:{type:"array",items:{type:"string"},description:"File paths to skeletonize"},detail:{type:"string",enum:["minimal","standard","detailed"],description:"Skeleton detail level (default: standard)"},repo:{type:"string",description:"Repo alias (from index_status). Default: primary repo"}},required:["files"]}};async function K$(t,e){let r=eF.parse(t),n={files:r.files.map(i=>({path:i,repo:r.repo})),detail:r.detail},a=await e.call("get_skeleton",n);return tF(a)}function tF(t){let e=[];if(!Array.isArray(t)||t.length===0)return e.push("# File Skeletons"),e.push(""),e.push("*No skeleton data \u2014 files may not be indexed yet. Run `index_status` to check.*"),e.join(`
 `);let r=new Map;for(let n of t){let a=r.get(n.file_path)??[];a.push(n),r.set(n.file_path,a)}e.push("# File Skeletons"),e.push(`> ${r.size} file(s), ${t.length} symbol(s)`),e.push("");for(let[n,a]of r){e.push(`## \`${n}\``),e.push("");for(let i of a){let o=i.token_reduction_pct>0?` *(${i.token_reduction_pct.toFixed(0)}% token reduction)*`:"";e.push(`### ${i.node}${o}`),e.push(`*\`${i.fqn}\`*`),e.push(""),e.push("```"),e.push(i.skeleton),e.push("```"),e.push("")}}return e.join(`
 `)}var rF=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){rF.parse(t);let r=Xa(),n=await e.call("index_status",{});return nF(n,r)}function J$(t){return t.replace(/[\\/]+$/,"").toLowerCase()}function nF(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 ${aF(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.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.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 aF(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 iF=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=iF.parse(t),n=await e.call("workspace_setup",r);return oF(n)}function oF(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 sF=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=sF.parse(t),n=await e.call("get_session_context",r);return cF(n)}function cF(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,7 +1,7 @@
 {
   "name": "vexp-cli",
-  "version": "2.4.0",
-  "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.",
+  "version": "2.5.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": {
     "vexp": "./bin/vexp.js"
@@ -32,66 +32,70 @@
     "typescript": "^5.4.0"
   },
   "author": "Vexp",
-  "license": "MIT",
+  "license": "UNLICENSED",
   "keywords": [
-    "vexp",
-    "ai",
+    "ai-context",
     "context-engine",
+    "save-tokens",
+    "token-optimization",
+    "reduce-ai-cost",
+    "ai-coding-cost",
+    "code-context",
+    "code-intelligence",
+    "ai-code-context",
+    "code-verification",
+    "pii-scanner",
+    "secret-scanner",
+    "ai-code-review",
     "mcp",
-    "coding-agent",
+    "mcp-server",
+    "mcp-tool",
+    "model-context-protocol",
+    "claude-code",
+    "claude",
     "cursor",
     "windsurf",
-    "claude",
-    "claude-code",
-    "copilot",
     "github-copilot",
-    "zed",
-    "augment",
-    "continue",
+    "copilot",
     "codex",
     "openai-codex",
-    "kiro",
-    "kilo-code",
+    "zed",
     "cline",
     "aider",
-    "antigravity",
+    "continue",
+    "kiro",
+    "kilo-code",
     "opencode",
-    "code-intelligence",
-    "token-optimization",
-    "token-saver",
+    "augment",
+    "antigravity",
     "ast",
     "tree-sitter",
-    "code-context",
     "dependency-graph",
-    "model-context-protocol",
-    "mcp-server",
-    "mcp-tool",
+    "code-index",
+    "code-search",
+    "code-rag",
+    "rag",
     "llm",
     "ai-agent",
+    "coding-agent",
     "ai-coding",
     "ai-coding-assistant",
     "developer-tools",
-    "code-search",
-    "code-index",
-    "swe-bench",
-    "context-window",
-    "rag",
-    "code-rag",
     "local-first",
     "offline",
     "privacy",
+    "on-premise",
     "typescript",
     "python",
     "rust",
     "go",
     "java",
-    "c",
-    "cpp",
-    "csharp",
-    "ruby",
-    "swift",
     "kotlin",
-    "php"
+    "swift",
+    "php",
+    "ruby",
+    "cpp",
+    "csharp"
   ],
   "publishConfig": {
     "access": "public"
@@ -99,11 +103,19 @@
   "engines": {
     "node": ">=20.0.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vexp-ai/vexp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Vexp-ai/vexp/issues"
+  },
+  "homepage": "https://vexp.dev",
   "optionalDependencies": {
-    "@vexp/core-linux-x64": "2.4.0",
-    "@vexp/core-linux-arm64": "2.4.0",
-    "@vexp/core-darwin-x64": "2.4.0",
-    "@vexp/core-darwin-arm64": "2.4.0",
-    "@vexp/core-win32-x64": "2.4.0"
+    "@vexp/core-linux-x64": "2.5.0",
+    "@vexp/core-linux-arm64": "2.5.0",
+    "@vexp/core-darwin-x64": "2.5.0",
+    "@vexp/core-darwin-arm64": "2.5.0",
+    "@vexp/core-win32-x64": "2.5.0"
   }
 }