@kontextmind/kxm 0.7.51 → 0.7.52

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.51",
+      "version": "0.7.52",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -6,17 +6,52 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
-- **Terminal component kit package:** `@kontextmind/tui` (`packages/core/tui`, also
-  exposed as the `@kontextmind/kxm/tui` export) ships the reusable Pi-renderer-based
-  terminal components in the package layer shape (`src/{types,tui,services,adapters,exports}`,
-  `tests/{unit,helpers}`), enforced by `test/core/package-layers.test.ts`.
-- **Per-package workspace tooling:** nx + Bun workspace wiring (`nx.json`,
-  `bunfig.toml`, `packages/*/project.json`, `scripts/build-package.mjs`) with
-  `npm run build:packages|test:packages|check:packages`. Bun is installer and task
-  runner only; tests, the hub, and the CLI remain on Node.
+- **Per-tenant hosting operations, and a backup that covers the whole state set.**
+  `docs/operations.md` gained a *Per-tenant hosted deployment* section (one tenant = one box
+  = one hub; loopback-only hub and supervisor; the tenant's proxy owns TLS and the browser
+  session; a reverse-proxy contract states what must hold without shipping generated proxy
+  config) and a rewritten *Backup and restore* that enumerates tenant state **by root**,
+  because the roots are not interchangeable and two of them are easy to mistake for one:
+  `$R` the fixed checkout `.kxm` tree (project, model, role, route, price and provenance
+  definition, environment, goals, tasks, memory, improvement candidates, skills — none of
+  which follow any workspace override); `$D` the workspace directories (config, logs,
+  assets, state — moved by `--workspace`/`KXM_WORKSPACE_DIR`, each individually
+  overridable, and `--workspace` ignores those overrides); `$W` the workspace state
+  directory (hub database, worker routing and recovery manifests, Pi sessions); `$S`
+  host-local machine state (`KXM_STATE_HOME`, absolute or rejected: Runtime `registry.db`
+  holding the supervisor claim as a registry row, per-project `run-events.db` **and its
+  full-filename `.run-prompts.json` sidecar**, repository bindings, `update.yaml`, hub
+  binding and credential records); `$C` user configuration; and `$T` federated telemetry,
+  resolved independently of `$C` and written by an exporter that currently has no
+  production caller. It separates recovery-critical manifests from Pi model histories whose
+  backup is an existing policy **choice**, marks what is disposable (PID and claim files,
+  `session-brief.json`, the re-generable supervisor token), applies WAL consistency to
+  every SQLite store, records each override as part of the backup, and notes that a bound
+  member repository's own `.kxm/repo/` files live on that member's filesystem — so copying
+  the binding JSON alone is not a restore path for an external member. The previous recipe
+  stopped the hub and copied `kxm.db`, which is a hub-only backup: a restore can pass every
+  hub check and still lose run history, the prompts that explain it, the project definition,
+  and the bindings that make the box reproducible.
 
 ### Changed
 
