vexp-cli 3.2.2 → 3.2.5

package/dist/agent-config.js

@@ -11,6 +11,7 @@ import * as path from "path";
 import * as os from "os";
 import { spawnSync } from "child_process";
 import * as crypto from "crypto";
+import { canonicalWorkspaceRoot } from "./socket-path.js";
 import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSearchHookScript, vexpHintHookCmdScript, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin, vexpOpencodeCompressPlugin, bakeEditHintHook, bakeReadHintHook, bakeBashCapHook } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -39,7 +40,9 @@ const CANONICAL_VEXP_TOML_SECTION_RE = /\n?\[mcp_servers\.vexp(?:\.[a-z_]+)?\][\
  * MUST stay in lockstep with that function.
  */
 function workspaceHash(workspaceRoot) {
-    const input = workspaceRoot.toLowerCase();
+    // The route hash must name the row the daemon registers: its canonical
+    // root, which on a mapped drive is the share, not the drive letter.
+    const input = canonicalWorkspaceRoot(workspaceRoot).toLowerCase();
     let hash = BigInt("0xcbf29ce484222325");
     const prime = BigInt("0x100000001b3");
     const mask = BigInt("0xffffffffffffffff");
@@ -1983,6 +1986,22 @@ function extractCodexVexpSection(content) {
     const m = content.match(CANONICAL_VEXP_TOML_SECTION_RE);
     return m ? m.join("\n") : "";
 }
+/** True when ~/.codex/config.toml carries a hand-written [mcp_servers.vexp]
+ *  section — one `vexp use` and `vexp setup` will never rewrite, so a caller
+ *  that promised to repoint Codex can say it did not. */
+export function codexGlobalSectionIsUserManaged() {
+    const home = os.homedir();
+    if (!home)
+        return false;
+    let content = "";
+    try {
+        content = fs.readFileSync(path.join(home, ".codex", "config.toml"), "utf-8");
+    }
+    catch {
+        return false;
+    }
+    return isUserManagedCodexSection(extractCodexVexpSection(content));
+}
 /** True when the existing [mcp_servers.vexp] section was written by the user
  *  (not by vexp) and must NOT be overwritten. */
 function isUserManagedCodexSection(section) {

package/dist/cli.js

@@ -18,6 +18,8 @@ import { isWsl, windsurfWslBridgeNote } from "./agent-config.js";
 import { runServe } from "./serve.js";
 import { runDoctor } from "./doctor.js";
 import { socketPathFor } from "./socket-path.js";
+import { isStateHome } from "./state-home.js";
+import { forgetRegistryRows, removeIndexArtifacts } from "./forget.js";
 import { mutableOutput, askSecretOn } from "./secret-prompt.js";
 import { isTraceEnabled } from "./trace.js";
 import { resolveParentWorkspace, listWorkspaceRepos, addRepoToWorkspace, } from "./workspace-repos.js";
@@ -48,6 +50,9 @@ const AUTOSTART_SKIP = new Set([
     // followed by `daemons` bring the stopped daemon straight back
     // (3.1 e2e, 2026-08).
     "daemons", "stop",
+    // `vexp forget` exists to make a workspace stay down; booting one first
+    // would be the joke `stop` used to play.
+    "forget", "unregister",
 ]);
 program.hook("preAction", async (_thisCmd, actionCmd) => {
     // One-shot config migration for the multi-session fix — de-pins a legacy
@@ -545,10 +550,62 @@ program
         console.error(`No such directory: ${target}`);
         process.exit(1);
     }
+    // A stop is not a good-bye: while `vexp serve` runs, every registered
+    // workspace that still has a manifest is brought back within a minute,
+    // and a user who wanted it gone read that as vexp ignoring him (field
+    // report, 2026-09-19). Say which command means gone. Printed before the
+    // stop because runBinary exits the process with the child.
+    if (fs.existsSync(path.join(target, ".vexp", "manifest.json"))) {
+        console.log(chalk.dim(`  (a login supervisor restarts registered workspaces within a minute — to unregister this one for good: vexp forget "${target}")`));
+    }
     // daemon-cmd stop resolves the daemon from its cwd, so run it from the
     // target workspace — this is what makes `vexp stop <workspace>` global.
     runBinary(binaryPath, ["daemon-cmd", "stop"], { cwd: target });
 });
+program
+    .command("forget [workspace]")
+    .alias("unregister")
+    .description("Unregister a workspace for good: stop its daemon, drop it from ~/.vexp/daemons.json and delete its index files, so no launcher brings it back (default: current directory). Safe on the home directory: only index files go — config, licence and registry stay")
+    .option("--purge", "Also delete the whole .vexp/ directory, config included (refused for the home directory)")
+    .action(async (workspace, opts) => {
+    const target = path.resolve(workspace ?? process.cwd());
+    if (!fs.existsSync(target)) {
+        console.error(`No such directory: ${target}`);
+        process.exit(1);
+    }
+    const home = isStateHome(target);
+    if (opts.purge && home) {
+        console.error(chalk.red(`${target} is your home directory: .vexp there is vexp's state dir (config, licence, daemon registry). --purge is refused; without it only the index files go.`));
+        process.exit(1);
+    }
+    const binaryPath = ensureBinary();
+    // 1. The daemon. `daemon-cmd stop` resolves it from its cwd.
+    const stop = spawnSync(binaryPath, ["daemon-cmd", "stop"], {
+        cwd: target,
+        encoding: "utf-8",
+        env: binaryEnv(binaryPath),
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stopSaid = `${stop.stdout ?? ""}${stop.stderr ?? ""}`.trim().split(/\r?\n/)[0] ?? "";
+    console.log(`  daemon: ${stopSaid || (stop.error ? stop.error.message : "stopped")}`);
+    // 2. The registry — this row and any connected repo routed to its socket.
+    const dropped = forgetRegistryRows(target, socketPathFor(target));
+    console.log(`  registry: ${dropped.length ? `dropped ${dropped.join(", ")}` : "no row for this workspace"}`);
+    // 3. The files that would bring it back. `--purge` takes config too.
+    const vexpDir = path.join(target, ".vexp");
+    if (opts.purge) {
+        fs.rmSync(vexpDir, { recursive: true, force: true });
+        console.log(`  files: removed ${vexpDir}`);
+    }
+    else {
+        const removed = removeIndexArtifacts(vexpDir);
+        console.log(`  files: ${removed.length ? `removed ${removed.join(", ")}` : "no index files"}${home ? "  (home directory: config, licence and registry untouched)" : ""}`);
+    }
+    console.log(chalk.green(`✓ ${target} forgotten`));
+    if (home) {
+        console.log(chalk.dim("  Nothing starts a daemon on the home directory any more: every launcher refuses it (VEXP_ALLOW_HOME_WORKSPACE=1 overrides)."));
+    }
+});
 program
     .command("shield <action>")
     .description("PII/secret shield: 'scan' reports what comments and string literals would hand to any AI agent (free, read-only, local)")
@@ -1255,7 +1312,16 @@ program
     const binaryPath = ensureBinary();
     const mcpServerPath = getMcpServerPath();
     // Import lazily so configureCodexGlobal's side effects (TOML rewrite + legacy cleanup) only fire here.
-    const { configureSelectedAgents } = await import("./agent-config.js");
+    const { configureSelectedAgents, codexGlobalSectionIsUserManaged } = await import("./agent-config.js");
+    // A hand-written [mcp_servers.vexp] is never rewritten (no-clobber), and
+    // this command used to print its success line anyway — the user then
+    // "repointed" Codex and watched it launch from the old cwd (field
+    // report, 2026-09-19). Say what did not happen and how to do it by hand.
+    if (codexGlobalSectionIsUserManaged()) {
+        console.error(chalk.yellow(`~/.codex/config.toml has a hand-written [mcp_servers.vexp] section, and vexp never rewrites one: Codex keeps launching it exactly as written, so nothing changed.`));
+        console.error(chalk.dim(`  Point it yourself — under [mcp_servers.vexp] add cwd = ${JSON.stringify(resolved)}, and under [mcp_servers.vexp.env] add VEXP_WORKSPACE = ${JSON.stringify(resolved)} — or delete the section and run 'vexp use' again.`));
+        process.exit(1);
+    }
     const version = (await getInstalledVersion()) ?? CLI_VERSION;
     // "Codex" is a no-op file-wise in non-detect mode but the shared flow
     // also writes codex global config via configureCodexGlobal — pass an

package/dist/doctor.js

@@ -10,6 +10,8 @@ import { resolveParentWorkspace, listWorkspaceRepos } from "./workspace-repos.js
 import { CLI_VERSION } from "./version.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";
 // `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),
@@ -17,12 +19,6 @@ import { slowMountNotice } from "./slow-mount.js";
 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) {
@@ -297,7 +293,7 @@ export function vsCodeMcpVerdict(cfg, wsRoot, exists = (p) => fs.existsSync(p))
     if (script && !exists(script))
         return { level: WARN, message: `.vscode/mcp.json vexp server bundle is missing: ${script} (an editor upgrade removed the old extension folder?) — re-run 'vexp setup'` };
     const pinned = typeof vexp.env?.VEXP_WORKSPACE === "string" ? vexp.env.VEXP_WORKSPACE : undefined;
-    if (pinned && path.resolve(pinned).toLowerCase() !== path.resolve(wsRoot).toLowerCase()) {
+    if (pinned && !samePath(pinned, wsRoot)) {
         return { level: WARN, message: `.vscode/mcp.json vexp server is pinned to ${pinned}, but this workspace is ${wsRoot} — re-run 'vexp setup' here` };
     }
     return { level: OK, message: `.vscode/mcp.json vexp server: ${command} ${script ?? args.join(" ")}` };
@@ -319,8 +315,9 @@ export function codexHookSpawnSpec(cmdLine, platform = process.platform, comspec
     return { file: "sh", args: ["-c", cmdLine], windowsVerbatimArguments: false };
 }
 function samePath(a, b) {
-    // The daemon registry lower-cases Windows roots; compare accordingly.
-    return path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase();
+    // The daemon registry lower-cases Windows roots and spells a mapped drive
+    // as its share; compare accordingly.
+    return canonicalWorkspaceRoot(path.resolve(a)).toLowerCase() === canonicalWorkspaceRoot(path.resolve(b)).toLowerCase();
 }
 /**
  * A connected repo of a multi-repo workspace has no daemon of its own: the
@@ -638,7 +635,7 @@ async function doctorChecks(onWorkspace) {
     // disagrees with this directory's natural target.
     if (ws.source === "VEXP_WORKSPACE") {
         const discovered = discoverWorkspaceRoot(process.cwd());
-        if (discovered.toLowerCase() !== ws.root.toLowerCase()) {
+        if (!samePath(discovered, ws.root)) {
             line(WARN, `global VEXP_WORKSPACE env var pins this session to ${ws.root}, but this directory's natural target is ${discovered} → agents here get [] / wrong-repo results. Unset the VEXP_WORKSPACE OS/shell env var for per-session targeting.`);
         }
     }
@@ -773,8 +770,15 @@ async function doctorChecks(onWorkspace) {
                 return false;
             } })();
             line(stale ? WARN : OK, `${root} → ${s}${stale ? "  (STALE: socket file gone)" : ""}`);
+            // A row for the home directory is never right: its .vexp is vexp's
+            // state dir, and a daemon there indexes everything under home. Every
+            // launcher now refuses it; the row and the daemon behind it are the
+            // residue (field report, 2026-09-19).
+            if (isStateHome(root)) {
+                line(BAD, `${root} is your home directory — never a workspace (its .vexp is vexp's state dir). A daemon here indexes everything under home. Run: vexp forget "${root}"   (stops it, drops this row, deletes only its index files — licence, config and registry stay)`);
+            }
         }
-        const inReg = entries.some(([r]) => r.toLowerCase() === ws.root.toLowerCase());
+        const inReg = entries.some(([r]) => samePath(r, ws.root));
         if (!inReg)
             line(WARN, `current workspace (${ws.root}) is NOT registered — a child here could mis-route`);
         // Multi-daemon + global pin: catches the case the section-1 check misses
@@ -837,7 +841,11 @@ async function doctorChecks(onWorkspace) {
             continue;
         }
         const toml = fs.readFileSync(file, "utf-8");
-        const m = toml.match(/\n?\[mcp_servers\.vexp\][\s\S]*?(?=\n\[[A-Za-z_]|$)/);
+        // The section INCLUDES its own subsections ([mcp_servers.vexp.env],
+        // .http_headers): the pin lives in .env, and a lookahead that stopped at
+        // any '[' hid it, so doctor reported "stdio (command)" for a stanza it
+        // could not tell apart from an unpinned one.
+        const m = toml.match(/\n?\[mcp_servers\.vexp\][\s\S]*?(?=\n\[(?!mcp_servers\.vexp\.)|$)/);
         const section = m ? m[0] : "";
         if (!section) {
             line(OK, `${label}: no [mcp_servers.vexp] stanza`);
@@ -852,7 +860,9 @@ async function doctorChecks(onWorkspace) {
             line(OK, `${label}: transport http (url)`);
         else if (hasCmd) {
             const wsm = section.match(/VEXP_WORKSPACE\s*=\s*['"]([^'"]+)['"]/);
-            line(OK, `${label}: transport stdio (command)${wsm ? `, VEXP_WORKSPACE=${wsm[1]}` : ""}`);
+            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"}`);
         }
         else
             line(WARN, `${label}: stanza present but neither url nor command found`);

package/dist/forget.js

@@ -0,0 +1,122 @@
+import * as fs from "fs";
+import * as path from "path";
+import { vexpHome } from "./state-home.js";
+import { canonicalWorkspaceRoot } from "./socket-path.js";
+/**
+ * `vexp forget`: the pieces that make a workspace stay forgotten.
+ *
+ * Stopping a daemon is not enough on a machine running `vexp serve`: the
+ * supervisor resurrects every registry row whose manifest still exists,
+ * within a minute. Removing the registry row by hand is not enough either:
+ * a daemon that is still alive is written back on the next health tick, and
+ * the daemon re-registers itself on every start. What keeps a workspace
+ * down is all three at once — daemon stopped, row gone, manifest and index
+ * gone — and that is what `vexp forget` does (field report, 2026-09-19: a
+ * user did each of the three by hand, in turn, four times).
+ */
+/** Everything a daemon or an index run leaves in `<workspace>/.vexp`.
+ *  Config is absent on purpose (`vexp.toml`, `workspace.json`,
+ *  `parent_workspace.json`, `.gitattributes`, `.gitignore`): forgetting a
+ *  workspace removes what brings its daemon back, not what the user wrote.
+ *  At the home directory the same `.vexp` is vexp's state dir, and this list
+ *  is exactly what may go there — `config.toml`, the licence tokens,
+ *  `daemons.json`, `mcp.pid`/`mcp.token`, `gpu-unusable`, models and plugins
+ *  are not on it. Keep in sync with vexp-core hook_installer VEXP_IGNORE_ENTRIES. */
+export const INDEX_ARTIFACTS = [
+    "index.db",
+    "index.db-wal",
+    "index.db-shm",
+    "index.lock",
+    "manifest.json",
+    "coverage.json",
+    "daemon.pid",
+    "daemon.pipe",
+    "daemon.sock",
+    "healthy",
+    "start-blocked",
+    "daemon-job-warning",
+    "mcp.port",
+    "daily-limit.json",
+];
+/** Rotating logs and per-session markers, matched by prefix. */
+export const INDEX_ARTIFACT_PREFIXES = [
+    "daemon.log",
+    "vexp.log",
+    "stop-gate-",
+    "idle-gate-",
+    "task-",
+];
+/** Per-session scratch directories the hooks write. */
+export const INDEX_ARTIFACT_DIRS = ["edit-hints", "search-hints", "read-hints"];
+/** True when an entry of `.vexp/` is index residue rather than config. */
+export function isIndexArtifact(name, isDir) {
+    if (isDir)
+        return INDEX_ARTIFACT_DIRS.includes(name);
+    if (INDEX_ARTIFACTS.includes(name))
+        return true;
+    return INDEX_ARTIFACT_PREFIXES.some((p) => name === p || name.startsWith(p));
+}
+/** Delete the index artifacts in `vexpDir`, nothing else. Returns what went. */
+export function removeIndexArtifacts(vexpDir) {
+    const removed = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(vexpDir, { withFileTypes: true });
+    }
+    catch {
+        return removed;
+    }
+    for (const e of entries) {
+        if (!isIndexArtifact(e.name, e.isDirectory()))
+            continue;
+        try {
+            fs.rmSync(path.join(vexpDir, e.name), { recursive: true, force: true });
+            removed.push(e.name);
+        }
+        catch {
+            /* a file the daemon still holds on Windows; reported by omission */
+        }
+    }
+    return removed;
+}
+function registryFile() {
+    return path.join(vexpHome(), ".vexp", "daemons.json");
+}
+/** The registry without every row that names `target` or routes to its
+ *  socket (a connected repo mapped to this workspace's socket is dangling
+ *  once the workspace is gone). Windows keys are lowercased by the daemon. */
+export function registryRowsWithout(reg, target, targetSocket) {
+    // A mapped drive is registered as its share; canonicalize before comparing.
+    const canon = (p) => (process.platform === "win32" ? canonicalWorkspaceRoot(path.resolve(p)).toLowerCase() : path.resolve(p));
+    const t = canon(target);
+    const kept = {};
+    const dropped = [];
+    for (const [ws, sock] of Object.entries(reg)) {
+        if (canon(ws) === t || sock === targetSocket)
+            dropped.push(ws);
+        else
+            kept[ws] = sock;
+    }
+    return { kept, dropped };
+}
+/** Apply `registryRowsWithout` to ~/.vexp/daemons.json. */
+export function forgetRegistryRows(target, targetSocket) {
+    const p = registryFile();
+    let reg = {};
+    try {
+        reg = JSON.parse(fs.readFileSync(p, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+    const { kept, dropped } = registryRowsWithout(reg, target, targetSocket);
+    if (dropped.length === 0)
+        return [];
+    try {
+        fs.writeFileSync(p, JSON.stringify(kept, null, 2), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    return dropped;
+}

package/dist/serve.js

@@ -5,6 +5,8 @@ import * as path from "path";
 import { spawn } from "child_process";
 import { getBinaryPath, binaryEnv } from "./binary.js";
 import { ensureMcpHttpServer } from "./mcp-supervisor.js";
+import { isStateHome } from "./state-home.js";
+import { canonicalWorkspaceRoot } from "./socket-path.js";
 const HEALTH_INTERVAL_MS = 60_000;
 const DEFAULT_MCP_PORT = 7821;
 function registryPath() {
@@ -187,6 +189,22 @@ export function isLinkedWorktree(ws) {
         return false;
     }
 }
+/** Why a registry row must never be spawned by this supervisor, or null.
+ *  The home directory is refused by the daemon itself (vexp-core
+ *  forbidden_workspace_reason); vetoing it here too spares a spawn per
+ *  minute that would only write "daemon did not start" to ~/.vexp
+ *  (field report, 2026-09-19: the supervisor was one of the launchers
+ *  that kept bringing the home daemon back). */
+export function resurrectionVeto(ws) {
+    if (isStateHome(ws)) {
+        return "the home directory is vexp's state dir, never a workspace — `vexp forget` removes this row";
+    }
+    if (!fs.existsSync(path.join(ws, ".vexp", "manifest.json")))
+        return "no manifest";
+    if (isLinkedWorktree(ws))
+        return "linked git worktree — on-demand only, never resurrected";
+    return null;
+}
 export function resurrectionPlan(reg) {
     const bySock = new Map();
     for (const [ws, sock] of Object.entries(reg)) {
@@ -224,19 +242,15 @@ async function resurrectAll() {
     // rewrite here would otherwise immortalize the phantom twin.
     const seenKeys = new Set();
     for (const [ws, sock] of Object.entries(reg)) {
-        const canonical = process.platform === "win32" ? ws.toLowerCase() : ws;
+        const canonical = process.platform === "win32" ? canonicalWorkspaceRoot(ws).toLowerCase() : ws;
         if (seenKeys.has(canonical)) {
             appendLog(`registry prune: ${ws} (case-variant duplicate)`);
             continue;
         }
         seenKeys.add(canonical);
-        const manifest = path.join(ws, ".vexp", "manifest.json");
-        if (!fs.existsSync(manifest)) {
-            appendLog(`registry prune: ${ws} (no manifest)`);
-            continue;
-        }
-        if (isLinkedWorktree(ws)) {
-            appendLog(`registry prune: ${ws} (linked git worktree — on-demand only, never resurrected)`);
+        const veto = resurrectionVeto(ws);
+        if (veto) {
+            appendLog(`registry prune: ${ws} (${veto})`);
             continue;
         }
         pruned[ws] = sock;
@@ -286,7 +300,7 @@ async function resurrectAll() {
  * report what it could not find, never delete what it does not own.
  */
 export async function survivingRegistryRows(before, resurrected, alive, log = () => { }) {
-    const canonical = (ws) => (process.platform === "win32" ? ws.toLowerCase() : ws);
+    const canonical = (ws) => (process.platform === "win32" ? canonicalWorkspaceRoot(ws).toLowerCase() : ws);
     const out = { ...resurrected };
     const kept = new Set(Object.keys(out).map(canonical));
     for (const [ws, sock] of Object.entries(before)) {

package/dist/socket-path.js

@@ -1,3 +1,4 @@
+import * as fs from "fs";
 import * as path from "path";
 /**
  * Where the daemon listens for a given workspace root.
@@ -18,7 +19,7 @@ import * as path from "path";
  */
 export function socketPathFor(workspaceRoot) {
     if (process.platform === "win32") {
-        return `\\\\.\\pipe\\vexp-${fnvHash(workspaceRoot.toLowerCase()).slice(0, 8)}`;
+        return `\\\\.\\pipe\\vexp-${fnvHash(canonicalWorkspaceRoot(workspaceRoot).toLowerCase()).slice(0, 8)}`;
     }
     const candidate = path.join(workspaceRoot, ".vexp", "daemon.sock");
     // macOS/BSD sockaddr_un caps the path at 104 bytes; vexp-core falls back to
@@ -27,6 +28,29 @@ export function socketPathFor(workspaceRoot) {
         return candidate;
     return `/tmp/vexp-${fnvHash(workspaceRoot).slice(0, 12)}.sock`;
 }
+/**
+ * The workspace root as the daemon spells it. vexp-core canonicalizes the
+ * root before deriving the pipe name and the daemons.json key, and on
+ * Windows a folder on a mapped drive canonicalizes to its share:
+ * `X:\proj` becomes `\\server\share\proj`. Every hash computed from the
+ * drive-letter spelling named a pipe the daemon never bound, so `vexp
+ * status` on a share reported the daemon as down and started a second one,
+ * and the MCP bridge could not reach it (field report, Samba share from
+ * Windows 11, 2026-09-20). Node's native realpath resolves the same way; a
+ * local path only gets its case corrected, which the lowercase hash never
+ * saw. Falls back to the spelling given when the folder cannot be resolved
+ * (a stale registry row, a path that is not there yet).
+ */
+export function canonicalWorkspaceRoot(root) {
+    if (process.platform !== "win32")
+        return root;
+    try {
+        return fs.realpathSync.native(root);
+    }
+    catch {
+        return root;
+    }
+}
 /** Longest `<root>/.vexp/daemon.sock` vexp binds in place; past it the socket lives in /tmp. */
 export const UNIX_SOCKET_PATH_LIMIT = 100;
 /**

package/dist/state-home.js

@@ -0,0 +1,23 @@
+import * as os from "os";
+import * as path from "path";
+/** The directory vexp keeps its own state in (`<here>/.vexp`): VEXP_HOME when
+ *  set to an absolute path, else the OS home. */
+export function vexpHome() {
+    const h = process.env.VEXP_HOME;
+    if (h && path.isAbsolute(h))
+        return h;
+    return os.homedir();
+}
+/** True when `dir` IS the home / VEXP_HOME directory. Its `.vexp` is vexp's
+ *  state dir (config, licence, daemons.json), never a workspace: a daemon
+ *  there indexes everything under home, and deleting the directory to be rid
+ *  of it takes the licence and the registry along (field report, 2026-09-19).
+ *  Lockstep with vexp-core utils::forbidden_workspace_reason and
+ *  vexp-mcp isVexpStateHome; VEXP_ALLOW_HOME_WORKSPACE=1 lifts it everywhere. */
+export function isStateHome(dir) {
+    if (process.env.VEXP_ALLOW_HOME_WORKSPACE === "1")
+        return false;
+    const a = path.resolve(dir);
+    const b = path.resolve(vexpHome());
+    return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}