@open-code-review/cli 2.0.0 → 2.1.0

package/README.md

@@ -4,6 +4,8 @@ Command-line interface for [Open Code Review](https://github.com/spencermarx/ope
 
 ## Quick Start
 
+**Requires Node.js >= 22.5** — OCR's storage engine is Node's built-in SQLite (`node:sqlite`), so there's no native module to compile and it installs cleanly under any package manager (npm, **pnpm 10+**, yarn).
+
 ```bash
 # 1. Install globally
 npm install -g @open-code-review/cli

package/dist/dashboard/server.js

@@ -30510,37 +30510,98 @@ function resolveOcrDir(startDir) {
 }
 
 // ../cli/src/lib/db/index.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, copyFileSync, statSync } from "node:fs";
+import {
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync2,
+  copyFileSync,
+  statSync,
+  mkdtempSync,
+  rmSync
+} from "node:fs";
 import { dirname as dirname4, join as join4 } from "node:path";
 
 // ../cli/src/lib/db/engine.ts
-import BetterSqlite3 from "better-sqlite3";
+import { createRequire } from "node:module";
+
+// ../cli/src/lib/runtime-checks.ts
+var NODE_FLOOR = { major: 22, minor: 5 };
+function isSupportedNode(version) {
+  const [major = 0, minor = 0] = version.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  return major > NODE_FLOOR.major || major === NODE_FLOOR.major && minor >= NODE_FLOOR.minor;
+}
+function nodeVersionGuardMessage(version) {
+  return `
+Open Code Review requires Node.js >= ${NODE_FLOOR.major}.${NODE_FLOOR.minor} (it uses Node's built-in SQLite, \`node:sqlite\`).
+You have Node ${version}. Upgrade Node (e.g. \`nvm install 22 && nvm use 22\`) and re-run.
+
+`;
+}
+function isSuppressibleSqliteWarning(warning) {
+  const message = typeof warning === "string" ? warning : warning?.message;
+  return typeof message === "string" && message.includes("SQLite is an experimental feature");
+}
+
+// ../cli/src/lib/db/engine.ts
+var SQLITE_BUSY = 5;
+var SQLITE_BUSY_SNAPSHOT = 261;
 var BUSY_RETRY_ATTEMPTS = 5;
 var BUSY_RETRY_BACKOFF_MS = 50;
-function isBusyError(e) {
-  if (e instanceof BetterSqlite3.SqliteError) {
-    return e.code === "SQLITE_BUSY" || e.code === "SQLITE_BUSY_SNAPSHOT";
+var savepointName = (depth) => `ocr_sp_${depth}`;
+var nodeRequire = createRequire(import.meta.url);
+var _preconditionsApplied = false;
+function applyEnginePreconditions() {
+  if (_preconditionsApplied) return;
+  _preconditionsApplied = true;
+  const originalEmitWarning = process.emitWarning.bind(process);
+  process.emitWarning = (warning, ...args) => {
+    if (isSuppressibleSqliteWarning(warning)) return;
+    originalEmitWarning(warning, ...args);
+  };
+}
+var _DatabaseSyncCtor;
+function newDatabase(path2) {
+  if (!_DatabaseSyncCtor) {
+    applyEnginePreconditions();
+    try {
+      _DatabaseSyncCtor = nodeRequire("node:sqlite").DatabaseSync;
+    } catch (e) {
+      if (!isSupportedNode(process.versions.node)) {
+        throw new Error(nodeVersionGuardMessage(process.versions.node).trim());
+      }
+      throw e;
+    }
   }
-  const code = e?.code;
-  return code === "SQLITE_BUSY" || code === "SQLITE_BUSY_SNAPSHOT";
+  return new _DatabaseSyncCtor(path2);
 }
+function isBusyError(e) {
+  const errcode = e?.errcode;
+  return errcode === SQLITE_BUSY || errcode === SQLITE_BUSY_SNAPSHOT;
+}
+var SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
 function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  Atomics.wait(SLEEP_BUF, 0, 0, ms);
 }
-var BetterSqliteAdapter = class {
+var NodeSqliteAdapter = class {
   raw;
+  /**
+   * Transaction nesting depth. `node:sqlite` has no transaction helper, so we
+   * drive `BEGIN IMMEDIATE` ourselves and use SAVEPOINTs for nested calls
+   * (better-sqlite3 did this automatically). 0 = no transaction open.
+   */
+  txnDepth = 0;
   constructor(db) {
     this.raw = db;
   }
   exec(sql, params) {
     const stmt = this.raw.prepare(sql);
-    if (!stmt.reader) {
+    const cols = stmt.columns();
+    if (cols.length === 0) {
       stmt.run(...params ?? []);
       return [];
     }
-    const columns = stmt.columns().map((c) => c.name);
-    const values = stmt.raw().all(...params ?? []);
-    return values.length > 0 ? [{ columns, values }] : [];
+    stmt.setReturnArrays(true);
+    const values = stmt.all(...params ?? []);
+    return values.length > 0 ? [{ columns: cols.map((c) => c.name), values }] : [];
   }
   run(sql, params) {
     if (params !== void 0) {
@@ -30553,34 +30614,93 @@ var BetterSqliteAdapter = class {
     return this.raw.prepare(sql);
   }
   transaction(fn) {
-    const tx = this.raw.transaction(fn);
-    for (let attempt = 0; ; attempt++) {
+    return this.txnDepth > 0 ? this.runNested(fn) : this.runOuter(fn);
+  }
+  /**
+   * Nested call: a SAVEPOINT within the outer transaction's write lock. No
+   * busy-retry — the outer transaction already holds the lock. The savepoint
+   * lets the inner block roll back independently while the outer continues.
+   */
+  runNested(fn) {
+    const name = savepointName(this.txnDepth);
+    this.raw.exec(`SAVEPOINT ${name}`);
+    this.txnDepth++;
+    try {
+      const result = fn();
+      this.raw.exec(`RELEASE ${name}`);
+      return result;
+    } catch (e) {
+      try {
+        this.raw.exec(`ROLLBACK TO ${name}`);
+        this.raw.exec(`RELEASE ${name}`);
+      } catch {
+      }
+      throw e;
+    } finally {
+      this.txnDepth--;
+    }
+  }
+  /**
+   * Outer transaction: `BEGIN IMMEDIATE` acquires the write lock up front so
+   * cross-process writers serialize cleanly under WAL instead of failing late
+   * on upgrade. `busy_timeout` covers most contention; a bounded synchronous
+   * retry absorbs the residual SQLITE_BUSY (another connection holds the lock
+   * past the timeout, or BUSY_SNAPSHOT). Non-busy errors and the final attempt
+   * re-throw so genuine failures propagate.
+   */
+  runOuter(fn) {
+    for (let attempt = 0; attempt < BUSY_RETRY_ATTEMPTS; attempt++) {
       try {
-        return tx.immediate();
+        return this.runOnce(fn);
       } catch (e) {
-        if (!isBusyError(e) || attempt >= BUSY_RETRY_ATTEMPTS - 1) throw e;
+        if (!isBusyError(e) || attempt === BUSY_RETRY_ATTEMPTS - 1) throw e;
         sleepSync(BUSY_RETRY_BACKOFF_MS);
       }
     }
+    throw new Error("transaction retry budget exhausted");
+  }
+  /** One `BEGIN IMMEDIATE` / `COMMIT` / `ROLLBACK` lifecycle. */
+  runOnce(fn) {
+    this.raw.exec("BEGIN IMMEDIATE");
+    this.txnDepth = 1;
+    try {
+      const result = fn();
+      this.raw.exec("COMMIT");
+      return result;
+    } catch (e) {
+      try {
+        this.raw.exec("ROLLBACK");
+      } catch {
+      }
+      throw e;
+    } finally {
+      this.txnDepth = 0;
+    }
   }
   pragma(source) {
-    return this.raw.pragma(source);
+    this.raw.exec(`PRAGMA ${source}`);
+    return void 0;
   }
   close() {
     try {
-      this.raw.pragma("wal_checkpoint(TRUNCATE)");
+      this.raw.exec("PRAGMA wal_checkpoint(TRUNCATE)");
     } catch {
     }
-    this.raw.close();
+    try {
+      this.raw.close();
+    } catch (e) {
+      const message = e?.message ?? "";
+      if (!/database is not open/i.test(message)) throw e;
+    }
   }
 };
 function openEngine(dbPath) {
-  const native = new BetterSqlite3(dbPath);
-  native.pragma("journal_mode = WAL");
-  native.pragma("foreign_keys = ON");
-  native.pragma("busy_timeout = 5000");
-  native.pragma("synchronous = NORMAL");
-  return new BetterSqliteAdapter(native);
+  const native = newDatabase(dbPath);
+  native.exec("PRAGMA journal_mode = WAL");
+  native.exec("PRAGMA foreign_keys = ON");
+  native.exec("PRAGMA busy_timeout = 5000");
+  native.exec("PRAGMA synchronous = NORMAL");
+  return new NodeSqliteAdapter(native);
 }
 
 // ../cli/src/lib/db/migrations.ts
@@ -31760,7 +31880,7 @@ function walCheckpointTruncate(dbPath) {
     return "failed";
   } finally {
     try {
-      transient?.raw.close();
+      transient?.close();
     } catch {
     }
   }

package/dist/index.js

@@ -39,6 +39,30 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/lib/runtime-checks.ts
+function isSupportedNode(version) {
+  const [major = 0, minor = 0] = version.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  return major > NODE_FLOOR.major || major === NODE_FLOOR.major && minor >= NODE_FLOOR.minor;
+}
+function nodeVersionGuardMessage(version) {
+  return `
+Open Code Review requires Node.js >= ${NODE_FLOOR.major}.${NODE_FLOOR.minor} (it uses Node's built-in SQLite, \`node:sqlite\`).
+You have Node ${version}. Upgrade Node (e.g. \`nvm install 22 && nvm use 22\`) and re-run.
+
+`;
+}
+function isSuppressibleSqliteWarning(warning) {
+  const message = typeof warning === "string" ? warning : warning?.message;
+  return typeof message === "string" && message.includes("SQLite is an experimental feature");
+}
+var NODE_FLOOR;
+var init_runtime_checks = __esm({
+  "src/lib/runtime-checks.ts"() {
+    "use strict";
+    NODE_FLOOR = { major: 22, minor: 5 };
+  }
+});
+
 // ../../node_modules/.pnpm/commander@13.1.0/node_modules/commander/lib/error.js
 var require_error = __commonJS({
   "../../node_modules/.pnpm/commander@13.1.0/node_modules/commander/lib/error.js"(exports) {
@@ -23320,21 +23344,41 @@ var init_result_mapper = __esm({
 });
 
 // src/lib/db/engine.ts
-import BetterSqlite3 from "better-sqlite3";
-function isBusyError(e) {
-  if (e instanceof BetterSqlite3.SqliteError) {
-    return e.code === "SQLITE_BUSY" || e.code === "SQLITE_BUSY_SNAPSHOT";
+import { createRequire as createRequire2 } from "node:module";
+function applyEnginePreconditions() {
+  if (_preconditionsApplied) return;
+  _preconditionsApplied = true;
+  const originalEmitWarning = process.emitWarning.bind(process);
+  process.emitWarning = (warning, ...args) => {
+    if (isSuppressibleSqliteWarning(warning)) return;
+    originalEmitWarning(warning, ...args);
+  };
+}
+function newDatabase(path2) {
+  if (!_DatabaseSyncCtor) {
+    applyEnginePreconditions();
+    try {
+      _DatabaseSyncCtor = nodeRequire("node:sqlite").DatabaseSync;
+    } catch (e) {
+      if (!isSupportedNode(process.versions.node)) {
+        throw new Error(nodeVersionGuardMessage(process.versions.node).trim());
+      }
+      throw e;
+    }
   }
-  const code = e?.code;
-  return code === "SQLITE_BUSY" || code === "SQLITE_BUSY_SNAPSHOT";
+  return new _DatabaseSyncCtor(path2);
+}
+function isBusyError(e) {
+  const errcode = e?.errcode;
+  return errcode === SQLITE_BUSY || errcode === SQLITE_BUSY_SNAPSHOT;
 }
 function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  Atomics.wait(SLEEP_BUF, 0, 0, ms);
 }
 function probeEngine() {
   try {
-    const db = new BetterSqlite3(":memory:");
-    db.pragma("journal_mode = WAL");
+    const db = newDatabase(":memory:");
+    db.exec("PRAGMA journal_mode = WAL");
     db.exec("CREATE TABLE _probe(x); INSERT INTO _probe VALUES (1);");
     const row = db.prepare("SELECT sqlite_version() AS v").get();
     db.close();
@@ -23344,33 +23388,47 @@ function probeEngine() {
   }
 }
 function openEngine(dbPath) {
-  const native = new BetterSqlite3(dbPath);
-  native.pragma("journal_mode = WAL");
-  native.pragma("foreign_keys = ON");
-  native.pragma("busy_timeout = 5000");
-  native.pragma("synchronous = NORMAL");
-  return new BetterSqliteAdapter(native);
-}
-var BUSY_RETRY_ATTEMPTS, BUSY_RETRY_BACKOFF_MS, BetterSqliteAdapter;
+  const native = newDatabase(dbPath);
+  native.exec("PRAGMA journal_mode = WAL");
+  native.exec("PRAGMA foreign_keys = ON");
+  native.exec("PRAGMA busy_timeout = 5000");
+  native.exec("PRAGMA synchronous = NORMAL");
+  return new NodeSqliteAdapter(native);
+}
+var SQLITE_BUSY, SQLITE_BUSY_SNAPSHOT, BUSY_RETRY_ATTEMPTS, BUSY_RETRY_BACKOFF_MS, savepointName, nodeRequire, _preconditionsApplied, _DatabaseSyncCtor, SLEEP_BUF, NodeSqliteAdapter;
 var init_engine = __esm({
   "src/lib/db/engine.ts"() {
     "use strict";
+    init_runtime_checks();
+    SQLITE_BUSY = 5;
+    SQLITE_BUSY_SNAPSHOT = 261;
     BUSY_RETRY_ATTEMPTS = 5;
     BUSY_RETRY_BACKOFF_MS = 50;
-    BetterSqliteAdapter = class {
+    savepointName = (depth) => `ocr_sp_${depth}`;
+    nodeRequire = createRequire2(import.meta.url);
+    _preconditionsApplied = false;
+    SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+    NodeSqliteAdapter = class {
       raw;
+      /**
+       * Transaction nesting depth. `node:sqlite` has no transaction helper, so we
+       * drive `BEGIN IMMEDIATE` ourselves and use SAVEPOINTs for nested calls
+       * (better-sqlite3 did this automatically). 0 = no transaction open.
+       */
+      txnDepth = 0;
       constructor(db) {
         this.raw = db;
       }
       exec(sql, params) {
         const stmt = this.raw.prepare(sql);
-        if (!stmt.reader) {
+        const cols = stmt.columns();
+        if (cols.length === 0) {
           stmt.run(...params ?? []);
           return [];
         }
-        const columns = stmt.columns().map((c) => c.name);
-        const values = stmt.raw().all(...params ?? []);
-        return values.length > 0 ? [{ columns, values }] : [];
+        stmt.setReturnArrays(true);
+        const values = stmt.all(...params ?? []);
+        return values.length > 0 ? [{ columns: cols.map((c) => c.name), values }] : [];
       }
       run(sql, params) {
         if (params !== void 0) {
@@ -23383,25 +23441,84 @@ var init_engine = __esm({
         return this.raw.prepare(sql);
       }
       transaction(fn) {
-        const tx = this.raw.transaction(fn);
-        for (let attempt = 0; ; attempt++) {
+        return this.txnDepth > 0 ? this.runNested(fn) : this.runOuter(fn);
+      }
+      /**
+       * Nested call: a SAVEPOINT within the outer transaction's write lock. No
+       * busy-retry — the outer transaction already holds the lock. The savepoint
+       * lets the inner block roll back independently while the outer continues.
+       */
+      runNested(fn) {
+        const name = savepointName(this.txnDepth);
+        this.raw.exec(`SAVEPOINT ${name}`);
+        this.txnDepth++;
+        try {
+          const result = fn();
+          this.raw.exec(`RELEASE ${name}`);
+          return result;
+        } catch (e) {
           try {
-            return tx.immediate();
+            this.raw.exec(`ROLLBACK TO ${name}`);
+            this.raw.exec(`RELEASE ${name}`);
+          } catch {
+          }
+          throw e;
+        } finally {
+          this.txnDepth--;
+        }
+      }
+      /**
+       * Outer transaction: `BEGIN IMMEDIATE` acquires the write lock up front so
+       * cross-process writers serialize cleanly under WAL instead of failing late
+       * on upgrade. `busy_timeout` covers most contention; a bounded synchronous
+       * retry absorbs the residual SQLITE_BUSY (another connection holds the lock
+       * past the timeout, or BUSY_SNAPSHOT). Non-busy errors and the final attempt
+       * re-throw so genuine failures propagate.
+       */
+      runOuter(fn) {
+        for (let attempt = 0; attempt < BUSY_RETRY_ATTEMPTS; attempt++) {
+          try {
+            return this.runOnce(fn);
           } catch (e) {
-            if (!isBusyError(e) || attempt >= BUSY_RETRY_ATTEMPTS - 1) throw e;
+            if (!isBusyError(e) || attempt === BUSY_RETRY_ATTEMPTS - 1) throw e;
             sleepSync(BUSY_RETRY_BACKOFF_MS);
           }
         }
+        throw new Error("transaction retry budget exhausted");
+      }
+      /** One `BEGIN IMMEDIATE` / `COMMIT` / `ROLLBACK` lifecycle. */
+      runOnce(fn) {
+        this.raw.exec("BEGIN IMMEDIATE");
+        this.txnDepth = 1;
+        try {
+          const result = fn();
+          this.raw.exec("COMMIT");
+          return result;
+        } catch (e) {
+          try {
+            this.raw.exec("ROLLBACK");
+          } catch {
+          }
+          throw e;
+        } finally {
+          this.txnDepth = 0;
+        }
       }
       pragma(source) {
-        return this.raw.pragma(source);
+        this.raw.exec(`PRAGMA ${source}`);
+        return void 0;
       }
       close() {
         try {
-          this.raw.pragma("wal_checkpoint(TRUNCATE)");
+          this.raw.exec("PRAGMA wal_checkpoint(TRUNCATE)");
         } catch {
         }
-        this.raw.close();
+        try {
+          this.raw.close();
+        } catch (e) {
+          const message = e?.message ?? "";
+          if (!/database is not open/i.test(message)) throw e;
+        }
       }
     };
   }
@@ -24764,6 +24881,7 @@ __export(db_exports, {
   listAgentSessionsForWorkflow: () => listAgentSessionsForWorkflow,
   openDatabase: () => openDatabase,
   probeEngine: () => probeEngine,
+  probeWrite: () => probeWrite,
   readCommandLog: () => readCommandLog,
   reconcileLegacyState: () => reconcileLegacyState,
   recordVendorSessionIdForExecution: () => recordVendorSessionIdForExecution,
@@ -24781,7 +24899,15 @@ __export(db_exports, {
   updateSession: () => updateSession,
   walCheckpointTruncate: () => walCheckpointTruncate
 });
-import { existsSync as existsSync12, mkdirSync as mkdirSync4, copyFileSync, statSync } from "node:fs";
+import {
+  existsSync as existsSync12,
+  mkdirSync as mkdirSync4,
+  copyFileSync,
+  statSync,
+  mkdtempSync,
+  rmSync
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname as dirname6, join as join14 } from "node:path";
 function maybeSnapshotBeforeUpgrade(db, dbPath, fromVersion) {
   if (fromVersion < 1 || fromVersion >= V2_SCHEMA_VERSION) return null;
@@ -24889,7 +25015,7 @@ function walCheckpointTruncate(dbPath) {
     return "failed";
   } finally {
     try {
-      transient?.raw.close();
+      transient?.close();
     } catch {
     }
   }
@@ -24907,6 +25033,41 @@ function closeAllDatabases() {
     connections.delete(path2);
   }
 }
+function probeWrite() {
+  let dir;
+  try {
+    dir = mkdtempSync(join14(tmpdir(), "ocr-probe-"));
+    const db = openEngine(join14(dir, "probe.db"));
+    try {
+      db.run("CREATE TABLE _probe_write (id INTEGER PRIMARY KEY, v TEXT)");
+      db.transaction(() => {
+        db.run("INSERT INTO _probe_write (v) VALUES (?)", ["written-in-txn"]);
+      });
+      const value = db.exec("SELECT v FROM _probe_write")[0]?.values[0]?.[0];
+      if (value !== "written-in-txn") {
+        return { ok: false, error: `unexpected probe value: ${String(value)}` };
+      }
+      return { ok: true };
+    } finally {
+      db.close();
+    }
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  } finally {
+    if (dir) rmDirBestEffort(dir);
+  }
+}
+function rmDirBestEffort(dir) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+      return;
+    } catch {
+      if (attempt === 2) return;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+}
 var V2_SCHEMA_VERSION, connections;
 var init_db = __esm({
   "src/lib/db/index.ts"() {
@@ -24929,6 +25090,13 @@ var init_db = __esm({
   }
 });
 
+// src/lib/runtime-guard.ts
+init_runtime_checks();
+if (!isSupportedNode(process.versions.node)) {
+  process.stderr.write(nodeVersionGuardMessage(process.versions.node));
+  process.exit(1);
+}
+
 // ../../node_modules/.pnpm/commander@13.1.0/node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
 var {
@@ -29333,7 +29501,7 @@ ${hint}
 }
 
 // src/lib/version.ts
-var CLI_VERSION = true ? "2.0.0" : createRequire(import.meta.url)("../../package.json").version;
+var CLI_VERSION = true ? "2.1.0" : createRequire(import.meta.url)("../../package.json").version;
 
 // ../shared/platform/src/index.ts
 import { pathToFileURL } from "node:url";
@@ -35412,8 +35580,50 @@ var dashboardCommand = new Command("dashboard").description("Start the OCR dashb
 import { existsSync as existsSync20 } from "node:fs";
 import { join as join24 } from "node:path";
 init_db();
-var doctorCommand = new Command("doctor").description("Check OCR installation and verify all dependencies").action(() => {
+function printStorageEngine(probeWriteEnabled) {
+  console.log();
+  console.log(source_default.bold("  Storage Engine"));
+  console.log();
+  const engine = probeEngine();
+  if (!engine.ok) {
+    console.log(`    ${source_default.red("\u2717")} node:sqlite unavailable`);
+    console.log(`      ${source_default.dim(engine.error)}`);
+    console.log(
+      `      ${source_default.dim(
+        "OCR requires Node >= 22.5 (node:sqlite). Upgrade Node, then re-run `ocr doctor`."
+      )}`
+    );
+    return false;
+  }
+  console.log(
+    `    ${source_default.green("\u2713")} node:sqlite (SQLite ${engine.version}, WAL)`
+  );
+  if (probeWriteEnabled) {
+    const write = probeWrite();
+    if (!write.ok) {
+      console.log(`    ${source_default.red("\u2717")} write probe failed`);
+      console.log(`      ${source_default.dim(write.error)}`);
+      return false;
+    }
+    console.log(
+      `    ${source_default.green("\u2713")} write probe (on-disk WAL transaction round-trip)`
+    );
+  }
+  return true;
+}
+var doctorCommand = new Command("doctor").description("Check OCR installation and verify all dependencies").option(
+  "--probe-write",
+  "additionally exercise an on-disk WAL transaction round-trip (used by the release install gate)"
+).option(
+  "--engine-only",
+  "check ONLY the storage engine and exit on its result \u2014 skips project/tool checks (used by the release install gate, which runs from a non-initialized dir with no AI tools)"
+).action((options) => {
   printHeader();
+  if (options.engineOnly) {
+    const ok = printStorageEngine(options.probeWrite ?? false);
+    console.log();
+    process.exit(ok ? 0 : 1);
+  }
   const targetDir = process.cwd();
   let hasIssues = false;
   const depResult = checkDependencies();
@@ -35450,25 +35660,8 @@ var doctorCommand = new Command("doctor").description("Check OCR installation an
   if (!ocrStatus.valid) {
     hasIssues = true;
   }
-  console.log();
-  console.log(source_default.bold("  Storage Engine"));
-  console.log();
-  const engine = probeEngine();
-  if (engine.ok) {
-    console.log(
-      `    ${source_default.green("\u2713")} better-sqlite3 (SQLite ${engine.version}, WAL)`
-    );
-  } else {
+  if (!printStorageEngine(options.probeWrite ?? false)) {
     hasIssues = true;
-    console.log(
-      `    ${source_default.red("\u2717")} better-sqlite3 failed to load`
-    );
-    console.log(`      ${source_default.dim(engine.error)}`);
-    console.log(
-      `      ${source_default.dim(
-        "Reinstall the CLI; if it persists your platform may need build tools (python3 + a C++ toolchain) or lacks a prebuilt binary."
-      )}`
-    );
   }
   console.log();
   printCapabilities(depResult);

package/dist/lib/db/index.js

@@ -1,35 +1,97 @@
 // src/lib/db/index.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, copyFileSync, statSync } from "node:fs";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  copyFileSync,
+  statSync,
+  mkdtempSync,
+  rmSync
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname as dirname3, join as join3 } from "node:path";
 
 // src/lib/db/engine.ts
-import BetterSqlite3 from "better-sqlite3";
+import { createRequire } from "node:module";
+
+// src/lib/runtime-checks.ts
+var NODE_FLOOR = { major: 22, minor: 5 };
+function isSupportedNode(version) {
+  const [major = 0, minor = 0] = version.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  return major > NODE_FLOOR.major || major === NODE_FLOOR.major && minor >= NODE_FLOOR.minor;
+}
+function nodeVersionGuardMessage(version) {
+  return `
+Open Code Review requires Node.js >= ${NODE_FLOOR.major}.${NODE_FLOOR.minor} (it uses Node's built-in SQLite, \`node:sqlite\`).
+You have Node ${version}. Upgrade Node (e.g. \`nvm install 22 && nvm use 22\`) and re-run.
+
+`;
+}
+function isSuppressibleSqliteWarning(warning) {
+  const message = typeof warning === "string" ? warning : warning?.message;
+  return typeof message === "string" && message.includes("SQLite is an experimental feature");
+}
+
+// src/lib/db/engine.ts
+var SQLITE_BUSY = 5;
+var SQLITE_BUSY_SNAPSHOT = 261;
 var BUSY_RETRY_ATTEMPTS = 5;
 var BUSY_RETRY_BACKOFF_MS = 50;
-function isBusyError(e) {
-  if (e instanceof BetterSqlite3.SqliteError) {
-    return e.code === "SQLITE_BUSY" || e.code === "SQLITE_BUSY_SNAPSHOT";
+var savepointName = (depth) => `ocr_sp_${depth}`;
+var nodeRequire = createRequire(import.meta.url);
+var _preconditionsApplied = false;
+function applyEnginePreconditions() {
+  if (_preconditionsApplied) return;
+  _preconditionsApplied = true;
+  const originalEmitWarning = process.emitWarning.bind(process);
+  process.emitWarning = (warning, ...args) => {
+    if (isSuppressibleSqliteWarning(warning)) return;
+    originalEmitWarning(warning, ...args);
+  };
+}
+var _DatabaseSyncCtor;
+function newDatabase(path) {
+  if (!_DatabaseSyncCtor) {
+    applyEnginePreconditions();
+    try {
+      _DatabaseSyncCtor = nodeRequire("node:sqlite").DatabaseSync;
+    } catch (e) {
+      if (!isSupportedNode(process.versions.node)) {
+        throw new Error(nodeVersionGuardMessage(process.versions.node).trim());
+      }
+      throw e;
+    }
   }
-  const code = e?.code;
-  return code === "SQLITE_BUSY" || code === "SQLITE_BUSY_SNAPSHOT";
+  return new _DatabaseSyncCtor(path);
+}
+function isBusyError(e) {
+  const errcode = e?.errcode;
+  return errcode === SQLITE_BUSY || errcode === SQLITE_BUSY_SNAPSHOT;
 }
+var SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
 function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  Atomics.wait(SLEEP_BUF, 0, 0, ms);
 }
-var BetterSqliteAdapter = class {
+var NodeSqliteAdapter = class {
   raw;
+  /**
+   * Transaction nesting depth. `node:sqlite` has no transaction helper, so we
+   * drive `BEGIN IMMEDIATE` ourselves and use SAVEPOINTs for nested calls
+   * (better-sqlite3 did this automatically). 0 = no transaction open.
+   */
+  txnDepth = 0;
   constructor(db) {
     this.raw = db;
   }
   exec(sql, params) {
     const stmt = this.raw.prepare(sql);
-    if (!stmt.reader) {
+    const cols = stmt.columns();
+    if (cols.length === 0) {
       stmt.run(...params ?? []);
       return [];
     }
-    const columns = stmt.columns().map((c) => c.name);
-    const values = stmt.raw().all(...params ?? []);
-    return values.length > 0 ? [{ columns, values }] : [];
+    stmt.setReturnArrays(true);
+    const values = stmt.all(...params ?? []);
+    return values.length > 0 ? [{ columns: cols.map((c) => c.name), values }] : [];
   }
   run(sql, params) {
     if (params !== void 0) {
@@ -42,31 +104,90 @@ var BetterSqliteAdapter = class {
     return this.raw.prepare(sql);
   }
   transaction(fn) {
-    const tx = this.raw.transaction(fn);
-    for (let attempt = 0; ; attempt++) {
+    return this.txnDepth > 0 ? this.runNested(fn) : this.runOuter(fn);
+  }
+  /**
+   * Nested call: a SAVEPOINT within the outer transaction's write lock. No
+   * busy-retry — the outer transaction already holds the lock. The savepoint
+   * lets the inner block roll back independently while the outer continues.
+   */
+  runNested(fn) {
+    const name = savepointName(this.txnDepth);
+    this.raw.exec(`SAVEPOINT ${name}`);
+    this.txnDepth++;
+    try {
+      const result = fn();
+      this.raw.exec(`RELEASE ${name}`);
+      return result;
+    } catch (e) {
       try {
-        return tx.immediate();
+        this.raw.exec(`ROLLBACK TO ${name}`);
+        this.raw.exec(`RELEASE ${name}`);
+      } catch {
+      }
+      throw e;
+    } finally {
+      this.txnDepth--;
+    }
+  }
+  /**
+   * Outer transaction: `BEGIN IMMEDIATE` acquires the write lock up front so
+   * cross-process writers serialize cleanly under WAL instead of failing late
+   * on upgrade. `busy_timeout` covers most contention; a bounded synchronous
+   * retry absorbs the residual SQLITE_BUSY (another connection holds the lock
+   * past the timeout, or BUSY_SNAPSHOT). Non-busy errors and the final attempt
+   * re-throw so genuine failures propagate.
+   */
+  runOuter(fn) {
+    for (let attempt = 0; attempt < BUSY_RETRY_ATTEMPTS; attempt++) {
+      try {
+        return this.runOnce(fn);
       } catch (e) {
-        if (!isBusyError(e) || attempt >= BUSY_RETRY_ATTEMPTS - 1) throw e;
+        if (!isBusyError(e) || attempt === BUSY_RETRY_ATTEMPTS - 1) throw e;
         sleepSync(BUSY_RETRY_BACKOFF_MS);
       }
     }
+    throw new Error("transaction retry budget exhausted");
+  }
+  /** One `BEGIN IMMEDIATE` / `COMMIT` / `ROLLBACK` lifecycle. */
+  runOnce(fn) {
+    this.raw.exec("BEGIN IMMEDIATE");
+    this.txnDepth = 1;
+    try {
+      const result = fn();
+      this.raw.exec("COMMIT");
+      return result;
+    } catch (e) {
+      try {
+        this.raw.exec("ROLLBACK");
+      } catch {
+      }
+      throw e;
+    } finally {
+      this.txnDepth = 0;
+    }
   }
   pragma(source) {
-    return this.raw.pragma(source);
+    this.raw.exec(`PRAGMA ${source}`);
+    return void 0;
   }
   close() {
     try {
-      this.raw.pragma("wal_checkpoint(TRUNCATE)");
+      this.raw.exec("PRAGMA wal_checkpoint(TRUNCATE)");
     } catch {
     }
-    this.raw.close();
+    try {
+      this.raw.close();
+    } catch (e) {
+      const message = e?.message ?? "";
+      if (!/database is not open/i.test(message)) throw e;
+    }
   }
 };
 function probeEngine() {
   try {
-    const db = new BetterSqlite3(":memory:");
-    db.pragma("journal_mode = WAL");
+    const db = newDatabase(":memory:");
+    db.exec("PRAGMA journal_mode = WAL");
     db.exec("CREATE TABLE _probe(x); INSERT INTO _probe VALUES (1);");
     const row = db.prepare("SELECT sqlite_version() AS v").get();
     db.close();
@@ -76,12 +197,12 @@ function probeEngine() {
   }
 }
 function openEngine(dbPath) {
-  const native = new BetterSqlite3(dbPath);
-  native.pragma("journal_mode = WAL");
-  native.pragma("foreign_keys = ON");
-  native.pragma("busy_timeout = 5000");
-  native.pragma("synchronous = NORMAL");
-  return new BetterSqliteAdapter(native);
+  const native = newDatabase(dbPath);
+  native.exec("PRAGMA journal_mode = WAL");
+  native.exec("PRAGMA foreign_keys = ON");
+  native.exec("PRAGMA busy_timeout = 5000");
+  native.exec("PRAGMA synchronous = NORMAL");
+  return new NodeSqliteAdapter(native);
 }
 
 // src/lib/db/migrations.ts
@@ -1484,7 +1605,7 @@ function walCheckpointTruncate(dbPath) {
     return "failed";
   } finally {
     try {
-      transient?.raw.close();
+      transient?.close();
     } catch {
     }
   }
@@ -1502,6 +1623,41 @@ function closeAllDatabases() {
     connections.delete(path);
   }
 }
+function probeWrite() {
+  let dir;
+  try {
+    dir = mkdtempSync(join3(tmpdir(), "ocr-probe-"));
+    const db = openEngine(join3(dir, "probe.db"));
+    try {
+      db.run("CREATE TABLE _probe_write (id INTEGER PRIMARY KEY, v TEXT)");
+      db.transaction(() => {
+        db.run("INSERT INTO _probe_write (v) VALUES (?)", ["written-in-txn"]);
+      });
+      const value = db.exec("SELECT v FROM _probe_write")[0]?.values[0]?.[0];
+      if (value !== "written-in-txn") {
+        return { ok: false, error: `unexpected probe value: ${String(value)}` };
+      }
+      return { ok: true };
+    } finally {
+      db.close();
+    }
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  } finally {
+    if (dir) rmDirBestEffort(dir);
+  }
+}
+function rmDirBestEffort(dir) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+      return;
+    } catch {
+      if (attempt === 2) return;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+    }
+  }
+}
 export {
   CANCELLED_EXIT_CODE,
   CASCADE_CLOSE_EXIT_CODE,
@@ -1540,6 +1696,7 @@ export {
   listAgentSessionsForWorkflow,
   openDatabase,
   probeEngine,
+  probeWrite,
   readCommandLog,
   reconcileLegacyState,
   recordVendorSessionIdForExecution,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-code-review/cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "CLI for Open Code Review - Multi-environment setup and progress tracking",
   "type": "module",
   "bin": {
@@ -63,7 +63,7 @@
   "license": "Apache-2.0",
   "author": "Spencer Marx",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.5.0"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.2.0",
@@ -73,15 +73,13 @@
     "log-update": "^7.0.2",
     "ora": "^8.1.1",
     "socket.io": "^4.8",
-    "better-sqlite3": "^11.8.1",
     "yaml": "^2.8.3",
-    "@open-code-review/agents": "2.0.0"
+    "@open-code-review/agents": "2.1.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.12",
     "@open-code-review/platform": "0.0.0"
   }
 }