context-mode 1.0.107 → 1.0.109

package/hooks/sessionstart.mjs

@@ -1,6 +1,4 @@
 #!/usr/bin/env node
-import "./suppress-stderr.mjs";
-import "./ensure-deps.mjs";
 /**
  * SessionStart hook for context-mode
  *
@@ -11,170 +9,204 @@ import "./ensure-deps.mjs";
  * Session Lifecycle Rules:
  * - "startup"  → Fresh session. Inject previous session knowledge. Cleanup old data.
  * - "compact"  → Auto-compact triggered. Inject resume snapshot + stats.
- * - "resume"   → User used --continue. Full history, no resume needed.
+ * - "resume"   → User invoked --continue, --resume, or /resume. CC sends the
+ *                ACTIVE session_id; for /resume this is typically a *fresh*
+ *                id, so live events miss → fall back to snapshot (#413).
  * - "clear"    → User cleared context. No resume.
+ *
+ * Crash-resilience: wrapped via runHook (#414) — all module loads happen
+ * dynamically inside the wrapper so a missing/poisoned dep can never hard-fail
+ * the hook. Errors land in ~/.claude/context-mode/hook-errors.log.
  */
 
-import { createRoutingBlock } from "./routing-block.mjs";
-import { createToolNamer } from "./core/tool-naming.mjs";
-import { detectPlatformFromEnv } from "./core/platform-detect.mjs";
-import { buildAutoInjection } from "./auto-injection.mjs";
-
-const detectedPlatform = detectPlatformFromEnv();
-const toolNamer = createToolNamer(detectedPlatform);
-const ROUTING_BLOCK = createRoutingBlock(toolNamer);
-import { readStdin, parseStdin, getSessionId, getSessionDBPath, getSessionEventsPath, getCleanupFlagPath, resolveConfigDir } from "./session-helpers.mjs";
-import { writeSessionEventsFile, buildSessionDirective, getSessionEvents } from "./session-directive.mjs";
-import { createSessionLoaders } from "./session-loaders.mjs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { readFileSync, unlinkSync, readdirSync, rmSync, statSync } from "node:fs";
-
-// Resolve absolute path for imports (fileURLToPath for Windows compat)
-const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
-const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
-
-let additionalContext = ROUTING_BLOCK;
-
-try {
-  const raw = await readStdin();
-  const input = parseStdin(raw);
-  const source = input.source ?? "startup";
-
-  if (source === "compact") {
-    // Session was compacted — write events to file for auto-indexing, inject directive only
-    const { SessionDB } = await loadSessionDB();
-    const dbPath = getSessionDBPath();
-    const db = new SessionDB({ dbPath });
-    const sessionId = getSessionId(input);
-    const resume = db.getResume(sessionId);
-
-    if (resume && !resume.consumed) {
-      db.markResumeConsumed(sessionId);
-    }
-
-    const events = getSessionEvents(db, sessionId);
-    if (events.length > 0) {
-      const eventMeta = writeSessionEventsFile(events, getSessionEventsPath());
-      additionalContext += buildSessionDirective("compact", eventMeta, toolNamer);
+import { runHook } from "./run-hook.mjs";
+
+await runHook(async () => {
+  const { createRoutingBlock } = await import("./routing-block.mjs");
+  const { createToolNamer } = await import("./core/tool-naming.mjs");
+  const { detectPlatformFromEnv } = await import("./core/platform-detect.mjs");
+  const { buildAutoInjection } = await import("./auto-injection.mjs");
+  const {
+    readStdin,
+    parseStdin,
+    getSessionId,
+    getSessionDBPath,
+    getSessionEventsPath,
+    getCleanupFlagPath,
+    resolveConfigDir,
+  } = await import("./session-helpers.mjs");
+  const { writeSessionEventsFile, buildSessionDirective, getSessionEvents } = await import(
+    "./session-directive.mjs"
+  );
+  const { createSessionLoaders } = await import("./session-loaders.mjs");
+  const { join, dirname } = await import("node:path");
+  const { fileURLToPath } = await import("node:url");
+  const { readFileSync, unlinkSync, readdirSync, rmSync, statSync } = await import("node:fs");
+
+  const detectedPlatform = detectPlatformFromEnv();
+  const toolNamer = createToolNamer(detectedPlatform);
+  const ROUTING_BLOCK = createRoutingBlock(toolNamer);
+
+  // Resolve absolute path for imports (fileURLToPath for Windows compat)
+  const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+  const { loadSessionDB } = createSessionLoaders(HOOK_DIR);
+
+  let additionalContext = ROUTING_BLOCK;
 
-      // Auto-inject behavioral state on compaction (role, decisions, skills, intent)
-      const autoInjection = buildAutoInjection(events);
-      if (autoInjection) {
-        additionalContext += "\n\n" + autoInjection;
+  try {
+    const raw = await readStdin();
+    const input = parseStdin(raw);
+    const source = input.source ?? "startup";
+
+    if (source === "compact") {
+      // Session was compacted — write events to file for auto-indexing, inject directive only
+      const { SessionDB } = await loadSessionDB();
+      const dbPath = getSessionDBPath();
+      const db = new SessionDB({ dbPath });
+      const sessionId = getSessionId(input);
+      const resume = db.getResume(sessionId);
+
+      if (resume && !resume.consumed) {
+        db.markResumeConsumed(sessionId);
       }
 
-      // Write session-resume event
-      try {
-        db.insertEvent(sessionId, {
-          type: "resume_completed",
-          category: "session-resume",
-          data: `Session resumed from ${source}. Prior events loaded.`,
-          priority: 1,
-        }, "SessionStart");
-      } catch { /* best-effort */ }
-    }
+      const events = getSessionEvents(db, sessionId);
+      if (events.length > 0) {
+        const eventMeta = writeSessionEventsFile(events, getSessionEventsPath());
+        additionalContext += buildSessionDirective("compact", eventMeta, toolNamer);
 
-    db.close();
-  } else if (source === "resume") {
-    // User used --continue — clear cleanup flag so startup doesn't wipe data
-    try { unlinkSync(getCleanupFlagPath()); } catch { /* no flag */ }
-
-    const { SessionDB } = await loadSessionDB();
-    const dbPath = getSessionDBPath();
-    const db = new SessionDB({ dbPath });
-
-    // Filter events to the session being resumed. Falling back to
-    // getLatestSessionEvents(db) leaks events from any other session whose
-    // session_meta.started_at is more recent — observed cross-session bleed
-    // when a different worktree session started after this one and before
-    // the resume.
-    const sessionId = getSessionId(input);
-    const events = sessionId ? getSessionEvents(db, sessionId) : [];
-    if (events.length > 0) {
-      const eventMeta = writeSessionEventsFile(events, getSessionEventsPath());
-      additionalContext += buildSessionDirective("resume", eventMeta, toolNamer);
-    }
+        // Auto-inject behavioral state on compaction (role, decisions, skills, intent)
+        const autoInjection = buildAutoInjection(events);
+        if (autoInjection) {
+          additionalContext += "\n\n" + autoInjection;
+        }
 
-    db.close();
-  } else if (source === "startup") {
-    // Fresh session (no --continue) — clean slate, capture CLAUDE.md rules.
-    const { SessionDB } = await loadSessionDB();
-    const dbPath = getSessionDBPath();
-    const db = new SessionDB({ dbPath });
-    try { unlinkSync(getSessionEventsPath()); } catch { /* no stale file */ }
-
-    // Detect true fresh start vs --continue (which fires startup→resume).
-    // If cleanup flag exists from a PREVIOUS startup that was never followed by
-    // resume, that was a true fresh start — aggressively wipe all data.
-    db.cleanupOldSessions(7);
-    db.db.exec(`DELETE FROM session_events WHERE session_id NOT IN (SELECT session_id FROM session_meta)`);
-
-    // Proactively capture CLAUDE.md files — Claude Code loads them as system
-    // context at startup, invisible to PostToolUse hooks. We read them from
-    // disk so they survive compact/resume via the session events pipeline.
-    const sessionId = getSessionId(input);
-    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-    db.ensureSession(sessionId, projectDir);
-    const claudeMdPaths = [
-      join(resolveConfigDir(), "CLAUDE.md"),
-      join(projectDir, "CLAUDE.md"),
-      join(projectDir, ".claude", "CLAUDE.md"),
-    ];
-    for (const p of claudeMdPaths) {
-      try {
-        const content = readFileSync(p, "utf-8");
-        if (content.trim()) {
-          db.insertEvent(sessionId, { type: "rule", category: "rule", data: p, priority: 1 });
-          db.insertEvent(sessionId, { type: "rule_content", category: "rule", data: content, priority: 1 });
+        // Write session-resume event
+        try {
+          db.insertEvent(
+            sessionId,
+            {
+              type: "resume_completed",
+              category: "session-resume",
+              data: `Session resumed from ${source}. Prior events loaded.`,
+              priority: 1,
+            },
+            "SessionStart",
+          );
+        } catch { /* best-effort */ }
+      }
+
+      db.close();
+    } else if (source === "resume") {
+      // User invoked --continue, --resume, or /resume — clear cleanup flag so
+      // startup doesn't wipe data on the next fresh boot.
+      try { unlinkSync(getCleanupFlagPath()); } catch { /* no flag */ }
+
+      const { SessionDB } = await loadSessionDB();
+      const dbPath = getSessionDBPath();
+      const db = new SessionDB({ dbPath });
+
+      // 1) Try live events for the resumed session. Filter strictly to the
+      //    incoming session_id — falling back to getLatestSessionEvents(db)
+      //    leaks events from any other session whose session_meta.started_at
+      //    is more recent (cross-worktree bleed observed in the wild).
+      const sessionId = getSessionId(input);
+      const events = sessionId ? getSessionEvents(db, sessionId) : [];
+      if (events.length > 0) {
+        const eventMeta = writeSessionEventsFile(events, getSessionEventsPath());
+        additionalContext += buildSessionDirective("resume", eventMeta, toolNamer);
+      } else if (sessionId) {
+        // 2) Snapshot fallback (#413). /resume hands us a *new* active session
+        //    id whose live event table is empty; the prior conversation lives
+        //    in `session_resume.snapshot`. Mirrors the OpenCode/OpenClaw resume
+        //    injection path (opencode-plugin.ts:454). claimLatestUnconsumedResume
+        //    excludes the current id, so we surface the latest unconsumed
+        //    snapshot from any prior session in this project.
+        const row = db.claimLatestUnconsumedResume(sessionId);
+        if (row?.snapshot) {
+          additionalContext += "\n\n" + row.snapshot;
         }
-      } catch { /* file doesn't exist — skip */ }
-    }
+      }
+
+      db.close();
+    } else if (source === "startup") {
+      // Fresh session (no --continue) — clean slate, capture CLAUDE.md rules.
+      const { SessionDB } = await loadSessionDB();
+      const dbPath = getSessionDBPath();
+      const db = new SessionDB({ dbPath });
+      try { unlinkSync(getSessionEventsPath()); } catch { /* no stale file */ }
+
+      // Detect true fresh start vs --continue (which fires startup→resume).
+      // If cleanup flag exists from a PREVIOUS startup that was never followed by
+      // resume, that was a true fresh start — aggressively wipe all data.
+      db.cleanupOldSessions(7);
+      db.db.exec(`DELETE FROM session_events WHERE session_id NOT IN (SELECT session_id FROM session_meta)`);
+
+      // Proactively capture CLAUDE.md files — Claude Code loads them as system
+      // context at startup, invisible to PostToolUse hooks. We read them from
+      // disk so they survive compact/resume via the session events pipeline.
+      const sessionId = getSessionId(input);
+      const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      db.ensureSession(sessionId, projectDir);
+      const claudeMdPaths = [
+        join(resolveConfigDir(), "CLAUDE.md"),
+        join(projectDir, "CLAUDE.md"),
+        join(projectDir, ".claude", "CLAUDE.md"),
+      ];
+      for (const p of claudeMdPaths) {
+        try {
+          const content = readFileSync(p, "utf-8");
+          if (content.trim()) {
+            db.insertEvent(sessionId, { type: "rule", category: "rule", data: p, priority: 1 });
+            db.insertEvent(sessionId, { type: "rule_content", category: "rule", data: content, priority: 1 });
+          }
+        } catch { /* file doesn't exist — skip */ }
+      }
 
-    db.close();
+      db.close();
 
-    // Age-gated lazy cleanup of old plugin cache version dirs (#181).
-    // Only delete dirs older than 1 hour to avoid breaking active sessions.
-    try {
-      const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
-      if (pluginRoot) {
-        const cacheParentMatch = pluginRoot.match(/^(.*[\\/]plugins[\\/]cache[\\/][^\\/]+[\\/][^\\/]+[\\/])/);
-        if (cacheParentMatch) {
-          const cacheParent = cacheParentMatch[1];
-          const myDir = pluginRoot.replace(cacheParent, "").replace(/[\\/]/g, "");
-          const ONE_HOUR = 3600000;
-          const now = Date.now();
-          for (const d of readdirSync(cacheParent)) {
-            if (d === myDir) continue;
-            try {
-              const st = statSync(join(cacheParent, d));
-              if (now - st.mtimeMs > ONE_HOUR) {
-                rmSync(join(cacheParent, d), { recursive: true, force: true });
-              }
-            } catch { /* skip */ }
+      // Age-gated lazy cleanup of old plugin cache version dirs (#181).
+      // Only delete dirs older than 1 hour to avoid breaking active sessions.
+      try {
+        const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+        if (pluginRoot) {
+          const cacheParentMatch = pluginRoot.match(/^(.*[\\/]plugins[\\/]cache[\\/][^\\/]+[\\/][^\\/]+[\\/])/);
+          if (cacheParentMatch) {
+            const cacheParent = cacheParentMatch[1];
+            const myDir = pluginRoot.replace(cacheParent, "").replace(/[\\/]/g, "");
+            const ONE_HOUR = 3600000;
+            const now = Date.now();
+            for (const d of readdirSync(cacheParent)) {
+              if (d === myDir) continue;
+              try {
+                const st = statSync(join(cacheParent, d));
+                if (now - st.mtimeMs > ONE_HOUR) {
+                  rmSync(join(cacheParent, d), { recursive: true, force: true });
+                }
+              } catch { /* skip */ }
+            }
           }
         }
-      }
-    } catch { /* best effort — never block session start */ }
+      } catch { /* best effort — never block session start */ }
+    }
+    // "clear" — no reset needed; ctx_purge is the only wipe mechanism
+  } catch (err) {
+    // Session continuity is best-effort — never block session start
+    try {
+      const { appendFileSync } = await import("node:fs");
+      const { join: pjoin } = await import("node:path");
+      const { resolveConfigDir: _resolve } = await import("./session-helpers.mjs");
+      appendFileSync(
+        pjoin(_resolve(), "context-mode", "sessionstart-debug.log"),
+        `[${new Date().toISOString()}] ${err?.message || err}\n${err?.stack || ""}\n`,
+      );
+    } catch { /* ignore logging failure */ }
   }
-  // "clear" — no reset needed; ctx_purge is the only wipe mechanism
-} catch (err) {
-  // Session continuity is best-effort — never block session start
-  try {
-    const { appendFileSync } = await import("node:fs");
-    const { join: pjoin } = await import("node:path");
-    const { homedir } = await import("node:os");
-    const { resolveConfigDir: _resolve } = await import("./session-helpers.mjs");
-    appendFileSync(
-      pjoin(_resolve(), "context-mode", "sessionstart-debug.log"),
-      `[${new Date().toISOString()}] ${err?.message || err}\n${err?.stack || ""}\n`,
-    );
-  } catch { /* ignore logging failure */ }
-}
-
-console.log(JSON.stringify({
-  hookSpecificOutput: {
-    hookEventName: "SessionStart",
-    additionalContext,
-  },
-}));
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext,
+    },
+  }));
+});

package/hooks/userpromptsubmit.mjs

@@ -1,6 +1,4 @@
 #!/usr/bin/env node
-import "./suppress-stderr.mjs";
-import "./ensure-deps.mjs";
 /**
  * UserPromptSubmit hook for context-mode session continuity.
  *
@@ -8,71 +6,84 @@ import "./ensure-deps.mjs";
  * point where the user left off after compact or session restart.
  *
  * Must be fast (<10ms). Just a single SQLite write.
+ *
+ * Crash-resilience: wrapped via runHook (#414) — module loads happen
+ * dynamically so missing deps log + exit 0 instead of MODULE_NOT_FOUND.
  */
 
-import { readStdin, parseStdin, getSessionId, getSessionDBPath, getInputProjectDir } from "./session-helpers.mjs";
-import { createSessionLoaders, attributeAndInsertEvents } from "./session-loaders.mjs";
-import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { runHook } from "./run-hook.mjs";
 
-const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
-const { loadSessionDB, loadExtract, loadProjectAttribution } = createSessionLoaders(HOOK_DIR);
+await runHook(async () => {
+  const {
+    readStdin,
+    parseStdin,
+    getSessionId,
+    getSessionDBPath,
+    getInputProjectDir,
+  } = await import("./session-helpers.mjs");
+  const { createSessionLoaders, attributeAndInsertEvents } = await import("./session-loaders.mjs");
+  const { dirname } = await import("node:path");
+  const { fileURLToPath } = await import("node:url");
 
-try {
-  const raw = await readStdin();
-  const input = parseStdin(raw);
-  const projectDir = getInputProjectDir(input);
+  const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
+  const { loadSessionDB, loadExtract, loadProjectAttribution } = createSessionLoaders(HOOK_DIR);
 
-  const prompt = input.prompt ?? input.message ?? "";
-  const trimmed = (prompt || "").trim();
+  try {
+    const raw = await readStdin();
+    const input = parseStdin(raw);
+    const projectDir = getInputProjectDir(input);
 
-  // Skip system-generated messages — only capture genuine user prompts
-  const isSystemMessage = trimmed.startsWith("<task-notification>")
-    || trimmed.startsWith("<system-reminder>")
-    || trimmed.startsWith("<context_guidance>")
-    || trimmed.startsWith("<tool-result>");
+    const prompt = input.prompt ?? input.message ?? "";
+    const trimmed = (prompt || "").trim();
 
-  if (trimmed.length > 0 && !isSystemMessage) {
-    const { SessionDB } = await loadSessionDB();
-    const { extractUserEvents } = await loadExtract();
-    const { resolveProjectAttributions } = await loadProjectAttribution();
-    const dbPath = getSessionDBPath();
-    const db = new SessionDB({ dbPath });
-    const sessionId = getSessionId(input);
+    // Skip system-generated messages — only capture genuine user prompts
+    const isSystemMessage = trimmed.startsWith("<task-notification>")
+      || trimmed.startsWith("<system-reminder>")
+      || trimmed.startsWith("<context_guidance>")
+      || trimmed.startsWith("<tool-result>");
 
-    db.ensureSession(sessionId, projectDir);
+    if (trimmed.length > 0 && !isSystemMessage) {
+      const { SessionDB } = await loadSessionDB();
+      const { extractUserEvents } = await loadExtract();
+      const { resolveProjectAttributions } = await loadProjectAttribution();
+      const dbPath = getSessionDBPath();
+      const db = new SessionDB({ dbPath });
+      const sessionId = getSessionId(input);
 
-    // 1. Always save the raw prompt
-    const promptEvent = {
-      type: "user_prompt",
-      category: "user-prompt",
-      data: prompt,
-      priority: 1,
-    };
-    const promptAttributions = attributeAndInsertEvents(
-      db, sessionId, [promptEvent], input, projectDir, "UserPromptSubmit", resolveProjectAttributions,
-    );
+      db.ensureSession(sessionId, projectDir);
 
-    // 2. Extract decision/role/intent/data from user message
-    const userEvents = extractUserEvents(trimmed);
-    // Feed lastKnownProjectDir from the first attribution into the second batch
-    const savedLastKnown = promptAttributions[0]?.projectDir || null;
-    const sessionStats = db.getSessionStats(sessionId);
-    const lastKnownProjectDir = typeof db.getLatestAttributedProjectDir === "function"
-      ? db.getLatestAttributedProjectDir(sessionId)
-      : null;
-    const userAttributions = resolveProjectAttributions(userEvents, {
-      sessionOriginDir: sessionStats?.project_dir || projectDir,
-      inputProjectDir: projectDir,
-      workspaceRoots: Array.isArray(input.workspace_roots) ? input.workspace_roots : [],
-      lastKnownProjectDir: savedLastKnown || lastKnownProjectDir,
-    });
-    for (let i = 0; i < userEvents.length; i++) {
-      db.insertEvent(sessionId, userEvents[i], "UserPromptSubmit", userAttributions[i]);
-    }
+      // 1. Always save the raw prompt
+      const promptEvent = {
+        type: "user_prompt",
+        category: "user-prompt",
+        data: prompt,
+        priority: 1,
+      };
+      const promptAttributions = attributeAndInsertEvents(
+        db, sessionId, [promptEvent], input, projectDir, "UserPromptSubmit", resolveProjectAttributions,
+      );
 
-    db.close();
+      // 2. Extract decision/role/intent/data from user message
+      const userEvents = extractUserEvents(trimmed);
+      // Feed lastKnownProjectDir from the first attribution into the second batch
+      const savedLastKnown = promptAttributions[0]?.projectDir || null;
+      const sessionStats = db.getSessionStats(sessionId);
+      const lastKnownProjectDir = typeof db.getLatestAttributedProjectDir === "function"
+        ? db.getLatestAttributedProjectDir(sessionId)
+        : null;
+      const userAttributions = resolveProjectAttributions(userEvents, {
+        sessionOriginDir: sessionStats?.project_dir || projectDir,
+        inputProjectDir: projectDir,
+        workspaceRoots: Array.isArray(input.workspace_roots) ? input.workspace_roots : [],
+        lastKnownProjectDir: savedLastKnown || lastKnownProjectDir,
+      });
+      for (let i = 0; i < userEvents.length; i++) {
+        db.insertEvent(sessionId, userEvents[i], "UserPromptSubmit", userAttributions[i]);
+      }
+
+      db.close();
+    }
+  } catch {
+    // UserPromptSubmit must never block the session — silent fallback
   }
-} catch {
-  // UserPromptSubmit must never block the session — silent fallback
-}
+});

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.107",
+  "version": "1.0.109",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.107",
+  "version": "1.0.109",
   "type": "module",
   "description": "MCP plugin that saves 98% of your context window. Works with Claude Code, Gemini CLI, VS Code Copilot, OpenCode, and Codex CLI. Sandboxed code execution, FTS5 knowledge base, and intent-driven search.",
   "author": "Mert Koseoğlu",
@@ -73,6 +73,7 @@
     "openclaw.plugin.json",
     "start.mjs",
     "scripts/postinstall.mjs",
+    "scripts/heal-better-sqlite3.mjs",
     "README.md",
     "LICENSE"
   ],

package/scripts/heal-better-sqlite3.mjs

@@ -0,0 +1,108 @@
+/**
+ * Self-heal a missing better-sqlite3 native binding (#408).
+ *
+ * Single source of truth for the 3-layer heal used by both
+ * `scripts/postinstall.mjs` (install-time) and `hooks/ensure-deps.mjs`
+ * (runtime). Keeping one implementation avoids the duplicated logic the
+ * maintainer flagged on PR #410.
+ *
+ * Background:
+ *   On Windows, `npm rebuild better-sqlite3` falls through to `node-gyp`
+ *   when prebuild-install is not on cmd.exe PATH, then dies for users
+ *   without Visual Studio C++ tooling. We bypass that by spawning
+ *   prebuild-install JS directly with `process.execPath`.
+ *
+ * Layered heal:
+ *   A. Spawn prebuild-install via process.execPath — bypasses PATH/MSVC.
+ *   B. `npm install better-sqlite3` (re-resolves tree, NOT `npm rebuild`).
+ *   C. Write actionable stderr message naming `npm install better-sqlite3`
+ *      and the Windows / #408 context.
+ *
+ * Best-effort posture: every layer is wrapped in try/catch and the
+ * function never throws. Caller will fail naturally on first DB open if
+ * heal could not produce a working binding.
+ *
+ * @see https://github.com/mksglu/context-mode/issues/408
+ */
+
+import { existsSync } from "node:fs";
+import { execSync, spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { createRequire } from "node:module";
+
+/**
+ * Self-heal a missing better_sqlite3.node binding.
+ *
+ * @param {string} pkgRoot - the directory containing node_modules/better-sqlite3
+ * @returns {{ healed: boolean, reason?: string }}
+ */
+export function healBetterSqlite3Binding(pkgRoot) {
+  try {
+    const bsqRoot = resolve(pkgRoot, "node_modules", "better-sqlite3");
+    if (!existsSync(bsqRoot)) {
+      // No package at all — caller (ensure-deps install branch) handles this.
+      return { healed: false, reason: "package-missing" };
+    }
+    const bindingPath = resolve(bsqRoot, "build", "Release", "better_sqlite3.node");
+    if (existsSync(bindingPath)) {
+      return { healed: true, reason: "binding-present" };
+    }
+
+    const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
+
+    // ── Layer A: spawn prebuild-install directly via process.execPath ──
+    // Bypasses cmd.exe PATH and MSVC requirement.
+    try {
+      let prebuildBin = null;
+      try {
+        const req = createRequire(resolve(bsqRoot, "package.json"));
+        prebuildBin = req.resolve("prebuild-install/bin");
+      } catch { /* fall through to manual walk */ }
+      if (!prebuildBin) {
+        const candidates = [
+          resolve(bsqRoot, "node_modules", "prebuild-install", "bin.js"),
+          resolve(pkgRoot, "node_modules", "prebuild-install", "bin.js"),
+        ];
+        for (const c of candidates) {
+          if (existsSync(c)) { prebuildBin = c; break; }
+        }
+      }
+      if (prebuildBin) {
+        const r = spawnSync(
+          process.execPath,
+          [prebuildBin, "--target", process.versions.node, "--runtime", "node"],
+          { cwd: bsqRoot, stdio: "pipe", timeout: 120000, env: { ...process.env } },
+        );
+        if (r.status === 0 && existsSync(bindingPath)) {
+          return { healed: true, reason: "prebuild-install" };
+        }
+      }
+    } catch { /* best effort — try Layer B */ }
+
+    // ── Layer B: `npm install better-sqlite3` — NOT `npm rebuild` ──
+    // Re-resolves tree and re-runs prebuild-install via the package's
+    // own install script. Avoids the rebuild → node-gyp fall-through.
+    try {
+      execSync(
+        `${npmBin} install better-sqlite3 --no-package-lock --no-save --silent`,
+        { cwd: pkgRoot, stdio: "pipe", timeout: 120000, shell: true },
+      );
+      if (existsSync(bindingPath)) {
+        return { healed: true, reason: "npm-install" };
+      }
+    } catch { /* best effort — fall through to Layer C */ }
+
+    // ── Layer C: actionable stderr — give the user a real next step ──
+    try {
+      process.stderr.write(
+        "\n[context-mode] better-sqlite3 native binding could not be installed automatically.\n" +
+        "  This is a known issue on Windows when prebuild-install is not on PATH (#408).\n" +
+        "  Workaround: run `npm install better-sqlite3` from the plugin directory.\n\n",
+      );
+    } catch { /* stderr unavailable — give up silently */ }
+    return { healed: false, reason: "manual-required" };
+  } catch {
+    // Outermost guard — never throw, never block the caller.
+    return { healed: false, reason: "manual-required" };
+  }
+}