@kontextmind/kxm 0.7.101 → 0.7.102

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.101",
+      "version": "0.7.102",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -385,6 +385,14 @@ All notable user-facing changes are documented here. The project follows [Semant
   `codex`) to list requests peers queued for it while it was offline, then answer them
   with `kxm peer reply`. The Pi extension's `kxm_inbox` tool now refuses instead of
   returning an empty list, because Pi activates each inbound request as a turn itself.
+- **A restarted Claude Code session keeps the requests it acknowledged but never answered.**
+  The MCP server acknowledges a request on arrival, and the hub pushes only unacknowledged
+  requests again on reconnect, so a session that restarted under the same agent name (the
+  plugin's `agent_name`) resumed its agent id but lost those requests from `kxm_inbox` and
+  the channel until they expired. After it registers, the server now reads them back from
+  the hub into `kxm_inbox` and announces each once as a channel event; one cancelled or
+  expired meanwhile is dropped, not announced. A tool call waits for that read, and a failed
+  read fails the call instead of listing a partial inbox.
 
 - **The Claude plugin's SessionStart hook is one bundled, read-only, project-scoped
   script.** The two shell hooks it replaces (`kxm session brief --status` and

package/docs/concepts/architecture.md

@@ -90,7 +90,7 @@ stateDiagram-v2
 
 - The sender gets the message ID at once. The recipient may reply straight from `queued` without acknowledging first.
 - `error` is declared in the protocol, but the hub never sets it. Treat it as reserved.
-- Open messages survive a hub restart. When an agent reconnects under the same project and name, the hub rotates its key and pushes every `queued` message again with its original ID. A `delivered` message is not pushed again; it stays open until a reply, cancellation, or expiry. Clients suppress a second turn for an ID they already handle.
+- Open messages survive a hub restart. When an agent reconnects under the same project and name, the hub rotates its key and pushes every `queued` message again with its original ID. A `delivered` message is not pushed again; it stays open until a reply, cancellation, or expiry. The Claude Code MCP server reads its agent's `delivered` messages back from the hub when it registers, so a session restarted under the same name still lists and announces them. Clients suppress a second turn for an ID they already handle.
 - An idempotency key deduplicates an exact retry by the same sender. It does not stop the recipient from repeating a side effect, so handlers must be safe to repeat.
 - The default TTL is 24 hours (at most 7 days). Terminal messages are purged after the retention window, 7 days by default.
 - If a workflow coordinator's prompt expires before its run finishes, the run fails.

package/docs/contributing/test-matrix.md

@@ -20,6 +20,7 @@ to run one file is in [Develop KXM](development.md#run-one-file-or-one-test).
 | Delivery modes, message fields, hop limits and validation | `hub-api.test.ts`, `protocol.test.ts` |
 | Queue, acknowledgement, visibility, reply and authorization | `hub-api.test.ts`, `hub.test.ts` |
 | An unacknowledged (queued) message replays after a recipient restart as the same record | `hub.test.ts`, `extension.test.ts`, `mcp.test.ts` |
+| An acknowledged, unanswered request survives a Claude Code restart under the same agent name and is announced once; one cancelled during the restart is not announced | `mcp.test.ts`, `inbox.test.ts` |
 | An `allowOffline` send queues, delivers once on resumption, and expires unread by TTL | `hub-api.test.ts` |
 | TTL expiry, sender cancellation and terminal retention | `hub-api.test.ts` |
 | Exact-retry idempotency, and rejection of a reused key with different content | `hub-api.test.ts` |

package/docs/guides/peer-messaging.md

@@ -37,7 +37,7 @@ stateDiagram-v2
 | State | Meaning |
 |---|---|
 | `queued` | Accepted and stored. Survives hub and agent restarts. The hub pushes it again each time the recipient reconnects, until the recipient acknowledges it. |
-| `delivered` | Acknowledged: by Pi when the model turn starts, by the Claude Code plugin on arrival. It is not pushed again after a reconnect. |
+| `delivered` | Acknowledged: by Pi when the model turn starts, by the Claude Code plugin on arrival. It is not pushed again after a reconnect; a Claude Code session that restarts under the same agent name reads it back from the hub. |
 | `replied`, `cancelled`, `expired` | Terminal. A later reply or cancel is refused. |
 | `error` | Declared in the protocol but never set by the hub. Treat it as reserved. |
 
@@ -288,7 +288,7 @@ Errors about `workflowContext` are covered in [Peer provenance and quorum gates]
 | Symptom | Cause | Fix |
 |---|---|---|
 | A request stays `queued` | The recipient is offline, busy with earlier work, or swapping its Pi session for a workflow run. | Check `kxm_list` and the recipient's log. Do not send a duplicate. |
-| A request stays `delivered` | The recipient's turn, tool, or provider call is still running, or a Claude Code session restarted after acknowledging it. | Wait, or cancel and send it again with a new idempotency key. |
+| A request stays `delivered` | The recipient's turn, tool, or provider call is still running, or the Claude Code session that acknowledged it came back under another agent name: `claude-<pid>` when `agent_name` is empty, or `<name>-<pid>` while the old session was still online. | Wait, or cancel and send it again with a new idempotency key. Keep the plugin's `agent_name` set, so a restarted session reads its requests back. |
 | `kxm_fanout` returns `pending` | The local wait ended before a reply. | Use the returned message IDs with `kxm_get`, or repeat the exact call. |
 | Claude Code never sees requests | Channel mode is off or blocked by policy. | Use `kxm_inbox` and `kxm_reply`. |
 | `kxm peer inbox` is always empty | `KXM_AGENT_NAME` is unset, so each call registers a new `cli-<pid>` agent that nobody has addressed. | Set `KXM_AGENT_NAME` to the name peers send to. |

package/docs/reference/tools.md

@@ -161,7 +161,7 @@ Returns the message record with `status: "cancelled"`. Cancelling an already can
 
 Lists inbound requests that still need a reply. It takes no parameters.
 
-- **Claude Code:** returns `{ "messages": [...] }` from the session's inbox, which fills from the hub's event stream while the session is registered. Before returning, it re-reads each request and drops those already answered, cancelled or expired. This is pull mode; see [Pushed channel mode and pull mode](../../plugins/kxm/README.md#pushed-channel-mode-and-pull-mode).
+- **Claude Code:** returns `{ "messages": [...] }` from the session's inbox, which fills from the hub's event stream while the session is registered. A session that restarts under the same agent name also reads back the requests the previous session acknowledged but never answered. Before returning, it re-reads each request and drops those already answered, cancelled or expired. This is pull mode; see [Pushed channel mode and pull mode](../../plugins/kxm/README.md#pushed-channel-mode-and-pull-mode).
 - **Pi:** refuses. The extension turns each inbound request into a model turn itself, and that turn's final response is the reply, so listing would offer requests its own queue is about to activate.
 - **CLI:** `kxm peer inbox` reads the agent's open requests from the hub (`GET /v1/agents/<agentId>/inbox`), acknowledging nothing. Run it with a stable `KXM_AGENT_NAME` to see requests queued for that name while it was offline; the default `cli-<pid>` is a new agent on every call, so its list is empty.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.101",
+  "version": "0.7.102",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.101",
+  "version": "0.7.102",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/README.md

@@ -160,7 +160,7 @@ Workflow authors can require replies from a snapshotted set of eligible peers. T
 
 Peer requests reach Claude in one of two ways. Everything else, including `kxm_send`, `kxm_fanout`, the workflow tools and the context tools, works the same in both.
 
-**Pull mode** is the default. Claude checks for work with `kxm_inbox`, handles one request, and answers it with `kxm_reply` and the request's message ID. Nothing arrives on its own: ask Claude to check the inbox, or to poll it with a backoff while it waits. The MCP server keeps the inbox, filling it from the hub's event stream while it is registered; in a KXM project with a project token that starts with the session.
+**Pull mode** is the default. Claude checks for work with `kxm_inbox`, handles one request, and answers it with `kxm_reply` and the request's message ID. Nothing arrives on its own: ask Claude to check the inbox, or to poll it with a backoff while it waits. The MCP server keeps the inbox, filling it from the hub's event stream while it is registered; in a KXM project with a project token that starts with the session. A session that restarts under the same `agent_name` also reads back the requests the previous session acknowledged but never answered, and announces each once on the channel.
 
 **Pushed channel mode** uses Claude Code channels to inject each peer request into the running session as a `<channel source="kxm" message_id="...">` event, which Claude handles and answers with `kxm_reply`. During the channels research preview, start Claude Code with the community channel explicitly and review the trust prompt:
 

package/plugins/kxm/dist/mcp-server.js

@@ -17294,8 +17294,13 @@ function enforceToolPolicy(commandName, env = process.env, options) {
 // plugins/kxm/src/inbox.ts
 async function deliverInboxNotification(messageId, delivered, notify) {
   if (delivered.has(messageId)) return false;
-  await notify();
   delivered.add(messageId);
+  try {
+    await notify();
+  } catch (error2) {
+    delivered.delete(messageId);
+    throw error2;
+  }
   return true;
 }
 
@@ -17308,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.101";
+var VERSION = "0.7.102";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
@@ -17344,39 +17349,50 @@ function sessionIdentity() {
     serverUrl: process.env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331"
   };
 }
-async function onHubEvent(event) {
-  if (event.type === "cancelled" || event.type === "expired") {
-    inbox.delete(event.message.id);
-    notifiedInbox.delete(event.message.id);
-    return;
-  }
-  if (event.type !== "message") return;
-  const client = meshClient;
-  if (!client) return;
-  if (event.message.status === "queued") await client.acknowledge(event.message.id);
-  inbox.set(event.message.id, event.message);
+async function announce(message) {
   const meta2 = {
-    message_id: event.message.id,
-    from_agent: event.message.fromName,
-    delivery: event.message.delivery
+    message_id: message.id,
+    from_agent: message.fromName,
+    delivery: message.delivery
   };
-  if (event.message.correlationId) meta2.correlation_id = event.message.correlationId;
-  await deliverInboxNotification(event.message.id, notifiedInbox, async () => {
+  if (message.correlationId) meta2.correlation_id = message.correlationId;
+  await deliverInboxNotification(message.id, notifiedInbox, async () => {
     await mcp.notification({
       method: "notifications/claude/channel",
       params: {
         content: [
-          `Peer request from ${event.message.fromName}:`,
+          `Peer request from ${message.fromName}:`,
           "",
-          event.message.content,
+          message.content,
           "",
-          `When complete, call kxm_reply with messageId ${event.message.id}.`
+          `When complete, call kxm_reply with messageId ${message.id}.`
         ].join("\n"),
         meta: meta2
       }
     });
   });
 }
+async function onHubEvent(client, event) {
+  if (event.type === "cancelled" || event.type === "expired") {
+    inbox.delete(event.message.id);
+    notifiedInbox.delete(event.message.id);
+    return;
+  }
+  if (event.type !== "message") return;
+  if (event.message.status === "queued") await client.acknowledge(event.message.id);
+  inbox.set(event.message.id, event.message);
+  await announce(event.message);
+}
+async function seedInbox(client) {
+  for (const message of await client.listInbox()) {
+    if (message.status === "delivered" && !inbox.has(message.id)) inbox.set(message.id, message);
+  }
+  await reconcileInbox(client, inbox, notifiedInbox);
+  for (const messageId of [...inbox.keys()]) {
+    const message = inbox.get(messageId);
+    if (message) await announce(message);
+  }
+}
 async function startClient(project, serverUrl, name, authToken) {
   const candidate = new HubClient({
     serverUrl,
@@ -17387,7 +17403,8 @@ async function startClient(project, serverUrl, name, authToken) {
     authToken
   });
   try {
-    await candidate.start(onHubEvent);
+    await candidate.start((event) => onHubEvent(candidate, event));
+    await seedInbox(candidate);
     meshClient = candidate;
     return candidate;
   } catch (error2) {

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.101",
+  "version": "0.7.102",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/inbox.ts

@@ -1,10 +1,18 @@
+/** Announce an inbox request at most once per process. The id is claimed before the send, so a
+ * request read back from the hub and the same request arriving on the event stream cannot both
+ * announce it; a failed send releases the claim, so the request stays retryable. */
 export async function deliverInboxNotification(
   messageId: string,
   delivered: Set<string>,
   notify: () => Promise<void>,
 ): Promise<boolean> {
   if (delivered.has(messageId)) return false;
-  await notify();
   delivered.add(messageId);
+  try {
+    await notify();
+  } catch (error) {
+    delivered.delete(messageId);
+    throw error;
+  }
   return true;
 }

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.101";
+const VERSION = "0.7.102";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
@@ -55,33 +55,24 @@ function sessionIdentity(): { projectDir: string; project: string; serverUrl: st
   };
 }
 
-async function onHubEvent(event: HubEvent): Promise<void> {
-  if (event.type === "cancelled" || event.type === "expired") {
-    inbox.delete(event.message.id);
-    notifiedInbox.delete(event.message.id);
-    return;
-  }
-  if (event.type !== "message") return;
-  const client = meshClient;
-  if (!client) return;
-  if (event.message.status === "queued") await client.acknowledge(event.message.id);
-  inbox.set(event.message.id, event.message);
+/** Tell the session about an inbox request on the channel, at most once per process. */
+async function announce(message: MessageRecord): Promise<void> {
   const meta: Record<string, string> = {
-    message_id: event.message.id,
-    from_agent: event.message.fromName,
-    delivery: event.message.delivery,
+    message_id: message.id,
+    from_agent: message.fromName,
+    delivery: message.delivery,
   };
-  if (event.message.correlationId) meta.correlation_id = event.message.correlationId;
-  await deliverInboxNotification(event.message.id, notifiedInbox, async () => {
+  if (message.correlationId) meta.correlation_id = message.correlationId;
+  await deliverInboxNotification(message.id, notifiedInbox, async () => {
     await mcp.notification({
       method: "notifications/claude/channel",
       params: {
         content: [
-          `Peer request from ${event.message.fromName}:`,
+          `Peer request from ${message.fromName}:`,
           "",
-          event.message.content,
+          message.content,
           "",
-          `When complete, call kxm_reply with messageId ${event.message.id}.`,
+          `When complete, call kxm_reply with messageId ${message.id}.`,
         ].join("\n"),
         meta,
       },
@@ -89,6 +80,36 @@ async function onHubEvent(event: HubEvent): Promise<void> {
   });
 }
 
+async function onHubEvent(client: HubClient, event: HubEvent): Promise<void> {
+  if (event.type === "cancelled" || event.type === "expired") {
+    inbox.delete(event.message.id);
+    notifiedInbox.delete(event.message.id);
+    return;
+  }
+  if (event.type !== "message") return;
+  if (event.message.status === "queued") await client.acknowledge(event.message.id);
+  inbox.set(event.message.id, event.message);
+  await announce(event.message);
+}
+
+/** A durable KXM_AGENT_NAME resumes its agent id, but the event stream replays only requests
+ * that agent has not acknowledged. One an earlier process acknowledged and never answered is
+ * still open on the hub, so it is read back here and announced like a pushed request: this
+ * session has not been told about it. The inbox is reconciled before anything is announced,
+ * so a request cancelled or expired while the list was in flight is dropped, not announced;
+ * its event may have gone to a stream that was not connected yet. Queued requests are left
+ * to the stream, which acknowledges them in order. */
+async function seedInbox(client: HubClient): Promise<void> {
+  for (const message of await client.listInbox()) {
+    if (message.status === "delivered" && !inbox.has(message.id)) inbox.set(message.id, message);
+  }
+  await reconcileInbox(client, inbox, notifiedInbox);
+  for (const messageId of [...inbox.keys()]) {
+    const message = inbox.get(messageId);
+    if (message) await announce(message);
+  }
+}
+
 async function startClient(project: string, serverUrl: string, name: string, authToken: string): Promise<HubClient> {
   const candidate = new HubClient({
     serverUrl,
@@ -99,7 +120,9 @@ async function startClient(project: string, serverUrl: string, name: string, aut
     authToken,
   });
   try {
-    await candidate.start(onHubEvent);
+    await candidate.start((event) => onHubEvent(candidate, event));
+    // A tool call waits for the seeded inbox: `starting` stays pending until this returns.
+    await seedInbox(candidate);
     meshClient = candidate;
     return candidate;
   } catch (error) {