vexp-cli 2.3.1 → 2.4.0

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 } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -320,6 +320,18 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
+            // 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);
+            if (hintResult) {
+                results.push({
+                    agent: "Claude Code Hint",
+                    configFile: ".claude/hooks/vexp-hint.sh",
+                    content: vexpHintHookScript(binaryPath),
+                    alreadyExists: false,
+                    action: hintResult,
+                });
+            }
             // Guard is OPT-IN from 2.3 (see GuardMode): strict installs the
             // PreToolUse deny hook; default removes any previously installed one.
             if (guardMode() === "strict") {
@@ -349,6 +361,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.codex/config.toml");
+            installCodexHintHook(workspaceRoot, binaryPath);
         }
         // Antigravity: machine-global MCP config (~/.gemini/antigravity/mcp_config.json)
         if (detector.agent === "Antigravity") {
@@ -376,6 +389,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
             // Kilo v7 vendors opencode, so it takes the same guard plugin — the rules
             // markdown alone was demonstrably not enough (a reported session loaded
             // vexp.md, quoted it back, and still read five files by hand).
@@ -437,6 +451,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         // Claude Code PreToolUse hook) — which is only safe once MCP is registered.
         if (detector.agent === "Opencode") {
             const wroteMcp = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
             if (wroteMcp)
                 mcpConfigs.push(wroteMcp);
             if (guardMode() === "strict") {
@@ -607,6 +622,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
+            installClaudeCodeHintHook(workspaceRoot, binaryPath);
             if (guardMode() === "strict")
                 installClaudeCodeHook(workspaceRoot);
             else
@@ -616,6 +632,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureCodexGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
                 mcpConfigs.push("~/.codex/config.toml");
+            installCodexHintHook(workspaceRoot, binaryPath);
         }
         if (detector.agent === "Antigravity") {
             const wrote = configureAntigravityGlobal(binaryPath, mcpServerPath);
@@ -636,6 +653,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".opencode/plugin");
             if (guardMode() === "strict")
                 installOpencodePlugin(workspaceRoot);
             else
@@ -655,6 +673,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             const wrote = configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
                 mcpConfigs.push(wrote);
+            installOpencodeHintPlugin(workspaceRoot, binaryPath, ".kilo/plugin");
             if (guardMode() === "strict")
                 installKiloPlugin(workspaceRoot);
             else
@@ -1634,20 +1653,23 @@ export function installClaudeCodeHook(workspaceRoot) {
     const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
     // Aggressively remove ALL vexp-related hook entries (old format, stale matchers, malformed)
     const filtered = existingPreToolUse.filter((h) => !isVexpGuardHookEntry(h));
-    // Exec form (`args` present → direct spawn, no `sh -c`): the old shell-form
-    // `$CLAUDE_PROJECT_DIR/...` word-split on project paths containing spaces,
-    // so sh tried to exec the path's first fragment and the guard NEVER ran —
-    // non-blocking failure, every search went through unguarded. In exec form
-    // Claude Code substitutes `${CLAUDE_PROJECT_DIR}` itself (brace form
-    // required) before spawning. `timeout` is SECONDS (default 600), not ms:
-    // 3000 configured a 50-minute hook timeout.
+    // Shell form with an explicit `bash` prefix and a QUOTED path — the one
+    // shape that works on every OS Claude Code supports:
+    //  - the quotes fix the historical spaces bug (unquoted
+    //    `$CLAUDE_PROJECT_DIR/...` word-split and the guard never ran);
+    //  - exec form (`args` present → direct spawn) fixed spaces but broke
+    //    Windows entirely: the OS cannot spawn a `.sh` without a shell, the
+    //    hook errored, failed open, and enforced nothing (field report) —
+    //    Claude Code on Windows runs shell-form hooks through Git Bash, so
+    //    `bash "$VAR"` works there and on unix alike.
+    // `timeout` is SECONDS (default 600), not ms: 3000 once configured a
+    // 50-minute hook timeout.
     filtered.push({
         matcher: "Grep|Glob|Regex",
         hooks: [
             {
                 type: "command",
-                command: "${CLAUDE_PROJECT_DIR}/.claude/hooks/vexp-guard.sh",
-                args: [],
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh"',
                 timeout: 5,
             },
         ],
@@ -1667,6 +1689,144 @@ export function installClaudeCodeHook(workspaceRoot) {
     }
     return existed ? "updated" : "created";
 }
+function isVexpHintHookEntry(h) {
+    if (!h || typeof h !== "object")
+        return false;
+    const entry = h;
+    const own = entry.command?.includes("vexp-hint");
+    if (own)
+        return true;
+    const hks = entry.hooks;
+    return Array.isArray(hks) && hks.some((hook) => {
+        if (!hook || typeof hook !== "object")
+            return false;
+        return hook.command?.includes("vexp-hint") ?? false;
+    });
+}
+/**
+ * Install the event-driven hint hook for Claude Code (2.3.3 default).
+ * Replaces the resident CLAUDE.md strategy text: a UserPromptSubmit hook
+ * asks the daemon to classify each prompt against the index and injects a
+ * one-line run_pipeline suggestion ONLY for unfamiliar-area prompts. On
+ * oriented prompts the injection is empty — zero context cost. Fail-open by
+ * construction (see VEXP_HINT_HOOK): any failure = vanilla behavior.
+ * Non-blocking and additive, so it is NOT gated by guardMode (the 2.3 A2
+ * opt-in applies to DENY hooks, which add a failure mode; this one cannot
+ * block anything).
+ */
+export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, "vexp-hint.sh");
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const script = vexpHintHookScript(binaryPath);
+    fs.mkdirSync(hookDir, { recursive: true });
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === 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.UserPromptSubmit)
+        ? hooks.UserPromptSubmit
+        : [];
+    const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
+    // Same cross-OS shape as the guard entry: bash prefix + QUOTED path
+    // (spaces-safe on unix, Git Bash on Windows). timeout is SECONDS.
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-hint.sh"',
+                timeout: 5,
+            },
+        ],
+    });
+    const merged = { ...hooks, UserPromptSubmit: 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";
+}
+/**
+ * opencode/Kilo hint plugin (2.4.0): default-ON, non-blocking, fail-open —
+ * unlike the deny guard (strict-only), this cannot break a session; it only
+ * ever appends an orientation line the daemon judged useful.
+ */
+export function installOpencodeHintPlugin(workspaceRoot, binaryPath, pluginDir) {
+    const pluginPath = path.join(workspaceRoot, pluginDir, "vexp-hint.js");
+    const content = vexpOpencodeHintPlugin(binaryPath);
+    fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
+    const existed = fs.existsSync(pluginPath);
+    if (existed && fs.readFileSync(pluginPath, "utf-8") === content)
+        return null;
+    fs.writeFileSync(pluginPath, content);
+    return existed ? "updated" : "created";
+}
+/**
+ * Codex hint hook (2.4.0). Codex >=0.129 discovers `<repo>/.codex/hooks.json`
+ * and its UserPromptSubmit stdout envelope is byte-identical to Claude
+ * Code's (hookSpecificOutput.additionalContext), so the same prompt-hint
+ * backend serves both: PROJECT-scope file, no global config touched.
+ * Fail-open: missing bash/binary/daemon => no output => vanilla.
+ */
+export function installCodexHintHook(workspaceRoot, binaryPath) {
+    const dir = path.join(workspaceRoot, ".codex");
+    const hookPath = path.join(dir, "vexp-hint.sh");
+    const hooksJsonPath = path.join(dir, "hooks.json");
+    const script = vexpHintHookScript(binaryPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    if (!scriptIdentical) {
+        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    }
+    let root = {};
+    if (fs.existsSync(hooksJsonPath)) {
+        try {
+            root = JSON.parse(fs.readFileSync(hooksJsonPath, "utf-8"));
+        }
+        catch {
+            warnUnparseable(hooksJsonPath);
+            return scriptIdentical ? null : existed ? "updated" : "created";
+        }
+    }
+    // Codex hooks.json shape: EVENT NAME at top level (no "hooks" wrapper).
+    const existing = Array.isArray(root.UserPromptSubmit)
+        ? root.UserPromptSubmit
+        : [];
+    const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
+    // Absolute path: Codex has no $CLAUDE_PROJECT_DIR substitution.
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: `bash "${hookPath.replace(/\\/g, "/")}"`,
+                timeout: 5,
+            },
+        ],
+    });
+    const before = JSON.stringify(root.UserPromptSubmit ?? null);
+    root.UserPromptSubmit = filtered;
+    const identical = before === JSON.stringify(filtered);
+    if (scriptIdentical && identical)
+        return null;
+    if (!identical) {
+        fs.writeFileSync(hooksJsonPath, JSON.stringify(root, null, 2) + "\n");
+    }
+    return existed ? "updated" : "created";
+}
 // ---------------------------------------------------------------------------
 // opencode plugin - blocks grep/glob (and shelled-out search) when the daemon
 // is healthy. opencode has no PreToolUse hook, but auto-loads plugins from
