vexp-cli 2.6.3 → 2.7.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, vexpHintHookScript, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSearchHookScript, vexpHintHookCmdScript, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -403,6 +403,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             // Event-driven hint hook: default-on (non-blocking, fail-open — the
             // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
             const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            installClaudeCodeSearchHook(workspaceRoot, binaryPath);
             installClaudeCodeStopGate(workspaceRoot, binaryPath);
             installClaudeCodeSessionContext(workspaceRoot, binaryPath);
             if (hintResult) {
@@ -2026,6 +2027,69 @@ function isVexpHintHookEntry(h) {
  * opt-in applies to DENY hooks, which add a failure mode; this one cannot
  * block anything).
  */
+/** Does this PreToolUse entry belong to us? */
+function isVexpSearchHookEntry(h) {
+    if (!h || typeof h !== "object")
+        return false;
+    const hks = h.hooks;
+    return Array.isArray(hks) && hks.some((hook) => typeof hook?.command === "string" &&
+        hook.command.includes("vexp-search"));
+}
+/**
+ * v4 M1: install the search answer as a PreToolUse hook on Bash.
+ *
+ * Matcher is Bash and nothing else. The hook rewrites only a recursive grep
+ * for names this index defines, keeps the original command after a `||`, and
+ * prints nothing at all in every other case — so a session where vexp has no
+ * opinion is byte-for-byte a session without vexp.
+ *
+ * Why a hook rather than a tool: 9 of 227 measured agent sessions called the
+ * MCP tools. All 227 called Bash.
+ */
+export function installClaudeCodeSearchHook(workspaceRoot, binaryPath) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, "vexp-search.sh");
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const script = vexpSearchHookScript(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.PreToolUse) ? hooks.PreToolUse : [];
+    const filtered = existing.filter((h) => !isVexpSearchHookEntry(h));
+    // Same shell-form-with-quoted-path shape as every other hook we write: exec
+    // form cannot run a .sh on Windows, and an unquoted path word-splits on
+    // "C:\Program Files" (both learned the hard way, c4a0b9e).
+    filtered.push({
+        matcher: "Bash",
+        hooks: [
+            {
+                type: "command",
+                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-search.sh"',
+                timeout: 10,
+            },
+        ],
+    });
+    const merged = { ...hooks, PreToolUse: 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 installClaudeCodeHintHook(workspaceRoot, binaryPath) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
     const hookPath = path.join(hookDir, "vexp-hint.sh");
@@ -2100,10 +2164,33 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
     const script = vexpHintHookScript(binaryPath);
     fs.mkdirSync(dir, { recursive: true });
     const existed = fs.existsSync(hookPath);
-    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    let scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
     if (!scriptIdentical) {
         fs.writeFileSync(hookPath, script, { mode: 0o755 });
     }
+    // Windows gets a batch twin. Codex runs a hook command through
+    // `cmd.exe /C` (COMSPEC, codex-rs/hooks command_runner), so `bash "..."`
+    // reaches a shell that has never heard of bash: a user with neither Git
+    // Bash nor WSL got "bash not found" on every prompt and orientation was
+    // inert. Codex's own answer is `commandWindows`, an optional per-OS
+    // override on the command handler (openai/codex#22159, ~0.131, months
+    // before the version that requires the nested `hooks` shape we already
+    // write). Older builds ignore the field rather than reject the file —
+    // the handler is not deny_unknown_fields, unlike the top level.
+    const cmdPath = path.join(dir, "vexp-hint.cmd");
+    let cmdCommand;
+    if (process.platform === "win32") {
+        const cmdScript = vexpHintHookCmdScript(binaryPath);
+        const cmdExisted = fs.existsSync(cmdPath);
+        if (!cmdExisted || fs.readFileSync(cmdPath, "utf-8") !== cmdScript) {
+            fs.writeFileSync(cmdPath, cmdScript);
+            scriptIdentical = false;
+        }
+        // Quoted: Codex hands `cmd /C` the whole line wrapped in one more pair
+        // of quotes, and cmd then strips the outermost pair — which leaves this
+        // path quoted and therefore safe to contain spaces.
+        cmdCommand = `"${cmdPath}"`;
+    }
     let root = {};
     if (fs.existsSync(hooksJsonPath)) {
         try {
@@ -2141,6 +2228,7 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
             {
                 type: "command",
                 command: `bash "${hookPath.replace(/\\/g, "/")}"`,
+                ...(cmdCommand ? { commandWindows: cmdCommand } : {}),
                 timeout: 5,
             },
         ],

package/dist/doctor.js

@@ -103,6 +103,47 @@ function isAlive(pid) {
         return false;
     }
 }
+/**
+ * The git-hooks verdict, as data.
+ *
+ * Extracted because it was wrong in a way no test could catch: an overriding
+ * `core.hooksPath` was reported as a FAILURE claiming "the index does not
+ * refresh on commit/merge/checkout", and the remedy offered was to edit a
+ * file that moon, husky and lefthook all regenerate. The claim is untrue —
+ * the daemon watches the tree live and reconciles it against disk every five
+ * minutes — and the remedy was unusable. A user spent a round trip on it.
+ */
+export function gitHooksVerdict(hooksPath, repoRoot, installedCount) {
+    const ourHooksDir = path.join(repoRoot, ".git", "hooks");
+    if (!hooksPath) {
+        if (installedCount === 3) {
+            return { level: OK, message: "vexp hooks present in .git/hooks and git will run them" };
+        }
+        if (installedCount === 0) {
+            return { level: OK, message: "no vexp git hooks (index refreshes on demand)" };
+        }
+        return {
+            level: WARN,
+            message: `only ${installedCount}/3 vexp git hooks present — re-run 'vexp hooks install'`,
+        };
+    }
+    const resolved = path.isAbsolute(hooksPath) ? hooksPath : path.join(repoRoot, hooksPath);
+    if (path.resolve(resolved) === path.resolve(ourHooksDir)) {
+        return {
+            level: OK,
+            message: `core.hooksPath points at .git/hooks (${installedCount}/3 vexp hooks present)`,
+        };
+    }
+    if (installedCount === 0) {
+        return { level: OK, message: `core.hooksPath = ${resolved} (no vexp git hooks installed here)` };
+    }
+    return {
+        level: WARN,
+        message: `core.hooksPath = ${resolved} — git runs hooks ONLY from there, so the ${installedCount} vexp hook(s) in .git/hooks never run.\n` +
+            `        the index still refreshes: the daemon watches the tree live and reconciles it against disk every 5 minutes (VEXP_RECONCILE_INTERVAL_SECS).\n` +
+            `        the hooks only make that immediate — if you want them and a tool manages this directory (moon, husky, lefthook), add 'vexp index --finalize || true' through ITS config, not the generated file.`,
+    };
+}
 export async function runDoctor() {
     const home = vexpHome();
     let warns = 0;
@@ -149,7 +190,26 @@ export async function runDoctor() {
                 : st.compressor ?? "unknown (older daemon)";
             line(OK, `index: ${st.total_files ?? "?"} files · ${st.total_nodes ?? "?"} nodes · state ${st.status ?? "?"} · compressor ${comp}`);
             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.`);
+                // The daemon knows WHY, and doctor was throwing it away: it printed
+                // the same "restart to load the model" the sidebar prints, to a user
+                // whose model fails on every start. Restarting is advice only when
+                // the cause can change between starts.
+                const why = typeof st.llm_inactive_reason === "string" ? st.llm_inactive_reason : undefined;
+                const restartIsPointless = why !== undefined &&
+                    /vanilla build|model load failed|incomplete|did not survive|worker did not start/i.test(why);
+                // A daemon still running its startup sync has not REACHED the model
+                // yet. Restarting there is worse than useless: it starts the sync
+                // over, and the user never arrives.
+                const stillStarting = why !== undefined && /still completing its startup/i.test(why);
+                line(WARN, `local LLM is installed and enabled in config but this daemon runs the RULE compressor — results are not LLM-compressed.` +
+                    (why ? `\n        reason: ${why}` : "") +
+                    (stillStarting
+                        ? `\n        wait for the sync to finish — do NOT restart, that begins it again` +
+                            `\n        the daemon logs 'LlmWorker active' when the model is up`
+                        : restartIsPointless
+                            ? `\n        restarting will NOT change this — fix the cause above`
+                            : `\n        run 'vexp daemon-cmd restart' to load the model`) +
+                    `\n        daemon: v${st.daemon_version ?? "?"} at ${st.workspace_root ?? "?"}`);
             }
             // 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
@@ -435,27 +495,8 @@ export async function runDoctor() {
                 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)`);
-            }
-        }
+        const verdict = gitHooksVerdict(hooksPath, ws.root, installed.length);
+        line(verdict.level, verdict.message);
     }
     console.log(chalk.bold("\nClaude Code orientation hooks (.claude/settings.json)"));
     {
@@ -578,12 +619,23 @@ export async function runDoctor() {
             else if (!fs.existsSync(scriptPath)) {
                 line(BAD, "hooks.json points at .codex/vexp-hint.sh but the script is missing — the hook fails on every prompt.");
             }
+            else if (process.platform === "win32" && typeof hook.commandWindows !== "string") {
+                // On Windows Codex runs the command through cmd.exe, which has no
+                // bash: without the commandWindows override the entry is inert on
+                // every prompt unless Git Bash happens to be on PATH. Probing it
+                // through bash here would hide exactly that.
+                line(BAD, "the entry has no 'commandWindows' — Codex runs hooks through cmd.exe on Windows, which cannot run the bash script, so orientation never fires (unless Git Bash is on PATH). Re-run 'vexp setup' to write the batch twin.");
+            }
             else {
-                // Run it. The script bakes an absolute path to the vexp binary and
-                // exits 0 when that path is not executable, so a stale or wrong-profile
-                // path leaves NO trace anywhere: no orientation, no error, forever.
-                // A Windows user found exactly that by reading the generated file.
-                const r = spawnSync(process.platform === "win32" ? "bash" : "sh", ["-c", hook.command], {
+                // Run it, through the same shell Codex would use: cmd.exe on
+                // Windows (COMSPEC), sh elsewhere. The script bakes an absolute path
+                // to the vexp binary and exits 0 when that path is not executable, so
+                // a stale or wrong-profile path leaves NO trace anywhere: no
+                // orientation, no error, forever. A Windows user found exactly that
+                // by reading the generated file.
+                const isWin = process.platform === "win32";
+                const cmdLine = (isWin ? hook.commandWindows : hook.command);
+                const r = spawnSync(isWin ? (process.env.COMSPEC || "cmd.exe") : "sh", [isWin ? "/c" : "-c", cmdLine], {
                     env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
                     input: JSON.stringify({ session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root }),
                     timeout: 10000,
@@ -591,15 +643,17 @@ export async function runDoctor() {
                 });
                 const baked = (() => {
                     try {
-                        const m = fs.readFileSync(scriptPath, "utf-8").match(/VEXP_BIN="([^"]+)"/);
-                        return m?.[1];
+                        // One pattern covers both twins: VEXP_BIN="path" (bash) and
+                        // set "VEXP_BIN=path" (cmd).
+                        const probed = isWin ? path.join(ws.root, ".codex", "vexp-hint.cmd") : scriptPath;
+                        return fs.readFileSync(probed, "utf-8").match(/VEXP_BIN="?([^"\r\n]+)"?/)?.[1];
                     }
                     catch {
                         return undefined;
                     }
                 })();
                 if (r.error) {
-                    line(BAD, `hook DID NOT RUN: ${r.error.code ?? r.error.message} — orientation is inert. On Windows this usually means bash (Git Bash) is not on PATH.`);
+                    line(BAD, `hook DID NOT RUN: ${r.error.code ?? r.error.message} — orientation is inert.`);
                 }
                 else if (r.status !== 0) {
                     line(BAD, `hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 160)}` : ""} — Codex continues without vexp.`);

package/dist/hook-template.js

@@ -397,6 +397,55 @@ exit 0
 export function vexpHintHookScript(binaryPath) {
     return VEXP_HINT_HOOK.replace("__VEXP_BIN__", binaryPath.replace(/\\/g, "/"));
 }
+/**
+ * Windows twin of the hint hook. Codex runs a hook command through
+ * `cmd.exe /C` (COMSPEC) on Windows, and cmd has no `bash`: a Windows user
+ * with neither Git Bash nor WSL got "bash not found" on every prompt, so
+ * orientation was inert and nothing said so. The logic is four lines and
+ * none of it is shell-specific, so it translates exactly — and `exit /b 0`
+ * on the last line keeps the same fail-open contract as the bash twin.
+ *
+ * CRLF on purpose: a batch file with bare LF endings is parsed
+ * inconsistently by cmd, and this one has to run on the machines least
+ * likely to have a POSIX toolchain that would normalise it.
+ */
+export const VEXP_HINT_HOOK_CMD = [
+    "@echo off",
+    "REM vexp-hint: event-driven orientation hint (UserPromptSubmit). Fails open.",
+    'set "VEXP_BIN=__VEXP_BIN__"',
+    'if not exist "%VEXP_BIN%" exit /b 0',
+    '"%VEXP_BIN%" prompt-hint 2>nul',
+    "exit /b 0",
+    "",
+].join("\r\n");
+/** Bake the binary path into the Windows hint hook. Backslashes stay. */
+export function vexpHintHookCmdScript(binaryPath) {
+    return VEXP_HINT_HOOK_CMD.replace("__VEXP_BIN__", binaryPath.replace(/\//g, "\\"));
+}
+/**
+ * v4 M1: the search answer (PreToolUse on Bash).
+ *
+ * Of 227 measured agent sessions with vexp installed, 9 called it — 4%. Bash
+ * is called in all of them. So this stops asking the model to adopt anything:
+ * when it is about to grep the repository for a name the index knows, the
+ * command is rewritten to ask vexp first, with the original grep preserved
+ * after a `||` so the failure mode is exactly "vexp is not installed".
+ *
+ * All the logic is in the binary (`vexp-core search-hook`), like prompt-hint:
+ * the script is a cross-OS wrapper that exits silently when anything is
+ * missing.
+ */
+export const VEXP_SEARCH_HOOK = `#!/bin/bash
+# vexp-search: answer a grep with structure instead of lines. Fails open.
+VEXP_BIN="__VEXP_BIN__"
+[ -x "$VEXP_BIN" ] || exit 0
+"$VEXP_BIN" search-hook 2>/dev/null
+exit 0
+`;
+/** Bake the binary path into the search hook script. */
+export function vexpSearchHookScript(binaryPath) {
+    return VEXP_SEARCH_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,