@sdsrs/code-graph 0.101.0 → 0.103.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sdsrss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/cli.js

@@ -45,24 +45,47 @@ if (sub === "uninstall") {
   if (process.argv.slice(3).some((a) => a === "--help" || a === "-h")) {
     process.stdout.write(
       "code-graph-mcp uninstall — remove code-graph config + cache from this machine\n\n" +
-      "USAGE:\n    code-graph-mcp uninstall\n\n" +
+      "USAGE:\n    code-graph-mcp uninstall [--unadopt-all] [--purge-global]\n\n" +
       "Restores your prior statusline, strips code-graph hooks from settings.json,\n" +
       "deletes ~/.cache/code-graph, and removes this project's CLAUDE.md adoption\n" +
-      "block. Also run `/plugin uninstall code-graph-mcp` in Claude Code to sync its\n" +
-      "UI, and `code-graph-mcp unadopt` in any OTHER adopted project.\n");
+      "block. --unadopt-all also removes the managed block + detail file from every\n" +
+      "registered adopted project; --purge-global removes the globally-installed\n" +
+      "@sdsrs npm packages even without the plugin-install marker. Also run\n" +
+      "`/plugin uninstall code-graph-mcp` in Claude Code to sync its UI.\n");
     process.exit(0);
   }
   const lifecycle = require("../claude-plugin/scripts/lifecycle");
   const { unadopt } = require("../claude-plugin/scripts/adopt");
-  const r = lifecycle.uninstall();
+  const r = lifecycle.uninstall({
+    purgeGlobal: process.argv.slice(3).includes("--purge-global"),
+    unadoptAll: process.argv.slice(3).includes("--unadopt-all"),
+  });
   let ua = { ok: false };
   try { ua = unadopt(); } catch { /* best-effort — settings/cache already cleaned */ }
   const projectUnadopted = !!(ua && (ua.blockPruned || ua.fileRemoved || ua.claudeMdRemoved));
