@kontextmind/kxm 0.7.97 → 0.7.98

package/plugins/kxm/dist/server.js

@@ -15271,6 +15271,10 @@ var READ_ONLY_ONESHOT_ARGS = Object.freeze({
 function oneShotReadOnlyArgs(harness) {
   return Object.hasOwn(READ_ONLY_ONESHOT_ARGS, harness) ? READ_ONLY_ONESHOT_ARGS[harness] : void 0;
 }
+var WRITER_ONESHOT_ARGS = Object.freeze({
+  pi: Object.freeze(["-a", "--no-extensions", "--no-skills", "--no-prompt-templates", "--no-session"]),
+  grok: Object.freeze(["--always-approve", "--no-subagents", "--disable-web-search"])
+});
 var BUILTIN_HARNESSES = Object.freeze([
   {
     id: "pi",
@@ -19418,6 +19422,9 @@ var DatabaseSync = class {
   }
 };
 
+// plugins/kxm/src/bindings.ts
+var MAX_BINDING_RECORD_BYTES = 256 * 1024;
+
 // plugins/kxm/src/database.ts
 function databaseError(code, file, message) {
   const issue2 = { phase: "semantic", code, file, message };

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.97",
+  "version": "0.7.98",
   "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 stores with a hashed manifest | `--out <dir>`, `--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` |
 
 ```bash
 kxm hub view --json
@@ -30,8 +30,9 @@ 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` does not include the Runtime supervisor's stores
-under the user state root.
+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.
 
 ## Operator steps
 

package/plugins/kxm/skills/kxm-project-setup/SKILL.md

@@ -122,8 +122,9 @@ or store the admin or project token in the conversation. The user enters
   in a workflow step, then run `kxm init` again. Only when
   `.kxm/project.yaml` does not exist yet, ask the user to follow the README's
   move-aside workaround; never do that in a committed project.
-- The template `default` workflow declares `limits.maxAgentTimeMs`, so
-  `kxm runs drive` on it fails with `run_handoff_required`. Use `first`.
+- The template `default` workflow can be driven, but even a simulated drive
+  runs its `npm test` gate, and a live drive spends Claude and Grok and lets
+  Grok edit the checkout. Use `first` for the first run.
 - `kxm run` starts the Runtime supervisor. Stop it with `kxm runtime stop`.
 - Only run workflow IDs that `kxm workflow definitions` lists; any other ID
   fails with `run_workflow_unknown`.

package/plugins/kxm/skills/kxm-routing-improve/SKILL.md

@@ -73,11 +73,14 @@ Never apply a candidate diff yourself or treat `readyForReview` as approval.
 |---|---|---|
 | `kxm routing report` | Compare verified completion, cost, and rework per behavioral configuration | `-f/--file`, `-l/--equivalent-list-cost`, `--list-prices`, `--prices <path>` |
 | `kxm routing benchmark` | Placeholder side-by-side comparison | `--task`, `--arms`, `--runs` |
+| `kxm prices acknowledge` | Stamp the existing `.kxm/prices.yaml` list as today's estimate without fetching vendor rates | `--json` |
 
 `kxm routing report` reads the same sources as `kxm improve`, and
 `routing report --json` includes the `sources`. `kxm routing benchmark` prints
 fixed placeholder figures in this build; never cite them as measured cost or
 quality. Use `kxm routing report` for recorded spend.
+Estimates stay unknown until the catalog carries today's stamp, and a routing
+total is null when any attempt has no cost.
 
 `--equivalent-list-cost` loads the price catalog (`.kxm/prices.yaml`, or
 `--prices <path>`) without a freshness check, so an old catalog quotes old

package/plugins/kxm/skills/kxm-runs/SKILL.md

@@ -7,8 +7,9 @@ description: Create, drive, and inspect local KXM runs. kxm runs drive with --si
 
 `kxm run` creates a run of a project workflow in the local Runtime and starts
 the Runtime supervisor. A created run stays `created` until
-`kxm runs drive` executes it. Do not invent get, create, or logs verbs under
-`runs`.
+`kxm runs drive` executes the pinned plan. Live drive is the default and spends
+an admitted model; `--simulated` is the model-free producer. Do not invent get,
+create, or logs verbs under `runs`.
 
 ## Commands
 
@@ -58,11 +59,11 @@ the receipt's settlement is terminal `completed`.
 - `run_workflow_unknown`: the workflow ID is not a project workflow. Run only
   IDs that `kxm workflow definitions` lists.
 - `run_handoff_required`: the Runtime does not execute a field the workflow
-  uses, so drive fails with `runtime request failed with HTTP 409` and the run
-  stays `preparing`. The template `default` workflow declares
-  `limits.maxAgentTimeMs`, which is one such field. Cancel the run with
-  `kxm runs cancel <runId>` and drive a workflow without the field, such as
-  `first`.
+  uses (such as `limits.maxAgentTimeMs`, which a fresh `kxm init` no longer
+  writes), so drive fails with `runtime request failed with HTTP 409` and the
+  run stays `preparing`. Cancel the run with `kxm runs cancel <runId>` and drive
+  a workflow without the field, such as `first`.
 
 Listing or status alone is not proof that steps ran; a verified receipt is.
+A read-only step that settles `passed` did not author a checkout change.
 `kxm workflow list` shows hub webhook runs, not these runs.

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

@@ -185,36 +185,41 @@ export async function cmdBackup(runtime: Runtime, options: { out?: string | unde
   try {
     const backupOptions = {
       projectRoot: runtime.cwd,
+      env: runtime.env,
       ...(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 },
+        { command: "backup", outDir: plan.outDir, stores: plan.stores, files: plan.files },
         [
-          ...plan.stores.map((store) => ({ action: "write" as const, target: join(plan.outDir, store.backupFile) })),
+          ...[...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) 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) to ${plan.outDir} (sources are not opened, so their WAL is not checkpointed)`,
       );
       return 0;
     }
     const { manifest, outDir } = createBackup(backupOptions);
+    const complete = manifest.complete === true;
     const payload = {
-      ok: true,
+      ok: complete,
       command: "backup",
       backupId: manifest.backupId,
       outDir,
       manifest,
     };
     const summary = [
-      `Created SQLite backup with ${manifest.stores.length} store(s):`,
+      complete
+        ? `Created SQLite backup with ${manifest.stores.length} store(s):`
+        : `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}`),
       `Manifest: ${join(outDir, "manifest.json")}`,
     ].join("\n");
     print(runtime.io, runtime.json, payload, summary);
-    return 0;
+    return complete ? 0 : 1;
   } catch (error) {
     if (error instanceof KxmConfigError) {
       print(runtime.io, runtime.json, { ok: false, command: "backup", error: "backup_failed", issues: error.issues }, `backup failed: ${error.message}`);
@@ -236,14 +241,18 @@ export async function cmdRestore(runtime: Runtime, manifestArg: string): Promise
           backupId: plan.backupId,
           manifestPath: plan.manifestPath,
           stores: plan.stores.map(({ storeId, targetPath, schemaVersion }) => ({ storeId, targetPath, schemaVersion })),
+          files: plan.files.map(({ id, targetPath }) => ({ id, targetPath })),
         },
-        plan.stores.flatMap((store) => [
-          { action: "write" as const, target: store.targetPath },
-          ...[`${store.targetPath}-wal`, `${store.targetPath}-shm`]
-            .filter((file) => existsSync(file))
-            .map((file) => ({ action: "delete" as const, target: file })),
-        ]),
-        `restore ${plan.stores.length} store(s) from ${plan.manifestPath}; digests verified against the manifest`,
+        [
+          ...plan.stores.flatMap((store) => [
+            { action: "write" as const, target: store.targetPath },
+            ...[`${store.targetPath}-wal`, `${store.targetPath}-shm`]
+              .filter((file) => existsSync(file))
+              .map((file) => ({ action: "delete" as const, target: file })),
+          ]),
+          ...plan.files.map((file) => ({ action: "write" as const, target: file.targetPath })),
+        ],
+        `restore ${plan.stores.length} store(s) and ${plan.files.length} file(s) from ${plan.manifestPath}; digests verified against the manifest`,
       );
       return 0;
     }

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

@@ -20,7 +20,7 @@ import {
   type RoutingRecord,
   type RoutingRecordV2,
 } from "../routing.ts";
-import { loadPriceCatalog, type PriceCatalog } from "../prices.ts";
+import { acknowledgePriceCatalog, loadPriceCatalog, type PriceCatalog } from "../prices.ts";
 import {
   buildImprovementReport,
   formatImprovementReport,
@@ -59,6 +59,7 @@ import {
 import {
   GUIDE_WORKFLOWS,
   parseGuideSelection,
+  mergeGuideRouteAdmission,
   planGuideSetup,
   renderGuideSetupFiles,
   writeGuideSetupFiles,
@@ -867,8 +868,10 @@ export async function maybeOfferGuideSetup(runtime: Runtime): Promise<void> {
   const plan = planGuideSetup({ inventory, selected });
   const files = renderGuideSetupFiles(runtime.cwd, plan);
   const report = writeGuideSetupFiles(files);
+  const admitted = mergeGuideRouteAdmission(runtime.cwd, plan);
   for (const file of report.written) runtime.io.stdout(`wrote ${file}\n`);
   for (const file of report.existed) runtime.io.stdout(`kept existing ${file} (not overwritten)\n`);
+  for (const selector of admitted) runtime.io.stdout(`admitted route ${selector}\n`);
   for (const skip of plan.skipped) {
     runtime.io.stdout(`skipped ${skip.workflow}/${skip.role}: ${skip.reason}\n`);
   }
@@ -877,6 +880,24 @@ export async function maybeOfferGuideSetup(runtime: Runtime): Promise<void> {
   }
 }
 
+export async function cmdPricesAcknowledge(runtime: Runtime): Promise<number> {
+  try {
+    const catalog = acknowledgePriceCatalog(runtime.cwd);
+    print(runtime.io, runtime.json, {
+      ok: true,
+      command: "prices acknowledge",
+      date: catalog.date,
+      sha256: catalog.sha256,
+      note: "stamped the existing list as today's estimate; vendor rates were not fetched",
+    }, `price catalog stamped ${catalog.date} (list estimate only; vendor rates were not fetched)`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    print(runtime.io, runtime.json, { ok: false, command: "prices acknowledge", error: "prices_acknowledge_failed", message }, `prices acknowledge failed: ${message}`);
+    return 1;
+  }
+}
+
 export async function cmdRoutingReport(
   runtime: Runtime,
   options: { file?: string | undefined; equivalentListCost?: boolean | undefined; listPrices?: boolean | undefined; prices?: string | undefined },

package/plugins/kxm/src/cli.ts

@@ -149,6 +149,7 @@ import {
   cmdConfigList,
   cmdCompletion,
   cmdCompletionInstall,
+  cmdPricesAcknowledge,
   cmdRoutingReport,
   cmdRoutingBenchmark,
   maybeOfferCompletionInstall,
@@ -416,7 +417,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       });
     });
 
-  addGlobalOptions(program.command("backup").description("Create a verified SQLite backup of the project hub store with a hashed manifest (Runtime stores under the user state root are not included)"))
+  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"))
     .option("--out <dir>", "Directory to write backup and manifest")
     .action(async function backupAction(this: Command, options: { out?: string }) {
       result.code = await cmdBackup(runtimeFrom(ctx, this), options);
@@ -442,7 +443,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     });
   addGlobalOptions(runCmd.command("drive").description("Drive a run with live harness calls, or with the model-free simulation when --simulated is passed"))
     .argument("<runId>", "Run id")
-    .option("--simulated", "Use the model-free simulation producer")
+    .option("--simulated", "Use the model-free simulation producer instead of a live model")
     .option("--wait", "Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement")
     .option("--timeout-ms <n>", "Wait timeout in milliseconds (default 60000, max 600000)")
     .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean; wait?: boolean; timeoutMs?: string }) {
@@ -474,6 +475,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdTenantStatus(runtimeFrom(ctx, this));
     });
 
+  const pricesCmd = addGlobalOptions(program.command("prices").description("Stamp the local list-price catalog. Estimates stay unknown until today's stamp"));
+  pricesCmd.helpCommand("help", "Show prices help");
+  addGlobalOptions(pricesCmd.command("acknowledge").description("Stamp the existing .kxm/prices.yaml list as today's estimate without fetching vendor rates"))
+    .action(async function pricesAcknowledgeAction(this: Command) {
+      result.code = await cmdPricesAcknowledge(runtimeFrom(ctx, this));
+    });
+
   const modelsCmd = addGlobalOptions(program.command("models").description("Manage model catalogs, roles, and route state"));
   modelsCmd.action(async function modelsScreenAction(this: Command) { result.code = await cmdModelsScreen(runtimeFrom(ctx, this)); });
   modelsCmd.helpCommand("help", "Show models help");
@@ -928,7 +936,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdGithubWatch(runtimeFrom(ctx, this), options);
     });
 
-  const improve = addGlobalOptions(program.command("improve").description("Propose coded-repeat candidates from this project's Runtime routing records and telemetry"));
+  const improve = addGlobalOptions(program.command("improve").description("Propose coded-repeat candidates from this project's Runtime routing records and telemetry. Proposals are not applied to the next run"));
   improve.helpCommand("help", "Show improve help");
   addGlobalOptions(improve.command("report", { isDefault: true }).description("Generate improvement report and candidates from routing records"))
     .option("--file <path>", "Read only this routing-record JSONL instead of the project's Runtime store and telemetry")

package/plugins/kxm/src/database.ts

@@ -12,6 +12,7 @@ import {
 } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
+import { kxmUserStateRoot } from "./bindings.ts";
 import { KxmConfigError, type KxmConfigIssue } from "./project-config.ts";
 
 export interface DatabaseSchemaSpec {
@@ -31,12 +32,24 @@ export interface BackupStoreRecord {
   integrity: "ok";
 }
 
+export interface BackupFileRecord {
+  id: string;
+  sourcePath: string;
+  backupFile: string;
+  sha256: string;
+  bytes: number;
+}
+
 export interface BackupManifest {
   schema: "kxm.backup-manifest.v1";
   backupId: string;
   createdAt: string;
   projectRoot?: string;
   stores: BackupStoreRecord[];
+  files?: BackupFileRecord[];
+  /** False when a discovered store or prompt sidecar was left out. Absent on legacy manifests. */
+  complete?: boolean;
+  omitted?: string[];
   manifestSha256?: string;
 }
 
@@ -607,46 +620,136 @@ export const KXM_BACKUP_CEILINGS = {
 } as const;
 
 export function kxmBackupCeiling(storeId: string): number {
+  if (storeId === "runtime-registry") return KXM_BACKUP_CEILINGS.registry;
   if (storeId.startsWith("events:")) return KXM_BACKUP_CEILINGS.events;
   // An id this build does not know keeps the ceiling restore has always defaulted to.
   return KXM_BACKUP_CEILINGS[storeId as keyof typeof KXM_BACKUP_CEILINGS] ?? KXM_BACKUP_CEILINGS["hub-store"];
 }
 
-export function discoverProjectStores(projectRoot: string, options: { hubDataPath?: string } = {}): Array<{ storeId: string; sourcePath: string; maxSupportedVersion: number }> {
+interface DiscoveredStore {
+  storeId: string;
+  sourcePath: string;
+  maxSupportedVersion: number;
+}
+
+interface DiscoveredFile {
+  id: string;
+  sourcePath: string;
+}
+
+function pushStore(stores: DiscoveredStore[], storeId: string, sourcePath: string): void {
+  if (stores.some((store) => store.storeId === storeId || store.sourcePath === sourcePath)) return;
+  stores.push({ storeId, sourcePath, maxSupportedVersion: kxmBackupCeiling(storeId) });
+}
+
+function discoverUserRuntime(env: NodeJS.ProcessEnv | undefined, stores: DiscoveredStore[], files: DiscoveredFile[]): void {
+  let stateRoot: string;
+  try {
+    stateRoot = kxmUserStateRoot(env ? { env } : {});
+  } catch {
+    return;
+  }
+  const runtimeDir = join(stateRoot, "runtime");
+  const registryPath = join(runtimeDir, "registry.db");
+  if (existsSync(registryPath)) {
+    const storeId = stores.some((store) => store.storeId === "registry") ? "runtime-registry" : "registry";
+    pushStore(stores, storeId, registryPath);
+  }
+  const projectsDir = join(runtimeDir, "projects");
+  if (!existsSync(projectsDir)) return;
+  let entries;
+  try {
+    entries = readdirSync(projectsDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dbPath = join(projectsDir, entry.name, "run-events.db");
+    if (!existsSync(dbPath)) continue;
+    const safe = entry.name.replace(/[^a-zA-Z0-9_.-]/g, "_");
+    let storeId = `events:${safe}`;
+    if (stores.some((store) => store.storeId === storeId)) storeId = `events:runtime:${safe}`;
+    pushStore(stores, storeId, dbPath);
+    const sidecar = `${dbPath}.run-prompts.json`;
+    if (existsSync(sidecar)) {
+      const id = `${storeId}:run-prompts`;
+      if (!files.some((file) => file.id === id || file.sourcePath === sidecar)) {
+        files.push({ id, sourcePath: sidecar });
+      }
+    }
+  }
+}
+
+function discoverBackupSources(
+  projectRoot: string,
+  options: { hubDataPath?: string; env?: NodeJS.ProcessEnv } = {},
+): { stores: DiscoveredStore[]; files: DiscoveredFile[] } {
   const root = resolve(projectRoot);
-  const stores: Array<{ storeId: string; sourcePath: string; maxSupportedVersion: number }> = [];
+  const stores: DiscoveredStore[] = [];
+  const files: DiscoveredFile[] = [];
 
   const hubPath = options.hubDataPath ? resolve(options.hubDataPath) : join(root, ".kxm", "state", "kxm.db");
-  if (existsSync(hubPath)) {
-    stores.push({ storeId: "hub-store", sourcePath: hubPath, maxSupportedVersion: kxmBackupCeiling("hub-store") });
-  }
+  if (existsSync(hubPath)) pushStore(stores, "hub-store", hubPath);
 
   const registryPath = join(root, ".kxm", "runtime", "registry.db");
-  if (existsSync(registryPath)) {
-    stores.push({ storeId: "registry", sourcePath: registryPath, maxSupportedVersion: kxmBackupCeiling("registry") });
-  }
+  if (existsSync(registryPath)) pushStore(stores, "registry", registryPath);
 
   const bindingsPath = join(root, ".kxm", "runtime", "bindings.db");
-  if (existsSync(bindingsPath)) {
-    stores.push({ storeId: "binding-store", sourcePath: bindingsPath, maxSupportedVersion: kxmBackupCeiling("binding-store") });
-  }
+  if (existsSync(bindingsPath)) pushStore(stores, "binding-store", bindingsPath);
 
   const eventsDir = join(root, ".kxm", "runtime", "events");
   if (existsSync(eventsDir)) {
     const entries = readdirSync(eventsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isFile() && entry.name.endsWith(".db")) {
-        const key = entry.name.replace(/\.db$/, "");
-        stores.push({
-          storeId: `events:${key}`,
-          sourcePath: join(eventsDir, entry.name),
-          maxSupportedVersion: kxmBackupCeiling(`events:${key}`),
-        });
+        const key = entry.name.replace(/\.db$/, "").replace(/[^a-zA-Z0-9_.-]/g, "_");
+        pushStore(stores, `events:${key}`, join(eventsDir, entry.name));
       }
     }
   }
 
-  return stores;
+  discoverUserRuntime(options.env, stores, files);
+  return { stores, files };
+}
+
+function backupPlainFile(sourcePath: string, targetPath: string, id: string): BackupFileRecord {
+  const resolvedSource = resolve(sourcePath);
+  const sourceStat = lstatSync(resolvedSource, { throwIfNoEntry: false });
+  if (!sourceStat || !sourceStat.isFile() || sourceStat.isSymbolicLink()) {
+    throw databaseError("runtime_path_invalid", resolvedSource, `backup file ${resolvedSource} must be a regular file, not a link or directory`);
+  }
+  checkedParent(targetPath, "backup target");
+  if (existsSync(targetPath)) unlinkSync(targetPath);
+  copyFileSync(resolvedSource, targetPath);
+  try { chmodSync(targetPath, 0o600); } catch { /* Windows */ }
+  return {
+    id,
+    sourcePath: resolvedSource,
+    backupFile: basename(targetPath),
+    sha256: fileSha256(targetPath),
+    bytes: sourceStat.size,
+  };
+}
+
+function backupFilename(sourcePath: string, id: string, used: Set<string>): string {
+  let filename = basename(sourcePath);
+  if (used.has(filename)) {
+    filename = `${id.replace(/[^a-zA-Z0-9_.-]/g, "_")}-${filename}`;
+  }
+  used.add(filename);
+  return filename;
+}
+
+function restorePlainFile(backupFilePath: string, targetPath: string): void {
+  checkedParent(targetPath, "restore target");
+  if (existsSync(targetPath)) unlinkSync(targetPath);
+  copyFileSync(backupFilePath, targetPath);
+  try { chmodSync(targetPath, 0o600); } catch { /* Windows */ }
+}
+
+export function discoverProjectStores(projectRoot: string, options: { hubDataPath?: string; env?: NodeJS.ProcessEnv } = {}): Array<{ storeId: string; sourcePath: string; maxSupportedVersion: number }> {
+  return discoverBackupSources(projectRoot, options).stores;
 }
 
 export interface BackupPlan {
@@ -654,21 +757,28 @@ export interface BackupPlan {
   outDir: string;
   createdAt: string;
   stores: Array<{ storeId: string; sourcePath: string; backupFile: string }>;
+  files: Array<{ id: string; sourcePath: string; backupFile: string }>;
+}
+
+function backupDiscoverOptions(options: { hubDataPath?: string; env?: NodeJS.ProcessEnv }): { hubDataPath?: string; env?: NodeJS.ProcessEnv } {
+  return {
+    ...(options.hubDataPath !== undefined ? { hubDataPath: options.hubDataPath } : {}),
+    ...(options.env !== undefined ? { env: options.env } : {}),
+  };
 }
 
-/** Which stores a backup would copy and where, without opening any of them.
+/** Which stores and files a backup would copy and where, without opening any of them.
  * Opening a source for backup checkpoints its WAL, so the plan stays at paths. */
 export function planBackup(options: {
   projectRoot?: string;
   outDir?: string;
   hubDataPath?: string;
+  env?: NodeJS.ProcessEnv;
 } = {}): BackupPlan {
   const projectRoot = options.projectRoot ? resolve(options.projectRoot) : process.cwd();
-  const stores = discoverProjectStores(projectRoot, {
-    ...(options.hubDataPath !== undefined ? { hubDataPath: options.hubDataPath } : {}),
-  });
+  const discovered = discoverBackupSources(projectRoot, backupDiscoverOptions(options));
 
-  if (stores.length === 0) {
+  if (discovered.stores.length === 0) {
     throw databaseError("backup_no_stores", projectRoot, "no existing SQLite stores found to backup");
   }
 
@@ -676,24 +786,26 @@ export function planBackup(options: {
   const timestamp = createdAt.replace(/[:.]/g, "-");
   const outDir = options.outDir ? resolve(options.outDir) : join(projectRoot, ".kxm", "backups", `backup-${timestamp}`);
   const usedFilenames = new Set<string>();
-  const planned = stores.map((store) => {
-    let filename = basename(store.sourcePath);
-    if (usedFilenames.has(filename)) {
-      const sanitizedId = store.storeId.replace(/[^a-zA-Z0-9_.-]/g, "_");
-      filename = `${sanitizedId}-${filename}`;
-    }
-    usedFilenames.add(filename);
-    return { storeId: store.storeId, sourcePath: store.sourcePath, backupFile: filename };
-  });
-  return { projectRoot, outDir, createdAt, stores: planned };
+  const stores = discovered.stores.map((store) => ({
+    storeId: store.storeId,
+    sourcePath: store.sourcePath,
+    backupFile: backupFilename(store.sourcePath, store.storeId, usedFilenames),
+  }));
+  const files = discovered.files.map((file) => ({
+    id: file.id,
+    sourcePath: file.sourcePath,
+    backupFile: backupFilename(file.sourcePath, file.id, usedFilenames),
+  }));
+  return { projectRoot, outDir, createdAt, stores, files };
 }
 
 export function createBackup(options: {
   projectRoot?: string;
   outDir?: string;
   hubDataPath?: string;
+  env?: NodeJS.ProcessEnv;
 } = {}): { manifest: BackupManifest; outDir: string } {
-  const { projectRoot, outDir, createdAt, stores } = planBackup(options);
+  const { projectRoot, outDir, createdAt, stores, files } = planBackup(options);
   const backupId = `bk_${randomBytes(8).toString("hex")}`;
 
   if (!existsSync(outDir)) {
@@ -701,8 +813,38 @@ export function createBackup(options: {
   }
 
   const backedUpStores: BackupStoreRecord[] = [];
+  const backedUpFiles: BackupFileRecord[] = [];
+  const omitted: string[] = [];
+
   for (const store of stores) {
-    backedUpStores.push(backupDatabaseFile(store.sourcePath, join(outDir, store.backupFile), store.storeId));
+    try {
+      backedUpStores.push(backupDatabaseFile(store.sourcePath, join(outDir, store.backupFile), store.storeId));
+    } catch {
+      omitted.push(store.storeId);
+    }
+  }
+  for (const file of files) {
+    try {
+      backedUpFiles.push(backupPlainFile(file.sourcePath, join(outDir, file.backupFile), file.id));
+    } catch {
+      omitted.push(file.id);
+    }
+  }
+
+  if (backedUpStores.length === 0) {
+    throw databaseError("backup_no_stores", projectRoot, "no SQLite store could be copied");
+  }
+
+  const again = discoverBackupSources(projectRoot, backupDiscoverOptions(options));
+  for (const store of again.stores) {
+    if (!backedUpStores.some((copied) => copied.storeId === store.storeId) && !omitted.includes(store.storeId)) {
+      omitted.push(store.storeId);
+    }
+  }
+  for (const file of again.files) {
+    if (!backedUpFiles.some((copied) => copied.id === file.id) && !omitted.includes(file.id)) {
+      omitted.push(file.id);
+    }
   }
 
   const manifest: BackupManifest = {
@@ -711,6 +853,9 @@ export function createBackup(options: {
     createdAt,
     projectRoot,
     stores: backedUpStores,
+    ...(backedUpFiles.length > 0 ? { files: backedUpFiles } : {}),
+    complete: omitted.length === 0,
+    ...(omitted.length > 0 ? { omitted } : {}),
   };
 
   const manifestJson = JSON.stringify(manifest, null, 2) + "\n";
@@ -728,6 +873,7 @@ export interface RestorePlan {
   manifestPath: string;
   backupId: string;
   stores: Array<{ storeId: string; backupFilePath: string; targetPath: string; schemaVersion: number; maxSupportedVersion: number }>;
+  files: Array<{ id: string; backupFilePath: string; targetPath: string }>;
 }
 
 /** Everything restore checks before it overwrites anything: the manifest, each
@@ -762,6 +908,9 @@ export function planRestore(
   if (manifest.schema !== "kxm.backup-manifest.v1" || !Array.isArray(manifest.stores) || manifest.stores.length === 0) {
     throw databaseError("restore_manifest_invalid", manifestPath, "manifest is not a valid kxm.backup-manifest.v1 document");
   }
+  if (manifest.complete === false) {
+    throw databaseError("restore_incomplete", manifestPath, "backup manifest is incomplete; refusing to restore a partial copy");
+  }
 
   const stores: RestorePlan["stores"] = [];
   for (const store of manifest.stores) {
@@ -796,7 +945,29 @@ export function planRestore(
     stores.push({ storeId: store.storeId, backupFilePath, targetPath, schemaVersion: store.schemaVersion, maxSupportedVersion });
   }
 
-  return { manifestPath, backupId: manifest.backupId, stores };
+  const files: RestorePlan["files"] = [];
+  for (const file of manifest.files ?? []) {
+    const backupFilePath = join(manifestDir, file.backupFile);
+    if (!existsSync(backupFilePath)) {
+      throw databaseError("restore_file_missing", backupFilePath, `backup file ${file.backupFile} missing from ${manifestDir}`);
+    }
+    const actualSha256 = fileSha256(backupFilePath);
+    if (actualSha256 !== file.sha256) {
+      throw databaseError(
+        "restore_manifest_digest_mismatch",
+        backupFilePath,
+        `backup file ${file.backupFile} sha256 ${actualSha256} does not match manifest hash ${file.sha256}`,
+      );
+    }
+    let targetPath = file.sourcePath;
+    if (options.projectRoot && manifest.projectRoot && targetPath.startsWith(manifest.projectRoot)) {
+      const rel = targetPath.slice(manifest.projectRoot.length).replace(/^[\\/]+/, "");
+      targetPath = join(resolve(options.projectRoot), rel);
+    }
+    files.push({ id: file.id, backupFilePath, targetPath });
+  }
+
+  return { manifestPath, backupId: manifest.backupId, stores, files };
 }
 
 export function restoreBackup(
@@ -811,6 +982,9 @@ export function restoreBackup(
     store.schemaVersion,
     store.maxSupportedVersion,
   ));
+  for (const file of plan.files) {
+    restorePlainFile(file.backupFilePath, file.targetPath);
+  }
   return {
     manifestPath: plan.manifestPath,
     backupId: plan.backupId,