@mxalbert/context-mode 2.0.0

package/scripts/plugin-cache-integrity.mjs

@@ -0,0 +1,248 @@
+/**
+ * Plugin cache integrity check (Algo-D4 + Algo-D5).
+ *
+ * Algorithmic defense against #550: a partial install (interrupted npm
+ * install, broken marketplace pull, half-finished /ctx-upgrade) leaves
+ * start.mjs spawnable but a critical sibling (server.bundle.mjs,
+ * cli.bundle.mjs, hooks/<event>.mjs, …) missing. The MCP child then
+ * dies silently downstream and the user sees an opaque "MCP server
+ * failed to start" with no actionable signal.
+ *
+ * The expected sibling tree is DERIVED from `package.json files[]` —
+ * the npm publish source of truth. Adding a new entry there auto-
+ * extends the integrity check; no parallel hardcoded list to maintain
+ * (the trap that bites every project that hand-rolls "list of files
+ * that must exist at runtime").
+ *
+ * Two consumers:
+ *   1. start.mjs at boot — calls assertPluginCacheIntegrity, on !ok
+ *      writes a structured CONTEXT_MODE_PARTIAL_INSTALL stderr block
+ *      and exits 2. Fail-fast — the alternative is a downstream stack
+ *      trace from `import("./server.bundle.mjs")` that hides the
+ *      actual root cause.
+ *   2. src/cli.ts ctx doctor (Algo-D5) — same helper, same answer,
+ *      surfaced as a HealthCheck so users get the diagnostic without
+ *      restarting the MCP server.
+ *
+ * Pure JS, Node.js built-ins only. Ships in package.json files[] so
+ * users running off the npm tarball get the same code path the
+ * developer ran during `pretest`.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/**
+ * Walk a directory recursively, returning a flat list of relative file
+ * paths (using `/` as separator inside the returned strings). Skips
+ * unreadable entries silently — the integrity check operates on what
+ * IS readable; missing entries are reported by the caller.
+ */
+function listFilesRecursive(absDir, baseAbs) {
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(absDir);
+  } catch {
+    return out; // unreadable — caller will report the parent as missing
+  }
+  for (const name of entries) {
+    const full = join(absDir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      out.push(...listFilesRecursive(full, baseAbs));
+    } else {
+      out.push(relative(baseAbs, full));
+    }
+  }
+  return out;
+}
+
+/**
+ * Compute the expected sibling tree for a given pluginRoot, derived
+ * from the supplied `package.json files[]` array.
+ *
+ * Algorithm:
+ *   - Each entry in files[] is resolved against pluginRoot.
+ *   - If it points to a directory → list every file inside recursively.
+ *   - If it points to a file → kept as-is.
+ *   - Entries that don't exist at probe-time are EXCLUDED from the
+ *     manifest (they show up as `missing` in the assert step instead).
+ *     This avoids the trap of "manifest contains paths that have never
+ *     existed" — the manifest is a snapshot of WHAT IS, not WHAT WAS
+ *     PUBLISHED.
+ *
+ * Returns relative paths (relative to pluginRoot). Used by both
+ * assertPluginCacheIntegrity and the doctor surface.
+ */
+export function derivePluginManifest({ pkg, pluginRoot }) {
+  if (!pkg || !Array.isArray(pkg.files)) return [];
+  const manifest = new Set();
+  for (const entry of pkg.files) {
+    if (typeof entry !== "string" || !entry) continue;
+    const absEntry = join(pluginRoot, entry);
+    if (!existsSync(absEntry)) continue;
+    let st;
+    try {
+      st = statSync(absEntry);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      for (const f of listFilesRecursive(absEntry, pluginRoot)) manifest.add(f);
+    } else {
+      manifest.add(entry);
+    }
+  }
+  return [...manifest];
+}
+
+/**
+ * LEGACY_FALLBACK — the v1.0.126 hardcoded REQUIRED_RUNTIME_SIBLINGS,
+ * preserved verbatim. Forms the union seed for the algorithmic set so
+ * the post-558 contract is strictly additive over the pre-558 contract
+ * (no required sibling ever silently disappears).
+ *
+ * Also acts as a safety net when `package.json` is unreadable — the
+ * boot gate stays loud even if the publish manifest is corrupted.
+ */
+const LEGACY_FALLBACK = Object.freeze([
+  "server.bundle.mjs",
+  "cli.bundle.mjs",
+  join("hooks", "pretooluse.mjs"),
+  join("hooks", "posttooluse.mjs"),
+  join("hooks", "precompact.mjs"),
+  join("hooks", "sessionstart.mjs"),
+  join("hooks", "userpromptsubmit.mjs"),
+]);
+
+/**
+ * SOFT_FALLBACK_BUNDLES — bundles that already implement
+ * bundle-first / build-fallback resolution (via session-loaders.mjs or
+ * session-helpers.mjs). Their absence on a published install is
+ * gracefully recoverable, so they MUST NOT join the fail-fast boot
+ * gate — the gate would refuse to start a working install.
+ *
+ * The security bundle is intentionally NOT here: its absence creates a
+ * silent fail-OPEN regression (#558), so it IS boot-critical.
+ */
+const SOFT_FALLBACK_BUNDLES = new Set([
+  "hooks/session-extract.bundle.mjs",
+  "hooks/session-snapshot.bundle.mjs",
+  "hooks/session-db.bundle.mjs",
+  "hooks/session-attribution.bundle.mjs",
+]);
+
+/**
+ * Algorithmically extract every esbuild output path from
+ * `package.json scripts.bundle`. The bundle script is the SINGLE
+ * SOURCE OF TRUTH for "what bundles this build produces" — parsing
+ * its `--outfile=…` arguments avoids the parallel-list trap that
+ * bit Algo-D4 v1.0.126 (the hardcoded REQUIRED list lagged the
+ * actual bundle output).
+ *
+ * Returns POSIX-style relative paths (forward slashes) for stable
+ * comparison with SOFT_FALLBACK_BUNDLES. Caller normalizes to
+ * `path.join` shape before pluginRoot-relative resolution.
+ */
+function extractBundleOutfiles(pkg) {
+  const script = pkg?.scripts?.bundle;
+  if (typeof script !== "string") return [];
+  const out = new Set();
+  // Match every `--outfile=<path>` token (path is whitespace-delimited
+  // because the script chains commands with `&&`).
+  const re = /--outfile=(\S+)/g;
+  let m;
+  while ((m = re.exec(script)) !== null) {
+    out.add(m[1]);
+  }
+  return [...out];
+}
+
+/**
+ * Algorithmic — derive the boot-critical sibling set as the union of:
+ *   1. LEGACY_FALLBACK (the v1.0.126 contract, preserved verbatim).
+ *   2. Every esbuild output path from `package.json scripts.bundle`
+ *      that is NOT in SOFT_FALLBACK_BUNDLES.
+ *
+ * Why algorithmic instead of hardcoded:
+ *
+ *   v1.0.126 shipped Algo-D4 with a hardcoded REQUIRED_RUNTIME_SIBLINGS
+ *   array that omitted `hooks/security.bundle.mjs` (the bundle didn't
+ *   ship until v1.0.127). The hardcoded list would need manual
+ *   extension every time a runtime bundle is added — the same trap
+ *   would re-bite the next bundle. Deriving from `scripts.bundle`
+ *   closes the trap: any new bundle output is auto-gated unless it
+ *   joins the soft-fallback whitelist (which is itself an explicit
+ *   architectural decision, not a maintenance burden). (#558)
+ *
+ * Returns OS-native-separator relative paths (suitable for
+ * `path.join(pluginRoot, …)`).
+ *
+ * If `package.json` is unreadable, returns LEGACY_FALLBACK as a
+ * safety net so the boot gate never goes silent due to a parse
+ * error in the publish manifest.
+ */
+export function getRequiredRuntimeSiblings(pluginRoot) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf-8"));
+  } catch {
+    return [...LEGACY_FALLBACK];
+  }
+  const required = new Set(LEGACY_FALLBACK);
+  for (const outfile of extractBundleOutfiles(pkg)) {
+    // Normalize to POSIX for soft-fallback membership check —
+    // scripts.bundle is hand-authored with forward slashes already,
+    // but be defensive in case a Windows-authored package.json ever
+    // reaches us.
+    const posix = outfile.split(sep).join("/");
+    if (SOFT_FALLBACK_BUNDLES.has(posix)) continue;
+    // Convert back to OS-native sep for downstream filesystem ops.
+    required.add(posix.split("/").join(sep));
+  }
+  return [...required];
+}
+
+/**
+ * Verify boot-critical siblings exist at pluginRoot.
+ *
+ * Returns `{ ok, missing }`. Pure — does NOT touch process.exit or
+ * stderr. The caller (start.mjs at boot, src/cli.ts at doctor) decides
+ * the failure surface (fail-fast exit 2 vs. doctor diagnostic).
+ *
+ * Required-set is computed by `getRequiredRuntimeSiblings()` —
+ * algorithmically derived from `package.json files[]` filtered to the
+ * RUNTIME_CRITICAL_PATTERN. Drift between publish manifest and runtime
+ * contract becomes architecturally impossible (#558).
+ */
+export function assertPluginCacheIntegrity({ pluginRoot }) {
+  const missing = [];
+  for (const rel of getRequiredRuntimeSiblings(pluginRoot)) {
+    const abs = join(pluginRoot, rel);
+    if (!existsSync(abs)) missing.push(abs);
+  }
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * Format the structured stderr block start.mjs emits when integrity
+ * fails. Marker line `CONTEXT_MODE_PARTIAL_INSTALL` lets external
+ * monitoring grep for the exact failure mode without parsing free-form
+ * text. Keep the format stable across versions.
+ */
+export function formatPartialInstallReport({ pluginRoot, missing }) {
+  const lines = [
+    "CONTEXT_MODE_PARTIAL_INSTALL",
+    `  pluginRoot: ${pluginRoot}`,
+    "  missing:",
+    ...missing.map((m) => `    - ${m}`),
+    "  fix: rm -rf the install dir and re-pull (marketplace) or run `npm install -g @mxalbert/context-mode` again.",
+    "",
+  ];
+  return lines.join("\n");
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+/**
+ * postinstall — cross-platform post-install tasks
+ *
+ * 1. OpenClaw detection (print helper message)
+ * 2. Windows global install: fix broken bin→node_modules path
+ *    when nvm4w places the shim and node_modules in different directories.
+ *    Creates a directory junction so npm's %~dp0\node_modules\... resolves.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, symlinkSync, lstatSync, unlinkSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { dirname, resolve, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { healBetterSqlite3Binding } from "./heal-better-sqlite3.mjs";
+import { healInstalledPlugins, healSettingsEnabledPlugins, healPluginJsonMcpServers, sweepStaleMcpJson } from "./heal-installed-plugins.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, "..");
+
+// npm package identity (v2.0.0 fork rename). The plugin/display id stays
+// "context-mode"; only the npm package name is scoped.
+const PACKAGE_NAME = "@mxalbert/context-mode";
+const PLUGIN_ID = "context-mode";
+// Claude Code registry key: "<pluginId>@<npmPackage>". A scoped package
+// yields a double-@ key ("context-mode@@mxalbert/context-mode").
+const PLUGIN_KEY = `${PLUGIN_ID}@${PACKAGE_NAME}`;
+
+// ── -2. Issue #564 — Linux SIGSEGV class hard-fail (v1.0.132) ────────
+// On Linux + Node < 22.5 + no Bun, better-sqlite3's native addon is
+// vulnerable to V8 calling `madvise(MADV_DONTNEED)` on memory ranges
+// that overlap the addon's `.got.plt` section, corrupting resolved
+// symbol addresses and causing sporadic SIGSEGV (1-4/hour) — see
+// https://github.com/nodejs/node/issues/62515 and our internal #564.
+//
+// node:sqlite (built-in, no native addon, no .got.plt to corrupt) ships
+// from Node 22.5 onward — that is the contract `hasModernSqlite()` in
+// src/db-base.ts encodes. Six prior fixes (#228, #331, #461, #540,
+// #551, #556) silently assumed users had Node >= 22.5 on Linux; #564
+// is the second confirmed report (after #556) of the same SIGSEGV
+// class on Node 20.
+//
+// The architect mandate for v1.0.132 is HARD-FAIL, not warn-then-
+// degrade. `engines.node >= 22.5.0` in package.json is cosmetic under
+// the default npm `engine-strict=false`, so the contract has to be
+// enforced HERE — preinstall/postinstall is the only place that can
+// `process.exit(1)` across npm/pnpm/yarn.
+//
+// Linux + Bun is allowed through (bun:sqlite sidesteps better-sqlite3
+// entirely). Non-Linux platforms are unaffected by the madvise bug
+// and pass through unchanged.
+{
+  const isLinux = process.platform === "linux";
+  const hasBun =
+    typeof globalThis.Bun !== "undefined" ||
+    typeof process.versions.bun === "string";
+  const [majStr, minStr] = (process.versions.node ?? "0.0.0").split(".");
+  const major = Number(majStr);
+  const minor = Number(minStr);
+  const hasModernNode =
+    Number.isFinite(major) &&
+    Number.isFinite(minor) &&
+    (major > 22 || (major === 22 && minor >= 5));
+  if (isLinux && !hasBun && !hasModernNode) {
+    process.stderr.write(
+      "\n" +
+      "context-mode: install aborted\n" +
+      "  Linux + Node " + (process.versions.node ?? "?") + " is unsupported.\n" +
+      "  context-mode requires Node.js >= 22.5 (or Bun) on Linux to avoid the\n" +
+      "  V8 madvise(MADV_DONTNEED) SIGSEGV affecting better-sqlite3 (1-4/hour).\n" +
+      "  Tracking: https://github.com/nodejs/node/issues/62515\n" +
+      "           https://github.com/mxalbert1996/context-mode/issues/564\n" +
+      "\n" +
+      "  Fix: upgrade Node (recommended)\n" +
+      "    nvm install 22.5 && nvm use 22.5\n" +
+      "    npm install -g @mxalbert/context-mode\n" +
+      "\n" +
+      "  Or: run under Bun\n" +
+      "    curl -fsSL https://bun.sh/install | bash\n" +
+      "    bun add -g @mxalbert/context-mode\n" +
+      "\n",
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * True when running as a real `npm install -g @mxalbert/context-mode`. We use this
+ * to keep contributors' local `npm install` runs from rewriting their HOME's
+ * Claude Code registry (would be very surprising during dev).
+ *
+ * Heuristic: npm sets `npm_config_global=true` for global installs AND the
+ * package directory has no nearby `.git` (a contributor's clone always
+ * does). Both signals must agree.
+ */
+function isGlobalInstall() {
+  if (process.env.npm_config_global !== "true") return false;
+  // Walk up a few levels looking for .git — contributors always have one.
+  let dir = pkgRoot;
+  for (let i = 0; i < 4; i++) {
+    if (existsSync(join(dir, ".git"))) return false;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return true;
+}
+
+/**
+ * Validate that a path is safe to interpolate into a cmd.exe command.
+ * Rejects characters that could enable command injection via cmd.exe.
+ */
+function isSafeWindowsPath(p) {
+  return !/[&|<>"^%\r\n]/.test(p);
+}
+
+// ── -1. v1.0.114 hotfix — installed_plugins.json registry repair ─────
+// /ctx-upgrade in v1.0.113 poisoned the registry (entry.version drifted
+// + enabledPlugins emptied), making Claude Code's plugin loader skip
+// context-mode entirely. start.mjs HEAL 3+4 fix this on every MCP boot,
+// but already-broken users have no MCP to boot — they need the heal to
+// run from npm postinstall. Shared module so both call sites stay in
+// sync. Only runs in real `npm install -g` to avoid surprising
+// contributors. Best effort, never blocks install. (#46915 follow-up.)
+if (isGlobalInstall()) {
+  try {
+    const registryPath = resolve(homedir(), ".claude", "plugins", "installed_plugins.json");
+    const pluginCacheRoot = resolve(homedir(), ".claude", "plugins", "cache");
+    const result = healInstalledPlugins({
+      registryPath,
+      pluginCacheRoot,
+      pluginKey: PLUGIN_KEY,
+    });
+    if (result.skipped === "no-registry") {
+      // Standalone npm user (no Claude Code) — silent success.
+      process.stderr.write("context-mode: install OK, no Claude Code registry found\n");
+    } else if (result.error) {
+      process.stderr.write(`context-mode: install OK, registry heal skipped (${result.error})\n`);
+    } else if (result.healed && result.healed.length > 0) {
+      process.stderr.write(`context-mode: healed installed_plugins.json (${result.healed.join(", ")})\n`);
+    } else {
+      process.stderr.write("context-mode: install OK, no heal needed\n");
+    }
+  } catch (err) {
+    // Never block install on a heal failure.
+    try {
+      process.stderr.write(`context-mode: install OK, heal aborted (${(err && err.message) || err})\n`);
+    } catch { /* truly best effort */ }
+  }
+
+  // v1.0.116: also heal settings.json.enabledPlugins (the file Claude Code's
+  // plugin loader actually reads). v1.0.114 only touched installed_plugins.json.
+  try {
+    const settingsPath = resolve(homedir(), ".claude", "settings.json");
+    const r = healSettingsEnabledPlugins({
+      settingsPath,
+      pluginKey: PLUGIN_KEY,
+    });
+    if (r.healed && r.healed.length > 0) {
+      process.stderr.write(`context-mode: healed settings.json (${r.healed.join(", ")})\n`);
+    }
+    // skipped/error: silent — already covered by the prior heal's stderr line.
+  } catch { /* never block install */ }
+
+  // v1.0.119: Layer 5b (Issue #523). Heal .claude-plugin/plugin.json's
+  // mcpServers["context-mode"].args[0] when /ctx-upgrade left a tmpdir-prefixed
+  // path baked in. Iterates EVERY installed cache entry's installPath so
+  // already-broken users self-recover the next time `npm install -g @mxalbert/context-mode`
+  // runs. Best effort, never blocks install.
+  try {
+    const ipPath = resolve(homedir(), ".claude", "plugins", "installed_plugins.json");
+    const cacheRoot = resolve(homedir(), ".claude", "plugins", "cache");
+    if (existsSync(ipPath)) {
+      const ip = JSON.parse(readFileSync(ipPath, "utf-8"));
+      const entries = (ip && ip.plugins && ip.plugins[PLUGIN_KEY]) || [];
+      let healedAny = false;
+      if (Array.isArray(entries)) {
+        for (const entry of entries) {
+          const installPath = entry && entry.installPath;
+          if (typeof installPath !== "string" || !installPath) continue;
+          try {
+            const r = healPluginJsonMcpServers({
+              pluginRoot: installPath,
+              pluginCacheRoot: cacheRoot,
+              pluginKey: PLUGIN_KEY,
+            });
+            if (r && Array.isArray(r.healed) && r.healed.length > 0) {
+              healedAny = true;
+            }
+          } catch { /* per-entry best effort */ }
+        }
+      }
+      // Issue #609 — Layer 6: sweep stale `.mcp.json` files from every
+      // per-version cache dir. Replaces the previous per-entry healMcpJsonArgs
+      // loop (v1.0.122) — `.mcp.json` is no longer written from cli.ts so
+      // remaining files in the cache are stale carry-forwards that block
+      // future auto-updates from working cleanly. Single sweep per install.
+      try {
+        const sweepResult = sweepStaleMcpJson({
+          pluginCacheRoot: cacheRoot,
+          pluginKey: PLUGIN_KEY,
+        });
+        if (sweepResult && Array.isArray(sweepResult.removed) && sweepResult.removed.length > 0) {
+          process.stderr.write(`context-mode: swept ${sweepResult.removed.length} stale .mcp.json file(s) (Issue #609)\n`);
+        }
+      } catch { /* never block install */ }
+      if (healedAny) {
+        process.stderr.write("context-mode: healed mcpServers args (Issue #523)\n");
+      }
+    }
+  } catch { /* never block install */ }
+}
+
+// ── 0. Self-heal Layer 3: Backward symlink for stale registry (anthropics/claude-code#46915) ──
+// When this install completes, installed_plugins.json may still point to an old
+// non-existent path. Create a symlink from that old path → our new directory.
+try {
+  const ipPath = resolve(homedir(), ".claude", "plugins", "installed_plugins.json");
+  if (existsSync(ipPath)) {
+    const ip = JSON.parse(readFileSync(ipPath, "utf-8"));
+    const cacheRoot = resolve(homedir(), ".claude", "plugins", "cache");
+    for (const [key, entries] of Object.entries(ip.plugins || {})) {
+      if (key !== PLUGIN_KEY) continue;
+      for (const entry of entries) {
+        const rp = entry.installPath;
+        if (!rp || existsSync(rp)) continue;
+        // Path traversal guard
+        if (!resolve(rp).startsWith(cacheRoot + sep)) continue;
+        // Remove dangling symlink
+        try { if (lstatSync(rp).isSymbolicLink()) unlinkSync(rp); } catch {}
+        const rpParent = dirname(rp);
+        if (!existsSync(rpParent)) mkdirSync(rpParent, { recursive: true });
+        try {
+          symlinkSync(pkgRoot, rp, process.platform === "win32" ? "junction" : undefined);
+        } catch { /* may fail if path is locked or permissions */ }
+      }
+    }
+  }
+} catch { /* best effort — don't block install */ }
+
+// ── 1. OpenClaw detection ────────────────────────────────────────────
+if (process.env.OPENCLAW_STATE_DIR) {
+  console.log("\n  OpenClaw detected. Run: npm run install:openclaw\n");
+}
+
+// ── 2. Windows global install — nvm4w junction fix ───────────────────
+// npm's .cmd shim resolves modules via %~dp0\node_modules\<pkg>\...
+// On nvm4w the shim lives at C:\nvm4w\nodejs\ but node_modules is at
+// C:\Users\<USER>\AppData\Roaming\npm\node_modules\. The relative path
+// breaks because they're on different prefixes.
+//
+// Fix: detect the mismatch and create a directory junction so the shim
+// can reach us through the expected relative path.
+
+if (process.platform === "win32" && process.env.npm_config_global === "true") {
+  try {
+    // npm prefix is where both the .cmd shims and node_modules live
+    // Use npm_config_prefix env (set during install) or fall back to `npm config get prefix`
+    // Note: `npm bin -g` was removed in npm v9+, so we use prefix instead
+    const prefix = (
+      process.env.npm_config_prefix ||
+      execSync("npm config get prefix", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim()
+    );
+
+    const actualPkgDir = pkgRoot;
+
+    // npm's .cmd shim uses %~dp0\node_modules\<pkg>\... to find the entry point.
+    // On nvm4w, stale shims at C:\nvm4w\nodejs\ may exist alongside correct ones
+    // at the npm prefix. We create junctions at ALL known shim locations.
+    const shimDirs = new Set([prefix]);
+
+    // Detect stale shim locations via `where` command
+    try {
+      const whereOutput = execSync("where context-mode.cmd", {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+      for (const line of whereOutput.split(/\r?\n/)) {
+        if (line.endsWith("context-mode.cmd")) {
+          shimDirs.add(dirname(line));
+        }
+      }
+    } catch { /* where may fail if not installed yet */ }
+
+    for (const shimDir of shimDirs) {
+      // Scoped package: npm places it at node_modules/@mxalbert/context-mode.
+      const expectedPkgDir = join(shimDir, "node_modules", PACKAGE_NAME);
+
+      if (
+        resolve(expectedPkgDir).toLowerCase() !== resolve(actualPkgDir).toLowerCase() &&
+        !existsSync(expectedPkgDir)
+      ) {
+        const expectedNodeModules = join(shimDir, "node_modules");
+        if (!existsSync(expectedNodeModules)) {
+          mkdirSync(expectedNodeModules, { recursive: true });
+        }
+        // Ensure the @scope parent directory exists before creating the junction.
+        if (!existsSync(dirname(expectedPkgDir))) {
+          mkdirSync(dirname(expectedPkgDir), { recursive: true });
+        }
+
+        // Create directory junction (no admin privileges needed on Windows 10+)
+        // Validate paths to prevent cmd.exe injection via shell metacharacters
+        if (!isSafeWindowsPath(expectedPkgDir) || !isSafeWindowsPath(actualPkgDir)) {
+          console.warn(`  context-mode: skipping junction — path contains unsafe characters`);
+        } else {
+          execSync(`mklink /J "${expectedPkgDir}" "${actualPkgDir}"`, {
+            shell: "cmd.exe",
+            stdio: "pipe",
+          });
+          console.log(`\n  context-mode: created junction for nvm4w compatibility`);
+          console.log(`    ${expectedPkgDir} → ${actualPkgDir}\n`);
+        }
+      }
+    }
+
+    // Also fix stale shims that reference old bin entry (build/cli.js → cli.bundle.mjs)
+    try {
+      const whereOutput = execSync("where context-mode.cmd", {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+      for (const line of whereOutput.split(/\r?\n/)) {
+        if (line.endsWith("context-mode.cmd")) {
+          const content = readFileSync(line, "utf-8");
+          if (content.includes("build\\cli.js") || content.includes("build/cli.js")) {
+            // Rewrite stale shim to use cli.bundle.mjs
+            const fixed = content
+              .replace(/build[\\\/]cli\.js/g, "cli.bundle.mjs");
+            writeFileSync(line, fixed);
+            console.log(`  context-mode: fixed stale shim at ${line}`);
+          }
+        }
+      }
+    } catch { /* best effort */ }
+  } catch {
+    // Best effort — don't block install. User can use npx as fallback.
+  }
+}
+
+// ── 3. Native binding self-heal — better-sqlite3 (#408) ──────────────
+// On Windows, `npm rebuild` falls through to node-gyp without MSVC; bypass
+// that by spawning prebuild-install directly. Cross-platform safety net —
+// the binding can also go missing on macOS/Linux when prebuilds are stale
+// or the install was interrupted.
+//
+// Logic lives in scripts/heal-better-sqlite3.mjs (shared with
+// hooks/ensure-deps.mjs so there's one source of truth).
+try { healBetterSqlite3Binding(pkgRoot); } catch { /* best effort — don't block install */ }
+
+// ── 4. Hook normalization at install time (#414) ─────────────────────
+// hooks/hooks.json + .claude-plugin/plugin.json ship with `${CLAUDE_PLUGIN_ROOT}`
+// + bare `node` command. On Windows + Claude Code that combination triggers
+// `cjs/loader:1479 MODULE_NOT_FOUND` (placeholder mangling, MSYS path issues,
+// PATH lookup failure). start.mjs normalizes on every MCP boot, but normalizing
+// here too closes the gap for the very first hook fire after a fresh install
+// (before any MCP server has run).
+//
+// Guard 1: only run on REAL `npm install -g @mxalbert/context-mode`. A contributor's
+// `npm install` from a git clone (or CI checkout) must NOT mutate the
+// source-tracked `.claude-plugin/plugin.json` — doing so substitutes the
+// literal `${CLAUDE_PLUGIN_ROOT}` with an absolute path and trips
+// `scripts/assert-asymmetric-drift.mjs` (Issue #531) in the build chain.
+// Reuses `isGlobalInstall()` (section -1 already gates that way); the
+// `.git` walk inside it is what keeps contributor / CI installs untouched.
+//
+// Guard 2: /ctx-upgrade clones the repo to `<tmpdir>/context-mode-upgrade-<epoch>/`
+// and runs `npm install` there before `cpSync`-ing files into the real pluginRoot
+// (src/cli.ts). The tmpdir has no `.git`, so `isGlobalInstall()` returns
+// true there — we need this second check to skip the staging dir. Without
+// it, pkgRoot is the tmpdir → hooks.json gets the tmpdir's absolute paths
+// baked in → cpSync copies that poisoned hooks.json into the real plugin
+// dir → tmpdir is later cleaned → every hook fires with MODULE_NOT_FOUND.
+// start.mjs normalizes correctly on the next MCP boot from the real
+// pluginRoot anyway.
+const TMPDIR_UPGRADE_RE = /[/\\]context-mode-upgrade-\d+[/\\]?$/;
+if (isGlobalInstall() && !TMPDIR_UPGRADE_RE.test(pkgRoot)) {
+  try {
+    // #738: probe for Bun ≥1.0 so the post-install hooks.json rewrite picks
+    // the faster runtime where available. Probe failures (e.g. build not
+    // present yet during `npm install` itself) fall through to nodePath.
+    let jsRuntimePath;
+    try {
+      const { resolveHookRuntime } = await import("../build/runtime.js");
+      const r = resolveHookRuntime();
+      if (r.isBun) jsRuntimePath = r.path;
+    } catch { /* best effort — fall through */ }
+    const { normalizeHooksOnStartup } = await import("../hooks/normalize-hooks.mjs");
+    normalizeHooksOnStartup({
+      pluginRoot: pkgRoot,
+      nodePath: process.execPath,
+      jsRuntimePath,
+      platform: process.platform,
+    });
+  } catch { /* best effort — never block install */ }
+}