@kontextmind/kxm 0.7.128 → 0.7.130

package/plugins/kxm/dist/runtime-supervisor.js

@@ -14783,7 +14783,7 @@ import { spawn as spawn3 } from "node:child_process";
 import { createHash as createHash15, createHmac, randomBytes as randomBytes2, timingSafeEqual as timingSafeEqual2 } from "node:crypto";
 import { chmodSync as chmodSync2, existsSync as existsSync16, lstatSync as lstatSync6, mkdirSync as mkdirSync9, readFileSync as readFileSync13, renameSync as renameSync5, rmSync as rmSync4, writeFileSync as writeFileSync9 } from "node:fs";
 import { createServer } from "node:http";
-import { dirname as dirname11, isAbsolute as isAbsolute7, join as join18 } from "node:path";
+import { dirname as dirname11, isAbsolute as isAbsolute8, join as join18 } from "node:path";
 
 // plugins/kxm/src/repo-root.ts
 import { existsSync } from "node:fs";
@@ -18244,9 +18244,10 @@ function legacyConfigFilesAt(root) {
 }
 
 // plugins/kxm/src/runtime-store.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
 import { createHash as createHash6, randomUUID } from "node:crypto";
-import { existsSync as existsSync6, lstatSync as lstatSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname5, resolve as resolve6 } from "node:path";
+import { existsSync as existsSync6, lstatSync as lstatSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, realpathSync as realpathSync3, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname5, isAbsolute as isAbsolute4, resolve as resolve6 } from "node:path";
 
 // plugins/kxm/src/sqlite.ts
 import { existsSync as existsSync4 } from "node:fs";
@@ -18760,22 +18761,25 @@ function ensureWalJournalMode(database, file, description, timeoutMs = 5e3) {
     Atomics.wait(sleeper, 0, 0, 10);
   }
 }
