@kontextmind/kxm 0.7.128 → 0.7.130

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

@@ -1,6 +1,7 @@
+import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, 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 { kxmProjectRunEventsPath, projectRuntimeKey } from "./runtime-paths.ts";
@@ -48,7 +49,9 @@ function checkedParent(path: string, description: string): void {
 }
 
 import {
+  assertDatabaseFile,
   openDatabase,
+  tableColumns,
   withDatabaseTransaction,
   type DatabaseSchemaSpec,
 } from "./database.ts";
@@ -74,14 +77,16 @@ export interface KxmProjectRegistration {
   projectKey: string;
   homeRuntimeId: string;
   configRevision?: string;
+  /** Set on a lane row: the home row's project key. Absent on the home row. */
+  laneOf?: string;
   registeredAt: string;
 }
 
-export const KXM_REGISTRY_SCHEMA_VERSION = 1;
+export const KXM_REGISTRY_SCHEMA_VERSION = 2;
 
 const 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"],
 } as const;
 
 const REGISTRY_SCHEMA = `
@@ -96,15 +101,142 @@ 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);
 `;
 
+const PROJECT_COLUMNS = "project_id, project_root, project_key, home_runtime_id, config_revision, registered_at, lane_of";
+
+interface ProjectRow {
+  project_id: string;
+  project_root: string;
+  project_key: string;
+  home_runtime_id: string;
+  config_revision: string | null;
+  registered_at: string;
+  lane_of: string | null;
+}
+
+function registrationFromRow(row: ProjectRow): KxmProjectRegistration {
+  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: string): boolean {
+  const stat = statSync(projectRoot, { throwIfNoEntry: false });
+  return Boolean(stat?.isDirectory());
+}
+
+function gitEnv(): NodeJS.ProcessEnv {
+  return Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.toUpperCase().startsWith("GIT_")));
+}
+
+/** Absolute git common directory, or undefined when `projectRoot` is not a repository. */
+function gitCommonDirectory(projectRoot: string): string | undefined {
+  const result = spawnSync("git", ["-C", projectRoot, "rev-parse", "--git-common-dir"], {
+    encoding: "utf8",
+    env: gitEnv(),
+    timeout: 30_000,
+    windowsHide: true,
+  });
+  if (result.status !== 0) return undefined;
+  const text = (result.stdout ?? "").trim();
+  if (!text) return undefined;
+  const absolute = isAbsolute(text) ? text : resolve(projectRoot, text);
+  let canonical: string;
+  try {
+    canonical = realpathSync.native(absolute);
+  } catch {
+    canonical = resolve(absolute);
+  }
+  return process.platform === "win32" ? canonical.toLocaleLowerCase("en-US") : canonical;
+}
+
+/** A primary checkout is the worktree whose git common dir is `<root>/.git`. */
+function isPrimaryWorktree(projectRoot: string, commonDir: string | undefined): boolean {
+  if (commonDir === undefined) return false;
+  const dotGit = resolve(projectRoot, ".git");
+  let canonical: string;
+  try {
+    canonical = realpathSync.native(dotGit);
+  } catch {
+    canonical = resolve(dotGit);
+  }
+  if (process.platform === "win32") canonical = canonical.toLocaleLowerCase("en-US");
+  return canonical === commonDir;
+}
+
+/**
+ * Registry schema 1 keyed `projects` on project id, so a second control root
+ * could not be stored. Schema 2 keys on the control root and adds `lane_of`.
+ * Existing rows are copied unchanged, with `lane_of` left null. A database
+ * that is already shape 2 and was only restamped as version 1 is not rebuilt.
+ * The file is opened only after the same symlink and sidecar checks as
+ * `openDatabase`.
+ */
+function migrateRegistryLanes(file: string): void {
+  const stat = lstatSync(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() as { user_version: number } | undefined;
+    if ((current?.user_version ?? 0) !== 1) return;
+    database.exec("BEGIN IMMEDIATE");
+    transaction = true;
+    const locked = database.prepare("PRAGMA user_version").get() as { user_version: number } | undefined;
+    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 { /* already rolled back */ }
+    }
+    throw error;
+  } finally {
+    database.close();
+  }
+}
+
 /** 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
@@ -129,6 +261,7 @@ export class KxmRuntimeRegistry {
 
   constructor(path: string) {
     this.path = resolve(path);
+    migrateRegistryLanes(this.path);
     this.database = openDatabase(this.path, "runtime registry", {
       schema: REGISTRY_SCHEMA,
       version: KXM_REGISTRY_SCHEMA_VERSION,
@@ -217,10 +350,9 @@ export class KxmRuntimeRegistry {
     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: string): Array<{ projectRoot: string; projectId: string }> {
     const rows = this.database.prepare(
       "SELECT project_root, project_id FROM projects WHERE home_runtime_id = ? ORDER BY registered_at",
@@ -228,88 +360,269 @@ export class KxmRuntimeRegistry {
     return rows.map((row) => ({ projectRoot: row.project_root, projectId: row.project_id }));
   }
 
-  registerProject(registration: { projectId: string; projectRoot: string; homeRuntimeId: string; configRevision?: string; now: string }): KxmProjectRegistration {
+  /**
+   * 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: {
+    projectId: string;
+    projectRoot: string;
+    homeRuntimeId: string;
+    configRevision?: string;
+    now: string;
+    logger?: (entry: Record<string, unknown>) => void;
+  }): KxmProjectRegistration {
     const projectRoot = resolve(registration.projectRoot);
     const projectKey = projectRuntimeKey(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) as
-        | { project_id: string; project_root: string; project_key: string; home_runtime_id: string; config_revision: string | null; registered_at: string }
-        | undefined;
-      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) as
-        | { project_id: string; project_root: string; project_key: string; home_runtime_id: string; config_revision: string | null; registered_at: string }
-        | undefined;
-      const existing = byId ?? byKey;
-      if (existing) {
-        const problems: string[] = [];
-        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) {
+    // Git runs only outside the write lock. The candidate is measured first;
+    // live rows are measured after a rollback, then the rows are read again.
+    const candidateCommon = gitCommonDirectory(projectRoot);
+    const commonByRoot = new Map<string, string | undefined>();
+
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      this.database.exec("BEGIN IMMEDIATE");
+      let rootsToMeasure: string[] | undefined;
+      try {
+        const byKey = this.projectRow("SELECT " + PROJECT_COLUMNS + " FROM projects WHERE project_key = ?", projectKey);
+        if (byKey) {
+          const problems: string[] = [];
+          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) as unknown as ProjectRow[];
+        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");
-          throw runtimeError("project_home_conflict", ".kxm/project.yaml", problems.join("; "));
+        } else if (live.length > 0) {
+          const anchor = live.find((row) => {
+            const dir = commonByRoot.get(row.project_root);
+            return candidateCommon !== undefined && 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 !== undefined && 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] as ProjectRow;
+          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);
         }
-        const result: KxmProjectRegistration = {
-          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;
+      } catch (error) {
+        try { this.database.exec("ROLLBACK"); } catch { /* already rolled back */ }
+        throw error;
       }
