vexp-cli 3.0.1 → 3.1.1

package/dist/cli.js

@@ -14,6 +14,7 @@ import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocke
 import { checkForUpdate } from "./update-check.js";
 import { ensureMcpHttpServer, mcpHttpStatus } from "./mcp-supervisor.js";
 import { installAutostart, uninstallAutostart, autostartStatus, migrateClaudeUnpinIfNeeded } from "./autostart.js";
+import { isWsl, windsurfWslBridgeNote } from "./agent-config.js";
 import { runServe } from "./serve.js";
 import { runDoctor } from "./doctor.js";
 import { socketPathFor } from "./socket-path.js";
@@ -42,6 +43,11 @@ if (isTraceEnabled()) {
 const AUTOSTART_SKIP = new Set([
     "setup", "daemon-cmd", "activate", "deactivate", "license", "version",
     "serve", "autostart", "use", "doctor",
+    // Lifecycle commands: `vexp daemons` LISTS daemons and `vexp stop` ENDS
+    // one — spawning a daemon for the current directory first made `stop`
+    // followed by `daemons` bring the stopped daemon straight back
+    // (3.1 e2e, 2026-08).
+    "daemons", "stop",
 ]);
 program.hook("preAction", async (_thisCmd, actionCmd) => {
     // One-shot config migration for the multi-session fix — de-pins a legacy
@@ -456,7 +462,7 @@ program
 });
 program
     .command("search <query>")
-    .description("Exhaustive index search: every matching node (code and docs), no top-K. Built for rename sweeps and zero-reference audits")
+    .description("Exhaustive index search: every symbol matching the query (code and docs) plus every line in indexed symbol bodies that references it, no top-K. Built for rename sweeps and zero-reference audits")
     .option("--substring", "Substring match (LIKE) instead of token search — partial identifiers, punctuation")
     .option("--files-only", "Print only the distinct file paths")
     .option("--json", "Machine-readable JSON with a stable shape")
@@ -796,6 +802,16 @@ program
                         console.log(chalk.dim(`    ${mcpFile}`));
                     }
                 }
+                // Windsurf/Devin Desktop on Windows with the project in WSL: Cascade
+                // starts its MCP servers on the Windows side and reads the Windows
+                // profile, which nothing in WSL can write. Hand over the exact entry
+                // instead of letting the user discover the boundary the hard way.
+                if (isWsl() && result.agents.some((a) => a.agent === "Windsurf")) {
+                    console.log("");
+                    for (const l of windsurfWslBridgeNote(workspaceRoot, binaryPath, mcpServerPath).split("\n")) {
+                        console.log(chalk.yellow(`  ${l}`));
+                    }
+                }
                 // Files we refused to touch because they would not parse. This
                 // used to be a stderr line mid-spinner: it scrolled away, and a
                 // skipped settings.json silently cost the whole hook (field
@@ -828,7 +844,15 @@ program
     // the daemon already cold-starts on the first `vexp` invocation, so this is
     // purely a convenience for post-reboot warm-up. Skip entirely when the user
     // opted out via env or when stdin is not a TTY (non-interactive install).
