vexp-cli 2.7.0 → 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

@@ -113,6 +113,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) {
@@ -222,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 */ }
@@ -501,10 +550,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 +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`);

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");
 }

package/dist/secret-prompt.js

@@ -0,0 +1,62 @@
+import { Writable } from "node:stream";
+import * as readline from "node:readline";
+export function mutableOutput(base) {
+    let muted = false;
+    const stream = new Writable({
+        write(chunk, enc, cb) {
+            if (!muted)
+                base.write(chunk);
+            cb();
+        },
+    });
+    // readline consults these to decide how to render; without them it treats
+    // the wrapper as a dumb pipe and the prompt never appears.
+    Object.defineProperty(stream, "isTTY", { get: () => base.isTTY === true });
+    Object.defineProperty(stream, "columns", { get: () => base.columns });
+    Object.defineProperty(stream, "rows", { get: () => base.rows });
+    return { stream, setMuted: (m) => { muted = m; } };
+}
+/** Prompt for a secret on a fresh readline interface. */
+export async function promptSecret(promptText, io) {
+    const { input, output, isTTY } = io;
+    if (!isTTY) {
+        // Piped: read the line with terminal mode OFF so readline cannot echo it.
+        const rl = readline.createInterface({ input, terminal: false });
+        output.write(promptText);
+        const line = await new Promise((resolve) => {
+            let settled = false;
+            rl.once("line", (l) => { settled = true; resolve(l); });
+            rl.once("close", () => { if (!settled)
+                resolve(""); });
+        });
+        rl.close();
+        output.write("\n");
+        return line;
+    }
+    const ctl = mutableOutput(output);
+    const rl = readline.createInterface({ input, output: ctl.stream, terminal: true });
+    try {
+        return await askSecretOn(rl, promptText, ctl, output);
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Prompt for a secret on an EXISTING interface — the interactive shell owns
+ * one readline for the whole session and closing it exits the process, so the
+ * shell mutes its own output instead of building a second one.
+ *
+ * The interface must have been created over `ctl.stream`.
+ */
+export async function askSecretOn(rl, promptText, ctl, output) {
+    const answer = await new Promise((resolve) => {
+        // question() writes the prompt synchronously, so muting immediately after
+        // hides the keystrokes and nothing else.
+        rl.question(promptText, (a) => resolve(a));
+        ctl.setMuted(true);
+    });
+    ctl.setMuted(false);
+    output.write("\n");
+    return answer;
+}