claude-mem-lite 2.83.1 → 2.84.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.83.1",
+      "version": "2.84.0",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.83.1",
+  "version": "2.84.0",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "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', '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', 'release']);
+const INSTALL_COMMANDS = new Set(['install', 'uninstall', 'status', 'doctor', 'cleanup', 'cleanup-hooks', 'self-update', 'repair', 'release']);
 
 const cmd = process.argv[2];
 

package/hook-update.mjs

@@ -5,10 +5,14 @@
 import { execSync, execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, copyFileSync, cpSync, readdirSync, existsSync, lstatSync, mkdirSync, rmSync, renameSync, chmodSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { tmpdir, homedir } from 'node:os';
 import { DB_DIR } from './schema.mjs';
 import { debugCatch, debugLog } from './utils.mjs';
-import { SOURCE_FILES, HOOK_SCRIPT_FILES } from './source-files.mjs';
+// Local manifest is fallback only — the active manifest is loaded from the
+// extracted tarball's own source-files.mjs inside installExtractedRelease.
+// See loadReleaseManifest below.
+import { SOURCE_FILES as LOCAL_SOURCE_FILES, HOOK_SCRIPT_FILES as LOCAL_HOOK_SCRIPT_FILES } from './source-files.mjs';
 
 // ── Configuration ──────────────────────────────────────────
 const GITHUB_REPO = 'sdsrss/claude-mem-lite';
@@ -192,11 +196,42 @@ export function getCurrentVersion() {
   } catch { return '0.0.0'; }
 }
 
-// Source files imported from shared ./source-files.mjs so install.mjs and
-// hook-update.mjs can never drift (see tests/source-files-sync.test.mjs).
 // SWITCHABLE_PATHS = everything in SOURCE_FILES plus the recursive dirs that
-// install.mjs copies as whole subtrees (scripts, registry, node_modules).
-const SWITCHABLE_PATHS = [...SOURCE_FILES, 'scripts', 'registry', 'node_modules'];
+// install.mjs copies as whole subtrees (scripts, registry, node_modules). It's
+// built per-call from the *tarball's* manifest, not the locally-imported one —
+// see loadReleaseManifest comment for why.
+function buildSwitchablePaths(sourceFiles) {
+  return [...sourceFiles, 'scripts', 'registry', 'node_modules'];
+}
+
+// Load the SOURCE_FILES / HOOK_SCRIPT_FILES manifest from the *extracted
+// tarball's* own source-files.mjs. Critical: the locally-imported
+// LOCAL_SOURCE_FILES is frozen at install time, so any entry added in the
+// release we're installing is invisible to the running update. Pre-fix
+// (≤ v2.83.2) used LOCAL_SOURCE_FILES for both copyReleaseIntoStaging and
+// SWITCHABLE_PATHS — v2.80.x → v2.81.0 auto-update copied the new hook.mjs
+// (in the v2.80 manifest) but skipped lib/cite-back-hint.mjs (added in v2.81),
+// breaking SessionStart on every machine that auto-updated and killing the
+// hook chain that would otherwise self-heal on the next round.
+async function loadReleaseManifest(sourceDir) {
+  const manifestPath = join(sourceDir, 'source-files.mjs');
+  if (!existsSync(manifestPath)) {
+    return { SOURCE_FILES: LOCAL_SOURCE_FILES, HOOK_SCRIPT_FILES: LOCAL_HOOK_SCRIPT_FILES, source: 'fallback-missing' };
+  }
+  try {
+    const mod = await import(pathToFileURL(manifestPath).href + `?t=${Date.now()}`);
+    if (!Array.isArray(mod.SOURCE_FILES) || mod.SOURCE_FILES.length === 0) {
+      throw new Error('SOURCE_FILES missing or empty');
+    }
+    if (!Array.isArray(mod.HOOK_SCRIPT_FILES)) {
+      throw new Error('HOOK_SCRIPT_FILES missing');
+    }
+    return { SOURCE_FILES: mod.SOURCE_FILES, HOOK_SCRIPT_FILES: mod.HOOK_SCRIPT_FILES, source: 'tarball' };
+  } catch (e) {
+    debugCatch(e, 'loadReleaseManifest');
+    return { SOURCE_FILES: LOCAL_SOURCE_FILES, HOOK_SCRIPT_FILES: LOCAL_HOOK_SCRIPT_FILES, source: 'fallback-error' };
+  }
+}
 
 // ── Download & Install ─────────────────────────────────────
 // Direct file copy instead of running old install.mjs (avoids symlink overwrite in dev)
