@kontextmind/kxm 0.7.51 → 0.7.53

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.53",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -6,17 +6,69 @@ 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
 
+- **No schema migration lanes, no legacy stamp tolerance (single-operator tool).** Stepwise
+  schema migration lanes are removed from the hub store and the per-project event store, and
+  the external-effects store no longer runs an in-place `ALTER TABLE ... ADD COLUMN` whose
+  failure it swallowed (that column is declared in the fresh schema, so the lane could only
+  ever fire on an older store; the store has no production caller yet, so this closes the
+  lane rather than fixing a live upgrade).
+  A database stamped behind this build now fails closed with `runtime_schema_outdated` and
+  a message that says to delete the state file or re-run `kxm init` — and the refusal never
+  advances `user_version`, so the store stays identifiably old (WAL sidecars may still be
+  checkpointed by opening the file, so the whole state set remains the backup unit — see
+  [`docs/operations.md`](docs/operations.md)). Relabelling a store it refused to open would
+  only hide the problem until a query hit a missing column. The coordinator fingerprint no
+  longer recomputes over stored authority to forgive rows written before set canonicalisation:
+  a stale coordinator is re-bound. Intake tests go from 23 to 22; the two forced-race tests
+  now win against ordinary current-format rows, and one refusal test asserts the untouched
+  stamp.
+
+- **`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/contracts/migration.md

@@ -16,7 +16,7 @@ Presence of KXM documents does not activate new behavior.
 | Long-lived manually started Pi workers | Runtime-managed run-scoped sessions | Existing worker mode remains available during compatibility release |
 | Shared/off workflow Pi history | `{run, agent, instance, scopeEpoch}` sessions | Never import shared conversation history into a narrower run scope |
 | Hub-owned workflow state | Home Runtime event log with hub projection | Import completed history as legacy records; active-run cutover requires quiescence |
-| SQLite schema v3 `kxm.db` | Runtime registry, per-project event stores, hub registry/project stores | Copy through versioned migration; never mutate the only database in place |
+| SQLite schema v3 `kxm.db` | Runtime registry, per-project event stores, hub registry/project stores | **No in-place schema migration.** A store stamped behind the current build fails closed with `runtime_schema_outdated` and the refusal never advances `user_version` (opening the file may still checkpoint WAL sidecars, so the whole state set is the backup unit); re-init instead. Stepwise lanes were removed 2026-09-20 under the single-operator decision from the hub store, the per-project event store, and the external-effects `ALTER TABLE` add-column; the Runtime registry never carried a stepwise lane (see [implementation-plan.md](../../plans/implementation-plan.md) → Decided) |
 | Full peer message bodies in hub DB | Summary-first sync events | Existing bodies remain protected legacy data and are not re-emitted automatically |
 | Project tokens/manual environment auth | Runtime enrollment and scoped credentials | Preserve current mode until enrollment is confirmed; never copy tokens into Git |
 | `.kxm/config/env.example` | Built-in defaults plus optional scoped env YAML | Import only explicit portable differences; secrets become references |
@@ -26,12 +26,27 @@ Presence of KXM documents does not activate new behavior.
 
 ## Compatibility releases and activation
 
+> **Scope note (2026-09-20).** This matrix documents the Mesh/v0.5 → KXM cutover. KXM has
+> one operator and no external installs, so **schema migration and old-state tolerance are
+> out of scope** and the lanes that existed are gone: stores refuse an older stamp rather
+> than upgrading, the external-effects store no longer adds a column in place, and the
+> coordinator fingerprint no longer recomputes to forgive pre-canonicalisation rows. What
+> remains here describes the **project/content** cutover, which the follow-up cut removes
+> along with `kxm migrate`. Nothing here promises that the runtime will read an old
+> database.
+
 Local Runtime support may ship publicly before hub KXM, but it remains beside
 existing hub contracts and stores. Old command names are not preserved. A project
 activates `kxm.*.v1` only by an explicit successful `kxm init`/migration receipt;
 file presence alone never activates it. Legacy hub runs continue on the legacy
 engine.
 
+> **Superseded (2026-09-20).** The single-operator decision removes legacy readers
+> **without** a compatibility release, so this transition-release list is no longer a plan of
+> record. It stays here to name what was given up: no dual-read window, no `mesh_*` shim, and
+> no period where legacy JSON stays loadable while KXM writes YAML. Anything still holding
+> legacy state is refused rather than served from both shapes.
+
 When Phase 8 activates hub KXM, at least one hub transition release provides:
 
 - current `mesh_*` peer tools;
@@ -58,6 +73,12 @@ kxm migrate verify
 
 `kxm init` invokes the planning flow when it detects legacy state.
 
+> **Superseded (2026-09-20).** The single-operator decision removed every schema
+> migration lane, so "database/WAL migration … remain later-phase work" below is
+> no longer the plan: there will be none. The `kxm migrate` commands described on
+> this page are deleted in the follow-up cut, and a tree still holding legacy JSON
+> fails closed at load instead of being converted.
+
 **Implementation status (Phase 1 slice):** the commands above are implemented
 for **configuration migration only** — legacy `agents.json`, `gates.json`, and
 workflow-definition JSON under `.kxm/config/`. Database/WAL migration,
@@ -120,6 +141,18 @@ installed resource bytes against the receipt. It performs no writes.
 
 ## Database migration
 
+> **Superseded in part (2026-09-20).** What the code guarantees today is narrower than the
+> checklist below and belongs to two different moments:
+>
+> - **Opening a store** verifies `user_version`, refuses a newer-than-known version, and
+>   enables WAL. That is implemented.
+> - **Backing a store up** is where checkpointing, `-wal` handling, integrity verification,
+>   and hash recording happen — see the whole-state-set recipe in
+>   [`docs/operations.md`](../operations.md). Those are **not** properties of an ordinary open.
+>
+> The legacy-record import paragraphs describe a cutover that will not happen: this build
+> migrates no database, and an older stamp is refused outright.
+
 Before any database operation:
 
 - verify SQLite `user_version`;
@@ -211,6 +244,11 @@ workflow history.
 
 ## Removal gate
 
+> **Superseded (2026-09-20).** The operator decided removal happens **without** a
+> compatibility release, so the list below no longer gates removal — it is kept only
+> to record why the gate existed. Legacy readers are being deleted now, and old names
+> fail closed by brake rather than alias.
+
 Legacy readers and command aliases are removed only after:
 
 - at least one compatibility release;

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.53",
   "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.53",
   "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;
@@ -23752,20 +23767,11 @@ function openDatabase(file, description, spec) {
       database.exec(spec.schema);
       database.exec(`PRAGMA user_version = ${spec.version}`);
     } else if (version < spec.version) {
-      let currentVersion = version;
-      while (currentVersion < spec.version) {
-        const step = spec.migrations?.find((m2) => m2.fromVersion === currentVersion);
-        if (!step) {
-          throw databaseError(
-            "runtime_schema_outdated",
-            file,
-            `${description} schema version ${version} is older than ${spec.version}; no migration lane, backup and restore remain E6`
-          );
-        }
-        step.migrate(database);
-        currentVersion = step.toVersion;
-        database.exec(`PRAGMA user_version = ${currentVersion}`);
-      }
+      throw databaseError(
+        "runtime_schema_outdated",
+        file,
+        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file (or re-run \`kxm init\`) to start fresh \u2014 upgrading old state in place is deliberately unsupported`
+      );
     }
     if (spec.tables) {
       verifyExpectedTables(database, file, description, spec.tables);
@@ -26098,6 +26104,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 +45229,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 +45866,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 +45965,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 +45982,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 +46353,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) {