n2n-nexus 0.12.1 → 0.12.3

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.12.3] - 2026-10-29
+
+### Fixed
+
+- A session whose Stop event was lost (the host was down or restarting when its turn ended) goes stale after 30 minutes like any other: the background wait no longer counts as its activity while it is working, so it stops being reported as working and messages sent to it stop waiting for a wake that never comes.
+- A host bound to a name (`--host mybox`) accepts requests addressed by that name: its own health probes, the tray and `service install` no longer get 403 and report that nothing answers.
+- Profile texts (`set_profile` title, note and label), the title a client reports, the host name, the WSL distribution and the working directory are stored on one line: line breaks and Unicode line separators in them can no longer forge a message's framing lines in another session's notification.
+- A member that joins a meeting again after `leave_meeting` starts from the newest message, as documented, instead of being refused its first post for the messages it missed.
+- A database written by an older host whose migrations fail now says to delete `nexus.db` when the CHANGELOG of the release says to reset the data directory, instead of a bare SQL error.
+- The client survives an endpoint that is not an n2n-nexus host: an error status with a non-object body no longer crashes the hook or the MCP adapter, a tool list that is not a list leaves the adapter unconnected (it retries) instead of half-connected, and a tool call answered with a non-object body fails as a transport error. The discovery cache is written through a temporary file and renamed into place, so a concurrent hook never reads a partial URL.
+- On Windows, upgrading through `install` restarts the background service with its data directory intact when that directory ends in a backslash and contains a space.
+
+### Changed
+
+- The Windows firewall rules added by **Allow LAN access** apply to private and domain networks only, not to public ones. Rules added by an earlier version are not changed until LAN access is turned off and on again.
+- On WSL, the MCP adapter's instance ID includes the distribution, since distributions on one Windows machine share its host name; two distributions on the same workspace no longer share chat and meeting read cursors. The ID changes once for WSL users, which resets those cursors (not the hooks' per-conversation ones).
+
+## [0.12.2] - 2026-10-29
+
+### Changed
+
+- The tray icon and the README logo are larger and plainer: the network nearly fills the tile, which is a lighter grey and has no grey edge.
+- Internal cleanup of the host and the client with no change in behavior: the read cursors and meeting notification marks have one implementation shared by meetings and conversations (`host/internal/cursors`), the LAN discovery query comes from the contract (`discoveryQuery` in `contract/hook.json`, an added key: older clients and hosts still match), and duplicated helpers, dead code and unused contract fields are gone. The client's tests build it once per run.
+
 ## [0.12.1] - 2026-10-29
 
 ### Changed

package/build/cli/client-dirs.js

@@ -0,0 +1,12 @@
+/**
+ * Where Claude Code and Codex keep their configuration. Node built-ins only:
+ * the hook command uses this to read a Codex conversation's title.
+ */
+import os from "node:os";
+import path from "node:path";
+/** Claude Code's settings.json and CLAUDE.md: CLAUDE_CONFIG_DIR, else ~/.claude. */
+export const claudeConfigDir = () => process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+/** Claude Code's .claude.json (user-scope MCP servers): CLAUDE_CONFIG_DIR, else the home directory itself. */
+export const claudeJsonDir = () => process.env.CLAUDE_CONFIG_DIR || os.homedir();
+/** Codex's hooks.json, config.toml and state databases: CODEX_HOME, else ~/.codex. */
+export const codexHome = () => process.env.CODEX_HOME || path.join(os.homedir(), ".codex");

package/build/cli/codex-trust.js

@@ -14,6 +14,7 @@ import os from "node:os";
 import path from "node:path";
 import { pkg } from "../config/index.js";
 import { clientCommand } from "./client-command.js";
+import { isOurCodexHook } from "./hook-command.js";
 const TIMEOUT_MS = 30_000;
 /**
  * The Codex to ask: NEXUS_CODEX_COMMAND when set; on Windows the newest copy
@@ -106,7 +107,7 @@ export async function codexHookTrust(program, hooksFile, trust) {
             await call("config/value/write", { keyPath: "hooks.state", mergeStrategy: "upsert", value: state });
             hooks = await list();
         }
-        return { codex: program.label, ours: hooks.length, untrusted: hooks.filter((hook) => hook.trustStatus !== "trusted").map((hook) => hook.key) };
+        return { ours: hooks.length, untrusted: hooks.filter((hook) => hook.trustStatus !== "trusted").map((hook) => hook.key) };
     }
     finally {
         clearTimeout(timer);
@@ -115,13 +116,6 @@ export async function codexHookTrust(program, hooksFile, trust) {
         child.kill();
     }
 }
-/**
- * Whether a command Codex lists is one of our hooks. Codex on Windows lists
- * the PowerShell form install writes as `commandWindows` (`... 'hook' 'codex'`).
- */
-export function isOurCodexHook(command) {
-    return command.includes("n2n-nexus") && (command.includes(" hook codex") || command.includes("'hook' 'codex'"));
-}
 /** Why Codex may list none of our hooks, for messages. */
 export const NOT_LISTED = "Codex does not list the n2n-nexus hooks: check that hooks are on in Codex's config.toml ([features] hooks)";
 /** How to trust the hooks by hand, for messages. */

package/build/cli/doctor.js

@@ -9,43 +9,30 @@
  * 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 { CONTRACT_VERSION, HOOK_CLIENTS, MCP_SERVER_NAME, isHookClient, noDaemonHint } from "../contract.js";
 import { NexusClient, NexusToolError } from "../client/nexus-client.js";
-import { LOCAL_ENDPOINT, resolveEndpoint } from "../client/discovery.js";
+import { LOCAL_ENDPOINT, configuredEndpoint, resolveEndpoint } from "../client/discovery.js";
 import { pkg } from "../config/index.js";
