pi-hermes-memory 0.8.2 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "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

@@ -312,8 +312,8 @@ 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/agent/pi-hermes-memory/skills/<slug>/SKILL.md, this extension's own directory, kept separate from skills the user installed themselves. Pi also loads its own ~/.pi/agent/skills/ first, so a name already used there is rejected rather than silently shadowed.
+- '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:
 - Prefer 'patch' for one section when you can pass structured fields

package/src/extension-root-migration.ts

@@ -4,7 +4,8 @@ import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { AtomicLockCoordinator, type AtomicLockLease } from "./store/atomic-lock-coordinator.js";
 import { canonicalStoragePathSync } from "./store/canonical-storage-path.js";
-import { loadBetterSqlite3 } from "./store/sqlite-native.js";
+import { createRequire } from "node:module";
+import { isBunRuntime, loadBetterSqlite3 } from "./store/sqlite-native.js";
 
 type MigrationDatabase = {
   exec: (sql: string) => void;
@@ -22,7 +23,94 @@ type MigrationDatabaseCtor = new (
   options?: { readonly?: boolean; fileMustExist?: boolean; timeout?: number },
 ) => MigrationDatabase;
 
-const Database = loadBetterSqlite3() as MigrationDatabaseCtor;
+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";
 
@@ -102,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, {
@@ -137,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}`;
@@ -390,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) {
@@ -448,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,9 +63,12 @@ export function resolveProjectSkillDiscovery(
   const detected = detectProjectSkills(projectsMemoryDir, cwd);
   skillStore.setProjectContext(detected.name, detected.skillsDir);
 
+  // Pi auto-discovers its own `~/.pi/agent/skills/`, but this extension keeps
+  // its generated skills in a directory of its own so users can audit, wipe, or
+  // ignore them without touching skills they installed themselves (#126). Both
+  // of ours must therefore be contributed here.
   const skillPaths = [skillStore.getGlobalSkillsDir()];
   if (detected.skillsDir) skillPaths.push(detected.skillsDir);
-
   return { skillPaths };
 }
 
@@ -103,10 +106,10 @@ export default function (pi: ExtensionAPI) {
   const projectName = project.name ?? "";
   const skillStore = new SkillStore({
     globalSkillsDir: path.join(globalDir, "skills"),
+    piGlobalSkillsDir: 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"),
     migrationSentinelPath: path.join(globalDir, ".skills-migrated-to-extension-storage"),
   });
   const dbManager = new DatabaseManager(globalDir);

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,7 +3,7 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
-import { loadBetterSqlite3 } from './sqlite-native.js';
+import { isBunRuntime, loadBetterSqlite3 } from './sqlite-native.js';
 
 type StatementLike = {
   run: (...args: unknown[]) => unknown;
@@ -34,17 +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;
+    }
   }
-  return loadBetterSqlite3({ requireImpl: require }) 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;
+  }
 }

package/src/store/db.ts

@@ -4,7 +4,7 @@ import { createRequire } from 'node:module';
 import { SCHEMA_SQL } from './schema.js';
 import { AtomicLockCoordinator } from './atomic-lock-coordinator.js';
 import { canonicalStoragePathSync } from './canonical-storage-path.js';
-import { loadBetterSqlite3 } from './sqlite-native.js';
+import { isBunRuntime, loadBetterSqlite3 } from './sqlite-native.js';
 
 type StatementLike = {
   run: (...args: any[]) => any;
@@ -120,19 +120,23 @@ function createBunCompatDatabaseCtor(require: NodeRequire): DatabaseCtor {
   };
 }
 
-function loadDatabaseCtor(): DatabaseCtor {
-  const require = createRequire(import.meta.url);
-  const isBunRuntime = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined';
-
-  if (isBunRuntime) {
-    return createBunCompatDatabaseCtor(require);
+let cachedDatabaseCtor: DatabaseCtor | null = null;
+
+/**
+ * Resolved on first use, never at import time. A module-scope native load turns
+ * any SQLite resolve/ABI failure into "Failed to load extension", which hides
+ * the actionable rebuild message and bricks the whole extension (issue #117).
+ */
+function getDatabaseCtor(): DatabaseCtor {
+  if (!cachedDatabaseCtor) {
+    const require = createRequire(import.meta.url);
+    cachedDatabaseCtor = isBunRuntime()
+      ? createBunCompatDatabaseCtor(require)
+      : (loadBetterSqlite3({ requireImpl: require }) as DatabaseCtor);
   }
-
-  return loadBetterSqlite3({ requireImpl: require }) as DatabaseCtor;
+  return cachedDatabaseCtor;
 }
 
-const Database = loadDatabaseCtor();
-
 export class DatabaseManager {
   private db: DatabaseLike | null = null;
   private readonly displayDbPath: string;
@@ -270,7 +274,7 @@ export class DatabaseManager {
 
   private openUnchecked(): DatabaseLike {
     const existed = this.hasExistingMainDatabaseFile();
-    const db = new Database(this.dbPath);
+    const db = new (getDatabaseCtor())(this.dbPath);
     let ok = false;
 
     try {
@@ -361,7 +365,7 @@ export class DatabaseManager {
   }
 
   private recoverDatabaseFile(cause: unknown, verify: () => void): DatabaseRecoveryResult {
-    const coordinator = new AtomicLockCoordinator(path.join(path.dirname(this.dbPath), '.pi-hermes-locks.sqlite'));
+    const coordinator = AtomicLockCoordinator.shared(path.join(path.dirname(this.dbPath), '.pi-hermes-locks.sqlite'));
     const lockKey = `recovery:${this.dbPath}`;
     const deadline = Date.now() + Math.max(0, this.recoveryOptions.recoveryLockWaitMs);
 
@@ -434,7 +438,7 @@ export class DatabaseManager {
     if (!this.hasExistingMainDatabaseFile()) return false;
     let db: DatabaseLike | null = null;
     try {
-      db = new Database(this.dbPath);
+      db = new (getDatabaseCtor())(this.dbPath);
       this.assertIntegrityOk(db, 'quick_check', 'while joining corruption recovery');
       return true;
     } catch {
@@ -546,6 +550,7 @@ export class DatabaseManager {
     let rebuildOk = false;
 
     try {
+      const Database = getDatabaseCtor();
       source = new Database(this.dbPath);
       target = new Database(tempPath);
       target.exec('PRAGMA journal_mode = DELETE');

package/src/store/fts-query.ts

@@ -63,6 +63,37 @@ export function buildFallbackFts5Query(query: string): string | null {
     .join(' OR ');
 }
 
+function quoteTerms(terms: string[], separator: string): string {
+  return terms.map((term) => `"${term.replace(/"/g, '""')}"`).join(separator);
+}
+
+/**
+ * Normalize a query as natural language even when it contains uppercase
+ * operator words. Queries like "DO NOT USE FIND /" are passed through as raw
+ * FTS5 syntax by normalizeFts5Query; when that raw form fails to parse, this
+ * produces the quoted-term form to retry with.
+ */
+export function normalizeNaturalLanguageFts5Query(query: string): string {
+  const trimmed = query.trim();
+  if (trimmed.length === 0) return '';
+
+  return quoteTerms(collectNaturalLanguageTerms(trimmed), ' ');
+}
+
+/**
+ * Build the broader OR fallback for the same recovery path, ignoring
+ * operator detection.
+ */
+export function buildNaturalLanguageFallbackQuery(query: string): string | null {
+  const trimmed = query.trim();
+  if (trimmed.length === 0) return null;
+
+  const terms = collectNaturalLanguageTerms(trimmed);
+  if (terms.length <= 1) return null;
+
+  return quoteTerms(terms, ' OR ');
+}
+
 export function isFts5QueryError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
   const msg = err.message.toLowerCase();