-      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);
+      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: string): boolean {
+    this.database.exec("BEGIN IMMEDIATE");
+    try {
+      const removed = this.deleteRegisteredRoot(projectRoot);
       this.database.exec("COMMIT");
-      return {
-        projectId: registration.projectId,
-        projectRoot,
-        projectKey,
-        homeRuntimeId: registration.homeRuntimeId,
-        ...(registration.configRevision !== undefined ? { configRevision: registration.configRevision } : {}),
-        registeredAt: registration.now,
-      };
+      return removed;
     } catch (error) {
       try { this.database.exec("ROLLBACK"); } catch { /* already rolled back */ }
       throw error;
     }
   }
 
-  project(projectId: string): KxmProjectRegistration | undefined {
-    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) as
-      | { project_id: string; project_root: string; project_key: string; home_runtime_id: string; config_revision: string | null; registered_at: string }
-      | undefined;
-    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,
+  /**
+   * 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: string,
+    supervisorIsLive: (record: KxmSupervisorRecord | undefined) => boolean,
+  ): "removed" | "absent" | "supervisor_live" {
+    this.database.exec("BEGIN IMMEDIATE");
+    try {
+      if (supervisorIsLive(this.readSupervisorRow())) {
+        this.database.exec("ROLLBACK");
+        return "supervisor_live";
       }
-      : undefined;
+      const removed = this.deleteRegisteredRoot(projectRoot);
+      this.database.exec("COMMIT");
+      return removed ? "removed" : "absent";
+    } catch (error) {
+      try { this.database.exec("ROLLBACK"); } catch { /* already rolled back */ }
+      throw error;
+    }
   }
 
