vexp-cli 3.3.0 → 3.3.1

package/dist/doctor.js

@@ -6,12 +6,13 @@ import { execFileSync, spawnSync } from "child_process";
 import chalk from "chalk";
 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 { 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";
@@ -1124,6 +1125,720 @@ export function ledgerFindings(ledger) {
     }
     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}'` });
+    }
+    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 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.
+ */
+function logLineText(line) {
+    let v;
+    try {
+        v = JSON.parse(line);
+    }
+    catch {
+        return { match: line, show: line };
+    }
+    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 };
+}
+/**
+ * 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 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;
+        }
+        if (/hook/i.test(t.match) && /(fail|error|timed? ?out|denied|ENOENT|EACCES|EPERM)/i.test(t.match))
+            failures.push(t);
+    }
+    const ours = failures.filter((t) => /vexp|prompt-hint/i.test(t.match));
+    const where = files.length > 0 ? ` (${files.join(", ")})` : "";
+    const out = [];
+    if (ours.length > 0) {
+        out.push({
+            level: WARN,
+            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
@@ -1294,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;
@@ -1367,7 +2117,7 @@ export async function writeDoctorReport(o) {
         configText,
         configProblem,
         configEncoding,
-        mountNotice: slowMountNotice(o.root),
+        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 });
@@ -1421,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"));
@@ -1541,24 +2298,39 @@ async function doctorChecks(onWorkspace) {
             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,
@@ -1825,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
@@ -2236,6 +3015,62 @@ async function doctorChecks(onWorkspace) {
                 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
     // cannot spawn silently enforces nothing there as well. The guard's stdin