-    if (process.env.VEXP_NO_AUTOSTART_INSTALL === "1") {
+    //
+    // A dry run must not reach this step at all: the prompt was asked even
+    // under --dry-run and answering Yes rewrote the Startup-folder .vbs while
+    // the summary still claimed nothing was written (field report, Peiyuan,
+    // 3.0.1 on Windows). Persistence is a write like any other.
+    if (opts.dryRun) {
+        console.log(chalk.dim("  --dry-run: would ask about login autostart (writes a Startup entry only if you accept)."));
+    }
+    else if (process.env.VEXP_NO_AUTOSTART_INSTALL === "1") {
         // Explicit opt-out — do nothing.
     }
     else if (!process.stdin.isTTY) {
@@ -1108,6 +1132,9 @@ program
     console.log(`  Max nodes: ${limits.maxNodes === 0 ? "unlimited" : limits.maxNodes.toLocaleString()}`);
     console.log(`  Max repos: ${limits.maxRepos === 0 ? "unlimited" : limits.maxRepos}`);
     console.log(`  All tools: ${limits.allTools ? "yes" : "no (7/10)"}`);
+    if (limits.allTools) {
+        console.log(`             (the MCP tool list shows 4 by default to keep the catalog small; every tool stays callable — VEXP_ALL_TOOLS=1 lists them all)`);
+    }
     if (limits.renewsAt) {
         console.log(ltd
             ? `  Renewal:   none — lifetime licence (local token auto-refreshes, ` +
@@ -1749,6 +1776,9 @@ async function executeCommand(label, rl, outCtl) {
                 console.log(`    Max nodes: ${limits.maxNodes === 0 ? "unlimited" : limits.maxNodes.toLocaleString()}`);
                 console.log(`    Max repos: ${limits.maxRepos === 0 ? "unlimited" : limits.maxRepos}`);
                 console.log(`    All tools: ${limits.allTools ? "yes" : "no (7/10)"}`);
+                if (limits.allTools) {
+                    console.log(`               (the MCP tool list shows 4 by default to keep the catalog small; every tool stays callable — VEXP_ALL_TOOLS=1 lists them all)`);
+                }
                 if (limits.renewsAt) {
                     console.log(ltd
                         ? `    Renewal:   none — lifetime licence (token auto-refreshes, valid to ${limits.renewsAt.toLocaleDateString()})`

package/dist/doctor.js

@@ -5,6 +5,9 @@ import * as net from "net";
 import { spawnSync } from "child_process";
 import chalk from "chalk";
 import { socketPathFor } from "./socket-path.js";
+import { parseJsonc, isWsl, windsurfWslBridgeNote, windsurfGlobalMcpPath } from "./agent-config.js";
+import { resolveParentWorkspace, listWorkspaceRepos } from "./workspace-repos.js";
+import { CLI_VERSION } from "./version.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),
@@ -23,7 +26,8 @@ function vexpHome() {
 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")),
+        // Bare .vexp — except home/VEXP_HOME, whose .vexp is vexp's state dir.
+        (d) => fs.existsSync(path.join(d, ".vexp")) && path.resolve(d) !== path.resolve(vexpHome()),
         (d) => fs.existsSync(path.join(d, ".git")),
     ]) {
         let cur = start;
@@ -191,8 +195,159 @@ export function gitHooksVerdict(hooksPath, repoRoot, installedCount) {
             `        the hooks only make that immediate — if you want them and a tool manages this directory (moon, husky, lefthook), add 'vexp index --finalize || true' through ITS config, not the generated file.`,
     };
 }
+/**
+ * The size-skip verdict, from `.vexp/coverage.json` (3.1 shape), as data.
+ *
+ * Files over `max_file_size_kb` are left out of the index by the walk. Until
+ * 3.1 the only trace was an INFO line in the daemon log: doctor, the
+ * `index_status` tool and coverage.json all reported a healthy index while a
+ * tier-4 user was missing five hand-written Dart files — 21% of the bytes of
+ * his lib/ — from every impact, search and pipeline answer (field report,
+ * 2026-08). Raising the cap only moved the cliff, so the cliff is reported
+ * wherever it stands. Null when nothing was skipped for size, or when the
+ * file predates 3.1 and has no skip keys.
+ */
+export function coverageVerdict(cov) {
+    if (!cov || typeof cov !== "object")
+        return null;
+    const c = cov;
+    const oversized = Number(c.skipped_oversized) || 0;
+    if (oversized === 0)
+        return null;
+    const cap = Number(c.max_file_size_kb) || 0;
+    const files = Array.isArray(c.skipped_files) ? c.skipped_files : [];
+    const examples = files
+        .filter((f) => f.reason === "oversized")
+        .slice(0, 5)
+        .map((f) => `${f.path} (${Number(f.size_kb) || 0} KB)`);
+    const more = oversized - examples.length;
+    return {
+        level: WARN,
+        message: `${oversized} file(s) over max_file_size_kb = ${cap} are NOT indexed — their symbols and callers are invisible to impact, search and run_pipeline:\n` +
+            examples.map((e) => `        - ${e}`).join("\n") +
+            (more > 0 ? `\n        … +${more} more (full list: .vexp/coverage.json)` : "") +
+            `\n        raise max_file_size_kb in .vexp/vexp.toml (0 = no cap) to include them, or exclude them on purpose with exclude_patterns — excluded files stop being counted here at the next reindex ('vexp index').`,
+    };
+}
+/**
+ * The `.vscode/mcp.json` verdict for GitHub Copilot, as data.
+ *
+ * A Copilot user who "set up the vexp agent" and sees neither a vexp server in
+ * VS Code nor vexp tools in chat has, in our experience, one of three things:
+ * the file is not where VS Code looks (the folder open in VS Code is not the
+ * one that was set up), the server entry cannot start (a bare `node` that the
+ * GUI-launched editor cannot find on its PATH, or a bundle path an extension
+ * upgrade removed), or Chat is not in Agent mode — the only mode that offers
+ * MCP tools. doctor can prove the first two; it can only say the third.
+ */
+export function vsCodeMcpVerdict(cfg, wsRoot, exists = (p) => fs.existsSync(p)) {
+    if (!cfg || typeof cfg !== "object")
+        return { level: WARN, message: ".vscode/mcp.json is present but not valid JSON — VS Code will ignore every server in it; fix the syntax and re-run 'vexp setup'" };
+    const servers = cfg.servers;
+    const vexp = servers?.vexp;
+    if (!vexp)
+        return { level: WARN, message: ".vscode/mcp.json has no 'vexp' server — run: vexp setup --agents \"GitHub Copilot\"" };
+    const command = typeof vexp.command === "string" ? vexp.command : "";
+    const args = Array.isArray(vexp.args) ? vexp.args.filter((a) => typeof a === "string") : [];
+    const script = args.find((a) => /\.[cm]?js$/.test(a));
+    if (!command)
+        return { level: WARN, message: ".vscode/mcp.json vexp server has no 'command' — re-run 'vexp setup'" };
+    if (!/[\\/]/.test(command)) {
+        return {
+            level: WARN,
+            message: `.vscode/mcp.json starts the vexp server with a bare '${command}' — resolved through the editor's PATH, which a VS Code launched from the Dock/Start menu usually lacks (symptom: 'spawn ${command} ENOENT' in Output › MCP: vexp, no vexp tools in chat).\n` +
+                `        re-run 'vexp setup' — 3.1 pins the absolute node path.`,
+        };
+    }
+    if (!exists(command))
+        return { level: WARN, message: `.vscode/mcp.json vexp command does not exist: ${command} — re-run 'vexp setup' to repin it` };
+    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()) {
+        return { level: WARN, message: `.vscode/mcp.json vexp server is pinned to ${pinned}, but this workspace is ${wsRoot} — re-run 'vexp setup' here` };
+    }
+    return { level: OK, message: `.vscode/mcp.json vexp server: ${command} ${script ?? args.join(" ")}` };
+}
+/**
+ * How doctor runs a Codex `UserPromptSubmit` hook line: the way Codex does.
+ * On Windows Codex hands `cmd.exe /C` the WHOLE line wrapped in one more pair
+ * of quotes, verbatim (codex-rs/hooks engine/command_runner: `raw_arg`), and
+ * cmd strips that outer pair — which is why the installer may quote the
+ * script path. Passing the line as a normal argument instead lets Node escape
+ * the inner quotes, and cmd then looks for a program literally named
+ * `\"D:\…\vexp-hint.cmd\"` (field report, 2026-09-01: a correct hooks.json
+ * failed doctor's probe and passed once the user removed the quotes).
+ */
+export function codexHookSpawnSpec(cmdLine, platform = process.platform, comspec = process.env.COMSPEC) {
+    if (platform === "win32") {
+        return { file: comspec || "cmd.exe", args: ["/C", `"${cmdLine}"`], windowsVerbatimArguments: true };
+    }
+    return { 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();
+}
+/**
+ * A connected repo of a multi-repo workspace has no daemon of its own: the
+ * parent's daemon serves it. Doctor run inside such a repo used to treat it as
+ * a standalone workspace — "daemon NOT reachable", "NOT registered" — while
+ * `vexp search` from the same directory answered fine (field report,
+ * 2026-09-01, nine repos). The link is `.vexp/parent_workspace.json` in the
+ * member; when that file is missing, any registered workspace whose
+ * workspace.json lists this directory is the parent.
+ */
+export function resolveMemberParent(root, registryRoots) {
+    const link = resolveParentWorkspace(root);
+    if (link) {
+        const alias = listWorkspaceRepos(link.parentRoot).find((r) => samePath(r.resolvedPath, root))?.alias
+            ?? path.basename(root);
+        return { parentRoot: link.parentRoot, alias, via: ".vexp/parent_workspace.json" };
+    }
+    for (const reg of registryRoots) {
+        if (samePath(reg, root))
+            continue;
+        const hit = listWorkspaceRepos(reg).find((r) => !r.isPrimary && samePath(r.resolvedPath, root));
+        if (hit)
+            return { parentRoot: reg, alias: hit.alias, via: `${path.join(reg, ".vexp", "workspace.json")} (daemon registry)` };
+    }
+    return null;
+}
+/**
+ * Coverage verdicts for the workspace at `root` AND every repo connected to
+ * it, each tagged with its alias. Each repo's indexer writes its own
+ * `.vexp/coverage.json`; reading only the primary's hid three oversized files
+ * in a connected repo from a doctor run at the primary (same report).
+ */
+export function workspaceCoverageFindings(root) {
+    const repos = listWorkspaceRepos(root);
+    const targets = repos.map((r) => ({ alias: r.alias, dir: r.resolvedPath, primary: r.isPrimary }));
+    if (!targets.some((t) => t.primary))
+        targets.unshift({ alias: path.basename(root), dir: root, primary: true });
+    const out = [];
+    for (const t of targets) {
+        let cov;
+        try {
+            cov = JSON.parse(fs.readFileSync(path.join(t.dir, ".vexp", "coverage.json"), "utf-8"));
+        }
+        catch {
+            continue; /* never indexed, or an index older than 2.7 */
+        }
+        const v = coverageVerdict(cov);
+        if (v)
+            out.push({ level: v.level, message: targets.length > 1 ? `[${t.alias}] ${v.message}` : v.message });
+    }
+    return out;
+}
 export async function runDoctor() {
     const home = vexpHome();
+    const regPath = path.join(home, ".vexp", "daemons.json");
+    let registry = {};
+    try {
+        registry = JSON.parse(fs.readFileSync(regPath, "utf-8"));
+    }
+    catch { /* absent */ }
     let warns = 0;
     let fails = 0;
     const line = (status, msg) => {
@@ -205,8 +360,15 @@ export async function runDoctor() {
     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();
+    const resolved = resolveWorkspace();
+    const member = resolveMemberParent(resolved.root, Object.keys(registry));
+    const ws = member
+        ? { root: member.parentRoot, source: `repo '${member.alias}' of the multi-repo workspace, linked by ${member.via}` }
+        : resolved;
     console.log(`  cwd: ${process.cwd()}`);
+    if (member) {
+        line(OK, `this directory is repo '${member.alias}' of the multi-repo workspace at ${member.parentRoot} — served by that workspace's daemon; diagnostics below target it`);
+    }
     line(OK, `resolves to: ${ws.root}  (via ${ws.source})`);
     // A *global* VEXP_WORKSPACE env var overrides the per-session signal
     // (CLAUDE_PROJECT_DIR) for EVERY agent session, pinning Claude *and* Codex to
@@ -310,14 +472,15 @@ export async function runDoctor() {
             }
         }
     }
+    // 3.1 — coverage gaps only the daemon log used to witness. Read from disk,
+    // not from the daemon: the index that skipped the files may have been
+    // built by a daemon that is no longer running.
+    // Every connected repo has its own coverage.json; each finding carries the
+    // repo alias so a run at the primary sees the whole workspace.
+    for (const f of workspaceCoverageFindings(ws.root))
+        line(f.level, f.message);
     // 2) Daemon registry (~/.vexp/daemons.json) — stale entries are a drift source.
     console.log(chalk.bold("\nDaemon registry (~/.vexp/daemons.json)"));
-    const 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)");
@@ -434,6 +597,53 @@ export async function runDoctor() {
     catch {
         line(OK, "no ~/.claude.json");
     }
+    // 5a) GitHub Copilot — VS Code reads MCP servers from <folder>/.vscode/mcp.json.
+    console.log(chalk.bold("\nGitHub Copilot / VS Code (.vscode/mcp.json)"));
+    {
+        const mcpPath = path.join(ws.root, ".vscode", "mcp.json");
+        if (!fs.existsSync(mcpPath)) {
+            line(OK, "no .vscode/mcp.json (Copilot MCP not configured in this folder — 'vexp setup --agents \"GitHub Copilot\"' writes it)");
+        }
+        else {
+            let cfg = null;
+            try {
+                cfg = parseJsonc(fs.readFileSync(mcpPath, "utf-8"));
+            }
+            catch {
+                cfg = null;
+            }
+            const v = vsCodeMcpVerdict(cfg, ws.root);
+            line(v.level, v.message);
+            console.log(chalk.dim("        VS Code shows it under Extensions → MCP SERVERS - INSTALLED; vexp tools appear only in Copilot Chat AGENT mode (tools picker → 'MCP Server: vexp')."));
+            console.log(chalk.dim("        server log: Command Palette → 'MCP: List Servers' → vexp → Show Output (channel 'MCP: vexp'); daemon log: .vexp/daemon.log"));
+        }
+    }
+    // 5a-bis) WSL: agents on the Windows side read Windows-side configs, which
+    // nothing running in WSL can see or write. Say so, and for Windsurf hand
+    // over the exact entry (field report, 2026-09-01: a user built the bridge by
+    // hand and found no documentation).
+    if (isWsl()) {
+        console.log(chalk.bold("\nWSL"));
+        const distro = process.env.WSL_DISTRO_NAME ?? "?";
+        line(OK, `running inside WSL (${distro}) — editors and apps on the Windows side read their own configs there; vexp writes only WSL-side files`);
+        const windsurfHere = fs.existsSync(path.join(ws.root, ".windsurf")) || fs.existsSync(path.join(ws.root, ".devin"));
+        if (windsurfHere) {
+            let bin = "vexp-core";
+            try {
+                const { getBinaryPath } = await import("./binary.js");
+                bin = getBinaryPath();
+            }
+            catch { /* note still useful without the exact binary path */ }
+            const bundle = path.join(path.dirname(new URL(import.meta.url).pathname), "..", "mcp", "mcp-server.cjs");
+            line(WARN, `Windsurf/Devin Desktop on Windows will not read ${windsurfGlobalMcpPath()} (WSL home). Windows-side entry to paste:`);
+            for (const l of windsurfWslBridgeNote(ws.root, bin, fs.existsSync(bundle) ? bundle : undefined).split("\n")) {
+                console.log(chalk.dim(`        ${l}`));
+            }
+        }
+        else {
+            console.log(chalk.dim("        Windows-side apps (Codex app, Claude Desktop, Windsurf) need a wsl.exe bridge entry: https://vexp.dev/docs#windows-wsl"));
+        }
+    }
     // 5b) Claude Code guard hook — EXECUTE it the way Claude Code would, don't
     // just check presence. A shell-form command that word-splits on a project
     // path containing a space fails non-blocking on every call: the guard never
@@ -686,15 +896,18 @@ export async function runDoctor() {
                 line(BAD, "the entry has no 'commandWindows' — Codex runs hooks through cmd.exe on Windows, which cannot run the bash script, so orientation never fires (unless Git Bash is on PATH). Re-run 'vexp setup' to write the batch twin.");
             }
             else {
-                // Run it, through the same shell Codex would use: cmd.exe on
-                // Windows (COMSPEC), sh elsewhere. The script bakes an absolute path
+                // Run it, through the same shell Codex would use — cmd.exe on
+                // Windows (COMSPEC) with the line wrapped the way Codex wraps it, sh
+                // elsewhere (codexHookSpawnSpec). The script bakes an absolute path
                 // to the vexp binary and exits 0 when that path is not executable, so
                 // a stale or wrong-profile path leaves NO trace anywhere: no
                 // orientation, no error, forever. A Windows user found exactly that
                 // by reading the generated file.
                 const isWin = process.platform === "win32";
                 const cmdLine = (isWin ? hook.commandWindows : hook.command);
-                const r = spawnSync(isWin ? (process.env.COMSPEC || "cmd.exe") : "sh", [isWin ? "/c" : "-c", cmdLine], {
+                const spec = codexHookSpawnSpec(cmdLine);
+                const r = spawnSync(spec.file, spec.args, {
+                    windowsVerbatimArguments: spec.windowsVerbatimArguments,
                     env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
                     input: JSON.stringify({ session_id: "vexp-doctor", prompt: "vexp doctor probe", cwd: ws.root }),
                     timeout: 10000,
@@ -795,7 +1008,19 @@ export async function runDoctor() {
     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)"}`);
+        const alive = isAlive(rec.pid);
+        line(alive ? OK : WARN, `pid ${rec.pid} on :${rec.port} — ${alive ? "alive" : "DEAD (stale pid file)"}${rec.version ? ` · v${rec.version}` : ""}`);
+        // The supervisor is replaced on version mismatch only when a vexp command
+        // next runs; until then every HTTP client (Codex http transport, a
+        // `serverUrl` entry) talks to the OLD build — which advertises the old
+        // tool surface (2 tools before 2.7.0) and none of the newer fixes. A user
+        // saw two vexp servers with different tool counts and could not tell why.
+        if (alive && rec.version && rec.version !== CLI_VERSION) {
+            line(WARN, `the HTTP MCP server on :${rec.port} is v${rec.version} but this CLI is v${CLI_VERSION} — HTTP clients get the old build until it is replaced — run 'vexp setup' (or any indexing/search command, e.g. 'vexp savings') in the project and the current CLI takes it over`);
+        }
+        else if (alive && !rec.version) {
+            line(WARN, `the HTTP MCP server on :${rec.port} predates version tracking (older than 2.4) — run 'vexp setup' (or 'vexp savings') in the project so the current CLI replaces it and HTTP clients get v${CLI_VERSION}`);
+        }
     }
     catch {
         line(OK, "not running (no mcp.pid)");
@@ -810,4 +1035,8 @@ export async function runDoctor() {
         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("");
+    // Scripts and CI read the exit code, not the colors: any FAIL exits 1.
+    // Warnings alone stay 0 — advice, not breakage (field request, 2026-09-02).
+    if (fails > 0)
+        process.exitCode = 1;
 }

package/dist/license.js

@@ -206,10 +206,10 @@ export async function tryOnlineRefresh(longJwt) {
             // Only save if the freshToken itself verifies locally
             if (verifyAndDecode(data.freshToken)) {
                 saveFreshToken(data.freshToken);
-                // The server re-issued a 30-day long token (entitlement changed:
-                // AppSumo tier up/downgrade, or a Stripe resub migration). Overwrite
-                // the on-disk long JWT so the new entitlement survives even fully
-                // offline and the previous one stops working — without the user
+                // The server re-issued the 30-day long token (rolled forward on every
+                // refresh since vexp-web 3.1; also on entitlement change). Overwrite
+                // the on-disk long JWT so the current entitlement survives even fully
+                // offline and a superseded one stops working — without the user
                 // re-pasting a key. Only persist if it verifies locally.
                 if (data.newLongToken && verifyAndDecode(data.newLongToken)) {
                     try {

package/dist/serve.js

@@ -108,6 +108,33 @@ export function isOwnerEntry(ws, sock) {
  *  cross-wired daemon serving the child's index on the parent's socket, which
  *  then blocked every legitimate restart of the parent (it held the bind) and
  *  never matched the parent's config. Routing rows must never be spawned. */
+/** A linked git worktree: `.git` is a FILE whose `gitdir:` points into
+ *  `<main>/.git/worktrees/`. Agent harnesses create one per parallel task
+ *  (Claude Code under `.claude/worktrees/`, Cursor, plain `git worktree add`
+ *  — the detection is the file's content, never a path convention). After a
+ *  reboot the supervisor resurrected 15 of them alongside 2 canonical repos
+ *  and took a 16-core host down: ~1,585% CPU, 2 GB/s of reads, hard reset
+ *  (field incident, 2026-09-02, tier 3). Worktree daemons run on demand
+ *  only; resurrection is for canonical workspaces. A submodule's gitdir
+ *  points at `/.git/modules/` and is left alone. Mirrors vexp-core
+ *  utils::git_project_root. */
+export function isLinkedWorktree(ws) {
+    try {
+        const dotGit = path.join(ws, ".git");
+        if (fs.statSync(dotGit).isDirectory())
+            return false;
+        const gitdir = fs
+            .readFileSync(dotGit, "utf-8")
+            .split(/\r?\n/)
+            .find((l) => l.trim().startsWith("gitdir:"));
+        if (!gitdir)
+            return false;
+        return gitdir.replace(/\\/g, "/").includes("/.git/worktrees/");
+    }
+    catch {
+        return false;
+    }
+}
 export function resurrectionPlan(reg) {
     const bySock = new Map();
     for (const [ws, sock] of Object.entries(reg)) {
@@ -156,11 +183,25 @@ async function resurrectAll() {
             appendLog(`registry prune: ${ws} (no manifest)`);
             continue;
         }
+        if (isLinkedWorktree(ws)) {
+            appendLog(`registry prune: ${ws} (linked git worktree — on-demand only, never resurrected)`);
+            continue;
+        }
         pruned[ws] = sock;
     }
     const resurrected = new Map();
+    // Stagger actual spawns: every freshly started daemon runs its checkout
+    // sync and reconcile immediately, and a burst of them after a reboot is an
+    // IO storm (same incident as above). Rows whose socket is already alive
+    // cost nothing and are not delayed.
+    let spawnedOne = false;
     for (const { ws, sock } of resurrectionPlan(pruned)) {
+        const alive = await isSocketAlive(sock);
+        if (!alive && spawnedOne)
+            await new Promise((r) => setTimeout(r, 2000));
         resurrected.set(sock, await resurrectDaemon(ws, sock));
+        if (!alive)
+            spawnedOne = true;
     }
     for (const [ws, sock] of Object.entries(pruned)) {
         if (resurrected.get(sock))