@kontextmind/kxm 0.7.97 → 0.7.99

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

package/.kxm/workflows/default.yaml

@@ -7,6 +7,8 @@ steps:
   - id: implement
     kind: agent
     agent: implementer
+    repositories:
+      control: write
     maxAttempts: 3
     on:
       passed: review-arch

package/CHANGELOG.md

@@ -69,6 +69,18 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **The rotation surface drive uses is the one setup writes.** Guide setup appends only
+  reviewed selectors to `.kxm/routes.yaml` and routes Google through Pi `antigravity`.
+
+- **CLI and Studio stop reporting work they did not do.** Drive help no longer
+  describes the default as a model-free simulation. A Studio mutation with no handler returns 501 and `mappedToCli: false`.
+
+- **Missing cost stays unknown.** `kxm prices acknowledge` restamps the local catalog
+  as today without fetching vendor rates, which is what an estimate will accept.
+  Routing totals are null when any attempt has no cost, and those rows sort after
+  complete-cost rows. `kxm improve` stays proposal-only. Wiki compile writes a file
+  only with `--out` and does not ingest.
+
 - **The workflow loader refuses a gate step that can never settle
   (`gate_outcome_impossible`).** A gate step settles only on `passed` or
   `implementation-failure` when `expect` is `pass`, and only on `passed` or `repro-missing`