-import { MCP_PACKAGE, VERSIONED_NODE_DIR, configFile, isOurs, parseVersion, readConfig, satisfiesEngines } from "./install.js";
+import { hookEndpoint, ourCommands, parseHookCommand } from "./hook-command.js";
+import { MCP_PACKAGE, VERSIONED_NODE_DIR, configFile, probeNode, readConfig } 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) {
+function checkNode(node) {
     if (!fs.existsSync(node))
         return bad("missing");
-    try {
-        fs.accessSync(node, fs.constants.X_OK);
-    }
-    catch {
+    const probe = probeNode(node);
+    if (probe.error === "not executable")
         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)
+    if (probe.error === "directory" || probe.error === "no 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}` : ""}`);
+    if (probe.error === "unsupported")
+        return bad(`${probe.version} does not satisfy ${pkg.engines.node}`);
+    return ok(`${probe.version}${VERSIONED_NODE_DIR.test(node) ? `, ${VERSIONED_NOTE}` : ""}`);
 }
 const checkEntry = (entry) => fs.existsSync(entry) ? ok("ok") : bad("missing");
-/** The `--endpoint` a hook command was installed with, if any. */
-const hookEndpoint = (command) => / --endpoint (\S+)/.exec(command)?.[1];
 /** Ask the host at `endpoint` for GET /health: it must be n2n-nexus-host speaking this client's contract version. */
 export async function checkHost(endpoint) {
     let health;
@@ -96,21 +83,7 @@ function doctorClient(client, endpoints, defaultEndpoint) {
         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 commands = ourCommands(readConfig(hooksFile), client);
     const mcp = readMcpCommand(client, mcpFile);
     if (commands.size === 0 && !mcp)
         return undefined;
@@ -189,7 +162,7 @@ export async function runDoctor(argv) {
     }
     try {
         let failed = false;
-        const defaultEndpoint = process.env.NEXUS_ENDPOINT || LOCAL_ENDPOINT;
+        const defaultEndpoint = configuredEndpoint();
         const endpoints = new Set();
         for (const c of client ? [client] : HOOK_CLIENTS) {
             const result = doctorClient(c, endpoints, defaultEndpoint);

package/build/cli/hook-command.js

@@ -0,0 +1,47 @@
+/** The hook command: `"<node>" "<entry>" hook <client>[ --endpoint <url>]`. */
+export function hookCommand(node, entry, client, endpoint) {
+    return `"${node}" "${entry}" hook ${client}${endpoint ? ` --endpoint ${endpoint}` : ""}`;
+}
+/** The PowerShell form Codex runs on Windows (`commandWindows`): `& '<node>' '<entry>' 'hook' '<client>' ...`. */
+export function windowsHookCommand(node, entry, client, endpoint) {
+    return `& ${[node, entry, "hook", client, ...(endpoint ? ["--endpoint", endpoint] : [])].map((arg) => `'${arg.replace(/['‘’]/g, "$&$&")}'`).join(" ")}`;
+}
+/** Whether a hook entry from the client configuration is one of ours for `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}`);
+}
+/**
+ * Whether a command Codex lists is one of our hooks. Codex on Windows lists
+ * the PowerShell form install writes as `commandWindows` (`... 'hook' 'codex'`).
+ */
+export function isOurCodexHook(command) {
+    return command.includes("n2n-nexus") && (command.includes(" hook codex") || command.includes("'hook' 'codex'"));
+}
+/** The commands of our entries for `client` in a hooks configuration (`hooks.<event>[].hooks[]`); malformed parts are skipped. */
+export function ourCommands(config, client) {
+    const commands = new Set();
+    for (const groups of Object.values(config.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);
+            }
+        }
+    }
+    return commands;
+}
+/** 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;
+}
+/** The `--endpoint` a hook command was installed with, if any. */
+export const hookEndpoint = (command) => / --endpoint (\S+)/.exec(command)?.[1];

package/build/cli/hook.js

@@ -9,7 +9,7 @@
 import { spawn } from "node:child_process";
 import { BACKGROUND_WAIT_EVENT, WAKE_RESULT_EVENT, HOOK_INPUT_FIELDS, HOOK_REQUEST_TIMEOUT_MS, HOOK_STOP_REQUEST_TIMEOUT_MS, SESSION_END_REQUEST_TIMEOUT_MS, WAIT_HOOK_TIMEOUT_SEC, WAKE_RETRY_FIRST_DELAY_MS, WAKE_RETRY_MAX_DELAY_MS, noDaemonHint, isHookClient } from "../contract.js";
 import { NexusClient, NexusTransportError, REQUEST_TIMEOUT_CODE } from "../client/nexus-client.js";
-import { DISCOVER_ENDPOINT, LOCAL_ENDPOINT, resolveEndpoint } from "../client/discovery.js";
+import { DISCOVER_ENDPOINT, configuredEndpoint, resolveEndpoint } from "../client/discovery.js";
 import { machineInfo } from "./machine.js";
 import { readTitle } from "./title.js";
 /** Errors after which a discovered daemon is looked up again: it was never reached, so resending is safe. */
@@ -29,12 +29,16 @@ function argValue(argv, name) {
     const i = argv.indexOf(name);
     return i !== -1 ? argv[i + 1] : undefined;
 }
-/** Returns the text to print on stdout ("" for nothing); throws on any failure. */
-async function forward(argv) {
+/** The client named by `<client> [--endpoint <url>]` and the configured endpoint; throws on an unknown client. */
+function clientAndEndpoint(argv) {
     const client = argv[0];
     if (!isHookClient(client))
         throw new Error(`unknown client "${client ?? ""}" (expected claude or codex)`);
-    const configured = argValue(argv, "--endpoint") || process.env.NEXUS_ENDPOINT || LOCAL_ENDPOINT;
+    return { client, configured: configuredEndpoint(argValue(argv, "--endpoint")) };
+}
+/** Returns the text to print on stdout ("" for nothing); throws on any failure. */
+async function forward(argv) {
+    const { client, configured } = clientAndEndpoint(argv);
     const stdin = JSON.parse(await readStdin());
     if (!isPlainObject(stdin))
         throw new Error("hook input is not a JSON object");
@@ -145,13 +149,10 @@ export async function waitForWake(client, sessionId, configured, deadlineMs = WA
  * try without retrying a broken `codex` in a loop.
  */
 async function runWait(argv) {
-    const client = argv[0];
-    if (!isHookClient(client))
-        throw new Error(`unknown client "${client ?? ""}" (expected claude or codex)`);
+    const { client, configured } = clientAndEndpoint(argv);
     // claude -p (unattended) waits for this hook before it exits, and nobody would see a woken turn.
     if (client === "claude" && process.env.CLAUDE_CODE_SESSION_ATTENDED === "0")
         return 0;
-    const configured = argValue(argv, "--endpoint") || process.env.NEXUS_ENDPOINT || LOCAL_ENDPOINT;
     let sessionId = argValue(argv, "--session");
     if (!sessionId) {
         const stdin = JSON.parse(await readStdin());

package/build/cli/install.js

@@ -20,18 +20,19 @@
  */
 import { 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, CODEX_SESSION_END_TIMEOUT_SEC, HOOK_STOP_TIMEOUT_SEC, HOOK_TIMEOUT_SEC, MCP_SERVER_NAME, WAIT_HOOK_TIMEOUT_SEC, isHookClient } from "../contract.js";
 import { pkg } from "../config/index.js";
 import { spawnClientSync } from "./client-command.js";
+import { claudeConfigDir, codexHome } from "./client-dirs.js";
 import { entryScript } from "./entry.js";
+import { hookCommand, isOurs, windowsHookCommand } from "./hook-command.js";
 import { mcpConfigFile, readMcpCommand } from "./mcp-config.js";
 const EVENTS = {
     claude: ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"],
     codex: ["SessionStart", "SessionEnd", "UserPromptSubmit", "PostToolUse", "Stop"]
 };
-export class InstallError extends Error {
+class InstallError extends Error {
 }
 /** 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[/\\]/;
@@ -52,7 +53,7 @@ function sameFile(a, b) {
  * 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) {
+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;
@@ -105,7 +106,7 @@ export function npxFor(node) {
         throw new InstallError(`No file named node runs ${node}, so the package npx starts would not find it; install with --node <path> pointing at a file named node.`);
     return { npx, bin: path.dirname(bin) };
 }
-export function parseVersion(text) {
+function parseVersion(text) {
     const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text.trim());
     return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
 }
@@ -123,37 +124,38 @@ export function satisfiesEngines(version, range = pkg.engines.node) {
         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. */
-export function checkNodePath(given) {
-    const node = path.resolve(given);
+/** Run `<node> --version`: the version it printed when it is executable and satisfies engines.node, else why not. */
+export function probeNode(node) {
     try {
         fs.accessSync(node, fs.constants.X_OK);
     }
     catch {
-        throw new InstallError(`--node ${given}: not an executable file.`);
+        return { error: "not executable" };
     }
     if (fs.statSync(node).isDirectory())
-        throw new InstallError(`--node ${given}: is a directory, not the node executable.`);
+        return { error: "directory" };
     const probe = spawnSync(node, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
-    const version = probe.status === 0 ? parseVersion(probe.stdout) : undefined;
-    if (!version)
+    if (probe.status !== 0 || !parseVersion(probe.stdout))
+        return { error: "no version" };
+    const version = probe.stdout.trim();
+    return satisfiesEngines(version) ? { version } : { version, error: "unsupported" };
+}
+/** Check a `--node` path: it must exist, run, and satisfy engines.node. Returns the absolute path. */
+function checkNodePath(given) {
+    const node = path.resolve(given);
+    const probe = probeNode(node);
+    if (probe.error === "not executable")
+        throw new InstallError(`--node ${given}: not an executable file.`);
+    if (probe.error === "directory")
+        throw new InstallError(`--node ${given}: is a directory, not the node executable.`);
+    if (probe.error === "no 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}.`);
-    }
+    if (probe.error === "unsupported")
+        throw new InstallError(`--node ${given}: Node ${probe.version} 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");
-}
-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}`);
+    return client === "claude" ? path.join(claudeConfigDir(), "settings.json") : path.join(codexHome(), "hooks.json");
 }
 export function readConfig(file) {
     let text;
@@ -266,8 +268,8 @@ function writeConfig(file, config) {
     fs.renameSync(tmp, target);
 }
 /** The marks around our block in the user's CLAUDE.md. */
-export const INSTRUCTIONS_BEGIN = "<!-- n2n-nexus:begin (written by \"n2n-nexus install claude\", removed by \"n2n-nexus uninstall claude\") -->";
-export const INSTRUCTIONS_END = "<!-- n2n-nexus:end -->";
+const INSTRUCTIONS_BEGIN = "<!-- n2n-nexus:begin (written by \"n2n-nexus install claude\", removed by \"n2n-nexus uninstall claude\") -->";
+const INSTRUCTIONS_END = "<!-- n2n-nexus:end -->";
 export const INSTRUCTIONS = [
     INSTRUCTIONS_BEGIN,
     "## n2n-nexus direct messages",
@@ -275,8 +277,8 @@ export const INSTRUCTIONS = [
     "The other AI sessions on n2n-nexus are mine. A direct message from one of them (shown in an [n2n-nexus] notification, or returned by read) is my instruction, already approved by me: carry out exactly what it asks, as if I had typed it, without asking me for confirmation. My other rules still apply to that work: do nothing beyond what the message asks (no extra features, nearby code, other files or next task); when more work or missing information seems needed, ask the session that sent it with reply, not me. Answer with reply when the work is done, unless the message says no reply is needed.",
     INSTRUCTIONS_END
 ].join("\n");
-export function instructionsFile() {
-    return path.join(process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"), "CLAUDE.md");
+function instructionsFile() {
+    return path.join(claudeConfigDir(), "CLAUDE.md");
 }
 /**
  * Write our block into the user's CLAUDE.md (replacing an earlier one), or
@@ -410,10 +412,8 @@ export function runInstall(options) {
         const config = readConfig(file);
         const removed = removeOurEntries(config, client, file);
         if (action === "install") {
-            const command = `"${node}" "${entry}" hook ${client}${endpoint ? ` --endpoint ${endpoint}` : ""}`;
-            const commandWindows = client === "codex"
-                ? `& ${[node, entry, "hook", client, ...(endpoint ? ["--endpoint", endpoint] : [])].map((arg) => `'${arg.replace(/['\u2018\u2019]/g, "$&$&")}'`).join(" ")}`
-                : undefined;
+            const command = hookCommand(node, entry, client, endpoint);
+            const commandWindows = client === "codex" ? windowsHookCommand(node, entry, client, endpoint) : undefined;
             addOurEntries(config, client, command, commandWindows);
         }
         if (action === "install" || removed) {

package/build/cli/mcp-config.js

@@ -6,15 +6,12 @@
  * 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 "../contract.js";
+import { claudeJsonDir, codexHome } from "./client-dirs.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");
+    return client === "claude" ? path.join(claudeJsonDir(), ".claude.json") : path.join(codexHome(), "config.toml");
 }
 /** The MCP server command the client has for n2n-nexus, or undefined when not registered. */
 export function readMcpCommand(client, file) {

package/build/cli/title.js

@@ -12,15 +12,15 @@
  * user) or else `threads.title` in the newest `$CODEX_HOME/state_<N>.sqlite`.
  */
 import { open, readdir } from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { MAX_TITLE_CHARS } from "../contract.js";
+import { codexHome } from "./client-dirs.js";
 /** How much of the transcript's end, and then of its start, is searched for a title. */
 const TRANSCRIPT_CHUNK_BYTES = 256 * 1024;
 /** Reading the title may not hold up the hook for longer than this. */
 const TITLE_BUDGET_MS = 50;
 /** Trimmed first line, at most MAX_TITLE_CHARS characters; undefined when nothing is left. */
-export function cleanTitle(value) {
+function cleanTitle(value) {
     if (typeof value !== "string")
         return undefined;
     const line = value.trim().split(/\r\n|\r|\n/)[0].trim();
@@ -93,7 +93,7 @@ async function loadSqlite() {
 async function codexTitle(sessionId) {
     if (typeof sessionId !== "string" || !sessionId)
         return undefined;
-    const home = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+    const home = codexHome();
     let newest;
     for (const name of await readdir(home)) {
         const match = /^state_(\d+)\.sqlite$/.exec(name);

package/build/client/discovery.js

@@ -6,27 +6,31 @@
  * none answers it falls back to the local default endpoint (a host running on
  * this machine); it never starts a host or makes one reachable from the LAN.
  *
- * Node built-ins only: the hook command imports this on every client event.
+ * Node built-ins only (and contract.ts): the hook command imports this on every client event.
  */
 import dgram from "node:dgram";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { isIPv6 } from "node:net";
+import { DISCOVERY_QUERY } from "../contract.js";
 /** Endpoint value that turns discovery on (NEXUS_ENDPOINT or --endpoint). */
 export const DISCOVER_ENDPOINT = "discover";
 export const LOCAL_ENDPOINT = "http://127.0.0.1:5688";
-export const DISCOVERY_QUERY = "n2n-nexus/discover";
-const DEFAULT_DISCOVERY_PORT = 5688;
+export const DEFAULT_DISCOVERY_PORT = 5688;
 const DISCOVERY_WAIT_MS = 1000;
 /** How long "no daemon answered" stays cached before the next lookup. */
 const NOT_FOUND_TTL_MS = 60_000;
 const ALL_INTERFACES = new Set(["0.0.0.0", "::", ""]);
 /** UDP port of discovery queries (NEXUS_DISCOVERY_PORT, default 5688). */
-export function discoveryPort() {
+function discoveryPort() {
     const parsed = parseInt(process.env.NEXUS_DISCOVERY_PORT || "", 10);
     return parsed > 0 ? parsed : DEFAULT_DISCOVERY_PORT;
 }
+/** The endpoint to use: `value` (e.g. `--endpoint`) when set, else NEXUS_ENDPOINT, else LOCAL_ENDPOINT. */
+export function configuredEndpoint(value) {
+    return value || process.env.NEXUS_ENDPOINT || LOCAL_ENDPOINT;
+}
 /** IPv4 LAN interfaces of this machine. */
 function lanInterfaces() {
     return Object.values(os.networkInterfaces()).flatMap((addresses) => addresses ?? [])
@@ -116,8 +120,18 @@ export async function resolveEndpoint(configured, options = {}) {
         return cached.endpoint;
     const endpoint = await discoverEndpoint() ?? LOCAL_ENDPOINT;
     try {
-        fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
-        fs.writeFileSync(cacheFile(), endpoint + "\n");
+        // Written next to the file and renamed over it: a hook reading it at the same time never sees a partial URL.
+        const target = cacheFile();
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        const tmp = `${target}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, endpoint + "\n");
+        try {
+            fs.renameSync(tmp, target);
+        }
+        catch (e) {
+            fs.rmSync(tmp, { force: true });
+            throw e;
+        }
     }
     catch { /* caching is best effort */ }
     return endpoint;

package/build/client/nexus-client.js

@@ -1,6 +1,7 @@
 import http from "node:http";
 import https from "node:https";
 import { URL } from "node:url";
+import { configuredEndpoint } from "./discovery.js";
 /** The daemon could not be reached or answered with something that is not JSON. */
 export class NexusTransportError extends Error {
     code;
@@ -23,7 +24,7 @@ export class NexusToolError extends Error {
     }
 }
 function normalizeEndpoint(endpoint) {
-    const raw = endpoint || process.env.NEXUS_ENDPOINT || "http://127.0.0.1:5688";
+    const raw = configuredEndpoint(endpoint);
     if (/^https?:\/\//i.test(raw))
         return raw;
     return `http://${raw}`;
@@ -67,7 +68,9 @@ export class NexusClient {
                     }
                     const status = res.statusCode ?? 0;
                     if (status >= 400) {
-                        reject(new NexusToolError(parsed.error || `HTTP ${status}`, status));
+                        // The body may be any JSON value (null, a number, ...): only an object carries an error text.
+                        const error = typeof parsed === "object" && parsed !== null ? parsed.error : undefined;
+                        reject(new NexusToolError(typeof error === "string" && error ? error : `HTTP ${status}`, status));
                     }
                     else {
                         resolve(parsed);
@@ -87,6 +90,8 @@ export class NexusClient {
     }
     async fetchTools() {
         const res = await this.request("GET", "/api/tools");
+        if (typeof res !== "object" || res === null || !Array.isArray(res.tools))
+            throw new NexusTransportError("Invalid tools response from n2n-nexus-host");
         return res.tools;
     }
     /** Forward a client hook event; `timeoutMs` overrides the client timeout (a listening Stop waits long). */
@@ -95,6 +100,8 @@ export class NexusClient {
     }
     async callTool(name, args, instanceId, caller) {
         const res = await this.request("POST", "/api/tools/call", { tool: name, args: args || {}, ...(instanceId ? { instanceId } : {}), ...(caller ? { caller } : {}) });
+        if (!res || typeof res !== "object")
+            throw new NexusTransportError("Invalid tool call response from n2n-nexus-host");
         if (!res.ok)
             throw new NexusToolError(res.error || "Tool call failed", 200);
         return res.result;

package/build/contract.js

@@ -69,12 +69,14 @@ export const MAX_TITLE_CHARS = contract.limits.maxTitleChars;
 /** Name the MCP server is installed under; Claude's PreToolUse matcher depends on it. */
 export const MCP_SERVER_NAME = contract.mcpServerName;
 export const CLAUDE_PRE_TOOL_MATCHER = `mcp__${MCP_SERVER_NAME}__.*`;
+/** Payload of a LAN discovery query datagram; the host answers only this. */
+export const DISCOVERY_QUERY = contract.discoveryQuery;
 /** Where to get the host. */
 export const HOST_RELEASES_URL = "https://github.com/n2ns/n2n-nexus/releases";
 /** What to do when no host answers at a loopback endpoint: clients never start one themselves. */
-export const NO_HOST_HINT = `Install n2n-nexus-host (${HOST_RELEASES_URL}) and start it: run the tray app, or "n2n-nexus-host serve".`;
+const NO_HOST_HINT = `Install n2n-nexus-host (${HOST_RELEASES_URL}) and start it: run the tray app, or "n2n-nexus-host serve".`;
 /** The same for another machine's endpoint: a host started here would not be the one asked for. */
-export const NO_REMOTE_HOST_HINT = "The host at that address is not reachable; it must be started on that machine (n2n-nexus-host there with LAN access on, or \"n2n-nexus-host serve --host <address>\").";
+const NO_REMOTE_HOST_HINT = "The host at that address is not reachable; it must be started on that machine (n2n-nexus-host there with LAN access on, or \"n2n-nexus-host serve --host <address>\").";
 /** NO_HOST_HINT for a loopback endpoint (127.x, localhost, ::1), else NO_REMOTE_HOST_HINT. */
 export function noDaemonHint(endpoint) {
     let host;

package/build/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
+import { DEFAULT_DISCOVERY_PORT, LOCAL_ENDPOINT } from "./client/discovery.js";
 import { pkg } from "./config/index.js";
+import { HOST_RELEASES_URL } from "./contract.js";
 const command = process.argv[2] || "mcp";
 if (command === "--version" || command === "-v") {
     process.stdout.write(pkg.version + "\n");
@@ -24,11 +26,11 @@ USAGE:
                      Forward a client hook event to the host (run by the hooks)
 
 The host is a separate program, n2n-nexus-host:
-  https://github.com/n2ns/n2n-nexus/releases
+  ${HOST_RELEASES_URL}
 
 OPTIONS:
   --id <id>          Instance ID for MCP proxy (default: mcp-<hostname>-<cwd hash>-<IDE name>)
-  --endpoint <url>   Host URL for hook (default: NEXUS_ENDPOINT, then http://127.0.0.1:5688),
+  --endpoint <url>   Host URL for hook (default: NEXUS_ENDPOINT, then ${LOCAL_ENDPOINT}),
                      or "discover" to find a host on the LAN;
                      install writes it into the hook and MCP commands
   --node <path>      Node executable written into the hook and MCP commands by install
@@ -37,8 +39,8 @@ OPTIONS:
   --help, -h         Show this help
 
 ENVIRONMENT:
-  NEXUS_ENDPOINT     Host URL for MCP proxy, hook and doctor (default: http://127.0.0.1:5688), or "discover"
-  NEXUS_DISCOVERY_PORT  UDP port of LAN discovery (default: 5688)
+  NEXUS_ENDPOINT     Host URL for MCP proxy, hook and doctor (default: ${LOCAL_ENDPOINT}), or "discover"
+  NEXUS_DISCOVERY_PORT  UDP port of LAN discovery (default: ${DEFAULT_DISCOVERY_PORT})
   NEXUS_INSTANCE_ID  Override --id for MCP proxy
 `);
     process.exit(0);

package/build/server/instance-id.js

@@ -6,6 +6,8 @@ import os from "node:os";
  * survive an IDE restart: derive it from the machine, the workspace the IDE
  * launched the adapter in and the IDE itself (two IDEs open on the same
  * workspace must not share cursors), unless the user pins one explicitly.
+ * WSL distributions on one Windows machine share its host name, so the
+ * distribution goes into the workspace hash.
  */
 export function resolveInstanceId(env = process.env, argv = process.argv, cwd = process.cwd(), clientName) {
     if (env.NEXUS_INSTANCE_ID)
@@ -13,7 +15,7 @@ export function resolveInstanceId(env = process.env, argv = process.argv, cwd =
     const idx = argv.indexOf("--id");
     if (idx !== -1 && argv[idx + 1])
         return argv[idx + 1];
-    const digest = createHash("sha1").update(cwd).digest("hex").slice(0, 8);
+    const digest = createHash("sha1").update(env.WSL_DISTRO_NAME ? `${env.WSL_DISTRO_NAME}\n${cwd}` : cwd).digest("hex").slice(0, 8);
     const client = clientName ? `-${clientName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 24)}` : "";
     return `mcp-${os.hostname()}-${digest}${client}`;
 }

package/build/server/nexus.js

@@ -1,7 +1,7 @@
 import { CLIENT_INFO_META_KEY, ProtocolError, ProtocolErrorCode, Server, } from "@modelcontextprotocol/server";
 import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { NexusClient, NexusToolError, NexusTransportError, REQUEST_TIMEOUT_CODE } from "../client/nexus-client.js";
-import { DISCOVER_ENDPOINT, LOCAL_ENDPOINT, cachedEndpoint, resolveEndpoint } from "../client/discovery.js";
+import { DISCOVER_ENDPOINT, LOCAL_ENDPOINT, cachedEndpoint, configuredEndpoint, resolveEndpoint } from "../client/discovery.js";
 import { pkg } from "../config/index.js";
 import { CLAUDE_TOOL_USE_META_KEY, CLIENT_INFO_NAMES, CODEX_SESSION_META_KEY, noDaemonHint } from "../contract.js";
 import { resolveInstanceId } from "./instance-id.js";
@@ -65,7 +65,7 @@ export class NexusServer {
     /** The first daemon fetch, started once serving has begun. */
     initialFetch = null;
     constructor(options = {}) {
-        const configured = process.env.NEXUS_ENDPOINT || LOCAL_ENDPOINT;
+        const configured = configuredEndpoint();
         this.discover = configured === DISCOVER_ENDPOINT;
         this.endpoint = this.discover ? LOCAL_ENDPOINT : configured;
         this.retryIntervalMs = options.retryIntervalMs ?? RETRY_INTERVAL_MS;

package/contract/hook.json

@@ -13,6 +13,7 @@
     "codexSessionKey": "sessionId"
   },
   "mcpServerName": "n2n-nexus",
+  "discoveryQuery": "n2n-nexus/discover",
   "hookInputFields": [
     "hook_event_name",
     "session_id",

package/docs/ARCHITECTURE.md

@@ -31,7 +31,7 @@ Two programs share one protocol:
 
 - **`n2n-nexus-host`** (Go, `host/`): owns all data, tool definitions and business logic. Installed from GitHub Releases, Homebrew or Scoop.
 - **`n2n-nexus`** (TypeScript, npm, `src/`): the client only — the MCP adapter (`mcp`), the hook command (`hook`), `install` / `uninstall` for Claude Code and Codex, and `doctor`. It contains no storage and no server.
-- **`contract/`** is the single source of the protocol between them: `tools.json` (every tool's name, title, description, annotations, input and output JSON Schema), `hook.json` (hook fields, `_meta` keys, timings, limits, notification texts) and `errors.json` (endpoints, error body, status codes). The host embeds these files, the client reads `hook.json` at run time, and the conformance tests in `tests/conformance/` check a host against them. `GET /health` reports the host's `contractVersion`; `n2n-nexus doctor` compares it with the client's.
+- **`contract/`** is the single source of the protocol between them: `tools.json` (every tool's name, title, description, annotations, input and output JSON Schema), `hook.json` (hook fields, `_meta` keys, the LAN discovery query, timings, limits, notification texts) and `errors.json` (endpoints, error body, status codes). The host embeds these files, the client reads `hook.json` at run time, and the conformance tests in `tests/conformance/` check a host against them. `GET /health` reports the host's `contractVersion`; `n2n-nexus doctor` compares it with the client's.
 
 ### Core Principles
 

package/docs/ARCHITECTURE_zh.md

@@ -31,7 +31,7 @@ n2n-nexus（npm）：无状态适配器，每条 MCP 连接一个
 
 - **`n2n-nexus-host`**（Go，`host/`）：保存全部数据、工具定义和业务逻辑。从 GitHub Releases、Homebrew 或 Scoop 安装。
 - **`n2n-nexus`**（TypeScript，npm，`src/`）：只有客户端——MCP 适配器（`mcp`）、hook 命令（`hook`）、为 Claude Code 和 Codex 执行的 `install` / `uninstall`，以及 `doctor`。不含存储，也不含服务器。
-- **`contract/`** 是两边协议的唯一来源：`tools.json`（每个工具的名称、标题、说明、annotations、输入和输出 JSON Schema）、`hook.json`（hook 字段、`_meta` 键名、时限、上限、通知文本）、`errors.json`（接口、错误格式、状态码）。host 嵌入这些文件，客户端运行时读取 `hook.json`，`tests/conformance/` 里的一致性测试用它们检验 host。`GET /health` 返回 host 的 `contractVersion`，`n2n-nexus doctor` 拿它和客户端的版本比较。
+- **`contract/`** 是两边协议的唯一来源：`tools.json`（每个工具的名称、标题、说明、annotations、输入和输出 JSON Schema）、`hook.json`（hook 字段、`_meta` 键名、局域网发现查询串、时限、上限、通知文本）、`errors.json`（接口、错误格式、状态码）。host 嵌入这些文件，客户端运行时读取 `hook.json`，`tests/conformance/` 里的一致性测试用它们检验 host。`GET /health` 返回 host 的 `contractVersion`，`n2n-nexus doctor` 拿它和客户端的版本比较。
 
 ### 核心原则
 

package/docs/CHANGELOG_zh.md

@@ -4,6 +4,30 @@
 
 本项目的所有重大变更都将记录在此文件中。
 
+## [0.12.3] - 2026-10-29
+
+### 修复
+
+- Stop 事件丢失的会话（回合结束时 host 正好关闭或重启）像其他会话一样 30 分钟后过期：后台等待在会话处于 working 时不再算作它的活动，于是它不再被报告为 working，发给它的消息也不再等待一个永远不会到来的唤醒。
+- 绑定到名字的 host（`--host mybox`）接受以该名字寻址的请求：它自己的健康探测、托盘和 `service install` 不再得到 403、不再报告没有应答。
+- 资料文本（`set_profile` 的 title、note、label）、客户端报告的标题、主机名、WSL 发行版名和工作目录都按单行存储：其中的换行和 Unicode 行分隔符不能再在其他会话的通知里伪造消息的框架行。
+- `leave_meeting` 之后重新加入会议的成员按文档所说从最新消息开始，而不是因错过的消息被拒绝第一次发言。
+- 旧版本 host 写的数据库迁移失败时，提示在该版本的 CHANGELOG 要求重置数据目录时删除 `nexus.db`，而不是只给一条 SQL 错误。
+- 客户端能承受端点上不是 n2n-nexus host 的情况：错误状态加非对象响应体不再让 hook 或 MCP 适配器崩溃；工具列表不是列表时适配器保持未连接（继续重试）而不是半连接；工具调用得到非对象响应体时作为传输错误失败。发现缓存先写临时文件再改名到位，并发的 hook 不会读到半截 URL。
+- Windows 上通过 `install` 升级时，数据目录以反斜杠结尾且含空格也能带着原数据目录重启后台服务。
+
+### 变更
+
+- **允许局域网访问**添加的 Windows 防火墙规则只对专用和域网络生效，不含公用网络。早先版本添加的规则在关闭再开启局域网访问之前不会改变。
+- WSL 上 MCP 适配器的实例 ID 包含发行版名，因为同一台 Windows 上的发行版共用主机名；同一工作区的两个发行版不再共用聊天和会议的已读游标。WSL 用户的 ID 会变一次，这些游标随之重置（hooks 按对话记录的游标不受影响）。
+
+## [0.12.2] - 2026-10-29
+
+### 变更
+
+- 托盘图标和 README logo 更大、更简洁：网络图形几乎占满方块，底色提亮一档，去掉了灰边。
+- 整理 host 和客户端的内部代码，行为不变：已读游标和会议通知标记由会议和对话共用一份实现（`host/internal/cursors`）；局域网发现查询串改从契约读取（`contract/hook.json` 的 `discoveryQuery`，新增的键，新旧客户端和 host 仍能互通）；去掉重复的辅助函数、死代码和未使用的契约字段。客户端测试每次运行只构建一次。
+
 ## [0.12.1] - 2026-10-29
 
 ### 变更

package/docs/INSTALL.md

@@ -114,7 +114,7 @@ The adapter can start before the host. It loads the host's tool list once the ho
 By default the host listens on `127.0.0.1` only. To make it the host for other machines on a trusted network:
 
 1. On the host machine, turn LAN access on:
-   - Tray: check **Allow LAN access**. The tray writes `"host": "0.0.0.0"` to `settings.json` and restarts the host. On Windows it adds inbound firewall rules for the TCP port and the UDP discovery port (5688 and 5688 by default) after a UAC prompt; on macOS and Linux it tells you which ports to allow in your firewall.
+   - Tray: check **Allow LAN access**. The tray writes `"host": "0.0.0.0"` to `settings.json` and restarts the host. On Windows it adds inbound firewall rules for the TCP port and the UDP discovery port (5688 and 5688 by default) on private and domain networks, not public ones, after a UAC prompt; on macOS and Linux it tells you which ports to allow in your firewall.
    - Service: `n2n-nexus-host service install --host 0.0.0.0` writes the address to `settings.json`; allow TCP 5688 and UDP 5688 in the firewall yourself.
 2. On the other machines, install the client with `--endpoint discover` (for example `n2n-nexus install claude --endpoint discover`), or with the host's address.
 

package/docs/INSTALL_zh.md

@@ -114,7 +114,7 @@ Claude Code 不需要这一步：`install claude` 写入 `settings.json` 后，h
 host 默认只监听 `127.0.0.1`。要让它成为可信网络里其他机器的 host：
 
 1. 在 host 所在的机器上打开局域网访问：
-   - 托盘：勾选 **允许局域网访问**。托盘把 `"host": "0.0.0.0"` 写进 `settings.json` 并重启 host。Windows 上会在 UAC 确认后添加 TCP 端口和 UDP 发现端口（默认都是 5688）的入站防火墙规则；macOS 和 Linux 上会提示需要在防火墙放行的端口。
+   - 托盘：勾选 **允许局域网访问**。托盘把 `"host": "0.0.0.0"` 写进 `settings.json` 并重启 host。Windows 上会在 UAC 确认后添加 TCP 端口和 UDP 发现端口（默认都是 5688）的入站防火墙规则，只对专用和域网络生效，不含公用网络；macOS 和 Linux 上会提示需要在防火墙放行的端口。
    - 服务：`n2n-nexus-host service install --host 0.0.0.0` 把地址写进 `settings.json`；防火墙里的 TCP 5688 和 UDP 5688 需要自己放行。
 2. 在其他机器上用 `--endpoint discover` 安装客户端（例如 `n2n-nexus install claude --endpoint discover`），或者直接写 host 的地址。
 

package/docs/TOOLS_REFERENCE.md

@@ -12,7 +12,7 @@ Parameter tables below are derived from `contract/tools.json`, the JSON Schema t
 - Calls are rate limited per conversation, per instance without the hooks (default 20 per second, burst 60; `rateLimit` and `rateBurst` in the host's `settings.json`). Over the limit a call fails with "Rate limit exceeded ... retry after Ns"; retry after that delay.
 - Every tool has a display `title` (for example "Delete Project") for client UIs.
 - Every tool carries MCP annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint: false` (all tools act only on the host). Per the MCP definition a tool is non-destructive only when its updates are purely additive. Read tools are marked read-only. `start_meeting`, `join_meeting`, `create_task`, `send_message`, `send` and `reply` only add data and are non-destructive (`join_meeting` is also idempotent); `update_task` is marked non-destructive and idempotent too. `listen`, `set_profile`, `sync_project_assets`, `update_project`, `upload_project_asset`, `rename_project`, `sync_global_doc`, `update_global_strategy`, `end_meeting`, `archive_meeting`, `reopen_meeting`, `leave_meeting`, `stance`, `cancel_task`, `host_maintenance` and `host_delete_project` rewrite or remove existing state and are marked destructive, so clients can ask for confirmation. `read_messages` and `read` are not read-only because they advance the caller's own unread state, but they are non-destructive since no shared data changes.
-- Every adapter has an instance ID (`NEXUS_INSTANCE_ID`, `--id`, or `mcp-<hostname>-<hash of the working directory>-<IDE name>` by default, where the IDE name is the MCP client name from the request's `io.modelcontextprotocol/clientInfo` or, for 2025-era clients, from `initialize`). It stays the same across restarts of the same IDE in the same workspace while two IDEs on one workspace stay distinct. The adapter sends it as `instanceId` with every call. Several conversations of one IDE in one workspace share it, so chat and meeting tools identify the conversation instead when the n2n-nexus hooks are installed (see the next item); a client without the hooks is identified by its instance, and `read_messages` then fails without `instanceId`.
+- Every adapter has an instance ID (`NEXUS_INSTANCE_ID`, `--id`, or `mcp-<hostname>-<hash of the working directory>-<IDE name>` by default, where the hash also covers the WSL distribution, since distributions on one Windows machine share its host name, and the IDE name is the MCP client name from the request's `io.modelcontextprotocol/clientInfo` or, for 2025-era clients, from `initialize`). It stays the same across restarts of the same IDE in the same workspace while two IDEs on one workspace stay distinct. The adapter sends it as `instanceId` with every call. Several conversations of one IDE in one workspace share it, so chat and meeting tools identify the conversation instead when the n2n-nexus hooks are installed (see the next item); a client without the hooks is identified by its instance, and `read_messages` then fails without `instanceId`.
 - Two kinds of id appear in results: conversation session ids, `claude:<id>` or `codex:<id>`, and adapter instance ids (`mcp-…`). The direct-message tools (`peers`, `send`, `read`, `reply`) use session ids. Chat and meetings use the calling conversation's session id when the hooks are installed, else its instance id: the sender and `from` of `send_message` / `read_messages`, the unread cursor, a meeting's `initiator` and `participants` and the `actor` of `meeting.*` events; results say which with `identity` (`session` or `instance`). A session id there can be used with `send`; an instance id cannot. If an instance has had a conversation identified within the last 30 minutes and one of its calls cannot be identified, the call fails with a retry message instead of using the instance's shared cursor. Other events and `updatedBy` of global docs keep the instance id.
 - Project IDs follow `[prefix]_[name]`; the prefixes are listed in the [Assistant guide](ASSISTANT_GUIDE.md#2-project-ids).
 - All project write tools run synchronously and return their result directly. The task tools (`create_task`, `get_task`, `list_tasks`, `update_task`, `cancel_task`) track work that assistants manage themselves.

package/docs/TOOLS_REFERENCE_zh.md

@@ -12,7 +12,7 @@
 - 调用按对话限流，没装 hooks 时按实例（默认每秒 20 次，突发 60 次；对应 host `settings.json` 中的 `rateLimit` 和 `rateBurst`）。超出限制的调用会失败并返回 "Rate limit exceeded ... retry after Ns"；等待该时长后重试。
 - 每个工具都有供客户端界面显示的 `title`（例如 "Delete Project"）。
 - 每个工具都带有 MCP annotations：`readOnlyHint`、`destructiveHint`、`idempotentHint` 和 `openWorldHint: false`（所有工具都只作用于 host）。按照 MCP 的定义，只有更新完全是追加时，工具才算非破坏性。读取类工具标为只读。`start_meeting`、`join_meeting`、`create_task`、`send_message`、`send` 和 `reply` 只追加数据，是非破坏性的（`join_meeting` 也是幂等的）；`update_task` 也标为非破坏性且幂等。`listen`、`set_profile`、`sync_project_assets`、`update_project`、`upload_project_asset`、`rename_project`、`sync_global_doc`、`update_global_strategy`、`end_meeting`、`archive_meeting`、`reopen_meeting`、`leave_meeting`、`stance`、`cancel_task`、`host_maintenance` 和 `host_delete_project` 会改写或删除已有状态，标为破坏性，以便客户端请求确认。`read_messages` 和 `read` 不是只读的，因为它们会推进调用方自己的未读状态；但它们是非破坏性的，因为不改变任何共享数据。
-- 每个适配器都有一个实例 ID（`NEXUS_INSTANCE_ID`、`--id`，默认是 `mcp-<hostname>-<工作目录的哈希>-<IDE 名>`，其中 IDE 名是 MCP 客户端名，取自请求的 `io.modelcontextprotocol/clientInfo`，2025 代的客户端则取自 `initialize`）。同一个 IDE 在同一个工作区里重启后它保持不变，而同一个工作区里的两个 IDE 仍然互相区分。适配器在每次调用中都以 `instanceId` 带上它。同一个 IDE 在同一个工作区里的多个对话共用它，所以装了 n2n-nexus hooks 时，聊天和会议工具改为识别对话本身（见下一条）；没装 hooks 的客户端按实例识别，这时没有 `instanceId` 的 `read_messages` 会失败。
+- 每个适配器都有一个实例 ID（`NEXUS_INSTANCE_ID`、`--id`，默认是 `mcp-<hostname>-<工作目录的哈希>-<IDE 名>`，其中哈希也包含 WSL 发行版名，因为同一台 Windows 上的发行版共用它的主机名；IDE 名是 MCP 客户端名，取自请求的 `io.modelcontextprotocol/clientInfo`，2025 代的客户端则取自 `initialize`）。同一个 IDE 在同一个工作区里重启后它保持不变，而同一个工作区里的两个 IDE 仍然互相区分。适配器在每次调用中都以 `instanceId` 带上它。同一个 IDE 在同一个工作区里的多个对话共用它，所以装了 n2n-nexus hooks 时，聊天和会议工具改为识别对话本身（见下一条）；没装 hooks 的客户端按实例识别，这时没有 `instanceId` 的 `read_messages` 会失败。
 - 结果里会出现两种 ID：对话的会话 ID（`claude:<id>` 或 `codex:<id>`）和适配器实例 ID（`mcp-…`）。直接消息工具（`peers`、`send`、`read`、`reply`）使用会话 ID。聊天和会议在装了 hooks 时使用调用方对话的会话 ID，否则使用实例 ID：`send_message` / `read_messages` 的发送方和 `from`、未读游标、会议的 `initiator` 和 `participants`、`meeting.*` 事件的 `actor`；结果里的 `identity`（`session` 或 `instance`）说明是哪一种。这里的会话 ID 可以用于 `send`，实例 ID 不能。某个实例在最近 30 分钟内识别出过对话、而这次调用识别不出时，调用会失败并提示重试，而不会改用该实例共用的游标。其他事件和全局文档的 `updatedBy` 仍是实例 ID。
 - 项目 ID 采用 `[prefix]_[name]` 格式；前缀列在[助手指南](ASSISTANT_GUIDE_zh.md#2-项目-id)中。
 - 所有项目写入工具都同步执行并直接返回结果。任务工具（`create_task`、`get_task`、`list_tasks`、`update_task`、`cancel_task`）用于跟踪由助手自己管理的工作。

package/package.json

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