@kontextmind/kxm 0.7.70 → 0.7.72

package/plugins/kxm/dist/server.js

@@ -7387,6 +7387,21 @@ 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;
+var MIN_LEASE_TTL_MS = 5e3;
+var MAX_LEASE_TTL_MS = 10 * 6e4;
+var DEFAULT_LEASE_TTL_MS = 5 * 6e4;
+var MAX_LEASE_RESOURCE_CHARS = 200;
+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 +8590,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 }) };
     }
   },
   {
@@ -11661,7 +11681,7 @@ function withDatabaseTransaction(database, work, mode = "IMMEDIATE", clock = mon
 }
 
 // plugins/kxm/src/store.ts
-var HUB_STORE_SCHEMA_VERSION = 3;
+var HUB_STORE_SCHEMA_VERSION = 4;
 var HUB_STORE_TABLES = Object.freeze({
   agents: Object.freeze(["id", "record"]),
   messages: Object.freeze(["id", "record"]),
@@ -11669,9 +11689,10 @@ var HUB_STORE_TABLES = Object.freeze({
   agent_sequences: Object.freeze(["agent_id", "next_seq"]),
   workflow_runs: Object.freeze(["id", "definition_id", "delivery_id", "record"]),
   workflow_journal: Object.freeze(["id", "run_id", "category", "area", "record"]),
-  context_items: Object.freeze(["id", "project", "kind", "record"])
+  context_items: Object.freeze(["id", "project", "kind", "record"]),
+  leases: Object.freeze(["resource", "holder_agent_id", "fencing_token", "expires_at", "record"])
 });
-var HUB_STORE_SCHEMA_V3 = `
+var HUB_STORE_SCHEMA_V4 = `
   CREATE TABLE IF NOT EXISTS agents (
     id TEXT PRIMARY KEY,
     record TEXT NOT NULL
@@ -11720,12 +11741,30 @@ var HUB_STORE_SCHEMA_V3 = `
     record TEXT NOT NULL
   ) STRICT;
   CREATE INDEX IF NOT EXISTS context_items_project ON context_items(project);
+  CREATE TABLE IF NOT EXISTS leases (
+    resource TEXT PRIMARY KEY,
+    holder_agent_id TEXT NOT NULL,
+    fencing_token INTEGER NOT NULL,
+    expires_at TEXT NOT NULL,
+    record TEXT NOT NULL
+  ) STRICT;
 `;
 var HUB_STORE_SCHEMA_SPEC = Object.freeze({
-  schema: HUB_STORE_SCHEMA_V3,
+  schema: HUB_STORE_SCHEMA_V4,
   version: HUB_STORE_SCHEMA_VERSION,
   tables: HUB_STORE_TABLES
 });
+function parseLeaseRecord(record) {
+  try {
+    return JSON.parse(record);
+  } catch {
+    return void 0;
+  }
+}
+function leaseHasLapsed(lease, nowMs) {
+  const expiresAtMs = Date.parse(lease.expiresAt);
+  return !Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs;
+}
 var MessageMap = class extends Map {
   store;
   constructor(store) {
@@ -11758,6 +11797,7 @@ var MeshStore = class {
   workflowRuns = /* @__PURE__ */ new Map();
   journal = /* @__PURE__ */ new Map();
   contextItems = /* @__PURE__ */ new Map();
+  leases = /* @__PURE__ */ new Map();
   path;
   database;
   agentSequences = /* @__PURE__ */ new Map();
@@ -11950,6 +11990,117 @@ var MeshStore = class {
     }
     return result;
   }
+  /** Read the lease over one already project-scoped resource. */
+  getLease(resource) {
+    if (!this.database) return this.leases.get(resource);
+    const row = this.database.prepare("SELECT record FROM leases WHERE resource = ?").get(resource);
+    if (!row) {
+      this.leases.delete(resource);
+      return void 0;
+    }
+    const lease = parseLeaseRecord(row.record);
+    if (lease) this.leases.set(resource, lease);
+    return lease;
+  }
+  /**
+   * Take or extend the lease over `resource`, deciding the whole outcome inside
+   * one transaction so two writers cannot both read "free" and both insert.
+   *
+   * The token is the fence: a first acquisition starts at 1, the holder's own
+   * re-acquisition keeps its token, and only a takeover of an expired lease
+   * increments it. That is what lets a holder that wakes up after its deadline
+   * be refused at commit rather than silently writing behind the new holder.
+   */
+  acquireLease(input) {
+    return this.inLeaseTransaction(() => {
+      const current = this.readLeaseForUpdate(input.resource);
+      const expired = current !== void 0 && leaseHasLapsed(current, input.nowMs);
+      if (current && !expired && current.holderAgentId !== input.holderAgentId) {
+        return { ok: false, reason: "held", lease: current };
+      }
+      const fencingToken = current === void 0 ? 1 : expired ? current.fencingToken + 1 : current.fencingToken;
+      const renewed = current !== void 0 && !expired;
+      const lease = {
+        resource: input.resource,
+        project: input.project,
+        name: input.name,
+        holderAgentId: input.holderAgentId,
+        holderAgentName: input.holderAgentName,
+        fencingToken,
+        acquiredAt: renewed && current ? current.acquiredAt : new Date(input.nowMs).toISOString(),
+        expiresAt: new Date(input.nowMs + input.ttlMs).toISOString()
+      };
+      this.writeLease(lease);
+      return { ok: true, lease, renewed };
+    });
+  }
+  /** Extend a lease the caller still holds under the token it was given. The
+   * token never changes on renewal — a renewal that would need a new token is
+   * a takeover, and takeovers go through `acquireLease`. */
+  renewLease(input) {
+    return this.inLeaseTransaction(() => {
+      const current = this.readLeaseForUpdate(input.resource);
+      if (!current) return { ok: false, reason: "missing" };
+      if (current.holderAgentId !== input.holderAgentId || current.fencingToken !== input.fencingToken) {
+        return { ok: false, reason: "superseded", lease: current };
+      }
+      if (leaseHasLapsed(current, input.nowMs)) {
+        return { ok: false, reason: "expired", lease: current };
+      }
+      const lease = { ...current, expiresAt: new Date(input.nowMs + input.ttlMs).toISOString() };
+      this.writeLease(lease);
+      return { ok: true, lease, renewed: true };
+    });
+  }
+  /** Drop a lease the caller holds. A clean release ends the fence: there is no
+   * stale writer left to keep a token for, so the next acquisition starts over. */
+  releaseLease(input) {
+    return this.inLeaseTransaction(() => {
+      const current = this.readLeaseForUpdate(input.resource);
+      if (!current) return { ok: false, reason: "missing" };
+      if (current.holderAgentId !== input.holderAgentId || current.fencingToken !== input.fencingToken) {
+        return { ok: false, reason: "superseded", lease: current };
+      }
+      this.deleteLease(input.resource);
+      return { ok: true, lease: current, renewed: false };
+    });
+  }
+  /** Every lease of one project, newest deadline last. Reader surface only. */
+  listLeases(project) {
+    if (this.database) {
+      const rows = this.database.prepare("SELECT record FROM leases").all();
+      this.leases.clear();
+      for (const row of rows) {
+        const lease = parseLeaseRecord(row.record);
+        if (lease) this.leases.set(lease.resource, lease);
+      }
+    }
+    return [...this.leases.values()].filter((lease) => lease.project === project).sort((left, right) => left.resource.localeCompare(right.resource));
+  }
+  inLeaseTransaction(work) {
+    if (!this.database) return work();
+    return withDatabaseTransaction(this.database, work);
+  }
+  readLeaseForUpdate(resource) {
+    if (!this.database) return this.leases.get(resource);
+    const row = this.database.prepare("SELECT record FROM leases WHERE resource = ?").get(resource);
+    return row ? parseLeaseRecord(row.record) : void 0;
+  }
+  writeLease(lease) {
+    this.leases.set(lease.resource, lease);
+    this.database?.prepare(`
+      INSERT INTO leases (resource, holder_agent_id, fencing_token, expires_at, record) VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(resource) DO UPDATE SET
+        holder_agent_id = excluded.holder_agent_id,
+        fencing_token = excluded.fencing_token,
+        expires_at = excluded.expires_at,
+        record = excluded.record
+    `).run(lease.resource, lease.holderAgentId, lease.fencingToken, lease.expiresAt, JSON.stringify(lease));
+  }
+  deleteLease(resource) {
+    this.leases.delete(resource);
+    this.database?.prepare("DELETE FROM leases WHERE resource = ?").run(resource);
+  }
   deleteWorkflowRun(runId) {
     this.workflowRuns.delete(runId);
     this.database?.prepare("DELETE FROM workflow_runs WHERE id = ?").run(runId);
@@ -11970,6 +12121,7 @@ var MeshStore = class {
     const purgedRuns = [];
     const purgedJournal = [];
     const purgedContextItems = [];
+    const purgedLeases = [];
     if (!this.database) {
       for (const m of [...Map.prototype.values.call(this.messages)]) {
         const terminal = m.status === "replied" || m.status === "cancelled" || m.status === "expired" || m.status === "error";
@@ -12040,7 +12192,24 @@ var MeshStore = class {
       this.deleteContextItem(id);
       purgedContextItems.push(id);
     }
-    return { purgedMessages, purgedRuns, purgedJournal, purgedContextItems };
+    const leaseCutoffMs = nowMs - runRetentionMs;
+    for (const lease of this.listAllLeases()) {
+      if (leaseHasLapsed(lease, leaseCutoffMs)) {
+        this.deleteLease(lease.resource);
+        purgedLeases.push(lease);
+      }
+    }
+    return { purgedMessages, purgedRuns, purgedJournal, purgedContextItems, purgedLeases };
+  }
+  listAllLeases() {
+    if (!this.database) return [...this.leases.values()];
+    const rows = this.database.prepare("SELECT record FROM leases").all();
+    const result = [];
+    for (const row of rows) {
+      const lease = parseLeaseRecord(row.record);
+      if (lease) result.push(lease);
+    }
+    return result;
   }
   saveWorkflowRun(run) {
     this.workflowRuns.set(run.id, run);
@@ -12111,6 +12280,7 @@ var MeshStore = class {
     const workflowRows = this.database.prepare("SELECT record FROM workflow_runs").all();
     const journalRows = this.database.prepare("SELECT record FROM workflow_journal").all();
     const contextRows = this.database.prepare("SELECT record FROM context_items").all();
+    const leaseRows = this.database.prepare("SELECT record FROM leases").all();
     for (const row of agentRows) {
       const agent = JSON.parse(row.record);
       this.agents.set(agent.id, agent);
@@ -12127,6 +12297,10 @@ var MeshStore = class {
       const item = JSON.parse(row.record);
       this.contextItems.set(item.id, item);
     }
+    for (const row of leaseRows) {
+      const lease = parseLeaseRecord(row.record);
+      if (lease) this.leases.set(lease.resource, lease);
+    }
   }
 };
 
@@ -12138,13 +12312,40 @@ 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);
 }
+function leaseRefusal(reason, name, lease) {
+  if (reason === "missing") {
+    return new ProtocolError(404, `no lease is held on ${name}`, "lease_not_found");
+  }
+  if (reason === "expired") {
+    return new ProtocolError(
+      409,
+      `lease on ${name} expired at ${lease?.expiresAt ?? "its deadline"}; re-acquire to take it over`,
+      "lease_expired",
+      { lease }
+    );
+  }
+  if (reason === "held") {
+    return new ProtocolError(
+      409,
+      `lease on ${name} is held by ${lease?.holderAgentName ?? "another agent"} until ${lease?.expiresAt ?? "its deadline"}`,
+      "lease_held",
+      { lease }
+    );
+  }
+  return new ProtocolError(
+    409,
+    `fencing token for ${name} was superseded; the hub is now at token ${lease?.fencingToken ?? "a newer value"}`,
+    "lease_superseded",
+    { lease }
+  );
+}
 function bearerToken(request) {
   const header = request.headers.authorization;
   return header?.startsWith("Bearer ") ? header.slice(7) : void 0;
@@ -12367,6 +12568,7 @@ function createMeshHub(options = {}) {
   };
   const webhookWorkflows2 = new Map((options.webhookWorkflows ?? []).map((workflow) => [workflow.id, workflow]));
   const logger = options.logger ?? (() => void 0);
+  const hubNow = options.now ?? (() => Date.now());
   const assetsDir2 = options.assetsDir;
   const hubRepoRoot = options.repoRoot ?? (options.dataPath && options.dataPath !== ":memory:" ? resolve6(dirname5(dirname5(options.dataPath))) : process.cwd());
   const store = new MeshStore(options.dataPath);
@@ -12415,7 +12617,10 @@ function createMeshHub(options = {}) {
     journalEntries: 0,
     contextRequests: 0,
     attemptLatencySecondsTotal: 0,
-    meteredCostUsdTotal: 0
+    meteredCostUsdTotal: 0,
+    leasesGranted: 0,
+    leasesRefused: 0,
+    leasesReleased: 0
   };
   let cleanupTimer;
   let closed = false;
@@ -12560,7 +12765,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 +12816,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");
@@ -12948,6 +13154,16 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
     for (const runId of swept.purgedRuns) {
       logger({ event: "workflow_run_purged", runId });
     }
+    for (const lease of swept.purgedLeases) {
+      logger({
+        event: "lease_purged",
+        resource: lease.resource,
+        project: lease.project,
+        agentId: lease.holderAgentId,
+        fencingToken: lease.fencingToken,
+        expiresAt: lease.expiresAt
+      });
+    }
   }
   function metricsBody() {
     const onlineAgents = [...agents.values()].filter((agent) => agent.online).length;
@@ -12994,6 +13210,12 @@ data: ${JSON.stringify({ type: "ops", project, topic, at: nowIso() })}
       `kxm_attempt_latency_seconds_total ${counters.attemptLatencySecondsTotal}`,
       "# TYPE kxm_metered_cost_usd_total counter",
       `kxm_metered_cost_usd_total ${counters.meteredCostUsdTotal}`,
+      "# TYPE kxm_leases_granted_total counter",
+      `kxm_leases_granted_total ${counters.leasesGranted}`,
+      "# TYPE kxm_leases_refused_total counter",
+      `kxm_leases_refused_total ${counters.leasesRefused}`,
+      "# TYPE kxm_leases_released_total counter",
+      `kxm_leases_released_total ${counters.leasesReleased}`,
       ""
     ].join("\n");
   }
@@ -13912,6 +14134,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 +14161,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 +14190,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\/([^/]+)$/);
@@ -13972,6 +14205,70 @@ data: ${JSON.stringify({ type: "ops", project, topic: "agents", at: nowIso() })}
         response.writeHead(204, { "cache-control": "no-store" }).end();
         return;
       }
+      const leaseMatch = url.pathname.match(/^\/v1\/leases\/([^/]+)\/(acquire|renew|release)$/);
+      if (method === "POST" && leaseMatch) {
+        const holder = requireAgent(request);
+        requireProjectAuth(request, holder.project);
+        const name = requireString(decodeURIComponent(leaseMatch[1]), "resource", { max: MAX_LEASE_RESOURCE_CHARS });
+        const action = leaseMatch[2];
+        const body = await readJson(request);
+        const resource = `${holder.project}/${name}`;
+        const nowMs = hubNow();
+        const leaseLog = { resource, project: holder.project, agentId: holder.id, agentName: holder.name };
+        if (action === "acquire") {
+          const ttlMs = parseBoundedInteger(body.ttlMs, "ttlMs", DEFAULT_LEASE_TTL_MS, MIN_LEASE_TTL_MS, MAX_LEASE_TTL_MS);
+          const outcome2 = store.acquireLease({
+            resource,
+            project: holder.project,
+            name,
+            holderAgentId: holder.id,
+            holderAgentName: holder.name,
+            ttlMs,
+            nowMs
+          });
+          if (!outcome2.ok) {
+            counters.leasesRefused += 1;
+            logger({ event: "lease_denied", ...leaseLog, reason: outcome2.reason, heldBy: outcome2.lease?.holderAgentId });
+            throw leaseRefusal(outcome2.reason, name, outcome2.lease);
+          }
+          counters.leasesGranted += 1;
+          logger({
+            event: outcome2.renewed ? "lease_renewed" : "lease_acquired",
+            ...leaseLog,
+            fencingToken: outcome2.lease.fencingToken,
+            expiresAt: outcome2.lease.expiresAt
+          });
+          json(response, 200, { lease: outcome2.lease, renewed: outcome2.renewed });
+          return;
+        }
+        if (body.fencingToken === void 0) {
+          throw new ProtocolError(400, "fencingToken is required", "lease_token_required");
+        }
+        const fencingToken = parseBoundedInteger(body.fencingToken, "fencingToken", 1, 1, Number.MAX_SAFE_INTEGER);
+        if (action === "renew") {
+          const ttlMs = parseBoundedInteger(body.ttlMs, "ttlMs", DEFAULT_LEASE_TTL_MS, MIN_LEASE_TTL_MS, MAX_LEASE_TTL_MS);
+          const outcome2 = store.renewLease({ resource, holderAgentId: holder.id, fencingToken, ttlMs, nowMs });
+          if (!outcome2.ok) {
+            counters.leasesRefused += 1;
+            logger({ event: "lease_denied", ...leaseLog, reason: outcome2.reason, fencingToken });
+            throw leaseRefusal(outcome2.reason, name, outcome2.lease);
+          }
+          counters.leasesGranted += 1;
+          logger({ event: "lease_renewed", ...leaseLog, fencingToken, expiresAt: outcome2.lease.expiresAt });
+          json(response, 200, { lease: outcome2.lease, renewed: true });
+          return;
+        }
+        const outcome = store.releaseLease({ resource, holderAgentId: holder.id, fencingToken });
+        if (!outcome.ok) {
+          counters.leasesRefused += 1;
+          logger({ event: "lease_denied", ...leaseLog, reason: outcome.reason, fencingToken });
+          throw leaseRefusal(outcome.reason, name, outcome.lease);
+        }
+        counters.leasesReleased += 1;
+        logger({ event: "lease_released", ...leaseLog, fencingToken });
+        json(response, 200, { released: true, lease: outcome.lease });
+        return;
+      }
       if (method === "GET" && url.pathname === "/v1/events") {
         const agentId = requireString(url.searchParams.get("agentId"), "agentId", { max: 80 });
         const current = requireAgent(request, agentId);
@@ -13989,7 +14286,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.72",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm/references/protocol.md

@@ -87,6 +87,24 @@ stored `queued` and delivered once through the reconnect cursor; unknown names
 still return `target_not_found`. Queued messages are not evidence unless
 `workflowContext` was hub-authorized at send.
 
+## Fenced leases
+
+- `POST /v1/leases/:resource/acquire` takes or extends the lease over a
+  resource. Body `{ttlMs}` is bounded to 5 s–10 min. A live lease held by
+  another agent returns `409 lease_held` with the current holder and token.
+- `POST /v1/leases/:resource/renew` extends a lease under the token it was
+  issued. Body `{fencingToken, ttlMs?}`.
+- `POST /v1/leases/:resource/release` gives the resource back. Body
+  `{fencingToken}`.
+
+All three are agent-authenticated and project-scoped: the hub prefixes the
+caller's project onto `:resource`, so the same name in two projects is two
+leases. Every decision is a compare-and-set on the hub clock inside one store
+transaction. The fencing token starts at 1, is unchanged by renewal, and
+increments only when a new holder takes over an expired lease; a stale token
+returns `409 lease_superseded` with the token the hub now holds. Present the
+token before committing anything shared — a refusal means stop, not retry.
+
 ## Request states
 
 - `queued`: stored by the hub but not acknowledged by the recipient.

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 ?? {});