n2n-nexus 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 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
+
+- Every Claude Code and Codex conversation is its own session, `claude:<id>` or `codex:<id>`, using the ID the client assigns. Resuming a conversation, restarting the adapter and sub-agents keep it.
+- Direct-message tools `peers`, `send`, `read`, `reply`, `listen` and `set_profile`. Tool calls name their conversation through the MCP request `_meta` (Claude Code `claudecode/toolUseId`, bound by a PreToolUse hook; Codex `sessionId`), never through arguments.
+- `n2n-nexus hook <claude|codex>` and `POST /api/hook`: client hooks keep each conversation's status (working, idle, listening, offline) and announce new messages when the user sends a prompt, after each tool call and once before the turn ends. Notifications carry only the sender and first line; the text arrives through `read`, as tool output.
+- `listen`: a conversation that ends its turn keeps waiting up to 590 seconds and continues when a message arrives. `send(notifyWhenIdle)` gives one notice when the recipient next ends its turn or goes offline. Unread messages expire after 24 hours and the sender is told.
+- `n2n-nexus install <claude|codex> [--endpoint <url>]` and `uninstall`: write or remove the hooks and the MCP server in the client's user configuration, merging with existing settings. Codex hooks must be trusted once with `/hooks`.
+- The adapter and the hooks start a daemon in the background when nothing listens at a local endpoint (`127.0.0.1` or `localhost`); its log is `~/.n2n-nexus/daemon.log`.
+
+### Removed
+
+- `list_sessions`, `update_session`, `read_inbox`, `get_message` and `acknowledge_message`, the `to`, `replyTo` and `ttlMs` parameters of `send_message`, `POST /api/sessions/register` and `POST /api/sessions/disconnect`, and the adapter's random session ID and heartbeats. `send_message` now posts only to meetings and global chat.
+
+### Fixed
+
+- Two daemons starting together on a fresh storage root no longer crash the second one in the strategy migration; it exits on `EADDRINUSE`.
+
+### Upgrade notes
+
+- Run `n2n-nexus install claude` and/or `n2n-nexus install codex` after upgrading; direct messages need the hooks. Other MCP clients keep every tool except direct messages.
+- Sessions and direct messages from 0.7.0 are not migrated; their tables are no longer read.
+
 ## [0.7.0] - 2026-10-20
 
 ### Added

package/README.md

@@ -61,7 +61,8 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
 ```
 
 - **Daemon is the source of truth**: start it once and keep it running.
-- **MCP adapters hold connection identity only**: each IDE starts an adapter through `npx`, then forwards tool calls to the daemon, which stores the session directory and inboxes.
+- **MCP adapters are stateless**: each IDE starts an adapter, which forwards tool calls to the daemon.
+- **Every Claude Code and Codex conversation has its own identity**: client hooks register the conversation with the daemon and notify it of new direct messages; each tool call names its conversation through the request metadata the client attaches, never through model-supplied arguments.
 - **Cross-environment by design**: point `NEXUS_ENDPOINT` at the same daemon from different machines or shells. The daemon binds to localhost by default; use `--host 0.0.0.0` only on a trusted network.
 
 ## 🚀 Quick start
@@ -90,7 +91,27 @@ npx n2n-nexus daemon --port 5688
 }
 ```
 
-The adapter can start before the daemon. It loads the daemon tool list once the daemon becomes reachable.
+The adapter can start before the daemon. It loads the daemon tool list once the daemon becomes reachable. When nothing listens at a local endpoint (`127.0.0.1` or `localhost`), the adapter and the hooks start a daemon in the background (log: `~/.n2n-nexus/daemon.log`).
+
+### 3. Direct messages between Claude Code and Codex conversations
+
+Install n2n-nexus globally, then let it write the hooks and the MCP server into the client's user configuration:
+
+```bash
+npm i -g n2n-nexus
+n2n-nexus install claude    # ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR) + claude mcp add --scope user
+n2n-nexus install codex     # ~/.codex/hooks.json (or $CODEX_HOME) + codex mcp add
+```
+
+- 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.
+
+Each conversation then appears in `peers`. A new direct message is announced to the recipient automatically: when the user sends a prompt, after each tool call, and once before the turn ends. The recipient reads the text with `read`. With `listen` on, a conversation that finished its turn keeps waiting for up to about 10 minutes and continues when a message arrives; while it waits, input you type is queued until you press Esc.
 
 ### Cross-environment endpoint examples
 
