@kontextmind/kxm 0.7.102 → 0.7.104

package/plugins/kxm/dist/server.js

@@ -3872,49 +3872,49 @@ var require_fast_uri = __commonJS({
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative2, options, skipNormalization) {
+    function resolveComponent(base, relative3, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse3(serialize(base, options), options);
-        relative2 = parse3(serialize(relative2, options), options);
+        relative3 = parse3(serialize(relative3, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative2.scheme) {
-        target.scheme = relative2.scheme;
-        target.userinfo = relative2.userinfo;
-        target.host = relative2.host;
-        target.port = relative2.port;
-        target.path = removeDotSegments(relative2.path || "");
-        target.query = relative2.query;
+      if (!options.tolerant && relative3.scheme) {
+        target.scheme = relative3.scheme;
+        target.userinfo = relative3.userinfo;
+        target.host = relative3.host;
+        target.port = relative3.port;
+        target.path = removeDotSegments(relative3.path || "");
+        target.query = relative3.query;
       } else {
-        if (relative2.userinfo !== void 0 || relative2.host !== void 0 || relative2.port !== void 0) {
-          target.userinfo = relative2.userinfo;
-          target.host = relative2.host;
-          target.port = relative2.port;
-          target.path = removeDotSegments(relative2.path || "");
-          target.query = relative2.query;
+        if (relative3.userinfo !== void 0 || relative3.host !== void 0 || relative3.port !== void 0) {
+          target.userinfo = relative3.userinfo;
+          target.host = relative3.host;
+          target.port = relative3.port;
+          target.path = removeDotSegments(relative3.path || "");
+          target.query = relative3.query;
         } else {
-          if (!relative2.path) {
+          if (!relative3.path) {
             target.path = base.path;
-            if (relative2.query !== void 0) {
-              target.query = relative2.query;
+            if (relative3.query !== void 0) {
+              target.query = relative3.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative2.path[0] === "/") {
-              target.path = removeDotSegments(relative2.path);
+            if (relative3.path[0] === "/") {
+              target.path = removeDotSegments(relative3.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative2.path;
+                target.path = "/" + relative3.path;
               } else if (!base.path) {
-                target.path = relative2.path;
+                target.path = relative3.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative2.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative3.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative2.query;
+            target.query = relative3.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -3922,7 +3922,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative2.fragment;
+      target.fragment = relative3.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -11411,10 +11411,10 @@ var require_resolve_block_map = __commonJS({
       let offset = bm.offset;
       let commentEnd = null;
       for (const collItem of bm.items) {
-        const { start, key, sep: sep2, value } = collItem;
+        const { start, key, sep: sep3, value } = collItem;
         const keyProps = resolveProps.resolveProps(start, {
           indicator: "explicit-key-ind",
-          next: key ?? sep2?.[0],
+          next: key ?? sep3?.[0],
           offset,
           onError,
           parentIndent: bm.indent,
@@ -11428,7 +11428,7 @@ var require_resolve_block_map = __commonJS({
             else if ("indent" in key && key.indent !== bm.indent)
               onError(offset, "BAD_INDENT", startColMsg);
           }
-          if (!keyProps.anchor && !keyProps.tag && !sep2) {
+          if (!keyProps.anchor && !keyProps.tag && !sep3) {
             commentEnd = keyProps.end;
             if (keyProps.comment) {
               if (map.comment)
@@ -11452,7 +11452,7 @@ var require_resolve_block_map = __commonJS({
         ctx.atKey = false;
         if (utilMapIncludes.mapIncludes(ctx, map.items, keyNode))
           onError(keyStart, "DUPLICATE_KEY", "Map keys must be unique");
-        const valueProps = resolveProps.resolveProps(sep2 ?? [], {
+        const valueProps = resolveProps.resolveProps(sep3 ?? [], {
           indicator: "map-value-ind",
           next: value,
           offset: keyNode.range[2],
@@ -11468,7 +11468,7 @@ var require_resolve_block_map = __commonJS({
             if (ctx.options.strict && keyProps.start < valueProps.found.offset - 1024)
               onError(keyNode.range, "KEY_OVER_1024_CHARS", "The : indicator must be at most 1024 chars after the start of an implicit block mapping key");
           }
-          const valueNode = value ? composeNode(ctx, value, valueProps, onError) : composeEmptyNode(ctx, offset, sep2, null, valueProps, onError);
+          const valueNode = value ? composeNode(ctx, value, valueProps, onError) : composeEmptyNode(ctx, offset, sep3, null, valueProps, onError);
           if (ctx.schema.compat)
             utilFlowIndentCheck.flowIndentCheck(bm.indent, value, onError);
           offset = valueNode.range[2];
@@ -11559,7 +11559,7 @@ var require_resolve_end = __commonJS({
       let comment = "";
       if (end) {
         let hasSpace = false;
-        let sep2 = "";
+        let sep3 = "";
         for (const token of end) {
           const { source, type } = token;
           switch (type) {
@@ -11573,13 +11573,13 @@ var require_resolve_end = __commonJS({
               if (!comment)
                 comment = cb;
               else
-                comment += sep2 + cb;
-              sep2 = "";
+                comment += sep3 + cb;
+              sep3 = "";
               break;
             }
             case "newline":
               if (comment)
-                sep2 += source;
+                sep3 += source;
               hasSpace = true;
               break;
             default:
@@ -11622,18 +11622,18 @@ var require_resolve_flow_collection = __commonJS({
       let offset = fc.offset + fc.start.source.length;
       for (let i = 0; i < fc.items.length; ++i) {
         const collItem = fc.items[i];
-        const { start, key, sep: sep2, value } = collItem;
+        const { start, key, sep: sep3, value } = collItem;
         const props = resolveProps.resolveProps(start, {
           flow: fcName,
           indicator: "explicit-key-ind",
-          next: key ?? sep2?.[0],
+          next: key ?? sep3?.[0],
           offset,
           onError,
           parentIndent: fc.indent,
           startOnNewline: false
         });
         if (!props.found) {
-          if (!props.anchor && !props.tag && !sep2 && !value) {
+          if (!props.anchor && !props.tag && !sep3 && !value) {
             if (i === 0 && props.comma)
               onError(props.comma, "UNEXPECTED_TOKEN", `Unexpected , in ${fcName}`);
             else if (i < fc.items.length - 1)
@@ -11687,8 +11687,8 @@ var require_resolve_flow_collection = __commonJS({
             }
           }
         }
-        if (!isMap2 && !sep2 && !props.found) {
-          const valueNode = value ? composeNode(ctx, value, props, onError) : composeEmptyNode(ctx, props.end, sep2, null, props, onError);
+        if (!isMap2 && !sep3 && !props.found) {
+          const valueNode = value ? composeNode(ctx, value, props, onError) : composeEmptyNode(ctx, props.end, sep3, null, props, onError);
           coll.items.push(valueNode);
           offset = valueNode.range[2];
           if (isBlock(value))
@@ -11700,7 +11700,7 @@ var require_resolve_flow_collection = __commonJS({
           if (isBlock(key))
             onError(keyNode.range, "BLOCK_IN_FLOW", blockMsg);
           ctx.atKey = false;
-          const valueProps = resolveProps.resolveProps(sep2 ?? [], {
+          const valueProps = resolveProps.resolveProps(sep3 ?? [], {
             flow: fcName,
             indicator: "map-value-ind",
             next: value,
@@ -11711,8 +11711,8 @@ var require_resolve_flow_collection = __commonJS({
           });
           if (valueProps.found) {
             if (!isMap2 && !props.found && ctx.options.strict) {
-              if (sep2)
-                for (const st of sep2) {
+              if (sep3)
+                for (const st of sep3) {
                   if (st === valueProps.found)
                     break;
                   if (st.type === "newline") {
@@ -11729,7 +11729,7 @@ var require_resolve_flow_collection = __commonJS({
             else
               onError(valueProps.start, "MISSING_CHAR", `Missing , or : between ${fcName} items`);
           }
-          const valueNode = value ? composeNode(ctx, value, valueProps, onError) : valueProps.found ? composeEmptyNode(ctx, valueProps.end, sep2, null, valueProps, onError) : null;
+          const valueNode = value ? composeNode(ctx, value, valueProps, onError) : valueProps.found ? composeEmptyNode(ctx, valueProps.end, sep3, null, valueProps, onError) : null;
           if (valueNode) {
             if (isBlock(value))
               onError(valueNode.range, "BLOCK_IN_FLOW", blockMsg);
@@ -11909,7 +11909,7 @@ var require_resolve_block_scalar = __commonJS({
           chompStart = i + 1;
       }
       let value = "";
-      let sep2 = "";
+      let sep3 = "";
       let prevMoreIndented = false;
       for (let i = 0; i < contentStart; ++i)
         value += lines[i][0].slice(trimIndent) + "\n";
@@ -11926,24 +11926,24 @@ var require_resolve_block_scalar = __commonJS({
           indent = "";
         }
         if (type === Scalar.Scalar.BLOCK_LITERAL) {
-          value += sep2 + indent.slice(trimIndent) + content;
-          sep2 = "\n";
+          value += sep3 + indent.slice(trimIndent) + content;
+          sep3 = "\n";
         } else if (indent.length > trimIndent || content[0] === "	") {
-          if (sep2 === " ")
-            sep2 = "\n";
-          else if (!prevMoreIndented && sep2 === "\n")
-            sep2 = "\n\n";
-          value += sep2 + indent.slice(trimIndent) + content;
-          sep2 = "\n";
+          if (sep3 === " ")
+            sep3 = "\n";
+          else if (!prevMoreIndented && sep3 === "\n")
+            sep3 = "\n\n";
+          value += sep3 + indent.slice(trimIndent) + content;
+          sep3 = "\n";
           prevMoreIndented = true;
         } else if (content === "") {
-          if (sep2 === "\n")
+          if (sep3 === "\n")
             value += "\n";
           else
-            sep2 = "\n";
+            sep3 = "\n";
         } else {
-          value += sep2 + content;
-          sep2 = " ";
+          value += sep3 + content;
+          sep3 = " ";
           prevMoreIndented = false;
         }
       }
@@ -12126,25 +12126,25 @@ var require_resolve_flow_scalar = __commonJS({
         trimBoth = /^[ \t]+|[ \t]+$/g;
       }
       let res = match[1].replace(trimEnd, "");
-      let sep2 = " ";
+      let sep3 = " ";
       let pos = line.lastIndex;
       while (match = line.exec(source)) {
         const lm = match[1].replace(trimBoth, "");
         if (lm === "") {
-          if (sep2 === "\n")
-            res += sep2;
+          if (sep3 === "\n")
+            res += sep3;
           else
-            sep2 = "\n";
+            sep3 = "\n";
         } else {
-          res += sep2 + lm;
-          sep2 = " ";
+          res += sep3 + lm;
+          sep3 = " ";
         }
         pos = line.lastIndex;
       }
       const last = /[ \t]*(.*)/sy;
       last.lastIndex = pos;
       match = last.exec(source);
-      return res + sep2 + (match?.[1] ?? "");
+      return res + sep3 + (match?.[1] ?? "");
     }
     function doubleQuotedValue(source, onError) {
       let res = "";
@@ -12954,14 +12954,14 @@ var require_cst_stringify = __commonJS({
         }
       }
     }
-    function stringifyItem({ start, key, sep: sep2, value }) {
+    function stringifyItem({ start, key, sep: sep3, value }) {
       let res = "";
       for (const st of start)
         res += st.source;
       if (key)
         res += stringifyToken(key);
-      if (sep2)
-        for (const st of sep2)
+      if (sep3)
+        for (const st of sep3)
           res += st.source;
       if (value)
         res += stringifyToken(value);
@@ -14128,18 +14128,18 @@ var require_parser = __commonJS({
         if (this.type === "map-value-ind") {
           const prev = getPrevProps(this.peek(2));
           const start = getFirstKeyStartProps(prev);
-          let sep2;
+          let sep3;
           if (scalar.end) {
-            sep2 = scalar.end;
-            sep2.push(this.sourceToken);
+            sep3 = scalar.end;
+            sep3.push(this.sourceToken);
             delete scalar.end;
           } else
-            sep2 = [this.sourceToken];
+            sep3 = [this.sourceToken];
           const map = {
             type: "block-map",
             offset: scalar.offset,
             indent: scalar.indent,
-            items: [{ start, key: scalar, sep: sep2 }]
+            items: [{ start, key: scalar, sep: sep3 }]
           };
           this.onKeyLine = true;
           this.stack[this.stack.length - 1] = map;
@@ -14292,15 +14292,15 @@ var require_parser = __commonJS({
                 } else if (isFlowToken(it.key) && !includesToken(it.sep, "newline")) {
                   const start2 = getFirstKeyStartProps(it.start);
                   const key = it.key;
-                  const sep2 = it.sep;
-                  sep2.push(this.sourceToken);
+                  const sep3 = it.sep;
+                  sep3.push(this.sourceToken);
                   delete it.key;
                   delete it.sep;
                   this.stack.push({
                     type: "block-map",
                     offset: this.offset,
                     indent: this.indent,
-                    items: [{ start: start2, key, sep: sep2 }]
+                    items: [{ start: start2, key, sep: sep3 }]
                   });
                 } else if (start.length > 0) {
                   it.sep = it.sep.concat(start, this.sourceToken);
@@ -14494,13 +14494,13 @@ var require_parser = __commonJS({
             const prev = getPrevProps(parent);
             const start = getFirstKeyStartProps(prev);
             fixFlowSeqItems(fc);
-            const sep2 = fc.end.splice(1, fc.end.length);
-            sep2.push(this.sourceToken);
+            const sep3 = fc.end.splice(1, fc.end.length);
+            sep3.push(this.sourceToken);
             const map = {
               type: "block-map",
               offset: fc.offset,
               indent: fc.indent,
-              items: [{ start, key: fc, sep: sep2 }]
+              items: [{ start, key: fc, sep: sep3 }]
             };
             this.onKeyLine = true;
             this.stack[this.stack.length - 1] = map;
@@ -19384,7 +19384,7 @@ import {
   unlinkSync,
   writeFileSync as writeFileSync4
 } from "node:fs";
-import { basename as basename3, dirname as dirname5, join as join5, resolve as resolve4 } from "node:path";
+import { basename as basename3, dirname as dirname5, isAbsolute as isAbsolute2, join as join5, relative as relative2, resolve as resolve4, sep as sep2 } from "node:path";
 
 // plugins/kxm/src/sqlite.ts
 import { createRequire } from "node:module";

package/plugins/kxm/package.json

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

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

@@ -15,7 +15,7 @@ invent restart or status subcommands.
 |---|---|---|
 | `kxm hub view` | Check `/health` and `/ready`; exits 1 when the hub is down | `--json` |
 | `kxm tenant status` | Hub metadata and Runtime run state as one labeled view; reads only and never starts the supervisor | `--json` |
-| `kxm backup` | Verified SQLite backup of the hub store and the Runtime stores with a hashed manifest; exits 1 when the backup is incomplete | `--out <dir>`, `--json` |
+| `kxm backup` | Verified SQLite backup of this project's hub store and Runtime event store with a hashed manifest; exits 1 when the backup is incomplete | `--out <dir>`, `--all-projects`, `--json` |
 
 ```bash
 kxm hub view --json
@@ -30,9 +30,12 @@ runs have separate ID spaces, so a comparison with no shared ID is
 `unverified`, never agreement.
 
 The durable hub store defaults to `.kxm/state/kxm.db` (`KXM_DATA_PATH`). Do not
-hand-edit it. `kxm backup` also copies the Runtime registry and every
-project's run event store and prompt sidecar under the user state root, so a
-`kxm restore` rolls back every project on the machine, not only this one.
+hand-edit it. `kxm backup` also copies this project's Runtime event store and
+prompt sidecar from the user state root. The shared Runtime registry and other
+projects' event stores are copied only with `--all-projects`, and only
+`kxm restore --all-projects` restores them, rolling back every project on the
+machine. Do not pass `--all-projects` unless the user asked for a whole-machine
+backup or restore.
 
 ## Operator steps
 
@@ -45,7 +48,7 @@ the hub admin token or a project token.
 | `kxm hub stop` | Request managed hub and worker shutdown | `--wait-ms <ms>` |
 | `kxm hub bind <url>` | Bind this machine to a running hub | http or https URL |
 | `kxm hub unbind` | Remove this machine's hub binding | `--json` |
-| `kxm restore <manifest>` | Replace the live stores from a verified backup manifest | `--json` |
+| `kxm restore <manifest>` | Replace this project's live stores from a verified backup manifest | `--all-projects`, `--json` |
 
 ```bash
 kxm hub start
@@ -70,5 +73,9 @@ kxm restore .kxm/backups/pre-upgrade/manifest.json
   claim is reclaimed automatically, an orphaned server is terminated first,
   and `kxm hub stop` recovers such orphans directly.
 - `kxm restore` replaces the live stores. Preview it with
-  `kxm restore <manifest> --dry-run`, stop the hub first, and never skip
-  restore verification.
+  `kxm restore <manifest> --dry-run`, and never skip restore verification. It
+  refuses before writing while the Runtime supervisor runs
+  (`restore_runtime_running`) or a hub holds the hub store
+  (`restore_hub_running`), so stop both first (`kxm runtime stop`,
+  `kxm hub stop`). A backup that holds the registry or another project's
+  event store is refused with `restore_requires_all_projects`.

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

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
-import { createBackup, planBackup, planRestore, restoreBackup } from "../database.ts";
+import { applyRestorePlan, createBackup, databaseError, planBackup, planRestore, type RestorePlan } from "../database.ts";
+import { readLiveHubClaim } from "../hub-autostart.ts";
 import { refreshModelInventory } from "../model-inventory.ts";
 import { listInventoryModels, listRoleBindings, loadRoutePolicy, setRouteState, updateRouteState } from "../routes.ts";
 import {
@@ -181,23 +182,30 @@ export async function cmdKxmInit(
   }
 }
 
-export async function cmdBackup(runtime: Runtime, options: { out?: string | undefined }): Promise<number> {
+/** The checkout backup and restore act for, found as the Runtime finds it, so the
+ * project's event store key is the one the Runtime derives. */
+function backupProjectRoot(runtime: Runtime): string {
+  return discoverKxmProjectRoot(runtime.cwd) ?? runtime.cwd;
+}
+
+export async function cmdBackup(runtime: Runtime, options: { out?: string | undefined; allProjects?: boolean | undefined }): Promise<number> {
   try {
     const backupOptions = {
-      projectRoot: runtime.cwd,
+      projectRoot: backupProjectRoot(runtime),
       env: runtime.env,
+      ...(options.allProjects === true ? { allProjects: true } : {}),
       ...(options.out ? { outDir: resolve(runtime.cwd, options.out) } : {}),
     };
     if (runtime.dryRun) {
       const plan = planBackup(backupOptions);
       printPlan(
         runtime,
-        { command: "backup", outDir: plan.outDir, stores: plan.stores, files: plan.files },
+        { command: "backup", scope: plan.scope, outDir: plan.outDir, stores: plan.stores, files: plan.files },
         [
           ...[...plan.stores, ...plan.files].map((entry) => ({ action: "write" as const, target: join(plan.outDir, entry.backupFile) })),
           { action: "write", target: join(plan.outDir, "manifest.json") },
         ],
-        `back up ${plan.stores.length} store(s) and ${plan.files.length} file(s) to ${plan.outDir} (sources are not opened, so their WAL is not checkpointed)`,
+        `back up ${plan.stores.length} store(s) and ${plan.files.length} file(s) (${plan.scope} scope) to ${plan.outDir} (sources are not opened, so their WAL is not checkpointed)`,
       );
       return 0;
     }
@@ -212,7 +220,7 @@ export async function cmdBackup(runtime: Runtime, options: { out?: string | unde
     };
     const summary = [
       complete
-        ? `Created SQLite backup with ${manifest.stores.length} store(s):`
+        ? `Created SQLite backup with ${manifest.stores.length} store(s) (${manifest.scope ?? "project"} scope):`
         : `Backup is incomplete (${manifest.omitted?.length ?? 0} omitted); not ok:`,
       ...manifest.stores.map((s) => `  - ${s.storeId}: ${s.sourcePath} -> ${s.backupFile} (schema v${s.schemaVersion}, ${s.bytes} bytes, sha256 ${s.sha256.slice(0, 12)}...)`),
       ...(manifest.omitted ?? []).map((id) => `  - omitted ${id}`),
@@ -230,16 +238,63 @@ export async function cmdBackup(runtime: Runtime, options: { out?: string | unde
   }
 }
 
-export async function cmdRestore(runtime: Runtime, manifestArg: string): Promise<number> {
+/**
+ * Refuse while anything holds the stores a restore would overwrite. Replacing a
+ * SQLite file under an open connection loses the writer's next commit or corrupts
+ * the store, and the supervisor holds the registry and every project's event store
+ * open. Reads only: the registry is opened read-only and the hub claim is a file,
+ * so the check is the same under --dry-run.
+ */
+function assertRestoreTargetsStopped(runtime: Runtime, plan: RestorePlan): void {
+  const paths = kxmRuntimePaths({ env: runtime.env });
+  let supervisor: ReturnType<typeof kxmSupervisorStatus>;
   try {
+    supervisor = kxmSupervisorStatus(paths, { readOnly: true });
+  } catch (error) {
+    // Fail closed, but name the way out: a registry too broken to read is also one a
+    // restore may be meant to replace.
+    throw databaseError(
+      "restore_runtime_unverified",
+      paths.registryDb,
+      `cannot read the Runtime registry to check whether the supervisor is running (${error instanceof Error ? error.message : String(error)}); stop the Runtime, move the registry aside, and restore again`,
+    );
+  }
+  if (supervisor.running) {
+    throw databaseError(
+      "restore_runtime_running",
+      paths.registryDb,
+      `the Runtime supervisor is running (pid ${String(supervisor.pid)}); stop it with \`kxm runtime stop\` and keep it stopped until the restore finishes`,
+    );
+  }
+  for (const store of plan.stores) {
+    if (store.storeId !== "hub-store") continue;
+    const claim = readLiveHubClaim(dirname(store.targetPath));
+    if (claim) {
+      throw databaseError(
+        "restore_hub_running",
+        store.targetPath,
+        `a hub (pid ${String(claim.pid)}) is running on ${store.targetPath}; stop it with \`kxm hub stop\` before restoring`,
+      );
+    }
+  }
+}
+
+export async function cmdRestore(runtime: Runtime, manifestArg: string, options: { allProjects?: boolean | undefined } = {}): Promise<number> {
+  try {
+    const plan = planRestore(resolve(runtime.cwd, manifestArg), {
+      projectRoot: backupProjectRoot(runtime),
+      env: runtime.env,
+      ...(options.allProjects === true ? { allProjects: true } : {}),
+    });
+    assertRestoreTargetsStopped(runtime, plan);
     if (runtime.dryRun) {
-      const plan = planRestore(resolve(runtime.cwd, manifestArg), { projectRoot: runtime.cwd });
       printPlan(
         runtime,
         {
           command: "restore",
           backupId: plan.backupId,
           manifestPath: plan.manifestPath,
+          ...(plan.scope !== undefined ? { scope: plan.scope } : {}),
           stores: plan.stores.map(({ storeId, targetPath, schemaVersion }) => ({ storeId, targetPath, schemaVersion })),
           files: plan.files.map(({ id, targetPath }) => ({ id, targetPath })),
         },
@@ -256,14 +311,13 @@ export async function cmdRestore(runtime: Runtime, manifestArg: string): Promise
       );
       return 0;
     }
-    const result = restoreBackup(resolve(runtime.cwd, manifestArg), {
-      projectRoot: runtime.cwd,
-    });
+    const result = applyRestorePlan(plan);
     const payload = {
       ok: true,
       command: "restore",
       backupId: result.backupId,
       manifestPath: result.manifestPath,
+      ...(plan.scope !== undefined ? { scope: plan.scope } : {}),
       restoredStores: result.restoredStores,
     };
     const summary = [

package/plugins/kxm/src/cli.ts

@@ -419,15 +419,17 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       });
     });
 
-  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of the project hub store and the Runtime stores under the user state root, with a hashed manifest"))
+  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of this project's hub store and Runtime event store, with a hashed manifest"))
     .option("--out <dir>", "Directory to write backup and manifest")
-    .action(async function backupAction(this: Command, options: { out?: string }) {
+    .option("--all-projects", "Also back up the shared Runtime registry and every project's event store on this machine")
+    .action(async function backupAction(this: Command, options: { out?: string; allProjects?: boolean }) {
       result.code = await cmdBackup(runtimeFrom(ctx, this), options);
     });
 
-  addGlobalOptions(program.command("restore <manifest>").description("Restore SQLite stores from a verified backup manifest"))
-    .action(async function restoreAction(this: Command, manifest: string) {
-      result.code = await cmdRestore(runtimeFrom(ctx, this), manifest);
+  addGlobalOptions(program.command("restore <manifest>").description("Restore this project's SQLite stores from a verified backup manifest; refuses while the Runtime or hub is running"))
+    .option("--all-projects", "Also restore the shared Runtime registry and other projects' event stores the backup holds")
+    .action(async function restoreAction(this: Command, manifest: string, options: { allProjects?: boolean }) {
+      result.code = await cmdRestore(runtimeFrom(ctx, this), manifest, options);
     });
 
   addGlobalOptions(program.command("run").description("Create a KXM run (offline-first; kxm runs drive <runId> --simulated executes it model-free)")