@kontextmind/kxm 0.7.166 → 0.7.168

package/docs/operations.md

@@ -88,16 +88,32 @@ kxm hub bind --cloud \
   http://127.0.0.1:17331
 ```
 
-Expected output:
+Expected output when `KXMD_HUB_TOKEN` is set:
 
 ```text
 bound hub http://127.0.0.1:17331 · remote · health=on · token is not stored
 hub health=true ready=true · remote hub · mode=cloud project=prj_example (.kxm/config.yaml hub.cloud.project) key=env:KXMD_HUB_TOKEN
 ```
 
+With only `--token-command`, and `KXMD_HUB_TOKEN` unset, `kxm hub view` prints
+`key=token-command`. It names the source that would actually supply the token:
+`env:<NAME>` only when that variable is non-empty, otherwise `op:<ref>`,
+`token-command`, `hub-env`, or `missing`. An unset variable is not reported as
+the source.
+
 `--token-env` and `--token-command` can be combined. A non-empty variable wins.
 Otherwise the command runs. The command is a program and arguments, not a shell
-pipeline (`|`, `&`, `;`, and redirection are refused).
+pipeline (`|`, `&`, `;`, and redirection are refused). `--token-command` is
+stored only in the machine-wide binding (`hub-binding.cloud.json` under the
+user state root). It is not written to `.kxm/config.yaml`. Config holds
+`key.op` and `key.env` references only.
+
+`https://hub.kxmd.dev` is behind an Authentik forward-auth proxy. Clients
+cannot use it: `GET /health` returns the login page (HTTP 200 HTML, or a 302).
+`kxm hub view` treats that as unhealthy (`health=false`, and the JSON `health`
+field is `{ "error": "auth_proxy" }`, not the HTML). `kxm hub bind` refuses
+with `hub_not_kxm` and writes nothing unless you pass `--force`. The supported
+client path is the SSH forward above.
 
 <details><summary>PowerShell</summary>
 
@@ -114,8 +130,8 @@ kxm hub view
 | | Local bind | `--cloud` bind |
 |---|---|---|
 | Loopback URL | Scope `loopback`. No credential required | Scope `remote`, including an SSH forward |
-| Token stored in `hub-binding.json` | No | No. The file names `tokenEnv` and/or `tokenCommand` |
-| Credential later commands send | `KXM_AUTH_TOKEN`, then the active mode's key reference in `.kxm/config.yaml`, then this machine's hub-env | The active mode's key reference, then the binding's named source. Hub-env is not a fallback |
+| Token stored in the binding | No | No. `hub-binding.cloud.json` names `tokenEnv` and/or `tokenCommand`. `hub-binding.json` stays a three-key local record, or is omitted, so a 0.7.159 reader does not throw |
+| Credential later commands send | Agent commands use `KXM_AUTH_TOKEN`, then `hub.local` `key.env` / `key.op`, then this project's saved project token. They never use the hub-env admin token (`project_token_missing`). `kxm hub view` and `kxm tenant status` may use the admin token | The active mode's key reference, then the binding's named source. Hub-env is not a fallback |
 | Missing source | Agent commands report `project_token_missing` and name the project id that was sent | `cloud_token_missing` or `cloud_token_command_failed`. The local admin token is not sent |
 | `kxm hub start` from an extension | May start a local hub | Does not start a local hub when the forward is down (`cloud_hub_unreachable`) |
 
@@ -124,6 +140,47 @@ kxm hub view
 all use that source. `kxm agent worker` puts `KXM_AUTH_TOKEN` in the child
 process environment only. It does not write the token to disk.
 
