vexp-cli 2.3.0 → 2.4.0

package/dist/doctor.js

@@ -2,6 +2,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import * as net from "net";
+import { spawnSync } from "child_process";
 import chalk from "chalk";
 import { socketPathFor } from "./socket-path.js";
 // `vexp doctor` — audit the vexp MCP/daemon state WITHOUT connecting to a daemon.
@@ -150,15 +151,50 @@ export async function runDoctor() {
             if (st.llm_configured_but_inactive === true) {
                 line(WARN, `local LLM is installed and enabled in config but this daemon runs the RULE compressor — results are not LLM-compressed. Run 'vexp daemon-cmd restart' to load the model.`);
             }
+            // 2.4.0 upgrade guard (CLI side): a daemon surviving an upgrade keeps
+            // serving the OLD feature set and its gaps read as product bugs
+            // (field case: pre-ledger daemon after the 2.4.0 install). The VS Code
+            // extension restarts automatically; CLI users get told explicitly.
+            try {
+                const { getBinaryPath } = await import("./binary.js");
+                const { execFileSync } = await import("node:child_process");
+                const out = execFileSync(getBinaryPath(), ["--version"], { timeout: 5000, encoding: "utf8" });
+                const bundled = out.trim().split(/\s+/).pop();
+                const running = st.daemon_version;
+                if (bundled && running && bundled !== running) {
+                    line(WARN, `daemon is v${running} but the installed binary is v${bundled} — this workspace is still served by the OLD version. Run 'vexp daemon-cmd restart' to upgrade it now.`);
+                }
+                else if (st.binary_stale === true) {
+                    line(WARN, `daemon is running a deleted executable (upgraded on disk) — run 'vexp daemon-cmd restart' to load the new build.`);
+                }
+            }
+            catch { /* best-effort */ }
             // 2.3 C1 — which agent sessions actually used vexp (a session with zero
             // calls never shows up here; that absence is the diagnostic).
             const sessions = Array.isArray(st.sessions) ? st.sessions : [];
+            // 2.3.3 Savings Ledger — activity counts even when no tool is ever
+            // called: silence on oriented prompts is vexp WORKING, and the old
+            // "never used" warning on quiet-but-active daemons generated real
+            // support tickets ("is it working? it never got called").
+            const ledger = (st.ledger ?? {});
+            const analyzed = Number(ledger.prompts_analyzed) || 0;
+            if (analyzed > 0) {
+                line(OK, `savings ledger (7d): ${analyzed} prompt(s) analyzed — ${Number(ledger.silences) || 0} silences (task already oriented), ${Number(ledger.hints_served) || 0} hints served. Details: vexp savings`);
+            }
             if (sessions.length > 0) {
                 const total = sessions.reduce((n, s) => n + (Number(s.pipeline_calls) || 0), 0);
                 line(OK, `sessions (4h): ${sessions.length} active, ${total} pipeline calls total`);
             }
+            else if (analyzed > 0) {
+                line(OK, `no tool calls in the last 4h — but the ledger above shows vexp is analyzing prompts (zero calls is normal on oriented tasks)`);
+            }
             else if (Number(st.daemon_uptime_s) > 600) {
-                line(WARN, `no agent session has called vexp since daemon start — if an agent is working here, it is not using vexp (check its MCP config)`);
+                // Embedded caveat: a stdio MCP server (`vexp-core mcp`) spawned while
+                // the daemon was unreachable serves from its own in-process index and
+                // never attaches to the daemon later — its calls are real but
+                // invisible to these counters. Don't tell that user "the agent is not
+                // using vexp"; tell them how to converge on the daemon.
+                line(WARN, `no agent session has called vexp through this daemon since it started — either no agent is using vexp here (check its MCP config), or the agent's vexp MCP server started BEFORE the daemon and is running embedded (in-process). If calls do succeed in the agent, restart the agent (with the daemon already up) so its MCP server attaches to the daemon.`);
             }
             else {
                 line(OK, `no session calls yet (daemon just started)`);
@@ -201,6 +237,12 @@ export async function runDoctor() {
     // 3) License (fresh.jwt rolling token vs license.jwt).
     console.log(chalk.bold("\nLicense tokens (~/.vexp)"));
     const now = Math.floor(Date.now() / 1000);
+    // Either valid token keeps the plan ACTIVE. An expired license.jwt next to
+    // a valid fresh.jwt is normal steady-state (the long token re-rolls on the
+    // next online validation) — labeling it a bare WARN read as "my license
+    // expired" and generated tickets from perfectly licensed users.
+    const freshExp = jwtExp(path.join(home, ".vexp", "fresh.jwt"));
+    const freshValid = freshExp != null && freshExp > now;
     for (const name of ["fresh.jwt", "license.jwt"]) {
         const p = path.join(home, ".vexp", name);
         if (!fs.existsSync(p)) {
@@ -214,38 +256,58 @@ export async function runDoctor() {
         }
         const days = Math.round((exp - now) / 86400);
         if (exp < now) {
-            line(name === "fresh.jwt" ? OK : WARN, `${name}: expired ${-days}d ago${name === "fresh.jwt" ? " (benign — rolling token, falls back to license.jwt)" : ""}`);
+            if (name === "fresh.jwt") {
+                line(OK, `${name}: expired ${-days}d ago (benign — rolling token, falls back to license.jwt)`);
+            }
+            else if (freshValid) {
+                line(OK, `${name}: long token expired ${-days}d ago — plan still ACTIVE via fresh.jwt; it renews automatically on the next online validation`);
+            }
+            else {
+                line(WARN, `${name}: expired ${-days}d ago and no valid fresh token — plan features may be limited; go online or re-activate the license`);
+            }
         }
         else {
             line(OK, `${name}: valid, ~${days}d remaining`);
         }
     }
-    // 4) Codex MCP transport stanza.
-    console.log(chalk.bold("\nCodex (~/.codex/config.toml)"));
-    const codexPath = path.join(os.homedir(), ".codex", "config.toml");
-    if (!fs.existsSync(codexPath)) {
-        line(OK, "no ~/.codex/config.toml (Codex not configured)");
-    }
-    else {
-        const toml = fs.readFileSync(codexPath, "utf-8");
+    // 4) Codex MCP transport stanza — global AND project-level. Codex supports
+    // per-project `.codex/config.toml`; checking only the global file made
+    // doctor report "[OK] no stanza" to users whose (working) config lives in
+    // the workspace.
+    console.log(chalk.bold("\nCodex (config.toml)"));
+    const codexConfigs = [
+        { label: "~/.codex/config.toml", file: path.join(os.homedir(), ".codex", "config.toml") },
+        { label: `${ws.root}/.codex/config.toml (project)`, file: path.join(ws.root, ".codex", "config.toml") },
+    ];
+    let codexStanzaSeen = false;
+    for (const { label, file } of codexConfigs) {
+        if (!fs.existsSync(file)) {
+            line(OK, `${label}: absent`);
+            continue;
+        }
+        const toml = fs.readFileSync(file, "utf-8");
         const m = toml.match(/\n?\[mcp_servers\.vexp\][\s\S]*?(?=\n\[[A-Za-z_]|$)/);
         const section = m ? m[0] : "";
-        if (!section)
-            line(OK, "no [mcp_servers.vexp] stanza");
-        else {
-            const hasUrl = /^\s*url\s*=/m.test(section);
-            const hasCmd = /^\s*command\s*=/m.test(section);
-            if (hasUrl && hasCmd)
-                line(BAD, "stanza has BOTH 'url' and 'command' → 'url is not supported for stdio'. Re-run setup to rewrite cleanly.");
-            else if (hasUrl)
-                line(OK, "transport: http (url)");
-            else if (hasCmd) {
-                const wsm = section.match(/VEXP_WORKSPACE\s*=\s*['"]([^'"]+)['"]/);
-                line(OK, `transport: stdio (command)${wsm ? `, VEXP_WORKSPACE=${wsm[1]}` : ""}`);
-            }
-            else
-                line(WARN, "stanza present but neither url nor command found");
+        if (!section) {
+            line(OK, `${label}: no [mcp_servers.vexp] stanza`);
+            continue;
+        }
+        codexStanzaSeen = true;
+        const hasUrl = /^\s*url\s*=/m.test(section);
+        const hasCmd = /^\s*command\s*=/m.test(section);
+        if (hasUrl && hasCmd)
+            line(BAD, `${label}: stanza has BOTH 'url' and 'command' → 'url is not supported for stdio'. Re-run setup to rewrite cleanly.`);
+        else if (hasUrl)
+            line(OK, `${label}: transport http (url)`);
+        else if (hasCmd) {
+            const wsm = section.match(/VEXP_WORKSPACE\s*=\s*['"]([^'"]+)['"]/);
+            line(OK, `${label}: transport stdio (command)${wsm ? `, VEXP_WORKSPACE=${wsm[1]}` : ""}`);
         }
+        else
+            line(WARN, `${label}: stanza present but neither url nor command found`);
+    }
+    if (!codexStanzaSeen) {
+        console.log(chalk.dim("        → no vexp stanza in either file (Codex not configured for vexp)"));
     }
     // 5) Claude Code entry (should be UNPINNED after the multi-session fix).
     console.log(chalk.bold("\nClaude Code (~/.claude.json)"));
@@ -263,6 +325,152 @@ export async function runDoctor() {
     catch {
         line(OK, "no ~/.claude.json");
     }
+    // 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
+    // denies anything while the config "looks correct" and presence-only checks
+    // report healthy (Nathan, 2026-07).
+    console.log(chalk.bold("\nClaude Code guard hook (.claude/settings.json)"));
+    {
+        const sPath = path.join(ws.root, ".claude", "settings.json");
+        let guardHooks = [];
+        let settingsReadable = false;
+        try {
+            const settings = JSON.parse(fs.readFileSync(sPath, "utf-8"));
+            settingsReadable = true;
+            const pre = Array.isArray(settings?.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
+            for (const m of pre) {
+                const hks = Array.isArray(m?.hooks) ? m.hooks : [];
+                for (const h of hks) {
+                    if (typeof h?.command === "string" && h.command.includes("vexp-guard"))
+                        guardHooks.push(h);
+                }
+            }
+        }
+        catch { /* absent or unparseable */ }
+        if (!settingsReadable) {
+            line(OK, "no .claude/settings.json (guard not installed)");
+        }
+        else if (guardHooks.length === 0) {
+            line(OK, "no vexp guard configured (2.3 default — enable with 'vexp setup --guard-strict')");
+        }
+        else {
+            for (const h of guardHooks) {
+                const cmd = h.command;
+                const execForm = Array.isArray(h.args);
+                const timeoutS = typeof h.timeout === "number" ? h.timeout : 600;
+                if (!execForm && /\$\{?CLAUDE_PROJECT_DIR\}?\//.test(cmd) && !cmd.includes('"')) {
+                    line(ws.root.includes(" ") ? BAD : WARN, `shell-form hook command with unquoted $CLAUDE_PROJECT_DIR — word-splits on paths with spaces${ws.root.includes(" ") ? ` and THIS project path has one: the guard never runs` : ""}. Re-run 'vexp setup --guard-strict' to rewrite with a quoted path.`);
+                }
+                if (execForm && process.platform === "win32") {
+                    // Exec form spawns the .sh directly, which Windows cannot do at
+                    // all — the entry LOOKS installed and enforces nothing. This was
+                    // invisible for days because doctor used to skip the live check
+                    // on Windows entirely.
+                    line(BAD, `exec-form hook entry ('args' present) cannot run a .sh on Windows — the guard fails open. Re-run 'vexp setup --guard-strict' to rewrite it (bash-prefixed shell form).`);
+                }
+                if (timeoutS > 600) {
+                    line(WARN, `hook timeout ${timeoutS} is in SECONDS (${Math.round(timeoutS / 60)} minutes) — likely meant milliseconds. Re-run 'vexp setup --guard-strict' to fix.`);
+                }
+                // Run it exactly as Claude Code would: exec form = direct spawn with
+                // the placeholder substituted by the host; shell form = a shell with
+                // CLAUDE_PROJECT_DIR in the environment. On Windows Claude Code runs
+                // shell-form hooks through Git Bash, so probe via bash there too —
+                // if bash is missing, that IS the finding (Claude Code itself
+                // requires Git Bash on Windows).
+                const substituted = cmd.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, ws.root);
+                const shell = process.platform === "win32" ? "bash" : "sh";
+                const r = execForm
+                    ? spawnSync(substituted, h.args.map((a) => String(a).replace(/\$\{CLAUDE_PROJECT_DIR\}/g, ws.root)), {
+                        env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
+                        timeout: 5000,
+                        encoding: "utf-8",
+                    })
+                    : spawnSync(shell, ["-c", cmd], {
+                        env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
+                        timeout: 5000,
+                        encoding: "utf-8",
+                    });
+                if (r.error) {
+                    line(BAD, `guard hook DID NOT RUN: ${r.error.code ?? r.error.message} spawning '${substituted}' — the guard is enforcing nothing. Re-run 'vexp setup --guard-strict'.`);
+                }
+                else if (r.status !== 0) {
+                    line(BAD, `guard hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 200)}` : ""} — Claude Code treats this as a non-blocking failure, so searches proceed unguarded.`);
+                }
+                else {
+                    const decision = /"permissionDecision"\s*:\s*"(\w+)"/.exec(String(r.stdout ?? ""))?.[1];
+                    if (decision)
+                        line(OK, `guard hook runs (live decision here: ${decision})`);
+                    else
+                        line(WARN, `guard hook ran (exit 0) but produced no permissionDecision output — check ${path.join(".claude", "hooks", "vexp-guard.sh")}`);
+                }
+            }
+        }
+    }
+    // 5c) Cursor guard hook — same live-execution philosophy as 5b. Cursor's
+    // hooks fail OPEN too (`failClosed` defaults to false), so a guard that
+    // cannot spawn silently enforces nothing there as well. The guard's stdin
+    // protocol: JSON {tool_name, tool_input, workspace_roots, cwd}; a healthy
+    // run answers {"permission":"allow"} with exit 0 OR a deny verdict with
+    // exit 2 — BOTH mean "the hook works", anything else is a failure.
+    console.log(chalk.bold("\nCursor guard hook (.cursor/hooks.json)"));
+    {
+        const cursorCfgPath = path.join(ws.root, ".cursor", "hooks.json");
+        let cursorCmds = [];
+        let cursorReadable = false;
+        try {
+            const cfg = JSON.parse(fs.readFileSync(cursorCfgPath, "utf-8"));
+            cursorReadable = true;
+            const pre = Array.isArray(cfg?.hooks?.preToolUse) ? cfg.hooks.preToolUse : [];
+            for (const h of pre) {
+                if (typeof h?.command === "string" && h.command.includes("vexp-guard"))
+                    cursorCmds.push(h.command);
+            }
+        }
+        catch { /* absent or unparseable */ }
+        if (!cursorReadable) {
+            line(OK, "no .cursor/hooks.json (guard not installed)");
+        }
+        else if (cursorCmds.length === 0) {
+            line(OK, "no vexp guard configured (enable with 'vexp setup --guard-strict')");
+        }
+        else if (process.platform === "win32") {
+            line(OK, `guard configured (${cursorCmds.length} entry) — live execution check skipped on Windows`);
+        }
+        else {
+            // A benign Grep probe: with a healthy daemon the guard denies (exit 2),
+            // without one it allows (exit 0) — either proves the hook executes.
+            const probe = JSON.stringify({
+                tool_name: "Grep",
+                tool_input: {},
+                workspace_roots: [ws.root],
+                cwd: ws.root,
+            });
+            for (const cmd of cursorCmds) {
+                // Cursor runs project hooks from the project root; emulate that.
+                const r = spawnSync("sh", ["-c", cmd], {
+                    cwd: ws.root,
+                    input: probe,
+                    timeout: 5000,
+                    encoding: "utf-8",
+                });
+                if (r.error) {
+                    line(BAD, `guard hook DID NOT RUN: ${r.error.code ?? r.error.message} spawning '${cmd}' — Cursor hooks fail open, so the guard is enforcing nothing. Re-run 'vexp setup --guard-strict'.`);
+                    continue;
+                }
+                const decision = /"permission"\s*:\s*"(\w+)"/.exec(String(r.stdout ?? ""))?.[1];
+                if ((r.status === 0 || r.status === 2) && decision) {
+                    line(OK, `guard hook runs (live decision here: ${decision})`);
+                }
+                else if (r.status !== 0 && r.status !== 2) {
+                    line(BAD, `guard hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 200)}` : ""} — Cursor treats hook failures as allow, so searches proceed unguarded.`);
+                }
+                else {
+                    line(WARN, `guard hook ran (exit ${r.status}) but produced no permission verdict — check ${path.join(".cursor", "hooks", "vexp-guard.js")}`);
+                }
+            }
+        }
+    }
     // 6) HTTP MCP supervisor.
     console.log(chalk.bold("\nHTTP MCP supervisor (~/.vexp/mcp.pid)"));
     try {

package/dist/hook-template.js

@@ -374,3 +374,66 @@ process.stdin.on("end", () => {
   try { main(input); } catch (e) { allow(); } // any surprise -> fail open
 });
 `;
+/**
+ * UserPromptSubmit hint hook (2.3.3 event-driven mandate). The resident
+ * CLAUDE.md strategy text is gone; instead, when a prompt names no known
+ * symbol or file of the indexed workspace, the daemon returns a one-line
+ * hint suggesting run_pipeline. All logic (stdin parsing, classification,
+ * hook-JSON output) lives in the Rust binary so the script is OS-neutral;
+ * Claude Code runs shell-form hooks through Git Bash on Windows.
+ * FAIL-OPEN CONTRACT: every failure path (binary missing, daemon down,
+ * timeout) exits 0 with no output = vanilla behavior, never a broken
+ * prompt. Keep in lockstep with the VS Code extension copy.
+ * The __VEXP_BIN__ placeholder is baked at install time.
+ */
+export const VEXP_HINT_HOOK = `#!/bin/bash
+# vexp-hint: event-driven orientation hint (UserPromptSubmit). Fails open.
+VEXP_BIN="__VEXP_BIN__"
+[ -x "$VEXP_BIN" ] || exit 0
+"$VEXP_BIN" prompt-hint 2>/dev/null
+exit 0
+`;
+/** Bake the binary path into the hint hook script. */
+export function vexpHintHookScript(binaryPath) {
+    return VEXP_HINT_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
+ * append parts — the opencode-family equivalent of UserPromptSubmit +
+ * additionalContext. All classification lives in the Rust binary
+ * (prompt-hint, Claude-shaped JSON envelope; we extract additionalContext
+ * here). FAIL-OPEN: any error/timeout/missing binary => no parts appended.
+ * __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.
+const VEXP_BIN = "__VEXP_BIN__";
+export const VexpHint = async ({ directory }) => {
+  return {
+    "chat.message": async (_input, output) => {
+      try {
+        const { execFileSync } = await import("node:child_process");
+        const text = (output.parts || [])
+          .filter((p) => p && p.type === "text" && typeof p.text === "string")
+          .map((p) => p.text)
+          .join("\\n");
+        if (!text || text.length < 40) return;
+        const out = execFileSync(VEXP_BIN, ["prompt-hint"], {
+          input: JSON.stringify({ prompt: text }),
+          timeout: 4000,
+          env: { ...process.env, CLAUDE_PROJECT_DIR: directory },
+          encoding: "utf8",
+        });
+        if (!out || !out.trim()) return;
+        const hint = JSON.parse(out).hookSpecificOutput?.additionalContext;
+        if (hint) output.parts.push({ type: "text", text: hint });
+      } catch (e) { /* fail open */ }
+    },
+  };
+};
+`;
+/** Bake the binary path into the opencode hint plugin. */
+export function vexpOpencodeHintPlugin(binaryPath) {
+    return VEXP_OPENCODE_HINT.replace("__VEXP_BIN__", binaryPath.replace(/\\/g, "/"));
+}

package/dist/serve.js

@@ -140,7 +140,17 @@ async function resurrectAll() {
     // Prune rows whose workspace vanished, but keep routing rows alive in the
     // registry — they are data, not spawn instructions.
     const pruned = {};
+    // Windows: dedupe case-variant keys for the same workspace (C:\ vs c:\)
+    // left behind by pre-2.3.3 daemons — they map to the same pipe and every
+    // rewrite here would otherwise immortalize the phantom twin.
+    const seenKeys = new Set();
     for (const [ws, sock] of Object.entries(reg)) {
+        const canonical = process.platform === "win32" ? ws.toLowerCase() : ws;
+        if (seenKeys.has(canonical)) {
+            appendLog(`registry prune: ${ws} (case-variant duplicate)`);
+            continue;
+        }
+        seenKeys.add(canonical);
         const manifest = path.join(ws, ".vexp", "manifest.json");
         if (!fs.existsSync(manifest)) {
             appendLog(`registry prune: ${ws} (no manifest)`);