vexp-cli 2.5.3 → 2.6.1

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, vexpStopGateHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -133,6 +133,17 @@ const AGENT_DETECTORS = [
         configFile: ".continue/config.json",
         templateName: "continue",
     },
+    {
+        // Cline keeps rules in the project (.clinerules) but its MCP registry is
+        // machine-global VS Code storage — handled by configureClineMcp() below.
+        // Detected either by an existing .clinerules or by the extension's
+        // globalStorage directory (Cline installed on this machine).
+        agent: "Cline",
+        detectPath: ".clinerules",
+        configFile: ".clinerules",
+        templateName: "cline",
+        detectAbsPaths: clineStorageDirs,
+    },
     {
         agent: "Augment",
         detectPath: ".augment",
@@ -221,6 +232,72 @@ const AGENT_DETECTORS = [
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/**
+ * Everything a real (non dry-run) setup writes for one agent, as
+ * human-readable lines.
+ *
+ * This exists because `--dry-run` used to print only `configFile` and
+ * `mcpConfigFile` from the detector metadata, so hooks, plugins and the
+ * user-scope MCP entry were invisible. A user comparing that output
+ * against his `.claude/settings.json` concluded the hint hook was never
+ * installed by design (field report, 2026-08) — the dry run was telling a
+ * true but badly incomplete story. Kept next to the installers, with a
+ * lockstep test asserting every detector has an entry.
+ */
+export function plannedWrites(agent, guard = guardMode()) {
+    const det = AGENT_DETECTORS.find((d) => d.agent === agent);
+    if (!det)
+        return [];
+    const out = [`${det.configFile}  (instructions)`];
+    if (det.mcpConfigFile)
+        out.push(`${det.mcpConfigFile}  (MCP server entry)`);
+    switch (agent) {
+        case "Claude Code":
+            out.push("~/.claude.json  (MCP server entry, user scope)");
+            out.push(".claude/hooks/vexp-hint.sh + settings.json hooks.UserPromptSubmit  (orientation)");
+            out.push(".claude/hooks/vexp-verify.sh + settings.json hooks.Stop  (verification gate)");
+            out.push(".claude/hooks/vexp-restore.sh + settings.json hooks.SessionStart  (context restore)");
+            if (guard === "strict") {
+                out.push(".claude/hooks/vexp-guard.sh + settings.json hooks.PreToolUse  (guard, opt-in)");
+            }
+            break;
+        case "Codex":
+            out.push("~/.codex/config.toml or .codex/config.toml  (MCP server entry)");
+            out.push(".codex/vexp-hint.sh + .codex/hooks.json hooks.UserPromptSubmit  (orientation)");
+            break;
+        case "Cline":
+            out.push("cline_mcp_settings.json in each installed VS Code variant  (MCP, machine-global)");
+            break;
+        case "Opencode":
+            out.push("opencode.json(c) `mcp` key  (MCP server entry)");
+            out.push(".opencode/plugin/vexp-hint.js  (orientation + idle verification)");
+            if (guard === "strict")
+                out.push(".opencode/plugins/vexp-guard.js  (guard, opt-in)");
+            break;
+        case "Kilo Code":
+            out.push("kilo.jsonc `mcp` key  (MCP server entry)");
+            out.push(".kilo/plugin/vexp-hint.js  (orientation + idle verification)");
+            if (guard === "strict")
+                out.push(".kilo/plugins/vexp-guard.js  (guard, opt-in)");
+            break;
+        case "Antigravity":
+            out.push("~/.gemini/antigravity MCP config  (user scope)");
+            break;
+        case "Zed":
+            out.push(".zed/settings.json `context_servers`  (MCP server entry)");
+            break;
+        case "Cursor":
+            if (guard === "strict")
+                out.push(".cursor/hooks/vexp-guard.js + .cursor/hooks.json  (guard, opt-in)");
+            break;
+        case "GitHub Copilot":
+            out.push(".vscode/mcp.json  (MCP server entry)");
+            break;
+        default:
+            break;
+    }
+    return out;
+}
 /**
  * Detect which AI coding agents are present in the workspace.
  */
@@ -235,6 +312,9 @@ export function detectAgents(workspaceRoot) {
         if (d.detectHome && fs.existsSync(path.join(os.homedir(), d.detectHome))) {
             return true;
         }
+        if (d.detectAbsPaths && d.detectAbsPaths().some((p) => fs.existsSync(p))) {
+            return true;
+        }
         return false;
     });
 }
@@ -324,6 +404,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
             const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
             installClaudeCodeStopGate(workspaceRoot, binaryPath);
+            installClaudeCodeSessionContext(workspaceRoot, binaryPath);
             if (hintResult) {
                 results.push({
                     agent: "Claude Code Hint",
@@ -445,6 +526,16 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
                 });
             }
         }
