@kontextmind/kxm 0.7.71 → 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.71",
+      "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.71",
+  "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.71",
+  "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

@@ -18360,6 +18360,8 @@ 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;
@@ -19396,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;
@@ -19589,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}`),
@@ -23862,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)) {
@@ -23968,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:")) {
@@ -42603,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";

package/plugins/kxm/dist/client.js

@@ -8,6 +8,8 @@ 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) {
@@ -219,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;
@@ -412,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

@@ -13,6 +13,10 @@ 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;
@@ -2017,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,
@@ -2031,9 +2036,12 @@ export {
   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,

package/plugins/kxm/dist/extension.js

@@ -14543,6 +14543,8 @@ 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;
+var MAX_LEASE_TTL_MS = 10 * 6e4;
+var DEFAULT_LEASE_TTL_MS = 5 * 6e4;
 
 // plugins/kxm/src/workflow.ts
 function canonicalWorkflowEvidenceKey(value) {
@@ -14754,6 +14756,37 @@ var HubClient = class {
     );
     return result2.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 result2 = await this.request("/v1/workflows");
     return result2.runs;
@@ -14947,6 +14980,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/mcp-server.js

@@ -15763,6 +15763,8 @@ 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) {
@@ -15974,6 +15976,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;
@@ -16167,6 +16200,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}`),
@@ -17145,7 +17179,7 @@ async function deliverInboxNotification(messageId, delivered, notify) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.71";
+var VERSION = "0.7.72";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
 var meshClient;

package/plugins/kxm/dist/runtime.js

@@ -17989,7 +17989,7 @@ function discoverProjectStores(projectRoot, options = {}) {
   const stores = [];
   const hubPath = options.hubDataPath ? resolve3(options.hubDataPath) : join4(root, ".kxm", "state", "kxm.db");
   if (existsSync4(hubPath)) {
-    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: 3 });
+    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: 4 });
   }
   const registryPath = join4(root, ".kxm", "runtime", "registry.db");
   if (existsSync4(registryPath)) {
@@ -18095,7 +18095,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:")) {
@@ -28684,6 +28684,8 @@ 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_LEASE_TTL_MS = 10 * 6e4;
+var DEFAULT_LEASE_TTL_MS = 5 * 6e4;
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }