n2n-nexus 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.9.4] - 2026-10-26
+
+### Changed
+
+- Contract version 2: the npm client and the host must be upgraded together (`n2n-nexus doctor` reports a mismatch).
+- Chat and meetings identify the conversation, not the MCP adapter instance, when the n2n-nexus hooks are installed. Several conversations of one IDE in one workspace share an instance; they now keep their own unread cursors, and their messages, a meeting's `initiator` and `participants` and the `actor` of `meeting.*` events carry their session id (`claude:<id>` / `codex:<id>`), which works with `send`. Clients without the hooks keep using the instance. If an instance has had a conversation identified within the last 30 minutes and a call of it cannot be identified, the call fails with a retry message instead of reading through the shared cursor. Results say which identity was used (`identity`).
+- `read_messages` no longer returns your own messages in unread mode; a conversation's first unread read of global chat starts at the newest message. New history mode: `latest: true` or `afterId` read without moving a cursor and include your own messages. Each message has `senderName`, and `category` is always present (null without one).
+- Meeting messages are numbered per meeting, from 1: `id` in `read_messages`, `messageId` from `send_message` (now returned for meetings too) and `afterId` in a meeting use that number, so a new meeting no longer continues the numbers of earlier ones.
+
+- Meetings have members. `join_meeting(meetingId, mode?, approver?, since?)` and `leave_meeting(meetingId)`; the initiator joins its meeting. News of a meeting reaches its members through the hooks as one line per meeting: active members are woken (or their turn continues), async members see it at their next prompt or tool call, and nobody is told about their own messages. Meeting news is not an automatic turn and still arrives past `maxAutoTurns`, so a meeting runs until it is ended; ending it gives each other member one notice. `list_meetings` shows the members and how many wakes the meeting caused.
+- Decisions by consensus. `send_message(..., draft: true)` publishes a meeting's current draft and fixes its required approvers (members that joined as `required` through the hooks); `stance(meetingId, messageId, endorse | object | withdraw, note?)` takes a stance on it, an objection with its reason. When at least two required approvers endorsed the current draft and nobody objects, the meeting closes by itself with the draft as a `DECISION` (`endReason: consensus`; `end_meeting` records `manual`). Ordinary proposals do not reset stances; a leaving or re-joining approver changes the list, which is posted to the meeting. Required approvers that have not taken a stance after a quiet `stanceReminderMinutes` (new `settings.json` field, default 10) are reminded once. `list_meetings` shows each meeting's `endReason` and current draft with its stances.
+- Direct messages say what they ask: `send` and `reply` take `expectsReply` (false: the notification says no reply is needed and does not ask for one) and `wake` (false: the message never wakes the recipient or holds its turn, and waits for its next prompt or tool call). `read` returns `expectsReply`.
+- Sessions have a readable `title`: the conversation's title as Claude Code or Codex shows it, read by the hooks and shown next to the name in `peers`, introductions, notifications and meeting members. `set_profile({ title })` sets your own (`""` returns to the client's). The name stays the handle for `send`.
+- A direct message is listed in full once; while it stays unread, later notifications only count it.
+
+### Fixed
+
+- A failed `codex queue` no longer loses the wake: the Codex background wait reports the result and the host undoes a wake that was not delivered, and the wait tries again after a delay (1 s, doubling up to 5 minutes), so the same messages and notices wake the conversation again; the failed wake is not counted as an automatic turn. The session no longer stays `working` until it goes stale.
+- A session that goes offline after 30 minutes without activity now tells its `notifyWhenIdle` subscribers, as a session that ends does, also when they only wait in the background.
+- The prompt that starts a woken turn no longer announces again what the wake announced.
+- The Codex SessionEnd hook fits Codex's 3-second limit: `n2n-nexus install codex` writes timeout 3 (run it again to update an existing installation, which removes Codex's "clamping SessionEnd hook timeout" warning), and the SessionEnd request gives up after 1.5 s without a second host lookup.
+- `n2n-nexus uninstall <client>` no longer needs the client on PATH: it removes the hooks from the client's config file anyway. Without the client it skips `<client> mcp remove` and, when the MCP server is still registered, says so and how to remove it (run that command later, or delete the `n2n-nexus` entry from `~/.claude.json` / `config.toml`). `install` still requires the client.
+- Tool calls are rate limited per conversation when the hooks identify it, so conversations that share an adapter instance (one client in one directory) no longer use up each other's budget; without the hooks calls are still limited per instance. The per-address limit is unchanged.
+
 ## [0.9.3] - 2026-10-24
 
 ### Changed

