@mndrk/agx 2.0.36 → 2.0.39

package/cloud-runtime/standalone/docs/superpowers/plans/2026-04-02-sqlite-migration.md

@@ -0,0 +1,1047 @@
+# Migrate better-sqlite3 → node:sqlite Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the `better-sqlite3` native addon with Node.js built-in `node:sqlite` (`DatabaseSync`) to eliminate native compilation and cross-platform distribution issues in both agx-cloud and agx CLI.
+
+**Architecture:** Create a thin compatibility layer (`lib/sqlite-compat.ts`) that provides `pragma()`, `transaction()`, and `backup()` helpers matching the better-sqlite3 API surface. All files then import from `node:sqlite` directly for the `DatabaseSync` class and use the compat helpers where needed. This avoids touching every call site for pragmas/transactions while keeping the migration mechanical.
+
+**Tech Stack:** `node:sqlite` (DatabaseSync) — built into Node.js ≥ 22.16
+
+**Runtime floor:** Node.js ≥ 22.16.0 (required — `readOnly` in 22.12, `--experimental-sqlite` flag removed in 22.13, `sqlite.backup()` added in 22.16). Enforced via `engines` field in all package.json files AND a hard preinstall version check that exits with a clear error on unsupported runtimes.
+
+**Constraints:**
+- `node:sqlite` has no `db.pragma()` method — use `db.exec("PRAGMA ...")` or `db.prepare("PRAGMA ...").get()`
+- `node:sqlite` has no `db.transaction()` wrapper — need manual BEGIN/COMMIT/ROLLBACK
+- `node:sqlite` has `backup(sourceDb, destPath)` as a module-level async function (not a method on db)
+- `node:sqlite` `readOnly` option uses camelCase (not `readonly`)
+- `DatabaseSync` results use `Object.create(null)` prototypes (no `hasOwnProperty` etc.)
+- Constructor: `new DatabaseSync(path)` not `new Database(path)`
+- Type: `DatabaseSync` not `Database.Database`
+- `@types/node` already ships `node:sqlite` typings — do NOT create local type declarations
+
+---
+
+## File Structure
+
+### agx-cloud — New files
+- `lib/sqlite-compat.ts` — Compat helpers: `pragma()`, `transaction()`
+
+### agx-cloud — Modified files (imports + API calls)
+1. `lib/sqlite-query-adapter.ts` — Singleton DB connection, import + constructor
+2. `lib/startup.ts` — Pragma validation, import + all `db.pragma()` calls
+3. `src/db/init.ts` — `applyPragmas()`, import + pragma calls
+4. `src/db/checks.ts` — Extension/version checks, import + type
+5. `src/db/backup.ts` — Backup/restore/checkpoint, import + backup rewrite
+6. `lib/sqlite_writer.ts` — Batch writer, import + pragma + transaction
+7. `lib/queue/sqlite-adapter.ts` — Job queue, import + pragma + transaction
+8. `lib/history-store.ts` — Chat history, import + transaction
+9. `lib/participants-store.ts` — Participant store, import + transaction
+10. `lib/agent-process-registry.ts` — Process registry, import + pragma
+11. `lib/attachment-store.ts` — Attachment store, import + pragma
+12. `src/graph/store.ts` — Graph store, import type + pragma + transaction
+13. `src/graph/schedule-runner.ts` — Import type only
+14. `src/prompt-scheduler/store.ts` — Import type only
+15. `lib/workspaces-to-projects-migration.ts` — Migration, import type + transaction
+16. `lib/db-adapter.interface.ts` — Comment update (mentions better-sqlite3)
+17. `mcp/src/db.ts` — MCP server DB, dynamic import + pragma
+18. `app/api/system/db-status/route.ts` — Health check, import + pragma
+19. `app/api/agents/[id]/messages/route.ts` — Messages API, import + pragma + readonly
+20. `next.config.ts` — Remove `serverExternalPackages`
+21. `scripts/fix-turbopack-externals.mjs` — DELETE this file
+22. `package.json` — Remove `better-sqlite3` + `@types/better-sqlite3`
+23. `components/errors/StartupGuard.tsx` — Update error message text (mentions better-sqlite3)
+24. `components/errors/StartupGuardWrapper.tsx` — Update error message text
+25. `__tests__/db/init.test.ts` — Test file, import + pragma assertions
+26. `__tests__/prompt-scheduler/store.test.ts` — Test file, import + pragma
+27. `__tests__/prompt-scheduler/engine.test.ts` — Test file, import + pragma
+28. `__tests__/graph/store.test.ts` — Test file, pragma calls
+29. `test/adapters/sqlite.ts` — Test adapter, import + constructor
+30. `scripts/bench-queue.ts` — Benchmark script, import + pragma
+31. `lib/repo-knowledge.ts` — transaction calls
+32. `lib/knowledge-store.ts` — transaction calls
+33. `lib/thread-knowledge-runs.ts` — transaction calls
+
+### agx CLI — Modified files
+1. `lib/storage/db.js` — Import + constructor + pragma + transaction
+2. `lib/cli/onboarding.js` — Import + constructor + pragma
+3. `package.json` — Remove `better-sqlite3`
+4. `scripts/postinstall.js` — Remove native addon copying logic
+
+---
+
+### Task 1: Create sqlite-compat.ts helper module (agx-cloud)
+
+**Files:**
+- Create: `agx-cloud/lib/sqlite-compat.ts`
+
+- [ ] **Step 1: Write the compat module**
+
+```typescript
+/**
+ * Compatibility helpers for migrating from better-sqlite3 to node:sqlite.
+ *
+ * Provides pragma() and transaction() helpers that match
+ * the better-sqlite3 API surface used throughout agx-cloud.
+ *
+ * For backups, use the module-level `backup()` from "node:sqlite" directly.
+ */
+import { DatabaseSync } from "node:sqlite";
+
+/**
+ * Read a PRAGMA value, returning the value directly (like better-sqlite3's simple mode).
+ * Example: pragmaGet(db, "journal_mode") => "wal"
+ */
+export function pragmaGet(db: DatabaseSync, key: string): unknown {
+  const row = db.prepare(`PRAGMA ${key}`).get() as Record<string, unknown> | undefined;
+  if (!row) return undefined;
+  return row[key];
+}
+
+/**
+ * Read a PRAGMA that returns multiple rows (like table_info, foreign_key_check).
+ * Example: pragmaAll(db, "table_info(agents)") => [{ cid: 0, name: "id", ... }]
+ */
+export function pragmaAll(db: DatabaseSync, key: string): unknown[] {
+  return db.prepare(`PRAGMA ${key}`).all();
+}
+
+/**
+ * Set a PRAGMA value.
+ * Example: pragmaSet(db, "journal_mode", "WAL")
+ * Example: pragmaSet(db, "journal_mode = WAL")
+ */
+export function pragmaSet(db: DatabaseSync, pragma: string): void {
+  db.exec(`PRAGMA ${pragma}`);
+}
+
+/**
+ * Run a function inside a transaction. Mimics better-sqlite3's db.transaction() API.
+ * Automatically commits on success, rolls back on error.
+ */
+export function transaction<T>(db: DatabaseSync, fn: () => T): T {
+  db.exec("BEGIN");
+  try {
+    const result = fn();
+    db.exec("COMMIT");
+    return result;
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
+/**
+ * Returns a reusable transaction wrapper (like better-sqlite3's db.transaction(fn)).
+ * The returned function accepts args and passes them to fn.
+ */
+export function transactionFn<TArgs extends unknown[], TResult>(
+  db: DatabaseSync,
+  fn: (...args: TArgs) => TResult,
+): (...args: TArgs) => TResult {
+  return (...args: TArgs) => {
+    db.exec("BEGIN");
+    try {
+      const result = fn(...args);
+      db.exec("COMMIT");
+      return result;
+    } catch (err) {
+      db.exec("ROLLBACK");
+      throw err;
+    }
+  };
+}
+
+```
+
+- [ ] **Step 2: Verify the module compiles**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npx tsc --noEmit lib/sqlite-compat.ts --esModuleInterop --module nodenext --moduleResolution nodenext --target es2022 --skipLibCheck 2>&1 | head -20`
+
+Note: This may show errors about node:sqlite types — that's expected since @types/node may need updating. The runtime works; type errors will be addressed in Task 2.
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add lib/sqlite-compat.ts
+git commit -m "feat: add node:sqlite compatibility helpers for better-sqlite3 migration"
+```
+
+---
+
+### Task 2: Enforce Node.js ≥ 22.16 runtime floor
+
+The migration requires Node ≥ 22.16 (`readOnly` in 22.12, `--experimental-sqlite` removed in 22.13, `sqlite.backup()` added in 22.16). Add `engines` to all three package.json files AND a hard preinstall version check — `engines` alone is advisory unless the user has `engine-strict` enabled.
+
+`@types/node` already ships `node:sqlite` typings in this repo — no local type declarations needed.
+
+**Files:**
+- Modify: `agx-cloud/package.json`
+- Modify: `agx-cloud/mcp/package.json`
+- Modify: `agx/package.json`
+- Modify: `agx/scripts/postinstall.js`
+- Modify: `agx-cloud/instrumentation.ts`
+- Modify: `agx-cloud/worker/index.ts`
+- Modify: `agx-cloud/mcp/src/index.ts`
+
+- [ ] **Step 1: Add engines to agx-cloud/package.json**
+
+Add to the top level:
+```json
+"engines": {
+  "node": ">=22.16.0"
+}
+```
+
+- [ ] **Step 2: Add engines to agx-cloud/mcp/package.json**
+
+Add to the top level:
+```json
+"engines": {
+  "node": ">=22.16.0"
+}
+```
+
+- [ ] **Step 3: Add engines to agx/package.json**
+
+Add to the top level:
+```json
+"engines": {
+  "node": ">=22.16.0"
+}
+```
+
+- [ ] **Step 4: Add a hard preinstall version check to agx CLI**
+
+The agx CLI is distributed via npm — `engines` won't block installs by default. Add a `preinstall` script that exits with a clear error:
+
+In `agx/package.json`, add:
+```json
+"scripts": {
+  "preinstall": "node -e \"var v=process.versions.node.split('.').map(Number);if(v[0]<22||(v[0]===22&&v[1]<16)){console.error('agx requires Node.js >= 22.16.0 (found '+process.version+'). node:sqlite is not available on older versions.');process.exit(1)}\""
+}
+```
+
+- [ ] **Step 5: Add a bootstrap version guard for agx-cloud**
+
+agx-cloud is self-hosted, not npm-distributed. The guard **cannot** live in `lib/startup.ts` because that file will statically import `node:sqlite` after Task 4 — Node resolves imports before executing module code, so the process would crash before reaching the check.
+
+Create a dedicated bootstrap module that runs before any `node:sqlite` import:
+
+Create `agx-cloud/lib/check-node-version.ts`:
+```typescript
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 16)) {
+  console.error(
+    `agx-cloud requires Node.js >= 22.16.0 (found ${process.version}). ` +
+    `node:sqlite is not available on older versions.`
+  );
+  process.exit(1);
+}
+```
+
+Then import it as the **first line** of the Next.js instrumentation hook (`instrumentation.ts` or the app entry point) so it runs before any other module loads:
+```typescript
+import "./lib/check-node-version";
+```
+
+This module must NOT import `node:sqlite` or any module that transitively imports it.
+
+agx-cloud also has a standalone worker entrypoint (`worker/index.ts` via `npm run worker`). Import the same guard as the **first line** there too, before any queue or DB imports:
+```typescript
+import "@/lib/check-node-version";
+```
+
+- [ ] **Step 6: Add a bootstrap version guard for MCP**
+
+The MCP package is separately runnable. Add the same guard to `mcp/src/index.ts` as the first import:
+
+Create `agx-cloud/mcp/src/check-node-version.ts`:
+```typescript
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 16)) {
+  console.error(
+    `agx-mcp requires Node.js >= 22.16.0 (found ${process.version}). ` +
+    `node:sqlite is not available on older versions.`
+  );
+  process.exit(1);
+}
+```
+
+Import as the first line of `mcp/src/index.ts`:
+```typescript
+import "./check-node-version";
+```
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add package.json mcp/package.json instrumentation.ts worker/index.ts mcp/src/index.ts \
+  lib/check-node-version.ts mcp/src/check-node-version.ts
+git commit -m "chore: enforce Node.js >= 22.16 runtime floor for node:sqlite migration"
+
+cd /Users/mendrika/Projects/Agents/agx
+git add package.json
+git commit -m "chore: enforce Node.js >= 22.16 runtime floor for node:sqlite migration"
+```
+
+---
+
+### Task 3: Migrate core DB init layer (agx-cloud)
+
+**Files:**
+- Modify: `agx-cloud/src/db/checks.ts`
+- Modify: `agx-cloud/src/db/init.ts`
+- Modify: `agx-cloud/__tests__/db/init.test.ts`
+
+- [ ] **Step 1: Migrate `src/db/checks.ts`**
+
+Replace:
+```typescript
+import Database from "better-sqlite3";
+```
+With:
+```typescript
+import { DatabaseSync } from "node:sqlite";
+```
+
+Replace all `Database.Database` type references with `DatabaseSync`.
+
+The `checkVersion`, `checkExtensions`, `checkFilesystem` functions use `db.prepare()`, `db.exec()`, `db.prepare().get()` — these are identical in node:sqlite. No logic changes needed.
+
+- [ ] **Step 2: Migrate `src/db/init.ts`**
+
+Replace:
+```typescript
+import Database from "better-sqlite3";
+```
+With:
+```typescript
+import { DatabaseSync } from "node:sqlite";
+import { pragmaGet, pragmaSet } from "@/lib/sqlite-compat";
+```
+
+Update `applyPragmas`:
+```typescript
+export function applyPragmas(db: DatabaseSync, opts?: InitOptions): void {
+  pragmaSet(db, "journal_mode = WAL");
+  const jm = String(pragmaGet(db, "journal_mode")).toLowerCase();
+  if (jm !== "wal") {
+    pragmaSet(db, "journal_mode = DELETE");
+    pragmaSet(db, "synchronous = FULL");
+    console.warn(`[db/init] WAL unavailable (got '${jm}'), using DELETE with synchronous=FULL`);
+  } else {
+    pragmaSet(db, `synchronous = ${opts?.synchronous ?? "NORMAL"}`);
+  }
+  pragmaSet(db, "foreign_keys = ON");
+  pragmaSet(db, `busy_timeout = ${opts?.busyTimeout ?? 5000}`);
+  pragmaSet(db, `cache_size = ${opts?.cacheSize ?? -64000}`);
+}
+```
+
+Update `initDatabase`:
+```typescript
+export function initDatabase(
+  dbPath: string,
+  opts?: InitOptions
+): DatabaseSync {
+  checkFilesystem(dbPath, { strict: opts?.strictFsCheck });
+  const db = new DatabaseSync(dbPath);
+  try {
+    checkVersion(db);
+    checkExtensions(db, { requireFts5: opts?.requireFts5 });
+    applyPragmas(db, opts);
+  } catch (err) {
+    db.close();
+    throw err;
+  }
+  return db;
+}
+```
+
+- [ ] **Step 3: Migrate `__tests__/db/init.test.ts`**
+
+Replace:
+```typescript
+import Database from "better-sqlite3";
+```
+With:
+```typescript
+import { DatabaseSync } from "node:sqlite";
+import { pragmaGet } from "@/lib/sqlite-compat";
+```
+
+Replace all `new Database(...)` with `new DatabaseSync(...)`.
+
+Replace pragma assertions like:
+```typescript
+expect(db.pragma("journal_mode", { simple: true })).toBe("wal");
+```
+With:
+```typescript
+expect(pragmaGet(db, "journal_mode")).toBe("wal");
+```
+
+Replace:
+```typescript
+expect(db.pragma("foreign_keys", { simple: true })).toBe(1);
+```
+With:
+```typescript
+expect(pragmaGet(db, "foreign_keys")).toBe(1);
+```
+
+Do the same for `busy_timeout`, `synchronous`, `cache_size` assertions.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npx jest __tests__/db/init.test.ts --no-coverage 2>&1`
+Expected: All tests pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add src/db/checks.ts src/db/init.ts __tests__/db/init.test.ts
+git commit -m "refactor: migrate db init layer from better-sqlite3 to node:sqlite"
+```
+
+---
+
+### Task 4: Migrate startup.ts (agx-cloud)
+
+**Files:**
+- Modify: `agx-cloud/lib/startup.ts`
+
+- [ ] **Step 1: Update imports**
+
+Replace:
+```typescript
+import Database from "better-sqlite3";
+```
+With:
+```typescript
+import { DatabaseSync } from "node:sqlite";
+import { pragmaGet, pragmaSet } from "./sqlite-compat";
+```
+
+- [ ] **Step 2: Replace all `Database.Database` types with `DatabaseSync`**
+
+Update function signatures: `checkExtension`, `validateSQLiteEnvironment`, `backupDatabase`.
+
+- [ ] **Step 3: Replace all pragma calls**
+
+Replace patterns like:
+```typescript
+db.pragma(`journal_mode = ${REQUIRED_PRAGMAS.journal_mode}`);
+```
+With:
+```typescript
+pragmaSet(db, `journal_mode = ${REQUIRED_PRAGMAS.journal_mode}`);
+```
+
+Replace pragma reads like:
+```typescript
+const jm = (db.pragma("journal_mode", { simple: true }) as string).toLowerCase();
+```
+With:
+```typescript
+const jm = String(pragmaGet(db, "journal_mode")).toLowerCase();
+```
+
+- [ ] **Step 4: Replace backup function**
+
+Replace:
+```typescript
+export async function backupDatabase(db: Database.Database, destPath: string): Promise<void> {
+  db.pragma("wal_checkpoint(TRUNCATE)");
+  await db.backup(destPath);
+}
+```
+With:
+```typescript
+import { backup as sqliteBackup } from "node:sqlite";
+
+export async function backupDatabase(db: DatabaseSync, destPath: string): Promise<void> {
+  db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  await sqliteBackup(db, destPath);
+}
+```
+
+Same async signature, same online-backup semantics — `backup()` is a module-level function in `node:sqlite`.
+
+- [ ] **Step 5: Update the fix suggestion in error messages**
+
+Replace any text mentioning `npm rebuild better-sqlite3` with guidance about Node.js version:
+```typescript
+fix: "Ensure Node.js >= 22.16 is installed (node:sqlite is built-in)"
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add lib/startup.ts
+git commit -m "refactor: migrate startup.ts from better-sqlite3 to node:sqlite"
+```
+
+---
+
+### Task 5: Migrate backup.ts (agx-cloud)
+
+**Files:**
+- Modify: `agx-cloud/src/db/backup.ts`
+
+- [ ] **Step 1: Update imports and types**
+
+Replace:
+```typescript
+import Database from "better-sqlite3";
+```
+With:
+```typescript
+import { DatabaseSync } from "node:sqlite";
+import { pragmaGet, pragmaAll } from "@/lib/sqlite-compat";
+```
+
+Replace all `Database.Database` with `DatabaseSync`.
+
+- [ ] **Step 2: Rewrite `backup()` function**
+
+`node:sqlite` exposes `backup(sourceDb, destPath)` as a module-level async function that uses the SQLite Online Backup API — same semantics as better-sqlite3's `db.backup()`. Import it and use directly:
+
+```typescript
+import { DatabaseSync, backup as sqliteBackup } from "node:sqlite";
+
+export async function backup(
+  db: DatabaseSync,
+  opts: BackupOptions
+): Promise<string> {
+  if (!fs.existsSync(opts.backupDir)) {
+    fs.mkdirSync(opts.backupDir, { recursive: true });
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = path.join(opts.backupDir, `backup-${timestamp}.db`);
+
+  // Online backup — consistent snapshot without stopping writes
+  await sqliteBackup(db, backupPath);
+
+  // Prune old backups
+  const maxBackups = opts.maxBackups ?? DEFAULT_MAX_BACKUPS;
+  const files = fs
+    .readdirSync(opts.backupDir)
+    .filter((f) => f.startsWith("backup-") && f.endsWith(".db"))
+    .sort();
+
+  while (files.length > maxBackups) {
+    const oldest = files.shift()!;
+    fs.unlinkSync(path.join(opts.backupDir, oldest));
+  }
+
+  return backupPath;
+}
+```
+
+Signature stays async, no `dbPath` parameter needed — same caller contract as before.
+
+- [ ] **Step 3: Update `restore()` function**
+
+Replace `new Database(targetDbPath)` with `new DatabaseSync(targetDbPath)`.
+Replace `db.pragma("integrity_check")` with `pragmaAll(db, "integrity_check")`.
+
+```typescript
+export function restore(
+  backupPath: string,
+  targetDbPath: string
+): DatabaseSync {
+  if (!fs.existsSync(backupPath)) {
+    throw new Error(`Backup file not found: ${backupPath}`);
+  }
+  for (const suffix of ["", "-wal", "-shm"]) {
+    const filePath = targetDbPath + suffix;
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  }
+  fs.copyFileSync(backupPath, targetDbPath);
+
+  const db = new DatabaseSync(targetDbPath);
+  const result = pragmaAll(db, "integrity_check") as { integrity_check: string }[];
+  const status = result[0]?.integrity_check ?? "unknown";
+  if (status !== "ok") {
+    db.close();
+    throw new Error(`Integrity check failed after restore: ${status}`);
+  }
+  return db;
+}
+```
+
+- [ ] **Step 4: Update `checkpoint()` function**
+
+Replace:
+```typescript
+db.pragma(`wal_checkpoint(${mode})`);
+```
+With:
+```typescript
+db.exec(`PRAGMA wal_checkpoint(${mode})`);
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add src/db/backup.ts
+git commit -m "refactor: migrate backup.ts from better-sqlite3 to node:sqlite"
+```
+
+---
+
+### Task 6: Migrate sqlite-query-adapter.ts (agx-cloud)
+
+**Files:**
+- Modify: `agx-cloud/lib/sqlite-query-adapter.ts`
+
+- [ ] **Step 1: Update import and singleton type**
+
+Replace:
+```typescript
+import Database from "better-sqlite3";
+```
+With:
+```typescript
+import { DatabaseSync } from "node:sqlite";
+```
+
+Replace:
+```typescript
+let _db: Database.Database | null = null;
+export function getSQLiteDb(): Database.Database {
+```
+With:
+```typescript
+let _db: DatabaseSync | null = null;
+export function getSQLiteDb(): DatabaseSync {
+```
+
+Replace `new Database(dbPath)` with `new DatabaseSync(dbPath)`.
+
+- [ ] **Step 2: Update pragma calls in the file**
+
+Search for any `db.pragma(` calls and replace with `pragmaGet`/`pragmaAll`/`pragmaSet` from `./sqlite-compat`. Common ones:
+- `db.pragma("table_info(...)")` → `pragmaAll(db, "table_info(...)")`
+
+- [ ] **Step 3: Run type check**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npx tsc --noEmit 2>&1 | head -30`
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add lib/sqlite-query-adapter.ts
+git commit -m "refactor: migrate sqlite-query-adapter.ts from better-sqlite3 to node:sqlite"
+```
+
+---
+
+### Task 7: Migrate transaction-heavy files (agx-cloud)
+
+**Files:**
+- Modify: `agx-cloud/lib/sqlite_writer.ts`
+- Modify: `agx-cloud/lib/queue/sqlite-adapter.ts`
+- Modify: `agx-cloud/lib/history-store.ts`
+- Modify: `agx-cloud/lib/participants-store.ts`
+- Modify: `agx-cloud/lib/workspaces-to-projects-migration.ts`
+- Modify: `agx-cloud/src/graph/store.ts`
+- Modify: `agx-cloud/lib/repo-knowledge.ts`
+- Modify: `agx-cloud/lib/knowledge-store.ts`
+- Modify: `agx-cloud/lib/thread-knowledge-runs.ts`
+
+For each file:
+
+- [ ] **Step 1: Update imports**
+
+Replace `import Database from "better-sqlite3"` or `import type Database from "better-sqlite3"` with:
+```typescript
+import { DatabaseSync } from "node:sqlite";
+// or for type-only:
+import type { DatabaseSync } from "node:sqlite";
+```
+
+Add compat imports where needed:
+```typescript
+import { transaction, transactionFn, pragmaSet, pragmaGet, pragmaAll } from "@/lib/sqlite-compat";
+// or relative path depending on file location
+```
+
+- [ ] **Step 2: Replace `Database.Database` types with `DatabaseSync`**
+
+Global find-replace within each file.
+
+- [ ] **Step 3: Replace `new Database(...)` with `new DatabaseSync(...)`**
+
+- [ ] **Step 4: Replace pragma calls**
+
+- `db.pragma("key = value")` → `pragmaSet(db, "key = value")`
+- `db.pragma("key", { simple: true })` → `pragmaGet(db, "key")`
+- `db.pragma("table_info(x)")` → `pragmaAll(db, "table_info(x)")`
+- `db.pragma("foreign_key_check")` → `pragmaAll(db, "foreign_key_check")`
+
+- [ ] **Step 5: Replace transaction calls**
+
+Pattern A — immediate execution:
+```typescript
+// Before:
+db.transaction(() => { ... })();
+// After:
+transaction(db, () => { ... });
+```
+
+Pattern B — parameterized transaction:
+```typescript
+// Before:
+const tx = db.transaction((args: Type) => { ... });
+tx(args);
+// After:
+const tx = transactionFn(db, (args: Type) => { ... });
+tx(args);
+```
+
+Pattern C — inline transaction with return:
+```typescript
+// Before:
+const result = db.transaction(() => { ...; return value; })();
+// After:
+const result = transaction(db, () => { ...; return value; });
+```
+
+- [ ] **Step 6: Run type check**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npx tsc --noEmit 2>&1 | head -50`
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add lib/sqlite_writer.ts lib/queue/sqlite-adapter.ts lib/history-store.ts \
+  lib/participants-store.ts lib/workspaces-to-projects-migration.ts \
+  src/graph/store.ts lib/repo-knowledge.ts lib/knowledge-store.ts \
+  lib/thread-knowledge-runs.ts
+git commit -m "refactor: migrate transaction-heavy files from better-sqlite3 to node:sqlite"
+```
+
+---
+
+### Task 8: Migrate remaining files (agx-cloud)
+
+**Files:**
+- Modify: `agx-cloud/lib/agent-process-registry.ts`
+- Modify: `agx-cloud/lib/attachment-store.ts`
+- Modify: `agx-cloud/mcp/src/db.ts`
+- Modify: `agx-cloud/app/api/system/db-status/route.ts`
+- Modify: `agx-cloud/app/api/agents/[id]/messages/route.ts`
+- Modify: `agx-cloud/src/graph/schedule-runner.ts`
+- Modify: `agx-cloud/src/prompt-scheduler/store.ts`
+- Modify: `agx-cloud/lib/db-adapter.interface.ts`
+- Modify: `agx-cloud/scripts/bench-queue.ts`
+
+- [ ] **Step 1: Migrate each file**
+
+Apply the same patterns as Task 7:
+- Update imports from `better-sqlite3` to `node:sqlite`
+- Replace `Database.Database` with `DatabaseSync`
+- Replace `new Database(...)` with `new DatabaseSync(...)`
+- Replace pragma calls with compat helpers
+- Note: `{ readonly: true }` → `{ readOnly: true }` in messages route
+
+For `mcp/src/db.ts`, replace:
+```typescript
+const Database = (await import("better-sqlite3")).default;
+```
+With:
+```typescript
+const { DatabaseSync } = await import("node:sqlite");
+```
+And `new Database(...)` → `new DatabaseSync(...)`.
+
+For `db-adapter.interface.ts`, update the comment mentioning `better-sqlite3 Database` to `node:sqlite DatabaseSync`.
+
+- [ ] **Step 2: Run type check for root project**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npx tsc --noEmit 2>&1 | head -50`
+
+- [ ] **Step 3: Run type check for MCP subpackage**
+
+The root tsconfig excludes `mcp/`. Type-check it separately:
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud/mcp && npx tsc --noEmit 2>&1 | head -30`
+
+If mcp has no tsconfig, run: `cd /Users/mendrika/Projects/Agents/agx-cloud/mcp && npx tsc --noEmit src/db.ts --esModuleInterop --module nodenext --moduleResolution nodenext --target es2022 --skipLibCheck 2>&1 | head -30`
+
+- [ ] **Step 4: Verify bench-queue script compiles**
+
+The root tsconfig also excludes `scripts/`. Use a no-emit compile check — do NOT execute the script as it has top-level side effects (creates/deletes DB files, runs benchmarks):
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npx tsc --noEmit --esModuleInterop --module nodenext --moduleResolution nodenext --target es2022 --skipLibCheck scripts/bench-queue.ts 2>&1 | head -20`
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add lib/agent-process-registry.ts lib/attachment-store.ts mcp/src/db.ts \
+  app/api/system/db-status/route.ts "app/api/agents/[id]/messages/route.ts" \
+  src/graph/schedule-runner.ts src/prompt-scheduler/store.ts \
+  lib/db-adapter.interface.ts scripts/bench-queue.ts
+git commit -m "refactor: migrate remaining files from better-sqlite3 to node:sqlite"
+```
+
+---
+
+### Task 9: Migrate test files (agx-cloud)
+
+**Files:**
+- Modify: `agx-cloud/__tests__/prompt-scheduler/store.test.ts`
+- Modify: `agx-cloud/__tests__/prompt-scheduler/engine.test.ts`
+- Modify: `agx-cloud/__tests__/graph/store.test.ts`
+- Modify: `agx-cloud/test/adapters/sqlite.ts`
+
+- [ ] **Step 1: Update imports in all test files**
+
+Replace `import Database from 'better-sqlite3'` with `import { DatabaseSync } from 'node:sqlite'`.
+Replace `new Database(...)` with `new DatabaseSync(...)`.
+Replace pragma calls with compat helpers.
+
+- [ ] **Step 2: Run all tests**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npm test 2>&1 | tail -30`
+Expected: All tests pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add __tests__/ test/
+git commit -m "refactor: migrate test files from better-sqlite3 to node:sqlite"
+```
+
+---
+
+### Task 10: Update error UI components (agx-cloud)
+
+**Files:**
+- Modify: `agx-cloud/components/errors/StartupGuard.tsx`
+- Modify: `agx-cloud/components/errors/StartupGuardWrapper.tsx`
+
+- [ ] **Step 1: Read both files and update any `better-sqlite3` references**
+
+Replace any user-facing text mentioning `better-sqlite3` or `npm rebuild better-sqlite3` with Node.js version guidance (e.g., "Ensure Node.js >= 22.16 is installed").
+
+- [ ] **Step 2: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add components/errors/
+git commit -m "refactor: update error UI to reference node:sqlite instead of better-sqlite3"
+```
+
+---
+
+### Task 11: Clean up build config and dependencies (agx-cloud + MCP)
+
+**Files:**
+- Modify: `agx-cloud/next.config.ts`
+- Delete: `agx-cloud/scripts/fix-turbopack-externals.mjs`
+- Modify: `agx-cloud/package.json`
+- Modify: `agx-cloud/mcp/package.json`
+
+- [ ] **Step 1: Remove `serverExternalPackages` from next.config.ts**
+
+Remove the line:
+```typescript
+serverExternalPackages: ["better-sqlite3"],
+```
+
+- [ ] **Step 2: Remove the build script from package.json**
+
+Change:
+```json
+"build": "next build && node scripts/fix-turbopack-externals.mjs",
+```
+To:
+```json
+"build": "next build",
+```
+
+- [ ] **Step 3: Delete `scripts/fix-turbopack-externals.mjs`**
+
+Run: `rm /Users/mendrika/Projects/Agents/agx-cloud/scripts/fix-turbopack-externals.mjs`
+
+- [ ] **Step 4: Remove dependencies from package.json**
+
+Remove from `dependencies`:
+```
+"better-sqlite3": "12.6.2",
+```
+
+Remove from `devDependencies`:
+```
+"@types/better-sqlite3": "^7.6.12",
+```
+
+- [ ] **Step 5: Remove better-sqlite3 from MCP package**
+
+Remove from `mcp/package.json` dependencies:
+```
+"better-sqlite3": "12.6.2",
+```
+
+- [ ] **Step 6: Run `npm install` in both root and mcp to update lockfiles**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npm install && cd mcp && npm install`
+
+- [ ] **Step 7: Build test**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npm run build 2>&1 | tail -20`
+Expected: Build succeeds without better-sqlite3 workarounds.
+
+- [ ] **Step 8: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud
+git add next.config.ts package.json package-lock.json mcp/package.json mcp/package-lock.json
+git rm scripts/fix-turbopack-externals.mjs
+git commit -m "chore: remove better-sqlite3 dependency and build workarounds from agx-cloud and MCP"
+```
+
+---
+
+### Task 12: Migrate agx CLI
+
+**Files:**
+- Modify: `agx/lib/storage/db.js`
+- Modify: `agx/lib/cli/onboarding.js`
+- Modify: `agx/package.json`
+- Modify: `agx/scripts/postinstall.js`
+
+- [ ] **Step 1: Migrate `lib/storage/db.js`**
+
+Replace:
+```javascript
+const Database = require('better-sqlite3');
+```
+With:
+```javascript
+const { DatabaseSync } = require('node:sqlite');
+```
+
+Replace `new Database(dbPath())` with `new DatabaseSync(dbPath())`.
+
+Replace pragma calls:
+```javascript
+// Before:
+_db.pragma('journal_mode = WAL');
+_db.pragma('foreign_keys = ON');
+// After:
+_db.exec('PRAGMA journal_mode = WAL');
+_db.exec('PRAGMA foreign_keys = ON');
+```
+
+Replace the transaction in `runMigrations`:
+```javascript
+// Before:
+db.transaction(() => {
+    db.exec(migration.sql);
+    db.prepare('INSERT INTO _migrations ...').run(...);
+})();
+// After:
+db.exec('BEGIN');
+try {
+    db.exec(migration.sql);
+    db.prepare('INSERT INTO _migrations ...').run(...);
+    db.exec('COMMIT');
+} catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+}
+```
+
+- [ ] **Step 2: Migrate `lib/cli/onboarding.js`**
+
+Replace:
+```javascript
+const Database = require('better-sqlite3');
+const db = new Database(dbPath);
+db.pragma('journal_mode = WAL');
+```
+With:
+```javascript
+const { DatabaseSync } = require('node:sqlite');
+const db = new DatabaseSync(dbPath);
+db.exec('PRAGMA journal_mode = WAL');
+```
+
+- [ ] **Step 3: Remove better-sqlite3 from package.json**
+
+Remove from `dependencies`:
+```
+"better-sqlite3": "^12.6.2",
+```
+
+- [ ] **Step 4: Clean up postinstall.js**
+
+Remove the entire `try` block (lines 22-87) that copies the better-sqlite3 native addon and runs fix-turbopack-externals. Keep the cron/auto-update logic.
+
+- [ ] **Step 5: Verify engines field in package.json**
+
+Confirm the `engines` field already reads `"node": ">=22.16.0"` from Task 2. If not, set it now.
+
+- [ ] **Step 6: Run tests**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx && npm test 2>&1 | tail -20`
+Expected: All tests pass.
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx
+git add lib/storage/db.js lib/cli/onboarding.js package.json scripts/postinstall.js
+git commit -m "refactor: migrate agx CLI from better-sqlite3 to node:sqlite"
+```
+
+---
+
+### Task 13: Final verification
+
+- [ ] **Step 1: Verify no remaining better-sqlite3 references in agx-cloud**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && grep -r "better-sqlite3" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.mjs" -l`
+Expected: No results (or only CHANGELOG/docs).
+
+- [ ] **Step 2: Verify no remaining better-sqlite3 references in agx**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx && grep -r "better-sqlite3" --include="*.js" --include="*.json" -l`
+Expected: Only `package-lock.json` (if not cleaned) or no results.
+
+- [ ] **Step 3: Run agx-cloud full test suite**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npm test 2>&1 | tail -30`
+Expected: All tests pass.
+
+- [ ] **Step 4: Run agx-cloud build**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && npm run build 2>&1 | tail -20`
+Expected: Build succeeds.
+
+- [ ] **Step 5: Run agx full test suite**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx && npm test 2>&1 | tail -30`
+Expected: All tests pass.
+
+- [ ] **Step 6: Smoke test — start agx-cloud dev server**
+
+Run: `cd /Users/mendrika/Projects/Agents/agx-cloud && timeout 10 npm run dev 2>&1 || true`
+Expected: Server starts without better-sqlite3 errors.