@openvole/volenet-mcp 0.2.0 → 0.3.0

package/README.md

@@ -17,8 +17,8 @@ npx -y @openvole/volenet-mcp install
 ```
 
 That is the whole setup. It registers the server with Claude Code, and there is nothing to
-configure: an identity is generated on first run, the name defaults to `claude-<hostname>`, and
-whether to join a hub is a decision you make later, from inside a session.
+configure: an identity is generated on first run for whichever project you are in, named after it,
+and whether to join a hub is a decision you make later, from inside a session.
 
 Restart Claude Code afterwards — MCP servers load at startup.
 
@@ -32,27 +32,33 @@ your behalf, not commands you type. Ask for them in your own words.
 > *"pair with the agent at http://10.0.0.5:9700"* → `volenet_connect`, which reports the
 > fingerprint first and pairs once you confirm it
 
-It registers for **every project**, because the identity it installs is per machine — one keypair
-in your home directory, shared by every session. Add `--local` to limit it to the current project.
+Running it again is safe, and is how you move an existing registration: an identical one is left
+alone, and one pointing somewhere else — a working-tree build, say, when you have since installed
+the published package — is replaced rather than reported as already done.
+
+It registers for **every project** — the server is the same everywhere, and it gives each project
+its own identity when it starts there. Add `--local` to register it in the current project only.
 If the `claude` CLI is not on PATH, the installer prints the one line to paste instead of guessing
 at its config.
 
 ### Settings
 
-Settings live with the identity in `~/.openvole/volenet-mcp/`, not in the command that launches
-the server, so changing one never means re-registering anything. `volenet_hub` writes the hub
-there; everything else has a default worth keeping.
+Settings live with the identity, in that project's directory, not in the command that launches the
+server — so changing one never means re-registering anything. `volenet_hub` writes the hub there;
+everything else has a default worth keeping.
 
 | variable | default | what |
 |---|---|---|
-| `VOLENET_MCP_NAME` | `claude-<hostname>` | What peers see. Not identity — the key is. |
+| `VOLENET_MCP_NAME` | `claude-<project>` | What peers see. Not identity — the key is. |
 | `VOLENET_MCP_HUB` | none | Normally set by `volenet_hub`; this overrides it for scripted setups. |
-| `VOLENET_MCP_DIR` | `~/.openvole/volenet-mcp` | Keypair, trust store, settings, transcript. |
-| `VOLENET_MCP_PORT` | `9750` | Listening port, for peers that *can* dial you. |
+| `VOLENET_MCP_DIR` | `~/.openvole/volenet-mcp/<project>` | Keypair, trust store, settings, messages. Set it to share one identity between projects. |
+| `VOLENET_MCP_PORT` | `0` | Listening port. A session dials out, so it takes any free one; set it only if a peer must dial you. |
+| `VOLENET_MCP_SESSION` | `session` | Which read state to use. Set it to keep two readers in one project apart. |
+| `VOLENET_MCP_NOTIFY` | platform default | `off`, or a command run with the title and body. |
 
 Environment wins over stored settings, which win over defaults. None of it is required.
 
-That directory **is** your identity: back it up, and anyone who has it is you.
+That directory **is** that project's identity: back it up, and anyone who has it is you.
 
 ## Slash commands
 
@@ -61,7 +67,7 @@ rather than hoping a sentence matches the right tool.
 
 | command | what it does |
 |---|---|
-| `whoami` | this session's identity, and whether it can reach anything |
+| `whoami` | this project's identity, and whether it can reach anything |
 | `peers` | who is reachable, and by which route |
 | `setup` | get onto the mesh — join a hub, or pair with an agent |
 | `pair` | pair with an agent, fingerprint checked, asking for brain access if wanted |
@@ -76,11 +82,13 @@ files only — no node is started, no port is bound — so they are safe to run
 and safe in a hook that fires on every session.
 
 ```bash
-volenet-mcp install [--user]    register with Claude Code
-volenet-mcp whoami              this machine's identity on the mesh
+volenet-mcp install [--local]   register with Claude Code (default: every project)
+volenet-mcp adopt               claim an identity left at the old shared location
+volenet-mcp whoami              this project's identity on the mesh
 volenet-mcp hub <url>           set the hub; joined on the next session start
 volenet-mcp hub --leave         come off it
 volenet-mcp inbox [--read]      what is waiting