+        // Cline: rules in .clinerules (generic template, handled by the writer
+        // above); MCP registry is machine-global VS Code storage.
+        if (detector.agent === "Cline") {
+            const wrote = configureClineMcp(workspaceRoot, binaryPath);
+            for (const w of wrote) {
+                mcpConfigs.push(w);
+            }
+            if (wrote.length === 0)
+                noteClineMcpUnreachable();
+        }
         // Opencode: MCP lives under the `mcp` key in opencode.json(c) — opencode
         // carries no `mcpConfigFile`, so without this call the generic writer above
         // skips it and setup registers no tool at all. Plus the guard plugin that
@@ -559,9 +650,14 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
     for (const detector of AGENT_DETECTORS) {
         if (!selectedAgentNames.includes(detector.agent))
             continue;
-        // Create agent directory if it doesn't exist (skip for file-based detectPaths like AGENTS.md)
+        // Create agent directory if it doesn't exist. Skip for file-based
+        // detectPaths: extension-bearing markers (AGENTS.md) and extensionless
+        // file markers where the marker IS the config file (.clinerules) —
+        // mkdir-ing those creates a directory where a file must go (EISDIR).
         const detectAbsPath = path.join(workspaceRoot, detector.detectPath);
-        if (!fs.existsSync(detectAbsPath) && !path.extname(detector.detectPath)) {
+        if (!fs.existsSync(detectAbsPath) &&
+            !path.extname(detector.detectPath) &&
+            detector.detectPath !== detector.configFile) {
             fs.mkdirSync(detectAbsPath, { recursive: true });
         }
         // Create parent directory for configFile (handles nested paths like .kiro/steering/vexp.md)
@@ -625,6 +721,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
                 mcpConfigs.push("~/.claude.json");
             installClaudeCodeHintHook(workspaceRoot, binaryPath);
             installClaudeCodeStopGate(workspaceRoot, binaryPath);
+            installClaudeCodeSessionContext(workspaceRoot, binaryPath);
             if (guardMode() === "strict")
                 installClaudeCodeHook(workspaceRoot);
             else
@@ -651,6 +748,13 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (writeZedMcpConfig(zedPath, binaryPath, mcpServerPath, workspaceRoot))
                 mcpConfigs.push(".zed/settings.json");
         }
+        if (detector.agent === "Cline") {
+            const wrote = configureClineMcp(workspaceRoot, binaryPath);
+            for (const w of wrote)
+                mcpConfigs.push(w);
+            if (wrote.length === 0)
+                noteClineMcpUnreachable();
+        }
         if (detector.agent === "Opencode") {
             const wrote = configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath);
             if (wrote)
@@ -862,7 +966,47 @@ function atomicWriteFileSync(filePath, content) {
     }
 }
 /** Warn that we refused to touch an unparseable config file. */
