vexp-cli 3.3.3 → 3.3.4

package/dist/doctor.js

@@ -3,6 +3,7 @@ import * as os from "os";
 import * as path from "path";
 import * as net from "net";
 import { execFileSync, spawnSync } from "child_process";
+import { fileURLToPath } from "url";
 import chalk from "chalk";
 import { fnvHash, socketPathFor, socketPathMargin } from "./socket-path.js";
 import { agentConsentPath, decisionFor, loadAgentConsentFile, readAgentConsent } from "./agent-consent.js";
@@ -10,7 +11,7 @@ import { parseJsonc, isWsl, windsurfWslBridgeNote, windsurfGlobalMcpPath, getAge
 import { resolveParentWorkspace, listWorkspaceRepos } from "./workspace-repos.js";
 import { CLI_VERSION } from "./version.js";
 import { formatCheckIn, registrationState } from "./license.js";
-import { parentPid } from "./mcp-supervisor.js";
+import { endProcessCommand, isOlderVersion, parentPid, processCommandLine, vexpProcessCheck } from "./mcp-supervisor.js";
 import { slowMountNotice } from "./slow-mount.js";
 import { cloudSyncNotice } from "./cloud-sync.js";
 import { vexpHome, isStateHome } from "./state-home.js";
@@ -138,15 +139,227 @@ function isAlive(pid) {
     }
 }
 /**
- * The git-hooks verdict, as data.
+ * The HTTP MCP server section (~/.vexp/mcp.pid), 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.
+ * Two stories used to be told for every record whose version was not this
+ * CLI's. "HTTP clients get the old build - run 'vexp setup' and the current
+ * CLI takes it over", and the one of the resident supervisor: a `vexp serve`
+ * from an older install respawns its build every 60 s, no takeover rule on
+ * this side can stop it, so doctor names it with its pid and says to end it
+ * first (field reports, 2026-09-06 and 2026-09-08: a :7821 server that came
+ * back with a new pid every two minutes; daemons restarted before the old
+ * supervisor was gone came back unregistered).
+ *
+ * Both are about `vexp serve`. For a server the IDE extension started
+ * (owner "plugin") neither holds: the extension has no loop on that server
+ * and leaves a newer one alone, the pid on record is the extension host, and
+ * its version is the right one for that extension. An extension user who
+ * ran doctor through npx, one release ahead, was told to `kill` the VS Code
+ * extension host and to run a `vexp setup` that would have moved Claude
+ * Code's entry into the npx cache (field report, 2026-10-08). That record
+ * now gets one INFO line. The supervisor story is kept for a `vexp serve`
+ * and for a record that does not say what wrote it, with two conditions it
+ * lacked: the pid is named as a process to end only when its command line
+ * still reads as vexp (a pid outlives its process), and the command is the
+ * platform's. A server that a `vexp` command started on its way (owner
+ * "cli") has no supervisor behind it, and a reader with the extension and
+ * no `vexp` command is given no command for any of them.
  */
