vexp-cli 2.3.1 → 2.5.0

package/dist/doctor.js

@@ -151,13 +151,43 @@ 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) {
                 // Embedded caveat: a stdio MCP server (`vexp-core mcp`) spawned while
                 // the daemon was unreachable serves from its own in-process index and
@@ -207,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)) {
@@ -220,7 +256,15 @@ 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`);
@@ -310,31 +354,39 @@ export async function runDoctor() {
         else if (guardHooks.length === 0) {
             line(OK, "no vexp guard configured (2.3 default — enable with 'vexp setup --guard-strict')");
         }
-        else if (process.platform === "win32") {
-            line(OK, `guard configured (${guardHooks.length} entry) — live execution check skipped on Windows`);
-        }
         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 ('args' missing) — 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 in exec form.`);
+                    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 = sh -c with
-                // CLAUDE_PROJECT_DIR in the environment.
+                // 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("sh", ["-c", cmd], {
+                    : spawnSync(shell, ["-c", cmd], {
                         env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
                         timeout: 5000,
                         encoding: "utf-8",

package/dist/hook-template.js

@@ -374,3 +374,138 @@ 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, "/"));
+}
+/**
+ * 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
+ * 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 + idle verification (fail-open). Managed by vexp.
+const VEXP_BIN = "__VEXP_BIN__";
+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) => {
+      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;
+        // 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, session_id: sid }),
+          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 */ }
+    },
+    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 */ }
+    },
+  };
+};
+`;
+/** 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/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/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)`);

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);
     }
 }