package/README.md

@@ -142,7 +142,7 @@ No. `n2n-memory` is a local memory tool for a single repository. `n2n-nexus` is
 
 ### Does it support Claude Desktop, Cursor, VS Code and other clients?
 
-Yes, as long as the client can run a local MCP command server. The IDE starts the adapter, and the adapter reaches the local host through `NEXUS_ENDPOINT`.
+Yes, as long as the client can run a local MCP command server. The IDE starts the adapter, and the adapter reaches the local host through `NEXUS_ENDPOINT`. In the Claude desktop app, register it for Claude Code (`n2n-nexus install claude`) only, not in `claude_desktop_config.json`: the app would bridge it into the Code tab and drop the conversation identity ([User guide, section 2](docs/USER_GUIDE.md#2-claude-desktop-app)).
 
 ### Can Windows and WSL work together?
 

package/SECURITY.md

@@ -32,7 +32,7 @@ Key boundaries to be aware of:
 
 - **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.
+- **Rate limiting**: Tool calls are limited per conversation, or per instance ID when no conversation is identified (default 20/s, burst 60, set with `rateLimit` / `rateBurst` in `settings.json`) and, because instance and session IDs are self-declared, per client address at five times that. Tool calls that name neither a conversation nor an 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.
 - **Destructive tools**: Destructive tools such as project deletion should be used through explicit review workflows.

package/build/cli/hook.js

@@ -2,15 +2,19 @@
  * `n2n-nexus hook <claude|codex> [--endpoint <url>] [--wait]`: forward one client
  * hook event to the daemon and print its output, or with `--wait` run the
  * background wait that wakes an idle conversation. Runs on every tool call, so
- * it loads only node built-ins (no MCP SDK, zod or SQLite), and every failure
+ * it loads only node built-ins (no MCP SDK or zod; node:sqlite only to read a
+ * Codex conversation's title, see title.ts), and every failure
  * is silent: exit 0 with nothing on stdout, so the client carries on unaffected.
  */
 import { spawn } from "node:child_process";
-import { BACKGROUND_WAIT_EVENT, HOOK_INPUT_FIELDS, HOOK_REQUEST_TIMEOUT_MS, HOOK_STOP_REQUEST_TIMEOUT_MS, WAIT_HOOK_TIMEOUT_SEC, noDaemonHint, isHookClient } from "../contract.js";
+import { BACKGROUND_WAIT_EVENT, WAKE_RESULT_EVENT, HOOK_INPUT_FIELDS, HOOK_REQUEST_TIMEOUT_MS, HOOK_STOP_REQUEST_TIMEOUT_MS, SESSION_END_REQUEST_TIMEOUT_MS, WAIT_HOOK_TIMEOUT_SEC, WAKE_RETRY_FIRST_DELAY_MS, WAKE_RETRY_MAX_DELAY_MS, noDaemonHint, isHookClient } from "../contract.js";
 import { NexusClient, NexusTransportError, REQUEST_TIMEOUT_CODE } from "../client/nexus-client.js";
 import { DISCOVER_ENDPOINT, LOCAL_ENDPOINT, resolveEndpoint } from "../client/discovery.js";
+import { readTitle } from "./title.js";
 /** Errors after which a discovered daemon is looked up again: it was never reached, so resending is safe. */
 const UNREACHABLE_CODES = new Set(["ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH", "ETIMEDOUT", "EADDRNOTAVAIL"]);
+/** Events whose forwarded input carries the conversation's title. */
+const TITLE_EVENTS = new Set(["SessionStart", "UserPromptSubmit", "Stop"]);
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -38,7 +42,15 @@ async function forward(argv) {
         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;
+    // The title is read only where the host updates it, not on the frequent tool events.
+    if (typeof stdin.hook_event_name === "string" && TITLE_EVENTS.has(stdin.hook_event_name)) {
+        const title = await readTitle(client, stdin);
+        if (title !== undefined)
+            input.title = title;
+    }
+    // SessionEnd must finish within Codex's 3 s hook limit (discovery included): a short budget and a single attempt.
+    const sessionEnd = stdin.hook_event_name === "SessionEnd";
+    const timeoutMs = stdin.hook_event_name === "Stop" ? HOOK_STOP_REQUEST_TIMEOUT_MS : sessionEnd ? SESSION_END_REQUEST_TIMEOUT_MS : HOOK_REQUEST_TIMEOUT_MS;
     /** Send to `endpoint`; nothing listening there is reported with what to do about it. */
     const send = async (endpoint) => {
         try {
@@ -60,7 +72,7 @@ async function forward(argv) {
         // A timed-out Stop may have been waiting for messages on purpose, so only other events count a timeout.
         const code = error instanceof NexusTransportError ? error.code ?? "" : "";
         const unreachable = UNREACHABLE_CODES.has(code) || (code === REQUEST_TIMEOUT_CODE && stdin.hook_event_name !== "Stop");
-        if (configured !== DISCOVER_ENDPOINT || !unreachable)
+        if (configured !== DISCOVER_ENDPOINT || !unreachable || sessionEnd)
             throw error;
         const found = await resolveEndpoint(configured, { fresh: true });
         if (found === endpoint)
@@ -79,8 +91,8 @@ 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;
 /**
- * Ask the daemon until something arrives for the session (the notification
- * text), the session becomes active again or the deadline passes (null).
+ * 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 });
@@ -89,8 +101,8 @@ export async function waitForWake(client, sessionId, endpoint, deadlineMs = WAIT
     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);
         const output = isPlainObject(response) ? response.output : null;
-        if (isPlainObject(output) && typeof output.wake === "string")
-            return output.wake;
+        if (isPlainObject(output) && typeof output.wake === "string" && typeof output.dispatchId === "string")
+            return { text: output.wake, dispatchId: output.dispatchId };
         if (!(isPlainObject(output) && output.timeout === true))
             return null;
     }
@@ -101,7 +113,11 @@ export async function waitForWake(client, sessionId, endpoint, deadlineMs = WAIT
  * asyncRewake hook: exit code 2 with the notification on stderr wakes the
  * conversation. Codex has no such hook, so its Stop hook starts a detached copy
  * (`--session <id>`) and returns at once; the copy hands the notification to
- * `codex queue` (NEXUS_CODEX_COMMAND, default `codex`), which starts a turn.
+ * `codex queue` (NEXUS_CODEX_COMMAND, default `codex`), which starts a turn,
+ * and reports to the host whether it did (WAKE_RESULT_EVENT): after a failed
+ * queue the host undoes the wake and the copy waits again after a delay that
+ * doubles on each failure, so the same messages wake the session on a later
+ * try without retrying a broken `codex` in a loop.
  */
 async function runWait(argv) {
     const client = argv[0];
@@ -127,16 +143,26 @@ 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 text = await waitForWake(client, sessionId, await resolveEndpoint(configured));
-    if (text === null)
-        return 0;
-    if (spawnClientSync) {
+    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());
+        if (wake === null)
+            return 0;
+        if (!spawnClientSync) {
+            await new Promise((resolve) => process.stderr.write(wake.text + "\n", () => resolve()));
+            return 2;
+        }
         // Never through cmd.exe: the text comes from another session and spans several lines.
-        spawnClientSync(process.env.NEXUS_CODEX_COMMAND || "codex", ["queue", "--thread", sessionId, "--message", text], { stdio: "ignore", windowsHide: true });
-        return 0;
+        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);
+        // Unknown result (no report): the host keeps the wake, and waiting again would deliver nothing.
+        if (ok || !reported || Date.now() + delay >= deadline)
+            return 0;
+        await new Promise((resolve) => setTimeout(resolve, delay));
     }
-    await new Promise((resolve) => process.stderr.write(text + "\n", () => resolve()));
-    return 2;
 }
 /** Run the hook command; resolves to exit code 0, or 2 when a background wait wakes a Claude conversation. */
 export async function runHook(argv) {

package/build/cli/install.js

@@ -17,7 +17,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { CLAUDE_PRE_TOOL_MATCHER, HOOK_STOP_TIMEOUT_SEC, HOOK_TIMEOUT_SEC, MCP_SERVER_NAME, WAIT_HOOK_TIMEOUT_SEC, isHookClient } from "../contract.js";
+import { CLAUDE_PRE_TOOL_MATCHER, CODEX_SESSION_END_TIMEOUT_SEC, HOOK_STOP_TIMEOUT_SEC, HOOK_TIMEOUT_SEC, MCP_SERVER_NAME, WAIT_HOOK_TIMEOUT_SEC, isHookClient } from "../contract.js";
 import { pkg } from "../config/index.js";
 import { spawnClientSync } from "./client-command.js";
 import { entryScript } from "./entry.js";
@@ -210,7 +210,11 @@ function removeOurEntries(config, client, file) {
 function addOurEntries(config, client, command, commandWindows) {
     const hooks = (config.hooks ??= {});
     for (const event of EVENTS[client]) {
-        const entry = { type: "command", command, timeout: event === "Stop" ? HOOK_STOP_TIMEOUT_SEC : HOOK_TIMEOUT_SEC };
+        // Codex clamps a SessionEnd hook timeout above 3 s (and warns in its settings), so ask for 3 s there.
+        const timeout = event === "Stop" ? HOOK_STOP_TIMEOUT_SEC
+            : client === "codex" && event === "SessionEnd" ? CODEX_SESSION_END_TIMEOUT_SEC
+                : HOOK_TIMEOUT_SEC;
+        const entry = { type: "command", command, timeout };
         if (commandWindows)
             entry.commandWindows = commandWindows;
         const group = client === "claude" && event === "PreToolUse"
@@ -289,7 +293,9 @@ function runClient(client, args, stdio) {
 /**
  * Run `<client> mcp remove`. A failure is ignored only when `<client> mcp get`
  * shows the server is not registered (never installed, or already removed);
- * otherwise the removal really failed and we stop before `mcp add`.
+ * otherwise the removal really failed and we stop before `mcp add`. On
+ * uninstall, a client that cannot be run skips the step with a note on how to
+ * remove the registration that is still there.
  */
 function removeMcpServer(client, action, hooksRemoved) {
     const removeArgs = mcpRemoveArgs(client);
@@ -311,6 +317,13 @@ function removeMcpServer(client, action, hooksRemoved) {
         }
         if (!registered)
             return;
+        if (action === "uninstall" && error.code === "ENOENT") {
+            const file = mcpConfigFile(client);
+            const what = client === "claude" ? `the "${MCP_SERVER_NAME}" entry under "mcpServers"` : `the [mcp_servers.${MCP_SERVER_NAME}] table`;
+            process.stdout.write(`Skipped "${client} ${removeArgs.join(" ")}": the "${client}" command could not be run (not on PATH, or not runnable without a shell). `
+                + `The MCP server is still registered in ${file}; run that command once ${client} can be run, or delete ${what} from ${file}.\n`);
+            return;
+        }
         const failure = error;
         const stderr = typeof failure.stderr === "string" ? failure.stderr.trim() : "";
         const detail = stderr || (typeof failure.status === "number" ? `exit code ${failure.status}` : failure.message);
@@ -328,9 +341,12 @@ export function runInstall(options) {
         if (action === "install" && /[/\\]_npx[/\\]/.test(entry)) {
             throw new InstallError(`n2n-nexus is running from an npx cache (${entry}), which can be cleared at any time. Install it first: npm i -g ${MCP_PACKAGE}`);
         }
-        const probe = spawnClientSync(client, ["--version"], { stdio: "ignore" });
-        if (probe.error || probe.status !== 0) {
-            throw new InstallError(`The "${client}" command was not found on PATH; install ${client === "claude" ? "Claude Code" : "Codex"} first.`);
+        // Uninstall does not need the client: our hooks are removed from its config file either way.
+        if (action === "install") {
+            const probe = spawnClientSync(client, ["--version"], { stdio: "ignore" });
+            if (probe.error || probe.status !== 0) {
+                throw new InstallError(`The "${client}" command was not found on PATH; install ${client === "claude" ? "Claude Code" : "Codex"} first.`);
+            }
         }
         const node = action === "install" ? (options.node ? checkNodePath(options.node) : stableNodePath()) : undefined;
         const npm = node ? npxFor(node) : undefined;

package/build/cli/title.js

@@ -0,0 +1,126 @@
+/**
+ * The conversation's title as its client shows it, which the hook command adds
+ * to the input it forwards as `title`. Neither source is documented, so every
+ * failure (missing file, unexpected format, locked database, time budget
+ * spent) yields undefined and the hook goes on without a title.
+ *
+ * Claude Code: the transcript (`transcript_path`, JSONL, can be very large)
+ * gets `{"type":"custom-title","customTitle":…}` records when the user renames
+ * the conversation and `{"type":"ai-title","aiTitle":…}` records for the
+ * automatic title, appended again and again; only its last and, failing that,
+ * first TRANSCRIPT_CHUNK_BYTES are read. Codex: `threads.name` (set by the
+ * user) or else `threads.title` in the newest `$CODEX_HOME/state_<N>.sqlite`.
+ */
+import { open, readdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { MAX_TITLE_CHARS } from "../contract.js";
+/** How much of the transcript's end, and then of its start, is searched for a title. */
+const TRANSCRIPT_CHUNK_BYTES = 256 * 1024;
+/** Reading the title may not hold up the hook for longer than this. */
+const TITLE_BUDGET_MS = 50;
+/** Trimmed first line, at most MAX_TITLE_CHARS characters; undefined when nothing is left. */
+export function cleanTitle(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const line = value.trim().split(/\r\n|\r|\n/)[0].trim();
+    const chars = Array.from(line);
+    const title = chars.length > MAX_TITLE_CHARS ? chars.slice(0, MAX_TITLE_CHARS).join("").trimEnd() : line;
+    return title || undefined;
+}
+/** The last custom title in `text`, or else the last automatic one. */
+function titleInJsonl(text) {
+    let custom;
+    let ai;
+    for (const line of text.split("\n")) {
+        if (!line.includes("-title"))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue; // the chunk's cut-off first or last line
+        }
+        if (typeof record !== "object" || record === null)
+            continue;
+        const { type, customTitle, aiTitle } = record;
+        if (type === "custom-title")
+            custom = cleanTitle(customTitle) ?? custom;
+        else if (type === "ai-title")
+            ai = cleanTitle(aiTitle) ?? ai;
+    }
+    return custom ?? ai;
+}
+async function claudeTitle(transcriptPath) {
+    if (typeof transcriptPath !== "string" || !transcriptPath)
+        return undefined;
+    const file = await open(transcriptPath, "r");
+    try {
+        const { size } = await file.stat();
+        const read = async (position, length) => {
+            const buffer = Buffer.alloc(length);
+            const { bytesRead } = await file.read(buffer, 0, length, position);
+            return buffer.toString("utf8", 0, bytesRead);
+        };
+        const tailStart = Math.max(0, size - TRANSCRIPT_CHUNK_BYTES);
+        const title = titleInJsonl(await read(tailStart, size - tailStart));
+        if (title !== undefined || tailStart === 0)
+            return title;
+        return titleInJsonl(await read(0, TRANSCRIPT_CHUNK_BYTES));
+    }
+    finally {
+        await file.close();
+    }
+}
+/** node:sqlite without the ExperimentalWarning older Node versions print on stderr when it loads. */
+async function loadSqlite() {
+    const emitWarning = process.emitWarning;
+    process.emitWarning = function (warning, ...args) {
+        const type = typeof args[0] === "string" ? args[0] : args[0]?.type ?? (warning instanceof Error ? warning.name : undefined);
+        const message = warning instanceof Error ? warning.message : String(warning);
+        if (type === "ExperimentalWarning" && message.includes("SQLite"))
+            return;
+        return emitWarning.call(process, warning, ...args);
+    };
+    try {
+        return await import("node:sqlite");
+    }
+    finally {
+        process.emitWarning = emitWarning;
+    }
+}
+async function codexTitle(sessionId) {
+    if (typeof sessionId !== "string" || !sessionId)
+        return undefined;
+    const home = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+    let newest;
+    for (const name of await readdir(home)) {
+        const match = /^state_(\d+)\.sqlite$/.exec(name);
+        if (match && (newest === undefined || Number(match[1]) > newest.n))
+            newest = { n: Number(match[1]), name };
+    }
+    if (!newest)
+        return undefined;
+    const { DatabaseSync } = await loadSqlite();
+    const db = new DatabaseSync(path.join(home, newest.name), { readOnly: true });
+    try {
+        const row = db.prepare("SELECT name, title FROM threads WHERE id = ?").get(sessionId);
+        return row ? cleanTitle(row.name) ?? cleanTitle(row.title) : undefined;
+    }
+    finally {
+        db.close();
+    }
+}
+/** The title of the conversation `input` (the hook's stdin) belongs to, or undefined; never throws. */
+export async function readTitle(client, input) {
+    let timer;
+    const budget = new Promise((resolve) => { timer = setTimeout(resolve, TITLE_BUDGET_MS, undefined); });
+    const read = client === "claude" ? claudeTitle(input.transcript_path) : codexTitle(input.session_id);
+    try {
+        return await Promise.race([read.catch(() => undefined), budget]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/build/contract.js

@@ -24,20 +24,28 @@ export const CLIENT_INFO_NAMES = contract.clientInfoNames;
 export const CLAUDE_TOOL_USE_META_KEY = contract.meta.claudeToolUseKey;
 export const CODEX_SESSION_META_KEY = contract.meta.codexSessionKey;
 /**
- * Hook stdin fields the host uses. The hook command forwards only these:
+ * Hook stdin fields the host uses. The hook command forwards only these (plus
+ * `title` on SessionStart, UserPromptSubmit and Stop, see cli/title.ts):
  * PostToolUse stdin also carries the whole tool input and response, which can
  * be large and runs on every tool call.
  */
 export const HOOK_INPUT_FIELDS = contract.hookInputFields;
 /**
  * Pseudo hook event of the background wait (`n2n-nexus hook <client> --wait`):
- * started when a turn ends, it waits and returns `{ wake: text }` when
+ * started when a turn ends, it waits and returns `{ wake: text, dispatchId }` when
  * something new arrives for the session, `{ timeout: true }` when the time
  * runs out (the client asks again), or null when the session became active
  * again (the client stops). Claude delivers the text through an asyncRewake
  * hook, Codex through `codex queue`.
  */
 export const BACKGROUND_WAIT_EVENT = contract.backgroundWaitEvent;
+/**
+ * Pseudo hook event with which the Codex background wait reports whether
+ * `codex queue` took a wake: input `{ session_id, dispatch_id, ok }`. On
+ * `ok: false` the host undoes the wake, so its messages and notices wake the
+ * session again.
+ */
+export const WAKE_RESULT_EVENT = contract.wakeResultEvent;
 /** HTTP timeout of the hook command: a listening Stop may wait long, every other event is quick. */
 export const HOOK_STOP_REQUEST_TIMEOUT_MS = contract.timing.hookStopRequestTimeoutMs;
 export const HOOK_REQUEST_TIMEOUT_MS = contract.timing.hookRequestTimeoutMs;
@@ -46,6 +54,18 @@ export const HOOK_STOP_TIMEOUT_SEC = contract.timing.hookStopTimeoutSec;
 /** `timeout` (seconds) of the background wait hook; a conversation idle for longer is not woken. */
 export const WAIT_HOOK_TIMEOUT_SEC = contract.timing.waitHookTimeoutSec;
 export const HOOK_TIMEOUT_SEC = contract.timing.hookTimeoutSec;
+/** `timeout` (seconds) of the Codex SessionEnd hook: Codex clamps a longer one to 3 s and warns about it. */
+export const CODEX_SESSION_END_TIMEOUT_SEC = contract.timing.codexSessionEndTimeoutSec;
+/** HTTP timeout of a SessionEnd hook, which is not resent after a timeout so it ends within CODEX_SESSION_END_TIMEOUT_SEC. */
+export const SESSION_END_REQUEST_TIMEOUT_MS = contract.timing.sessionEndRequestTimeoutMs;
+/** After a failed `codex queue`, the Codex wait asks again after this delay, doubled on each failure up to the maximum. */
+export const WAKE_RETRY_FIRST_DELAY_MS = contract.timing.wakeRetryFirstDelayMs;
+export const WAKE_RETRY_MAX_DELAY_MS = contract.timing.wakeRetryMaxDelayMs;
+/**
+ * The hook command adds the conversation's title, as its client shows it, to
+ * the input it forwards as `title` (at most this many characters).
+ */
+export const MAX_TITLE_CHARS = contract.limits.maxTitleChars;
 /** Name the MCP server is installed under; Claude's PreToolUse matcher depends on it. */
 export const MCP_SERVER_NAME = contract.mcpServerName;
 export const CLAUDE_PRE_TOOL_MATCHER = `mcp__${MCP_SERVER_NAME}__.*`;

package/build/server/nexus.js

@@ -12,10 +12,14 @@ 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; listen waits for messages after each turn. " +
+    "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. " +
     "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; the instance ids in read_messages, list_events and meetings (mcp-…) name MCP adapters, not sessions. " +
+    "takes; with the hooks, chat and meetings also record senders and unread cursors per session id " +
+    "(without them, per MCP adapter instance id, mcp-…). join_meeting makes new messages of a meeting wake you " +
+    "(mode active) or show at your next prompt (async) until leave_meeting or the meeting ends; a draft " +
+    "(send_message draft) is decided with stance, and the meeting closes once its required approvers endorse it. " +
     "Projects, global docs, the strategy document and tasks are shared through the other tools.";
 /**
  * MCP adapter in front of the daemon. It holds no session of its own: each

package/contract/errors.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": 1,
+  "contractVersion": 2,
   "errorBody": {
     "type": "object",
     "properties": {
@@ -21,7 +21,7 @@
         "ok": true,
         "service": "n2n-nexus",
         "version": "<host version>",
-        "contractVersion": 1,
+        "contractVersion": 2,
         "sessions": {
           "online": "<number of agent sessions not offline>"
         }

package/contract/hook.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": 1,
+  "contractVersion": 2,
   "clients": [
     "claude",
     "codex"
@@ -24,6 +24,7 @@
     "reason"
   ],
   "backgroundWaitEvent": "BackgroundWait",
+  "wakeResultEvent": "WakeResult",
   "agentStatuses": [
     "working",
     "idle",
@@ -37,6 +38,10 @@
     "hookStopTimeoutSec": 600,
     "waitHookTimeoutSec": 3600,
     "hookTimeoutSec": 10,
+    "codexSessionEndTimeoutSec": 3,
+    "sessionEndRequestTimeoutMs": 1500,
+    "wakeRetryFirstDelayMs": 1000,
+    "wakeRetryMaxDelayMs": 300000,
     "wakePromptWindowMs": 60000,
     "toolUseBindingTtlMs": 300000,
     "messageTtlMs": 86400000,
@@ -48,6 +53,7 @@
     "defaultMaxAutoTurns": 0,
     "maxMessageChars": 32000,
     "maxNoteChars": 200,
+    "maxTitleChars": 80,
     "sessionNamePattern": "^[A-Za-z0-9._@#-]{1,48}$",
     "previewChars": 100,
     "notifyListLimit": 5
@@ -59,6 +65,17 @@
     "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.",
+    "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.",
+    "meetingClosing": "Read them with read_messages(meetingId); post with send_message(meetingId) only when you have something to add.",
+    "meetingEnded": "Meeting \"%s\" (%s) has ended%s. No reply needed.",
+    "stanceNotice": "%s %s draft #%d of meeting \"%s\" (%s)%s. No reply needed.",
+    "approversChanged": "Required approvers of draft #%d changed (version %d): %s.",
+    "consensusDecision": "Decision by consensus on draft #%d: every required approver (%s) endorsed it.\n\n%s",
+    "stanceReminder": "Meeting \"%s\" (%s) waits for your stance on draft #%d: call stance with meetingId and messageId %d, endorse or object (with a reason). No other reply needed.",
+    "stanceWaiting": "Meeting \"%s\" (%s): draft #%d still waits for the stance of %s. No reply needed.",
     "noAgentSessionError": "This call carries no agent session, so direct messaging cannot tell who you are. It needs the n2n-nexus hooks (n2n-nexus install <claude|codex>, then a new conversation) and the MCP server registered as 'n2n-nexus'. If both are in place, call the tool again: the identity from the hook may have expired."
   },
   "schemas": {