vexp-cli 2.0.23 → 2.0.25

package/dist/agent-config.js

@@ -490,6 +490,28 @@ function backupConfig(filePath) {
     }
     catch { /* non-fatal */ }
 }
+/**
+ * Atomic write: write to a temp file then rename over the target. rename is
+ * atomic on POSIX and Windows, so a concurrent reader (e.g. Codex reloading
+ * ~/.codex/config.toml while VS Code AND Cursor both rewrite it on activation)
+ * never observes a half-written / mixed-transport config. Used for the shared
+ * global config files where cross-process races are possible.
+ */
+function atomicWriteFileSync(filePath, content) {
+    const tmp = `${filePath}.vexp-tmp-${process.pid}`;
+    try {
+        fs.writeFileSync(tmp, content, "utf-8");
+        fs.renameSync(tmp, filePath);
+    }
+    catch {
+        // Cross-device rename or a Windows edge — fall back to a direct write.
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        fs.writeFileSync(filePath, content, "utf-8");
+    }
+}
 /** Warn that we refused to touch an unparseable config file. */
 function warnUnparseable(filePath) {
     process.stderr.write(`  [!] ${filePath} could not be parsed - leaving it untouched. Fix the file or add vexp manually, then re-run setup.\n`);
@@ -698,7 +720,10 @@ function buildCodexSection(opts) {
             "[mcp_servers.vexp]",
             `${CODEX_MANAGED_MARKER}: direct transport (set VEXP_CODEX_TRANSPORT=http for the HTTP supervisor)`,
             `command = ${tomlString(opts.coreBinaryPath)}`,
-            `args = ["mcp"]`,
+            // Pass --workspace explicitly (highest precedence in cmd_mcp) IN ADDITION to
+            // the env pin below, so a stale cwd / stale cached env can't drift the child
+            // to the wrong repo. JSON.stringify yields a TOML-valid quoted string array.
+            `args = ${opts.workspaceRoot ? JSON.stringify(["mcp", "--workspace", opts.workspaceRoot]) : '["mcp"]'}`,
         ];
         if (opts.workspaceRoot)
             lines.push(`cwd = ${tomlString(opts.workspaceRoot)}`);
@@ -734,10 +759,12 @@ export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot)
     const mcpPort = readMcpPort(workspaceRoot);
     const token = resolveCodexToken();
     const requested = (process.env.VEXP_CODEX_TRANSPORT ?? "direct").toLowerCase();
-    let transport = requested === "http" ? "http" : "direct";
-    if (transport === "direct" && !(binaryPath && fs.existsSync(binaryPath))) {
-        transport = "http";
-    }
+    const transport = requested === "http" ? "http" : "direct";
+    // Do NOT auto-fall-back to http when the binary is missing — that emits a `url=`
+    // stanza Codex can cache → "url is not supported for stdio". Pass the binary only
+    // when it exists; buildCodexSection(direct, undefined) returns null → we then
+    // PRESERVE the existing managed section instead of clobbering it with a url.
+    const coreBinaryPath = binaryPath && fs.existsSync(binaryPath) ? binaryPath : undefined;
     let content = "";
     if (fs.existsSync(configPath))
         content = fs.readFileSync(configPath, "utf-8");
@@ -754,16 +781,18 @@ export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot)
     if (isUserManagedCodexSection(existingSection)) {
         if (content !== original) {
             backupConfig(configPath);
-            fs.writeFileSync(configPath, content, "utf-8");
+            atomicWriteFileSync(configPath, content);
             return true;
         }
         return false;
     }
-    const newSection = buildCodexSection({ transport, coreBinaryPath: binaryPath, workspaceRoot, mcpPort, token, home });
+    const newSection = buildCodexSection({ transport, coreBinaryPath, workspaceRoot, mcpPort, token, home });
     if (!newSection) {
+        // direct requested but binary missing → preserve the existing section (only
+        // persist any legacy cleanup we already did); never emit a url fallback.
         if (content !== original) {
             backupConfig(configPath);
-            fs.writeFileSync(configPath, content, "utf-8");
+            atomicWriteFileSync(configPath, content);
             return true;
         }
         return false;
@@ -773,7 +802,7 @@ export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot)
     if (content === original)
         return false;
     backupConfig(configPath);
