@kontextmind/kxm 0.7.102 → 0.7.104

package/plugins/kxm/src/database.ts

@@ -10,10 +10,10 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
-import { kxmUserStateRoot } from "./bindings.ts";
 import { KxmConfigError, type KxmConfigIssue } from "./project-config.ts";
+import { kxmProjectRunEventsPath, kxmRuntimePaths, projectRuntimeKey, type KxmRuntimePaths } from "./runtime-paths.ts";
 
 export interface DatabaseSchemaSpec {
   schema: string;
@@ -40,11 +40,25 @@ export interface BackupFileRecord {
   bytes: number;
 }
 
+/**
+ * What a backup holds from the user state root. `project` (the default): the
+ * checkout's own Runtime event store and its prompt sidecar. `all-projects`: the
+ * shared Runtime registry and every project's event store, so restoring it rolls
+ * back every project on the machine.
+ */
+export type KxmBackupScope = "project" | "all-projects";
+
 export interface BackupManifest {
   schema: "kxm.backup-manifest.v1";
   backupId: string;
   createdAt: string;
   projectRoot?: string;
+  /** Absent on manifests written before backups were scoped. */
+  scope?: KxmBackupScope;
+  /** The user state root the Runtime stores were copied from; restore rebases them onto the current one. */
+  stateRoot?: string;
+  /** The Runtime store key of the checkout the backup ran from, derived as the Runtime derives it. */
+  runtimeProjectKey?: string;
   stores: BackupStoreRecord[];
   files?: BackupFileRecord[];
   /** False when a discovered store or prompt sidecar was left out. Absent on legacy manifests. */
@@ -642,49 +656,75 @@ function pushStore(stores: DiscoveredStore[], storeId: string, sourcePath: strin
   stores.push({ storeId, sourcePath, maxSupportedVersion: kxmBackupCeiling(storeId) });
 }
 
-function discoverUserRuntime(env: NodeJS.ProcessEnv | undefined, stores: DiscoveredStore[], files: DiscoveredFile[]): void {
-  let stateRoot: string;
+interface DiscoveredSources {
+  stores: DiscoveredStore[];
+  files: DiscoveredFile[];
+  stateRoot?: string;
+  runtimeProjectKey: string;
+}
+
+interface BackupDiscoverOptions {
+  hubDataPath?: string;
+  env?: NodeJS.ProcessEnv;
+  allProjects?: boolean;
+}
+
+function pushEventStore(stores: DiscoveredStore[], files: DiscoveredFile[], paths: KxmRuntimePaths, key: string): void {
+  const dbPath = join(paths.projectsDir, key, "run-events.db");
+  if (!existsSync(dbPath)) return;
+  const safe = key.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 });
+    }
+  }
+}
+
+/**
+ * The Runtime stores under the user state root. By default only this checkout's
+ * event store: the registry and the other projects' event stores are shared by every
+ * project on the machine, and a restore of them rolls all of those projects back, so
+ * only an explicit `allProjects` backup holds them.
+ */
+function discoverUserRuntime(
+  runtimeProjectKey: string,
+  options: BackupDiscoverOptions,
+  stores: DiscoveredStore[],
+  files: DiscoveredFile[],
+): string | undefined {
+  let paths: KxmRuntimePaths;
   try {
-    stateRoot = kxmUserStateRoot(env ? { env } : {});
+    paths = kxmRuntimePaths(options.env ? { env: options.env } : {});
   } catch {
-    return;
+    return undefined;
   }
-  const runtimeDir = join(stateRoot, "runtime");
-  const registryPath = join(runtimeDir, "registry.db");
-  if (existsSync(registryPath)) {
+  if (!options.allProjects) {
+    pushEventStore(stores, files, paths, runtimeProjectKey);
+    return paths.stateRoot;
+  }
+  if (existsSync(paths.registryDb)) {
     const storeId = stores.some((store) => store.storeId === "registry") ? "runtime-registry" : "registry";
-    pushStore(stores, storeId, registryPath);
+    pushStore(stores, storeId, paths.registryDb);
   }
-  const projectsDir = join(runtimeDir, "projects");
-  if (!existsSync(projectsDir)) return;
+  if (!existsSync(paths.projectsDir)) return paths.stateRoot;
   let entries;
   try {
-    entries = readdirSync(projectsDir, { withFileTypes: true });
+    entries = readdirSync(paths.projectsDir, { withFileTypes: true });
   } catch {
-    return;
+    return paths.stateRoot;
   }
   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 });
