claude-mem-lite 6.25.2 → 6.26.0

package/install.mjs

@@ -18,7 +18,7 @@ import {
   lstatSync,
   constants as fsConstants,
 } from 'fs';
-import { join, resolve, dirname, basename, sep } from 'path';
+import { join, resolve, dirname, basename, sep, relative, isAbsolute } from 'path';
 import { homedir, tmpdir } from 'os';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
@@ -93,11 +93,25 @@ import {
   ensureBetterSqlite3Working,
   nativeBindingRepairHint,
   isNativeBindingError,
+  probeBindingInFreshProcess,
+  flattenBindingError,
 } from './lib/binding-probe.mjs';
 import { detectInstallShape, probeRuntimeRoots, hasAnyManagedCode } from './lib/install-shape.mjs';
 import { probeSchemaCompat, schemaSkewRemedy } from './lib/schema-skew.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
-import { acquireLock, lockHeld } from './lib/proc-lock.mjs';
+// A namespace, not named imports: a swap renames files one at a time, so for a moment this file can
+// sit over the previous release's lib/proc-lock.mjs, and a named import of an export that release
+// lacks is a SyntaxError that stops install.mjs loading — and repair and cleanup are what finish that
+// state (pre-ship delta review P2-1). Exports newer than v6.25.2 are detected.
+import * as procLock from './lib/proc-lock.mjs';
+const { lockHeld } = procLock;
+const lockDirBlocked = procLock.lockDirBlocked ?? (() => null);
+const takeLock =
+  procLock.takeLock ??
+  ((p) => {
+    const release = procLock.acquireLock(p);
+    return release ? { release } : {};
+  });
 import { atomicWriteFileSync, atomicCopyFileSync } from './lib/atomic-write.mjs';
 import { shellWord } from './cli-path.mjs';
 import { dirAccessError, walOpenBlocked, dataDirRemedy, WAL_BLOCKED_WHY } from './lib/wal-open-blocked.mjs';