@@ -90,8 +102,8 @@ All notable user-facing changes are documented here. The project follows [Semant
   execute until the run engine lands. The JSON result and its
   `phase` are unchanged. A `run_handoff_required` refusal from `kxm runs drive` now ends
   with `(handoff reason …; field …; detail …)`, each part capped at 200 characters; a run of
-  the `default` workflow that `kxm init` writes, for example, reports `limit_unsupported`
-  on `limits.maxAgentTimeMs`. Top-level help names the product KXM instead of KontextMind,
+  a workflow that declares `limits.maxAgentTimeMs`, for example, reports `limit_unsupported`
+  on that field. Top-level help names the product KXM instead of KontextMind,
   and `kxm init` text output lists each validation issue as `file: code: message`.
 - **`kxm suggest` recommends only KXM command skills.** Suggested skills come from the
   command skills shipped in `plugins/kxm/skills` (such as `kxm-workflow`, `kxm-runs`,
@@ -307,6 +319,31 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **Live `kxm runs drive` can author on an audited writer profile.** A write-repository
+  step on pi (`-a`, with extensions, skills, and the session off) or grok
+  (`--always-approve`, with subagents and web search off) runs against the checkout.
+  A live write that leaves the tree unchanged settles `failed` with `authored: false`.
+  A read-only step that changes the tree cannot settle `passed`. Harnesses without a
+  writer profile still hand off. Simulated drive does not require a diff. The witness
+  fingerprints the one checkout, so a live write step must be a single assignment
+  (`assignments.maximum: 1`) in a project whose `limits.maxConcurrentRuns` is 1; a
+  panel of writers or a project that admits concurrent runs hands off with
+  `step_unsupported` instead of crediting one writer's change to another.
+
+- **Fresh `kxm init` can be driven.** The current template drops `limits.maxAgentTimeMs`,
+  names coordinator `claude` / `anthropic/fable` and implementer `grok` / `xai/grok-4.6`,
+  and admits those two routes. One-shot production no longer falls through to an
+  unadmitted `claude-3-7-sonnet`.
+
+- **`kxm backup` includes the Runtime stores under the user-state root.** Discovery
+  copies `$S/runtime/registry.db` and `$S/runtime/projects/<projectKey>/run-events.db`,
+  plus each `run-events.db.run-prompts.json` sidecar. A copy that misses a discovered
+  store is `complete: false`: `kxm backup` exits 1 with `ok: false`, and restore
+  refuses that manifest. Cross-box remap of absolute `$S` paths is still the file recipe.
+  The Runtime stores are machine-wide, so a backup holds every project's run store and a
+  restore rolls all of them back. `kxm backup --help` no longer says Runtime stores are
+  left out.
+
 - **Signed webhooks cannot be replayed.** KXM's own webhook senders now sign the
   timestamp, delivery ID, definition, run and signal key along with the body
   (`x-kxm-signature`, `x-kxm-timestamp`, `x-kxm-delivery-id`; see
@@ -328,6 +365,13 @@ All notable user-facing changes are documented here. The project follows [Semant
 - **Workflow prompts no longer point agents at `.kxm/config`**, a path KXM refuses.
 - **`kxm gate signal` and `kxm workflow wait` inside a KXM project reach the hub for hub
   runs.** They go to the local Runtime only for a run its store holds.
+- **`kxm peer inbox` lists the requests waiting for a named CLI agent.** It returned
+  `{"messages":[]}` every time. The hub now serves `GET /v1/agents/:id/inbox`
+  (agent-authenticated, project-scoped): the caller's queued and delivered requests,
+  oldest first, acknowledging nothing. Run with a stable `KXM_AGENT_NAME` (for example
+  `codex`) to list requests peers queued for it while it was offline, then answer them
+  with `kxm peer reply`. The Pi extension's `kxm_inbox` tool now refuses instead of
+  returning an empty list, because Pi activates each inbound request as a turn itself.
 
 - **The Claude plugin's SessionStart hook is one bundled, read-only, project-scoped
   script.** The two shell hooks it replaces (`kxm session brief --status` and

package/docs/concepts/architecture.md

@@ -204,7 +204,7 @@ The package ships a directory of `SKILL.md` suites that Pi and Claude Code both
 
 `kxm dash` draws live terminal screens (agents, tasks, workflows, plans, inbox, processes, and spend, which is always empty today) from the admin-only operations stream, a presence-only fallback, and a read-only snapshot of `kxm.db`. Treat it as an observer: its action keys `a`, `r`, `s` and `c` post to hub routes that do not exist, so they change nothing even though the status line reports success, and `d` creates a git branch and worktree.
 
-`kxm studio layout` renders a workflow as DAG, stepper, and swimlane JSON, and `kxm studio serve` hosts a local viewer on `127.0.0.1:4242`. The Studio mutation endpoint is not wired to commands: it acknowledges requests without running them.
+`kxm studio layout` renders a workflow as DAG, stepper, and swimlane JSON, and `kxm studio serve` hosts a local viewer on `127.0.0.1:4242`. The Studio mutation endpoint is not wired to commands: it answers every allowed request with HTTP 501 `mutation_handler_missing` and runs nothing.
 
 ## Configuration is reviewed Git YAML
 

package/docs/concepts/data-and-storage.md

@@ -169,7 +169,7 @@ Every store opens in WAL mode with a 5-second busy timeout, `synchronous=NORMAL`
 ## Reset a store
 
 > [!CAUTION]
-> Deleting a store erases its history for good. Back it up first if you might need it. `kxm backup` copies the hub store, but it does not find the Runtime stores in the user state root, so copy those with the Runtime stopped.
+> Deleting a store erases its history for good. Back it up first if you might need it. `kxm backup` copies the hub store and the Runtime stores in the user state root, for every project on the machine.
 
 Stop every writer first, then delete each database together with its sidecars:
 

package/docs/contracts/routing.md

@@ -227,7 +227,7 @@ backfilled: they still resolve an outcome, but they group per run.
 - **Price catalog:** `.kxm/prices.yaml` (`kxm.prices.v1`, dated and hashed) defines input, output, cache-read, cache-write rates, and context tiers for active models. Missing rows or uncataloged models evaluate to `costBasis: "unknown"`.
 - **Ranked report:** `kxm routing report` (`plugins/kxm/src/routing.ts`, CLI command `kxm routing report`) groups records by `(harness, model, thinking, role)`.
 - **Ranking order:** Quality first (`verifyPassRate` descending, then `reworkRate` ascending where rework measures back-edge re-entries `transitions > 0`), followed by `costPerAcceptedUsd` ascending.
-- **Underquote prevention:** Routes with unknown cost are flagged (`*`). Any unknown-cost attempt makes a route's cost a lower bound, so the route ranks after every route of equal quality that has no unknown-cost attempt. Displayed values are unchanged: a route that mixes unmetered and unknown-cost attempts still shows `$0` per accepted attempt, so read the flag and the population counts before comparing cost.
+- **Underquote prevention:** Routes with unknown cost are flagged (`*`). Any unknown-cost attempt makes a route's cost unknown: `costPerAcceptedUsd` is `null` (displayed `-`), never a partial sum, and the route ranks after every route of equal quality that has no unknown-cost attempt. Per-configuration comparisons likewise report `totalCostUsd: null` with a `missingCostRuns` count when any record lacks a cost.
 - **Population separation:** Reports metered cost, unmetered attempt counts, unknown-cost attempt counts, and quota-exhausted attempt counts as separate metrics rather than a single misleading total.
 - **List prices flag:** Supports `--equivalent-list-cost` / `--list-prices` to display estimated list rates for comparison alongside actual recorded spend.
 - **Rework column:** reads `transitions`, which Runtime records never set, so Runtime rework shows up only as a resolved `reworked` outcome, which the report does not count as a pass.

package/docs/contributing/test-matrix.md

@@ -133,16 +133,17 @@ The context suites in detail:
 | Metadata-only dashboard: ops mode, presence-only fallback, observer filtering, keys, body-free local projection | `tui.test.ts`, `hub-api.test.ts` |
 | Restricted loader, deterministic bundle hash, init classification, atomic creation, three-way repair, crash resumption | `project-config.test.ts`, `cli.test.ts`, `package-install.test.ts` |
 | Legacy `.kxm/config` JSON is refused with `legacy_state_unsupported`; `kxm migrate` is unknown; older stores are refused | `project-config.test.ts`, `cli.test.ts`, `e6-backup-restore-migrations.test.ts` |
-| `kxm backup` and `kxm restore` round-trip the hub store and Runtime stores seeded under `.kxm/runtime/`; tampered or newer backups are refused | `e6-backup-restore-migrations.test.ts` |
+| `kxm backup` and `kxm restore` round-trip the hub store and Runtime stores seeded under `.kxm/runtime/`; Runtime stores and prompt sidecars under `KXM_STATE_HOME` are discovered; tampered, newer or incomplete (`complete: false`) backups are refused | `e6-backup-restore-migrations.test.ts` |
 | Permission-diff trust: authority lattice, prose neutrality, Git base shadowing, CLI diff and check | `permission.test.ts`, `cli.test.ts`, `contracts.test.ts`, `package-install.test.ts` |
 | KXM schemas, restricted YAML fixtures, cross-resource semantics and sync-safe rejection | `contracts.test.ts`, `restricted-yaml.test.ts` |
 | Harness detection, auth and dispatch for the built-in catalog, including Windows launch rules | `harness.test.ts` |
 | `kxm update`: `update.yaml` validation, GitHub or npm version checks, install-kind detection, `kxm-<v>.tgz` asset selection | `kxm-update.test.ts`, `kxm-update-cli.test.ts`, `kxm-install-kind.test.ts` |
 
-The backup round trip seeds its Runtime stores in a project-local
-`.kxm/runtime/` layout that the Runtime never writes. Production Runtime stores
-live under the user state root, which `kxm backup` does not discover, so no test
-backs up the real Runtime stores.
+The round trip seeds its Runtime stores in a project-local `.kxm/runtime/`
+layout that the Runtime never writes. A separate test seeds a registry, an event
+store and its prompt sidecar under a temporary `KXM_STATE_HOME` and checks that
+`kxm backup` finds them and that a partial manifest is refused. No test backs up
+stores a running supervisor wrote.
 
 ## Packaging, release and repository gates
 

package/docs/guides/peer-messaging.md

@@ -210,7 +210,7 @@ CLI (run with the recipient's `KXM_AGENT_NAME`):
 kxm peer reply msg_779f5e0f22e04ac1af6078589a874971 "The plan is sound. Add a test for a zero discount."
 ```
 
-Only the recipient can reply, and only once. From the CLI, `kxm peer inbox` always returns an empty list, because a one-shot command has no long-running inbox. Use `kxm dash --screen inbox` to see pending requests.
+Only the recipient can reply, and only once. From the CLI, `kxm peer inbox` lists the requests still waiting for the agent named by `KXM_AGENT_NAME`, including ones queued while it was offline, without acknowledging them. The default `cli-<pid>` name is a new agent on every call, so its list is empty.
 
 ## Choose a delivery mode
 
@@ -291,7 +291,7 @@ Errors about `workflowContext` are covered in [Peer provenance and quorum gates]
 | A request stays `delivered` | The recipient's turn, tool, or provider call is still running, or a Claude Code session restarted after acknowledging it. | Wait, or cancel and send it again with a new idempotency key. |
 | `kxm_fanout` returns `pending` | The local wait ended before a reply. | Use the returned message IDs with `kxm_get`, or repeat the exact call. |
 | Claude Code never sees requests | Channel mode is off or blocked by policy. | Use `kxm_inbox` and `kxm_reply`. |
-| `kxm peer inbox` is always empty | The CLI has no long-running inbox. | Use `kxm dash --screen inbox`. |
+| `kxm peer inbox` is always empty | `KXM_AGENT_NAME` is unset, so each call registers a new `cli-<pid>` agent that nobody has addressed. | Set `KXM_AGENT_NAME` to the name peers send to. |
 
 For hub-level problems, see [Troubleshoot KXM](../operations/troubleshooting.md).
 

package/docs/operations/backup-and-restore.md

@@ -59,17 +59,17 @@ Record every override with the backup. A restore that lands where the running se
 
 ## Know what each backup covers
 
-`kxm backup` protects SQLite stores it can find from the current directory. Everything else needs the stopped-state copy described below.
+`kxm backup` copies the SQLite stores it can find: the hub store under the current directory, and the Runtime stores and their prompt sidecars under the user state root. Everything else needs the stopped-state copy described below.
 
 > [!WARNING]
-> `kxm backup` does not back up the Runtime. It looks for Runtime stores under `.kxm/runtime/` in the checkout, but the Runtime writes them under the user state root (`$S/runtime/registry.db` and `$S/runtime/projects/<key>/run-events.db`). In practice a backup holds only the hub store. Back up the Runtime stores and their prompt sidecars by hand, stopped, as shown in [Back up everything else](#back-up-everything-else).
+> The Runtime stores are shared by every project on the machine. `kxm backup` copies `$S/runtime/registry.db` and the `run-events.db` of every project under `$S/runtime/projects/`, not only the project you run it from, and `kxm restore` writes all of them back. Restoring one project's backup returns every project's runs to the moment of that backup.
 
 | Path | Holds | In `kxm backup` |
 |---|---|---|
 | `$W/kxm.db` | Hub store: agents, messages, workflow runs, journals, context items, leases, synced run facts | Yes, at `<current directory>/.kxm/state/kxm.db` only |
-| `$S/runtime/registry.db` | Runtime registry: projects, their roots, the supervisor identity and claim | No |
-| `$S/runtime/projects/<key>/run-events.db` | Event-sourced runs, drive receipts, gate evidence, the sync outbox | No |
-| `$S/runtime/projects/<key>/run-events.db.run-prompts.json` | Run prompt text; restoring a store without it loses every prompt | No |
+| `$S/runtime/registry.db` | Runtime registry: projects, their roots, the supervisor identity and claim | Yes (`registry`) |
+| `$S/runtime/projects/<key>/run-events.db` | Event-sourced runs, drive receipts, gate evidence, the sync outbox | Yes, for every project (`events:<key>`) |
+| `$S/runtime/projects/<key>/run-events.db.run-prompts.json` | Run prompt text; restoring a store without it loses every prompt | Yes, as a plain file (`events:<key>:run-prompts`) |
 | `$S/projects/<hash>/repository-bindings.json`, `$S/update.yaml` | Member repository paths; updater settings | No |
 | `$S/hub-env.json`, `$S/hub-binding.json`, `$C/session.token` | Credentials and the machine's hub binding | No; prefer regenerating secrets to copying them |
 | `$R/.kxm/` definition files and durable records | Project, roles, routes, prices, roster, memory, skills, goals, tasks, candidates | No; commit them to Git or copy the checkout |
@@ -82,9 +82,9 @@ A restore without `roster.yaml`, `routes.yaml` or `prices.yaml` comes back healt
 
 These files are disposable and need no backup: `hub.pid`, `hub.stop`, `worker-*.pid`, `session-brief.json`, `update-check.json`, `runtime/supervisor.token`, `runtime/supervisor.error`.
 
-## Back up the hub store with `kxm backup`
+## Back up the SQLite stores with `kxm backup`
 
-Run it from the checkout root. It resolves stores from the current directory and ignores `--workspace`, `KXM_WORKDIR`, `KXM_STATE_DIR` and `KXM_DATA_PATH`, so a relocated hub database is not found.
+Run it from the checkout root. It finds the hub store from the current directory and ignores `--workspace`, `KXM_WORKDIR`, `KXM_STATE_DIR` and `KXM_DATA_PATH`, so a relocated hub database is not found. It finds the Runtime stores under the user state root, including one moved with `KXM_STATE_HOME`.
 
 Preview first. A dry run lists what it would write, opens no store and writes nothing:
 
@@ -96,31 +96,40 @@ kxm backup --dry-run
 Expected output:
 
 ```text
-dry run: back up 1 store(s) to /srv/kxm/product/.kxm/backups/backup-2026-09-23T18-29-09-107Z (sources are not opened, so their WAL is not checkpointed)
+dry run: back up 3 store(s) and 1 file(s) to /srv/kxm/product/.kxm/backups/backup-2026-09-23T18-29-09-107Z (sources are not opened, so their WAL is not checkpointed)
   would write /srv/kxm/product/.kxm/backups/backup-2026-09-23T18-29-09-107Z/kxm.db
+  would write /srv/kxm/product/.kxm/backups/backup-2026-09-23T18-29-09-107Z/registry.db
+  would write /srv/kxm/product/.kxm/backups/backup-2026-09-23T18-29-09-107Z/run-events.db
+  would write /srv/kxm/product/.kxm/backups/backup-2026-09-23T18-29-09-107Z/run-events.db.run-prompts.json
   would write /srv/kxm/product/.kxm/backups/backup-2026-09-23T18-29-09-107Z/manifest.json
 ```
 
 Then write the backup outside the checkout:
 
 ```bash
-kxm backup --out /backups/kxm/2026-09-23/hub
+kxm backup --out /backups/kxm/2026-09-23/sqlite
 ```
 
 Expected output:
 
 ```text
-Created SQLite backup with 1 store(s):
+Created SQLite backup with 3 store(s):
   - hub-store: /srv/kxm/product/.kxm/state/kxm.db -> kxm.db (schema v5, 110592 bytes, sha256 sha256:86549...)
-Manifest: /backups/kxm/2026-09-23/hub/manifest.json
+  - registry: /home/kxm/.local/state/kxm/runtime/registry.db -> registry.db (schema v1, 20480 bytes, sha256 sha256:a5bde...)
+  - events:38ed26cb8eeaa297f3b0b452: /home/kxm/.local/state/kxm/runtime/projects/38ed26cb8eeaa297f3b0b452/run-events.db -> run-events.db (schema v7, 348160 bytes, sha256 sha256:27c13...)
+Manifest: /backups/kxm/2026-09-23/sqlite/manifest.json
 ```
 
-For each store, `kxm backup` checkpoints the write-ahead log, runs `PRAGMA integrity_check`, copies the database with `VACUUM INTO`, checks the copy's integrity, sets mode `0600`, and records its schema version and SHA-256 in `manifest.json` (`kxm.backup-manifest.v1`). `VACUUM INTO` reads one consistent snapshot, so the hub can keep running during this step.
+The summary lists stores only; the prompt sidecar is in the manifest's `files`. When two projects' event stores share a file name, the second copy is prefixed with its store id.
+
+For each store, `kxm backup` checkpoints the write-ahead log, runs `PRAGMA integrity_check`, copies the database with `VACUUM INTO`, checks the copy's integrity, sets mode `0600`, and records its schema version and SHA-256 in `manifest.json` (`kxm.backup-manifest.v1`). `VACUUM INTO` reads one consistent snapshot, so the hub and the Runtime can keep running during this step. Each prompt sidecar is copied as a regular file with mode `0600` and its SHA-256 recorded.
+
+A backup is complete only when it copied everything it found. If a store or sidecar cannot be copied, or one appears while the backup runs, the manifest lists it under `omitted` and records `complete: false`, the command prints `Backup is incomplete (<n> omitted); not ok:` and exits 1, and `kxm restore` refuses that manifest.
 
 > [!NOTE]
 > Without `--out`, backups go to `.kxm/backups/` inside the checkout. Keep that directory out of Git, or always pass `--out`.
 
-It fails with `backup_no_stores` when `.kxm/state/kxm.db` does not exist under the current directory, and with `database_corrupted` when an integrity check fails.
+It fails with `backup_no_stores` when it finds no store at all, neither `.kxm/state/kxm.db` under the current directory nor a Runtime store under the user state root, and with `database_corrupted` when an integrity check fails.
 
 ## Back up everything else
 
@@ -142,11 +151,11 @@ Copy the remaining state with both services stopped. SQLite runs in write-ahead-
    S="${KXM_STATE_HOME:-$HOME/.local/state/kxm}"   # macOS: "$HOME/Library/Application Support/KXM"
    B=/backups/kxm/2026-09-23
    mkdir -p "$B"
-   kxm backup --out "$B/hub"
+   kxm backup --out "$B/sqlite"
    tar -C "$S" --exclude 'supervisor.token' --exclude 'hub-env.json' -czf "$B/user-state.tgz" .
    ```
 
-   The archive holds `registry.db`, every project's `run-events.db` with any `-wal` and `-shm` files and its `.run-prompts.json` sidecar, the repository bindings, the hub binding and `update.yaml`. It leaves out the credential file; keep tokens in your secret store, or include `hub-env.json` and protect the archive as a secret.
+   `kxm backup` already holds the Runtime stores and sidecars. The archive holds them again, as files, together with what `kxm backup` does not copy: the repository bindings, the hub binding and `update.yaml`. It leaves out the credential file; keep tokens in your secret store, or include `hub-env.json` and protect the archive as a secret.
 
    If `KXM_STATE_DIR` or `KXM_DATA_PATH` moved the hub database, `kxm backup` fails with `backup_no_stores`. With both services stopped, copy that database file and any `-wal` and `-shm` files instead.
 4. Copy the other roots your recovery needs: the checkout's untracked `.kxm/` records, `$D/assets/`, `$W/worker-*.json` (and `$W/pi-sessions/` only if your policy keeps model history), and `$C`.
@@ -157,40 +166,45 @@ Keep at least one previous backup, and bound retention: run events and prompt si
 
 ## Restore with `kxm restore`
 
-`kxm restore` overwrites the live database and deletes its `-wal` and `-shm` files, and it does not check whether the hub is running. Stop the hub and the Runtime first, and move the current state aside rather than deleting it.
+`kxm restore` overwrites every live database in the manifest, including the Runtime stores of every project on the machine, and deletes their `-wal` and `-shm` files. It does not check whether the hub or the Runtime is running. Stop the hub and the Runtime first, and move the current state aside rather than deleting it.
 
 Preview the restore. The dry run performs every check below and lists what it would overwrite:
 
 ```bash
 cd /srv/kxm/product
-kxm restore /backups/kxm/2026-09-23/hub/manifest.json --dry-run
+kxm restore /backups/kxm/2026-09-23/sqlite/manifest.json --dry-run
 ```
 
 Expected output:
 
 ```text
-dry run: restore 1 store(s) from /backups/kxm/2026-09-23/hub/manifest.json; digests verified against the manifest
+dry run: restore 3 store(s) and 1 file(s) from /backups/kxm/2026-09-23/sqlite/manifest.json; digests verified against the manifest
   would write /srv/kxm/product/.kxm/state/kxm.db
   would delete /srv/kxm/product/.kxm/state/kxm.db-wal
   would delete /srv/kxm/product/.kxm/state/kxm.db-shm
+  would write /home/kxm/.local/state/kxm/runtime/registry.db
+  would write /home/kxm/.local/state/kxm/runtime/projects/38ed26cb8eeaa297f3b0b452/run-events.db
+  would write /home/kxm/.local/state/kxm/runtime/projects/38ed26cb8eeaa297f3b0b452/run-events.db.run-prompts.json
 ```
 
 Then run it without `--dry-run`:
 
 ```bash
-kxm restore /backups/kxm/2026-09-23/hub/manifest.json
+kxm restore /backups/kxm/2026-09-23/sqlite/manifest.json
 ```
 
 Expected output:
 
 ```text
-Restored 1 SQLite store(s) from /backups/kxm/2026-09-23/hub/manifest.json:
+Restored 3 SQLite store(s) from /backups/kxm/2026-09-23/sqlite/manifest.json:
   - hub-store: -> /srv/kxm/product/.kxm/state/kxm.db (schema v5, integrity ok)
+  - registry: -> /home/kxm/.local/state/kxm/runtime/registry.db (schema v1, integrity ok)
+  - events:38ed26cb8eeaa297f3b0b452: -> /home/kxm/.local/state/kxm/runtime/projects/38ed26cb8eeaa297f3b0b452/run-events.db (schema v7, integrity ok)
 ```
 
-Before it overwrites anything, `kxm restore` checks that the manifest is a `kxm.backup-manifest.v1` document, that every listed file exists, that each file's SHA-256 matches the manifest, and that no store is newer than this build supports. The manifest's own `manifestSha256` is not checked.
+Before it overwrites anything, `kxm restore` checks that the manifest is a `kxm.backup-manifest.v1` document that does not record `complete: false` (`restore_incomplete`), that every listed file exists, that each file's SHA-256 matches the manifest, and that no store is newer than this build supports. The manifest's own `manifestSha256` is not checked. A manifest from an older build that has no `complete` field still restores.
 
-It then checks each backup's integrity and schema version again, copies it into place with mode `0600`, and checks the result. Each store returns to its recorded path, rebased onto the current directory when the manifest came from another checkout.
+It then checks each backup's integrity and schema version again, copies it into place with mode `0600`, checks the result, and then copies the prompt sidecars back. A store under the checkout is rebased onto the current directory when the manifest came from another checkout. The Runtime stores and sidecars return to their recorded absolute paths under the user state root; restore does not move them to a different machine's or a different `KXM_STATE_HOME`.
 
 ### Restore ceilings
 
@@ -207,6 +221,8 @@ The ceilings come from `KXM_BACKUP_CEILINGS` in `plugins/kxm/src/database.ts` an
 
 ### Restore the Runtime stores by hand
 
+`kxm restore` puts the Runtime stores back at the paths they came from. Use the archive instead when the user state root moved, or when you also need the bindings and `update.yaml`.
+
 1. Stop the Runtime and the hub, as in the backup procedure.
 2. Move `$S/runtime/registry.db` and `$S/runtime/projects/` aside.
 3. Extract the archive into the user state root:
@@ -232,8 +248,11 @@ Test a full restore on a spare machine before you rely on it, and repeat the tes
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `backup_no_stores` | No `.kxm/state/kxm.db` under the current directory, or it was moved with `KXM_STATE_DIR` or `KXM_DATA_PATH` | Run from the checkout root; copy a relocated database with the stopped-state procedure |
-| Runs are missing after a restore | `kxm backup` never contained the Runtime stores | Restore `$S/runtime/` from the stopped-state archive |
+| `backup_no_stores` | No `.kxm/state/kxm.db` under the current directory (or it was moved with `KXM_STATE_DIR` or `KXM_DATA_PATH`) and no Runtime store under the user state root | Run from the checkout root; copy a relocated database with the stopped-state procedure |
+| `Backup is incomplete (<n> omitted); not ok:`, exit 1 | A store or sidecar could not be copied, or appeared while the backup ran | Fix the source named after `omitted`, then run `kxm backup` again |
+| `restore_incomplete` | The manifest records `complete: false` | Restore a complete backup; the partial one is not restorable |
+| Runs are missing after a restore | The checkout moved to another absolute path, so the Runtime derives a different store key, or the user state root changed | Keep the checkout at its original path and restore under the same `KXM_STATE_HOME` |
+| Another project's recent runs disappeared after a restore | `kxm restore` rolled back every project's Runtime store to the backup's moment | Restore that project's store from a newer backup or from the moved-aside copy |
 | `restore_manifest_digest_mismatch` | A backup file changed after the manifest was written | Use another backup; do not edit files in a backup set |
 | `restore_file_missing` | A file listed in the manifest is not beside it | Copy the whole backup directory, not only `manifest.json` |
 | `runtime_schema_mismatch` | A backup file's schema version differs from the one its manifest records | Use another backup set; never mix files between sets |

package/docs/operations/deploy.md

@@ -237,7 +237,7 @@ flowchart LR
 Hold these invariants on every tenant box:
 
 1. **A service account, not root.** Session isolation routes model context; it is not a sandbox against a hostile process under the same account. Give untrusted workers separate accounts or containers.
-2. **Explicit, stable paths.** Set `KXM_WORKSPACE_DIR`, `KXM_STATE_DIR`, `KXM_DATA_PATH`, `KXM_LOG_PATH` and `KXM_STATE_HOME` instead of inheriting a home directory, and pin `KXM_HOST=127.0.0.1`. `kxm backup` ignores `KXM_STATE_DIR` and `KXM_DATA_PATH`, so on such a box it finds no hub store and fails with `backup_no_stores`; use the [stopped-state backup](backup-and-restore.md#back-up-everything-else) instead.
+2. **Explicit, stable paths.** Set `KXM_WORKSPACE_DIR`, `KXM_STATE_DIR`, `KXM_DATA_PATH`, `KXM_LOG_PATH` and `KXM_STATE_HOME` instead of inheriting a home directory, and pin `KXM_HOST=127.0.0.1`. `kxm backup` ignores `KXM_STATE_DIR` and `KXM_DATA_PATH`, so on such a box it finds no hub store: it copies only the Runtime stores under `KXM_STATE_HOME`, or fails with `backup_no_stores` when there are none. Copy the hub database with the [stopped-state backup](backup-and-restore.md#back-up-everything-else).
 3. **Loopback listeners only.** Neither the hub nor the supervisor has a public port, and nothing is load-balanced across hubs.
 4. **Edge authentication.** The proxy authenticates browsers (for example with Authentik forward auth) on the portal's routes only. The hub never interprets browser identity; see [ADR-0004](../adr/ADR-0004-edge-identity-authentik.md).
 5. **Server-side machine credentials.** The portal backend keeps the hub credentials and calls the hub itself. `kxm tenant status`, which uses the admin token, gives it one labelled view of hub metadata and Runtime runs.