@kontextmind/kxm 0.7.51 → 0.7.53

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

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

package/plugins/kxm/dist/runtime-supervisor.js

@@ -17612,20 +17612,11 @@ function openDatabase(file, description, spec) {
       database.exec(spec.schema);
       database.exec(`PRAGMA user_version = ${spec.version}`);
     } else if (version < spec.version) {
-      let currentVersion = version;
-      while (currentVersion < spec.version) {
-        const step = spec.migrations?.find((m) => m.fromVersion === currentVersion);
-        if (!step) {
-          throw databaseError(
-            "runtime_schema_outdated",
-            file,
-            `${description} schema version ${version} is older than ${spec.version}; no migration lane, backup and restore remain E6`
-          );
-        }
-        step.migrate(database);
-        currentVersion = step.toVersion;
-        database.exec(`PRAGMA user_version = ${currentVersion}`);
-      }
+      throw databaseError(
+        "runtime_schema_outdated",
+        file,
+        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file (or re-run \`kxm init\`) to start fresh \u2014 upgrading old state in place is deliberately unsupported`
+      );
     }
     if (spec.tables) {
       verifyExpectedTables(database, file, description, spec.tables);
@@ -18270,71 +18261,6 @@ CREATE TABLE project_controls (
   record TEXT NOT NULL
 ) STRICT;
 `;
-var COORDINATOR_INTAKE_DDL = `
-CREATE TABLE IF NOT EXISTS coordinators (
-  coordinator_id TEXT PRIMARY KEY,
-  project_id TEXT NOT NULL,
-  role TEXT NOT NULL,
-  channel TEXT NOT NULL,
-  ceiling_hash TEXT NOT NULL,
-  config_revision TEXT NOT NULL,
-  bound_at TEXT NOT NULL,
-  schema TEXT NOT NULL,
-  record TEXT NOT NULL
-) STRICT;
-CREATE UNIQUE INDEX IF NOT EXISTS coordinators_slot ON coordinators(project_id, role, channel);
-CREATE TABLE IF NOT EXISTS intake_messages (
-  message_id TEXT PRIMARY KEY,
-  project_id TEXT NOT NULL,
-  coordinator_id TEXT NOT NULL,
-  idempotency_key TEXT NOT NULL,
-  content_hash TEXT NOT NULL,
-  received_at TEXT NOT NULL,
-  dispatch_state TEXT NOT NULL CHECK (dispatch_state IN ('ready','held_paused','admitted','refused')),
-  schema TEXT NOT NULL,
-  record TEXT NOT NULL
-) STRICT;
-CREATE UNIQUE INDEX IF NOT EXISTS intake_idempotency ON intake_messages(project_id, coordinator_id, idempotency_key);
-CREATE INDEX IF NOT EXISTS intake_dispatch ON intake_messages(project_id, dispatch_state, received_at, message_id);
-CREATE TABLE IF NOT EXISTS project_controls (
-  project_id TEXT PRIMARY KEY,
-  paused INTEGER NOT NULL CHECK (paused IN (0, 1)),
-  reason TEXT,
-  updated_at TEXT NOT NULL,
-  actor TEXT NOT NULL,
-  schema TEXT NOT NULL,
-  record TEXT NOT NULL
-) STRICT;
-`;
-var DRIVE_RECEIPTS_DDL = `
-CREATE TABLE IF NOT EXISTS drive_receipts (
-  drive_id TEXT PRIMARY KEY,
-  run_id TEXT NOT NULL,
-  project_id TEXT NOT NULL,
-  opened_sequence INTEGER NOT NULL,
-  last_sequence INTEGER NOT NULL,
-  closed_at TEXT NOT NULL,
-  schema TEXT NOT NULL,
-  receipt TEXT NOT NULL
-) STRICT;
-CREATE INDEX IF NOT EXISTS drive_receipts_run ON drive_receipts(run_id);
-`;
-var EVENT_STORE_MIGRATIONS = [
-  {
-    fromVersion: 3,
-    toVersion: 4,
-    migrate(database) {
-      database.exec(DRIVE_RECEIPTS_DDL);
-    }
-  },
-  {
-    fromVersion: 4,
-    toVersion: 5,
-    migrate(database) {
-      database.exec(COORDINATOR_INTAKE_DDL);
-    }
-  }
-];
 var KxmRunEventStore = class {
   path;
   database;
@@ -18343,8 +18269,7 @@ var KxmRunEventStore = class {
     this.database = openDatabase(this.path, "run event store", {
       schema: EVENT_STORE_SCHEMA,
       version: KXM_EVENT_STORE_SCHEMA_VERSION,
-      tables: EVENT_STORE_TABLES,
-      migrations: EVENT_STORE_MIGRATIONS
+      tables: EVENT_STORE_TABLES
     });
   }
   close() {

package/plugins/kxm/dist/runtime.js

@@ -17783,20 +17783,11 @@ function openDatabase(file, description, spec) {
       database.exec(spec.schema);
       database.exec(`PRAGMA user_version = ${spec.version}`);
     } else if (version < spec.version) {
-      let currentVersion = version;
-      while (currentVersion < spec.version) {
-        const step = spec.migrations?.find((m) => m.fromVersion === currentVersion);
-        if (!step) {
-          throw databaseError(
-            "runtime_schema_outdated",
-            file,
-            `${description} schema version ${version} is older than ${spec.version}; no migration lane, backup and restore remain E6`
-          );
-        }
-        step.migrate(database);
-        currentVersion = step.toVersion;
-        database.exec(`PRAGMA user_version = ${currentVersion}`);
-      }
+      throw databaseError(
+        "runtime_schema_outdated",
+        file,
+        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file (or re-run \`kxm init\`) to start fresh \u2014 upgrading old state in place is deliberately unsupported`
+      );
     }
     if (spec.tables) {
       verifyExpectedTables(database, file, description, spec.tables);
@@ -18710,71 +18701,6 @@ CREATE TABLE project_controls (
   record TEXT NOT NULL
 ) STRICT;
 `;
-var COORDINATOR_INTAKE_DDL = `
-CREATE TABLE IF NOT EXISTS coordinators (
-  coordinator_id TEXT PRIMARY KEY,
-  project_id TEXT NOT NULL,
-  role TEXT NOT NULL,
-  channel TEXT NOT NULL,
-  ceiling_hash TEXT NOT NULL,
-  config_revision TEXT NOT NULL,
-  bound_at TEXT NOT NULL,
-  schema TEXT NOT NULL,
-  record TEXT NOT NULL
-) STRICT;
-CREATE UNIQUE INDEX IF NOT EXISTS coordinators_slot ON coordinators(project_id, role, channel);
-CREATE TABLE IF NOT EXISTS intake_messages (
-  message_id TEXT PRIMARY KEY,
-  project_id TEXT NOT NULL,
-  coordinator_id TEXT NOT NULL,
-  idempotency_key TEXT NOT NULL,
-  content_hash TEXT NOT NULL,
-  received_at TEXT NOT NULL,
-  dispatch_state TEXT NOT NULL CHECK (dispatch_state IN ('ready','held_paused','admitted','refused')),
-  schema TEXT NOT NULL,
-  record TEXT NOT NULL
-) STRICT;
-CREATE UNIQUE INDEX IF NOT EXISTS intake_idempotency ON intake_messages(project_id, coordinator_id, idempotency_key);
-CREATE INDEX IF NOT EXISTS intake_dispatch ON intake_messages(project_id, dispatch_state, received_at, message_id);
-CREATE TABLE IF NOT EXISTS project_controls (
-  project_id TEXT PRIMARY KEY,
-  paused INTEGER NOT NULL CHECK (paused IN (0, 1)),
-  reason TEXT,
-  updated_at TEXT NOT NULL,
-  actor TEXT NOT NULL,
-  schema TEXT NOT NULL,
-  record TEXT NOT NULL
-) STRICT;
-`;
-var DRIVE_RECEIPTS_DDL = `
-CREATE TABLE IF NOT EXISTS drive_receipts (
-  drive_id TEXT PRIMARY KEY,
-  run_id TEXT NOT NULL,
-  project_id TEXT NOT NULL,
-  opened_sequence INTEGER NOT NULL,
-  last_sequence INTEGER NOT NULL,
-  closed_at TEXT NOT NULL,
-  schema TEXT NOT NULL,
-  receipt TEXT NOT NULL
-) STRICT;
-CREATE INDEX IF NOT EXISTS drive_receipts_run ON drive_receipts(run_id);
-`;
-var EVENT_STORE_MIGRATIONS = [
-  {
-    fromVersion: 3,
-    toVersion: 4,
-    migrate(database) {
-      database.exec(DRIVE_RECEIPTS_DDL);
-    }
-  },
-  {
-    fromVersion: 4,
-    toVersion: 5,
-    migrate(database) {
-      database.exec(COORDINATOR_INTAKE_DDL);
-    }
-  }
-];
 var KxmRunEventStore = class {
   path;
   database;
@@ -18783,8 +18709,7 @@ var KxmRunEventStore = class {
     this.database = openDatabase(this.path, "run event store", {
       schema: EVENT_STORE_SCHEMA,
       version: KXM_EVENT_STORE_SCHEMA_VERSION,
-      tables: EVENT_STORE_TABLES,
-      migrations: EVENT_STORE_MIGRATIONS
+      tables: EVENT_STORE_TABLES
     });
   }
   close() {

package/plugins/kxm/dist/server.js

@@ -11504,20 +11504,11 @@ function openDatabase(file, description, spec) {
       database.exec(spec.schema);
       database.exec(`PRAGMA user_version = ${spec.version}`);
     } else if (version < spec.version) {
-      let currentVersion = version;
-      while (currentVersion < spec.version) {
-        const step = spec.migrations?.find((m) => m.fromVersion === currentVersion);
-        if (!step) {
-          throw databaseError(
-            "runtime_schema_outdated",
-            file,
-            `${description} schema version ${version} is older than ${spec.version}; no migration lane, backup and restore remain E6`
-          );
-        }
-        step.migrate(database);
-        currentVersion = step.toVersion;
-        database.exec(`PRAGMA user_version = ${currentVersion}`);
-      }
+      throw databaseError(
+        "runtime_schema_outdated",
+        file,
+        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file (or re-run \`kxm init\`) to start fresh \u2014 upgrading old state in place is deliberately unsupported`
+      );
     }
     if (spec.tables) {
       verifyExpectedTables(database, file, description, spec.tables);
@@ -11683,100 +11674,10 @@ var HUB_STORE_SCHEMA_V3 = `
   ) STRICT;
   CREATE INDEX IF NOT EXISTS context_items_project ON context_items(project);
 `;
-var HUB_STORE_MIGRATIONS = Object.freeze([
-  {
-    fromVersion: 1,
-    toVersion: 2,
-    migrate: (db) => {
-      db.exec(`
-        CREATE TABLE IF NOT EXISTS agents (
-          id TEXT PRIMARY KEY,
-          record TEXT NOT NULL
-        ) STRICT;
-        CREATE TABLE IF NOT EXISTS messages (
-          id TEXT PRIMARY KEY,
-          record TEXT NOT NULL
-        ) STRICT;
-        CREATE TABLE IF NOT EXISTS workflow_runs (
-          id TEXT PRIMARY KEY,
-          definition_id TEXT NOT NULL,
-          delivery_id TEXT NOT NULL,
-          record TEXT NOT NULL,
-          UNIQUE(definition_id, delivery_id)
-        ) STRICT;
-        CREATE TABLE IF NOT EXISTS workflow_journal (
-          id TEXT PRIMARY KEY,
-          run_id TEXT NOT NULL,
-          category TEXT NOT NULL,
-          area TEXT NOT NULL,
-          record TEXT NOT NULL
-        ) STRICT;
-        CREATE INDEX IF NOT EXISTS workflow_journal_run_id ON workflow_journal(run_id);
-      `);
-    }
-  },
-  {
-    fromVersion: 2,
-    toVersion: 3,
-    migrate: (db) => {
-      db.exec(`
-        CREATE TABLE IF NOT EXISTS agents (
-          id TEXT PRIMARY KEY,
-          record TEXT NOT NULL
-        ) STRICT;
-        CREATE TABLE IF NOT EXISTS messages (
-          id TEXT PRIMARY KEY,
-          record TEXT NOT NULL
-        ) STRICT;
-        CREATE TABLE IF NOT EXISTS workflow_runs (
-          id TEXT PRIMARY KEY,
-          definition_id TEXT NOT NULL,
-          delivery_id TEXT NOT NULL,
-          record TEXT NOT NULL,
-          UNIQUE(definition_id, delivery_id)
-        ) STRICT;
-        CREATE TABLE IF NOT EXISTS workflow_journal (
-          id TEXT PRIMARY KEY,
-          run_id TEXT NOT NULL,
-          category TEXT NOT NULL,
-          area TEXT NOT NULL,
-          record TEXT NOT NULL
-        ) STRICT;
-        CREATE INDEX IF NOT EXISTS workflow_journal_run_id ON workflow_journal(run_id);
-        CREATE TABLE IF NOT EXISTS context_items (
-          id TEXT PRIMARY KEY,
-          project TEXT NOT NULL,
-          kind TEXT NOT NULL,
-          record TEXT NOT NULL
-        ) STRICT;
-        CREATE INDEX IF NOT EXISTS context_items_project ON context_items(project);
-        CREATE UNIQUE INDEX IF NOT EXISTS messages_from_idempotency
-        ON messages(
-          json_extract(record, '$.from'),
-          json_extract(record, '$.idempotencyKey')
-        ) WHERE json_extract(record, '$.idempotencyKey') IS NOT NULL;
-        CREATE INDEX IF NOT EXISTS messages_to_seq
-        ON messages(
-          json_extract(record, '$.to'),
-          COALESCE(json_extract(record, '$.seq'), 0)
-        );
-        CREATE TABLE IF NOT EXISTS consumer_cursors (
-          agent_id TEXT PRIMARY KEY,
-          cursor INTEGER NOT NULL
-        ) STRICT;
-        CREATE TABLE IF NOT EXISTS agent_sequences (
-          agent_id TEXT PRIMARY KEY,
-          next_seq INTEGER NOT NULL
-        ) STRICT;
-      `);
-    }
-  }
-]);
 var HUB_STORE_SCHEMA_SPEC = Object.freeze({
   schema: HUB_STORE_SCHEMA_V3,
   version: HUB_STORE_SCHEMA_VERSION,
-  tables: HUB_STORE_TABLES,
-  migrations: HUB_STORE_MIGRATIONS
+  tables: HUB_STORE_TABLES
 });
 var MessageMap = class extends Map {
   store;

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.51",
+  "version": "0.7.53",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/cli/hub.ts

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 import { join, resolve } from "node:path";
 import { redactSecrets } from "../redact.ts";
 import { defaultProjectName } from "../project-name.ts";
-import { resolveClientHubAuthToken } from "../hub-env.ts";
+import { hasClientHubCredential, resolveClientHubAuthToken } from "../hub-env.ts";
 import { agentWorker, type Worker } from "../envelope.ts";
 import { MESH_TUI_PANELS, runMeshTui, type MeshTuiPanel } from "../tui.ts";
 import { formatSessionBriefText, loadSessionBriefAsync, type SessionHubStatus } from "../session-work.ts";
@@ -12,6 +12,7 @@ import {
   HubBindingError,
   hubBindingFile,
   probeHubHealth,
+  hubBindingScope,
   readHubBinding,
   removeHubBinding,
   validateHubUrl,
@@ -104,8 +105,22 @@ export async function refreshKxmUpdateNotice(runtime: Runtime, config?: KxmUpdat
 export async function cmdStatus(runtime: Runtime): Promise<number> {
   const health = await hubGet(`${runtime.serverUrl}/health`, runtime.fetchImpl);
   const ready = await hubGet(`${runtime.serverUrl}/ready`, runtime.fetchImpl);
-  const payload = { ok: health.ok && ready.ok, command: "hub view", health: health.body, ready: ready.body };
-  print(runtime.io, runtime.json, payload, `hub health=${health.ok} ready=${ready.ok}`);
+  // Scope on the status line deliberately: "attached across a network" and "attached on
+  // this box" are otherwise indistinguishable, and only one of them ships a token.
+  // Scope is a property of the URL actually contacted, not of whichever file the
+  // binding came from: KXM_SERVER_URL overrides the binding, and labelling the binding
+  // while probing an override would report "loopback" about a remote request.
+  const effectiveScope = hubBindingScope(runtime.serverUrl);
+  const overridden = Boolean(runtime.boundHubUrl && runtime.boundHubUrl !== runtime.serverUrl);
+  const payload = {
+    ok: health.ok && ready.ok,
+    command: "hub view",
+    target: { url: runtime.serverUrl, scope: effectiveScope, ...(overridden ? { source: "env" } : {}) },
+    health: health.body,
+    ready: ready.body,
+  };
+  print(runtime.io, runtime.json, payload,
+    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""}`);
   return payload.ok ? 0 : 1;
 }
 
@@ -191,6 +206,10 @@ export function formatHubBindHealth(health: HubHealth): string {
   return "health=unknown (no reply within 300 ms)";
 }
 
+/** Kept in one place so the JSON payload and the prose line cannot drift apart. */
+const HUB_BIND_UNAUTHENTICATED_HINT =
+  "export KXM_AUTH_TOKEN (or point KXM_STATE_HOME at the hub-env record that already holds one), then re-run; the hub itself requires a token beyond loopback";
+
 export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<number> {
   let url: string;
   try {
@@ -207,14 +226,73 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string): Promise<numb
     }
     throw error;
   }
+  const scope = hubBindingScope(url);
+  // Scope-scoped on purpose, and only for **this command**. A remote binding puts a
+  // bearer on a network path, so it is refused when nothing can authenticate it; a
+  // stored-but-unusable URL otherwise reads later like a network fault and gets debugged
+  // as one. Loopback is not consulted here because a loopback URL puts nothing on a wire —
+  // not because credentials are never resolved locally: other client paths still call
+  // `resolveClientHubAuthToken` regardless of scope, so a damaged host record can still
+  // fail `kxm peer list` on loopback. Narrowing the claim is the point; the first version
+  // of this guard checked the record *before* the scope and refused loopback binds that had
+  // always worked, which is a regression against behaviour predating this slice.
+  if (scope === "remote") {
+    // The project that will actually authenticate: a record holding only another
+    // project's token cannot authorise this one.
+    const bindProject = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
+    let credentialReady = false;
+    try {
+      credentialReady = hasClientHubCredential(runtime.env, bindProject);
+    } catch (error) {
+      // A malformed record is a readable configuration failure, not an uncaught throw
+      // past a user-facing entry point.
+      print(
+        runtime.io,
+        runtime.json,
+        {
+          ok: false,
+          command: "hub bind",
+          error: "hub_credential_unreadable",
+          url,
+          scope,
+          nextAction: "repair_hub_env_record",
+          hint: `${error instanceof Error ? error.message : String(error)}; no binding was written`,
+        },
+        `cannot read the hub credential: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return 2;
+    }
+    if (!credentialReady) {
+      print(
+        runtime.io,
+        runtime.json,
+        {
+          ok: false,
+          command: "hub bind",
+          error: "hub_bind_unauthenticated",
+          url,
+          scope,
+          project: bindProject,
+          // The hint belongs in the payload, not only the prose line: under --json the
+          // prose is suppressed, and a refusal that names no next step gets debugged by
+          // reading source.
+          nextAction: "export_kxm_auth_token",
+          hint: `${HUB_BIND_UNAUTHENTICATED_HINT} (needs a token for project ${bindProject})`,
+        },
+        `refusing to bind remote hub ${url} with no credential for project ${bindProject}; ${HUB_BIND_UNAUTHENTICATED_HINT}`,
+      );
+      return 2;
+    }
+  }
   const file = hubBindingFile(runtime.env);
   if (runtime.dryRun) {
-    print(runtime.io, runtime.json, { ok: true, command: "hub bind", dryRun: true, url, file }, `would bind hub ${url}`);
+    print(runtime.io, runtime.json, { ok: true, command: "hub bind", dryRun: true, url, scope, file }, `would bind hub ${url} (${scope})`);
     return 0;
   }
   writeHubBinding({ schema: HUB_BINDING_SCHEMA, url, boundAt: new Date().toISOString() }, runtime.env);
   const { health, probeMs } = await probeHubHealth(url, runtime.fetchImpl);
-  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, file, health, probeMs }, `bound hub ${url} · ${formatHubBindHealth(health)}`);
+  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, scope, file, health, probeMs },
+    `bound hub ${url} · ${scope} · ${formatHubBindHealth(health)}${scope === "remote" ? " · token leaves this machine" : ""}`);
   return 0;
 }
 