@@ -1929,90 +2089,30 @@ function generateAgentConfig(template, vars) {
 // ---------------------------------------------------------------------------
 function claudeCodeTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
-
-### Context strategy: one pipeline call up front, then your normal tools
-For every multi-file task - bug fixes, features, refactors, debugging:
-**call \`run_pipeline\` ONCE at the start**. It executes context search + impact
-analysis + memory recall in a single call: which files matter, what breaks,
-what was learned before. Then implement with your normal tools.
-
-Division of labor (each tool where it wins):
-- **Architecture, impact, "where is X wired"**: \`run_pipeline\` - the graph
-  answers these better and cheaper than exploratory reading.
-- **Literal text sweeps** (string constants, log messages, config keys, e.g.
-  \`localStorage\`, API paths): Grep/Glob directly - text search is what they
-  are best at, do NOT route text sweeps through vexp.
-- **Editing**: Read the files you are about to modify; use \`get_skeleton\`
-  (detail: minimal/standard/detailed, 70-90% token savings) for files you only
+vexp runs entirely on this machine: local daemon, index in \`.vexp/\`.
+\`run_pipeline\` transmits nothing to any external service.
+- \`run_pipeline({ "task": "..." })\` - orientation in one call (ranked pivot
+  files with line ranges + blast radius + session notes) when a task does NOT
+  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.
+- vexp may append a one-line hint to a prompt when orientation would help;
+  otherwise it stays silent.
 
-Every extra tool call costs a turn: one good \`run_pipeline\` call beats five
-small ones. Each result opens with a coverage header (index: N files, M nodes) -
-if it does not match this repo, run \`vexp index\`.
-vexp only covers indexed source inside the workspace: for runtime logs, build
-output (dist/, .vite/, node_modules/) or files outside the repo use Bash/Read.
-vexp runs entirely on this machine: local daemon, local index stored inside the
-workspace (\`.vexp/\`). \`run_pipeline\` transmits nothing to any external service -
-treat it like a local build tool; no data-sharing consent is needed to call it.
-
-### Primary Tool
-- \`run_pipeline\` - **USE THIS FOR EVERYTHING**. Single call that runs
-  capsule + impact + memory server-side. Returns compressed results.
-  Auto-detects intent (debug/modify/refactor/explore) from your task.
-  Includes full file content for pivots.
-  Examples:
-  - \`run_pipeline({ "task": "fix JWT validation bug" })\` - auto-detect
-  - \`run_pipeline({ "task": "refactor db layer", "preset": "refactor" })\` - explicit
-  - \`run_pipeline({ "task": "add auth", "observation": "using JWT" })\` - save insight in same call
-
-### Other MCP tools (use only when run_pipeline is insufficient)
-- \`get_skeleton\` - **preferred over Read** for inspecting files (minimal/standard/detailed detail levels, 70-90% token savings)
-- \`index_status\` - indexing status and health check
-- \`expand_vexp_ref\` - expand V-REF hash placeholders in v2 compact output
-
-${QUERY_SHAPE}
-
-### Workflow
-1. \`run_pipeline("your task")\` - ONCE at task start. Returns pivots + impact + memories in 1 call
-2. Literal string sweeps? Grep/Glob directly. Editing a file? Read it directly.
-3. Structural overview of a non-edit file? \`get_skeleton({ files: [...], detail: "detailed" })\`
-4. Make targeted changes based on the context returned
-5. \`run_pipeline\` again ONLY when the task moves to a new area - do NOT chain vexp calls per turn
-
-### Subagent / Explore / Plan mode
-- Subagents CAN call \`run_pipeline\` - always include the task description
-- Before spawning Agent(Explore) for architecture questions, call \`run_pipeline\`
-  and pass the returned context into the agent prompt - it usually replaces the
-  exploration entirely
-
-### Smart Features (automatic - no action needed)
-- **Intent Detection**: auto-detects from your task keywords. "fix bug" -> Debug, "refactor" -> blast-radius, "add" -> Modify
-- **Hybrid Search**: keyword + semantic + graph centrality ranking
-- **Session Memory**: auto-captures observations; memories auto-surfaced in results
-- **LSP Bridge**: VS Code captures type-resolved call edges
-- **Change Coupling**: co-changed files included as related context
-
-### Advanced Parameters
-- \`preset: "debug"\` - forces debug mode (capsule+tests+impact+memory)
-- \`preset: "refactor"\` - deep impact analysis (depth 5)
-- \`max_tokens: 12000\` - increase total budget for complex tasks
-- \`include_tests: true\` - include test files in results
-- \`include_file_content: false\` - omit full file content (lighter response)
-
-### Fallback
-If \`run_pipeline\` returns \`status: "degraded"\` or 0 pivots with an INDEX EMPTY warning,
-the index is empty or rebuilding. Use Grep, Glob, and Read directly until the index is ready.
-
-### Multi-Repo Workspaces
-\`run_pipeline\` auto-queries all indexed repos. Use \`repos: ["alias"]\` to scope.
-Use \`index_status\` to discover available repo aliases.
+### Query shape (do this)
+Anchor the task on real identifiers (ClassName, functionName) or file paths:
+\`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 <!-- /vexp -->`;
 }
 function cursorTemplate(vars) {
     return `## vexp rules for Cursor <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2032,6 +2132,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2059,7 +2163,11 @@ function windsurfTemplate(vars) {
     return `## vexp for Windsurf <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2079,6 +2187,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2117,7 +2229,11 @@ function augmentTemplate(vars) {
     return `## vexp for Augment <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2137,6 +2253,10 @@ When working on this codebase:
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2156,7 +2276,11 @@ function copilotTemplate(vars) {
     return `## vexp context tools <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2176,6 +2300,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2195,7 +2323,11 @@ function zedTemplate(vars) {
     return `## vexp for Zed <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2215,6 +2347,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ### Agentic search
@@ -2234,7 +2370,11 @@ function agentsMdTemplate(vars) {
     return `## vexp <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2276,7 +2416,11 @@ function kiroTemplate(vars) {
     return `# vexp steering <!-- vexp v${vars.version} -->
 
 **Call \`run_pipeline\` ONCE at task start for orientation - then use your normal tools.**
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 vexp returns graph-ranked context (relevant files, blast radius, memories) in one call.
+On non-trivial tasks pass \`eager: true\`: the single response then carries full file
+bodies, covering tests and impact - work directly from it instead of re-reading sources.
 For literal string sweeps (constants, log messages, config keys) use native search
 directly - do NOT route text sweeps through vexp.
 vexp runs entirely on this machine: local daemon, local index stored inside the
@@ -2296,6 +2440,10 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+(Recommended core set, not the full schema: paid plans advertise 14 MCP tools -
+capsule, impact graph, logic flow, memory and more. \`run_pipeline\` already runs
+those server-side, so the four above cover the normal workflow.)
+
 ${QUERY_SHAPE}
 
 ## Agentic search
@@ -2315,6 +2463,8 @@ function genericTemplate(vars) {
     return `## vexp - Context-Aware AI Coding <!-- vexp v${vars.version} -->
 
 ### Context strategy: call run_pipeline ONCE at task start
+If the task already names the files/symbols to touch, skip vexp and work
+with your normal tools - a skipped call costs nothing.
 For every multi-file task - bug fixes, features, refactors, questions about the code:
 **start with one \`run_pipeline\` call**. It runs context search + impact analysis +
 memory recall in a single call and returns compressed, graph-ranked results: the

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",