pi-hermes-memory 0.8.1 → 0.9.0

package/README.md

@@ -122,6 +122,23 @@ Or test locally without installing:
 pi -e /path/to/pi-hermes-memory/src/index.ts
 ```
 
+### Homebrew / Node ABI mismatches
+
+`better-sqlite3` is a native addon. If Pi is installed via Homebrew and the extension was compiled for a different Node ABI, session search may warn:
+
+```text
+was compiled against a different Node.js version using NODE_MODULE_VERSION ...
+```
+
+The extension attempts one automatic `npm rebuild better-sqlite3` against the Node that is running Pi. If that still fails:
+
+```bash
+cd ~/.pi/agent/npm/node_modules/better-sqlite3
+npm rebuild better-sqlite3
+```
+
+Or install Pi with npm so the host runtime and extension install share one Node toolchain.
+
 ## Two-Tier Memory Architecture
 
 The extension stores memory at two levels:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "🧠 Persistent memory + 🔍 session search + 🛡️ secret scanning for Pi. Token-aware policy-only memory by default, SQLite FTS5 search, auto-consolidation, procedural skills. 693 tests. Ported from Hermes agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/constants.ts

@@ -70,7 +70,7 @@ If memory conflicts with current evidence, prefer current evidence and mention t
 Procedural skills:
 - Use the skill_manage tool during normal work when a task reveals a reusable how-to workflow, or when the user asks you to remember how to do something later.
 - Always pass scope explicitly on create: scope="global" for portable procedures, scope="project" for workflows tied to this repo's paths, scripts, architecture, deploy steps, or conventions.
-- Prefer structured fields for create/update: when_to_use, procedure_steps, pitfalls, verification_steps. Use patch to improve a specific section of an existing skill, update for a full rewrite, and view to inspect existing skills before changing them.
+- Prefer structured fields for create/update/patch: when_to_use, procedure_steps, pitfalls, verification_steps. Use patch with the matching structured field for one section, update for a full rewrite, and view before changing an existing skill.
 - Do not create skills for one-off task state, generic summaries, or overly file-specific notes that will create noisy future matches.
 
 Do not use memory_search for generic questions, one-off examples, or explanations where durable memory would not help.
@@ -92,7 +92,7 @@ Memory write targets: user for preferences/profile; memory for global notes and
 
 memory_search filters: target searches user/global/failure memories; project filters project-scoped memories; category filters categorized failure/lesson memories only.
 
-Use the skill_manage tool during normal work for reusable procedures. On create, scope is required: global for transferable workflows, project for repo-specific ones. Prefer structured fields for create/update, patch for focused changes, and update for full rewrites. Skip one-off or overly narrow skills.
+Use the skill_manage tool during normal work for reusable procedures. On create, scope is required: global for transferable workflows, project for repo-specific ones. Prefer structured fields for create/update/patch, patch for one section, and update for full rewrites. Skip one-off or overly narrow skills.
 
 Use category only for categorized failure/lesson searches. Do not use memory_search for generic questions, one-off examples, or explanations where durable memory would not help.
 
@@ -312,23 +312,24 @@ WHEN TO CREATE A SKILL:
 - When the user teaches you a specific workflow or procedure
 
 SCOPE:
-- 'global': transferable procedures that can be reused across repositories
-- 'project': procedures tied to this repo's paths, scripts, architecture, deploy flow, or conventions
+- 'global': transferable procedures that can be reused across repositories. Written to Pi's own global skills root, ~/.pi/agent/skills/<slug>/SKILL.md — the same directory Pi loads user skills from, so a name used there is already taken.
+- 'project': procedures tied to this repo's paths, scripts, architecture, deploy flow, or conventions. Written to ~/.pi/agent/projects-memory/<project>/skills/<slug>/SKILL.md.
 
-WHEN TO UPDATE A SKILL (use 'patch'):
-- You discover a better approach for an existing skill
-- A pitfall or edge case not covered by the skill
-- A step in the procedure changed
+WHEN TO UPDATE A SKILL:
+- Prefer 'patch' for one section when you can pass structured fields
+- Prefer 'update' for multi-section rewrites or when patch formatting would be unstable
+- Use patch when you discover a better approach, pitfall, or changed step in one section
 
 SKILL FORMAT:
 - name: short, descriptive (e.g., "debug-typescript-errors")
 - description: one-line summary of when to use it
 - body: structured with sections — ## When to Use, ## Procedure, ## Pitfalls, ## Verification
-- Prefer structured create/update fields over raw markdown when possible:
+- Prefer structured fields over raw markdown when possible:
   - when_to_use: trigger conditions and boundaries
   - procedure_steps: ordered concrete steps
   - pitfalls: caveats or failure modes
   - verification_steps: checks that prove success
+- For patch, pass section plus the matching structured field (section="Procedure" + procedure_steps, etc.). Do not pass JSON array/object strings as content.
 
 ONE-SHOT EXAMPLE:
 {

package/src/extension-root-migration.ts

@@ -2,10 +2,115 @@ import fs from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
-import Database from "better-sqlite3";
 import { AtomicLockCoordinator, type AtomicLockLease } from "./store/atomic-lock-coordinator.js";
 import { canonicalStoragePathSync } from "./store/canonical-storage-path.js";
+import { createRequire } from "node:module";
+import { isBunRuntime, loadBetterSqlite3 } from "./store/sqlite-native.js";
+
+type MigrationDatabase = {
+  exec: (sql: string) => void;
+  prepare: (sql: string) => { get: (...args: unknown[]) => unknown; run: (...args: unknown[]) => unknown };
+  close: () => void;
+  pragma: (query: string, options?: { simple?: boolean }) => unknown;
+  backup: (
+    destination: string,
+    options?: { progress?: () => void },
+  ) => Promise<void> | void;
+};
+
+type MigrationDatabaseCtor = new (
+  dbPath: string,
+  options?: { readonly?: boolean; fileMustExist?: boolean; timeout?: number },
+) => MigrationDatabase;
+
+type BunDatabaseInstance = {
+  exec: (sql: string) => void;
+  prepare: (sql: string) => { get: (...args: unknown[]) => unknown; run: (...args: unknown[]) => unknown };
+  close: () => void;
+};
 
+/**
+ * bun:sqlite shim covering the slice of the better-sqlite3 API this migration
+ * uses. Compiled Pi cannot resolve better-sqlite3 at all, so under Bun this is
+ * the only way the legacy-root migration can touch sessions.db.
+ */
+function createBunMigrationDatabaseCtor(): MigrationDatabaseCtor {
+  const require = createRequire(import.meta.url);
+  const bunSqlite = require("bun:sqlite") as {
+    Database: new (
+      dbPath: string,
+      options?: { readonly?: boolean; readwrite?: boolean; create?: boolean },
+    ) => BunDatabaseInstance;
+  };
+
+  return class BunMigrationDatabase implements MigrationDatabase {
+    private readonly db: BunDatabaseInstance;
+
+    constructor(
+      dbPath: string,
+      options: { readonly?: boolean; fileMustExist?: boolean; timeout?: number } = {},
+    ) {
+      const readonly = options.readonly === true;
+      this.db = new bunSqlite.Database(dbPath, {
+        readonly,
+        readwrite: !readonly,
+        create: !readonly && options.fileMustExist !== true,
+      });
+      if (typeof options.timeout === "number") {
+        this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.trunc(options.timeout))}`);
+      }
+    }
+
+    exec(sql: string): void {
+      this.db.exec(sql);
+    }
+
+    prepare(sql: string): { get: (...args: unknown[]) => unknown; run: (...args: unknown[]) => unknown } {
+      return this.db.prepare(sql);
+    }
+
+    close(): void {
+      this.db.close();
+    }
+
+    pragma(query: string, options?: { simple?: boolean }): unknown {
+      if (query.includes("=")) {
+        this.db.exec(`PRAGMA ${query}`);
+        return undefined;
+      }
+      const row = this.db.prepare(`PRAGMA ${query}`).get();
+      if (typeof row !== "object" || row === null) return options?.simple ? row : [];
+      return options?.simple ? Object.values(row)[0] : [row];
+    }
+
+    /**
+     * bun:sqlite exposes no online backup API. `VACUUM INTO` writes an
+     * equivalent consistent snapshot under a read transaction, but has no
+     * incremental callback, so the heartbeat only fires either side of it.
+     */
+    async backup(destination: string, options?: { progress?: () => void }): Promise<void> {
+      options?.progress?.();
+      this.db.prepare("VACUUM INTO ?").run(destination);
+      options?.progress?.();
+    }
+  };
+}
+
+let cachedDatabaseCtor: MigrationDatabaseCtor | null = null;
+
+/**
+ * Resolved on first use, never at import time: this module is pulled in by
+ * src/index.ts at extension load, and a module-scope native load turns any
+ * SQLite resolve/ABI failure into "Failed to load extension" (issue #117).
+ */
+function getDatabaseCtor(): MigrationDatabaseCtor {
+  if (!cachedDatabaseCtor) {
+    cachedDatabaseCtor = isBunRuntime()
+      ? createBunMigrationDatabaseCtor()
+      : (loadBetterSqlite3() as MigrationDatabaseCtor);
+  }
+  return cachedDatabaseCtor;
+}
 const DATABASE_FILES = ["sessions.db", "sessions.db-wal", "sessions.db-shm"] as const;
 const DATABASE_MIGRATION_PENDING_FILE = ".sessions-db-migration-pending";
 
