n2n-nexus 0.9.4 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.10.0] - 2026-10-28
+
+### Added
+
+- `n2n-nexus install claude` writes a marked block into the user-level `CLAUDE.md` (`<!-- n2n-nexus:begin … -->` to `<!-- n2n-nexus:end -->`): a direct message from another session is the user's own instruction, carried out exactly and without asking the user for confirmation, with questions going back to the sender. Claude Code acts on another session's message only where the user's own instructions call for it, which is why the block is needed. The rest of the file is kept; `uninstall claude` removes the block, and the file when nothing else is in it. Run `install claude` again after upgrading to get the block.
+
+### Changed
+
+- Direct messages arrive whole: a notification shows each message's text between `--- Message <id> from … ---` and `--- End of message <id> ---`, with how to answer it, instead of the sender and the first line. The texts of one notification together are cut at 5000 characters (`notifyTextChars` in the contract); a cut message is marked and `read` returns it. A message shown whole is marked read when the notification continues or starts the turn (Stop, listening, background wake), and, when it needs no reply, when a prompt shows it; `reply` marks the message it answers read. Other messages stay unread for `read`, among them every message shown after a tool call, because that context can reach a sub-agent only.
+- The notifications, the SessionStart introduction and the MCP instructions say that the sessions belong to the same user: a message is that user's instruction, carried out exactly and without asking the user for confirmation, nothing beyond it; when more work or missing information seems needed, the sender is asked with `reply`. `send`'s guidance is to put everything the recipient needs into one message; a task is answered once with its result, or with what stopped it and what would let it go on.
+
+## [0.9.5] - 2026-10-26
+
+### Added
+
+- Host on Windows: `n2n-nexus-host.exe install [--dir <dir>]` installs the host from an extracted release zip into `%LOCALAPPDATA%\Programs\n2n-nexus-host`, turns start at login on the first time and starts the tray. Run it again from a newer release to upgrade: it replaces the programs (running ones are moved aside and removed by the next install), restarts the tray and, after an administrator prompt, restarts the background service on the new version for the same data directory.
+
+### Changed
+
+- `n2n-nexus install codex` trusts the n2n-nexus hooks in Codex itself: it asks Codex (`codex app-server`, the copy the Codex app runs on Windows, else `codex` on `PATH`) for each hook's trust hash and stores it, so no `/hooks` step is needed. If that fails, it says how to trust them by hand (the Codex app's settings, or `/hooks` in the CLI). `n2n-nexus doctor codex` checks with Codex that the hooks are trusted, which a Codex update can undo.
+
 ## [0.9.4] - 2026-10-26
 
 ### Changed

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [2025] [Antigravity Dev Team]
+   Copyright 2025-2026 Datafrog LLC
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -92,13 +92,13 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
 
 1. Install and start the host, `n2n-nexus-host`, with Scoop, Homebrew or an archive from [Releases](https://github.com/n2ns/n2n-nexus/releases): [Installation guide, steps 1–2](docs/INSTALL.md#1-install-the-host).
 2. Install the client and connect Claude Code or Codex (`npm i -g n2n-nexus@latest`, then `n2n-nexus install claude` or `n2n-nexus install codex`): [step 3](docs/INSTALL.md#3-install-the-client-for-claude-code-and-codex).
-3. Codex only: trust the n2n-nexus hooks once with `/hooks`: [step 4](docs/INSTALL.md#4-turn-on-the-codex-hooks-one-time-required).
+3. Codex only: `install codex` trusts the n2n-nexus hooks in Codex; if it says it could not, trust them by hand: [step 4](docs/INSTALL.md#4-turn-on-the-codex-hooks-one-time-required).
 
 Other MCP clients and several machines: see the [Installation guide](docs/INSTALL.md). Using it, troubleshooting and configuration: see the [User guide](docs/USER_GUIDE.md).
 
 ## 🛠️ Toolset
 
-The host exposes 33 tools, grouped by purpose:
+The host exposes 36 tools, grouped by purpose:
 
 | Group | Tools | Purpose |
 | --- | --- | --- |
@@ -107,7 +107,7 @@ The host exposes 33 tools, grouped by purpose:
 | **Global docs** | `list_global_docs`, `get_global_doc`, `sync_global_doc`, `get_global_strategy`, `update_global_strategy` | List, read, create and update shared global documents and the master strategy document. |
 | **Messaging** | `send_message`, `read_messages`, `list_events` | Post meeting or global messages; read them and the activity log. |
 | **Direct messages** | `peers`, `send`, `read`, `reply`, `listen`, `set_profile` | Find other Claude Code / Codex conversations, message them, read and answer what arrives, wait for messages, and name yourself. |
-| **Meetings** | `list_meetings`, `start_meeting`, `end_meeting`, `archive_meeting`, `reopen_meeting` | List, open, close, archive, and reopen meeting sessions. |
+| **Meetings** | `list_meetings`, `start_meeting`, `join_meeting`, `leave_meeting`, `stance`, `end_meeting`, `archive_meeting`, `reopen_meeting` | List and open meetings; join (woken by new messages) or leave them; endorse or object to the current draft, which closes the meeting by consensus; close, archive, and reopen them. |
 | **Tasks** | `create_task`, `get_task`, `list_tasks`, `update_task`, `cancel_task` | Create, update and track tasks that assistants manage themselves. |
 | **Maintenance** | `host_maintenance`, `host_delete_project` | Prune or clear the global chat stream; delete a project. |
 

package/build/cli/codex-trust.js

@@ -0,0 +1,128 @@
+/**
+ * Codex runs a hook from hooks.json only once it is trusted: config.toml keeps
+ * a `hooks.state.<key>.trusted_hash` per hook, a hash Codex computes from the
+ * hook's whole configuration as its own version serializes it, so another
+ * Codex version may compute another hash and the value cannot be computed
+ * here. Codex's app server reports it instead: `hooks/list` gives each hook's
+ * key, current hash and trust status, and `config/value/write` stores the
+ * hash, as the CLI's /hooks screen and the app's settings do. The Codex the
+ * user runs decides, so the app's own copy is preferred to the one on PATH.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pkg } from "../config/index.js";
+import { clientCommand } from "./client-command.js";
+const TIMEOUT_MS = 30_000;
+/**
+ * The Codex to ask: NEXUS_CODEX_COMMAND when set; on Windows the newest copy
+ * the Codex app keeps in %LOCALAPPDATA%\OpenAI\Codex\bin\<build>\codex.exe;
+ * else `codex` on PATH. Null when none can be run.
+ */
+export function codexProgram() {
+    const override = process.env.NEXUS_CODEX_COMMAND;
+    if (override) {
+        const resolved = clientCommand(override);
+        return resolved && { ...resolved, label: override };
+    }
+    if (process.platform === "win32" && process.env.LOCALAPPDATA) {
+        const bin = path.join(process.env.LOCALAPPDATA, "OpenAI", "Codex", "bin");
+        let newest;
+        try {
+            for (const build of fs.readdirSync(bin)) {
+                const file = path.join(bin, build, "codex.exe");
+                const time = fs.statSync(file, { throwIfNoEntry: false })?.mtimeMs;
+                if (time !== undefined && (!newest || time > newest.time))
+                    newest = { file, time };
+            }
+        }
+        catch { /* no Codex app */ }
+        if (newest)
+            return { command: newest.file, args: [], label: newest.file };
+    }
+    const resolved = clientCommand("codex");
+    return resolved && { ...resolved, label: "codex" };
+}
+/**
+ * Ask `codex app-server` about our hooks in `hooksFile`
+ * and, with `trust`, store the trust of those it does not trust yet. Returns
+ * the state afterwards; throws when the app server cannot be used.
+ */
+export async function codexHookTrust(program, hooksFile, trust) {
+    const child = spawn(program.command, [...program.args, "app-server"], { stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
+    const waiting = new Map();
+    let fail = () => { };
+    const failure = new Promise((_, reject) => { fail = reject; });
+    failure.catch(() => { });
+    child.on("error", (error) => fail(error));
+    // A write after the app server closed its input (it crashed) fails here, not as an uncaught error.
+    child.stdin.on("error", (error) => fail(error));
+    child.on("exit", (code) => fail(new Error(`codex app-server exited (${code})`)));
+    let buffer = "";
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        buffer += chunk;
+        let end;
+        while ((end = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, end);
+            buffer = buffer.slice(end + 1);
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (typeof message.id === "number")
+                waiting.get(message.id)?.(message);
+        }
+    });
+    let next = 1;
+    const call = async (method, params) => {
+        const id = next++;
+        const answer = new Promise((resolve) => waiting.set(id, resolve));
+        child.stdin.write(JSON.stringify({ id, method, params }) + "\n");
+        const message = await Promise.race([answer, failure]);
+        waiting.delete(id);
+        if (message.error)
+            throw new Error(`${method}: ${message.error.message ?? "failed"}`);
+        return message.result;
+    };
+    const file = path.resolve(hooksFile);
+    const list = async () => {
+        const result = await call("hooks/list", { cwds: [os.homedir()] });
+        return (result.data ?? []).flatMap((entry) => entry.hooks ?? [])
+            .filter((hook) => typeof hook.sourcePath === "string" && path.resolve(hook.sourcePath) === file && isOurCodexHook(hook.command ?? ""));
+    };
+    const timer = setTimeout(() => fail(new Error("codex app-server did not answer in time")), TIMEOUT_MS);
+    try {
+        await call("initialize", { clientInfo: { name: "n2n-nexus", version: pkg.version } });
+        child.stdin.write(JSON.stringify({ method: "initialized" }) + "\n");
+        let hooks = await list();
+        const pending = hooks.filter((hook) => hook.trustStatus === "untrusted" || hook.trustStatus === "modified");
+        if (trust && pending.length > 0) {
+            const state = Object.fromEntries(pending.map((hook) => [hook.key, { trusted_hash: hook.currentHash }]));
+            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) };
+    }
+    finally {
+        clearTimeout(timer);
+        child.removeAllListeners("exit");
+        child.stdin.end();
+        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. */
+export const MANUAL_TRUST = "trust the n2n-nexus hooks by hand: in the Codex app's settings (hooks), or with /hooks in the Codex CLI";

package/build/cli/doctor.js

@@ -3,7 +3,8 @@
  * script in the hook commands, and the Node path and npm's npx script in the
  * MCP server command (`"<node>" "<npx>" -y n2n-nexus@latest mcp`), that
  * `install` wrote still exist and run, that the host those commands talk to answers
- * GET /health as n2n-nexus-host with this client's contract version, and say
+ * GET /health as n2n-nexus-host with this client's contract version, that
+ * Codex trusts the Codex hooks (asked through codex-trust.ts), 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.
@@ -80,7 +81,7 @@ async function doctorHosts(endpoints) {
 }
 /**
  * Check one client; prints the report and returns whether everything passed, or undefined when nothing is installed.
- * Adds the endpoints its hook commands use (`defaultEndpoint` for those without --endpoint) to `endpoints`.
+ * Adds the endpoints its hook and MCP commands use to `endpoints`, falling back to defaultEndpoint.
  */
 function doctorClient(client, endpoints, defaultEndpoint) {
     const hooksFile = configFile(client);
@@ -131,6 +132,7 @@ function doctorClient(client, endpoints, defaultEndpoint) {
         report(`MCP server ${MCP_SERVER_NAME} in ${mcpFile}`, bad("not registered"));
     }
     else {
+        endpoints.add(mcp.endpoint === undefined ? defaultEndpoint : mcp.endpoint || LOCAL_ENDPOINT);
         report(`MCP Node ${mcp.command}`, checkNode(mcp.command));
         const [npx, ...rest] = mcp.args;
         if (npx && rest.join(" ") === `-y ${MCP_PACKAGE} mcp`)
@@ -147,6 +149,37 @@ function doctorClient(client, endpoints, defaultEndpoint) {
     process.stdout.write(lines.join("\n") + "\n");
     return !failed;
 }
+/**
+ * Whether Codex trusts our hooks (it runs untrusted or modified ones not at
+ * all); prints the result. A Codex that cannot be asked is only noted.
+ */
+async function doctorCodexTrust() {
+    const { MANUAL_TRUST, NOT_LISTED, codexHookTrust, codexProgram } = await import("./codex-trust.js");
+    const program = codexProgram();
+    if (!program) {
+        process.stdout.write(`  note: hook trust not checked: the "codex" command could not be run.\n`);
+        return true;
+    }
+    let state;
+    try {
+        state = await codexHookTrust(program, configFile("codex"), false);
+    }
+    catch (error) {
+        process.stdout.write(`  note: hook trust not checked with ${program.label}: ${error.message}\n`);
+        return true;
+    }
+    if (state.ours === 0) {
+        process.stdout.write(`  FAIL hook trust (${program.label}): ${NOT_LISTED}, then run "n2n-nexus install codex" again.\n`);
+        return false;
+    }
+    if (state.untrusted.length === 0) {
+        process.stdout.write(`  ok   hook trust (${program.label}): ${state.ours} hooks trusted\n`);
+        return true;
+    }
+    process.stdout.write(`  FAIL hook trust (${program.label}): not trusted: ${state.untrusted.join(", ")}\n`
+        + `  fix: run "n2n-nexus install codex" again, or ${MANUAL_TRUST}.\n`);
+    return false;
+}
 /** Parse `[claude|codex]`, run the checks and return the exit code. */
 export async function runDoctor(argv) {
     const client = argv[0];
@@ -172,6 +205,8 @@ export async function runDoctor(argv) {
             else if (!result) {
                 failed = true;
             }
+            if (c === "codex" && result !== undefined && !await doctorCodexTrust())
+                failed = true;
         }
         if (endpoints.size === 0)
             endpoints.add(defaultEndpoint);

package/build/cli/hook.js

@@ -90,19 +90,41 @@ async function forward(argv) {
 }
 /** The background wait ends before the client's hook timeout would kill it during a request. */
 const WAIT_DEADLINE_MS = (WAIT_HOOK_TIMEOUT_SEC - 10) * 1000;
+const WAIT_RETRY_CODES = new Set([...UNREACHABLE_CODES, "ECONNRESET", "EPIPE", "ENOTFOUND", "EAI_AGAIN", REQUEST_TIMEOUT_CODE]);
 /**
  * Ask the daemon until something arrives for the session (the wake), the
  * session becomes active again or the deadline passes (null).
  */
-export async function waitForWake(client, sessionId, endpoint, deadlineMs = WAIT_DEADLINE_MS) {
-    const nexus = new NexusClient({ endpoint });
-    // Start a request only if it can run to its own timeout before the deadline.
-    const deadline = Date.now() + deadlineMs - HOOK_STOP_REQUEST_TIMEOUT_MS;
+export async function waitForWake(client, sessionId, configured, deadlineMs = WAIT_DEADLINE_MS) {
+    const deadline = Date.now() + deadlineMs;
+    let endpoint = await resolveEndpoint(configured);
+    let delay = WAKE_RETRY_FIRST_DELAY_MS;
+    let fresh = false;
     while (Date.now() < deadline) {
-        const response = await nexus.hook({ client, input: { hook_event_name: BACKGROUND_WAIT_EVENT, session_id: sessionId } }, HOOK_STOP_REQUEST_TIMEOUT_MS);
+        if (fresh)
+            endpoint = await resolveEndpoint(configured, { fresh: true });
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return null;
+        let response;
+        try {
+            response = await new NexusClient({ endpoint }).hook({ client, input: { hook_event_name: BACKGROUND_WAIT_EVENT, session_id: sessionId } }, Math.min(HOOK_STOP_REQUEST_TIMEOUT_MS, remaining));
+        }
+        catch (error) {
+            if (!(error instanceof NexusTransportError) || !WAIT_RETRY_CODES.has(error.code ?? ""))
+                throw error;
+            if (Date.now() + delay >= deadline)
+                return null;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            delay = Math.min(delay * 2, WAKE_RETRY_MAX_DELAY_MS);
+            fresh = true;
+            continue;
+        }
+        fresh = false;
+        delay = WAKE_RETRY_FIRST_DELAY_MS;
         const output = isPlainObject(response) ? response.output : null;
         if (isPlainObject(output) && typeof output.wake === "string" && typeof output.dispatchId === "string")
-            return { text: output.wake, dispatchId: output.dispatchId };
+            return { text: output.wake, dispatchId: output.dispatchId, endpoint };
         if (!(isPlainObject(output) && output.timeout === true))
             return null;
     }
@@ -143,10 +165,9 @@ async function runWait(argv) {
     // Load what a wake needs before waiting: the wait lasts up to an hour, and an
     // upgrade or a cleared npx cache may remove the package's files meanwhile.
     const { spawnClientSync } = client === "codex" ? await import("./client-command.js") : { spawnClientSync: undefined };
-    const endpoint = await resolveEndpoint(configured);
     const deadline = Date.now() + WAIT_DEADLINE_MS;
     for (let delay = WAKE_RETRY_FIRST_DELAY_MS;; delay = Math.min(delay * 2, WAKE_RETRY_MAX_DELAY_MS)) {
-        const wake = await waitForWake(client, sessionId, endpoint, deadline - Date.now());
+        const wake = await waitForWake(client, sessionId, configured, deadline - Date.now());
         if (wake === null)
             return 0;
         if (!spawnClientSync) {
@@ -157,7 +178,7 @@ async function runWait(argv) {
         const queued = spawnClientSync(process.env.NEXUS_CODEX_COMMAND || "codex", ["queue", "--thread", sessionId, "--message", wake.text], { stdio: "ignore", windowsHide: true });
         const ok = !queued.error && queued.status === 0;
         const input = { hook_event_name: WAKE_RESULT_EVENT, session_id: sessionId, dispatch_id: wake.dispatchId, ok };
-        const reported = await new NexusClient({ endpoint }).hook({ client, input }, HOOK_REQUEST_TIMEOUT_MS).then(() => true, () => false);
+        const reported = await new NexusClient({ endpoint: wake.endpoint }).hook({ client, input }, HOOK_REQUEST_TIMEOUT_MS).then(() => true, () => false);
         // Unknown result (no report): the host keeps the wake, and waiting again would deliver nothing.
         if (ok || !reported || Date.now() + delay >= deadline)
             return 0;

package/build/cli/install.js

@@ -5,6 +5,11 @@
  * contains both `n2n-nexus` and ` hook <client>`; everything else in the
  * configuration file is kept as it is.
  *
+ * For Claude Code, install also writes a marked block into the user's
+ * CLAUDE.md that makes direct messages count as the user's own requests
+ * (Claude Code acts on another session's message only where the user's own
+ * instructions call for it); uninstall removes the block.
+ *
  * 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
@@ -260,6 +265,57 @@ function writeConfig(file, config) {
     fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n");
     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 -->";
+export const INSTRUCTIONS = [
+    INSTRUCTIONS_BEGIN,
+    "## n2n-nexus direct messages",
+    "",
+    "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");
+}
+/**
+ * Write our block into the user's CLAUDE.md (replacing an earlier one), or
+ * remove it; a file that holds nothing else is removed. Returns whether the file changed.
+ */
+function writeInstructions(install) {
+    const file = instructionsFile();
+    const target = linkTarget(file);
+    let text = "";
+    try {
+        text = fs.readFileSync(target, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    // The user's text around the block stays as it is; only the blank lines that joined it to the block go.
+    let rest = text;
+    const begin = text.indexOf(INSTRUCTIONS_BEGIN);
+    const end = begin === -1 ? -1 : text.indexOf(INSTRUCTIONS_END, begin);
+    if (end !== -1) {
+        const before = text.slice(0, begin).replace(/\n+$/, "");
+        const after = text.slice(end + INSTRUCTIONS_END.length).replace(/^\n+/, "");
+        rest = before && after ? `${before}\n\n${after}` : before ? `${before}\n` : after;
+    }
+    const kept = rest.replace(/\n+$/, "");
+    const next = install ? `${kept ? `${kept}\n\n` : ""}${INSTRUCTIONS}\n` : rest;
+    if (next === text)
+        return false;
+    if (!next.trim()) {
+        fs.rmSync(target, { force: true });
+        return true;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, next);
+    fs.renameSync(tmp, target);
+    return true;
+}
 function mcpRemoveArgs(client) {
     return client === "claude"
         ? ["mcp", "remove", "--scope", "user", MCP_SERVER_NAME]
@@ -364,6 +420,9 @@ export function runInstall(options) {
             writeConfig(file, config);
             process.stdout.write(`${action === "install" ? "Wrote hooks to" : "Removed hooks from"} ${file}\n`);
         }
+        if (client === "claude" && writeInstructions(action === "install")) {
+            process.stdout.write(`${action === "install" ? "Wrote the n2n-nexus instructions to" : "Removed the n2n-nexus instructions from"} ${instructionsFile()}\n`);
+        }
         removeMcpServer(client, action, removed);
         if (action === "install" && node && npm) {
             const addArgs = mcpAddArgs(client, node, npm, endpoint);
@@ -373,9 +432,6 @@ export function runInstall(options) {
             if (VERSIONED_NODE_DIR.test(node) || VERSIONED_NODE_DIR.test(npm.npx)) {
                 process.stdout.write(`Note: this Node or npx 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");
-            }
         }
         return 0;
     }
@@ -385,7 +441,7 @@ export function runInstall(options) {
     }
 }
 /** Parse `<claude|codex> [--endpoint <url>] [--node <path>]` and run. */
-export function runInstallCommand(action, argv) {
+export async function runInstallCommand(action, argv) {
     const client = argv[0];
     if (!isHookClient(client)) {
         process.stderr.write(`Usage: n2n-nexus ${action} <claude|codex>${action === "install" ? " [--endpoint <url>] [--node <path>]" : ""}\n`);
@@ -408,5 +464,29 @@ export function runInstallCommand(action, argv) {
     const node = option("--node", "a path");
     if (node === null)
         return 1;
-    return runInstall({ action, client, endpoint, node });
+    const code = runInstall({ action, client, endpoint, node });
+    if (code === 0 && action === "install" && client === "codex")
+        await trustCodex();
+    return code;
+}
+/**
+ * Codex runs the hooks just written only once they are trusted: trust them
+ * through Codex itself, or say how to do it by hand. Never fails the install.
+ */
+async function trustCodex() {
+    const { MANUAL_TRUST, NOT_LISTED, codexHookTrust, codexProgram } = await import("./codex-trust.js");
+    const program = codexProgram();
+    try {
+        if (!program)
+            throw new Error(`the "codex" command could not be run`);
+        const state = await codexHookTrust(program, configFile("codex"), true);
+        if (state.ours === 0)
+            throw new Error(`${program.label}: ${NOT_LISTED}`);
+        if (state.untrusted.length > 0)
+            throw new Error(`Codex (${program.label}) still does not trust ${state.untrusted.join(", ")}`);
+        process.stdout.write(`Trusted the ${state.ours} n2n-nexus hooks in Codex (${program.label}); start a new Codex conversation to use them.\n`);
+    }
+    catch (error) {
+        process.stdout.write(`Could not trust the hooks automatically (${error.message}). Codex does not run them until you ${MANUAL_TRUST}.\n`);
+    }
 }

package/build/cli/mcp-config.js

@@ -39,20 +39,27 @@ export function readMcpCommand(client, file) {
         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) : [] };
+        const endpoint = server.env?.NEXUS_ENDPOINT;
+        return { command: server.command, args: Array.isArray(server.args) ? server.args.map(String) : [],
+            ...(typeof endpoint === "string" ? { endpoint } : {}) };
     }
     // 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)
+    const readTable = (suffix = "") => {
+        const start = lines.findIndex((line) => new RegExp(`^\\s*\\[mcp_servers\\.(["']?)${MCP_SERVER_NAME}\\1${suffix}\\]\\s*(?:#.*)?$`).test(line));
+        if (start === -1)
+            return undefined;
+        const body = [];
+        for (const line of lines.slice(start + 1)) {
+            if (/^\s*\[/.test(line))
+                break;
+            body.push(line);
+        }
+        return body.join("\n");
+    };
+    const table = readTable();
+    if (table === undefined)
         return undefined;
-    const body = [];
-    for (const line of lines.slice(start + 1)) {
-        if (/^\s*\[/.test(line))
-            break;
-        body.push(line);
-    }
-    const table = body.join("\n");
     const value = String.raw `"(?:[^"\\\r\n]|\\.)*"|'[^'\r\n]*'`;
     const decode = (s) => s.startsWith("'") ? s.slice(1, -1) : JSON.parse(s);
     const command = new RegExp(`^\\s*command\\s*=\\s*(${value})`, "m").exec(table);
@@ -62,5 +69,19 @@ export function readMcpCommand(client, file) {
     const array = new RegExp(`^\\s*args\\s*=\\s*\\[((?:${value}|#[^\\n]*|[^\\]"'#])*)\\]`, "m").exec(table);
     const args = array ? [...array[1].matchAll(new RegExp(`(${value})|#[^\\n]*`, "g"))]
         .filter((m) => m[1] !== undefined).map((m) => decode(m[1])) : [];
-    return { command: decode(command[1]), args };
+    const endpointKey = `(?:NEXUS_ENDPOINT|"NEXUS_ENDPOINT"|'NEXUS_ENDPOINT')`;
+    const envTable = readTable(String.raw `\.(?:env|"env"|'env')`);
+    let endpoint = envTable === undefined ? undefined : new RegExp(`^\\s*${endpointKey}\\s*=\\s*(${value})`, "m").exec(envTable)?.[1];
+    endpoint ??= new RegExp(`^\\s*env\\.${endpointKey}\\s*=\\s*(${value})`, "m").exec(table)?.[1];
+    if (endpoint === undefined) {
+        const inline = new RegExp(`^\\s*env\\s*=\\s*\\{((?:${value}|#[^\\n]*|[^}"'#])*)\\}`, "m").exec(table)?.[1];
+        if (inline !== undefined) {
+            // Consume complete key/value pairs: endpoint-looking text inside another value is not a setting.
+            for (const entry of inline.matchAll(new RegExp(`(${value}|[A-Za-z0-9_-]+)\\s*=\\s*(${value})|#[^\\n]*`, "g"))) {
+                if (entry[1] && (entry[1] === "NEXUS_ENDPOINT" || /^["']/.test(entry[1]) && decode(entry[1]) === "NEXUS_ENDPOINT"))
+                    endpoint = entry[2];
+            }
+        }
+    }
+    return { command: decode(command[1]), args, ...(endpoint === undefined ? {} : { endpoint: decode(endpoint) }) };
 }

package/build/client/discovery.js

@@ -12,6 +12,7 @@ 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";
 /** 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";
@@ -47,7 +48,13 @@ export function discoverEndpoint(udpPort = discoveryPort(), waitMs = DISCOVERY_W
     // listens on all interfaces, else the one address it is bound to.
     const own = new Set(lanInterfaces().map((a) => a.address));
     const address = (rinfo, reply) => {
-        if (!own.has(rinfo.address) && !rinfo.address.startsWith("127."))
+        const local = own.has(rinfo.address) || rinfo.address.startsWith("127.");
+        if (typeof reply.host === "string" && isIPv6(reply.host)) {
+            const host = new URL(`http://[${reply.host}]`).hostname;
+            // The IPv4 discovery source cannot identify an IPv6-only listener on another machine.
+            return host === "[::]" ? (local ? "[::1]" : null) : host;
+        }
+        if (!local)
             return rinfo.address;
         return typeof reply.host === "string" && !ALL_INTERFACES.has(reply.host) ? reply.host : "127.0.0.1";
     };
@@ -68,7 +75,9 @@ export function discoverEndpoint(udpPort = discoveryPort(), waitMs = DISCOVERY_W
             try {
                 const reply = JSON.parse(msg.toString("utf8"));
                 if (reply.service === "n2n-nexus" && Number.isInteger(reply.port) && reply.port > 0) {
-                    finish(`http://${address(rinfo, reply)}:${reply.port}`);
+                    const host = address(rinfo, reply);
+                    if (host !== null)
+                        finish(`http://${host}:${reply.port}`);
                 }
             }
             catch { /* not a discovery reply */ }

package/build/client/nexus-client.js

@@ -50,7 +50,7 @@ export class NexusClient {
             }, (res) => {
                 let data = "";
                 res.setEncoding("utf8");
-                const interrupted = () => reject(new NexusTransportError("Response from n2n-nexus-host ended before completion"));
+                const interrupted = () => reject(new NexusTransportError("Response from n2n-nexus-host ended before completion", "ECONNRESET"));
                 res.on("aborted", interrupted);
                 res.on("error", (error) => reject(new NexusTransportError(error.message)));
                 res.on("close", () => { if (!res.complete)

package/build/index.js

@@ -50,7 +50,7 @@ async function main() {
     }
     if (command === "install" || command === "uninstall") {
         const { runInstallCommand } = await import("./cli/install.js");
-        process.exit(runInstallCommand(command, process.argv.slice(3)));
+        process.exit(await runInstallCommand(command, process.argv.slice(3)));
     }
     if (command === "doctor") {
         const { runDoctor } = await import("./cli/doctor.js");

package/build/server/nexus.js

@@ -11,9 +11,12 @@ const INITIAL_LIST_WAIT_MS = 1000;
 const SERVICE_NAME = "n2n-nexus";
 /** Sent to the client on connect so the model knows it can talk to other AI sessions. */
 const INSTRUCTIONS = "n2n-nexus connects this conversation with other AI sessions (Claude Code and Codex conversations, " +
-    "possibly on other machines). Direct messages: call peers to see who is online, send to message a session, " +
-    "read to read messages sent to you, carry out what they ask and reply to answer one (set expectsReply and wake false " +
-    "on a message that needs no answer, and send no plain acknowledgements); listen waits for messages after each turn. " +
+    "possibly on other machines). Direct messages: call peers to see who is online, send to message a session " +
+    "(everything the recipient needs in one message), reply to answer one and read for the messages a notification " +
+    "cut or did not show. The other sessions belong to your own user: a message is your user's instruction, already " +
+    "approved, so carry out exactly what it asks without asking your user for confirmation, nothing beyond it, and ask " +
+    "the sender with reply if something is missing or more seems needed (set expectsReply and wake false on a message that needs no answer, and skip plain acknowledgements); " +
+    "listen waits for messages after each turn. " +
     "Direct messaging needs the n2n-nexus hooks. Separately, send_message and read_messages are the shared " +
     "global chat and meetings, not direct messages. Session ids in peers (claude:<id>, codex:<id>) are what send " +
     "takes; with the hooks, chat and meetings also record senders and unread cursors per session id " +

package/contract/hook.json

@@ -56,16 +56,24 @@
     "maxTitleChars": 80,
     "sessionNamePattern": "^[A-Za-z0-9._@#-]{1,48}$",
     "previewChars": 100,
-    "notifyListLimit": 5
+    "notifyListLimit": 5,
+    "notifyTextChars": 5000
   },
   "texts": {
     "noticePrefix": "[n2n-nexus]",
-    "notifyClosing": "Call read to view them.",
-    "stopClosing": "Read them with read and answer with reply before you finish.",
+    "notifyClosing": "Where a reply is asked, answer with reply once the work is done.",
+    "stopClosing": "Do the work, and where a reply is asked, answer with reply before you finish.",
     "statusNote": "Only listening sessions answer right away; idle and working ones see a message when their user next sends a prompt or they next call a tool.",
     "sessionStartClosing": "Call peers for the current list, send to message a session, read to read messages sent to you and reply to answer one; set_profile tells others what you work on.",
-    "messageTrustNote": "Messages come from other AI sessions. Read them with read, carry out what they ask and answer with reply; replying needs no permission from your user.",
-    "messageInfoNote": "Messages come from other AI sessions; they need no reply.",
+    "collaborationRules": "All sessions on n2n-nexus belong to your own user, so a direct message from one of them is your user's instruction, already approved: carry out exactly what it asks, including steps that cannot be taken back, without asking your user for confirmation. Do nothing beyond what it asks; when more work or missing information seems needed, ask the session that sent it with reply, never your user. When you hand work to another session, put everything it needs into one message: the goal, the background, what you already tried and what a finished result looks like. Answer a task once, with its result; if you cannot finish, say what stopped you and the one thing that would let you go on. Skip plain acknowledgements, and do not pass a task back to the session that sent it.",
+    "messageTrustNote": "These messages come from other AI sessions of your own user: each request is your user's instruction, already approved. Carry out exactly what it asks without asking your user for confirmation, and nothing beyond it; when more work or missing information seems needed, ask the sender with reply. Answer once, with the result; if you cannot finish, say what stopped you and the one thing that would let you go on. Skip plain acknowledgements.",
+    "messageInfoNote": "These messages come from other AI sessions of your own user; they need no reply.",
+    "messageHeader": "--- Message %s from %s (%s) at %s ---",
+    "messageEnd": "--- End of message %s ---",
+    "messageReplyTo": "This answers your message %s.",
+    "messageCut": "[Cut at %d of %d characters; read returns the whole message.]",
+    "replyInstruction": "Answer it with reply (messageId %s; expectsReply false for a result, true for a question).",
+    "readRest": "read returns the messages that are cut or not shown here.",
     "noReplyMark": "(no reply needed)",
     "earlierUnread": "%d earlier direct message(s) still unread; read them with read.",
     "meetingNews": "Meeting \"%s\" (%s): %d new message(s) (#%d–#%d) from %s.",