claude-mem-lite 6.25.2 → 6.25.3

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.25.2",
+      "version": "6.25.3",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.25.2",
+  "version": "6.25.3",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/hook-update.mjs

@@ -43,7 +43,11 @@ import {
 // because checkForUpdate is silent on network failure the plugin then reports
 // itself permanently up to date. Same tunnel the OpenRouter call site uses.
 import { httpConnectProxyFor, getViaConnectProxy, redactProxyUrl } from './lib/proxy-fetch.mjs';
-import { acquireLock } from './lib/proc-lock.mjs';
+// A namespace, not a named import: 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 this module loading — and with it recoverInterruptedSwaps, which
+// finishes that very swap (pre-ship delta review P2-1). takeLock is newer than v6.25.2: detected.
+import * as procLock from './lib/proc-lock.mjs';
 import { atomicWriteFileSync } from './lib/atomic-write.mjs';
 import { verifyReleaseFiles, verifyManifestSignature } from './lib/release-digest.mjs';
 import { detectInstallShape } from './lib/install-shape.mjs';
@@ -262,7 +266,7 @@ function pluginOnlyInstall() {
   return Boolean(shape && !shape.managed && shape.activePluginVersion);
 }
 
-function isPluginMode() {
+export function isPluginMode() {
   return Boolean(process.env.CLAUDE_PLUGIN_ROOT) || pluginOnlyInstall();
 }
 
@@ -964,6 +968,30 @@ const BACKUP_SEQ_RE = /^\.update-backup-s(\d+)-/;
 const swapSeqOf = (name) => Number(BACKUP_SEQ_RE.exec(name)?.[1] ?? 0);
 const nextSwapSeq = (names) => Math.max(0, ...names.map(swapSeqOf)) + 1;
 
+/** Unresolved backup dir names in the order recovery undoes them: newest first, by seq, then name.
+ * cleanup --dry-run walks the same order to say what recovery would leave (D#307 F3). */
+const unresolvedSwapOrder = (names) =>
+  [...names].sort((a, b) => swapSeqOf(b) - swapSeqOf(a) || b.localeCompare(a));
+
+/**
+ * Which unresolved backup dirs recovery would leave in place because a newer one's journal cannot be
+ * read: recovery walks them newest first and stops there (recoverInterruptedSwaps). cleanup --dry-run
+ * reports from this instead of judging each dir alone (D#307 F3). It cannot foresee a file that
+ * fails to go back, which also stops the walk.
+ * @param {{name: string, readable: boolean}[]} swaps
+ * @returns {Map<string, string>} name → the newer unreadable dir that blocks it
+ */
+export function swapsBlockedByUnreadable(swaps) {
+  const readable = new Map(swaps.map((s) => [s.name, s.readable]));
+  const blockedBy = new Map();
+  let newestUnreadable = null;
+  for (const name of unresolvedSwapOrder([...readable.keys()])) {
+    if (newestUnreadable) blockedBy.set(name, newestUnreadable);
+    else if (!readable.get(name)) newestUnreadable = name;
+  }
+  return blockedBy;
+}
+
 // The `.update-backup-*` dirs in targetDir that carry no resolved marker.
 function unresolvedBackups(targetDir) {
   try {
@@ -1058,8 +1086,7 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
   // they are undone like a stack: newest first by the seq in the name, and none older while a newer
   // one is unfinished or cannot be read. An older journal replayed first puts back a file that a
   // newer journal, which installed that path, then deletes; with nothing left to restore it from.
-  pending.sort((a, b) => swapSeqOf(b) - swapSeqOf(a) || b.localeCompare(a));
-  for (const name of pending) {
+  for (const name of unresolvedSwapOrder(pending)) {
     const dir = join(targetDir, name);
     // No journal: the swap is over and its journal is gone (or it was killed before its first
     // rename), so there is nothing to replay and the dir is residue. A journal that is there but
@@ -1241,12 +1268,18 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
   // holding the lock means an install is already in flight — skip rather than
   // race. Shared path with install.mjs so direct install + repair + auto-update
   // are mutually exclusive.
-  const release = acquireLock(join(STATE_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
+  const lockPath = join(STATE_DIR, 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
+  const { release, error: lockError } = procLock.takeLock
+    ? procLock.takeLock(lockPath)
+    : { release: procLock.acquireLock(lockPath) };
   if (!release) {
+    // doctor is the face that names a lock that cannot be taken (D#307); this log is debug-only.
     debugLog(
       'DEBUG',
       'hook-update',
-      'installExtractedRelease: another install/update is in progress — skipping',
+      lockError
+        ? `installExtractedRelease: install.lock cannot be taken — ${lockError.dir} (${lockError.code}) — skipping`
+        : 'installExtractedRelease: another install/update is in progress — skipping',
     );
     return false;
   }

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}`;

package/lib/proc-lock.mjs

@@ -16,7 +16,18 @@
 // already doing the write). Release unlinks the file. Crash-safe: a crashed holder's
 // pid is gone, so the next session reclaims its lock at once.
 
-import { writeFileSync, readFileSync, unlinkSync, mkdirSync, renameSync, linkSync, lstatSync } from 'node:fs';
+import {
+  writeFileSync,
+  readFileSync,
+  unlinkSync,
+  mkdirSync,
+  renameSync,
+  linkSync,
+  lstatSync,
+  statSync,
+  accessSync,
+  constants as fsConstants,
+} from 'node:fs';
 import { dirname } from 'node:path';
 import { workerDirGone } from './worker-data-dir.mjs';
 
@@ -75,13 +86,21 @@ function isStale(lockPath, staleMs, now) {
  * temp carries a `.lock` suffix so hook.mjs's sweeper reclaims it if we die in between.
  * Filesystems without hard links (some network / FAT mounts) fall back to the old form —
  * they keep the narrow window, which is still better than never acquiring a lock at all.
+ *
+ * A failure is returned as the errno, so a caller can say why the lock cannot be taken.
  */
 function createExclusive(lockPath, payload) {
   const tmp = `${lockPath}.new-${process.pid}-${Math.random().toString(36).slice(2)}.lock`;
   try {
     writeFileSync(tmp, payload, { flag: 'wx' });
-  } catch {
-    return 'error';
+  } catch (e) {
+    // open() may have created it before the write failed (a full disk): do not leave it behind.
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* never created */
+    }
+    return { error: e.code || 'EIO' };
   }
   try {
     linkSync(tmp, lockPath);
@@ -93,7 +112,7 @@ function createExclusive(lockPath, payload) {
       writeFileSync(lockPath, payload, { flag: 'wx' });
       return 'ok';
     } catch (e2) {
-      return e2.code === 'EEXIST' ? 'exists' : 'error';
+      return e2.code === 'EEXIST' ? 'exists' : { error: e2.code || 'EIO' };
     }
   } finally {
     try {
@@ -131,10 +150,29 @@ function makeRelease(lockPath, payload) {
  * @returns {(() => void)|null}  A release() fn, or null if a live peer holds it, the lock file
  *   could not be created, or this is a background worker whose lock directory was removed.
  */
-export function acquireLock(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.now } = {}) {
+export function acquireLock(lockPath, opts) {
+  return takeLock(lockPath, opts).release || null;
+}
+
+/**
+ * acquireLock, saying why when it does not take the lock. acquireLock's null stands both for a
+ * live holder and for a lock file that cannot be created at all, and every installer read that
+ * null as "another install is in progress": with a runtime dir a `sudo` run left root-owned, a
+ * read-only data dir, a runtime link to nowhere or a full disk, every update skipped silently and
+ * install exited 0 having done nothing (D#304, D#307). An error is reported for every failed
+ * create: as lockDirBlocked names it when it sees the cause, otherwise with the create's own errno,
+ * which covers the causes its access() check cannot see (a Windows ACL, ENOSPC).
+ * @returns {{release: () => void} | {error: {dir: string, code: string}} | {}} {} when a live peer
+ *   holds it, or this is a background worker whose lock directory was removed.
+ */
+export function takeLock(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.now } = {}) {
+  // lockDirBlocked, when it sees the cause, names the directory that has to change and why: it walks
+  // to an ancestor that cannot be entered, a link to nowhere, a component that is a file. A cause it
+  // cannot see (a full disk, a Windows ACL access() does not read) keeps the create's own errno.
+  const failed = (code) => ({ error: lockDirBlocked(lockPath) || { dir: dirname(lockPath), code } });
   // A background worker (auto-maintain takes its lock in the runtime dir) does not re-create a
   // directory removed while it ran (D#265). Not taking the lock is the caller's no-op path.
-  if (workerDirGone(dirname(lockPath))) return null;
+  if (workerDirGone(dirname(lockPath))) return {};
   try {
     mkdirSync(dirname(lockPath), { recursive: true });
   } catch {
@@ -150,8 +188,8 @@ export function acquireLock(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.n
     nonce: Math.random().toString(36).slice(2),
   });
   const first = createExclusive(lockPath, payload);
-  if (first === 'ok') return makeRelease(lockPath, payload);
-  if (first === 'error') return null; // permission / fs error → fail closed
+  if (first === 'ok') return { release: makeRelease(lockPath, payload) };
+  if (first.error) return failed(first.error); // permission / fs error → fail closed, and say why
   {
     let sampled;
     try {
@@ -162,9 +200,11 @@ export function acquireLock(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.n
       // it would move a peer's freshly created lock aside with nothing to compare it to,
       // which is the double-acquire this whole protocol exists to prevent. Just retry the
       // plain exclusive create once and take the answer.
-      return createExclusive(lockPath, payload) === 'ok' ? makeRelease(lockPath, payload) : null;
+      const again = createExclusive(lockPath, payload);
+      if (again === 'ok') return { release: makeRelease(lockPath, payload) };
+      return again.error ? failed(again.error) : {};
     }
-    if (!isStale(lockPath, staleMs, now)) return null; // live peer holds it
+    if (!isStale(lockPath, staleMs, now)) return {}; // live peer holds it
     // ── Stealing a stale lock (R10 P1-7) ──────────────────────────────────────────────
     // This used to be unlink-then-create, and the comment "lose the race → null" was only
     // true of the create. The losing interleave: A unlinks, A creates, B unlinks A's BRAND
@@ -182,7 +222,7 @@ export function acquireLock(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.n
     try {
       renameSync(lockPath, tombstone);
     } catch {
-      return null; // another stealer won the rename; it owns the re-create
+      return {}; // another stealer won the rename; it owns the re-create
     }
     let stolen = null;
     try {
@@ -201,14 +241,16 @@ export function acquireLock(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.n
       } catch {
         /* best-effort */
       }
-      return null;
+      return {};
     }
     try {
       unlinkSync(tombstone);
     } catch {
       /* best-effort — the .lock suffix keeps it sweepable either way */
     }
-    return createExclusive(lockPath, payload) === 'ok' ? makeRelease(lockPath, payload) : null;
+    const retaken = createExclusive(lockPath, payload);
+    if (retaken === 'ok') return { release: makeRelease(lockPath, payload) };
+    return retaken.error ? failed(retaken.error) : {};
   }
 }
 
@@ -235,6 +277,87 @@ export function lockHeld(lockPath, { staleMs = DEFAULT_STALE_MS, now = Date.now
   return !isStale(lockPath, staleMs, now);
 }
 
+/**
+ * Why acquireLock cannot create `lockPath` whoever holds it, or null when it can. acquireLock
+ * answers null both for a live holder and for a lock file it cannot create at all, and every
+ * caller read that null as "another install is in progress": with a runtime dir a `sudo` run left
+ * root-owned, or a read-only data dir, every update skipped silently, install exited 0 having done
+ * nothing, and cleanup named a lock that did not exist (D#304, D#307). This tells the two apart.
+ * Read-only, like lockHeld: it creates nothing.
+ *
+ * The directory asked about is the lock's own, or, when that does not exist yet, the nearest one
+ * that does: acquireLock creates the rest, so that is the one it has to write into.
+ * @returns {{dir: string, code: string}|null}
+ */
+export function lockDirBlocked(lockPath) {
+  let dir = dirname(lockPath);
+  for (;;) {
+    // A path that is there but is a file, not a directory: access() reads the file's own mode bits
+    // (EACCES, or a pass for a 0777 file), so it is asked first.
+    try {
+      if (!statSync(dir).isDirectory()) return { dir, code: 'ENOTDIR' };
+    } catch {
+      /* absent, or not reachable: access() below says which */
+    }
+    try {
+      accessSync(dir, fsConstants.W_OK | fsConstants.X_OK);
+      return null;
+    } catch (e) {
+      // A link to nowhere reads as absent, but nothing can be created under it (review P2-1).
+      if (e.code === 'ENOENT' && isLink(dir)) return { dir, code: 'ENOENT' };
+      // A component that is a file, not a directory: name that file.
+      if (e.code === 'ENOTDIR') return { dir: firstNonDirectory(dir) ?? dir, code: 'ENOTDIR' };
+      // A directory under one that cannot be entered fails EACCES too: name the one to fix.
+      if (e.code !== 'ENOENT') return unenterableAncestor(dir) || { dir, code: e.code || 'EACCES' };
+      const up = dirname(dir);
+      if (up === dir) return null;
+      dir = up;
+    }
+  }
+}
+
+function isLink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** The component of `dir` nearest the root that exists and is not a directory, or null. */
+function firstNonDirectory(dir) {
+  const chain = [];
+  for (let d = dir; ; d = dirname(d)) {
+    chain.unshift(d);
+    if (dirname(d) === d) break;
+  }
+  for (const d of chain) {
+    try {
+      if (!statSync(d).isDirectory()) return d;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/** The ancestor of `dir` nearest the root that this user cannot enter, or null. */
+function unenterableAncestor(dir) {
+  const chain = [];
+  for (let d = dirname(dir); ; d = dirname(d)) {
+    chain.unshift(d);
+    if (dirname(d) === d) break;
+  }
+  for (const d of chain) {
+    try {
+      accessSync(d, fsConstants.X_OK);
+    } catch (e) {
+      return e.code === 'ENOENT' ? null : { dir: d, code: e.code || 'EACCES' };
+    }
+  }
+  return null;
+}
+
 /**
  * Run `fn` while holding the lock; release in a finally. No-op if not acquired.
  * @returns {{acquired: boolean, result?: any}}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.25.2",
+  "version": "6.25.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.25.2",
+      "version": "6.25.3",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.25.2",
+  "version": "6.25.3",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",

package/scripts/binding-probe-cli.mjs

@@ -114,11 +114,14 @@ try {
   process.stderr.write(`[claude-mem-lite] binding probe: ${e.message}\n`);
   process.exit(1);
 }
-const release = helpers.acquireLock(lockPath);
+const { release, error: blocked } = helpers.takeLock(lockPath);
 if (!release) {
+  // A lock that cannot be created at all is not an install in flight (D#307): name it, as doctor does.
   process.stderr.write(
     `[claude-mem-lite] binding probe: ${helpers.flattenBindingError(first.error)} ` +
-      '(another install/repair in flight — deferring heal)\n',
+      (blocked
+        ? `(install.lock cannot be taken — ${blocked.dir} cannot be written (${blocked.code}); run doctor for the fix)\n`
+        : '(another install/repair in flight — deferring heal)\n'),
   );
   process.exit(1);
 }

package/scripts/hook-launcher.mjs

@@ -497,9 +497,7 @@ function healNativeBindingIfBroken() {
     // (install.mjs::rebuildBinding). Clearing it here would mean a rebuild that
     // silently did nothing — lock contention, a no-op npm — still reads as
     // "healed", dropping the cooldown and re-spawning npm on every session.
-    process.stderr.write(
-      '[claude-mem-lite] native DB binding unusable (Node version change?) — rebuilding in the background\n',
-    );
+    process.stderr.write('[claude-mem-lite] native DB binding unusable — rebuilding in the background\n');
     const child = spawn(process.execPath, [installer, 'rebuild-binding'], {
       detached: true,
       stdio: 'ignore',

package/scripts/launch.mjs

@@ -116,11 +116,19 @@ try {
   // mid-compile. Take the lock for the rebuild-capable path; a live peer →
   // wait up to 10s, then degrade to a probe-only pass (healthy binding
   // proceeds; a broken one defers to the peer instead of racing it).
-  const { acquireLock } = await import('../lib/proc-lock.mjs');
+  const { takeLock } = await import('../lib/proc-lock.mjs');
   const { resolveDataDir } = await import('../lib/resolve-data-dir.mjs');
   const lockPath = join(resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
+  // A lock that cannot be created at all (a runtime dir a sudo run left root-owned, a link to
+  // nowhere, a full disk) is not a peer to wait for: nothing ever releases it, and waiting cost
+  // every MCP launch 10 s (D#307). takeLock says which it is.
   let release = null;
-  for (let i = 0; i < 20 && !(release = acquireLock(lockPath)); i++) {
+  let blocked = null;
+  for (let i = 0; i < 20; i++) {
+    const taken = takeLock(lockPath);
+    release = taken.release || null;
+    blocked = taken.error || null;
+    if (release || blocked) break;
     await new Promise((r) => setTimeout(r, 500));
   }
   let verify;
@@ -137,7 +145,9 @@ try {
         ? { ok: true, action: 'verified' }
         : {
             ok: false,
-            error: `${probe.error} (another install/repair holds the lock — not rebuilding concurrently; reconnect with /mcp once it finishes)`,
+            error: blocked
+              ? `${probe.error} (install.lock cannot be taken — ${blocked.dir} cannot be written (${blocked.code}), so it was not rebuilt; \`doctor\` names the fix)`
+              : `${probe.error} (another install/repair holds the lock — not rebuilding concurrently; reconnect with /mcp once it finishes)`,
           };
     }
   } finally {