vexp-cli 2.6.2 → 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/cli.js

@@ -10,7 +10,7 @@ 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 { CLI_VERSION } from "./version.js";
-import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocked, } from "./license.js";
+import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocked, tryOnlineRefresh, } from "./license.js";
 import { checkForUpdate } from "./update-check.js";
 import { ensureMcpHttpServer, mcpHttpStatus } from "./mcp-supervisor.js";
 import { installAutostart, uninstallAutostart, autostartStatus, migrateClaudeUnpinIfNeeded } from "./autostart.js";
@@ -1057,6 +1057,18 @@ program
         console.log(`  Plan:    ${claims.plan}`);
         console.log(`  Email:   ${claims.sub}`);
         console.log(`  Expires: ${new Date(claims.exp * 1000).toLocaleDateString()}`);
+        // Register this machine NOW, while the user is watching, instead of
+        // whenever a later command happens to fall outside the 24h refresh
+        // window. The dashboard tells people to "open vexp on any machine to
+        // register it" and activating IS that — a tier-4 user read 0 of 10
+        // devices immediately after activating and reasonably thought something
+        // had failed. Best effort by design: the refresh has its own short
+        // timeout and never throws, so an offline activation still succeeds and
+        // simply registers later.
+        try {
+            await tryOnlineRefresh(key.trim());
+        }
+        catch { /* offline or server down: registration happens on a later run */ }
         console.log("");
     }
     catch (err) {
@@ -1076,15 +1088,28 @@ program
     .description("Show current license status")
     .action(() => {
     const limits = readLicenseLimits();
+    // AppSumo lifetime tiers print as the raw internal string ("tier3") with a
+    // "Renews" date one month out — which is the local token's expiry, not the
+    // licence's. It rolls forward by itself on every check-in. A tier-3 buyer
+    // read that as a monthly deadline and re-activated his key by hand every
+    // month for nothing, and he was right to be alarmed by what it said.
+    const ltd = /^tier[1-4]$/.test(limits.plan);
+    const planLabel = ltd
+        ? `Lifetime · Tier ${limits.plan.slice(4)}`
+        : limits.plan;
     console.log(chalk.bold("\nvexp License Status\n"));
-    console.log(`  Plan:      ${limits.plan}`);
+    console.log(`  Plan:      ${planLabel}`);
     if (limits.email)
         console.log(`  Email:     ${limits.email}`);
     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.renewsAt)
-        console.log(`  Renews:    ${limits.renewsAt.toLocaleDateString()}`);
+    if (limits.renewsAt) {
+        console.log(ltd
+            ? `  Renewal:   none — lifetime licence (local token auto-refreshes, ` +
+                `current one valid to ${limits.renewsAt.toLocaleDateString()})`
+            : `  Renews:    ${limits.renewsAt.toLocaleDateString()}`);
+    }
     const blocked = readDeviceBlocked();
     if (blocked) {
         console.log("");
@@ -1708,14 +1733,20 @@ async function executeCommand(label, rl) {
             // ── License commands ──
             case "status": {
                 const limits = readLicenseLimits();
-                console.log(`    Plan:      ${limits.plan}`);
+                // Same wording as `vexp license`: a lifetime tier must not be shown as
+                // a raw "tier3" with a monthly renewal date it does not have.
+                const ltd = /^tier[1-4]$/.test(limits.plan);
+                console.log(`    Plan:      ${ltd ? `Lifetime · Tier ${limits.plan.slice(4)}` : limits.plan}`);
                 if (limits.email)
                     console.log(`    Email:     ${limits.email}`);
                 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.renewsAt)
-                    console.log(`    Renews:    ${limits.renewsAt.toLocaleDateString()}`);
+                if (limits.renewsAt) {
+                    console.log(ltd
+                        ? `    Renewal:   none — lifetime licence (token auto-refreshes, valid to ${limits.renewsAt.toLocaleDateString()})`
+                        : `    Renews:    ${limits.renewsAt.toLocaleDateString()}`);
+                }
                 break;
             }
             case "activate": {

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)"));
     {
@@ -527,6 +568,106 @@ export async function runDoctor() {
             }
         }
     }
+    // 5b-bis) Codex orientation hook. The section above it reports Codex's MCP
+    // config and stops there, so a Codex user could have half the product wired
+    // and read nothing but [OK]: the tools come from ~/.codex/config.toml, the
+    // per-prompt orientation comes from .codex/hooks.json, and until now only
+    // the first was ever checked. Two users reached that blind spot from
+    // opposite directions in one week — one could not tell whether orientation
+    // was configured, the other could not tell whether it ran.
+    console.log(chalk.bold("\nCodex orientation hook (.codex/hooks.json)"));
+    {
+        const hooksJson = path.join(ws.root, ".codex", "hooks.json");
+        const scriptPath = path.join(ws.root, ".codex", "vexp-hint.sh");
+        const codexMcp = (() => {
+            try {
+                return fs
+                    .readFileSync(path.join(os.homedir(), ".codex", "config.toml"), "utf-8")
+                    .includes("vexp");
+            }
+            catch {
+                return false;
+            }
+        })();
+        let cfg = null;
+        try {
+            cfg = JSON.parse(fs.readFileSync(hooksJson, "utf-8"));
+        }
+        catch { /* absent */ }
+        if (!cfg) {
+            // Only a finding for someone who actually uses Codex here.
+            line(codexMcp ? WARN : OK, codexMcp
+                ? "no .codex/hooks.json, but vexp MCP is configured for Codex — the tools work and the per-prompt orientation was never installed. Run 'vexp setup' here (needs Codex >= 0.129)."
+                : "no .codex/hooks.json (Codex not configured here)");
+        }
+        else {
+            // Two shapes exist in the wild: the installer nests under "hooks", and
+            // files from earlier versions (or edited by hand) carry the event at the
+            // top level. Reading only one of them would leave the other undiagnosable
+            // — and the flat one is what the user who reported this had on disk.
+            const events = (Array.isArray(cfg?.hooks?.UserPromptSubmit)
+                ? cfg.hooks.UserPromptSubmit
+                : Array.isArray(cfg?.UserPromptSubmit)
+                    ? cfg.UserPromptSubmit
+                    : []);
+            const hook = events
+                .flatMap((m) => (Array.isArray(m?.hooks) ? m.hooks : []))
+                .find((h) => typeof h?.command === "string" && h.command.includes("vexp-hint"));
+            if (!hook) {
+                line(WARN, "hooks.json has no vexp UserPromptSubmit entry — re-run 'vexp setup'.");
+            }
+            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, 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,
+                    encoding: "utf-8",
+                });
+                const baked = (() => {
+                    try {
+                        // 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.`);
+                }
+                else if (r.status !== 0) {
+                    line(BAD, `hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 160)}` : ""} — Codex continues without vexp.`);
+                }
+                else if (baked && !fs.existsSync(baked)) {
+                    line(BAD, `hook runs but the binary it points at does not exist: ${baked} — it exits silently on every prompt. Re-run 'vexp setup' as the user that owns this install.`);
+                }
+                else {
+                    const why = String(r.stderr ?? "").trim().replace(/^vexp [\w-]+: /, "");
+                    line(OK, `UserPromptSubmit hook runs${why ? ` (this probe: ${why.slice(0, 120)})` : ""}`);
+                }
+            }
+        }
+    }
     // 5c) Cursor guard hook — same live-execution philosophy as 5b. Cursor's
     // hooks fail OPEN too (`failClosed` defaults to false), so a guard that
     // cannot spawn silently enforces nothing there as well. The guard's stdin

package/dist/hook-template.js

@@ -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,

package/dist/license.js

@@ -71,6 +71,15 @@ function readLastCheck() {
         return 0;
     }
 }
+/** Forget when we last checked in, so the next refresh is not throttled. */
+export function clearLastCheck() {
+    try {
+        fs.rmSync(getLastCheckPath(), { force: true });
+    }
+    catch {
+        /* best effort: a stale stamp only delays registration, never breaks it */
+    }
+}
 function writeLastCheck(ts) {
     try {
         fs.mkdirSync(path.dirname(getLastCheckPath()), { recursive: true });
@@ -289,6 +298,14 @@ export function activateLicense(jwt) {
     // leaving it would shadow the just-activated tier until it expired. The next
     // online refresh re-creates fresh.jwt at the new tier.
     removeFreshToken();
+    // Activation is the one moment we KNOW the user is at this machine, so it is
+    // the moment to register it. Clearing the throttle stamp makes the very next
+    // refresh run instead of waiting out the 24h backoff — without it the device
+    // does not appear on the dashboard until some later command happens to fall
+    // outside the window, and the page meanwhile says "Open vexp on any machine
+    // to register it" to someone who just did exactly that. Reported by a tier-4
+    // user whose dashboard read 0 of 10 right after activating.
+    clearLastCheck();
     return claims;
 }
 /** Remove the current license file (and any cached freshToken) */