@@ -540,6 +618,7 @@ export async function cmdSessionBrief(runtime: Runtime, options: { status?: bool
       evidence: health === "unknown" ? "timeout" : "probed",
       online: health === "on",
       url: targetUrl,
+      scope: hubBindingScope(targetUrl),
     };
   } else {
     hub = { state: "off", evidence: "unconfigured", online: false };

package/plugins/kxm/src/database.ts

@@ -14,17 +14,10 @@ import { basename, dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
 import { KxmConfigError, type KxmConfigIssue } from "./project-config.ts";
 
-export interface DatabaseMigrationStep {
-  fromVersion: number;
-  toVersion: number;
-  migrate: (database: DatabaseSync) => void;
-}
-
 export interface DatabaseSchemaSpec {
   schema: string;
   version: number;
   tables?: Readonly<Record<string, readonly string[]>>;
-  migrations?: readonly DatabaseMigrationStep[];
   timeoutMs?: number;
 }
 
@@ -179,20 +172,15 @@ export function openDatabase(file: string, description: string, spec: DatabaseSc
       database.exec(spec.schema);
       database.exec(`PRAGMA user_version = ${spec.version}`);
     } else if (version < spec.version) {
-      let currentVersion = version;
-      while (currentVersion < spec.version) {
-        const step = spec.migrations?.find((m) => m.fromVersion === currentVersion);
-        if (!step) {
-          throw databaseError(
-            "runtime_schema_outdated",
-            file,
-            `${description} schema version ${version} is older than ${spec.version}; no migration lane, backup and restore remain E6`,
-          );
-        }
-        step.migrate(database);
-        currentVersion = step.toVersion;
-        database.exec(`PRAGMA user_version = ${currentVersion}`);
-      }
+      // No migration lanes. This is a single-operator tool: an older database is
+      // re-initialised, not upgraded in place, and the code never carries two schema
+      // shapes at once. Silently accepting an older file would mean every query has to
+      // work against shapes it no longer tests.
+      throw databaseError(
+        "runtime_schema_outdated",
+        file,
+        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file (or re-run \`kxm init\`) to start fresh — upgrading old state in place is deliberately unsupported`,
+      );
     }
 
     if (spec.tables) {

package/plugins/kxm/src/external-effects.ts

@@ -16,6 +16,7 @@ import {
   lstatSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { openDatabase } from "./database.ts";
 import { spawnSync } from "node:child_process";
 
 export const EXTERNAL_EFFECT_SCHEMA = "kxm.external-effect-receipt.v1" as const;
@@ -114,6 +115,33 @@ export function computeEffectKey(
   return `eff_${createHash("sha256").update(raw).digest("hex").slice(0, 16)}`;
 }
 
+const EXTERNAL_EFFECTS_SCHEMA_VERSION = 1;
+
+const EXTERNAL_EFFECTS_DDL = `
+CREATE TABLE IF NOT EXISTS external_effects (
+  effect_key TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  step_id TEXT NOT NULL,
+  attempt_id TEXT NOT NULL,
+  action_kind TEXT NOT NULL,
+  target_ref TEXT NOT NULL,
+  status TEXT NOT NULL,
+  payload_hash TEXT NOT NULL,
+  receipt_payload TEXT NOT NULL,
+  executed_at TEXT NOT NULL,
+  last_heartbeat_at TEXT,
+  completed_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_ext_effects_run ON external_effects(run_id);
+`;
+
+const EXTERNAL_EFFECTS_SHAPE = {
+  external_effects: [
+    "effect_key", "run_id", "step_id", "attempt_id", "action_kind", "target_ref",
+    "status", "payload_hash", "receipt_payload", "executed_at", "last_heartbeat_at", "completed_at",
+  ],
+} as const;
+
 export class ExternalEffectsLedger {
   private db: DatabaseSync;
 
@@ -121,33 +149,15 @@ export class ExternalEffectsLedger {
     if (dbPath !== ":memory:") {
       mkdirSync(dirname(dbPath), { recursive: true });
     }
-    this.db = new DatabaseSync(dbPath);
-    this.initSchema();
-  }
-
-  private initSchema(): void {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS external_effects (
-        effect_key TEXT PRIMARY KEY,
-        run_id TEXT NOT NULL,
-        step_id TEXT NOT NULL,
-        attempt_id TEXT NOT NULL,
-        action_kind TEXT NOT NULL,
-        target_ref TEXT NOT NULL,
-        status TEXT NOT NULL,
-        payload_hash TEXT NOT NULL,
-        receipt_payload TEXT NOT NULL,
-        executed_at TEXT NOT NULL,
-        last_heartbeat_at TEXT,
-        completed_at TEXT
-      );
-      CREATE INDEX IF NOT EXISTS idx_ext_effects_run ON external_effects(run_id);
-    `);
-    try {
-      this.db.exec(`ALTER TABLE external_effects ADD COLUMN last_heartbeat_at TEXT;`);
-    } catch {
-      // Column already present in schema
-    }
+    // Goes through the shared opener, not a bare `new DatabaseSync`: that is what gives this
+    // store the same contract as every other one — path checks, WAL, the `user_version` gate
+    // that refuses an older stamp outright, and the column-shape check that turns a missing
+    // column into `runtime_schema_shape_invalid` here instead of a bare SQL error on first use.
+    this.db = openDatabase(dbPath, "external effects ledger", {
+      schema: EXTERNAL_EFFECTS_DDL,
+      version: EXTERNAL_EFFECTS_SCHEMA_VERSION,
+      tables: EXTERNAL_EFFECTS_SHAPE,
+    });
   }
 
   /**

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();