@kontextmind/kxm 0.7.70 → 0.7.71

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.70",
+      "version": "0.7.71",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.70",
+  "version": "0.7.71",
   "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.70",
+  "version": "0.7.71",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -18350,9 +18350,7 @@ function findKxmRepoRoot(fromUrl = import.meta.url) {
 
 // plugins/kxm/src/client.ts
 import { createHash as createHash3 } from "node:crypto";
-
-// plugins/kxm/src/workflow.ts
-import { createHash as createHash2 } from "node:crypto";
+import { hostname } from "node:os";
 
 // plugins/kxm/src/protocol.ts
 import { randomUUID } from "node:crypto";
@@ -18361,6 +18359,7 @@ var MIN_MESSAGE_TTL_MS = 1e3;
 var MAX_MESSAGE_TTL_MS = 7 * 24 * 60 * 6e4;
 var DEFAULT_MESSAGE_RETENTION_MS = 7 * 24 * 60 * 6e4;
 var MAX_BODY_BYTES = 256 * 1024;
+var MAX_AGENT_HOST_CHARS = 64;
 var ProtocolError = class extends Error {
   statusCode;
   code;
@@ -18453,6 +18452,7 @@ function validateTerminalReceipt(value) {
 }
 
 // plugins/kxm/src/workflow.ts
+import { createHash as createHash2 } from "node:crypto";
 var PROMOTABLE_JOURNAL_CATEGORIES = ["skill-candidate", "hypothesis", "experiment"];
 var WORKFLOW_TERMINAL_TARGET = "$terminal";
 function normalizeOutcomeValue(value, field) {
@@ -19200,6 +19200,13 @@ var MeshWaitError = class extends Error {
     this.waitStatus = waitStatus;
   }
 };
+function defaultHostLabel() {
+  try {
+    return hostname().trim().slice(0, MAX_AGENT_HOST_CHARS) || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function completedFanoutResult(target, message) {
   if (message.status === "queued" || message.status === "delivered") {
     throw new Error(`message ${message.id} is not complete`);
@@ -19289,8 +19296,11 @@ var HubClient = class {
     this.onEvent = void 0;
     this.eventLoop = void 0;
   }
-  async listAgents() {
-    const result = await this.request("/v1/agents");
+  /** Online peers of this client's project. `includeOffline` also returns
+   * registered members whose lease the hub has already retired. */
+  async listAgents(options = {}) {
+    const path4 = options.includeOffline ? "/v1/agents?includeOffline=true" : "/v1/agents";
+    const result = await this.request(path4);
     return result.agents;
   }
   async send(options) {
@@ -19530,7 +19540,8 @@ var HubClient = class {
           name: this.options.name,
           purpose: this.options.purpose,
           project: this.options.project,
-          model: this.options.model
+          model: this.options.model,
+          host: this.options.host ?? defaultHostLabel()
         })
       }, false);
       this.agent = registration.agent;
@@ -19770,14 +19781,19 @@ var AGENT_COMMANDS = [
     group: "peer",
     verb: "list",
     label: "List hub peers",
-    description: "List online peer agents in this project's hub pool, including their names and purposes.",
+    description: "List peer agents in this project's hub pool with their names, purposes, host label, and hub-clocked presence (online, stale, offline). Registered offline peers are listed only when includeOffline is set.",
     parameters: {
       type: "object",
-      properties: {},
+      properties: {
+        includeOffline: {
+          type: "boolean",
+          description: "Also list registered peers whose hub lease has expired"
+        }
+      },
       additionalProperties: false
     },
-    async execute(client) {
-      return { agents: await client.listAgents() };
+    async execute(client, args) {
+      return { agents: await client.listAgents({ includeOffline: args.includeOffline === true }) };
     }
   },
   {
@@ -26188,8 +26204,8 @@ function printWorker(runtime, worker, payload, text, outcome) {
 }
 function hostMode(runtime) {
   try {
-    const hostname = new URL(runtime.serverUrl).hostname;
-    if (hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1") return "local";
+    const hostname2 = new URL(runtime.serverUrl).hostname;
+    if (hostname2 === "127.0.0.1" || hostname2 === "localhost" || hostname2 === "::1") return "local";
   } catch {
   }
   return "hub";
@@ -43087,6 +43103,13 @@ function meshTuiTheme(color) {
 function visibleAgents(snapshot) {
   return snapshot.agents.filter((agent) => agent.model !== "tui");
 }
+function presenceCell(agent, theme, width = 7) {
+  const presence = agent.presence ?? "n/a";
+  const cell = pad(presence, width);
+  if (presence === "online") return theme.success(cell);
+  if (presence === "stale") return theme.warning(cell);
+  return theme.dim(cell);
+}
 function panelMetric(snapshot, panel) {
   if (panel === "agents") {
     const agents = visibleAgents(snapshot);
@@ -43137,7 +43160,7 @@ function listLines(snapshot, view, theme) {
   const now = Date.parse(snapshot.fetchedAt);
   const mark = (index) => cursor(theme, index === view.selected, "list", view.pane);
   if (view.tab === "agents") {
-    return visibleAgents(snapshot).map((agent, index) => `${mark(index)}${pad(agent.name, 14)} ${agent.online ? theme.success(pad("yes", 3)) : theme.dim(pad("no", 3))} ${pad(agent.model ?? "-", 18)} ${pad(age(agent.lastSeenAt, now), 4)}`);
+    return visibleAgents(snapshot).map((agent, index) => `${mark(index)}${pad(agent.name, 14)} ${presenceCell(agent, theme)} ${pad(agent.host ?? "-", 12)} ${pad(agent.model ?? "-", 14)} ${pad(age(agent.lastSeenAt, now), 4)}`);
   }
   if (view.tab === "tasks" || view.tab === "workflows") {
     const runs = view.tab === "tasks" ? snapshot.runs.filter((run) => run.status === "running" || run.status === "waiting") : snapshot.runs;
@@ -43175,9 +43198,10 @@ function detailLines(snapshot, view, theme) {
     const related = snapshot.openMessages.filter((message) => message.fromName === agent.name || message.toName === agent.name);
     return [
       theme.accent(agent.name),
-      `${agent.online ? theme.success("online") : theme.dim("offline")}  ${agent.model ?? "-"}`,
+      `${presenceCell(agent, theme, (agent.presence ?? "n/a").length)}  ${agent.model ?? "-"}`,
+      `host ${agent.host ?? "-"}`,
       agent.purpose,
-      `seen ${age(agent.lastSeenAt, now)} ago`,
+      `seen ${age(agent.lastSeenAt, now)} ago \xB7 lease ${agent.leaseExpiresAt?.slice(11, 19) ?? "n/a"} UTC`,
       "",
       theme.dim("Open work"),
       ...related.length === 0 ? [theme.dim("none")] : related.map((message) => `${message.status}  ${message.fromName} \u2192 ${message.toName}  ${age(message.createdAt, now)}`)
@@ -43486,7 +43510,7 @@ async function runMeshTui(input) {
     }
     if (!useOpsStream && identity) {
       try {
-        const listed = await input.fetchImpl(`${base}/v1/agents`, { headers: headers(identity) });
+        const listed = await input.fetchImpl(`${base}/v1/agents?includeOffline=true`, { headers: headers(identity) });
         if (listed.ok) {
           const body = await readJson(listed);
           const byId = new Map(local.agents.map((agent) => [agent.id, agent]));
@@ -47744,7 +47768,7 @@ function createProgram(ctx, result) {
   });
   const peer = addGlobalOptions(program2.command("peer").description("Peer agent messaging and coordination"));
   peer.helpCommand("help", "Show peer help");
-  addGlobalOptions(peer.command("list").description("List online peer agents in this project's hub pool")).option("--payload <json>", "JSON payload").action(async function peerListAction(opts) {
+  addGlobalOptions(peer.command("list").description("List peer agents in this project's hub pool with host and presence")).option("--include-offline", "Also list registered peers whose hub lease has expired").option("--payload <json>", "JSON payload").action(async function peerListAction(opts) {
     result.code = await dispatchAgentCliCommand(runtimeFrom(ctx, this), "kxm_list", opts ?? {});
   });
   addGlobalOptions(peer.command("send [target] [content]").description("Send a focused request to a peer agent")).option("--target <name>", "Peer name or agent ID").option("--content <text>", "Focused request content").option("--delivery <mode>", "steer, followUp, or nextTurn").option("--correlation-id <id>", "Task grouping ID").option("--idempotency-key <key>", "Deduplication key").option("--workflow-context <json>", "Workflow context JSON").option("--ttl-ms <ms>", "Message TTL in milliseconds").option("--allow-offline", "Queue the request if the target is registered but offline").option("--payload <json>", "JSON payload").action(async function peerSendAction(target, content, opts) {

package/plugins/kxm/dist/client.js

@@ -1,11 +1,13 @@
 // plugins/kxm/src/client.ts
 import { createHash } from "node:crypto";
+import { hostname } from "node:os";
 
 // plugins/kxm/src/protocol.ts
 var DEFAULT_MESSAGE_TTL_MS = 24 * 60 * 6e4;
 var MAX_MESSAGE_TTL_MS = 7 * 24 * 60 * 6e4;
 var DEFAULT_MESSAGE_RETENTION_MS = 7 * 24 * 60 * 6e4;
 var MAX_BODY_BYTES = 256 * 1024;
+var MAX_AGENT_HOST_CHARS = 64;
 
 // plugins/kxm/src/workflow.ts
 function canonicalWorkflowEvidenceKey(value) {
@@ -21,6 +23,13 @@ var MeshWaitError = class extends Error {
     this.waitStatus = waitStatus;
   }
 };
+function defaultHostLabel() {
+  try {
+    return hostname().trim().slice(0, MAX_AGENT_HOST_CHARS) || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function completedFanoutResult(target, message) {
   if (message.status === "queued" || message.status === "delivered") {
     throw new Error(`message ${message.id} is not complete`);
@@ -110,8 +119,11 @@ var HubClient = class {
     this.onEvent = void 0;
     this.eventLoop = void 0;
   }
-  async listAgents() {
-    const result = await this.request("/v1/agents");
+  /** Online peers of this client's project. `includeOffline` also returns
+   * registered members whose lease the hub has already retired. */
+  async listAgents(options = {}) {
+    const path = options.includeOffline ? "/v1/agents?includeOffline=true" : "/v1/agents";
+    const result = await this.request(path);
     return result.agents;
   }
   async send(options) {
@@ -351,7 +363,8 @@ var HubClient = class {
           name: this.options.name,
           purpose: this.options.purpose,
           project: this.options.project,
-          model: this.options.model
+          model: this.options.model,
+          host: this.options.host ?? defaultHostLabel()
         })
       }, false);
       this.agent = registration.agent;

package/plugins/kxm/dist/core.js

@@ -12,6 +12,17 @@ var DEFAULT_RATE_LIMIT_MAX = 600;
 var DEFAULT_RATE_LIMIT_WINDOW_MS = 6e4;
 var MAX_BODY_BYTES = 256 * 1024;
 var MAX_CONTENT_CHARS = 32e3;
+var MAX_AGENT_HOST_CHARS = 64;
+function agentPresenceView(agent, staleAfterMs = DEFAULT_STALE_AFTER_MS, now = Date.now()) {
+  const lastSeenMs = Date.parse(agent.lastSeenAt);
+  const leaseExpiresAtMs = (Number.isFinite(lastSeenMs) ? lastSeenMs : 0) + staleAfterMs;
+  const leaseExpiresAt = new Date(leaseExpiresAtMs).toISOString();
+  if (!agent.online) return { leaseExpiresAt, presence: "offline" };
+  return { leaseExpiresAt, presence: now < leaseExpiresAtMs ? "online" : "stale" };
+}
+function toAgentRecord(agent, staleAfterMs, now) {
+  return { ...agent, ...agentPresenceView(agent, staleAfterMs, now) };
+}
 var ProtocolError = class extends Error {
   statusCode;
   code;
@@ -945,14 +956,19 @@ var AGENT_COMMANDS = [
     group: "peer",
     verb: "list",
     label: "List hub peers",
-    description: "List online peer agents in this project's hub pool, including their names and purposes.",
+    description: "List peer agents in this project's hub pool with their names, purposes, host label, and hub-clocked presence (online, stale, offline). Registered offline peers are listed only when includeOffline is set.",
     parameters: {
       type: "object",
-      properties: {},
+      properties: {
+        includeOffline: {
+          type: "boolean",
+          description: "Also list registered peers whose hub lease has expired"
+        }
+      },
       additionalProperties: false
     },
-    async execute(client) {
-      return { agents: await client.listAgents() };
+    async execute(client, args) {
+      return { agents: await client.listAgents({ includeOffline: args.includeOffline === true }) };
     }
   },
   {
@@ -2011,6 +2027,7 @@ export {
   DEFAULT_RATE_LIMIT_WINDOW_MS,
   DEFAULT_STALE_AFTER_MS,
   LOG_LEVEL_PRIORITY,
+  MAX_AGENT_HOST_CHARS,
   MAX_BODY_BYTES,
   MAX_CONTENT_CHARS,
   MAX_CONTEXT_ITEM_IDS,
@@ -2026,6 +2043,7 @@ export {
   TERMINAL_RECEIPT_SCHEMA,
   WORKER_RESULT_SCHEMA,
   WORKER_SCHEMA,
+  agentPresenceView,
   agentWorker,
   behavioralConfigHash,
   clearSessionTokenFromDisk,
@@ -2066,6 +2084,7 @@ export {
   rotateLogFiles,
   sessionTokenPath,
   timingSafeStringCompare,
+  toAgentRecord,
   validateTerminalReceipt,
   workerResult
 };

package/plugins/kxm/dist/extension.js

@@ -14534,6 +14534,7 @@ import { dirname, join, resolve } from "node:path";
 
 // plugins/kxm/src/client.ts
 import { createHash } from "node:crypto";
+import { hostname } from "node:os";
 
 // plugins/kxm/src/protocol.ts
 var DEFAULT_MESSAGE_TTL_MS = 24 * 60 * 6e4;
@@ -14541,6 +14542,7 @@ var MAX_MESSAGE_TTL_MS = 7 * 24 * 60 * 6e4;
 var DEFAULT_MESSAGE_RETENTION_MS = 7 * 24 * 60 * 6e4;
 var MAX_BODY_BYTES = 256 * 1024;
 var MAX_CONTENT_CHARS = 32e3;
+var MAX_AGENT_HOST_CHARS = 64;
 
 // plugins/kxm/src/workflow.ts
 function canonicalWorkflowEvidenceKey(value) {
@@ -14556,6 +14558,13 @@ var MeshWaitError = class extends Error {
     this.waitStatus = waitStatus;
   }
 };
+function defaultHostLabel() {
+  try {
+    return hostname().trim().slice(0, MAX_AGENT_HOST_CHARS) || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function completedFanoutResult(target, message) {
   if (message.status === "queued" || message.status === "delivered") {
     throw new Error(`message ${message.id} is not complete`);
@@ -14645,8 +14654,11 @@ var HubClient = class {
     this.onEvent = void 0;
     this.eventLoop = void 0;
   }
-  async listAgents() {
-    const result2 = await this.request("/v1/agents");
+  /** Online peers of this client's project. `includeOffline` also returns
+   * registered members whose lease the hub has already retired. */
+  async listAgents(options = {}) {
+    const path = options.includeOffline ? "/v1/agents?includeOffline=true" : "/v1/agents";
+    const result2 = await this.request(path);
     return result2.agents;
   }
   async send(options) {
@@ -14886,7 +14898,8 @@ var HubClient = class {
           name: this.options.name,
           purpose: this.options.purpose,
           project: this.options.project,
-          model: this.options.model
+          model: this.options.model,
+          host: this.options.host ?? defaultHostLabel()
         })
       }, false);
       this.agent = registration.agent;
@@ -15014,14 +15027,19 @@ var AGENT_COMMANDS = [
     group: "peer",
     verb: "list",
     label: "List hub peers",
-    description: "List online peer agents in this project's hub pool, including their names and purposes.",
+    description: "List peer agents in this project's hub pool with their names, purposes, host label, and hub-clocked presence (online, stale, offline). Registered offline peers are listed only when includeOffline is set.",
     parameters: {
       type: "object",
-      properties: {},
+      properties: {
+        includeOffline: {
+          type: "boolean",
+          description: "Also list registered peers whose hub lease has expired"
+        }
+      },
       additionalProperties: false
     },
-    async execute(client) {
-      return { agents: await client.listAgents() };
+    async execute(client, args) {
+      return { agents: await client.listAgents({ includeOffline: args.includeOffline === true }) };
     }
   },
   {

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

@@ -15755,12 +15755,14 @@ var StdioServerTransport = class {
 
 // plugins/kxm/src/client.ts
 import { createHash } from "node:crypto";
+import { hostname } from "node:os";
 
 // plugins/kxm/src/protocol.ts
 var DEFAULT_MESSAGE_TTL_MS = 24 * 60 * 6e4;
 var MAX_MESSAGE_TTL_MS = 7 * 24 * 60 * 6e4;
 var DEFAULT_MESSAGE_RETENTION_MS = 7 * 24 * 60 * 6e4;
 var MAX_BODY_BYTES = 256 * 1024;
+var MAX_AGENT_HOST_CHARS = 64;
 
 // plugins/kxm/src/workflow.ts
 function canonicalWorkflowEvidenceKey(value) {
@@ -15776,6 +15778,13 @@ var MeshWaitError = class extends Error {
     this.waitStatus = waitStatus;
   }
 };
+function defaultHostLabel() {
+  try {
+    return hostname().trim().slice(0, MAX_AGENT_HOST_CHARS) || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function completedFanoutResult(target, message) {
   if (message.status === "queued" || message.status === "delivered") {
     throw new Error(`message ${message.id} is not complete`);
@@ -15865,8 +15874,11 @@ var HubClient = class {
     this.onEvent = void 0;
     this.eventLoop = void 0;
   }
-  async listAgents() {
-    const result = await this.request("/v1/agents");
+  /** Online peers of this client's project. `includeOffline` also returns
+   * registered members whose lease the hub has already retired. */
+  async listAgents(options = {}) {
+    const path = options.includeOffline ? "/v1/agents?includeOffline=true" : "/v1/agents";
+    const result = await this.request(path);
     return result.agents;
   }
   async send(options) {
@@ -16106,7 +16118,8 @@ var HubClient = class {
           name: this.options.name,
           purpose: this.options.purpose,
           project: this.options.project,
-          model: this.options.model
+          model: this.options.model,
+          host: this.options.host ?? defaultHostLabel()
         })
       }, false);
       this.agent = registration.agent;
@@ -16325,14 +16338,19 @@ var AGENT_COMMANDS = [
     group: "peer",
     verb: "list",
     label: "List hub peers",
-    description: "List online peer agents in this project's hub pool, including their names and purposes.",
+    description: "List peer agents in this project's hub pool with their names, purposes, host label, and hub-clocked presence (online, stale, offline). Registered offline peers are listed only when includeOffline is set.",
     parameters: {
       type: "object",
-      properties: {},
+      properties: {
+        includeOffline: {
+          type: "boolean",
+          description: "Also list registered peers whose hub lease has expired"
+        }
+      },
       additionalProperties: false
     },
-    async execute(client) {
-      return { agents: await client.listAgents() };
+    async execute(client, args) {
+      return { agents: await client.listAgents({ includeOffline: args.includeOffline === true }) };
     }
   },
   {
@@ -17127,7 +17145,7 @@ async function deliverInboxNotification(messageId, delivered, notify) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.70";
+var VERSION = "0.7.71";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
 var meshClient;

package/plugins/kxm/dist/server.js

@@ -7387,6 +7387,17 @@ var DEFAULT_RATE_LIMIT_MAX = 600;
 var DEFAULT_RATE_LIMIT_WINDOW_MS = 6e4;
 var MAX_BODY_BYTES = 256 * 1024;
 var MAX_CONTENT_CHARS = 32e3;
+var MAX_AGENT_HOST_CHARS = 64;
+function agentPresenceView(agent, staleAfterMs = DEFAULT_STALE_AFTER_MS, now = Date.now()) {
+  const lastSeenMs = Date.parse(agent.lastSeenAt);
+  const leaseExpiresAtMs = (Number.isFinite(lastSeenMs) ? lastSeenMs : 0) + staleAfterMs;
+  const leaseExpiresAt = new Date(leaseExpiresAtMs).toISOString();
+  if (!agent.online) return { leaseExpiresAt, presence: "offline" };
+  return { leaseExpiresAt, presence: now < leaseExpiresAtMs ? "online" : "stale" };
+}
+function toAgentRecord(agent, staleAfterMs, now) {
+  return { ...agent, ...agentPresenceView(agent, staleAfterMs, now) };
+}
 var ProtocolError = class extends Error {
   statusCode;
   code;
@@ -8575,14 +8586,19 @@ var AGENT_COMMANDS = [
     group: "peer",
     verb: "list",
     label: "List hub peers",
-    description: "List online peer agents in this project's hub pool, including their names and purposes.",
+    description: "List peer agents in this project's hub pool with their names, purposes, host label, and hub-clocked presence (online, stale, offline). Registered offline peers are listed only when includeOffline is set.",
     parameters: {
       type: "object",
-      properties: {},
+      properties: {
+        includeOffline: {
+          type: "boolean",
+          description: "Also list registered peers whose hub lease has expired"
+        }
+      },
       additionalProperties: false
     },
-    async execute(client) {
-      return { agents: await client.listAgents() };
+    async execute(client, args) {
+      return { agents: await client.listAgents({ includeOffline: args.includeOffline === true }) };
     }
   },
   {
@@ -12138,9 +12154,9 @@ function isLoopback(host2) {
   if (host2 === "localhost" || host2 === "::1") return true;
   return isIP(host2) === 4 && host2.startsWith("127.");
 }
-function publicAgent(agent) {
-  const { key: _key, ...record } = agent;
-  return record;
+function publicAgent(agent, staleAfterMs, now = Date.now()) {
+  const { key: _key, ...identity } = agent;
+  return toAgentRecord(identity, staleAfterMs, now);
 }
 function safeTokenEqual(actual, expected) {
   return timingSafeStringCompare(actual, expected);
@@ -12560,7 +12576,8 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
     }
   }
   function opsSnapshot(project) {
-    const projectAgents = [...agents.values()].filter((agent) => agent.project === project).map(publicAgent).sort((left, right) => Number(right.online) - Number(left.online) || left.name.localeCompare(right.name));
+    const snapshotAt = Date.now();
+    const projectAgents = [...agents.values()].filter((agent) => agent.project === project).map((agent) => publicAgent(agent, staleAfterMs, snapshotAt)).sort((left, right) => Number(right.online) - Number(left.online) || left.name.localeCompare(right.name));
     const open = store.getOpenMessages(project);
     const projectRuns = [...workflowRuns.values()].filter((run) => run.project === project).sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
     return {
@@ -12610,7 +12627,7 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
   function broadcastPresence(agent) {
     for (const candidate of agents.values()) {
       if (candidate.project === agent.project && candidate.id !== agent.id && candidate.online) {
-        publish(candidate.id, { type: "presence", agent: publicAgent(agent) });
+        publish(candidate.id, { type: "presence", agent: publicAgent(agent, staleAfterMs) });
       }
     }
     publishOps(agent.project, "agents");
@@ -13912,6 +13929,7 @@ data: ${JSON.stringify({ type: "ops", project, topic: "agents", at: nowIso() })}
         const project = requireString(body.project, "project", { max: 128 });
         requireProjectAuth(request, project);
         const model = optionalString(body.model, "model", 128);
+        const hostLabel = optionalString(body.host, "host", MAX_AGENT_HOST_CHARS);
         const existing = [...agents.values()].find(
           (agent2) => agent2.project === project && agent2.name.toLowerCase() === name.toLowerCase()
         );
@@ -13938,17 +13956,27 @@ data: ${JSON.stringify({ type: "ops", project, topic: "agents", at: nowIso() })}
         agent.online = true;
         if (model) agent.model = model;
         else delete agent.model;
+        if (hostLabel) agent.host = hostLabel;
+        else delete agent.host;
         store.saveAgent(agent);
         counters.registrations += 1;
-        logger({ event: existing ? "agent_resumed" : "agent_registered", agentId: agent.id, name, project });
+        logger({
+          event: existing ? "agent_resumed" : "agent_registered",
+          agentId: agent.id,
+          name,
+          project,
+          ...hostLabel ? { host: hostLabel } : {}
+        });
         broadcastPresence(agent);
-        json(response, existing ? 200 : 201, { agent: publicAgent(agent), agentKey: agent.key, resumed: Boolean(existing) });
+        json(response, existing ? 200 : 201, { agent: publicAgent(agent, staleAfterMs), agentKey: agent.key, resumed: Boolean(existing) });
         return;
       }
       if (method === "GET" && url.pathname === "/v1/agents") {
         const current = requireAgent(request);
         requireProjectAuth(request, current.project);
-        const result = [...agents.values()].filter((agent) => agent.project === current.project && agent.online).map(publicAgent);
+        const includeOffline = url.searchParams.get("includeOffline") === "true";
+        const listedAt = Date.now();
+        const result = [...agents.values()].filter((agent) => agent.project === current.project && (agent.online || includeOffline)).map((agent) => publicAgent(agent, staleAfterMs, listedAt));
         json(response, 200, { agents: result });
         return;
       }
@@ -13957,7 +13985,7 @@ data: ${JSON.stringify({ type: "ops", project, topic: "agents", at: nowIso() })}
         const current = requireAgent(request, decodeURIComponent(heartbeatMatch[1]));
         requireProjectAuth(request, current.project);
         await readJson(request);
-        json(response, 200, { agent: publicAgent(current) });
+        json(response, 200, { agent: publicAgent(current, staleAfterMs) });
         return;
       }
       const agentMatch = url.pathname.match(/^\/v1\/agents\/([^/]+)$/);
@@ -13989,7 +14017,7 @@ data: ${JSON.stringify({ type: "ops", project, topic: "agents", at: nowIso() })}
           ...presenceOnly ? { "x-kxm-events-mode": "presence" } : {}
         });
         response.write(`event: ready
-data: ${JSON.stringify({ agent: publicAgent(current) })}
+data: ${JSON.stringify({ agent: publicAgent(current, staleAfterMs) })}
 
 `);
         const client = {

package/plugins/kxm/package.json

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

package/plugins/kxm/skills/kxm-peer/SKILL.md

@@ -15,7 +15,9 @@ All commands support `--json` for machine-readable output.
 
 | Command | Purpose | Key Options |
 |---|---|---|
-| `kxm peer list` | List online peer agents and their purposes | `--json` |
+| `kxm peer list` | List peer agents with purpose, host label, and presence | `--json`, `--include-offline` |
+
+Every listed peer carries `host` (the box it declared at registration), `lastSeenAt`, `leaseExpiresAt`, and `presence`. Presence is the hub's own reading of its heartbeat lease: `online` holds the lease, `stale` has passed `leaseExpiresAt` but has not been swept yet, and `offline` is a registered peer the hub has retired. Offline peers are listed only with `--include-offline`. The host label is a reading aid, never a permission.
 
 ### Sending Requests (`kxm peer send`)
 

package/plugins/kxm/src/cli.ts

@@ -533,7 +533,8 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   const peer = addGlobalOptions(program.command("peer").description("Peer agent messaging and coordination"));
   peer.helpCommand("help", "Show peer help");
 
-  addGlobalOptions(peer.command("list").description("List online peer agents in this project's hub pool"))
+  addGlobalOptions(peer.command("list").description("List peer agents in this project's hub pool with host and presence"))
+    .option("--include-offline", "Also list registered peers whose hub lease has expired")
     .option("--payload <json>", "JSON payload")
     .action(async function peerListAction(this: Command, opts?: Record<string, unknown>) {
       result.code = await dispatchAgentCliCommand(runtimeFrom(ctx, this), "kxm_list", opts ?? {});

package/plugins/kxm/src/client.ts

@@ -1,4 +1,6 @@
 import { createHash } from "node:crypto";
+import { hostname } from "node:os";
+import { MAX_AGENT_HOST_CHARS } from "./protocol.ts";
 import type { AgentRecord, DeliveryMode, HubEvent, MessageRecord, WorkflowMessageContext } from "./protocol.ts";
 import type { ContextAuthority, ContextConfidence, ContextItem, ContextItemAuditMetadata, ContextItemKind, ContextPacket } from "./context.ts";
 import {
@@ -52,6 +54,10 @@ export interface HubClientOptions {
   purpose: string;
   project: string;
   model?: string;
+  /** Label for the box this client runs on, declared at registration.
+   * Defaults to the machine hostname; the hub records it for readers and
+   * never uses it to authorize anything. */
+  host?: string;
   heartbeatMs?: number;
   reconnectMs?: number;
   requestTimeoutMs?: number;
@@ -94,6 +100,17 @@ class MeshWaitError extends Error {
   }
 }
 
+/** The box label a client declares when it registers. Bounded to the hub's
+ * limit so a long hostname cannot turn registration into a 400, and dropped
+ * entirely when the platform cannot report one. */
+function defaultHostLabel(): string | undefined {
+  try {
+    return hostname().trim().slice(0, MAX_AGENT_HOST_CHARS) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function completedFanoutResult(target: string, message: MessageRecord): FanoutResult {
   if (message.status === "queued" || message.status === "delivered") {
     throw new Error(`message ${message.id} is not complete`);
@@ -208,8 +225,11 @@ export class HubClient {
     this.eventLoop = undefined;
   }
 
-  async listAgents(): Promise<AgentRecord[]> {
-    const result = await this.request<{ agents: AgentRecord[] }>("/v1/agents");
+  /** Online peers of this client's project. `includeOffline` also returns
+   * registered members whose lease the hub has already retired. */
+  async listAgents(options: { includeOffline?: boolean } = {}): Promise<AgentRecord[]> {
+    const path = options.includeOffline ? "/v1/agents?includeOffline=true" : "/v1/agents";
+    const result = await this.request<{ agents: AgentRecord[] }>(path);
     return result.agents;
   }
 
@@ -555,6 +575,7 @@ export class HubClient {
           purpose: this.options.purpose,
           project: this.options.project,
           model: this.options.model,
+          host: this.options.host ?? defaultHostLabel(),
         }),
       }, false);
       this.agent = registration.agent;

package/plugins/kxm/src/commands.ts

@@ -194,14 +194,20 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
     group: "peer",
     verb: "list",
     label: "List hub peers",
-    description: "List online peer agents in this project's hub pool, including their names and purposes.",
+    description:
+      "List peer agents in this project's hub pool with their names, purposes, host label, and hub-clocked presence (online, stale, offline). Registered offline peers are listed only when includeOffline is set.",
     parameters: {
       type: "object",
-      properties: {},
+      properties: {
+        includeOffline: {
+          type: "boolean",
+          description: "Also list registered peers whose hub lease has expired",
+        },
+      },
       additionalProperties: false,
     },
-    async execute(client) {
-      return { agents: await client.listAgents() };
+    async execute(client, args) {
+      return { agents: await client.listAgents({ includeOffline: args.includeOffline === true }) };
     },
   },
   {

package/plugins/kxm/src/hub.ts

@@ -10,6 +10,7 @@ import {
   DEFAULT_RATE_LIMIT_MAX,
   DEFAULT_RATE_LIMIT_WINDOW_MS,
   DEFAULT_STALE_AFTER_MS,
+  MAX_AGENT_HOST_CHARS,
   MAX_BODY_BYTES,
   MAX_CONTENT_CHARS,
   MAX_MESSAGE_TTL_MS,
@@ -22,6 +23,7 @@ import {
   parseBoundedInteger,
   parseDeliveryMode,
   requireString,
+  toAgentRecord,
   type AgentRecord,
   type DeliveryMode,
   type HubEvent,
@@ -118,9 +120,12 @@ function isLoopback(host: string): boolean {
   return isIP(host) === 4 && host.startsWith("127.");
 }
 
-function publicAgent(agent: StoredAgent): AgentRecord {
-  const { key: _key, ...record } = agent;
-  return record;
+/** Drop the agent key and attach hub-clocked presence. Every caller passes the
+ * hub's own `staleAfterMs` and clock, so no reader ever sees a lease derived
+ * from a client timestamp. */
+function publicAgent(agent: StoredAgent, staleAfterMs: number, now = Date.now()): AgentRecord {
+  const { key: _key, ...identity } = agent;
+  return toAgentRecord(identity, staleAfterMs, now);
 }
 
 function safeTokenEqual(actual: string | undefined, expected: string): boolean {
@@ -623,9 +628,10 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
   }
 
   function opsSnapshot(project: string) {
+    const snapshotAt = Date.now();
     const projectAgents = [...agents.values()]
       .filter((agent) => agent.project === project)
-      .map(publicAgent)
+      .map((agent) => publicAgent(agent, staleAfterMs, snapshotAt))
       .sort((left, right) => Number(right.online) - Number(left.online) || left.name.localeCompare(right.name));
     const open = store.getOpenMessages(project);
     const projectRuns = [...workflowRuns.values()]
@@ -683,7 +689,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
   function broadcastPresence(agent: StoredAgent): void {
     for (const candidate of agents.values()) {
       if (candidate.project === agent.project && candidate.id !== agent.id && candidate.online) {
-        publish(candidate.id, { type: "presence", agent: publicAgent(agent) });
+        publish(candidate.id, { type: "presence", agent: publicAgent(agent, staleAfterMs) });
       }
     }
     publishOps(agent.project, "agents");
@@ -2109,6 +2115,9 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         const project = requireString(body.project, "project", { max: 128 });
         requireProjectAuth(request, project);
         const model = optionalString(body.model, "model", 128);
+        // A client declares which box it runs on. The label is a reading aid
+        // only: the project token is still the whole of admission.
+        const hostLabel = optionalString(body.host, "host", MAX_AGENT_HOST_CHARS);
         const existing = [...agents.values()].find(
           (agent) => agent.project === project && agent.name.toLowerCase() === name.toLowerCase(),
         );
@@ -2135,20 +2144,34 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         agent.online = true;
         if (model) agent.model = model;
         else delete agent.model;
+        if (hostLabel) agent.host = hostLabel;
+        else delete agent.host;
         store.saveAgent(agent);
         counters.registrations += 1;
-        logger({ event: existing ? "agent_resumed" : "agent_registered", agentId: agent.id, name, project });
+        logger({
+          event: existing ? "agent_resumed" : "agent_registered",
+          agentId: agent.id,
+          name,
+          project,
+          ...(hostLabel ? { host: hostLabel } : {}),
+        });
         broadcastPresence(agent);
-        json(response, existing ? 200 : 201, { agent: publicAgent(agent), agentKey: agent.key, resumed: Boolean(existing) });
+        json(response, existing ? 200 : 201, { agent: publicAgent(agent, staleAfterMs), agentKey: agent.key, resumed: Boolean(existing) });
         return;
       }
 
       if (method === "GET" && url.pathname === "/v1/agents") {
         const current = requireAgent(request);
         requireProjectAuth(request, current.project);
+        // Offline members are registered peers of the caller's own project
+        // whose lease the sweep has already retired. They stay out of the
+        // list unless a caller asks for them, so discovery keeps meaning
+        // "who can answer right now".
+        const includeOffline = url.searchParams.get("includeOffline") === "true";
+        const listedAt = Date.now();
         const result = [...agents.values()]
-          .filter((agent) => agent.project === current.project && agent.online)
-          .map(publicAgent);
+          .filter((agent) => agent.project === current.project && (agent.online || includeOffline))
+          .map((agent) => publicAgent(agent, staleAfterMs, listedAt));
         json(response, 200, { agents: result });
         return;
       }
@@ -2158,7 +2181,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
         const current = requireAgent(request, decodeURIComponent(heartbeatMatch[1]!));
         requireProjectAuth(request, current.project);
         await readJson(request);
-        json(response, 200, { agent: publicAgent(current) });
+        json(response, 200, { agent: publicAgent(current, staleAfterMs) });
         return;
       }
 
@@ -2191,7 +2214,7 @@ export function createMeshHub(options: MeshHubOptions = {}): MeshHub {
           "x-content-type-options": "nosniff",
           ...(presenceOnly ? { "x-kxm-events-mode": "presence" } : {}),
         });
-        response.write(`event: ready\ndata: ${JSON.stringify({ agent: publicAgent(current) })}\n\n`);
+        response.write(`event: ready\ndata: ${JSON.stringify({ agent: publicAgent(current, staleAfterMs) })}\n\n`);
         const client: SseClient = {
           response,
           heartbeat: setInterval(() => response.write(": heartbeat\n\n"), 15_000),

package/plugins/kxm/src/local-snapshot.ts

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
-import type { AgentRecord, MessageRecord } from "./protocol.ts";
+import type { AgentIdentity, AgentRecord, MessageRecord } from "./protocol.ts";
 import type { WorkflowRun } from "./workflow.ts";
 import { readRoutingRecords } from "./telemetry.ts";
 import type { RoutingRecord, RoutingRecordV2 } from "./routing.ts";
@@ -253,7 +253,15 @@ export function loadLocalMeshSnapshot(
     const database = new DatabaseSync(dataPath, { readOnly: true });
     try {
       database.exec("PRAGMA busy_timeout = 5000");
-      agents = readJsonRows<AgentRecord>(database, "SELECT record FROM agents");
+      // Stored rows carry identity only. Presence is derived here against the
+      // default lease window, because the hub's configured `staleAfterMs` is
+      // not in the file; a reachable hub's own records replace these.
+      // Stored rows carry identity only. Presence is NOT computed here: the hub's
+      // configured staleAfterMs and its clock are not in the file, so a reader-side
+      // lease would mislabel agents against the hub's own projection. The stored
+      // `online` boolean is the only durable truth; the hub's /v1/agents or the
+      // ops snapshot is the authoritative presence source.
+      agents = readJsonRows<AgentIdentity>(database, "SELECT record FROM agents");
       openMessages = readOpenMessageMetadata(database);
       openMessageTotal = countRows(database, "messages", " WHERE json_extract(record, '$.status') IN ('queued', 'delivered')");
       legacyRuns = readJsonRows<WorkflowRun>(database, "SELECT record FROM workflow_runs ORDER BY rowid DESC LIMIT 8");

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

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.70";
+const VERSION = "0.7.71";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/protocol.ts

@@ -12,21 +12,62 @@ export const DEFAULT_RATE_LIMIT_MAX = 600;
 export const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
 export const MAX_BODY_BYTES = 256 * 1024;
 export const MAX_CONTENT_CHARS = 32_000;
+export const MAX_AGENT_HOST_CHARS = 64;
 
 export type DeliveryMode = "steer" | "followUp" | "nextTurn";
 export type MessageStatus = "queued" | "delivered" | "replied" | "cancelled" | "expired" | "error";
+export type AgentPresence = "online" | "stale" | "offline";
 
-export interface AgentRecord {
+/** The durable half of an agent: exactly the fields the hub persists in the
+ * agents record JSON. Presence is never stored, so a restored database can
+ * never claim an agent was alive. */
+export interface AgentIdentity {
   id: string;
   name: string;
   purpose: string;
   project: string;
   model?: string;
+  /** Client-declared label for the box this agent runs on. It exists so a
+   * reader can tell two boxes apart; the hub never reads it for
+   * authorization, project scope, or target resolution. */
+  host?: string;
   connectedAt: string;
   lastSeenAt: string;
   online: boolean;
 }
 
+/** The public projection of an agent: durable identity plus presence derived
+ * from the hub clock at read time. */
+export interface AgentRecord extends AgentIdentity {
+  /** `lastSeenAt + staleAfterMs`: the heartbeat lease the stale sweep enforces.
+   * Absent when projected from the local store without the hub's clock or lease. */
+  leaseExpiresAt?: string;
+  /** Hub-clocked presence. Absent when the reader has no hub projection. */
+  presence?: AgentPresence;
+}
+
+/** Presence is hub-clocked and never client-reported. An agent holds its lease
+ * until `lastSeenAt + staleAfterMs`; between lease expiry and the sweep that
+ * retires it, it reads `stale`; once retired it reads `offline`. An
+ * unparseable `lastSeenAt` leaves the lease at the epoch, which reads as an
+ * expired lease rather than as a live agent. */
+export function agentPresenceView(
+  agent: AgentIdentity,
+  staleAfterMs: number = DEFAULT_STALE_AFTER_MS,
+  now: number = Date.now(),
+): { leaseExpiresAt: string; presence: AgentPresence } {
+  const lastSeenMs = Date.parse(agent.lastSeenAt);
+  const leaseExpiresAtMs = (Number.isFinite(lastSeenMs) ? lastSeenMs : 0) + staleAfterMs;
+  const leaseExpiresAt = new Date(leaseExpiresAtMs).toISOString();
+  if (!agent.online) return { leaseExpiresAt, presence: "offline" };
+  return { leaseExpiresAt, presence: now < leaseExpiresAtMs ? "online" : "stale" };
+}
+
+/** Project a durable identity onto the wire shape readers consume. */
+export function toAgentRecord(agent: AgentIdentity, staleAfterMs?: number, now?: number): AgentRecord {
+  return { ...agent, ...agentPresenceView(agent, staleAfterMs, now) };
+}
+
 export interface MessageReply {
   content: string;
   createdAt: string;

package/plugins/kxm/src/store.ts

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import type { DatabaseSync } from "./sqlite.ts";
-import type { AgentRecord, MessageRecord } from "./protocol.ts";
+import type { AgentIdentity, MessageRecord } from "./protocol.ts";
 import type { ContextItem } from "./context.ts";
 import type { WorkflowJournalEntry, WorkflowRun } from "./workflow.ts";
 import {
@@ -78,7 +78,10 @@ export const HUB_STORE_SCHEMA_SPEC: DatabaseSchemaSpec = Object.freeze({
   tables: HUB_STORE_TABLES,
 });
 
-export interface StoredAgent extends AgentRecord {
+/** The stored shape stays the durable identity plus the agent key: presence
+ * and the lease are derived on read, so the agents record JSON grows only by
+ * the additive `host` label. */
+export interface StoredAgent extends AgentIdentity {
   key: string;
 }
 

package/plugins/kxm/src/tui.ts

@@ -310,6 +310,19 @@ function visibleAgents(snapshot: MeshTuiSnapshot): AgentRecord[] {
   return snapshot.agents.filter((agent) => agent.model !== "tui");
 }
 
+/** Presence comes from the hub clock, so the dash colours it rather than
+ * recomputing it: green holds a lease, amber has lost it but has not been
+ * swept, dim is a registered peer that is gone. */
+function presenceCell(agent: AgentRecord, theme: MeshTuiTheme, width = 7): string {
+  // Local-store projections carry no hub-clocked presence; the dash shows "n/a"
+  // rather than inventing a lease from the reader's clock.
+  const presence = agent.presence ?? "n/a";
+  const cell = pad(presence, width);
+  if (presence === "online") return theme.success(cell);
+  if (presence === "stale") return theme.warning(cell);
+  return theme.dim(cell);
+}
+
 function panelMetric(snapshot: MeshTuiSnapshot, panel: MeshTuiPanel): string {
   if (panel === "agents") {
     const agents = visibleAgents(snapshot);
@@ -441,7 +454,7 @@ function listLines(snapshot: MeshTuiSnapshot, view: MeshTuiView, theme: MeshTuiT
   const mark = (index: number) => cursor(theme, index === view.selected, "list", view.pane);
   if (view.tab === "agents") {
     return visibleAgents(snapshot).map((agent, index) => (
-      `${mark(index)}${pad(agent.name, 14)} ${agent.online ? theme.success(pad("yes", 3)) : theme.dim(pad("no", 3))} ${pad(agent.model ?? "-", 18)} ${pad(age(agent.lastSeenAt, now), 4)}`
+      `${mark(index)}${pad(agent.name, 14)} ${presenceCell(agent, theme)} ${pad(agent.host ?? "-", 12)} ${pad(agent.model ?? "-", 14)} ${pad(age(agent.lastSeenAt, now), 4)}`
     ));
   }
   if (view.tab === "tasks" || view.tab === "workflows") {
@@ -489,9 +502,10 @@ function detailLines(snapshot: MeshTuiSnapshot, view: MeshTuiView, theme: MeshTu
     const related = snapshot.openMessages.filter((message) => message.fromName === agent.name || message.toName === agent.name);
     return [
       theme.accent(agent.name),
-      `${agent.online ? theme.success("online") : theme.dim("offline")}  ${agent.model ?? "-"}`,
+      `${presenceCell(agent, theme, (agent.presence ?? "n/a").length)}  ${agent.model ?? "-"}`,
+      `host ${agent.host ?? "-"}`,
       agent.purpose,
-      `seen ${age(agent.lastSeenAt, now)} ago`,
+      `seen ${age(agent.lastSeenAt, now)} ago · lease ${agent.leaseExpiresAt?.slice(11, 19) ?? "n/a"} UTC`,
       "",
       theme.dim("Open work"),
       ...(related.length === 0 ? [theme.dim("none")] : related.map((message) => `${message.status}  ${message.fromName} → ${message.toName}  ${age(message.createdAt, now)}`)),
@@ -875,7 +889,9 @@ export async function runMeshTui(input: {
     }
     if (!useOpsStream && identity) {
       try {
-        const listed = await input.fetchImpl(`${base}/v1/agents`, { headers: headers(identity) });
+        // Offline members too: the ops snapshot lists the whole project, and
+        // the legacy path is a fallback for the same screen, not a narrower one.
+        const listed = await input.fetchImpl(`${base}/v1/agents?includeOffline=true`, { headers: headers(identity) });
         if (listed.ok) {
           const body = await readJson<{ agents: AgentRecord[] }>(listed);
           const byId = new Map(local.agents.map((agent) => [agent.id, agent]));