@kontextmind/kxm 0.7.50 → 0.7.52

package/plugins/kxm/src/hub-binding.ts

@@ -7,6 +7,15 @@ export const HUB_HEALTH_PROBE_MS = 300;
 
 export type HubHealth = "on" | "off" | "unknown";
 
+/**
+ * Where a bound hub sits relative to this machine — a trust question, not a cosmetic one.
+ * A loopback URL never puts a bearer on a network; a remote URL means the operator chose
+ * to. `kxm hub bind` therefore refuses a remote URL it cannot authenticate, mirroring the
+ * rule the hub applies to its own listener ("KXM_AUTH_TOKEN is required when binding
+ * beyond localhost").
+ */
+export type HubBindingScope = "loopback" | "remote";
+
 export interface HubBindingRecord {
   schema: typeof HUB_BINDING_SCHEMA;
   url: string;
@@ -62,6 +71,19 @@ export function validateHubUrl(raw: string): string {
   return parsed.href.replace(/\/$/, "");
 }
 
+/** Loopback literals only; `0.0.0.0`, a LAN address or a hostname are all remote. */
+export function hubBindingScope(url: string): HubBindingScope {
+  let host: string;
+  try {
+    host = new URL(url).hostname.toLowerCase();
+  } catch {
+    return "remote";
+  }
+  if (host === "localhost" || host === "::1" || host === "[::1]" || host.endsWith(".localhost")) return "loopback";
+  const v4 = /^127\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})$/.exec(host);
+  return v4 && [v4[1], v4[2], v4[3]].every((part) => Number(part) <= 255) ? "loopback" : "remote";
+}
+
 function isIsoTimestamp(value: string): boolean {
   if (Number.isNaN(Date.parse(value))) return false;
   return value === new Date(value).toISOString();

package/plugins/kxm/src/hub-env.ts

@@ -200,6 +200,34 @@ export function resolveHubCredentials(options: ResolveHubCredentialsOptions = {}
  * matches the credential precedence `kxm hub start` announces, so a hub
  * started fresh (generated token persisted) accepts authenticated client
  * commands without the operator exporting the token. */
+/**
+ * Can this machine authenticate to a hub at all, following the same precedence one-shot
+ * clients use: explicit `KXM_AUTH_TOKEN`, else the persisted record's admin token, else a
+ * persisted **project** token. Read-only on purpose — a refusal has to tell the operator
+ * to configure something, not reveal that the tool quietly configured it for them.
+ *
+ * Pass `project` when the caller knows which project will authenticate. A record holding
+ * only another project's token cannot authorise this one, and a guard that counts it as a
+ * credential stores a binding that will fail exactly like the one it prevented.
+ */
+export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, project?: string): boolean {
+  if (env.KXM_AUTH_TOKEN?.trim()) return true;
+  let record: HubEnvRecord | undefined;
+  try {
+    record = readHubEnvRecord(env);
+  } catch (error) {
+    // A malformed or invalid record is a configuration failure, not "no credential".
+    // Letting it surface as an uncaught throw would print neither JSON nor prose.
+    throw new HubEnvError(
+      `${error instanceof Error ? error.message : String(error)}; refusing to guess a credential — repair or remove ${hubEnvFile(env)}`,
+    );
+  }
+  if (record?.authToken?.trim()) return true;
+  const tokens = record?.projectTokens ?? {};
+  if (project !== undefined) return typeof tokens[project] === "string" && tokens[project].trim().length > 0;
+  return Object.values(tokens).some((token) => typeof token === "string" && token.trim().length > 0);
+}
+
 export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: string): string | undefined {
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;

package/plugins/kxm/src/intake.ts

@@ -98,7 +98,45 @@ const ACTOR_ID_RE = /^.{1,200}$/;
 
 /** Canonical SHA-256 over the authority ceiling — the coordinator's fingerprint. */
 export function kxmCeilingHash(authority: KxmCoordinatorAuthority): string {
-  return `sha256:${createHash("sha256").update(stableStringify(authority), "utf8").digest("hex")}`;
+  return `sha256:${createHash("sha256").update(stableStringify(normalizeAuthority(authority)), "utf8").digest("hex")}`;
+}
+
+/**
+ * Does an already-stored coordinator express this ceiling?
+ *
+ * A row written before set normalisation existed carries a fingerprint that
+ * `kxmCeilingHash` no longer reproduces, so comparing the stored hash alone is
+ * not enough: recompute over the authority it kept. Every path that asks this
+ * question — the initial slot lookup and **both** lost-write read-backs — must
+ * go through here, or an upgrade makes the same row equivalent on lookup and a
+ * `coordinator_write_lost` conflict on the race path.
+ *
+ * A legacy row is returned as stored, so its `ceilingHash` is historical: a
+ * caller must not assume every persisted hash uses today's algorithm.
+ */
+function ceilingsMatch(stored: KxmCoordinatorRecord, ceilingHash: string): boolean {
+  return stored.ceilingHash === ceilingHash || kxmCeilingHash(stored.authority) === ceilingHash;
+}
+
+function normalizeAuthority(authority: KxmCoordinatorAuthority): KxmCoordinatorAuthority {
+  const tools = authority.tools;
+  return {
+    repositoryAccess: authority.repositoryAccess,
+    effects: canonicalSet(authority.effects ?? []),
+    ...(tools !== undefined
+      ? {
+          tools: {
+            ...(tools.preset !== undefined ? { preset: tools.preset } : {}),
+            ...(tools.allow !== undefined ? { allow: canonicalSet(tools.allow) } : {}),
+            ...(tools.deny !== undefined ? { deny: canonicalSet(tools.deny) } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+function canonicalSet(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
 }
 
 /**
@@ -131,7 +169,7 @@ export function bindKxmCoordinator(
 
   if (existing) {
     const current = JSON.parse(existing.record) as KxmCoordinatorRecord;
-    if (current.ceilingHash === ceilingHash) {
+    if (ceilingsMatch(current, ceilingHash)) {
       return { coordinator: current, created: false };
     }
     if (!input.rebind) {
@@ -169,11 +207,11 @@ export function bindKxmCoordinator(
       record: kxmCanonicalJson(record as unknown as JsonValue),
     });
     if (!replaced) {
-      // Another process got the same policy through. Return its identity when it
-      // reached the ceiling we asked for; anything else is a real conflict.
+      // Another process reached the same ceiling first. Return its identity when it
+      // is the ceiling we asked for; anything else is a real conflict.
       const winner = context.eventStore.coordinatorInSlot(context.projectId, role, channel);
       const record2 = winner ? (JSON.parse(winner.record) as KxmCoordinatorRecord) : undefined;
-      if (record2 && record2.ceilingHash === ceilingHash) {
+      if (record2 && ceilingsMatch(record2, ceilingHash)) {
         return { coordinator: record2, created: false };
       }
       throw runtimeError("coordinator_write_lost", existing.coordinatorId, "the coordinator slot changed underneath this rebind");
@@ -196,7 +234,7 @@ export function bindKxmCoordinator(
     configRevision: context.configRevision,
     ceilingHash,
   };
-  return { ...persistCoordinator(context, record), created: true };
+  return persistCoordinator(context, record);
 }
 
 /** Resolve a coordinator by id; unknown identity fails closed. */
@@ -210,10 +248,15 @@ export function resolveKxmCoordinator(context: KxmRuntimeContext, coordinatorId:
  * Accept one internal message at the intake boundary.
  *
  * Duplicate ingress (same idempotency key, same content) returns the original
- * record and cannot create another task. The same key with **different** content
+ * record and cannot produce a second admission record. This layer deduplicates
+ * *intake and admission*; creating a task is the M2 consumer's job, so nothing here can
+ * promise anything about tasks. The same key with **different** content
  * is rejected: a reused key must not smuggle a different payload. Payloads
- * classified `secret` are never persisted — only their hash, so intake cannot
- * become a secret store. While the project is paused the message is durable with
+ * classified `secret` are never persisted — only their hash, so a caller that
+ * classifies honestly gets a store that will not hold that payload. The scope is
+ * exactly that: classification is caller-asserted, so this is a storage decision
+ * under a label, not secret detection, and intake is still not a place to keep
+ * credentials. While the project is paused the message is durable with
  * a held dispatch intent instead of being dropped.
  */
 export function acceptKxmIntakeMessage(
@@ -429,28 +472,45 @@ export function isKxmProjectPaused(context: KxmRuntimeContext): boolean {
   return context.eventStore.projectControl(context.projectId)?.paused === true;
 }
 
+/** How many held rows one drain page reads. Bounds a page, not the whole drain. */
+const INTAKE_DRAIN_PAGE_ROWS = 500;
+
 function releaseHeldIntake(context: KxmRuntimeContext, now: string): KxmIntakeMessage[] {
   const released: KxmIntakeMessage[] = [];
   // Drain every held row. A paging loop, not a single capped page: stranding the
   // 501st message behind a "resume releases held intent" claim is a lie of omission.
-  for (let page = 0; page < 1000; page += 1) {
-    const held = context.eventStore.intakeInStates(context.projectId, ["held_paused"], 500);
-    if (held.length === 0) break;
+  //
+  // What is still true after that fix: the loop holds one write transaction and
+  // retains every released message, so total work and memory grow with the held
+  // backlog even though each read is bounded. Measured on an in-memory store: 150k
+  // held rows with 64-byte payloads took 4.5 s synchronously and ~95 MiB of heap;
+  // 500k maximum-size payloads would retain ~7.6 GiB before any database overhead,
+  // and an allocation failure will not reliably arrive as `intake_drain_stalled`.
+  // Resume is finite because the write lock keeps ingress out of the loop, so this
+  // is a throughput and memory limit, not a correctness hole. Bounding it is a
+  // pre-condition of M2 sustained traffic, not of this contract — see "Still open".
+  for (;;) {
+    const held = context.eventStore.intakeInStates(context.projectId, ["held_paused"], INTAKE_DRAIN_PAGE_ROWS);
+    if (held.length === 0) return released;
+    let progressed = false;
     for (const row of held) {
       const message = JSON.parse(row.record) as KxmIntakeMessage;
       const next: KxmIntakeMessage = { ...message, dispatch: { state: "ready", updatedAt: now } };
       validateIntakeMessage(next, next.messageId);
       if (context.eventStore.updateIntakeDispatch(row.messageId, "held_paused", { state: "ready", record: kxmCanonicalJson(next as unknown as JsonValue) })) {
         released.push(next);
+        progressed = true;
       }
     }
-    const stillHeld = context.eventStore.intakeInStates(context.projectId, ["held_paused"], 1).length;
-    if (stillHeld === 0) break;
+    if (!progressed) {
+      // Cannot move anything: fail loudly inside the caller's transaction, which
+      // rolls the resume back, rather than half-resuming and leaving rows held.
+      throw runtimeError("intake_drain_stalled", context.projectId, `held intake did not drain; ${String(held.length)} row(s) still held`);
+    }
   }
-  return released;
 }
 
-function persistCoordinator(context: KxmRuntimeContext, record: KxmCoordinatorRecord): { coordinator: KxmCoordinatorRecord } {
+function persistCoordinator(context: KxmRuntimeContext, record: KxmCoordinatorRecord): { coordinator: KxmCoordinatorRecord; created: boolean } {
   validateCoordinator(record, record.coordinatorId);
   const inserted = context.eventStore.insertCoordinatorIfAbsent({
     coordinatorId: record.coordinatorId,
@@ -462,13 +522,13 @@ function persistCoordinator(context: KxmRuntimeContext, record: KxmCoordinatorRe
     boundAt: record.boundAt,
     record: kxmCanonicalJson(record as unknown as JsonValue),
   });
-  if (inserted) return { coordinator: record };
+  if (inserted) return { coordinator: record, created: true };
   // Lost the race for an empty slot: binding is create-once, so the winner is the
   // answer whenever it reached the same ceiling. Only a different ceiling is a
-  // conflict worth reporting.
+  // conflict worth reporting. The loser must not report that it created anything.
   const winner = context.eventStore.coordinatorInSlot(record.projectId, record.role, record.channel);
   const won = winner ? (JSON.parse(winner.record) as KxmCoordinatorRecord) : undefined;
-  if (won && won.ceilingHash === record.ceilingHash) return { coordinator: won };
+  if (won && ceilingsMatch(won, record.ceilingHash)) return { coordinator: won, created: false };
   throw runtimeError("coordinator_write_lost", record.coordinatorId, "the coordinator slot was claimed by a different ceiling");
 }
 
@@ -502,6 +562,12 @@ function assertCeilingNotWidened(
     if (newlyAllowed.length > 0) {
       throw runtimeError("coordinator_rebind_widens_tools", coordinatorId, `a rebind may not allow new tools: ${newlyAllowed.join(", ")}`);
     }
+    // Tool evaluation applies no allowlist restriction when the list is empty or
+    // absent (`commands.ts` gates only on a non-empty allow list), so dropping a
+    // populated list is a widening even though every entry it named is gone.
+    if (allowedBefore.size > 0 && (nextTools.allow ?? []).length === 0) {
+      throw runtimeError("coordinator_rebind_clears_allowlist", coordinatorId, "a rebind may not drop or empty a populated allow list; an absent allow list imposes no restriction");
+    }
     const deniedBefore = new Set(previousTools.deny ?? []);
     const undenied = [...deniedBefore].filter((tool) => !(nextTools.deny ?? []).includes(tool));
     if (undenied.length > 0) {
@@ -540,24 +606,9 @@ function validateAuthority(authority: KxmCoordinatorAuthority): KxmCoordinatorAu
   }
   // Sets are stored canonically: order and repeats carry no authority, and leaving
   // them as supplied would let an equivalent ceiling masquerade as a rebind.
-  return {
-    repositoryAccess: authority.repositoryAccess,
-    effects: canonicalSet(effects),
-    ...(tools !== undefined
-      ? {
-          tools: {
-            ...(tools.preset !== undefined ? { preset: tools.preset } : {}),
-            ...(tools.allow !== undefined ? { allow: canonicalSet(tools.allow) } : {}),
-            ...(tools.deny !== undefined ? { deny: canonicalSet(tools.deny) } : {}),
-          },
-        }
-      : {}),
-  };
+  return normalizeAuthority(authority);
 }
 
-function canonicalSet(values: readonly string[]): string[] {
-  return [...new Set(values)].sort();
-}
 
 function validateActor<T extends { kind: KxmCoordinatorRecord["boundBy"]["kind"]; id: string }>(actor: T, field: string): T {
   const kinds: string[] = ["human", "runtime", "hub", "agent", "adapter"];

package/plugins/kxm/src/mcp-server.ts

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.50";
+const VERSION = "0.7.52";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/runtime-store.ts

@@ -1255,7 +1255,14 @@ export class KxmRunEventStore {
     return row ? intakeFromRow(row) : undefined;
   }
 
-  /** Intake rows in the given dispatch states, in arrival order (replay-safe). */
+  /**
+   * Intake rows in the given dispatch states, in arrival order (replay-safe).
+   *
+   * `rowid` gives same-store arrival order, which is what queue priority needs
+   * here. It is **not** a durable sequence: this repository backs stores up with
+   * `VACUUM INTO`, and a vacuum may renumber implicit rowids. An explicit
+   * immutable arrival sequence is tracked in the plan's schema-v6 follow-ups.
+   */
   intakeInStates(projectId: string, states: readonly KxmIntakeMessageRow["dispatchState"][], limit = 100): KxmIntakeMessageRow[] {
     if (states.length === 0) return [];
     const placeholders = states.map(() => "?").join(", ");

package/plugins/kxm/src/session-work.ts

@@ -42,6 +42,8 @@ export interface SessionHubStatus {
   evidence: "probed" | "bound" | "cached" | "unconfigured" | "process" | "timeout";
   online?: boolean;
   url?: string;
+  /** Loopback or remote, so a brief never reads the same on both. */
+  scope?: "loopback" | "remote";
 }
 
 export interface SessionShipStatus {
@@ -65,9 +67,13 @@ export interface SessionBrief {
 }
 
 function hubPrefix(hub?: Partial<SessionHubStatus>): string {
-  if (hub?.state === "on" || (hub?.state === undefined && hub?.online === true)) return "kxm hub:on";
-  if (hub?.state === "off" || (hub?.state === undefined && hub?.online === false)) return "kxm hub:off";
-  if (hub?.state === "unknown") return "kxm hub:unknown";
+  // A remote hub carries a bearer over a network; a loopback one does not. The JSON
+  // said so while every text surface printed the same bytes for both, which is the
+  // distinction an operator actually reads.
+  const suffix = hub?.scope === "remote" ? "/remote" : "";
+  if (hub?.state === "on" || (hub?.state === undefined && hub?.online === true)) return `kxm hub:on${suffix}`;
+  if (hub?.state === "off" || (hub?.state === undefined && hub?.online === false)) return `kxm hub:off${suffix}`;
+  if (hub?.state === "unknown") return `kxm hub:unknown${suffix}`;
   return "kxm";
 }