claude-mem-lite 6.25.1 → 6.25.3

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.25.1",
+      "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.1",
+  "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-shared.mjs

@@ -31,6 +31,7 @@ import {
 import { isDbUnusableError, DB_UNUSABLE_MARKER_PREFIX } from './lib/db-unusable.mjs';
 import { shouldRecordOnce } from './lib/record-once.mjs';
 import { backgroundWorkerEnv, workerDirGone } from './lib/worker-data-dir.mjs';
+import { LIVE_HOLDER_MAX_MS } from './lib/proc-lock.mjs';
 import { hookSessionId } from './lib/provenance.mjs';
 import { PROJECT_REKEY_MARKER_PREFIX } from './lib/project-rekey.mjs';
 // Audit 2026-09-05 P1-2 (carried from 2026-09-02 P2-9): `callLLM`, the quiet/adoption
@@ -67,12 +68,13 @@ export const STALE_SESSION_MS = 24 * 60 * 60 * 1000; // 24h
 export const STALE_LOCK_MS = 30000; // 30s
 
 // Backstop for cleanStaleLockFiles(): a lock whose recorded pid is ALIVE is kept until it
-// reaches this age, not STALE_LOCK_MS. Deliberately LONGER than proc-lock.mjs's own 5-min
-// steal window, so the sweeper is never the more aggressive of the two — whatever it
-// removes, the lock protocol itself would already have let the next caller steal. Its only
-// job is to garbage-collect a leaked file whose pid was recycled onto an unrelated live
-// process, which would otherwise pin the file forever. (A20260905-R5-P1-1)
-export const ABANDONED_LOCK_MS = 10 * 60 * 1000; // 10 min
+// reaches this age, not STALE_LOCK_MS. The same bound proc-lock.mjs steals a live holder's lock
+// at, so the sweeper is never the more aggressive of the two — whatever it removes, the lock
+// protocol itself would already have let the next caller steal. Its only job is to
+// garbage-collect a leaked file whose pid was recycled onto an unrelated live process, which
+// would otherwise pin the file forever. (A20260905-R5-P1-1) It was 10 min, shorter than an
+// update holds install.lock while its smoke gate builds the binding from source (D#294).
+export const ABANDONED_LOCK_MS = LIVE_HOLDER_MAX_MS;
 
 // The background-maintenance mutex, defined HERE next to the sweeper policy it has to
 // escape. cleanStaleLockFiles() sweeps every `*.lock` in RUNTIME_DIR; until
@@ -83,7 +85,8 @@ export const ABANDONED_LOCK_MS = 10 * 60 * 1000; // 10 min
 // probe, and pid checks are meaningless across a shared homedir. `tests/auto-maintain-proc-lock.test.mjs`
 // asserts that against THIS constant rather than a re-typed copy: the first version of that
 // test built its own path from a literal, so renaming the lock left it green with the hazard
-// back. proc-lock's own staleness policy (age OR provably-dead pid) is the correct one.
+// back. proc-lock's own staleness policy (a provably-dead pid at once, a live one only past
+// LIVE_HOLDER_MAX_MS) is the correct one.
 export const AUTO_MAINTAIN_LOCK = 'auto-maintain.proclock';
 export const DEDUP_WINDOW_MS = 5 * 60 * 1000; // 5 min (title dedup)
 export const RELATED_OBS_WINDOW_MS = 7 * DAY_MS; // 7 days

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();
 }
 
@@ -954,6 +958,40 @@ function retireUnresolvedBackups(targetDir, names) {
   }
 }
 
