@kontextmind/kxm 0.7.100 → 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.100",
+      "version": "0.7.102",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -375,8 +375,9 @@ All notable user-facing changes are documented here. The project follows [Semant
   or the Claude MCP server send one hop past the inbound request being handled, so a
   chain of agents forwarding to each other stops at `hop_limit_reached`.
 - **Workflow prompts no longer point agents at `.kxm/config`**, a path KXM refuses.
-- **`kxm gate signal` and `kxm workflow wait` inside a KXM project reach the hub for hub
-  runs.** They go to the local Runtime only for a run its store holds.
+- **`kxm gate signal`, `kxm workflow wait` and `kxm role resume` inside a KXM project reach
+  the hub for hub runs.** They go to the local Runtime only for a run its store holds, and
+  the lookup leaves no files behind, so `--dry-run` changes nothing.
 - **`kxm peer inbox` lists the requests waiting for a named CLI agent.** It returned
   `{"messages":[]}` every time. The hub now serves `GET /v1/agents/:id/inbox`
   (agent-authenticated, project-scoped): the caller's queued and delivered requests,
@@ -384,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/cli-reference.md

@@ -1351,11 +1351,13 @@ kxm role resume <runId> [ruling]
 Resumes an audit-escalated run with an operator directive. The default ruling is `operator_ruling: waived and resumed`.
 
 - Arguments: `<runId>`; `[ruling]`, free text recorded with the decision.
-- For a KXM run ID (`run_` followed by 32 hex digits) inside a project, posts an `audit_escalation` signal with action `unblock` to the Runtime, starting the supervisor if needed. `--dry-run` plans the request without starting the supervisor. JSON keys: `runId`, `ruling`, `unblocked`.
-- For any other ID, updates the hub store at `.kxm/state/kxm.db` in the current directory directly (ignoring `--workspace` and `KXM_DATA_PATH`) and adds a `decision` journal entry. `--dry-run` reads the store read-only, reports the stage it would resume and the resulting `status`, and plans the write. JSON keys: `runId`, `stageId`, `ruling`, `status`.
+- Inside a project, a run that this project's Runtime store holds gets an `audit_escalation` signal with action `unblock` in the Runtime, starting the supervisor if needed. Hub workflow runs share the `run_` + 32-hex shape, so the store, not the ID, decides. `--dry-run` plans the request without starting the supervisor. JSON keys: `runId`, `ruling`, `unblocked`.
+- Any other run ID, including a hub workflow run of the same shape, updates the hub store at `.kxm/state/kxm.db` in the current directory directly (ignoring `--workspace` and `KXM_DATA_PATH`) and adds a `decision` journal entry. `--dry-run` reads the store read-only, reports the stage it would resume and the resulting `status`, and plans the write. JSON keys: `runId`, `stageId`, `ruling`, `status`.
 - The hub-run path bypasses the hub even while one is running: it writes SQLite directly, without authentication, in two statements outside one transaction. A running hub keeps runs in memory, so it does not see the change until it restarts, and its next write to that run overwrites it; it also pushes no event and sends the coordinator no resume message. Stop the hub first, or resume a live hub's run with a signed `audit_escalation` signal (see [Waits, signals and escalation](workflow-definitions.md#waits-signals-and-escalation)).
 - Errors: `resume_failed` (exit 1), or a plain `not found` line (exit 1).
 
+A run the project's Runtime holds:
+
 ```bash
 kxm role resume run_0123456789abcdef0123456789abcdef "waive the audit" --dry-run --json
 ```

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.100",
+  "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.100",
+  "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/cli.js

@@ -24677,7 +24677,7 @@ function kxmProjectRunEventsPath(projectRoot, env) {
 function projectRuntimeOwnsRun(projectRoot, runId, env) {
   const path4 = kxmProjectRunEventsPath(projectRoot, env);
   if (!existsSync10(path4)) return false;
-  const database = new DatabaseSync(path4, { readOnly: true });
+  const database = openReadOnlyDatabase(path4);
   try {
     database.exec("PRAGMA busy_timeout = 5000");
     return database.prepare("SELECT 1 FROM runs WHERE run_id = ?").get(runId) !== void 0;
@@ -28834,7 +28834,7 @@ async function cmdRoleResume(runtime, runId, ruling) {
   }
   const effectiveRuling = ruling?.trim() || "operator_ruling: waived and resumed";
   const projectRoot = discoverKxmProjectRoot(runtime.cwd);
-  if (projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
+  if (projectRoot && projectRuntimeOwnsRun(projectRoot, runId, runtime.env)) {
     if (runtime.dryRun) {
       printPlan(
         runtime,

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.100";
+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) {