@@ -223,7 +258,7 @@ async function downloadAndInstall(tarballUrl, expectedVersion) {
       return false;
     }
 
-    return installExtractedRelease(tmpDir);
+    return await installExtractedRelease(tmpDir);
   } catch (err) {
     debugCatch(err, 'downloadAndInstall');
     return false;
@@ -271,25 +306,28 @@ export function validateExtractedTarball(sourceDir, expectedVersion, expectedNam
   return { ok: true };
 }
 
-export function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR) {
+export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR) {
   const ts = `${Date.now()}-${process.pid}`;
   const stagingDir = join(targetDir, `.update-staging-${ts}`);
   const backupDir = join(targetDir, `.update-backup-${ts}`);
   const backedUp = [];
   const installed = [];
 
+  const manifest = await loadReleaseManifest(sourceDir);
+  const switchablePaths = buildSwitchablePaths(manifest.SOURCE_FILES);
+
   try {
     mkdirSync(stagingDir, { recursive: true });
     mkdirSync(backupDir, { recursive: true });
 
-    copyReleaseIntoStaging(sourceDir, stagingDir);
+    copyReleaseIntoStaging(sourceDir, stagingDir, manifest);
     execSync(NPM_INSTALL_CMD, {
       cwd: stagingDir,
       timeout: 60000,
       stdio: 'pipe',
     });
 
-    for (const relPath of SWITCHABLE_PATHS) {
+    for (const relPath of switchablePaths) {
       const stagedPath = join(stagingDir, relPath);
       if (!existsSync(stagedPath)) continue;
 
@@ -368,10 +406,10 @@ export function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR) {
   }
 }
 
-function copyReleaseIntoStaging(sourceDir, stagingDir) {
+function copyReleaseIntoStaging(sourceDir, stagingDir, manifest = { SOURCE_FILES: LOCAL_SOURCE_FILES, HOOK_SCRIPT_FILES: LOCAL_HOOK_SCRIPT_FILES }) {
   let copied = 0;
 
-  for (const f of SOURCE_FILES) {
+  for (const f of manifest.SOURCE_FILES) {
     const src = join(sourceDir, f);
     const dest = join(stagingDir, f);
     if (!existsSync(src)) continue;
@@ -389,7 +427,7 @@ function copyReleaseIntoStaging(sourceDir, stagingDir) {
   const sourceScripts = join(sourceDir, 'scripts');
   if (existsSync(sourceScripts)) {
     mkdirSync(stagingScripts, { recursive: true });
-    for (const name of HOOK_SCRIPT_FILES) {
+    for (const name of manifest.HOOK_SCRIPT_FILES) {
       const src = join(sourceScripts, name);
       if (existsSync(src)) copyFileSync(src, join(stagingScripts, name));
     }

package/hooks/hooks.json

@@ -12,7 +12,7 @@
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hook.mjs\" session-start",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" hook.mjs session-start",
             "timeout": 15
           }
         ]
@@ -24,7 +24,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hook.mjs\" pre-compact",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" hook.mjs pre-compact",
             "timeout": 5
           }
         ]
@@ -36,7 +36,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-tool-recall.js\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" scripts/pre-tool-recall.js",
             "timeout": 3
           }
         ]
@@ -46,7 +46,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-skill-bridge.js\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" scripts/pre-skill-bridge.js",
             "timeout": 3
           }
         ]
@@ -70,7 +70,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hook.mjs\" stop",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" hook.mjs stop",
             "timeout": 5
           }
         ]
@@ -82,12 +82,12 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/user-prompt-search.js\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" scripts/user-prompt-search.js",
             "timeout": 2
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hook.mjs\" user-prompt",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" hook.mjs user-prompt",
             "timeout": 5
           }
         ]

package/install.mjs

@@ -4,7 +4,7 @@
 import { execSync, execFileSync } from 'child_process';
 import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, copyFileSync, cpSync, renameSync, symlinkSync, unlinkSync, readdirSync, statSync, lstatSync } from 'fs';
 import { join, resolve, dirname, isAbsolute } from 'path';
-import { homedir } from 'os';
+import { homedir, tmpdir } from 'os';
 import { fileURLToPath } from 'url';
 
 const PROJECT_DIR = resolve(import.meta.dirname ?? dirname(fileURLToPath(import.meta.url)));
@@ -553,7 +553,13 @@ async function install() {
   }
   settings.hooks = settings.hooks || {};
 
