vexp-cli 3.2.5 → 3.3.1

package/dist/doctor.js

@@ -2,16 +2,20 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import * as net from "net";
-import { spawnSync } from "child_process";
+import { execFileSync, spawnSync } from "child_process";
 import chalk from "chalk";
-import { socketPathFor, socketPathMargin } from "./socket-path.js";
-import { parseJsonc, isWsl, windsurfWslBridgeNote, windsurfGlobalMcpPath } from "./agent-config.js";
+import { fnvHash, socketPathFor, socketPathMargin } from "./socket-path.js";
+import { agentConsentPath, decisionFor, loadAgentConsentFile, readAgentConsent } from "./agent-consent.js";
+import { parseJsonc, isWsl, windsurfWslBridgeNote, windsurfGlobalMcpPath, getAgentList, isVexpZcodeHookEntry, setupAgentsCommand, zcodeUserConfigPath } from "./agent-config.js";
 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 { slowMountNotice } from "./slow-mount.js";
+import { cloudSyncNotice } from "./cloud-sync.js";
 import { vexpHome, isStateHome } from "./state-home.js";
 import { canonicalWorkspaceRoot } from "./socket-path.js";
+import { codexHome, codexHookTrust, codexOtherConfigLayers, codexTrustCandidates, codexTrustFindings } from "./codex-trust.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),
@@ -19,6 +23,8 @@ import { canonicalWorkspaceRoot } from "./socket-path.js";
 const OK = chalk.green("OK");
 const WARN = chalk.yellow("WARN");
 const BAD = chalk.red("FAIL");
+// Said, not counted: a check doctor cannot make here, with nothing wrong found.
+const INFO = chalk.cyan("INFO");
 /** Walk up for the nearest INITIALIZED .vexp (manifest/index), then bare .vexp,
  *  then .git — mirrors discover_workspace_root / discoverWorkspaceRoot. */
 function discoverWorkspaceRoot(start) {
@@ -188,8 +194,18 @@ export function staleDaemonRemedy(exePath) {
     }
     return `run 'vexp daemon-cmd restart' to upgrade it now.`;
 }
