vexp-cli 3.1.0 → 3.1.1

package/dist/doctor.js

@@ -5,7 +5,9 @@ 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";
+import { parseJsonc, isWsl, windsurfWslBridgeNote, windsurfGlobalMcpPath } from "./agent-config.js";
+import { resolveParentWorkspace, listWorkspaceRepos } from "./workspace-repos.js";
+import { CLI_VERSION } from "./version.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),
@@ -24,7 +26,8 @@ function vexpHome() {
 function discoverWorkspaceRoot(start) {
     for (const test of [
         (d) => fs.existsSync(path.join(d, ".vexp", "manifest.json")) || fs.existsSync(path.join(d, ".vexp", "index.db")),
-        (d) => fs.existsSync(path.join(d, ".vexp")),
+        // Bare .vexp — except home/VEXP_HOME, whose .vexp is vexp's state dir.
+        (d) => fs.existsSync(path.join(d, ".vexp")) && path.resolve(d) !== path.resolve(vexpHome()),
         (d) => fs.existsSync(path.join(d, ".git")),
     ]) {
         let cur = start;
@@ -223,7 +226,7 @@ export function coverageVerdict(cov) {
         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.`,
+            `\n        raise max_file_size_kb in .vexp/vexp.toml (0 = no cap) to include them, or exclude them on purpose with exclude_patterns — excluded files stop being counted here at the next reindex ('vexp index').`,
     };
 }
 /**
@@ -266,8 +269,85 @@ export function vsCodeMcpVerdict(cfg, wsRoot, exists = (p) => fs.existsSync(p))
     }
     return { level: OK, message: `.vscode/mcp.json vexp server: ${command} ${script ?? args.join(" ")}` };
 }
+/**
+ * How doctor runs a Codex `UserPromptSubmit` hook line: the way Codex does.
+ * On Windows Codex hands `cmd.exe /C` the WHOLE line wrapped in one more pair
+ * of quotes, verbatim (codex-rs/hooks engine/command_runner: `raw_arg`), and
+ * cmd strips that outer pair — which is why the installer may quote the
+ * script path. Passing the line as a normal argument instead lets Node escape
+ * the inner quotes, and cmd then looks for a program literally named
+ * `\"D:\…\vexp-hint.cmd\"` (field report, 2026-09-01: a correct hooks.json
+ * failed doctor's probe and passed once the user removed the quotes).
+ */
+export function codexHookSpawnSpec(cmdLine, platform = process.platform, comspec = process.env.COMSPEC) {
+    if (platform === "win32") {
+        return { file: comspec || "cmd.exe", args: ["/C", `"${cmdLine}"`], windowsVerbatimArguments: true };
+    }
+    return { file: "sh", args: ["-c", cmdLine], windowsVerbatimArguments: false };
+}
+function samePath(a, b) {
+    // The daemon registry lower-cases Windows roots; compare accordingly.
+    return path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
+}
+/**
+ * A connected repo of a multi-repo workspace has no daemon of its own: the
+ * parent's daemon serves it. Doctor run inside such a repo used to treat it as
+ * a standalone workspace — "daemon NOT reachable", "NOT registered" — while
+ * `vexp search` from the same directory answered fine (field report,
+ * 2026-09-01, nine repos). The link is `.vexp/parent_workspace.json` in the
+ * member; when that file is missing, any registered workspace whose
+ * workspace.json lists this directory is the parent.
+ */
+export function resolveMemberParent(root, registryRoots) {
+    const link = resolveParentWorkspace(root);
+    if (link) {
+        const alias = listWorkspaceRepos(link.parentRoot).find((r) => samePath(r.resolvedPath, root))?.alias
+            ?? path.basename(root);
+        return { parentRoot: link.parentRoot, alias, via: ".vexp/parent_workspace.json" };
+    }
+    for (const reg of registryRoots) {
+        if (samePath(reg, root))
+            continue;
+        const hit = listWorkspaceRepos(reg).find((r) => !r.isPrimary && samePath(r.resolvedPath, root));
+        if (hit)
+            return { parentRoot: reg, alias: hit.alias, via: `${path.join(reg, ".vexp", "workspace.json")} (daemon registry)` };
+    }
+    return null;
+}
+/**
+ * Coverage verdicts for the workspace at `root` AND every repo connected to
+ * it, each tagged with its alias. Each repo's indexer writes its own
+ * `.vexp/coverage.json`; reading only the primary's hid three oversized files
+ * in a connected repo from a doctor run at the primary (same report).
+ */
+export function workspaceCoverageFindings(root) {
+    const repos = listWorkspaceRepos(root);
+    const targets = repos.map((r) => ({ alias: r.alias, dir: r.resolvedPath, primary: r.isPrimary }));
+    if (!targets.some((t) => t.primary))
+        targets.unshift({ alias: path.basename(root), dir: root, primary: true });
+    const out = [];
+    for (const t of targets) {
+        let cov;
+        try {
+            cov = JSON.parse(fs.readFileSync(path.join(t.dir, ".vexp", "coverage.json"), "utf-8"));
+        }
+        catch {
+            continue; /* never indexed, or an index older than 2.7 */
+        }
+        const v = coverageVerdict(cov);
+        if (v)
+            out.push({ level: v.level, message: targets.length > 1 ? `[${t.alias}] ${v.message}` : v.message });
+    }
+    return out;
+}
 export async function runDoctor() {
     const home = vexpHome();
+    const regPath = path.join(home, ".vexp", "daemons.json");
+    let registry = {};
+    try {
+        registry = JSON.parse(fs.readFileSync(regPath, "utf-8"));
+    }
+    catch { /* absent */ }
     let warns = 0;
     let fails = 0;
     const line = (status, msg) => {
@@ -280,8 +360,15 @@ export async function runDoctor() {
     console.log(chalk.bold("\nvexp doctor — MCP / daemon diagnostics\n"));
     // 1) Workspace resolution for the current directory.
     console.log(chalk.bold("Workspace targeting"));
-    const ws = resolveWorkspace();
+    const resolved = resolveWorkspace();
+    const member = resolveMemberParent(resolved.root, Object.keys(registry));
+    const ws = member
+        ? { root: member.parentRoot, source: `repo '${member.alias}' of the multi-repo workspace, linked by ${member.via}` }
+        : resolved;
     console.log(`  cwd: ${process.cwd()}`);
+    if (member) {
+        line(OK, `this directory is repo '${member.alias}' of the multi-repo workspace at ${member.parentRoot} — served by that workspace's daemon; diagnostics below target it`);
+    }
     line(OK, `resolves to: ${ws.root}  (via ${ws.source})`);
     // A *global* VEXP_WORKSPACE env var overrides the per-session signal
     // (CLAUDE_PROJECT_DIR) for EVERY agent session, pinning Claude *and* Codex to
@@ -388,21 +475,12 @@ 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 */ }
+    // Every connected repo has its own coverage.json; each finding carries the
+    // repo alias so a run at the primary sees the whole workspace.
+    for (const f of workspaceCoverageFindings(ws.root))
+        line(f.level, f.message);
     // 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");
-    let registry = {};
-    try {
-        registry = JSON.parse(fs.readFileSync(regPath, "utf-8"));
-    }
-    catch { /* absent */ }
     const entries = Object.entries(registry);
     if (entries.length === 0) {
         line(OK, "no registered daemons (empty/absent registry)");
@@ -540,6 +618,32 @@ export async function runDoctor() {
             console.log(chalk.dim("        server log: Command Palette → 'MCP: List Servers' → vexp → Show Output (channel 'MCP: vexp'); daemon log: .vexp/daemon.log"));
         }
     }
+    // 5a-bis) WSL: agents on the Windows side read Windows-side configs, which
+    // nothing running in WSL can see or write. Say so, and for Windsurf hand
+    // over the exact entry (field report, 2026-09-01: a user built the bridge by
+    // hand and found no documentation).
+    if (isWsl()) {
+        console.log(chalk.bold("\nWSL"));
+        const distro = process.env.WSL_DISTRO_NAME ?? "?";
+        line(OK, `running inside WSL (${distro}) — editors and apps on the Windows side read their own configs there; vexp writes only WSL-side files`);
+        const windsurfHere = fs.existsSync(path.join(ws.root, ".windsurf")) || fs.existsSync(path.join(ws.root, ".devin"));
+        if (windsurfHere) {
+            let bin = "vexp-core";
+            try {
+                const { getBinaryPath } = await import("./binary.js");
+                bin = getBinaryPath();
+            }
+            catch { /* note still useful without the exact binary path */ }
+            const bundle = path.join(path.dirname(new URL(import.meta.url).pathname), "..", "mcp", "mcp-server.cjs");
+            line(WARN, `Windsurf/Devin Desktop on Windows will not read ${windsurfGlobalMcpPath()} (WSL home). Windows-side entry to paste:`);
+            for (const l of windsurfWslBridgeNote(ws.root, bin, fs.existsSync(bundle) ? bundle : undefined).split("\n")) {
+                console.log(chalk.dim(`        ${l}`));
+            }
+        }
+        else {
+            console.log(chalk.dim("        Windows-side apps (Codex app, Claude Desktop, Windsurf) need a wsl.exe bridge entry: https://vexp.dev/docs#windows-wsl"));
+        }
+    }
     // 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
@@ -792,15 +896,18 @@ export async function runDoctor() {
                 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
+                // Run it, through the same shell Codex would use — cmd.exe on
+                // Windows (COMSPEC) with the line wrapped the way Codex wraps it, sh
+                // elsewhere (codexHookSpawnSpec). 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], {
+                const spec = codexHookSpawnSpec(cmdLine);
+                const r = spawnSync(spec.file, spec.args, {
+                    windowsVerbatimArguments: spec.windowsVerbatimArguments,
                     env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
                     input: JSON.stringify({ session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root }),
                     timeout: 10000,
@@ -901,7 +1008,19 @@ export async function runDoctor() {
     console.log(chalk.bold("\nHTTP MCP supervisor (~/.vexp/mcp.pid)"));
     try {
         const rec = JSON.parse(fs.readFileSync(path.join(home, ".vexp", "mcp.pid"), "utf-8"));
-        line(isAlive(rec.pid) ? OK : WARN, `pid ${rec.pid} on :${rec.port} — ${isAlive(rec.pid) ? "alive" : "DEAD (stale pid file)"}`);
+        const alive = isAlive(rec.pid);
+        line(alive ? OK : WARN, `pid ${rec.pid} on :${rec.port} — ${alive ? "alive" : "DEAD (stale pid file)"}${rec.version ? ` · v${rec.version}` : ""}`);
+        // The supervisor is replaced on version mismatch only when a vexp command
+        // next runs; until then every HTTP client (Codex http transport, a
+        // `serverUrl` entry) talks to the OLD build — which advertises the old
+        // tool surface (2 tools before 2.7.0) and none of the newer fixes. A user
+        // saw two vexp servers with different tool counts and could not tell why.
+        if (alive && rec.version && rec.version !== CLI_VERSION) {
+            line(WARN, `the HTTP MCP server on :${rec.port} is v${rec.version} but this CLI is v${CLI_VERSION} — HTTP clients get the old build until it is replaced — run 'vexp setup' (or any indexing/search command, e.g. 'vexp savings') in the project and the current CLI takes it over`);
+        }
+        else if (alive && !rec.version) {
+            line(WARN, `the HTTP MCP server on :${rec.port} predates version tracking (older than 2.4) — run 'vexp setup' (or 'vexp savings') in the project so the current CLI replaces it and HTTP clients get v${CLI_VERSION}`);
+        }
     }
     catch {
         line(OK, "not running (no mcp.pid)");
@@ -916,4 +1035,8 @@ export async function runDoctor() {
         console.log(chalk.dim("  Tips: 'vexp daemon-cmd restart' restarts the workspace daemon; 'vexp setup' rewrites agent configs; restart Codex to drop a cached config."));
     }
     console.log("");
+    // Scripts and CI read the exit code, not the colors: any FAIL exits 1.
+    // Warnings alone stay 0 — advice, not breakage (field request, 2026-09-02).
+    if (fails > 0)
+        process.exitCode = 1;
 }

package/dist/serve.js

@@ -108,6 +108,33 @@ export function isOwnerEntry(ws, sock) {
  *  cross-wired daemon serving the child's index on the parent's socket, which
  *  then blocked every legitimate restart of the parent (it held the bind) and
  *  never matched the parent's config. Routing rows must never be spawned. */
+/** A linked git worktree: `.git` is a FILE whose `gitdir:` points into
+ *  `<main>/.git/worktrees/`. Agent harnesses create one per parallel task
+ *  (Claude Code under `.claude/worktrees/`, Cursor, plain `git worktree add`
+ *  — the detection is the file's content, never a path convention). After a
+ *  reboot the supervisor resurrected 15 of them alongside 2 canonical repos
+ *  and took a 16-core host down: ~1,585% CPU, 2 GB/s of reads, hard reset
+ *  (field incident, 2026-09-02, tier 3). Worktree daemons run on demand
+ *  only; resurrection is for canonical workspaces. A submodule's gitdir
+ *  points at `/.git/modules/` and is left alone. Mirrors vexp-core
+ *  utils::git_project_root. */
+export function isLinkedWorktree(ws) {
+    try {
+        const dotGit = path.join(ws, ".git");
+        if (fs.statSync(dotGit).isDirectory())
+            return false;
+        const gitdir = fs
+            .readFileSync(dotGit, "utf-8")
+            .split(/\r?\n/)
+            .find((l) => l.trim().startsWith("gitdir:"));
+        if (!gitdir)
+            return false;
+        return gitdir.replace(/\\/g, "/").includes("/.git/worktrees/");
+    }
+    catch {
+        return false;
+    }
+}
 export function resurrectionPlan(reg) {
     const bySock = new Map();
     for (const [ws, sock] of Object.entries(reg)) {
@@ -156,11 +183,25 @@ async function resurrectAll() {
             appendLog(`registry prune: ${ws} (no manifest)`);
             continue;
         }
+        if (isLinkedWorktree(ws)) {
+            appendLog(`registry prune: ${ws} (linked git worktree — on-demand only, never resurrected)`);
+            continue;
+        }
         pruned[ws] = sock;
     }
     const resurrected = new Map();
+    // Stagger actual spawns: every freshly started daemon runs its checkout
+    // sync and reconcile immediately, and a burst of them after a reboot is an
+    // IO storm (same incident as above). Rows whose socket is already alive
+    // cost nothing and are not delayed.
+    let spawnedOne = false;
     for (const { ws, sock } of resurrectionPlan(pruned)) {
+        const alive = await isSocketAlive(sock);
+        if (!alive && spawnedOne)
+            await new Promise((r) => setTimeout(r, 2000));
         resurrected.set(sock, await resurrectDaemon(ws, sock));
+        if (!alive)
+            spawnedOne = true;
     }
     for (const [ws, sock] of Object.entries(pruned)) {
         if (resurrected.get(sock))