+- **`kxm hub bind` no longer stores a remote URL it cannot authenticate to.** A remote
+  binding is a deliberate network decision, so it is now refused when no credential resolves
+  (explicit `KXM_AUTH_TOKEN`, or the persisted hub record's admin or project tokens) —
+  mirroring the rule the hub already applies to its own listener, which refuses to bind
+  beyond loopback without a token. The refusal carries `nextAction` and the same hint string
+  in both the JSON payload and the prose line, so `--json` consumers are not left with a bare
+  code and no way forward; a stored-but-unusable binding otherwise reads later like a
+  network fault and gets debugged as one.
+- **`kxm hub view` and the session brief label the binding `loopback` or `remote`.**
+  "Attached across a network" and "attached on this box" looked identical before, and only
+  one of them puts a bearer on a wire. `localhost`, `127.0.0.1`, `::1` and `*.localhost` are
+  loopback; `0.0.0.0`, LAN addresses and host names are remote. The **bind** guard is
+  scoped to remote URLs — a damaged host record must not cost a local operator their start,
+  and the first cut of the guard did exactly that. That is a statement about `hub bind`
+  only: other client paths resolve credentials whatever the scope, so loopback commands can
+  still fail on a malformed record.
+
 - **Naming sweep:** the retired `vnext` naming is gone from file and folder names,
   symbols, constants, schema `$id` segments, and error codes (`vnext_*` is now
   `initialization_failed`, `initialization_io_failed`, `wait_failed`); package and

package/docs/configuration.md

@@ -296,7 +296,7 @@ The current hub command groups are `agent`, `session`, `workflow`, `gate`, `hub`
 | `kxm gate github watch` | Poll required GitHub checks and post the existing signed signal |
 | `kxm init` | Create or validate a project; configuration remains project-owned and no package dogfood templates are copied |
 | `kxm hub view` | Check `/health` and `/ready` |
-| `kxm hub bind <url>` | Bind this machine to a running hub |
+| `kxm hub bind <url>` | Bind this machine to a running hub. A **remote** URL is refused unless a credential resolves (`KXM_AUTH_TOKEN`, or the persisted hub record); `kxm hub view` reports the binding as `loopback` or `remote` |
 | `kxm hub unbind` | Remove this machine's hub binding |
 | `kxm update --check` / `kxm update --kxm` | Check or apply a kxm operator package update from an npm-global install only. Other install kinds (source checkout, Pi git, Claude marketplace, npm-local, unknown) refuse `--kxm` and skip auto-apply. Source checkouts neither fetch nor nag. Default source is GitHub release tarballs; the release asset `kxm-<v>.tgz` must carry a sha256 digest or install fails closed. `source: npm` is for after the public package exists. Optional per-user `update.yaml` (`kxm.update.v1`, `auto` boolean) under the host state root (`KXM_STATE_HOME` / `%LOCALAPPDATA%\KXM` / macOS Application Support / XDG state) enables auto-apply on `kxm update`. A project `.kxm/update.yaml` is ignored with a warning. Notice also prints on `kxm hub start` (not from source) and on the session widget from cache |
 | `kxm dash` | Open the read-only SSE observer dashboard; non-TTY output is one ANSI-free snapshot |

package/docs/operations.md

@@ -144,28 +144,204 @@ Recommended alerts:
 - waiting-run count or workflow wait timeouts rise beyond the expected external-system latency.
 - quorum degradation approvals occur outside a declared incident or change window.
 
-## Backup and restore
-
-> **Hub-only today, and labelled as such.** The recipe below stops the hub and copies
-> `.kxm/state/kxm.db`. That is not the whole tenant state set: the Runtime keeps its own
-> `registry.db`, per-project event stores under the user state root, prompt sidecars,
-> bindings and configuration. A restore that follows only these steps can bring the hub back
-> while losing Runtime history. Queue step **S1** replaces this section with a stopped-state
-> procedure covering the full set, and **S5** proves it with one deployed restore before real
-> use; until S1 lands, treat this as the hub database only.
-
-SQLite runs in WAL mode. The safest simple backup is a coordinated copy while the hub is stopped:
-
-1. Stop the hub gracefully.
-2. Copy `.kxm/state/kxm.db` to protected backup storage.
-3. Keep the backup with the application version and configuration used to create it.
-4. Restart the hub and confirm `/ready` returns `ok: true`.
+## Per-tenant hosted deployment
+
+One tenant is one machine: one hub process, one Runtime supervisor, one SQLite state set.
+Tenancy is the box, not a table — the hub has no tenant column and no user accounts, and
+`kxm hub bind` still means *this machine's client attaches to that hub URL*. The portal
+(kontextmind/kxmd-portal) is the multi-tenant, multi-user surface; browsers never talk to
+the hub.
+
+Topology on the tenant box:
+
+```text
+browser ──HTTPS──▶ reverse proxy + Authentik ──▶ portal (users, sessions, tenant directory)
+                                                   │
+                                                   │  server-side, loopback
+                                                   ▼
+                                    hub 127.0.0.1:7331  ·  Runtime supervisor (loopback)
+```
 
-For online backups, use a SQLite-aware backup tool or snapshot the database, `-wal`, and `-shm` files consistently. A plain copy of only `kxm.db` while the service is writing may omit committed WAL data.
+1. **Service account, not root.** Run the hub and Runtime under a dedicated unprivileged
+   account. Workflow session isolation is a routing and cross-run safety mechanism, not a
+   sandbox against a hostile same-OS process (see
+   [architecture.md](architecture.md)); a model with shell access can reach anything its
+   own account can reach, so untrusted workers need separate accounts or containers.
+2. **Stable paths, declared explicitly** rather than inherited from a home directory:
+   `KXM_WORKSPACE_DIR`, `KXM_STATE_DIR`, `KXM_DATA_PATH`, `KXM_LOG_PATH`, and
+   `KXM_STATE_HOME` for the machine-level hub credential and binding records. Pin
+   `KXM_HOST=127.0.0.1`.
+3. **Loopback listeners only.** The hub and the supervisor expose no public port; nothing
+   is load-balanced across hubs. The hub keeps one writer per database.
+4. **One project, the slim workflow.** `kxm init` the workspace, then start the hub with
+   `kxm hub start` and confirm with `kxm hub view` — the status line reports the binding as
+   `loopback` or `remote`, so an operator can see which side of the trust line they are on
+   without reading files. `kxm hub bind` refuses a **remote** URL when the machine has no
+   credential to authenticate with, because a stored-but-unusable URL later reads as a
+   network fault and gets debugged as one.
+5. **Restart recovery is the existing one:** the PID claim file, dead-claim reclaim and
+   graceful `SIGTERM` shutdown described under *PID claims and restart recovery*. Do not
+   add a second service manager for the hub; use the tenant's existing one.
+
+### Reverse-proxy contract
+
+The tenant's proxy owns TLS and the browser session. KXM ships no proxy configuration,
+because a generated config reads as authoritative while one missing directive silently
+re-opens header forgery. What must hold, whatever the stack:
+
+- The hub and supervisor ports are **not** reachable from outside the box.
+- The proxy **strips** client-supplied identity, tenant, agent, caller and `Authorization`
+  headers before injecting its own validated values. The hub must never see a
+  browser-forged `x-kxm-agent-id`, `x-kxm-caller-id` or bearer.
+- The proxy **never injects the hub admin token on a user's behalf**. That flattens every
+  authenticated user in the tenant to hub admin and destroys attribution.
+- Machine credentials stay server-side in the portal process. A browser must not hold,
+  echo, or be redirected with a hub bearer.
+- `kxm hub bind` on a remote hub URL therefore requires an explicit credential, and a
+  refusal names the fix instead of only the failure.
+
+Example (illustrative shape — not generated config, not tested by this repository's CI):
+Authentik's embedded proxy answers a forward-auth subrequest per request; the tenant proxy
+`proxy_cache_bypass`/`auth_request`-style gate allows only the portal's routes and keeps
+`/v1/*` and the supervisor off the public interface entirely.
 
-To restore, stop the hub, preserve the current files for rollback, place the restored database at `.kxm/state/kxm.db` or the configured `KXM_DATA_PATH`, and start the same or newer compatible release. The runtime refuses a database whose schema version is newer than it supports.
+## Backup and restore
 
-Test restoration periodically. A backup that has never been restored is not a verified recovery path.
+> **This section covers the whole tenant state set, on purpose.** A recipe that copies only
+> `.kxm/state/kxm.db` is a hub-only backup: it silently omits the Runtime registry,
+> per-project event stores, prompt sidecars, bindings and configuration, so a restore that
+> passes every hub check can still lose run history. Verify with a real restore before first
+> hosted use, not after an incident.
+
+SQLite runs in WAL mode, so a consistent copy requires a stopped service (or a SQLite-aware
+online tool). Stop the hub and the Runtime supervisor first.
+
+**What a tenant backup contains.** Six roots — one fixed to the checkout, one for the
+workspace directories, and four more that can each sit anywhere — and confusing them is how
+a backup goes missing while looking complete:
+
+- **`$S`** — host-local machine state: `$KXM_STATE_HOME` **when set**, and it must be an
+  absolute path — a relative value is **rejected** with `local_state_root_not_absolute`, not
+  redirected. When unset, the default is `~/.local/state/kxm` on Linux (honouring
+  `XDG_STATE_HOME`), `~/Library/Application Support/KXM` on macOS, or
+  `%LOCALAPPDATA%\KXM` on Windows. The silent case to know about is a relative
+  `XDG_STATE_HOME`/`LOCALAPPDATA` **base**: that falls back to the default without error,
+  so a backup path derived from it can quietly point somewhere else.
+- **`$R`** — the checkout root. Everything below it is **fixed to the repository and does
+  not follow any workspace override**: `$R/.kxm/project.yaml`, `$R/.kxm/config.yaml`,
+  `$R/.kxm/agents/`, `$R/.kxm/workflows/`, `$R/.kxm/gates.yaml`, `$R/.kxm/roles/`,
+  `$R/.kxm/role-hosts.yaml` (or `.json`), `$R/.kxm/producers.yaml`, `$R/.kxm/roster.yaml`,
+  `$R/.kxm/routes.yaml`, `$R/.kxm/prices.yaml`, `$R/.kxm/repo/`,
+  `$R/.kxm/template-provenance.yaml`, plus the durable work and learning records
+  `$R/.kxm/goals/`, `$R/.kxm/tasks/`, `$R/.kxm/memory/` (with `memory/candidates/`) and
+  `$R/.kxm/skills/`. Conflating these with the next root is how a backup omits the project
+  definition while believing it copied the project.
+- **`$D`** — the **workspace directories**, resolved from `--workspace` or
+  `KXM_WORKSPACE_DIR`, else `$R/.kxm`, relative to `KXM_WORKDIR`/cwd:
+  `$D/config`, `$D/logs`, `$D/assets`, `$D/state`. `--workspace` **derives all four** and
+  ignores the per-directory variables; otherwise `KXM_CONFIG_DIR`, `KXM_LOGS_DIR`,
+  `KXM_ASSETS_DIR` and `KXM_STATE_DIR` override each one independently, and
+  `KXM_DATA_PATH`/`KXM_LOG_PATH` move two files again inside that. `$D` therefore **defaults to `$R/.kxm`**, and the two
+  move together only when the *workspace* is relocated: `KXM_WORKSPACE_DIR` (or
+  `--workspace`) moves `$D` and every default beneath it, while `KXM_CONFIG_DIR`,
+  `KXM_LOGS_DIR`, `KXM_ASSETS_DIR`, `KXM_STATE_DIR`, `KXM_DATA_PATH` and `KXM_LOG_PATH`
+  move **their own target and nothing else** — `KXM_STATE_DIR=/srv/state` alone leaves `$D`
+  at `$R/.kxm` and shifts only `$W`. A backup that assumes one shared location starts
+  omitting the other in exactly that case, which is why every row below is labelled as a
+  default.
+- **`$W`** — the workspace *state* directory: `KXM_STATE_DIR` when set, else `$D/state`
+  (and `--workspace` derives it, ignoring that variable). It holds the
+  hub database, worker routing/recovery manifests and Pi sessions.
+- **`$C`** — user configuration: `KXM_USER_CONFIG_DIR`, else `~/.config/kxm`.
+- **`$T`** — federated telemetry output: an explicit global directory joined with
+  **`telemetry/`**, else `$XDG_CONFIG_HOME/kxm/telemetry`, else `~/.config/kxm/telemetry`.
+  It is built from `XDG_CONFIG_HOME`/`HOME`, **not** from `KXM_USER_CONFIG_DIR`, so `$T` can
+  land outside `$C`; and it is a *different file* from local accounting in `$D/logs`.
+
+| Path | Contents | Loss means |
+|---|---|---|
+| `$W/kxm.db` (+ `-wal`, `-shm`, or `KXM_DATA_PATH`) | hub store: agents, messages, workflow runs, checkpoints, gate evidence | hub history and delivery state |
+| `$S/runtime/registry.db` | Runtime registry, including the **supervisor identity and claim row** | which projects this Runtime knows; the claim is a registry row — there is no `supervisor.json` |
+| `$S/runtime/projects/<projectKey>/run-events.db` (+ `-wal`/`-shm`) | event-sourced run state, commands, drives, receipts, gate evidence, intake, coordinators, pause control | run history and every receipt that proves it |
+| `$S/runtime/projects/<projectKey>/run-events.db.run-prompts.json` | prompt text; the sidecar name appends to the **full** database filename | the prompts that explain the runs — restoring databases without sidecars is a partial restore |
+| `$S/projects/<control-root-hash>/repository-bindings.json` | host-local member repository paths | member bindings are host state, outside the project tree |
+| `$S/update.yaml` | release/update configuration consumed by the updater | the box reverts to defaults on the next update path |
+| `$W/pi-sessions/<workerKey>/{default,runs/<runId>}/` | Pi model histories | **optional by existing policy** (see *Workflow-specific Pi sessions*): never a system of record — decide and record, do not silently widen scope |
+| `$W/worker-session-binding-<workerKey>.json` (+ `.corrupt-*`), `worker-context-*.json`, `worker-recovery-*.json` | routing and recovery manifests | not optional: these are what make worker routing resumable after a restart |
+| `$R/.kxm/…` project definition: `project.yaml`, `config.yaml`, `agents/`, `models/`, `workflows/`, `gates.yaml`, `roles/`, `role-hosts.yaml` (or `.json`), `producers.yaml`, `roster.yaml`, `routes.yaml`, `prices.yaml`, `repo/`, `project/env.yaml`, `template-provenance.yaml` | project, role, route, price and provenance definition | the tenant stops being reproducible — and a restore without `roster.yaml`/`routes.yaml`/`prices.yaml` comes back with **different admission and cost behaviour** while reporting itself healthy |
+| `$R/.kxm/goals/`, `tasks/`, `memory/` (with `memory/candidates/`), `skills/` (candidate/promoted/rejected, history, patches) | durable work and learning records | open goals/tasks and approved memory disappear |
+| `$R/.kxm/candidates/` — improvement candidate JSON and their diffs, **default only**: `kxm improve report --out-dir` relocates this directory outside every root listed here | the improvement queue itself | proposed fixes nobody was told about |
+| each bound member repository's own `$memberRepo/.kxm/repo/repo.yaml` and `.kxm/repo/env.yaml` | member repository definition and environment | for **externally bound** members, the binding JSON alone is not enough — these files live on the member's own filesystem and need their own backup or an explicit, checked reconstruction prerequisite |
+| `$D/assets/` (default; `KXM_ASSETS_DIR` relocates it) — retrospectives, improvements, artifacts, evidence | exported evidence | provenance and the ability to audit a past decision |
+| `$D/logs/` (default; `KXM_LOGS_DIR` relocates the directory and `KXM_LOG_PATH` the hub log) and `$D/logs/telemetry.jsonl` | operator logs and **local** usage accounting — the spend numbers routing reports read | no local accounting to reconcile against |
+| `KXM_WORKER_LOG_PATH` / `KXM_AGENT_LOG_PATH` targets (defaulting under `$D/logs`) | per-worker lifecycle and raw Pi output | worker diagnostics; **separate overrides, not local accounting** |
+| `$T/model-metrics.jsonl` | **federated** metrics only. Absent almost everywhere: the exporter exists and `telemetry.federated` defaults to `true` in the shipped config, but **no hub or CLI path calls it today**, so absence is the normal state rather than evidence someone opted out. A different file from local accounting, which is `$D/logs/telemetry.jsonl` | cross-machine reporting continuity, and a privacy boundary worth naming: federated records are separate, with `anonymize` defaulting to `true` |
+| `$S/hub-binding.json`, `$S/hub-env.json`, `$C/session.token` | host hub URL, credentials, local session token | a re-bind and a token rotation. **Secrets:** prefer regeneration to shipping them off-box, and never commit them |
+| `$C` global roles/workflows/host configuration | user-level defaults | operator conventions |
+
+**Overrides are part of the backup record.** `KXM_WORKSPACE_DIR` (and the `--workspace`
+flag, which additionally **ignores** the per-directory variables) moves every `$D`
+**default** at once; a directory with its own override stays where that variable points.
+Neither moves `$R`, so the fixed project tree must still be backed up from the checkout even
+when the workspace was relocated elsewhere — and copying the whole checkout is what protects
+`$R`'s default locations, which is why an enumerated-paths backup should be re-checked
+against this table whenever a loader grows a file. `KXM_STATE_HOME` moves `$S`
+only if absolute. An explicit telemetry directory is likewise joined with `telemetry/`,
+not used verbatim.
+`KXM_DATA_PATH`, `KXM_STATE_DIR`, `KXM_CONFIG_DIR`, `KXM_ASSETS_DIR`, `KXM_LOGS_DIR`,
+`KXM_LOG_PATH`, `KXM_WORKER_LOG_PATH`, `KXM_AGENT_LOG_PATH` or an explicit telemetry
+directory each relocate one more thing. Record every override **with** the backup, or a
+restore lands somewhere the running service will not look.
+
+**Disposable, not backup material:** `session-brief.json`, `update-check.json`,
+`*.error`, PID/claim files such as `hub.pid` and `worker-<key>.pid`, and
+`supervisor.token` (host-local secret, re-generated on start). WAL-consistent copying or
+`VACUUM INTO` applies to **every** SQLite file above, not only the hub database.
+
+**Back up (stopped-state recipe):**
+
+1. Stop **both** services, confirm they are down, and **keep them down until the copy
+   finishes**. `kxm hub stop` covers the hub and its worker PID claims; the Runtime
+   supervisor is a **separate** process owning `registry.db` and the project event stores,
+   stopped by `kxm runtime stop` — and that call acknowledges shutdown *initiated*, not
+   databases closed. So: verify neither reports live, then suspend whatever would start them
+   again — the service manager's auto-restart, hub autostart on login, and any client that
+   would reconnect and begin new work (a bound CLI, MCP server or Pi worker restarting a
+   supervisor on demand). A manager that respawns the hub halfway through a copy produces a
+   backup that is internally inconsistent across files, which is precisely the failure mode
+   this recipe is otherwise careful about. Only then copy.
+2. Copy the whole set above as one tree — **every root**, `$R`, `$D`, `$W`, `$S`, `$C` and
+   `$T` — or take `VACUUM INTO` snapshots per database. **Snapshots replace the database
+   copies, not the file copy**: configuration, repository bindings, prompt sidecars,
+   routing manifests and update configuration are not databases, so a snapshot-only backup
+   reproduces exactly the failure this section exists to remove. The hub's own backup path already writes a hashed manifest and records
+   a schema version ceiling; keep that manifest with the files.
+3. Record the package version, configuration revision and schema versions beside the copy.
+   A restore that cannot state which release produced it is not a restore path.
+4. Keep at least one rotation, and bound retention explicitly — run events and prompt
+   sidecars grow, and unbounded retention is how a tenant box fills up.
+
+**Restore:**
+
+1. Stop the services. Move the current state aside rather than overwriting it.
+2. Place each file back at its recorded path under the right root — `KXM_DATA_PATH`, the
+   Runtime registry and each project event store **with its sidecar**, repository bindings
+   under `$S/projects/…`, config, and `$S/runtime/registry.db` so the supervisor claim
+   returns with it.
+3. Start the hub and confirm `/ready`, then `kxm hub view` — including that the reported
+   binding scope is what the environment actually is.
+4. Read back a run and its drive receipt, and confirm prompt text is present. Restoring
+   databases without their sidecars leaves runs whose prompts are gone; that is a partial
+   restore, not a success.
+
+The runtime refuses a database whose schema version is newer than it supports, so
+restore order is: matching-or-newer release, then data. Online backups need a
+SQLite-aware tool or a consistent snapshot of each database with its `-wal` and `-shm`;
+a plain copy of a live `kxm.db` can omit committed WAL data.
+
+Test restoration periodically. Routine unattended recovery (automated discovery of every
+Runtime store plus sidecars) is deliberately **not** claimed here: it is a tracked
+post-MVP item, and today this procedure is executed stopped and by hand.
 
 ## Upgrade and rollback
 

package/package.json

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

package/plugins/kxm/dist/cli.js

@@ -19657,6 +19657,21 @@ function readHubEnvRecord(env = process.env) {
     ...record.projectTokens !== void 0 ? { projectTokens: record.projectTokens } : {}
   };
 }
+function hasClientHubCredential(env = process.env, project) {
+  if (env.KXM_AUTH_TOKEN?.trim()) return true;
+  let record;
+  try {
+    record = readHubEnvRecord(env);
+  } catch (error) {
+    throw new HubEnvError(
+      `${error instanceof Error ? error.message : String(error)}; refusing to guess a credential \u2014 repair or remove ${hubEnvFile(env)}`
+    );
+  }
+  if (record?.authToken?.trim()) return true;
+  const tokens = record?.projectTokens ?? {};
+  if (project !== void 0) return typeof tokens[project] === "string" && tokens[project].trim().length > 0;
+  return Object.values(tokens).some((token) => typeof token === "string" && token.trim().length > 0);
+}
 function resolveClientHubAuthToken(env, project) {
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
@@ -26098,6 +26113,17 @@ function validateHubUrl(raw) {
   }
   return parsed.href.replace(/\/$/, "");
 }
+function hubBindingScope(url) {
+  let host;
+  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) {
   if (Number.isNaN(Date.parse(value))) return false;
   return value === new Date(value).toISOString();
@@ -45212,9 +45238,10 @@ var MAX_SESSION_BRIEF_PLANS = 5;
 var SESSION_BRIEF_SCHEMA = "kxm.session-brief.v1";
 var DEFAULT_SESSION_BRIEF_STALE_SECONDS = 5;
 function hubPrefix(hub) {
-  if (hub?.state === "on" || hub?.state === void 0 && hub?.online === true) return "kxm hub:on";
-  if (hub?.state === "off" || hub?.state === void 0 && hub?.online === false) return "kxm hub:off";
-  if (hub?.state === "unknown") return "kxm hub:unknown";
+  const suffix = hub?.scope === "remote" ? "/remote" : "";
+  if (hub?.state === "on" || hub?.state === void 0 && hub?.online === true) return `kxm hub:on${suffix}`;
+  if (hub?.state === "off" || hub?.state === void 0 && hub?.online === false) return `kxm hub:off${suffix}`;
+  if (hub?.state === "unknown") return `kxm hub:unknown${suffix}`;
   return "kxm";
 }
 function truncate(value, width) {
@@ -45848,8 +45875,21 @@ async function refreshKxmUpdateNotice(runtime, config) {
 async function cmdStatus(runtime) {
   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}`);
+  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} \xB7 ${effectiveScope} hub${overridden ? " (KXM_SERVER_URL)" : ""}`
+  );
   return payload.ok ? 0 : 1;
 }
 async function cmdDash(runtime, options = {}) {
@@ -45934,6 +45974,7 @@ function formatHubBindHealth(health) {
   if (health === "off") return "health=off (nothing answered; run kxm hub start)";
   return "health=unknown (no reply within 300 ms)";
 }
+var 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";
 async function cmdHubBind(runtime, rawUrl) {
   let url;
   try {
@@ -45950,14 +45991,64 @@ async function cmdHubBind(runtime, rawUrl) {
     }
     throw error;
   }
+  const scope = hubBindingScope(url);
+  if (scope === "remote") {
+    const bindProject = defaultProjectName(runtime.dirs.workdir, runtime.env) || "project";
+    let credentialReady = false;
+    try {
+      credentialReady = hasClientHubCredential(runtime.env, bindProject);
+    } catch (error) {
+      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: (/* @__PURE__ */ 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} \xB7 ${formatHubBindHealth(health)}`);
+  print(
+    runtime.io,
+    runtime.json,
+    { ok: true, command: "hub bind", url, scope, file, health, probeMs },
+    `bound hub ${url} \xB7 ${scope} \xB7 ${formatHubBindHealth(health)}${scope === "remote" ? " \xB7 token leaves this machine" : ""}`
+  );
   return 0;
 }
 async function cmdHubUnbind(runtime) {
@@ -46271,7 +46362,8 @@ async function cmdSessionBrief(runtime, options = {}) {
       state: health,
       evidence: health === "unknown" ? "timeout" : "probed",
       online: health === "on",
-      url: targetUrl
+      url: targetUrl,
+      scope: hubBindingScope(targetUrl)
     };
   } else {
     hub = { state: "off", evidence: "unconfigured", online: false };

package/plugins/kxm/dist/extension.js

@@ -36775,9 +36775,10 @@ var MAX_SESSION_BRIEF_PLANS = 5;
 var SESSION_BRIEF_SCHEMA = "kxm.session-brief.v1";
 var DEFAULT_SESSION_BRIEF_STALE_SECONDS = 5;
 function hubPrefix(hub) {
-  if (hub?.state === "on" || hub?.state === void 0 && hub?.online === true) return "kxm hub:on";
-  if (hub?.state === "off" || hub?.state === void 0 && hub?.online === false) return "kxm hub:off";
-  if (hub?.state === "unknown") return "kxm hub:unknown";
+  const suffix = hub?.scope === "remote" ? "/remote" : "";
+  if (hub?.state === "on" || hub?.state === void 0 && hub?.online === true) return `kxm hub:on${suffix}`;
+  if (hub?.state === "off" || hub?.state === void 0 && hub?.online === false) return `kxm hub:off${suffix}`;
+  if (hub?.state === "unknown") return `kxm hub:unknown${suffix}`;
   return "kxm";
 }
 function truncate(value, width) {

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.52";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
 var meshClient;

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.51",
+  "version": "0.7.52",
   "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/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/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.51";
+const VERSION = "0.7.52";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

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";
 }