@kontextmind/kxm 0.7.166 → 0.7.168

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

@@ -31668,6 +31668,9 @@ function resolveUserStateRoot(env) {
 function hubBindingFile(env = process.env) {
   return join19(resolveUserStateRoot(env), "hub-binding.json");
 }
+function hubBindingCloudFile(env = process.env) {
+  return join19(resolveUserStateRoot(env), "hub-binding.cloud.json");
+}
 function validateHubUrl(raw) {
   let parsed;
   try {
@@ -31777,33 +31780,37 @@ function isIsoTimestamp(value) {
   if (Number.isNaN(Date.parse(value))) return false;
   return value === new Date(value).toISOString();
 }
-function readHubBinding(env = process.env) {
-  const file = hubBindingFile(env);
-  if (!existsSync16(file)) return void 0;
+var LEGACY_BINDING_KEYS = ["schema", "url", "boundAt"];
+var BINDING_KEYS = /* @__PURE__ */ new Set([...LEGACY_BINDING_KEYS, "cloud", "tokenEnv", "tokenCommand"]);
+function bindingFallbackWarning(file, reason) {
+  return `hub binding at ${file} ${reason}; falling back to the local hub. Restart the Runtime supervisor, the hub, and workers after upgrading and before a cloud bind.`;
+}
+function writeBindingJson(file, value) {
+  mkdirSync7(dirname9(file), { recursive: true, mode: 448 });
+  const temporary = join19(dirname9(file), `.${file.endsWith("cloud.json") ? "hub-binding-cloud" : "hub-binding"}-${process.pid}.tmp`);
+  try {
+    writeFileSync8(temporary, `${JSON.stringify(value, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    renameSync2(temporary, file);
+  } finally {
+    rmSync2(temporary, { force: true });
+  }
+}
+function parseBindingObject(file) {
+  if (!existsSync16(file)) return new HubBindingError(`missing hub binding at ${file}`);
   let parsed;
   try {
     parsed = JSON.parse(readFileSync14(file, "utf8"));
   } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return new HubBindingError(`malformed hub binding at ${file}`);
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
-  }
-  const row = parsed;
-  const keys = Object.keys(row);
-  const allowed = /* @__PURE__ */ new Set(["schema", "url", "boundAt", "cloud", "tokenEnv", "tokenCommand"]);
-  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
-  if (keys.some((key) => !allowed.has(key)) || !cloudish && keys.length !== 3 || row.schema !== HUB_BINDING_SCHEMA || typeof row.url !== "string" || typeof row.boundAt !== "string" || !isIsoTimestamp(row.boundAt)) {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return new HubBindingError(`malformed hub binding at ${file}`);
   }
-  let url;
-  try {
-    url = validateHubUrl(row.url);
-  } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
-  }
-  if (!cloudish) return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
-  if (row.cloud !== true) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return parsed;
+}
+function cloudRecordFromRow(file, row, url, boundAt) {
+  if (row.cloud !== true) return void 0;
   let tokenEnv;
   let tokenCommand;
   if (row.tokenEnv !== void 0) {
@@ -31825,12 +31832,65 @@ function readHubBinding(env = process.env) {
   return {
     schema: HUB_BINDING_SCHEMA,
     url,
-    boundAt: row.boundAt,
+    boundAt,
     cloud: true,
     ...tokenEnv ? { tokenEnv } : {},
     ...tokenCommand ? { tokenCommand } : {}
   };
 }
+function interpretBindingFile(file) {
+  if (!existsSync16(file)) return {};
+  const parsed = parseBindingObject(file);
+  if (parsed instanceof HubBindingError) throw parsed;
+  const keys = Object.keys(parsed);
+  const unknown = keys.filter((key) => !BINDING_KEYS.has(key));
+  if (parsed.schema !== HUB_BINDING_SCHEMA || unknown.length > 0) {
+    return { warning: bindingFallbackWarning(file, `is newer than this build understands (${String(parsed.schema)})`) };
+  }
+  if (typeof parsed.url !== "string" || typeof parsed.boundAt !== "string" || !isIsoTimestamp(parsed.boundAt)) {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  let url;
+  try {
+    url = validateHubUrl(parsed.url);
+  } catch {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
+  if (!cloudish) {
+    if (keys.length !== 3) throw new HubBindingError(`malformed hub binding at ${file}`);
+    return { record: { schema: HUB_BINDING_SCHEMA, url, boundAt: parsed.boundAt } };
+  }
+  const record2 = cloudRecordFromRow(file, parsed, url, parsed.boundAt);
+  if (!record2) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return { record: record2, legacyCloud: true };
+}
+function loadHubBinding(env = process.env) {
+  const cloudFile = hubBindingCloudFile(env);
+  const cloud = interpretBindingFile(cloudFile);
+  if (cloud.warning && !cloud.record) {
+    const local = existsSync16(hubBindingFile(env)) ? interpretBindingFile(hubBindingFile(env)) : {};
+    if (local.record && !local.record.cloud) return { record: local.record, warning: cloud.warning };
+    return { warning: cloud.warning };
+  }
+  if (cloud.record?.cloud) return { record: cloud.record, ...cloud.warning ? { warning: cloud.warning } : {} };
+  const main = interpretBindingFile(hubBindingFile(env));
+  if (main.legacyCloud && main.record) {
+    writeBindingJson(cloudFile, main.record);
+    rmSync2(hubBindingFile(env), { force: true });
+    return {
+      record: main.record,
+      warning: bindingFallbackWarning(
+        hubBindingFile(env),
+        "stored a cloud bind in the pre-0.7.160 file"
+      )
+    };
+  }
+  return { ...main.record ? { record: main.record } : {}, ...main.warning ? { warning: main.warning } : {} };
+}
+function readHubBinding(env = process.env) {
+  return loadHubBinding(env).record;
+}
 
 // plugins/kxm/src/hub-env.ts
 import { existsSync as existsSync18, mkdirSync as mkdirSync8, readFileSync as readFileSync16, renameSync as renameSync3, rmSync as rmSync3, writeFileSync as writeFileSync9 } from "node:fs";
@@ -31906,15 +31966,6 @@ function resolveProjectIdentity(cwd, env = process.env, explicit) {
   if (fromPackage) return { project: fromPackage, source: "package.json", sourceLabel: "package.json name" };
   return { project: basename4(cwd), source: "directory", sourceLabel: "directory name" };
 }
-function opReferenceFromTokenCommand(command) {
-  try {
-    const args = splitTokenCommand(command);
-    if (args[0] === "op" && args[1] === "read" && args[2] && isHubOpReference(args[2])) return args[2];
-  } catch {
-    return void 0;
-  }
-  return void 0;
-}
 function defaultOpRead(reference, env) {
   if (!isHubOpReference(reference)) {
     throw new CloudTokenError("cloud_token_command_invalid", `refusing to resolve ${reference}; an op:// reference is required`);
@@ -31959,18 +32010,24 @@ function resolveKeyReference(ref, env, opRead = defaultOpRead) {
 }
 function keySourceFor(input) {
   const ref = input.endpoint?.key;
-  if (input.mode === "local" && input.env.KXM_AUTH_TOKEN?.trim()) return "env:KXM_AUTH_TOKEN";
-  if (ref?.env && input.env[ref.env]?.trim()) return `env:${ref.env}`;
-  if (ref?.op) return `op:${ref.op}`;
-  if (ref?.env) return `env:${ref.env}`;
+  const envName = (name) => {
+    if (!name) return void 0;
+    return input.env[name]?.trim() ? `env:${name}` : void 0;
+  };
   if (input.mode === "cloud") {
-    if (input.binding?.tokenEnv) return `env:${input.binding.tokenEnv}`;
-    if (input.binding?.tokenCommand) {
-      const op = opReferenceFromTokenCommand(input.binding.tokenCommand);
-      return op ? `op:${op}` : "command";
-    }
+    const fromEnv2 = envName(ref?.env);
+    if (fromEnv2) return fromEnv2;
+    if (ref?.op) return `op:${ref.op}`;
+    const fromBindingEnv = envName(input.binding?.tokenEnv);
+    if (fromBindingEnv) return fromBindingEnv;
+    if (input.binding?.tokenCommand) return "token-command";
     return "missing";
   }
+  const fromAuth = envName("KXM_AUTH_TOKEN");
+  if (fromAuth) return fromAuth;
+  const fromEnv = envName(ref?.env);
+  if (fromEnv) return fromEnv;
+  if (ref?.op) return `op:${ref.op}`;
   if (input.hasSavedProjectToken?.(input.project)) return "hub-env";
   return "missing";
 }
@@ -32631,8 +32688,17 @@ async function syncKxmOutbox(eventStore, client, options = {}) {
     }
   }
 }
-function runtimeHubClientFor(context, env) {
-  const serverUrl = env.KXM_SERVER_URL?.trim() || readHubBinding(env)?.url;
+function runtimeHubClientFor(context, env, onBindingWarning) {
+  let recordUrl;
+  try {
+    const loaded = loadHubBinding(env);
+    if (loaded.warning) onBindingWarning?.(loaded.warning);
+    recordUrl = loaded.record?.url;
+  } catch (error) {
+    if (!(error instanceof HubBindingError)) throw error;
+    onBindingWarning?.(`${error.message}; falling back to the local hub so sync can continue`);
+  }
+  const serverUrl = env.KXM_SERVER_URL?.trim() || recordUrl;
   if (!serverUrl) return void 0;
   const project = context.projectId;
   const authToken = resolveClientHubAuthToken(env, project);
@@ -33160,6 +33226,7 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
     else logger.info(entry);
   };
   let syncing = false;
+  let bindingWarning;
   const syncTimer = setInterval(() => {
     if (syncing || stopping) return;
     syncing = true;
@@ -33177,7 +33244,11 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
           consecutiveFailures: 0
         };
         try {
-          const client = runtimeHubClientFor(context, env);
+          const client = runtimeHubClientFor(context, env, (message) => {
+            if (bindingWarning === message) return;
+            bindingWarning = message;
+            logger.warn({ event: "hub_binding_fallback", message });
+          });
           if (!client) {
             recordSyncStatus(context, { ...base, state: "no_hub" });
             continue;

package/plugins/kxm/dist/runtime.js

@@ -32416,6 +32416,9 @@ function resolveUserStateRoot(env) {
 function hubBindingFile(env = process.env) {
   return join19(resolveUserStateRoot(env), "hub-binding.json");
 }
+function hubBindingCloudFile(env = process.env) {
+  return join19(resolveUserStateRoot(env), "hub-binding.cloud.json");
+}
 function validateHubUrl(raw) {
   let parsed;
   try {
@@ -32525,33 +32528,37 @@ function isIsoTimestamp(value) {
   if (Number.isNaN(Date.parse(value))) return false;
   return value === new Date(value).toISOString();
 }
-function readHubBinding(env = process.env) {
-  const file = hubBindingFile(env);
-  if (!existsSync16(file)) return void 0;
+var LEGACY_BINDING_KEYS = ["schema", "url", "boundAt"];
+var BINDING_KEYS = /* @__PURE__ */ new Set([...LEGACY_BINDING_KEYS, "cloud", "tokenEnv", "tokenCommand"]);
+function bindingFallbackWarning(file, reason) {
+  return `hub binding at ${file} ${reason}; falling back to the local hub. Restart the Runtime supervisor, the hub, and workers after upgrading and before a cloud bind.`;
+}
+function writeBindingJson(file, value) {
+  mkdirSync7(dirname9(file), { recursive: true, mode: 448 });
+  const temporary = join19(dirname9(file), `.${file.endsWith("cloud.json") ? "hub-binding-cloud" : "hub-binding"}-${process.pid}.tmp`);
+  try {
+    writeFileSync8(temporary, `${JSON.stringify(value, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    renameSync2(temporary, file);
+  } finally {
+    rmSync2(temporary, { force: true });
+  }
+}
+function parseBindingObject(file) {
+  if (!existsSync16(file)) return new HubBindingError(`missing hub binding at ${file}`);
   let parsed;
   try {
     parsed = JSON.parse(readFileSync14(file, "utf8"));
   } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return new HubBindingError(`malformed hub binding at ${file}`);
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
-  }
-  const row = parsed;
-  const keys = Object.keys(row);
-  const allowed = /* @__PURE__ */ new Set(["schema", "url", "boundAt", "cloud", "tokenEnv", "tokenCommand"]);
-  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
-  if (keys.some((key) => !allowed.has(key)) || !cloudish && keys.length !== 3 || row.schema !== HUB_BINDING_SCHEMA || typeof row.url !== "string" || typeof row.boundAt !== "string" || !isIsoTimestamp(row.boundAt)) {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return new HubBindingError(`malformed hub binding at ${file}`);
   }
-  let url;
-  try {
-    url = validateHubUrl(row.url);
-  } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
-  }
-  if (!cloudish) return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
-  if (row.cloud !== true) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return parsed;
+}
+function cloudRecordFromRow(file, row, url, boundAt) {
+  if (row.cloud !== true) return void 0;
   let tokenEnv;
   let tokenCommand;
   if (row.tokenEnv !== void 0) {
@@ -32573,12 +32580,65 @@ function readHubBinding(env = process.env) {
   return {
     schema: HUB_BINDING_SCHEMA,
     url,
-    boundAt: row.boundAt,
+    boundAt,
     cloud: true,
     ...tokenEnv ? { tokenEnv } : {},
     ...tokenCommand ? { tokenCommand } : {}
   };
 }
+function interpretBindingFile(file) {
+  if (!existsSync16(file)) return {};
+  const parsed = parseBindingObject(file);
+  if (parsed instanceof HubBindingError) throw parsed;
+  const keys = Object.keys(parsed);
+  const unknown = keys.filter((key) => !BINDING_KEYS.has(key));
+  if (parsed.schema !== HUB_BINDING_SCHEMA || unknown.length > 0) {
+    return { warning: bindingFallbackWarning(file, `is newer than this build understands (${String(parsed.schema)})`) };
+  }
+  if (typeof parsed.url !== "string" || typeof parsed.boundAt !== "string" || !isIsoTimestamp(parsed.boundAt)) {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  let url;
+  try {
+    url = validateHubUrl(parsed.url);
+  } catch {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
+  if (!cloudish) {
+    if (keys.length !== 3) throw new HubBindingError(`malformed hub binding at ${file}`);
+    return { record: { schema: HUB_BINDING_SCHEMA, url, boundAt: parsed.boundAt } };
+  }
+  const record2 = cloudRecordFromRow(file, parsed, url, parsed.boundAt);
+  if (!record2) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return { record: record2, legacyCloud: true };
+}
+function loadHubBinding(env = process.env) {
+  const cloudFile = hubBindingCloudFile(env);
+  const cloud = interpretBindingFile(cloudFile);
+  if (cloud.warning && !cloud.record) {
+    const local = existsSync16(hubBindingFile(env)) ? interpretBindingFile(hubBindingFile(env)) : {};
+    if (local.record && !local.record.cloud) return { record: local.record, warning: cloud.warning };
+    return { warning: cloud.warning };
+  }
+  if (cloud.record?.cloud) return { record: cloud.record, ...cloud.warning ? { warning: cloud.warning } : {} };
+  const main = interpretBindingFile(hubBindingFile(env));
+  if (main.legacyCloud && main.record) {
+    writeBindingJson(cloudFile, main.record);
+    rmSync2(hubBindingFile(env), { force: true });
+    return {
+      record: main.record,
+      warning: bindingFallbackWarning(
+        hubBindingFile(env),
+        "stored a cloud bind in the pre-0.7.160 file"
+      )
+    };
+  }
+  return { ...main.record ? { record: main.record } : {}, ...main.warning ? { warning: main.warning } : {} };
+}
+function readHubBinding(env = process.env) {
+  return loadHubBinding(env).record;
+}
 
 // plugins/kxm/src/hub-env.ts
 import { existsSync as existsSync18, mkdirSync as mkdirSync8, readFileSync as readFileSync16, renameSync as renameSync3, rmSync as rmSync3, writeFileSync as writeFileSync9 } from "node:fs";
@@ -32654,15 +32714,6 @@ function resolveProjectIdentity(cwd, env = process.env, explicit) {
   if (fromPackage) return { project: fromPackage, source: "package.json", sourceLabel: "package.json name" };
   return { project: basename4(cwd), source: "directory", sourceLabel: "directory name" };
 }
-function opReferenceFromTokenCommand(command) {
-  try {
-    const args = splitTokenCommand(command);
-    if (args[0] === "op" && args[1] === "read" && args[2] && isHubOpReference(args[2])) return args[2];
-  } catch {
-    return void 0;
-  }
-  return void 0;
-}
 function defaultOpRead(reference, env) {
   if (!isHubOpReference(reference)) {
     throw new CloudTokenError("cloud_token_command_invalid", `refusing to resolve ${reference}; an op:// reference is required`);
@@ -32707,18 +32758,24 @@ function resolveKeyReference(ref, env, opRead = defaultOpRead) {
 }
 function keySourceFor(input) {
   const ref = input.endpoint?.key;
-  if (input.mode === "local" && input.env.KXM_AUTH_TOKEN?.trim()) return "env:KXM_AUTH_TOKEN";
-  if (ref?.env && input.env[ref.env]?.trim()) return `env:${ref.env}`;
-  if (ref?.op) return `op:${ref.op}`;
-  if (ref?.env) return `env:${ref.env}`;
+  const envName = (name) => {
+    if (!name) return void 0;
+    return input.env[name]?.trim() ? `env:${name}` : void 0;
+  };
   if (input.mode === "cloud") {
-    if (input.binding?.tokenEnv) return `env:${input.binding.tokenEnv}`;
-    if (input.binding?.tokenCommand) {
-      const op = opReferenceFromTokenCommand(input.binding.tokenCommand);
-      return op ? `op:${op}` : "command";
-    }
+    const fromEnv2 = envName(ref?.env);
+    if (fromEnv2) return fromEnv2;
+    if (ref?.op) return `op:${ref.op}`;
+    const fromBindingEnv = envName(input.binding?.tokenEnv);
+    if (fromBindingEnv) return fromBindingEnv;
+    if (input.binding?.tokenCommand) return "token-command";
     return "missing";
   }
+  const fromAuth = envName("KXM_AUTH_TOKEN");
+  if (fromAuth) return fromAuth;
+  const fromEnv = envName(ref?.env);
+  if (fromEnv) return fromEnv;
+  if (ref?.op) return `op:${ref.op}`;
   if (input.hasSavedProjectToken?.(input.project)) return "hub-env";
   return "missing";
 }
@@ -33379,8 +33436,17 @@ async function syncKxmOutbox(eventStore, client, options = {}) {
     }
   }
 }
-function runtimeHubClientFor(context, env) {
-  const serverUrl = env.KXM_SERVER_URL?.trim() || readHubBinding(env)?.url;
+function runtimeHubClientFor(context, env, onBindingWarning) {
+  let recordUrl;
+  try {
+    const loaded = loadHubBinding(env);
+    if (loaded.warning) onBindingWarning?.(loaded.warning);
+    recordUrl = loaded.record?.url;
+  } catch (error) {
+    if (!(error instanceof HubBindingError)) throw error;
+    onBindingWarning?.(`${error.message}; falling back to the local hub so sync can continue`);
+  }
+  const serverUrl = env.KXM_SERVER_URL?.trim() || recordUrl;
   if (!serverUrl) return void 0;
   const project = context.projectId;
   const authToken = resolveClientHubAuthToken(env, project);
@@ -33908,6 +33974,7 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
     else logger.info(entry);
   };
   let syncing = false;
+  let bindingWarning;
   const syncTimer = setInterval(() => {
     if (syncing || stopping) return;
     syncing = true;
@@ -33925,7 +33992,11 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
           consecutiveFailures: 0
         };
         try {
-          const client = runtimeHubClientFor(context, env);
+          const client = runtimeHubClientFor(context, env, (message) => {
+            if (bindingWarning === message) return;
+            bindingWarning = message;
+            logger.warn({ event: "hub_binding_fallback", message });
+          });
           if (!client) {
             recordSyncStatus(context, { ...base, state: "no_hub" });
             continue;

package/plugins/kxm/dist/server.js

@@ -23491,6 +23491,8 @@ var CloudTokenError = class extends Error {
     this.code = code;
   }
 };
+var LEGACY_BINDING_KEYS = ["schema", "url", "boundAt"];
+var BINDING_KEYS = /* @__PURE__ */ new Set([...LEGACY_BINDING_KEYS, "cloud", "tokenEnv", "tokenCommand"]);
 
 // plugins/kxm/src/hub-identity.ts
 var OP_TIMEOUT_MS = 15e3;

package/plugins/kxm/package.json

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

package/plugins/kxm/skills/kxm-harness-auth/SKILL.md

@@ -39,8 +39,10 @@ still blocks the tools.
 | `kxm update [harness] --extensions` | Update only extensions and plugins (Pi packages, the Claude kxm plugin) |
 | `kxm update [harness] --models` | Refresh model catalogs where the harness supports it |
 
-- `kxm update --kxm` downloads the GitHub release tarball by default, so it
-  needs an authenticated `gh`.
+- `kxm update --kxm` downloads the GitHub release tarball by default. It uses
+  `gh` when that CLI answers `gh --version`, and otherwise curl with the same
+  sha256 check. A host with neither can follow the curl commands in
+  docs/operations/upgrade.md.
 - `kxm update claude --extensions` updates only a user-scope plugin install;
   its dry run prints `claude extensions: would claude plugin update kxm -y`.
   A project-scope install is the operator's `claude plugin update kxm@kxm --scope project`.

package/plugins/kxm/skills/kxm-hub-ops/SKILL.md

@@ -77,10 +77,15 @@ kxm restore .kxm/backups/pre-upgrade/manifest.json
   `hub_bind_unauthenticated` unless a credential for the current project
   resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`.
 - `kxm hub bind --cloud` is the bind for a loopback SSH forward of a remote
-  hub. It never falls back to this machine's hub-env token. Pass
-  `--token-env KXMD_HUB_TOKEN`, `--key-op op://Private/kxmd/project-token`,
-  or `--token-command "op read op://..."`. The non-secret fields are written
-  to `.kxm/config.yaml`. See docs/operations.md, section "Cross-box peer attach".
+  hub (`http://127.0.0.1:17331`). `https://hub.kxmd.dev` is an Authentik login
+  page, not a client URL. Bind refuses an HTML 200 or a 30x (`hub_not_kxm`)
+  unless `--force` is set. It never falls back to this machine's hub-env
+  token. Pass `--token-env KXMD_HUB_TOKEN`, `--key-op op://Private/kxmd/project-token`,
+  or `--token-command "op read op://..."`. `--token-command` is stored only in
+  the machine-wide `hub-binding.cloud.json`, not in `.kxm/config.yaml`.
+  `kxm hub view` names the source that would supply the token. See
+  docs/operations.md, section "Cross-box peer attach". Restart the supervisor,
+  hub, and workers after an upgrade and before a cloud bind.
 - Hub PID claims record the wrapper and server child PID. A dead wrapper's
   claim is reclaimed automatically, an orphaned server is terminated first,
   and `kxm hub stop` recovers such orphans directly.

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

@@ -13,8 +13,10 @@ import {
   HUB_BINDING_SCHEMA,
   CloudTokenError,
   HubBindingError,
+  hubBindingCloudFile,
   hubBindingFile,
   probeHubHealth,
+  readHubEndpoint,
   hubBindingScope,
   effectiveHubBindingScope,
   isCloudTokenEnvName,
@@ -181,8 +183,17 @@ export async function cmdStatus(runtime: Runtime): Promise<number> {
     }
     if (!(error instanceof HubBindingError)) throw error;
   }
-  const health = await hubGet(`${runtime.serverUrl}/health`, runtime.fetchImpl, headers);
-  const ready = await hubGet(`${runtime.serverUrl}/ready`, runtime.fetchImpl, headers);
+  const health = await readHubEndpoint(runtime.serverUrl, "health", runtime.fetchImpl, headers ? { headers } : {});
+  const ready = await readHubEndpoint(runtime.serverUrl, "ready", runtime.fetchImpl, headers ? { headers } : {});
+  const proxyKind = [health.kind, ready.kind].find((kind) => kind === "redirect" || kind === "auth_proxy");
+  const notHub = !proxyKind && (health.kind === "not_hub" || ready.kind === "not_hub");
+  const probeNote = proxyKind === "redirect"
+    ? " · auth proxy or redirect"
+    : proxyKind === "auth_proxy"
+      ? " · auth proxy (HTML login page)"
+      : notHub
+        ? " · not a kxm hub"
+        : "";
   // 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
@@ -210,7 +221,7 @@ export async function cmdStatus(runtime: Runtime): Promise<number> {
     ready: ready.body,
   };
   print(runtime.io, runtime.json, payload,
-    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} · mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}`);
+    `hub health=${health.ok} ready=${ready.ok} · ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""} · mode=${identity.mode} project=${identity.project} (${connection.sourceLabel}) key=${identity.keySource}${probeNote}`);
   return payload.ok ? 0 : 1;
 }
 
@@ -314,6 +325,7 @@ export interface HubBindOptions {
   tokenEnv?: string | undefined;
   tokenCommand?: string | undefined;
   keyOp?: string | undefined;
+  force?: boolean | undefined;
 }
 
 export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubBindOptions = {}): Promise<number> {
@@ -444,7 +456,7 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubB
       return 2;
     }
   }
-  const file = hubBindingFile(runtime.env);
+  const file = cloud ? hubBindingCloudFile(runtime.env) : hubBindingFile(runtime.env);
   const bindingCommand = tokenCommand ?? (cloud && keyOp ? `op read ${keyOp}` : undefined);
   const cloudFields = cloud
     ? { cloud: true as const, ...(tokenEnv ? { tokenEnv } : {}), ...(bindingCommand ? { tokenCommand: bindingCommand } : {}) }
@@ -471,6 +483,27 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubB
     );
     return 0;
   }
+  const probe = await probeHubHealth(url, runtime.fetchImpl);
+  const acceptable = probe.kind === "hub" || probe.kind === "timeout" || probe.kind === "unreachable";
+  if (!acceptable && options.force !== true) {
+    print(
+      runtime.io,
+      runtime.json,
+      {
+        ok: false,
+        command: "hub bind",
+        error: "hub_not_kxm",
+        url,
+        scope,
+        kind: probe.kind,
+        status: probe.status,
+        detail: probe.detail,
+        nextAction: "bind_a_kxm_hub_or_pass_force",
+      },
+      `refusing to bind ${url}: ${probe.detail}; no binding was written. Pass --force to bind anyway`,
+    );
+    return 2;
+  }
   try {
     writeHubEndpoint(runtime.dirs.workdir, {
       mode: cloud ? "cloud" : "local",
@@ -491,9 +524,11 @@ export async function cmdHubBind(runtime: Runtime, rawUrl: string, options: HubB
     throw error;
   }
   writeHubBinding({ ...record, 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, scope, file, configFile, project: identity.project, health, probeMs, ...cloudFields },
-    `bound hub ${url} · ${scope} · ${formatHubBindHealth(health)}${cloud ? cloudNote : scope === "remote" ? " · token leaves this machine" : ""}`);
+  const healthText = acceptable
+    ? formatHubBindHealth(probe.health)
+    : `${probe.detail} (--force)`;
+  print(runtime.io, runtime.json, { ok: true, command: "hub bind", url, scope, file, configFile, project: identity.project, health: probe.health, probeMs: probe.probeMs, kind: probe.kind, ...cloudFields },
+    `bound hub ${url} · ${scope} · ${healthText}${cloud ? cloudNote : scope === "remote" ? " · token leaves this machine" : ""}`);
   return 0;
 }
 

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

@@ -75,6 +75,7 @@ import {
 import {
   installedKxmVersion,
   fetchLatestKxmVersion,
+  ghReleaseDownloadAvailable,
   kxmReleaseAssetName,
   noticeFromVersions,
   planKxmPackageUpdate,
@@ -159,7 +160,8 @@ export function applyKxmPackageUpdate(runtime: Runtime, notice: KxmUpdateNotice)
   }
   const releaseDir = mkdtempSync(join(tmpdir(), "kxm-pkg-update-"));
   try {
-    const planned = planKxmPackageUpdate(notice.source, notice.latest, releaseDir, notice.asset);
+    const downloader = notice.source === "github" && !ghReleaseDownloadAvailable(runtime.env) ? "curl" : "gh";
+    const planned = planKxmPackageUpdate(notice.source, notice.latest, releaseDir, notice.asset, downloader);
     if (runtime.dryRun) {
       return { ok: true, detail: planned.map(formatPackageUpdateStep).join(" && ") };
     }

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

@@ -10,7 +10,7 @@ import {
   HubBindingError,
   effectiveHubBindingScope,
   hubBindingFile,
-  readHubBinding,
+  loadHubBinding,
 } from "../hub-binding.ts";
 import { describeHubConnection } from "../hub-identity.ts";
 import type { InstallProbe } from "../kxm-install-kind.ts";
@@ -280,10 +280,12 @@ export function runtimeFrom(ctx: CliContext, command: Command): Runtime {
   const envServerUrl = ctx.env.KXM_SERVER_URL?.trim();
   let boundHubUrl: string | undefined;
   try {
-    boundHubUrl = readHubBinding(ctx.env)?.url;
+    const loaded = loadHubBinding(ctx.env);
+    if (loaded.warning) ctx.io.stderr(`kxm: ${loaded.warning}\n`);
+    boundHubUrl = loaded.record?.url;
   } catch (error) {
     if (error instanceof HubBindingError) {
-      ctx.io.stderr(`kxm: ignoring malformed hub binding at ${hubBindingFile(ctx.env)}; run kxm hub bind <url> again\n`);
+      ctx.io.stderr(`kxm: ignoring malformed hub binding at ${hubBindingFile(ctx.env)}; falling back to the local hub. Run kxm hub bind <url> again\n`);
     } else {
       throw error;
     }

package/plugins/kxm/src/cli.ts

@@ -1374,7 +1374,8 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
     .option("--token-env <name>", "Environment variable that holds the hub token; the token is not stored")
     .option("--token-command <command>", "Program that prints the hub token; the token is not stored")
     .option("--key-op <ref>", "op:// reference for the hub token; resolved with op read, never stored")
-    .action(async function hubBindAction(this: Command, url: string, options: { cloud?: boolean; tokenEnv?: string; tokenCommand?: string; keyOp?: string }) {
+    .option("--force", "Bind even when the URL is not a kxm hub")
+    .action(async function hubBindAction(this: Command, url: string, options: { cloud?: boolean; tokenEnv?: string; tokenCommand?: string; keyOp?: string; force?: boolean }) {
       result.code = await cmdHubBind(runtimeFrom(ctx, this), url, options);
     });
   addGlobalOptions(hub.command("unbind").description("Remove this machine's hub binding")).action(bind(cmdHubUnbind));