+function assertDatabaseFile(file, description) {
+  checkedParent(file, description);
+  const stat = lstatSync2(file, { throwIfNoEntry: false });
+  if (stat) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw databaseError("runtime_path_invalid", description, `${description} must be a regular file, not a link or directory`);
+    }
+  }
+  for (const sidecar of [`${file}-wal`, `${file}-shm`]) {
+    const info = lstatSync2(sidecar, { throwIfNoEntry: false });
+    if (info?.isSymbolicLink()) {
+      throw databaseError("runtime_path_invalid", description, `${description} sidecar must not be a link`);
+    }
+  }
+}
 function openDatabase(file, description, spec) {
   const isMemory = file === ":memory:";
   if (!isMemory) {
-    checkedParent(file, description);
-    const stat = lstatSync2(file, { throwIfNoEntry: false });
-    if (stat) {
-      if (stat.isSymbolicLink() || !stat.isFile()) {
-        throw databaseError("runtime_path_invalid", description, `${description} must be a regular file, not a link or directory`);
-      }
-    }
-    for (const sidecar of [`${file}-wal`, `${file}-shm`]) {
-      const info = lstatSync2(sidecar, { throwIfNoEntry: false });
-      if (info?.isSymbolicLink()) {
-        throw databaseError("runtime_path_invalid", description, `${description} sidecar must not be a link`);
-      }
-    }
+    assertDatabaseFile(file, description);
   }
   const database = new DatabaseSync(file);
   let transaction = false;
@@ -18804,7 +18808,7 @@ function openDatabase(file, description, spec) {
       throw databaseError(
         "runtime_schema_outdated",
         file,
-        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file to start fresh and let its owning process recreate it (\`kxm hub start\` for hub state, the Runtime for registry/event stores); \`kxm init\` is project-only and rebuilds no database \u2014 upgrading old state in place is deliberately unsupported`
+        `${description} is schema version ${version}; this build requires ${spec.version}. Delete the state file to start fresh and let its owning process recreate it (\`kxm hub start\` for hub state, the Runtime for event stores). The Runtime registry copy from schema 1 to 2 is the one exception. \`kxm init\` is project-only and rebuilds no database. Upgrading any other old state in place is deliberately unsupported`
       );
     }
     if (spec.tables) {
@@ -18917,10 +18921,10 @@ function runtimeIssue(phase, code, file, message) {
 function runtimeError(code, file, message) {
   return new KxmConfigError([runtimeIssue("semantic", code, file, message)]);
 }
-var KXM_REGISTRY_SCHEMA_VERSION = 1;
+var KXM_REGISTRY_SCHEMA_VERSION = 2;
 var REGISTRY_TABLES = {
   supervisor: ["singleton_id", "runtime_id", "pid", "port", "token_hash", "started_at", "heartbeat_at", "state"],
-  projects: ["project_id", "project_root", "project_key", "home_runtime_id", "config_revision", "registered_at"]
+  projects: ["project_id", "project_root", "project_key", "home_runtime_id", "config_revision", "registered_at", "lane_of"]
 };
 var REGISTRY_SCHEMA = `
 CREATE TABLE supervisor (
@@ -18934,14 +18938,117 @@ CREATE TABLE supervisor (
   state TEXT NOT NULL
 ) STRICT;
 CREATE TABLE projects (
-  project_id TEXT PRIMARY KEY,
+  project_key TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
   project_root TEXT NOT NULL,
-  project_key TEXT NOT NULL UNIQUE,
   home_runtime_id TEXT NOT NULL,
   config_revision TEXT,
-  registered_at TEXT NOT NULL
+  registered_at TEXT NOT NULL,
+  lane_of TEXT
 ) STRICT;
+CREATE INDEX projects_by_project_id ON projects (project_id);
 `;
+var PROJECT_COLUMNS = "project_id, project_root, project_key, home_runtime_id, config_revision, registered_at, lane_of";
+function registrationFromRow(row) {
+  return {
+    projectId: row.project_id,
+    projectRoot: row.project_root,
+    projectKey: row.project_key,
+    homeRuntimeId: row.home_runtime_id,
+    ...row.config_revision !== null ? { configRevision: row.config_revision } : {},
+    ...row.lane_of !== null ? { laneOf: row.lane_of } : {},
+    registeredAt: row.registered_at
+  };
+}
+function controlRootDirectoryExists(projectRoot) {
+  const stat = statSync(projectRoot, { throwIfNoEntry: false });
+  return Boolean(stat?.isDirectory());
+}
+function gitEnv() {
+  return Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.toUpperCase().startsWith("GIT_")));
+}
+function gitCommonDirectory(projectRoot) {
+  const result = spawnSync3("git", ["-C", projectRoot, "rev-parse", "--git-common-dir"], {
+    encoding: "utf8",
+    env: gitEnv(),
+    timeout: 3e4,
+    windowsHide: true
+  });
+  if (result.status !== 0) return void 0;
+  const text = (result.stdout ?? "").trim();
+  if (!text) return void 0;
+  const absolute = isAbsolute4(text) ? text : resolve6(projectRoot, text);
+  let canonical;
+  try {
+    canonical = realpathSync3.native(absolute);
+  } catch {
+    canonical = resolve6(absolute);
+  }
+  return process.platform === "win32" ? canonical.toLocaleLowerCase("en-US") : canonical;
+}
+function isPrimaryWorktree(projectRoot, commonDir) {
+  if (commonDir === void 0) return false;
+  const dotGit = resolve6(projectRoot, ".git");
+  let canonical;
+  try {
+    canonical = realpathSync3.native(dotGit);
+  } catch {
+    canonical = resolve6(dotGit);
+  }
+  if (process.platform === "win32") canonical = canonical.toLocaleLowerCase("en-US");
+  return canonical === commonDir;
+}
+function migrateRegistryLanes(file) {
+  const stat = lstatSync3(file, { throwIfNoEntry: false });
+  if (!stat) return;
+  assertDatabaseFile(file, "runtime registry");
+  const database = new DatabaseSync(file);
+  let transaction = false;
+  try {
+    database.exec("PRAGMA busy_timeout = 5000");
+    const current = database.prepare("PRAGMA user_version").get();
+    if ((current?.user_version ?? 0) !== 1) return;
+    database.exec("BEGIN IMMEDIATE");
+    transaction = true;
+    const locked = database.prepare("PRAGMA user_version").get();
+    if ((locked?.user_version ?? 0) !== 1) {
+      database.exec("ROLLBACK");
+      transaction = false;
+      return;
+    }
+    if (!tableColumns(database, "projects").includes("lane_of")) {
+      database.exec(`
+        CREATE TABLE projects_v2 (
+          project_key TEXT PRIMARY KEY,
+          project_id TEXT NOT NULL,
+          project_root TEXT NOT NULL,
+          home_runtime_id TEXT NOT NULL,
+          config_revision TEXT,
+          registered_at TEXT NOT NULL,
+          lane_of TEXT
+        ) STRICT;
+        INSERT INTO projects_v2 (project_key, project_id, project_root, home_runtime_id, config_revision, registered_at, lane_of)
+        SELECT project_key, project_id, project_root, home_runtime_id, config_revision, registered_at, NULL FROM projects;
+        DROP TABLE projects;
+        ALTER TABLE projects_v2 RENAME TO projects;
+        CREATE INDEX projects_by_project_id ON projects (project_id);
+      `);
+    }
+    database.exec("PRAGMA user_version = 2");
+    database.exec("COMMIT");
+    transaction = false;
+  } catch (error) {
+    if (transaction) {
+      try {
+        database.exec("ROLLBACK");
+      } catch {
+      }
+    }
+    throw error;
+  } finally {
+    database.close();
+  }
+}
 function readKxmSupervisorRecord(database) {
   const row = database.prepare("SELECT runtime_id, pid, port, token_hash, started_at, heartbeat_at, state FROM supervisor WHERE singleton_id = 1").get();
   return row ? {
@@ -18959,6 +19066,7 @@ var KxmRuntimeRegistry = class {
   database;
   constructor(path) {
     this.path = resolve6(path);
+    migrateRegistryLanes(this.path);
     this.database = openDatabase(this.path, "runtime registry", {
       schema: REGISTRY_SCHEMA,
       version: KXM_REGISTRY_SCHEMA_VERSION,
@@ -19037,57 +19145,188 @@ var KxmRuntimeRegistry = class {
   supervisor() {
     return this.readSupervisorRow();
   }
-  /** Register or revalidate a project's home binding. Home Runtime is immutable. */
-  /** All projects registered to this Runtime, for restart recovery: the
-   * supervisor needs to reopen their contexts so pending outbox rows resume
-   * syncing and presence keeps beating. */
+  /** All projects registered to this Runtime, including lane roots, for restart
+   * recovery: the supervisor reopens their contexts so pending outbox rows
+   * resume syncing and presence keeps beating. */
   projectsForRuntime(homeRuntimeId) {
     const rows = this.database.prepare(
       "SELECT project_root, project_id FROM projects WHERE home_runtime_id = ? ORDER BY registered_at"
     ).all(homeRuntimeId);
     return rows.map((row) => ({ projectRoot: row.project_root, projectId: row.project_id }));
   }
+  /**
+   * Register or revalidate a control root. The home runtime of a live row is
+   * immutable. A second root whose git common directory matches a live row
+   * for the same project is a lane, unless the registering root is the primary
+   * worktree and the live home row is not: then the primary becomes the home
+   * row (same home runtime id) and every other live row of that repository
+   * becomes its lane. A primary never becomes a lane. A root whose directory
+   * is gone is replaced. A live root that is a different repository is
+   * `project_home_conflict`.
+   */
   registerProject(registration) {
     const projectRoot = resolve6(registration.projectRoot);
     const projectKey = projectRuntimeKey(projectRoot);
+    const candidateCommon = gitCommonDirectory(projectRoot);
+    const commonByRoot = /* @__PURE__ */ new Map();
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      this.database.exec("BEGIN IMMEDIATE");
+      let rootsToMeasure;
+      try {
+        const byKey = this.projectRow("SELECT " + PROJECT_COLUMNS + " FROM projects WHERE project_key = ?", projectKey);
+        if (byKey) {
+          const problems = [];
+          if (byKey.project_id !== registration.projectId) problems.push(`control root is already bound to a different project id ${byKey.project_id}`);
+          if (byKey.home_runtime_id !== registration.homeRuntimeId) problems.push(`project ${registration.projectId} home runtime is immutable and cannot be rebound`);
+          if (problems.length > 0) {
+            this.database.exec("ROLLBACK");
+            throw runtimeError("project_home_conflict", ".kxm/project.yaml", problems.join("; "));
+          }
+          const result = registrationFromRow(byKey);
+          this.database.exec("COMMIT");
+          return result;
+        }
+        const rows = this.database.prepare(
+          `SELECT ${PROJECT_COLUMNS} FROM projects WHERE project_id = ? ORDER BY registered_at`
+        ).all(registration.projectId);
+        const live = rows.filter((row) => controlRootDirectoryExists(row.project_root));
+        const dead = rows.filter((row) => !controlRootDirectoryExists(row.project_root));
+        const unknown = live.filter((row) => !commonByRoot.has(row.project_root));
+        if (unknown.length > 0) {
+          rootsToMeasure = unknown.map((row) => row.project_root);
+          this.database.exec("ROLLBACK");
+        } else if (live.length > 0) {
+          const anchor = live.find((row) => {
+            const dir = commonByRoot.get(row.project_root);
+            return candidateCommon !== void 0 && dir === candidateCommon;
+          });
+          if (!anchor) {
+            this.database.exec("ROLLBACK");
+            throw runtimeError(
+              "project_home_conflict",
+              ".kxm/project.yaml",
+              `project ${registration.projectId} is already bound to a different control root`
+            );
+          }
+          if (live.some((row) => row.home_runtime_id !== registration.homeRuntimeId)) {
+            this.database.exec("ROLLBACK");
+            throw runtimeError(
+              "project_home_conflict",
+              ".kxm/project.yaml",
+              `project ${registration.projectId} home runtime is immutable and cannot be rebound`
+            );
+          }
+          const sameRepo = live.filter((row) => commonByRoot.get(row.project_root) === candidateCommon);
+          const home = sameRepo.find((row) => row.lane_of === null);
+          const registeringIsPrimary = isPrimaryWorktree(projectRoot, candidateCommon);
+          const homeIsPrimary = home !== void 0 && isPrimaryWorktree(home.project_root, commonByRoot.get(home.project_root));
+          if (registeringIsPrimary && !homeIsPrimary) {
+            this.insertHome(registration, projectRoot, projectKey);
+            for (const row of sameRepo) {
+              this.database.prepare("UPDATE projects SET lane_of = ? WHERE project_key = ?").run(projectKey, row.project_key);
+            }
+            this.database.exec("COMMIT");
+            registration.logger?.({
+              event: "project_home_promoted",
+              projectId: registration.projectId,
+              projectRoot,
+              homeRuntimeId: registration.homeRuntimeId,
+              previousHomeRoot: home?.project_root ?? null,
+              previousHomeKey: home?.project_key ?? null
+            });
+            return this.insertedRegistration(registration, projectRoot, projectKey);
+          }
+          if (registeringIsPrimary) {
+            this.database.exec("ROLLBACK");
+            throw runtimeError(
+              "project_home_conflict",
+              ".kxm/project.yaml",
+              `project ${registration.projectId} primary checkout is already the home row`
+            );
+          }
+          const laneOf = anchor.lane_of ?? anchor.project_key;
+          this.database.prepare(`
+            INSERT INTO projects (project_key, project_id, project_root, home_runtime_id, config_revision, registered_at, lane_of)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+          `).run(projectKey, registration.projectId, projectRoot, registration.homeRuntimeId, registration.configRevision ?? null, registration.now, laneOf);
+          const result = this.insertedRegistration(registration, projectRoot, projectKey, laneOf);
+          this.database.exec("COMMIT");
+          return result;
+        } else if (dead.length > 0) {
+          const replaced = dead[0];
+          if (dead.some((row) => row.home_runtime_id !== registration.homeRuntimeId)) {
+            this.database.exec("ROLLBACK");
+            throw runtimeError(
+              "project_home_conflict",
+              ".kxm/project.yaml",
+              `project ${registration.projectId} home runtime is immutable and cannot be rebound`
+            );
+          }
+          this.database.prepare("DELETE FROM projects WHERE project_id = ?").run(registration.projectId);
+          this.insertHome(registration, projectRoot, projectKey);
+          this.database.exec("COMMIT");
+          registration.logger?.({
+            event: "project_registration_replaced",
+            projectId: registration.projectId,
+            projectRoot,
+            replacedRoot: replaced.project_root,
+            replacedCount: dead.length,
+            replacedHomeRuntimeId: replaced.home_runtime_id,
+            replacedProjectKey: replaced.project_key
+          });
+          return this.insertedRegistration(registration, projectRoot, projectKey);
+        } else {
+          this.insertHome(registration, projectRoot, projectKey);
+          this.database.exec("COMMIT");
+          return this.insertedRegistration(registration, projectRoot, projectKey);
+        }
+      } catch (error) {
+        try {
+          this.database.exec("ROLLBACK");
+        } catch {
+        }
+        throw error;
+      }
+      for (const root of rootsToMeasure ?? []) {
+        commonByRoot.set(root, gitCommonDirectory(root));
+      }
+    }
+    throw runtimeError(
+      "runtime_registry_busy",
+      projectRoot,
+      `project ${registration.projectId} registration could not be rechecked`
+    );
+  }
+  /** Remove one control root. Returns false when that root was not registered. */
+  unregisterProject(projectRoot) {
     this.database.exec("BEGIN IMMEDIATE");
     try {
-      const byId = this.database.prepare("SELECT project_id, project_root, project_key, home_runtime_id, config_revision, registered_at FROM projects WHERE project_id = ?").get(registration.projectId);
-      const byKey = this.database.prepare("SELECT project_id, project_root, project_key, home_runtime_id, config_revision, registered_at FROM projects WHERE project_key = ?").get(projectKey);
-      const existing = byId ?? byKey;
-      if (existing) {
-        const problems = [];
-        if (byId && byId.project_key !== projectKey) problems.push(`project ${registration.projectId} is already bound to a different control root`);
-        if (byKey && byKey.project_id !== registration.projectId) problems.push(`control root is already bound to a different project id ${byKey.project_id}`);
-        if (existing.home_runtime_id !== registration.homeRuntimeId) problems.push(`project ${registration.projectId} home runtime is immutable and cannot be rebound`);
-        if (problems.length > 0) {
-          this.database.exec("ROLLBACK");
-          throw runtimeError("project_home_conflict", ".kxm/project.yaml", problems.join("; "));
-        }
-        const result = {
-          projectId: existing.project_id,
-          projectRoot: existing.project_root,
-          projectKey: existing.project_key,
-          homeRuntimeId: existing.home_runtime_id,
-          ...existing.config_revision !== null ? { configRevision: existing.config_revision } : {},
-          registeredAt: existing.registered_at
-        };
-        this.database.exec("COMMIT");
-        return result;
+      const removed = this.deleteRegisteredRoot(projectRoot);
+      this.database.exec("COMMIT");
+      return removed;
+    } catch (error) {
+      try {
+        this.database.exec("ROLLBACK");
+      } catch {
+      }
+      throw error;
+    }
+  }
+  /**
+   * Delete the row only when `supervisorIsLive` is false for the supervisor
+   * row read inside this write transaction. A live supervisor keeps the row;
+   * the caller uses the supervisor route instead of editing the file.
+   */
+  unregisterProjectIfIdle(projectRoot, supervisorIsLive) {
+    this.database.exec("BEGIN IMMEDIATE");
+    try {
+      if (supervisorIsLive(this.readSupervisorRow())) {
+        this.database.exec("ROLLBACK");
+        return "supervisor_live";
       }
-      this.database.prepare(`
-        INSERT INTO projects (project_id, project_root, project_key, home_runtime_id, config_revision, registered_at)
-        VALUES (?, ?, ?, ?, ?, ?)
-      `).run(registration.projectId, projectRoot, projectKey, registration.homeRuntimeId, registration.configRevision ?? null, registration.now);
+      const removed = this.deleteRegisteredRoot(projectRoot);
       this.database.exec("COMMIT");
-      return {
-        projectId: registration.projectId,
-        projectRoot,
-        projectKey,
-        homeRuntimeId: registration.homeRuntimeId,
-        ...registration.configRevision !== void 0 ? { configRevision: registration.configRevision } : {},
-        registeredAt: registration.now
-      };
+      return removed ? "removed" : "absent";
     } catch (error) {
       try {
         this.database.exec("ROLLBACK");
@@ -19096,28 +19335,65 @@ var KxmRuntimeRegistry = class {
       throw error;
     }
   }
+  /** How many other rows share this home root's project. Zero when this root is a lane or missing. */
+  homeLaneCount(projectRoot) {
+    const row = this.projectRow(`SELECT ${PROJECT_COLUMNS} FROM projects WHERE project_key = ?`, projectRuntimeKey(resolve6(projectRoot)));
+    if (!row || row.lane_of !== null) return 0;
+    const count = this.database.prepare(
+      "SELECT COUNT(*) AS total FROM projects WHERE project_id = ? AND project_key != ?"
+    ).get(row.project_id, row.project_key);
+    return Number(count?.total ?? 0);
+  }
+  /** Caller holds the write transaction. Does not commit. */
+  deleteRegisteredRoot(projectRoot) {
+    const projectKey = projectRuntimeKey(resolve6(projectRoot));
+    const row = this.projectRow(`SELECT ${PROJECT_COLUMNS} FROM projects WHERE project_key = ?`, projectKey);
+    if (!row) return false;
+    this.database.prepare("DELETE FROM projects WHERE project_key = ?").run(projectKey);
+    if (row.lane_of === null) {
+      const successor = this.database.prepare(
+        "SELECT project_key FROM projects WHERE project_id = ? ORDER BY registered_at LIMIT 1"
+      ).get(row.project_id);
+      if (successor) {
+        this.database.prepare("UPDATE projects SET lane_of = NULL WHERE project_key = ?").run(successor.project_key);
+        this.database.prepare(
+          "UPDATE projects SET lane_of = ? WHERE project_id = ? AND project_key != ? AND (lane_of IS NULL OR lane_of = ?)"
+        ).run(successor.project_key, row.project_id, successor.project_key, projectKey);
+      }
+    }
+    return true;
+  }
+  /** The home row for a project id, or the earliest row when every row is a lane. */
   project(projectId) {
-    const row = this.database.prepare("SELECT project_id, project_root, project_key, home_runtime_id, config_revision, registered_at FROM projects WHERE project_id = ?").get(projectId);
-    return row ? {
-      projectId: row.project_id,
-      projectRoot: row.project_root,
-      projectKey: row.project_key,
-      homeRuntimeId: row.home_runtime_id,
-      ...row.config_revision !== null ? { configRevision: row.config_revision } : {},
-      registeredAt: row.registered_at
-    } : void 0;
+    const row = this.projectRow(
+      `SELECT ${PROJECT_COLUMNS} FROM projects WHERE project_id = ? ORDER BY CASE WHEN lane_of IS NULL THEN 0 ELSE 1 END, registered_at LIMIT 1`,
+      projectId
+    );
+    return row ? registrationFromRow(row) : void 0;
   }
   projectByRoot(projectRoot) {
-    const key = projectRuntimeKey(projectRoot);
-    const row = this.database.prepare("SELECT project_id, project_root, project_key, home_runtime_id, config_revision, registered_at FROM projects WHERE project_key = ?").get(key);
-    return row ? {
-      projectId: row.project_id,
-      projectRoot: row.project_root,
-      projectKey: row.project_key,
-      homeRuntimeId: row.home_runtime_id,
-      ...row.config_revision !== null ? { configRevision: row.config_revision } : {},
-      registeredAt: row.registered_at
-    } : void 0;
+    const row = this.projectRow(`SELECT ${PROJECT_COLUMNS} FROM projects WHERE project_key = ?`, projectRuntimeKey(projectRoot));
+    return row ? registrationFromRow(row) : void 0;
+  }
+  projectRow(sql, parameter) {
+    return this.database.prepare(sql).get(parameter);
+  }
+  insertHome(registration, projectRoot, projectKey) {
+    this.database.prepare(`
+      INSERT INTO projects (project_key, project_id, project_root, home_runtime_id, config_revision, registered_at, lane_of)
+      VALUES (?, ?, ?, ?, ?, ?, NULL)
+    `).run(projectKey, registration.projectId, projectRoot, registration.homeRuntimeId, registration.configRevision ?? null, registration.now);
+  }
+  insertedRegistration(registration, projectRoot, projectKey, laneOf) {
+    return {
+      projectId: registration.projectId,
+      projectRoot,
+      projectKey,
+      homeRuntimeId: registration.homeRuntimeId,
+      ...registration.configRevision !== void 0 ? { configRevision: registration.configRevision } : {},
+      ...laneOf !== void 0 ? { laneOf } : {},
+      registeredAt: registration.now
+    };
   }
 };
 var KXM_RUN_EVENT_SCHEMA = "kxm.run-event.v1";
@@ -23559,7 +23835,8 @@ function openKxmRuntimeContext(projectRoot, options) {
       projectRoot: bundle.projectRoot,
       homeRuntimeId: options.homeRuntimeId,
       configRevision: bundle.configRevision,
-      now: options.now ?? (/* @__PURE__ */ new Date()).toISOString()
+      now: options.now ?? (/* @__PURE__ */ new Date()).toISOString(),
+      ...options.logger ? { logger: options.logger } : {}
     });
     const eventStore = new KxmRunEventStore(join7(paths.projectsDir, registration.projectKey, "run-events.db"));
     registerKxmRuntimeHandle(eventStore.path);
@@ -24022,7 +24299,7 @@ async function beginOneShotEvidence(root, intent, sensitive) {
 // plugins/kxm/src/prices.ts
 var import_yaml3 = __toESM(require_dist(), 1);
 import { createHash as createHash10 } from "node:crypto";
-import { existsSync as existsSync8, readFileSync as readFileSync6, statSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync6, statSync as statSync2, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join9 } from "node:path";
 
 // plugins/kxm/src/price-calc.ts
@@ -24175,7 +24452,7 @@ function parsePriceCatalog(text) {
   return catalog;
 }
 function loadPriceCatalog(rootOrPath) {
-  const candidatePath = existsSync8(join9(rootOrPath, ".kxm", "prices.yaml")) ? join9(rootOrPath, ".kxm", "prices.yaml") : existsSync8(join9(rootOrPath, "prices.yaml")) ? join9(rootOrPath, "prices.yaml") : existsSync8(rootOrPath) && statSync(rootOrPath).isFile() ? rootOrPath : void 0;
+  const candidatePath = existsSync8(join9(rootOrPath, ".kxm", "prices.yaml")) ? join9(rootOrPath, ".kxm", "prices.yaml") : existsSync8(join9(rootOrPath, "prices.yaml")) ? join9(rootOrPath, "prices.yaml") : existsSync8(rootOrPath) && statSync2(rootOrPath).isFile() ? rootOrPath : void 0;
   if (!candidatePath || !existsSync8(candidatePath)) {
     return void 0;
   }
@@ -24228,9 +24505,9 @@ function isRouteAdmitted(root, modelId) {
 }
 
 // plugins/kxm/src/worktree-witness.ts
-import { spawnSync as spawnSync3 } from "node:child_process";
+import { spawnSync as spawnSync4 } from "node:child_process";
 function gitText(cwd, args) {
-  const result = spawnSync3("git", ["-C", cwd, ...args], {
+  const result = spawnSync4("git", ["-C", cwd, ...args], {
     encoding: "utf8",
     windowsHide: true,
     timeout: 15e3
@@ -24543,7 +24820,7 @@ function pruneContextPacket(packet, tokenBudget) {
 }
 
 // plugins/kxm/src/dispatch-context.ts
-import { spawnSync as spawnSync4 } from "node:child_process";
+import { spawnSync as spawnSync5 } from "node:child_process";
 import { readdirSync as readdirSync8 } from "node:fs";
 import { extname as extname3, join as join13 } from "node:path";
 
@@ -25303,7 +25580,7 @@ function loadAuthoredMemory(repoRoot) {
 // plugins/kxm/src/skills.ts
 var import_yaml8 = __toESM(require_dist(), 1);
 import { createHash as createHash11 } from "node:crypto";
-import { existsSync as existsSync11, mkdirSync as mkdirSync5, readdirSync as readdirSync7, readFileSync as readFileSync9, renameSync, rmSync, statSync as statSync2, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync5, readdirSync as readdirSync7, readFileSync as readFileSync9, renameSync, rmSync, statSync as statSync3, writeFileSync as writeFileSync6 } from "node:fs";
 import { dirname as dirname7, join as join12 } from "node:path";
 var SKILL_CANDIDATE_SCHEMA = "kxm.skill-candidate.v1";
 var SKILL_EVALUATION_SCHEMA = "kxm.skill-evaluation.v1";
@@ -25683,7 +25960,7 @@ function boundedList(value, field) {
   return [...new Set(refs)];
 }
 function readdirSorted(dir) {
-  return readdirSync7(dir).filter((entry) => statSync2(join12(dir, entry)).isDirectory()).sort();
+  return readdirSync7(dir).filter((entry) => statSync3(join12(dir, entry)).isDirectory()).sort();
 }
 
 // plugins/kxm/src/dispatch-context.ts
@@ -25744,7 +26021,7 @@ function gitEnvironment2() {
   return Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.toUpperCase().startsWith("GIT_")));
 }
 function committedGateGap(projectRoot) {
-  const result = spawnSync4("git", [
+  const result = spawnSync5("git", [
     "--no-optional-locks",
     "-C",
     projectRoot,
@@ -25886,11 +26163,11 @@ function assembleDispatchContext(sources, input) {
 import { join as join14 } from "node:path";
 
 // plugins/kxm/src/artifacts-exist.ts
-import { lstatSync as lstatSync5, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
-import { isAbsolute as isAbsolute4, relative as relative4, resolve as resolve8 } from "node:path";
+import { lstatSync as lstatSync5, realpathSync as realpathSync4, statSync as statSync4 } from "node:fs";
+import { isAbsolute as isAbsolute5, relative as relative4, resolve as resolve8 } from "node:path";
 function staysUnder(root, candidate) {
   const child = relative4(root, candidate);
-  return child === "" || !isAbsolute4(child) && child !== ".." && !child.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`);
+  return child === "" || !isAbsolute5(child) && child !== ".." && !child.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`);
 }
 function verifyArtifactExists(rootInput, pathInput) {
   const lexicalRoot = resolve8(rootInput);
@@ -25901,12 +26178,12 @@ function verifyArtifactExists(rootInput, pathInput) {
   let realRoot;
   let realPath;
   try {
-    realRoot = realpathSync3(lexicalRoot);
+    realRoot = realpathSync4(lexicalRoot);
   } catch {
     return { ok: false, error: "artifact_unreadable", path: lexicalPath };
   }
   try {
-    realPath = realpathSync3(lexicalPath);
+    realPath = realpathSync4(lexicalPath);
   } catch {
     return { ok: false, error: "artifact_missing", path: lexicalPath };
   }
@@ -25918,7 +26195,7 @@ function verifyArtifactExists(rootInput, pathInput) {
     if (link.isSymbolicLink()) {
       return { ok: false, error: "artifact_outside_workspace_assets", path: lexicalPath };
     }
-    const artifact = statSync3(realPath);
+    const artifact = statSync4(realPath);
     if (!artifact.isFile()) return { ok: false, error: "artifact_not_file", path: lexicalPath };
     if (artifact.size < 1) return { ok: false, error: "artifact_empty", path: lexicalPath };
     return { ok: true, path: realPath, bytes: artifact.size };
@@ -30041,7 +30318,7 @@ var RuntimeHubClient = class {
 // plugins/kxm/src/hub-binding.ts
 import { existsSync as existsSync13, mkdirSync as mkdirSync6, readFileSync as readFileSync11, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname8, isAbsolute as isAbsolute5, join as join16, resolve as resolve9 } from "node:path";
+import { dirname as dirname8, isAbsolute as isAbsolute6, join as join16, resolve as resolve9 } from "node:path";
 var HUB_BINDING_SCHEMA = "kxm.hub-binding.v1";
 var HubBindingError = class extends Error {
   constructor(message) {
@@ -30052,17 +30329,17 @@ var HubBindingError = class extends Error {
 function resolveUserStateRoot(env) {
   const explicit = env.KXM_STATE_HOME?.trim();
   if (explicit) {
-    if (!isAbsolute5(explicit)) throw new HubBindingError("local_state_root_not_absolute");
+    if (!isAbsolute6(explicit)) throw new HubBindingError("local_state_root_not_absolute");
     return resolve9(explicit);
   }
   if (process.platform === "win32") {
     const localAppData = env.LOCALAPPDATA?.trim();
-    const base2 = localAppData && isAbsolute5(localAppData) ? localAppData : join16(homedir2(), "AppData", "Local");
+    const base2 = localAppData && isAbsolute6(localAppData) ? localAppData : join16(homedir2(), "AppData", "Local");
     return resolve9(base2, "KXM");
   }
   if (process.platform === "darwin") return resolve9(homedir2(), "Library", "Application Support", "KXM");
   const xdgState = env.XDG_STATE_HOME?.trim();
-  const base = xdgState && isAbsolute5(xdgState) ? xdgState : join16(homedir2(), ".local", "state");
+  const base = xdgState && isAbsolute6(xdgState) ? xdgState : join16(homedir2(), ".local", "state");
   return resolve9(base, "kxm");
 }
 function hubBindingFile(env = process.env) {
@@ -30113,7 +30390,7 @@ function readHubBinding(env = process.env) {
 // plugins/kxm/src/hub-env.ts
 import { existsSync as existsSync14, mkdirSync as mkdirSync7, readFileSync as readFileSync12, renameSync as renameSync3, rmSync as rmSync3, writeFileSync as writeFileSync8 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { dirname as dirname9, isAbsolute as isAbsolute6, join as join17, resolve as resolve10 } from "node:path";
+import { dirname as dirname9, isAbsolute as isAbsolute7, join as join17, resolve as resolve10 } from "node:path";
 var HUB_ENV_SCHEMA = "kxm.hub-env.v1";
 var HubEnvError = class extends Error {
   constructor(message) {
@@ -30124,17 +30401,17 @@ var HubEnvError = class extends Error {
 function resolveUserStateRoot2(env) {
   const explicit = env.KXM_STATE_HOME?.trim();
   if (explicit) {
-    if (!isAbsolute6(explicit)) throw new HubEnvError("local_state_root_not_absolute");
+    if (!isAbsolute7(explicit)) throw new HubEnvError("local_state_root_not_absolute");
     return resolve10(explicit);
   }
   if (process.platform === "win32") {
     const localAppData = env.LOCALAPPDATA?.trim();
-    const base2 = localAppData && isAbsolute6(localAppData) ? localAppData : join17(homedir3(), "AppData", "Local");
+    const base2 = localAppData && isAbsolute7(localAppData) ? localAppData : join17(homedir3(), "AppData", "Local");
     return resolve10(base2, "KXM");
   }
   if (process.platform === "darwin") return resolve10(homedir3(), "Library", "Application Support", "KXM");
   const xdgState = env.XDG_STATE_HOME?.trim();
-  const base = xdgState && isAbsolute6(xdgState) ? xdgState : join17(homedir3(), ".local", "state");
+  const base = xdgState && isAbsolute7(xdgState) ? xdgState : join17(homedir3(), ".local", "state");
   return resolve10(base, "kxm");
 }
 function hubEnvFile(env = process.env) {
@@ -30185,7 +30462,7 @@ function resolveClientHubAuthToken(env, project) {
 }
 
 // plugins/kxm/src/logger.ts
-import { appendFileSync, existsSync as existsSync15, mkdirSync as mkdirSync8, renameSync as renameSync4, statSync as statSync4, unlinkSync as unlinkSync2 } from "node:fs";
+import { appendFileSync, existsSync as existsSync15, mkdirSync as mkdirSync8, renameSync as renameSync4, statSync as statSync5, unlinkSync as unlinkSync2 } from "node:fs";
 import { dirname as dirname10 } from "node:path";
 var LOG_LEVEL_PRIORITY = {
   debug: 10,
@@ -30256,7 +30533,7 @@ function createLogger(options) {
   let currentSize = 0;
   if (filePath && existsSync15(filePath)) {
     try {
-      currentSize = statSync4(filePath).size;
+      currentSize = statSync5(filePath).size;
     } catch {
       currentSize = 0;
     }
@@ -30403,6 +30680,24 @@ function readRecentSupervisorError(paths) {
     return void 0;
   }
 }
+var SETTLED_RUN_STATUS = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+function kxmSupervisorRecordIsLive(record2) {
+  return supervisorStatusOf(record2).running;
+}
+function unsettledRunIds(context) {
+  const ids = [];
+  for (const stored of context.eventStore.runsForProject(context.projectId, 1e4)) {
+    let status = stored.status;
+    try {
+      status = projectKxmRunReadOnly(context, stored.runId).status;
+    } catch {
+      ids.push(stored.runId);
+      continue;
+    }
+    if (!SETTLED_RUN_STATUS.has(status)) ids.push(stored.runId);
+  }
+  return ids;
+}
 function supervisorStatusOf(record2) {
   if (!record2) return { running: false };
   const heartbeatAgeMs = Date.now() - Date.parse(record2.heartbeatAt);
@@ -30751,7 +31046,7 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
     }
   };
   const contextFor = (projectRoot) => {
-    if (!isAbsolute7(projectRoot)) {
+    if (!isAbsolute8(projectRoot)) {
       throw runtimeError("runtime_request_invalid", "projectRoot", "projectRoot must be an absolute path");
     }
     const key = projectRuntimeKey(projectRoot);
@@ -30817,6 +31112,62 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
           sendJson(response, 200, { ok: true, projectId: context.projectId, retried, outbox: context.eventStore.outboxStatus() });
           return;
         }
+        if (request.method === "POST" && url.pathname === "/v1/projects/unregister") {
+          const body = await readJsonBody(request);
+          const projectRoot = typeof body.projectRoot === "string" ? body.projectRoot : "";
+          const force = body.force === true;
+          if (!projectRoot || !isAbsolute8(projectRoot)) {
+            sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: "projectRoot must be an absolute path" });
+            return;
+          }
+          if (!force) {
+            const key2 = projectRuntimeKey(projectRoot);
+            const existing2 = contexts.get(key2);
+            let openRunIds = [];
+            if (existing2) {
+              openRunIds = unsettledRunIds(existing2);
+            } else {
+              const registration = registry.projectByRoot(projectRoot);
+              const eventsPath = join18(paths.projectsDir, registration?.projectKey ?? projectRuntimeKey(projectRoot), "run-events.db");
+              if (registration && existsSync16(eventsPath)) {
+                const store = new KxmRunEventStore(eventsPath);
+                try {
+                  openRunIds = store.runsForProject(registration.projectId, 1e4).filter((run) => !SETTLED_RUN_STATUS.has(run.status)).map((run) => run.runId);
+                } finally {
+                  store.close();
+                }
+              }
+            }
+            if (openRunIds.length > 0) {
+              sendJson(response, 409, {
+                ok: false,
+                error: "runtime_project_busy",
+                message: `unsettled run ${openRunIds.join(", ")}`,
+                runIds: openRunIds
+              });
+              return;
+            }
+            const laneCount = registry.homeLaneCount(projectRoot);
+            if (laneCount > 0) {
+              sendJson(response, 409, {
+                ok: false,
+                error: "runtime_project_has_lanes",
+                message: `home root still has ${laneCount} lane(s)`
+              });
+              return;
+            }
+          }
+          const key = projectRuntimeKey(projectRoot);
+          const existing = contexts.get(key);
+          const unregistered = registry.unregisterProject(projectRoot);
+          if (existing) {
+            contexts.delete(key);
+            syncStatuses.delete(key);
+            closeKxmRuntimeContext(existing);
+          }
+          sendJson(response, 200, { ok: true, unregistered });
+          return;
+        }
         if (request.method === "POST" && url.pathname === "/v1/runs") {
           const body = await readJsonBody(request);
           const projectRoot = typeof body.projectRoot === "string" ? body.projectRoot : "";
@@ -31040,7 +31391,10 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
             sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: `project ${requestedProjectId} is not the bound project ${context.projectId}` });
             return;
           }
-          const runs = context.eventStore.runsForProject(requestedProjectId, 50).map((stored) => {
+          const limitText = url.searchParams.get("limit");
+          const parsedLimit = limitText === null ? 50 : Number(limitText);
+          const limit = Number.isInteger(parsedLimit) && parsedLimit > 0 ? Math.min(parsedLimit, 1e4) : 50;
+          const runs = context.eventStore.runsForProject(requestedProjectId, limit).map((stored) => {
             try {
               return projectKxmRunReadOnly(context, stored.runId);
             } catch (error) {
@@ -31314,6 +31668,7 @@ export {
   hashKxmSupervisorToken,
   hashKxmTokenProof,
   kxmRuntimeRequest,
+  kxmSupervisorRecordIsLive,
   kxmSupervisorStatus,
   kxmSupervisorTokenFile,
   readKxmSupervisorToken,