@kontextmind/kxm 0.7.96 → 0.7.98

package/plugins/kxm/src/cli.ts

@@ -18,7 +18,7 @@ import { Command, CommanderError } from "commander";
 import { readInstalledKxmVersion } from "./kxm-update.ts";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { HubClient } from "./client.ts";
-import { resolveClientHubAuthToken } from "./hub-env.ts";
+import { AgentProjectTokenMissingError, resolveAgentHubAuthToken } from "./hub-env.ts";
 import { defaultProjectName } from "./project-name.ts";
 import {
   AGENT_COMMANDS_MAP,
@@ -27,6 +27,7 @@ import {
 import { discoverKxmProjectRoot } from "./project-config.ts";
 import { JOURNAL_CATEGORIES } from "./workflow.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "./runtime-supervisor.ts";
+import { projectRuntimeOwnsRun } from "./runtime-store.ts";
 
 // Submodule imports
 import {
@@ -148,6 +149,7 @@ import {
   cmdConfigList,
   cmdCompletion,
   cmdCompletionInstall,
+  cmdPricesAcknowledge,
   cmdRoutingReport,
   cmdRoutingBenchmark,
   maybeOfferCompletionInstall,
@@ -234,14 +236,17 @@ async function ensureCliClient(runtime: Runtime): Promise<HubClient> {
   const project = defaultProjectName(runtime.cwd, runtime.env);
   const name = runtime.env.KXM_AGENT_NAME?.trim() || `cli-${process.pid}`;
   const purpose = runtime.env.KXM_AGENT_PURPOSE?.trim() || "CLI agent client";
-  const authToken = resolveClientHubAuthToken(runtime.env, project);
+  // These commands act as a peer agent, so they take the agent credential: never the
+  // persisted admin token, which the hub accepts for any project without its own token.
+  const authToken = resolveAgentHubAuthToken(runtime.env, project);
+  if (!authToken) throw new AgentProjectTokenMissingError(project);
   const client = new HubClient({
     serverUrl,
     name,
     project,
     purpose,
     fetchImpl: runtime.fetchImpl,
-    ...(authToken ? { authToken } : {}),
+    authToken,
   });
   await client.start(() => {});
   return client;
@@ -308,11 +313,12 @@ async function dispatchAgentCliCommand(
     }
   }
 
-  // Handle KXM run binding for workflow wait
+  // A workflow wait on a run this project's Runtime owns goes to the Runtime; any other
+  // run id, including a hub workflow run of the same shape, goes to the hub.
   if (toolName === "kxm_workflow_wait") {
     const runId = typeof args.runId === "string" ? args.runId : undefined;
     const projectRoot = discoverKxmProjectRoot(runtime.cwd);
-    if (runId && projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
+    if (runId && projectRoot && projectRuntimeOwnsRun(projectRoot, runId, runtime.env)) {
       if (runtime.dryRun) {
         print(runtime.io, runtime.json, { ok: true, command: "workflow wait", runId, dryRun: true }, `would wait for signal on KXM run ${runId}`);
         return 0;
@@ -349,6 +355,15 @@ async function dispatchAgentCliCommand(
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof AgentProjectTokenMissingError) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, error: error.code, project: error.project, nextAction: "export_kxm_auth_token", detail: message },
+        message,
+      );
+      return 2;
+    }
     print(runtime.io, runtime.json, { ok: false, error: "command_failed", detail: message }, `command failed: ${message}`);
     return 1;
   } finally {
@@ -402,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);
@@ -428,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 }) {
@@ -460,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");
@@ -914,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/client.ts

@@ -259,6 +259,8 @@ export class HubClient {
     ttlMs?: number;
     timeoutMs?: number;
     signal?: AbortSignal;
+    hops?: number;
+    maxHops?: number;
   }): Promise<FanoutResult[]> {
     const targets = [...new Set(options.targets.map((target) => target.trim().toLowerCase()).filter(Boolean))];
     if (targets.length < 1 || targets.length > 3) throw new Error("fanout requires between one and three unique targets");
@@ -280,6 +282,8 @@ export class HubClient {
             ),
           } : {}),
           ...(options.ttlMs ? { ttlMs: options.ttlMs } : {}),
+          ...(options.hops !== undefined ? { hops: options.hops } : {}),
+          ...(options.maxHops !== undefined ? { maxHops: options.maxHops } : {}),
         });
         const completed = await this.awaitResponse(
           message.id,

package/plugins/kxm/src/commands.ts

@@ -74,6 +74,26 @@ export interface CommandExecutionContext {
   signal?: AbortSignal | undefined;
   inbox?: Map<string, MessageRecord> | undefined;
   notifiedInbox?: Set<string> | undefined;
+  /** Inbound requests this session is handling: the Pi extension's active request, the MCP
+   * server's open inbox. A request sent meanwhile is one more hop along their chain. */
+  handling?: readonly Pick<MessageRecord, "hops" | "maxHops">[] | undefined;
+}
+
+/**
+ * Hop fields for a request sent while handling inbound work: one hop past the furthest
+ * handled request, under the tightest limit among them, so the hub's `hop_limit_reached`
+ * refusal bounds a chain of agents forwarding to each other. Handling nothing starts a new
+ * chain with the hub defaults. When several requests are open the furthest one counts, so a
+ * forwarding loop cannot reset its count because an unrelated request arrived beside it.
+ */
+export function forwardedHops(
+  handling: CommandExecutionContext["handling"],
+): { hops: number; maxHops: number } | undefined {
+  if (!handling?.length) return undefined;
+  return {
+    hops: Math.max(...handling.map((message) => message.hops)) + 1,
+    maxHops: Math.min(...handling.map((message) => message.maxHops)),
+  };
 }
 
 export interface AgentCommand {
@@ -260,12 +280,13 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
       required: ["target", "content"],
       additionalProperties: false,
     },
-    async execute(client, args) {
+    async execute(client, args, context) {
       const delivery = optionalString(args.delivery) as DeliveryMode | undefined;
       const correlationId = optionalString(args.correlationId);
       const idempotencyKey = optionalString(args.idempotencyKey);
       const workflowContext = optionalWorkflowContext(args.workflowContext);
       const message = await client.send({
+        ...forwardedHops(context?.handling),
         target: requiredString(args.target, "target"),
         content: requiredString(args.content, "content"),
         ...(delivery ? { delivery } : {}),
@@ -346,6 +367,7 @@ export const AGENT_COMMANDS: readonly AgentCommand[] = [
         : [];
       return {
         responses: await client.fanout({
+          ...forwardedHops(context?.handling),
           targets,
           content: requiredString(args.content, "content"),
           ...(optionalString(args.correlationId) ? { correlationId: optionalString(args.correlationId)! } : {}),

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,