+/**
+ * Config files we refused to touch because they would not parse. A stderr
+ * line was not enough: it scrolls past inside a spinner-driven setup, and a
+ * user then reasonably concludes the feature was never installed rather
+ * than that ONE write was skipped (field report: an unparseable
+ * `.claude/settings.json` silently cost the whole hint hook, and the
+ * session looked like vexp had no injection path at all). Collected here
+ * and surfaced as a block at the END of setup.
+ */
+const skippedConfigs = [];
+/** Drain the skipped-config list (call after a setup run to report it). */
+export function takeSkippedConfigs() {
+    return skippedConfigs.splice(0, skippedConfigs.length);
+}
+/**
+ * Configuration an agent needs that has no target on this machine yet. Kept
+ * apart from `skippedConfigs` (which means "malformed JSON, we refused to
+ * touch it"): the cause and the fix are different, and merging them would
+ * tell a user to repair a file that does not exist.
+ */
+const unreachableTargets = [];
+/** Drain the unreachable-target list (call after a setup run to report it). */
+export function takeUnreachableTargets() {
+    return unreachableTargets.splice(0, unreachableTargets.length);
+}
+/**
+ * Cline keeps its MCP registry inside the VS Code extension's globalStorage,
+ * so there is nothing to write until the extension has been installed once.
+ * The user still asked for Cline, and half a configuration (rules written,
+ * tools missing) looks from the inside exactly like vexp not working.
+ */
+function noteClineMcpUnreachable() {
+    const msg = "Cline MCP registry (cline_mcp_settings.json): no Cline install found in any VS Code variant. " +
+        ".clinerules was written, but Cline has no vexp tools until the extension is installed and setup re-run.";
+    if (!unreachableTargets.includes(msg))
+        unreachableTargets.push(msg);
+}
 function warnUnparseable(filePath) {
+    if (!skippedConfigs.includes(filePath)) {
+        skippedConfigs.push(filePath);
+    }
     process.stderr.write(`  [!] ${filePath} could not be parsed - leaving it untouched. Fix the file or add vexp manually, then re-run setup.\n`);
 }
 function appendOrCreate(filePath, content, version) {
@@ -1327,6 +1471,61 @@ export function opencodeConfigTarget(workspaceRoot) {
  * file is backed up before rewrite. Returns the workspace-relative path written,
  * or null on a no-op / unparseable file.
  */
+/** Cline's globalStorage dirs across OSes and VS Code variants: the marker
+ * that Cline is installed, and the parent of its MCP settings file. */
+function clineStorageDirs() {
+    const home = os.homedir();
+    const base = process.platform === "win32"
+        ? (process.env.APPDATA ?? path.join(home, "AppData", "Roaming"))
+        : process.platform === "darwin"
+            ? path.join(home, "Library", "Application Support")
+            : path.join(home, ".config");
+    return ["Code", "Code - Insiders", "VSCodium"].map((variant) => path.join(base, variant, "User", "globalStorage", "saoudrizwan.claude-dev"));
+}
+/**
+ * Cline: MCP servers live in a MACHINE-GLOBAL file per VS Code variant
+ * (globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json),
+ * not in the workspace. We write the vexp entry into every variant where
+ * Cline is actually installed (storage dir exists), pinning the workspace
+ * with an explicit --workspace flag: Cline gives no cwd guarantee for
+ * spawned servers, and a global file cannot rely on one. Re-running setup
+ * from another project repins — same trade-off as every global-registry
+ * agent. VEXP_ALL_TOOLS=1 because Cline has no hook channel: the agent
+ * only has tools + rules, so it gets the full tool set.
+ */
+export function configureClineMcp(workspaceRoot, binaryPath) {
+    const written = [];
+    for (const storeDir of clineStorageDirs()) {
+        if (!fs.existsSync(storeDir))
+            continue;
+        const target = path.join(storeDir, "settings", "cline_mcp_settings.json");
+        const read = readJsonConfigSafe(target);
+        if (!read.ok) {
+            warnUnparseable(target);
+            continue;
+        }
+        const cfg = read.data;
+        const servers = cfg.mcpServers ?? {};
+        const entry = {
+            command: binaryPath,
+            args: ["mcp", "--workspace", workspaceRoot],
+            env: { VEXP_ALL_TOOLS: "1" },
+            disabled: false,
+            autoApprove: [],
+        };
+        const prev = servers["vexp"];
+        if (JSON.stringify(prev) === JSON.stringify(entry))
+            continue;
+        servers["vexp"] = entry;
+        cfg.mcpServers = servers;
+        if (read.existed)
+            backupConfig(target);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, JSON.stringify(cfg, null, 2), "utf-8");
+        written.push(target);
+    }
+    return written;
+}
 export function configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath) {
     const target = opencodeConfigTarget(workspaceRoot);
     const read = readJsonConfigSafe(target);
@@ -1711,6 +1910,55 @@ function isVexpHookEntry(h, needle) {
  * references (parse errors, imports of removed names). No daemon = no
  * gate = vanilla stop. Additive like the hint hook, so not guardMode-gated.
  */
+/**
+ * v3 context lifecycle: SessionStart restore hook for Claude Code. The
+ * script exits silently on fresh starts; only compact/resume get the
+ * one-paragraph context restore from the Rust side. Additive and
+ * fail-open like the hint hook.
+ */
+export function installClaudeCodeSessionContext(workspaceRoot, binaryPath) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, "vexp-restore.sh");
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    fs.mkdirSync(hookDir, { recursive: true });
+    const script = vexpSessionContextHookScript(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.SessionStart)
+        ? hooks.SessionStart
+        : [];
+    const filtered = existing.filter((h) => !isVexpHookEntry(h, "vexp-restore"));
+    filtered.push({
+        hooks: [
+            {
+                type: "command",
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-restore.sh"',
+                timeout: 5,
+            },
+        ],
+    });
+    const merged = { ...hooks, SessionStart: 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";
+}
 export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
     const hookPath = path.join(hookDir, "vexp-verify.sh");
@@ -1866,10 +2114,26 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
             return scriptIdentical ? null : existed ? "updated" : "created";
         }
     }
-    // Codex hooks.json shape: EVENT NAME at top level (no "hooks" wrapper).
-    const existing = Array.isArray(root.UserPromptSubmit)
+    // Codex hooks.json shape: events live UNDER a top-level `hooks` object.
+    // We used to write the event name at top level, which older Codex accepted
+    // and 0.147 rejects outright ("unknown field `UserPromptSubmit`, expected
+    // `description` or `hooks`") — the whole file fails to parse, so EVERY
+    // hook in it dies, not only ours (field report, 2026-08).
+    //
+    // Migration matters as much as the new shape: a file left with both the
+    // legacy top-level key and the new wrapper still trips the same unknown
+    // field error. Any pre-existing top-level `UserPromptSubmit` array is
+    // MOVED into the wrapper (the user's own entries included) and the legacy
+    // key removed.
+    const legacyTopLevel = Array.isArray(root.UserPromptSubmit)
         ? root.UserPromptSubmit
         : [];
