vexp-cli 2.6.3 → 3.0.1

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, plannedWrites, takeSkippedConfigs, takeUnreachableTargets } from "./agent-config.js";
+import { detectAgents, getAgentList, configureSelectedAgents, resolveAgentName, suggestAgentName, setGuardMode, setInterventionMode, plannedWrites, takeSkippedConfigs, takeUnreachableTargets } from "./agent-config.js";
 import { CLI_VERSION } from "./version.js";
 import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocked, tryOnlineRefresh, } from "./license.js";
 import { checkForUpdate } from "./update-check.js";
@@ -17,6 +17,7 @@ import { installAutostart, uninstallAutostart, autostartStatus, migrateClaudeUnp
 import { runServe } from "./serve.js";
 import { runDoctor } from "./doctor.js";
 import { socketPathFor } from "./socket-path.js";
+import { mutableOutput, askSecretOn } from "./secret-prompt.js";
 import { isTraceEnabled } from "./trace.js";
 import { resolveParentWorkspace, listWorkspaceRepos, addRepoToWorkspace, } from "./workspace-repos.js";
 const program = new Command();
@@ -633,9 +634,12 @@ program
     .option("--dry-run", "Show what would be configured without writing files")
     .option("--personal", "Personal mode: index locally without writing agent configs or git hooks to the shared repo")
     .option("--guard-strict", "Install the Grep/Glob deny hooks (opt-in since 2.3; default setup removes them)")
+    .option("--interventions", "Install the stop gate and the edit-time coupling hint (opt-in since 2.8: each buys tokens with turns, and a turn costs the whole transcript)")
     .action(async (dir, opts) => {
     const workspaceRoot = path.resolve(dir ?? process.cwd());
     setGuardMode(opts.guardStrict ? "strict" : "off");
+    setInterventionMode(opts.interventions ? "on" : "off");
+    setInterventionMode(opts.interventions ? "on" : "off");
     console.log(chalk.bold(`\nvexp setup — ${workspaceRoot}\n`));
     // Step 1: Ensure binary
     const spinner1 = ora("Checking vexp binary...").start();
@@ -889,6 +893,7 @@ program
     .command("setup-agents [dir]")
     .description("Configure AI coding agents to use vexp MCP (interactive multi-select)")
     .option("--guard-strict", "Install the Grep/Glob deny hooks (opt-in since 2.3; default removes them)")
+    .option("--interventions", "Install the stop gate and the edit-time coupling hint (opt-in since 2.8: each buys tokens with turns, and a turn costs the whole transcript)")
     .action(async (dir, opts) => {
     setGuardMode(opts.guardStrict ? "strict" : "off");
     await runSetupAgents(dir);
@@ -1039,17 +1044,16 @@ async function runSetupInteractive(rl) {
 // ────────────────────────────────────────────────────
 program
     .command("activate [key]")
-    .description("Activate a vexp Pro/Team license key")
+    .description("Activate a vexp Pro/Team license key (omit the key to enter it without it reaching shell history)")
     .action(async (key) => {
     if (!key) {
         console.log(chalk.cyan("Get your license key at https://vexp.dev/#pricing\n"));
-        const readline = await import("readline");
-        const rl = readline.createInterface({
+        const { promptSecret } = await import("./secret-prompt.js");
+        key = await promptSecret("License key: ", {
             input: process.stdin,
             output: process.stdout,
+            isTTY: process.stdin.isTTY === true,
         });
-        key = await new Promise((resolve) => rl.question("License key: ", resolve));
-        rl.close();
     }
     try {
         const claims = activateLicense(key.trim());
@@ -1370,7 +1374,10 @@ async function interactiveMode() {
     }
     await printBanner();
     printMainMenu();
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    // Built over a mutable stdout so `activate` can hide the key being typed:
+    // this interface lives for the whole session and closing it exits.
+    const outCtl = mutableOutput(process.stdout);
+    const rl = readline.createInterface({ input: process.stdin, output: outCtl.stream, terminal: true });
     rl.on("close", () => { console.log(""); process.exit(0); });
     let currentMenu = "main";
     const prompts = {
@@ -1424,7 +1431,7 @@ async function interactiveMode() {
             const allItems = [...MENU_CONFIG, ...MENU_EXPLORE, ...MENU_SAVINGS, ...MENU_LICENSE, ...MENU_REPOS];
             const direct = allItems.find((m) => m.label === input);
             if (direct) {
-                await executeCommand(direct.label, rl);
+                await executeCommand(direct.label, rl, outCtl);
                 // After a direct command, reprint the main menu so options stay visible.
                 printMainMenu();
                 continue;
@@ -1453,14 +1460,14 @@ async function interactiveMode() {
         }
         // Show description before executing
         console.log(chalk.dim(`\n    ${item.description}\n`));
-        await executeCommand(item.label, rl);
+        await executeCommand(item.label, rl, outCtl);
         console.log("");
         // Sticky sub-menu: reprint the current sub-menu after every command so
         // the user always sees the available options without typing '?'.
         printSubMenu(titles[currentMenu], items);
     }
 }
-async function executeCommand(label, rl) {
+async function executeCommand(label, rl, outCtl) {
     try {
         switch (label) {
             // ── Config commands ──
@@ -1750,7 +1757,7 @@ async function executeCommand(label, rl) {
                 break;
             }
             case "activate": {
-                const key = await ask(rl, chalk.cyan("    License key: "));
+                const key = await askSecretOn(rl, chalk.cyan("    License key: "), outCtl, process.stdout);
                 if (key.trim()) {
                     try {
                         const claims = activateLicense(key.trim());

package/dist/doctor.js

@@ -103,6 +103,94 @@ 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.
+ */
+/**
+ * Which IDE owns a running daemon, from its executable path.
+ *
+ * A daemon started by an IDE extension runs the binary bundled INSIDE that
+ * extension's directory, and the extension host owns its lifecycle. Telling
+ * that user to run `vexp daemon-cmd restart` sends them in a circle: the kill
+ * lands, the same extension host respawns the same old binary, and nothing
+ * changes. The window has to reload so the host picks up the new extension.
+ * A user lost time on exactly this and worked it out himself.
+ *
+ * Matching is on the IDE's own extensions directory, which is where the
+ * bundled core lives (`<ide>/extensions/<publisher>.vexp-<ver>/binaries/...`).
+ * Remote/WSL installs use `.vscode-server`; forks use their own dot-dir.
+ */
+export function daemonOwnerIde(exePath) {
+    if (!exePath)
+        return null;
+    const p = exePath.replace(/\\/g, "/").toLowerCase();
+    const ides = [
+        [/\/\.vscode-server-insiders\/extensions\//, "VS Code Insiders (Remote)"],
+        [/\/\.vscode-server\/extensions\//, "VS Code (Remote/WSL)"],
+        [/\/\.vscode-insiders\/extensions\//, "VS Code Insiders"],
+        [/\/\.vscode-oss\/extensions\//, "VSCodium"],
+        [/\/\.vscode\/extensions\//, "VS Code"],
+        [/\/\.cursor-server\/extensions\//, "Cursor (Remote)"],
+        [/\/\.cursor\/extensions\//, "Cursor"],
+        [/\/\.windsurf-server\/extensions\//, "Windsurf (Remote)"],
+        [/\/\.windsurf\/extensions\//, "Windsurf"],
+        [/\/\.trae\/extensions\//, "Trae"],
+        [/\/\.antigravity\/extensions\//, "Antigravity"],
+    ];
+    for (const [re, label] of ides) {
+        if (re.test(p))
+            return label;
+    }
+    return null;
+}
+/** The remedy line for a daemon that is behind the installed engine. */
+export function staleDaemonRemedy(exePath) {
+    const ide = daemonOwnerIde(exePath);
+    if (ide) {
+        return (`this daemon belongs to ${ide} (${exePath}) — 'vexp daemon-cmd restart' will NOT fix it: ` +
+            `the extension host respawns the same build.\n` +
+            `        reload the ${ide} window instead (Command Palette → "Developer: Reload Window").`);
+    }
+    return `run 'vexp daemon-cmd restart' to upgrade it now.`;
+}
+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 +237,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
@@ -162,10 +269,12 @@ export async function runDoctor() {
                 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.`);
+                    const exe = st.daemon_exe;
+                    line(WARN, `daemon is v${running} but the installed binary is v${bundled} — this workspace is still served by the OLD version.\n        ${staleDaemonRemedy(exe)}`);
                 }
                 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.`);
+                    const exe = st.daemon_exe;
+                    line(WARN, `daemon is running a deleted executable (upgraded on disk).\n        ${staleDaemonRemedy(exe)}`);
                 }
             }
             catch { /* best-effort */ }
@@ -435,35 +544,21 @@ 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)"));
     {
         const sPath = path.join(ws.root, ".claude", "settings.json");
+        // `optIn` hooks are not written by a default setup, so their absence is
+        // the expected state and must not read as a fault. The verification gate
+        // buys correctness with TURNS, and a turn costs the whole transcript
+        // (65,521 tokens measured over 13 bench sessions); `vexp setup
+        // --interventions` installs it for anyone who wants that trade.
         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" },
+            { event: "Stop", marker: "vexp-verify", label: "verification gate", optIn: true },
         ];
         let settings = null;
         try {
@@ -492,7 +587,12 @@ export async function runDoctor() {
                     .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.`);
+                    if (w.optIn) {
+                        line(OK, `${w.event} (${w.label}) not installed — opt-in since 2.8; 'vexp setup --interventions' adds it.`);
+                    }
+                    else {
+                        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`);
@@ -578,12 +678,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 +702,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

@@ -393,10 +393,192 @@ VEXP_BIN="__VEXP_BIN__"
 "$VEXP_BIN" prompt-hint 2>/dev/null
 exit 0
 `;
+/**
+ * v5: the coupling, delivered on the edit that needs it (PostToolUse).
+ *
+ * The only evidence about WHY an agent fails a multi-file task says its plan
+ * was incomplete, not its patch. That is the reverse-dependency question, and
+ * nothing in a context window answers it. This puts the answer on Edit and
+ * Write, which every agent uses in every session — against 4% that ever call
+ * a vexp tool.
+ *
+ * PostToolUse rather than PreToolUse because a deny on an edit stops real
+ * work, and after rather than before because the channel that reaches the
+ * model is `additionalContext`, verified empirically on Claude Code: it
+ * arrives as a system-reminder naming the hook that produced it. It adds no
+ * turn, which the 2.9 gate experiment showed to be worth +17% and nothing.
+ *
+ * FAIL-OPEN like every other hook: no binary, no daemon, nothing to say —
+ * exit 0 silent.
+ */
+export const VEXP_EDIT_HINT_HOOK = `#!/bin/bash
+# vexp-edit-hint: what else references the file you just changed. Fails open.
+VEXP_BIN="__VEXP_BIN__"
+[ -x "$VEXP_BIN" ] || exit 0
+"$VEXP_BIN" edit-hint 2>/dev/null
+exit 0
+`;
+export const VEXP_READ_HINT_HOOK = `#!/bin/bash
+# vexp-read-hint: answer a whole-file read of a large file with its skeleton.
+# The only mechanism vexp has that SUBTRACTS tokens. Fails open.
+VEXP_BIN="__VEXP_BIN__"
+[ -x "$VEXP_BIN" ] || exit 0
+"$VEXP_BIN" read-hint 2>/dev/null
+exit 0
+`;
+export const VEXP_BASH_CAP_HOOK = `#!/bin/bash
+# vexp-bash-cap: bound the output of a shell command that has no bound of its
+# own. The other door: narrowing reads alone just moved the work here. Fails
+# open, and never touches a build or a test.
+VEXP_BIN="__VEXP_BIN__"
+[ -x "$VEXP_BIN" ] || exit 0
+"$VEXP_BIN" bash-cap 2>/dev/null
+exit 0
+`;
+/**
+ * opencode / Kilo compression plugin.
+ *
+ * Their `tool.execute.before` can MUTATE the arguments, not only refuse them —
+ * the documented example is `output.args.command = escape(output.args.command)`
+ * — which is the whole mechanism. Same two doors as everywhere else: a
+ * whole-file read becomes that file's skeleton, and a shell command with no
+ * bound of its own gets one.
+ *
+ * Fails open at every step. A plugin that throws takes the tool call with it,
+ * and a compression that breaks a session is worse than no compression.
+ */
+export const VEXP_OPENCODE_COMPRESS = `import { spawn } from "child_process";
+
+const BIN = "__VEXP_BIN__";
+
+function ask(sub, payload) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+    let child;
+    try {
+      child = spawn(BIN, [sub], { stdio: ["pipe", "pipe", "ignore"] });
+    } catch { return finish(null); }
+    const timer = setTimeout(() => { try { child.kill(); } catch {} finish(null); }, 8000);
+    let out = "";
+    child.stdout.on("data", (d) => { out += d.toString(); });
+    child.on("error", () => { clearTimeout(timer); finish(null); });
+    child.on("close", () => {
+      clearTimeout(timer);
+      try { finish(JSON.parse(out.trim() || "null")); } catch { finish(null); }
+    });
+    try { child.stdin.end(JSON.stringify(payload)); } catch { clearTimeout(timer); finish(null); }
+  });
+}
+
+function patchOf(r) {
+  return (r && r.hookSpecificOutput && r.hookSpecificOutput.updatedInput) || null;
+}
+
+export const VexpCompress = async () => ({
+  "tool.execute.before": async (input, output) => {
+    const args = output && output.args;
+    if (!args) return;
+    try {
+      const tool = String(input.tool || "").toLowerCase();
+      if (tool === "bash" && typeof args.command === "string") {
+        const p = patchOf(await ask("bash-cap", {
+          tool_name: "Bash",
+          tool_input: { command: args.command },
+          session_id: input.sessionID || "",
+        }));
+        if (p && typeof p.command === "string") args.command = p.command;
+        return;
+      }
+      if (tool === "read") {
+        const key = args.filePath !== undefined ? "filePath"
+          : args.file_path !== undefined ? "file_path"
+          : args.path !== undefined ? "path" : null;
+        if (!key || typeof args[key] !== "string") return;
+        // An agent that already asked for a range knows what it wants.
+        if (args.offset !== undefined || args.limit !== undefined) return;
+        const p = patchOf(await ask("read-hint", {
+          tool_name: "Read",
+          tool_input: { file_path: args[key] },
+          session_id: input.sessionID || "",
+        }));
+        if (p && typeof p.file_path === "string") args[key] = p.file_path;
+      }
+    } catch {
+      // Never let compression break a tool call.
+    }
+  },
+});
+`;
+/** Bake the binary path into the opencode/Kilo compression plugin. */
+export function vexpOpencodeCompressPlugin(binaryPath) {
+    return VEXP_OPENCODE_COMPRESS.replace("__VEXP_BIN__", binaryPath.replace(/\\/g, "/"));
+}
+/** Bake the binary path into the read-hint hook script. */
+export function bakeReadHintHook(binaryPath) {
+    return VEXP_READ_HINT_HOOK.replace("__VEXP_BIN__", binaryPath);
+}
+/** Bake the binary path into the bash-cap hook script. */
+export function bakeBashCapHook(binaryPath) {
+    return VEXP_BASH_CAP_HOOK.replace("__VEXP_BIN__", binaryPath);
+}
+/** Bake the binary path into the edit-hint hook script. */
+export function bakeEditHintHook(binaryPath) {
+    return VEXP_EDIT_HINT_HOOK.replace("__VEXP_BIN__", binaryPath);
+}
 /** Bake the binary path into the hint hook script. */
 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,
@@ -468,6 +650,37 @@ export const VexpHint = async ({ directory, client }) => {
       }).catch(() => resolve(""));
     });
   return {
+    // v5: the coupling on the edit, for opencode and Kilo.
+    //
+    // Their guard plugin uses "tool.execute.before" (verified in our own
+    // tests), so ".after" follows the pattern. If that event does not exist
+    // the handler is simply never called — inert, never harmful, which is the
+    // same fail-open contract as every other surface here.
+    "tool.execute.after": async (input, output) => {
+      try {
+        const tool = String((input && input.tool) || "");
+        if (!/^(edit|write|patch|multiedit)$/i.test(tool)) return;
+        const args = (input && input.args) || {};
+        const file =
+          args.filePath || args.file_path || args.path || (output && output.filePath);
+        if (!file) return;
+        const payload = JSON.stringify({
+          tool_name: "Edit",
+          session_id: (input && input.sessionID) || "",
+          tool_input: { file_path: String(file) },
+        });
+        const raw = await runVexp(["edit-hint"], { cwd: directory, input: payload, timeout: 5000 });
+        if (!raw) return;
+        const parsed = JSON.parse(raw);
+        const text = parsed?.hookSpecificOutput?.additionalContext;
+        if (!text) return;
+        if (output && Array.isArray(output.parts)) {
+          output.parts.push({ type: "text", text: String(text) });
+        }
+      } catch (e) {
+        /* fail open */
+      }
+    },
     "chat.message": async (input, output) => {
       try {
         const text = (output.parts || [])
@@ -491,7 +704,19 @@ export const VexpHint = async ({ directory, client }) => {
         });
         if (!out || !out.trim()) return;
         const hint = JSON.parse(out).hookSpecificOutput?.additionalContext;
-        if (hint) output.parts.push({ type: "text", text: hint });
+        // Never push a bare {type,text} part: Kilo 7.4.x validates every part
+        // against a schema requiring id/sessionID/messageID before save, so an
+        // injected bare part poisons the whole user message (43/43
+        // InvalidDurableEvent, prompt dies in both the extension and the CLI -
+        // Kilo field report, 2026-08). Appending onto the user's own text part
+        // rides its already-valid identity on every opencode/Kilo version.
+        if (hint) {
+          const texts = (output.parts || []).filter(
+            (p) => p && p.type === "text" && typeof p.text === "string"
+          );
+          const target = texts[texts.length - 1];
+          if (target) target.text = target.text + "\\n\\n" + hint;
+        }
       } catch (e) { /* fail open */ }
     },
     event: async ({ event }) => {

package/dist/license.js

@@ -22,8 +22,12 @@ const VEXP_WEB_ORIGIN = process.env.VEXP_WEB_ORIGIN || "https://vexp.dev";
 const GRACE_MS = 14 * 24 * 60 * 60 * 1000;
 // Opportunistic refresh cadence: don't hit the network more than once per 24h.
 const REFRESH_BACKOFF_MS = 24 * 60 * 60 * 1000;
-// 3 second timeout on validate calls — any slower falls back silently.
-const VALIDATE_TIMEOUT_MS = 3000;
+// 10 second timeout on validate calls — any slower falls back silently.
+// Was 3s: a serverless cold start plus slow DNS (WSL resolvers routinely
+// take seconds) blew that budget, so the refresh that keeps the rolling
+// fresh.jwt alive quietly never landed and users fell back to the long
+// JWT — or, once that lapsed, to the free tier.
+const VALIDATE_TIMEOUT_MS = 10_000;
 function getLicensePath() {
     return path.join(vexpHomeDir(), ".vexp", "license.jwt");
 }