n2n-nexus 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.9.0] - 2026-10-23
+
+Version 0.9.0 of both programs: the host is now `n2n-nexus-host`, a separate Go program, and the npm package `n2n-nexus` is the client only.
+
+### Added
+
+- `n2n-nexus-host`, the host rewritten in Go as one executable for Windows, macOS and Linux (amd64 and arm64). Without arguments it runs as a tray app: status, address and online sessions, open the log and data folders, LAN access on / off (on Windows it adds the TCP and UDP firewall rules after a UAC prompt; elsewhere it names the ports to allow), start at login (turned on the first time the tray runs), restart, quit; Chinese texts on a Chinese system, English otherwise. `serve` runs it in the foreground; `service install|uninstall|status` registers a boot service that runs as the installing user and restarts the host 5 s after it exits (Windows scheduled task, macOS LaunchDaemon, Linux systemd unit), and refuses to install while the tray runs the host; `autostart on|off` starts the tray at login. When a host already answers on the port (the service), the tray only controls it. One host runs per data directory.
+- Installation through Homebrew (`brew install n2ns/tap/n2n-nexus-host`, built from source), Scoop (`scoop bucket add n2ns https://github.com/n2ns/scoop-bucket`, `scoop install n2ns/n2n-nexus-host`) and archives on GitHub Releases (tags `host-v*`) with `SHA256SUMS` and build provenance (`gh attestation verify`). The binaries are not code-signed yet.
+- `update_task`: update a task's `status`, `progress` (0–1), `result_uri`, `error_message` or `metadata`; returns the task.
+- `contract/`: the protocol between host and client in JSON (`tools.json`, `hook.json`, `errors.json`), shipped in the npm package. `GET /health` reports the host's `contractVersion`, and `n2n-nexus doctor` checks that the host answers with the client's.
+- LAN discovery: `NEXUS_ENDPOINT=discover` (or `--endpoint discover`) makes the MCP adapter and the hooks find a host by UDP broadcast on `NEXUS_DISCOVERY_PORT` (default 5688), cache it in `~/.n2n-nexus/discovered-endpoint` and look again when it cannot be reached. A host listening on a non-loopback address answers on its `discoveryPort`. When none answers, clients use the local endpoint `http://127.0.0.1:5688`.
+- The SessionStart hook tells a new conversation its own session name and ID and which other sessions are not offline, so it can message them without being asked to look first.
+- The MCP adapter sends server instructions describing how to find and message other AI sessions.
+- Idle conversations are woken: `install` adds a second Stop hook (`n2n-nexus hook <client> --wait`) that waits up to an hour after a turn for new messages or notices and then starts a turn with them, through an `asyncRewake` hook in Claude Code and `codex queue` in Codex (`NEXUS_CODEX_COMMAND` overrides the command). The session shows as `listening` meanwhile; any new activity ends the wait. Run `n2n-nexus install <client>` again to add the hook. An unattended Claude session (`claude -p`, `CLAUDE_CODE_SESSION_ATTENDED=0`) skips the wait, so it exits as soon as it answers.
+- Automatic turn limit: wakes, listening Stops and Stops held open for messages count as automatic turns, and after `maxAutoTurns` (host `settings.json`, default 8; `0` = no limit) since the user's last prompt, messages are stored but no longer wake or hold the conversation, so two AI sessions cannot keep waking each other. The announcement says `Automatic turn n of N`; the prompt that starts a woken turn does not reset the count.
+
+### Changed
+
+- **Breaking:** the npm package `n2n-nexus` is the client only (MCP adapter, `hook`, `install` / `uninstall`, `doctor`); `n2n-nexus daemon` is removed and the package no longer depends on `better-sqlite3`. Run the host with `n2n-nexus-host`.
+- **Breaking:** storage is a new SQLite database, `nexus.db` in the host's data directory (`%LOCALAPPDATA%\n2n-nexus`, `~/Library/Application Support/n2n-nexus`, `$XDG_DATA_HOME/n2n-nexus` with default `~/.local/share/n2n-nexus`; `--root` or `NEXUS_ROOT` overrides it). Projects, assets and global docs are tables in it instead of files, every write is one transaction, and the schema is managed by numbered migrations. The data of earlier versions in `~/.n2n-nexus` is not imported and is left untouched.
+- **Breaking:** the host has only four endpoints: `GET /health`, `GET /api/tools`, `POST /api/tools/call` and `POST /api/hook`. The project, message, global, meeting, task, event and maintenance REST endpoints are removed; every one of them has a tool of the same purpose.
+- **Breaking:** `read_messages` needs an `instanceId` (the MCP adapter always sends one); calls without one no longer share an `unknown` read cursor.
+- **Breaking:** host settings live in `settings.json` in the data directory (`host`, `port`, `discoveryPort`, `allowedHosts`, `rateLimit`, `rateBurst`, `maxAutoTurns`), overridden by command-line flags; the host reads no environment variable except `NEXUS_ROOT`. `NEXUS_HOST`, `NEXUS_DAEMON_PORT`, `NEXUS_ALLOWED_HOSTS`, `NEXUS_RATE_LIMIT`, `NEXUS_RATE_BURST` and `NEXUS_MAX_AUTO_TURNS` are gone; `NEXUS_DISCOVERY_PORT` remains for clients using `discover`.
+- Hooks are rate limited per conversation and per client address, in buckets separate from tool calls.
+- The host keeps data for a bounded time: events, read or expired direct messages and delivered notices for 30 days, finished tasks for 7 days; `host.log` rotates at 10 MB with 3 old files kept (the tray's own lines go to `tray.log`).
+- The MCP adapter and the hooks never start a host. When none answers at a local endpoint, tool calls fail with a message saying to install and start `n2n-nexus-host`; at a remote endpoint, that it must be started on that machine. The hooks skip silently.
+- `peers` lists only the sessions that are not offline; `includeOffline: true` adds the offline ones active in the last 24 hours, as before.
+- An `idle` or `working` session without activity for 30 minutes is marked `offline`, since clients do not always send SessionEnd (finished or closed Codex threads stayed "online" forever); its next event brings it back. `peers` and the SessionStart introduction say that only `listening` sessions answer right away.
+
+### Fixed
+
+- A background wait counts as activity, so a session waiting longer than 30 minutes is not marked `offline` between two waits. A session with `listen` on no longer stays `listening` after its waits have ended, and a host restart resets sessions left `listening`, so they go `offline` after 30 minutes without activity like any other session.
+- Starting, ending and reopening a meeting each update the meeting and the active meeting in one transaction.
+- The event filter `action` matches the exact name or the exact `<action>.` prefix; it no longer ignores case or treats `_` and `%` as wildcards.
+- A tool call the host does not answer within the request timeout fails on its own; the MCP adapter no longer drops the tool list and reconnects, which led clients to retry calls the host was still completing.
+- Windows: `install <claude|codex>` finds `claude.cmd` / `codex.cmd` installed by npm, and the `--wait` hook wakes Codex installed that way. The script behind npm's shim runs with Node directly, never through cmd.exe, so a message text cannot run commands and keeps its line breaks; installing from an npx cache path is refused as on other systems.
+- The `create_task` description no longer points to a tool that does not exist.
+- The npm package includes the documents its README and guides link to (tools reference, security, contributing, Chinese assistant guide, 2025-12-29 meeting notes).
+
 ## [0.8.2] - 2026-10-22
 
 ### Fixed

package/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Thanks for helping improve n2n-nexus.
+
+## Development Setup
+
+Use Node.js 24, matching CI and the lint toolchain, and the Go version in `go.mod` for the host (`npm test` builds the Go test host too). The published client requires Node.js 22.14+ on the 22.x release line, or Node.js 23.6+.
+
+```bash
+npm install
+npm run build
+npm test
+go vet ./...
+go test ./host/...
+npm run host:build-test && npm run test:conformance
+```
+
+Pre-commit runs lint. Pre-push runs `go vet`, `go test ./host/...`, build, `npm test`, the test-host build and the conformance tests via lefthook.
+
+For a full local run:
+
+```bash
+# Start a host
+go run ./host/cmd/n2n-nexus-host serve --root /tmp/nexus-test --port 5799
+
+# Start MCP adapter (separate terminal)
+NEXUS_ENDPOINT=http://127.0.0.1:5799 node build/index.js mcp
+```
+
+## Pull Request Guidelines
+
+- Keep changes focused and easy to review.
+- Add or update tests for behavior changes: Go tests next to the host code, conformance tests in `tests/conformance/` for anything a client can observe over HTTP, client tests in `tests/`.
+- Update `docs/ARCHITECTURE.md` before changing the HTTP API, the database schema, or the protocol in `contract/`.
+- Update `docs/ASSISTANT_GUIDE.md` and `docs/ASSISTANT_GUIDE_zh.md` when tool behavior visible to AI assistants changes.
+- Run `npm run build && npm test`, `go test ./host/...` and `npm run test:conformance` before opening a PR.
+
+## Commit Hygiene
+
+- Do not commit host data directories, `tests/tmp/`, `host/bin/`, or generated `node_modules/`.
+- Explain user-visible behavior changes in the PR description.
+
+## Architecture Notes
+
+The host (`n2n-nexus-host`, Go, `host/`) is the single source of truth. The MCP adapter (`n2n-nexus`, TypeScript, `src/`) is a stateless proxy — it has no tool definitions and no local data. Tool definitions live in `contract/tools.json`, their handlers in `host/internal/core` and `host/internal/agents`. See `docs/ARCHITECTURE.md` for the full system design and `host/README.md` for building and releasing the host.
+
+## Changelog
+
+User-visible changes should be recorded in `CHANGELOG.md`.

package/README.md

@@ -16,7 +16,7 @@ Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaborat
 
 ---
 
-> **One daemon. Many assistants. Shared project state.**
+> **One host. Many assistants. Shared project state.**
 
 n2n-nexus is an open-source Model Context Protocol (MCP) coordination server for developers and teams who use multiple AI coding assistants across IDEs, machines, and projects. Use it when Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, JetBrains, or other MCP-enabled clients need a shared local coordination layer instead of isolated per-chat context.
 
@@ -36,20 +36,20 @@ n2n-nexus is an open-source Model Context Protocol (MCP) coordination server for
 
 ## 💡 What is n2n-nexus?
 
-n2n-nexus gives AI assistants a shared coordination workspace. A long-running local daemon owns project state, meetings, messages, tasks, shared docs, and project assets. Lightweight MCP adapters connect each IDE or assistant to the same daemon.
+n2n-nexus gives AI assistants a shared coordination workspace. A long-running local host, `n2n-nexus-host`, owns project state, meetings, messages, tasks, shared docs, and project assets. Lightweight MCP adapters from the `n2n-nexus` npm package connect each IDE or assistant to the same host.
 
 - Coordinate multiple AI assistants working on the same project.
 - Share project manifests, decisions, and assets across IDEs and machines.
 - Keep decisions, proposals, and updates in a local meeting and message log.
-- Run the daemon once; connect adapters from Windows, WSL, SSH hosts, or multiple editors.
+- Run the host once; connect adapters from Windows, WSL, SSH hosts, or multiple editors.
 - Avoid giving each assistant broad filesystem or backend access.
 
 ## 🏗️ Architecture
 
 ```text
 ┌──────────────────────────────────────┐
-│          n2n-nexus daemon            │
-│  Standalone HTTP server · always on  │
+│           n2n-nexus-host             │
+│  Tray app or background service      │
 │  Owns data, tools, tasks, messages   │
 └──────────────┬───────────────────────┘
                │ HTTP (NEXUS_ENDPOINT)
@@ -57,25 +57,62 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
        ▼       ▼       ▼
     MCP-A   MCP-B   MCP-C
    (Win)   (WSL)   (SSH/VM)
-  Stateless adapter per IDE
+  n2n-nexus adapter per IDE
 ```
 
-- **Daemon is the source of truth**: start it once and keep it running.
-- **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.
+- **The host is the source of truth**: install it once and keep it running, as a tray app or as a background service.
+- **MCP adapters are stateless**: each IDE starts an adapter (`n2n-nexus mcp`), which forwards tool calls to the host.
+- **Every Claude Code and Codex conversation has its own identity**: client hooks register the conversation with the host 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 host from different machines or shells. The host listens on `127.0.0.1` by default; turn on LAN access only on a trusted network.
 
 ## 🚀 Quick start
 
-Requires Node.js 22.14+ on the 22.x release line, or Node.js 23.6+.
+### 1. Install the host
+
+| Platform | Install |
+| --- | --- |
+| Windows (Scoop) | `scoop bucket add n2ns https://github.com/n2ns/scoop-bucket`, then `scoop install n2ns/n2n-nexus-host` |
+| Windows (winget) | coming soon |
+| macOS (Homebrew) | `brew install n2ns/tap/n2n-nexus-host` |
+| Linux | download `n2n-nexus-host_<version>_linux_<amd64\|arm64>.tar.gz` from [Releases](https://github.com/n2ns/n2n-nexus/releases), extract it and put `n2n-nexus-host` on your `PATH` |
+
+[Releases](https://github.com/n2ns/n2n-nexus/releases) (tags `host-v<version>`) has the archives for every platform: `n2n-nexus-host_<version>_<os>_<arch>.zip` for Windows and `.tar.gz` for macOS and Linux, amd64 and arm64.
+
+- The binaries are not code-signed yet. On Windows, the first start of `n2n-nexus-host.exe` or `n2n-nexus-host-tray.exe` may show a SmartScreen warning: click **More info → Run anyway**. Homebrew builds the host from source on your Mac, so there is no Gatekeeper prompt.
+- Run `n2n-nexus-host` without arguments to start it as a tray app. The tray menu shows the address it listens on and the number of online sessions, opens the log and data folders, switches LAN access on and off, restarts the host and turns **Start at login** on or off (`n2n-nexus-host autostart on|off` does the same). The first time the tray runs it turns **Start at login** on; after that it stays as you set it. The menu is in Chinese on a Chinese system and in English otherwise.
+- Or run it as a background service that starts at boot, without a tray: `n2n-nexus-host service install` from an elevated terminal (Windows) or with `sudo` (macOS, Linux). The service runs as the user who installed it. Quit the tray first: `service install` refuses while the tray runs the host. While the service runs, a tray started later only controls it.
+- On Linux the tray needs a desktop with StatusNotifierItem (AppIndicator) support; on a server, use `service install`.
+
+Verify a download against the release's `SHA256SUMS` and its build provenance:
+
+```bash
+sha256sum -c SHA256SUMS --ignore-missing
+gh attestation verify n2n-nexus-host_<version>_<os>_<arch>.tar.gz --repo n2ns/n2n-nexus
+```
 
-### 1. Start the daemon
+### 2. Install the client and connect Claude Code or Codex
+
+Requires Node.js 22.14+ on the 22.x release line, or Node.js 23.6+.
 
 ```bash
-npx n2n-nexus daemon --port 5688
+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
+n2n-nexus doctor            # check the installed commands and that the host answers
 ```
 
-### 2. Configure an MCP client
+`install` writes the hooks and the MCP server into the client's user configuration.
+
+- Codex runs new hooks only after you trust them: open Codex and run `/hooks` once.
+- Pass `--endpoint <url>` to both commands when the host is not at `http://127.0.0.1:5688`, or `--endpoint discover` to find a host on the LAN.
+- On Windows, run `npm i -g` and `install` from a regular terminal, not from the terminal of a packaged app such as Codex: that terminal installs into the app's private copy of `%APPDATA%`, which hides the global install from the app.
+- 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 that the host they talk to answers with the client's contract version; it exits with code 1 when a check fails.
+- `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; Codex hooks also support Windows PowerShell. Other MCP clients can use every tool except direct messages.
+
+### Other MCP clients
 
 ```json
 {
@@ -91,40 +128,36 @@ npx n2n-nexus daemon --port 5688
 }
 ```
 
-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`).
+The adapter can start before the host. It loads the host's tool list once the host becomes reachable. The adapter and the hooks never start a host themselves: when none answers, tool calls fail with a message saying how to start it (or, for a remote endpoint, that it must be started on that machine), and the hooks skip silently. A call the host does not answer in time fails on its own; the host may still complete it.
 
-### 3. Direct messages between Claude Code and Codex conversations
+### 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:
+Each conversation 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`. An idle conversation is woken too: when a turn ends, a background hook waits up to an hour for anything new and then starts a turn with it (Claude Code through an `asyncRewake` hook, Codex through `codex queue`), so AI sessions can answer each other without anyone typing. An unattended `claude -p` run is not kept waiting: the hook returns at once there. A Codex conversation is woken only while it is loaded in the running Codex app, and not again after Codex restarts until it ends a turn; see [Architecture](docs/ARCHITECTURE.md#sessions-presence-and-waking-idle-conversations) for the limits. 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.
 
-```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
-```
+### LAN access
 
-- 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.
+By default the host listens on `127.0.0.1` only. To make it the host for other machines on a trusted network:
+
+- 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.
+- 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.
 
-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.
+A host that listens on a non-loopback address answers LAN discovery on UDP `discoveryPort`.
 
 ### Cross-environment endpoint examples
 
 | Scenario | `NEXUS_ENDPOINT` |
 | --- | --- |
 | Same machine | `http://127.0.0.1:5688` |
-| WSL IDE to Windows daemon | `http://host.docker.internal:5688` |
-| Windows IDE to WSL daemon | `http://<WSL-IP>:5688` |
+| WSL IDE to Windows host | `http://host.docker.internal:5688` |
+| Windows IDE to WSL host | `http://<WSL-IP>:5688` |
 | Remote machine | `http://<Server-IP>:5688` |
+| Find a host on the LAN | `discover` |
+
+With `discover`, the adapter and the hooks broadcast a query on UDP `NEXUS_DISCOVERY_PORT` and use the first host that answers; the result is cached in `~/.n2n-nexus/discovered-endpoint` and looked up again when that host cannot be reached. A host answers only when it listens on a non-loopback address (LAN access on), so allow UDP and TCP 5688 through its firewall for the trusted network. When none answers, the client uses `http://127.0.0.1:5688` (a host on this machine) and looks again after a minute.
 
 ## 🛠️ Toolset
 
-The daemon exposes 32 tools, grouped by purpose:
+The host exposes 33 tools, grouped by purpose:
 
 | Group | Tools | Purpose |
 | --- | --- | --- |
@@ -134,7 +167,7 @@ The daemon exposes 32 tools, grouped by purpose:
 | **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. |
+| **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. |
 
 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).
@@ -143,31 +176,43 @@ See [Tools reference](./docs/TOOLS_REFERENCE.md) for parameter schemas and call
 
 ## 💾 Data storage
 
-Default storage root:
+The host keeps all coordination data in one SQLite database in its data directory:
 
-| Platform | Path |
-| --- | --- |
-| Linux / WSL | `~/.n2n-nexus` |
-| Windows | `%USERPROFILE%\.n2n-nexus` |
-| macOS | `~/.n2n-nexus` |
+| Platform | Data directory | Log directory |
+| --- | --- | --- |
+| Windows | `%LOCALAPPDATA%\n2n-nexus` | `%LOCALAPPDATA%\n2n-nexus\logs` |
+| macOS | `~/Library/Application Support/n2n-nexus` | `~/Library/Logs/n2n-nexus` |
+| Linux | `$XDG_DATA_HOME/n2n-nexus` (default `~/.local/share/n2n-nexus`) | `$XDG_STATE_HOME/n2n-nexus` (default `~/.local/state/n2n-nexus`) |
 
-Override with `--root <path>` or `NEXUS_ROOT`.
+Override the data directory with `--root <path>` or `NEXUS_ROOT`.
 
 ```text
-~/.n2n-nexus/
-├── global/
-│   ├── blueprint.md
-│   ├── docs_index.json
-│   └── docs/
-├── projects/
-│   └── {project-id}/
-│       ├── manifest.json
-│       ├── internal_blueprint.md
-│       └── assets/
-├── registry.json
-└── nexus.db          # meetings, global chat, events, tasks, read cursors, conversations and direct messages
+<data directory>/
+├── nexus.db          # projects, assets, docs, meetings, global chat, events, tasks, read cursors, conversations, direct messages
+├── settings.json     # host settings (see below)
+└── host.lock         # one host per data directory
 ```
 
+The background service, and the tray while it runs the host itself, log to `host.log` in the log directory (10 MB per file, 3 old files kept); the tray's own lines go to `tray.log` there; `n2n-nexus-host serve` logs to standard error. Every hour the host deletes events, read or expired direct messages and delivered notices older than 30 days, and tasks 7 days after they finished.
+
+Data of n2n-nexus 0.x (`~/.n2n-nexus`) is not imported: the host does not read it and leaves it in place.
+
+### settings.json
+
+Read when the host starts; command-line flags override it. A missing file or field uses the default.
+
+| Field | Description | Default |
+| --- | --- | --- |
+| `host` | Address to listen on (an IPv4 address listens on IPv4 only, an IPv6 address on IPv6 only); `0.0.0.0` makes the host reachable from the LAN | `"127.0.0.1"` |
+| `port` | TCP port | `5688` |
+| `discoveryPort` | UDP port of LAN discovery, answered only when `host` is not a loopback address | `5688` |
+| `allowedHosts` | Extra DNS names accepted in the `Host` header (IP literals, `localhost` and `host.docker.internal` are always accepted) | `[]` |
+| `rateLimit` | Tool calls per second per instance; each client address gets 5x. Hooks have their own budget at the same rate per conversation and 5x per client address. `0` disables rate limiting | `20` |
+| `rateBurst` | Calls an instance may make at once before the per-second limit applies (minimum 1) | `60` |
+| `maxAutoTurns` | Automatic turns a conversation may take between its user's prompts (wakes, listening and Stops held open for messages); past it, messages wait until the user prompts. `0` disables the limit | `8` |
+
+After editing the file, restart the host (tray **Restart**, or restart `serve` or the service).
+
 ## 🏷️ Project ID conventions
 
 Project IDs follow `[prefix]_[name]`.
@@ -186,53 +231,86 @@ Project IDs follow `[prefix]_[name]`.
 
 ## 💻 CLI reference
 
+### n2n-nexus-host
+
 ```bash
-# Start daemon
-n2n-nexus daemon [--port 5688] [--root ~/.n2n-nexus] [--host 127.0.0.1]
+# Tray app (default)
+n2n-nexus-host
+
+# Run in the foreground without a tray; flags override settings.json (--port 0 picks a free port)
+n2n-nexus-host serve [--host 127.0.0.1] [--port 5688] [--root <dir>]
 
-# Start MCP adapter
-NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
+# Background service that starts at boot (elevated terminal on Windows, sudo on macOS / Linux).
+# install refuses while the tray runs the host (quit it first; reopened, it controls the service),
+# writes --host / --port to settings.json, stops a host running for the data directory,
+# registers and starts the service, and reports what answers on the port.
+# uninstall removes the service and stops its host; a tray or a foreground serve keeps running.
+n2n-nexus-host service install [--host <addr>] [--port <port>] [--root <dir>]
+n2n-nexus-host service uninstall [--root <dir>]
+n2n-nexus-host service status [--host <addr>] [--port <port>] [--root <dir>]
+
+# Start the tray at login, or stop doing so
+n2n-nexus-host autostart on|off
+
+n2n-nexus-host version
+```
+
+What `service install` registers, and where `autostart on` registers the tray:
+
+| Platform | Service (starts at boot, runs as the installing user, restarts the host 5 s after it exits) | Tray at login |
+| --- | --- | --- |
+| Windows | Scheduled task `n2n-nexus-host` | `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`, value `n2n-nexus-host` |
+| macOS | `/Library/LaunchDaemons/io.n2ns.n2n-nexus-host.plist` | `~/Library/LaunchAgents/io.n2ns.n2n-nexus-host.tray.plist` |
+| Linux | `/etc/systemd/system/n2n-nexus-host.service` | `~/.config/autostart/n2n-nexus-host.desktop` |
+
+Under `sudo`, the service uses the default data and log directories of the user who ran `sudo`, unless `--root` names another data directory. Only one host runs per data directory: a second one exits with "another n2n-nexus-host is running".
+
+### n2n-nexus (client)
+
+```bash
+# Start the MCP adapter (launched by the IDE)
+NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp [--id <instance id>]
 
 # 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)
+# Check that the installed hook and MCP commands still run and that the host answers
+# with the client's contract version (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>]
+n2n-nexus hook <claude|codex> [--endpoint <url>] [--wait]
 ```
 
 ### Environment variables
 
+Client (`n2n-nexus`):
+
 | Variable | Description | Default |
 | --- | --- | --- |
-| `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` |
-| `NEXUS_RATE_LIMIT` | Tool calls per second per instance; each client address gets 5x. `0` disables rate limiting | `20` |
-| `NEXUS_RATE_BURST` | Calls an instance may make at once before the per-second limit applies (minimum 1) | `60` |
-| `NEXUS_ALLOWED_HOSTS` | Extra DNS names accepted in the `Host` header (IP literals, `localhost`, `host.docker.internal` are always accepted) | empty |
-| `NEXUS_INSTANCE_ID` | Override MCP instance ID (read cursors and meeting permissions are keyed on it) | `mcp-<hostname>-<hash of working directory>-<IDE name>` |
+| `NEXUS_ENDPOINT` | Host URL for the MCP adapter, the hooks and `doctor`, or `discover` to find one on the LAN | `http://127.0.0.1:5688` |
+| `NEXUS_DISCOVERY_PORT` | UDP port the client queries with `discover` | `5688` |
+| `NEXUS_INSTANCE_ID` | Override the MCP instance ID (read cursors and meeting permissions are keyed on it) | `mcp-<hostname>-<hash of working directory>-<IDE name>` |
+| `NEXUS_CODEX_COMMAND` | Command the Codex background wait runs as `<command> queue ...` | `codex` |
+
+Host (`n2n-nexus-host`): only `NEXUS_ROOT`, the data directory (`--root` overrides it). Every other host setting is in `settings.json`, which the tray, the service and the command line share.
 
 ## 🔐 Security and governance notes
 
 - n2n-nexus stores coordination data locally by default.
 - Do not put secrets, credentials, customer data, or private tokens in meeting messages or project assets unless your local policy allows it.
 - Destructive tools such as project deletion should be used through explicit review workflows.
-- Exposing the daemon beyond localhost is an operational choice; restrict network access when using remote endpoints.
+- Exposing the host beyond localhost is an operational choice; restrict network access when using remote endpoints.
 - Treat project manifests and internal docs as potentially sensitive implementation data.
 
 ## 🌐 Real-world example
 
-The docs include a recorded multi-agent session that shows n2n-nexus in action. Four AI assistants — running in different IDEs and assigned to different projects — used a shared n2n-nexus daemon to coordinate in real time.
+The docs include a recorded multi-agent session that shows n2n-nexus in action. Four AI assistants — running in different IDEs and assigned to different projects — used a shared n2n-nexus host to coordinate in real time.
 
 What to look for in the session:
 
-- **Shared coordination space**: each assistant registered its active project (with the `register_session_context` tool of that release; current versions pass `projectId` explicitly instead), then read and wrote to the same daemon throughout the session.
+- **Shared coordination space**: each assistant registered its active project (with the `register_session_context` tool of that release; current versions pass `projectId` explicitly instead), then read and wrote to the same host throughout the session.
 - **Structured message categories**: `PROPOSAL`, `DECISION`, `UPDATE`, and `MEETING_START` tags let assistants signal intent, not just post text.
 - **SYSTEM entries**: lines like `[Augment] Synced global doc: edge-sync-protocol-v1` record actual tool calls. That version wrote them into the chat stream; current versions keep them out of the conversation and expose them as structured events through `list_events`.
 - **Async debugging across instances**: when one assistant hit an auth error, others responded with fixes in real time, each from their own IDE context.
@@ -245,7 +323,7 @@ What to look for in the session:
 
 ## 🔧 Local development
 
-Use Node.js 24 for development, matching CI and the lint toolchain.
+Use Node.js 24 for the client, matching CI and the lint toolchain, and the Go version in `go.mod` for the host.
 
 ```bash
 git clone https://github.com/n2ns/n2n-nexus.git
@@ -253,16 +331,18 @@ cd n2n-nexus
 npm install
 npm run build
 
-# Run daemon
-node build/index.js daemon --root /tmp/nexus-test --port 5688
+# Run a host
+go run ./host/cmd/n2n-nexus-host serve --port 5799 --root /tmp/nexus-test
 
-# Run MCP adapter
-NEXUS_ENDPOINT=http://127.0.0.1:5688 node build/index.js mcp
+# Run the MCP adapter against it
+NEXUS_ENDPOINT=http://127.0.0.1:5799 node build/index.js mcp
 ```
 
+See [host/README.md](./host/README.md) for building, testing and releasing the host.
+
 ## 📖 Related docs
 
-- **[Architecture](./docs/ARCHITECTURE.md)**: System design and daemon-adapter separation explained.
+- **[Architecture](./docs/ARCHITECTURE.md)**: System design and host-client separation explained.
 - **[Tools reference](./docs/TOOLS_REFERENCE.md)**: Full tool list and parameters.
 - **[AI Assistant Guide](./docs/ASSISTANT_GUIDE.md)**: How AI assistants should call tools and stay in project context.
 - **[Changelog](./CHANGELOG.md)**: Version history and release notes.

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes target the latest published versions of n2n-nexus (npm client) and n2n-nexus-host.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for suspected vulnerabilities.
+
+Report security concerns through GitHub private vulnerability reporting for this repository, or contact Datafrog through the security channel listed on the organization profile.
+
+When reporting, include:
+
+- A description of the vulnerability.
+- Steps to reproduce or a proof of concept.
+- Affected versions or commit hashes.
+- Any known impact or mitigation.
+
+We aim to acknowledge reports within 5 business days.
+
+## Security Model
+
+n2n-nexus runs a local HTTP host, `n2n-nexus-host`, that stores coordination data in `nexus.db` in its data directory (`%LOCALAPPDATA%\n2n-nexus`, `~/Library/Application Support/n2n-nexus` or `~/.local/share/n2n-nexus` by default). It does not send project data to remote services.
+
+Key boundaries to be aware of:
+
+- **Unsigned binaries**: The `n2n-nexus-host` release binaries are not code-signed yet. Verify a download with the release's `SHA256SUMS` and `gh attestation verify <file> --repo n2ns/n2n-nexus` (build provenance), or install through Homebrew, which builds from source.
+- **Local trust model**: Every process running as the same operating-system user is trusted. The host has no authentication; such a process can call it directly or read and write `nexus.db` and the client transcripts under `~/.claude` and `~/.codex`. Conversation IDs and Claude tool-use bindings route direct messages between conversations; they are not credentials, so an AI session with shell access can act as another conversation of the same user. Checks inside the host cannot prevent that while the data stays readable to that user. The barrier that matters is the client's permission to run commands, which the user controls. To isolate agents from each other, run them as different operating-system users, each with its own host and data directory.
+
+- **Host network exposure**: The host binds to `127.0.0.1` by default. LAN access (the tray's **Allow LAN access**, `"host": "0.0.0.0"` in `settings.json`, or `--host 0.0.0.0`) exposes it to your local network, and it then answers LAN discovery on UDP `discoveryPort`. There is no authentication layer in the open-source baseline — only expose the host beyond localhost on networks you control.
+- **Browser requests**: The host has no authentication, so it refuses requests that carry a browser `Origin` header or a cross-site `Sec-Fetch-Site` header (403), requires `Content-Type: application/json` on POST (415) and caps request bodies at 16 MB (413). It also rejects any `Host` header that is not an IP literal, `localhost`, `host.docker.internal` or a name listed in `allowedHosts` in `settings.json`, which closes DNS-rebinding attacks where a page reaches the host as a same-origin request under the attacker's domain. MCP adapters and scripts are unaffected.
+- **Rate limiting**: Tool calls are limited per instance ID (default 20/s, burst 60, set with `rateLimit` / `rateBurst` in `settings.json`) and, because instance IDs are self-declared, per client address at five times that. Tool calls that name no instance ID are limited only per address. Hooks (`POST /api/hook`) are limited per conversation and per client address in buckets of their own. Over the limit the host answers `429` with `Retry-After`; `/health` and `GET /api/tools` are exempt.
+- **Malformed requests**: Invalid request URLs or Host headers return 400 without terminating the host. Validly formed requests still pass through the browser and Host checks above.
+- **Sensitive content in coordination data**: Project manifests, internal docs, meeting messages, and global documents are stored in plaintext in the host's local database. Do not store secrets, credentials, or customer data in these fields.
+- **Project assets**: Binary assets uploaded via `upload_project_asset` are stored in the host's database in its data directory. Treat them as local files with the same access controls.
+- **API key for MCP**: The MCP adapter connects to the host over plain HTTP. If you expose the host to other machines, consider adding a reverse proxy with TLS in front of it.

package/build/cli/client-command.js

@@ -0,0 +1,58 @@
+/**
+ * Run the `claude` / `codex` command without a shell. On Windows npm installs
+ * them as `.cmd` shims, which Node cannot start without cmd.exe, and cmd.exe
+ * would parse the arguments again: a message text from another session could
+ * end a quoted argument and run commands, and a newline ends the command line.
+ * So a shim written by npm is resolved to the script it runs, started with
+ * this Node; an `.exe` or `.com` runs directly; anything else is not run.
+ *
+ * Node built-ins only: the hook command imports this to run `codex queue`.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+/** The bin path in npm's cmd-shim launch line: `"%dp0%\<path>" %*`. */
+const NPM_SHIM_TARGET = /"%~?dp0%?\\([^"]+)"\s*%\*/;
+/** The program and leading arguments that run `name` on this platform, or null when it cannot be run without a shell. */
+export function clientCommand(name) {
+    if (process.platform !== "win32")
+        return { command: name, args: [] };
+    const file = findOnPath(name);
+    if (!file)
+        return null;
+    const ext = path.extname(file).toLowerCase();
+    if (ext === ".exe" || ext === ".com")
+        return { command: file, args: [] };
+    if (ext !== ".cmd" && ext !== ".bat")
+        return null;
+    const target = NPM_SHIM_TARGET.exec(fs.readFileSync(file, "utf8"))?.[1];
+    if (!target)
+        return null;
+    const script = path.join(path.dirname(file), ...target.split(/[\\/]+/));
+    const scriptExt = path.extname(script).toLowerCase();
+    if (scriptExt === ".exe")
+        return { command: script, args: [] };
+    return [".js", ".cjs", ".mjs"].includes(scriptExt) || scriptExt === "" ? { command: process.execPath, args: [script] } : null;
+}
+/** `name` as given (a path) or the first PATH entry with a PATHEXT extension that exists. */
+function findOnPath(name) {
+    const exts = (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    const candidates = (base) => path.extname(base) ? [base] : exts.map((ext) => base + ext.toLowerCase());
+    const dirs = /[\\/]/.test(name) ? [""] : (process.env.PATH || "").split(path.delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        for (const file of candidates(dir ? path.join(dir, name) : name)) {
+            if (fs.existsSync(file) && fs.statSync(file).isFile())
+                return file;
+        }
+    }
+    return null;
+}
+/** spawnSync for a client command; a command that cannot be run reports ENOENT like a missing one. */
+export function spawnClientSync(name, args, options) {
+    const resolved = clientCommand(name);
+    if (!resolved) {
+        const error = Object.assign(new Error(`spawnSync ${name} ENOENT`), { code: "ENOENT" });
+        return { pid: 0, output: [], stdout: "", stderr: "", status: null, signal: null, error };
+    }
+    return spawnSync(resolved.command, [...resolved.args, ...args], options);
+}