claude-mem-lite 3.59.1 → 3.60.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.59.1",
+      "version": "3.60.1",
       "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.59.1",
+  "version": "3.60.1",
   "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/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 const CLI_COMMANDS = new Set(['search', 'recent', 'recall', 'get', 'timeline', 'save', 'stats', 'context', 'browse', 'citation-stats', 'delete', 'update', 'export', 'restore', 'compress', 'maintain', 'optimize', 'fts-check', 'registry', 'import', 'import-jsonl', 'enrich', 'activity', 'adopt', 'unadopt', 'memdir-audit', 'defer', 'help']);
-const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'repair', 'release']);
+const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'repair', 'rebuild-binding', 'release']);
 
 const cmd = process.argv[2];
 

package/install.mjs

@@ -40,7 +40,8 @@ const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 import { RESOURCE_METADATA } from './install-metadata.mjs';
 import { scanPluginCacheHookPollution } from './plugin-cache-guard.mjs';
 import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
-import { probeBetterSqlite3Binding, ensureBetterSqlite3Working } from './lib/binding-probe.mjs';
+import { probeBetterSqlite3Binding, probeBindingInFreshProcess, ensureBetterSqlite3Working, NATIVE_BINDING_REBUILD_CMD } from './lib/binding-probe.mjs';
+import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
 import { acquireLock } from './lib/proc-lock.mjs';
 import { atomicWriteFileSync } from './lib/atomic-write.mjs';
@@ -1395,14 +1396,17 @@ async function doctor() {
     issues++;
   }
 
-  // Dependencies
-  try {
-    const Database = (await import('better-sqlite3')).default;
-    const probe = new Database(':memory:');
-    probe.close();
+  // Dependencies. Out of process: an in-process open of a STALE .node caches a
+  // dead module handle for the rest of doctor and can SIGSEGV on teardown —
+  // truncating the report of the very run the user started because things are
+  // broken. This is also what makes the native-binding check further down
+  // (which reads the same tree) honest rather than answering from a poisoned
+  // process.
+  const depProbe = probeBindingInFreshProcess(bindingHostDir());
+  if (depProbe.ok) {
     ok('better-sqlite3: verified (import + open OK)');
-  } catch (e) {
-    fail(`better-sqlite3: import/init failed (${e.message})`);
+  } else {
+    fail(`better-sqlite3: import/init failed (${String(depProbe.error).split('\n')[0]})`);
     issues++;
   }
 
@@ -1447,6 +1451,25 @@ async function doctor() {
     ok('Hook self-heal: no recent silent hook breakage');
   }
 
+  // Native DB binding. Two signals, because they answer different questions:
+  // the marker says "hooks have been failing" (possibly for days, since the hint
+  // is 6h-rate-limited stderr nobody reads), the live probe says "is it broken
+  // right now". A Node upgrade breaks every DB-touching path at once, so this is
+  // the single highest-value line in doctor when it fires.
+  const breakage = readNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
+  // Reuses the dependency probe above — same tree, same question, and doctor
+  // should not pay for two child spawns to ask it twice.
+  const bindingProbe = depProbe;
+  if (!bindingProbe.ok) {
+    fail(`Native DB binding: unusable (${String(bindingProbe.error).split('\n')[0]}) — run \`node ${join(PROJECT_DIR, 'cli.mjs')} rebuild-binding\``);
+    issues++;
+  } else if (breakage) {
+    const ageH = Math.round((Date.now() - (breakage.ts || 0)) / 3600000);
+    dwarn(`Native DB binding: healthy now, but a fire failed ~${ageH}h ago (${breakage.reason || 'unknown'}) — stale marker clears on the next successful rebuild-binding`);
+  } else {
+    ok(`Native DB binding: loadable on Node ${process.version}`);
+  }
+
   // Plugin/hook lifecycle state
   const settings = readSettings();
   const hasHooks = hasMemHooksConfigured(settings);
@@ -2129,6 +2152,51 @@ function regenerateLockfile() {
 
 // ─── Main ───────────────────────────────────────────────────────────────────
 
+// An install can own MORE THAN ONE better-sqlite3 tree (dev repo, ~/.claude-mem-lite,
+// the plugin cache), each with its own .node — and only the one the RUNNING code
+// resolves matters, i.e. the one next to this file. Rebuilding the wrong tree
+// reports success while every hook keeps failing. Fall back to INSTALL_DIR when
+// this file sits in a source-only layout with no deps of its own.
+function bindingHostDir() {
+  return existsSync(join(PROJECT_DIR, 'node_modules', 'better-sqlite3')) ? PROJECT_DIR : INSTALL_DIR;
+}
+
+// Local, network-free repair for an unusable native DB binding — the Node-upgrade
+// fault (ABI 127 → 137) that `repair` is the wrong size for: repair re-downloads
+// and signature-verifies a whole GitHub release and fails closed offline, while
+// this recompiles one module in place. Named in the hook hint, run unattended by
+// scripts/hook-launcher.mjs at session-start, and usable by hand.
+//
+// Takes the same install.lock as the install write phase and launch.mjs's rebuild:
+// 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 host = bindingHostDir();
+  const release = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock'));
+  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.');
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const verify = await ensureBetterSqlite3Working(host);
+    if (verify.ok) {
+      ok(`better-sqlite3 binding ${verify.action} for Node ${process.version} (${host})`);
+      // The fault is gone → drop the marker so session-start stops retrying.
+      clearNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
+    } else {
+      fail(`better-sqlite3 binding still unusable: ${verify.error}`);
+      log(`Try manually: cd ${host} && ${NATIVE_BINDING_REBUILD_CMD}`);
+      process.exitCode = 1;
+    }
+  } finally {
+    release();
+  }
+}
+
 // Cross-process gate around the install write phase. repair() is intentionally
 // NOT locked here: it spawns `install.mjs install` as a child, which takes this
 // lock — locking the parent too would deadlock. A live peer (another session's
