vexp-cli 2.7.0 → 3.1.0

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();
@@ -41,6 +42,11 @@ if (isTraceEnabled()) {
 const AUTOSTART_SKIP = new Set([
     "setup", "daemon-cmd", "activate", "deactivate", "license", "version",
     "serve", "autostart", "use", "doctor",
+    // Lifecycle commands: `vexp daemons` LISTS daemons and `vexp stop` ENDS
+    // one — spawning a daemon for the current directory first made `stop`
+    // followed by `daemons` bring the stopped daemon straight back
+    // (3.1 e2e, 2026-08).
+    "daemons", "stop",
 ]);
 program.hook("preAction", async (_thisCmd, actionCmd) => {
     // One-shot config migration for the multi-session fix — de-pins a legacy
@@ -455,7 +461,7 @@ program
 });
 program
     .command("search <query>")
-    .description("Exhaustive index search: every matching node (code and docs), no top-K. Built for rename sweeps and zero-reference audits")
+    .description("Exhaustive index search: every symbol matching the query (code and docs) plus every line in indexed symbol bodies that references it, no top-K. Built for rename sweeps and zero-reference audits")
     .option("--substring", "Substring match (LIKE) instead of token search — partial identifiers, punctuation")
     .option("--files-only", "Print only the distinct file paths")
     .option("--json", "Machine-readable JSON with a stable shape")
@@ -633,9 +639,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();
@@ -824,7 +833,15 @@ program
     // the daemon already cold-starts on the first `vexp` invocation, so this is
     // purely a convenience for post-reboot warm-up. Skip entirely when the user
     // opted out via env or when stdin is not a TTY (non-interactive install).
-    if (process.env.VEXP_NO_AUTOSTART_INSTALL === "1") {
+    //
+    // A dry run must not reach this step at all: the prompt was asked even
+    // under --dry-run and answering Yes rewrote the Startup-folder .vbs while
+    // the summary still claimed nothing was written (field report, Peiyuan,
+    // 3.0.1 on Windows). Persistence is a write like any other.
+    if (opts.dryRun) {
+        console.log(chalk.dim("  --dry-run: would ask about login autostart (writes a Startup entry only if you accept)."));
+    }
+    else if (process.env.VEXP_NO_AUTOSTART_INSTALL === "1") {
         // Explicit opt-out — do nothing.
     }
     else if (!process.stdin.isTTY) {
@@ -889,6 +906,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 +1057,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());
@@ -1104,6 +1121,9 @@ program
     console.log(`  Max nodes: ${limits.maxNodes === 0 ? "unlimited" : limits.maxNodes.toLocaleString()}`);
     console.log(`  Max repos: ${limits.maxRepos === 0 ? "unlimited" : limits.maxRepos}`);
     console.log(`  All tools: ${limits.allTools ? "yes" : "no (7/10)"}`);
+    if (limits.allTools) {
+        console.log(`             (the MCP tool list shows 4 by default to keep the catalog small; every tool stays callable — VEXP_ALL_TOOLS=1 lists them all)`);
+    }
     if (limits.renewsAt) {
         console.log(ltd
             ? `  Renewal:   none — lifetime licence (local token auto-refreshes, ` +
@@ -1370,7 +1390,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 +1447,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 +1476,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 ──
@@ -1742,6 +1765,9 @@ async function executeCommand(label, rl) {
                 console.log(`    Max nodes: ${limits.maxNodes === 0 ? "unlimited" : limits.maxNodes.toLocaleString()}`);
                 console.log(`    Max repos: ${limits.maxRepos === 0 ? "unlimited" : limits.maxRepos}`);
                 console.log(`    All tools: ${limits.allTools ? "yes" : "no (7/10)"}`);
+                if (limits.allTools) {
+                    console.log(`               (the MCP tool list shows 4 by default to keep the catalog small; every tool stays callable — VEXP_ALL_TOOLS=1 lists them all)`);
+                }
                 if (limits.renewsAt) {
                     console.log(ltd
                         ? `    Renewal:   none — lifetime licence (token auto-refreshes, valid to ${limits.renewsAt.toLocaleDateString()})`
@@ -1750,7 +1776,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

@@ -5,6 +5,7 @@ import * as net from "net";
 import { spawnSync } from "child_process";
 import chalk from "chalk";
 import { socketPathFor } from "./socket-path.js";
+import { parseJsonc } from "./agent-config.js";
 // `vexp doctor` — audit the vexp MCP/daemon state WITHOUT connecting to a daemon.
 // Surfaces the failure modes behind the Codex drift report: stale daemons.json
 // entries, wrong-workspace resolution, mixed Codex transport (url+stdio),
@@ -113,6 +114,53 @@ function isAlive(pid) {
  * 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) {
@@ -144,6 +192,80 @@ export function gitHooksVerdict(hooksPath, repoRoot, installedCount) {
             `        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.`,
     };
 }
+/**
+ * The size-skip verdict, from `.vexp/coverage.json` (3.1 shape), as data.
+ *
+ * Files over `max_file_size_kb` are left out of the index by the walk. Until
+ * 3.1 the only trace was an INFO line in the daemon log: doctor, the
+ * `index_status` tool and coverage.json all reported a healthy index while a
+ * tier-4 user was missing five hand-written Dart files — 21% of the bytes of
+ * his lib/ — from every impact, search and pipeline answer (field report,
+ * 2026-08). Raising the cap only moved the cliff, so the cliff is reported
+ * wherever it stands. Null when nothing was skipped for size, or when the
+ * file predates 3.1 and has no skip keys.
+ */
+export function coverageVerdict(cov) {
+    if (!cov || typeof cov !== "object")
+        return null;
+    const c = cov;
+    const oversized = Number(c.skipped_oversized) || 0;
+    if (oversized === 0)
+        return null;
+    const cap = Number(c.max_file_size_kb) || 0;
+    const files = Array.isArray(c.skipped_files) ? c.skipped_files : [];
+    const examples = files
+        .filter((f) => f.reason === "oversized")
+        .slice(0, 5)
+        .map((f) => `${f.path} (${Number(f.size_kb) || 0} KB)`);
+    const more = oversized - examples.length;
+    return {
+        level: WARN,
+        message: `${oversized} file(s) over max_file_size_kb = ${cap} are NOT indexed — their symbols and callers are invisible to impact, search and run_pipeline:\n` +
+            examples.map((e) => `        - ${e}`).join("\n") +
+            (more > 0 ? `\n        … +${more} more (full list: .vexp/coverage.json)` : "") +
+            `\n        raise max_file_size_kb in .vexp/vexp.toml (0 = no cap) to include them, or exclude them on purpose with exclude_patterns.`,
+    };
+}
+/**
+ * The `.vscode/mcp.json` verdict for GitHub Copilot, as data.
+ *
+ * A Copilot user who "set up the vexp agent" and sees neither a vexp server in
+ * VS Code nor vexp tools in chat has, in our experience, one of three things:
+ * the file is not where VS Code looks (the folder open in VS Code is not the
+ * one that was set up), the server entry cannot start (a bare `node` that the
+ * GUI-launched editor cannot find on its PATH, or a bundle path an extension
+ * upgrade removed), or Chat is not in Agent mode — the only mode that offers
+ * MCP tools. doctor can prove the first two; it can only say the third.
+ */
+export function vsCodeMcpVerdict(cfg, wsRoot, exists = (p) => fs.existsSync(p)) {
+    if (!cfg || typeof cfg !== "object")
+        return { level: WARN, message: ".vscode/mcp.json is present but not valid JSON — VS Code will ignore every server in it; fix the syntax and re-run 'vexp setup'" };
+    const servers = cfg.servers;
+    const vexp = servers?.vexp;
+    if (!vexp)
+        return { level: WARN, message: ".vscode/mcp.json has no 'vexp' server — run: vexp setup --agents \"GitHub Copilot\"" };
+    const command = typeof vexp.command === "string" ? vexp.command : "";
+    const args = Array.isArray(vexp.args) ? vexp.args.filter((a) => typeof a === "string") : [];
+    const script = args.find((a) => /\.[cm]?js$/.test(a));
+    if (!command)
+        return { level: WARN, message: ".vscode/mcp.json vexp server has no 'command' — re-run 'vexp setup'" };
+    if (!/[\\/]/.test(command)) {
+        return {
+            level: WARN,
+            message: `.vscode/mcp.json starts the vexp server with a bare '${command}' — resolved through the editor's PATH, which a VS Code launched from the Dock/Start menu usually lacks (symptom: 'spawn ${command} ENOENT' in Output › MCP: vexp, no vexp tools in chat).\n` +
+                `        re-run 'vexp setup' — 3.1 pins the absolute node path.`,
+        };
+    }
+    if (!exists(command))
+        return { level: WARN, message: `.vscode/mcp.json vexp command does not exist: ${command} — re-run 'vexp setup' to repin it` };
+    if (script && !exists(script))
+        return { level: WARN, message: `.vscode/mcp.json vexp server bundle is missing: ${script} (an editor upgrade removed the old extension folder?) — re-run 'vexp setup'` };
+    const pinned = typeof vexp.env?.VEXP_WORKSPACE === "string" ? vexp.env.VEXP_WORKSPACE : undefined;
+    if (pinned && path.resolve(pinned).toLowerCase() !== path.resolve(wsRoot).toLowerCase()) {
+        return { level: WARN, message: `.vscode/mcp.json vexp server is pinned to ${pinned}, but this workspace is ${wsRoot} — re-run 'vexp setup' here` };
+    }
+    return { level: OK, message: `.vscode/mcp.json vexp server: ${command} ${script ?? args.join(" ")}` };
+}
 export async function runDoctor() {
     const home = vexpHome();
     let warns = 0;
@@ -222,10 +344,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 */ }
@@ -261,6 +385,16 @@ export async function runDoctor() {
             }
         }
     }
+    // 3.1 — coverage gaps only the daemon log used to witness. Read from disk,
+    // not from the daemon: the index that skipped the files may have been
+    // built by a daemon that is no longer running.
+    try {
+        const cov = JSON.parse(fs.readFileSync(path.join(ws.root, ".vexp", "coverage.json"), "utf-8"));
+        const v = coverageVerdict(cov);
+        if (v)
+            line(v.level, v.message);
+    }
+    catch { /* no coverage.json: never indexed here, or an index older than 2.7 */ }
     // 2) Daemon registry (~/.vexp/daemons.json) — stale entries are a drift source.
     console.log(chalk.bold("\nDaemon registry (~/.vexp/daemons.json)"));
     const regPath = path.join(home, ".vexp", "daemons.json");
@@ -385,6 +519,27 @@ export async function runDoctor() {
     catch {
         line(OK, "no ~/.claude.json");
     }
+    // 5a) GitHub Copilot — VS Code reads MCP servers from <folder>/.vscode/mcp.json.
+    console.log(chalk.bold("\nGitHub Copilot / VS Code (.vscode/mcp.json)"));
+    {
+        const mcpPath = path.join(ws.root, ".vscode", "mcp.json");
+        if (!fs.existsSync(mcpPath)) {
+            line(OK, "no .vscode/mcp.json (Copilot MCP not configured in this folder — 'vexp setup --agents \"GitHub Copilot\"' writes it)");
+        }
+        else {
+            let cfg = null;
+            try {
+                cfg = parseJsonc(fs.readFileSync(mcpPath, "utf-8"));
+            }
+            catch {
+                cfg = null;
+            }
+            const v = vsCodeMcpVerdict(cfg, ws.root);
+            line(v.level, v.message);
+            console.log(chalk.dim("        VS Code shows it under Extensions → MCP SERVERS - INSTALLED; vexp tools appear only in Copilot Chat AGENT mode (tools picker → 'MCP Server: vexp')."));
+            console.log(chalk.dim("        server log: Command Palette → 'MCP: List Servers' → vexp → Show Output (channel 'MCP: vexp'); daemon log: .vexp/daemon.log"));
+        }
+    }
     // 5b) Claude Code guard hook — EXECUTE it the way Claude Code would, don't
     // just check presence. A shell-form command that word-splits on a project
     // path containing a space fails non-blocking on every call: the guard never
@@ -501,10 +656,15 @@ export async function runDoctor() {
     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 {
@@ -533,7 +693,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`);

package/dist/hook-template.js

@@ -393,6 +393,139 @@ 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, "/"));
@@ -517,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 || [])
@@ -540,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");
 }
@@ -202,10 +206,10 @@ export async function tryOnlineRefresh(longJwt) {
             // Only save if the freshToken itself verifies locally
             if (verifyAndDecode(data.freshToken)) {
                 saveFreshToken(data.freshToken);
-                // The server re-issued a 30-day long token (entitlement changed:
-                // AppSumo tier up/downgrade, or a Stripe resub migration). Overwrite
-                // the on-disk long JWT so the new entitlement survives even fully
-                // offline and the previous one stops working — without the user
+                // The server re-issued the 30-day long token (rolled forward on every
+                // refresh since vexp-web 3.1; also on entitlement change). Overwrite
+                // the on-disk long JWT so the current entitlement survives even fully
+                // offline and a superseded one stops working — without the user
                 // re-pasting a key. Only persist if it verifies locally.
                 if (data.newLongToken && verifyAndDecode(data.newLongToken)) {
                     try {