-  process.stdout.write(
+  let out =
     `Uninstalled code-graph-mcp | settings cleaned=${r.settingsChanged}` +
-    ` | this project unadopted=${projectUnadopted}\n` +
-    "  Also run `/plugin uninstall code-graph-mcp` in Claude Code, and\n" +
-    "  `code-graph-mcp unadopt` in any other adopted project.\n");
+    ` | this project unadopted=${projectUnadopted}\n`;
+  if (r.globalPkgsRemoved.length) {
+    out += `  Removed global npm package(s): ${r.globalPkgsRemoved.join(", ")}\n`;
+  }
+  if (r.globalPkgsRemaining.length) {
+    out += `  Global npm package(s) still installed: ${r.globalPkgsRemaining.join(", ")}\n` +
+      `    Remove with: npm uninstall -g ${r.globalPkgsRemaining.join(" ")}` +
+      (r.pluginInstalledGlobals ? "\n" : "   (or re-run with --purge-global)\n");
+  }
+  if (r.unadopted.length) {
+    const cleaned = r.unadopted.filter((u) => u.cleaned).length;
+    out += `  Unadopted ${cleaned}/${r.unadopted.length} registered project(s) (--unadopt-all).\n`;
+  }
+  const otherAdopted = r.adoptedProjects.filter((p) => p !== process.cwd());
+  if (otherAdopted.length) {
+    out += "  Other adopted project(s) — re-run with --unadopt-all, or in each:" +
+      " `code-graph-mcp unadopt` + `rm -rf .code-graph`\n" +
+      otherAdopted.map((p) => `    ${p}\n`).join("");
+  }
+  out += "  Also run `/plugin uninstall code-graph-mcp` in Claude Code to sync its UI state.\n";
+  process.stdout.write(out);
   process.exit(0);
 }
 

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.101.0",
+  "version": "0.103.0",
   "keywords": [
     "code-graph",
     "ast",

package/claude-plugin/scripts/adopt.js

@@ -339,7 +339,46 @@ function platformGuard() {
 // now lives in project-detect.js — the single activation gate shared with
 // mcp-launcher.js and session-init.js. Imported above and re-exported below.
 
-function adopt({ cwd, templatePath } = {}) {
+// ── Adopted-projects registry ───────────────────────────────
+// ~/.cache/code-graph/adopted-projects.json — every project adopt() has touched.
+// Sole consumer is lifecycle.js uninstall(): without this list it cannot tell
+// the user WHICH projects still carry a managed CLAUDE.md block + .code-graph/
+// index dir (adoption state is otherwise only discoverable per-project).
+// Best-effort: registry loss only degrades uninstall guidance, never adoption.
+
+function adoptedRegistryFile(home) {
+  return path.join(home || os.homedir(), '.cache', 'code-graph', 'adopted-projects.json');
+}
+
+function readAdoptedProjects(home) {
+  try {
+    const list = JSON.parse(fs.readFileSync(adoptedRegistryFile(home), 'utf8'));
+    return Array.isArray(list) ? list.filter((p) => typeof p === 'string') : [];
+  } catch { return []; }
+}
+
+function recordAdopted(projectDir, home) {
+  try {
+    const file = adoptedRegistryFile(home);
+    const list = readAdoptedProjects(home);
+    const abs = path.resolve(projectDir);
+    if (list.includes(abs)) return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeFileAtomic(file, JSON.stringify([...list, abs], null, 2) + '\n');
+  } catch { /* best-effort */ }
+}
+
+function removeAdopted(projectDir, home) {
+  try {
+    const list = readAdoptedProjects(home);
+    const abs = path.resolve(projectDir);
+    const next = list.filter((p) => p !== abs);
+    if (next.length === list.length) return;
+    writeFileAtomic(adoptedRegistryFile(home), JSON.stringify(next, null, 2) + '\n');
+  } catch { /* best-effort */ }
+}
+
+function adopt({ cwd, templatePath, home } = {}) {
   const blocked = platformGuard();
   if (blocked) return blocked;
 
@@ -376,6 +415,7 @@ function adopt({ cwd, templatePath } = {}) {
   const exists = fs.existsSync(cPath);
   const current = exists ? fs.readFileSync(cPath, 'utf8') : '';
   if (current.includes(block)) {
+    recordAdopted(effectiveCwd, home);
     return { ok: true, detailPath: dPath, claudeMdPath: cPath, detailWritten, claudeMdWritten: false, created: false, healed: false };
   }
   const cleaned = exists ? stripSentinelBlock(current) : '';
@@ -383,6 +423,7 @@ function adopt({ cwd, templatePath } = {}) {
   const base = cleaned.replace(/\n+$/, '');
   const prefix = base ? base + '\n\n' : '';
   writeFileAtomic(cPath, prefix + block + '\n');
+  recordAdopted(effectiveCwd, home);
   return { ok: true, detailPath: dPath, claudeMdPath: cPath, detailWritten, claudeMdWritten: true, created: !exists, healed };
 }
 
@@ -495,12 +536,12 @@ function maybeAutoAdopt({ cwd, home, env, scriptPath } = {}) {
     // shipped template / 管理块 漂移时重跑 adopt 对齐。
     // opt-out: CODE_GRAPH_NO_TEMPLATE_REFRESH=1（锁定手动编辑）。
     if (env.CODE_GRAPH_NO_TEMPLATE_REFRESH !== '1' && needsRefresh({ cwd })) {
-      const result = adopt({ cwd });
+      const result = adopt({ cwd, home });
       return { attempted: true, reason: 'refreshed', result, migrated };
     }
     return { attempted: false, reason: 'already-adopted', migrated };
   }
-  const result = adopt({ cwd });
+  const result = adopt({ cwd, home });
   return { attempted: true, reason: 'adopted', result, migrated };
 }
 
@@ -544,6 +585,7 @@ function unadopt({ cwd, home } = {}) {
   // Also sweep any legacy memory-dir remnants (uninstall before auto-migration ran).
   const migrated = migrateLegacyMemoryDir({ cwd, home });
 
+  removeAdopted(effectiveCwd, home);
   return { ok: true, fileRemoved, blockPruned, claudeMdRemoved, target: dPath, claudeMdPath: cPath, migrated };
 }
 
@@ -603,6 +645,7 @@ if (require.main === module) {
 
 module.exports = {
   adopt, unadopt, memoryDir, formatResult, stripSentinelBlock,
+  readAdoptedProjects, recordAdopted, removeAdopted, adoptedRegistryFile,
   isAdopted, isPluginModeInstall, maybeAutoAdopt, needsRefresh, isProjectRoot,
   detectProjectType, buildBlock, buildTriggerRows, migrateLegacyMemoryDir,
   claudeMdPath, detailDir, detailPath,

package/claude-plugin/scripts/auto-update.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 'use strict';
-const { execFileSync } = require('child_process');
+const { execFileSync, spawn } = require('child_process');
 const fs = require('fs');
 const https = require('https');
 const http = require('http');
@@ -9,9 +9,11 @@ const path = require('path');
 const os = require('os');
 const { CACHE_DIR, PLUGIN_ID, MARKETPLACE_NAME, readManifest, readJson, writeJsonAtomic, installedPluginsPath, pluginsCacheDir } = require('./lifecycle');
 const { claudeHome } = require('./claude-config');
-const { clearCache: clearBinaryCache } = require('./find-binary');
-const { readBinaryVersion, isDevMode } = require('./version-utils');
+const { clearCache: clearBinaryCache, globalNodeModulesCandidates, PLATFORM_PKG, detectLibc } = require('./find-binary');
+const { readBinaryVersion, compareVersions, isDevMode } = require('./version-utils');
 const { cgTmpDir } = require('./tmp-dir');
+const { npmSpawnOpts } = require('./npm-exec');
+const { acquireLock } = require('./install-lock');
 
 // ── Environment Checks ────────────────────────────────────
 
@@ -56,9 +58,13 @@ function isForceMode(argv = process.argv.slice(2)) {
 }
 
 // ── Platform → GitHub release asset name mapping ──────────
-function getPlatformAssetName() {
-  const platform = os.platform();
-  const arch = os.arch();
+function getPlatformAssetName({ platform = os.platform(), arch = os.arch(), libc = null } = {}) {
+  // No musl asset is published: the glibc linux build downloads fine but cannot
+  // exec on Alpine, so promoteVerifiedBinary always rejected it and — with the
+  // binary still missing — every SessionStart bypassed the throttle and pulled
+  // the same futile ~40MB again. Null stops the download path entirely; the
+  // launcher surfaces unsupportedPlatformHint (cargo install / glibc image).
+  if (platform === 'linux' && (libc || detectLibc()) === 'musl') return null;
   const key = `${platform}-${arch}`;
   const map = {
     'linux-x64': 'code-graph-mcp-linux-x64',
@@ -106,21 +112,9 @@ function shouldCheck(state, { force = false } = {}) {
   return elapsed >= interval;
 }
 
-// ── Version Comparison (semver) ────────────────────────────
-
-// Assumes plain numeric "M.m.p" releases (the project's tag scheme). A pre-release
-// tag (e.g. "1.2.4-rc1") is NOT semver-ordered: `Number("4-rc1")` is NaN → coerced
-// to 0, dropping that segment's number (so "1.2.4-rc1" wrongly sorts below "1.2.3").
-// Revisit with a real semver compare only if the release process adopts pre-releases.
-function compareVersions(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
-    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
-  }
-  return 0;
-}
+// ── Version Comparison ─────────────────────────────────────
+// compareVersions is imported from version-utils.js (single canonical,
+// pre-release-aware implementation) and re-exported below.
 
 // ── GitHub API ─────────────────────────────────────────────
 
@@ -284,7 +278,11 @@ function cachedBinaryPath() {
 function cachedBinaryNeedsUpdate(latest, { binaryPath = cachedBinaryPath(), readVersion = readBinaryVersion } = {}) {
   if (!latest || !latest.binaryUrl) return false;
   if (!fs.existsSync(binaryPath)) return true;
-  return readVersion(binaryPath) !== latest.version;
+  const current = readVersion(binaryPath);
+  if (!current) return true; // unreadable/broken binary — let the heal replace it
+  // Ordered compare, not string inequality: a binary NEWER than releases/latest
+  // (dev build, or the API momentarily lagging a publish) must not be downgraded.
+  return compareVersions(current, latest.version) < 0;
 }
 
 /**
@@ -298,7 +296,10 @@ function cachedBinaryNeedsUpdate(latest, { binaryPath = cachedBinaryPath(), read
 function cachedBinaryStaleVsState(state, { binaryPath = cachedBinaryPath(), readVersion = readBinaryVersion } = {}) {
   if (!state || !state.latestVersion) return false;
   if (!fs.existsSync(binaryPath)) return false;
-  return readVersion(binaryPath) !== state.latestVersion;
+  const current = readVersion(binaryPath);
+  if (!current) return true; // unreadable/broken — bypass throttle so the heal runs
+  // Ordered compare (see cachedBinaryNeedsUpdate): newer-than-state is not stale.
+  return compareVersions(current, state.latestVersion) < 0;
 }
 
 /**
@@ -556,7 +557,98 @@ async function selfHealStaleBinary(latest, { needsUpdate = cachedBinaryNeedsUpda
   return await download(latest);
 }
 
+// ── Global npm package self-heal ───────────────────────────
+// The `code-graph-mcp` CLI on the user's PATH is the GLOBAL npm shell package
+// (@sdsrs/code-graph) — a delivery surface entirely outside the marketplace
+// plugin, so /plugin update and the binary self-heal above never touch it. In
+// the field it drifts for months (a 0.46.0 wrapper delegating to a 0.101.0
+// binary) and users were expected to run `npm update -g` by hand — which also
+// breaks on unrelated npm-config quirks (EALLOWGIT). Same story for a platform
+// package installed EXPLICITLY at the global top level (the old launcher's
+// manual-install hint suggested exactly that): that relic was the 0.16.6
+// landmine behind the MCP connect-timeout incident.
+//
+// Heal contract: refresh ONLY what the user already installed globally (never
+// introduce a global install they didn't ask for), one bounded npm run per
+// release target, silent failure (an unhealable npm env must not block or spam).
+
+const SHELL_PKG = '@sdsrs/code-graph';
+const GLOBAL_PKG_HEAL_MAX_ATTEMPTS = 3;
+const GLOBAL_PKG_HEAL_TIMEOUT_MS = 180000; // npm resolves + downloads the platform optionalDependency (~40MB)
+
+/** Installed version of a top-level GLOBAL npm package, or null when absent. */
+function globalPkgVersion(name, roots = null) {
+  for (const root of (roots || globalNodeModulesCandidates())) {
+    try {
+      const pkg = readJson(path.join(root, name, 'package.json'));
+      if (pkg && pkg.version) return pkg.version;
+    } catch { /* not installed under this root */ }
+  }
+  return null;
+}
+
+/** Globally-installed packages of ours whose version lags `latestVersion`. */
+function staleGlobalPkgs(latestVersion, roots = null) {
+  const out = [];
+  for (const name of [SHELL_PKG, PLATFORM_PKG]) {
+    const ver = globalPkgVersion(name, roots);
+    if (ver && compareVersions(ver, latestVersion) < 0) out.push({ name, version: ver });
+  }
+  return out;
+}
+
+/** One targeted `npm install -g` for the given specs. Resolves true on exit 0. */
+function npmInstallGlobal(specs) {
+  return new Promise((resolve) => {
+    if (!commandExists('npm')) { resolve(false); return; }
+    const child = spawn('npm', ['install', '-g', ...specs], npmSpawnOpts({
+      timeout: GLOBAL_PKG_HEAL_TIMEOUT_MS,
+      stdio: ['ignore', 'ignore', 'pipe'],
+    }));
+    let stderr = '';
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', () => resolve(false));
+    child.on('exit', (code) => {
+      if (code === 0) {
+        console.error(`[code-graph] global npm package(s) refreshed: ${specs.join(' ')}`);
+        resolve(true);
+      } else {
+        const tail = stderr.trim().split('\n').slice(-2).join(' | ');
+        console.error(`[code-graph] global npm refresh failed (exit ${code}): ${tail}`);
+        resolve(false);
+      }
+    });
+  });
+}
+
+/**
+ * Self-heal globally-installed shell/platform packages to `latest.version`.
+ * Returns a state patch (spread into the update-state save): attempts are
+ * counted PER target version so a persistently-failing npm env stops being
+ * retried after GLOBAL_PKG_HEAL_MAX_ATTEMPTS, and the counter re-arms when the
+ * next release moves the target.
+ */
+async function selfHealGlobalPkgs(latest, state, {
+  readStale = staleGlobalPkgs,
+  install = npmInstallGlobal,
+} = {}) {
+  if (!latest || !latest.version) return {};
+  const stale = readStale(latest.version);
+  if (stale.length === 0) {
+    // Healthy (or nothing installed globally) — clear any leftover counter.
+    return state.globalPkgHealAttempts ? { globalPkgHealAttempts: 0, globalPkgHealVersion: null } : {};
+  }
+  const attempts = state.globalPkgHealVersion === latest.version ? (state.globalPkgHealAttempts || 0) : 0;
+  if (attempts >= GLOBAL_PKG_HEAL_MAX_ATTEMPTS) return {};
+  const ok = await install(stale.map((s) => `${s.name}@${latest.version}`));
+  return {
+    globalPkgHealVersion: latest.version,
+    globalPkgHealAttempts: ok ? 0 : attempts + 1,
+  };
+}
+
 async function checkForUpdate({ installMissing = false, force = false } = {}) {
+  let installLock = null;
   try {
     // Skip in dev mode — unless the launcher explicitly requested a missing-
     // binary install, in which case we MUST proceed regardless of mode (the
@@ -596,6 +688,19 @@ async function checkForUpdate({ installMissing = false, force = false } = {}) {
     // Compare versions
     const hasUpdate = compareVersions(latest.version, installedVersion) > 0;
 
+    // Inter-process gate for every mutating path below (plugin-cache copy,
+    // binary download, global npm heals): concurrent sessions racing here ran
+    // parallel `npm install -g` against one global prefix and clobbered each
+    // other's state-file counters (rateLimited, heal attempts). Skip-if-held:
+    // the holder does the work and its state outcome wins. The launcher's
+    // install chain already holds this lock across its spawn of this script —
+    // it marks that with CODE_GRAPH_INSTALL_LOCK_HELD so we don't deadlock
+    // against our own parent.
+    if (process.env.CODE_GRAPH_INSTALL_LOCK_HELD !== '1') {
+      installLock = acquireLock(path.join(CACHE_DIR, 'install.lock'));
+      if (!installLock) return null;
+    }
+
     if (hasUpdate) {
       const result = await downloadAndInstall(latest);
       const success = result.pluginUpdated;
@@ -615,7 +720,10 @@ async function checkForUpdate({ installMissing = false, force = false } = {}) {
         binaryUpdated: result.binaryUpdated,
         marketplaceRefreshed: result.marketplaceRefreshed,
       };
-      saveState(newState);
+      // Keep any globally-installed shell/platform npm packages in step with
+      // the release the plugin just moved to (see selfHealGlobalPkgs).
+      const globalHeal = await selfHealGlobalPkgs(latest, state);
+      saveState({ ...newState, ...globalHeal });
 
       return {
         updateAvailable: !success,
@@ -632,6 +740,12 @@ async function checkForUpdate({ installMissing = false, force = false } = {}) {
     // failure observed in the field (shell at v0.45, binary pinned at v0.16.6).
     const selfHealedBinary = await selfHealStaleBinary(latest);
 
+    // Same for the GLOBAL npm delivery surface (the `code-graph-mcp` CLI on
+    // PATH + any explicitly-installed platform package): nothing else ever
+    // updates it, and stale copies drift for months (0.46.0 wrapper) or years
+    // (the 0.16.6 platform relic).
+    const globalHeal = await selfHealGlobalPkgs(latest, state);
+
     saveState({
       ...state,
       installedVersion,
@@ -640,6 +754,7 @@ async function checkForUpdate({ installMissing = false, force = false } = {}) {
       updateAvailable: false,
       rateLimited: false,
       binaryUpdated: selfHealedBinary || state.binaryUpdated,
+      ...globalHeal,
     });
     return selfHealedBinary
       ? { updated: false, binaryUpdated: true, from: installedVersion, to: installedVersion }
@@ -647,6 +762,8 @@ async function checkForUpdate({ installMissing = false, force = false } = {}) {
   } catch {
     // Silent failure — never block session
     return null;
+  } finally {
+    if (installLock) installLock.release();
   }
 }
 
@@ -656,7 +773,9 @@ module.exports = {
   isSilentMode, isInstallMissingMode, isForceMode,
   requestJson, resolveProxy, parseLatestRelease, fetchLatestRelease,
   downloadBinary, cachedBinaryPath, cachedBinaryNeedsUpdate, cachedBinaryStaleVsState,
+  getPlatformAssetName,
   selfHealStaleBinary,
+  selfHealGlobalPkgs, staleGlobalPkgs, globalPkgVersion, npmInstallGlobal,
   downloadAndInstall, refreshMarketplaceClone, marketplaceCloneDir,
 };
 

package/claude-plugin/scripts/doctor.js

@@ -8,6 +8,7 @@ const { readBinaryVersion, isDevMode, getNewestMtime } = require('./version-util
 const {
   getPluginVersion, readJson, healthCheck, CACHE_DIR,
   settingsPath, surveyHookCoverage,
+  installedGlobalPkgs, GLOBAL_INSTALL_MARKER, SHELL_PKG,
 } = require('./lifecycle');
 const { findBinary, clearCache: clearBinaryCache } = require('./find-binary');
 
@@ -278,6 +279,37 @@ function runDiagnostics() {
     }
   } catch { /* probe failed — skip */ }
 
+  // 9. Global npm residue — the launcher's background install (or the user)
+  //    may have `npm install -g`'d the shell + platform packages. Surface what
+  //    exists and who owns cleanup: with the plugin-install marker,
+  //    `lifecycle.js uninstall` removes them; without it they are treated as
+  //    user-installed and a plugin uninstall leaves them on PATH.
+  try {
+    const { globalPkgVersion } = require('./auto-update');
+    const { PLATFORM_PKG } = require('./find-binary');
+    const found = [SHELL_PKG, PLATFORM_PKG]
+      .map((name) => ({ name, version: globalPkgVersion(name) }))
+      .filter((p) => p.version);
+    if (found.length) {
+      const marker = !!readJson(GLOBAL_INSTALL_MARKER);
+      // Heal-exhausted is otherwise invisible: selfHealGlobalPkgs stops after
+      // 3 failed npm runs per target version and stays silent until the next
+      // release re-arms the counter — a drifted CLI shim just sits there.
+      const state = readJson(path.join(CACHE_DIR, 'update-state.json')) || {};
+      const healGaveUp = (state.globalPkgHealAttempts || 0) >= 3;
+      results.push({
+        name: 'Global npm packages',
+        status: healGaveUp ? 'warn' : 'ok',
+        detail: found.map((p) => `${p.name}@${p.version}`).join(', ') + (healGaveUp
+          ? ` — self-heal gave up after ${state.globalPkgHealAttempts} failed npm runs targeting v${state.globalPkgHealVersion}; ` +
+            `your npm env likely can't install globally (EACCES/system node). Run manually: npm install -g ${found.map((p) => `${p.name}@${state.globalPkgHealVersion}`).join(' ')}`
+          : (marker
+            ? ' — plugin-installed; `node lifecycle.js uninstall` removes them'
+            : ` — no plugin-install marker; uninstall leaves them (remove: npm uninstall -g ${found.map((p) => p.name).join(' ')})`)),
+      });
+    }
+  } catch { /* probe failed — skip */ }
+
   return results;
 }