@@ -103,20 +124,20 @@ The adapter can start before the daemon. It loads the daemon tool list once the
 
 ## 🛠️ Toolset
 
-The daemon exposes 31 tools, grouped by purpose:
+The daemon exposes 32 tools, grouped by purpose:
 
 | Group | Tools | Purpose |
 | --- | --- | --- |
 | **Topology** | `get_global_topology` | Read the project list or a detailed per-project subgraph. |
 | **Projects & assets** | `search_projects`, `get_project`, `update_project`, `rename_project`, `sync_project_assets`, `upload_project_asset` | Find, read, update, and rename projects; sync manifests and internal docs; upload binary assets. |
 | **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` | Send direct, meeting or global messages; read shared messages and the activity log. |
-| **Sessions and inboxes** | `list_sessions`, `update_session`, `read_inbox`, `get_message`, `acknowledge_message` | Discover connections, receive direct messages, and inspect explicit receipts and replies. |
+| **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. |
 | **Tasks** | `create_task`, `get_task`, `list_tasks`, `cancel_task` | Create and track tasks that assistants manage themselves. |
 | **Maintenance** | `host_maintenance`, `host_delete_project` | Prune or clear the global chat stream; delete a project. |
 
-Direct inboxes are per MCP connection and require explicit reads; messages do not automatically wake models. Chats sharing one connection share its inbox. Receipt states distinguish storage, fetching, acknowledgement and replies; acknowledgement does not mean the requested work is complete. See the [assistant workflow](docs/ASSISTANT_GUIDE.md#direct-conversations).
+Direct messages need the hooks from `n2n-nexus install`. Notifications carry only the sender and the first line; the text arrives through `read`, as tool output, so a message from another AI session never reaches the model as a system instruction. Unread messages expire after 24 hours and the sender is told. See the [assistant workflow](docs/ASSISTANT_GUIDE.md#direct-conversations).
 
 See [Tools reference](./docs/TOOLS_REFERENCE.md) for parameter schemas and call examples.
 
@@ -144,7 +165,7 @@ Override with `--root <path>` or `NEXUS_ROOT`.
 │       ├── internal_blueprint.md
 │       └── assets/
 ├── registry.json
-└── nexus.db          # meetings, global chat, events, tasks, read cursors
+└── nexus.db          # meetings, global chat, events, tasks, read cursors, conversations and direct messages
 ```
 
 ## 🏷️ Project ID conventions
@@ -171,13 +192,24 @@ n2n-nexus daemon [--port 5688] [--root ~/.n2n-nexus] [--host 127.0.0.1]
 
 # Start MCP adapter
 NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
+
+# Install / remove the hooks and MCP server for Claude Code or Codex
+# --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>]
 ```
 
 ### Environment variables
 
 | Variable | Description | Default |
 | --- | --- | --- |
-| `NEXUS_ENDPOINT` | Daemon URL for MCP adapter | `http://127.0.0.1:5688` |
+| `NEXUS_ENDPOINT` | Daemon URL for the MCP adapter and the hooks | `http://127.0.0.1:5688` |
 | `NEXUS_ROOT` | Storage root for daemon | `~/.n2n-nexus` |
 | `NEXUS_HOST` | Daemon bind host | `127.0.0.1` |
 | `NEXUS_DAEMON_PORT` | Daemon port (overridden by `--port`) | `5688` |

