@kontextmind/kxm 0.7.78 → 0.7.80

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

package/docs/contracts/synchronization.md

@@ -1,8 +1,9 @@
 # Hub synchronization contract
 
 > **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
+> implementation** (cross-host P5): the event store `outbox` (v7, which adds
+> `attempt_count` and the refusal columns named below), 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).
@@ -87,6 +88,12 @@ values. Extensions require a new reviewed schema revision.
 The outbox stores only the already-derived sync object plus retry transport
 metadata. It does not retain the full local source payload for later redaction.
 
+A row sits in exactly one of three states: **pending** (retryable), **acked**
+(the hub holds it), or **refused** (the hub answered in a way that re-sending the
+same bytes cannot change). `refused_code` carries the hub's own code, and it is
+what keeps a permanently unacceptable row from being re-pushed on every tick —
+see Ordering and idempotency.
+
 ## Redaction
 
 Before transformation, the Runtime registers resolved secret values with an
@@ -108,13 +115,34 @@ values MUST NOT be persisted merely to support later redaction.
 - The hub accepts an exact event once by `{projectId, runId, sequence}`.
 - Repeating identical bytes is idempotent.
 - Reusing a sequence with different content is a conflict and security alert.
+- The hub answers **one result per event, in request order**. The Runtime reads the
+  answer at its row's index and verifies the echoed `runId`/`sequence` against the
+  row it claims to describe; an answer that does not describe its row is treated as
+  no answer at all, never as an acknowledgement.
+- The project a Runtime names on the wire MUST be the same identity its sync events
+  carry — the `prj_*` id in `.kxm/project.yaml`. The hub pins a project id to the
+  first hub project that claims it, so a second label on the same facts is refused
+  forever after, not merely once.
 - A gap remains pending until filled or explicitly declared unavailable.
 - Hub projections never invent missing events.
 - A hub acknowledgement advances the outbox cursor; loss before acknowledgement
   causes a safe transport retry.
+- A **durable** refusal — `sync_sequence_reused`, `sync_project_mismatch`,
+  `sync_home_runtime_mismatch`, `sync_event_invalid`, or a row too large to carry —
+  moves that row out of the pending queue with the hub's code, because the next tick
+  would raise the same alert on the same bytes. Nothing is deleted: the row, its
+  code and its attempt count stay until an operator clears the refusal
+  (`kxm runtime sync-retry`) after correcting the hub-side state. Only an operator
+  decides that a refusal has become retryable.
+- A **transient** failure (unreachable hub, refused credential, a batch that
+  isolation could not resolve) leaves every row pending, records the reason, and
+  backs the next attempt off exponentially.
 
 Synchronization delay does not pause local execution except when the next action
-requires a shared-operation lease.
+requires a shared-operation lease. It is never silent either: the supervisor keeps a
+per-project sync state (pending, acked and refused counts, the last failure and when
+the next attempt is due) at `GET /v1/sync/status`, surfaced by `kxm runtime status`
+and logged once per state change.
 
 ## Prompts and evidence on demand
 

package/docs/operations.md

@@ -264,6 +264,7 @@ a backup goes missing while looking complete:
 | `$S/runtime/registry.db` | Runtime registry, including the **supervisor identity and claim row** | which projects this Runtime knows; the claim is a registry row — there is no `supervisor.json` |
 | `$S/runtime/projects/<projectKey>/run-events.db` (+ `-wal`/`-shm`) | event-sourced run state, commands, drives, receipts, gate evidence, intake, coordinators, pause control | run history and every receipt that proves it |
 | `$S/runtime/projects/<projectKey>/run-events.db.run-prompts.json` | prompt text; the sidecar name appends to the **full** database filename | the prompts that explain the runs — restoring databases without sidecars is a partial restore |