-  const PREFILTER_PATH = join(INSTALL_DIR, 'scripts', 'post-tool-use.sh');
+  const SCRIPTS_PATH = join(INSTALL_DIR, 'scripts');
+  const PREFILTER_PATH = join(SCRIPTS_PATH, 'post-tool-use.sh');
+  // v2.84: every Node hook invocation routes through hook-launcher.mjs so an
+  // ERR_MODULE_NOT_FOUND from a partial-install drift auto-heals via
+  // install.mjs repair instead of permanently bricking the hook chain.
+  const LAUNCHER_PATH = join(SCRIPTS_PATH, 'hook-launcher.mjs');
+  const nodeHook = (entry, ...args) => `node "${LAUNCHER_PATH}" ${entry} ${args.join(' ')}`.trim();
 
   const memPostToolUse = {
     matcher: '*',
@@ -568,7 +574,7 @@ async function install() {
     matcher: 'startup|clear|compact',
     hooks: [{
       type: 'command',
-      command: `node "${HOOK_PATH}" session-start`,
+      command: nodeHook('hook.mjs', 'session-start'),
       timeout: 10
     }]
   };
@@ -577,24 +583,22 @@ async function install() {
     matcher: '*',
     hooks: [{
       type: 'command',
-      command: `node "${HOOK_PATH}" stop`,
+      command: nodeHook('hook.mjs', 'stop'),
       timeout: 5
     }]
   };
 
-  const SCRIPTS_PATH = join(INSTALL_DIR, 'scripts');
-
   const memUserPrompt = {
     matcher: '*',
     hooks: [
       {
         type: 'command',
-        command: `node "${join(SCRIPTS_PATH, 'user-prompt-search.js')}"`,
+        command: nodeHook('scripts/user-prompt-search.js'),
         timeout: 2
       },
       {
         type: 'command',
-        command: `node "${HOOK_PATH}" user-prompt`,
+        command: nodeHook('hook.mjs', 'user-prompt'),
         timeout: 5
       }
     ]
@@ -608,7 +612,7 @@ async function install() {
     hooks: [
       {
         type: 'command',
-        command: `node "${join(SCRIPTS_PATH, 'pre-tool-recall.js')}"`,
+        command: nodeHook('scripts/pre-tool-recall.js'),
         timeout: 3
       }
     ]
@@ -619,7 +623,7 @@ async function install() {
     hooks: [
       {
         type: 'command',
-        command: `node "${join(SCRIPTS_PATH, 'pre-skill-bridge.js')}"`,
+        command: nodeHook('scripts/pre-skill-bridge.js'),
         timeout: 3
       }
     ]
@@ -1758,6 +1762,45 @@ async function manualUpdate() {
   console.log('');
 }
 
+// ─── Repair: Re-sync from latest GitHub Release ─────────────────────────────
+// Recovery path for installs broken by a partial auto-update (most often the
+// stale-manifest bug fixed in v2.84.0: hook-update.mjs copied the new hook.mjs
+// but skipped a new lib/* entry, leaving an ERR_MODULE_NOT_FOUND that
+// permanently disables the hook chain — including the next auto-update that
+// would have healed it). Self-contained: downloads a fresh tarball and spawns
+// the tarball's own install.mjs install, so the recovery path always runs the
+// latest code even when local install.mjs / hook-update.mjs are themselves
+// buggy on disk.
+async function repair() {
+  console.log('\nclaude-mem-lite repair — re-syncing from latest GitHub release\n');
+  const stagingDir = join(tmpdir(), `claude-mem-lite-repair-${Date.now()}`);
+  mkdirSync(stagingDir, { recursive: true });
+  try {
+    const tarballUrl = 'https://api.github.com/repos/sdsrss/claude-mem-lite/tarball';
+    const tarballPath = join(stagingDir, 'release.tgz');
+    log('Downloading latest release tarball...');
+    execFileSync('curl', ['-sL', '-f', '-H', 'Accept: application/vnd.github+json', tarballUrl, '-o', tarballPath],
+      { timeout: 60000, stdio: ['ignore', 'pipe', 'inherit'] });
+    log('Extracting...');
+    execFileSync('tar', ['xzf', tarballPath, '-C', stagingDir, '--strip-components=1'],
+      { timeout: 30000, stdio: ['ignore', 'pipe', 'inherit'] });
+    const tarballInstaller = join(stagingDir, 'install.mjs');
+    if (!existsSync(tarballInstaller)) {
+      fail('Tarball missing install.mjs — repair aborted');
+      process.exit(1);
+    }
+    log('Re-running install from freshly-downloaded sources...');
+    execFileSync(process.execPath, [tarballInstaller, 'install'],
+      { stdio: 'inherit', timeout: 300000 });
+    ok('Repair complete — broken install resynced from latest release');
+  } catch (e) {
+    fail(`Repair failed: ${e.message}`);
+    process.exit(1);
+  } finally {
+    try { rmSync(stagingDir, { recursive: true, force: true }); } catch {}
+  }
+}
+
 // ─── Release: Sync Versions ─────────────────────────────────────────────────
 
 function syncVersions() {
@@ -1860,6 +1903,9 @@ export async function main(argv = process.argv.slice(2)) {
     case 'update':
       await manualUpdate();
       break;
+    case 'repair':
+      await repair();
+      break;
     case 'release':
       syncVersions();
       if (!flags.has('--no-lock')) regenerateLockfile();
@@ -1889,6 +1935,7 @@ Usage:
   node install.mjs cleanup            Remove stale temp/staging files (use --dry-run to preview)
   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 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.83.1",
+  "version": "2.84.0",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -119,6 +119,7 @@
     "scripts/pre-tool-recall.js",
     "scripts/pre-skill-bridge.js",
     "scripts/prompt-search-utils.mjs",
+    "scripts/hook-launcher.mjs",
     ".mcp.json",
     ".claude-plugin/plugin.json",
     ".claude-plugin/marketplace.json",

package/scripts/hook-launcher.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// scripts/hook-launcher.mjs — Self-healing wrapper for Node hook entry points.
+//
+// Why: pre-v2.84 a stale-manifest bug in hook-update.mjs could leave the
+// install with a hook.mjs that imports lib/cite-back-hint.mjs (or any other
+// newly-added module) while the file itself was never copied. The resulting
+// ERR_MODULE_NOT_FOUND killed every hook fire, including the next auto-update
+// that would have healed the install. v2.84.0 fixes the root cause; this
+// launcher is defense-in-depth for similar future drift (corrupt download,
+// half-applied install, manual file deletion).
+//
+// Behavior: try-import the target entry. On ERR_MODULE_NOT_FOUND whose URL
+// points under the install dir, run `install.mjs repair` (rate-limited via a
+// 6h marker file under runtime/) and retry the import once. On any other
+// exception, re-throw so Node's default error surface is preserved.
+//
+// HARD constraint: pure node: imports only. Importing anything from lib/ here
+// would defeat the entire purpose — the launcher must survive a broken
+// install.
+
+import { existsSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INSTALL_DIR = join(__dirname, '..');
+const RUNTIME_DIR = process.env.CLAUDE_MEM_DIR
+  ? join(process.env.CLAUDE_MEM_DIR, 'runtime')
+  : join(homedir(), '.claude-mem-lite', 'runtime');
+const HEAL_MARKER = join(RUNTIME_DIR, 'hook-launcher-lastheal');
+const HEAL_COOLDOWN_MS = 6 * 60 * 60 * 1000;
+
+const [, , entryArg, ...rest] = process.argv;
+if (!entryArg) {
+  process.stderr.write('[claude-mem-lite] hook-launcher: missing entry argument\n');
+  process.exit(1);
+}
+
+const entryAbs = entryArg.startsWith('/') ? entryArg : join(INSTALL_DIR, entryArg);
+
+async function runEntry({ bustCache = false } = {}) {
+  // Mirror direct invocation: process.argv[1] is the entry, [2..] are its args.
+  process.argv = [process.argv[0], entryAbs, ...rest];
+  // Node ESM caches resolution outcomes (success AND failure) by URL. On the
+  // post-self-heal retry the freshly-written module file lives at the same
+  // path the first import already cached as ERR_MODULE_NOT_FOUND — without a
+  // cache-buster query the second await import() returns the cached rejection
+  // and the heal looks like it did nothing.
+  const url = pathToFileURL(entryAbs).href + (bustCache ? `?t=${Date.now()}` : '');
+  await import(url);
+}
+
+function isLocalModuleErr(e) {
+  if (!e || e.code !== 'ERR_MODULE_NOT_FOUND') return false;
+  const where = String(e.url || e.message || '');
+  return where.includes('.claude-mem-lite') || where.startsWith(`file://${INSTALL_DIR}`);
+}
+
+function recentHealAttempt() {
+  try {
+    return Date.now() - statSync(HEAL_MARKER).mtimeMs < HEAL_COOLDOWN_MS;
+  } catch { return false; }
+}
+
+function recordHealAttempt() {
+  try {
+    mkdirSync(RUNTIME_DIR, { recursive: true });
+    writeFileSync(HEAL_MARKER, String(Date.now()));
+  } catch { /* best-effort */ }
+}
+
+async function attemptHeal(reason) {
+  if (recentHealAttempt()) {
+    process.stderr.write(
+      `[claude-mem-lite] Self-heal skipped (last attempt < 6h ago). Manual recovery: claude-mem-lite repair\n`,
+    );
+    return false;
+  }
+  recordHealAttempt();
+  process.stderr.write(`[claude-mem-lite] Detected broken install (${reason}) — running self-heal\n`);
+  const installer = join(INSTALL_DIR, 'install.mjs');
+  if (!existsSync(installer)) {
+    process.stderr.write(`[claude-mem-lite] install.mjs missing at ${installer} — cannot self-heal\n`);
+    return false;
+  }
+  const result = spawnSync(process.execPath, [installer, 'repair'], {
+    stdio: 'inherit',
+    timeout: 300000,
+  });
+  return result.status === 0;
+}
+
+try {
+  await runEntry();
+} catch (e) {
+  if (!isLocalModuleErr(e)) throw e;
+  const reason = String(e.url || e.message).split('/').slice(-2).join('/');
+  const healed = await attemptHeal(reason);
+  if (!healed) throw e;
+  try {
+    await runEntry({ bustCache: true });
+  } catch (retryErr) {
+    process.stderr.write(`[claude-mem-lite] Hook still failing after self-heal: ${retryErr.message}\n`);
+    process.exit(1);
+  }
+}

package/scripts/post-tool-use.sh

@@ -56,6 +56,7 @@ case "$tool" in
     ;;
 esac
 
-# Tool not skipped — hand off to Node for full processing
+# Tool not skipped — hand off to Node for full processing.
+# Routed through hook-launcher.mjs (self-heal on ERR_MODULE_NOT_FOUND).
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" || exit 1
-printf '%s' "$input" | node "${SCRIPT_DIR}/hook.mjs" post-tool-use
+printf '%s' "$input" | node "${SCRIPT_DIR}/scripts/hook-launcher.mjs" hook.mjs post-tool-use

package/scripts/pre-tool-recall.js

@@ -9,6 +9,7 @@ import { basename, join } from 'path';
 import { homedir } from 'os';
 import { buildNotLowSignalSql } from '../lib/low-signal-patterns.mjs';
 import { recordHookError } from '../lib/hook-telemetry.mjs';
+import { citeFactorClause } from '../scoring-sql.mjs';
 
 // CLAUDE_MEM_DIR matches schema.mjs / main CLI — one env var sandboxes the
 // whole system. CLAUDE_MEM_DB_PATH / CLAUDE_MEM_RUNTIME_DIR remain as
@@ -232,6 +233,11 @@ try {
           OR (o.type IN ('bugfix', 'decision') AND ${notLowSignalSql})
         )`;
     const obsLimit = isRead ? 1 : 2;
+    // A1.5 (v2.83.2): cite_factor as a tertiary sort key. When multiple file-
+    // matching lessons exist, the one with proven cite history outranks the
+    // merely-most-recent one. Single-match files unchanged (obsLimit=1 Read /
+    // 2 Edit). Composes with v2.83.0 A1 to extend the citation-decay feedback
+    // loop to the 85%-recall PreToolUse:Read/Edit path.
     const rows = db.prepare(`
       SELECT DISTINCT o.id, o.type, o.title, o.lesson_learned
       FROM observations o
@@ -245,6 +251,7 @@ try {
         ${typeFallback}
       ORDER BY
         CASE WHEN o.lesson_learned IS NOT NULL AND o.lesson_learned != '' THEN 0 ELSE 1 END,
+        ${citeFactorClause('o')} DESC,
         o.created_at_epoch DESC
       LIMIT ${obsLimit}
     `).all(project, cutoff, filePath, likePattern);

package/source-files.mjs

@@ -110,4 +110,9 @@ export const HOOK_SCRIPT_FILES = [
   'prompt-search-utils.mjs',
   'pre-tool-recall.js',
   'pre-skill-bridge.js',
+  // v2.84: self-heal wrapper that detects ERR_MODULE_NOT_FOUND under the
+  // install dir and runs install.mjs repair before retrying the entry.
+  // hooks.json + install.mjs settings template invoke node hook entries
+  // through this wrapper so any partial-install drift heals automatically.
+  'hook-launcher.mjs',
 ];