claude-mem-lite 6.25.2 → 6.26.0

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.26.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.25.2",
+      "version": "6.26.0",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.25.2",
+  "version": "6.26.0",
   "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 {