+    delete root.UserPromptSubmit;
+    const codexHooks = (root.hooks ?? {});
+    const wrapped = Array.isArray(codexHooks.UserPromptSubmit)
+        ? codexHooks.UserPromptSubmit
+        : [];
+    const existing = [...wrapped, ...legacyTopLevel];
     const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
     // Absolute path: Codex has no $CLAUDE_PROJECT_DIR substitution.
     filtered.push({
@@ -1881,9 +2145,10 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
             },
         ],
     });
-    const before = JSON.stringify(root.UserPromptSubmit ?? null);
-    root.UserPromptSubmit = filtered;
-    const identical = before === JSON.stringify(filtered);
+    const before = JSON.stringify(root);
+    codexHooks.UserPromptSubmit = filtered;
+    root.hooks = codexHooks;
+    const identical = before === JSON.stringify(root);
     if (scriptIdentical && identical)
         return null;
     if (!identical) {
@@ -2162,7 +2427,8 @@ vexp runs entirely on this machine: local daemon, index in \`.vexp/\`.
   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.
+  errors), untouched dependents of the files you changed (file:line), and
+  the impacted tests - RUN those tests before declaring done.
 - vexp may append a one-line hint to a prompt when orientation would help;
   otherwise it stays silent.
 
@@ -2197,7 +2463,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
   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.
+  mechanically broken references, untouched dependents, and impacted tests
+  to RUN before declaring done, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2254,7 +2521,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
   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.
+  mechanically broken references, untouched dependents, and impacted tests
+  to RUN before declaring done, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2322,7 +2590,8 @@ When working on this codebase:
   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.
+  mechanically broken references, untouched dependents, and impacted tests
+  to RUN before declaring done, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2371,7 +2640,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
   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.
+  mechanically broken references, untouched dependents, and impacted tests
+  to RUN before declaring done, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2420,7 +2690,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
   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.
+  mechanically broken references, untouched dependents, and impacted tests
+  to RUN before declaring done, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2469,7 +2740,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
   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.
+  mechanically broken references, untouched dependents, and impacted tests
+  to RUN before declaring done, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2517,7 +2789,8 @@ treat it like a local build tool; no data-sharing consent is needed to call it.
   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.
+  mechanically broken references, untouched dependents, and impacted tests
+  to RUN before declaring done, with file:line.
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
@@ -2561,7 +2834,8 @@ Then implement with your normal tools:
   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.
+  parse errors), untouched dependents of your changes (file:line), and the
+  impacted tests - RUN those tests before declaring done.
 
 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

@@ -8,7 +8,7 @@ import * as fs from "fs";
 import * as net from "net";
 import { checkbox, confirm } from "@inquirer/prompts";
 import { getBinaryPath, getInstalledVersion, getMcpServerPath, binaryEnv } from "./binary.js";
-import { detectAgents, getAgentList, configureSelectedAgents, resolveAgentName, suggestAgentName, setGuardMode } from "./agent-config.js";
+import { detectAgents, getAgentList, configureSelectedAgents, resolveAgentName, suggestAgentName, setGuardMode, plannedWrites, takeSkippedConfigs, takeUnreachableTargets } from "./agent-config.js";
 import { CLI_VERSION } from "./version.js";
 import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocked, } from "./license.js";
 import { checkForUpdate } from "./update-check.js";
@@ -306,7 +306,26 @@ async function startBackgroundServices(binaryPath, workspaceRoot) {
             spinnerMcp.warn(`Port ${result.port} already bound by an unknown process`);
         }
         else if (result.started) {
-            spinnerMcp.succeed(`MCP HTTP server started (pid=${result.pid}, port=${result.port})`);
+            // Announce a live server, not a spawn attempt. The child can exit
+            // immediately (port taken, missing runtime) and the success line was
+            // printed regardless, leaving users looking for a pid that never
+            // existed (field report, 2026-08). One short settle, then verify.
+            await new Promise((r) => setTimeout(r, 400));
+            let alive = false;
+            try {
+                process.kill(result.pid, 0);
+                alive = true;
+            }
+            catch {
+                alive = false;
+            }
+            if (alive) {
+                spinnerMcp.succeed(`MCP HTTP server started (pid=${result.pid}, port=${result.port})`);
+            }
+            else {
+                spinnerMcp.warn(`MCP HTTP server exited immediately after start (pid=${result.pid} is gone). ` +
+                    `Check ~/.vexp/mcp.log; vexp works without it, the shared HTTP bridge is optional.`);
+            }
         }
         else {
             spinnerMcp.succeed(`MCP HTTP server already running (pid=${result.pid}, port=${result.port})`);
@@ -456,10 +475,11 @@ program
 });
 program
     .command("verify")
-    .description("Mechanical completion check of the working tree: parse errors, broken imports, dependents of changed files not yet touched (advice, never a block)")
+    .description("Mechanical completion check of the working tree: parse errors, broken imports, untouched dependents, impacted tests to run (advice, never a block)")
     .option("--json", "Emit raw JSON instead of the human report")
     .option("--task-file <path>", "Task/instruction text: also checks instruction-level oracles (forbidden paths, promised artifacts)")
     .option("--gate", "CI gate mode (Horizon): exit 2 on any mechanical violation")
+    .option("--run-tests", "Execute the impacted tests with the repo's own runner (bounded: 5 files/300s) and report pass/fail")
     .action(async (opts) => {
     const binaryPath = ensureBinary();
     const args = ["verify"];
@@ -469,6 +489,8 @@ program
         args.push("--task-file", opts.taskFile);
     if (opts.gate)
         args.push("--gate");
+    if (opts.runTests)
+        args.push("--run-tests");
     runBinary(binaryPath, args);
 });
 program
@@ -627,12 +649,14 @@ program
         spinner1.fail(`Binary not found: ${err}`);
         process.exit(1);
     }
+    // Set once the agents are known: only editor-hosted ones need a restart.
+    let editorHosted = false;
     const isPersonal = !!opts.personal;
     if (isPersonal) {
         console.log(chalk.cyan("  Personal mode: skipping agent configs and git hooks\n"));
     }
     // Step 2: Init + Index
-    if (opts.index !== false) {
+    if (opts.index !== false && !opts.dryRun) {
         const spinner2 = ora("Indexing codebase...").start();
         try {
             const initArgs = ["init", workspaceRoot];
@@ -649,10 +673,15 @@ program
     else {
         console.log(chalk.dim("  Skipping indexing (--no-index)"));
     }
-    // Step 2.5: Start daemon + MCP HTTP server (survive terminal close)
-    await startBackgroundServices(binaryPath, workspaceRoot);
+    // Step 2.5: Start daemon + MCP HTTP server (survive terminal close).
+    // A dry run must not start processes: --dry-run used to index, install
+    // git hooks, spawn the daemon and bind an HTTP port, and only the final
+    // agent-config step was actually simulated (field report, 2026-08).
+    if (!opts.dryRun) {
+        await startBackgroundServices(binaryPath, workspaceRoot);
+    }
     // In personal mode, make .vexp/ fully gitignored
-    if (isPersonal) {
+    if (isPersonal && !opts.dryRun) {
         const vexpGitignore = path.join(workspaceRoot, ".vexp", ".gitignore");
         const fs = await import("fs");
         fs.mkdirSync(path.join(workspaceRoot, ".vexp"), { recursive: true });
@@ -718,15 +747,17 @@ program
         // Step 4: Configure selected agents
         if (selectedNames.length > 0) {
             if (opts.dryRun) {
-                console.log(chalk.dim("\n  --dry-run: would configure:"));
+                // Every artifact a real run writes, not just the instruction
+                // file: hooks and user-scope MCP entries used to be invisible
+                // here, which read as "vexp installs nothing else".
+                console.log(chalk.dim("\n  --dry-run: would write:"));
                 for (const name of selectedNames) {
-                    const agent = allAgents.find((a) => a.agent === name);
-                    if (agent) {
-                        console.log(chalk.dim(`    ${agent.agent} → ${agent.configFile}`));
-                        if (agent.mcpConfigFile)
-                            console.log(chalk.dim(`      MCP: ${agent.mcpConfigFile}`));
+                    console.log(chalk.dim(`    ${name}:`));
+                    for (const line of plannedWrites(name)) {
+                        console.log(chalk.dim(`      - ${line}`));
                     }
                 }
+                console.log(chalk.dim("\n  Nothing was written (dry run)."));
             }
             else {
                 const spinner4 = ora("Writing agent configurations...").start();
@@ -734,6 +765,13 @@ program
                 const mcpServerPath = getMcpServerPath();
                 const result = configureSelectedAgents(workspaceRoot, binaryPath, version, selectedNames, mcpServerPath);
                 spinner4.succeed("Agent configurations written");
+                // Only editor-hosted agents need the host restarted. Telling a
+                // Codex-only or Claude-Code-only user to restart VS Code invites
+                // exactly the question we keep getting: "do I need VS Code for
+                // this?" (AppSumo, 2026-08). The answer is no, and the summary
+                // should not imply otherwise.
+                const TERMINAL_AGENTS = new Set(["Claude Code", "Codex", "Opencode"]);
+                editorHosted = result.agents.some((a) => !TERMINAL_AGENTS.has(a.agent));
                 console.log("");
                 for (const agent of result.agents) {
                     const icon = agent.action === "skipped" ? "○" : "●";
@@ -754,6 +792,29 @@ program
                         console.log(chalk.dim(`    ${mcpFile}`));
                     }
                 }
+                // Files we refused to touch because they would not parse. This
+                // used to be a stderr line mid-spinner: it scrolled away, and a
+                // skipped settings.json silently cost the whole hook (field
+                // report, 2026-08). It is a visible, actionable block now.
+                const skipped = takeSkippedConfigs();
+                if (skipped.length > 0) {
+                    console.log("");
+                    console.log(chalk.yellow(`  ⚠ ${skipped.length} config file(s) were NOT updated - they are not valid JSON:`));
+                    for (const f of skipped)
+                        console.log(chalk.yellow(`    ${f}`));
+                    console.log(chalk.yellow("    Anything vexp installs through those files (hooks, MCP entries) is MISSING."));
+                    console.log(chalk.yellow("    We tolerate comments and trailing commas, so this is genuinely malformed"));
+                    console.log(chalk.yellow("    (usually an unbalanced brace from a half-finished edit). Fix it and re-run setup."));
+                }
+                // Agents selected whose config target does not exist on this
+                // machine yet: rules land, tools do not, and nothing said so.
+                const unreachable = takeUnreachableTargets();
+                if (unreachable.length > 0) {
+                    console.log("");
+                    console.log(chalk.yellow(`  ⚠ ${unreachable.length} agent config(s) could not be written yet:`));
+                    for (const f of unreachable)
+                        console.log(chalk.yellow(`    ${f}`));
+                }
             }
         }
     }
@@ -795,6 +856,15 @@ program
     }
     // Final summary
     console.log("");
+    if (opts.dryRun) {
+        // A dry run wrote nothing and started nothing: claiming otherwise is
+        // exactly the optimistic summary that hides a failed setup.
+        console.log(chalk.green.bold("✓ dry run complete — nothing was written."));
+        console.log("");
+        console.log("Re-run without --dry-run to apply the plan above.");
+        console.log("");
+        return;
+    }
     console.log(chalk.green.bold("✓ vexp setup complete!"));
     console.log("");
     if (isPersonal) {
@@ -806,9 +876,11 @@ program
         console.log("The vexp daemon is running and ready to serve context.");
     }
     console.log("");
-    console.log(chalk.yellow("⚠ If VS Code is open, restart it to load the new agent configurations."));
-    console.log(chalk.dim("  (or reload window: Ctrl+Shift+P → \"Developer: Reload Window\")"));
-    console.log("");
+    if (editorHosted) {
+        console.log(chalk.yellow("⚠ If your editor is open, restart it to load the new agent configurations."));
+        console.log(chalk.dim("  (VS Code and its forks: Ctrl+Shift+P → \"Developer: Reload Window\")"));
+        console.log("");
+    }
 });
 // ────────────────────────────────────────────────────
 // Command: setup-agents (interactive checkbox select)

package/dist/doctor.js

@@ -407,6 +407,126 @@ export async function runDoctor() {
             }
         }
     }
+    // 5b-bis) Claude Code orientation/verification hooks. The guard is opt-in
+    // and usually absent; THESE are what setup installs by default, and when
+    // setup skipped them silently the whole layer was inert while every other
+    // check reported healthy — a third-party evaluation lost two days to
+    // exactly that (2026-08). Presence is not enough: run them.
+    // Git hooks are how the index refreshes on commit/merge/checkout. Git obeys
+    // core.hooksPath exclusively, so with it set our hooks sit in .git/hooks and
+    // never run, while every surface reports them installed (field report).
+    console.log(chalk.bold("\nGit hooks (index refresh)"));
+    {
+        const hooksPath = (() => {
+            const r = spawnSync("git", ["config", "--get", "core.hooksPath"], {
+                cwd: ws.root,
+                encoding: "utf-8",
+                timeout: 5000,
+            });
+            const v = String(r.stdout ?? "").trim();
+            return r.status === 0 && v ? v : null;
+        })();
+        const ours = path.join(ws.root, ".git", "hooks");
+        const installed = ["pre-commit", "post-merge", "post-checkout"].filter((h) => {
+            try {
+                return fs.readFileSync(path.join(ours, h), "utf-8").includes("vexp");
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!hooksPath) {
+            if (installed.length === 3)
+                line(OK, "vexp hooks present in .git/hooks and git will run them");
+            else if (installed.length === 0)
+                line(OK, "no vexp git hooks (index refreshes on demand)");
+            else
+                line(WARN, `only ${installed.length}/3 vexp git hooks present — re-run 'vexp hooks install'`);
+        }
+        else {
+            const resolved = path.isAbsolute(hooksPath) ? hooksPath : path.join(ws.root, hooksPath);
+            const sameDir = path.resolve(resolved) === path.resolve(ours);
+            if (sameDir) {
+                line(OK, `core.hooksPath points at .git/hooks (${installed.length}/3 vexp hooks present)`);
+            }
+            else if (installed.length > 0) {
+                line(BAD, `core.hooksPath = ${resolved} — git runs hooks ONLY from there, so the ${installed.length} vexp hook(s) in .git/hooks NEVER run and the index does not refresh on commit/merge/checkout. Add 'vexp index --finalize || true' to ${path.join(resolved, "pre-commit")}, or 'git config --unset core.hooksPath' for this repo.`);
+            }
+            else {
+                line(OK, `core.hooksPath = ${resolved} (no vexp git hooks installed here)`);
+            }
+        }
+    }
+    console.log(chalk.bold("\nClaude Code orientation hooks (.claude/settings.json)"));
+    {
+        const sPath = path.join(ws.root, ".claude", "settings.json");
+        const wanted = [
+            { event: "UserPromptSubmit", marker: "vexp-hint", label: "orientation" },
+            { event: "Stop", marker: "vexp-verify", label: "verification gate" },
+            { event: "SessionStart", marker: "vexp-restore", label: "context restore" },
+        ];
+        let settings = null;
+        try {
+            settings = JSON.parse(fs.readFileSync(sPath, "utf-8"));
+        }
+        catch { /* absent or unparseable */ }
+        const mcpConfigured = (() => {
+            try {
+                const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".claude.json"), "utf-8"));
+                return Boolean(cfg?.mcpServers?.vexp);
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (!settings) {
+            // Only a finding for someone who actually uses Claude Code here.
+            line(mcpConfigured ? WARN : OK, mcpConfigured
+                ? "no .claude/settings.json, but vexp MCP is configured for Claude Code — the orientation hooks were never installed. Run 'vexp setup' (use --dry-run first to see what it would write)."
+                : "no .claude/settings.json (Claude Code not configured here)");
+        }
+        else {
+            for (const w of wanted) {
+                const entries = Array.isArray(settings?.hooks?.[w.event]) ? settings.hooks[w.event] : [];
+                const hook = entries
+                    .flatMap((m) => (Array.isArray(m?.hooks) ? m.hooks : []))
+                    .find((h) => typeof h?.command === "string" && h.command.includes(w.marker));
+                if (!hook) {
+                    line(WARN, `${w.event} (${w.label}) not installed — re-run 'vexp setup' to write it.`);
+                    continue;
+                }
+                const scriptPath = path.join(ws.root, ".claude", "hooks", `${w.marker}.sh`);
+                if (!fs.existsSync(scriptPath)) {
+                    line(BAD, `${w.event} points at ${w.marker}.sh but the script is missing — the hook fails on every prompt.`);
+                    continue;
+                }
+                // Feed it a payload shaped like the real event and see it survive.
+                const payload = JSON.stringify(w.event === "SessionStart"
+                    ? { session_id: "vexp-doctor", source: "compact", cwd: ws.root }
+                    : w.event === "Stop"
+                        ? { session_id: "vexp-doctor", stop_hook_active: true, cwd: ws.root }
+                        : { session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root });
+                const r = spawnSync(process.platform === "win32" ? "bash" : "sh", ["-c", hook.command], {
+                    env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
+                    input: payload,
+                    timeout: 10000,
+                    encoding: "utf-8",
+                });
+                if (r.error) {
+                    line(BAD, `${w.event} hook DID NOT RUN: ${r.error.code ?? r.error.message} — the ${w.label} is inert.`);
+                }
+                else if (r.status !== 0) {
+                    line(BAD, `${w.event} hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 160)}` : ""} — Claude Code treats this as a failure and continues without vexp.`);
+                }
+                else {
+                    // Silence is a legitimate outcome for the hint hook (the classifier
+                    // decides), so report the daemon's reason instead of guessing.
+                    const why = String(r.stderr ?? "").trim().replace(/^vexp [\w-]+: /, "");
+                    line(OK, `${w.event} hook runs${why ? ` (this probe: ${why.slice(0, 120)})` : ""}`);
+                }
+            }
+        }
+    }
     // 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