@@ -1873,6 +1887,7 @@ async function status() {
   const unwritable = dataDirDenied
     ? ` — ${MEM_DATA_DIR} can be read but not written (${dataDirDenied}). Fix: ${dataDirAccessRemedy(dataDirDenied)}`
     : '';
+  let statusProbe;
   if (dataDirUnreadable) {
     push(
       'fail',
@@ -1880,6 +1895,17 @@ async function status() {
       `Database: ${MEM_DATA_DIR} is not accessible (${dataDirUnreadable}) — Fix: ${dataDirAccessRemedy(dataDirUnreadable)}`,
       { exists: null, error: dataDirUnreadable },
     );
+  } else if (existsSync(DB_PATH) && !(statusProbe = probeBindingInFreshProcess(PROJECT_DIR)).ok) {
+    // Out of process first, as doctor does: the open below loads the addon IN this process, and a
+    // truncated prebuild raises SIGBUS in dlopen rather than throwing, so status died with no
+    // output (D#306). The human line says why it did not look; the machine face keeps the loader's
+    // own error (review P3-10).
+    push(
+      dataDirDenied ? 'fail' : 'warn',
+      'database',
+      `Database: exists, but not checked — ${BINDING_MISSING_WHY}${unwritable}`,
+      { exists: true, error: flattenBindingError(statusProbe.error) },
+    );
   } else if (existsSync(DB_PATH)) {
     try {
       const Database = (await import('better-sqlite3')).default;
@@ -2173,6 +2199,11 @@ async function doctor() {
   // process.
   const rootProbes = probeRuntimeRoots(shape.runtimeRoots);
   const brokenRoots = rootProbes.filter((r) => !r.ok);
+  // Database and DB stats below open the store IN this process, through the better-sqlite3 the
+  // running CLI's tree resolves. When the out-of-process probe of that tree has already failed,
+  // loading it here is not just pointless: a truncated prebuild raises SIGBUS in dlopen, which
+  // killed doctor (exit 135) before it printed the rest (D#306). They say "not checked" instead.
+  const bindingBrokenHere = rootProbes.some((r) => !r.ok && sameDir(r.root, PROJECT_DIR));
   if (rootProbes.length === 0 && codeDirDenied) {
     // The code home is locked, so it may own a binding nobody could look at (D#284 review P3-4).
     notCheckedDenied('better-sqlite3', INSTALL_DIR);
@@ -2604,6 +2635,8 @@ async function doctor() {
   // Database
   if (dataDirUnreadable) {
     notCheckedDenied('Database');
+  } else if (existsSync(DB_PATH) && bindingBrokenHere) {
+    dwarn(`Database: not checked — ${BINDING_MISSING_WHY}`);
   } else if (existsSync(DB_PATH)) {
     try {
       const Database = (await import('better-sqlite3')).default;
@@ -3028,8 +3061,34 @@ async function doctor() {
   // install.lock is held, cleanup skips update residue (a running update's own staging and backup
   // dirs among it), so doctor does not count it either, and says it did not look (D#297). The holder
   // may be any installer: an update, install, repair, a binding rebuild. It asks without taking it.
+  // A runtime dir install.lock cannot be created in (a sudo run left it root-owned, a read-only data
+  // dir): every update entry skips on it as if a peer held the lock, silently, so this is the only
+  // face that can say why updates stopped (D#307). Counted here unless the Data directory line above
+  // already counts the directory it sits in.
+  const installLockBlocked = lockDirBlocked(INSTALL_LOCK_PATH);
+  if (installLockBlocked) {
+    const line = `Install lock: ${lockBlockedWhy(installLockBlocked)} — every update, install, repair and binding rebuild skips until it can be taken`;
+    // The same directory the Data directory line counts (or one above it), or the same read-only
+    // mount: one fault, one ✗. A runtime dir inside a data dir that both need fixing is two.
+    const relToData = relative(MEM_DATA_DIR, installLockBlocked.dir);
+    const sameFault =
+      dataDirDenied &&
+      (relToData === '' ||
+        relToData.startsWith('..') ||
+        isAbsolute(relToData) ||
+        (dataDirDenied === 'EROFS' && installLockBlocked.code === 'EROFS'));
+    if (sameFault) dwarn(line);
+    else {
+      fail(line);
+      issues++;
+    }
+  }
   try {
-    const lockHeldNow = lockHeld(join(MEM_DATA_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
+    // Held and blocked are separate answers. A lock can be both: a sudo-run installer still running
+    // in the root-owned runtime dir it made holds it there (pre-ship review). Held, the residue may
+    // be that installer's own and is not counted; blocked and not held, an unfinished swap is a real
+    // one and is counted (D#289), and every repair it names waits on the lock line's fix.
+    const lockHeldNow = lockHeld(INSTALL_LOCK_PATH);
     const { stale, inFlight, unfinishedSwaps, unreadableJournals, notChecked } = scanStaleTempFiles({
       codeDir: INSTALL_DIR,
       runtimeDir: MEM_RUNTIME_DIR,
@@ -3037,14 +3096,16 @@ async function doctor() {
       installLockHeld: lockHeldNow,
     });
     const installer = `node ${shellWord(join(PROJECT_DIR, 'install.mjs'))}`;
+    const onceLock =
+      installLockBlocked && !lockHeldNow ? ' once install.lock can be taken (see Install lock)' : '';
     if (unfinishedSwaps > 0) {
       dwarn(
-        `Unfinished update: ${unfinishedSwaps} backup dir(s) in ${INSTALL_DIR} still hold a swap journal — an update was interrupted, or could not put back every file it moved aside (run: ${installer} cleanup — it finishes them newest first, and stops at one it cannot read or put back)`,
+        `Unfinished update: ${unfinishedSwaps} backup dir(s) in ${INSTALL_DIR} still hold a swap journal — an update was interrupted, or could not put back every file it moved aside (run: ${installer} cleanup${onceLock} — it finishes them newest first, and stops at one it cannot read or put back)`,
       );
     }
     if (unreadableJournals > 0) {
       dwarn(
-        `Unfinished update: ${unreadableJournals} backup dir(s) in ${INSTALL_DIR} whose journal cannot be read, so nothing can finish that update; they hold the files it moved aside (run: ${installer} repair — it reinstalls over them; cleanup then removes them)`,
+        `Unfinished update: ${unreadableJournals} backup dir(s) in ${INSTALL_DIR} whose journal cannot be read, so nothing can finish that update; they hold the files it moved aside (run: ${installer} repair${onceLock} — it reinstalls over them; cleanup then removes them)`,
       );
     }
     const skipped = lockHeldNow
@@ -3054,11 +3115,13 @@ async function doctor() {
       const where = notChecked.map((n) => `${n.dir} is not accessible (${n.code})`).join('; ');
       dwarn(
         `Stale temp files: not checked — ${where}` +
-          (stale > 0 ? `; ${stale} found elsewhere (run: ${installer} cleanup)` : '') +
+          (stale > 0 ? `; ${stale} found elsewhere (run: ${installer} cleanup${onceLock})` : '') +
           (skipped ? `; ${skipped}` : ''),
       );
     } else if (stale > 0) {
-      dwarn(`Stale temp files: ${stale} found (run: ${installer} cleanup)${skipped ? `; ${skipped}` : ''}`);
+      dwarn(
+        `Stale temp files: ${stale} found (run: ${installer} cleanup${onceLock})${skipped ? `; ${skipped}` : ''}`,
+      );
     } else if (skipped) {
       dwarn(`Stale temp files: ${skipped}`);
     } else {
@@ -3081,7 +3144,9 @@ async function doctor() {
   }
 
   // DB stats
-  if (existsSync(DB_PATH)) {
+  if (existsSync(DB_PATH) && bindingBrokenHere) {
+    dwarn(`DB stats: not checked — ${BINDING_MISSING_WHY}`);
+  } else if (existsSync(DB_PATH)) {
     try {
       const dbSize = statSync(DB_PATH).size;
       const sizeMB = (dbSize / 1024 / 1024).toFixed(1);
@@ -3504,10 +3569,23 @@ async function cleanup() {
   let finished = 0;
   // --dry-run writes nothing, so it asks whether the lock is held instead of taking it: taking it
   // created the data dir, its runtime dir and the lock on a machine with nothing installed (D#297).
-  const lockPath = join(MEM_DATA_DIR, 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
-  const updateLock = dryRun ? (lockHeld(lockPath) ? null : () => {}) : acquireLock(lockPath);
+  // A lock that cannot be taken at all is not one a peer holds (D#304): both runs name its directory.
+  // The real run takes the answer from its own failed create (any errno); the dry run, which must not
+  // create anything, predicts it from the directory (lockDirBlocked).
+  let updateLock = null;
+  let lockBlocked;
+  if (dryRun) {
+    lockBlocked = lockDirBlocked(INSTALL_LOCK_PATH);
+    if (!lockBlocked && !lockHeld(INSTALL_LOCK_PATH)) updateLock = () => {};
+  } else {
+    const taken = takeLock(INSTALL_LOCK_PATH);
+    updateLock = taken.release || null;
+    lockBlocked = taken.error || null;
+  }
   if (!updateLock) {
-    warn('Update residue skipped: install in progress (install.lock held)');
+    warn(
+      `Update residue skipped: ${lockBlocked ? lockBlockedWhy(lockBlocked) : 'install in progress (install.lock held)'}`,
+    );
   } else {
     try {
       let found = [];
@@ -3517,8 +3595,29 @@ async function cleanup() {
         warn(`Update residue: could not list ${INSTALL_DIR} (${e.code || e.message})`);
       }
       if (dryRun) {
+        // Recovery undoes unfinished swaps like a stack, newest first, and stops at the first whose
+        // journal cannot be read, leaving it and every older one (D#293). Judged one dir at a time,
+        // the dry run promised to finish an older swap the real run leaves (D#307 F3), so it walks
+        // them in recovery's own order, taken from hook-update rather than restated here.
+        const swaps = found
+          .filter((r) => r.kind === 'unfinished-swap' || r.kind === 'unreadable-journal')
+          .map((r) => ({ name: r.f, readable: r.kind === 'unfinished-swap' }));
+        let blockedBy = new Map();
+        let cannotLoad = null;
+        if (swaps.some((s) => s.readable)) {
+          try {
+            const { swapsBlockedByUnreadable } = await import('./hook-update.mjs');
+            blockedBy = swapsBlockedByUnreadable(swaps);
+          } catch (e) {
+            cannotLoad = e.message;
+          }
+        }
         for (const { f, kind } of found) {
-          if (kind === 'unfinished-swap') {
+          if (kind === 'unfinished-swap' && cannotLoad) {
+            warn(`Would leave in place: ${f} (the updater that finishes it cannot load: ${cannotLoad})`);
+          } else if (kind === 'unfinished-swap' && blockedBy.has(f)) {
+            warn(`Would leave in place: ${f} (a newer one, ${blockedBy.get(f)}, cannot be finished first)`);
+          } else if (kind === 'unfinished-swap') {
             ok(`Would finish an interrupted update: ${f} (puts back the files its journal lists)`);
             finished++;
           } else if (kind === 'unreadable-journal') {
@@ -3547,21 +3646,29 @@ async function cleanup() {
       }
       // A relocated data dir that an updater older than v2.90.0 swapped into: its residue is stale,
       // whatever it holds, and is never replayed (lib/doctor-stale-temp.mjs, legacyDir).
-      if (!sameDir(INSTALL_DIR, MEM_DATA_DIR) && existsSync(MEM_DATA_DIR)) {
-        for (const f of readdirSync(MEM_DATA_DIR)) {
-          if (!isUpdateResidue(f)) continue;
-          if (dryRun) {
-            ok(`Would remove: ${join(MEM_DATA_DIR, f)}`);
-            removed++;
-            continue;
-          }
-          try {
-            rmSync(join(MEM_DATA_DIR, f), { recursive: true, force: true });
-            ok(`Removed: ${join(MEM_DATA_DIR, f)}`);
-            removed++;
-          } catch (e) {
-            warn(`Failed to remove ${join(MEM_DATA_DIR, f)}: ${e.message}`);
-          }
+      let legacyEntries = [];
+      if (!sameDir(INSTALL_DIR, MEM_DATA_DIR)) {
+        try {
+          legacyEntries = readdirSync(MEM_DATA_DIR);
+        } catch (e) {
+          // Absent is nothing to clean; one it can enter but not list threw out of cleanup (review P3-6).
+          if (e.code !== 'ENOENT')
+            warn(`Update residue: could not list ${MEM_DATA_DIR} (${e.code || e.message})`);
+        }
+      }
+      for (const f of legacyEntries) {
+        if (!isUpdateResidue(f)) continue;
+        if (dryRun) {
+          ok(`Would remove: ${join(MEM_DATA_DIR, f)}`);
+          removed++;
+          continue;
+        }
+        try {
+          rmSync(join(MEM_DATA_DIR, f), { recursive: true, force: true });
+          ok(`Removed: ${join(MEM_DATA_DIR, f)}`);
+          removed++;
+        } catch (e) {
+          warn(`Failed to remove ${join(MEM_DATA_DIR, f)}: ${e.message}`);
         }
       }
     } finally {
@@ -3582,10 +3689,18 @@ async function cleanup() {
   // fixture sweep below, whose comment already states the principle: a MANUAL cleanup is
   // the conservative one.
   const runtimeDir = MEM_RUNTIME_DIR;
-  if (existsSync(runtimeDir)) {
+  let runtimeEntries = [];
+  try {
+    runtimeEntries = readdirSync(runtimeDir);
+  } catch (e) {
+    // Absent is nothing to clean. A runtime dir that cannot be listed (a sudo run left it 0700 and
+    // root-owned) threw out of cleanup uncaught, dry run included (D#304).
+    if (e.code !== 'ENOENT') warn(`Runtime scratch: could not list ${runtimeDir} (${e.code || e.message})`);
+  }
+  if (runtimeEntries.length > 0) {
     const now = Date.now();
     let inFlight = 0;
-    for (const f of readdirSync(runtimeDir)) {
+    for (const f of runtimeEntries) {
       if (isEpisodeResidue(f)) {
         // The gate itself lives in lib/doctor-stale-temp.mjs, so doctor's count and this
         // deletion cannot disagree about which files are in flight (D#53).
@@ -3625,6 +3740,10 @@ async function cleanup() {
   if (removed > 0) done.push(`${removed} stale file(s) ${verb}`);
   if (finished > 0)
     done.push(`${finished} interrupted update(s) ${dryRun ? 'would be finished' : 'finished'}`);
+  // Skipped update residue is not "nothing found" (review P3-4). Held, a peer is working on it; a
+  // lock that cannot be taken is a failure no wait clears, so the exit says so, as install's does.
+  if (!updateLock) done.push('update residue not checked (see above)');
+  if (lockBlocked) process.exitCode = 1;
   console.log(`\n  ${done.length === 0 ? 'No stale files found.' : `${done.join('; ')}.`}\n`);
 }
 
@@ -3635,7 +3754,8 @@ async function manualUpdate() {
   console.log('\nclaude-mem-lite self-update\n');
 
   // Force check by importing hook-update (bypasses throttle for manual use)
-  const { checkForUpdate, getCurrentVersion, updateCheckDisabledReason } = await import('./hook-update.mjs');
+  const { checkForUpdate, getCurrentVersion, updateCheckDisabledReason, isPluginMode } =
+    await import('./hook-update.mjs');
   // checkForUpdate returns null without looking in these two cases, and the branch at the
   // bottom would then report "Already up to date" for a check that never ran. (D#251)
   const disabled = updateCheckDisabledReason();
@@ -3651,6 +3771,16 @@ async function manualUpdate() {
     console.log('');
     return;
   }
+  // An update installs under install.lock, and hook-update reads a lock it cannot take as "an install
+  // is in progress", which this printed as "install failed" (review P3-5).
+  // Plugin mode only checks, it never installs, so the lock is not its business (delta review P3-3).
+  const lockBlocked = isPluginMode?.() ? null : lockDirBlocked(INSTALL_LOCK_PATH);
+  if (lockBlocked) {
+    warn(`Not checked: ${lockBlockedWhy(lockBlocked)}`);
+    process.exitCode = 1;
+    console.log('');
+    return;
+  }
   log('Checking for updates...');
   const result = await checkForUpdate({ force: true, allowInstall: true, reportFailure: true });
 
@@ -3687,6 +3817,15 @@ async function manualUpdate() {
 // buggy on disk.
 async function repair() {
   console.log('\nclaude-mem-lite repair — re-syncing from the latest SIGNED GitHub release\n');
+  // The install this ends in takes install.lock. One that cannot be taken here fails that install
+  // after a whole release was downloaded, and the manual fallback below fails the same way, so say
+  // it first and stop (review P3-5). A peer holding it is left to the install's own message.
+  const lockBlocked = lockDirBlocked(INSTALL_LOCK_PATH);
+  if (lockBlocked) {
+    fail(`Repair not started: ${lockBlockedWhy(lockBlocked)}`);
+    process.exitCode = 1;
+    return;
+  }
   const stagingDir = mkdtempSync(join(tmpdir(), 'claude-mem-lite-repair-'));
   try {
     // Resolve the latest RELEASE (tag) and cryptographically VERIFY it before running any
@@ -3929,12 +4068,16 @@ function bindingHostDir() {
 // two concurrent rebuilds can clobber the .node mid-compile. A live peer → report
 // and exit 0 (it is doing this very work), never race it.
 async function rebuildBinding() {
-  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
+  const { release, error: blocked } = takeLock(INSTALL_LOCK_PATH);
   if (!release) {
     // NOT exit 0: skipping is not healing. Callers key their state on the exit
     // code — a false success would let the launcher drop its cooldown and the
     // CLI re-exec into the same broken binding.
-    console.error('[install] Another install/repair is in progress — it owns the rebuild; skipping.');
+    console.error(
+      blocked
+        ? `[install] ${lockBlockedWhy(blocked)} — the binding was not rebuilt.`
+        : '[install] Another install/repair is in progress — it owns the rebuild; skipping.',
+    );
     process.exitCode = 1;
     return;
   }
@@ -4011,6 +4154,35 @@ function sameDir(a, b) {
 // The fix for a data dir this user cannot use, chosen by the error code (lib/wal-open-blocked.mjs).
 export const dataDirAccessRemedy = (code) => dataDirRemedy(code, MEM_DATA_DIR);
 
+// install.lock serialises every installer (install, repair, update, binding rebuild, cleanup's
+// update residue). One that cannot be created at all is not one a peer holds, and each face says
+// which (D#304, D#307): waiting does not clear it, the fix below does.
+const INSTALL_LOCK_PATH = join(MEM_DATA_DIR, 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
+const lockBlockedWhy = ({ dir, code }) =>
+  `install.lock cannot be taken — ${dir} cannot be written (${code}). Fix: ${lockDirRemedy(code, dir)}`;
+
+// The fix for the directory lockDirBlocked / takeLock name. One ABOVE the data dir (it does not exist
+// yet and cannot be created there, or cannot be reached) is not this program's to chmod or chown: on
+// a CLAUDE_MEM_DIR under /opt that advice would hand /opt to the user (review P3-3).
+function lockDirRemedy(code, dir) {
+  const rel = relative(MEM_DATA_DIR, dir);
+  // Creating the data dir fixes only a parent that can be entered but not written; one that cannot be
+  // entered (the data dir may already be the user's), or a link to nowhere, leaves CLAUDE_MEM_DIR
+  // (delta review P3-1).
+  const above = rel.startsWith('..') || isAbsolute(rel);
+  if (above && (code === 'ENOENT' || dirAccessError(dir, fsConstants.X_OK)))
+    return `${shellWord(dir)} cannot be entered or does not exist — set CLAUDE_MEM_DIR to a directory your user can write`;
+  if (above)
+    return `make ${shellWord(MEM_DATA_DIR)} a directory your user owns (e.g. sudo mkdir -p ${shellWord(MEM_DATA_DIR)} && sudo chown "$USER" ${shellWord(MEM_DATA_DIR)}), or set CLAUDE_MEM_DIR to one`;
+  if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS') return dataDirRemedy(code, dir);
+  if (code === 'ENOSPC' || code === 'EDQUOT')
+    return `free space on the file system holding ${shellWord(dir)}`;
+  if (code === 'ENOTDIR') return `${shellWord(dir)} is a file, not a directory — move it aside`;
+  if (code === 'ENOENT')
+    return `${shellWord(dir)} is a link to a directory that does not exist — create its target, or remove the link`;
+  return `check that your user can create files in ${shellWord(dir)}`;
+}
+
 // This process cannot load better-sqlite3: none installed where it runs (a checkout, or a plugin
 // cache before its first launch installed node_modules), or one that will not load (a stale ABI, a
 // damaged prebuild). The better-sqlite3 line names and counts that; a line that would open the DB
@@ -4028,8 +4200,14 @@ async function runLockedInstall() {
     process.exitCode = 1;
     return;
   }
-  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
+  const { release, error: blocked } = takeLock(INSTALL_LOCK_PATH);
   if (!release) {
+    if (blocked) {
+      // Not a peer: nothing will ever release it, and exit 0 told the caller it installed.
+      console.error(`[install] ${lockBlockedWhy(blocked)} — nothing was done.`);
+      process.exitCode = 1;
+      return;
+    }
     console.log('[install] Another install/repair is in progress — skipping to avoid a torn write.');
     return;
   }

package/lib/binding-probe.mjs

@@ -76,10 +76,16 @@ export function nativeBindingRepairHint(root) {
 // Set on a re-exec'd child so one failed heal cannot fork-bomb the CLI.
 export const BINDING_HEAL_GUARD_ENV = 'CLAUDE_MEM_BINDING_HEALED';
 
-// The native-binding fault family, in the four shapes it actually reaches callers:
+// The native-binding fault family, in the shapes it actually reaches callers:
 //   • ERR_DLOPEN_FAILED            — Node's code for a failed dlopen (ABI mismatch)
 //   • NODE_MODULE_VERSION N vs M   — the ABI text itself (some throws carry no code)
 //   • Could not locate the bindings file — build/Release missing or never compiled
+//     (better-sqlite3 ≤12, through the `bindings` package)
+//   • Cannot find module '…better_sqlite3.node' — the same fault on 13, which dropped
+//     `bindings`: with no prebuild for the platform and no source build, lib/binding.js
+//     requires build/Release/better_sqlite3.node and Node throws a plain MODULE_NOT_FOUND
+//     (D#306). Every first load on a platform 13 ships no prebuild for. Anchored on the
+//     addon's file name: a missing PACKAGE needs an install, not a rebuild.
 //   • Module did not self-register — the .node was REPLACED under a process that
 //     already dlopen'd the old one; only a fresh process recovers (hence the
 //     re-exec in healAndReexec, not an in-process retry)
@@ -88,6 +94,8 @@ export const BINDING_HEAL_GUARD_ENV = 'CLAUDE_MEM_BINDING_HEALED';
 const NATIVE_BINDING_PATTERNS = [
   /NODE_MODULE_VERSION/,
   /Could not locate the bindings file/i,
+  // A quote may sit inside the path; the quoted path must end the line (Node's own shape).
+  /Cannot find module '[^\n]*[\\/]better_sqlite3\.node'(?:\r?\n|$)/,
   /did not self-register/i,
   /invalid ELF header/i,
 ];

package/lib/native-binding-hint.mjs

@@ -135,9 +135,11 @@ export function formatHookError(err, event, { now = Date.now(), runtimeDir } = {
       !nativeBindingHintDue(runtimeDir, now, NATIVE_BINDING_HINT_COOLDOWN_MS, errKey(err.message))
     )
       return null;
+    // No guessed cause: better-sqlite3 13's addons are N-API and survive a Node upgrade, and on 13 the
+    // addon can also never have been there — no prebuild for the platform (D#306).
     return (
       `[claude-mem-lite] [${ts}] [WARN] ${event}: native DB binding can't load ` +
-      `(likely a Node version change) — auto-heals at the next session start, or run now: ${CLI_REBUILD_BINDING}`
+      `— auto-heals at the next session start, or run now: ${CLI_REBUILD_BINDING}`
     );
   }
   return `[claude-mem-lite] [${ts}] [ERROR] ${event}: ${err && err.message}`;