@kontextmind/kxm 0.7.70 → 0.7.72

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

package/CHANGELOG.md

@@ -6,6 +6,21 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **Fenced hub leases, and shared external effects that will not run without one.**
+  `POST /v1/leases/:resource/acquire|renew|release` are agent-authenticated and
+  project-scoped (the hub prefixes the caller's project onto the resource name). Each call
+  is a compare-and-set inside one store transaction on the **hub clock**, with TTLs bounded
+  to 5 s–10 min. The fencing token starts at 1, survives renewal unchanged, and increments
+  only when a new holder takes over an expired lease, so a holder that returns after its
+  deadline is told its token was superseded instead of writing behind its replacement.
+  Shared external effects (`git-push` to a ref the run does not own, `pr-create`,
+  `tracker-issue`, `webhook`) acquire a lease keyed by `targetRef` before executing, record
+  `{leaseResource, fencingToken}` in the receipt, renew on the existing Q6 heartbeat, and
+  re-present the token at commit; a superseded token leaves the effect `in-flight` and the
+  attempt `blocked_uncertain` with nothing retrying. An unreachable hub refuses the effect
+  (`effect_lease_unavailable`) rather than executing it unfenced. Unique-namespace kinds
+  (`git-branch`, `git-commit`, and a push to the run's own branch) stay lease-free.
+
 - **`kxm peer send --allow-offline` queues to a registered offline peer.**
   `POST /v1/messages` accepts `allowOffline: true` (also `kxm_send.allowOffline`): a
   registered agent in the same project is stored `queued` instead of `target_not_found`,
@@ -42,6 +57,13 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Hub store schema v3 → v4, external-effects ledger v1 → v2.** The hub store gains a
+  `leases` table and the ledger gains `lease_resource`/`fencing_token` columns. Neither has
+  a migration lane: an older file is refused at open with `runtime_schema_outdated`, and the
+  hub backup/restore ceiling in `database.ts` moves to 4 with the bump, so a v3 backup must
+  be restored with the release that produced it. Delete the state file to start fresh and
+  let `kxm hub start` recreate it.
+
 - **`kxm tenant status`: one composed read for the portal, with the authorities labelled.**
   The portal needs hub metadata (roster, message queue, the hub's run projection) *and* the
   Runtime's authoritative run state, and the failure mode S2 exists to prevent is rendering

package/docs/operations.md

@@ -315,7 +315,10 @@ restore lands somewhere the running service will not look.
    copies, not the file copy**: configuration, repository bindings, prompt sidecars,
    routing manifests and update configuration are not databases, so a snapshot-only backup
    reproduces exactly the failure this section exists to remove. The hub's own backup path already writes a hashed manifest and records
-   a schema version ceiling; keep that manifest with the files.
+   a schema version ceiling; keep that manifest with the files. That ceiling is
+   **hub store v4** as of the fenced-lease release: a backup taken by an earlier
+   build records v3 and is refused by this one, because there is no migration lane.
+   Restore such a backup with the release that produced it, or start fresh.
 3. Record the package version, configuration revision and schema versions beside the copy.
    A restore that cannot state which release produced it is not a restore path.
 4. Keep at least one rotation, and bound retention explicitly — run events and prompt
@@ -392,10 +395,10 @@ Broader deployments need shared state and coordination, external identity and fi
 
 ## v0.5 context/state storage
 
-The hub database (schema version 3) carries `context_items` alongside
-agents, messages, workflow runs, and the journal. Temporal state, knowledge
-records, and their audit trails live in the same SQLite file and upgrade in
-place from v0.4 databases.
+The hub database (schema version 4) carries `context_items` and `leases`
+alongside agents, messages, workflow runs, and the journal. Temporal state,
+knowledge records, and their audit trails live in the same SQLite file and
+upgrade in place from v0.4 databases.
 
 - **Backup and restore**: include the hub database file and, if used, the
   `.kxm/skills/` and `.kxm/knowledge/` trees. The wiki is a compiled view and
@@ -412,6 +415,35 @@ place from v0.4 databases.
   to open on an older runtime). Restore a database backup taken before the
   upgrade instead.
 
+### Fenced leases over shared resources
+
+`leases` holds one row per project-scoped resource: the holder, a monotonic
+fencing token, and a deadline. `POST /v1/leases/:resource/acquire|renew|release`
+are agent-authenticated and scoped to the caller's project, which the hub
+prefixes onto the resource name — two projects naming the same branch never
+contend. TTLs are bounded to 5 s–10 min and every decision is made on the **hub
+clock** inside one store transaction, so a skewed client cannot extend its own
+grip.
+
+The token is the safety property. It starts at 1, stays put across renewals, and
+increments only when a new holder takes over an expired lease. A holder that
+comes back after its deadline is therefore told its token was superseded rather
+than allowed to write behind whoever replaced it. Shared external effects
+(`git-push` to a ref the run does not own, `pr-create`, `tracker-issue`,
+`webhook`) take a lease before executing and re-present the token at commit; a
+superseded token leaves the effect `in-flight` and the attempt
+`blocked_uncertain` for an operator to resolve, and nothing retries it. An
+unreachable hub refuses the effect (`effect_lease_unavailable`) rather than
+running it unfenced.
+
+Expired rows are **not** reaped immediately — their token is what the next
+takeover has to increment past. The retention sweep drops rows whose deadline is
+older than the run-retention window (7 days by default), far beyond any live
+holder. `kxm_leases_granted_total`, `kxm_leases_refused_total` and
+`kxm_leases_released_total` in `/metrics` report contention;
+`lease_acquired`, `lease_renewed`, `lease_released`, `lease_denied` and
+`lease_purged` are the structured log events.
+
 ## Hub Q&A / knowledge base
 
 - [What is all stored on the hub?](kb/qa-what-the-hub-stores.md)

package/docs/test-matrix.md

@@ -23,6 +23,7 @@ npm run verify
 | Queue, acknowledgement, visibility, reply, and authorization | `test/core/hub-api.test.ts`, `test/core/hub.test.ts` |
 | Queued/delivered replay after recipient restart reuses one message record | `test/core/hub.test.ts`, `test/core/extension.test.ts`, `test/core/mcp.test.ts` |
 | Known-offline peer send with `allowOffline` queues, delivers once on resumption, and expires unread by TTL | `test/core/hub-api.test.ts` |
+| Fenced hub leases: CAS acquire/renew/release, monotonic token on takeover only, hub-clocked expiry, and a shared external effect refused at commit under a superseded token | `test/core/hub-api.test.ts`, `test/core/store.test.ts`, `test/core/external-effects.test.ts` |
 | One-to-three-peer fanout, recoverable local timeouts/aborts, exact retries, and partial-error collection | `test/core/client.test.ts`, `test/core/hub-api.test.ts`, `test/core/extension.test.ts`, `test/core/mcp.test.ts` |
 | TTL expiry, sender cancellation, and terminal retention | `test/core/hub-api.test.ts` |
 | Terminal inbound cleanup and next-request activation | `test/core/extension.test.ts`, `test/core/mcp.test.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.70",
+  "version": "0.7.72",
   "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.72",
   "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,9 @@ 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 MAX_LEASE_TTL_MS = 10 * 6e4;
+var DEFAULT_LEASE_TTL_MS = 5 * 6e4;
 var ProtocolError = class extends Error {
   statusCode;
   code;
@@ -18453,6 +18454,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 +19202,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 +19298,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) {
@@ -19386,6 +19398,37 @@ var HubClient = class {
     );
     return result.message;
   }
+  // ----- Fenced leases over shared resources (P3) -----
+  /**
+   * Take or extend the lease over `resource` inside this client's project.
+   *
+   * The returned `fencingToken` is the whole point: hold it, present it on every
+   * renewal, and present it again before committing anything shared. A hub that
+   * has moved past it refuses, and the caller must stop rather than retry —
+   * another holder owns the resource now. Rejects `HubHttpError` with code
+   * `lease_held` when a live holder has it.
+   */
+  async acquireLease(resource, ttlMs) {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/acquire`, {
+      method: "POST",
+      body: JSON.stringify(ttlMs === void 0 ? {} : { ttlMs })
+    });
+  }
+  /** Extend a lease this client holds. The token never changes on renewal; a
+   * `lease_superseded` or `lease_expired` refusal means it is gone. */
+  async renewLease(resource, fencingToken, ttlMs) {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/renew`, {
+      method: "POST",
+      body: JSON.stringify(ttlMs === void 0 ? { fencingToken } : { fencingToken, ttlMs })
+    });
+  }
+  /** Give the resource back. */
+  async releaseLease(resource, fencingToken) {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/release`, {
+      method: "POST",
+      body: JSON.stringify({ fencingToken })
+    });
+  }
   async listWorkflows() {
     const result = await this.request("/v1/workflows");
     return result.runs;
@@ -19530,7 +19573,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;
@@ -19578,6 +19622,7 @@ var HubClient = class {
       for (const key of ["operation", "nextAction", "assignedCoordinatorName"]) {
         if (typeof body[key] === "string") extras[key] = body[key];
       }
+      if (body.lease && typeof body.lease === "object") extras.lease = body.lease;
       throw new HubHttpError(
         response.status,
         String(body.error ?? `HTTP ${response.status}`),
@@ -19770,14 +19815,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 }) };
     }
   },
   {
@@ -23846,7 +23896,7 @@ function discoverProjectStores(projectRoot, options = {}) {
   const stores = [];
   const hubPath = options.hubDataPath ? resolve5(options.hubDataPath) : join8(root, ".kxm", "state", "kxm.db");
   if (existsSync8(hubPath)) {
-    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: 3 });
+    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: 4 });
   }
   const registryPath = join8(root, ".kxm", "runtime", "registry.db");
   if (existsSync8(registryPath)) {
@@ -23952,7 +24002,7 @@ function restoreBackup(manifestPathOrDir, options = {}) {
         `backup file ${store.backupFile} sha256 ${actualSha256} does not match manifest hash ${store.sha256}`
       );
     }
