n2n-nexus 0.9.3 → 0.9.5

package/CHANGELOG.md

@@ -4,6 +4,36 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.9.5] - 2026-10-26
+
+### Changed
+
+- `n2n-nexus install codex` trusts the n2n-nexus hooks in Codex itself: it asks Codex (`codex app-server`, the copy the Codex app runs on Windows, else `codex` on `PATH`) for each hook's trust hash and stores it, so no `/hooks` step is needed. If that fails, it says how to trust them by hand (the Codex app's settings, or `/hooks` in the CLI). `n2n-nexus doctor codex` checks with Codex that the hooks are trusted, which a Codex update can undo.
+
+## [0.9.4] - 2026-10-26
+
+### Changed
+
+- 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

@@ -92,7 +92,7 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
 
 1. Install and start the host, `n2n-nexus-host`, with Scoop, Homebrew or an archive from [Releases](https://github.com/n2ns/n2n-nexus/releases): [Installation guide, steps 1–2](docs/INSTALL.md#1-install-the-host).
 2. Install the client and connect Claude Code or Codex (`npm i -g n2n-nexus@latest`, then `n2n-nexus install claude` or `n2n-nexus install codex`): [step 3](docs/INSTALL.md#3-install-the-client-for-claude-code-and-codex).
-3. Codex only: trust the n2n-nexus hooks once with `/hooks`: [step 4](docs/INSTALL.md#4-turn-on-the-codex-hooks-one-time-required).
+3. Codex only: `install codex` trusts the n2n-nexus hooks in Codex; if it says it could not, trust them by hand: [step 4](docs/INSTALL.md#4-turn-on-the-codex-hooks-one-time-required).
 
 Other MCP clients and several machines: see the [Installation guide](docs/INSTALL.md). Using it, troubleshooting and configuration: see the [User guide](docs/USER_GUIDE.md).
 
@@ -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/codex-trust.js

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

package/build/cli/doctor.js

@@ -3,7 +3,8 @@
  * script in the hook commands, and the Node path and npm's npx script in the
  * MCP server command (`"<node>" "<npx>" -y n2n-nexus@latest mcp`), that
  * `install` wrote still exist and run, that the host those commands talk to answers
- * GET /health as n2n-nexus-host with this client's contract version, and say
+ * GET /health as n2n-nexus-host with this client's contract version, that
+ * Codex trusts the Codex hooks (asked through codex-trust.ts), and say
  * how to fix what does not. Without a client both are checked; a client with
  * nothing installed is only reported when it was named. Exit code 1 when a
  * check failed.
@@ -147,6 +148,37 @@ function doctorClient(client, endpoints, defaultEndpoint) {
     process.stdout.write(lines.join("\n") + "\n");
     return !failed;
 }
+/**
+ * Whether Codex trusts our hooks (it runs untrusted or modified ones not at
+ * all); prints the result. A Codex that cannot be asked is only noted.
+ */
+async function doctorCodexTrust() {
+    const { MANUAL_TRUST, NOT_LISTED, codexHookTrust, codexProgram } = await import("./codex-trust.js");
+    const program = codexProgram();
+    if (!program) {
+        process.stdout.write(`  note: hook trust not checked: the "codex" command could not be run.\n`);
+        return true;
+    }
+    let state;
+    try {
+        state = await codexHookTrust(program, configFile("codex"), false);
+    }
+    catch (error) {
+        process.stdout.write(`  note: hook trust not checked with ${program.label}: ${error.message}\n`);
+        return true;
+    }
+    if (state.ours === 0) {
+        process.stdout.write(`  FAIL hook trust (${program.label}): ${NOT_LISTED}, then run "n2n-nexus install codex" again.\n`);
+        return false;
+    }
+    if (state.untrusted.length === 0) {
+        process.stdout.write(`  ok   hook trust (${program.label}): ${state.ours} hooks trusted\n`);
+        return true;
+    }
+    process.stdout.write(`  FAIL hook trust (${program.label}): not trusted: ${state.untrusted.join(", ")}\n`
+        + `  fix: run "n2n-nexus install codex" again, or ${MANUAL_TRUST}.\n`);
+    return false;
+}
 /** Parse `[claude|codex]`, run the checks and return the exit code. */
 export async function runDoctor(argv) {
     const client = argv[0];
@@ -172,6 +204,8 @@ export async function runDoctor(argv) {
             else if (!result) {
                 failed = true;
             }
+            if (c === "codex" && result !== undefined && !await doctorCodexTrust())
+                failed = true;
         }
         if (endpoints.size === 0)
             endpoints.add(defaultEndpoint);

package/build/cli/hook.js

@@ -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;
@@ -357,9 +373,6 @@ export function runInstall(options) {
             if (VERSIONED_NODE_DIR.test(node) || VERSIONED_NODE_DIR.test(npm.npx)) {
                 process.stdout.write(`Note: this Node or npx path contains a version directory that an upgrade may remove. After upgrading Node, run "n2n-nexus install ${client}" again, or install with --node <path> pointing at a stable entry such as /usr/local/bin/node.\n`);
             }
-            if (client === "codex") {
-                process.stdout.write("Next: open Codex and run /hooks to trust the n2n-nexus hooks; until then they do not run.\n");
-            }
         }
         return 0;
     }
@@ -369,7 +382,7 @@ export function runInstall(options) {
     }
 }
 /** Parse `<claude|codex> [--endpoint <url>] [--node <path>]` and run. */
-export function runInstallCommand(action, argv) {
+export async function runInstallCommand(action, argv) {
     const client = argv[0];
     if (!isHookClient(client)) {
         process.stderr.write(`Usage: n2n-nexus ${action} <claude|codex>${action === "install" ? " [--endpoint <url>] [--node <path>]" : ""}\n`);
@@ -392,5 +405,29 @@ export function runInstallCommand(action, argv) {
     const node = option("--node", "a path");
     if (node === null)
         return 1;
-    return runInstall({ action, client, endpoint, node });
+    const code = runInstall({ action, client, endpoint, node });
+    if (code === 0 && action === "install" && client === "codex")
+        await trustCodex();
+    return code;
+}
+/**
+ * Codex runs the hooks just written only once they are trusted: trust them
+ * through Codex itself, or say how to do it by hand. Never fails the install.
+ */
+async function trustCodex() {
+    const { MANUAL_TRUST, NOT_LISTED, codexHookTrust, codexProgram } = await import("./codex-trust.js");
+    const program = codexProgram();
+    try {
+        if (!program)
+            throw new Error(`the "codex" command could not be run`);
+        const state = await codexHookTrust(program, configFile("codex"), true);
+        if (state.ours === 0)
+            throw new Error(`${program.label}: ${NOT_LISTED}`);
+        if (state.untrusted.length > 0)
+            throw new Error(`Codex (${program.label}) still does not trust ${state.untrusted.join(", ")}`);
+        process.stdout.write(`Trusted the ${state.ours} n2n-nexus hooks in Codex (${program.label}); start a new Codex conversation to use them.\n`);
+    }
+    catch (error) {
+        process.stdout.write(`Could not trust the hooks automatically (${error.message}). Codex does not run them until you ${MANUAL_TRUST}.\n`);
+    }
 }

package/build/cli/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);
+    }
+}