package/dist/hook-template.js

@@ -415,6 +415,24 @@ exit 0
 export function vexpStopGateHookScript(binaryPath) {
     return VEXP_STOP_GATE_HOOK.replace("__VEXP_BIN__", binaryPath.replace(/\\/g, "/"));
 }
+/**
+ * v3 context lifecycle: SessionStart hook (Claude Code). Fires on every
+ * session start; the Rust side acts ONLY on source=compact/resume (the
+ * lifecycle events that rebuild the window and lose the session's vexp
+ * orientation) and re-injects one compact context paragraph. FAIL-OPEN:
+ * no binary / no daemon / fresh start = silent exit 0.
+ */
+export const VEXP_SESSION_CONTEXT_HOOK = `#!/bin/bash
+# vexp-restore: context lifecycle restore on SessionStart (compact/resume). Fails open.
+VEXP_BIN="__VEXP_BIN__"
+[ -x "$VEXP_BIN" ] || exit 0
+"$VEXP_BIN" session-context 2>/dev/null
+exit 0
+`;
+/** Bake the binary path into the session-context hook script. */
+export function vexpSessionContextHookScript(binaryPath) {
+    return VEXP_SESSION_CONTEXT_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
@@ -434,10 +452,24 @@ export const VexpHint = async ({ directory, client }) => {
     path.join(directory, ".vexp", "task-" + String(sid || "unknown") + ".txt");
   const gateMarker = (sid) =>
     path.join(directory, ".vexp", "idle-gate-" + String(sid || "unknown") + ".done");
+  // Never block the host: execFileSync freezes the editor's event loop for
+  // as long as the child runs, so a busy daemon turned into an unresponsive
+  // UI (Kilo field report, 2026-08 - the user had to kill the process). Same
+  // budget, same fail-open contract, asynchronous.
+  const runVexp = (args, opts) =>
+    new Promise((resolve) => {
+      import("node:child_process").then(({ execFile }) => {
+        const child = execFile(VEXP_BIN, args, { ...opts, encoding: "utf8" }, (err, stdout) =>
+          resolve(err ? "" : String(stdout || ""))
+        );
+        if (opts && opts.input) {
+          try { child.stdin.end(opts.input); } catch (e) { resolve(""); }
+        }
+      }).catch(() => resolve(""));
+    });
   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)
@@ -452,11 +484,10 @@ export const VexpHint = async ({ directory, client }) => {
             fs.writeFileSync(tf, text);
           }
         } catch (e) { /* fail open */ }
