claude-mem-lite 3.96.1 → 3.97.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.96.1",
+      "version": "3.97.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF 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": "3.96.1",
+  "version": "3.97.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF 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-context.mjs

@@ -22,7 +22,7 @@ import {
 } from './utils.mjs';
 import {
   STALE_SESSION_MS,
-  FALLBACK_OBS_WINDOW_MS,
+  RELATED_OBS_WINDOW_MS,
   RUNTIME_DIR,
   effectiveQuiet,
   isQuietHooks,
@@ -459,7 +459,7 @@ export function buildSessionContextLines(
   let fallbackObs = [];
   if (observations.length < 3) {
     const fbOneDayAgo = now.getTime() - STALE_SESSION_MS;
-    const fbSevenDaysAgo = now.getTime() - FALLBACK_OBS_WINDOW_MS;
+    const fbSevenDaysAgo = now.getTime() - RELATED_OBS_WINDOW_MS;
     fallbackObs = db
       .prepare(
         `

package/hook-shared.mjs

@@ -54,18 +54,27 @@ export const SESSION_EXPIRY_MS = 12 * 60 * 60 * 1000; // 12h
 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
+
 // The background-maintenance mutex, defined HERE next to the sweeper policy it has to
-// escape. cleanStaleLockFiles() below unlinks any `*.lock` older than STALE_LOCK_MS
-// WITHOUT checking whether the holder is alive — right for the episode lock's millisecond
-// critical section, fatal for a maintenance pass that runs for seconds to minutes. The
-// name therefore ends in `.proclock`, and `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
+// escape. cleanStaleLockFiles() sweeps every `*.lock` in RUNTIME_DIR; until
+// A20260905-R5-P1-1 it did so on AGE ALONE once past STALE_LOCK_MS — right for the episode
+// lock's millisecond critical section, fatal for a maintenance pass that runs for seconds
+// to minutes. The sweeper now spares a live holder, but this mutex keeps the `.proclock`
+// name: not being swept at all is a stronger guarantee than being spared by a liveness
+// 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.
 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
-export const FALLBACK_OBS_WINDOW_MS = RELATED_OBS_WINDOW_MS; // same window
 // Candidate rows the SessionStart Key Context surface considers (hook-context.mjs
 // keyObs; each of the two sections then renders at most 5). The user-prompt
 // exclude-set does NOT mirror this query — it reads the ids actually rendered

package/hook-update.mjs

@@ -16,6 +16,7 @@ import {
   rmSync,
   renameSync,
   chmodSync,
+  realpathSync,
 } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -1294,6 +1295,19 @@ export function clearCacheHookResidue() {
 // ── Plugin Cache Pruning ──────────────────────────────────
 const PLUGIN_CACHE_KEEP = 3;
 
+/**
+ * Same-directory test that survives trailing slashes, `..` segments and symlinks.
+ * realpathSync throws on a path that no longer exists → fall back to lexical resolve.
+ */
+function isSameDir(a, b) {
+  if (!a || !b) return false;
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return resolve(a) === resolve(b);
+  }
+}
+
 export function prunePluginCache() {
   const cacheBase = join(homedir(), '.claude', 'plugins', 'cache', 'sdsrss', 'claude-mem-lite');
   if (!existsSync(cacheBase)) return 0;
@@ -1304,11 +1318,20 @@ export function prunePluginCache() {
 
   if (entries.length <= PLUGIN_CACHE_KEEP) return 0;
 
+  // A20260905-R5-Q1: "not in the newest 3" is not the same question as "not in use".
+  // CLAUDE_PLUGIN_ROOT is the version dir THIS process was launched from, and after a
+  // marketplace rollback (a bad release withdrawn while >=3 newer dirs are already cached)
+  // it is not among the newest 3 — so keep-latest-3 rm -rf'd the tree the running hooks and
+  // MCP server import from. scripts/setup.sh step 8 carries the same guard for the same
+  // reason; the two prune the same directory and must agree.
+  const runningRoot = process.env.CLAUDE_PLUGIN_ROOT;
   const toRemove = entries.slice(PLUGIN_CACHE_KEEP);
   let removed = 0;
   for (const ver of toRemove) {
+    const dir = join(cacheBase, ver);
+    if (isSameDir(dir, runningRoot)) continue;
     try {
-      rmSync(join(cacheBase, ver), { recursive: true, force: true });
+      rmSync(dir, { recursive: true, force: true });
       removed++;
     } catch {}
   }

package/hook.mjs

@@ -70,6 +70,7 @@ import {
   SESSION_EXPIRY_MS,
   STALE_SESSION_MS,
   STALE_LOCK_MS,
+  ABANDONED_LOCK_MS,
   AUTO_MAINTAIN_LOCK,
   STALE_EPISODE_BUFFER_AGE_MS,
   HANDOFF_EXPIRY_CLEAR,
@@ -1945,14 +1946,15 @@ function scheduleSessionStartAutoMaintain(project) {
   if (!process.env.CLAUDE_MEM_SKIP_MAINTAIN) spawnBackground('auto-maintain', project);
 }
 
-// The maintenance mutex deliberately does NOT end in `.lock`: cleanStaleLockFiles()
-// below unlinks every `*.lock` in RUNTIME_DIR whose age exceeds STALE_LOCK_MS (30s)
-// WITHOUT consulting the holder's pid — a policy written for the episode lock, whose
-// critical section is milliseconds. A maintenance pass is seconds to minutes (VACUUM INTO
-// snapshot, purge, decay, dedup over the whole DB), so that sweeper would strip this lock
-// mid-pass and hand the exclusion straight back to the race it exists to close.
-// proc-lock brings its own staleness policy (age OR provably-dead pid), which is the
-// correct one here.
+// The maintenance mutex deliberately does NOT end in `.lock`, so cleanStaleLockFiles()
+// below never sees it at all. That sweeper used to unlink every `*.lock` past
+// STALE_LOCK_MS (30s) without consulting the holder's pid — a policy written for the
+// episode lock, whose critical section is milliseconds — and a maintenance pass is seconds
+// 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.
 const AUTO_MAINTAIN_LOCK_STALE_MS = 10 * 60 * 1000;
@@ -2078,8 +2080,29 @@ function saveHandoffAndFastSummary(
   }
 }
 
+/**
+ * Sweep abandoned `*.lock` files out of RUNTIME_DIR on SessionStart.
+ *
+ * "Stale" has to mean ABANDONED, not merely old. Until A20260905-R5-P1-1 this swept on AGE
+ * ALONE (pid was consulted only for locks YOUNGER than STALE_LOCK_MS, i.e. exactly the ones
+ * it was going to keep anyway), so a lock older than 30s was unlinked no matter who held it.
+ * `runtime/install.lock` — lib/proc-lock.mjs, taken by `install.mjs repair`,
+ * `install.mjs rebuild-binding`, hook-update.installExtractedRelease and scripts/launch.mjs —
+ * guards a critical section that routinely runs 30s–2min (npm install in staging is capped at
+ * 60s, npm rebuild in smoke at 120s). Any parallel Claude Code window starting up during that
+ * span deleted the live holder's lock; the next installer then acquired it and began renaming
+ * files into the same install dir, which is the torn mixed-version install (server vN + hook
+ * vN+1) proc-lock.mjs's header exists to prevent.
+ *
+ * Policy now: a recorded pid that is ALIVE (or alive-but-not-ours, EPERM) is spared until
+ * ABANDONED_LOCK_MS; a provably-dead pid (ESRCH) is swept at any age; a lock with no usable
+ * pid falls back to STALE_LOCK_MS, as before.
+ *
+ * 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.
+ */
 function cleanStaleLockFiles() {
-  // Clean stale lock files in runtime dir
   try {
     for (const f of readdirSync(RUNTIME_DIR)) {
       if (!f.endsWith('.lock')) continue;
@@ -2089,12 +2112,16 @@ function cleanStaleLockFiles() {
         const info = JSON.parse(raw);
         const age = Date.now() - (info.ts || 0);
         let stale = age > STALE_LOCK_MS;
-        if (!stale && info.pid) {
+        if (info.pid) {
+          let alive = false;
           try {
             process.kill(info.pid, 0);
+            alive = true;
           } catch (killErr) {
-            stale = killErr.code === 'ESRCH';
+            // EPERM = the process exists but belongs to another user — still a live holder.
+            alive = killErr.code === 'EPERM';
           }
+          stale = alive ? age > ABANDONED_LOCK_MS : true;
         }
         if (stale) unlinkSync(lp);
       } catch {

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.96.1",
+  "version": "3.97.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.96.1",
+      "version": "3.97.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.30.0",
         "better-sqlite3": "^12.11.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.96.1",
+  "version": "3.97.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF 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/hook-launcher.mjs

@@ -14,7 +14,9 @@
 // dir) or a missing bare dependency like better-sqlite3 (e.url is undefined and
 // the importer named in the message is under the install dir) — run
 // `install.mjs repair` (rate-limited via a 6h marker file under runtime/) and
-// retry the import once. If repair is unavailable or fails, degrade quietly:
+// retry the import once. That repair runs at SESSION-START ONLY; every other
+// event records the breakage and defers (A20260905-R5-Q2, see attemptHeal).
+// If repair is unavailable, deferred or fails, degrade quietly:
 // these are best-effort memory hooks, so a broken/missing dependency emits one
 // clean recovery line and exits 0 rather than dumping a Node stack trace on
 // every fire. On any other (foreign) exception, re-throw so Node's default
@@ -272,6 +274,37 @@ function clearBreakage() {
   }
 }
 
+// Hot-path counterpart of attemptHeal (A20260905-R5-Q2).
+//
+// attemptHeal() runs `install.mjs repair` SYNCHRONOUSLY with a 300s timeout. The events
+// this launcher fires on cannot host that: hooks/hooks.json gives PreToolUse 3s,
+// PostToolUse 3s, UserPromptSubmit 2s, Stop and PreCompact 5s — only SessionStart's 15s is
+// in the same order of magnitude as an npm run. Worse than being killed: recordHealAttempt()
+// arms the 6h cooldown BEFORE the spawn, deliberately, as concurrent-fire rate limiting (see
+// clearHealMarker below). So a repair the host killed at 2s still bought six hours of
+// "Self-heal skipped" — including for the SessionStart fire that had the budget to finish it.
+// The hot path now records the breakage for `doctor` and gets out of the way.
+//
+// This is the same rule healNativeBindingIfBroken() below already follows, for the same
+// reason ("never on the per-tool hot path, where an npm run would stall the user's edit").
+//
+// Do NOT "fix" the cooldown by moving recordHealAttempt() after the spawn instead: that is
+// the mutual-exclusion between concurrent fires, and the R5 report's first suggestion.
+//
+// Known gap this does NOT close, because it was already open: if the missing module sits on
+// a DIFFERENT entry's import chain and session-start's own entry imports cleanly, nothing
+// heals — a clean session-start clears the breakage marker without repairing. Narrow in
+// practice (hook.mjs imports most of lib/), and closing it needs a detached, stdio-ignored
+// spawn like the native-binding path, not this one.
+function deferHealToSessionStart(reason) {
+  process.stderr.write(
+    `[claude-mem-lite] Broken install (${reason}) — self-heal deferred to the next SessionStart ` +
+      `(this hook has a 2-5s budget; repair needs minutes).\n` +
+      `[claude-mem-lite] Manual recovery: ${CLI_REPAIR}\n`,
+  );
+  return false;
+}
+
 async function attemptHeal(reason) {
   if (recentHealAttempt()) {
     process.stderr.write(
@@ -298,6 +331,64 @@ async function attemptHeal(reason) {
   return result.status === 0;
 }
 
+// Session-start heal driven by the BREAKAGE MARKER rather than by our own failed import
+// (A20260905-R5-Q2, second half).
+//
+// Since the heal moved off the hot path, a hot-path fire that hits a missing module records
+// the breakage and defers. But this launcher fronts several entries — hook.mjs plus
+// pre-tool-recall.js, pre-skill-bridge.js, post-tool-recall.js, user-prompt-search.js — and
+// the missing module may sit on one of THEIR import chains and not on hook.mjs's. Then
+// session-start's own entry imports cleanly, the catch below never fires, and before this
+// function existed the clean fire simply cleared the marker: nothing ever repaired it. (That
+// gap predates the hot-path gate — a clean session-start always cleared the marker — but the
+// gate is what makes it the ONLY remaining route, so it is closed here.)
+//
+// DETACHED with stdio ignored, exactly like healNativeBindingIfBroken() below and for the
+// same two reasons: the fire is capped at 15s while `install.mjs repair` can take minutes,
+// and install.mjs logs to STDOUT while SessionStart stdout is a JSON envelope Claude Code
+// parses. That is also why this cannot reuse attemptHeal(), whose spawn is synchronous and
+// inherits stdio — correct where the entry failed and nothing has been written yet, wrong
+// here, where runEntry() has already emitted the envelope.
+//
+// Marker bookkeeping, and why it differs from the native-binding path: `install.mjs repair`
+// does not know about `hook-launcher-broken` (only doctor reads it, only this file writes
+// it), so no child can clear it on our behalf. Clearing it here after spawning keeps
+// `doctor` honest — a repair that did not take is re-recorded by the very next failing fire
+// — while the 6h cooldown, not the marker, is what bounds repair spawns to one per window.
+// Within that window the marker is deliberately left in place so doctor still reports the
+// unrepaired breakage.
+function healRecordedBreakage() {
+  try {
+    if (!existsSync(BROKEN_MARKER)) {
+      // No fire has recorded a degraded exit since the last session-start → as healthy as
+      // this launcher can tell. Drop a stale cooldown so a LATER unrelated break heals
+      // immediately rather than waiting out a window earned by an old fault. (#6/#9)
+      clearHealMarker();
+      return;
+    }
+    if (recentHealAttempt()) return; // on cooldown — keep the marker, doctor should see it
+    const installer = join(INSTALL_DIR, 'install.mjs');
+    if (!existsSync(installer)) {
+      process.stderr.write(
+        `[claude-mem-lite] A hook fire degraded to exit 0 and install.mjs is missing — ${TARBALL_FALLBACK}\n`,
+      );
+      return;
+    }
+    recordHealAttempt();
+    process.stderr.write(
+      '[claude-mem-lite] A previous hook fire degraded to exit 0 — repairing in the background\n',
+    );
+    const child = spawn(process.execPath, [installer, 'repair'], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    clearBreakage();
+  } catch {
+    /* best-effort — a heal failure must never stop the fire */
+  }
+}
+
 // Defense-in-depth for plugin-mode version drift: the plugin-cache MCP server
 // (kept current by Claude Code) migrates the shared DB schema forward, while
 // this data-dir code (the standalone CLI + these hooks) is only advanced by the
@@ -398,9 +489,12 @@ if (IS_SESSION_START) {
 
 try {
   await runEntry();
-  // A clean session-start fire confirms the install is healthy → clear any stale
-  // breakage marker. Gated to session-start so the per-tool hot path pays nothing.
-  if (IS_SESSION_START) clearBreakage();
+  // Our entry imported cleanly, but that is NOT the same as "the install is whole": this
+  // launcher fronts five entries and the missing module may be on another one's chain. So
+  // act on the recorded breakage instead of just clearing it — background repair if there is
+  // one to do, clear either way. Gated to session-start so the hot path pays nothing.
+  // (Was an unconditional clearBreakage(); A20260905-R5-Q2.)
+  if (IS_SESSION_START) healRecordedBreakage();
   // After the entry too: the fire that DISCOVERS the breakage is the one that
   // records it, so a pre-entry-only check would leave the whole session dead and
   // heal one session late.
@@ -408,7 +502,7 @@ try {
 } catch (e) {
   if (!isLocalModuleErr(e)) throw e;
   const reason = describeFailure(e);
-  const healed = await attemptHeal(reason);
+  const healed = IS_SESSION_START ? await attemptHeal(reason) : deferHealToSessionStart(reason);
   if (!healed) {
     // Broken/missing dependency we can't repair right now (repair failed, or
     // was skipped within the 6h cooldown). attemptHeal already wrote actionable

package/scripts/setup.sh

@@ -248,10 +248,25 @@ if [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
     done < <(for _d in "${_all_dirs[@]}"; do [[ -d "$_d" ]] && echo "${_d##*/}"; done | sort -t. -k1,1nr -k2,2nr -k3,3nr | tail -n +4)
     unset _all_dirs _d
     if [[ ${#OLD_VERS[@]} -gt 0 ]]; then
+      PRUNED=0
       for ver in "${OLD_VERS[@]}"; do
+        # A20260905-R5-Q1: "not in the newest 3" is not the same question as "not in use".
+        # CLAUDE_PLUGIN_ROOT is the version dir this session is RUNNING from, and after a
+        # marketplace rollback (a bad release withdrawn while >=3 newer dirs sit in the
+        # cache) it falls outside the newest 3 — so this loop deleted the tree every hook
+        # and the MCP server import from, mid-session. -ef compares device+inode, so it is
+        # not fooled by a trailing slash, a `..` segment or a symlinked cache dir.
+        # hook-update.mjs prunePluginCache() carries the same guard; the two prune the same
+        # directory and must agree.
+        if [[ "$CACHE_DIR/$ver" -ef "$CLAUDE_PLUGIN_ROOT" ]]; then
+          continue
+        fi
         rm -rf "${CACHE_DIR:?}/$ver" 2>/dev/null || true
+        PRUNED=$((PRUNED + 1))
       done
-      log_ok "Plugin cache pruned: removed ${#OLD_VERS[@]} old version(s)"
+      if [[ $PRUNED -gt 0 ]]; then
+        log_ok "Plugin cache pruned: removed $PRUNED old version(s)"
+      fi
     fi
   fi
 fi