vexp-cli 3.1.1 → 3.1.3

package/dist/agent-config.js

@@ -2918,7 +2918,11 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
     let root = {};
     if (fs.existsSync(hooksJsonPath)) {
         try {
-            root = JSON.parse(fs.readFileSync(hooksJsonPath, "utf-8"));
+            // parseJsonc, not JSON.parse: every other config reader here is
+            // BOM-tolerant and this one was missed. Windows PowerShell 5.1 writes
+            // JSON with a UTF-8 BOM, and a user who edits .codex/hooks.json by hand
+            // there would have the hook silently left unregistered.
+            root = parseJsonc(fs.readFileSync(hooksJsonPath, "utf-8"));
         }
         catch {
             warnUnparseable(hooksJsonPath);

package/dist/cli.js

@@ -66,13 +66,32 @@ program.hook("preAction", async (_thisCmd, actionCmd) => {
     // the parent, so we boot (or reuse) the parent daemon instead of spawning
     // a conflicting one for the child.
     const eff = findEffectiveWorkspace();
-    if (!eff)
+    // Say so. Bootstrapping is what replaces a stale daemon and takes over a
+    // stale MCP server on :7821, and it is silently skipped outside a
+    // configured workspace: a tester ran the command doctor had suggested from
+    // a package subdirectory of a monorepo, got no error and no takeover, and
+    // reasonably concluded the server had been replaced (tier-4 field report,
+    // 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;
+    }
     let binaryPath;
     try {
         binaryPath = getBinaryPath();
     }
-    catch {
+    catch (err) {
+        console.error(chalk.yellow(`  ⚠ vexp-core binary not resolved (${err instanceof Error ? err.message : err}) — nothing was started or updated.`));
         return;
     }
     // Full bootstrap: daemon + MCP + autostart-if-needed. All three steps are
@@ -274,7 +293,12 @@ async function ensureBootstrap(workspaceRoot, binaryPath) {
     try {
         await ensureMcpHttpServer({ owner: "cli" });
     }
-    catch { /* non-fatal */ }
+    catch (err) {
+        // Non-fatal, but never silent: this is the step that replaces an MCP
+        // server left behind by an older install, and skipping it leaves every
+        // MCP client on the old build.
+        console.error(chalk.dim(`  ⚠ MCP HTTP server not started or taken over: ${err instanceof Error ? err.message : err}`));
+    }
 }
 /**
  * Start the vexp daemon and MCP HTTP server in the background.
@@ -629,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]")
@@ -725,6 +750,21 @@ program
             selectedNames = requested.map((n) => resolveAgentName(n));
             console.log(chalk.dim(`  Agents (from flag): ${selectedNames.join(", ")}`));
         }
+        else if (!process.stdin.isTTY) {
+            // No one is at the keyboard. This command is named as a remediation
+            // in doctor's own output, and an agent — or a CI step, or a script
+            // reading that line — cannot answer a prompt: it hangs until it is
+            // killed, which is worse than failing (field report, 2026-09-07: a
+            // tester followed doctor's advice and had to abandon the command).
+            // Configure what is detected, and say that is what happened.
+            selectedNames = allAgents.filter((a) => detectedNames.has(a.agent)).map((a) => a.agent);
+            if (selectedNames.length === 0) {
+                console.error(chalk.yellow("  No AI agent detected here and stdin is not a terminal — nothing to configure."));
+                console.error(chalk.dim("  Name them explicitly: vexp setup --agents \"Claude Code,Codex\""));
+                process.exit(1);
+            }
+            console.log(chalk.dim(`  Agents (detected, non-interactive): ${selectedNames.join(", ")}`));
+        }
         else {
             // Interactive selection
             console.log(chalk.bold("\n  Select AI agents to configure:\n"));

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);
@@ -207,7 +235,7 @@ export function gitHooksVerdict(hooksPath, repoRoot, installedCount) {
  * wherever it stands. Null when nothing was skipped for size, or when the
  * file predates 3.1 and has no skip keys.
  */
-export function coverageVerdict(cov) {
+export function coverageVerdict(cov, coveragePath = ".vexp/coverage.json") {
     if (!cov || typeof cov !== "object")
         return null;
     const c = cov;
@@ -225,7 +253,12 @@ export function coverageVerdict(cov) {
         level: WARN,
         message: `${oversized} file(s) over max_file_size_kb = ${cap} are NOT indexed — their symbols and callers are invisible to impact, search and run_pipeline:\n` +
             examples.map((e) => `        - ${e}`).join("\n") +
-            (more > 0 ? `\n        … +${more} more (full list: .vexp/coverage.json)` : "") +
+            (more > 0 ? `\n        … +${more} more` : "") +
+            // The path, not the name. coverage.json lives at the WORKSPACE root;
+            // a tester on a monorepo looked for it beside the package he was
+            // working in, found nothing, and concluded the feature had not
+            // shipped (tier-4 field report, 2026-09-05).
+            `\n        full list: ${coveragePath}` +
             `\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').`,
     };
 }
@@ -334,13 +367,212 @@ export function workspaceCoverageFindings(root) {
         catch {
             continue; /* never indexed, or an index older than 2.7 */
         }
-        const v = coverageVerdict(cov);
+        const v = coverageVerdict(cov, path.join(t.dir, ".vexp", "coverage.json"));
         if (v)
             out.push({ level: v.level, message: targets.length > 1 ? `[${t.alias}] ${v.message}` : v.message });
     }
     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 = {};
@@ -365,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`);
@@ -388,15 +621,36 @@ 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.
     if (live) {
         const st = await queryDaemon(sock, "index_status");
         if (st) {
+            // A daemon that is still loading its model answers "rule", which reads
+            // as a downgrade for the ~20s it takes to settle. The daemon already
+            // says which of the two it is; doctor was printing the label and
+            // dropping the reason (tier-4 field report, 2026-09-05).
+            const loading = st.compressor !== "llm"
+                && typeof st.llm_inactive_reason === "string"
+                && /still loading|finishing its startup/i.test(st.llm_inactive_reason);
             const comp = st.compressor === "llm"
                 ? `llm (${st.llm_model ?? "?"}, ${st.llm_inference ?? "?"})`
-                : st.compressor ?? "unknown (older daemon)";
+                : loading
+                    ? "loading (the model is still starting — this is not the rule compressor settling in)"
+                    : 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) {
                 // The daemon knows WHY, and doctor was throwing it away: it printed
@@ -644,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
@@ -1004,22 +1269,72 @@ export async function runDoctor() {
             }
         }
     }
+    // A supervisor from an older install respawning the current bundle. It
+    // keeps reclaiming :7821 every 60s, and NO takeover rule on this side can
+    // stop it: the old process runs the old comparison. The only fix is to end
+    // it, so doctor has to name it — with its pid, which the record now
+    // carries. A tester spent a night on a :7821 server that came back with a
+    // new pid every two minutes, reported as v3.0.1 on a machine where 3.0.1
+    // was not installed anywhere: the LABEL came from a `vexp serve` resident
+    // since before the upgrade, holding its own version in memory
+    // (field report, 2026-09-06).
+    const staleSupervisorLine = (rec) => {
+        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 who = rec.owner === "serve" ? "'vexp serve' supervisor" : `${rec.owner ?? "process"}`;
+        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
+            // package.json and serves the current build. The tester who did this
+            // had a correct server one second later without running anything
+            // 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).
+            (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)"));
     try {
         const rec = JSON.parse(fs.readFileSync(path.join(home, ".vexp", "mcp.pid"), "utf-8"));
         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}` : ""}`);
+        if (alive && rec.version === CLI_VERSION)
+            staleSupervisorLine(rec);
         // 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`);
+            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' in the WORKSPACE ROOT (the directory holding .vexp/) and the current CLI takes it over`);
+            staleSupervisorLine(rec);
         }
         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}`);
+            line(WARN, `the HTTP MCP server on :${rec.port} predates version tracking (older than 2.4) — run 'vexp setup' in the WORKSPACE ROOT so the current CLI replaces it and HTTP clients get v${CLI_VERSION}`);
         }
     }
     catch {