package/src/store/markdown-mutation-lock.ts

@@ -12,7 +12,7 @@ export async function canonicalMarkdownIdentity(filePath: string): Promise<strin
 export async function acquireMarkdownMutationLock(filePath: string): Promise<AtomicLockLease> {
   const identity = await canonicalMarkdownIdentity(filePath);
   const coordinatorDir = path.dirname(path.dirname(identity));
-  const coordinator = new AtomicLockCoordinator(path.join(coordinatorDir, ".pi-hermes-locks.sqlite"));
+  const coordinator = AtomicLockCoordinator.shared(path.join(coordinatorDir, ".pi-hermes-locks.sqlite"));
   const lockKey = `mutation:${identity}`;
   const deadline = Date.now() + MUTATION_WAIT_MS;
   let lease = coordinator.tryAcquire(lockKey, { staleMs: MUTATION_STALE_MS });

package/src/store/session-search.ts

@@ -1,5 +1,12 @@
 import { DatabaseManager } from './db.js';
-import { buildFallbackFts5Query, hasExplicitFts5Operator, isFts5QueryError, normalizeFts5Query } from './fts-query.js';
+import {
+  buildFallbackFts5Query,
+  buildNaturalLanguageFallbackQuery,
+  hasExplicitFts5Operator,
+  isFts5QueryError,
+  normalizeFts5Query,
+  normalizeNaturalLanguageFts5Query,
+} from './fts-query.js';
 
 /**
  * Search result from session history.
@@ -93,6 +100,8 @@ export function searchSessions(
   const db = dbManager.getDb();
   const { limit = 10, project, role, since } = options;
 
+  let ftsParseError = false;
+
   const executeSearch = (match: SearchMatch): SessionSearchResult[] => {
     const conditions: string[] = [];
     const params: unknown[] = [];
@@ -160,6 +169,7 @@ export function searchSessions(
       return mapRows(rows);
     } catch (err) {
       if (match.type === 'fts' && isFts5QueryError(err)) {
+        ftsParseError = true;
         return [];
       }
       throw err;
@@ -178,7 +188,28 @@ export function searchSessions(
 
   const explicitOperatorQuery = hasExplicitFts5Operator(query);
   if (explicitOperatorQuery) {
-    return exactResults;
+    // Same recovery as searchMemories: only when the raw operator query fails
+    // to parse do we retry it as natural language; valid operator queries that
+    // match nothing keep their exact semantics.
+    if (!ftsParseError) {
+      return exactResults;
+    }
+    const nlQuery = normalizeNaturalLanguageFts5Query(query);
+    if (nlQuery.length > 0 && nlQuery !== normalizedQuery) {
+      const nlResults = executeSearch({ type: 'fts', query: nlQuery });
+      if (nlResults.length > 0) {
+        return nlResults;
+      }
+      const nlFallback = buildNaturalLanguageFallbackQuery(query);
+      if (nlFallback && nlFallback !== nlQuery) {
+        const nlFallbackResults = executeSearch({ type: 'fts', query: nlFallback });
+        if (nlFallbackResults.length > 0) {
+          return nlFallbackResults;
+        }
+      }
+    }
+    const likeTerms = collectLikeTerms(query);
+    return executeSearch({ type: 'like', terms: likeTerms });
   }
 
   const fallbackQuery = buildFallbackFts5Query(query);

package/src/store/skill-store.ts

@@ -23,11 +23,13 @@ import type { SkillDocument, SkillIndex, SkillResult, SkillScope } from "../type
 import { AGENT_ROOT } from "../paths.js";
 
 interface SkillStoreOptions {
+  /** Where this extension writes global skills. Never Pi's own root. */
   globalSkillsDir?: string;
+  /** Pi's global skills root, consulted read-only to refuse shadowed writes. */
+  piGlobalSkillsDir?: string;
   projectSkillsDir?: string | null;
   projectName?: string | null;
   legacySkillsDir?: string;
-  legacyPiGlobalSkillsDir?: string;
   migrationSentinelPath?: string;
 }
 