+| `$S/runtime/logs/kxm-runtime.jsonl` (+ rotated `.1`…) | the Runtime supervisor's own structured log, including every outbound-sync state change | the supervisor runs detached with no stdio: this file and `GET /v1/sync/status` are its only voice |
 | `$S/projects/<control-root-hash>/repository-bindings.json` | host-local member repository paths | member bindings are host state, outside the project tree |
 | `$S/update.yaml` | release/update configuration consumed by the updater | the box reverts to defaults on the next update path |
 | `$W/pi-sessions/<workerKey>/{default,runs/<runId>}/` | Pi model histories | **optional by existing policy** (see *Workflow-specific Pi sessions*): never a system of record — decide and record, do not silently widen scope |
@@ -449,7 +450,7 @@ holder. `kxm_leases_granted_total`, `kxm_leases_refused_total` and
 ### 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
+`outbox` (event store v7), 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
@@ -467,6 +468,31 @@ 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.
 
+The project on the wire is the project the sync events carry — the `prj_*` id in
+`.kxm/project.yaml`, not the package name. The hub pins a project id to the first
+hub project that claims it, so a Runtime that ever pushed under a second label
+leaves its own later pushes refused; the supervisor's sync status names that
+refusal instead of hiding it.
+
+Two kinds of hub answer come back, and they are not the same thing. A
+**transient** failure (unreachable hub, refused credential) leaves every row
+pending, records the reason and backs the next attempt off exponentially. A
+**durable** refusal (`sync_sequence_reused`, `sync_project_mismatch`,
+`sync_home_runtime_mismatch`, `sync_event_invalid`, a row too large to carry)
+takes *that row* out of the pending queue with the hub's code, so one row the hub
+will never accept can neither block the rows behind it nor re-alert the hub every
+ten seconds. Refused rows are not deleted: `kxm runtime sync-retry` re-queues them
+once the hub-side state is corrected, and only an operator decides that a refusal
+has become retryable.
+
+`kxm runtime status` prints what the tick last saw per project — `ok`, `no_hub`,
+`blocked` or `refusing`, with pending/acked/refused counts, the refusal codes, the
+last failure and the next attempt — read from the supervisor's
+`GET /v1/sync/status`. The same transitions are logged to
+`$S/runtime/logs/kxm-runtime.jsonl` (`runtime_sync_state`,
+`runtime_sync_stalled`), one line per change: the supervisor runs detached with no
+stdio, so that file and that endpoint are its only voice.
+
 `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.78",
+  "version": "0.7.80",
   "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.78",
+  "version": "0.7.80",
   "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

@@ -23980,20 +23980,30 @@ function restoreDatabaseFile(backupPath, targetPath, storeId, expectedSchemaVers
     integrity: "ok"
   };
 }
+var KXM_BACKUP_CEILINGS = {
+  "hub-store": 5,
+  registry: 1,
+  "binding-store": 1,
+  events: 7
+};
+function kxmBackupCeiling(storeId) {
+  if (storeId.startsWith("events:")) return KXM_BACKUP_CEILINGS.events;
+  return KXM_BACKUP_CEILINGS[storeId] ?? KXM_BACKUP_CEILINGS["hub-store"];
+}
 function discoverProjectStores(projectRoot, options = {}) {
   const root = resolve5(projectRoot);
   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: 5 });
+    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: kxmBackupCeiling("hub-store") });
   }
   const registryPath = join8(root, ".kxm", "runtime", "registry.db");
   if (existsSync8(registryPath)) {
-    stores.push({ storeId: "registry", sourcePath: registryPath, maxSupportedVersion: 1 });
+    stores.push({ storeId: "registry", sourcePath: registryPath, maxSupportedVersion: kxmBackupCeiling("registry") });
   }
   const bindingsPath = join8(root, ".kxm", "runtime", "bindings.db");
   if (existsSync8(bindingsPath)) {
-    stores.push({ storeId: "binding-store", sourcePath: bindingsPath, maxSupportedVersion: 1 });
+    stores.push({ storeId: "binding-store", sourcePath: bindingsPath, maxSupportedVersion: kxmBackupCeiling("binding-store") });
   }
   const eventsDir = join8(root, ".kxm", "runtime", "events");
   if (existsSync8(eventsDir)) {
@@ -24004,7 +24014,7 @@ function discoverProjectStores(projectRoot, options = {}) {
         stores.push({
           storeId: `events:${key}`,
           sourcePath: join8(eventsDir, entry.name),
-          maxSupportedVersion: 6
+          maxSupportedVersion: kxmBackupCeiling(`events:${key}`)
         });
       }
     }
@@ -24091,12 +24101,7 @@ function restoreBackup(manifestPathOrDir, options = {}) {
         `backup file ${store.backupFile} sha256 ${actualSha256} does not match manifest hash ${store.sha256}`
       );
     }
-    let maxSupported = 5;
-    if (store.storeId === "registry" || store.storeId === "binding-store") {
-      maxSupported = 1;
-    } else if (store.storeId.startsWith("events:")) {
-      maxSupported = 6;
-    }
+    const maxSupported = kxmBackupCeiling(store.storeId);
     let targetPath = store.sourcePath;
     if (options.projectRoot && manifest.projectRoot && targetPath.startsWith(manifest.projectRoot)) {
       const rel = targetPath.slice(manifest.projectRoot.length).replace(/^[\\/]+/, "");
@@ -24449,7 +24454,17 @@ var EVENT_STORE_TABLES = {
     "record"
   ],
   project_controls: ["project_id", "paused", "reason", "updated_at", "actor", "schema", "record"],
-  outbox: ["seq", "run_id", "sequence", "sync_event", "attempted_at", "acked_at"]
+  outbox: [
+    "seq",
+    "run_id",
+    "sequence",
+    "sync_event",
+    "attempted_at",
+    "attempt_count",
+    "acked_at",
+    "refused_code",
+    "refused_at"
+  ]
 };
 var KXM_EVENT_STORE_TABLE_NAMES = Object.keys(EVENT_STORE_TABLES).sort();
 
@@ -25970,6 +25985,9 @@ async function probeHubHealth(url, fetchImpl, timeoutMs = HUB_HEALTH_PROBE_MS) {
   }
 }
 
+// plugins/kxm/src/logger.ts
+var DEFAULT_LOG_MAX_BYTES = 10 * 1024 * 1024;
+
 // plugins/kxm/src/runtime-supervisor.ts
 function kxmSupervisorTokenFile(paths) {
   return join13(paths.runtimeDir, "supervisor.token");
@@ -26117,6 +26135,7 @@ async function ensureKxmSupervisor(options = {}) {
   }
   throw runtimeError("runtime_supervisor_start_failed", scriptPath, `runtime supervisor (pid ${pid}) did not become ready in time`);
 }
+var RUNTIME_SYNC_MAX_BACKOFF_MS = 5 * 6e4;
 async function kxmRuntimeRequest(handle, method, path4, body) {
   const response = await fetch(`http://127.0.0.1:${handle.port}${path4}`, {
     method,
