n2n-nexus 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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,187 @@
+/**
+ * `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 os from "node:os";
+import path from "node:path";
+import { HOOK_CLIENTS, MCP_SERVER_NAME, isHookClient } from "../daemon/hook-contract.js";
+import { pkg } from "../config/index.js";
+import { InstallError, VERSIONED_NODE_DIR, configFile, isOurs, parseVersion, readConfig, satisfiesEngines } from "./install.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");
+/** 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 InstallError(`${file} is not valid JSON (${error.message}).`);
+        }
+        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 };
+}
+/** 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,106 @@
 /**
- * `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";
 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 +182,10 @@ 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"];
 }
 /** Install or uninstall; prints what it did and returns the exit code. */
 export function runInstall(options) {
@@ -128,11 +199,12 @@ 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) {
@@ -148,10 +220,14 @@ export function runInstall(options) {
         catch {
             // Not registered yet (or already removed): nothing to undo.
         }
-        if (action === "install") {
-            const addArgs = mcpAddArgs(client, entry, endpoint);
+        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 +239,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/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/index.js

@@ -75,13 +75,27 @@ export class StorageManager {
     // --- Project Methods ---
     static getProjectDocs(id) { return 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,16 +103,7 @@ 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 ---

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 { toDict, writeFileAtomic, writeJsonAtomic } from "./fs-utils.js";
 const emptyRegistry = () => ({ projects: toDict() });
 async function readRegistry() {
     try {
@@ -233,39 +233,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/docs/ARCHITECTURE.md

@@ -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

@@ -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.1",
   "description": "Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaboration.",
   "main": "build/index.js",
   "type": "module",