-  projectByRoot(projectRoot: string): KxmProjectRegistration | undefined {
-    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) as
-      | { project_id: string; project_root: string; project_key: string; home_runtime_id: string; config_revision: string | null; registered_at: string }
-      | undefined;
-    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,
+  /** How many other rows share this home root's project. Zero when this root is a lane or missing. */
+  homeLaneCount(projectRoot: string): number {
+    const row = this.projectRow(`SELECT ${PROJECT_COLUMNS} FROM projects WHERE project_key = ?`, projectRuntimeKey(resolve(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) as { total: number } | undefined;
+    return Number(count?.total ?? 0);
+  }
+
+  /** Caller holds the write transaction. Does not commit. */
+  private deleteRegisteredRoot(projectRoot: string): boolean {
+    const projectKey = projectRuntimeKey(resolve(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) as { project_key: string } | undefined;
+      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);
       }
-      : undefined;
+    }
+    return true;
+  }
+
+  /** The home row for a project id, or the earliest row when every row is a lane. */
+  project(projectId: string): KxmProjectRegistration | undefined {
+    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) : undefined;
+  }
+
+  projectByRoot(projectRoot: string): KxmProjectRegistration | undefined {
+    const row = this.projectRow(`SELECT ${PROJECT_COLUMNS} FROM projects WHERE project_key = ?`, projectRuntimeKey(projectRoot));
+    return row ? registrationFromRow(row) : undefined;
+  }
+
+  private projectRow(sql: string, parameter: string): ProjectRow | undefined {
+    return this.database.prepare(sql).get(parameter) as ProjectRow | undefined;
+  }
+
+  private insertHome(
+    registration: { projectId: string; homeRuntimeId: string; configRevision?: string; now: string },
+    projectRoot: string,
+    projectKey: string,
+  ): void {
+    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);
+  }
+
+  private insertedRegistration(
+    registration: { projectId: string; homeRuntimeId: string; configRevision?: string; now: string },
+    projectRoot: string,
+    projectKey: string,
+    laneOf?: string,
+  ): KxmProjectRegistration {
+    return {
+      projectId: registration.projectId,
+      projectRoot,
+      projectKey,
+      homeRuntimeId: registration.homeRuntimeId,
+      ...(registration.configRevision !== undefined ? { configRevision: registration.configRevision } : {}),
+      ...(laneOf !== undefined ? { laneOf } : {}),
+      registeredAt: registration.now,
+    };
   }
 }
 

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

@@ -6,13 +6,13 @@ import { dirname, isAbsolute, join } from "node:path";
 import { findKxmRepoRoot } from "./repo-root.ts";
 import { loadKxmProject, KxmConfigError, type KxmConfigOptions } from "./project-config.ts";
 import {
+  KxmRunEventStore,
   KxmRuntimeRegistry,
   projectRuntimeKey,
   readKxmSupervisorRecord,
   runtimeError,
   verifyKxmDriveReceipt,
   kxmRuntimePaths,
-  type KxmRunEventStore,
   type KxmRuntimePaths,
   type KxmSupervisorRecord,
 } from "./runtime-store.ts";
@@ -126,6 +126,28 @@ function readRecentSupervisorError(paths: KxmRuntimePaths): string | undefined {
   }
 }
 
+const SETTLED_RUN_STATUS = new Set(["completed", "failed", "cancelled"]);
+
+/** Same liveness rule as `kxmSupervisorStatus`: running, a fresh heartbeat, and a live pid. */
+export function kxmSupervisorRecordIsLive(record: KxmSupervisorRecord | undefined): boolean {
+  return supervisorStatusOf(record).running;
+}
+
+function unsettledRunIds(context: KxmRuntimeContext): string[] {
+  const ids: string[] = [];
+  for (const stored of context.eventStore.runsForProject(context.projectId, 10_000)) {
+    let status: string = 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(record: KxmSupervisorRecord | undefined): KxmSupervisorStatus {
   if (!record) return { running: false };
   // Pid-only liveness is not enough: after a crash the pid may be reused by
@@ -781,6 +803,65 @@ async function startKxmRuntimeSupervisorInner(
           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 || !isAbsolute(projectRoot)) {
+            sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: "projectRoot must be an absolute path" });
+            return;
+          }
+          if (!force) {
+            const key = projectRuntimeKey(projectRoot);
+            const existing = contexts.get(key);
+            let openRunIds: string[] = [];
+            if (existing) {
+              openRunIds = unsettledRunIds(existing);
+            } else {
+              const registration = registry.projectByRoot(projectRoot);
+              const eventsPath = join(paths.projectsDir, registration?.projectKey ?? projectRuntimeKey(projectRoot), "run-events.db");
+              if (registration && existsSync(eventsPath)) {
+                const store = new KxmRunEventStore(eventsPath);
+                try {
+                  openRunIds = store.runsForProject(registration.projectId, 10_000)
+                    .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 : "";
@@ -1026,9 +1107,12 @@ async function startKxmRuntimeSupervisorInner(
           // that returned raw rows would let every consumer — including the portal's
           // tenant read — present cached status as authoritative. Folding replays each
           // run's events; workflows are transition-bounded, so this stays cheap at the
-          // 50-run cap. A run that refuses to fold is returned with its cached row plus
+          // default 50-run cap (`limit` may ask for up to 10000). A run that refuses to fold is returned with its cached row plus
           // `projectionError`, so one corrupt run cannot make the listing lie by omission.
-          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, 10_000) : 50;
+          const runs = context.eventStore.runsForProject(requestedProjectId, limit).map((stored) => {
             try {
               return projectKxmRunReadOnly(context, stored.runId);
             } catch (error) {