-    let maxSupported = 3;
+    let maxSupported = 4;
     if (store.storeId === "registry" || store.storeId === "binding-store") {
       maxSupported = 1;
     } else if (store.storeId.startsWith("events:")) {
@@ -26188,8 +26238,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";
@@ -42587,6 +42637,12 @@ function slugifyBranchPart(text, maxLength = 40) {
   if (cleaned.length <= maxLength) return cleaned;
   return cleaned.slice(0, maxLength).replace(/-+$/, "");
 }
+var SHARED_EFFECT_KINDS = Object.freeze([
+  "git-push",
+  "pr-create",
+  "tracker-issue",
+  "webhook"
+]);
 
 // plugins/kxm/src/local-snapshot.ts
 import { existsSync as existsSync26, readdirSync as readdirSync11, readFileSync as readFileSync26 } from "node:fs";
@@ -43087,6 +43143,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 +43200,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 +43238,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 +43550,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 +47808,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,15 @@
 // 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;
+var MAX_LEASE_TTL_MS = 10 * 6e4;
+var DEFAULT_LEASE_TTL_MS = 5 * 6e4;
 
 // plugins/kxm/src/workflow.ts
 function canonicalWorkflowEvidenceKey(value) {
@@ -21,6 +25,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 +121,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) {
@@ -207,6 +221,37 @@ var HubClient = class {
     );
     return result.message;
   }
+  // ----- Fenced leases over shared resources (P3) -----
+  /**
+   * Take or extend the lease over `resource` inside this client's project.
+   *
+   * The returned `fencingToken` is the whole point: hold it, present it on every
+   * renewal, and present it again before committing anything shared. A hub that
+   * has moved past it refuses, and the caller must stop rather than retry —
+   * another holder owns the resource now. Rejects `HubHttpError` with code
+   * `lease_held` when a live holder has it.
+   */
+  async acquireLease(resource, ttlMs) {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/acquire`, {
+      method: "POST",
+      body: JSON.stringify(ttlMs === void 0 ? {} : { ttlMs })
+    });
+  }
+  /** Extend a lease this client holds. The token never changes on renewal; a
+   * `lease_superseded` or `lease_expired` refusal means it is gone. */
+  async renewLease(resource, fencingToken, ttlMs) {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/renew`, {
+      method: "POST",
+      body: JSON.stringify(ttlMs === void 0 ? { fencingToken } : { fencingToken, ttlMs })
+    });
+  }
+  /** Give the resource back. */
+  async releaseLease(resource, fencingToken) {
+    return await this.request(`/v1/leases/${encodeURIComponent(resource)}/release`, {
+      method: "POST",
+      body: JSON.stringify({ fencingToken })
+    });
+  }
   async listWorkflows() {
     const result = await this.request("/v1/workflows");
     return result.runs;
@@ -351,7 +396,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;
@@ -399,6 +445,7 @@ var HubClient = class {
       for (const key of ["operation", "nextAction", "assignedCoordinatorName"]) {
         if (typeof body[key] === "string") extras[key] = body[key];
       }
+      if (body.lease && typeof body.lease === "object") extras.lease = body.lease;
       throw new HubHttpError(
         response.status,
         String(body.error ?? `HTTP ${response.status}`),

package/plugins/kxm/dist/core.js

@@ -12,6 +12,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;
@@ -945,14 +960,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 }) };
     }
   },
   {
@@ -2001,6 +2021,7 @@ export {
   AGENT_COMMANDS,
   AGENT_COMMANDS_MAP,
   BEHAVIORAL_HASH_VERSION,
+  DEFAULT_LEASE_TTL_MS,
   DEFAULT_LOG_MAX_BYTES,
   DEFAULT_LOG_MAX_FILES,
   DEFAULT_MAX_HOPS,
@@ -2011,12 +2032,16 @@ 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,
+  MAX_LEASE_RESOURCE_CHARS,
+  MAX_LEASE_TTL_MS,
   MAX_MESSAGE_TTL_MS,
   MAX_PROVIDER_METADATA_FIELDS,
   MAX_SKILL_REFS,
+  MIN_LEASE_TTL_MS,
   MIN_MESSAGE_RETENTION_MS,
   MIN_MESSAGE_TTL_MS,
   ProtocolError,
@@ -2026,6 +2051,7 @@ export {
   TERMINAL_RECEIPT_SCHEMA,
   WORKER_RESULT_SCHEMA,
   WORKER_SCHEMA,
+  agentPresenceView,
   agentWorker,
   behavioralConfigHash,
   clearSessionTokenFromDisk,
@@ -2066,6 +2092,7 @@ export {
   rotateLogFiles,
   sessionTokenPath,
   timingSafeStringCompare,
+  toAgentRecord,
   validateTerminalReceipt,
   workerResult
 };