-export function gitHooksVerdict(hooksPath, repoRoot, installedCount) {
+export function gitHooksVerdict(hooksPath, repoRoot, installedCount, 
+/** The first line of .vexp/git-hooks.declined, when this clone said no to the hooks. */
+declined) {
     const ourHooksDir = path.join(repoRoot, ".git", "hooks");
+    if (declined !== undefined && installedCount === 0) {
+        // "Skip" in VS Code, `vexp setup --personal` or `vexp hooks remove`: the
+        // daemon installs none while .vexp/git-hooks.declined is there.
+        return {
+            level: OK,
+            message: `no vexp git hooks: declined for this clone (${declined.trim() || "git-hooks.declined"}); the index refreshes on demand, and 'vexp hooks install' installs them`,
+        };
+    }
     if (!hooksPath) {
         if (installedCount === 3) {
             return { level: OK, message: "vexp hooks present in .git/hooks and git will run them" };
@@ -258,6 +274,35 @@ export function coverageVerdict(cov, coveragePath = ".vexp/coverage.json") {
             `\n        raise max_file_size_kb in .vexp/vexp.toml (0 = no cap) to include them, or exclude them on purpose with exclude_patterns — excluded files stop being counted here at the next reindex ('vexp index').`,
     };
 }
+/**
+ * The partial-parse verdict, from `.vexp/coverage.json`, as data.
+ *
+ * A file the parser could only partly read is indexed, but the declarations
+ * in the lines it could not read are missing or misplaced. Dart classes
+ * written with a primary constructor (Dart 3.13) were lost this way, their
+ * methods indexed as top-level functions, with every status surface green
+ * (2026-09). Null when the list is empty or absent (an older index).
+ */
+export function partialParseVerdict(cov, coveragePath = ".vexp/coverage.json") {
+    if (!cov || typeof cov !== "object")
+        return null;
+    const list = cov.partially_parsed_files;
+    if (!Array.isArray(list) || list.length === 0)
+        return null;
+    const files = list;
+    const examples = files
+        .slice(0, 5)
+        .map((f) => `${f.path} (${Number(f.lines) || 0} line(s) from line ${Number(f.first_line) || 0})`);
+    const more = files.length - examples.length;
+    return {
+        level: WARN,
+        message: `${files.length} file(s) were only partly parsed - the declarations in the lines the parser could not read are missing from impact, search and run_pipeline:\n` +
+            examples.map((e) => `        - ${e}`).join("\n") +
+            (more > 0 ? `\n        ... +${more} more` : "") +
+            `\n        full list: ${coveragePath}` +
+            `\n        a newer vexp may read them: update, then run 'vexp index'.`,
+    };
+}
 /**
  * The `.vscode/mcp.json` verdict for GitHub Copilot, as data.
  *
@@ -296,106 +341,1504 @@ export function vsCodeMcpVerdict(cfg, wsRoot, exists = (p) => fs.existsSync(p))
     if (pinned && !samePath(pinned, wsRoot)) {
         return { level: WARN, message: `.vscode/mcp.json vexp server is pinned to ${pinned}, but this workspace is ${wsRoot} — re-run 'vexp setup' here` };
     }
-    return { level: OK, message: `.vscode/mcp.json vexp server: ${command} ${script ?? args.join(" ")}` };
-}
-/**
- * How doctor runs a Codex `UserPromptSubmit` hook line: the way Codex does.
- * On Windows Codex hands `cmd.exe /C` the WHOLE line wrapped in one more pair
- * of quotes, verbatim (codex-rs/hooks engine/command_runner: `raw_arg`), and
- * cmd strips that outer pair — which is why the installer may quote the
- * script path. Passing the line as a normal argument instead lets Node escape
- * the inner quotes, and cmd then looks for a program literally named
- * `\"D:\…\vexp-hint.cmd\"` (field report, 2026-09-01: a correct hooks.json
- * failed doctor's probe and passed once the user removed the quotes).
- */
-export function codexHookSpawnSpec(cmdLine, platform = process.platform, comspec = process.env.COMSPEC) {
-    if (platform === "win32") {
-        return { file: comspec || "cmd.exe", args: ["/C", `"${cmdLine}"`], windowsVerbatimArguments: true };
+    return { level: OK, message: `.vscode/mcp.json vexp server: ${command} ${script ?? args.join(" ")}` };
+}
+/**
+ * How doctor runs a Codex `UserPromptSubmit` hook line through cmd.exe: the
+ * way Codex does when it has no session shell to use. Codex then hands
+ * `cmd.exe /C` the WHOLE line wrapped in one more pair of quotes, verbatim
+ * (codex-rs/hooks engine/command_runner: `raw_arg`), and cmd strips that
+ * outer pair. Passing the line as a normal argument instead lets Node escape
+ * the inner quotes, and cmd then looks for a program literally named
+ * `\"D:\…\vexp-hint.cmd\"` (field report, 2026-09-01: a correct hooks.json
+ * failed doctor's probe and passed once the user removed the quotes).
+ *
+ * This is the fallback, not the usual path: see codexPowerShellSpawnSpec.
+ */
+export function codexHookSpawnSpec(cmdLine, platform = process.platform, comspec = process.env.COMSPEC) {
+    if (platform === "win32") {
+        return { file: comspec || "cmd.exe", args: ["/C", `"${cmdLine}"`], windowsVerbatimArguments: true };
+    }
+    return { file: "sh", args: ["-c", cmdLine], windowsVerbatimArguments: false };
+}
+/**
+ * How Codex runs a hook line on Windows by default: through the session
+ * shell, PowerShell, as `<pwsh|powershell> -NoProfile -Command <line>` with
+ * ordinary argument quoting (codex-rs core/src/shell.rs derive_exec_args;
+ * shell_detect prefers pwsh, then Windows PowerShell). doctor used to probe
+ * only through cmd.exe, and passed a hook line that PowerShell merely printed.
+ */
+export function codexPowerShellSpawnSpec(cmdLine, powershell) {
+    return { file: powershell, args: ["-NoProfile", "-Command", cmdLine], windowsVerbatimArguments: false };
+}
+/**
+ * The PowerShell Codex picks on Windows: pwsh (7+) when installed, else
+ * Windows PowerShell (shell_detect get_powershell_shell). By name first,
+ * then at the paths Codex falls back to.
+ */
+function windowsPowerShell() {
+    const onPath = (name) => {
+        try {
+            return spawnSync("where.exe", [name], { encoding: "utf-8", windowsHide: true, timeout: 5000 }).status === 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (onPath("pwsh.exe"))
+        return "pwsh.exe";
+    if (fs.existsSync("C:\\Program Files\\PowerShell\\7\\pwsh.exe"))
+        return "C:\\Program Files\\PowerShell\\7\\pwsh.exe";
+    if (onPath("powershell.exe"))
+        return "powershell.exe";
+    return "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe";
+}
+/**
+ * Did the hook print its own command instead of running it? A quoted path is
+ * a string expression to PowerShell: it echoes the path and exits 0, and
+ * Codex injects that text as the context of every prompt while the script
+ * never runs (the 3.2.5 Windows form, `"C:\...\vexp-hint.cmd"`).
+ */
+export function hookEchoedItself(stdout, cmdLine) {
+    const out = stdout.trim();
+    if (!out)
+        return false;
+    const bare = cmdLine.trim().replace(/^"(.*)"$/, "$1");
+    return out === bare || out === cmdLine.trim();
+}
+const GIT_BASH_KEY = "CLAUDE_CODE_GIT_BASH_PATH";
+/** The folder Claude Code reads managed-settings.json from, per OS. */
+function claudeManagedSettingsDir(platform = process.platform) {
+    if (platform === "win32")
+        return "C:\\Program Files\\ClaudeCode";
+    if (platform === "darwin")
+        return "/Library/Application Support/ClaudeCode";
+    return "/etc/claude-code";
+}
+/** The key in a settings file's "env" block: a string, or undefined when the
+ *  file is absent, unparseable or does not set it. */
+function settingsEnvValue(file, read) {
+    try {
+        const value = parseJsonc(read(file))?.env?.[GIT_BASH_KEY];
+        return typeof value === "string" ? value : undefined;
+    }
+    catch {
+        return undefined; // absent or unparseable: Claude Code skips it too
+    }
+}
+/**
+ * CLAUDE_CODE_GIT_BASH_PATH as Claude Code's Git Bash lookup sees it (see
+ * above): managed settings over the user settings over ~/.claude.json over
+ * the environment. Not read: the --settings file (doctor cannot know it),
+ * the registry policies and managed-settings.d drop-ins, and the project's
+ * own settings files, which Claude Code ignores for this key.
+ */
+export function claudeGitBashSetting(deps = {}) {
+    const env = deps.env ?? process.env;
+    const home = deps.home ?? os.homedir();
+    const read = deps.read ?? ((p) => fs.readFileSync(p, "utf-8"));
+    const configDir = env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
+    // Highest first: the first file that sets the key is the one that won.
+    for (const file of [
+        path.join(deps.managedDir ?? claudeManagedSettingsDir(), "managed-settings.json"),
+        path.join(configDir, "settings.json"),
+        path.join(env.CLAUDE_CONFIG_DIR || home, ".claude.json"),
+    ]) {
+        const value = settingsEnvValue(file, read);
+        // An empty string still overwrites the environment, and unsets the pin.
+        if (value !== undefined)
+            return value ? { value, from: `the "env" block of ${file}` } : undefined;
+    }
+    const value = env[GIT_BASH_KEY];
+    return value ? { value, from: `the ${GIT_BASH_KEY} environment variable` } : undefined;
+}
+/** The project's settings files that pin a Git Bash Claude Code never uses. */
+export function projectGitBashPins(root, read = (p) => fs.readFileSync(p, "utf-8")) {
+    return [path.join(root, ".claude", "settings.local.json"), path.join(root, ".claude", "settings.json")].filter((file) => !!settingsEnvValue(file, read));
+}
+/** The one INFO line for such files, never a FAIL. */
+export function projectGitBashPinNote(files, env = process.env, home = os.homedir()) {
+    const user = path.join(env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), "settings.json");
+    return (`${GIT_BASH_KEY} in ${files.join(" and ")} is not used: Claude Code finds its Git Bash before it reads that key from a project's settings, ` +
+        `so doctor ignores it too. To pin a Git Bash, set it in the "env" block of ${user}.`);
+}
+const STANDARD_GIT_BASH = ["C:\\Program Files\\Git\\bin\\bash.exe", "C:\\Program Files (x86)\\Git\\bin\\bash.exe"];
+function whereGitDefault(cwd) {
+    try {
+        const where = path.win32.join(process.env.SYSTEMROOT || "C:\\Windows", "System32", "where.exe");
+        return execFileSync(where, ["git"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 5000,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .trim()
+            .split(/\r?\n/)
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/** Claude Code's "is this hit inside the session folder" test, path first,
+ *  then through the real paths; an unresolvable hit counts as inside. */
+function insideFolder(file, dir, realpath) {
+    const d = path.win32.resolve(dir).toLowerCase();
+    const f = path.win32.resolve(file).toLowerCase();
+    if (path.win32.dirname(f) === d || f.startsWith(d + "\\"))
+        return true;
+    let rd;
+    try {
+        rd = realpath(dir).toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    let rf;
+    try {
+        rf = realpath(path.win32.dirname(path.win32.resolve(file))).toLowerCase();
+    }
+    catch {
+        return true;
+    }
+    return rf === rd || rf.startsWith(rd + "\\");
+}
+/** The Git Bash Claude Code would run hooks with on Windows (see above). */
+export function resolveClaudeGitBash(deps) {
+    const exists = deps.exists ?? fs.existsSync;
+    const realpath = deps.realpath ?? ((p) => fs.realpathSync.native(p));
+    if (deps.setting) {
+        return exists(deps.setting.value)
+            ? { path: deps.setting.value, via: deps.setting.from }
+            : { path: null, via: deps.setting.from, pinnedMissing: deps.setting.value };
+    }
+    for (const p of STANDARD_GIT_BASH) {
+        if (exists(p))
+            return { path: p, via: "the standard Git for Windows folder" };
+    }
+    // Only the FIRST usable hit counts: Claude Code does not try the next one
+    // when that git has no bin\bash.exe beside it.
+    const git = (deps.whereGit ?? (() => whereGitDefault(deps.cwd)))().find((g) => exists(g) && !insideFolder(g, deps.cwd, realpath) && /\.(com|exe|bat|cmd)$/i.test(g.replace(/[. ]+$/, "")));
+    if (git) {
+        const bash = path.win32.join(git, "..", "..", "bin", "bash.exe");
+        if (exists(bash))
+            return { path: bash, via: `next to ${git}` };
+    }
+    return { path: null, via: "not found" };
+}
+/**
+ * How Claude Code runs a shell-form hook command: Git Bash on Windows, /bin/sh
+ * elsewhere (Node's `shell: true`), cwd = the project. Null on Windows without
+ * a Git Bash: doctor cannot reproduce Claude Code's shell, so it runs nothing.
+ */
+export function claudeHookSpawnSpec(command, root, platform, gitBash, baseEnv = process.env) {
+    if (platform !== "win32") {
+        return { file: "/bin/sh", args: ["-c", command], env: { ...baseEnv, CLAUDE_PROJECT_DIR: root }, cwd: root };
+    }
+    if (!gitBash)
+        return null;
+    const env = { ...baseEnv, CLAUDE_PROJECT_DIR: root.replace(/\\/g, "/") };
+    // The `bash` inside the command must resolve to Git Bash too, not WSL's.
+    if (path.win32.isAbsolute(gitBash)) {
+        const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH";
+        const dir = path.win32.dirname(gitBash);
+        env[key] = env[key] ? `${dir};${env[key]}` : dir;
+    }
+    return { file: gitBash, args: ["-c", command], env, cwd: root };
+}
+/** An entry Claude Code runs with PowerShell, which doctor does not reproduce. */
+export function isPowerShellHook(h) {
+    const shell = h?.shell;
+    return typeof shell === "string" && shell.toLowerCase() === "powershell";
+}
+/** The doctor line for Claude Code hooks that cannot run on this PC at all. */
+export function claudeShellMissing(what, lookup) {
+    if (lookup.pinnedMissing) {
+        return (`${what}: CLAUDE_CODE_GIT_BASH_PATH is set to ${lookup.pinnedMissing} (in ${lookup.via}), which does not exist — ` +
+            `Claude Code itself refuses to start with this setting.\n` +
+            `        point it at the bash.exe of Git for Windows, or remove it.`);
+    }
+    return (`${what} cannot run on this PC: on Windows Claude Code runs hooks with Git Bash, and there is none where it looks ` +
+        `(CLAUDE_CODE_GIT_BASH_PATH, C:\\Program Files\\Git\\bin\\bash.exe, bin\\bash.exe beside the git.exe on PATH). ` +
+        `It then runs them with PowerShell, which cannot run vexp's bash hooks. A 'bash' on PATH does not count: with WSL installed it is WSL's, which cannot see this project.\n` +
+        `        install Git for Windows (https://git-scm.com/downloads/win) or set CLAUDE_CODE_GIT_BASH_PATH to your bash.exe ` +
+        `(in the environment or the "env" block of ~/.claude/settings.json; a project's settings do not count), then restart Claude Code.`);
+}
+/**
+ * What the ledger adds to a failed hook probe. Its prompts arrive only
+ * through an agent's hook — doctor's own probe is tagged manual and never
+ * counted — so a count above zero means an agent's hooks reach vexp here,
+ * whatever the probe met. Not "on this machine": the index of a project on
+ * a share may also be written from another one. Only on the orientation
+ * probes' own failures: the prompts it counts come from UserPromptSubmit
+ * hooks, and next to a failure that is real (no Git Bash for Claude Code, an
+ * exec-form guard Windows cannot spawn) "may be the probe's alone" talked the
+ * reader out of the one line he had to act on (review, 2026-09-24).
+ */
+export function hookLedgerNote(hookPrompts7d) {
+    if (!(hookPrompts7d > 0))
+        return "";
+    return (`\n        note: the savings ledger counted ${hookPrompts7d} prompt(s) in the last 7 days that reached vexp through an agent's hook ` +
+        `(doctor's own probe is never counted), so an agent's hooks do reach vexp in this project — this failure may be the probe's alone.`);
+}
+/** The answers file when it exists but does not read as answers. */
+function unreadableAnswers(file) {
+    // The same loader the CLI and the extension read the answers with: it
+    // decodes a UTF-8 BOM and UTF-16 (Windows PowerShell 5.1 writes UTF-16),
+    // so a file they read is never reported here as unreadable (integration
+    // of the 3.2.6 consent work, 2026-09-25: a UTF-16 file holding answers
+    // made doctor say 'could not be read' on every run).
+    const loaded = loadAgentConsentFile(file);
+    return loaded.state === "unreadable" || loaded.state === "corrupt" ? file : undefined;
+}
+/**
+ * Whether Codex is used in this project. Without `consent`, the answers are
+ * read from agent-consent.json, and one that is there but unreadable is
+ * reported rather than taken for "no answer" as readAgentConsent takes it.
+ */
+export function codexUseHere(root, consent, exists = fs.existsSync) {
+    let answersUnreadable;
+    if (!consent) {
+        answersUnreadable = unreadableAnswers(agentConsentPath());
+        consent = readAgentConsent();
+    }
+    const decision = decisionFor(consent, root, "Codex");
+    // The detector's own list (codexHomeArtefacts, CODEX_HOME honoured), so
+    // doctor and the extension's question agree on what "Codex is here" means.
+    const codex = getAgentList().find((d) => d.agent === "Codex");
+    const onMachine = (codex?.detectAbsPaths?.() ?? []).some((p) => exists(p));
+    const used = exists(path.join(root, ".codex", "config.toml")) || decision === "yes";
+    return { used, decision, onMachine, ...(answersUnreadable && !used ? { answersUnreadable } : {}) };
+}
+/** No answer on record, and either Codex has run on this machine or the
+ *  answers could not be read: vexp's Codex files here may be a working setup. */
+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. */
+function parseTomlString(raw) {
+    const literal = /^'([^']*)'$/.exec(raw);
+    if (literal)
+        return literal[1];
+    const basic = /^"((?:[^"\\]|\\.)*)"$/.exec(raw);
+    return basic ? basic[1].replace(/\\(["\\])/g, "$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. */
+function codexSectionPin(section) {
+    const env = /^\s*VEXP_WORKSPACE\s*=\s*(.+?)\s*$/m.exec(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 cwd = /^\s*cwd\s*=\s*(.+?)\s*$/m.exec(section);
+    const fromCwd = cwd ? parseTomlString(cwd[1]) : undefined;
+    if (fromCwd)
+        return { path: fromCwd };
+    const url = /^\s*url\s*=\s*"[^"]*\/ws\/([0-9a-f]+)\/mcp"/m.exec(section);
+    return url ? { hash: url[1] } : {};
+}
+/** Does a vexp-written [mcp_servers.vexp] section name `root`? */
+function codexSectionPinnedTo(section, root) {
+    const pin = codexSectionPin(section);
+    if (pin.path !== undefined)
+        return samePath(pin.path, root);
+    return pin.hash !== undefined && pin.hash === fnvHash(canonicalWorkspaceRoot(root).toLowerCase()).slice(0, 8);
+}
+/**
+ * The Codex remedies as commands that name the project. `vexp use .` and a
+ * bare `vexp setup` both take the folder they run in as the project, and
+ * doctor also runs from a subfolder (it resolves the root upwards): "run
+ * 'vexp use .' in this folder" from src\deep would have set Codex up for
+ * src\deep (review, 2026-09-24, on a share started from a subfolder).
+ */
+export function codexUseCommand(root) {
+    return `vexp use ${quotedRoot(root)}`;
+}
+export function codexSetupCommand(root) {
+    return `vexp setup ${quotedRoot(root)} --agents Codex`;
+}
+/**
+ * The root as one shell argument, for the commands above. A Windows root that
+ * ends in a backslash — X:\ for a share mapped straight to the project, or a
+ * \\server\share\ root — would print as "X:\", and the Windows argument
+ * parser reads \" as a literal quote: vexp received `X:"` (review of the fix,
+ * 2026-09-24). "X:\." names the same folder. Off Windows, sh expands $ and `
+ * inside double quotes and reads \ and " there as escapes: those four get a
+ * backslash in front, so a POSIX root arrives as written.
+ */
+function quotedRoot(root) {
+    if (/^(?:[A-Za-z]:\\|\\\\)/.test(root) && root.endsWith("\\"))
+        return `"${root}."`;
+    if (root.startsWith("/"))
+        return `"${root.replace(/[$`"\\]/g, "\\$&")}"`;
+    return `"${root}"`;
+}
+/**
+ * The remedy for a [mcp_servers.vexp] section with both `url` and `command`
+ * (Codex refuses it: "url is not supported for stdio"). The machine-wide
+ * section may be another project's, which did choose Codex: deleting it from
+ * here would break that one, so an entry pinned elsewhere is left to it.
+ */
+export function codexBrokenStanzaRemedy(use, section, root) {
+    if (use.used)
+        return `Re-run '${codexSetupCommand(root)}' to rewrite it cleanly.`;
+    const pin = codexSectionPin(section);
+    if ((pin.path !== undefined || pin.hash !== undefined) && !codexSectionPinnedTo(section, root)) {
+        return `It points Codex at ${pin.path ?? "another project"}, not at this one: run 'vexp doctor' in that project to see what to do there.`;
+    }
+    const remove = "delete the [mcp_servers.vexp] section and the [mcp_servers.vexp.*] sections under it from that file";
+    if (codexUseUnknown(use)) {
+        return `No choice of Codex for this project is on record: if you use Codex here, run '${codexUseCommand(root)}' to rewrite it; if not, ${remove}.`;
+    }
+    return `Codex is not set up for this project: ${remove}.`;
+}
+/**
+ * A vexp stdio entry that names another project. Codex starts it in each
+ * session's folder, and a pin overrides that: sessions here query the other
+ * project's index. 3.2.5 pinned the project set up last; the next setup
+ * rewrites that without a pin. A pin made with `vexp use --pin` is the
+ * user's, and only `vexp use` moves it.
+ */
+export function codexStdioPinNote(section, pin, root) {
+    const explicit = section.includes("pinned by 'vexp use'");
+    return (`the vexp entry for Codex is pinned to ${pin}, so Codex sessions in this project query that project's index, not this one's. ` +
+        (explicit
+            ? `The pin is from 'vexp use --pin': run 'vexp use --unpin' to let each session use its own folder, or '${codexUseCommand(root)} --pin' to pin it here.`
+            : "vexp 3.2.5 and earlier pinned the project set up last; the next 'vexp setup' or VS Code start with Codex set up rewrites it without a pin."));
+}
+/** The http entry routes every Codex session to one project's daemon. */
+export function codexHttpPinNote(pinnedHere) {
+    return (`the http transport routes every Codex session to ${pinnedHere ? "this project" : "one other project"}, whatever folder it starts in: with Codex in several projects, the others query ${pinnedHere ? "this one's" : "that one's"} index. ` +
+        "The direct transport (the default: unset VEXP_CODEX_TRANSPORT, or set vexp.codexMcpTransport to direct in VS Code, then run setup again) starts vexp in each session's folder.");
+}
+/** What vexp wrote for Codex in and for this project. */
+export function codexLeftovers(root, globalConfig = path.join(os.homedir(), ".codex", "config.toml")) {
+    const dir = path.join(root, ".codex");
+    const ours = ["hooks.json", "vexp-hint.sh", "vexp-hint.cmd"];
+    const files = [];
+    let foreignHooks = false;
+    let hooksJsonOurs = false;
+    try {
+        const obj = parseJsonc(fs.readFileSync(path.join(dir, "hooks.json"), "utf-8"));
+        const scan = (holder, skipHooksKey) => {
+            for (const [event, list] of Object.entries(holder)) {
+                if (skipHooksKey && event === "hooks")
+                    continue;
+                if (!Array.isArray(list)) {
+                    foreignHooks = true;
+                    continue;
+                }
+                for (const group of list) {
+                    for (const h of Array.isArray(group?.hooks) ? group.hooks : [group]) {
+                        if (typeof h?.command === "string" && h.command.includes("vexp-hint"))
+                            hooksJsonOurs = true;
+                        else
+                            foreignHooks = true;
+                    }
+                }
+            }
+        };
+        if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+            const o = obj;
+            scan(o, true); // the flat shape of older files
+            if (o.hooks && typeof o.hooks === "object" && !Array.isArray(o.hooks))
+                scan(o.hooks, false);
+            else if (o.hooks !== undefined)
+                foreignHooks = true;
+        }
+        else
+            foreignHooks = true;
+    }
+    catch {
+        // Absent: nothing to say. Unparseable: it may be the user's; not ours to name.
+        if (fs.existsSync(path.join(dir, "hooks.json")))
+            foreignHooks = true;
+    }
+    if (hooksJsonOurs)
+        files.push(".codex/hooks.json");
+    for (const f of ["vexp-hint.sh", "vexp-hint.cmd"]) {
+        if (fs.existsSync(path.join(dir, f)))
+            files.push(`.codex/${f}`);
+    }
+    let onlyOurs = false;
+    try {
+        onlyOurs = files.length > 0 && !foreignHooks && fs.readdirSync(dir).every((e) => ours.includes(e));
+    }
+    catch {
+        /* no folder */
+    }
+    let stanza;
+    try {
+        const toml = fs.readFileSync(globalConfig, "utf-8");
+        const m = toml.match(/\n?\[mcp_servers\.vexp\][\s\S]*?(?=\n\[(?!mcp_servers\.vexp\.)|$)/);
+        // A section without the marker is hand-written: the user's, not a leftover.
+        if (m && m[0].includes("# vexp-managed") && codexSectionPinnedTo(m[0], root)) {
+            stanza = { file: globalConfig, sections: m[0].match(/^\[mcp_servers\.vexp(?:\.[A-Za-z_]+)?\]/gm) ?? ["[mcp_servers.vexp]"] };
+        }
+    }
+    catch {
+        /* no machine-wide config */
+    }
+    return { files, onlyOurs, stanza };
+}
+/** The line for a .codex/hooks.json that starts with a byte-order mark. */
+export const CODEX_HOOKS_BOM_NOTE = ".codex/hooks.json starts with a byte-order mark (Windows PowerShell 5.1 writes one): doctor reads past it, Codex may not, and a hooks.json Codex cannot read runs none of its hooks.\n" +
+    "        save it as UTF-8 without a BOM (in VS Code: click the encoding in the status bar, then Save with Encoding, UTF-8).";
+/**
+ * The ways out through VS Code's question, for someone who does not use
+ * Codex here. 'Not here' is the answer for this project; 'Never' answers
+ * for Codex in every project on the machine, and in another project 3.2.5
+ * set up for Codex it then takes vexp's Codex files out too — doctor used to
+ * offer only 'Never', for a cleanup of this project (review, 2026-09-24).
+ * VS Code asks one question per tool (offerMachineAgents), so 'Never' here
+ * says nothing about any other tool; an earlier wording claimed it did,
+ * from the time one question named them all (review of the fix, 2026-09-24).
+ * 'Not here' leaves the machine-wide entry alone (releaseDeclinedAgents);
+ * only 'Never' removes it.
+ */
+function vsCodeDeclines(projectFiles, stanzaFile) {
+    const notHere = projectFiles
+        ? `, or answer 'Not here' when VS Code asks: vexp then removes its files in this project itself` +
+            (stanzaFile ? ` (the entry in ${stanzaFile} stays: delete it as above).` : ".")
+        : ".";
+    return (notHere +
+        `\n        'Not here' is for this project only; 'Never' says no to Codex for every project on this machine` +
+        (stanzaFile ? `, and also removes the entry in ${stanzaFile}.` : "."));
+}
+/**
+ * The Codex orientation-hook verdict, as data. `run` means: probe the hook.
+ * Never names `vexp setup` to someone who did not choose Codex here.
+ */
+export function codexHookVerdict(s) {
+    if (!s.use.used) {
+        const { files, onlyOurs, stanza } = s.leftovers;
+        if (files.length === 0 && !stanza) {
+            return { level: OK, message: "no vexp Codex hook here (Codex is not set up for this project)", run: false };
+        }
+        const what = [...files];
+        if (stanza)
+            what.push(`the vexp entry in ${stanza.file}, which points every Codex session on this machine at this project`);
+        const steps = [];
+        if (files.length > 0) {
+            const scripts = files.filter((f) => f !== ".codex/hooks.json");
+            steps.push(onlyOurs
+                ? "delete the .codex folder in this project (it holds only vexp's files)"
+                : `in this project's .codex folder delete ${[
+                    ...scripts,
+                    ...(files.includes(".codex/hooks.json") ? ["vexp's entry (the one naming vexp-hint) in hooks.json"] : []),
+                ].join(" and ")}; the rest of that folder is not vexp's`);
+        }
+        if (stanza) {
+            steps.push(`in ${stanza.file} delete the ${stanza.sections.join(" and ")} sections, each from its line in square brackets down to the next such line`);
+        }
+        if (codexUseUnknown(s.use)) {
+            // Possibly a Codex user of 3.2.5 or earlier: no answer existed then.
+            // VS Code asks only while Codex's own files are on the machine; without
+            // them it drops the project files silently and never asks.
+            const asks = s.use.onMachine === true;
+            return {
+                level: WARN,
+                message: `vexp set Codex up here, but no choice of Codex for this project is on record (vexp 3.2.5 and earlier did not ask), so doctor cannot tell whether you use Codex here: ${what.join("; ")}.` +
+                    (s.use.answersUnreadable ? `\n        vexp's saved answers in ${s.use.answersUnreadable} could not be read; run doctor again.` : "") +
+                    `\n        if you use Codex in this project: run '${codexUseCommand(s.root)}', which points Codex at this project and records that you use it here` +
+                    (asks ? ", or answer 'Set up' when VS Code asks whether to set up Codex." : ".") +
+                    `\n        if you do not: ${steps.join(", then ")}` +
+                    (asks ? vsCodeDeclines(files.length > 0, stanza?.file) : "."),
+                run: false,
+            };
+        }
+        return {
+            level: WARN,
+            message: `vexp left Codex files here although Codex is not set up for this project: ${what.join("; ")}.\n` +
+                `        to remove them: ${steps.join(", then ")}.`,
+            run: false,
+        };
+    }
+    if (s.hooksJson === "absent") {
+        return {
+            level: WARN,
+            message: 
+            // "The tools work" only with a vexp entry seen above: Codex counts as
+            // used here also through its own project config or a saved "yes",
+            // with no vexp entry anywhere (review, 2026-09-24).
+            // An entry pinned to another project does not count: Codex here would
+            // answer from that project's index (review of the fix, 2026-09-24).
+            (s.mcpEntrySeen
+                ? "no .codex/hooks.json, but Codex is set up for this project — the tools work and the per-prompt orientation was never installed."
+                : s.mcpEntryElsewhere
+                    ? `no .codex/hooks.json, but Codex is set up for this project — the per-prompt orientation was never installed, and the vexp entry for Codex above points at ${s.mcpEntryElsewhere}, not at this project.`
+                    : "no .codex/hooks.json, but Codex is set up for this project — the per-prompt orientation was never installed, and no usable vexp entry for Codex was found above either.") +
+                ` Run '${codexSetupCommand(s.root)}' (needs Codex >= 0.129).`,
+            run: false,
+        };
+    }
+    if (s.hooksJson === "no-entry") {
+        return { level: WARN, message: `hooks.json has no vexp UserPromptSubmit entry — run '${codexSetupCommand(s.root)}'.`, run: false };
+    }
+    if (!s.scriptPresent) {
+        // On Windows the entry's Windows command runs, and it names the .cmd.
+        const script = s.platform === "win32" && s.hasCommandWindows ? "vexp-hint.cmd" : "vexp-hint.sh";
+        return { level: BAD, message: `hooks.json points at .codex/${script} but the script is missing — the hook fails on every prompt.`, run: false };
+    }
+    if (s.platform === "win32" && !s.hasCommandWindows) {
+        // Probing it through a bash here would hide exactly this.
+        return {
+            level: WARN,
+            message: "the vexp entry in .codex/hooks.json has no Windows command: on Windows Codex would need a bash to run the .sh script, and without one it gets no per-prompt orientation on this PC.\n" +
+                `        to fix it, run '${codexSetupCommand(s.root)}': it adds the Windows version of the hook (.codex/vexp-hint.cmd) to the entry.`,
+            run: false,
+        };
+    }
+    if (s.platform === "win32" && s.commandWindows !== undefined && /^"?[^"]*vexp-hint\.cmd"?$/i.test(s.commandWindows.trim())) {
+        // The 3.2.5 form. Codex runs hook lines in PowerShell by default, which
+        // reads a quoted path as a string: it prints it, exits 0, and Codex
+        // hands the path to the model as the context of every prompt.
+        return {
+            level: WARN,
+            message: "the Windows command of vexp's entry in .codex/hooks.json is the bare script path: Codex runs hooks through PowerShell on Windows, which prints that path instead of running the script, so Codex gets the path as context on every prompt and no orientation.\n" +
+                `        to fix it, run '${codexSetupCommand(s.root)}': it rewrites the command as cmd /d /c call "...". Then approve the changed hook once in Codex (Settings > Hooks in the VS Code extension, /hooks in a terminal).`,
+            run: false,
+        };
+    }
+    return { level: OK, message: "", run: true };
+}
+function samePath(a, b) {
+    // The daemon registry lower-cases Windows roots and spells a mapped drive
+    // as its share; compare accordingly.
+    return canonicalWorkspaceRoot(path.resolve(a)).toLowerCase() === canonicalWorkspaceRoot(path.resolve(b)).toLowerCase();
+}
+/**
+ * A connected repo of a multi-repo workspace has no daemon of its own: the
+ * parent's daemon serves it. Doctor run inside such a repo used to treat it as
+ * a standalone workspace — "daemon NOT reachable", "NOT registered" — while
+ * `vexp search` from the same directory answered fine (field report,
+ * 2026-09-01, nine repos). The link is `.vexp/parent_workspace.json` in the
+ * member; when that file is missing, any registered workspace whose
+ * workspace.json lists this directory is the parent.
+ */
+export function resolveMemberParent(root, registryRoots) {
+    const link = resolveParentWorkspace(root);
+    if (link) {
+        const alias = listWorkspaceRepos(link.parentRoot).find((r) => samePath(r.resolvedPath, root))?.alias
+            ?? path.basename(root);
+        return { parentRoot: link.parentRoot, alias, via: ".vexp/parent_workspace.json" };
+    }
+    for (const reg of registryRoots) {
+        if (samePath(reg, root))
+            continue;
+        const hit = listWorkspaceRepos(reg).find((r) => !r.isPrimary && samePath(r.resolvedPath, root));
+        if (hit)
+            return { parentRoot: reg, alias: hit.alias, via: `${path.join(reg, ".vexp", "workspace.json")} (daemon registry)` };
+    }
+    return null;
+}
+/**
+ * Coverage verdicts for the workspace at `root` AND every repo connected to
+ * it, each tagged with its alias. Each repo's indexer writes its own
+ * `.vexp/coverage.json`; reading only the primary's hid three oversized files
+ * in a connected repo from a doctor run at the primary (same report).
+ */
+export function workspaceCoverageFindings(root) {
+    const repos = listWorkspaceRepos(root);
+    const targets = repos.map((r) => ({ alias: r.alias, dir: r.resolvedPath, primary: r.isPrimary }));
+    if (!targets.some((t) => t.primary))
+        targets.unshift({ alias: path.basename(root), dir: root, primary: true });
+    const out = [];
+    for (const t of targets) {
+        let cov;
+        try {
+            cov = JSON.parse(fs.readFileSync(path.join(t.dir, ".vexp", "coverage.json"), "utf-8"));
+        }
+        catch {
+            continue; /* never indexed, or an index older than 2.7 */
+        }
+        const covPath = path.join(t.dir, ".vexp", "coverage.json");
+        for (const v of [coverageVerdict(cov, covPath), partialParseVerdict(cov, covPath)]) {
+            if (v)
+                out.push({ level: v.level, message: targets.length > 1 ? `[${t.alias}] ${v.message}` : v.message });
+        }
+    }
+    return out;
+}
+/**
+ * The ignore-rules verdict, from the `Rules:` line of `vexp-core index
+ * --status`, as data.
+ *
+ * The index records which root ignore rules (.vexpignore, .gitignore,
+ * .ignore, .git/info/exclude, the exclude settings of vexp.toml) it last
+ * applied. A CLI query applies a change before it answers, except the files
+ * on disk the index lacks (let back in by a removed line, or created since
+ * the last index) when there are more than a query indexes: they wait for
+ * `vexp index` or the daemon, "pending". A tester who runs only the CLI had
+ * no way to see either state outside `index --status`.
+ * Null when the engine prints no such line (before 3.2.6) or did not run.
+ */
+export function rulesVerdict(statusOut, utf16 = []) {
+    if (/another vexp indexer is running/.test(statusOut)) {
+        return { level: INFO, message: "ignore rules: not checked - an indexer is running on this workspace; run 'vexp index --status' once it is done" };
+    }
+    const found = stripAnsi(statusOut).split("\n").map((l) => l.trim()).find((l) => l.startsWith("Rules:"));
+    if (!found)
+        return null;
+    const text = found.replace(/^Rules:\s*/, "");
+    // A UTF-16 root rule file applies none of its lines, whatever an engine
+    // that does not check for it (before 3.3.0) reports.
+    if (utf16.length > 0 && !/UTF-16/.test(text)) {
+        return { level: WARN, message: `ignore rules: ${utf16Notice(utf16)}` };
+    }
+    // Applied as they are on disk, with nothing left over; or recorded by no
+    // pass yet on an index the rules still describe.
+    const fine = /^applied \(/.test(text) || (/^not recorded/.test(text) && !/excluded by the current ignore rules/.test(text));
+    return { level: fine ? OK : WARN, message: `ignore rules: ${text}` };
+}
+/** The root rule files, as the engine's walk reads them (rules_stamp.rs). */
+const ROOT_RULE_FILES = [".gitignore", ".ignore", ".vexpignore", ".vexp_ignore", ".git/info/exclude"];
+/**
+ * The root rule files of `dir` written in UTF-16 (a byte-order mark or a
+ * NUL byte): what Windows PowerShell 5.1 writes for `echo x > .vexpignore`
+ * and `Out-File`. The engine reads rule files as UTF-8, so none of their
+ * lines applies.
+ */
+export function utf16RuleFiles(dir) {
+    return ROOT_RULE_FILES.filter((name) => {
+        try {
+            const b = fs.readFileSync(path.join(dir, name));
+            return (b.length >= 2 && ((b[0] === 0xff && b[1] === 0xfe) || (b[0] === 0xfe && b[1] === 0xff))) || b.includes(0);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The engine's wording for {@link utf16RuleFiles} (rules_stamp.rs `utf16_notice`). */
+export function utf16Notice(files) {
+    const [is, its, it] = files.length === 1 ? ["is", "its", "it"] : ["are", "their", "them"];
+    return `${files.join(", ")} ${is} UTF-16; vexp reads rule files as UTF-8, so ${its} lines do not apply: save ${it} as UTF-8 (in PowerShell: Set-Content -Encoding utf8, or Out-File -Encoding utf8)`;
+}
+/**
+ * The `Calls:` line of `vexp-core index --status`: files a query added
+ * before it answered, whose call edges wait for the daemon's next pass or
+ * `vexp index` ("who calls X" is empty for them until then). Null when the
+ * line is absent (nothing waits, or an engine before 3.2.6).
+ */
+export function callsVerdict(statusOut) {
+    const found = stripAnsi(statusOut).split("\n").map((l) => l.trim()).find((l) => l.startsWith("Calls:"));
+    if (!found)
+        return null;
+    return { level: WARN, message: `call edges: ${found.replace(/^Calls:\s*/, "")}` };
+}
+/**
+ * The `Parser:` line of `vexp-core index --status`: a full rebuild the next
+ * `vexp index` or daemon start runs once (this engine reads more of each
+ * file than the one that built the index, or an older vexp install, such as
+ * an editor extension not yet updated, re-read files since), or an index a
+ * newer engine built, which this one answers from and leaves alone. Null
+ * when the index is current or the line is absent.
+ */
+export function parserVerdict(statusOut) {
+    const found = stripAnsi(statusOut).split("\n").map((l) => l.trim()).find((l) => l.startsWith("Parser:"));
+    if (!found)
+        return null;
+    const text = found.replace(/^Parser:\s*/, "");
+    if (/rebuild pending/.test(text))
+        return { level: WARN, message: `index parser: ${text}` };
+    if (/newer vexp engine/.test(text))
+        return { level: INFO, message: `index parser: ${text}` };
+    return null;
+}
+/**
+ * `vexp-core index --status <dir>`, run by `bin`: its stdout, or null when
+ * it could not run or failed. The engine reports the index in `dir` itself
+ * when `dir` holds one (not the git root above it) and creates none.
+ */
+export function coreIndexStatus(bin, dir) {
+    const r = spawnSync(bin, ["index", "--status", dir], { cwd: dir, timeout: 15000, encoding: "utf-8", windowsHide: true });
+    return r.error || r.status !== 0 ? null : String(r.stdout ?? "");
+}
+/**
+ * Ignore-rules verdicts for the workspace at `root` and every repo connected
+ * to it (each has its own index), tagged with the alias when there are
+ * several. `status` runs `vexp-core index --status <dir>` and returns its
+ * stdout, or null when it could not run.
+ */
+export function workspaceRulesFindings(root, status) {
+    const repos = listWorkspaceRepos(root);
+    const targets = repos.map((r) => ({ alias: r.alias, dir: r.resolvedPath, primary: r.isPrimary }));
+    if (!targets.some((t) => t.primary))
+        targets.unshift({ alias: path.basename(root), dir: root, primary: true });
+    const out = [];
+    for (const t of targets) {
+        // Never indexed: nothing to compare, and --status would create the database.
+        if (!fs.existsSync(path.join(t.dir, ".vexp", "index.db")))
+            continue;
+        const text = status(t.dir);
+        if (text === null)
+            continue;
+        for (const v of [rulesVerdict(text, utf16RuleFiles(t.dir)), callsVerdict(text), parserVerdict(text)]) {
+            if (v)
+                out.push({ level: v.level, message: targets.length > 1 ? `[${t.alias}] ${v.message}` : v.message });
+        }
+    }
+    return out;
+}
+/**
+ * The 7-day activity ledger as doctor lines. Zero calls is not "not
+ * working": silence on oriented prompts is vexp doing its job, so the OK
+ * line exists whenever prompts were analyzed. The WARN is the other half of
+ * 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).
+ */
+export function ledgerFindings(ledger) {
+    const out = [];
+    const analyzed = Number(ledger.prompts_analyzed) || 0;
+    const late = Number(ledger.late) || 0;
+    // The parts add up to the total (silences + served + held out + late);
+    // held out and late are named only when there are some.
+    const held = Number(ledger.held_out) || 0;
+    if (analyzed > 0) {
+        out.push({
+            level: OK,
+            message: `savings ledger (7d): ${analyzed} prompt(s) analyzed: ${Number(ledger.silences) || 0} silences (task already oriented), ${Number(ledger.hints_served) || 0} hints served` +
+                `${held > 0 ? `, ${held} held out (randomized measurement)` : ""}${late > 0 ? `, ${late} late` : ""}. Details: vexp savings`,
+        });
+    }
+    if (late > 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`,
+        });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Who reached the daemon, and from where.
+//
+// Field report (2026-09-28, macOS, ZCode, a project in iCloud Drive): "vexp
+// setup done for ZCode but vexp is not used". His doctor was green except
+// the license and read "sessions (4h): 2 active, 0 pipeline calls total",
+// with no ledger line. Neither "session" was an agent: the orientation
+// hook's own pseudo-session ("internal-hook") and a one-shot CLI call were
+// counted as active sessions next to the agents'. The hook's abstentions
+// (a prompt under 8 words, an empty index) were recorded nowhere, so "the
+// hook fires and skips" read exactly like "the hook never fires". And a hook
+// run from a folder no daemon serves (ZCode had the PARENT of the nested,
+// same-name project open) left no trace at all. Each function below answers
+// one of those, from what the daemon (index_status) and the hook client
+// (~/.vexp/hook-calls.json) now record.
+// ---------------------------------------------------------------------------
+/** A finding doctor prints dim and indented under the lines before it; never counted. */
+export const NOTE = "NOTE";
+/**
+ * What an index_status `sessions` row is: an agent's MCP session, the
+ * pseudo-session of vexp's hooks, or a one-shot CLI call. Daemons from this
+ * release on say so in "kind"; older ones sent only the id cut to 8
+ * characters, where the hooks' "internal-hook" reads "internal" and a CLI
+ * call of this release's client still shows its "cli-" prefix. Only an older
+ * client's CLI call (a bare uuid) cannot be told from an agent.
+ */
+export function sessionKind(row) {
+    const k = row.kind;
+    if (k === "agent" || k === "hook" || k === "cli")
+        return k;
+    const s = typeof row.session === "string" ? row.session : "";
+    if (s === "internal")
+        return "hook";
+    // A daemon from before "kind" that outlived an upgrade (the CLI's bootstrap
+    // only probes the socket, it never replaces it) still shows the new client's
+    // "cli-" prefix in its 8 characters; a uuid never starts with it.
+    return s.startsWith("cli-") ? "cli" : "agent";
+}
+/** "5 min ago", "3 h ago", "2 days ago": age of a unix-seconds stamp. */
+export function agoText(seconds) {
+    const s = Math.max(0, Math.floor(Number(seconds) || 0));
+    if (s < 60)
+        return "less than a minute ago";
+    if (s < 3600)
+        return `${Math.floor(s / 60)} min ago`;
+    if (s < 48 * 3600)
+        return `${Math.floor(s / 3600)} h ago`;
+    return `${Math.floor(s / 86400)} days ago`;
+}
+function count(v) {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+/**
+ * The live sessions of the last 4 hours as doctor lines. Only agent
+ * sessions are "agent sessions": the hooks' row counts hook calls, not agent
+ * tool calls, and a CLI row is a person at a terminal. The no-session
+ * branches are the ones doctor always had, now decided on agent sessions
+ * alone.
+ */
+export function sessionsFindings(sessions, o) {
+    const of = (kind) => sessions.filter((s) => sessionKind(s) === kind);
+    const agents = of("agent");
+    const hooks = of("hook");
+    const clis = of("cli");
+    const sum = (rows, key) => rows.reduce((t, s) => t + count(s[key]), 0);
+    // The hooks' shared pseudo-session ("internal-hook") records each call as
+    // an "other" one: the prompt hook's prompt_hint, and also Claude Code's
+    // SessionStart context restore (index_status on compact/resume, installed
+    // by default) and its opt-in stop gate (verify_done). Not a prompt count;
+    // hook_activity is. Doctor's own probes go in as CLI calls.
+    const hookCalls = sum(hooks, "other_calls");
+    const agentHookAgo = typeof o.hookLastAt === "number" && Number.isFinite(o.hookLastAt) && o.nowS !== undefined && o.nowS - o.hookLastAt <= 4 * 3600
+        ? agoText(o.nowS - o.hookLastAt)
+        : null;
+    const out = [];
+    if (agents.length > 0) {
+        out.push({
+            level: OK,
+            message: `agent sessions (4h): ${agents.length} - ${sum(agents, "pipeline_calls")} pipeline, ${sum(agents, "skeleton_calls")} skeleton, ${sum(agents, "other_calls")} other tool call(s)`,
+        });
+    }
+    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.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
+        // never attaches to the daemon later — its calls are real but
+        // invisible to these counters. Don't tell that user "the agent is not
+        // using vexp"; tell them how to converge on the daemon.
+        out.push({
+            level: WARN,
+            message: `no agent session has called vexp through this daemon since it started — either no agent is using vexp here (check its MCP config), or the agent's vexp MCP server started BEFORE the daemon and is running embedded (in-process). If calls do succeed in the agent, restart the agent (with the daemon already up) so its MCP server attaches to the daemon.` +
+                // The field report's exact state: an agent's hook reached the
+                // daemon, so an agent was at work here, and no tool call came in.
+                (agentHookAgo
+                    ? `\n        an agent's hook brought a prompt to this daemon ${agentHookAgo}, so an agent is at work in this project: its vexp MCP tools are either not connected or never called.`
+                    : ""),
+        });
+    }
+    else {
+        out.push({ level: OK, message: `no session calls yet (daemon just started)` });
+    }
+    if (hooks.length > 0) {
+        out.push({
+            level: OK,
+            message: `vexp hooks (4h): ${hookCalls} call(s) reached this daemon - prompts, plus Claude Code's context restore after compact/resume and its stop gate`,
+        });
+    }
+    if (clis.length > 0) {
+        const calls = sum(clis, "pipeline_calls") + sum(clis, "skeleton_calls") + sum(clis, "other_calls");
+        out.push({ level: NOTE, message: `${calls} one-shot CLI call(s) in the last 4h (vexp search, skeleton, doctor's own hook probes, ... from a terminal or a script): not agent sessions` });
+    }
+    return out;
+}
+/**
+ * What the orientation hook did when it did not orient: index_status's
+ * `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.
+ */
+export function hookActivityFindings(ha, ledger, nowS) {
+    if (!ha || typeof ha !== "object" || Array.isArray(ha))
+        return [];
+    const h = ha;
+    const days = count(h.period_days) || 7;
+    const short = count(h.abstained_short);
+    const empty = count(h.abstained_empty_index);
+    const skipped = short + empty;
+    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` : "",
+    ]
+        .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}` });
+    }
+    else if (skipped > 0) {
+        out.push({ level: NOTE, message: `the hook also skipped ${skipped} prompt(s) in the last ${days} days: ${parts}` });
+    }
+    const last = typeof h.last_at === "number" && Number.isFinite(h.last_at) ? h.last_at : null;
+    if (last !== null) {
+        out.push({ level: OK, message: `last prompt through an agent hook: ${agoText(nowS - last)}` });
+    }
+    else {
+        // "Fires and skips" and "never fires" are now two different lines.
+        out.push({ level: NOTE, message: `no prompt has reached this daemon through an agent hook in the last ${days} days` });
+    }
+    return out;
+}
+/** Where the hook client leaves its breadcrumbs: <vexp home>/.vexp/hook-calls.json. */
+export function hookCallsPath(home = vexpHome()) {
+    return path.join(home, ".vexp", "hook-calls.json");
+}
+/** The breadcrumbs, newest first; anything unreadable is skipped, never thrown. */
+export function parseHookCalls(text) {
+    let obj;
+    try {
+        obj = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    }
+    catch {
+        return [];
+    }
+    const list = obj?.entries;
+    if (!Array.isArray(list))
+        return [];
+    const out = [];
+    for (const e of list) {
+        if (!e || typeof e !== "object")
+            continue;
+        const r = e;
+        const at = Number(r.at);
+        if (typeof r.root !== "string" || !r.root || !Number.isFinite(at))
+            continue;
+        out.push({
+            root: r.root,
+            at,
+            outcome: typeof r.outcome === "string" && r.outcome ? r.outcome : "unknown",
+            reason: typeof r.reason === "string" && r.reason ? r.reason : null,
+            agent: typeof r.agent === "string" && r.agent ? r.agent : null,
+        });
+    }
+    return out.sort((a, b) => b.at - a.at);
+}
+/**
+ * Where `a` stands relative to `b`: the same folder, a strict ancestor of it,
+ * a strict descendant, or neither. Case-folded where the platform's default
+ * filesystem is (Windows, macOS).
+ */
+export function pathRelation(a, b, platform) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    const fold = platform === "win32" || platform === "darwin";
+    const norm = (s) => (fold ? p.resolve(s).toLowerCase() : p.resolve(s));
+    const x = norm(a);
+    const y = norm(b);
+    const inside = (rel) => rel !== "" && rel !== ".." && !rel.startsWith(".." + p.sep) && !p.isAbsolute(rel);
+    if (p.relative(x, y) === "")
+        return "same";
+    if (inside(p.relative(x, y)))
+        return "ancestor";
+    if (inside(p.relative(y, x)))
+        return "descendant";
+    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)",
+    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",
+};
+/**
+ * The hook client's breadcrumbs as doctor lines: the last call from this
+ * workspace, and the calls from a folder above or below it that found no
+ * daemon, which is how an agent with the wrong folder open looks from here
+ * (the field report's ZCode had the parent open: it read neither the
+ * project's AGENTS.md nor its MCP config, and its hook met no daemon).
+ * `aliases` are other spellings of `wsRoot` (its real path, its share).
+ * `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.
+ */
+export function hookCallFindings(entries, wsRoot, nowS, platform, aliases = [], neverServed = []) {
+    const roots = [wsRoot, ...aliases.filter((a) => !!a)];
+    const relation = (e) => {
+        const rels = roots.map((r) => pathRelation(e.root, r, platform));
+        return rels.includes("same") ? "same" : rels.includes("ancestor") ? "ancestor" : rels.includes("descendant") ? "descendant" : "unrelated";
+    };
+    const by = (e) => (e.agent ? ` (${e.agent})` : "");
+    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 reason = here.reason ? `: ${here.reason.slice(0, 200)}` : "";
+        out.push({
+            level: trouble ? WARN : OK,
+            message: `last agent-hook call from this workspace: ${agoText(nowS - here.at)}${by(here)} - ${here.outcome}${reason}${trouble ? `\n        ${trouble}` : ""}`,
+        });
+    }
+    const week = 7 * 86400;
+    // The hook has since worked from the project itself: whatever the agent
+    // had open before, it has opened the right folder since.
+    const worksHere = here && (here.outcome === "served" || here.outcome === "no-injection") ? here : undefined;
+    const p = platform === "win32" ? path.win32 : path.posix;
+    const unservable = (root) => p.parse(p.resolve(root)).root === p.resolve(root) || neverServed.some((h) => !!h && pathRelation(root, h, platform) === "same");
+    let elsewhere = 0;
+    for (const e of entries) {
+        if (e.outcome !== "no-daemon" || nowS - e.at > week || elsewhere >= 3)
+            continue;
+        if (worksHere && e.at <= worksHere.at)
+            continue;
+        const rel = relation(e);
+        if (rel === "ancestor" && unservable(e.root))
+            continue;
+        if (rel === "ancestor") {
+            elsewhere++;
+            out.push({
+                level: WARN,
+                message: `an agent's hook ran from ${e.root}${by(e)} ${agoText(nowS - e.at)} and found no vexp daemon there: that is a parent folder of this project. ` +
+                    `The agent has the parent folder open, so it reads neither this project's AGENTS.md nor its MCP config, and its hook finds no daemon - open ${wsRoot} itself.`,
+            });
+        }
+        else if (rel === "descendant") {
+            elsewhere++;
+            out.push({
+                level: WARN,
+                message: `an agent's hook ran from ${e.root}${by(e)} ${agoText(nowS - e.at)} and found no vexp daemon there: that is a subfolder of this project. ` +
+                    `The agent has the subfolder open, not the project, so its hook gets no orientation (and an agent that reads AGENTS.md and its MCP config in the folder it opened, as ZCode does, finds neither) - open ${wsRoot} itself.`,
+            });
+        }
+    }
+    return out;
+}
+/** Read a JSON(C) config the way setup does (BOM tolerant, comments and trailing commas allowed). */
+export function readJsonFileState(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf-8");
+    }
+    catch (e) {
+        const code = e.code;
+        return code === "ENOENT" || code === "ENOTDIR" ? { file, state: "absent" } : { file, state: "unparseable" };
+    }
+    if (raw.replace(/^\uFEFF/, "").trim() === "")
+        return { file, state: "ok", data: {} };
+    try {
+        const v = parseJsonc(raw);
+        if (v && typeof v === "object" && !Array.isArray(v))
+            return { file, state: "ok", data: v };
+    }
+    catch {
+        /* reported below */
+    }
+    return { file, state: "unparseable" };
+}
+function asObject(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+/** A file's MCP server map: `mcp.servers` in ZCode's own files, `mcpServers` in .agents/mcp.json. */
+function zcodeServers(f, shape) {
+    if (f.state !== "ok")
+        return undefined;
+    return shape === "native" ? asObject(asObject(f.data.mcp)?.servers) : asObject(f.data.mcpServers);
+}
+/** vexp's UserPromptSubmit entry in ZCode's user config, and the hook in it that runs vexp. */
+export function zcodeVexpHook(cfg) {
+    const events = asObject(asObject(asObject(cfg)?.hooks)?.events);
+    const list = Array.isArray(events?.UserPromptSubmit) ? events.UserPromptSubmit : [];
+    const group = list.find((g) => isVexpZcodeHookEntry(g));
+    if (!group)
+        return null;
+    const hooks = group.hooks.filter((h) => !!asObject(h));
+    const hook = hooks.find((h) => isVexpZcodeHookEntry({ hooks: [h] })) ?? hooks[0];
+    return hook ? { group, hook } : null;
+}
+/** Hooks of the user's own in ZCode's user config: the same test installZcodeHintHook makes
+ *  before it honours hooks.enabled: false as the user's decision. */
+function zcodeForeignHooks(cfg) {
+    const events = asObject(asObject(asObject(cfg)?.hooks)?.events);
+    if (!events)
+        return false;
+    return Object.entries(events).some(([event, list]) => Array.isArray(list) && list.some((h) => event !== "UserPromptSubmit" || !isVexpZcodeHookEntry(h)));
+}
+/** Is ZCode set up for this project: its folder here, vexp in the project's
+ *  .agents/mcp.json, or the user said yes to ZCode for it. Project evidence
+ *  only: vexp's hook in ~/.zcode/cli/config.json is machine-wide, and taking
+ *  it for "ZCode here" failed doctor (exit 1) in every other project once
+ *  one project had been set up for ZCode. */
+export function zcodeInUse(i) {
+    const p = i.platform === "win32" ? path.win32 : path.posix;
+    if (i.exists(p.join(i.root, ".zcode")))
+        return true;
+    if (zcodeServers(i.workspaceCompat, "compat")?.vexp)
+        return true;
+    return i.consent === "yes";
+}
+/** The command doctor runs to probe vexp's hook, exactly as ZCode would
+ *  (a `process` hook: argv, no shell); null when there is nothing runnable. */
+export function zcodeProbeSpec(i) {
+    if (i.userNative.state !== "ok")
+        return null;
+    const found = zcodeVexpHook(i.userNative.data);
+    if (!found || found.hook.type !== "process")
+        return null;
+    const command = typeof found.hook.command === "string" ? found.hook.command : "";
+    const abs = i.platform === "win32" ? path.win32.isAbsolute(command) : path.posix.isAbsolute(command);
+    if (!command || !abs || !i.exists(command))
+        return null;
+    const args = Array.isArray(found.hook.args) ? found.hook.args.filter((a) => typeof a === "string") : [];
+    return { command, args };
+}
+/** A path as the doctor line names it: ~/... under home, relative under the project. */
+function zcodeLabel(file, i) {
+    const p = i.platform === "win32" ? path.win32 : path.posix;
+    if (pathRelation(i.root, file, i.platform) === "ancestor")
+        return p.relative(i.root, file).replace(/\\/g, "/");
+    if (pathRelation(i.home, file, i.platform) === "ancestor")
+        return `~/${p.relative(i.home, file).replace(/\\/g, "/")}`;
+    return file;
+}
+/** One vexp MCP entry of ZCode's, checked. */
+function zcodeEntryFinding(entry, label, userScope, i, setup) {
+    const e = asObject(entry);
+    if (!e)
+        return { level: BAD, message: `${label}: the vexp server entry is not an object - ZCode cannot start it; re-run '${setup}'` };
+    const command = typeof e.command === "string" ? e.command.trim() : "";
+    const args = Array.isArray(e.args) ? e.args.filter((a) => typeof a === "string") : [];
+    const env = asObject(e.env);
+    const pin = typeof env?.VEXP_WORKSPACE === "string" && env.VEXP_WORKSPACE ? env.VEXP_WORKSPACE : undefined;
+    if (!command) {
+        if (typeof e.url === "string")
+            return { level: INFO, message: `${label}: vexp server over http (${e.url}) - not checked here` };
+        return { level: BAD, message: `${label}: the vexp server entry has no command - ZCode cannot start it; re-run '${setup}'` };
+    }
+    const abs = i.platform === "win32" ? path.win32.isAbsolute(command) : path.posix.isAbsolute(command);
+    if (abs && !i.exists(command)) {
+        return { level: BAD, message: `${label}: the vexp server command does not exist: ${command} - ZCode cannot start it, so there are no vexp tools (an upgrade moved the binary?); re-run '${setup}'` };
+    }
+    // The Kiro lesson: a GUI app started from the Dock or the Start menu does
+    // not get the shell's PATH, and a server it cannot spawn fails silently.
+    // Bare names only: an absolute node needs no PATH lookup, and setup keeps
+    // an entry that resolves, so its re-run would not change it anyway.
+    const base = path.win32.basename(command).toLowerCase();
+    if (!/[\\/]/.test(command) && ["node", "node.exe", "npx", "npx.cmd", "npx.exe"].includes(base)) {
+        return {
+            level: WARN,
+            message: `${label}: the vexp server starts through '${command}' - ZCode is a GUI app, and launched from the Dock or Start menu it may not have node on its PATH (the server then never starts and no vexp tools appear); re-run '${setup}', which writes the vexp binary itself`,
+        };
+    }
+    // An absolute npx outside Windows is a `#!/usr/bin/env node` script: it
+    // still looks node up on that PATH. Setup adopts an entry that resolves,
+    // so the entry has to go before its re-run can write the binary.
+    if (i.platform !== "win32" && base === "npx") {
+        return {
+            level: WARN,
+            message: `${label}: the vexp server starts through ${command}, a script that runs node from ZCode's PATH, which a GUI app launched from the Dock may lack (then no vexp tools appear) - delete the vexp entry there, then run '${setup}', which writes the vexp binary itself`,
+        };
+    }
+    if (!/[\\/]/.test(command)) {
+        return {
+            level: WARN,
+            message: `${label}: the vexp server command is a bare '${command}', looked up on ZCode's PATH, which a GUI app launched from the Dock or Start menu usually lacks; re-run '${setup}' to write the absolute path`,
+        };
+    }
+    if (pin && !samePath(pin, i.root)) {
+        return {
+            level: WARN,
+            message: `${label}: the vexp server is pinned to ${pin} (VEXP_WORKSPACE), but this project is ${i.root} - ZCode sessions here query that project's index. ` +
+                (userScope
+                    ? `That entry is in your user config and serves every project: run '${setup}' here to give this project its own entry.`
+                    : `Re-run '${setup}' to repin it.`),
+        };
+    }
+    return { level: OK, message: `${label}: vexp server ${command}${args.length ? ` ${args.join(" ")}` : ""}${pin ? `, pinned to ${pin}` : ", no workspace pin"}` };
+}
+/** The ZCode section of doctor, as data (the log has its own function). */
+export function zcodeFindings(i) {
+    const setup = setupAgentsCommand(["ZCode"], i.root);
+    if (!zcodeInUse(i)) {
+        // vexp's hook runs in every folder ZCode opens, this one included: say
+        // what opening it in ZCode would lack, never as a fault of a project
+        // that may not use ZCode at all.
+        if (i.zcodeHomeExists && i.userNative.state === "ok" && zcodeVexpHook(i.userNative.data) !== null) {
+            return [
+                {
+                    level: INFO,
+                    message: `vexp's ZCode hook (~/.zcode/cli/config.json) runs in every folder ZCode opens, but this project has no vexp MCP entry for ZCode (.zcode/config.json, .agents/mcp.json)` +
+                        (i.consent === "no" || i.consent === "never" ? " - you said no to ZCode here" : `: if you open it in ZCode, run '${setup}'`),
+                },
+            ];
+        }
+        return [{ level: OK, message: "no .zcode here (ZCode not configured for this project)" }];
+    }
+    const p = i.platform === "win32" ? path.win32 : path.posix;
+    const fold = i.platform === "win32" || i.platform === "darwin";
+    const out = [];
+    // The field report's layout: .../Repos/<Project>/<Project>,
+    // a clone inside a folder of its own name. Opening the outer one is easy
+    // and reads as the project in ZCode's title bar.
+    const name = p.basename(i.root);
+    const parent = p.dirname(i.root);
+    if (name && parent !== i.root && (fold ? name.toLowerCase() === p.basename(parent).toLowerCase() : name === p.basename(parent))) {
+        out.push({
+            level: INFO,
+            message: `this project sits in a folder of the same name (${parent}): open ${i.root} itself in ZCode, not its parent - from the parent, ZCode reads neither this AGENTS.md nor .zcode/config.json`,
+        });
+    }
+    if (i.agentsMd !== null && /<!--\s*vexp v|^#{1,6}\s*vexp\b/im.test(i.agentsMd)) {
+        out.push({ level: OK, message: "AGENTS.md at the project root has the vexp section (ZCode reads it from the root of the folder it opened)" });
+    }
+    else {
+        out.push({
+            level: WARN,
+            message: (i.agentsMd === null ? `no AGENTS.md in ${i.root}` : `AGENTS.md in ${i.root} has no vexp section`) +
+                `: ZCode reads AGENTS.md at the root of the folder it opened, and without it the agent is never told vexp exists - run '${setup}'`,
+        });
+    }
+    // A file ZCode cannot parse contributes nothing, as if it were absent;
+    // setup never overwrites one, so only the user can fix it.
+    for (const f of [i.workspaceNative, i.workspaceCompat, i.userNative, i.userCompat]) {
+        if (f.state === "unparseable") {
+            out.push({ level: BAD, message: `${zcodeLabel(f.file, i)} does not parse as JSON: nothing in it takes effect in ZCode, and 'vexp setup' will not overwrite it - fix its syntax` });
+        }
+    }
+    // MCP, in ZCode's documented order: in each scope the .zcode file wins
+    // outright as soon as it defines any server.
+    const wsNative = zcodeServers(i.workspaceNative, "native");
+    const wsCompat = zcodeServers(i.workspaceCompat, "compat");
+    const usNative = zcodeServers(i.userNative, "native");
+    const usCompat = zcodeServers(i.userCompat, "compat");
+    const names = (s) => Object.keys(s ?? {});
+    let served = false;
+    if (wsNative?.vexp) {
+        out.push(zcodeEntryFinding(wsNative.vexp, zcodeLabel(i.workspaceNative.file, i), false, i, setup));
+        served = true;
+    }
+    else if (names(wsNative).length > 0 && wsCompat?.vexp) {
+        out.push({
+            level: BAD,
+            message: `${zcodeLabel(i.workspaceCompat.file, i)} holds the vexp server, but ${zcodeLabel(i.workspaceNative.file, i)} defines servers of its own (${names(wsNative).join(", ")}): ` +
+                `ZCode skips .agents/mcp.json whenever .zcode/config.json defines servers, so no vexp tools here. Run '${setup}': it writes the vexp entry into .zcode/config.json.`,
+        });
+    }
+    else if (wsCompat?.vexp) {
+        out.push(zcodeEntryFinding(wsCompat.vexp, zcodeLabel(i.workspaceCompat.file, i), false, i, setup));
+        served = true;
+    }
+    if (!served) {
+        if (usNative?.vexp) {
+            out.push(zcodeEntryFinding(usNative.vexp, zcodeLabel(i.userNative.file, i), true, i, setup));
+        }
+        else if (names(usNative).length > 0 && usCompat?.vexp) {
+            out.push({
+                level: BAD,
+                message: `${zcodeLabel(i.userCompat.file, i)} holds the vexp server, but ${zcodeLabel(i.userNative.file, i)} defines servers of its own (${names(usNative).join(", ")}): ` +
+                    `ZCode skips ~/.agents/mcp.json whenever ~/.zcode/cli/config.json defines servers. Run '${setup}': it writes the vexp entry into this project's .zcode/config.json.`,
+            });
+        }
+        else if (usCompat?.vexp) {
+            out.push(zcodeEntryFinding(usCompat.vexp, zcodeLabel(i.userCompat.file, i), true, i, setup));
+        }
+        else if (!(names(wsNative).length > 0 && wsCompat?.vexp)) {
+            out.push({
+                level: BAD,
+                message: `no vexp MCP server for ZCode here: none in .zcode/config.json, .agents/mcp.json, ~/.zcode/cli/config.json or ~/.agents/mcp.json, so ZCode sessions get no vexp tools. Run '${setup}'.`,
+            });
+        }
+    }
+    out.push({ level: NOTE, message: "ZCode connects MCP servers at session start: start a NEW ZCode session after 'vexp setup'." });
+    // The orientation hook: user scope only.
+    const hookFile = zcodeLabel(i.userNative.file, i);
+    if (i.userNative.state === "absent") {
+        out.push({ level: WARN, message: `${hookFile} does not exist: vexp's per-prompt orientation hook was never installed (ZCode runs hooks only from that file) - run '${setup}'` });
     }
-    return { file: "sh", args: ["-c", cmdLine], windowsVerbatimArguments: false };
-}
-function samePath(a, b) {
-    // The daemon registry lower-cases Windows roots and spells a mapped drive
-    // as its share; compare accordingly.
-    return canonicalWorkspaceRoot(path.resolve(a)).toLowerCase() === canonicalWorkspaceRoot(path.resolve(b)).toLowerCase();
+    else if (i.userNative.state === "ok") {
+        const cfg = i.userNative.data;
+        const enabled = asObject(cfg.hooks)?.enabled;
+        const found = zcodeVexpHook(cfg);
+        // WARN, as every other "orientation inert" state is (the entry missing
+        // or disabled, Codex's hooks = false): the MCP tools still work, only the
+        // per-prompt orientation is off. Said only when vexp's hook is there to
+        // be switched off; without one, the missing-hook line below covers both,
+        // since setup writes the entry and hooks.enabled together.
+        if (enabled !== true && found) {
+            out.push(enabled === false && zcodeForeignHooks(cfg)
+                ? {
+                    level: WARN,
+                    message: `hooks are switched off in ${hookFile} (hooks.enabled: false) while hooks of your own are registered there - that looks deliberate, so vexp leaves it alone; vexp's orientation hook stays inert until hooks.enabled is true`,
+                }
+                : {
+                    level: WARN,
+                    message: `hooks.enabled is not true in ${hookFile}: ZCode runs no hooks at all (they are off by default), vexp's orientation hook included - set "enabled": true under "hooks", or re-run '${setup}'`,
+                });
+        }
+        if (!found) {
+            out.push({ level: WARN, message: `no vexp UserPromptSubmit hook in ${hookFile}: ZCode gets no per-prompt orientation - re-run '${setup}'` });
+        }
+        else {
+            const { group, hook } = found;
+            if (group.enabled === false || hook.enabled === false) {
+                out.push({ level: WARN, message: `vexp's UserPromptSubmit hook in ${hookFile} is disabled ("enabled": false), so ZCode skips it - remove that key or set it to true` });
+            }
+            if (hook.type !== "process") {
+                out.push({ level: INFO, message: `vexp's hook in ${hookFile} is of type '${String(hook.type ?? "(none)")}', not 'process' - not probed here` });
+            }
+            else {
+                const command = typeof hook.command === "string" ? hook.command : "";
+                const abs = i.platform === "win32" ? path.win32.isAbsolute(command) : path.posix.isAbsolute(command);
+                if (!command) {
+                    out.push({ level: BAD, message: `vexp's hook in ${hookFile} has no command - it fails on every prompt; re-run '${setup}'` });
+                }
+                else if (abs && !i.exists(command)) {
+                    out.push({ level: BAD, message: `vexp's hook in ${hookFile} runs ${command}, which does not exist - it fails on every prompt; re-run '${setup}'` });
+                }
+                else if (!abs) {
+                    out.push({ level: WARN, message: `vexp's hook in ${hookFile} runs a bare '${command}', looked up on ZCode's PATH, which a GUI app launched from the Dock or Start menu usually lacks; re-run '${setup}' to write the absolute path` });
+                }
+                const t = hook.timeoutMs;
+                if (typeof t === "number" && t < 4000) {
+                    out.push({ level: WARN, message: `vexp's hook in ${hookFile} has timeoutMs ${t}: the orientation alone may take 3 s, so ZCode can stop the hook before it answers - set it to 5000 (what setup writes)` });
+                }
+                if (i.probe) {
+                    if (i.probe.error) {
+                        out.push({ level: BAD, message: `UserPromptSubmit hook DID NOT RUN: ${i.probe.error} - orientation is inert.` });
+                    }
+                    else if (i.probe.status !== 0) {
+                        const err = i.probe.stderr.trim();
+                        out.push({ level: BAD, message: `UserPromptSubmit hook exited ${i.probe.status}${err ? `: ${err.slice(0, 160)}` : ""} - ZCode continues without vexp.` });
+                    }
+                    else {
+                        // Silence is a legitimate outcome for the hint hook (the probe's
+                        // prompt is short on purpose), so report the daemon's reason.
+                        const why = i.probe.stderr.trim().replace(/^vexp prompt-hint: /, "");
+                        out.push({ level: OK, message: `UserPromptSubmit hook runs${why ? ` (this probe: ${why.slice(0, 120)})` : ""}` });
+                    }
+                }
+            }
+        }
+        out.push({ level: NOTE, message: `ZCode applies hook changes to NEW sessions only: start a new ZCode session after 'vexp setup' or any edit of ${hookFile}.` });
+    }
+    return out;
 }
 /**
- * A connected repo of a multi-repo workspace has no daemon of its own: the
- * parent's daemon serves it. Doctor run inside such a repo used to treat it as
- * a standalone workspace — "daemon NOT reachable", "NOT registered" — while
- * `vexp search` from the same directory answered fine (field report,
- * 2026-09-01, nine repos). The link is `.vexp/parent_workspace.json` in the
- * member; when that file is missing, any registered workspace whose
- * workspace.json lists this directory is the parent.
+ * A log line as text twice over: `match` holds the string values only, keys
+ * left out (`"error": null` is not an error); `show` keeps each key next to
+ * its value, so a secret under a key such as api_key is recognisable to
+ * maskSecretsForReport. A line that is not JSON is both.
  */
-export function resolveMemberParent(root, registryRoots) {
-    const link = resolveParentWorkspace(root);
-    if (link) {
-        const alias = listWorkspaceRepos(link.parentRoot).find((r) => samePath(r.resolvedPath, root))?.alias
-            ?? path.basename(root);
-        return { parentRoot: link.parentRoot, alias, via: ".vexp/parent_workspace.json" };
+function logLineText(line) {
+    let v;
+    try {
+        v = JSON.parse(line);
     }
-    for (const reg of registryRoots) {
-        if (samePath(reg, root))
-            continue;
-        const hit = listWorkspaceRepos(reg).find((r) => !r.isPrimary && samePath(r.resolvedPath, root));
-        if (hit)
-            return { parentRoot: reg, alias: hit.alias, via: `${path.join(reg, ".vexp", "workspace.json")} (daemon registry)` };
+    catch {
+        return { match: line, show: line };
     }
-    return null;
+    const values = [];
+    const pairs = [];
+    const walk = (x, key, depth) => {
+        if (depth > 6)
+            return;
+        if (typeof x === "string") {
+            values.push(x);
+            pairs.push(key ? `${key}=${x}` : x);
+        }
+        else if (Array.isArray(x))
+            x.forEach((y) => walk(y, key, depth + 1));
+        else if (x && typeof x === "object")
+            Object.entries(x).forEach(([k, y]) => walk(y, k, depth + 1));
+    };
+    walk(v, "", 0);
+    return values.length > 0 ? { match: values.join(" "), show: pairs.join(" ") } : { match: line, show: line };
 }
 /**
- * Coverage verdicts for the workspace at `root` AND every repo connected to
- * it, each tagged with its alias. Each repo's indexer writes its own
- * `.vexp/coverage.json`; reading only the primary's hid three oversized files
- * in a connected repo from a doctor run at the primary (same report).
+ * ZCode's own log, read as text (its line schema is not documented): the
+ * hook runs that failed, vexp's apart, and the project-level hook configs
+ * it ignored (expected: ZCode never runs project hooks). `lines` null: no
+ * log folder. `files` names what was read.
  */
-export function workspaceCoverageFindings(root) {
-    const repos = listWorkspaceRepos(root);
-    const targets = repos.map((r) => ({ alias: r.alias, dir: r.resolvedPath, primary: r.isPrimary }));
-    if (!targets.some((t) => t.primary))
-        targets.unshift({ alias: path.basename(root), dir: root, primary: true });
-    const out = [];
-    for (const t of targets) {
-        let cov;
-        try {
-            cov = JSON.parse(fs.readFileSync(path.join(t.dir, ".vexp", "coverage.json"), "utf-8"));
-        }
-        catch {
-            continue; /* never indexed, or an index older than 2.7 */
+export function zcodeLogFindings(lines, files = []) {
+    if (lines === null) {
+        return [{ level: NOTE, message: "no ZCode log folder (~/.zcode/cli/log): ZCode has not run a session on this machine, or keeps its log elsewhere" }];
+    }
+    const ignored = [];
+    const failures = [];
+    for (const raw of lines) {
+        if (!raw.trim())
+            continue;
+        const t = logLineText(raw);
+        if (/\bignor/i.test(t.match) && /(project|workspace)/i.test(t.match) && /(hook|config)/i.test(t.match)) {
+            ignored.push(t.show);
+            continue;
         }
-        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 });
+        if (/hook/i.test(t.match) && /(fail|error|timed? ?out|denied|ENOENT|EACCES|EPERM)/i.test(t.match))
+            failures.push(t);
     }
-    return out;
-}
-/**
- * The 7-day activity ledger as doctor lines. Zero calls is not "not
- * working": silence on oriented prompts is vexp doing its job, so the OK
- * line exists whenever prompts were analyzed. The WARN is the other half of
- * 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).
- */
-export function ledgerFindings(ledger) {
+    const ours = failures.filter((t) => /vexp|prompt-hint/i.test(t.match));
+    const where = files.length > 0 ? ` (${files.join(", ")})` : "";
     const out = [];
-    const analyzed = Number(ledger.prompts_analyzed) || 0;
-    if (analyzed > 0) {
-        out.push({
-            level: OK,
-            message: `savings ledger (7d): ${analyzed} prompt(s) analyzed — ${Number(ledger.silences) || 0} silences (task already oriented), ${Number(ledger.hints_served) || 0} hints served. Details: vexp savings`,
-        });
-    }
-    const late = Number(ledger.late) || 0;
-    if (late > 0) {
+    if (ours.length > 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: `ZCode's log${where} records ${ours.length} failed run(s) of vexp's hook; the last: ${maskSecretsForReport(ours[ours.length - 1].show).slice(0, 200)}`,
         });
     }
+    else if (failures.length > 0) {
+        out.push({ level: INFO, message: `ZCode's log${where} records ${failures.length} failed run(s) of other hooks, none of vexp's` });
+    }
+    if (ignored.length > 0) {
+        out.push({ level: INFO, message: `ZCode's log notes ${ignored.length} ignored project-level config(s): expected, ZCode never runs a project's hooks (vexp's hook is in the user config)` });
+    }
+    if (out.length === 0) {
+        out.push(files.length > 0
+            ? { level: OK, message: `ZCode's log${where}: no hook failures recorded` }
+            : { level: NOTE, message: "the ZCode log folder holds no zcode-*.jsonl yet" });
+    }
     return out;
 }
+/** The tail of the newest two ZCode logs, oldest first; null when there is no log folder. */
+export function readZcodeLogTail(dir, maxBytes = 2 * 1024 * 1024) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const newest = names
+        .filter((n) => /^zcode-.*\.jsonl$/.test(n))
+        .map((n) => {
+        try {
+            return { n, mtime: fs.statSync(path.join(dir, n)).mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((x) => x !== null)
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, 2)
+        .reverse();
+    const lines = [];
+    const files = [];
+    for (const { n } of newest) {
+        let fd;
+        try {
+            fd = fs.openSync(path.join(dir, n), "r");
+            const size = fs.fstatSync(fd).size;
+            const start = Math.max(0, size - maxBytes);
+            const buf = Buffer.alloc(size - start);
+            fs.readSync(fd, buf, 0, buf.length, start);
+            const text = buf.toString("utf-8").split(/\r?\n/);
+            // A cut first line is half a record.
+            lines.push(...(start > 0 ? text.slice(1) : text));
+            files.push(n);
+        }
+        catch {
+            /* unreadable: skip it */
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    /* closed */
+                }
+            }
+        }
+    }
+    return { files, lines };
+}
 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
@@ -427,6 +1870,69 @@ export function maskSecretsForReport(text) {
     out = out.replace(ASSIGNED_SECRET, (whole, key, val) => /[$<{]/.test(val) ? whole : key + maskValue(val));
     return out;
 }
+/** Where the first invalid UTF-8 sequence starts (Rust's `valid_up_to`). */
+function utf8ValidUpTo(b) {
+    let i = 0;
+    while (i < b.length) {
+        const c = b[i];
+        if (c < 0x80) {
+            i++;
+            continue;
+        }
+        const len = c >= 0xc2 && c <= 0xdf ? 2 : c >= 0xe0 && c <= 0xef ? 3 : c >= 0xf0 && c <= 0xf4 ? 4 : 0;
+        if (len === 0 || i + len > b.length)
+            return i;
+        // The second byte's range excludes overlong forms, surrogates and > U+10FFFF.
+        const lo = c === 0xe0 ? 0xa0 : c === 0xf0 ? 0x90 : 0x80;
+        const hi = c === 0xed ? 0x9f : c === 0xf4 ? 0x8f : 0xbf;
+        if (b[i + 1] < lo || b[i + 1] > hi)
+            return i;
+        for (let k = 2; k < len; k++)
+            if ((b[i + k] & 0xc0) !== 0x80)
+                return i;
+        i += len;
+    }
+    return i;
+}
+/**
+ * vexp.toml's bytes as text, the way the engine decodes them
+ * (vexp-core config.rs, decode_config_bytes): a byte-order mark is honoured
+ * (UTF-8, UTF-16LE, UTF-16BE), without one the text must be UTF-8. Windows
+ * PowerShell 5.1's `>` writes UTF-16LE (field report, 2026-09-24: the
+ * daemon refused to start on one), which the engine now reads; the report
+ * still read it as UTF-8 and would have shown support the text with a NUL
+ * between every letter instead of the settings the engine runs with.
+ */
+export function decodeConfigBytes(bytes) {
+    const utf16 = (rest, littleEndian, encoding) => {
+        if (rest.length % 2 !== 0)
+            return { problem: "is UTF-16 with a truncated last character" };
+        const le = littleEndian ? rest : Uint8Array.from(rest, (_, i) => rest[i ^ 1]);
+        try {
+            return { text: new TextDecoder("utf-16le", { fatal: true, ignoreBOM: true }).decode(le), encoding };
+        }
+        catch {
+            return { problem: "is not valid UTF-16 text" };
+        }
+    };
+    const utf8 = (rest, bom, encoding) => {
+        try {
+            return { text: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(rest), encoding };
+        }
+        catch {
+            // Worded, and the offset counted, as the engine's warning does.
+            const at = utf8ValidUpTo(rest) + (bom ? 3 : 0);
+            return { problem: bom ? `is not valid UTF-8 (invalid byte at offset ${at})` : `is not UTF-8 text (invalid byte at offset ${at})` };
+        }
+    };
+    if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+        return utf8(bytes.subarray(3), true, "UTF-8 with a byte-order mark");
+    if (bytes[0] === 0xff && bytes[1] === 0xfe)
+        return utf16(bytes.subarray(2), true, "UTF-16LE");
+    if (bytes[0] === 0xfe && bytes[1] === 0xff)
+        return utf16(bytes.subarray(2), false, "UTF-16BE");
+    return utf8(bytes, false, "UTF-8");
+}
 /**
  * The report a tester can hand over without editing it first.
  *
@@ -466,7 +1972,14 @@ export function buildDoctorReport(i) {
     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```");
+    if (i.configProblem) {
+        parts.push(`present, but it ${i.configProblem}: the engine ignores it and runs with the defaults (save it as UTF-8)`);
+    }
+    else {
+        if (i.configEncoding && i.configText !== null)
+            parts.push(`saved as ${i.configEncoding} (the engine reads it)`, "");
+        parts.push(i.configText === null ? "absent — defaults in use" : "```toml\n" + i.configText.trim() + "\n```");
+    }
     parts.push("");
     return maskSecretsForReport(parts.join("\n"));
 }
@@ -496,6 +2009,41 @@ export function logWarningsFrom(text, keep = 80, scan = 3000) {
         .map(({ last, count }) => (count > 1 ? `${last}  (x${count})` : last))
         .slice(-keep);
 }
+/** 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. */
+function icloudLinkedFolders(home) {
+    if (process.platform !== "darwin")
+        return [];
+    const out = [];
+    for (const name of ["Desktop", "Documents"]) {
+        try {
+            const link = path.join(home, "Library", "Mobile Documents", "com~apple~CloudDocs", name);
+            const local = path.join(home, name);
+            if (!fs.lstatSync(link).isSymbolicLink())
+                continue;
+            const real = fs.realpathSync.native(local);
+            if (samePath(fs.realpathSync.native(link), real))
+                out.push(real);
+        }
+        catch { /* not there: not synced */ }
+    }
+    return out;
+}
+/** cloudSyncNotice for this machine: the root as given, then its real path
+ *  (a ~/Repos symlink into iCloud Drive is still in iCloud Drive). */
+function cloudSyncHere(root) {
+    const home = os.homedir();
+    const ctx = { platform: process.platform, home, env: process.env, icloudLinked: icloudLinkedFolders(home) };
+    const direct = cloudSyncNotice(root, ctx);
+    if (direct)
+        return direct;
+    try {
+        return cloudSyncNotice(fs.realpathSync.native(root), ctx);
+    }
+    catch {
+        return null;
+    }
+}
 /** Gather every input on this machine and write the report. Returns its path. */
 export async function writeDoctorReport(o) {
     let bin = null;
@@ -538,8 +2086,17 @@ export async function writeDoctorReport(o) {
         }
     }
     let configText = null;
+    let configProblem;
+    let configEncoding;
     try {
-        configText = fs.readFileSync(path.join(o.root, ".vexp", "vexp.toml"), "utf-8");
+        const decoded = decodeConfigBytes(fs.readFileSync(path.join(o.root, ".vexp", "vexp.toml")));
+        if ("problem" in decoded)
+            configProblem = decoded.problem;
+        else {
+            configText = decoded.text;
+            if (decoded.encoding !== "UTF-8")
+                configEncoding = decoded.encoding;
+        }
     }
     catch {
         /* absent: defaults */
@@ -558,7 +2115,9 @@ export async function writeDoctorReport(o) {
         logName,
         logWarnings,
         configText,
-        mountNotice: slowMountNotice(o.root),
+        configProblem,
+        configEncoding,
+        mountNotice: [slowMountNotice(o.root), cloudSyncHere(o.root)].filter(Boolean).join(" ") || null,
     });
     const dest = o.outFile ? path.resolve(o.outFile) : path.join(o.root, DEFAULT_REPORT_FILE);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -612,6 +2171,13 @@ async function doctorChecks(onWorkspace) {
             fails++;
         console.log(`  [${status}] ${msg}`);
     };
+    // A pure verdict's findings: NOTE is a dim, indented aside, never counted.
+    const emit = (f) => {
+        if (f.level === NOTE)
+            console.log(chalk.dim(`        ${f.message}`));
+        else
+            line(f.level, f.message);
+    };
     console.log(chalk.bold("\nvexp doctor — MCP / daemon diagnostics\n"));
     // 1) Workspace resolution for the current directory.
     console.log(chalk.bold("Workspace targeting"));
@@ -659,6 +2225,9 @@ async function doctorChecks(onWorkspace) {
     // 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.
+    // Prompts that reached vexp through an agent's hook (7 days): the hook
+    // probes below weigh their own failures against it.
+    let hookPrompts7d = 0;
     if (live) {
         const st = await queryDaemon(sock, "index_status");
         if (st) {
@@ -726,26 +2295,42 @@ async function doctorChecks(onWorkspace) {
             // support tickets ("is it working? it never got called").
             const ledger = (st.ledger ?? {});
             const analyzed = Number(ledger.prompts_analyzed) || 0;
+            hookPrompts7d = analyzed;
             for (const f of ledgerFindings(ledger))
                 line(f.level, f.message);
-            if (sessions.length > 0) {
-                const total = sessions.reduce((n, s) => n + (Number(s.pipeline_calls) || 0), 0);
-                line(OK, `sessions (4h): ${sessions.length} active, ${total} pipeline calls total`);
-            }
-            else if (analyzed > 0) {
-                line(OK, `no tool calls in the last 4h — but the ledger above shows vexp is analyzing prompts (zero calls is normal on oriented tasks)`);
-            }
-            else if (Number(st.daemon_uptime_s) > 600) {
-                // Embedded caveat: a stdio MCP server (`vexp-core mcp`) spawned while
-                // the daemon was unreachable serves from its own in-process index and
-                // never attaches to the daemon later — its calls are real but
-                // invisible to these counters. Don't tell that user "the agent is not
-                // using vexp"; tell them how to converge on the daemon.
-                line(WARN, `no agent session has called vexp through this daemon since it started — either no agent is using vexp here (check its MCP config), or the agent's vexp MCP server started BEFORE the daemon and is running embedded (in-process). If calls do succeed in the agent, restart the agent (with the daemon already up) so its MCP server attaches to the daemon.`);
-            }
-            else {
-                line(OK, `no session calls yet (daemon just started)`);
+            // The hook's abstentions, apart from the ledger they never change.
+            for (const f of hookActivityFindings(st.hook_activity, ledger, Math.floor(Date.now() / 1000)))
+                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;
+            for (const f of sessionsFindings(sessions, {
+                uptimeS: Number(st.daemon_uptime_s) || 0,
+                prompts7d: analyzed,
+                hookLastAt: typeof hookLastAt === "number" ? hookLastAt : null,
+                nowS: Math.floor(Date.now() / 1000),
+            }))
+                emit(f);
+        }
+    }
+    // Where the agent hooks ran from, as the hook client recorded it: read from
+    // disk, so it speaks also when no daemon answers here, which is exactly
+    // when an agent with the parent folder open leaves its only trace.
+    {
+        let text = null;
+        try {
+            text = fs.readFileSync(hookCallsPath(), "utf-8");
+        }
+        catch { /* no hook has run on this machine since the breadcrumbs exist */ }
+        if (text !== null) {
+            const aliases = [canonicalWorkspaceRoot(ws.root)];
+            try {
+                aliases.push(fs.realpathSync.native(ws.root));
             }
+            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))
+                emit(f);
         }
     }
     // 3.1 — coverage gaps only the daemon log used to witness. Read from disk,
@@ -755,6 +2340,21 @@ async function doctorChecks(onWorkspace) {
     // repo alias so a run at the primary sees the whole workspace.
     for (const f of workspaceCoverageFindings(ws.root))
         line(f.level, f.message);
+    // Whether each index applies the ignore rules on disk, read from the index
+    // itself: the CLI-only case has no daemon to ask.
+    {
+        let bin = null;
+        try {
+            const { getBinaryPath } = await import("./binary.js");
+            bin = getBinaryPath();
+        }
+        catch { /* no binary: no rules line */ }
+        if (bin) {
+            const exe = bin;
+            for (const f of workspaceRulesFindings(ws.root, (dir) => coreIndexStatus(exe, dir)))
+                line(f.level, f.message);
+        }
+    }
     // 2) Daemon registry (~/.vexp/daemons.json) — stale entries are a drift source.
     console.log(chalk.bold("\nDaemon registry (~/.vexp/daemons.json)"));
     const entries = Object.entries(registry);
@@ -825,16 +2425,61 @@ async function doctorChecks(onWorkspace) {
             line(OK, `${name}: valid, ~${days}d remaining`);
         }
     }
+    // Registration: only a check-in with vexp.dev puts this machine on the
+    // account's device list, and nothing long-running used to make one — a
+    // license could work for a month with the dashboard reading 0 devices.
+    // The stamp alone is not proof: a revocation or a device-cap refusal writes
+    // it too. Registered = the stamp AND a fresh token that still verifies.
+    if (fs.existsSync(path.join(home, ".vexp", "license.jwt"))) {
+        const reg = registrationState();
+        const retry = "run `vexp license` online to check in and see why";
+        switch (reg.state) {
+            case "blocked":
+                line(WARN, `device: NOT registered - the license's ${reg.blocked.maxDevices} device slots are full; free one at ${reg.blocked.manageUrl}`);
+                break;
+            case "registered":
+                line(OK, `device: registered (last check-in ${formatCheckIn(reg.at)})`);
+                break;
+            case "not_registered":
+                line(WARN, `device: last check-in ${formatCheckIn(reg.at)} did not register this device; ${retry}`);
+                break;
+            case "unconfirmed":
+                line(WARN, `device: vexp.dev renewed the license but has not confirmed this device on your account yet; ${retry}`);
+                break;
+            case "never":
+                line(WARN, "device: never checked in with vexp.dev, so it is not on your account's device list yet; run `vexp license` online to register it");
+                break;
+        }
+    }
     // 4) Codex MCP transport stanza — global AND project-level. Codex supports
     // per-project `.codex/config.toml`; checking only the global file made
     // doctor report "[OK] no stanza" to users whose (working) config lives in
     // the workspace.
     console.log(chalk.bold("\nCodex (config.toml)"));
+    // 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);
     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") },
     ];
     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
+    // only when it names no project or this one — the machine-wide entry is
+    // pinned to whichever project was set up last, and from any other one
+    // Codex would answer from that project's index (review of the fix,
+    // 2026-09-24).
+    let codexMcpUsable = false;
+    let codexMcpElsewhere;
+    const codexEntryHere = (section) => {
+        const pin = codexSectionPin(section);
+        if ((pin.path === undefined && pin.hash === undefined) || codexSectionPinnedTo(section, ws.root))
+            return true;
+        codexMcpElsewhere ??= pin.path ?? "another project";
+        return false;
+    };
     for (const { label, file } of codexConfigs) {
         if (!fs.existsSync(file)) {
             line(OK, `${label}: absent`);
@@ -854,15 +2499,30 @@ async function doctorChecks(onWorkspace) {
         codexStanzaSeen = true;
         const hasUrl = /^\s*url\s*=/m.test(section);
         const hasCmd = /^\s*command\s*=/m.test(section);
-        if (hasUrl && hasCmd)
-            line(BAD, `${label}: stanza has BOTH 'url' and 'command' → 'url is not supported for stdio'. Re-run setup to rewrite cleanly.`);
-        else if (hasUrl)
+        if (hasUrl && hasCmd) {
+            line(BAD, `${label}: stanza has BOTH 'url' and 'command' → 'url is not supported for stdio'. ` + codexBrokenStanzaRemedy(codexUse, section, ws.root));
+        }
+        else if (hasUrl) {
+            if (codexEntryHere(section))
+                codexMcpUsable = 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.
+            if (section.includes("# vexp-managed") && codexSectionPin(section).hash !== undefined) {
+                line(WARN, codexHttpPinNote(codexSectionPinnedTo(section, ws.root)));
+            }
+        }
         else if (hasCmd) {
+            const here = codexEntryHere(section);
+            if (here)
+                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 resolves from Codex's cwd"}`);
+            line(OK, `${label}: transport stdio (command)${pins ? `, ${pins}` : ", no workspace pin: the server starts in each Codex session's folder"}`);
+            const pin = codexSectionPin(section).path;
+            if (!here && pin !== undefined && section.includes("# vexp-managed"))
+                line(WARN, codexStdioPinNote(section, pin, ws.root));
         }
         else
             line(WARN, `${label}: stanza present but neither url nor command found`);
@@ -937,11 +2597,18 @@ async function doctorChecks(onWorkspace) {
     // 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).
+    // And a workspace inside a cloud-synced folder uploads .vexp/index.db, a
+    // live SQLite database, on every write (field report, 2026-09-28: iCloud
+    // Drive on macOS).
     {
         const slow = slowMountNotice(ws.root);
-        if (slow) {
+        const cloud = cloudSyncHere(ws.root);
+        if (slow || cloud) {
             console.log(chalk.bold("\nFilesystem"));
-            line(WARN, slow);
+            if (slow)
+                line(WARN, slow);
+            if (cloud)
+                line(WARN, cloud);
         }
     }
     // 5b) Claude Code guard hook — EXECUTE it the way Claude Code would, don't
@@ -949,6 +2616,19 @@ async function doctorChecks(onWorkspace) {
     // path containing a space fails non-blocking on every call: the guard never
     // denies anything while the config "looks correct" and presence-only checks
     // report healthy (Nathan, 2026-07).
+    // Git Bash is looked up once, and only on Windows when a hook needs it.
+    let gitBashLookup;
+    const claudeGitBash = () => {
+        if (!gitBashLookup) {
+            gitBashLookup = resolveClaudeGitBash({ cwd: ws.root, setting: claudeGitBashSetting() });
+            // A pin in the project's own settings is what someone tried; say it
+            // does not count, once, where the lookup is first needed.
+            const pins = projectGitBashPins(ws.root);
+            if (pins.length > 0)
+                line(INFO, projectGitBashPinNote(pins));
+        }
+        return gitBashLookup;
+    };
     console.log(chalk.bold("\nClaude Code guard hook (.claude/settings.json)"));
     {
         const sPath = path.join(ws.root, ".claude", "settings.json");
@@ -991,27 +2671,37 @@ async function doctorChecks(onWorkspace) {
                 if (timeoutS > 600) {
                     line(WARN, `hook timeout ${timeoutS} is in SECONDS (${Math.round(timeoutS / 60)} minutes) — likely meant milliseconds. Re-run 'vexp setup --guard-strict' to fix.`);
                 }
+                if (isPowerShellHook(h)) {
+                    line(INFO, `guard hook declares "shell": "powershell" — not tested here; Claude Code runs it with PowerShell`);
+                    continue;
+                }
                 // Run it exactly as Claude Code would: exec form = direct spawn with
-                // the placeholder substituted by the host; shell form = a shell with
-                // CLAUDE_PROJECT_DIR in the environment. On Windows Claude Code runs
-                // shell-form hooks through Git Bash, so probe via bash there too —
-                // if bash is missing, that IS the finding (Claude Code itself
-                // requires Git Bash on Windows).
+                // the placeholder substituted by the host; shell form = the shell
+                // Claude Code uses (claudeHookSpawnSpec: Git Bash on Windows, never
+                // a `bash` from PATH), both from the project folder.
                 const substituted = cmd.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, ws.root);
-                const shell = process.platform === "win32" ? "bash" : "sh";
-                const r = execForm
-                    ? spawnSync(substituted, h.args.map((a) => String(a).replace(/\$\{CLAUDE_PROJECT_DIR\}/g, ws.root)), {
-                        env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
-                        timeout: 5000,
-                        encoding: "utf-8",
-                    })
-                    : spawnSync(shell, ["-c", cmd], {
+                let spawned = substituted;
+                let r;
+                if (execForm) {
+                    r = spawnSync(substituted, h.args.map((a) => String(a).replace(/\$\{CLAUDE_PROJECT_DIR\}/g, ws.root)), {
                         env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
+                        cwd: ws.root,
                         timeout: 5000,
                         encoding: "utf-8",
                     });
+                }
+                else {
+                    const bash = process.platform === "win32" ? claudeGitBash() : null;
+                    const spec = claudeHookSpawnSpec(cmd, ws.root, process.platform, bash?.path ?? null);
+                    if (!spec) {
+                        line(BAD, claudeShellMissing("the guard hook", bash));
+                        continue;
+                    }
+                    spawned = spec.file;
+                    r = spawnSync(spec.file, spec.args, { env: spec.env, cwd: spec.cwd, timeout: 5000, encoding: "utf-8", windowsHide: true });
+                }
                 if (r.error) {
-                    line(BAD, `guard hook DID NOT RUN: ${r.error.code ?? r.error.message} spawning '${substituted}' — the guard is enforcing nothing. Re-run 'vexp setup --guard-strict'.`);
+                    line(BAD, `guard hook DID NOT RUN: ${r.error.code ?? r.error.message} spawning '${spawned}' — the guard is enforcing nothing. Re-run 'vexp setup --guard-strict'.`);
                 }
                 else if (r.status !== 0) {
                     line(BAD, `guard hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 200)}` : ""} — Claude Code treats this as a non-blocking failure, so searches proceed unguarded.`);
@@ -1054,7 +2744,12 @@ async function doctorChecks(onWorkspace) {
                 return false;
             }
         });
-        const verdict = gitHooksVerdict(hooksPath, ws.root, installed.length);
+        let declined;
+        try {
+            declined = fs.readFileSync(path.join(ws.root, ".vexp", "git-hooks.declined"), "utf-8").split(/\r?\n/)[0];
+        }
+        catch { /* not declined */ }
+        const verdict = gitHooksVerdict(hooksPath, ws.root, installed.length, declined);
         line(verdict.level, verdict.message);
     }
     console.log(chalk.bold("\nClaude Code orientation hooks (.claude/settings.json)"));
@@ -1091,6 +2786,9 @@ async function doctorChecks(onWorkspace) {
                 : "no .claude/settings.json (Claude Code not configured here)");
         }
         else {
+            // Hooks Claude Code cannot run on this PC for want of Git Bash: one line
+            // for all of them, after the loop.
+            const noShell = [];
             for (const w of wanted) {
                 const entries = Array.isArray(settings?.hooks?.[w.event]) ? settings.hooks[w.event] : [];
                 const hook = entries
@@ -1105,6 +2803,13 @@ async function doctorChecks(onWorkspace) {
                     }
                     continue;
                 }
+                // Before the .sh check: a PowerShell entry names its own script (a
+                // .ps1), and "vexp-verify.sh is missing — fails on every prompt" was
+                // a FAIL for an entry that never runs that file (review, 2026-09-24).
+                if (isPowerShellHook(hook)) {
+                    line(INFO, `${w.event} hook declares "shell": "powershell" — not tested here; Claude Code runs it with PowerShell`);
+                    continue;
+                }
                 const scriptPath = path.join(ws.root, ".claude", "hooks", `${w.marker}.sh`);
                 if (!fs.existsSync(scriptPath)) {
                     line(BAD, `${w.event} points at ${w.marker}.sh but the script is missing — the hook fails on every prompt.`);
@@ -1116,17 +2821,26 @@ async function doctorChecks(onWorkspace) {
                     : w.event === "Stop"
                         ? { session_id: "vexp-doctor", stop_hook_active: true, cwd: ws.root }
                         : { session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root });
-                const r = spawnSync(process.platform === "win32" ? "bash" : "sh", ["-c", hook.command], {
-                    env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
+                // In Claude Code's own shell (claudeHookSpawnSpec), from the project.
+                const bash = process.platform === "win32" ? claudeGitBash() : null;
+                const spec = claudeHookSpawnSpec(hook.command, ws.root, process.platform, bash?.path ?? null);
+                if (!spec) {
+                    noShell.push(w.event);
+                    continue;
+                }
+                const r = spawnSync(spec.file, spec.args, {
+                    env: spec.env,
+                    cwd: spec.cwd,
                     input: payload,
                     timeout: 10000,
                     encoding: "utf-8",
+                    windowsHide: true,
                 });
                 if (r.error) {
-                    line(BAD, `${w.event} hook DID NOT RUN: ${r.error.code ?? r.error.message} — the ${w.label} is inert.`);
+                    line(BAD, `${w.event} hook DID NOT RUN: ${r.error.code ?? r.error.message} — the ${w.label} is inert.` + hookLedgerNote(hookPrompts7d));
                 }
                 else if (r.status !== 0) {
-                    line(BAD, `${w.event} hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 160)}` : ""} — Claude Code treats this as a failure and continues without vexp.`);
+                    line(BAD, `${w.event} hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 160)}` : ""} — Claude Code treats this as a failure and continues without vexp.` + hookLedgerNote(hookPrompts7d));
                 }
                 else {
                     // Silence is a legitimate outcome for the hint hook (the classifier
@@ -1135,6 +2849,9 @@ async function doctorChecks(onWorkspace) {
                     line(OK, `${w.event} hook runs${why ? ` (this probe: ${why.slice(0, 120)})` : ""}`);
                 }
             }
+            if (noShell.length > 0) {
+                line(BAD, claudeShellMissing(`the ${noShell.join(", ")} hook${noShell.length > 1 ? "s" : ""}`, claudeGitBash()));
+            }
         }
     }
     // 5b-bis) Codex orientation hook. The section above it reports Codex's MCP
@@ -1148,97 +2865,211 @@ async function doctorChecks(onWorkspace) {
     {
         const hooksJson = path.join(ws.root, ".codex", "hooks.json");
         const scriptPath = path.join(ws.root, ".codex", "vexp-hint.sh");
-        const codexMcp = (() => {
-            try {
-                return fs
-                    .readFileSync(path.join(os.homedir(), ".codex", "config.toml"), "utf-8")
-                    .includes("vexp");
-            }
-            catch {
-                return false;
-            }
-        })();
         let cfg = null;
+        let hooksRaw = "";
+        // The installer's own parser: a BOM (Windows PowerShell 5.1 writes one)
+        // made a valid file read as "no .codex/hooks.json" here.
         try {
-            cfg = JSON.parse(fs.readFileSync(hooksJson, "utf-8"));
+            hooksRaw = fs.readFileSync(hooksJson, "utf-8");
+            cfg = parseJsonc(hooksRaw);
         }
         catch { /* absent */ }
-        if (!cfg) {
-            // Only a finding for someone who actually uses Codex here.
-            line(codexMcp ? WARN : OK, codexMcp
-                ? "no .codex/hooks.json, but vexp MCP is configured for Codex — the tools work and the per-prompt orientation was never installed. Run 'vexp setup' here (needs Codex >= 0.129)."
-                : "no .codex/hooks.json (Codex not configured here)");
+        // Two shapes exist in the wild: the installer nests under "hooks", and
+        // files from earlier versions (or edited by hand) carry the event at the
+        // top level. Reading only one of them would leave the other undiagnosable
+        // — and the flat one is what the user who reported this had on disk.
+        const events = (Array.isArray(cfg?.hooks?.UserPromptSubmit)
+            ? cfg.hooks.UserPromptSubmit
+            : Array.isArray(cfg?.UserPromptSubmit)
+                ? cfg.UserPromptSubmit
+                : []);
+        const hook = events
+            .flatMap((m) => (Array.isArray(m?.hooks) ? m.hooks : []))
+            .find((h) => typeof h?.command === "string" && h.command.includes("vexp-hint"));
+        const verdict = codexHookVerdict({
+            platform: process.platform,
+            root: ws.root,
+            use: codexUse,
+            mcpEntrySeen: codexMcpUsable,
+            mcpEntryElsewhere: codexMcpElsewhere,
+            hooksJson: !cfg ? "absent" : hook ? "entry" : "no-entry",
+            hasCommandWindows: typeof hook?.commandWindows === "string",
+            commandWindows: typeof hook?.commandWindows === "string" ? hook.commandWindows : undefined,
+            // The script the platform's command runs: on Windows the entry's
+            // Windows command, vexp-hint.cmd.
+            scriptPresent: fs.existsSync(process.platform === "win32" && typeof hook?.commandWindows === "string" ? path.join(ws.root, ".codex", "vexp-hint.cmd") : scriptPath),
+            leftovers: codexUse.used ? { files: [], onlyOurs: false } : codexLeftovers(ws.root),
+        });
+        // Reading past the BOM must not turn into an [OK] for a file Codex may
+        // refuse: serde_json, Rust's usual JSON reader, rejects one ("expected
+        // value at line 1 column 1", checked on 1.0.150), and a hooks.json Codex
+        // cannot parse runs none of its hooks. Before the tolerant read above,
+        // the wrong "no .codex/hooks.json" at least led to a rewrite (review of
+        // the fix, 2026-09-24). The installer leaves a file that already holds
+        // vexp's entry as it is, so the remedy is a re-save, not 'vexp setup'.
+        if (codexUse.used && cfg && hooksRaw.charCodeAt(0) === 0xfeff)
+            line(WARN, CODEX_HOOKS_BOM_NOTE);
+        if (!verdict.run) {
+            line(verdict.level, verdict.message);
         }
         else {
-            // Two shapes exist in the wild: the installer nests under "hooks", and
-            // files from earlier versions (or edited by hand) carry the event at the
-            // top level. Reading only one of them would leave the other undiagnosable
-            // — and the flat one is what the user who reported this had on disk.
-            const events = (Array.isArray(cfg?.hooks?.UserPromptSubmit)
-                ? cfg.hooks.UserPromptSubmit
-                : Array.isArray(cfg?.UserPromptSubmit)
-                    ? cfg.UserPromptSubmit
-                    : []);
-            const hook = events
-                .flatMap((m) => (Array.isArray(m?.hooks) ? m.hooks : []))
-                .find((h) => typeof h?.command === "string" && h.command.includes("vexp-hint"));
-            if (!hook) {
-                line(WARN, "hooks.json has no vexp UserPromptSubmit entry — re-run 'vexp setup'.");
-            }
-            else if (!fs.existsSync(scriptPath)) {
-                line(BAD, "hooks.json points at .codex/vexp-hint.sh but the script is missing — the hook fails on every prompt.");
-            }
-            else if (process.platform === "win32" && typeof hook.commandWindows !== "string") {
-                // On Windows Codex runs the command through cmd.exe, which has no
-                // bash: without the commandWindows override the entry is inert on
-                // every prompt unless Git Bash happens to be on PATH. Probing it
-                // through bash here would hide exactly that.
-                line(BAD, "the entry has no 'commandWindows' — Codex runs hooks through cmd.exe on Windows, which cannot run the bash script, so orientation never fires (unless Git Bash is on PATH). Re-run 'vexp setup' to write the batch twin.");
-            }
-            else {
-                // Run it, through the same shell Codex would use — cmd.exe on
-                // Windows (COMSPEC) with the line wrapped the way Codex wraps it, sh
-                // elsewhere (codexHookSpawnSpec). The script bakes an absolute path
-                // to the vexp binary and exits 0 when that path is not executable, so
-                // a stale or wrong-profile path leaves NO trace anywhere: no
-                // orientation, no error, forever. A Windows user found exactly that
-                // by reading the generated file.
-                const isWin = process.platform === "win32";
-                const cmdLine = (isWin ? hook.commandWindows : hook.command);
-                const spec = codexHookSpawnSpec(cmdLine);
+            // Run it, through the shells Codex would use: on Windows PowerShell
+            // (its default) and cmd.exe with the line wrapped the way Codex wraps
+            // it (its fallback), sh elsewhere. The script bakes an absolute path
+            // to the vexp binary and exits 0 when that path is not executable, so
+            // a stale or wrong-profile path leaves NO trace anywhere: no
+            // orientation, no error, forever. A Windows user found exactly that
+            // by reading the generated file.
+            const isWin = process.platform === "win32";
+            const cmdLine = (isWin ? hook.commandWindows : hook.command);
+            const probes = isWin
+                ? [
+                    { shell: "PowerShell", spec: codexPowerShellSpawnSpec(cmdLine, windowsPowerShell()) },
+                    { shell: "cmd.exe", spec: codexHookSpawnSpec(cmdLine) },
+                ]
+                : [{ shell: "sh", spec: codexHookSpawnSpec(cmdLine) }];
+            const baked = (() => {
+                try {
+                    // One pattern covers both twins: VEXP_BIN="path" (bash) and
+                    // set "VEXP_BIN=path" (cmd).
+                    const probed = isWin ? path.join(ws.root, ".codex", "vexp-hint.cmd") : scriptPath;
+                    return fs.readFileSync(probed, "utf-8").match(/VEXP_BIN="?([^"\r\n]+)"?/)?.[1];
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            for (const { shell, spec } of probes) {
+                const via = isWin ? ` (through ${shell})` : "";
                 const r = spawnSync(spec.file, spec.args, {
                     windowsVerbatimArguments: spec.windowsVerbatimArguments,
                     env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
+                    // From the project, as Codex runs it — except a \\server\share
+                    // root on Windows: cmd.exe cannot stand in one, prints "UNC paths are
+                    // not supported. Defaulting to Windows directory." on stderr and runs
+                    // from there anyway. Start it there directly; the hook line names its
+                    // script by absolute path.
+                    cwd: isWin && /^[\\/]{2}/.test(ws.root) ? process.env.SystemRoot || "C:\\Windows" : ws.root,
                     input: JSON.stringify({ session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root }),
                     timeout: 10000,
                     encoding: "utf-8",
+                    windowsHide: true,
                 });
-                const baked = (() => {
-                    try {
-                        // One pattern covers both twins: VEXP_BIN="path" (bash) and
-                        // set "VEXP_BIN=path" (cmd).
-                        const probed = isWin ? path.join(ws.root, ".codex", "vexp-hint.cmd") : scriptPath;
-                        return fs.readFileSync(probed, "utf-8").match(/VEXP_BIN="?([^"\r\n]+)"?/)?.[1];
-                    }
-                    catch {
-                        return undefined;
-                    }
-                })();
                 if (r.error) {
-                    line(BAD, `hook DID NOT RUN: ${r.error.code ?? r.error.message} — orientation is inert.`);
+                    line(BAD, `hook DID NOT RUN${via}: ${r.error.code ?? r.error.message}; orientation is inert.`);
                 }
                 else if (r.status !== 0) {
-                    line(BAD, `hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 160)}` : ""} — Codex continues without vexp.`);
+                    line(BAD, `hook exited ${r.status}${via}${r.stderr ? `: ${String(r.stderr).trim().slice(0, 160)}` : ""}; Codex continues without vexp.`);
+                }
+                else if (hookEchoedItself(String(r.stdout ?? ""), cmdLine)) {
+                    line(BAD, `hook printed its own command instead of running it${via}: Codex would hand that text to the model on every prompt, and the script never runs. Re-run '${codexSetupCommand(ws.root)}'.`);
                 }
                 else if (baked && !fs.existsSync(baked)) {
-                    line(BAD, `hook runs but the binary it points at does not exist: ${baked} — it exits silently on every prompt. Re-run 'vexp setup' as the user that owns this install.`);
+                    // The root named, as in every other Codex remedy: a bare 'vexp setup'
+                    // takes the folder it runs in as the project, and from src/deep it
+                    // set that subfolder up as a new one (review of the fix, 2026-09-24).
+                    line(BAD, `hook runs but the binary it points at does not exist: ${baked} — it exits silently on every prompt. Re-run '${codexSetupCommand(ws.root)}' as the user that owns this install.`);
+                    break;
                 }
                 else {
                     const why = String(r.stderr ?? "").trim().replace(/^vexp [\w-]+: /, "");
-                    line(OK, `UserPromptSubmit hook runs${why ? ` (this probe: ${why.slice(0, 120)})` : ""}`);
+                    line(OK, `UserPromptSubmit hook runs${via}${why ? ` (this probe: ${why.slice(0, 120)})` : ""}`);
                 }
             }
         }
+        // Running is not enough: Codex runs a project hook only in a project it
+        // trusts, and only once the user approved that exact hook (/hooks in the
+        // terminal, Settings > Hooks in the VS Code extension). Both records live
+        // in Codex's own config.toml; vexp reads them and never writes them.
+        const nested = Array.isArray(cfg?.hooks?.UserPromptSubmit) ? cfg.hooks.UserPromptSubmit : [];
+        const groupIndex = nested.findIndex((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => typeof h?.command === "string" && h.command.includes("vexp-hint")));
+        if (codexUse.used && groupIndex >= 0) {
+            const handlerIndex = nested[groupIndex].hooks.findIndex((h) => typeof h?.command === "string" && h.command.includes("vexp-hint"));
+            const home = codexHome();
+            const configPath = path.join(home, "config.toml");
+            let userConfig;
+            try {
+                userConfig = fs.readFileSync(configPath, "utf-8");
+            }
+            catch { /* none yet */ }
+            const trust = codexHookTrust({
+                platform: process.platform,
+                userConfig,
+                userConfigPath: configPath,
+                otherLayers: codexOtherConfigLayers(),
+                trustCandidates: codexTrustCandidates(ws.root, (args) => {
+                    try {
+                        const r = spawnSync("git", args, { cwd: ws.root, encoding: "utf-8", timeout: 5000, windowsHide: true });
+                        return r.status === 0 ? String(r.stdout).trim() || undefined : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                }),
+                hooksJsonPath: hooksJson,
+                groupIndex,
+                handlerIndex,
+                handler: nested[groupIndex].hooks[handlerIndex],
+            });
+            for (const f of codexTrustFindings(trust, ws.root, configPath, { OK, WARN }))
+                line(f.level, f.message);
+        }
+    }
+    // 5b-ter) ZCode. Setup has written its three pieces since 3.2.0 (AGENTS.md,
+    // an MCP entry, a user-level hook) and doctor checked none of them: a user
+    // whose ZCode had the project's parent folder open read an all-green doctor
+    // and "vexp is not used" in the same afternoon (field report, 2026-09-28).
+    // Every decision is in zcodeFindings; this block only reads and probes.
+    console.log(chalk.bold("\nZCode (AGENTS.md, .zcode/config.json, ~/.zcode/cli/config.json)"));
+    try {
+        const home = os.homedir();
+        let agentsMd = null;
+        try {
+            agentsMd = fs.readFileSync(path.join(ws.root, "AGENTS.md"), "utf-8");
+        }
+        catch { /* absent */ }
+        const input = {
+            root: ws.root,
+            platform: process.platform,
+            home,
+            workspaceNative: readJsonFileState(path.join(ws.root, ".zcode", "config.json")),
+            workspaceCompat: readJsonFileState(path.join(ws.root, ".agents", "mcp.json")),
+            userNative: readJsonFileState(zcodeUserConfigPath()),
+            userCompat: readJsonFileState(path.join(home, ".agents", "mcp.json")),
+            agentsMd,
+            exists: (p) => fs.existsSync(p),
+            zcodeHomeExists: fs.existsSync(path.join(home, ".zcode")),
+            consent: decisionFor(readAgentConsent(), ws.root, "ZCode"),
+        };
+        const inUse = zcodeInUse(input);
+        const spec = inUse ? zcodeProbeSpec(input) : null;
+        if (spec) {
+            // Run it as ZCode does: a `process` hook, argv without a shell, from
+            // the project. No hook_event_name or transcript_path in the payload:
+            // the hook client takes it for a manual probe, so it counts in no
+            // ledger and leaves no breadcrumb.
+            const r = spawnSync(spec.command, spec.args, {
+                input: JSON.stringify({ session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root }),
+                cwd: ws.root,
+                timeout: 10000,
+                encoding: "utf-8",
+                windowsHide: true,
+            });
+            input.probe = r.error
+                ? { error: r.error.code ?? r.error.message, status: r.status, stderr: String(r.stderr ?? "") }
+                : { status: r.status, stderr: String(r.stderr ?? "") };
+        }
+        for (const f of zcodeFindings(input))
+            emit(f);
+        if (inUse) {
+            const log = readZcodeLogTail(path.join(home, ".zcode", "cli", "log"));
+            for (const f of zcodeLogFindings(log ? log.lines : null, log ? log.files : []))
+                emit(f);
+        }
+    }
+    catch (e) {
+        // Never the reason doctor stops: the sections below still run.
+        line(INFO, `ZCode: not checked (${e?.message ?? String(e)})`);
     }
     // 5c) Cursor guard hook — same live-execution philosophy as 5b. Cursor's
     // hooks fail OPEN too (`failClosed` defaults to false), so a guard that
@@ -1382,7 +3213,9 @@ async function doctorChecks(onWorkspace) {
     else
         console.log(`  ${fails > 0 ? BAD : WARN} ${fails} failure(s), ${warns} warning(s)`);
     if (warns > 0 || fails > 0) {
-        console.log(chalk.dim("  Tips: 'vexp daemon-cmd restart' restarts the workspace daemon; 'vexp setup' rewrites agent configs; restart Codex to drop a cached config."));
+        // 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("");
     // Scripts and CI read the exit code, not the colors: any FAIL exits 1.