vexp-cli 3.1.2 → 3.1.3

package/dist/cli.js

@@ -74,6 +74,14 @@ program.hook("preAction", async (_thisCmd, actionCmd) => {
     // 2026-09-05). Doing nothing quietly is the one outcome that cannot be
     // told apart from success.
     if (!eff) {
+        // `index` and `init` are the commands that CREATE a workspace, so telling
+        // them to go run `vexp setup` first is advice the command is in the middle
+        // of superseding — and it read as a contradiction to a user watching one
+        // invocation warn that no workspace exists and the next one start a daemon
+        // for it (field report, 2026-09-08). The bootstrap still does nothing here;
+        // it just does not misdirect.
+        if (actionCmd.name() === "index" || actionCmd.name() === "init")
+            return;
         console.error(chalk.yellow(`  ⚠ no vexp workspace found from ${process.cwd()} — the daemon and the MCP server were NOT started or updated.`));
         console.error(chalk.dim(`     vexp walks up for .vexp/manifest.json; run 'vexp setup' in the workspace root.`));
         return;
@@ -645,8 +653,9 @@ program
 program
     .command("doctor")
     .description("Diagnose vexp MCP/daemon state — workspace drift, stale daemons, Codex transport, license (no daemon needed)")
-    .action(async () => {
-    await runDoctor();
+    .option("--report [file]", "Also write a shareable Markdown report: this diagnosis, the local tool-call ledger (counts and timings, never contents), daemon log warnings, config — secrets masked (default: .vexp/vexp-report.md)")
+    .action(async (opts) => {
+    await runDoctor({ report: opts.report });
 });
 program
     .command("setup [dir]")

package/dist/doctor.js

@@ -4,10 +4,12 @@ import * as path from "path";
 import * as net from "net";
 import { spawnSync } from "child_process";
 import chalk from "chalk";
-import { socketPathFor } from "./socket-path.js";
+import { socketPathFor, socketPathMargin } from "./socket-path.js";
 import { parseJsonc, isWsl, windsurfWslBridgeNote, windsurfGlobalMcpPath } from "./agent-config.js";
 import { resolveParentWorkspace, listWorkspaceRepos } from "./workspace-repos.js";
 import { CLI_VERSION } from "./version.js";
+import { parentPid } from "./mcp-supervisor.js";
+import { slowMountNotice } from "./slow-mount.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),
@@ -98,6 +100,32 @@ function jwtExp(file) {
         return null;
     }
 }
+/**
+ * What doctor should say about the process that spawned the MCP server.
+ *
+ * Pure, and exported, because this guard has now been wrong twice in the same
+ * way. The first version compared the recorded `spawnedBy` against ours and
+ * returned on anything else — so a record written BEFORE that field existed
+ * took the same branch as a record that matches, and the disclosure was
+ * silent on the one upgrade it exists for: the first one after it shipped
+ * (field report, 2026-09-08).
+ *
+ * "I cannot tell" and "there is no mismatch" are different answers and must
+ * never share a branch again.
+ */
+export function supervisorVerdict(rec, cliVersion, io) {
+    const by = typeof rec.spawnedBy === "string" ? rec.spawnedBy : undefined;
+    if (by === cliVersion)
+        return { kind: "ok" };
+    // The supervisor is the PARENT of the server, which is observable whatever
+    // wrote the record — and is how the field report identified it.
+    const recorded = typeof rec.spawnedByPid === "number" ? rec.spawnedByPid : undefined;
+    const pid = recorded ?? (typeof rec.pid === "number" ? io.parentOf(rec.pid) : undefined);
+    if (pid === undefined) {
+        return by ? { kind: "stale", by } : { kind: "unknown" };
+    }
+    return { kind: "stale", by, pid, alive: io.alive(pid) };
+}
 function isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -345,7 +373,206 @@ export function workspaceCoverageFindings(root) {
     }
     return out;
 }
-export async function runDoctor() {
+export const SUPPORT_EMAIL = "staff@vexp.dev";
+export const DEFAULT_REPORT_FILE = path.join(".vexp", "vexp-report.md");
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*m/g;
+export function stripAnsi(s) {
+    return s.replace(ANSI, "");
+}
+/**
+ * Mask secret-shaped values in text that leaves the machine. The Rust
+ * shield (`shield::redact_secrets`) is the reference; this is the subset a
+ * doctor report needs: known token shapes and KEY=value assignments. Never
+ * enough of the value to reconstruct it, always enough to see there was one.
+ */
+const SECRET_SHAPES = [
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, // JWT
+    /\b(?:ghp|gho|ghs|ghr)_[A-Za-z0-9]{20,}\b/g, // GitHub tokens
+    /\bgithub_pat_[A-Za-z0-9_]{22,}\b/g,
+    /\bAKIA[A-Z0-9]{16}\b/g, // AWS access key id
+    /\b(?:sk|pylf|xox[abp])[-_][A-Za-z0-9_-]{12,}\b/g, // OpenAI / Logfire / Slack shapes
+];
+const ASSIGNED_SECRET = /((?:api[_-]?key|apikey|token|secret|password|passwd|credential|private[_-]?key|access[_-]?key)[A-Za-z0-9_-]*\s*[=:]\s*["']?)([^\s"',;)}]{8,})/gi;
+function maskValue(v) {
+    return v.length <= 6 ? "*".repeat(v.length) : `${v.slice(0, 3)}***${v.slice(-2)}`;
+}
+export function maskSecretsForReport(text) {
+    let out = text;
+    for (const re of SECRET_SHAPES)
+        out = out.replace(re, (m) => maskValue(m));
+    out = out.replace(ASSIGNED_SECRET, (whole, key, val) => /[$<{]/.test(val) ? whole : key + maskValue(val));
+    return out;
+}
+/**
+ * The report a tester can hand over without editing it first.
+ *
+ * Field request (2026-09-09): "make a way to ask AI to generate a usage
+ * report into an .md file that can be sent to you. that way you can get
+ * great bug reports" — from a user whose agent had just done exactly that
+ * by reading index.db by hand. Sections: what doctor saw, the local
+ * tool-call ledger (counts and timings, never prompt or file contents), the
+ * daemon log's warnings, the config. Secret-shaped values are masked
+ * everywhere; paths stay, and the header says so.
+ */
+export function buildDoctorReport(i) {
+    const head = [
+        `Generated ${i.generatedAt} · vexp-cli ${i.cliVersion} · binary ${i.binaryVersion ?? "not runnable"} · ${i.platform} · node ${i.nodeVersion}${i.wsl ? " · WSL" : ""}`,
+        `Workspace: ${i.root}`,
+    ].join("\n");
+    const parts = [
+        "# vexp report",
+        "",
+        head,
+        "",
+        "Written by `vexp doctor --report`. It holds the doctor output, the local tool-call ledger " +
+            "(counts and timings only — never prompt text or file contents), the daemon log's warnings " +
+            "and errors, and the vexp config. Secret-shaped values are masked; file paths are visible. " +
+            `Review it, then send it to ${SUPPORT_EMAIL} or attach it to your issue.`,
+    ];
+    if (i.mountNotice)
+        parts.push("", `> **Filesystem:** ${i.mountNotice}`);
+    parts.push("", "## Doctor", "", "```", stripAnsi(i.doctorText).trim(), "```");
+    parts.push("", "## Usage ledger", "");
+    parts.push(i.ledgerMarkdown?.trim() || `ledger unavailable: ${i.ledgerError ?? "unknown error"}`);
+    parts.push("", `## Daemon log${i.logName ? ` (.vexp/${i.logName})` : ""}: warnings and errors`, "");
+    if (!i.logName)
+        parts.push("no daemon log found under .vexp/");
+    else if (i.logWarnings.length === 0)
+        parts.push("no warnings or errors in the last 3000 lines");
+    else
+        parts.push("```", ...i.logWarnings, "```");
+    parts.push("", "## Config (.vexp/vexp.toml)", "");
+    parts.push(i.configText === null ? "absent — defaults in use" : "```toml\n" + i.configText.trim() + "\n```");
+    parts.push("");
+    return maskSecretsForReport(parts.join("\n"));
+}
+/**
+ * Warnings and errors from the daemon log tail, ANSI stripped, newest last.
+ * Repeats of one message (the same config warning on every start) collapse
+ * into the latest occurrence with a count: a report is read by a person,
+ * and eighty identical lines hide the one that differs.
+ */
+export function logWarningsFrom(text, keep = 80, scan = 3000) {
+    const lines = stripAnsi(text).trimEnd().split("\n").slice(-scan);
+    const hits = lines.filter((l) => /\b(WARN|ERROR|panicked)\b/.test(l));
+    const byMessage = new Map();
+    for (const l of hits) {
+        const key = l.replace(/^\S*\d{4}-\d{2}-\d{2}T[\d:.]+Z?\s*/, "");
+        const cur = byMessage.get(key);
+        if (cur) {
+            cur.last = l;
+            cur.count++;
+            byMessage.delete(key); // re-insert so the map stays in last-seen order
+            byMessage.set(key, cur);
+        }
+        else
+            byMessage.set(key, { last: l, count: 1 });
+    }
+    return [...byMessage.values()]
+        .map(({ last, count }) => (count > 1 ? `${last}  (x${count})` : last))
+        .slice(-keep);
+}
+/** Gather every input on this machine and write the report. Returns its path. */
+export async function writeDoctorReport(o) {
+    let bin = null;
+    try {
+        const { getBinaryPath } = await import("./binary.js");
+        bin = getBinaryPath();
+    }
+    catch {
+        /* no binary: the report says so and still carries everything else */
+    }
+    const run = (args, timeout) => bin ? spawnSync(bin, args, { cwd: o.root, timeout, encoding: "utf-8" }) : null;
+    const ver = run(["--version"], 5000);
+    const binaryVersion = ver && ver.status === 0 ? String(ver.stdout).trim().split(/\s+/).pop() ?? null : null;
+    const ledger = run(["usage-report", "--days", "30"], 30000);
+    let ledgerMarkdown = null;
+    let ledgerError;
+    if (!ledger)
+        ledgerError = "vexp-core binary not found";
+    else if (ledger.error)
+        ledgerError = ledger.error.message;
+    else if (ledger.status !== 0) {
+        const err = String(ledger.stderr ?? "").trim().split("\n")[0];
+        ledgerError = /unrecognized subcommand|unexpected argument/.test(err)
+            ? `binary ${binaryVersion ?? "?"} predates usage-report (3.1.3) — update vexp-core`
+            : err || `exit ${ledger.status}`;
+    }
+    else
+        ledgerMarkdown = String(ledger.stdout);
+    let logName = null;
+    let logWarnings = [];
+    for (const name of ["daemon.log", "vexp.log"]) {
+        try {
+            const text = fs.readFileSync(path.join(o.root, ".vexp", name), "utf-8");
+            logName = name;
+            logWarnings = logWarningsFrom(text);
+            break;
+        }
+        catch {
+            /* try the next name */
+        }
+    }
+    let configText = null;
+    try {
+        configText = fs.readFileSync(path.join(o.root, ".vexp", "vexp.toml"), "utf-8");
+    }
+    catch {
+        /* absent: defaults */
+    }
+    const md = buildDoctorReport({
+        generatedAt: new Date().toISOString(),
+        cliVersion: CLI_VERSION,
+        binaryVersion,
+        platform: `${process.platform} ${process.arch}`,
+        nodeVersion: process.version,
+        wsl: isWsl(),
+        root: o.root,
+        doctorText: o.doctorText,
+        ledgerMarkdown,
+        ledgerError,
+        logName,
+        logWarnings,
+        configText,
+        mountNotice: slowMountNotice(o.root),
+    });
+    const dest = o.outFile ? path.resolve(o.outFile) : path.join(o.root, DEFAULT_REPORT_FILE);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, md);
+    return dest;
+}
+export async function runDoctor(opts = {}) {
+    // --report: tee everything doctor prints into the report, colors stripped.
+    const captured = [];
+    const origLog = console.log;
+    if (opts.report) {
+        console.log = (...args) => {
+            origLog(...args);
+            captured.push(stripAnsi(args.map((a) => String(a)).join(" ")));
+        };
+    }
+    let reportRoot = null;
+    try {
+        await doctorChecks((root) => {
+            reportRoot = root;
+        });
+    }
+    finally {
+        console.log = origLog;
+    }
+    if (opts.report) {
+        const dest = await writeDoctorReport({
+            root: reportRoot ?? process.cwd(),
+            doctorText: captured.join("\n"),
+            outFile: typeof opts.report === "string" ? opts.report : undefined,
+        });
+        const kb = Math.max(1, Math.round(fs.statSync(dest).size / 1024));
+        console.log(`  [${OK}] report written to ${dest} (${kb} KB) — review it, then send it to ${SUPPORT_EMAIL}`);
+        console.log("");
+    }
+}
+async function doctorChecks(onWorkspace) {
     const home = vexpHome();
     const regPath = path.join(home, ".vexp", "daemons.json");
     let registry = {};
@@ -370,6 +597,7 @@ export async function runDoctor() {
     const ws = member
         ? { root: member.parentRoot, source: `repo '${member.alias}' of the multi-repo workspace, linked by ${member.via}` }
         : resolved;
+    onWorkspace(ws.root);
     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`);
@@ -393,6 +621,18 @@ export async function runDoctor() {
     line(live ? OK : WARN, `daemon socket ${live ? "reachable" : "NOT reachable"}: ${sock}`);
     if (!live)
         console.log(chalk.dim(`        → run: vexp daemon-cmd start   (or 'vexp daemon-cmd restart')`));
+    // The /tmp relocation is silent by construction — every client computes
+    // the same fallback and none of them says so. A tester measured his
+    // Claude Code worktrees at 89 of the 100 characters and pointed out that
+    // a longer auto-generated name would move the socket with nothing
+    // announcing it. Announce it here, and the margin before it.
+    const m = socketPathMargin(ws.root);
+    if (m.relocated) {
+        line(OK, `socket lives in /tmp because ${m.candidate} is ${m.length} chars, over the ${m.limit} a Unix socket path allows — every vexp client computes the same fallback, nothing is missing`);
+    }
+    else if (Number.isFinite(m.margin) && m.margin <= 15) {
+        line(WARN, `socket path is ${m.length} of ${m.limit} chars (${m.margin} to spare): a longer directory name — a Claude Code worktree is auto-named — moves this workspace's socket to /tmp/vexp-<hash>.sock. Nothing breaks; when a daemon looks absent, read the 'daemon socket' line above first`);
+    }
     // 2.3 B1/B2 — live daemon truth: coverage + active compressor. The config can
     // say "LLM enabled" while the daemon serves rule-compressed output (config
     // race / stale daemon / non-LLM build); only the daemon knows what's active.
@@ -658,6 +898,17 @@ export async function runDoctor() {
             console.log(chalk.dim("        Windows-side apps (Codex app, Claude Desktop, Windsurf) need a wsl.exe bridge entry: https://vexp.dev/docs#windows-wsl"));
         }
     }
+    // 5a-ter) Filesystem: a workspace behind an OS boundary (9p, drvfs, a
+    // network share) makes every vexp call 10-50x slower and reads as a vexp
+    // bug (field report, 2026-09-09: verify_done at 41-170 s on /app over 9p,
+    // every other line of doctor green).
+    {
+        const slow = slowMountNotice(ws.root);
+        if (slow) {
+            console.log(chalk.bold("\nFilesystem"));
+            line(WARN, slow);
+        }
+    }
     // 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
@@ -1028,14 +1279,23 @@ export async function runDoctor() {
     // since before the upgrade, holding its own version in memory
     // (field report, 2026-09-06).
     const staleSupervisorLine = (rec) => {
-        const by = typeof rec.spawnedBy === "string" ? rec.spawnedBy : undefined;
-        if (!by || by === CLI_VERSION)
+        const v = supervisorVerdict(rec, CLI_VERSION, {
+            parentOf: parentPid,
+            alive: isAlive,
+        });
+        if (v.kind === "ok")
+            return;
+        if (v.kind === "unknown") {
+            line(WARN, `cannot tell which build spawned that server — the record predates the field and its parent process could not be read.\n` +
+                `        If :${rec.port} keeps reverting to an older version, a resident 'vexp serve' is the cause: find it (ps) and end it.`);
             return;
-        const pid = typeof rec.spawnedByPid === "number" ? rec.spawnedByPid : undefined;
-        const stillUp = pid !== undefined && isAlive(pid);
+        }
         const who = rec.owner === "serve" ? "'vexp serve' supervisor" : `${rec.owner ?? "process"}`;
-        line(WARN, `that server was spawned by a ${who} running v${by}, not v${CLI_VERSION}` +
-            (pid ? ` (pid ${pid}${stillUp ? ", still running" : ", already gone"})` : "") +
+        const provenance = v.by
+            ? `running v${v.by}, not v${CLI_VERSION}`
+            : `started before this CLI was installed — its version was not recorded, so it is a build older than v${CLI_VERSION}`;
+        line(WARN, `that server was spawned by a ${who} ${provenance}` +
+            (v.pid ? ` (pid ${v.pid}${v.alive ? ", still running" : ", already gone"})` : "") +
             `\n        an older supervisor reclaims :${rec.port} on its own schedule and cannot be stopped by re-running setup` +
             // Ending it is the whole remediation: login autostart (or the next
             // `vexp` command) starts a fresh supervisor, which reads the current
@@ -1044,7 +1304,17 @@ export async function runDoctor() {
             // else — and the `vexp setup` this line used to recommend blocks on
             // an interactive prompt, which for the reader of a doctor line is a
             // hang, not a fix (field report, 2026-09-07).
-            (stillUp ? `\n        end it — 'kill ${pid}' — a fresh supervisor starts on its own and serves the current build` : ""));
+            (v.alive
+                ? `\n        end it FIRST — 'kill ${v.pid}' — before restarting any daemon.` +
+                    // The order is load-bearing and nothing said so: an old
+                    // supervisor's health loop rebuilds the daemon registry every 60s
+                    // from its own rows, so it deletes each daemon's registration as
+                    // fast as the daemon writes it. Restart the daemons first and they
+                    // come back invisible — and nobody restarts a daemon they have
+                    // just restarted (field report, 2026-09-08).
+                    `\n        Its health loop deletes daemon registrations as fast as they are written, so a daemon` +
+                    `\n        restarted before it is gone comes back invisible to 'vexp daemons'.`
+                : ""));
     };
     // 6) HTTP MCP supervisor.
     console.log(chalk.bold("\nHTTP MCP supervisor (~/.vexp/mcp.pid)"));

package/dist/mcp-supervisor.js

@@ -3,7 +3,7 @@ import { CLI_VERSION } from "./version.js";
 import * as net from "net";
 import * as os from "os";
 import * as path from "path";
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import { randomUUID } from "crypto";
 import { getMcpServerPath } from "./binary.js";
 const DEFAULT_PORT = 7821;
@@ -112,6 +112,29 @@ export function resolveOrGenerateMcpToken() {
  * ships it — the build a client will actually be served, as opposed to the
  * version of whatever process happens to be spawning it.
  */
+/**
+ * The parent of a running process, or undefined.
+ *
+ * The supervisor that spawned the MCP server is its parent, and that is true
+ * however old the build that wrote ~/.vexp/mcp.pid — which is what makes it
+ * the right evidence for a record written before vexp recorded the spawner.
+ * Best-effort by design: an unreadable parent must degrade to "cannot tell",
+ * never to silence.
+ */
+export function parentPid(pid) {
+    try {
+        const r = process.platform === "win32"
+            ? spawnSync("powershell", ["-NoProfile", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").ParentProcessId`], { encoding: "utf-8", timeout: 4000 })
+            : spawnSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf-8", timeout: 4000 });
+        const n = Number.parseInt(String(r.stdout ?? "").trim(), 10);
+        // pid 1 is init adopting an orphan: a real parent, but never OUR
+        // supervisor, and naming it would invite someone to kill init.
+        return Number.isFinite(n) && n > 1 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function mcpBundleVersion(mcpPath) {
     const pkg = path.resolve(path.dirname(mcpPath), "..", "package.json");
     try {
@@ -167,6 +190,18 @@ export async function ensureMcpHttpServer(opts = {}) {
             if (!isOlderVersion(existing.version, CLI_VERSION)) {
                 return { pid: existing.pid, port, started: false };
             }
+            // Name the process that will undo this in sixty seconds, HERE, where the
+            // takeover happens — a user who never runs doctor otherwise watches the
+            // port revert with nothing to read. The supervisor is the parent of the
+            // server we are about to end; the recorded pid, when a recent build
+            // wrote it, says the same thing without a process lookup.
+            const boss = existing.spawnedByPid ?? parentPid(existing.pid);
+            if (boss !== undefined && isPidAlive(boss)) {
+                console.error(`  ⚠ replacing the MCP server on :${port} (was v${existing.version ?? "pre-2.4"}). ` +
+                    `It was started by pid ${boss}, a supervisor from an older install.\n` +
+                    `     If :${port} reverts, end that process FIRST — before restarting any daemon: its ` +
+                    `health loop deletes daemon registrations as fast as they are written.`);
+            }
             try {
                 process.kill(existing.pid, "SIGTERM");
             }

package/dist/slow-mount.js

@@ -0,0 +1,81 @@
+/**
+ * Slow-filesystem detection for doctor.
+ *
+ * CLI and VS Code twins: packages/vexp-cli/src/slow-mount.ts and
+ * packages/vexp-vscode/src/slow-mount.ts must stay byte-identical (a
+ * lockstep test compares them). Pure functions take the /proc/mounts text
+ * so they are testable anywhere; only `slowMountNotice` touches the OS.
+ *
+ * Field report (2026-09-09): a 229-file repo on /app inside Docker Desktop,
+ * a Windows drive over 9p. verify_done at 41-170 s, 19 slow-statement
+ * warnings from SQLite (a bare INSERT at 1.25 s), 49 slow connection
+ * acquires. Nothing in vexp was wrong on that machine except that the whole
+ * workspace, index included, sat behind an OS boundary. Doctor said
+ * everything was [OK]. It now says this.
+ */
+import * as fs from "fs";
+/** Filesystem types where every stat, read and git walk crosses an OS boundary. */
+export const SLOW_FS_TYPES = {
+    "9p": "a host drive mounted over 9p (WSL2 /mnt/*, Docker Desktop bind mount)",
+    drvfs: "a Windows drive mounted in WSL (drvfs)",
+    "fuse.grpcfuse": "a macOS host folder bind-mounted into Docker Desktop (grpcfuse)",
+    virtiofs: "a host folder shared into a VM (virtiofs)",
+    vboxsf: "a VirtualBox shared folder",
+    prl_fs: "a Parallels shared folder",
+    cifs: "a network share (CIFS/SMB)",
+    smb3: "a network share (SMB3)",
+    nfs: "a network share (NFS)",
+    nfs4: "a network share (NFS)",
+    "fuse.sshfs": "a remote folder over sshfs",
+};
+/** The mount that holds `root`: the longest mount point that is a prefix of it. */
+export function mountFor(root, mountsText) {
+    let best = null;
+    for (const line of mountsText.split("\n")) {
+        const parts = line.split(" ");
+        if (parts.length < 3)
+            continue;
+        // /proc/mounts escapes spaces in mount points as \040.
+        const mountPoint = parts[1].replace(/\\040/g, " ");
+        const fsType = parts[2];
+        const prefix = mountPoint.endsWith("/") ? mountPoint : mountPoint + "/";
+        if (root === mountPoint || root.startsWith(prefix)) {
+            if (!best || mountPoint.length > best.mountPoint.length)
+                best = { mountPoint, fsType };
+        }
+    }
+    return best;
+}
+/** The WARN text when the workspace sits on a slow mount; null when it does not. */
+export function slowMountVerdict(root, mountsText) {
+    const m = mountFor(root, mountsText);
+    if (!m)
+        return null;
+    const what = SLOW_FS_TYPES[m.fsType];
+    if (!what)
+        return null;
+    return (`workspace is on ${what}: ${m.fsType} at ${m.mountPoint}. Every stat, read and git walk ` +
+        "crosses an OS boundary, 10-50x slower than a native disk; indexing, verify_done and the " +
+        "SQLite index in .vexp/ all pay it on every call. Keep the clone on the Linux filesystem " +
+        "(WSL: under ~, not /mnt/c; Docker: a named volume, not a bind mount from the host).");
+}
+/** Linux only: reads /proc/mounts. Any other platform, or an unreadable table, is silent. */
+export function slowMountNotice(root) {
+    if (process.platform !== "linux")
+        return null;
+    let text;
+    try {
+        text = fs.readFileSync("/proc/mounts", "utf8");
+    }
+    catch {
+        return null;
+    }
+    let real = root;
+    try {
+        real = fs.realpathSync(root);
+    }
+    catch {
+        /* an unresolvable root is still matchable as given */
+    }
+    return slowMountVerdict(real, text);
+}

package/dist/socket-path.js

@@ -27,6 +27,30 @@ export function socketPathFor(workspaceRoot) {
         return candidate;
     return `/tmp/vexp-${fnvHash(workspaceRoot).slice(0, 12)}.sock`;
 }
+/** Longest `<root>/.vexp/daemon.sock` vexp binds in place; past it the socket lives in /tmp. */
+export const UNIX_SOCKET_PATH_LIMIT = 100;
+/**
+ * How close a workspace is to the relocation above — the number doctor
+ * prints. A tester measured his Claude Code worktrees at 78-89 characters
+ * (auto-named `adjective-name-hash` directories under `.claude/worktrees/`)
+ * and found nothing that would have announced the move when a longer name
+ * crossed the line (field report, 2026-09-10). On Windows there is no path
+ * to measure: the pipe name is a hash.
+ */
+export function socketPathMargin(workspaceRoot) {
+    const candidate = path.join(workspaceRoot, ".vexp", "daemon.sock");
+    if (process.platform === "win32") {
+        return { candidate, length: candidate.length, limit: UNIX_SOCKET_PATH_LIMIT, margin: Infinity, relocated: false };
+    }
+    const length = candidate.length;
+    return {
+        candidate,
+        length,
+        limit: UNIX_SOCKET_PATH_LIMIT,
+        margin: UNIX_SOCKET_PATH_LIMIT - length,
+        relocated: length > UNIX_SOCKET_PATH_LIMIT,
+    };
+}
 /** FNV-1a 64-bit, hex, unpadded — mirrors md5_hash() in vexp-core/src/utils.rs. */
 export function fnvHash(input) {
     let hash = BigInt("0xcbf29ce484222325");