n2n-nexus 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.8.2] - 2026-10-22
+
+### Fixed
+
+- Two daemons starting together on a fresh storage root: the loser no longer crashes with `SqliteError: database is locked` before reaching the port; database initialisation waits for the other process and the loser exits on `EADDRINUSE` as intended.
+- Reads of the file store (`get_project`, `search_projects`, topology, global docs) share a read-write lock with the writes, so a read during `rename_project` no longer returns an entry with empty docs and tech stack.
+- `sync_project_assets` and `update_project` write the manifest and docs first and the registry last, and restore the files they wrote when a later step fails; a failed create no longer leaves a project without a directory, and a failed update no longer mixes new and old fields.
+- Tasks whose timestamps were written before 0.6.0 (`YYYY-MM-DD HH:MM:SS`) are converted to ISO 8601 on startup, so they are no longer purged up to a day early.
+- `n2n-nexus uninstall` (and `install`) report a failing `mcp remove` when the server is still registered in the client's configuration, exit with code 1 and say what to do; "not registered" is still ignored.
+
+## [0.8.1] - 2026-10-22
+
+### Added
+
+- `n2n-nexus install <claude|codex>` writes the `node` found on PATH when it is the running binary, instead of `process.execPath`, the resolved version directory (nvm, Homebrew Cellar, fnm, ...) that disappears when Node is upgraded. `--node <path>` chooses the path explicitly; it must exist, run and satisfy `engines.node`. `install` prints the path it wrote and warns when it is in a version directory.
+- `n2n-nexus doctor [claude|codex]`: checks that the Node path and the entry script in the installed hook and MCP commands exist and run, and says how to fix them.
+
+### Fixed
+
+- Daemon responses are decoded as streaming UTF-8; a multi-byte character split across two chunks no longer turns into U+FFFD.
+- `rename_project` renames the directory, the manifests and the registry entry as one unit and rolls everything back when a step fails.
+- `host_delete_project` fails, and keeps the registry entry, when the project files cannot be removed.
+- `upload_project_asset` checks that the project exists inside the write lock, so an upload racing a delete no longer recreates the deleted project. It returns the name the asset is saved under, and a file name that sanitizes to `.` is rejected.
+- `listen({ on: false })` ends a Stop hook that is already waiting instead of letting it run to the timeout.
+
+### Upgrade notes
+
+- Run `n2n-nexus install claude` and/or `n2n-nexus install codex` again so the hooks and the MCP command use a stable Node path.
+
 ## [0.8.0] - 2026-10-21
 
 ### Added

package/README.md

@@ -105,6 +105,9 @@ n2n-nexus install codex     # ~/.codex/hooks.json (or $CODEX_HOME) + codex mcp a
 
 - Codex runs new hooks only after you trust them: open Codex and run `/hooks` once.
 - Pass `--endpoint <url>` to both commands when the daemon is not at `http://127.0.0.1:5688`.
+- The hooks and the MCP server command use an absolute Node path, because GUI clients started from the Dock (such as Claude Desktop) do not read your shell's `PATH`. By default `install` writes the `node` found on `PATH` when it is the same file as the Node running `install` (for example `/usr/local/bin/node`, `/opt/homebrew/bin/node`, `~/.local/bin/node` or a version manager's stable entry point), and otherwise the real path of the running Node. `install` prints the path it wrote as `Node: <path>`.
+- Pass `--node <path>` to choose the Node path yourself. It must exist, be executable and satisfy the `engines` range in package.json (`^22.14.0 || >=23.6.0`); otherwise `install` exits with code 1 and writes nothing.
+- After upgrading Node: if `install` warned that the Node path contains a version directory (Homebrew `Cellar`, nvm, fnm, Volta, asdf, `node-v<version>`), run `n2n-nexus install <claude|codex>` again after each upgrade, or pass `--node` with a stable path. `n2n-nexus doctor [claude|codex]` checks that the Node path and the entry script in the installed hook and MCP commands still exist and run, and exits with code 1 when they do not.
 - `n2n-nexus uninstall <claude|codex>` removes the hooks and the MCP server that `install` added and leaves the rest of the configuration alone.
 - Supported on Linux, WSL and macOS. Other MCP clients can use every tool except direct messages.
 
@@ -191,9 +194,13 @@ n2n-nexus daemon [--port 5688] [--root ~/.n2n-nexus] [--host 127.0.0.1]
 NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
 
 # Install / remove the hooks and MCP server for Claude Code or Codex
-n2n-nexus install <claude|codex> [--endpoint <url>]
+# --node <path>: the Node executable to write into the client configuration
+n2n-nexus install <claude|codex> [--endpoint <url>] [--node <path>]
 n2n-nexus uninstall <claude|codex>
 