+// Backup dirs still unresolved are undone like a stack, newest first (D#293), and their order is
+// carried in the dir NAME, `.update-backup-s<seq>-<ms>-<pid>`: a swap takes one more than the
+// highest seq among the unresolved dirs it finds. Neither the wall clock in the name nor a field in
+// the journal decides it: a clock can go back, and a journal can be unreadable at the moment the
+// order is needed (a scanner holding it on Windows), which made a replay lose a file (review P2-1).
+// A dir named before 6.25.2 has no seq and reads as 0, so it comes last.
+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 {
@@ -969,8 +1007,19 @@ function unresolvedBackups(targetDir) {
 
 // The backup dir is resolved before staging goes: removing a whole staging tree takes long enough
 // for a kill to land in, and a kill there left a committed swap's journal to be replayed.
-function discardSwapDirs(stagingDir, backupDir) {
-  discardBackupDir(backupDir);
+//
+// After a rollback, `notRestored` lists what it could not put back. The backup dir then holds the
+// only copy of each, so it stays whole with its journal, unresolved, and the next entry replays it
+// (D#293). The caller used to delete it. Nothing gates a later update on it: one that commits
+// retires it, so a restore that keeps failing cannot block updates (a2cf96a1's gate did).
+function discardSwapDirs(stagingDir, backupDir, notRestored = []) {
+  if (notRestored.length === 0) discardBackupDir(backupDir);
+  else
+    debugLog(
+      'WARN',
+      'hook-update',
+      `Kept ${backupDir}: could not put back ${notRestored.join(', ')}; the next update, install or cleanup tries again`,
+    );
   try {
     rmSync(stagingDir, { recursive: true, force: true });
   } catch (e) {
@@ -978,6 +1027,18 @@ function discardSwapDirs(stagingDir, backupDir) {
   }
 }
 
+// Whether a path is there, by lstat: a symlink counts whatever it points to, and an error other
+// than "no such path" counts as there. existsSync follows the link and answers false on EACCES, so
+// a backup that was a dangling symlink read as already put back, and was deleted (review r2 F11).
+function present(p) {
+  try {
+    lstatSync(p);
+    return true;
+  } catch (e) {
+    return e.code !== 'ENOENT' && e.code !== 'ENOTDIR';
+  }
+}
+
 /**
  * Finish any swap a previous process was killed in the middle of, then clear its
  * residue. Called on every install entry, under the install lock, BEFORE a new
@@ -995,6 +1056,7 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
   }
 
   let recovered = 0;
+  const pending = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const dir = join(targetDir, entry.name);
@@ -1017,42 +1079,62 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
       recovered++;
       continue;
     }
+    pending.push(entry.name);
+  }
 
+  // Several dirs are unresolved only when a rollback could not put every file back (D#293), and
+  // 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.
+  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
     // cannot be read, or not as one (an in-place write of 6.25.0 or older torn by a kill), says
-    // nothing about what moved, and the dir may hold the only copy of it: leave it. It used to be
-    // read as "nothing moved" and deleted (v6.25.1 review). doctor and cleanup name it; the next
-    // swap that commits, or an install, retires it.
-    let journal = { backedUp: [], installed: [] };
-    let raw = null;
+    // nothing about what moved, and the dir may hold the only copy of it: leave it, and everything
+    // older with it. It used to be read as "nothing moved" and deleted (v6.25.1 review). doctor and
+    // cleanup name it; the next swap that commits, or an install, retires it.
+    let raw;
     try {
       raw = readFileSync(join(dir, SWAP_JOURNAL), 'utf8');
     } catch (e) {
-      if (e.code !== 'ENOENT') {
-        debugCatch(e, 'recover-read-journal');
+      if (e.code === 'ENOENT') {
+        discardBackupDir(dir);
+        recovered++;
         continue;
       }
+      debugCatch(e, 'recover-read-journal');
+      break;
     }
-    if (raw !== null) {
-      try {
-        journal = JSON.parse(raw);
-      } catch {
-        journal = null;
-      }
-      if (!Array.isArray(journal?.backedUp) || !Array.isArray(journal?.installed)) {
-        debugLog('WARN', 'hook-update', `Left ${entry.name} in place: its swap journal cannot be read`);
-        continue;
-      }
+    let journal;
+    try {
+      journal = JSON.parse(raw);
+    } catch {
+      journal = null;
+    }
+    if (!Array.isArray(journal?.backedUp) || !Array.isArray(journal?.installed)) {
+      debugLog(
+        'WARN',
+        'hook-update',
+        `Left ${name} in place, and any older one: its swap journal cannot be read`,
+      );
+      break;
+    }
+    const notRestored = rollbackInstall(journal.installed, journal.backedUp, dir, targetDir);
+    if (notRestored.length > 0) {
+      debugLog(
+        'WARN',
+        'hook-update',
+        `Could not finish ${name}: ${notRestored.join(', ')} not put back; left, with any older one, for the next entry`,
+      );
+      break;
     }
-    const { backedUp, installed } = journal;
-    rollbackInstall(installed, backedUp, dir, targetDir);
     discardBackupDir(dir);
     recovered++;
     debugLog(
       'WARN',
       'hook-update',
-      `Recovered an interrupted update swap: restored ${backedUp.length} path(s) from ${entry.name}`,
+      `Recovered an interrupted update swap: restored ${journal.backedUp.length} path(s) from ${name}`,
     );
   }
   return recovered;
@@ -1069,10 +1151,12 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
 // when the journal cannot be removed, the resolved marker keeps it from being replayed. A backup
 // dir 6.25.0 or older left half deleted beside its journal can still replay to a mix.
 // The arrays are copied, not reversed in place, so a caller's journal is left as it was.
+//
+// Returns the backed-up paths it could not put back, still in the backup dir (D#293).
 function rollbackInstall(installed, backedUp, backupDir, targetDir) {
   markSwapStart();
   try {
-    const restored = new Set(backedUp.filter((relPath) => !existsSync(join(backupDir, relPath))));
+    const restored = new Set(backedUp.filter((relPath) => !present(join(backupDir, relPath))));
     for (const relPath of [...installed].reverse()) {
       if (restored.has(relPath)) continue;
       try {
@@ -1085,7 +1169,7 @@ function rollbackInstall(installed, backedUp, backupDir, targetDir) {
       const backupPath = join(backupDir, relPath);
       const targetPath = join(targetDir, relPath);
       try {
-        if (existsSync(backupPath)) {
+        if (present(backupPath)) {
           mkdirSync(dirname(targetPath), { recursive: true });
           renameSync(backupPath, targetPath);
         }
@@ -1096,6 +1180,7 @@ function rollbackInstall(installed, backedUp, backupDir, targetDir) {
   } finally {
     clearSwapMarker();
   }
+  return backedUp.filter((relPath) => present(join(backupDir, relPath)));
 }
 
 // MED-5 post-install health gate: load-test the freshly-switched code in a SEPARATE
@@ -1183,18 +1268,25 @@ 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;
   }
   const ts = `${Date.now()}-${process.pid}`;
   const stagingDir = join(targetDir, `.update-staging-${ts}`);
-  const backupDir = join(targetDir, `.update-backup-${ts}`);
+  // Named once the seq is known, below; until then nothing has been written into it.
+  let backupDir = join(targetDir, `.update-backup-${ts}`);
   const backedUp = [];
   const installed = [];
   let committed = false;
@@ -1207,9 +1299,11 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     // one — otherwise this install stacks on top of a mixed-version tree and its
     // own backup can no longer restore a coherent state.
     recoverInterruptedSwaps(targetDir);
-    // What recovery left unfinished (a journal it cannot read right now) is retired if this swap
-    // commits, and left for the next entry if it rolls back.
+    // What recovery left unfinished (a journal it cannot read right now, or a replay that could not
+    // put every file back, D#293) is retired if this swap commits, and left for the next entry if it
+    // rolls back. Nothing here waits on it: a gate on it blocked every later update (a2cf96a1).
     const leftUnresolved = unresolvedBackups(targetDir);
+    backupDir = join(targetDir, `.update-backup-s${nextSwapSeq(leftUnresolved)}-${ts}`);
 
     mkdirSync(stagingDir, { recursive: true });
     mkdirSync(backupDir, { recursive: true });
@@ -1238,7 +1332,7 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
         mkdirSync(dirname(targetPath), { recursive: true });
         mkdirSync(dirname(backupPath), { recursive: true });
 
-        if (existsSync(targetPath)) {
+        if (present(targetPath)) {
           backedUp.push(relPath);
           journalSwap(backupDir, backedUp, installed);
           renameSync(targetPath, backupPath);
@@ -1257,8 +1351,7 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     // If it can't, restore the backup and report failure — the running (old) version
     // keeps working rather than leaving a broken install with no way back.
     if (!opts.skipSmoke && !smokeInstalledRelease(targetDir)) {
-      rollbackInstall(installed, backedUp, backupDir, targetDir);
-      discardSwapDirs(stagingDir, backupDir);
+      discardSwapDirs(stagingDir, backupDir, rollbackInstall(installed, backedUp, backupDir, targetDir));
       return false;
     }
 
@@ -1354,8 +1447,7 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     // Past the commit point the backups are gone and the new release IS the install: a rollback
     // would delete the paths it added and restore nothing (D#283).
     if (committed) return true;
-    rollbackInstall(installed, backedUp, backupDir, targetDir);
-    discardSwapDirs(stagingDir, backupDir);
+    discardSwapDirs(stagingDir, backupDir, rollbackInstall(installed, backedUp, backupDir, targetDir));
     return false;
   } finally {
     release();

package/hook.mjs

@@ -2287,10 +2287,12 @@ function scheduleSessionStartAutoMaintain(project) {
 // to minutes (VACUUM INTO snapshot, purge, decay, dedup over the whole DB). It now spares a
 // live holder (A20260905-R5-P1-1), but this escape stays: not being swept is a stronger
 // guarantee than being spared by a pid probe, and pids are meaningless across a shared
-// homedir. proc-lock brings its own staleness policy (age OR provably-dead pid), which is
-// the correct one here.
-// Generous upper bound on one pass; a crashed holder is normally reclaimed sooner via the
-// dead-pid check, so this only matters for a holder killed on another host.
+// homedir. proc-lock brings its own staleness policy (a provably-dead pid at once, a live one
+// only past LIVE_HOLDER_MAX_MS), which is the correct one here.
+// Since D#294 this bound applies only to a lock that records no pid, which acquireLock never
+// writes: a crashed holder is reclaimed through its dead pid, and a pid that looks alive (a
+// recycled one, or one from another host on a shared homedir) holds the lock for
+// LIVE_HOLDER_MAX_MS, 1 h, not 10 min.
 const AUTO_MAINTAIN_LOCK_STALE_MS = 10 * 60 * 1000;
 
 // Detached `auto-maintain` worker entry: opens its own DB and runs the maintenance
@@ -2448,7 +2450,8 @@ function saveHandoffAndFastSummary(
  *
  * Liveness of the two real lock families does not depend on this sweeper, so tightening it
  * cannot wedge either: hook-episode.acquireLock() preempts a >30s episode lock itself at
- * acquire time, and proc-lock.acquireLock() steals on age OR dead pid at 5 min.
+ * acquire time, and proc-lock.acquireLock() steals on a dead pid at once and on age only past
+ * LIVE_HOLDER_MAX_MS (D#294), the same bound as ABANDONED_LOCK_MS here.
  */
 function cleanStaleLockFiles() {
   try {