@@ -2173,6 +2241,9 @@ export async function main(argv = process.argv.slice(2)) {
     case 'repair':
       await repair();
       break;
+    case 'rebuild-binding':
+      await rebuildBinding();
+      break;
     case 'release':
       syncVersions();
       if (!flags.has('--no-lock')) regenerateLockfile();
@@ -2203,6 +2274,7 @@ Usage:
   node install.mjs cleanup-hooks      Remove only claude-mem-lite hooks from settings.json
   node install.mjs self-update         Check for and install updates
   node install.mjs repair             Recover a broken install: download latest tarball, re-run install
+  node install.mjs rebuild-binding    Recompile better-sqlite3 for the running Node (fixes "NODE_MODULE_VERSION" after a Node upgrade)
   node install.mjs release            Sync versions (plugin/marketplace/CLAUDE.md) + regen lockfile via npm@10.9.2 (use --no-lock to skip lock regen)
 
   npx claude-mem-lite                 Install via npx (one-liner)

package/lib/binding-probe.mjs

@@ -6,10 +6,51 @@
 // Node v24), and the presence of node_modules/better-sqlite3/ on disk is not
 // sufficient — the binding can be present-but-stale after a Node upgrade.
 
-import { execSync } from 'node:child_process';
+import { execSync, spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 
+// npm >= 12 blocks lifecycle scripts by default, so a plain `npm rebuild` exits 0
+// WITHOUT compiling — see the rebuild() comment below. Single home for the one
+// command that actually works, so hints, docs and heal paths cannot drift apart.
+export const NATIVE_BINDING_REBUILD_CMD = 'npm rebuild better-sqlite3 --dangerously-allow-all-scripts';
+
+// 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:
+//   • 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
+//   • 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)
+// Deliberately NARROW: a rebuild cannot fix DB corruption or a missing data dir,
+// and misclassifying those would burn a 30s npm run on every fire.
+const NATIVE_BINDING_PATTERNS = [
+  /NODE_MODULE_VERSION/,
+  /Could not locate the bindings file/i,
+  /did not self-register/i,
+  /invalid ELF header/i,
+];
+
+/**
+ * True when `err` means "the better-sqlite3 native binding is unusable and a
+ * rebuild is the right repair".
+ *
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isNativeBindingError(err) {
+  if (!err) return false;
+  if (err.code === 'ERR_DLOPEN_FAILED') return true;
+  // `err ?? ''` covers a thrown STRING: recordHookError accepts any thrown value
+  // and already normalizes that shape for its log, so the classifier must not
+  // silently read undefined and miss it.
+  const msg = String(err.message ?? err ?? '');
+  return NATIVE_BINDING_PATTERNS.some((re) => re.test(msg));
+}
+
 /**
  * Probe better-sqlite3's native binding by importing it from `installDir`'s
  * node_modules and opening an in-memory DB. Returns {ok, error?}.
@@ -29,21 +70,95 @@ export async function probeBetterSqlite3Binding(installDir) {
   }
 }
 
+/**
+ * Probe the binding from a FRESH child process.
+ *
+ * Why this exists: better-sqlite3 dlopen's its .node lazily and Node caches the
+ * module handle process-wide, so a process that has already touched a STALE
+ * binary can never load its replacement — the retry dies with "Module did not
+ * self-register" (and, under scripts/setup.sh's probe, a segfault on the way
+ * out). Verifying a freshly rebuilt binding therefore has to happen somewhere
+ * that never saw the old one. Same constraint healAndReexec re-execs for.
+ *
+ * Synchronous (spawnSync) to match the surrounding execSync rebuild — this runs
+ * in installers and hook-adjacent scripts, never on a request path.
+ *
+ * @param {string} installDir Directory containing node_modules/better-sqlite3
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {{ok: true} | {ok: false, error: string}}
+ */
+export function probeBindingInFreshProcess(installDir, { timeoutMs = 30_000 } = {}) {
+  // The child catches and prints the MESSAGE on its own stdout. Two reasons it
+  // is not just an uncaught throw read off stderr: an uncaught exception's first
+  // stderr line is the stack HEADER (`node:internal/modules/cjs/loader:1520`),
+  // not the diagnostic — and this string is the highest-value line `doctor`
+  // prints — and any node warning emitted before the throw would land on stderr
+  // first and hijack it. The child's stdout is captured by spawnSync and never
+  // inherited, so writing there cannot reach a hook's JSON envelope.
+  // installDir is interpolated as a JSON string literal, so a path containing
+  // quotes/backslashes cannot break out of the script.
+  const script =
+    'try {'
+    + 'const { createRequire } = require("node:module");'
+    + `const D = createRequire(${JSON.stringify(join(installDir, 'package.json'))})("better-sqlite3");`
+    + 'new D(":memory:").close();'
+    + '} catch (e) { process.stdout.write(String((e && e.message) || e)); process.exit(1); }';
+  const r = spawnSync(process.execPath, ['-e', script], { stdio: 'pipe', timeout: timeoutMs });
+  // BEFORE the status check: spawnSync's `timeout` is SIGTERM-then-wait, not a
+  // deadline, so a child that survives the signal can still exit 0 while
+  // r.error is ETIMEDOUT. Reading status alone would call that healthy.
+  if (r.error) return { ok: false, error: r.error.message };
+  if (r.status === 0) return { ok: true };
+  // Fallbacks cover the paths where the catch never ran: a native crash (the
+  // SIGSEGV above) or a failure to spawn at all — both leave stdout empty.
+  const printed = String(r.stdout || '').trim();
+  const stderrLine = String(r.stderr || '').split('\n').map((l) => l.trim()).find(Boolean);
+  return {
+    ok: false,
+    error: printed
+      || stderrLine
+      || `binding probe exited ${r.status ?? `on signal ${r.signal}`}`,
+  };
+}
+
 /**
  * Verify better-sqlite3 binding works in `installDir`; if not, run
  * `npm rebuild better-sqlite3` and re-probe. Returns
  * { ok: true, action: 'verified' | 'rebuilt' } on success or
- * { ok: false, error } if rebuild can't fix it. The `probe` and `rebuild`
- * deps are injectable so this can be unit-tested without a real npm
+ * { ok: false, error } if rebuild can't fix it. The `probe`, `verify` and
+ * `rebuild` deps are injectable so this can be unit-tested without a real npm
  * subprocess.
  *
  * @param {string} installDir Directory containing node_modules/better-sqlite3
- * @param {{probe?: () => Promise<{ok: boolean, error?: string}>, rebuild?: () => Promise<void>, exec?: (cmd: string, opts: object) => void}} [deps]
+ * @param {{probe?: () => Promise<{ok: boolean, error?: string}>, verify?: () => Promise<{ok: boolean, error?: string}> | {ok: boolean, error?: string}, rebuild?: () => Promise<void>, exec?: (cmd: string, opts: object) => void}} [deps]
  * @returns {Promise<{ok: true, action: 'verified' | 'rebuilt'} | {ok: false, error: string}>}
  */
 export async function ensureBetterSqlite3Working(installDir, deps = {}) {
-  const probe = deps.probe || (() => probeBetterSqlite3Binding(installDir));
-  const exec = deps.exec || execSync;
+  // BOTH probes run out of process by default, because a probe must never
+  // poison the process that has to act on its answer. Loading a stale .node
+  // caches a dead module handle process-wide (and can SIGSEGV on teardown), so
+  // an in-process probe→rebuild→re-probe cycle always ends in "Module did not
+  // self-register" — reporting a SUCCESSFUL rebuild as a failure. Measured
+  // 2026-08-13 on a real ABI 127-under-137 tree: this function returned
+  // {ok:false} while the rebuilt .node loaded fine in a fresh process. Every
+  // caller keyed state on that lie — setup.sh wrote .deps-broken over a healthy
+  // install, install.mjs::rebuildBinding skipped clearNativeBindingBreakage so
+  // the launcher re-spawned npm every 6h forever, and `rebuild-binding` exited 1.
+  //
+  // Isolating only the SECOND probe is not enough: scripts/launch.mjs imports
+  // the MCP server into this very process right after a successful rebuild, so a
+  // first probe that dlopened the stale binary would hand the server the dead
+  // handle. Cost is one ~40ms spawn on a path that already runs npm.
+  //
+  // `deps.probe` alone still drives BOTH probes: injected-stub tests keep their
+  // existing semantics.
+  const probe = deps.probe || (() => probeBindingInFreshProcess(installDir));
+  const verify = deps.verify || deps.probe || (() => probeBindingInFreshProcess(installDir));
+  // Bounded by default: a node-gyp fallback that stalls (no compiler, a hung
+  // registry fetch) must not hang the caller forever — the CLI blocks a user at
+  // the terminal, and scripts/setup.sh passes an even tighter 20s cap because it
+  // runs under a hook timeout. Callers needing a different budget inject `exec`.
+  const exec = deps.exec || ((cmd, opts) => execSync(cmd, { timeout: 240_000, ...opts }));
   const rebuild = deps.rebuild || (async () => {
     // npm >= 12 blocks install/lifecycle scripts by default (the `allow-scripts`
     // allowlist ships empty). better-sqlite3's install step
@@ -57,7 +172,7 @@ export async function ensureBetterSqlite3Working(installDir, deps = {}) {
     // npm has no such gate and treats the unknown flag as an ignored config; if
     // it instead errors on the flag, fall back to the plain rebuild.
     try {
-      exec('npm rebuild better-sqlite3 --dangerously-allow-all-scripts', { cwd: installDir, stdio: 'pipe' });
+      exec(NATIVE_BINDING_REBUILD_CMD, { cwd: installDir, stdio: 'pipe' });
     } catch {
       exec('npm rebuild better-sqlite3', { cwd: installDir, stdio: 'pipe' });
     }
@@ -72,8 +187,51 @@ export async function ensureBetterSqlite3Working(installDir, deps = {}) {
     return { ok: false, error: `rebuild failed: ${e.message}` };
   }
 
-  const second = await probe();
+  const second = await verify();
   if (second.ok) return { ok: true, action: 'rebuilt' };
 
   return { ok: false, error: second.error || first.error };
 }
+
+/**
+ * Foreground heal for a user-invoked process (the CLI): rebuild the binding,
+ * then RE-EXEC this process with its original argv and return the child's exit
+ * code. The re-exec is not a convenience — better-sqlite3 dlopen's its .node
+ * lazily and caches the handle, so a process that has already hit the stale
+ * binary cannot use the fresh one: retrying in-process fails with "Module did
+ * not self-register" (observed 2026-08-13 while healing this exact fault).
+ *
+ * Refuses to act when the guard env is already set, so a heal that does not
+ * actually fix the binding cannot spawn an unbounded chain of children.
+ *
+ * @param {{installDir?: string, argv?: string[], env?: Record<string,string|undefined>, ensure?: () => Promise<{ok: boolean, action?: string, error?: string}>, reexec?: (argv: string[], env: Record<string,string|undefined>) => number, log?: (msg: string) => void}} opts
+ * @returns {Promise<{healed: true, exitCode: number} | {healed: false, reason: string, error?: string}>}
+ */
+export async function healAndReexec(opts) {
+  const {
+    installDir,
+    argv = process.argv,
+    env = process.env,
+    log = () => {},
+  } = opts;
+  const ensure = opts.ensure || (() => ensureBetterSqlite3Working(installDir));
+  const reexec = opts.reexec || ((childArgv, childEnv) => {
+    const r = spawnSync(childArgv[0], childArgv.slice(1), { stdio: 'inherit', env: childEnv });
+    return typeof r.status === 'number' ? r.status : 1;
+  });
+
+  if (env[BINDING_HEAL_GUARD_ENV]) return { healed: false, reason: 'already-attempted' };
+
+  log(`native DB binding unusable — rebuilding for this Node (${process.version})…`);
+  let verify;
+  try {
+    verify = await ensure();
+  } catch (e) {
+    return { healed: false, reason: 'rebuild-failed', error: e.message };
+  }
+  if (!verify.ok) return { healed: false, reason: 'rebuild-failed', error: verify.error };
+
+  log('binding rebuilt — retrying');
+  const exitCode = reexec(argv, { ...env, [BINDING_HEAL_GUARD_ENV]: '1' });
+  return { healed: true, exitCode };
+}

package/lib/hook-telemetry.mjs

@@ -20,6 +20,11 @@
 
 import { appendFileSync, mkdirSync, existsSync, readdirSync, readFileSync, statSync, unlinkSync } from 'fs';
 import { join } from 'path';
+// Both are pure-`node:`-static modules (better-sqlite3 is only createRequire'd
+// lazily inside binding-probe's functions), so this keeps the "usable from the
+// lightweight standalone scripts" property stated above.
+import { isNativeBindingError } from './binding-probe.mjs';
+import { recordNativeBindingBreakage } from './native-binding-hint.mjs';
 
 const DAY_MS = 86400000;
 const RETENTION_MS = 14 * DAY_MS;
@@ -82,6 +87,18 @@ export function recordHookError(scope, err, runtimeDir, ctx) {
     appendFileSync(join(dir, `${today()}.jsonl`), line, { mode: 0o600 });
     // Amortized retention sweep: 14-day window kept clean without a cron.
     pruneOldShards(dir);
+
+    // Every hook script funnels its failures through here — including the
+    // STANDALONE ones (scripts/pre-tool-recall.js, scripts/pre-skill-bridge.js)
+    // that never import hook.mjs and so never reach its dispatch catch. That gap
+    // is why the 2026-08-13 outage stayed invisible: 78 of that day's 79 entries
+    // were `pre-recall:db-open`, i.e. the ONE path whose errors nothing but this
+    // log could see. Flagging the native-binding family here — rather than at
+    // each call site — is what makes the session-start heal fire no matter which
+    // script hits the stale binding first.
+    if (isNativeBindingError(err)) {
+      recordNativeBindingBreakage(runtimeDir, { reason: String(err?.message ?? err ?? ''), event: String(scope || '') });
+    }
   } catch { /* recorder must never throw */ }
 }
 

package/lib/native-binding-hint.mjs

@@ -16,20 +16,33 @@
 //     run `npm rebuild` itself (2–5s timeout + concurrent-fire races).
 //
 // Pure node: imports + injectable now/runtimeDir so it unit-tests without the
-// hook dependency graph (no schema.mjs / better-sqlite3 import).
+// hook dependency graph (no schema.mjs / better-sqlite3 import). The one non-node:
+// import — lib/binding-probe.mjs for the shared fault classifier — keeps that
+// property: it only `createRequire`s better-sqlite3 lazily inside its functions,
+// so importing it never dlopen's the very binding this module reports on.
 
 import { join } from 'node:path';
-import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { isNativeBindingError } from './binding-probe.mjs';
 
 export const NATIVE_BINDING_HINT_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6h
 const MARKER_NAME = 'native-binding-hint-last';
 
-// Resolvable invocation of the bundled CLI's repair path. Absolute via
+// Breakage marker read by scripts/hook-launcher.mjs at session-start to trigger
+// the unattended rebuild. The hint alone was NOT enough: it goes to hook stderr,
+// is rate-limited to once per 6h, and in the field (2026-08-13) a Node 22 → 24
+// upgrade left the binding stale for 4 days across 79 failed fires because the
+// only healer was the MCP-server launch path, which those sessions never ran.
+export const NATIVE_BINDING_BROKEN_MARKER = 'native-binding-broken';
+
+// Resolvable invocation of the bundled CLI's LOCAL binding repair. Absolute via
 // import.meta.url (cli.mjs is one dir up from lib/) so it works on a plugin-only
-// install, where bare `claude-mem-lite` is not on PATH. cli.mjs routes `repair`
-// → install.mjs. (review #3)
-const CLI_REPAIR = `node ${fileURLToPath(new URL('../cli.mjs', import.meta.url))} repair`;
+// install, where bare `claude-mem-lite` is not on PATH. `rebuild-binding`, not
+// `repair`: repair re-downloads and Ed25519-verifies a whole GitHub release and
+// fails closed offline — the wrong (often impossible) tool for recompiling one
+// native module against the running Node. (review #3)
+const CLI_REBUILD_BINDING = `node ${fileURLToPath(new URL('../cli.mjs', import.meta.url))} rebuild-binding`;
 
 // Stable-ish identity of a fault so DISTINCT failures get DISTINCT cooldown
 // windows: the same fault → same key (suppressed within the window), a different
@@ -93,13 +106,56 @@ export function nativeBindingHintDue(runtimeDir, now = Date.now(), cooldownMs =
  */
 export function formatHookError(err, event, { now = Date.now(), runtimeDir } = {}) {
   const ts = new Date(now).toISOString();
-  if (err && err.code === 'ERR_DLOPEN_FAILED') {
+  if (isNativeBindingError(err)) {
+    // Record BEFORE the cooldown check: the hint is cosmetic and rate-limited,
+    // the marker is the heal trigger. Gating the marker on the hint would mean a
+    // silenced hint also silences the repair — exactly the 4-day outage shape.
+    if (runtimeDir) recordNativeBindingBreakage(runtimeDir, { reason: err.message, event, now });
     // Key the cooldown on the fault identity so a DISTINCT native failure within
     // the window still surfaces (a second ABI mismatch after a partial rebuild, a
     // corrupt .node) instead of being silenced by a prior, different DLOPEN. (#8/#15)
     if (runtimeDir && !nativeBindingHintDue(runtimeDir, now, NATIVE_BINDING_HINT_COOLDOWN_MS, errKey(err.message))) return null;
     return `[claude-mem-lite] [${ts}] [WARN] ${event}: native DB binding can't load ` +
-      `(likely a Node version change) — auto-heals on next MCP server start, or run: ${CLI_REPAIR}`;
+      `(likely a Node version change) — auto-heals at the next session start, or run now: ${CLI_REBUILD_BINDING}`;
   }
   return `[claude-mem-lite] [${ts}] [ERROR] ${event}: ${err && err.message}`;
 }
+
+/**
+ * Record the "native binding is unusable" state for the launcher's session-start
+ * heal. Overwrites: the newest fault is the one worth repairing. Best-effort —
+ * a hook must never fail because a marker could not be written.
+ *
+ * @param {string} runtimeDir
+ * @param {{reason?: string, event?: string, now?: number}} [opts]
+ */
+export function recordNativeBindingBreakage(runtimeDir, { reason = '', event = '', now = Date.now() } = {}) {
+  try {
+    mkdirSync(runtimeDir, { recursive: true });
+    const marker = join(runtimeDir, NATIVE_BINDING_BROKEN_MARKER);
+    const tmp = `${marker}.tmp-${process.pid}`;
+    // First line only: the ABI error is multi-line and the marker is read by the
+    // launcher (pure node:, no parser beyond JSON.parse) and by `doctor`.
+    writeFileSync(tmp, JSON.stringify({ reason: String(reason).split('\n')[0], event, ts: now }));
+    renameSync(tmp, marker);
+  } catch { /* best-effort */ }
+}
+
+/**
+ * @param {string} runtimeDir
+ * @returns {{reason?: string, event?: string, ts?: number} | null} null when
+ * absent, unreadable or torn — a garbage marker must never throw into a hook.
+ */
+export function readNativeBindingBreakage(runtimeDir) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(runtimeDir, NATIVE_BINDING_BROKEN_MARKER), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Idempotent. @param {string} runtimeDir */
+export function clearNativeBindingBreakage(runtimeDir) {
+  try { unlinkSync(join(runtimeDir, NATIVE_BINDING_BROKEN_MARKER)); } catch { /* already gone */ }
+}

package/mem-cli.mjs

@@ -35,11 +35,14 @@ import { auditMemdir, memdirPath } from './memdir.mjs';
 import { aggregateProjectCiteRecall } from './lib/citation-tracker.mjs';
 import { probeOtherSources as probeIdSources, bucketIdTokens, splitDeferredTokens } from './lib/id-routing.mjs';
 import { join, sep, dirname } from 'path';
+import { spawnSync } from 'child_process';
 import { readFileSync, existsSync, readdirSync } from 'fs';
 
 // v2.41: shared CLI helpers extracted to cli/common.mjs. Keep this file as the
 // router + remaining-command bodies during the incremental split. Future work:
 // move each cmdXxx into its own cli/<cmd>.mjs; mem-cli.mjs becomes pure dispatch.
+import { isNativeBindingError, healAndReexec } from './lib/binding-probe.mjs';
+import { CLI_PATH, CLI_INVOKE } from './cli-path.mjs';
 import { parseArgs, out, fail, relativeTime, fmtDateShort, parseIdToken, formatProbeHints, rejectBareStringFlags, resolvePositionalAlias, suggestUnknownFlags, OBS_TIME_FIELDS, formatObsFieldValue } from './cli/common.mjs';
 import { saveObservation } from './lib/save-observation.mjs';
 import { rebuildObservationDerived, normalizeScope, insertObservationVector } from './lib/observation-write.mjs';
@@ -3204,6 +3207,37 @@ export async function run(argv) {
     // previously threw here with no auto-repair until the next MCP start.
     db = ensureDbWithWalRecovery({ warn: (m) => process.stderr.write(`[mem] ${m}\n`) });
   } catch (e) {
+    // A Node upgrade leaves better_sqlite3.node compiled for the old ABI, and
+    // every DB-touching path fails at once. Pre-v3.60 this printed the raw
+    // multi-line NODE_MODULE_VERSION error with no repair named, and the only
+    // healer was an MCP server start the user might never perform — the shape of
+    // the 4-day outage on 2026-08-13. Heal in place, then RE-EXEC: this process
+    // has already dlopen'd the stale binary, so it cannot use the new one.
+    if (isNativeBindingError(e)) {
+      const healed = await healAndReexec({
+        // Delegate the actual rebuild to `cli.mjs rebuild-binding` so there is
+        // ONE healer: it takes install.lock, resolves which node_modules tree
+        // the running code uses, and clears the hooks' breakage marker.
+        ensure: async () => {
+          // Child stdout is DISCARDED, not inherited: install.mjs logs progress
+          // to stdout, and this CLI's stdout is a data channel (`search --json`
+          // is piped into jq). Progress still reaches the user via stderr.
+          const r = spawnSync(process.execPath, [CLI_PATH, 'rebuild-binding'], {
+            stdio: ['ignore', 'ignore', 'inherit'],
+            timeout: 300_000,
+          });
+          return r.status === 0
+            ? { ok: true, action: 'rebuilt' }
+            : { ok: false, error: `rebuild-binding exited ${r.status ?? 'on signal'}` };
+        },
+        log: (m) => process.stderr.write(`[mem] ${m}\n`),
+      });
+      if (healed.healed) { process.exitCode = healed.exitCode; return; }
+      out(`[mem] Error: native DB binding unusable on Node ${process.version}${healed.error ? ` — ${healed.error}` : ''}`);
+      out(`[mem] Fix: ${CLI_INVOKE} rebuild-binding`);
+      process.exitCode = 1;
+      return;
+    }
     out(`[mem] Error: Cannot open database: ${e.message}`);
     out(`[mem] DB path: ${DB_PATH}`);
     process.exitCode = 1;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.59.1",
+  "version": "3.60.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "3.59.1",
+      "version": "3.60.1",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.26.0",
         "better-sqlite3": "^12.6.2",
@@ -1570,22 +1570,6 @@
         }
       }
     },
-    "node_modules/ajv/node_modules/fast-uri": {
-      "version": "3.1.4",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.4.tgz",
-      "integrity": "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/fastify"
-        },
-        {
-          "type": "opencollective",
-          "url": "https://opencollective.com/fastify"
-        }
-      ],
-      "license": "BSD-3-Clause"
-    },
     "node_modules/assertion-error": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
@@ -2401,6 +2385,22 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/fast-uri": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz",
+      "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
     "node_modules/fd-package-json": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/fd-package-json/-/fd-package-json-2.0.0.tgz",
@@ -2687,9 +2687,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.31",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.31.tgz",
-      "integrity": "sha512-zJIHFrl6bq3RDd2YusFNCDlM8qUprxKswyi/OPzPyzKDdyBXDqWx8bZlZ7R+saTdSTatUmb3O7K4SspGPaEOQg==",
+      "version": "4.13.2",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.2.tgz",
+      "integrity": "sha512-JydRilDRkYBQMt9qR9U92mXxmbGqsqSn/IKOrh4e7/gEbn+0zSr8igTu0obwJoNGN4sez28DIql7FBHWydoJpA==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -2791,9 +2791,9 @@
       "license": "ISC"
     },
     "node_modules/ip-address": {
-      "version": "10.2.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
-      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.5.0.tgz",
+      "integrity": "sha512-R5SnVLJmgYYvf2F2ZgwSBnelz5G4q5AxIC277GDfUaNbrZKNANcBC7RHqYYePlszf4kBolVkJauG0ZjHHFh55g==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.59.1",
+  "version": "3.60.1",
   "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",
@@ -158,6 +158,7 @@
     "scripts/pre-agent-inject.js",
     "scripts/prompt-search-utils.mjs",
     "scripts/hook-launcher.mjs",
+    "scripts/binding-probe-cli.mjs",
     ".mcp.json",
     ".claude-plugin/plugin.json",
     ".claude-plugin/marketplace.json",

package/scripts/binding-probe-cli.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// scripts/binding-probe-cli.mjs — SessionStart native-binding probe + bounded heal.
+//
+// Contract with scripts/setup.sh: exit 0 = binding usable NOW, non-zero = not.
+// Everything human-readable goes to stderr — SessionStart stdout is a JSON
+// envelope Claude Code parses, so this must never write there.
+//
+// Extracted (v3.60.1) from an inline `node --input-type=module -e '…'` string
+// inside setup.sh. Two load-bearing reasons, both observed rather than assumed:
+//   • That form CRASHED. The -e process SIGSEGV'd during exit after a
+//     verified-good rebuild (Node v24.18, ~50% of runs, no fatal-error report
+//     produced), so a SUCCESSFUL heal exited 139 and setup.sh wrote
+//     .deps-broken over a healthy install. install.mjs::rebuildBinding doing
+//     the same work as a normal module never reproduced it.
+//   • It could not contain an apostrophe. The script was interpolated into a
+//     single-quoted bash string, so a single `don't` in a comment truncated the
+//     shell command — a footgun that fired during development of this fix.
+//
+// Rebuilds are bounded to 20s because setup.sh runs under the SessionStart hook
+// cap (hooks/hooks.json timeout 30): letting the hook SIGKILL a mid-flight
+// node-gyp would leave a partial .node with no flag written. On lock-miss or
+// timeout, mark broken and defer to the MCP launch path (no cap, same lock).
+
+import { execSync, spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = process.env.PROBE_ROOT || join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Fallback for a half-installed tree where lib/ helpers are absent: a bare
+// probe with no rebuild. A WORKING binding must still be able to clear the
+// broken flag, and a helperless broken tree is repaired by the hook-launcher
+// path instead. Out of process like every other probe here — loading a stale
+// .node caches a dead module handle for the rest of THIS process.
+function bareProbe(root) {
+  const script =
+    'try {'
+    + 'const { createRequire } = require("node:module");'
+    + `const D = createRequire(${JSON.stringify(join(root, 'package.json'))})("better-sqlite3");`
+    + 'new D(":memory:").close();'
+    + '} catch (e) { process.stdout.write(String((e && e.message) || e)); process.exit(1); }';
+  const r = spawnSync(process.execPath, ['-e', script], { stdio: 'pipe', timeout: 8000 });
+  if (!r.error && r.status === 0) return true;
+  // Say WHY. The inline predecessor printed the cause here; dropping it left the
+  // user with setup.sh's generic "binding unusable" and nothing to act on.
+  const why = String(r.stdout || '').trim().split('\n')[0]
+    || (r.error && r.error.message)
+    || `probe exited ${r.status ?? `on signal ${r.signal}`}`;
+  process.stderr.write(`[claude-mem-lite] binding probe: ${why}\n`);
+  return false;
+}
+
+let helpers = null;
+try {
+  const [probeMod, lockMod, dirMod] = await Promise.all(
+    ['binding-probe.mjs', 'proc-lock.mjs', 'resolve-data-dir.mjs']
+      .map((f) => import(pathToFileURL(join(ROOT, 'lib', f)).href)),
+  );
+  helpers = { ...probeMod, ...lockMod, ...dirMod };
+} catch {
+  process.exit(bareProbe(ROOT) ? 0 : 1);
+}
+
+// Probe first — read-only, no lock needed. A healthy binding exits here.
+// Bounded like every other step: the whole script runs under the SessionStart
+// hook cap (hooks/hooks.json timeout 30) and an unbounded probe would spend the
+// entire budget before the rebuild it exists to trigger.
+const first = helpers.probeBindingInFreshProcess(ROOT, { timeoutMs: 8000 });
+if (first.ok) process.exit(0);
+
+// Broken: rebuild ONLY under the shared install.lock. A second MCP launch or an
+// install.mjs repair rebuilding the same node_modules concurrently can tear the
+// .node mid-compile.
+let lockPath;
+try {
+  lockPath = join(helpers.resolveDataDir(process.env.CLAUDE_MEM_DIR), 'runtime', 'install.lock');
+} catch (e) {
+  // resolveDataDir THROWS on a non-absolute CLAUDE_MEM_DIR. Unhandled, that
+  // prints an 8-line rejection stack onto SessionStart stderr; one line is enough.
+  process.stderr.write(`[claude-mem-lite] binding probe: ${e.message}\n`);
+  process.exit(1);
+}
+const release = helpers.acquireLock(lockPath);
+if (!release) {
+  const firstLine = String(first.error).split('\n')[0];
+  process.stderr.write(
+    `[claude-mem-lite] binding probe: ${firstLine} (another install/repair in flight — deferring heal)\n`,
+  );
+  process.exit(1);
+}
+
+let result;
+try {
+  result = await helpers.ensureBetterSqlite3Working(ROOT, {
+    // Reuse the probe we already paid for. Without this, ensure() spawns its own
+    // default first probe — a second identical child on the critical path, under
+    // a hook cap, to re-learn what `first` already says.
+    probe: () => first,
+    exec: (cmd, opts) => execSync(cmd, { ...opts, timeout: 20000 }),
+    verify: () => helpers.probeBindingInFreshProcess(ROOT, { timeoutMs: 8000 }),
+  });
+} finally {
+  // process.exit skips finally blocks — every exit below this point, so the
+  // lock is always released.
+  release();
+}
+
+if (!result.ok) {
+  process.stderr.write(`[claude-mem-lite] binding probe: ${result.error}\n`);
+  process.exit(1);
+}
+if (result.action === 'rebuilt') {
+  process.stderr.write('[claude-mem-lite] rebuilt better-sqlite3 binding for current Node ABI\n');
+}
+process.exit(0);

package/scripts/hook-launcher.mjs

@@ -25,7 +25,7 @@
 // install.
 
 import { existsSync, mkdirSync, writeFileSync, statSync, unlinkSync, readFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { dirname, join, isAbsolute } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { homedir } from 'node:os';
@@ -47,6 +47,34 @@ const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
 // the intentional silence (no stack trace per fire) stays detectable. (#4/#8)
 const BROKEN_MARKER = join(RUNTIME_DIR, 'hook-launcher-broken');
 
+// ── Native-binding (ABI) self-heal ──────────────────────────────────────────
+// A stale better_sqlite3.node after a Node upgrade does NOT throw at import time
+// — better-sqlite3 dlopen's it lazily at the first `new Database()`, deep inside
+// the hook script, whose own catch swallows it. So it never reaches the
+// ERR_MODULE_NOT_FOUND path below.
+//
+// scripts/setup.sh has probed + rebuilt the binding at SessionStart since v3.58,
+// but ONLY on plugin-manifest installs: hooks/hooks.json registers setup.sh,
+// while an install.mjs-managed settings.json does NOT — it wires the launcher
+// alone. On that install shape nothing healed. Field result (2026-08-13): 4 days
+// with a dead memory system, 79 failed fires in one day.
+//
+// The hook scripts now drop a marker on every such fire (via
+// lib/hook-telemetry.mjs and lib/native-binding-hint.mjs); this heals from it at
+// SESSION-START only — never on the per-tool hot path, where an npm run would
+// stall the user's edit.
+// Marker dir mirrors the standalone hook scripts (pre-tool-recall /
+// pre-skill-bridge), which honor CLAUDE_MEM_RUNTIME_DIR — they write 78 of every
+// 79 of these markers, so reading a different dir would mean never healing.
+const NB_RUNTIME_DIR = process.env.CLAUDE_MEM_RUNTIME_DIR || RUNTIME_DIR;
+const NB_BROKEN_MARKER = join(NB_RUNTIME_DIR, 'native-binding-broken');
+const NB_HEAL_MARKER = join(NB_RUNTIME_DIR, 'native-binding-lastheal');
+// Literal, not imported: the pure-`node:` charter above forbids importing lib/
+// here (this file must survive a broken install). Kept in sync with
+// lib/binding-probe.mjs::NATIVE_BINDING_REBUILD_CMD, which is the single home
+// everywhere the charter allows an import.
+const NB_MANUAL_CMD = 'npm rebuild better-sqlite3 --dangerously-allow-all-scripts';
+
 // Resolvable invocation of the bundled CLI's repair path. Absolute via
 // INSTALL_DIR (import.meta.url) so it works on a plugin-only install, where
 // bare `claude-mem-lite` is not on PATH and ~/.claude-mem-lite/ holds no source.
@@ -248,6 +276,62 @@ async function attemptHeal(reason) {
 // falls through to the normal entry import. The dynamic import keeps this
 // launcher's pure-`node:` static-import charter intact (it must survive a broken
 // install even if hook-update.mjs is unimportable).
+// → the function this describes is trySyncDataDirFromCache(), below.
+
+// Rebuild the native binding when a prior fire recorded it as unusable.
+//
+// DETACHED, never awaited. This hook runs under a 15s Claude Code cap
+// (hooks/hooks.json) while a rebuild can take far longer — prebuild-install has
+// to fetch, and a node-gyp fallback is minutes. Waiting would trade a broken
+// binding for a SIGKILL'd session-start (no memory context at all) plus a
+// half-written .node, the exact hazard scripts/setup.sh's 20s exec cap documents.
+// Detaching costs one fire: the rebuild lands within seconds and the NEXT hook
+// fire — usually the same session's first PreToolUse — is already healthy.
+// stdio is fully ignored: install.mjs logs to STDOUT, and SessionStart stdout is
+// a JSON envelope Claude Code parses, so inheriting it corrupts the fire.
+//
+// Bounded by its own 6h cooldown so an unfixable case (no prebuild for this Node,
+// no compiler, offline) does not re-spawn npm every session. The cooldown is
+// dropped once the binding is confirmed healthy, so a LATER unrelated break heals
+// immediately instead of waiting out a stale window.
+// Best-effort throughout — a heal failure must never stop the hook fire.
+function healNativeBindingIfBroken() {
+  try {
+    if (!existsSync(NB_BROKEN_MARKER)) {
+      // Healthy (or already healed by the child) → reset the cooldown.
+      try { unlinkSync(NB_HEAL_MARKER); } catch { /* nothing to reset */ }
+      return;
+    }
+    try {
+      if (Date.now() - statSync(NB_HEAL_MARKER).mtimeMs < HEAL_COOLDOWN_MS) return;
+    } catch { /* no marker → not on cooldown */ }
+    try {
+      mkdirSync(NB_RUNTIME_DIR, { recursive: true });
+      writeFileSync(NB_HEAL_MARKER, String(Date.now()));
+    } catch { /* best-effort */ }
+
+    const installer = join(INSTALL_DIR, 'install.mjs');
+    if (!existsSync(installer)) {
+      process.stderr.write(
+        `[claude-mem-lite] native DB binding unusable and install.mjs is missing — run: cd "${INSTALL_DIR}" && ${NB_MANUAL_CMD}\n`,
+      );
+      return;
+    }
+    // The CHILD clears the breakage marker, and only on a verified-good rebuild
+    // (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',
+    );
+    const child = spawn(process.execPath, [installer, 'rebuild-binding'], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+  } catch { /* best-effort — never block the hook fire */ }
+}
+
 async function trySyncDataDirFromCache() {
   try {
     const { syncDataDirFromCache } = await import(
@@ -257,15 +341,27 @@ async function trySyncDataDirFromCache() {
   } catch { /* best-effort — proceed to the normal entry regardless */ }
 }
 
-if (rest.includes('session-start')) {
+const IS_SESSION_START = rest.includes('session-start');
+
+if (IS_SESSION_START) {
+  // Before the entry: this process has not dlopen'd better-sqlite3 yet, so the
+  // freshly built .node is picked up by the very fire that follows. (After a
+  // failed dlopen, only a NEW process can load the replacement — the module
+  // handle is cached and an in-process retry dies with "did not self-register".)
+  healNativeBindingIfBroken();
   await trySyncDataDirFromCache();
 }
 
+
 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 (rest.includes('session-start')) clearBreakage();
+  if (IS_SESSION_START) clearBreakage();
+  // 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.
+  if (IS_SESSION_START) healNativeBindingIfBroken();
 } catch (e) {
   if (!isLocalModuleErr(e)) throw e;
   const reason = describeFailure(e);

package/scripts/launch.mjs

@@ -36,7 +36,7 @@ if (!existsSync(join(ROOT, 'node_modules', 'better-sqlite3'))) {
 // intact but the .node binary stale → server FATALs with "Could not locate
 // the bindings file" on first DB open. Probe + auto-rebuild before launching.
 try {
-  const { ensureBetterSqlite3Working, probeBetterSqlite3Binding } = await import('../lib/binding-probe.mjs');
+  const { ensureBetterSqlite3Working, probeBindingInFreshProcess } = await import('../lib/binding-probe.mjs');
   // The rebuild inside ensureBetterSqlite3Working mutates node_modules — the
   // same write class as install/repair/update, and this was the ONE rebuild
   // path outside the shared install.lock: a second MCP launch or a concurrent
@@ -56,7 +56,11 @@ try {
     if (release) {
       verify = await ensureBetterSqlite3Working(ROOT);
     } else {
-      const probe = await probeBetterSqlite3Binding(ROOT);
+      // Out of process, like the rebuild-capable branch above: this process goes
+      // on to import the MCP server, and a stale .node loaded here would leave a
+      // dead module handle cached for it. Also keeps the exit(1) guidance below
+      // reachable — an in-process load of a stale binding can SIGSEGV instead.
+      const probe = probeBindingInFreshProcess(ROOT);
       verify = probe.ok
         ? { ok: true, action: 'verified' }
         : { ok: false, error: `${probe.error} (another install/repair holds the lock — not rebuilding concurrently; reconnect with /mcp once it finishes)` };

package/scripts/setup.sh

@@ -136,65 +136,38 @@ fi
 #     stat, a new plugin-cache version dir (fresh node_modules) re-probes, and
 #     a Node upgrade (new ABI) re-probes. While broken, every SessionStart
 #     retries the rebuild until it heals.
-# shellcheck disable=SC2016  # node script single-quoted on purpose; ROOT passed via env, not shell expansion
+# Delegates to scripts/binding-probe-cli.mjs — a real module file, NOT an inline
+# `node -e` string. That inline form SIGSEGV'd during exit after a verified-good
+# rebuild (Node v24.18, ~50% of runs), so a successful heal returned 139 and this
+# branch recorded .deps-broken over a healthy install; it also could not contain
+# an apostrophe without truncating the shell command. See that file's header.
+# Contract: exit 0 = binding usable now.
 probe_binding() {
-  PROBE_ROOT="$ROOT" node --input-type=module -e '
-    // NOTE: this whole script sits in a single-quoted bash string — no
-    // apostrophes anywhere in it.
-    const { pathToFileURL } = await import("node:url");
-    const { join } = await import("node:path");
-    const root = process.env.PROBE_ROOT;
-    const libUrl = (f) => pathToFileURL(join(root, "lib", f)).href;
-    let helpers = null;
-    try {
-      const [probeMod, lockMod, dirMod] = await Promise.all(
-        ["binding-probe.mjs", "proc-lock.mjs", "resolve-data-dir.mjs"].map((f) => import(libUrl(f))));
-      helpers = { ...probeMod, ...lockMod, ...dirMod };
-    } catch {
-      // Probe helpers missing (half-installed tree) — fall back to a bare
-      // probe with no rebuild: a WORKING binding must still clear the flag,
-      // and a helperless broken tree is repaired by the hook-launcher path.
-      const { createRequire } = await import("node:module");
-      try {
-        const D = createRequire(join(root, "package.json"))("better-sqlite3");
-        new D(":memory:").close();
-        process.exit(0);
-      } catch (e) {
-        process.stderr.write(`[claude-mem-lite] binding probe: ${e.message}\n`);
-        process.exit(1);
-      }
-    }
-    // Probe first — read-only, no lock needed. Healthy binding exits here.
-    const first = await helpers.probeBetterSqlite3Binding(root);
-    if (first.ok) process.exit(0);
-    // Broken: rebuild ONLY under the shared install.lock (a second MCP launch
-    // or install.mjs repair rebuilding the same node_modules concurrently can
-    // tear the .node), and with the exec bounded to 20s — this script runs
-    // under the SessionStart hook cap (hooks.json timeout 30), and letting the
-    // hook SIGKILL a mid-flight node-gyp leaves a partial .node with no flag
-    // written. On lock-miss or timeout: mark broken and defer the heal to the
-    // MCP launch path (no hook cap, same lock).
-    const lockPath = join(helpers.resolveDataDir(process.env.CLAUDE_MEM_DIR), "runtime", "install.lock");
-    const release = helpers.acquireLock(lockPath);
-    if (!release) {
-      const firstLine = String(first.error).split("\n")[0];
-      process.stderr.write(`[claude-mem-lite] binding probe: ${firstLine} (another install/repair in flight — deferring heal)\n`);
-      process.exit(1);
-    }
-    let r;
-    try {
-      const { execSync } = await import("node:child_process");
-      r = await helpers.ensureBetterSqlite3Working(root, {
-        exec: (cmd, opts) => execSync(cmd, { ...opts, timeout: 20000 }),
-      });
-    } finally {
-      // process.exit skips finally blocks — exits live BELOW this so the
-      // lock is always released.
-      release();
-    }
-    if (!r.ok) { process.stderr.write(`[claude-mem-lite] binding probe: ${r.error}\n`); process.exit(1); }
-    if (r.action === "rebuilt") process.stderr.write("[claude-mem-lite] rebuilt better-sqlite3 binding for current Node ABI\n");
-  '
+  # Absent on a truncated tree: without this guard node prints a full
+  # MODULE_NOT_FOUND stack onto SessionStart stderr on every marker-miss.
+  [[ -f "$ROOT/scripts/binding-probe-cli.mjs" ]] || return 1
+  # stdout muted: this child runs `npm rebuild`, and SessionStart stdout is a
+  # JSON envelope Claude Code parses. Nothing writes there today (verified) —
+  # this keeps a future non-piped exec from being able to.
+  PROBE_ROOT="$ROOT" node "$ROOT/scripts/binding-probe-cli.mjs" >/dev/null
+}
+
+# Ground truth about the binding, independent of how the healer above exited.
+# Belt-and-braces: moving the probe out of the inline `node -e` string removed
+# the observed SIGSEGV, but the healer's exit code is a PROXY for the question
+# that actually matters, and a proxy can lie again (a future crash, a partial
+# state, a kill at the hook cap). So ask the real question in a fresh process:
+# can we open a DB right now? A false .deps-broken here is not cosmetic — it
+# renders a "hooks degraded" banner into the user's session over a healthy
+# install. Costs one ~50ms spawn, and only off the marker fast-path.
+# shellcheck disable=SC2016  # node script single-quoted on purpose; ROOT passed via env, not shell expansion
+binding_usable() {
+  VERIFY_ROOT="$ROOT" node -e '
+    const { createRequire } = require("node:module");
+    const { join } = require("node:path");
+    const D = createRequire(join(process.env.VERIFY_ROOT, "package.json"))("better-sqlite3");
+    new D(":memory:").close();
+  ' >/dev/null 2>&1
 }
 
 if [[ -d "$ROOT/node_modules/better-sqlite3" ]]; then
@@ -202,7 +175,7 @@ if [[ -d "$ROOT/node_modules/better-sqlite3" ]]; then
   BINDING_MARKER="$ROOT/node_modules/.mem-binding-ok-$NODE_ABI"
   if [[ -f "$BINDING_MARKER" ]]; then
     mark_deps_ok
-  elif probe_binding; then
+  elif probe_binding || binding_usable; then
     rm -f "$ROOT/node_modules/.mem-binding-ok-"* 2>/dev/null || true
     touch "$BINDING_MARKER" 2>/dev/null || true
     mark_deps_ok

package/source-files.mjs

@@ -250,6 +250,9 @@ export const HOOK_SCRIPT_FILES = [
 //     as the MCP server. v3.42 audit HIGH-1.
 //   - setup.sh: run on plugin SessionStart via hooks.json. Signed for defense-in-depth
 //     (no tarball→executed-path propagation today, but it ships in files[] and is executed).
+//   - binding-probe-cli.mjs: setup.sh spawns it on every SessionStart that misses the ABI
+//     marker, and it runs `npm rebuild` — an unsigned copy would be arbitrary code executed
+//     at session start with a build step attached. Same class as setup.sh itself.
 // These ship via package.json files[] directly, not via HOOK_SCRIPT_FILES' copy path, so
 // listing them here changes ONLY what is signed/verified, not what install materializes.
 // Module-internal (spread into RELEASE_SIGNED_FILES below); not exported — no external
@@ -258,6 +261,7 @@ const LAUNCHER_SCRIPT_FILES = [
   'launch.mjs',
   'launch-preflight.mjs',
   'setup.sh',
+  'binding-probe-cli.mjs',
 ];
 
 // The complete set of files the release signature MUST cover: every runtime .mjs