-    fs.writeFileSync(configPath, content, "utf-8");
+    atomicWriteFileSync(configPath, content);
     return true;
 }
 /**
@@ -884,11 +913,19 @@ export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRo
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
     const desiredCommand = useNode ? "node" : binaryPath;
     const desiredArgs = useNode ? [mcpServerPath] : ["mcp"];
-    const desiredEnv = workspaceRoot ? { VEXP_WORKSPACE: workspaceRoot } : undefined;
+    // Multi-session fix: do NOT pin VEXP_WORKSPACE on this user-scope entry.
+    // Claude Code applies ~/.claude.json mcpServers to EVERY project, so a pinned
+    // workspace forces all parallel sessions onto one daemon (the wrong project for
+    // every session but the last one configured). With no env, each session resolves
+    // its own project at runtime via CLAUDE_PROJECT_DIR / cwd (see
+    // daemon-client.ts resolveWorkspaceRoot). `workspaceRoot` is intentionally unused
+    // here now; an existing pinned entry is migrated away by the identical-check
+    // (prevEnv !== undefined → not identical → rewritten without env).
+    const prevEnv = existing?.env;
     const identical = existing?.["command"] === desiredCommand &&
         Array.isArray(existing?.["args"]) &&
         JSON.stringify(existing["args"]) === JSON.stringify(desiredArgs) &&
-        JSON.stringify(existing?.env) === JSON.stringify(desiredEnv);
+        prevEnv === undefined;
     const removed = stripLegacyVexpEntries(config, "mcpServers");
     logRemoval(removed);
     if (identical && removed.length === 0)
@@ -897,14 +934,63 @@ export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRo
     servers["vexp"] = {
         command: desiredCommand,
         args: desiredArgs,
-        ...(desiredEnv ? { env: desiredEnv } : {}),
     };
     config.mcpServers = servers;
     if (read.existed)
         backupConfig(configPath);
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+    atomicWriteFileSync(configPath, JSON.stringify(config, null, 2));
     return true;
 }
+/**
+ * One-shot migration for the multi-session fix: remove the legacy
+ * `env.VEXP_WORKSPACE` pin from the vexp entry in user-scope `~/.claude.json`.
+ *
+ * A CLI-only user who merely upgrades the package keeps the OLD pinned config
+ * until they re-run `vexp setup` — and while pinned, every parallel Claude Code
+ * session still targets one project (the bug). This de-pins it surgically:
+ * only the pin is removed (the entry, its command/args, and every OTHER server
+ * are preserved), a backup is written first, and only a vexp-managed entry is
+ * ever touched (never a hand-rolled `vexp`). After de-pinning, each session
+ * resolves its own project at runtime via CLAUDE_PROJECT_DIR.
+ *
+ * Returns: `migrated` (pin removed), `noop` (no vexp pin / not vexp-managed),
+ * `absent` (no ~/.claude.json), `unreadable` (file present but unparseable —
+ * left untouched).
+ */
+export function migrateClaudeCodeUnpin() {
+    const home = os.homedir();
+    if (!home)
+        return "absent";
+    const configPath = path.join(home, ".claude.json");
+    if (!fs.existsSync(configPath))
+        return "absent";
+    const read = readJsonConfigSafe(configPath);
+    if (!read.ok)
+        return "unreadable"; // never clobber an unparseable user file
+    const config = read.data;
+    const servers = config.mcpServers;
+    const vexp = servers?.["vexp"];
+    if (!vexp)
+        return "noop";
+    const env = vexp.env;
+    if (!env || typeof env !== "object" || env["VEXP_WORKSPACE"] === undefined)
+        return "noop";
+    // Only migrate an entry that looks vexp-managed (`args: ["mcp"]` for the Rust
+    // binary, or a `node …/mcp-server.cjs` bundle), never a hand-rolled `vexp`.
+    const args = vexp["args"];
+    const looksManaged = Array.isArray(args) &&
+        (JSON.stringify(args) === JSON.stringify(["mcp"]) ||
+            (typeof args[0] === "string" && /mcp-server\.cjs$/.test(args[0])));
+    if (!looksManaged)
+        return "noop";
+    // Remove only the pin; drop `env` entirely if it becomes empty.
+    delete env["VEXP_WORKSPACE"];
+    if (Object.keys(env).length === 0)
+        delete vexp.env;
+    backupConfig(configPath);
+    atomicWriteFileSync(configPath, JSON.stringify(config, null, 2));
+    return "migrated";
+}
 // ---------------------------------------------------------------------------
 // Claude Code PreToolUse hook - blocks Grep/Glob when daemon is available
 // ---------------------------------------------------------------------------

