vexp-cli 3.2.5 → 3.3.0

package/dist/doctor.js

@@ -2,16 +2,19 @@ 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 } 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 { 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 +22,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 +193,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 +273,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.
  *
@@ -299,14 +343,16 @@ export function vsCodeMcpVerdict(cfg, wsRoot, exists = (p) => fs.existsSync(p))
     return { level: OK, message: `.vscode/mcp.json vexp server: ${command} ${script ?? args.join(" ")}` };
 }
 /**
- * How doctor runs a Codex `UserPromptSubmit` hook line: the way Codex does.
- * On Windows Codex hands `cmd.exe /C` the WHOLE line wrapped in one more pair
- * of quotes, verbatim (codex-rs/hooks engine/command_runner: `raw_arg`), and
- * cmd strips that outer pair — which is why the installer may quote the
- * script path. Passing the line as a normal argument instead lets Node escape
+ * 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") {
@@ -314,6 +360,561 @@ export function codexHookSpawnSpec(cmdLine, platform = process.platform, comspec
     }
     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.
@@ -364,9 +965,132 @@ export function workspaceCoverageFindings(root) {
         catch {
             continue; /* never indexed, or an index older than 2.7 */
         }
-        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 });
+        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;
 }
@@ -381,13 +1105,17 @@ export function workspaceCoverageFindings(root) {
 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. Details: vexp savings`,
+            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`,
         });
     }
-    const late = Number(ledger.late) || 0;
     if (late > 0) {
         out.push({
             level: WARN,
@@ -427,6 +1155,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 +1257,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"));
 }
@@ -538,8 +1336,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,6 +1365,8 @@ export async function writeDoctorReport(o) {
         logName,
         logWarnings,
         configText,
+        configProblem,
+        configEncoding,
         mountNotice: slowMountNotice(o.root),
     });
     const dest = o.outFile ? path.resolve(o.outFile) : path.join(o.root, DEFAULT_REPORT_FILE);
@@ -659,6 +1468,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,6 +1538,7 @@ 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) {
@@ -755,6 +1568,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 +1653,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 +1727,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`);
@@ -949,6 +1837,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 +1892,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 +1965,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 +2007,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 +2024,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 +2042,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 +2070,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 +2086,155 @@ 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);
+        }
     }
     // 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 +2378,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.