+volenet-mcp wait [--timeout s]  block until a message arrives, then print it and exit
 ```
 
 Anything needing a live node — the roster, pairing, asking an agent's brain — is a tool rather
@@ -136,6 +144,12 @@ that command is run with the title and body as its two arguments.
 Claude Code declares no capabilities at all — `volenet_whoami` reports which it is, so nobody waits
 for a reply that cannot come. What is left is making sure an arrived message is *seen* promptly.
 
+**A session can be reached unprompted**, though not by this server. MCP gives a server no way to
+wake a client — but a process that *exits* does. `volenet-mcp wait` blocks on the message log and
+exits when something lands, so running it in the background makes an arriving message wake the
+session that started it. One arrival per wait, so re-arm after each; and it only helps while a
+session is open.
+
 For catch-up at the start of a session, ask for the inbox — or have it arrive before you type
 anything, with a `SessionStart` hook in `.claude/settings.json`:
 
@@ -151,8 +165,8 @@ anything, with a `SessionStart` hook in `.claude/settings.json`:
 
 `--read` marks them seen, since the hook has just put them in front of you.
 
-Swap `SessionStart` for `UserPromptSubmit` and waiting messages arrive on every turn you take,
-which is as close to unprompted as this client allows.
+Swap `SessionStart` for `UserPromptSubmit` and waiting messages arrive on every turn you take;
+add `PostToolUse` and they arrive within a tool call while the session is working.
 
 ## The node runs in a daemon
 
@@ -173,20 +187,36 @@ and keeps its own cursor — the protocol covers acting, not looking, and your h
 if the daemon is gone. `VOLENET_MCP_NO_DAEMON=1` keeps the node in the session, which is the
 fallback where spawning is not allowed.
 
-## One identity, several sessions
+## One identity per project
+
+The identity is the **project directory**, not the machine. Pairing is per identity, so a shared
+one makes every session the same participant: the peer you paired with cannot tell them apart, and
+each reads the others' conversations. Two projects open at once are two correspondents and look
+like it — separate keys, separate pairings, separate history.
+
+Several sessions in the *same* directory are one participant, which is right: same project, same
+conversation, same history.
+
+```
+~/.openvole/volenet-mcp/
+  my-project-8c7bd921/    keys, peers, settings, messages
+  other-thing-9d0f8056/   a different peer entirely
+```
+
+The name a peer sees follows the project too — `claude-my-project` — which says something useful to
+whoever is on the other end, and keeps your machine's hostname off their roster.
 
-The identity is per machine — one keypair in `~/.openvole/volenet-mcp/`, shared by every session,
-because pairing once is the whole point of having one. Being *caught up* is not shared: messages
-are an append-only log, and each session keeps its own read cursor, keyed by the directory it was
-started in.
+A node dials the hub and everything it has paired with, both recorded beside the identity. Trust
+and address are different things kept in different places: the keystore says whose signature to
+accept, this says where to find them. Without the second, a paired peer stays trusted and
+unreachable after a restart.
 
-So a session opening its inbox does not mark those messages seen for the others; a session
-reopened in the same project is the same reader and does not replay what it has already been
-shown; and two projects open at once are two readers of one log. Appending rather than rewriting
-is what makes that safe without a lock or a daemon.
+`VOLENET_MCP_DIR` overrides the directory outright, which is how you deliberately share one
+identity between projects. That is the exception, not the default.
 
-`VOLENET_MCP_SESSION` names the reader explicitly, if you want two sessions in one directory kept
-apart.
+Upgrading from the version that kept one identity for the whole machine: `volenet-mcp adopt` claims
+it for the current directory — keys, peers and history intact, so nothing needs re-pairing. Only one
+project can have it, so which one is a decision rather than a guess.
 
 ## Session lifetime
 

package/dist/index.d.ts

@@ -4,18 +4,44 @@ interface StoredConfig {
     name?: string;
     hub?: string;
     port?: number;
+    /**
+     * Nodes to dial on start, learned by pairing.
+     *
+     * Trust and address are different things and are kept in different places: the keystore says
+     * whose signature to accept, and this says where to find them. Without it a paired peer stayed
+     * trusted and unreachable after a restart — nothing dialled it, so nothing connected.
+     */
+    peers?: string[];
 }
+/** Add a peer URL to what this identity dials, keeping the list unique and bounded. */
+declare function rememberPeer(dir: string, url: string): Promise<void>;
 interface Settings {
     name: string;
     hub?: string;
     dir: string;
     port: number;
-    /** Which read state in the shared inbox is this session's. See {@link sessionKey}. */
+    /** Which read state in this directory's inbox is ours. See {@link sessionKey}. */
     session: string;
 }
-declare function defaultDir(): string;
-/** A name that says what this is without needing to be chosen. Identity is the key, not this. */
-declare function defaultName(): string;
+/** Where every identity on this machine is kept, one directory each. */
+declare function baseDir(): string;
+/**
+ * A stable, recognisable name for a directory: its basename, plus a hash so two projects that
+ * share one do not share an identity.
+ */
+declare function sessionKey(cwd?: string): string;
+/**
+ * This project's identity directory.
+ *
+ * `VOLENET_MCP_DIR` overrides it outright, which is how you deliberately share one identity
+ * between projects — the exception, not the default.
+ */
+declare function defaultDir(cwd?: string): string;
+/**
+ * What peers see. The project's name, not the machine's — it says something useful to whoever is
+ * on the other end, and it keeps a laptop's hostname off other people's rosters.
+ */
+declare function defaultName(cwd?: string): string;
 declare function loadStored(dir: string): Promise<StoredConfig>;
 declare function saveStored(dir: string, patch: StoredConfig): Promise<StoredConfig>;
 /** Environment over stored settings over defaults. Every layer is optional. */
@@ -49,8 +75,19 @@ declare class Inbox {
     private get log();
     private get cursor();
     load(): Promise<void>;
-    /** Re-read what other sessions have appended since we loaded. */
+    /**
+     * Re-read what has changed on disk since we loaded — both the messages another session
+     * appended, and the cursor another *process* moved.
+     *
+     * The cursor matters as much as the messages: a long-lived server holds one in memory while a
+     * hook, running as its own process for the same session, marks things read behind it. Without
+     * this the server goes on reporting messages as unread that the person has already been shown.
+     */
     refresh(): Promise<void>;
+    /** Take the later of what we hold and what is on disk: a cursor only ever moves forward. */
+    private readCursor;
+    /** Cursors only move forward, so take the later of what we hold and what was read. */
+    private merge;
     /** Record a message. Returns false when this id was already recorded. */
     add(m: Message): Promise<boolean>;
     /** Everything with one peer, oldest first. */
@@ -132,6 +169,12 @@ interface AskResult {
 interface Identity {
     instanceId: string;
     publicKeyString: string;
+    /**
+     * The port the node actually bound, which is the daemon's business and not the session's.
+     * A session attached to a daemon has no listener of its own, so reporting its own configured
+     * port would name one nothing is listening on.
+     */
+    port?: number;
 }
 interface RoomView {
     room: string;
@@ -169,6 +212,7 @@ interface NetLike {
     initiatePair(url: string, publicKey: string, note?: string, wants?: string[]): Promise<{
         ok: boolean;
         pending?: boolean;
+        alreadyTrusted?: boolean;
         error?: string;
     }>;
     requestRelayConnect(ref: string, note?: string): Promise<{
@@ -314,10 +358,10 @@ declare const TOOLS: ToolDef[];
  * ambient awareness in place of the notification the protocol cannot send. The tools that just
  * showed you the messages are excluded, since they leave nothing unread.
  */
-declare function unreadFooter(node: Node, toolName: string): string;
+declare function unreadFooter(node: Node, toolName: string): Promise<string>;
 /** Wire the tools to an MCP server. Separated so a test can drive it without a transport. */
 declare function createServer(node: Node): Server;
 /** Remember what the client can do, so a later session can say so without asking again. */
 declare function recordClientCapabilities(dir: string, caps: unknown): Promise<void>;
 
-export { Inbox, type Node, type NodeOptions, PROMPTS, type PromptDef, type Settings, TOOLS, type ToolDef, createServer, defaultDir, defaultName, loadStored, recordClientCapabilities, resolveSettings, run as runCli, saveStored, startNode, unreadFooter };
+export { Inbox, type Node, type NodeOptions, PROMPTS, type PromptDef, type Settings, type StoredConfig, TOOLS, type ToolDef, baseDir, createServer, defaultDir, defaultName, loadStored, recordClientCapabilities, rememberPeer, resolveSettings, run as runCli, saveStored, sessionKey, startNode, unreadFooter };

package/dist/index.js

@@ -17,9 +17,12 @@ var __export = (target, all) => {
 // src/config.ts
 var config_exports = {};
 __export(config_exports, {
+  baseDir: () => baseDir,
+  cursorKey: () => cursorKey,
   defaultDir: () => defaultDir,
   defaultName: () => defaultName,
   loadStored: () => loadStored,
+  rememberPeer: () => rememberPeer,
   resolveSettings: () => resolveSettings,
   saveStored: () => saveStored,
   sessionKey: () => sessionKey
@@ -28,16 +31,31 @@ import * as crypto from "crypto";
 import * as fs from "fs/promises";
 import * as os from "os";
 import * as path from "path";
+async function rememberPeer(dir, url) {
+  const clean = url.replace(/\/$/, "");
+  const stored = await loadStored(dir);
+  const peers2 = stored.peers ?? [];
+  if (peers2.includes(clean)) return;
+  await saveStored(dir, { peers: [...peers2, clean].slice(-32) });
+}
+function cursorKey() {
+  return process.env.VOLENET_MCP_SESSION?.trim() || "session";
+}
+function baseDir() {
+  return path.join(os.homedir(), ".openvole", "volenet-mcp");
+}
 function sessionKey(cwd = process.cwd()) {
   const hash = crypto.createHash("sha256").update(cwd).digest("hex").slice(0, 8);
   const base = (cwd.split("/").filter(Boolean).pop() ?? "session").toLowerCase().replace(/[^a-z0-9._-]+/g, "-").slice(0, 40);
   return `${base}-${hash}`;
 }
-function defaultDir() {
-  return process.env.VOLENET_MCP_DIR?.trim() || path.join(os.homedir(), ".openvole", "volenet-mcp");
+function defaultDir(cwd = process.cwd()) {
+  const override = process.env.VOLENET_MCP_DIR?.trim();
+  return override || path.join(baseDir(), sessionKey(cwd));
 }
-function defaultName() {
-  return `claude-${os.hostname().split(".")[0].toLowerCase()}`;
+function defaultName(cwd = process.cwd()) {
+  const base = (cwd.split("/").filter(Boolean).pop() ?? "session").toLowerCase().replace(/[^a-z0-9._-]+/g, "-").slice(0, 40);
+  return `claude-${base}`;
 }
 async function loadStored(dir) {
   try {
@@ -65,8 +83,10 @@ async function resolveSettings() {
     name: process.env.VOLENET_MCP_NAME?.trim() || stored.name || defaultName(),
     hub: process.env.VOLENET_MCP_HUB?.trim() || stored.hub || void 0,
     dir,
-    port: (Number.isFinite(envPort) && envPort > 0 ? envPort : stored.port) || 9750,
-    session: process.env.VOLENET_MCP_SESSION?.trim() || sessionKey()
+    // 0 by default: a session dials out, and several projects open at once would otherwise
+    // queue for one number. A peer that can dial you wants a fixed one — set it then.
+    port: (Number.isFinite(envPort) && envPort > 0 ? envPort : stored.port) || 0,
+    session: cursorKey()
   };
 }
 var file;
@@ -129,16 +149,48 @@ var init_inbox = __esm({
       async load() {
         await this.adoptLegacy();
         this.messages = await readLog(this.log);
+        this.readAt = /* @__PURE__ */ new Map();
+        await this.readCursor();
+      }
+      /**
+       * Re-read what has changed on disk since we loaded — both the messages another session
+       * appended, and the cursor another *process* moved.
+       *
+       * The cursor matters as much as the messages: a long-lived server holds one in memory while a
+       * hook, running as its own process for the same session, marks things read behind it. Without
+       * this the server goes on reporting messages as unread that the person has already been shown.
+       */
+      async refresh() {
+        this.messages = await readLog(this.log);
+        await this.readCursor();
+      }
+      /** Take the later of what we hold and what is on disk: a cursor only ever moves forward. */
+      async readCursor() {
         try {
           const raw = JSON.parse(await fs2.readFile(this.cursor, "utf-8"));
-          this.readAt = new Map(Object.entries(raw ?? {}));
+          this.merge(raw);
+          return;
+        } catch {
+        }
+        const legacy = /^[a-z0-9._-]+-[0-9a-f]{8}\.json$/;
+        try {
+          const dir = path2.dirname(this.cursor);
+          for (const name of await fs2.readdir(dir)) {
+            if (!legacy.test(name)) continue;
+            try {
+              this.merge(JSON.parse(await fs2.readFile(path2.join(dir, name), "utf-8")));
+            } catch {
+            }
+          }
         } catch {
-          this.readAt = /* @__PURE__ */ new Map();
         }
       }
-      /** Re-read what other sessions have appended since we loaded. */
-      async refresh() {
-        this.messages = await readLog(this.log);
+      /** Cursors only move forward, so take the later of what we hold and what was read. */
+      merge(raw) {
+        if (!raw || typeof raw !== "object") return;
+        for (const [peer, at] of Object.entries(raw)) {
+          if (typeof at === "number" && at > (this.readAt.get(peer) ?? 0)) this.readAt.set(peer, at);
+        }
       }
       /** Record a message. Returns false when this id was already recorded. */
       async add(m) {
@@ -243,7 +295,11 @@ function localNet(m) {
   return {
     async identity() {
       const k = m.getKeyPair();
-      return k ? { instanceId: k.instanceId, publicKeyString: k.publicKeyString } : null;
+      return k ? {
+        instanceId: k.instanceId,
+        publicKeyString: k.publicKeyString,
+        port: m.getTransport()?.getPort?.() ?? void 0
+      } : null;
     },
     async instances() {
       const live = new Set(
@@ -549,6 +605,11 @@ async function startLocal(options, inbox, notify) {
   const notices = [];
   const listeners = /* @__PURE__ */ new Set();
   const port = await isFree(options.port) ? options.port : 0;
+  const stored = await loadStored(options.dir);
+  const dial = [
+    ...options.hub ? [options.hub] : [],
+    ...(stored.peers ?? []).filter((u) => u !== options.hub)
+  ];
   const manager = new VoleNetManager(
     {
       enabled: true,
@@ -556,9 +617,11 @@ async function startLocal(options, inbox, notify) {
       role: "peer",
       port,
       keyPath: path5.join(options.dir, "net", "vole_key"),
-      // A hub is a peer we dial. 'read' rather than 'full': a hub carries our sealed traffic,
-      // it has no business acting on this node.
-      peers: options.hub ? [{ url: options.hub, trust: "read" }] : []
+      // 'read' rather than 'full': these carry our traffic and answer our questions, they
+      // have no business acting on this node.
+      peers: dial.map((url) => ({ url, trust: "read" })),
+      // Pairing learns an address at runtime; without this it is forgotten on exit.
+      persistPeer: (url) => rememberPeer(options.dir, url)
     },
     options.dir
   );
@@ -702,6 +765,8 @@ import {
 // src/cli.ts
 init_config();
 init_inbox();
+import * as fsSync2 from "fs";
+import * as fs4 from "fs/promises";
 import * as path6 from "path";
 import { loadKeyPair } from "@openvole/volenet";
 
@@ -718,15 +783,16 @@ function addArgs(scope, command) {
   return ["mcp", "add", SERVER_NAME, "-s", scope, "--", ...command];
 }
 var NEXT_STEPS = '\nRestart Claude Code \u2014 MCP servers load at startup \u2014 then:\n\n  volenet_whoami             who you are on the mesh (an identity is made on first run)\n  volenet_hub url:"..."      join a hub, to be reachable from anywhere\n  volenet_connect url:"..."  or pair directly with an agent you can dial\n\nNothing else needs configuring.\n';
-function install(argv, out = process.stdout) {
+var spawnClaude = (args) => spawnSync("claude", args, {
+  stdio: ["ignore", "pipe", "pipe"],
+  encoding: "utf-8",
+  timeout: 3e4
+});
+function install(argv, out = process.stdout, exec = spawnClaude) {
   const scope = argv.includes("--local") ? "local" : "user";
   const command = launchCommand();
   const paste = `claude mcp add ${SERVER_NAME} -s ${scope} -- ${command.join(" ")}`;
-  const run3 = (args) => spawnSync("claude", args, {
-    stdio: ["ignore", "pipe", "pipe"],
-    encoding: "utf-8",
-    timeout: 3e4
-  });
+  const run3 = exec;
   const listed = run3(["mcp", "list"]);
   if (listed.error) {
     out.write(
@@ -738,10 +804,18 @@ function install(argv, out = process.stdout) {
     );
     return 1;
   }
-  if (listed.stdout?.includes(`${SERVER_NAME}:`)) {
-    out.write(`${SERVER_NAME} is already registered \u2014 nothing to do.
+  const existing = listed.stdout?.split("\n").find((l) => l.trimStart().startsWith(`${SERVER_NAME}:`));
+  if (existing) {
+    if (existing.includes(command.join(" "))) {
+      out.write(`${SERVER_NAME} is already registered, unchanged.
 ${NEXT_STEPS}`);
-    return 0;
+      return 0;
+    }
+    out.write(`Replacing the existing ${SERVER_NAME} registration:
+  was: ${existing.trim()}
+`);
+    run3(["mcp", "remove", SERVER_NAME, "-s", scope]);
+    run3(["mcp", "remove", SERVER_NAME, "-s", scope === "user" ? "local" : "user"]);
   }
   const added = run3(addArgs(scope, command));
   if (added.status !== 0) {
@@ -770,6 +844,8 @@ var USAGE = `volenet-mcp \u2014 VoleNet as an MCP server
   volenet-mcp whoami               this machine's identity on the mesh
   volenet-mcp daemon               run the node in the foreground (normally started for you)
   volenet-mcp hub [url|--leave]    which hub to use; takes effect on the next session
+  volenet-mcp adopt                take over an identity left at the old shared location
+  volenet-mcp wait [--timeout <s>]  block until a message arrives, then print it and exit
   volenet-mcp inbox [--read] [--quiet]
                                    messages waiting. --read marks them seen, --quiet says
                                    nothing when there are none (for hooks)
@@ -778,7 +854,12 @@ With no command it runs as the MCP server itself, over stdio, which is how Claud
 Anything needing a live node \u2014 peers, pairing, asking an agent's brain \u2014 is a tool you ask for in
 a session, not a command here.
 `;
-var when = (ts) => new Date(ts).toISOString().replace("T", " ").slice(0, 16);
+var when = (ts) => new Date(ts).toLocaleString(void 0, {
+  month: "short",
+  day: "numeric",
+  hour: "2-digit",
+  minute: "2-digit"
+});
 async function run2(argv, out = process.stdout) {
   const [command, ...rest] = argv;
   const dir = defaultDir();
@@ -793,6 +874,40 @@ async function run2(argv, out = process.stdout) {
     await runDaemon2(await resolveSettings2());
     return 0;
   }
+  if (command === "adopt") {
+    const legacy = baseDir();
+    const from = path6.join(legacy, "net", "vole_key");
+    try {
+      await fs4.access(from);
+    } catch {
+      out.write(`Nothing to adopt: no identity at ${legacy}.
+`);
+      return 0;
+    }
+    try {
+      await fs4.access(path6.join(dir, "net", "vole_key"));
+      out.write(
+        `This directory already has an identity at ${dir}.
+Adopting would overwrite it, so nothing was moved.
+`
+      );
+      return 1;
+    } catch {
+    }
+    await fs4.mkdir(dir, { recursive: true });
+    for (const name of ["net", "messages.jsonl", "config.json", "cursors"]) {
+      try {
+        await fs4.rename(path6.join(legacy, name), path6.join(dir, name));
+      } catch {
+      }
+    }
+    out.write(
+      `Adopted the identity at ${legacy} for this directory.
+It keeps its keys, its peers and its history, so nothing needs re-pairing.
+`
+    );
+    return 0;
+  }
   if (command === "whoami") {
     const stored = await loadStored(dir);
     const keys = await loadKeyPair(path6.join(dir, "net")).catch(() => null);
@@ -843,8 +958,51 @@ It is joined the next time the server starts \u2014 restart Claude Code, or ask
     );
     return 0;
   }
+  if (command === "wait") {
+    const inbox = new Inbox(dir, cursorKey());
+    await inbox.load();
+    const seconds = Number(rest[rest.indexOf("--timeout") + 1]);
+    const limit = Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : 36e5;
+    const log = path6.join(dir, "messages.jsonl");
+    const arrived = await new Promise((resolve2) => {
+      const done = (v) => {
+        clearInterval(timer);
+        clearTimeout(cap);
+        watcher?.close();
+        resolve2(v);
+      };
+      const check = async () => {
+        await inbox.refresh().catch(() => void 0);
+        const unread = inbox.unread();
+        if (unread.length > 0) done(unread);
+      };
+      let watcher;
+      try {
+        watcher = fsSync2.watch(path6.dirname(log), (_e, name) => {
+          if (name === "messages.jsonl") void check();
+        });
+      } catch {
+      }
+      const timer = setInterval(() => void check(), 1e3);
+      const cap = setTimeout(() => done([]), limit);
+      void check();
+    });
+    if (arrived.length === 0) {
+      out.write(`Nothing arrived within ${Math.round(limit / 1e3)}s.
+`);
+      return 0;
+    }
+    out.write(`${arrived.length} new VoleNet message${arrived.length === 1 ? "" : "s"}:
+
+`);
+    for (const m of arrived) out.write(`  [${when(m.ts)}] ${m.peerName}: ${m.text}
+`);
+    if (!rest.includes("--keep")) await inbox.markRead();
+    out.write("\n");
+    return 0;
+  }
   if (command === "inbox") {
-    const inbox = new Inbox(dir, process.env.VOLENET_MCP_SESSION?.trim() || sessionKey());
+    const inbox = new Inbox(dir, cursorKey());
     await inbox.load();
     const unread = inbox.unread();
     if (unread.length === 0) {
@@ -1059,8 +1217,9 @@ var TOOLS = [
         `instanceId  ${key?.instanceId ?? "(not started)"}`,
         `hub         ${node.hubStatus}`,
         `connected   ${online} peer(s) online`,
-        `listening   port ${node.options.port} (reachable only from networks that can dial it)`,
+        `listening   port ${key?.port ?? node.options.port} (reachable only from networks that can dial it)`,
         `store       ${node.options.dir}`,
+        "identity    this project directory \u2014 another project is a different peer",
         `node        ${node.where === "daemon" ? "a daemon, so this identity stays reachable when no session is open" : "in this session, so it is only reachable while this session is"}`
       ];
       lines.push(
@@ -1419,6 +1578,13 @@ Call with leave:true to come off it, or url to move to another.` : "Not on a hub
           args.brain ? ["brain"] : void 0
         );
         if (!res.ok) return `Could not ask: ${res.error}`;
+        if (res.alreadyTrusted) {
+          return [
+            `${probe.name ?? url} already trusts this session, so there was nothing to ask for \u2014`,
+            "the link is usable now. Call volenet_peers to see it.",
+            args.brain ? "Whether it also allows its brain is a separate grant its operator makes in net.peers; volenet_ask will say plainly if it does not." : ""
+          ].filter(Boolean).join(" ");
+        }
         return [
           `Trusted ${probe.name ?? url} and asked it to trust this session.`,
           args.brain ? "The request also asks to use its brain, so its operator can grant that while accepting \u2014 no config editing, no restart." : "It asks for trust only. Pass brain:true to also ask for brain access.",
@@ -1439,8 +1605,9 @@ Call with leave:true to come off it, or url to move to another.` : "Not on a hub
 init_inbox();
 init_config();
 init_node();
-function unreadFooter(node, toolName) {
+async function unreadFooter(node, toolName) {
   if (toolName === "volenet_inbox" || toolName === "volenet_wait") return "";
+  await node.inbox.refresh().catch(() => void 0);
   const unread = node.inbox.unread();
   if (unread.length === 0) return "";
   const who = [...new Set(unread.map((m) => m.peerName))].join(", ");
@@ -1493,7 +1660,9 @@ function createServer2(node) {
     }
     try {
       const text = await tool.run(node, request.params.arguments ?? {});
-      return { content: [{ type: "text", text: text + unreadFooter(node, tool.name) }] };
+      return {
+        content: [{ type: "text", text: text + await unreadFooter(node, tool.name) }]
+      };
     } catch (err) {
       return {
         content: [
@@ -1507,10 +1676,10 @@ function createServer2(node) {
 }
 async function recordClientCapabilities(dir, caps) {
   try {
-    const fs4 = await import("fs/promises");
+    const fs5 = await import("fs/promises");
     const path7 = await import("path");
-    await fs4.mkdir(dir, { recursive: true });
-    await fs4.writeFile(
+    await fs5.mkdir(dir, { recursive: true });
+    await fs5.writeFile(
       path7.join(dir, "client.json"),
       `${JSON.stringify(caps ?? {}, null, 2)}
 `,
@@ -1562,14 +1731,17 @@ export {
   Inbox,
   PROMPTS,
   TOOLS,
+  baseDir,
   createServer2 as createServer,
   defaultDir,
   defaultName,
   loadStored,
   recordClientCapabilities,
+  rememberPeer,
   resolveSettings,
   run2 as runCli,
   saveStored,
+  sessionKey,
   startNode,
   unreadFooter
 };