package/dist/autostart.js

@@ -2,6 +2,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { execFileSync, spawnSync } from "child_process";
+import { migrateClaudeCodeUnpin } from "./agent-config.js";
 const LABEL = "io.vexp.serve";
 const BEGIN_MARKER = "# vexp-autostart-begin";
 const END_MARKER = "# vexp-autostart-end";
@@ -364,6 +365,50 @@ export function installAutostartIfNeeded() {
     }
     catch { /* non-fatal — opt-in best effort */ }
 }
+const CLAUDE_UNPIN_MARKER_FILE = "claude-unpin-migrated";
+function claudeUnpinMarkerPath() {
+    return path.join(homedir(), ".vexp", CLAUDE_UNPIN_MARKER_FILE);
+}
+/**
+ * One-shot, idempotent migration run from `vexp`'s preAction on every invocation.
+ *
+ * The multi-session fix dropped the `VEXP_WORKSPACE` pin from Claude Code's
+ * user-scope `~/.claude.json` entry, but a CLI-only user who merely upgrades the
+ * package keeps the OLD pinned config until they re-run `vexp setup`. This
+ * de-pins it automatically on the FIRST `vexp` command after upgrade.
+ *
+ * Marker-gated (`~/.vexp/claude-unpin-migrated`) so it runs at most once and we
+ * never re-parse the possibly-large `~/.claude.json` on subsequent invocations.
+ * The actual edit is surgical + backed up (see `migrateClaudeCodeUnpin`). Opt out
+ * with `VEXP_NO_AUTOSTART_INSTALL=1` (same switch as autostart install). A
+ * transient `unreadable` result does NOT write the marker, so it retries later.
+ */
+export function migrateClaudeUnpinIfNeeded() {
+    if (process.env.VEXP_NO_AUTOSTART_INSTALL === "1")
+        return;
+    const marker = claudeUnpinMarkerPath();
+    if (fs.existsSync(marker))
+        return;
+    let result;
+    try {
+        result = migrateClaudeCodeUnpin();
+    }
+    catch {
+        return; // non-fatal; retry on a later invocation
+    }
+    if (result === "unreadable")
+        return; // don't mark done — give it another chance
+    if (result === "migrated") {
+        console.error("[vexp] Updated ~/.claude.json: removed the global VEXP_WORKSPACE pin so " +
+            "parallel Claude Code sessions each target their own project " +
+            "(backup at ~/.claude.json.vexp-bak).");
+    }
+    try {
+        fs.mkdirSync(path.dirname(marker), { recursive: true });
+        fs.writeFileSync(marker, new Date().toISOString());
+    }
+    catch { /* non-fatal */ }
+}
 export function autostartStatus() {
     if (process.platform === "darwin") {
         const p = macPlistPath();

package/dist/cli.js

@@ -13,8 +13,9 @@ import { CLI_VERSION } from "./version.js";
 import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocked, } from "./license.js";
 import { checkForUpdate } from "./update-check.js";
 import { ensureMcpHttpServer, mcpHttpStatus } from "./mcp-supervisor.js";
-import { installAutostart, installAutostartIfNeeded, uninstallAutostart, autostartStatus } from "./autostart.js";
+import { installAutostart, installAutostartIfNeeded, uninstallAutostart, autostartStatus, migrateClaudeUnpinIfNeeded } from "./autostart.js";
 import { runServe } from "./serve.js";
+import { runDoctor } from "./doctor.js";
 import { isTraceEnabled } from "./trace.js";
 const program = new Command();
 program
@@ -37,9 +38,17 @@ if (isTraceEnabled()) {
 // workspace was already configured (marker: .vexp/manifest.json).
 const AUTOSTART_SKIP = new Set([
     "setup", "daemon-cmd", "activate", "deactivate", "license", "version",
-    "serve", "autostart", "use",
+    "serve", "autostart", "use", "doctor",
 ]);
 program.hook("preAction", async (_thisCmd, actionCmd) => {
+    // One-shot config migration for the multi-session fix — de-pins a legacy
+    // VEXP_WORKSPACE from ~/.claude.json on the first `vexp` command after upgrade.
+    // Marker-gated (near-free after first run) and independent of workspace/daemon,
+    // so it also runs for AUTOSTART_SKIP commands and VEXP_NO_AUTOSTART users.
+    try {
+        migrateClaudeUnpinIfNeeded();
+    }
+    catch { /* non-fatal */ }
     if (process.env.VEXP_NO_AUTOSTART === "1")
         return;
     if (AUTOSTART_SKIP.has(actionCmd.name()))
@@ -340,8 +349,9 @@ program
     const args = ["capsule", query, "--max-tokens", opts.maxTokens];
     if (opts.repos)
         args.push("--repos", opts.repos);
-    if (opts.format === "json")
-        args.push("--json");
+    // The Rust binary's clap arg is `--format <json|markdown>` (there is no
+    // `--json` flag). Map the CLI's "text"/"json" to the binary's vocabulary.
+    args.push("--format", opts.format === "json" ? "json" : "markdown");
     runBinary(binaryPath, args);
 });
 program
@@ -464,7 +474,7 @@ program
 });
 program
     .command("daemon-cmd <action>")