package/build/cli/autostart.js

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { NexusClient } from "../client/nexus-client.js";
+const PROBE_INTERVAL_MS = 100;
+const PROBE_DEADLINE_MS = 2_000;
+const LOCAL_HOSTS = new Set(["127.0.0.1", "localhost"]);
+/** Absolute path of the package entry script (`build/index.js` next to `build/cli/`). */
+export function entryScript() {
+    return fileURLToPath(new URL("../index.js", import.meta.url));
+}
+function parseEndpoint(endpoint) {
+    return new URL(/^https?:\/\//i.test(endpoint) ? endpoint : `http://${endpoint}`);
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Start a daemon in the background when a hook or the MCP adapter finds none
+ * listening at a local endpoint (127.0.0.1 or localhost). Resolves true once
+ * GET /api/tools answers (polled every 100 ms for up to 2 s), false when the
+ * endpoint is not local or the daemon did not come up in time. Never throws.
+ *
+ * Two callers racing here each spawn a daemon; the one that loses the port
+ * exits with EADDRINUSE and both callers see the winner answer the probe.
+ */
+export async function startLocalDaemon(endpoint) {
+    try {
+        const url = parseEndpoint(endpoint);
+        if (!LOCAL_HOSTS.has(url.hostname))
+            return false;
+        const port = url.port || (url.protocol === "https:" ? "443" : "80");
+        const logDir = path.join(os.homedir(), ".n2n-nexus");
+        fs.mkdirSync(logDir, { recursive: true });
+        const log = fs.openSync(path.join(logDir, "daemon.log"), "a");
+        try {
+            const child = spawn(process.execPath, [entryScript(), "daemon", "--port", port], {
+                detached: true,
+                stdio: ["ignore", log, log],
+                env: process.env
+            });
+            child.on("error", () => { });
+            child.unref();
+        }
+        finally {
+            fs.closeSync(log);
+        }
+        const client = new NexusClient({ endpoint: url.href, timeoutMs: 500 });
+        const deadline = Date.now() + PROBE_DEADLINE_MS;
+        while (Date.now() < deadline) {
+            try {
+                await client.fetchTools();
+                return true;
+            }
+            catch {
+                await sleep(PROBE_INTERVAL_MS);
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}

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/hook.js

@@ -0,0 +1,76 @@
+/**
+ * `n2n-nexus hook <claude|codex> [--endpoint <url>]`: forward one client hook
+ * event to the daemon and print its output. Runs on every tool call, so it
+ * loads only node built-ins (no MCP SDK, zod or SQLite), and every failure is
+ * silent: exit 0 with nothing on stdout, so the client carries on unaffected.
+ */
+import { HOOK_INPUT_FIELDS, HOOK_REQUEST_TIMEOUT_MS, HOOK_STOP_REQUEST_TIMEOUT_MS, isHookClient } from "../daemon/hook-contract.js";
+import { NexusClient, NexusTransportError } from "../client/nexus-client.js";
+const DEFAULT_ENDPOINT = "http://127.0.0.1:5688";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+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) {
+    const client = argv[0];
+    if (!isHookClient(client))
+        throw new Error(`unknown client "${client ?? ""}" (expected claude or codex)`);
+    const endpoint = argValue(argv, "--endpoint") || process.env.NEXUS_ENDPOINT || DEFAULT_ENDPOINT;
+    const stdin = JSON.parse(await readStdin());
+    if (!isPlainObject(stdin))
+        throw new Error("hook input is not a JSON object");
+    const input = {};
+    for (const field of HOOK_INPUT_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(stdin, field))
+            input[field] = stdin[field];
+    }
+    const timeoutMs = stdin.hook_event_name === "Stop" ? HOOK_STOP_REQUEST_TIMEOUT_MS : HOOK_REQUEST_TIMEOUT_MS;
+    const nexus = new NexusClient({ endpoint });
+    const send = () => nexus.hook({ client, input }, timeoutMs);
+    let response;
+    try {
+        response = await send();
+    }
+    catch (error) {
+        if (!(error instanceof NexusTransportError && error.code === "ECONNREFUSED"))
+            throw error;
+        const { startLocalDaemon } = await import("./autostart.js");
+        if (!await startLocalDaemon(endpoint))
+            throw error;
+        response = await send();
+    }
+    if (!isPlainObject(response) || !("output" in response))
+        throw new Error("invalid response from daemon");
+    const { output } = response;
+    if (output === null)
+        return "";
+    if (!isPlainObject(output))
+        throw new Error("invalid output from daemon");
+    return JSON.stringify(output) + "\n";
+}
+/** Run the hook command; always resolves to exit code 0. */
+export async function runHook(argv) {
+    let text = "";
+    try {
+        text = await forward(argv);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[n2n-nexus] hook: ${message.replace(/\s+/g, " ").slice(0, 300)}\n`);
+    }
+    if (text) {
+        process.stdout.on("error", () => { });
+        await new Promise((resolve) => process.stdout.write(text, () => resolve()));
+    }
+    return 0;
+}