+export function httpServerFindings(rec, o) {
+    const alive = o.io.alive(rec.pid);
+    const out = [
+        { level: alive ? OK : WARN, message: `pid ${rec.pid} on :${rec.port} — ${alive ? "alive" : "DEAD (stale pid file)"}${rec.version ? ` · v${rec.version}` : ""}` },
+    ];
+    if (!alive)
+        return out;
+    const version = typeof rec.version === "string" ? rec.version : undefined;
+    // Who talks to this server: of the agents vexp sets up, Codex alone, and
+    // only on the http transport.
+    const whoTalks = (served) => o.codexHttp
+        ? `Codex's vexp entry above is on the http transport, so Codex talks to this server and gets v${served}; no other agent uses it.`
+        : `no agent that vexp sets up talks to this server unless Codex's transport is set to http (vexp.codexMcpTransport; the default is direct, and no http entry for Codex was found above).`;
+    if (rec.owner === "plugin") {
+        const by = typeof rec.spawnedBy === "string" ? rec.spawnedBy : version;
+        if (version === o.cliVersion && by === o.cliVersion)
+            return out;
+        const ide = ideName(o.install.extensions, by);
+        const whose = `the vexp extension of ${ide === UNNAMED_IDE ? "an IDE" : ide}${by ? `, v${by}` : " (a version from before 2.4, which recorded none)"}`;
+        out.push({
+            level: INFO,
+            message: `this server belongs to ${whose}; ${thisCliIs(o.cliVersion, by, o.install.npxCache)}. They are separate installs, and the server is the right one for that extension.\n` +
+                `        ${whoTalks(version ?? by ?? "?")}\n` +
+                `        its version changes when the extension is updated in the IDE: there is nothing to end or to set up from here.`,
+        });
+        return out;
+    }
+    // The server is NEWER than this CLI: this CLI is the old install, and an
+    // older build stands down (ensureMcpHttpServer). Nothing to take over.
+    if (version && isOlderVersion(o.cliVersion, version) && !isOlderVersion(version, o.cliVersion)) {
+        out.push({
+            level: INFO,
+            message: `the HTTP MCP server on :${rec.port} is v${version}; ${thisCliIs(o.cliVersion, version, o.install.npxCache)}, and leaves that server alone: an older build never takes over a newer one. To compare like with like: npx vexp-cli@${version} doctor`,
+        });
+        return out;
+    }
+    const v = supervisorVerdict(rec, o.cliVersion, { parentOf: o.io.parentOf, alive: o.io.alive });
+    if (version === o.cliVersion && v.kind === "ok")
+        return out;
+    // What runs under the supervisor's pid NOW. A number on record is tested
+    // for existence by `alive`, and a reused one belongs to an unrelated
+    // program: the number is printed only for a process that still reads as
+    // vexp, or for none at all.
+    const now = v.kind === "stale" && v.pid !== undefined && v.alive ? vexpProcessCheck(o.io.commandLineOf(v.pid), rec.owner) : undefined;
+    // A `vexp serve` is resident and takes the port back; a `vexp` command
+    // that started the server on its way (owner "cli") has no loop on it.
+    const oneOff = rec.owner === "cli";
+    // The reader has the extension and no `vexp` command: the same record is
+    // information. "run 'vexp setup'" is a command they do not have, and
+    // through npx it is the one that moves their agents' entries into the npx
+    // cache; such a server is usually what an earlier npx run left behind
+    // (review of the fix, 2026-10-08).
+    if (extensionOnly(o.install)) {
+        const viaNpx = runsFromNpxCache(o.io.commandLineOf(rec.pid));
+        // Only a record that names its owner says whose the server is not.
+        const starter = rec.owner === "serve"
+            ? " and is not the extension's: a 'vexp serve' started it"
+            : oneOff
+                ? " and is not the extension's: a 'vexp' command started it"
+                : ", and what started it is not on record";
+        out.push({
+            level: INFO,
+            message: `the HTTP MCP server on :${rec.port} is ${version ? `v${version}` : "from before 2.4 (no version on record)"}${starter}${viaNpx ? ", out of an npx cache" : ""}; ` +
+                `${thisCliIs(o.cliVersion, version, o.install.npxCache)}.\n` +
+                `        ${whoTalks(version ?? "?")}\n` +
+                `        the vexp extension replaces a server older than itself when a window opens in ${ideName(o.install.extensions)}, and leaves a newer one alone: there is nothing to run from here.`,
+        });
+        if (!oneOff && now === "vexp") {
+            out.push({
+                level: WARN,
+                message: `a 'vexp serve'${v.by ? ` v${v.by}` : ""} is still running on this machine (pid ${v.pid}) and starts that server again whenever it ends, so :${rec.port} stays with its build for as long as it runs.\n` +
+                    `        it was not started by the extension: ${(o.io.commandLineOf(v.pid) ?? "").slice(0, 200)}`,
+            });
+        }
+        return out;
+    }
+    // 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 (version && version !== o.cliVersion) {
+        out.push({ level: WARN, message: `the HTTP MCP server on :${rec.port} is v${version} but this CLI is v${o.cliVersion} — 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` });
+    }
+    else if (!version) {
+        out.push({ level: WARN, message: `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${o.cliVersion}` });
+        return out;
+    }
+    if (v.kind === "ok")
+        return out;
+    const find = o.platform === "win32"
+        ? `in PowerShell: Get-CimInstance Win32_Process | Where-Object CommandLine -like '*vexp*serve*' | Select-Object ProcessId, CommandLine`
+        : `ps -ef | grep '[v]exp.*serve'`;
+    if (v.kind === "unknown") {
+        out.push({
+            level: WARN,
+            message: `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 (${find}) and end it.`,
+        });
+        return out;
+    }
+    if (oneOff) {
+        // Said, not counted: the WARN above is the whole finding. The paragraph
+        // below was printed for this record too, and a command that started the
+        // server on its way reclaims nothing (review of the fix, 2026-10-08).
+        out.push({
+            level: NOTE,
+            message: `that server was started by a 'vexp' command${v.by ? ` running v${v.by}` : " of an older install"}${now === "vexp" ? ` (pid ${v.pid}, still running)` : ""}, ` +
+                `not by a resident 'vexp serve': nothing takes :${rec.port} back on a schedule.`,
+        });
+        return out;
+    }
+    const who = rec.owner === "serve" ? "'vexp serve' supervisor" : "process";
+    const provenance = v.by
+        ? `running v${v.by}, not v${o.cliVersion}`
+        : `started before this CLI was installed — its version was not recorded, so it is a build older than v${o.cliVersion}`;
+    // A pid that was never recorded was read as the server's parent: when
+    // that is another program, the process that started the server has ended
+    // and the server was handed to it.
+    const recorded = typeof rec.spawnedByPid === "number";
+    const pidNote = v.pid === undefined
+        ? ""
+        : now === "vexp"
+            ? ` (pid ${v.pid}, still running)`
+            : now === "unreadable"
+                ? ` (whether it still runs could not be read: the process under its ${recorded ? "recorded pid" : "parent's pid"} does not show its command line)`
+                : now === "other"
+                    ? recorded
+                        ? ` (already gone: its recorded pid now belongs to another program)`
+                        : ` (no longer running: the server's parent process is another program now)`
+                    : ` (pid ${v.pid}, already gone)`;
+    // The supervisor is not running under the pid doctor has for it: whether
+    // another one is resident is not known, so its return is a condition, not
+    // a statement.
+    if (now === "other" || (v.pid !== undefined && !v.alive)) {
+        out.push({
+            level: WARN,
+            message: `that server was spawned by a ${who} ${provenance}${pidNote}` +
+                `\n        if :${rec.port} goes back to that build after it is replaced, a 'vexp serve' of the older install is running again: find it (${find}) and end it first.`,
+        });
+        return out;
+    }
+    out.push({
+        level: WARN,
+        message: `that server was spawned by a ${who} ${provenance}${pidNote}` +
+            `\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).
+            (now === "vexp"
+                ? `\n        end it FIRST — '${endProcessCommand(v.pid, o.platform)}'${o.platform === "win32" ? ` (in PowerShell also: Stop-Process -Id ${v.pid} -Force)` : ""} — 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'.`
+                : now === "unreadable"
+                    ? `\n        look for it (${find}): if a 'vexp serve' is listed, end that one FIRST, before restarting any daemon.`
+                    : ""),
+    });
+    return out;
+}
+/** The dot-folder of each IDE whose `extensions/` directory holds vexp's
+ *  extension, with the name doctor gives it. `.vscode-server` is a
+ *  Remote/WSL install; the forks use their own folder. The table gives the
+ *  NAME only: whether a path is the extension's is read from the path itself
+ *  (extensionFolderOf), so a fork that is not listed here is still told
+ *  apart from a CLI install and is called "your IDE". */
+const IDE_HOMES = [
+    [".vscode-server-insiders", "VS Code Insiders (Remote)"],
+    [".vscode-server", "VS Code (Remote/WSL)"],
+    [".vscode-insiders", "VS Code Insiders"],
+    [".vscode-oss", "VSCodium"],
+    [".vscode", "VS Code"],
+    [".cursor-server", "Cursor (Remote)"],
+    [".cursor", "Cursor"],
+    [".windsurf-server", "Windsurf (Remote)"],
+    [".windsurf", "Windsurf"],
+    [".trae", "Trae"],
+    [".antigravity", "Antigravity"],
+    [".kiro", "Kiro"],
+];
+/** What doctor calls an IDE it has no name for, or cannot pick among several. */
+const UNNAMED_IDE = "your IDE";
+/** "the VS Code window", and "the window" for an IDE doctor cannot name. */
+function ideWindow(ide) {
+    return ide === UNNAMED_IDE ? "the window" : `the ${ide} window`;
+}
 /**
  * Which IDE owns a running daemon, from its executable path.
  *
@@ -160,29 +373,22 @@ function isAlive(pid) {
  * Matching is on the IDE's own extensions directory, which is where the
  * bundled core lives (`<ide>/extensions/<publisher>.vexp-<ver>/binaries/...`).
  * Remote/WSL installs use `.vscode-server`; forks use their own dot-dir.
+ *
+ * The extension is also on Open VSX, for editors this table does not list.
+ * Their daemon was taken for a CLI's, and its owner sent to `vexp daemon-cmd
+ * restart`, which through npx puts an engine from the npx cache in the
+ * extension's place (review of the fix, 2026-10-08). The vexp folder in the
+ * path is enough to know whose daemon it is: such an editor is "your IDE".
  */
 export function daemonOwnerIde(exePath) {
     if (!exePath)
         return null;
     const p = exePath.replace(/\\/g, "/").toLowerCase();
-    const ides = [
-        [/\/\.vscode-server-insiders\/extensions\//, "VS Code Insiders (Remote)"],
-        [/\/\.vscode-server\/extensions\//, "VS Code (Remote/WSL)"],
-        [/\/\.vscode-insiders\/extensions\//, "VS Code Insiders"],
-        [/\/\.vscode-oss\/extensions\//, "VSCodium"],
-        [/\/\.vscode\/extensions\//, "VS Code"],
-        [/\/\.cursor-server\/extensions\//, "Cursor (Remote)"],
-        [/\/\.cursor\/extensions\//, "Cursor"],
-        [/\/\.windsurf-server\/extensions\//, "Windsurf (Remote)"],
-        [/\/\.windsurf\/extensions\//, "Windsurf"],
-        [/\/\.trae\/extensions\//, "Trae"],
-        [/\/\.antigravity\/extensions\//, "Antigravity"],
-    ];
-    for (const [re, label] of ides) {
-        if (re.test(p))
+    for (const [dir, label] of IDE_HOMES) {
+        if (p.includes(`/${dir}/extensions/`))
             return label;
     }
-    return null;
+    return extensionFolderOf(exePath) ? UNNAMED_IDE : null;
 }
 /** The remedy line for a daemon that is behind the installed engine. */
 export function staleDaemonRemedy(exePath) {
@@ -190,10 +396,521 @@ export function staleDaemonRemedy(exePath) {
     if (ide) {
         return (`this daemon belongs to ${ide} (${exePath}) — 'vexp daemon-cmd restart' will NOT fix it: ` +
             `the extension host respawns the same build.\n` +
-            `        reload the ${ide} window instead (Command Palette → "Developer: Reload Window").`);
+            `        reload ${ideWindow(ide)} instead (Command Palette → "Developer: Reload Window").`);
     }
     return `run 'vexp daemon-cmd restart' to upgrade it now.`;
 }
+/** `vexp.vexp-vscode-3.3.2-win32-x64` -> 3.3.2; undefined for any other name. */
+function extensionFolderVersion(name) {
+    return /^vexp\.vexp(?:-vscode)?-(\d+\.\d+\.\d+)/i.exec(name)?.[1];
+}
+/** The extension folder a path sits in: the folder itself, the extensions
+ *  directory around it, its name and the version in that name. Null for a
+ *  path outside any. */
+export function extensionFolderOf(p) {
+    if (!p)
+        return null;
+    const m = /^((.*[\\/]extensions)[\\/](vexp\.vexp(?:-vscode)?-(\d+\.\d+\.\d+)[^\\/]*))(?:[\\/]|$)/i.exec(p);
+    return m ? { dir: m[1], extensionsDir: m[2], folder: m[3], version: m[4] } : null;
+}
+/** The newest vexp extension version among the entries of one extensions directory. */
+export function newestExtensionVersion(names) {
+    let newest;
+    for (const n of names) {
+        const v = extensionFolderVersion(n);
+        if (v && (newest === undefined || isOlderVersion(newest, v)))
+            newest = v;
+    }
+    return newest;
+}
+/**
+ * The vexp extension folders under `home`: in the IDEs doctor has a name
+ * for, in the table's order, then in any other `~/.<editor>/extensions`.
+ * The second half is what makes a reader of an unlisted editor an extension
+ * user at all: with the table alone their install read as "no extension",
+ * and every remedy was a `vexp` command again (review of the fix,
+ * 2026-10-08).
+ */
+export function vexpExtensionInstalls(home, readdir = (d) => fs.readdirSync(d)) {
+    const out = [];
+    const scan = (dir, ide) => {
+        const extensionsDir = path.join(home, dir, "extensions");
+        let names;
+        try {
+            names = readdir(extensionsDir);
+        }
+        catch {
+            return; // no such IDE here
+        }
+        for (const n of names) {
+            const version = extensionFolderVersion(n);
+            if (version)
+                out.push({ ide, version, dir: path.join(extensionsDir, n) });
+        }
+    };
+    for (const [dir, ide] of IDE_HOMES)
+        scan(dir, ide);
+    let dotFolders = [];
+    try {
+        dotFolders = readdir(home).filter((n) => n.startsWith(".") && !IDE_HOMES.some(([dir]) => dir === n));
+    }
+    catch {
+        /* the home cannot be listed: the table is all there is */
+    }
+    for (const dir of dotFolders.sort())
+        scan(dir, UNNAMED_IDE);
+    return out;
+}
+/** The npx cache a script runs from: `<npm cache>/_npx/<hash>`, or null. */
+export function npxCacheOf(scriptPath) {
+    return /^(.*[\\/]_npx[\\/][^\\/]+)[\\/]node_modules[\\/]/.exec(scriptPath)?.[1] ?? null;
+}
+/** Does a process's command line name a script inside an npx cache? Only
+ *  that: an argument with a space in it is not told apart from two there,
+ *  so the cache's own path is not read out of it. */
+function runsFromNpxCache(commandLine) {
+    return /[\\/]_npx[\\/][^\\/\s]+[\\/]node_modules[\\/]/.test(commandLine ?? "");
+}
+/**
+ * The `vexp` command a person can type in a shell, or null. A PATH entry
+ * that is a package tree's own `node_modules/.bin` does not count: npx puts
+ * the .bin of the package it fetched on the PATH of the command it runs, and
+ * that `vexp` is gone from the reader's shell the moment the run ends. The
+ * test is on the folder, so any runner that works the same way is covered.
+ */
+export function vexpCommandOnPath(env = process.env, platform = process.platform, isFile = (p) => {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH");
+    const names = platform === "win32" ? ["vexp.cmd", "vexp.exe", "vexp.ps1", "vexp.bat"] : ["vexp"];
+    for (const entry of (key ? env[key] ?? "" : "").split(p.delimiter)) {
+        // Windows allows an entry in quotes ("C:\Program Files\nodejs"), and
+        // resolves commands through it all the same.
+        const dir = entry.replace(/^"(.*)"$/, "$1");
+        if (!dir || /[\\/]_npx[\\/]/.test(dir) || (p.isAbsolute(dir) && /[\\/]node_modules[\\/]\.bin[\\/]?$/.test(dir)))
+            continue;
+        for (const name of names) {
+            const file = p.join(dir, name);
+            if (isFile(file))
+                return file;
+        }
+    }
+    return null;
+}
+/** The reader has the extension and no `vexp` command: remedies are IDE
+ *  actions, never commands. */
+export function extensionOnly(i) {
+    return i.cliOnPath === null && i.extensions.length > 0;
+}
+/** The IDE to name in a line: the one that has the extension (at `version`,
+ *  when given), "your IDE" when none or several do. */
+export function ideName(extensions, version) {
+    const at = version ? extensions.filter((e) => e.version === version) : extensions;
+    const ides = [...new Set((at.length > 0 ? at : extensions).map((e) => e.ide))];
+    return ides.length === 1 ? ides[0] : UNNAMED_IDE;
+}
+/** The three facts on this machine, for this process. */
+function installContextHere() {
+    let script = "";
+    try {
+        script = fileURLToPath(import.meta.url);
+    }
+    catch {
+        /* not a file URL: not an npx cache either */
+    }
+    return {
+        cliOnPath: vexpCommandOnPath(),
+        npxCache: npxCacheOf(script),
+        extensions: vexpExtensionInstalls(os.homedir()),
+    };
+}
+/** How this CLI stands to another vexp build, in words: the newer or the
+ *  older of the two, and that it came out of an npx cache when it did. */
+function thisCliIs(cliVersion, other, npxCache) {
+    const rank = !other
+        ? ""
+        : isOlderVersion(other, cliVersion)
+            ? ", the newer of the two"
+            : isOlderVersion(cliVersion, other)
+                ? ", the older of the two"
+                : "";
+    return `this CLI is v${cliVersion}${rank}${npxCache ? ", run from an npx cache" : ""}`;
+}
+/**
+ * The first line of doctor when it runs out of an npx cache: which CLI the
+ * reader is looking at, and why its version need not be the one installed.
+ * Null for an installed CLI, whose doctor starts as it always did.
+ */
+export function npxOriginNote(cliVersion, npxCache) {
+    if (!npxCache)
+        return null;
+    return (`this is vexp-cli v${cliVersion}, run from an npx cache (${npxCache}): npx fetches the latest release unless a version is given, ` +
+        `so it can be newer than the vexp you have installed. To run a given version: npx vexp-cli@<version> doctor`);
+}
+/**
+ * How the reader sets `agents` up for this project, with the install they
+ * have. A plain `vexp setup` is not it: since 3.3.0 it leaves an agent found
+ * only on the machine alone until it is chosen, so the line that sent a
+ * reader there for missing Claude Code hooks installed none of them (review
+ * of a support ticket, 2026-10-08).
+ */
+export function setupAgentsRemedy(install, agents, root) {
+    if (extensionOnly(install)) {
+        return `with this project open in ${ideName(install.extensions)}, run "vexp: Setup Agents" from the Command Palette and tick ${agents.join(" and ")}`;
+    }
+    return `run '${setupAgentsCommand(agents, root)}'`;
+}
+/**
+ * The closing tips. For a reader with the extension and no `vexp` command
+ * they translate the commands that lines above may still name into the IDE
+ * actions that do the same, and say why not to reach for npx: `vexp setup`
+ * run out of an npx cache rewrites the agents' entries to point into it.
+ */
+export function summaryTips(install, codexUsed) {
+    const codex = codexUsed ? "; restart Codex to drop a cached config" : "";
+    if (extensionOnly(install)) {
+        const ide = ideName(install.extensions);
+        return (`Tips: this machine has the vexp extension and no 'vexp' command. Where a line above names one, use ${ide} instead: ` +
+            `Command Palette > "vexp: Setup Agents" for 'vexp setup', "vexp: Restart Daemon" for 'vexp daemon-cmd restart'${codex}. ` +
+            `Do not run those commands through npx: 'vexp setup' from an npx cache points your agents' entries into that cache.`);
+    }
+    return `Tips: 'vexp daemon-cmd restart' restarts the workspace daemon; 'vexp setup' rewrites agent configs${codex}.`;
+}
+/**
+ * What `root` is when vexp never serves it as a project, or undefined: the
+ * engine's own two refusals (utils::forbidden_workspace_reason), which is
+ * where doctor's walk ends up when it is run outside any project.
+ */
+export function notAProject(root, home = os.homedir(), env = process.env) {
+    if (env.VEXP_ALLOW_HOME_WORKSPACE === "1")
+        return undefined;
+    if (samePath(root, home))
+        return "your home directory";
+    if (isStateHome(root))
+        return "the folder VEXP_HOME names, where vexp keeps its own state";
+    const abs = path.resolve(root);
+    return path.dirname(abs) === abs ? "a filesystem root" : undefined;
+}
+/** A refusal as the engine wrote it, less the sentences that name a `vexp`
+ *  command: for a reader who has none to type. */
+function withoutVexpCommands(line) {
+    return line
+        .split(/(?<=[.!?])\s+/)
+        .filter((sentence) => !/[`']vexp /.test(sentence))
+        .join(" ");
+}
+/**
+ * What doctor says when no daemon answers for this workspace.
+ *
+ * It used to be one WARN and "run: vexp daemon-cmd start", whoever read it.
+ * With the IDE extension that is the ordinary state of a project that is not
+ * open: the extension starts a project's daemon when its window opens (if
+ * the project has an index) and stops it when the window closes. The reader
+ * has no `vexp` command, and through npx that remedy starts a daemon out of
+ * the npx cache that no window owns or stops (field report, 2026-10-08).
+ * Doctor cannot see whether a window is open, so it says what it knows and
+ * where to look. A start the engine refused is another matter: its reason
+ * stays in .vexp/start-blocked until the next attempt, and no surface of
+ * doctor read it.
+ *
+ * And a root that is no project at all (doctor typed in a terminal that
+ * opens in the home folder) has no daemon by design: "start one" is refused
+ * by the engine, and "open the project and press Start Indexing" would open
+ * the home folder (review of the fix, 2026-10-08).
+ */
+export function daemonDownFindings(o) {
+    if (o.outside) {
+        return [
+            {
+                level: INFO,
+                message: `no daemon is running here (${o.sock}), and none is meant to: doctor was run outside a project. It resolved ${o.outside.root}, ${o.outside.what}, which vexp never serves as one.\n` +
+                    `        what follows describes this machine and that folder, not a project of yours: run doctor again from the folder of the project you want checked.`,
+            },
+        ];
+    }
+    const ext = extensionOnly(o.install);
+    const ide = ideName(o.install.extensions);
+    const blocked = (o.startBlocked ?? "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    if (blocked.length > 0) {
+        // The engine's own text; for a reader with no `vexp` command, less the
+        // sentences that name one. By the sentence and not by the line: the
+        // engine's reason can be a single line, and dropping it whole left
+        // "was refused:" with nothing after it.
+        const lines = ext ? blocked.map(withoutVexpCommands).filter(Boolean) : blocked;
+        if (ext && /concurrent-workspace cap/.test(blocked[0]))
+            lines.push(`closing ${ideWindow(ide)} of one of them frees a place; then reopen this project.`);
+        if (lines.length === 0)
+            lines.push("the engine's reason is in .vexp/start-blocked.");
+        return [
+            {
+                level: WARN,
+                message: `daemon socket NOT reachable: ${o.sock}\n        the last start of this project's daemon was refused: ${lines.join("\n        ")}`,
+            },
+        ];
+    }
+    if (ext && !o.hasIndex) {
+        return [
+            {
+                level: INFO,
+                message: `no daemon is running for this project (${o.sock}), and the project has no index yet (.vexp/index.db): the vexp extension starts a daemon only for a project that has one.\n` +
+                    `        open the project in ${ide} and press "Start Indexing" in the vexp sidebar.`,
+            },
+        ];
+    }
+    if (ext) {
+        return [
+            {
+                level: INFO,
+                message: `no daemon is running for this project (${o.sock}). With the vexp extension that is the state of a project that is not open in ${ide}: ` +
+                    `the extension starts a project's daemon when its window opens and stops it when the window closes.\n` +
+                    `        if the project is open in a window right now, look at the vexp item in that window's status bar and at .vexp/vexp.log.`,
+            },
+        ];
+    }
+    return [
+        { level: WARN, message: `daemon socket NOT reachable: ${o.sock}` },
+        { level: NOTE, message: `→ run: vexp daemon-cmd start   (or 'vexp daemon-cmd restart')` },
+    ];
+}
+/**
+ * The line for a daemon whose version is not this CLI's engine's, or whose
+ * executable is gone from disk. Null when there is nothing to say.
+ *
+ * Doctor compared the two with `!==`, called its own engine "the installed
+ * binary" and the daemon "the OLD version", and told the owner of an IDE
+ * daemon to reload the window. For an extension user who ran doctor through
+ * npx the installed engine IS the extension's: reloading starts the same
+ * build again, and only an extension update changes it (field report,
+ * 2026-10-08). The reload advice is kept for the case it was written for,
+ * told apart by what is on disk: a newer extension folder beside the one the
+ * daemon runs from, or that folder gone.
+ */
+export function daemonVersionFinding(o) {
+    const differ = !!o.engine && !!o.running && o.engine !== o.running;
+    const ide = daemonOwnerIde(o.exe);
+    const own = ide ? extensionFolderOf(o.exe)?.version ?? o.running : undefined;
+    if (ide) {
+        // Whatever this CLI's version: the extension was updated under a window
+        // that is still open.
+        const onDisk = newestExtensionVersion(o.siblings ?? []);
+        if (onDisk !== undefined && own !== undefined && isOlderVersion(own, onDisk)) {
+            return {
+                level: WARN,
+                message: `daemon is v${o.running ?? own}, and the vexp extension of ${ide} is v${onDisk} on disk: this window still runs the build it started with.\n        ${staleDaemonRemedy(o.exe)}`,
+            };
+        }
+    }
+    if (!differ && o.binaryStale !== true)
+        return null;
+    if (ide) {
+        if (o.binaryStale === true) {
+            return { level: WARN, message: `daemon is running a deleted executable (upgraded on disk).\n        ${staleDaemonRemedy(o.exe)}` };
+        }
+        // Two installs at two versions, and nothing stale on either side.
+        const cli = thisCliIs(o.cliVersion, o.running, o.npxCache) + (o.engine && o.engine !== o.cliVersion ? `, with an engine at v${o.engine}` : "");
+        return {
+            level: INFO,
+            message: `daemon is v${o.running}: the engine of the vexp extension of ${ide}${own ? ` (v${own})` : ""}, which is the version that answers your agents in this project.\n` +
+                `        ${cli}. The two are separate installs, and nothing here is stale.\n` +
+                `        to compare like with like: npx vexp-cli@${own ?? o.running} doctor\n` +
+                `        the daemon changes version when the extension is updated in ${ide}.`,
+        };
+    }
+    if (!differ) {
+        return { level: WARN, message: `daemon is running a deleted executable (upgraded on disk).\n        ${staleDaemonRemedy(o.exe)}` };
+    }
+    // Ordered: a daemon NEWER than this CLI is not "the OLD version", and a
+    // restart from here would put the older engine in its place.
+    if (isOlderVersion(o.engine, o.running) && !isOlderVersion(o.running, o.engine)) {
+        return {
+            level: INFO,
+            message: `daemon is v${o.running}, newer than this CLI's engine (v${o.engine}): ${thisCliIs(o.cliVersion, o.running, o.npxCache)}. ` +
+                `Do not restart the daemon from this CLI: that would put the older engine in its place. To compare like with like: npx vexp-cli@${o.running} doctor`,
+        };
+    }
+    return {
+        level: WARN,
+        message: `daemon is v${o.running} but this CLI's engine is v${o.engine} — this workspace is still served by the OLD version.\n        ${staleDaemonRemedy(o.exe)}`,
+    };
+}
+/** A path doctor can test from where it runs: absolute in this platform's
+ *  own form, with nothing in it an agent would expand first (`${HOME}`,
+ *  `%APPDATA%`). A path in the other platform's form belongs to the other
+ *  side of a bridge (`wsl.exe ... node /home/...` in a Windows-side config). */
+function testablePath(v, platform) {
+    if (typeof v !== "string" || v.includes("${"))
+        return false;
+    return platform === "win32" ? /^(?:[A-Za-z]:[\\/]|\\\\)/.test(v) && !/%[^%\\/]+%/.test(v) : v.startsWith("/");
+}
+/** Programs that run their arguments somewhere else: the paths after them
+ *  are not this machine's to look for. */
+const RUNS_ELSEWHERE = /^(?:wsl|ssh|docker|podman)(?:\.exe)?$/i;
+/**
+ * What an MCP entry starts: the program, and the script it hands to a node.
+ * Only what doctor can test. A bare `node` or `vexp-core` is resolved through
+ * the agent's own PATH, a relative path from the agent's folder, `~` and
+ * `${HOME}` by the agent: looking for those from here failed entries that
+ * work, with exit 1 and a remedy that would have rewritten the user's own
+ * entry (review of the fix, 2026-10-08). The script is a .js argument that
+ * is not the value of an option before it: `--workspace /srv/three.js` names
+ * a project.
+ */
+export function mcpEntryTargets(command, args, platform = process.platform) {
+    const out = {};
+    if (testablePath(command, platform))
+        out.command = command;
+    if (typeof command === "string" && RUNS_ELSEWHERE.test(command.split(/[\\/]/).pop() ?? ""))
+        return out;
+    const list = Array.isArray(args) ? args : [];
+    const script = list.find((a, i) => testablePath(a, platform) && /\.[cm]?js$/i.test(a) && !(i > 0 && typeof list[i - 1] === "string" && /^-[^=]*$/.test(list[i - 1])));
+    if (script)
+        out.script = script;
+    return out;
+}
+/**
+ * The machine-wide vexp entry of an agent (~/.claude.json, Codex's
+ * config.toml), checked for what it starts. `fail` when the program or the
+ * script it names is not on disk; `note` when both are there but inside an
+ * npx cache, or inside an extension folder older than one installed beside
+ * it.
+ *
+ * Both entries hold absolute paths into `vexp.vexp-vscode-<version>`, and an
+ * IDE removes that folder some time after an update. They are rewritten only
+ * by a start in a project where that agent is set up, so a user who updates
+ * and then opens another project keeps two entries that point at nothing:
+ * the agent has no vexp tools in any project, vexp says nothing, and doctor
+ * printed [OK] for both because it never looked (field report, 2026-10-08).
+ *
+ * The reason and the repair are read, not assumed: the folder is looked for
+ * before it is called gone (a file missing from an installed extension is
+ * not repaired by rewriting the entry to the same path), and the IDE is
+ * offered only where a vexp extension is installed to do the rewriting
+ * (review of the fix, 2026-10-08).
+ */
+export function machineEntryCheck(o) {
+    const exists = o.exists ?? ((p) => fs.existsSync(p));
+    const readdir = o.readdir ?? ((d) => fs.readdirSync(d));
+    const targets = mcpEntryTargets(o.command, o.args, o.platform);
+    const missing = [targets.command, targets.script].filter((p) => !!p && !exists(p));
+    // The extension's own entry names its folder in one of the two.
+    const inExtension = [targets.command, targets.script].find((p) => extensionFolderOf(p) !== null);
+    if (missing.length > 0) {
+        const lost = extensionFolderOf(missing.find((p) => extensionFolderOf(p) !== null));
+        const ide = (inExtension ? daemonOwnerIde(inExtension) : null) ?? ideName(o.install.extensions);
+        const starts = `vexp's entry starts ${missing.join(" and ")}, which ${missing.length > 1 ? "do" : "does"} not exist`;
+        if (lost && exists(lost.dir)) {
+            // The extension is installed and a file of it is not there. Whoever
+            // rewrites the entry writes this same path again.
+            return {
+                fail: `${starts} (the folder of the vexp extension v${lost.version} is there, and this file is missing from it) - ${o.agent} cannot start vexp until the file is back.\n` +
+                    `        to repair it: reinstall the vexp extension in ${ide} (uninstall it in the Extensions view, then install it again). The entry is right as it is.`,
+            };
+        }
+        const why = lost
+            ? ` (the folder of the vexp extension v${lost.version} is gone: an IDE removes the old one after an update)`
+            : missing.some((p) => npxCacheOf(p) !== null)
+                ? " (a path inside an npx cache, which is not a lasting install)"
+                : "";
+        if (o.machineWide === false) {
+            return { fail: `${starts}${why} - ${o.agent} cannot start vexp in this project. vexp does not write this file: correct the path in it, or remove the entry.` };
+        }
+        if (o.managed === false) {
+            return {
+                fail: `${starts}${why} - ${o.agent} has no vexp tools in any project. vexp did not write this entry (it has no '# vexp-managed' line) and leaves it as it finds it: correct the path in it, or remove the entry.`,
+            };
+        }
+        const tools = `${starts}${why} - ${o.agent} has no vexp tools in any project until the entry is rewritten.\n`;
+        const inIde = `open in ${ide} a project where ${o.agent} is set up (the extension rewrites the entry when the window opens), or run "vexp: Setup Agents" from the Command Palette there with ${o.agent} ticked`;
+        const dropIt = `If you no longer use ${o.agent} with vexp, delete the entry instead.`;
+        const hasExtension = o.install.extensions.length > 0;
+        // An entry of the extension's is repaired from the IDE, whoever reads
+        // this, as long as the extension is still installed to do it.
+        if (hasExtension && (inExtension || o.install.cliOnPath === null))
+            return { fail: `${tools}        to repair it: ${inIde}. ${dropIt}` };
+        if (o.install.cliOnPath !== null)
+            return { fail: `${tools}        to repair it: run '${setupAgentsCommand([o.agent], o.root)}'. ${dropIt}` };
+        // Neither is on this machine any more: nothing here can rewrite it.
+        return {
+            fail: `${tools}        no vexp is installed on this machine to rewrite it: install the vexp extension in your IDE, or the CLI ('npm install -g vexp-cli'), and set ${o.agent} up with it; ` +
+                `or delete the entry if you no longer use ${o.agent} with vexp.`,
+        };
+    }
+    // Still there, but not in an install: what a `vexp setup` run through npx
+    // leaves behind, which is where doctor's own advice used to send the
+    // reader of this line.
+    const cache = [targets.command, targets.script].map((p) => (p ? npxCacheOf(p) : null)).find((c) => c !== null);
+    if (cache) {
+        return {
+            note: `this entry starts vexp out of an npx cache (${cache}), not out of an install: it stops working when that cache is cleaned.` +
+                (o.install.extensions.length > 0 && o.machineWide !== false && o.managed !== false
+                    ? ` To hand it back to the extension: delete the entry, then run "vexp: Setup Agents" in ${ideName(o.install.extensions)} with ${o.agent} ticked.`
+                    : ""),
+        };
+    }
+    // Still there, but in a folder an update has already superseded.
+    const folder = extensionFolderOf(inExtension);
+    if (folder) {
+        let names = [];
+        try {
+            names = readdir(folder.extensionsDir);
+        }
+        catch {
+            /* not listable: nothing to compare */
+        }
+        const newest = newestExtensionVersion(names);
+        if (newest && isOlderVersion(folder.version, newest)) {
+            return {
+                note: `this entry starts the vexp extension v${folder.version}, and v${newest} is installed beside it: if the IDE removes the older folder, the entry points at nothing and ${o.agent} loses vexp's tools. Run doctor again after the next IDE restart.`,
+            };
+        }
+    }
+    return {};
+}
+/**
+ * The line for a project with no .claude/settings.json.
+ *
+ * It is a finding only for someone who uses Claude Code here: vexp's entry
+ * in ~/.claude.json is machine-wide, so it is there for every project once
+ * one was set up, and a project the user answered "Not here" for is as they
+ * want it. For the others the remedy has to install the hooks, which a plain
+ * `vexp setup` does not (see setupAgentsRemedy).
+ */
+export function claudeNotSetUpFinding(o) {
+    if (!o.mcpConfigured)
+        return { level: OK, message: "no .claude/settings.json (Claude Code not configured here)" };
+    const remedy = setupAgentsRemedy(o.install, ["Claude Code"], o.root);
+    if (o.decision === "no" || o.decision === "never") {
+        return {
+            level: OK,
+            message: `no .claude/settings.json: Claude Code was declined for this project ('${o.decision === "never" ? "Never" : "Not here"}' on record), so vexp installs no orientation hooks here. To set it up after all: ${remedy}.`,
+        };
+    }
+    // "gets vexp's tools here" only for an entry that can start: twenty lines
+    // above, the same run may have failed it for a path that is gone.
+    const effect = o.entryStarts === false ? "" : ", so Claude Code gets vexp's tools here and no per-prompt orientation";
+    return {
+        level: WARN,
+        message: `no .claude/settings.json, but vexp MCP is configured for Claude Code — the orientation hooks were never installed in this project${effect}.\n` +
+            `        to install them: ${remedy}.` +
+            (extensionOnly(o.install) ? "" : ` A plain 'vexp setup' leaves an agent it finds only on this machine alone until you pick it.`),
+    };
+}
+/**
+ * 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, 
 /** The first line of .vexp/git-hooks.declined, when this clone said no to the hooks. */
 declined) {
@@ -616,14 +1333,49 @@ export function codexUseHere(root, consent, exists = fs.existsSync) {
 function codexUseUnknown(use) {
     return !use.used && use.decision === undefined && (use.onMachine === true || use.answersUnreadable !== undefined);
 }
-/** Inverse of the two TOML strings vexp writes: '...' literal, "..." basic. */
+/** A TOML string value: '...' literal or "..." basic, the two vexp writes,
+ *  with or without a comment after it (a hand-edited line may carry one). */
 function parseTomlString(raw) {
-    const literal = /^'([^']*)'$/.exec(raw);
+    const literal = /^'([^']*)'\s*(?:#.*)?$/.exec(raw);
     if (literal)
         return literal[1];
-    const basic = /^"((?:[^"\\]|\\.)*)"$/.exec(raw);
+    const basic = /^"((?:[^"\\]|\\.)*)"\s*(?:#.*)?$/.exec(raw);
     return basic ? basic[1].replace(/\\(["\\])/g, "$1") : undefined;
 }
+/** A one-line TOML array of strings, in either quoting. vexp writes JSON's
+ *  (`["mcp"]`); a hand-written `['mcp']` is the same array to Codex, and
+ *  JSON.parse read it as no array at all. Undefined for anything else. */
+function parseTomlStringArray(raw) {
+    try {
+        // The array as vexp writes it, with JSON's own escapes.
+        const list = JSON.parse(raw.trim());
+        if (Array.isArray(list) && list.every((v) => typeof v === "string"))
+            return list;
+    }
+    catch {
+        /* not JSON: read it as TOML below */
+    }
+    const m = /^\[(.*)\]\s*(?:#.*)?$/.exec(raw.trim());
+    if (!m)
+        return undefined;
+    const out = [];
+    const item = /\s*(?:'([^']*)'|"((?:[^"\\]|\\.)*)")\s*(?:,|$)/y;
+    let pos = 0;
+    while (pos < m[1].length) {
+        item.lastIndex = pos;
+        const hit = item.exec(m[1]);
+        if (!hit)
+            break;
+        out.push(hit[1] ?? hit[2].replace(/\\(["\\])/g, "$1"));
+        pos = item.lastIndex;
+    }
+    return m[1].slice(pos).trim() === "" ? out : undefined;
+}
+/** The `args` of a [mcp_servers.vexp] section, when it is a one-line array. */
+function codexSectionArgs(section) {
+    const args = /^\s*args\s*=\s*(\[.*)$/m.exec(section);
+    return args ? parseTomlStringArray(args[1]) : undefined;
+}
 /** The project a [mcp_servers.vexp] section names, if any. Same reading as
  *  the extension's codexStanzaPin: the env pin, --workspace, cwd, then the
  *  /ws/<hash>/ route of the http transport. */
@@ -632,17 +1384,11 @@ function codexSectionPin(section) {
     const fromEnv = env ? parseTomlString(env[1]) : undefined;
     if (fromEnv)
         return { path: fromEnv };
-    const args = /^\s*args\s*=\s*(\[.*\])\s*$/m.exec(section);
-    if (args) {
-        try {
-            const list = JSON.parse(args[1]);
-            const i = list.indexOf("--workspace");
-            if (i >= 0 && typeof list[i + 1] === "string")
-                return { path: list[i + 1] };
-        }
-        catch {
-            /* not the array vexp writes */
-        }
+    const list = codexSectionArgs(section);
+    if (list) {
+        const i = list.indexOf("--workspace");
+        if (i >= 0 && typeof list[i + 1] === "string")
+            return { path: list[i + 1] };
     }
     const cwd = /^\s*cwd\s*=\s*(.+?)\s*$/m.exec(section);
     const fromCwd = cwd ? parseTomlString(cwd[1]) : undefined;
@@ -651,6 +1397,11 @@ function codexSectionPin(section) {
     const url = /^\s*url\s*=\s*"[^"]*\/ws\/([0-9a-f]+)\/mcp"/m.exec(section);
     return url ? { hash: url[1] } : {};
 }
+/** The program and the arguments a [mcp_servers.vexp] section starts. */
+function codexSectionCommand(section) {
+    const command = /^\s*command\s*=\s*(.+?)\s*$/m.exec(section);
+    return { command: command ? parseTomlString(command[1]) : undefined, args: codexSectionArgs(section) };
+}
 /** Does a vexp-written [mcp_servers.vexp] section name `root`? */
 function codexSectionPinnedTo(section, root) {
     const pin = codexSectionPin(section);
@@ -1156,6 +1907,13 @@ export function workspaceRulesFindings(root, status) {
  * the same ledger: orientations the daemon finished after the hook client
  * (3 s) had stopped waiting were computed, counted by 3.1.x as served, and
  * never read by the agent (field ledger, 3.1.3: up to 8 of 33).
+ *
+ * The WARN says what the count is and stops there. It used to end "long
+ * prompts are slow on this index", a cause the ledger does not hold: a
+ * 14-word prompt goes late behind a held index lock, and a late row is also
+ * written for a long prompt the daemon skipped after two late ones (review
+ * of a support ticket, 2026-10-08: 10 late of 27, cause not established).
+ * The timings that separate the causes are in the report, so it points there.
  */
 export function ledgerFindings(ledger) {
     const out = [];
@@ -1172,9 +1930,11 @@ export function ledgerFindings(ledger) {
         });
     }
     if (late > 0) {
+        const served = Number(ledger.hints_served) || 0;
         out.push({
             level: WARN,
-            message: `${late} orientation(s) in the last 7 days finished after the hook client's budget (3 s by default) and never reached the agent - long prompts are slow on this index; vexp savings shows the count`,
+            message: `${late} orientation(s) in the last 7 days were recorded late, against ${served} served: not ready within the hook client's wait (3 s by default), or a long prompt skipped after two late ones in its session. A late one normally does not reach the agent.\n` +
+                `        what made them late is not recorded here: 'doctor --report' writes the timings (the slowest calls in its usage ledger, the slow statements in its daemon log section)`,
         });
     }
     return out;
@@ -1264,6 +2024,16 @@ export function sessionsFindings(sessions, o) {
     else if (o.prompts7d > 0) {
         out.push({ level: OK, message: `no agent tool calls in the last 4h — but the ledger above shows vexp is analyzing prompts (zero calls is normal on oriented tasks)` });
     }
+    else if ((o.unoriented7d ?? 0) > 0) {
+        // Since the seed gate a prompt the search found nothing solid for gets
+        // nothing and is in no ledger number: twelve such prompts in a week
+        // read here as the WARN below ("check its MCP config"), directly under
+        // the line saying the hook had reached vexp twelve times.
+        out.push({
+            level: OK,
+            message: `no agent tool calls in the last 4h — but the prompt hook is reaching vexp: ${o.unoriented7d} prompt(s) in the last 7 days were searched and not oriented (the hook line above says why); zero tool calls is normal`,
+        });
+    }
     else if (o.uptimeS > 600) {
         // Embedded caveat: a stdio MCP server (`vexp-core mcp`) spawned while
         // the daemon was unreachable serves from its own in-process index and
@@ -1300,6 +2070,15 @@ export function sessionsFindings(sessions, o) {
  * `hook_activity` (7 days) as doctor lines, apart from the savings ledger,
  * whose numbers these abstentions never change. Nothing for a daemon that
  * predates the key.
+ *
+ * Since the seed gate two more kinds of prompt get nothing: a typed prompt
+ * the search found nothing for that passed the gate (it used to get the
+ * one-line notice, or a seed on thin evidence, and "prompts analyzed" then
+ * counted it), and a prompt whose one-line notice the session had already
+ * received. Without them here a user who upgrades sees the ledger's count
+ * fall and no line that says where the prompts went. The gate's third kind
+ * is no abstention: a definition list served alone, with the seed switched
+ * off, is in "hints served", and the aside says how many of those it was.
  */
 export function hookActivityFindings(ha, ledger, nowS) {
     if (!ha || typeof ha !== "object" || Array.isArray(ha))
@@ -1310,21 +2089,45 @@ export function hookActivityFindings(ha, ledger, nowS) {
     const empty = count(h.abstained_empty_index);
     // Absent from a daemon that predates the key: zero.
     const agentText = count(h.abstained_agent_text);
-    const skipped = short + empty + agentText;
+    const unanchored = count(h.abstained_unanchored);
+    const noticeHad = count(h.abstained_hintcap);
+    // The first three were never searched: skipped. The gate's two were
+    // classified and searched, and then nothing was sent: "skipped" is not
+    // what happened to them, so a line that holds any says "not oriented".
+    const unoriented = unanchored + noticeHad;
+    const skipped = short + empty + agentText + unoriented;
     const analyzed = count(ledger.prompts_analyzed);
     const parts = [
         short > 0 ? `${short} under 8 words (follow-ups are never oriented)` : "",
         empty > 0 ? `${empty} while the index was empty` : "",
         agentText > 0 ? `${agentText} that were the agent's own text, nothing typed (a task notice, an approval)` : "",
+        unanchored > 0 ? `${unanchored} typed and searched with nothing found that passed the seed gate (no orientation spent)` : "",
+        noticeHad > 0 ? `${noticeHad} that would have repeated the one-line notice (sent once per session)` : "",
     ]
         .filter(Boolean)
         .join(", ");
     const out = [];
     if (skipped > 0 && analyzed === 0) {
-        out.push({ level: OK, message: `orientation hook reached vexp ${skipped} time(s) in the last ${days} days and every prompt was skipped: ${parts}` });
+        const what = unoriented > 0 ? "no prompt was oriented" : "every prompt was skipped";
+        out.push({ level: OK, message: `orientation hook reached vexp ${skipped} time(s) in the last ${days} days and ${what}: ${parts}` });
     }
     else if (skipped > 0) {
-        out.push({ level: NOTE, message: `the hook also skipped ${skipped} prompt(s) in the last ${days} days: ${parts}` });
+        const what = unoriented === 0
+            ? `skipped ${skipped} prompt(s)`
+            : unoriented === skipped
+                ? `left ${skipped} prompt(s) unoriented`
+                : `skipped or left unoriented ${skipped} prompt(s)`;
+        out.push({ level: NOTE, message: `the hook also ${what} in the last ${days} days: ${parts}` });
+    }
+    // Past tense: the count is of the window, not of today's config. "The
+    // seed is switched off" was printed for seven days after the key had
+    // been set for one afternoon and removed.
+    const definitionLists = count(h.evidence_alone);
+    if (definitionLists > 0) {
+        out.push({
+            level: NOTE,
+            message: `${definitionLists} of the hints served in the last ${days} days were a definition list alone, served while the seed was switched off (ambient_seed = false or VEXP_AMBIENT_SEED=0)`,
+        });
     }
     const last = typeof h.last_at === "number" && Number.isFinite(h.last_at) ? h.last_at : null;
     if (last !== null) {
@@ -1391,7 +2194,7 @@ export function pathRelation(a, b, platform) {
     return "unrelated";
 }
 const HOOK_OUTCOME_TROUBLE = {
-    "no-daemon": "no vexp daemon was serving this folder then, so that prompt got no orientation ('vexp daemon-cmd start' starts one)",
+    "no-daemon": "no vexp daemon was serving this folder then, so that prompt got no orientation",
     timeout: "the daemon did not answer within the hook client's budget (3 s by default), so that prompt got no orientation",
     error: "the daemon answered with an error, so that prompt got no orientation; .vexp/daemon.log has the details",
 };
@@ -1405,8 +2208,10 @@ const HOOK_OUTCOME_TROUBLE = {
  * `neverServed` are folders no daemon can ever serve (the home directory,
  * the vexp home): a user-level hook (ZCode's, Codex's) meets no daemon there
  * every time a session opens in them, which says nothing about this project.
+ * `startsOne` is what starts a daemon for the reader's install: the command,
+ * unless they have the extension and no `vexp` to run it with.
  */
-export function hookCallFindings(entries, wsRoot, nowS, platform, aliases = [], neverServed = []) {
+export function hookCallFindings(entries, wsRoot, nowS, platform, aliases = [], neverServed = [], startsOne = "'vexp daemon-cmd start' starts one") {
     const roots = [wsRoot, ...aliases.filter((a) => !!a)];
     const relation = (e) => {
         const rels = roots.map((r) => pathRelation(e.root, r, platform));
@@ -1416,7 +2221,8 @@ export function hookCallFindings(entries, wsRoot, nowS, platform, aliases = [],
     const out = [];
     const here = entries.filter((e) => relation(e) === "same").sort((a, b) => b.at - a.at)[0];
     if (here) {
-        const trouble = HOOK_OUTCOME_TROUBLE[here.outcome];
+        const what = HOOK_OUTCOME_TROUBLE[here.outcome];
+        const trouble = what && here.outcome === "no-daemon" ? `${what} (${startsOne})` : what;
         const reason = here.reason ? `: ${here.reason.slice(0, 200)}` : "";
         out.push({
             level: trouble ? WARN : OK,
@@ -2040,15 +2846,155 @@ export function buildDoctorReport(i) {
     parts.push("");
     return maskSecretsForReport(parts.join("\n"));
 }
+// The timestamp and level a daemon log line starts with, as the engine's
+// human format writes them (`2026-10-08T10:16:38.645986Z  WARN message`).
+const LOG_STAMP = String.raw `^\s*(\d{4}-\d{2}-\d{2}T[\d:.]+Z?)\s+`;
+const LOG_LINE = new RegExp(`${LOG_STAMP}(TRACE|DEBUG|INFO|WARN|ERROR)\\b`);
+// The records that carry a prompt: the engine logs the query of every
+// capsule at INFO, as the user typed it, newlines included (mcp/capsule.rs,
+// the same four lines from 2.7.0 to 3.3.3), and a daemon started at the
+// debug level logs it in three more (mcp/pipeline.rs, memory/search.rs).
+// Each closes with a tail of its own, but for one: "No pivot nodes found"
+// ends where the query ends, and always comes after "Generating capsule"
+// for the same query. `loose` is a tail too plain to be looked for outside
+// its record (the closing quote of 80 bytes of the task).
+const promptRecord = (level, opens) => new RegExp(`${LOG_STAMP}${level}\\s+${opens}`);
+const PROMPT_RECORDS = [
+    { start: promptRecord("INFO", "Generating capsule for query: "), end: / \[intent=[^\]]*, budget=\d+\]\s*$/ },
+    { start: promptRecord("INFO", "Pivot threshold yielded 0 hits for query '"), end: /'; promoting top \d+ code BM25 candidate\(s\)\s*$/ },
+    { start: promptRecord("INFO", "Only doc/data nodes matched code-action query '"), end: /'; returning honest empty capsule\s*$/ },
+    { start: promptRecord("INFO", "No pivot nodes found for query: ") },
+    { start: promptRecord("DEBUG", "T5 query expansion: '"), end: /' -> \[.*\]\s*$/ },
+    { start: promptRecord("DEBUG", "Memory search for '"), end: /': \d+ candidates, \d+ results\s*$/ },
+    { start: promptRecord("DEBUG", "B\\.15 preprocessor: running for task '"), end: /'\s*$/, loose: true },
+];
+const PROMPT_RECORD_ENDS = PROMPT_RECORDS.flatMap((r) => (r.end && !r.loose ? [r.end] : []));
+// A Rust panic's first line: the thread and where in the source, no text.
+// The toolchain the engine is built with prints the thread's id after its
+// name (`thread 'main' (1692879) panicked at`); older ones did not.
+const PANIC_LINE = /^thread '[^']*'(?: \(\d+\))? panicked at /;
+// SQLite quotes back the piece of a full-text query it could not read, and
+// for a capsule's search that piece is a word of the prompt.
+const SQLITE_ECHO = /(error returned from database: \(code: \d+\) (?:unknown special query: |fts5: syntax error near ))(.+)$/;
+// The engine now leaves that piece out of its log itself, and writes how
+// long it was in its place (log_text.rs: "(11 chars of the query, not
+// logged)"). A tail that reads so is the engine's note, not a word of the
+// prompt: wrapped again it came out as "(35 chars of the query, not
+// quoted)", the length of the note.
+const SQLITE_ECHO_LEFT_OUT = /^\(\d+ chars of the query, not logged\)/;
+const LOG_VALUE_MAX = 120;
+const LOG_LINE_MAX = 600;
+/** A WARN or ERROR line cut to what a reader needs: a long quoted value (the
+ *  SQL of a slow statement runs to 700 characters) is shortened where it
+ *  stands, so the fields after it, the timings, are kept. */
+function shortenLogLine(line) {
+    const cut = line
+        .replace(SQLITE_ECHO, (whole, head, echoed) => SQLITE_ECHO_LEFT_OUT.test(echoed) ? whole : `${head}(${echoed.length} chars of the query, not quoted)`)
+        .replace(/="((?:[^"\\]|\\.)*)"/g, (whole, value) => value.length > LOG_VALUE_MAX ? `="${value.slice(0, LOG_VALUE_MAX)}... (+${value.length - LOG_VALUE_MAX} chars)"` : whole);
+    return cut.length > LOG_LINE_MAX ? `${cut.slice(0, LOG_LINE_MAX)}... (+${cut.length - LOG_LINE_MAX} chars)` : cut;
+}
+/** The level of a line of the engine's JSON log format (VEXP_LOG_FORMAT=json:
+ *  one object per record, with `timestamp` and an upper-case `level`), or
+ *  undefined for any other line, a JSON line of someone else's log included. */
+function jsonLogLevel(line) {
+    if (!line.startsWith("{"))
+        return undefined;
+    try {
+        const rec = JSON.parse(line);
+        return typeof rec?.level === "string" && typeof rec.timestamp === "string" ? rec.level : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * 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.
+ *
+ * Only lines the daemon itself logged at WARN or ERROR, and the first line
+ * of a panic. The filter used to keep any line that CONTAINED one of those
+ * words, and the daemon log holds every oriented prompt in full: a prompt
+ * with a pasted error log put its lines in a report whose header says it
+ * never carries prompt text (review of a support ticket, 2026-10-08: 10 of
+ * the 11 lines quoted from a test log were lines of a prompt). A pasted log
+ * can itself be in the engine's format, so the lines of a prompt record are
+ * skipped whatever they look like.
+ *
+ * Where a prompt ends cannot always be read off the log, and wherever it
+ * cannot the line is left out: a report that misses a warning is a smaller
+ * fault than one that quotes a prompt. So the log is read from its top (a
+ * record that began above the lines quoted is still a record), a record
+ * runs to its closing tail however long it is, and three more rules cover
+ * what a first version let through (review of the fix, 2026-10-08):
+ *  - a line seen inside a prompt is never quoted afterwards, which is what
+ *    covers the record with no tail;
+ *  - a closing tail with no record open means the record was closed early
+ *    by a tail pasted inside the prompt (a piece of vexp's own log), and
+ *    everything quoted since that record began is taken back;
+ *  - a record that never closes (a line cut short, or an engine that words
+ *    it differently) stops at the next record logged after it, and when
+ *    there is none the count of lines left out is said.
  */
 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 lines = stripAnsi(text).trimEnd().split("\n").map((l) => l.replace(/\r$/, ""));
+    const from = Math.max(0, lines.length - scan);
+    const hits = [];
+    const promptLines = new Set();
+    const remember = (l) => {
+        promptLines.add(l);
+        // The same line closes one record and is plain text in the next.
+        for (const end of PROMPT_RECORD_ENDS)
+            if (end.test(l))
+                promptLines.add(l.replace(end, ""));
+    };
+    // The record being read: its closing tail, when it was logged, where.
+    let open = null;
+    // The latest record by its own timestamp, with what had been quoted when
+    // it began. Pasted records carry older times and do not move it.
+    let latest = "";
+    let mark = 0;
+    let since = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        const rec = PROMPT_RECORDS.find((r) => r.start.test(l));
+        const at = rec ? rec.start.exec(l)[1] : "";
+        if (open) {
+            if (!(rec && at > open.at)) {
+                remember(l);
+                if (open.end.test(l))
+                    open = null;
+                continue;
+            }
+            open = null; // a later record began: the one being read never closed
+        }
+        if (rec) {
+            if (at >= latest) {
+                latest = at;
+                mark = hits.length;
+                since = i + 1;
+            }
+            if (rec.end && !rec.end.test(l))
+                open = { end: rec.end, at, line: i };
+            continue;
+        }
+        if (promptLines.has(l))
+            continue;
+        if (PROMPT_RECORD_ENDS.some((end) => end.test(l))) {
+            hits.length = mark;
+            for (let j = since; j <= i; j++)
+                remember(lines[j]);
+            continue;
+        }
+        if (i < from)
+            continue;
+        const level = LOG_LINE.exec(l)?.[2] ?? jsonLogLevel(l);
+        if (level === "WARN" || level === "ERROR")
+            hits.push(shortenLogLine(l));
+        else if (PANIC_LINE.test(l))
+            hits.push(l.slice(0, LOG_LINE_MAX));
+    }
     const byMessage = new Map();
     for (const l of hits) {
         const key = l.replace(/^\S*\d{4}-\d{2}-\d{2}T[\d:.]+Z?\s*/, "");
@@ -2062,9 +3008,27 @@ export function logWarningsFrom(text, keep = 80, scan = 3000) {
         else
             byMessage.set(key, { last: l, count: 1 });
     }
-    return [...byMessage.values()]
+    const out = [...byMessage.values()]
         .map(({ last, count }) => (count > 1 ? `${last}  (x${count})` : last))
         .slice(-keep);
+    const unread = open ? lines.length - 1 - Math.max(open.line, from - 1) : 0;
+    if (unread > 0)
+        out.push(`(${unread} line(s) at the end of the log were not read: they follow a logged prompt whose end was not found)`);
+    return out;
+}
+/**
+ * The daemon log the report quotes: the one written last. `daemon.log` is
+ * the CLI-started daemon's and `vexp.log` the IDE extension's; with both in
+ * .vexp the report took `daemon.log` whatever its age, so an extension
+ * user who had once started a daemon from a terminal sent the warnings of
+ * that old run under the heading of today's (review, 2026-10-08).
+ */
+export function newestLogName(mtimes) {
+    let best = null;
+    for (const m of mtimes)
+        if (!best || m.mtimeMs > best.mtimeMs)
+            best = m;
+    return best ? best.name : null;
 }
 /** The home folders iCloud's "Desktop & Documents Folders" syncs on this
  *  Mac: the ones com~apple~CloudDocs holds a symlink to. Sync off, no link. */
@@ -2131,15 +3095,23 @@ export async function writeDoctorReport(o) {
         ledgerMarkdown = String(ledger.stdout);
     let logName = null;
     let logWarnings = [];
+    const logs = [];
     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;
+            logs.push({ name, mtimeMs: fs.statSync(path.join(o.root, ".vexp", name)).mtimeMs });
         }
         catch {
-            /* try the next name */
+            /* no such log */
+        }
+    }
+    const newest = newestLogName(logs);
+    if (newest) {
+        try {
+            logWarnings = logWarningsFrom(fs.readFileSync(path.join(o.root, ".vexp", newest), "utf-8"));
+            logName = newest;
+        }
+        catch {
+            /* unreadable: the report says no log was found */
         }
     }
     let configText = null;
@@ -2236,6 +3208,16 @@ async function doctorChecks(onWorkspace) {
             line(f.level, f.message);
     };
     console.log(chalk.bold("\nvexp doctor — MCP / daemon diagnostics\n"));
+    // Which install the reader has decides every remedy below (see
+    // InstallContext): read once.
+    const install = installContextHere();
+    {
+        const origin = npxOriginNote(CLI_VERSION, install.npxCache);
+        if (origin) {
+            line(INFO, origin);
+            console.log("");
+        }
+    }
     // 1) Workspace resolution for the current directory.
     console.log(chalk.bold("Workspace targeting"));
     const resolved = resolveWorkspace();
@@ -2264,9 +3246,29 @@ async function doctorChecks(onWorkspace) {
     }
     const sock = socketForWorkspace(ws.root);
     const live = await reachable(sock);
-    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')`));
+    // No daemon, the extension and no `vexp` command: most often a project
+    // that is simply not open in the IDE, which is no fault at all.
+    let closedInIde = false;
+    if (live)
+        line(OK, `daemon socket reachable: ${sock}`);
+    else {
+        let startBlocked;
+        try {
+            startBlocked = fs.readFileSync(path.join(ws.root, ".vexp", "start-blocked"), "utf-8");
+        }
+        catch { /* the last start was not refused */ }
+        const what = notAProject(ws.root);
+        const down = daemonDownFindings({
+            sock,
+            install,
+            hasIndex: fs.existsSync(path.join(ws.root, ".vexp", "index.db")),
+            startBlocked,
+            outside: what ? { root: ws.root, what } : undefined,
+        });
+        closedInIde = down.every((f) => f.level === INFO);
+        for (const f of down)
+            emit(f);
+    }
     // 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
@@ -2332,15 +3334,28 @@ async function doctorChecks(onWorkspace) {
                 const { execFileSync } = await import("node:child_process");
                 const out = execFileSync(getBinaryPath(), ["--version"], { timeout: 5000, encoding: "utf8" });
                 const bundled = out.trim().split(/\s+/).pop();
-                const running = st.daemon_version;
-                if (bundled && running && bundled !== running) {
-                    const exe = st.daemon_exe;
-                    line(WARN, `daemon is v${running} but the installed binary is v${bundled} — this workspace is still served by the OLD version.\n        ${staleDaemonRemedy(exe)}`);
-                }
-                else if (st.binary_stale === true) {
-                    const exe = st.daemon_exe;
-                    line(WARN, `daemon is running a deleted executable (upgraded on disk).\n        ${staleDaemonRemedy(exe)}`);
+                const exe = typeof st.daemon_exe === "string" ? st.daemon_exe : undefined;
+                // What else is installed beside the extension folder the daemon
+                // runs from: a newer one there means the window was not reloaded.
+                let siblings = [];
+                const folder = extensionFolderOf(exe);
+                if (folder) {
+                    try {
+                        siblings = fs.readdirSync(folder.extensionsDir);
+                    }
+                    catch { /* not listable from here (another user's home, a remote) */ }
                 }
+                const stale = daemonVersionFinding({
+                    running: typeof st.daemon_version === "string" ? st.daemon_version : undefined,
+                    engine: bundled,
+                    exe,
+                    binaryStale: st.binary_stale === true,
+                    cliVersion: CLI_VERSION,
+                    npxCache: install.npxCache,
+                    siblings,
+                });
+                if (stale)
+                    emit(stale);
             }
             catch { /* best-effort */ }
             // 2.3 C1 — which agent sessions actually used vexp (a session with zero
@@ -2360,10 +3375,12 @@ async function doctorChecks(onWorkspace) {
                 emit(f);
             // Agent sessions only: the hook's pseudo-session and one-shot CLI
             // calls were counted as "active" sessions (field report, 2026-09-28).
-            const hookLastAt = st.hook_activity?.last_at;
+            const hookActivity = (st.hook_activity ?? {});
+            const hookLastAt = hookActivity.last_at;
             for (const f of sessionsFindings(sessions, {
                 uptimeS: Number(st.daemon_uptime_s) || 0,
                 prompts7d: analyzed,
+                unoriented7d: count(hookActivity.abstained_unanchored) + count(hookActivity.abstained_hintcap),
                 hookLastAt: typeof hookLastAt === "number" ? hookLastAt : null,
                 nowS: Math.floor(Date.now() / 1000),
             }))
@@ -2386,7 +3403,8 @@ async function doctorChecks(onWorkspace) {
             }
             catch { /* the root as given */ }
             const neverServed = [os.homedir(), vexpHome()];
-            for (const f of hookCallFindings(parseHookCalls(text), ws.root, Math.floor(Date.now() / 1000), process.platform, aliases, neverServed))
+            const startsOne = extensionOnly(install) ? `the vexp extension starts one when the project's window opens in ${ideName(install.extensions)}` : undefined;
+            for (const f of hookCallFindings(parseHookCalls(text), ws.root, Math.floor(Date.now() / 1000), process.platform, aliases, neverServed, startsOne))
                 emit(f);
         }
     }
@@ -2438,7 +3456,11 @@ async function doctorChecks(onWorkspace) {
             }
         }
         const inReg = entries.some(([r]) => samePath(r, ws.root));
-        if (!inReg)
+        // A project with no daemon has no row: said once, above, when that is
+        // its ordinary state.
+        if (!inReg && closedInIde)
+            line(INFO, `current workspace (${ws.root}) is not registered: no daemon is running for it (see 'Workspace targeting' above)`);
+        else if (!inReg)
             line(WARN, `current workspace (${ws.root}) is NOT registered — a child here could mis-route`);
         // Multi-daemon + global pin: catches the case the section-1 check misses
         // (doctor run from the same dir VEXP_WORKSPACE points at). With several
@@ -2518,11 +3540,19 @@ async function doctorChecks(onWorkspace) {
     // Whether this project chose Codex decides every Codex remedy below: a
     // user who did not is never sent to `vexp setup`, which on 3.2.5 set Codex
     // up again from its own leftovers.
-    const codexUse = codexUseHere(ws.root);
+    // The machine-wide file is never the project's own, also when doctor is
+    // run from the home folder and the two paths are one: read as the
+    // project's, it made the home "a project set up for Codex".
+    const codexGlobalConfig = path.join(os.homedir(), ".codex", "config.toml");
+    const codexUse = codexUseHere(ws.root, undefined, (p) => fs.existsSync(p) && !samePath(p, codexGlobalConfig));
+    // The machine-wide file, then the project's own. From the home folder the
+    // two are one file: read as the project's it was printed twice, the
+    // second time as a file "vexp does not write" (review of the fix,
+    // 2026-10-08).
     const codexConfigs = [
-        { label: "~/.codex/config.toml", file: path.join(os.homedir(), ".codex", "config.toml") },
-        { label: `${ws.root}/.codex/config.toml (project)`, file: path.join(ws.root, ".codex", "config.toml") },
-    ];
+        { label: "~/.codex/config.toml", file: codexGlobalConfig, machineWide: true },
+        { label: `${ws.root}/.codex/config.toml (project)`, file: path.join(ws.root, ".codex", "config.toml"), machineWide: false },
+    ].filter((c, i, all) => i === 0 || !samePath(c.file, all[0].file));
     let codexStanzaSeen = false;
     // An entry Codex can start: the hook verdict below says "the tools work"
     // only after one (not after a url + command one, which Codex refuses), and
@@ -2532,6 +3562,9 @@ async function doctorChecks(onWorkspace) {
     // 2026-09-24).
     let codexMcpUsable = false;
     let codexMcpElsewhere;
+    // An entry on the http transport: the one client of the HTTP MCP server
+    // that vexp itself sets up (section 6 says who talks to that server).
+    let codexHttp = false;
     const codexEntryHere = (section) => {
         const pin = codexSectionPin(section);
         if ((pin.path === undefined && pin.hash === undefined) || codexSectionPinnedTo(section, ws.root))
@@ -2539,7 +3572,7 @@ async function doctorChecks(onWorkspace) {
         codexMcpElsewhere ??= pin.path ?? "another project";
         return false;
     };
-    for (const { label, file } of codexConfigs) {
+    for (const { label, file, machineWide } of codexConfigs) {
         if (!fs.existsSync(file)) {
             line(OK, `${label}: absent`);
             continue;
@@ -2564,6 +3597,7 @@ async function doctorChecks(onWorkspace) {
         else if (hasUrl) {
             if (codexEntryHere(section))
                 codexMcpUsable = true;
+            codexHttp = true;
             line(OK, `${label}: transport http (url)`);
             // The URL routes to one workspace's daemon, so this form cannot follow
             // the session's folder the way the direct one does.
@@ -2573,12 +3607,31 @@ async function doctorChecks(onWorkspace) {
         }
         else if (hasCmd) {
             const here = codexEntryHere(section);
-            if (here)
+            // The entry is only as good as the program it names: one left pointing
+            // into an extension folder an update removed starts nothing.
+            const started = codexSectionCommand(section);
+            const entry = machineEntryCheck({
+                agent: "Codex",
+                command: started.command,
+                args: started.args,
+                install,
+                root: ws.root,
+                machineWide,
+                // A section without the marker is the user's: setup and the
+                // extension both leave it as it is (isUserManagedCodexSection).
+                managed: section.includes("# vexp-managed"),
+            });
+            if (here && !entry.fail)
                 codexMcpUsable = true;
             const wsm = section.match(/VEXP_WORKSPACE\s*=\s*['"]([^'"]+)['"]/);
             const cwdm = section.match(/^\s*cwd\s*=\s*['"]([^'"]+)['"]/m);
             const pins = [wsm ? `VEXP_WORKSPACE=${wsm[1]}` : "", cwdm ? `cwd=${cwdm[1]}` : ""].filter(Boolean).join(", ");
-            line(OK, `${label}: transport stdio (command)${pins ? `, ${pins}` : ", no workspace pin: the server starts in each Codex session's folder"}`);
+            if (entry.fail)
+                line(BAD, `${label}: ${entry.fail}`);
+            else
+                line(OK, `${label}: transport stdio (command)${pins ? `, ${pins}` : ", no workspace pin: the server starts in each Codex session's folder"}`);
+            if (entry.note)
+                emit({ level: NOTE, message: entry.note });
             const pin = codexSectionPin(section).path;
             if (!here && pin !== undefined && section.includes("# vexp-managed"))
                 line(WARN, codexStdioPinNote(section, pin, ws.root));
@@ -2592,15 +3645,28 @@ async function doctorChecks(onWorkspace) {
     // 5) Claude Code entry (should be UNPINNED after the multi-session fix).
     console.log(chalk.bold("\nClaude Code (~/.claude.json)"));
     const claudePath = path.join(os.homedir(), ".claude.json");
+    // Whether the entry can start what it names: the hooks section below
+    // speaks of "vexp's tools" only when it can.
+    let claudeEntryStarts = true;
     try {
         const cfg = JSON.parse(fs.readFileSync(claudePath, "utf-8"));
         const v = cfg?.mcpServers?.vexp;
         if (!v)
             line(OK, "no user-scope vexp entry");
-        else if (v.env?.VEXP_WORKSPACE)
-            line(WARN, `vexp entry still pins VEXP_WORKSPACE=${v.env.VEXP_WORKSPACE} → run 'vexp setup' to de-pin (multi-session fix)`);
-        else
-            line(OK, "vexp entry present, no VEXP_WORKSPACE pin (per-session targeting OK)");
+        else {
+            // Present is not the same as startable (see machineEntryCheck).
+            const entry = machineEntryCheck({ agent: "Claude Code", command: v.command, args: v.args, install, root: ws.root });
+            if (entry.fail) {
+                claudeEntryStarts = false;
+                line(BAD, entry.fail);
+            }
+            if (v.env?.VEXP_WORKSPACE)
+                line(WARN, `vexp entry still pins VEXP_WORKSPACE=${v.env.VEXP_WORKSPACE} → run 'vexp setup' to de-pin (multi-session fix)`);
+            else if (!entry.fail)
+                line(OK, "vexp entry present, no VEXP_WORKSPACE pin (per-session targeting OK)");
+            if (entry.note)
+                emit({ level: NOTE, message: entry.note });
+        }
     }
     catch {
         line(OK, "no ~/.claude.json");
@@ -2840,9 +3906,7 @@ async function doctorChecks(onWorkspace) {
         })();
         if (!settings) {
             // Only a finding for someone who actually uses Claude Code here.
-            line(mcpConfigured ? WARN : OK, mcpConfigured
-                ? "no .claude/settings.json, but vexp MCP is configured for Claude Code — the orientation hooks were never installed. Run 'vexp setup' (use --dry-run first to see what it would write)."
-                : "no .claude/settings.json (Claude Code not configured here)");
+            emit(claudeNotSetUpFinding({ mcpConfigured, decision: decisionFor(readAgentConsent(), ws.root, "Claude Code"), install, root: ws.root, entryStarts: claudeEntryStarts }));
         }
         else {
             // Hooks Claude Code cannot run on this PC for want of Git Bash: one line
@@ -2858,7 +3922,7 @@ async function doctorChecks(onWorkspace) {
                         line(OK, `${w.event} (${w.label}) not installed — opt-in since 2.8; 'vexp setup --interventions' adds it.`);
                     }
                     else {
-                        line(WARN, `${w.event} (${w.label}) not installed — re-run 'vexp setup' to write it.`);
+                        line(WARN, `${w.event} (${w.label}) not installed — to write it: ${setupAgentsRemedy(install, ["Claude Code"], ws.root)}.`);
                     }
                     continue;
                 }
@@ -3194,73 +4258,18 @@ async function doctorChecks(onWorkspace) {
             }
         }
     }
-    // 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.
+    // 6) HTTP MCP supervisor. Every decision is in httpServerFindings.
     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' 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' in the WORKSPACE ROOT so the current CLI replaces it and HTTP clients get v${CLI_VERSION}`);
-        }
+        for (const f of httpServerFindings(rec, {
+            cliVersion: CLI_VERSION,
+            platform: process.platform,
+            install,
+            codexHttp,
+            io: { parentOf: parentPid, alive: isAlive, commandLineOf: processCommandLine },
+        }))
+            emit(f);
     }
     catch {
         line(OK, "not running (no mcp.pid)");
@@ -3274,7 +4283,7 @@ async function doctorChecks(onWorkspace) {
     if (warns > 0 || fails > 0) {
         // The Codex half only where Codex was chosen: to anyone else it read as
         // one more reason to set Codex up (field report, 2026-09-24).
-        console.log(chalk.dim(`  Tips: 'vexp daemon-cmd restart' restarts the workspace daemon; 'vexp setup' rewrites agent configs${codexUse.used ? "; restart Codex to drop a cached config" : ""}.`));
+        console.log(chalk.dim(`  ${summaryTips(install, codexUse.used)}`));
     }
     console.log("");
     // Scripts and CI read the exit code, not the colors: any FAIL exits 1.