-    .description("Manage the vexp daemon (start, stop, status, logs)")
+    .description("Manage the vexp daemon (start, stop, restart, status, logs)")
     .option("--follow", "Follow log output (with 'logs' action)")
     .action(async (action, opts) => {
     const binaryPath = ensureBinary();
@@ -473,6 +483,12 @@ program
         args.push("--follow");
     runBinary(binaryPath, args);
 });
+program
+    .command("doctor")
+    .description("Diagnose vexp MCP/daemon state — workspace drift, stale daemons, Codex transport, license (no daemon needed)")
+    .action(async () => {
+    await runDoctor();
+});
 program
     .command("setup [dir]")
     .description("Complete one-command setup: index, detect agents, configure MCP")

package/dist/doctor.js

@@ -0,0 +1,220 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as net from "net";
+import chalk from "chalk";
+// `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),
+// expired rolling jwt, and a stuck HTTP supervisor. Read-only.
+const OK = chalk.green("OK");
+const WARN = chalk.yellow("WARN");
+const BAD = chalk.red("FAIL");
+function vexpHome() {
+    const h = process.env.VEXP_HOME;
+    if (h && path.isAbsolute(h))
+        return h;
+    return os.homedir();
+}
+/** Walk up for the nearest INITIALIZED .vexp (manifest/index), then bare .vexp,
+ *  then .git — mirrors discover_workspace_root / discoverWorkspaceRoot. */
+function discoverWorkspaceRoot(start) {
+    for (const test of [
+        (d) => fs.existsSync(path.join(d, ".vexp", "manifest.json")) || fs.existsSync(path.join(d, ".vexp", "index.db")),
+        (d) => fs.existsSync(path.join(d, ".vexp")),
+        (d) => fs.existsSync(path.join(d, ".git")),
+    ]) {
+        let cur = start;
+        while (true) {
+            if (test(cur))
+                return cur;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                break;
+            cur = parent;
+        }
+    }
+    return start;
+}
+function resolveWorkspace() {
+    if (process.env.VEXP_WORKSPACE)
+        return { root: process.env.VEXP_WORKSPACE, source: "VEXP_WORKSPACE" };
+    if (process.env.CLAUDE_PROJECT_DIR)
+        return { root: process.env.CLAUDE_PROJECT_DIR, source: "CLAUDE_PROJECT_DIR" };
+    return { root: discoverWorkspaceRoot(process.cwd()), source: "cwd-discovery" };
+}
+function socketForWorkspace(root) {
+    if (process.platform === "win32") {
+        // FNV-1a, lowercase — mirrors get_socket_path / fnvHash.
+        let hash = BigInt("0xcbf29ce484222325");
+        const prime = BigInt("0x100000001b3");
+        const mask = BigInt("0xffffffffffffffff");
+        for (const b of Buffer.from(root.toLowerCase(), "utf-8")) {
+            hash ^= BigInt(b);
+            hash = (hash * prime) & mask;
+        }
+        return `\\\\.\\pipe\\vexp-${hash.toString(16).padStart(16, "0").slice(0, 8)}`;
+    }
+    return path.join(root, ".vexp", "daemon.sock");
+}
+function reachable(sock, timeoutMs = 600) {
+    return new Promise((resolve) => {
+        const c = process.platform === "win32" ? net.createConnection(sock) : net.createConnection({ path: sock });
+        const t = setTimeout(() => { c.destroy(); resolve(false); }, timeoutMs);
+        c.on("connect", () => { clearTimeout(t); c.destroy(); resolve(true); });
+        c.on("error", () => { clearTimeout(t); resolve(false); });
+    });
+}
+/** Decode a JWT's `exp` (seconds) without verifying the signature. */
+function jwtExp(file) {
+    try {
+        const tok = fs.readFileSync(file, "utf-8").trim();
+        const payload = JSON.parse(Buffer.from(tok.split(".")[1], "base64").toString("utf-8"));
+        return typeof payload.exp === "number" ? payload.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runDoctor() {
+    const home = vexpHome();
+    let warns = 0;
+    let fails = 0;
+    const line = (status, msg) => {
+        if (status === WARN)
+            warns++;
+        if (status === BAD)
+            fails++;
+        console.log(`  [${status}] ${msg}`);
+    };
+    console.log(chalk.bold("\nvexp doctor — MCP / daemon diagnostics\n"));
+    // 1) Workspace resolution for the current directory.
+    console.log(chalk.bold("Workspace targeting"));
+    const ws = resolveWorkspace();
+    console.log(`  cwd: ${process.cwd()}`);
+    line(OK, `resolves to: ${ws.root}  (via ${ws.source})`);
+    const sock = socketForWorkspace(ws.root);
+    const live = await reachable(sock);
+    line(live ? OK : WARN, `daemon socket ${live ? "reachable" : "NOT reachable"}: ${sock}`);
+    if (!live)
+        console.log(chalk.dim(`        → run: vexp daemon-cmd start   (or 'vexp daemon-cmd restart')`));
+    // 2) Daemon registry (~/.vexp/daemons.json) — stale entries are a drift source.
+    console.log(chalk.bold("\nDaemon registry (~/.vexp/daemons.json)"));
+    const regPath = path.join(home, ".vexp", "daemons.json");
+    let registry = {};
+    try {
+        registry = JSON.parse(fs.readFileSync(regPath, "utf-8"));
+    }
+    catch { /* absent */ }
+    const entries = Object.entries(registry);
+    if (entries.length === 0) {
+        line(OK, "no registered daemons (empty/absent registry)");
+    }
+    else {
+        for (const [root, s] of entries) {
+            const stale = process.platform === "win32" ? false : !(() => { try {
+                return fs.statSync(s).isSocket();
+            }
+            catch {
+                return false;
+            } })();
+            line(stale ? WARN : OK, `${root} → ${s}${stale ? "  (STALE: socket file gone)" : ""}`);
+        }
+        const inReg = entries.some(([r]) => r.toLowerCase() === ws.root.toLowerCase());
+        if (!inReg)
+            line(WARN, `current workspace (${ws.root}) is NOT registered — a child here could mis-route`);
+    }
+    // 3) License (fresh.jwt rolling token vs license.jwt).
+    console.log(chalk.bold("\nLicense tokens (~/.vexp)"));
+    const now = Math.floor(Date.now() / 1000);
+    for (const name of ["fresh.jwt", "license.jwt"]) {
+        const p = path.join(home, ".vexp", name);
+        if (!fs.existsSync(p)) {
+            line(name === "license.jwt" ? WARN : OK, `${name}: absent`);
+            continue;
+        }
+        const exp = jwtExp(p);
+        if (exp == null) {
+            line(WARN, `${name}: present but unparseable`);
+            continue;
+        }
+        const days = Math.round((exp - now) / 86400);
+        if (exp < now) {
+            line(name === "fresh.jwt" ? OK : WARN, `${name}: expired ${-days}d ago${name === "fresh.jwt" ? " (benign — rolling token, falls back to license.jwt)" : ""}`);
+        }
+        else {
+            line(OK, `${name}: valid, ~${days}d remaining`);
+        }
+    }
+    // 4) Codex MCP transport stanza.
+    console.log(chalk.bold("\nCodex (~/.codex/config.toml)"));
+    const codexPath = path.join(os.homedir(), ".codex", "config.toml");
+    if (!fs.existsSync(codexPath)) {
+        line(OK, "no ~/.codex/config.toml (Codex not configured)");
+    }
+    else {
+        const toml = fs.readFileSync(codexPath, "utf-8");
+        const m = toml.match(/\n?\[mcp_servers\.vexp\][\s\S]*?(?=\n\[[A-Za-z_]|$)/);
+        const section = m ? m[0] : "";
+        if (!section)
+            line(OK, "no [mcp_servers.vexp] stanza");
+        else {
+            const hasUrl = /^\s*url\s*=/m.test(section);
+            const hasCmd = /^\s*command\s*=/m.test(section);
+            if (hasUrl && hasCmd)
+                line(BAD, "stanza has BOTH 'url' and 'command' → 'url is not supported for stdio'. Re-run setup to rewrite cleanly.");
+            else if (hasUrl)
+                line(OK, "transport: http (url)");
+            else if (hasCmd) {
+                const wsm = section.match(/VEXP_WORKSPACE\s*=\s*['"]([^'"]+)['"]/);
+                line(OK, `transport: stdio (command)${wsm ? `, VEXP_WORKSPACE=${wsm[1]}` : ""}`);
+            }
+            else
+                line(WARN, "stanza present but neither url nor command found");
+        }
+    }
+    // 5) Claude Code entry (should be UNPINNED after the multi-session fix).
+    console.log(chalk.bold("\nClaude Code (~/.claude.json)"));
+    const claudePath = path.join(os.homedir(), ".claude.json");
+    try {
+        const cfg = JSON.parse(fs.readFileSync(claudePath, "utf-8"));
+        const v = cfg?.mcpServers?.vexp;
+        if (!v)
+            line(OK, "no user-scope vexp entry");
+        else if (v.env?.VEXP_WORKSPACE)
+            line(WARN, `vexp entry still pins VEXP_WORKSPACE=${v.env.VEXP_WORKSPACE} → run 'vexp setup' to de-pin (multi-session fix)`);
+        else
+            line(OK, "vexp entry present, no VEXP_WORKSPACE pin (per-session targeting OK)");
+    }
+    catch {
+        line(OK, "no ~/.claude.json");
+    }
+    // 6) HTTP MCP supervisor.
+    console.log(chalk.bold("\nHTTP MCP supervisor (~/.vexp/mcp.pid)"));
+    try {
+        const rec = JSON.parse(fs.readFileSync(path.join(home, ".vexp", "mcp.pid"), "utf-8"));
+        line(isAlive(rec.pid) ? OK : WARN, `pid ${rec.pid} on :${rec.port} — ${isAlive(rec.pid) ? "alive" : "DEAD (stale pid file)"}`);
+    }
+    catch {
+        line(OK, "not running (no mcp.pid)");
+    }
+    // Summary.
+    console.log(chalk.bold("\nSummary"));
+    if (fails === 0 && warns === 0)
+        console.log(`  ${OK} no issues detected`);
+    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."));
+    }
+    console.log("");
+}