@@ -32758,9 +32777,32 @@ async function cmdKxmRuntime(runtime, action) {
     }
     if (action === "status") {
       const status = kxmSupervisorStatus(paths);
-      print(runtime.io, runtime.json, { ok: true, command: "runtime status", ...status }, status.running ? `runtime supervisor running: ${status.runtimeId} pid ${status.pid} on 127.0.0.1:${status.port}` : "runtime supervisor is not running");
+      const sync = status.running ? await readKxmSupervisorSync(runtime) : void 0;
+      print(runtime.io, runtime.json, { ok: true, command: "runtime status", ...status, ...sync ? { sync } : {} }, [
+        status.running ? `runtime supervisor running: ${status.runtimeId} pid ${status.pid} on 127.0.0.1:${status.port}` : "runtime supervisor is not running",
+        ...formatKxmSyncStatus(sync)
+      ].join("\n"));
       return status.running ? 0 : 1;
     }
+    if (action === "sync-retry") {
+      const supervisor = await attachKxmSupervisor({ env: runtime.env });
+      if (!supervisor) {
+        print(runtime.io, runtime.json, { ok: false, command: "runtime sync-retry", error: "runtime_not_running" }, "runtime supervisor is not running");
+        return 1;
+      }
+      const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+      if (!projectRoot) {
+        print(runtime.io, runtime.json, { ok: false, command: "runtime sync-retry", error: "project_required" }, "kxm runtime sync-retry requires a KXM project (run kxm init first)");
+        return 1;
+      }
+      if (runtime.dryRun) {
+        print(runtime.io, runtime.json, { ok: true, command: "runtime sync-retry", projectRoot, dryRun: true }, "would re-queue rows the hub durably refused");
+        return 0;
+      }
+      const result = await kxmRuntimeRequest(supervisor, "POST", "/v1/sync/retry", { projectRoot });
+      print(runtime.io, runtime.json, { ok: true, command: "runtime sync-retry", ...result }, `re-queued ${String(result.retried ?? 0)} refused outbox rows for ${String(result.projectId ?? projectRoot)}`);
+      return 0;
+    }
     if (action === "stop") {
       const status = kxmSupervisorStatus(paths);
       if (!status.running || !status.port) {
@@ -32787,6 +32829,26 @@ async function cmdKxmRuntime(runtime, action) {
     return 1;
   }
 }
+async function readKxmSupervisorSync(runtime) {
+  const supervisor = await attachKxmSupervisor({ env: runtime.env });
+  if (!supervisor) return void 0;
+  try {
+    const response = await kxmRuntimeRequest(supervisor, "GET", "/v1/sync/status");
+    return response.projects;
+  } catch {
+    return void 0;
+  }
+}
+function formatKxmSyncStatus(sync) {
+  if (sync === void 0) return ["sync: the supervisor did not answer /v1/sync/status"];
+  if (sync.length === 0) return ["sync: no project registered with this Runtime yet"];
+  return sync.map((project) => {
+    const codes = project.outbox.refusals.map((refusal) => `${refusal.code} x${refusal.count}`).join(", ");
+    const counts = `pending ${project.outbox.pending}, acked ${project.outbox.acked}, refused ${project.outbox.refused}`;
+    const tail = project.state === "refusing" ? ` (${codes || "see log"}) \u2014 fix the hub, then: kxm runtime sync-retry` : project.state === "blocked" ? ` \u2014 last error: ${project.lastError ?? "unreachable"}${project.nextAttemptAt ? `; next attempt ${project.nextAttemptAt}` : ""}` : "";
+    return `sync ${project.projectId}: ${project.state} (${counts})${tail}`;
+  });
+}
 async function cmdKxmRunReceipt(runtime, runId, options = {}) {
   try {
     const projectRoot = discoverKxmProjectRoot(runtime.cwd);
@@ -47847,6 +47909,9 @@ function createProgram(ctx, result) {
   addGlobalOptions(runtimeCmd.command("status").description("Show Runtime supervisor liveness")).action(async function runtimeStatusAction() {
     result.code = await cmdKxmRuntime(runtimeFrom(ctx, this), "status");
   });
+  addGlobalOptions(runtimeCmd.command("sync-retry").description("Re-queue outbox rows the hub durably refused, after the hub-side state is corrected")).action(async function runtimeSyncRetryAction() {
+    result.code = await cmdKxmRuntime(runtimeFrom(ctx, this), "sync-retry");
+  });
   addGlobalOptions(runtimeCmd.command("stop").description("Gracefully stop the Runtime supervisor")).action(async function runtimeStopAction() {
     result.code = await cmdKxmRuntime(runtimeFrom(ctx, this), "stop");
   });

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

@@ -17182,7 +17182,7 @@ async function deliverInboxNotification(messageId, delivered, notify) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.78";
+var VERSION = "0.7.80";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
 var meshClient;