-        const out = execFileSync(VEXP_BIN, ["prompt-hint"], {
+        const out = await runVexp(["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;
@@ -476,12 +507,11 @@ export const VexpHint = async ({ directory, client }) => {
         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 out = await runVexp(["verify", "--json", "--task-file", tf], {
+          timeout: 15000,
+          cwd: directory,
+        });
+        if (!out || !out.trim()) return;
         const rep = JSON.parse(out);
         const items = [];
         for (const f of (rep.spec && rep.spec.forbidden_touched) || [])
@@ -490,6 +520,19 @@ export const VexpHint = async ({ directory, client }) => {
           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);
+        // Impacted tests (2.5.4): the run-or-update mandate, same split as
+        // the Claude Stop gate. Helpers get UPDATE, real suites get RUN.
+        for (const t of (rep.impacted_tests || []).filter((t) => !t.touched).slice(0, 6)) {
+          if (t.runnable === false) {
+            items.push("- \`" + t.file + "\` is a shared test helper tied to changed code" +
+              (t.references && t.references.length ? " (references " + t.references.join(", ") + ")" : "") +
+              ": UPDATE it to match the changes");
+          } else {
+            items.push("- \`" + t.file + "\` tests changed code" +
+              (t.references && t.references.length ? " (references " + t.references.join(", ") + ")" : "") +
+              ": RUN it and fix any failure before finishing");
+          }
+        }
         if (!items.length) return;
         fs.writeFileSync(marker, "1");
         await client.session.prompt({

package/dist/mcp-supervisor.js

@@ -15,7 +15,9 @@ function tokenFilePath() {
     const home = os.homedir();
     return path.join(home, ".vexp", "mcp.token");
 }
-function readPidRecord() {
+/** Exported for regression tests (macOS 2.5.3 field report: the version
+ * field dropped here turned the reuse fast path into a 60s kill loop). */
+export function readPidRecord() {
     try {
         const raw = fs.readFileSync(pidFilePath(), "utf-8");
         const rec = JSON.parse(raw);
@@ -25,6 +27,12 @@ function readPidRecord() {
                 port: rec.port,
                 startedAt: rec.startedAt ?? 0,
                 owner: rec.owner ?? "unknown",
+                // Field report (macOS, 2.5.3): dropping this field made the
+                // supervisor misread every healthy same-version child as a
+                // version mismatch and SIGTERM+respawn it on EVERY 60s health
+                // pass (measured 60.7s replacement period). The reuse fast path
+                // is only as good as the record it reads.
+                version: typeof rec.version === "string" ? rec.version : undefined,
             };
         }
     }
@@ -33,7 +41,7 @@ function readPidRecord() {
     }
     return null;
 }
-function writePidRecord(rec) {
+export function writePidRecord(rec) {
     const p = pidFilePath();
     fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, JSON.stringify(rec, null, 2), { mode: 0o600 });

package/package.json

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