+# Check that the installed hook and MCP commands still run (exit 1 when not)
+n2n-nexus doctor [claude|codex]
+
 # Hook entry point (written into the client configuration by install)
 n2n-nexus hook <claude|codex> [--endpoint <url>]
 ```

package/build/cli/doctor.js

@@ -0,0 +1,135 @@
+/**
+ * `n2n-nexus doctor [claude|codex]`: check that the Node path and the entry
+ * script in the hook commands and in the MCP server command that `install`
+ * wrote still exist and run, and say how to fix what does not. Without a
+ * client both are checked; a client with nothing installed is only reported
+ * when it was named. Exit code 1 when a check failed.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { HOOK_CLIENTS, MCP_SERVER_NAME, isHookClient } from "../daemon/hook-contract.js";
+import { pkg } from "../config/index.js";
+import { VERSIONED_NODE_DIR, configFile, isOurs, parseVersion, readConfig, satisfiesEngines } from "./install.js";
+import { mcpConfigFile, readMcpCommand } from "./mcp-config.js";
+const ok = (text) => ({ ok: true, text });
+const bad = (text) => ({ ok: false, text });
+const VERSIONED_NOTE = "in a version directory that an upgrade may remove";
+/** The Node path and the entry script of one of our hook commands, `"<node>" "<entry>" hook <client> ...`. */
+export function parseHookCommand(command) {
+    const m = /^"([^"]+)" "([^"]+)" hook /.exec(command);
+    return m ? { node: m[1], entry: m[2] } : undefined;
+}
+export function checkNode(node) {
+    if (!fs.existsSync(node))
+        return bad("missing");
+    try {
+        fs.accessSync(node, fs.constants.X_OK);
+    }
+    catch {
+        return bad("not executable");
+    }
+    const probe = spawnSync(node, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const version = probe.status === 0 ? parseVersion(probe.stdout) : undefined;
+    if (!version)
+        return bad("does not run");
+    const text = probe.stdout.trim();
+    if (!satisfiesEngines(text))
+        return bad(`${text} does not satisfy ${pkg.engines.node}`);
+    return ok(`${text}${VERSIONED_NODE_DIR.test(node) ? `, ${VERSIONED_NOTE}` : ""}`);
+}
+const checkEntry = (entry) => fs.existsSync(entry) ? ok("ok") : bad("missing");
+/** Check one client; prints the report and returns whether everything passed, or undefined when nothing is installed. */
+function doctorClient(client) {
+    const hooksFile = configFile(client);
+    const mcpFile = mcpConfigFile(client);
+    const lines = [];
+    let failed = false;
+    let versioned = false;
+    const report = (label, check) => {
+        lines.push(`  ${check.ok ? "ok  " : "FAIL"} ${label}: ${check.text}`);
+        if (!check.ok)
+            failed = true;
+        if (check.text.includes(VERSIONED_NOTE))
+            versioned = true;
+    };
+    const hooks = readConfig(hooksFile).hooks ?? {};
+    const commands = new Set();
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            const entries = group?.hooks;
+            if (!Array.isArray(entries))
+                continue;
+            for (const entry of entries) {
+                if (isOurs(entry, client))
+                    commands.add(entry.command);
+            }
+        }
+    }
+    const mcp = readMcpCommand(client, mcpFile);
+    if (commands.size === 0 && !mcp)
+        return undefined;
+    lines.push(`${client}`);
+    if (commands.size === 0)
+        report(`hooks in ${hooksFile}`, bad("not installed"));
+    for (const command of commands) {
+        const parsed = parseHookCommand(command);
+        if (!parsed) {
+            report(`hook command ${command}`, bad("not in the form \"<node>\" \"<entry>\" hook ..."));
+            continue;
+        }
+        report(`hook Node ${parsed.node}`, checkNode(parsed.node));
+        report(`hook entry ${parsed.entry}`, checkEntry(parsed.entry));
+    }
+    if (!mcp) {
+        report(`MCP server ${MCP_SERVER_NAME} in ${mcpFile}`, bad("not registered"));
+    }
+    else {
+        report(`MCP Node ${mcp.command}`, checkNode(mcp.command));
+        const entry = mcp.args[0];
+        if (entry)
+            report(`MCP entry ${entry}`, checkEntry(entry));
+        else
+            report(`MCP command in ${mcpFile}`, bad("has no entry script argument"));
+    }
+    if (failed) {
+        lines.push(`  fix: run "n2n-nexus install ${client}" again (add --node <path> to use a stable Node path such as /usr/local/bin/node).`);
+    }
+    else if (versioned) {
+        lines.push(`  note: after upgrading Node, run "n2n-nexus install ${client}" again, or install with --node <path> pointing at a stable entry such as /usr/local/bin/node.`);
+    }
+    process.stdout.write(lines.join("\n") + "\n");
+    return !failed;
+}
+/** Parse `[claude|codex]`, run the checks and return the exit code. */
+export function runDoctor(argv) {
+    const client = argv[0];
+    if (client !== undefined && !isHookClient(client)) {
+        process.stderr.write("Usage: n2n-nexus doctor [claude|codex]\n");
+        return 1;
+    }
+    try {
+        let failed = false;
+        for (const c of client ? [client] : HOOK_CLIENTS) {
+            const result = doctorClient(c);
+            if (result === undefined) {
+                if (client) {
+                    process.stdout.write(`${c}\n  FAIL nothing installed: run "n2n-nexus install ${c}".\n`);
+                    failed = true;
+                }
+                else {
+                    process.stdout.write(`${c}\n  not installed\n`);
+                }
+            }
+            else if (!result) {
+                failed = true;
+            }
+        }
+        return failed ? 1 : 0;
+    }
+    catch (error) {
+        process.stderr.write(`[n2n-nexus] doctor failed: ${error.message}\n`);
+        return 1;
+    }
+}

package/build/cli/install.js

@@ -1,35 +1,107 @@
 /**
- * `n2n-nexus install <claude|codex> [--endpoint <url>]` and
+ * `n2n-nexus install <claude|codex> [--endpoint <url>] [--node <path>]` and
  * `n2n-nexus uninstall <claude|codex>`: register the hooks and the MCP server
  * with Claude Code or Codex. Our hook entries are recognised by a command that
  * contains both `n2n-nexus` and ` hook <client>`; everything else in the
  * configuration file is kept as it is.
+ *
+ * The commands start with an absolute Node path: GUI clients started from the
+ * Dock do not read the shell PATH. The `node` found on PATH is preferred when it
+ * is the running binary, because process.execPath is the resolved, versioned
+ * location (nvm, Homebrew Cellar, ...) that disappears when Node is upgraded.
  */
 import { execFileSync, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { CLAUDE_PRE_TOOL_MATCHER, HOOK_STOP_TIMEOUT_SEC, HOOK_TIMEOUT_SEC, MCP_SERVER_NAME, isHookClient } from "../daemon/hook-contract.js";
+import { pkg } from "../config/index.js";
 import { entryScript } from "./autostart.js";
+import { mcpConfigFile, readMcpCommand } from "./mcp-config.js";
 const EVENTS = {
     claude: ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"],
     codex: ["SessionStart", "SessionEnd", "UserPromptSubmit", "PostToolUse", "Stop"]
 };
-class InstallError extends Error {
+export class InstallError extends Error {
 }
-function configFile(client) {
+/** Path segments of Node installs that are replaced on upgrade. */
+export const VERSIONED_NODE_DIR = /\/Cellar\/|\/\.nvm\/versions\/|\/node-v\d|\/fnm\/|\/fnm_multishells\/|\/\.volta\/|\/\.asdf\/installs\//;
+/** fnm puts a per-shell symlink directory first on PATH; it is gone when the shell ends. */
+const PER_SHELL_NODE_DIR = /\/fnm_multishells\//;
+function sameFile(a, b) {
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The `node` on PATH when it is the running binary (its stable entry), else
+ * process.execPath. Relative PATH entries and fnm's per-shell directory are
+ * skipped: the commands must work from any directory and after the shell ends.
+ */
+export function stableNodePath(env = process.env) {
+    for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+        if (!path.isAbsolute(dir) || PER_SHELL_NODE_DIR.test(dir))
+            continue;
+        const candidate = path.join(dir, "node");
+        if (sameFile(candidate, process.execPath))
+            return candidate;
+    }
+    return process.execPath;
+}
+export function parseVersion(text) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+const atLeast = (v, min) => v[0] !== min[0] ? v[0] > min[0] : v[1] !== min[1] ? v[1] > min[1] : v[2] >= min[2];
+/** Whether `version` satisfies the package's engines.node range (`^a.b.c` and `>=a.b.c` clauses joined by `||`). */
+export function satisfiesEngines(version, range = pkg.engines.node) {
+    const v = parseVersion(version);
+    if (!v)
+        return false;
+    return range.split("||").some((clause) => {
+        const m = /^\s*(\^|>=)\s*v?(\d+\.\d+\.\d+)\s*$/.exec(clause);
+        const min = m && parseVersion(m[2]);
+        if (!m || !min)
+            throw new Error(`Unsupported engines.node clause: ${clause.trim()}`);
+        return atLeast(v, min) && (m[1] === ">=" || v[0] === min[0]);
+    });
+}
+/** Check a `--node` path: it must exist, run, and satisfy engines.node. Returns the absolute path. */
+function checkNodePath(given) {
+    const node = path.resolve(given);
+    try {
+        fs.accessSync(node, fs.constants.X_OK);
+    }
+    catch {
+        throw new InstallError(`--node ${given}: not an executable file.`);
+    }
+    if (fs.statSync(node).isDirectory())
+        throw new InstallError(`--node ${given}: is a directory, not the node executable.`);
+    const probe = spawnSync(node, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const version = probe.status === 0 ? parseVersion(probe.stdout) : undefined;
+    if (!version)
+        throw new InstallError(`--node ${given}: "${node} --version" did not print a Node version.`);
+    if (!satisfiesEngines(probe.stdout)) {
+        throw new InstallError(`--node ${given}: Node ${probe.stdout.trim()} does not satisfy ${pkg.engines.node}.`);
+    }
+    return node;
+}
+export function configFile(client) {
     if (client === "claude") {
         return path.join(process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"), "settings.json");
     }
     return path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "hooks.json");
 }
-function isOurs(entry, client) {
+export function isOurs(entry, client) {
     if (typeof entry !== "object" || entry === null)
         return false;
     const command = entry.command;
     return typeof command === "string" && command.includes("n2n-nexus") && command.includes(` hook ${client}`);
 }
-function readConfig(file) {
+export function readConfig(file) {
     let text;
     try {
         text = fs.readFileSync(file, "utf8");
@@ -111,10 +183,44 @@ function mcpRemoveArgs(client) {
         ? ["mcp", "remove", "--scope", "user", MCP_SERVER_NAME]
         : ["mcp", "remove", MCP_SERVER_NAME];
 }
-function mcpAddArgs(client, entry, endpoint) {
+function mcpAddArgs(client, node, entry, endpoint) {
     const env = endpoint ? [client === "claude" ? "-e" : "--env", `NEXUS_ENDPOINT=${endpoint}`] : [];
     const scope = client === "claude" ? ["--scope", "user"] : [];
-    return ["mcp", "add", ...scope, MCP_SERVER_NAME, ...env, "--", process.execPath, entry, "mcp"];
+    return ["mcp", "add", ...scope, MCP_SERVER_NAME, ...env, "--", node, entry, "mcp"];
+}
+/**
+ * Run `<client> mcp remove`. A failure is ignored only when `<client> mcp get`
+ * shows the server is not registered (never installed, or already removed);
+ * otherwise the removal really failed and we stop before `mcp add`.
+ */
+function removeMcpServer(client, action, hooksRemoved) {
+    const removeArgs = mcpRemoveArgs(client);
+    try {
+        execFileSync(client, removeArgs, { encoding: "utf8", stdio: ["ignore", "ignore", "pipe"] });
+        if (action === "uninstall")
+            process.stdout.write(`Ran: ${client} ${removeArgs.join(" ")}\n`);
+        return;
+    }
+    catch (error) {
+        // "Not registered" is the one failure to ignore; the registration is read from the
+        // client's configuration file (an unreadable file counts as still registered).
+        let registered = true;
+        try {
+            registered = readMcpCommand(client, mcpConfigFile(client)) !== undefined;
+        }
+        catch {
+            // Keep registered = true: the error below tells the user what to look at.
+        }
+        if (!registered)
+            return;
+        const failure = error;
+        const stderr = typeof failure.stderr === "string" ? failure.stderr.trim() : "";
+        const detail = stderr || (typeof failure.status === "number" ? `exit code ${failure.status}` : failure.message);
+        const state = action === "uninstall"
+            ? `${hooksRemoved ? "The hooks were removed; t" : "T"}he MCP server is still registered in ${mcpConfigFile(client)}.`
+            : "The hooks were written; the existing MCP server registration was left unchanged.";
+        throw new InstallError(`"${client} ${removeArgs.join(" ")}" failed: ${detail}\n${state} Fix the error and run "n2n-nexus ${action} ${client}" again.`);
+    }
 }
 /** Install or uninstall; prints what it did and returns the exit code. */
 export function runInstall(options) {
@@ -128,30 +234,27 @@ export function runInstall(options) {
         if (probe.error || probe.status !== 0) {
             throw new InstallError(`The "${client}" command was not found on PATH; install ${client === "claude" ? "Claude Code" : "Codex"} first.`);
         }
+        const node = action === "install" ? (options.node ? checkNodePath(options.node) : stableNodePath()) : undefined;
         const file = configFile(client);
         const config = readConfig(file);
         const removed = removeOurEntries(config, client, file);
         if (action === "install") {
-            const command = `"${process.execPath}" "${entry}" hook ${client}${endpoint ? ` --endpoint ${endpoint}` : ""}`;
+            const command = `"${node}" "${entry}" hook ${client}${endpoint ? ` --endpoint ${endpoint}` : ""}`;
             addOurEntries(config, client, command);
         }
         if (action === "install" || removed) {
             writeConfig(file, config);
             process.stdout.write(`${action === "install" ? "Wrote hooks to" : "Removed hooks from"} ${file}\n`);
         }
-        const removeArgs = mcpRemoveArgs(client);
-        try {
-            execFileSync(client, removeArgs, { stdio: "ignore" });
-            if (action === "uninstall")
-                process.stdout.write(`Ran: ${client} ${removeArgs.join(" ")}\n`);
-        }
-        catch {
-            // Not registered yet (or already removed): nothing to undo.
-        }
-        if (action === "install") {
-            const addArgs = mcpAddArgs(client, entry, endpoint);
+        removeMcpServer(client, action, removed);
+        if (action === "install" && node) {
+            const addArgs = mcpAddArgs(client, node, entry, endpoint);
             execFileSync(client, addArgs, { stdio: ["ignore", "ignore", "inherit"] });
             process.stdout.write(`Ran: ${client} ${addArgs.join(" ")}\n`);
+            process.stdout.write(`Node: ${node}\n`);
+            if (VERSIONED_NODE_DIR.test(node)) {
+                process.stdout.write(`Note: this Node path contains a version directory that an upgrade may remove. After upgrading Node, run "n2n-nexus install ${client}" again, or install with --node <path> pointing at a stable entry such as /usr/local/bin/node.\n`);
+            }
             if (client === "codex") {
                 process.stdout.write("Next: open Codex and run /hooks to trust the n2n-nexus hooks; until then they do not run.\n");
             }
@@ -163,18 +266,29 @@ export function runInstall(options) {
         return 1;
     }
 }
-/** Parse `<claude|codex> [--endpoint <url>]` and run. */
+/** Parse `<claude|codex> [--endpoint <url>] [--node <path>]` and run. */
 export function runInstallCommand(action, argv) {
     const client = argv[0];
     if (!isHookClient(client)) {
-        process.stderr.write(`Usage: n2n-nexus ${action} <claude|codex>${action === "install" ? " [--endpoint <url>]" : ""}\n`);
+        process.stderr.write(`Usage: n2n-nexus ${action} <claude|codex>${action === "install" ? " [--endpoint <url>] [--node <path>]" : ""}\n`);
         return 1;
     }
-    const i = argv.indexOf("--endpoint");
-    const endpoint = action === "install" && i !== -1 ? argv[i + 1] : undefined;
-    if (i !== -1 && action === "install" && !endpoint) {
-        process.stderr.write("--endpoint needs a URL\n");
+    const option = (name, what) => {
+        const i = argv.indexOf(name);
+        if (i === -1 || action !== "install")
+            return undefined;
+        const value = argv[i + 1];
+        if (!value || value.startsWith("--")) {
+            process.stderr.write(`${name} needs ${what}\n`);
+            return null;
+        }
+        return value;
+    };
+    const endpoint = option("--endpoint", "a URL");
+    if (endpoint === null)
         return 1;
-    }
-    return runInstall({ action, client, endpoint });
+    const node = option("--node", "a path");
+    if (node === null)
+        return 1;
+    return runInstall({ action, client, endpoint, node });
 }

package/build/cli/mcp-config.js

@@ -0,0 +1,62 @@
+/**
+ * Where Claude Code and Codex keep their MCP server registrations, and how to
+ * read the n2n-nexus entry: `~/.claude.json` (user scope) and
+ * `$CODEX_HOME/config.toml`. `claude mcp get` is not used for this because it
+ * looks in every scope, not only the user scope that install writes to, and
+ * it starts the server for a health check.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { MCP_SERVER_NAME } from "../daemon/hook-contract.js";
+/** Where the client keeps the MCP server command. */
+export function mcpConfigFile(client) {
+    if (client === "claude") {
+        return path.join(process.env.CLAUDE_CONFIG_DIR || os.homedir(), ".claude.json");
+    }
+    return path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "config.toml");
+}
+/** The MCP server command the client has for n2n-nexus, or undefined when not registered. */
+export function readMcpCommand(client, file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (client === "claude") {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`${file} is not valid JSON (${error.message}).`, { cause: error });
+        }
+        const servers = parsed?.mcpServers;
+        const server = servers?.[MCP_SERVER_NAME];
+        if (!server || typeof server.command !== "string")
+            return undefined;
+        return { command: server.command, args: Array.isArray(server.args) ? server.args.map(String) : [] };
+    }
+    // Codex: a TOML table [mcp_servers.n2n-nexus] (the key may be quoted) with command = "..." and args = [...].
+    const lines = text.split("\n");
+    const start = lines.findIndex((line) => new RegExp(`^\\s*\\[mcp_servers\\.("?)${MCP_SERVER_NAME}\\1\\]\\s*$`).test(line));
+    if (start === -1)
+        return undefined;
+    let command;
+    let args = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^\s*\[/.test(line))
+            break;
+        const c = /^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"/.exec(line);
+        if (c)
+            command = JSON.parse(`"${c[1]}"`);
+        const a = /^\s*args\s*=\s*\[(.*)\]/.exec(line);
+        if (a)
+            args = [...a[1].matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => JSON.parse(`"${m[1]}"`));
+    }
+    return command === undefined ? undefined : { command, args };
+}