-      }
-    }
+    if (entry.isDirectory()) pushEventStore(stores, files, paths, entry.name);
   }
+  return paths.stateRoot;
 }
 
-function discoverBackupSources(
-  projectRoot: string,
-  options: { hubDataPath?: string; env?: NodeJS.ProcessEnv } = {},
-): { stores: DiscoveredStore[]; files: DiscoveredFile[] } {
+function discoverBackupSources(projectRoot: string, options: BackupDiscoverOptions = {}): DiscoveredSources {
   const root = resolve(projectRoot);
   const stores: DiscoveredStore[] = [];
   const files: DiscoveredFile[] = [];
@@ -709,8 +749,9 @@ function discoverBackupSources(
     }
   }
 
-  discoverUserRuntime(options.env, stores, files);
-  return { stores, files };
+  const runtimeProjectKey = projectRuntimeKey(root);
+  const stateRoot = discoverUserRuntime(runtimeProjectKey, options, stores, files);
+  return { stores, files, runtimeProjectKey, ...(stateRoot !== undefined ? { stateRoot } : {}) };
 }
 
 function backupPlainFile(sourcePath: string, targetPath: string, id: string): BackupFileRecord {
@@ -748,7 +789,7 @@ function restorePlainFile(backupFilePath: string, targetPath: string): void {
   try { chmodSync(targetPath, 0o600); } catch { /* Windows */ }
 }
 
-export function discoverProjectStores(projectRoot: string, options: { hubDataPath?: string; env?: NodeJS.ProcessEnv } = {}): Array<{ storeId: string; sourcePath: string; maxSupportedVersion: number }> {
+export function discoverProjectStores(projectRoot: string, options: BackupDiscoverOptions = {}): Array<{ storeId: string; sourcePath: string; maxSupportedVersion: number }> {
   return discoverBackupSources(projectRoot, options).stores;
 }
 
@@ -756,24 +797,26 @@ export interface BackupPlan {
   projectRoot: string;
   outDir: string;
   createdAt: string;
+  scope: KxmBackupScope;
+  stateRoot?: string;
+  runtimeProjectKey: 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 } {
+function backupDiscoverOptions(options: BackupDiscoverOptions): BackupDiscoverOptions {
   return {
     ...(options.hubDataPath !== undefined ? { hubDataPath: options.hubDataPath } : {}),
     ...(options.env !== undefined ? { env: options.env } : {}),
+    ...(options.allProjects === true ? { allProjects: true } : {}),
   };
 }
 
 /** 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: {
+export function planBackup(options: BackupDiscoverOptions & {
   projectRoot?: string;
   outDir?: string;
-  hubDataPath?: string;
-  env?: NodeJS.ProcessEnv;
 } = {}): BackupPlan {
   const projectRoot = options.projectRoot ? resolve(options.projectRoot) : process.cwd();
   const discovered = discoverBackupSources(projectRoot, backupDiscoverOptions(options));
@@ -796,16 +839,23 @@ export function planBackup(options: {
     sourcePath: file.sourcePath,
     backupFile: backupFilename(file.sourcePath, file.id, usedFilenames),
   }));
-  return { projectRoot, outDir, createdAt, stores, files };
+  return {
+    projectRoot,
+    outDir,
+    createdAt,
+    scope: options.allProjects === true ? "all-projects" : "project",
+    ...(discovered.stateRoot !== undefined ? { stateRoot: discovered.stateRoot } : {}),
+    runtimeProjectKey: discovered.runtimeProjectKey,
+    stores,
+    files,
+  };
 }
 
-export function createBackup(options: {
+export function createBackup(options: BackupDiscoverOptions & {
   projectRoot?: string;
   outDir?: string;
-  hubDataPath?: string;
-  env?: NodeJS.ProcessEnv;
 } = {}): { manifest: BackupManifest; outDir: string } {
-  const { projectRoot, outDir, createdAt, stores, files } = planBackup(options);
+  const { projectRoot, outDir, createdAt, scope, stateRoot, runtimeProjectKey, stores, files } = planBackup(options);
   const backupId = `bk_${randomBytes(8).toString("hex")}`;
 
   if (!existsSync(outDir)) {
@@ -852,6 +902,9 @@ export function createBackup(options: {
     backupId,
     createdAt,
     projectRoot,
+    scope,
+    ...(stateRoot !== undefined ? { stateRoot } : {}),
+    runtimeProjectKey,
     stores: backedUpStores,
     ...(backedUpFiles.length > 0 ? { files: backedUpFiles } : {}),
     complete: omitted.length === 0,
@@ -872,16 +925,74 @@ export function createBackup(options: {
 export interface RestorePlan {
   manifestPath: string;
   backupId: string;
+  /** The manifest's scope; absent on manifests written before backups were scoped. */
+  scope?: KxmBackupScope;
   stores: Array<{ storeId: string; backupFilePath: string; targetPath: string; schemaVersion: number; maxSupportedVersion: number }>;
   files: Array<{ id: string; backupFilePath: string; targetPath: string }>;
 }
 
+export interface RestoreOptions {
+  /** The checkout to restore into. Its stores are rebased onto it, and its own Runtime
+   * event store is the one the Runtime derives for it. */
+  projectRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  /** Also restore the shared Runtime registry and other projects' event stores. */
+  allProjects?: boolean;
+}
+
+function pathUnder(root: string | undefined, path: string): string | undefined {
+  if (!root) return undefined;
+  const rel = relative(root, path);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined;
+  return rel;
+}
+
+/**
+ * Where one backed-up store or file goes, and whether it belongs to this checkout.
+ *
+ * A path under the manifest's project root is rebased onto the checkout being restored.
+ * The checkout's own Runtime event store (and its prompt sidecar) goes to the store the
+ * Runtime derives for that checkout, under the current user state root. Anything else
+ * under the user state root is machine-wide — the registry, another project's event
+ * store — and so is anything outside both recorded roots except a relocated hub store,
+ * which is how a manifest written before scopes records Runtime stores. Those restore
+ * only with `allProjects`, rebased onto the current user state root when the manifest
+ * recorded one.
+ */
+function restoreTarget(
+  manifest: BackupManifest,
+  sourcePath: string,
+  id: string,
+  options: RestoreOptions,
+  currentStateRoot: () => string,
+): { targetPath: string; machineWide: boolean } {
+  const stateRel = pathUnder(manifest.stateRoot, sourcePath);
+  const projectRel = pathUnder(manifest.projectRoot, sourcePath);
+  // KXM_STATE_HOME may sit inside the checkout; the deeper root owns the path.
+  if (stateRel !== undefined && (projectRel === undefined || stateRel.length <= projectRel.length)) {
+    const ownEvents = manifest.runtimeProjectKey !== undefined
+      ? join("runtime", "projects", manifest.runtimeProjectKey, "run-events.db")
+      : undefined;
+    const own = ownEvents !== undefined && (stateRel === ownEvents || stateRel === `${ownEvents}.run-prompts.json`);
+    if (own && !options.allProjects && options.projectRoot !== undefined) {
+      const eventsPath = kxmProjectRunEventsPath(resolve(options.projectRoot), options.env ?? process.env);
+      return { targetPath: stateRel === ownEvents ? eventsPath : `${eventsPath}.run-prompts.json`, machineWide: false };
+    }
+    return { targetPath: join(currentStateRoot(), stateRel), machineWide: !own };
+  }
+  if (projectRel !== undefined) {
+    return { targetPath: options.projectRoot ? join(resolve(options.projectRoot), projectRel) : sourcePath, machineWide: false };
+  }
+  return { targetPath: sourcePath, machineWide: id !== "hub-store" };
+}
+
 /** Everything restore checks before it overwrites anything: the manifest, each
- * backup file's digest, and each store's schema against this build's ceiling
- * (from the manifest). Reads files; opens no database. */
+ * backup file's digest, each store's schema against this build's ceiling (from
+ * the manifest), and that nothing outside this checkout would be overwritten
+ * without `allProjects`. Reads files; opens no database. */
 export function planRestore(
   manifestPathOrDir: string,
-  options: { projectRoot?: string } = {},
+  options: RestoreOptions = {},
 ): RestorePlan {
   let manifestPath = resolve(manifestPathOrDir);
   const stat = lstatSync(manifestPath, { throwIfNoEntry: false });
@@ -912,6 +1023,10 @@ export function planRestore(
     throw databaseError("restore_incomplete", manifestPath, "backup manifest is incomplete; refusing to restore a partial copy");
   }
 
+  let stateRoot: string | undefined;
+  const currentStateRoot = (): string => (stateRoot ??= kxmRuntimePaths({ env: options.env ?? process.env }).stateRoot);
+  const machineWide: string[] = [];
+
   const stores: RestorePlan["stores"] = [];
   for (const store of manifest.stores) {
     const backupFilePath = join(manifestDir, store.backupFile);
@@ -937,12 +1052,9 @@ export function planRestore(
       );
     }
 
-    let targetPath = store.sourcePath;
-    if (options.projectRoot && manifest.projectRoot && targetPath.startsWith(manifest.projectRoot)) {
-      const rel = targetPath.slice(manifest.projectRoot.length).replace(/^[\\/]+/, "");
-      targetPath = join(resolve(options.projectRoot), rel);
-    }
-    stores.push({ storeId: store.storeId, backupFilePath, targetPath, schemaVersion: store.schemaVersion, maxSupportedVersion });
+    const target = restoreTarget(manifest, store.sourcePath, store.storeId, options, currentStateRoot);
+    if (target.machineWide) machineWide.push(store.storeId);
+    stores.push({ storeId: store.storeId, backupFilePath, targetPath: target.targetPath, schemaVersion: store.schemaVersion, maxSupportedVersion });
   }
 
   const files: RestorePlan["files"] = [];
@@ -959,22 +1071,31 @@ export function planRestore(
         `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 });
+    const target = restoreTarget(manifest, file.sourcePath, file.id, options, currentStateRoot);
+    if (target.machineWide) machineWide.push(file.id);
+    files.push({ id: file.id, backupFilePath, targetPath: target.targetPath });
   }
 
-  return { manifestPath, backupId: manifest.backupId, stores, files };
+  if (machineWide.length > 0 && !options.allProjects) {
+    throw databaseError(
+      "restore_requires_all_projects",
+      manifestPath,
+      `backup ${manifest.backupId} holds Runtime state shared by every project on this machine (${machineWide.join(", ")}); `
+        + "restoring it rolls back the registry or other projects' runs. Pass --all-projects to restore all of it, or restore a backup taken without --all-projects",
+    );
+  }
+
+  return {
+    manifestPath,
+    backupId: manifest.backupId,
+    ...(manifest.scope !== undefined ? { scope: manifest.scope } : {}),
+    stores,
+    files,
+  };
 }
 
-export function restoreBackup(
-  manifestPathOrDir: string,
-  options: { projectRoot?: string } = {},
-): RestoreResult {
-  const plan = planRestore(manifestPathOrDir, options);
+/** Overwrite each target in a checked plan: the stores, then their prompt sidecars. */
+export function applyRestorePlan(plan: RestorePlan): RestoreResult {
   const restoredStores = plan.stores.map((store) => restoreDatabaseFile(
     store.backupFilePath,
     store.targetPath,
@@ -991,3 +1112,10 @@ export function restoreBackup(
     restoredStores,
   };
 }
+
+export function restoreBackup(
+  manifestPathOrDir: string,
+  options: RestoreOptions = {},
+): RestoreResult {
+  return applyRestorePlan(planRestore(manifestPathOrDir, options));
+}

package/plugins/kxm/src/init-guide-setup.ts

@@ -16,8 +16,15 @@
  * and does not use the kxm.role.v1 subsystem.
  *
  * Guide research ids are not dispatch ids. Only the admitted map below is
- * written, and only when that harness is authenticated. Google goes through
- * the Pi `antigravity` provider. Unmapped ids are skipped.
+ * written, and only when that harness is authenticated. Unmapped ids are skipped.
+ *
+ * Google candidates are unmapped on purpose. Google's route is the Pi
+ * `antigravity` provider, which only the KXM Pi extension registers. The
+ * Runtime's Pi one-shot runs with `--no-extensions`, and `pi auth check` never
+ * loads extensions, so a drive of an `antigravity/…` role fails at dispatch.
+ * Mapping Google to `agy` instead would contradict the routing decision. Add
+ * Google back only when drive can reach `antigravity` and a reviewed
+ * admission decision says so.
  */
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
@@ -55,8 +62,6 @@ const ADMITTED_GUIDE_BINDINGS: Readonly<Record<string, AgentBinding>> = Object.f
   "openai/gpt-5.6-sol": { harness: "codex", provider: "openai", model: "gpt-5.6-sol" },
   "x-ai/grok-4.6": { harness: "grok", provider: "xai", model: "grok-4.6" },
   "xai/grok-4.6": { harness: "grok", provider: "xai", model: "grok-4.6" },
-  "google/gemini-3.8-flash": { harness: "pi", provider: "antigravity", model: "gemini-3.8-flash-high" },
-  "google/gemini-3.8-flash-high": { harness: "pi", provider: "antigravity", model: "gemini-3.8-flash-high" },
   "qwen/qwen3-coder-plus": { harness: "pi", provider: "openrouter", model: "qwen/qwen3-coder-plus" },
 });
 

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.102";
+const VERSION = "0.7.104";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/runtime-paths.ts

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { kxmUserStateRoot } from "./bindings.ts";
+
+/* ------------------------------------------------------------------ *
+ * Where the Runtime keeps its stores under the user state root.
+ *
+ * A leaf module on purpose: backup and restore (`database.ts`) must find a
+ * project's event store exactly as the Runtime does, and `runtime-store.ts`
+ * imports `database.ts`, so the derivation cannot live there without a cycle.
+ * ------------------------------------------------------------------ */
+
+export interface KxmRuntimePaths {
+  stateRoot: string;
+  runtimeDir: string;
+  registryDb: string;
+  projectsDir: string;
+}
+
+export function kxmRuntimePaths(options: { stateRoot?: string; env?: NodeJS.ProcessEnv; homeDir?: string } = {}): KxmRuntimePaths {
+  const stateRoot = options.stateRoot
+    ? resolve(options.stateRoot)
+    : kxmUserStateRoot({ ...(options.env ? { env: options.env } : {}), ...(options.homeDir ? { homeDir: options.homeDir } : {}) });
+  const runtimeDir = join(stateRoot, "runtime");
+  return {
+    stateRoot,
+    runtimeDir,
+    registryDb: join(runtimeDir, "registry.db"),
+    projectsDir: join(runtimeDir, "projects"),
+  };
+}
+
+export function projectRuntimeKey(projectRoot: string): string {
+  // Canonicalize through the filesystem like the repository binding store so
+  // reaching a project through a link cannot mint a second key for it.
+  let canonical: string;
+  try {
+    canonical = realpathSync.native(resolve(projectRoot));
+  } catch {
+    canonical = resolve(projectRoot);
+  }
+  const folded = process.platform === "win32" ? canonical.toLocaleLowerCase("en-US") : canonical;
+  return createHash("sha256").update(folded, "utf8").digest("hex").slice(0, 24);
+}
+
+/** The project's Runtime event store, derived exactly as the Runtime derives it. */
+export function kxmProjectRunEventsPath(projectRoot: string, env: NodeJS.ProcessEnv): string {
+  return join(kxmRuntimePaths({ env }).projectsDir, projectRuntimeKey(projectRoot), "run-events.db");
+}

package/plugins/kxm/src/runtime-store.ts

@@ -1,34 +1,16 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { DatabaseSync, openReadOnlyDatabase } from "./sqlite.ts";
 import { KxmConfigError, validateCoordinator, validateDriveReceipt, validateIntakeMessage, validateRunEvent, kxmCanonicalJson, type JsonValue, type KxmConfigIssue, type KxmConfigOptions } from "./project-config.ts";
-import { kxmUserStateRoot } from "./bindings.ts";
+import { kxmProjectRunEventsPath, projectRuntimeKey } from "./runtime-paths.ts";
 import { deriveKxmSyncEvent, kxmSyncEventBytes, KxmSyncRedactor } from "./sync-transform.ts";
 
 /* ------------------------------------------------------------------ *
  * Runtime registry (per-user, platform state root)
  * ------------------------------------------------------------------ */
 
-export interface KxmRuntimePaths {
-  stateRoot: string;
-  runtimeDir: string;
-  registryDb: string;
-  projectsDir: string;
-}
-
-export function kxmRuntimePaths(options: { stateRoot?: string; env?: NodeJS.ProcessEnv; homeDir?: string } = {}): KxmRuntimePaths {
-  const stateRoot = options.stateRoot
-    ? resolve(options.stateRoot)
-    : kxmUserStateRoot({ ...(options.env ? { env: options.env } : {}), ...(options.homeDir ? { homeDir: options.homeDir } : {}) });
-  const runtimeDir = join(stateRoot, "runtime");
-  return {
-    stateRoot,
-    runtimeDir,
-    registryDb: join(runtimeDir, "registry.db"),
-    projectsDir: join(runtimeDir, "projects"),
-  };
-}
+export { kxmRuntimePaths, projectRuntimeKey, kxmProjectRunEventsPath, type KxmRuntimePaths } from "./runtime-paths.ts";
 
 function runtimeIssue(phase: KxmConfigIssue["phase"], code: string, file: string, message: string): KxmConfigIssue {
   return { phase, code, file, message };
@@ -38,24 +20,6 @@ export function runtimeError(code: string, file: string, message: string): KxmCo
   return new KxmConfigError([runtimeIssue("semantic", code, file, message)]);
 }
 
-export function projectRuntimeKey(projectRoot: string): string {
-  // Canonicalize through the filesystem like the repository binding store so
-  // reaching a project through a link cannot mint a second key for it.
-  let canonical: string;
-  try {
-    canonical = realpathSync.native(resolve(projectRoot));
-  } catch {
-    canonical = resolve(projectRoot);
-  }
-  const folded = process.platform === "win32" ? canonical.toLocaleLowerCase("en-US") : canonical;
-  return createHash("sha256").update(folded, "utf8").digest("hex").slice(0, 24);
-}
-
-/** The project's Runtime event store, derived exactly as the Runtime derives it. */
-export function kxmProjectRunEventsPath(projectRoot: string, env: NodeJS.ProcessEnv): string {
-  return join(kxmRuntimePaths({ env }).projectsDir, projectRuntimeKey(projectRoot), "run-events.db");
-}
-
 /**
  * Whether this project's Runtime event store holds `runId`. Hub workflow runs and Runtime
  * runs share the `run_<32 hex>` shape, so a command addressed by run id asks the owning
@@ -141,6 +105,24 @@ CREATE TABLE projects (
 ) STRICT;
 `;
 
+/** The supervisor singleton row, from any connection to a registry, including a read-only one. */
+export function readKxmSupervisorRecord(database: DatabaseSync): KxmSupervisorRecord | undefined {
+  const row = database.prepare("SELECT runtime_id, pid, port, token_hash, started_at, heartbeat_at, state FROM supervisor WHERE singleton_id = 1").get() as
+    | { runtime_id: string; pid: number; port: number; token_hash: string; started_at: string; heartbeat_at: string; state: KxmSupervisorRecord["state"] }
+    | undefined;
+  return row
+    ? {
+      runtimeId: row.runtime_id,
+      pid: row.pid,
+      port: row.port,
+      tokenHash: row.token_hash,
+      startedAt: row.started_at,
+      heartbeatAt: row.heartbeat_at,
+      state: row.state,
+    }
+    : undefined;
+}
+
 export class KxmRuntimeRegistry {
   readonly path: string;
   private readonly database: DatabaseSync;
@@ -228,20 +210,7 @@ export class KxmRuntimeRegistry {
   }
 
   private readSupervisorRow(): KxmSupervisorRecord | undefined {
-    const row = this.database.prepare("SELECT runtime_id, pid, port, token_hash, started_at, heartbeat_at, state FROM supervisor WHERE singleton_id = 1").get() as
-      | { runtime_id: string; pid: number; port: number; token_hash: string; started_at: string; heartbeat_at: string; state: KxmSupervisorRecord["state"] }
-      | undefined;
-    return row
-      ? {
-        runtimeId: row.runtime_id,
-        pid: row.pid,
-        port: row.port,
-        tokenHash: row.token_hash,
-        startedAt: row.started_at,
-        heartbeatAt: row.heartbeat_at,
-        state: row.state,
-      }
-      : undefined;
+    return readKxmSupervisorRecord(this.database);
   }
 
   supervisor(): KxmSupervisorRecord | undefined {

package/plugins/kxm/src/runtime-supervisor.ts

@@ -8,12 +8,15 @@ import { loadKxmProject, KxmConfigError, type KxmConfigOptions } from "./project
 import {
   KxmRuntimeRegistry,
   projectRuntimeKey,
+  readKxmSupervisorRecord,
   runtimeError,
   verifyKxmDriveReceipt,
   kxmRuntimePaths,
   type KxmRunEventStore,
   type KxmRuntimePaths,
+  type KxmSupervisorRecord,
 } from "./runtime-store.ts";
+import { openReadOnlyDatabase } from "./sqlite.ts";
 import {
   acceptKxmRun,
   cancelKxmRun,
@@ -122,26 +125,44 @@ function readRecentSupervisorError(paths: KxmRuntimePaths): string | undefined {
   }
 }
 
-export function kxmSupervisorStatus(paths: KxmRuntimePaths): KxmSupervisorStatus {
+function supervisorStatusOf(record: KxmSupervisorRecord | undefined): KxmSupervisorStatus {
+  if (!record) return { running: false };
+  // Pid-only liveness is not enough: after a crash the pid may be reused by
+  // an unrelated process. A stale heartbeat is authoritative.
+  const heartbeatAgeMs = Date.now() - Date.parse(record.heartbeatAt);
+  const fresh = Number.isFinite(heartbeatAgeMs) && heartbeatAgeMs < HEARTBEAT_STALE_MS;
+  const alive = record.state === "running" && fresh && processAlive(record.pid);
+  return {
+    running: alive,
+    runtimeId: record.runtimeId,
+    pid: record.pid,
+    port: record.port,
+    state: alive ? record.state : "dead",
+    heartbeatAt: record.heartbeatAt,
+    startedAt: record.startedAt,
+  };
+}
+
+/**
+ * Is the supervisor up? `readOnly` gives the same answer without opening the
+ * registry for writing: the ordinary open takes the write lock and, as the last
+ * connection, checkpoints the WAL on close. `kxm restore` asks this way, dry run
+ * or not, because a project-scoped restore never otherwise touches the registry.
+ */
+export function kxmSupervisorStatus(paths: KxmRuntimePaths, options: { readOnly?: boolean } = {}): KxmSupervisorStatus {
   if (!existsSync(paths.registryDb)) return { running: false };
+  if (options.readOnly) {
+    const database = openReadOnlyDatabase(paths.registryDb);
+    try {
+      database.exec("PRAGMA busy_timeout = 5000");
+      return supervisorStatusOf(readKxmSupervisorRecord(database));
+    } finally {
+      database.close();
+    }
+  }
   const registry = new KxmRuntimeRegistry(paths.registryDb);
   try {
-    const record = registry.supervisor();
-    if (!record) return { running: false };
-    // Pid-only liveness is not enough: after a crash the pid may be reused by
-    // an unrelated process. A stale heartbeat is authoritative.
-    const heartbeatAgeMs = Date.now() - Date.parse(record.heartbeatAt);
-    const fresh = Number.isFinite(heartbeatAgeMs) && heartbeatAgeMs < HEARTBEAT_STALE_MS;
-    const alive = record.state === "running" && fresh && processAlive(record.pid);
-    return {
-      running: alive,
-      runtimeId: record.runtimeId,
-      pid: record.pid,
-      port: record.port,
-      state: alive ? record.state : "dead",
-      heartbeatAt: record.heartbeatAt,
-      startedAt: record.startedAt,
-    };
+    return supervisorStatusOf(registry.supervisor());
   } finally {
     registry.close();
   }