+A local bind does not give agents the admin token from hub-env. Give them a
+project token in one of these ways:
+
+- On the client, export `KXM_AUTH_TOKEN` to that project's token, or set
+  `hub.local.key.env` / `hub.local.key.op` in `.kxm/config.yaml`.
+- On the hub, map the project id in `hub.projects` (an `op://` reference or an
+  environment variable name) or in `KXM_PROJECT_TOKENS`, keyed by the same id
+  the client sends.
+
+### Where to store tokens
+
+Keep hub admin and project tokens in 1Password and point KXM at `op://` references
+(`--key-op`, `key.op`, or `--token-command "op read op://..."`). Do not paste the
+token into `.kxm/config.yaml`, `hub-binding.json`, or `hub-binding.cloud.json`.
+
+A hub host that has no `op` binary should take the token from the environment
+or from a systemd credentials file. The unit in
+[Supervise the hub and Runtime](operations/deploy.md#the-hub) loads
+`EnvironmentFile=/etc/kxm/hub.env` (mode 0600) for `KXM_AUTH_TOKEN` and
+`KXM_PROJECT_TOKENS`.
+
+### Restart after an upgrade, and before a cloud bind
+
+Restart the Runtime supervisor, the hub, and workers after upgrading and before
+`kxm hub bind --cloud`:
+
+```bash
+kxm runtime stop
+kxm hub stop
+kxm runtime start
+kxm hub start
+```
+
+A 0.7.159 supervisor treats any extra key in `hub-binding.json` as
+`malformed hub binding` and stops syncing. This release keeps cloud fields in
+`hub-binding.cloud.json` and leaves `hub-binding.json` as a three-key local
+record, or omits it. An older reader then keeps the local hub instead of
+throwing. A binding newer than this build is ignored with a warning, and sync
+continues as `no_hub` rather than stalling. Processes that were already running
+keep the binding they loaded at start, so restart them after the upgrade.
+
 The hub project id is the same value everywhere: `--project` or `KXM_PROJECT`,
 then the active mode's `project` in `.kxm/config.yaml`, then the `id` in
 `.kxm/project.yaml`, then `package.json` `name`, then the directory name.
@@ -147,7 +204,8 @@ hub:
       op: op://Private/kxm/local-project-token
       env: KXM_LOCAL_PROJECT_TOKEN
   cloud:
-    url: https://hub.kxmd.dev
+    # Clients use an SSH forward. https://hub.kxmd.dev is an Authentik login page.
+    url: http://127.0.0.1:17331
     project: prj_example
     key:
       op: op://Private/kxmd/project-token
@@ -167,7 +225,8 @@ with `hub_config_invalid`.
 `kxm hub bind` and `kxm hub bind --cloud` write the mode, URL, project id, and
 key reference. `--key-op` is the `op://` reference for either mode.
 `--token-env` names the variable for either mode. `--token-command` stays
-cloud-only. `kxm hub view` prints the mode, URL, project id, and key source.
+cloud-only, and only in `hub-binding.cloud.json`, not in this file.
+`kxm hub view` prints the mode, URL, project id, and key source.
 It does not print the token. `kxm hub unbind` removes the binding and
 `hub.mode`, and leaves the `local` and `cloud` blocks in place.
 
@@ -185,7 +244,8 @@ send the `.kxm/project.yaml` id and the hub has no token for it.
 kxm hub unbind
 ```
 
-Unbind deletes `hub-binding.json` and clears `hub.mode` in `.kxm/config.yaml`.
+Unbind deletes `hub-binding.json` and `hub-binding.cloud.json`, and clears
+`hub.mode` in `.kxm/config.yaml`.
 The `local` and `cloud` blocks stay, so the next bind can switch mode again.
 It does not delete hub-env, and it does not close the SSH forward. Stop the
 forward by ending the `ssh -N` session.
@@ -200,6 +260,9 @@ forward by ending the `ssh -N` session.
 | `cloud_token_command_failed` | `op` exited non-zero, timed out, or printed more than one line | Run the same command in a terminal and sign in to 1Password. Do not paste the token into the binding |
 | Clients through one SSH host get locked out together | The hub rate-limits by agent id, otherwise by source address. Every forward from one SSH session shares `127.0.0.1` on the hub. `sshd` `MaxStartups` and `MaxSessions` can refuse new forwards first | Give each long-lived agent its own name. Raise the SSH limits on that host if many people share one jump host. Do not point two tenants at one hub |
 | `kxm hub view` says `loopback` for the forward | `--cloud` was omitted | Bind again with `--cloud`. `KXM_SERVER_URL` overrides the binding URL and is labeled on its own |
+| `hub_not_kxm`, or `kxm hub view` prints `auth proxy` with `health=false` | The URL is an Authentik (or other) login page, or a 30x redirect, not a kxm hub. `https://hub.kxmd.dev` is that case | Bind `http://127.0.0.1:17331` through the SSH forward. `--force` writes the binding anyway and is not a working client path |
+| `key=env:KXMD_HUB_TOKEN` while that variable is unset | An older `kxm hub view` named the configured variable even when it was empty | Upgrade. The line names `token-command`, `op:<ref>`, `hub-env`, or `missing` for the source that actually supplies the token |
+| `malformed hub binding` and sync stops after a cloud bind | A supervisor older than this release read cloud fields in `hub-binding.json` | Upgrade, then restart the supervisor, hub, and workers before binding `--cloud` again |
 
 ## Next steps
 

package/docs/reference/cli-reference.md

@@ -477,12 +477,12 @@ Starts, inspects, and stops the local KXM hub, and binds this machine to a hub.
 kxm hub view
 ```
 
-Calls `GET /health` and `GET /ready` on the target hub and reports whether the URL is loopback or remote, plus the mode, project id, and key source in effect. The key source is an environment variable name or an `op://` reference. The token is not printed.
+Calls `GET /health` and `GET /ready` on the target hub and reports whether the URL is loopback or remote, plus the mode, project id, and key source in effect. A probe counts only when the response is JSON (`application/json`, or `text/plain` with a JSON object) of the hub shape: `/health` is `{ "ok": true, "agents": <number> }` and `/ready` is `{ "ok": true, "storage": "sqlite"|"memory" }`. An HTTP 200 HTML login page, or a 30x redirect, is not healthy. The JSON `health` and `ready` fields then hold `{ "error": "auth_proxy" }` and never the HTML. The key source is the one that would supply the token: `env:<NAME>` only when that variable is non-empty, `op:<ref>`, `token-command`, `hub-env`, or `missing`. The token is not printed.
 
 No command-specific options.
 
 - Needs a hub to succeed. Reads only.
-- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `identity` (`mode`, `modeSource`, `url`, `urlSource`, `project`, `projectSource`, `keySource`), `health`, `ready`. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes.
+- JSON keys: `target` (`url`, `scope`, and `source: "env"` when `KXM_SERVER_URL` overrides a binding), `identity` (`mode`, `modeSource`, `url`, `urlSource`, `project`, `projectSource`, `keySource`), `health`, `ready`. An unreachable hub reports `{"error":"hub_unreachable"}` for both probes. An auth proxy or redirect reports `{"error":"auth_proxy"}`.
 - Exit 0 when both probes succeed, 1 otherwise. A cloud mode with no resolvable key exits 2 with `cloud_token_missing`.
 
 ```bash
@@ -569,15 +569,16 @@ kxm hub stop --wait-ms 8000 --json
 ### `kxm hub bind`
 
 ```text
-kxm hub bind <url> [--cloud] [--token-env <name>] [--token-command <command>] [--key-op <op://vault/item/field>]
+kxm hub bind <url> [--cloud] [--token-env <name>] [--token-command <command>] [--key-op <op://vault/item/field>] [--force]
 ```
 
-Binds this machine to a running hub by writing `hub-binding.json` under the user state root and the non-secret endpoint (mode, URL, project id, key reference) into `.kxm/config.yaml`, then probes the hub's health for up to 300 ms. Every hub client uses that endpoint when `KXM_SERVER_URL` is unset. The token is never written.
+Binds this machine to a running hub by writing the binding under the user state root and the non-secret endpoint (mode, URL, project id, key reference) into `.kxm/config.yaml`, then probes the hub's health for up to 300 ms. A local bind writes `hub-binding.json` (`schema`, `url`, `boundAt` only). A `--cloud` bind writes `hub-binding.cloud.json` and leaves a three-key local file in place, or omits `hub-binding.json`, so a 0.7.159 reader does not throw `malformed hub binding` and stop sync. `--token-command` is stored only in that cloud file, not in `.kxm/config.yaml`. Every hub client uses that endpoint when `KXM_SERVER_URL` is unset. The token is never written.
 
 - Arguments: `<url>`, Hub base URL (http or https).
 - A URL with credentials, a query, a fragment, or a scheme other than http or https fails with `hub_url_invalid` (exit 2).
 - A remote (non-loopback) URL is refused with `hub_bind_unauthenticated` (exit 2, `nextAction: "export_kxm_auth_token"`) unless a credential for the current project resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`. A malformed record fails with `hub_credential_unreadable` (exit 2). A loopback URL without `--cloud` still binds with no credential.
 - `--cloud` marks the binding remote even when the URL is a loopback forward. It requires `--token-env`, `--token-command`, `--key-op`, or a combination. The token is not written. A non-empty variable wins; otherwise an `op://` reference is read with `op read`, or the command runs. `--token-command` without `--cloud` fails with `cloud_flag_required`. `--token-env` and `--key-op` are also valid on a local bind and are stored only as references in config. A missing cloud source later fails with `cloud_token_missing` and does not fall back to hub-env. See [Cross-box peer attach](../operations.md#cross-box-peer-attach).
+- The probe accepts a kxm `/health` body. A timeout (`health=unknown`) or a connection failure (`health=off`) still writes the binding. An HTML login page or a 30x redirect is `hub_not_kxm` (exit 2, `kind` `auth_proxy` or `redirect`) and writes nothing. The error names an auth proxy or a redirect. `--force` writes anyway. `https://hub.kxmd.dev` is an Authentik login page; clients use the SSH forward at `http://127.0.0.1:17331`.
 - Mutates the binding file and `.kxm/config.yaml`. `--dry-run` validates and prints the plan without writing.
 - JSON keys: `url`, `scope`, `file`, `configFile`, `project`, `health` (`on`, `off`, or `unknown`), `probeMs`. A cloud bind also returns `cloud`, and `tokenEnv` or `tokenCommand` when set.
 
@@ -984,7 +985,20 @@ Checks for or applies a KXM operator package update, and runs the native updater
 
 - Arguments: `[harness]`, Harness id (default: every detected harness).
 - `--check` cannot be combined with any other update flag or a harness (exit 2, `scope_conflict`), and at most one of `--self`, `--extensions`, `--models` is allowed (exit 2).
-- From a source checkout, `--check` reports the running version without network access, and `--kxm` is refused (exit 2, `install_kind_source`) with an instruction to `git pull`. Only npm-global installs can apply `--kxm`; other install kinds exit 2 with `install_kind_<kind>`. A GitHub release must publish a sha256 digest for `kxm-<version>.tgz` or the install fails closed (`release_digest_missing`, `release_digest_mismatch`).
+- From a source checkout, `--check` reports the running version without network access, and `--kxm` is refused (exit 2, `install_kind_source`) with an instruction to `git pull`. Only npm-global installs can apply `--kxm`; other install kinds exit 2 with `install_kind_<kind>`. A GitHub release must publish a sha256 digest for `kxm-<version>.tgz` or the install fails closed (`release_digest_missing`, `release_digest_mismatch`). When `gh` is missing, the github source downloads that same asset with `curl --fail --silent --show-error --location` and still verifies the digest before `npm install -g`.
+
+On a host with neither `gh` nor a working `kxm`, download and check it yourself:
+
+```bash
+version=0.7.166
+curl --fail --silent --show-error --location \
+  --output "kxm-${version}.tgz" \
+  "https://github.com/kontextmind/kxm/releases/download/v${version}/kxm-${version}.tgz"
+# Compare with the sha256 digest published on the GitHub release asset.
+sha256sum "kxm-${version}.tgz"
+npm install --global --omit=peer "./kxm-${version}.tgz"
+```
+
 - Settings come only from `update.yaml` under the user state root (`auto: true` enables auto-apply); a project `.kxm/update.yaml` is ignored with a warning.
 - Without `--check` or a lone `--kxm`, KXM probes harnesses (as `harness list` does) and runs each updater for the selected scope. An unknown harness id exits 2 (`unknown_harness` step); a failed step exits 1.
 - Honors `--dry-run`: steps are planned, not run, and the cached update notice is not refreshed.
@@ -1612,7 +1626,7 @@ Create a KXM run without executing steps. The run pins the project's `homeRuntim
 - Refuses `--workspace` (exit 2, `workspace_option_unsupported`).
 - Needs a KXM project. Starts and uses the Runtime; no hub needed. Honors `--dry-run`, which validates the project and prints the plan without starting the supervisor.
 - JSON keys: `idempotent`, `run` (`runId`, `homeRuntimeId`, `status`, `configRevision`), `supervisor` (`runtimeId`, `port`, `started`), and `execution` (`status: not_started`, `mode: live`, `defaultHarness`, `authentication: not_checked`, `prerequisites`, `nextSteps`). Dry run: `projectRoot`, `workflowId`, `configRevision`, `defaultHarness`, `prerequisites`. The obsolete `phase: pre-3a` field is no longer returned.
-- Errors: `workflow_required` (exit 2), `project_required`, `run_workflow_unknown`, `brief_and_prompt`, `brief_unreadable`, `lane_missing`, `lane_run_open`, `run_failed` with `issues` (any invalid file in the project fails the load, for example `gate_outcome_impossible`), `run_io_failed` (exit 1).
+- Errors: `workflow_required` (exit 2), `project_required`, `run_workflow_unknown`, `brief_and_prompt`, `brief_unreadable`, `lane_missing`, `lane_run_open`, `run_failed` with `issues` (any invalid file in the project fails the load, for example `gate_outcome_impossible`), `run_io_failed` (exit 1). `project_home_conflict` means this checkout is not the registered home for that project id: a different repository already owns it, the home runtime is immutable, or the primary checkout is already the home row. Use the original checkout, or a worktree of that repository. Do not copy the project id into an unrelated clone, and do not delete the database. `runtime_schema_newer` means the store was written by a newer release than this build. Upgrade KXM. Do not delete the database.
 - The `default` workflow that `kxm init` writes does not set `limits.maxAgentTimeMs`, so it can be driven. A workflow that sets that limit is created, but `kxm runs drive` refuses it with `run_handoff_required` (`limit_unsupported`); projects from older `kxm init` templates carry it on `default`.
 
 ```bash
@@ -1826,6 +1840,7 @@ No command-specific options.
 - Reads only. Never starts the supervisor.
 - JSON keys: `running`, `runtimeId`, `pid`, `port`, `state`, `heartbeatAt`, `startedAt`, `sync`.
 - Exit 0 when running, 1 when not (the JSON still says `ok: true`).
+- When the supervisor process is up but `GET /v1/sync/status` fails, the text line is `sync: the supervisor is running but did not answer /v1/sync/status`. The usual causes are a hung supervisor, a token the status command does not hold, or a supervisor started before an upgrade. `kxm runtime stop` and `kxm runtime start` replace it. A binding this build cannot read is a warning and `no_hub`, not a stalled sync; restart after upgrading and before a cloud bind. See [Check sync status](../operations/runtime-sync.md#check-sync-status).
 
 ```bash
 kxm runtime status

package/docs/reference/config-reference.md

@@ -1311,6 +1311,8 @@ no recorded cost is never ready.
 ```yaml
 # .kxm/config.yaml (project scope) or ~/.config/kxm/config.yaml (user scope).
 # The project file wins. Key fields are references, never tokens.
+# --token-command is not a config field. It lives only in the machine-wide
+# hub-binding.cloud.json written by `kxm hub bind --cloud`.
 hub:
   autoStart: background        # background | off
   mode: local                  # local | cloud
@@ -1321,7 +1323,8 @@ hub:
       op: op://Private/kxm/local-project-token
       env: KXM_LOCAL_PROJECT_TOKEN
   cloud:
-    url: https://hub.kxmd.dev
+    # Clients use an SSH forward. https://hub.kxmd.dev is an Authentik login page.
+    url: http://127.0.0.1:17331
     project: prj_example
     key:
       op: op://Private/kxmd/project-token

package/docs/start/install.md

@@ -8,7 +8,7 @@ KXM has three parts you can install: the `kxm` command-line tool, the Claude Cod
 - Git.
 - Claude Code, if you want the plugin.
 - Pi, if you want Pi agents. Install it with `npm install --global @earendil-works/pi-coding-agent` and sign in to a model provider as the [Pi documentation](https://pi.dev/docs/latest) describes.
-- The GitHub CLI (`gh`), only if you plan to update with `kxm update --kxm`, which downloads the release tarball from GitHub.
+- The GitHub CLI (`gh`), only if you plan to update with `kxm update --kxm` from the GitHub source. When `gh` is missing, that command falls back to curl and still checks the release checksum. The manual curl commands are in [Upgrade KXM](../operations/upgrade.md#update-the-cli-without-gh).
 
 ## Choose what to install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.166",
+  "version": "0.7.168",
   "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.166",
+  "version": "0.7.168",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/claude-hook.js

@@ -556,6 +556,9 @@ function resolveUserStateRoot(env) {
 function hubBindingFile(env = process.env) {
   return join3(resolveUserStateRoot(env), "hub-binding.json");
 }
+function hubBindingCloudFile(env = process.env) {
+  return join3(resolveUserStateRoot(env), "hub-binding.cloud.json");
+}
 function validateHubUrl(raw) {
   let parsed;
   try {
@@ -618,33 +621,35 @@ function isAbortError(error) {
     error && typeof error === "object" && ("name" in error && error.name === "AbortError" || "code" in error && error.code === "ABORT_ERR")
   );
 }
-function readHubBinding(env = process.env) {
-  const file = hubBindingFile(env);
-  if (!existsSync4(file)) return void 0;
+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) {
+  mkdirSync3(dirname(file), { recursive: true, mode: 448 });
+  const temporary = join3(dirname(file), `.${file.endsWith("cloud.json") ? "hub-binding-cloud" : "hub-binding"}-${process.pid}.tmp`);
+  try {
+    writeFileSync2(temporary, `${JSON.stringify(value, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+function parseBindingObject(file) {
+  if (!existsSync4(file)) return new HubBindingError(`missing hub binding at ${file}`);
   let parsed;
   try {
     parsed = JSON.parse(readFileSync4(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}`);
-  }
-  let url;
-  try {
-    url = validateHubUrl(row.url);
-  } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return 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) {
@@ -666,36 +671,163 @@ 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 (!existsSync4(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 record = cloudRecordFromRow(file, parsed, url, parsed.boundAt);
+  if (!record) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return { record, legacyCloud: true };
+}
+function loadHubBinding(env = process.env) {
+  const cloudFile = hubBindingCloudFile(env);
+  const cloud = interpretBindingFile(cloudFile);
+  if (cloud.warning && !cloud.record) {
+    const local = existsSync4(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 main2 = interpretBindingFile(hubBindingFile(env));
+  if (main2.legacyCloud && main2.record) {
+    writeBindingJson(cloudFile, main2.record);
+    rmSync(hubBindingFile(env), { force: true });
+    return {
+      record: main2.record,
+      warning: bindingFallbackWarning(
+        hubBindingFile(env),
+        "stored a cloud bind in the pre-0.7.160 file"
+      )
+    };
+  }
+  return { ...main2.record ? { record: main2.record } : {}, ...main2.warning ? { warning: main2.warning } : {} };
+}
+function readHubBinding(env = process.env) {
+  return loadHubBinding(env).record;
+}
+function contentTypeBase(header) {
+  return (header ?? "").split(";")[0].trim().toLowerCase();
+}
+function looksLikeHtml(contentType, body) {
+  if (contentType === "text/html" || contentType === "application/xhtml+xml") return true;
+  const sample = body.slice(0, 800).trim().toLowerCase();
+  return sample.startsWith("<!doctype html") || sample.startsWith("<html") || sample.includes("<form") && (sample.includes("login") || sample.includes("authentik") || sample.includes("password"));
+}
+function jsonObject(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+function hubEndpointShape(role, body) {
+  if (role === "health") return body.ok === true && typeof body.agents === "number";
+  return body.ok === true && (body.storage === "sqlite" || body.storage === "memory");
+}
+function classifyHubResponse(input) {
+  const contentType = contentTypeBase(input.contentType);
+  if (input.status >= 300 && input.status < 400) {
+    return {
+      ok: false,
+      status: input.status,
+      kind: "redirect",
+      detail: `HTTP ${input.status} redirect; this looks like an auth proxy or a redirect, not a kxm hub`,
+      body: { error: "auth_proxy", detail: `HTTP ${input.status} redirect` }
+    };
+  }
+  if (looksLikeHtml(contentType, input.bodyText)) {
+    return {
+      ok: false,
+      status: input.status,
+      kind: "auth_proxy",
+      detail: `HTTP ${input.status} returned an HTML login page${contentType ? ` (${contentType})` : ""}; this looks like an auth proxy, not a kxm hub`,
+      body: { error: "auth_proxy", detail: "HTML login page" }
+    };
+  }
+  const jsonType = contentType === "application/json" || contentType === "text/plain" || contentType === "";
+  const body = jsonType ? jsonObject(input.bodyText) : void 0;
+  if (body && hubEndpointShape(input.role, body) && input.status >= 200 && input.status < 300) {
+    if (contentType !== "" && contentType !== "application/json" && contentType !== "text/plain") {
+      return {
+        ok: false,
+        status: input.status,
+        kind: "not_hub",
+        detail: `HTTP ${input.status} content-type ${contentType} is not application/json`,
+        body: { error: "not_hub", detail: contentType }
+      };
+    }
+    return { ok: true, status: input.status, kind: "hub", detail: "kxm hub", body };
+  }
+  const typeNote = contentType && contentType !== "application/json" ? ` content-type ${contentType}` : "";
+  return {
+    ok: false,
+    status: input.status,
+    kind: "not_hub",
+    detail: `HTTP ${input.status}${typeNote} is not a kxm hub ${input.role} response`,
+    body: { error: "not_hub", detail: `HTTP ${input.status}${typeNote}` }
+  };
+}
+async function readHubEndpoint(url, role, fetchImpl, init = {}) {
+  try {
+    const response = await fetchImpl(`${url}/${role}`, {
+      ...init.headers ? { headers: init.headers } : {},
+      ...init.signal ? { signal: init.signal } : {},
+      redirect: "manual"
+    });
+    const bodyText = await response.text();
+    return classifyHubResponse({
+      role,
+      status: response.status,
+      contentType: response.headers.get("content-type"),
+      bodyText
+    });
+  } catch (error) {
+    if (isAbortError(error)) {
+      return { ok: false, status: 0, kind: "timeout", detail: "no reply within the probe budget", body: { error: "hub_unreachable" } };
+    }
+    return { ok: false, status: 0, kind: "unreachable", detail: "nothing answered", body: { error: "hub_unreachable" } };
+  }
+}
 async function probeHubHealth(url, fetchImpl, timeoutMs = HUB_HEALTH_PROBE_MS) {
   const started = Date.now();
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const response = await fetchImpl(`${url}/health`, { signal: controller.signal });
-    if (!response.ok) return { health: "unknown", probeMs: Date.now() - started };
-    let body;
-    try {
-      body = await response.json();
-    } catch {
-      return { health: "unknown", probeMs: Date.now() - started };
-    }
-    if (body && typeof body === "object" && body.ok === true) {
-      return { health: "on", probeMs: Date.now() - started };
-    }
-    return { health: "unknown", probeMs: Date.now() - started };
-  } catch (error) {
-    return { health: isAbortError(error) ? "unknown" : "off", probeMs: Date.now() - started };
+    const verdict = await readHubEndpoint(url, "health", fetchImpl, { signal: controller.signal });
+    const health = verdict.kind === "hub" ? "on" : verdict.kind === "unreachable" ? "off" : "unknown";
+    return { health, probeMs: Date.now() - started, kind: verdict.kind, detail: verdict.detail, status: verdict.status };
   } finally {
     clearTimeout(timer);
   }
 }
-var HUB_BINDING_SCHEMA, HUB_HEALTH_PROBE_MS, CloudTokenError, TOKEN_ENV_NAME, HubBindingError;
+var HUB_BINDING_SCHEMA, HUB_HEALTH_PROBE_MS, CloudTokenError, TOKEN_ENV_NAME, HubBindingError, LEGACY_BINDING_KEYS, BINDING_KEYS;
 var init_hub_binding = __esm({
   "plugins/kxm/src/hub-binding.ts"() {
     "use strict";
@@ -716,6 +848,8 @@ var init_hub_binding = __esm({
         this.name = "HubBindingError";
       }
     };
+    LEGACY_BINDING_KEYS = ["schema", "url", "boundAt"];
+    BINDING_KEYS = /* @__PURE__ */ new Set([...LEGACY_BINDING_KEYS, "cloud", "tokenEnv", "tokenCommand"]);
   }
 });