@kontextmind/kxm 0.7.71 → 0.7.73

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.73",
       "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/contracts/synchronization.md

@@ -1,8 +1,11 @@
 # Hub synchronization contract
 
-> **Status.** `kxm.sync-event.v1` is a **schema-tested contract**. There is no
-> outbox table, sync transform, or hub ingestion in source. Implementation
-> begins in [Phase 8](../../plans/implementation-plan.md#phase-8-multi-project-hub-kxm).
+> **Status.** `kxm.sync-event.v1` is a **schema-tested contract with an
+> implementation** (cross-host P5): the event store `outbox` (v6), the
+> `sync-transform.ts` derivation under the default policy, supervisor push to
+> `POST /v1/sync/events`, and hub ingestion into `sync_events` (hub store v5).
+> Custom project policies and on-demand content transfer remain unimplemented.
+> Phase 8 gate: [implementation plan](../../plans/implementation-plan.md#phase-8-multi-project-hub-kxm).
 
 Synchronization is summary-first, project-scoped, at-least-once, and
 allowlist-based. The full local event is never placed directly in the outbox.

package/docs/operations.md

@@ -315,7 +315,11 @@ 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 v5 and event store v6** as of the sync-outbox release: a backup taken by
+   an earlier build records hub v4 or event store v5 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 +396,11 @@ 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 5) carries `context_items`, `leases`,
+`sync_events` and `runtime_presence` 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 +417,64 @@ 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.
+
+### Runtime → hub run-fact sync
+
+Every event the Runtime commits also writes one row to the event store's
+`outbox` (event store v6), in the same transaction. The row holds only a derived
+`kxm.sync-event.v1` object — allowlisted fields, registered secret values and
+credential shapes replaced, absolute paths removed, text bounded, the default
+sync policy revision recorded — never the local event. A field the allowlist
+does not name is listed by name in `redaction.fieldsOmitted` and its value is
+dropped.
+
+The supervisor pushes outbound only: every `KXM_RUNTIME_SYNC_INTERVAL_MS` (10 s
+by default) it posts `POST /v1/runtime/presence` for each open project, then
+`POST /v1/sync/events` in outbox order, to `KXM_SERVER_URL` or the `kxm hub bind`
+URL with that project's token. No bound hub means nothing is sent and rows stay
+pending; local execution never waits on sync. The hub accepts each event once by
+`{projectId, runId, sequence}`: the same bytes again are an idempotent
+`duplicate`; different bytes under a used sequence, a run claimed by another
+project, or a push for another Runtime's events are refused and logged as
+`security_alert`. Out-of-order events are held, and the per-run cursor is the
+gapless prefix, so a gap stays pending until it is filled.
+
+`GET /v1/ops/snapshot` adds `homeRuntimes`: synchronized runs grouped by home
+Runtime, each with its bounded title/status, `lastSequence`, `pendingGap`, and
+`orphaned` once the Runtime's presence lease (`heartbeatAt + staleAfterMs`, hub
+clock) has lapsed. Orphaned is view state; nothing is migrated.
+`kxm_sync_events_accepted_total`, `kxm_sync_events_duplicate_total`,
+`kxm_sync_events_refused_total`, `kxm_sync_conflicts_total` and
+`kxm_runtime_heartbeats_total` are in `/metrics`.
+
 ## 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.73",
   "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.73",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",