package/build/client/nexus-client.js

@@ -47,6 +47,7 @@ export class NexusClient {
                 timeout: timeoutMs
             }, (res) => {
                 let data = "";
+                res.setEncoding("utf8");
                 const interrupted = () => reject(new NexusTransportError("Response from daemon ended before completion"));
                 res.on("aborted", interrupted);
                 res.on("error", (error) => reject(new NexusTransportError(error.message)));

package/build/daemon/server.js

@@ -35,7 +35,9 @@ async function toolSyncProjectAssets(args, instanceId) {
 async function toolUploadAsset(args, instanceId) {
     if (!await StorageManager.getProjectManifest(args.projectId))
         throw new Error(`Project '${args.projectId}' not found.`);
-    const sanitized = args.fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
+    // Must produce the final saved name: StorageManager.saveAsset's sanitizeFileName
+    // (src/storage/projects.ts) has to leave this result unchanged, so keep both rules in step.
+    const sanitized = args.fileName.replace(/[^a-zA-Z0-9._-]/g, "_").replace(/\.\./g, "_");
     const buf = Buffer.from(args.base64Content, "base64");
     await StorageManager.saveAsset(args.projectId, sanitized, buf);
     EventStore.record(instanceId, "project.asset", args.projectId, { fileName: sanitized, bytes: buf.length });
@@ -282,6 +284,7 @@ async function toolRead(args, caller) {
 async function toolListen(args, caller) {
     const self = resolveAgent(caller);
     AgentStore.setListening(self.id, args.on);
+    wake([self.id]);
     return { listening: args.on };
 }
 async function toolSetProfile(args, caller) {
@@ -354,8 +357,9 @@ function waitForMessages(sessionId, waitMs, signal) {
             if (done)
                 return;
             // SessionEnd (or listen off) during the wait: nobody will act on a block any more.
+            // stopWaiting sets idle only while still "listening", so SessionEnd stays offline.
             if (!AgentStore.get(sessionId)?.listening)
-                return finish(null);
+                return stopWaiting();
             const text = notifyFresh(sessionId, STOP_CLOSING);
             if (text === null)
                 return;

package/build/index.js

@@ -12,10 +12,13 @@ n2n-nexus v${pkg.version} — Multi-AI assistant coordination hub
 USAGE:
   n2n-nexus daemon   Start the Nexus server (run once, stays alive)
   n2n-nexus mcp      Start the MCP proxy (launched by IDE automatically)
-  n2n-nexus install <claude|codex> [--endpoint <url>]
+  n2n-nexus install <claude|codex> [--endpoint <url>] [--node <path>]
                      Register the hooks and the MCP server with Claude Code or Codex
   n2n-nexus uninstall <claude|codex>
                      Remove the hooks and the MCP server installed by install
+  n2n-nexus doctor [claude|codex]
+                     Check that the Node path and entry script in the installed hook and
+                     MCP commands exist and run; exit 1 and say how to fix them when not
   n2n-nexus hook <claude|codex> [--endpoint <url>]
                      Forward a client hook event to the daemon (run by the hooks)
 
@@ -26,6 +29,8 @@ OPTIONS:
   --id <id>          Instance ID for MCP proxy (default: mcp-<hostname>-<cwd hash>-<IDE name>)
   --endpoint <url>   Daemon URL for hook (default: NEXUS_ENDPOINT, then http://127.0.0.1:5688);
                      install writes it into the hook and MCP commands
+  --node <path>      Node executable written into the hook and MCP commands by install
+                     (default: the node on PATH when it is the running one, else its real path)
   --version, -v      Show version
   --help, -h         Show this help
 
@@ -47,6 +52,10 @@ async function main() {
         const { runInstallCommand } = await import("./cli/install.js");
         process.exit(runInstallCommand(command, process.argv.slice(3)));
     }
+    if (command === "doctor") {
+        const { runDoctor } = await import("./cli/doctor.js");
+        process.exit(runDoctor(process.argv.slice(3)));
+    }
     if (command === "daemon") {
         const { runDaemon } = await import("./daemon/index.js");
         await runDaemon();

package/build/storage/fs-utils.js

@@ -1,13 +1,14 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { AsyncMutex } from "../utils/async-mutex.js";
+import { AsyncRWLock } from "../utils/async-rwlock.js";
 import { FILE_ENCODING } from "../constants.js";
 /**
- * Serializes every file-store write inside the daemon. HTTP requests are
- * handled concurrently, so read-modify-write sequences on registry.json,
- * manifests and the docs index must be queued behind one lock.
+ * Guards the file store inside the daemon. HTTP requests are handled
+ * concurrently: writes take it exclusively, so read-modify-write sequences on
+ * registry.json, manifests and the docs index are queued; reads take it
+ * shared, so they never observe a multi-file write (such as a rename) halfway.
  */
-export const fileWriteLock = new AsyncMutex();
+export const fileStoreLock = new AsyncRWLock();
 /**
  * Write to a temp file in the same directory, then rename over the target so
  * readers never observe a partially written file.
@@ -40,3 +41,48 @@ export function toDict(entries = []) {
 export function writeJsonAtomic(filePath, value) {
     return writeFileAtomic(filePath, JSON.stringify(value, null, 2));
 }
+export async function snapshotFile(filePath) {
+    const dir = path.dirname(filePath);
+    let createsDir = false;
+    try {
+        await fs.access(dir);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        createsDir = true;
+    }
+    let original = null;
+    if (!createsDir) {
+        try {
+            original = await fs.readFile(filePath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return { path: filePath, original, createsDir };
+}
+/**
+ * Puts a file back as snapshotFile recorded it: original bytes rewritten,
+ * a file that did not exist removed, and a directory the write created
+ * removed with everything in it. Best effort: an undo failure is swallowed
+ * so the caller can rethrow the error that caused the rollback.
+ */
+export async function restoreFile(snapshot) {
+    try {
+        if (snapshot.createsDir) {
+            await fs.rm(path.dirname(snapshot.path), { recursive: true, force: true });
+        }
+        else if (snapshot.original === null) {
+            await fs.rm(snapshot.path, { force: true });
+        }
+        else {
+            await writeFileAtomic(snapshot.path, snapshot.original);
+        }
+    }
+    catch {
+        // Best effort, see above.
+    }
+}

package/build/storage/index.js

@@ -4,7 +4,7 @@ import { NexusPaths } from "./paths.js";
 import { RegistryStorage } from "./registry.js";
 import { ProjectStorage } from "./projects.js";
 import { DocStorage } from "./docs.js";
-import { fileWriteLock, writeFileAtomic, writeJsonAtomic } from "./fs-utils.js";
+import { fileStoreLock, restoreFile, snapshotFile, writeFileAtomic, writeJsonAtomic } from "./fs-utils.js";
 export const BLUEPRINT_PLACEHOLDER = "# Global Coordination Blueprint\n\nShared meeting space.";
 export class StorageManager {
     static initialized = false;
@@ -54,34 +54,73 @@ export class StorageManager {
             return false;
         }
     }
-    // Every mutation of the file store goes through this lock; reads are
-    // lock-free because writes are atomic (temp file + rename).
+    // Every mutation of the file store takes the lock exclusively and every
+    // public read takes it shared. Single files are written atomically (temp
+    // file + rename), but some writes span several files (a rename moves the
+    // directory before the registry switches ids), and a read between those
+    // steps would see a registry entry whose files are gone. Code inside
+    // write() or read() must call the sub-modules directly, never these locked
+    // StorageManager methods: the lock is not reentrant (a read inside a read
+    // deadlocks as soon as a writer is queued between them).
     static write(fn) {
-        return fileWriteLock.withLock(fn);
+        return fileStoreLock.withWrite(fn);
+    }
+    static read(fn) {
+        return fileStoreLock.withRead(fn);
     }
     // --- Registry Methods ---
-    static listRegistry() { return RegistryStorage.listRegistry(); }
-    static getProjectManifest(id) { return RegistryStorage.getProjectManifest(id); }
+    static listRegistry() { return this.read(() => RegistryStorage.listRegistry()); }
+    static getProjectManifest(id) { return this.read(() => RegistryStorage.getProjectManifest(id)); }
     static saveProjectManifest(manifest) { return this.write(() => RegistryStorage.saveProjectManifest(manifest)); }
-    /** Manifest and internal docs in one critical section, so a concurrent delete cannot interleave. */
+    /**
+     * Manifest and internal docs in one critical section, so a concurrent
+     * delete cannot interleave. Docs are written first and
+     * saveProjectManifest writes the registry last, so the registry only
+     * lists the project once all its files are in place. If anything fails,
+     * the docs file is put back to its original bytes (removed if it did not
+     * exist, with the project directory if this call created it) and the
+     * original error is rethrown; saveProjectManifest rolls back its own
+     * manifest write.
+     */
     static saveProject(manifest, docs) {
         return this.write(async () => {
-            await RegistryStorage.saveProjectManifest(manifest);
-            await ProjectStorage.saveProjectDocs(manifest.id, docs);
+            const snapshot = await snapshotFile(NexusPaths.projectDocPath(manifest.id));
+            try {
+                await ProjectStorage.saveProjectDocs(manifest.id, docs);
+                await RegistryStorage.saveProjectManifest(manifest);
+            }
+            catch (error) {
+                await restoreFile(snapshot);
+                throw error;
+            }
         });
     }
     static patchProjectManifest(id, patch) { return this.write(() => RegistryStorage.patchProjectManifest(id, patch)); }
-    static calculateTopology(projectId) { return RegistryStorage.calculateTopology(projectId); }
+    static calculateTopology(projectId) { return this.read(() => RegistryStorage.calculateTopology(projectId)); }
     // --- Project Methods ---
-    static getProjectDocs(id) { return ProjectStorage.getProjectDocs(id); }
+    static getProjectDocs(id) { return this.read(() => ProjectStorage.getProjectDocs(id)); }
     static saveProjectDocs(id, content) { return this.write(() => ProjectStorage.saveProjectDocs(id, content)); }
-    static saveAsset(id, fileName, content) { return this.write(() => ProjectStorage.saveAsset(id, fileName, content)); }
+    /**
+     * The existence check runs inside the write lock: writeFileAtomic creates
+     * missing directories, so an upload queued behind a delete would otherwise
+     * bring the deleted project's directory back.
+     */
+    static saveAsset(id, fileName, content) {
+        return this.write(async () => {
+            const registry = await RegistryStorage.listRegistry();
+            if (!registry.projects[id])
+                throw new Error(`Project '${id}' not found.`);
+            return ProjectStorage.saveAsset(id, fileName, content);
+        });
+    }
+    /** Files first, index last: if the files cannot be removed, the throw leaves the registry entry in place. */
     static deleteProject(id) {
         return this.write(async () => {
             await ProjectStorage.deleteProject(id);
             await RegistryStorage.deleteProject(id);
         });
     }
+    /** RegistryStorage.renameProject moves the directory, manifests and registry together and rolls back on failure. */
     static renameProject(oldId, newId) {
         return this.write(async () => {
             if (!await RegistryStorage.getProjectManifest(oldId))
@@ -89,23 +128,14 @@ export class StorageManager {
             const renamed = await RegistryStorage.renameProject(oldId, newId);
             if (renamed === 0)
                 throw new Error(`Project '${oldId}' could not be renamed.`);
-            try {
-                const result = await ProjectStorage.renameProject(oldId, newId);
-                if (result === 0)
-                    throw new Error(`Project '${oldId}' could not be renamed.`);
-                return result;
-            }
-            catch (error) {
-                await RegistryStorage.renameProject(newId, oldId).catch(() => { });
-                throw error;
-            }
+            return renamed;
         });
     }
     // --- Doc Methods ---
-    static listGlobalDocs() { return DocStorage.listDocs(); }
-    static getGlobalDoc(docId) { return DocStorage.getDoc(docId); }
+    static listGlobalDocs() { return this.read(() => DocStorage.listDocs()); }
+    static getGlobalDoc(docId) { return this.read(() => DocStorage.getDoc(docId)); }
     static saveGlobalDoc(docId, title, content, updatedBy) { return this.write(() => DocStorage.saveDoc(docId, title, content, updatedBy)); }
     static deleteGlobalDoc(docId) { return this.write(() => DocStorage.deleteDoc(docId)); }
-    static getGlobalBlueprint() { return DocStorage.getBlueprint(); }
+    static getGlobalBlueprint() { return this.read(() => DocStorage.getBlueprint()); }
     static saveGlobalBlueprint(content) { return this.write(() => DocStorage.saveBlueprint(content)); }
 }

package/build/storage/projects.js

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { NexusPaths } from "./paths.js";
 import { FILE_ENCODING } from "../constants.js";
-import { writeFileAtomic, writeJsonAtomic } from "./fs-utils.js";
+import { writeFileAtomic } from "./fs-utils.js";
 export class ProjectStorage {
     static projectFilePath(projectId) {
         return {
@@ -27,43 +27,22 @@ export class ProjectStorage {
     }
     static async saveAsset(projectId, fileName, content) {
         const safeName = this.sanitizeFileName(fileName);
+        // "." would resolve to the assets directory itself and writeFileAtomic would create a file in its place.
+        if (safeName === ".")
+            throw new Error(`Invalid fileName '${fileName}': it names no file.`);
         const paths = this.projectFilePath(projectId);
         const assetPath = path.join(paths.assetsDir, safeName);
         await writeFileAtomic(assetPath, content);
         return path.relative(NexusPaths.root, assetPath);
     }
+    /**
+     * Removes the project directory. A missing directory counts as deleted
+     * (force); any other failure is thrown so the caller keeps the registry
+     * entry instead of indexing a project whose files are still on disk.
+     */
     static async deleteProject(projectId) {
         const paths = this.projectFilePath(projectId);
-        try {
-            await fs.rm(paths.projectDir, { recursive: true, force: true });
-            return 1;
-        }
-        catch {
-            return 0;
-        }
-    }
-    static async renameProject(oldId, newId) {
-        if (!oldId || !newId || oldId === newId)
-            return 0;
-        const oldPath = this.projectFilePath(oldId);
-        const newPath = this.projectFilePath(newId);
-        try {
-            await fs.access(oldPath.projectDir);
-        }
-        catch {
-            return 0;
-        }
-        await fs.mkdir(path.dirname(newPath.projectDir), { recursive: true });
-        await fs.rename(oldPath.projectDir, newPath.projectDir);
-        try {
-            const manifestRaw = await fs.readFile(newPath.manifestPath, FILE_ENCODING);
-            const manifest = JSON.parse(manifestRaw);
-            manifest.id = newId;
-            await writeJsonAtomic(newPath.manifestPath, manifest);
-        }
-        catch {
-            // Manifest is optional for some flows.
-        }
+        await fs.rm(paths.projectDir, { recursive: true, force: true });
         return 1;
     }
     static sanitizeFileName(fileName) {

package/build/storage/registry.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import { NexusPaths } from "./paths.js";
-import { toDict, writeJsonAtomic } from "./fs-utils.js";
+import { restoreFile, snapshotFile, toDict, writeFileAtomic, writeJsonAtomic } from "./fs-utils.js";
 const emptyRegistry = () => ({ projects: toDict() });
 async function readRegistry() {
     try {
@@ -91,8 +91,14 @@ export class RegistryStorage {
     static async listRegistry() {
         return readRegistry();
     }
+    /**
+     * Creates or replaces a project. Order: manifest first, registry last, so
+     * the registry never lists a project whose manifest was not written. If
+     * the registry write fails, the manifest is put back to its original
+     * bytes (removed if it did not exist, together with the project directory
+     * if this call created it) and the original error is rethrown.
+     */
     static async saveProjectManifest(manifest) {
-        const projectDir = NexusPaths.projectDir(manifest.id);
         const manifestPath = NexusPaths.projectManifestPath(manifest.id);
         const registry = await readRegistry();
         registry.projects[manifest.id] = {
@@ -100,9 +106,15 @@ export class RegistryStorage {
             summary: manifest.description || "",
             lastActive: new Date().toISOString()
         };
-        await writeRegistry(registry);
-        await fs.mkdir(projectDir, { recursive: true });
+        const snapshot = await snapshotFile(manifestPath);
         await writeJsonAtomic(manifestPath, { ...manifest, lastUpdated: manifest.lastUpdated || new Date().toISOString() });
+        try {
+            await writeRegistry(registry);
+        }
+        catch (error) {
+            await restoreFile(snapshot);
+            throw error;
+        }
     }
     static async getProjectManifest(id) {
         const registry = await readRegistry();
@@ -128,6 +140,11 @@ export class RegistryStorage {
             feature_tier: m.feature_tier
         };
     }
+    /**
+     * Applies a patch to the manifest and the registry entry. Same order and
+     * rollback as saveProjectManifest: manifest first, registry last; if the
+     * registry write fails the manifest is restored to its original bytes.
+     */
     static async patchProjectManifest(id, patch) {
         const registry = await readRegistry();
         const existing = registry.projects[id];
@@ -139,7 +156,8 @@ export class RegistryStorage {
             name: patch.name ?? existing.name,
             lastActive: new Date().toISOString()
         };
-        await writeRegistry(registry);
+        const manifestPath = NexusPaths.projectManifestPath(id);
+        const snapshot = await snapshotFile(manifestPath);
         const manifest = await readProjectManifest(id) || {};
         const patchedManifest = {
             id,
@@ -158,7 +176,14 @@ export class RegistryStorage {
             api_versions: patch.api_versions ?? manifest.api_versions,
             feature_tier: patch.feature_tier ?? manifest.feature_tier
         };
-        await writeJsonAtomic(NexusPaths.projectManifestPath(id), patchedManifest);
+        await writeJsonAtomic(manifestPath, patchedManifest);
+        try {
+            await writeRegistry(registry);
+        }
+        catch (error) {
+            await restoreFile(snapshot);
+            throw error;
+        }
     }
     static async calculateTopology(projectId) {
         const registry = await readRegistry();
@@ -233,39 +258,97 @@ export class RegistryStorage {
         await writeRegistry(registry);
         return 1;
     }
+    /**
+     * Renames a project as one unit: its directory, its own manifest id, every
+     * relation that targets it in other manifests, and the registry key.
+     *
+     * Order: directory rename, then manifest writes, then the registry write
+     * last. The registry is the index readers trust, so it only switches to
+     * the new id once everything it points at is in place. If any step
+     * throws, the completed steps are undone in reverse (manifests restored to
+     * their original bytes, directory renamed back) and the original error is
+     * rethrown. Rollback is best effort: a failure while undoing is swallowed
+     * so the caller still sees the error that caused the rollback.
+     *
+     * Returns 0 when oldId is not registered or its directory does not exist.
+     */
     static async renameProject(oldId, newId) {
+        if (!oldId || !newId || oldId === newId)
+            return 0;
         const registry = await readRegistry();
         if (!registry.projects[oldId])
             return 0;
         if (registry.projects[newId]) {
             throw new Error(`Project '${newId}' already exists.`);
         }
-        const entry = registry.projects[oldId];
-        delete registry.projects[oldId];
-        registry.projects[newId] = entry;
-        await writeRegistry(registry);
+        const oldDir = NexusPaths.projectDir(oldId);
+        const newDir = NexusPaths.projectDir(newId);
+        try {
+            await fs.access(oldDir);
+        }
+        catch {
+            return 0;
+        }
+        // Plan every manifest rewrite before touching disk. `original` keeps
+        // the exact bytes for rollback; `path` is where the file lives after
+        // the directory rename.
+        const rewrites = [];
         for (const projectId of Object.keys(registry.projects)) {
-            const manifestId = projectId === newId ? oldId : projectId;
-            const manifest = await readProjectManifest(manifestId);
-            if (!manifest)
+            let original;
+            try {
+                original = await fs.readFile(NexusPaths.projectManifestPath(projectId), "utf-8");
+            }
+            catch {
                 continue;
+            }
+            let manifest;
+            try {
+                manifest = JSON.parse(original);
+            }
+            catch {
+                continue;
+            }
             let changed = false;
-            if (projectId === newId && manifest.id !== newId) {
+            if (projectId === oldId) {
                 manifest.id = newId;
                 changed = true;
             }
             if (Array.isArray(manifest.relations)) {
-                const relations = manifest.relations.map((relation) => {
-                    if (relation.targetId !== oldId)
+                manifest.relations = manifest.relations.map((relation) => {
+                    if (relation?.targetId !== oldId)
                         return relation;
                     changed = true;
                     return { ...relation, targetId: newId };
                 });
-                manifest.relations = relations;
             }
             if (changed) {
-                await writeJsonAtomic(NexusPaths.projectManifestPath(manifestId), manifest);
+                const target = projectId === oldId ? newId : projectId;
+                rewrites.push({ path: NexusPaths.projectManifestPath(target), original, updated: manifest });
+            }
+        }
+        let dirMoved = false;
+        const written = [];
+        try {
+            await fs.mkdir(NexusPaths.projectsRoot, { recursive: true });
+            await fs.rename(oldDir, newDir);
+            dirMoved = true;
+            for (const rewrite of rewrites) {
+                await writeJsonAtomic(rewrite.path, rewrite.updated);
+                written.push(rewrite);
+            }
+            const entry = registry.projects[oldId];
+            delete registry.projects[oldId];
+            registry.projects[newId] = entry;
+            await writeRegistry(registry);
+        }
+        catch (error) {
+            for (const rewrite of written.reverse()) {
+                await writeFileAtomic(rewrite.path, rewrite.original).catch(() => { });
+            }
+            if (dirMoved) {
+                await fs.rename(newDir, oldDir).catch(() => { });
             }
+            throw error;
         }
         return 1;
     }

package/build/storage/sqlite.js

@@ -162,19 +162,64 @@ CREATE INDEX IF NOT EXISTS idx_tool_use_bindings_created ON tool_use_bindings(cr
 export function getDbPath() {
     return NexusPaths.dbFile;
 }
+/** Longest a first start waits for another process that is initialising the same database. */
+const INIT_BUSY_WAIT_MS = 10_000;
+const INIT_RETRY_DELAY_MS = 50;
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const isBusy = (error) => error?.code === "SQLITE_BUSY";
 /**
- * Initialize the SQLite database with WAL mode
+ * Open the database, switch it to WAL and create the schema. Throws SQLITE_BUSY
+ * (from the pragma or the schema statements) while another process is writing.
  */
-export function initDatabase() {
+function openDatabase(dbPath) {
+    const candidate = new Database(dbPath);
+    try {
+        // WAL for better concurrent access. The pragma answers with the mode in effect;
+        // anything but "wal" (an in-memory database, a VFS without shared memory) would
+        // leave the daemon in rollback-journal mode, which the startup race cannot survive.
+        const mode = candidate.pragma("journal_mode = WAL", { simple: true });
+        if (mode !== "wal")
+            throw new Error(`WAL mode is not available for ${dbPath}: journal_mode stayed "${mode}".`);
+        candidate.pragma("foreign_keys = ON");
+        candidate.exec(SCHEMA);
+        return candidate;
+    }
+    catch (error) {
+        candidate.close();
+        throw error;
+    }
+}
+/**
+ * Initialize the SQLite database with WAL mode.
+ *
+ * Two daemons starting on a fresh root reach this together. SQLite answers the
+ * second one with SQLITE_BUSY at once (not through the busy timeout) while the
+ * first holds its write lock in rollback-journal mode, so the open is retried
+ * until the other process has finished; no retry starts after `busyWaitMs`.
+ */
+export function initDatabase(options = {}) {
     if (db)
         return db;
     const dbPath = getDbPath();
-    db = new Database(dbPath);
-    // Enable WAL mode for better concurrent access
-    db.pragma("journal_mode = WAL");
-    db.pragma("foreign_keys = ON");
-    // Initialize schema
-    db.exec(SCHEMA);
+    const started = Date.now();
+    const deadline = started + (options.busyWaitMs ?? INIT_BUSY_WAIT_MS);
+    let opened;
+    for (;;) {
+        try {
+            opened = openDatabase(dbPath);
+            break;
+        }
+        catch (error) {
+            if (!isBusy(error))
+                throw error;
+            if (Date.now() >= deadline) {
+                error.message += ` (gave up after ${Date.now() - started} ms waiting for another process initialising ${dbPath})`;
+                throw error;
+            }
+            sleepSync(INIT_RETRY_DELAY_MS);
+        }
+    }
+    db = opened;
     // Migration: Add initiator column if it doesn't exist (Upgrade from v0.1.7)
     try {
         const columns = db.prepare("PRAGMA table_info(meetings)").all();
@@ -187,6 +232,21 @@ export function initDatabase() {
     catch (e) {
         console.error("[Nexus] Migration check failed:", e);
     }
+    // Migration: Convert task timestamps written by the pre-0.6.0 trigger and
+    // column defaults (datetime('now'), 'YYYY-MM-DD HH:MM:SS') to ISO 8601, so
+    // string comparisons against new Date().toISOString() order correctly.
+    try {
+        for (const column of ["created_at", "updated_at"]) {
+            const { changes } = db.prepare(`UPDATE tasks SET ${column} = strftime('%Y-%m-%dT%H:%M:%fZ', ${column})
+                 WHERE ${column} NOT LIKE '%T%' AND strftime('%Y-%m-%dT%H:%M:%fZ', ${column}) IS NOT NULL`).run();
+            if (changes > 0) {
+                console.error(`[Nexus] Migrating database: Converted ${changes} 'tasks.${column}' value(s) to ISO 8601.`);
+            }
+        }
+    }
+    catch (e) {
+        console.error("[Nexus] Migration check failed:", e);
+    }
     // Initialize default state if not exists
     const stmt = db.prepare("INSERT OR IGNORE INTO meeting_state (key, value) VALUES (?, ?)");
     stmt.run("active_meetings", "[]");

package/build/utils/async-rwlock.js

@@ -0,0 +1,64 @@
+/**
+ * Readers-writer lock for async code. Any number of readers run together; a
+ * writer runs alone. Waiters are served in FIFO order and writers take
+ * priority: once a writer is queued, readers that arrive later queue behind
+ * it instead of joining the readers already running, so a steady stream of
+ * reads cannot starve a write.
+ */
+export class AsyncRWLock {
+    readers = 0;
+    writing = false;
+    queue = [];
+    acquire(write) {
+        // A reader may join running readers only while nothing is queued (a queued entry is either a writer or a reader behind one).
+        const free = write ? !this.writing && this.readers === 0 : !this.writing && this.queue.length === 0;
+        if (free) {
+            if (write)
+                this.writing = true;
+            else
+                this.readers++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.queue.push({ write, resolve }));
+    }
+    release(write) {
+        if (write)
+            this.writing = false;
+        else
+            this.readers--;
+        if (this.writing || this.readers > 0)
+            return;
+        // Lock is free: wake the next writer alone, or every reader up to the next queued writer.
+        const next = this.queue[0];
+        if (!next)
+            return;
+        if (next.write) {
+            this.queue.shift();
+            this.writing = true;
+            next.resolve();
+            return;
+        }
+        while (this.queue.length > 0 && !this.queue[0].write) {
+            this.readers++;
+            this.queue.shift().resolve();
+        }
+    }
+    async withRead(fn) {
+        await this.acquire(false);
+        try {
+            return await fn();
+        }
+        finally {
+            this.release(false);
+        }
+    }
+    async withWrite(fn) {
+        await this.acquire(true);
+        try {
+            return await fn();
+        }
+        finally {
+            this.release(true);
+        }
+    }
+}

package/docs/ARCHITECTURE.md

@@ -92,7 +92,7 @@ All data lives under the daemon's storage root (default `~/.n2n-nexus`):
 
 **SQLite WAL mode**: Only the daemon process opens the database. MCP adapters never touch it — they go through HTTP.
 
-**File-store writes**: HTTP requests are handled concurrently, so every mutation of `registry.json`, manifests and the docs index is queued behind one daemon-wide lock and written atomically (temp file + rename).
+**File-store access**: HTTP requests are handled concurrently, so every mutation of `registry.json`, manifests and the docs index holds one daemon-wide read-write lock alone and is written atomically (temp file + rename); reads share the lock, so a rename or update is never observed half-done. A write orders its files so that `registry.json` goes last and restores what it had already written when a later step fails.
 
 **Activity log**: state changes made through the daemon (project sync/rename/delete, meeting start/end, doc sync, ...) are recorded as structured events in SQLite and read with `list_events` / `GET /api/events`; they are not mixed into chat streams.
 
@@ -132,7 +132,8 @@ n2n-nexus
   ├─ n2n-nexus daemon    Start once, keep running. Owns all data.
   ├─ n2n-nexus mcp       IDE starts automatically via npx. Stateless proxy.
   ├─ n2n-nexus hook      Run by Claude Code / Codex on each hook event.
-  └─ n2n-nexus install   Write the hooks and MCP server into a client's user configuration.
+  ├─ n2n-nexus install   Write the hooks and MCP server into a client's user configuration.
+  └─ n2n-nexus doctor    Check that the installed hook and MCP commands still run.
 ```
 
 **Daemon** (started by the user, or in the background by a hook or adapter when none listens at a local endpoint):

package/docs/ARCHITECTURE_zh.md

@@ -92,7 +92,7 @@ Stop                           ◀── decision: block   ◀─┘  每次结
 
 **SQLite WAL 模式**：只有 daemon 进程打开数据库。MCP 适配器不直接访问，全部经由 HTTP。
 
-**文件存储写入**：HTTP 请求是并发处理的，因此对 `registry.json`、manifest 和文档索引的每次修改都排在一把 daemon 级写锁后面，并以原子方式写入（临时文件 + rename）。
+**文件存储访问**：HTTP 请求是并发处理的，因此对 `registry.json`、manifest 和文档索引的每次修改都独占一把 daemon 级读写锁，并以原子方式写入（临时文件 + rename）；读取共享这把锁，所以不会读到改名或更新进行到一半的状态。写入时各文件按 `registry.json` 最后写的顺序进行，后一步失败就还原已写的文件。
 
 **活动日志**：经由 daemon 发生的状态变更（项目同步/重命名/删除、会议开始/结束、文档同步等）以结构化事件记录在 SQLite 中，通过 `list_events` / `GET /api/events` 读取，不混入聊天流。
 
@@ -132,7 +132,8 @@ n2n-nexus
   ├─ n2n-nexus daemon    启动一次，持续运行，持有所有数据。
   ├─ n2n-nexus mcp       IDE 通过 npx 自动启动，无状态代理。
   ├─ n2n-nexus hook      Claude Code / Codex 在每个 hook 事件时运行。
-  └─ n2n-nexus install   把 hooks 和 MCP 服务写进客户端的用户级配置。
+  ├─ n2n-nexus install   把 hooks 和 MCP 服务写进客户端的用户级配置。
+  └─ n2n-nexus doctor    检查已安装的 hook 和 MCP 命令是否还能运行。
 ```
 
 **Daemon**（由用户启动；本机地址上没有 daemon 时，也会由 hook 或适配器在后台拉起）：

package/docs/README_zh.md

@@ -114,6 +114,9 @@ n2n-nexus install codex     # ~/.codex/hooks.json（或 $CODEX_HOME）+ codex mc
 
 - Codex 只运行已信任的 hooks：打开 Codex，执行一次 `/hooks` 完成信任。
 - daemon 不在 `http://127.0.0.1:5688` 时，两条命令都加上 `--endpoint <url>`。
+- hooks 和 MCP 服务的命令里写的是 Node 的绝对路径，因为从 Dock 启动的 GUI 客户端（如 Claude 桌面版）不读取 shell 的 `PATH`。默认情况下，`PATH` 上的 `node` 与运行 `install` 的 Node 是同一个文件时，`install` 写入 `PATH` 上的路径（例如 `/usr/local/bin/node`、`/opt/homebrew/bin/node`、`~/.local/bin/node` 或版本管理工具的稳定入口），否则写入当前运行的 Node 的真实路径。`install` 会打印一行 `Node: <path>` 显示实际写入的路径。
+- 用 `--node <path>` 手动指定 Node 路径。路径必须存在、可执行，且版本满足 package.json 的 `engines`（`^22.14.0 || >=23.6.0`），否则 `install` 以退出码 1 退出，不写任何配置。
+- 升级 Node 后：如果 `install` 提示 Node 路径位于带版本号的目录（Homebrew `Cellar`、nvm、fnm、Volta、asdf、`node-v<版本>`），每次升级 Node 后都要重新运行 `n2n-nexus install <claude|codex>`，或用 `--node` 指定稳定路径。`n2n-nexus doctor [claude|codex]` 检查已安装的 hook 命令和 MCP 命令里的 Node 路径与入口脚本是否仍然存在、能否运行，有问题时以退出码 1 退出。
 - `n2n-nexus uninstall <claude|codex>` 删除 `install` 写入的 hooks 和 MCP 服务，配置里的其他内容不动。
 - 支持 Linux、WSL 和 macOS。其他 MCP 客户端可以使用除直接消息以外的全部工具。
 
@@ -234,9 +237,13 @@ n2n-nexus daemon [--port 5688] [--root ~/.n2n-nexus] [--host 127.0.0.1]
 NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
 
 # 为 Claude Code 或 Codex 安装 / 删除 hooks 和 MCP 服务
-n2n-nexus install <claude|codex> [--endpoint <url>]
+# --node <path>：写进客户端配置的 Node 可执行文件路径
+n2n-nexus install <claude|codex> [--endpoint <url>] [--node <path>]
 n2n-nexus uninstall <claude|codex>
 
+# 检查已安装的 hook 和 MCP 命令是否还能运行（有问题时退出码 1）
+n2n-nexus doctor [claude|codex]
+
 # hook 入口（由 install 写进客户端配置）
 n2n-nexus hook <claude|codex> [--endpoint <url>]
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n2n-nexus",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaboration.",
   "main": "build/index.js",
   "type": "module",

package/build/utils/async-mutex.js

@@ -1,36 +0,0 @@
-/**
- * Simple mutex lock for preventing concurrent file writes.
- * Ensures that only one write operation can happen at a time.
- */
-export class AsyncMutex {
-    locked = false;
-    queue = [];
-    async acquire() {
-        if (!this.locked) {
-            this.locked = true;
-            return;
-        }
-        return new Promise((resolve) => {
-            this.queue.push(resolve);
-        });
-    }
-    release() {
-        if (this.queue.length > 0) {
-            const next = this.queue.shift();
-            if (next)
-                next();
-        }
-        else {
-            this.locked = false;
-        }
-    }
-    async withLock(fn) {
-        await this.acquire();
-        try {
-            return await fn();
-        }
-        finally {
-            this.release();
-        }
-    }
-}