@@ -85,6 +190,7 @@ async function stageDatabaseSnapshot(
   staged: string,
   onProgress?: () => void,
 ): Promise<void> {
+  const Database = getDatabaseCtor();
   const sourceDb = new Database(source, { readonly: true, fileMustExist: true });
   try {
     await sourceDb.backup(staged, {
@@ -120,7 +226,7 @@ function isDatabaseCorruption(error: unknown): boolean {
 }
 
 async function acquireMigrationLease(legacyRoot: string, targetRoot: string): Promise<AtomicLockLease> {
-  const coordinator = new AtomicLockCoordinator(path.join(targetRoot, ".pi-hermes-locks.sqlite"));
+  const coordinator = AtomicLockCoordinator.shared(path.join(targetRoot, ".pi-hermes-locks.sqlite"));
   const sourceIdentity = canonicalStoragePathSync(path.join(legacyRoot, "sessions.db"));
   const targetIdentity = canonicalStoragePathSync(path.join(targetRoot, "sessions.db"));
   const key = `extension-root-migration:${sourceIdentity}:${targetIdentity}`;
@@ -373,7 +479,7 @@ async function migrateDatabaseGeneration(
     const staged = path.join(stagingDir, "sessions.db");
     const sourceState = await fs.lstat(source);
     try {
-      writeLock = new Database(source, { fileMustExist: true, timeout: 0 });
+      writeLock = new (getDatabaseCtor())(source, { fileMustExist: true, timeout: 0 });
       writeLock.pragma("busy_timeout = 0");
       writeLock.exec("BEGIN IMMEDIATE");
     } catch (error) {
@@ -431,7 +537,15 @@ async function migrateDatabaseGeneration(
       published.set(target, await fileIdentity(target));
     }
 
-    if (writeLock) writeLock.exec("COMMIT");
+    if (writeLock) {
+      // Every generation file has already been moved out of legacyRoot, so this
+      // transaction can no longer guard anything and its database no longer
+      // exists at this path. bun:sqlite reports SQLITE_IOERR here where
+      // better-sqlite3 succeeds; either way a failed cleanup COMMIT must not
+      // roll back an otherwise completed migration.
+      // The connection is closed in `finally` either way.
+      try { writeLock.exec("COMMIT"); } catch {}
+    }
     result.moved += generationNames.length;
   } catch (error) {
     for (const [target, identity] of [...published.entries()].reverse()) {

package/src/handlers/auto-consolidate.ts

@@ -61,7 +61,7 @@ async function tryAcquireConsolidationLock(
   const storageIdentity = await store.getStorageIdentity(target);
   const root = consolidationLockRoot();
   await fs.mkdir(root, { recursive: true });
-  const coordinator = new AtomicLockCoordinator(path.join(root, "locks.sqlite"));
+  const coordinator = AtomicLockCoordinator.shared(path.join(root, "locks.sqlite"));
   const lease = coordinator.tryAcquire(
     consolidationLockKey(target, toolTarget, storageIdentity),
     { staleMs: Math.max(timeoutMs, 0) + CONSOLIDATION_LOCK_STALE_GRACE_MS },

package/src/index.ts

@@ -63,10 +63,10 @@ export function resolveProjectSkillDiscovery(
   const detected = detectProjectSkills(projectsMemoryDir, cwd);
   skillStore.setProjectContext(detected.name, detected.skillsDir);
 
-  const skillPaths = [skillStore.getGlobalSkillsDir()];
-  if (detected.skillsDir) skillPaths.push(detected.skillsDir);
-
-  return { skillPaths };
+  // Global skills live in Pi's own `~/.pi/agent/skills/`, which Pi already
+  // auto-discovers at higher precedence than anything contributed here. Only
+  // the project skills directory needs registering (#125, #126).
+  return { skillPaths: detected.skillsDir ? [detected.skillsDir] : [] };
 }
 
 export function registerProjectSkillDiscoveryHandler(
@@ -102,12 +102,13 @@ export default function (pi: ExtensionAPI) {
   const project = detectProject(config.projectsMemoryDir);
   const projectName = project.name ?? "";
   const skillStore = new SkillStore({
-    globalSkillsDir: path.join(globalDir, "skills"),
+    globalSkillsDir: path.join(agentRoot, "skills"),
     projectSkillsDir: project.memoryDir ? path.join(project.memoryDir, "skills") : null,
     projectName: project.name,
     legacySkillsDir: path.join(legacyGlobalDir, "skills"),
-    legacyPiGlobalSkillsDir: path.join(agentRoot, "skills"),
+    legacyExtensionSkillsDir: path.join(globalDir, "skills"),
     migrationSentinelPath: path.join(globalDir, ".skills-migrated-to-extension-storage"),
+    extensionSkillsMigrationSentinelPath: path.join(globalDir, ".skills-migrated-to-pi-global"),
   });
   const dbManager = new DatabaseManager(globalDir);
   let databaseMigrationPending = shouldMigrateExtensionRoot

package/src/project.ts

@@ -3,6 +3,7 @@
  * represents a project and resolves its name.
  */
 
+import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { resolveProjectsRoot } from "./paths.js";
@@ -19,11 +20,80 @@ export interface ProjectSkillInfo extends ProjectInfo {
   skillsDir: string | null;
 }
 
+/**
+ * Resolve the repository root shared by every linked worktree of `dir`'s repo.
+ *
+ * Mirrors what `git rev-parse --git-common-dir` reports, without spawning git:
+ * a linked worktree's `.git` is a file pointing at
+ * `<main>/.git/worktrees/<name>`, and that directory carries a `commondir`
+ * file pointing back at the shared `<main>/.git`. Returns null outside a
+ * repository, or for a bare/detached layout with no obvious working root.
+ */
+function findGitRepoRoot(dir: string): string | null {
+  let current = path.resolve(dir);
+
+  while (true) {
+    const dotGit = path.join(current, ".git");
+    let stat: fs.Stats | undefined;
+    try {
+      stat = fs.statSync(dotGit);
+    } catch {
+      stat = undefined;
+    }
+
+    if (stat?.isDirectory()) return current;
+
+    if (stat?.isFile()) {
+      const commonDir = resolveWorktreeCommonDir(current, dotGit);
+      if (!commonDir) return current;
+      return path.basename(commonDir) === ".git" ? path.dirname(commonDir) : commonDir;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function resolveWorktreeCommonDir(worktreeRoot: string, dotGitFile: string): string | null {
+  let pointer: string;
+  try {
+    pointer = fs.readFileSync(dotGitFile, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const match = /^gitdir:\s*(.+)$/m.exec(pointer);
+  if (!match) return null;
+
+  const gitDir = path.resolve(worktreeRoot, match[1].trim());
+  try {
+    const commonDir = fs.readFileSync(path.join(gitDir, "commondir"), "utf-8").trim();
+    if (commonDir) return path.resolve(gitDir, commonDir);
+  } catch {
+    // Not a linked worktree, or an older layout without `commondir`.
+  }
+
+  // `<main>/.git/worktrees/<name>` — two levels up is the shared git dir.
+  const parent = path.dirname(gitDir);
+  return path.basename(parent) === "worktrees" ? path.dirname(parent) : null;
+}
+
+const repoRootCache = new Map<string, string | null>();
+
 /**
  * Detect project from the current working directory.
  *
- * A "project" is any directory that is not the user's home directory.
- * The project name is the directory's basename.
+ * A "project" is any directory that is not the user's home directory. Inside a
+ * Git repository the project name is the *repository* root's basename, so every
+ * linked worktree shares one identity instead of stranding its memory and
+ * skills under the worktree directory name (#120). Outside Git it stays the
+ * working directory's basename.
+ *
+ * An existing `projects-memory/<cwd-basename>/` directory still wins over a
+ * newly derived repository name, so upgrading never orphans memory that was
+ * written under the old cwd-basename identity.
+ *
  * Project-scoped memory is stored at ~/.pi/agent/<projectsMemoryDir>/<projectName>/.
  */
 export function detectProject(projectsMemoryDir = "projects-memory", cwd?: string): ProjectInfo {
@@ -38,17 +108,46 @@ export function detectProject(projectsMemoryDir = "projects-memory", cwd?: strin
     return { name: null, memoryDir: null };
   }
 
-  const name = path.basename(resolved);
-  if (!name || name === "." || name === "..") {
+  const cwdName = path.basename(resolved);
+  if (!cwdName || cwdName === "." || cwdName === "..") {
     return { name: null, memoryDir: null };
   }
 
+  const projectsRoot = resolveProjectsRoot(projectsMemoryDir);
+  const name = resolveProjectName(resolved, resolvedHome, cwdName, projectsRoot);
+
   return {
     name,
-    memoryDir: path.join(resolveProjectsRoot(projectsMemoryDir), name),
+    memoryDir: path.join(projectsRoot, name),
   };
 }
 
+function resolveProjectName(
+  resolved: string,
+  resolvedHome: string,
+  cwdName: string,
+  projectsRoot: string,
+): string {
+  let repoRoot = repoRootCache.get(resolved);
+  if (repoRoot === undefined) {
+    repoRoot = findGitRepoRoot(resolved);
+    repoRootCache.set(resolved, repoRoot);
+  }
+
+  if (!repoRoot || repoRoot === resolved || repoRoot === resolvedHome) return cwdName;
+
+  const repoName = path.basename(repoRoot);
+  if (!repoName || repoName === cwdName) return cwdName;
+
+  // Migration bridge: a store already written under the old cwd-basename
+  // identity keeps working. Only fresh directories adopt the repository name.
+  if (!fs.existsSync(path.join(projectsRoot, repoName)) && fs.existsSync(path.join(projectsRoot, cwdName))) {
+    return cwdName;
+  }
+
+  return repoName;
+}
+
 export function detectProjectSkills(projectsMemoryDir = "projects-memory", cwd?: string): ProjectSkillInfo {
   const project = detectProject(projectsMemoryDir, cwd);
   return {

package/src/store/atomic-lock-coordinator.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
+import { isBunRuntime, loadBetterSqlite3 } from './sqlite-native.js';
 
 type StatementLike = {
   run: (...args: unknown[]) => unknown;
@@ -33,18 +34,25 @@ export interface AtomicLockCoordinatorOptions {
   probeIncarnation?: (pid: number) => string | null;
 }
 
-function loadDatabaseCtor(): DatabaseCtor {
-  const require = createRequire(import.meta.url);
-  if (typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined') {
-    const bunSqlite = require('bun:sqlite') as { Database: DatabaseCtor };
-    return bunSqlite.Database;
+let cachedDatabaseCtor: DatabaseCtor | null = null;
+
+/**
+ * Resolved on first use, never at import time — see the same note in db.ts.
+ * Compiled Pi cannot resolve better-sqlite3 at all, so Bun must take bun:sqlite.
+ */
+function getDatabaseCtor(): DatabaseCtor {
+  if (!cachedDatabaseCtor) {
+    const require = createRequire(import.meta.url);
+    if (isBunRuntime()) {
+      const bunSqlite = require('bun:sqlite') as { Database: DatabaseCtor };
+      cachedDatabaseCtor = bunSqlite.Database;
+    } else {
+      cachedDatabaseCtor = loadBetterSqlite3({ requireImpl: require }) as DatabaseCtor;
+    }
   }
-  const mod = require('better-sqlite3') as { default?: DatabaseCtor } | DatabaseCtor;
-  return (mod as { default?: DatabaseCtor }).default ?? (mod as DatabaseCtor);
+  return cachedDatabaseCtor;
 }
 
-const Database = loadDatabaseCtor();
-
 function processIsAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -86,11 +94,13 @@ function probeProcessIncarnation(pid: number): string | null {
 const currentProcessIncarnation = probeProcessIncarnation(process.pid);
 const RELEASE_ATTEMPTS = 3;
 const pendingReleases = new Map<string, () => void>();
+const sharedCoordinators = new Map<string, AtomicLockCoordinator>();
 
 export class AtomicLockCoordinator {
   private readonly pid: number;
   private readonly incarnation: string | null;
   private readonly probeIncarnation: (pid: number) => string | null;
+  private cachedDb: DatabaseLike | null = null;
 
   constructor(private readonly dbPath: string, options: AtomicLockCoordinatorOptions = {}) {
     this.pid = options.pid ?? process.pid;
@@ -108,10 +118,9 @@ export class AtomicLockCoordinator {
     const db = this.open();
     let acquired = false;
 
+    db.exec('BEGIN IMMEDIATE');
     try {
-      db.exec('BEGIN IMMEDIATE');
-      try {
-        const owner = db.prepare(`
+      const owner = db.prepare(`
           SELECT token, pid, incarnation, acquired_at
           FROM locks
           WHERE lock_key = ?
@@ -149,12 +158,16 @@ export class AtomicLockCoordinator {
         }
 
         db.exec('COMMIT');
-      } catch (error) {
-        try { db.exec('ROLLBACK'); } catch {}
-        throw error;
+    } catch (error) {
+      try {
+        db.exec('ROLLBACK');
+      } catch {
+        // The transaction is still open on a connection we are about to hand
+        // to the next caller, whose BEGIN IMMEDIATE would then fail forever.
+        // Drop the handle so open() rebuilds it.
+        this.discardCachedDb();
       }
-    } finally {
-      db.close();
+      throw error;
     }
 
     if (!acquired) return null;
@@ -176,12 +189,8 @@ export class AtomicLockCoordinator {
    */
   isCurrentOwner(key: string, token: string): boolean {
     const db = this.open();
-    try {
-      const row = db.prepare('SELECT token FROM locks WHERE lock_key = ?').get(key) as { token: string } | undefined;
-      return row?.token === token;
-    } finally {
-      db.close();
-    }
+    const row = db.prepare('SELECT token FROM locks WHERE lock_key = ?').get(key) as { token: string } | undefined;
+    return row?.token === token;
   }
 
   release(key: string, token: string): void {
@@ -199,11 +208,7 @@ export class AtomicLockCoordinator {
 
   private deleteOwnedLock(key: string, token: string): void {
     const db = this.open();
-    try {
-      db.prepare('DELETE FROM locks WHERE lock_key = ? AND token = ?').run(key, token);
-    } finally {
-      db.close();
-    }
+    db.prepare('DELETE FROM locks WHERE lock_key = ? AND token = ?').run(key, token);
   }
 
   private retryPendingReleases(key: string): void {
@@ -217,10 +222,19 @@ export class AtomicLockCoordinator {
     return `${path.resolve(this.dbPath)}\0${key}\0${token}`;
   }
 
+  private discardCachedDb(): void {
+    const db = this.cachedDb;
+    this.cachedDb = null;
+    if (db) {
+      try { db.close(); } catch {}
+    }
+  }
+
   private open(): DatabaseLike {
+    if (this.cachedDb) return this.cachedDb;
     fs.mkdirSync(path.dirname(this.dbPath), { recursive: true });
     const existed = fs.existsSync(this.dbPath);
-    const db = new Database(this.dbPath);
+    const db = new (getDatabaseCtor())(this.dbPath);
     try {
       db.exec(`
         PRAGMA busy_timeout = 5000;
@@ -243,10 +257,30 @@ export class AtomicLockCoordinator {
         }
       }
       if (!existed) fs.chmodSync(this.dbPath, 0o600);
+      this.cachedDb = db;
       return db;
     } catch (error) {
       db.close();
       throw error;
     }
   }
+
+  /**
+   * Process-wide coordinator for `dbPath`.
+   *
+   * Each instance now pins its SQLite connection for its own lifetime, so a
+   * caller that constructs a fresh coordinator per operation would leak one
+   * open WAL connection per call. Every default-options caller must share.
+   * The option-carrying constructor stays public for tests, which pass a
+   * synthetic pid/incarnation that a dbPath-keyed cache would silently ignore.
+   */
+  static shared(dbPath: string): AtomicLockCoordinator {
+    const key = path.resolve(dbPath);
+    let coordinator = sharedCoordinators.get(key);
+    if (!coordinator) {
+      coordinator = new AtomicLockCoordinator(dbPath);
+      sharedCoordinators.set(key, coordinator);
+    }
+    return coordinator;
+  }
 }