@@ -153,19 +155,19 @@ export function normalizeSkillPatchContent(
 
 export class SkillStore {
   private globalSkillsDir: string;
+  private piGlobalSkillsDir: string;
   private projectSkillsDir: string | null;
   private projectName: string | null;
   private legacySkillsDir: string;
-  private legacyPiGlobalSkillsDir: string;
   private migrationSentinelPath: string;
 
   constructor(options: SkillStoreOptions = {}) {
     const agentRoot = AGENT_ROOT;
-    this.globalSkillsDir = options.globalSkillsDir ?? path.join(agentRoot, "skills");
+    this.globalSkillsDir = options.globalSkillsDir ?? path.join(agentRoot, "pi-hermes-memory", "skills");
+    this.piGlobalSkillsDir = options.piGlobalSkillsDir ?? path.join(agentRoot, "skills");
     this.projectSkillsDir = options.projectSkillsDir ?? null;
     this.projectName = options.projectName ?? null;
     this.legacySkillsDir = options.legacySkillsDir ?? path.join(agentRoot, "memory", "skills");
-    this.legacyPiGlobalSkillsDir = options.legacyPiGlobalSkillsDir ?? path.join(agentRoot, "skills");
     this.migrationSentinelPath = options.migrationSentinelPath
       ?? path.join(agentRoot, "pi-hermes-memory", ".skills-migrated-to-extension-storage");
   }
@@ -174,6 +176,15 @@ export class SkillStore {
     return this.globalSkillsDir;
   }
 
+  /**
+   * Pi's own global skills root. Read-only from here: we never create, patch,
+   * or delete inside it. It is consulted solely to refuse writes that Pi would
+   * silently shadow (see `findShadowingPiGlobalSkill`).
+   */
+  getPiGlobalSkillsDir(): string {
+    return this.piGlobalSkillsDir;
+  }
+
   getProjectSkillsDir(): string | null {
     return this.projectSkillsDir;
   }
@@ -205,11 +216,13 @@ export class SkillStore {
 
     await fs.mkdir(path.dirname(this.migrationSentinelPath), { recursive: true });
 
+    // Only this migration's own warnings may hold back its sentinel — a
+    // permanently shadowed skill reported above must not make it retry forever.
+    const warningsBefore = result.warnings.length;
     try {
       await this.migrateLegacyMarkdownSkills(result);
-      await this.migrateLegacyPiGlobalSkillDirs(result);
     } finally {
-      if (result.warnings.length === 0) {
+      if (result.warnings.length === warningsBefore) {
         await fs.writeFile(this.migrationSentinelPath, `${new Date().toISOString()}\n`, "utf-8");
       }
     }
@@ -307,45 +320,23 @@ export class SkillStore {
     }
   }
 
-  private async migrateLegacyPiGlobalSkillDirs(result: LegacySkillMigrationResult): Promise<void> {
-    if (path.resolve(this.legacyPiGlobalSkillsDir) === path.resolve(this.globalSkillsDir)) return;
-    if (!await exists(this.legacyPiGlobalSkillsDir)) return;
-
-    const entries = await fs.readdir(this.legacyPiGlobalSkillsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-
-      const sourceDir = path.join(this.legacyPiGlobalSkillsDir, entry.name);
-      const sourceSkill = path.join(sourceDir, "SKILL.md");
-      if (!await exists(sourceSkill)) continue;
-
-      const targetDir = path.join(this.globalSkillsDir, entry.name);
-      const targetSkill = path.join(targetDir, "SKILL.md");
-      if (await exists(targetSkill)) {
-        result.skipped++;
-        continue;
-      }
-
-      try {
-        const raw = await fs.readFile(sourceSkill, "utf-8");
-        const parsed = parseFrontmatter(raw);
-        const hasExtensionManagedMeta = Boolean(parsed.meta.display_name)
-          && Boolean(parsed.meta.created)
-          && Boolean(parsed.meta.updated)
-          && /^\d+$/.test(parsed.meta.version ?? "");
-
-        if (!hasExtensionManagedMeta) {
-          result.skipped++;
-          continue;
-        }
-
-        await fs.mkdir(path.dirname(targetDir), { recursive: true });
-        await fs.rename(sourceDir, targetDir);
-        result.migrated++;
-      } catch (error) {
-        result.warnings.push(`${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    }
+  /**
+   * Is `slug` already claimed by a skill in Pi's own global root?
+   *
+   * Pi keys skills by name, first-loaded wins, and `~/.pi/agent/skills/` is
+   * auto-discovered at higher precedence than anything an extension contributes
+   * via `resources_discover`. A global skill we write under a name that also
+   * exists there is never the copy Pi loads, so the write succeeds on disk and
+   * changes nothing about the agent's behaviour — silent write-loss (#125).
+   *
+   * Callers refuse the write and name both paths instead, which makes the
+   * shadowed state impossible to create rather than merely reported after the
+   * fact. Returns the shadowing path, or null when the name is free.
+   */
+  private async findShadowingPiGlobalSkill(slug: string): Promise<string | null> {
+    if (path.resolve(this.piGlobalSkillsDir) === path.resolve(this.globalSkillsDir)) return null;
+    const candidate = path.join(this.piGlobalSkillsDir, slug, "SKILL.md");
+    return await exists(candidate) ? candidate : null;
   }
 
   async loadIndex(scope?: SkillScope): Promise<SkillIndex[]> {
@@ -428,6 +419,19 @@ export class SkillStore {
           suggestedAction: "rename",
         };
       }
+
+      const shadowedBy = await this.findShadowingPiGlobalSkill(slug);
+      if (shadowedBy) {
+        return {
+          success: false,
+          error: `Pi already loads a global skill named '${slug}' from ${shadowedBy}. `
+            + `Pi keys skills by name and loads its own root first, so a skill written to `
+            + `${path.join(this.globalSkillsDir, slug, "SKILL.md")} would never be the copy in effect. `
+            + `Choose a different name, or edit ${shadowedBy} directly.`,
+          conflictType: "name-collision",
+          suggestedAction: "rename",
+        };
+      }
     }
 
     const filePath = path.join(root, slug, "SKILL.md");

package/src/store/sqlite-memory-store.ts

@@ -1,5 +1,11 @@
 import { DatabaseManager } from './db.js';
-import { buildFallbackFts5Query, isFts5QueryError, normalizeFts5Query } from './fts-query.js';
+import {
+  buildFallbackFts5Query,
+  buildNaturalLanguageFallbackQuery,
+  isFts5QueryError,
+  normalizeFts5Query,
+  normalizeNaturalLanguageFts5Query,
+} from './fts-query.js';
 import { normalizeMemoryLookupText } from './memory-lookup.js';
 import type { MemoryCategory } from '../types.js';
 
@@ -697,6 +703,8 @@ export function searchMemories(
     return [];
   }
 
+  let ftsParseError = false;
+
   const runSearch = (matchQuery: string): SqliteMemoryEntry[] => {
     const conditions: string[] = [];
     const params: unknown[] = [];
@@ -750,6 +758,7 @@ export function searchMemories(
       return rows.map(mapRow);
     } catch (err) {
       if (isFts5QueryError(err)) {
+        ftsParseError = true;
         return [];
       }
       throw err;
@@ -761,6 +770,26 @@ export function searchMemories(
     return exactResults;
   }
 
+  // A query with uppercase operator words (e.g. "DO NOT USE FIND /") passes
+  // through as raw FTS5 syntax; when that fails to parse, retry it as natural
+  // language instead of silently returning nothing. Valid operator queries
+  // that legitimately match nothing keep their exact semantics.
+  if (ftsParseError) {
+    const nlQuery = normalizeNaturalLanguageFts5Query(query);
+    if (nlQuery.length === 0 || nlQuery === normalizedQuery) {
+      return [];
+    }
+    const nlResults = runSearch(nlQuery);
+    if (nlResults.length > 0) {
+      return nlResults;
+    }
+    const nlFallback = buildNaturalLanguageFallbackQuery(query);
+    if (nlFallback && nlFallback !== nlQuery) {
+      return runSearch(nlFallback);
+    }
+    return nlResults;
+  }
+
   const fallbackQuery = buildFallbackFts5Query(query);
   if (!fallbackQuery || fallbackQuery === normalizedQuery) {
     return exactResults;

package/src/store/sqlite-native.ts

@@ -44,6 +44,18 @@ export class BetterSqlite3LoadError extends Error {
 const ABI_MISMATCH_RE =
   /NODE_MODULE_VERSION|was compiled against a different Node\.js version|ERR_DLOPEN_FAILED/i;
 
+/**
+ * True when running under Bun (including the compiled Pi binary).
+ *
+ * Compiled Pi cannot resolve `better-sqlite3` — neither the bare specifier nor
+ * the package's own transitive `require("bindings")` resolve from an on-disk
+ * extension file, so every code path that needs SQLite must route through
+ * `bun:sqlite` instead of loading the native module.
+ */
+export function isBunRuntime(): boolean {
+  return "Bun" in globalThis;
+}
+
 export function isNativeModuleAbiMismatch(error: unknown): boolean {
   if (!error) return false;
   const message = error instanceof Error ? error.message : String(error);