claude-mem-lite 6.3.0 → 6.5.0

package/install.mjs

@@ -17,7 +17,7 @@ import {
   statSync,
   lstatSync,
 } from 'fs';
-import { join, resolve, dirname, basename } from 'path';
+import { join, resolve, dirname, basename, sep } from 'path';
 import { homedir, tmpdir } from 'os';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
@@ -54,7 +54,7 @@ const SERVER_PATH = join(INSTALL_DIR, 'server.mjs');
 const HOOK_PATH = join(INSTALL_DIR, 'hook.mjs');
 // P2-7: both constants and the predicate come from lib/plugin-key.mjs, which hook.mjs also
 // imports — this pair used to be typed out in each.
-import { MARKETPLACE_KEY, PLUGIN_KEY, isPluginExplicitlyDisabled } from './lib/plugin-key.mjs';
+import { MARKETPLACE_KEY, PLUGIN_KEY, PLUGIN_NAME, isPluginExplicitlyDisabled } from './lib/plugin-key.mjs';
 const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 
 import {
@@ -68,9 +68,11 @@ import {
   probeBetterSqlite3Binding,
   ensureBetterSqlite3Working,
   nativeBindingRepairHint,
+  isNativeBindingError,
 } from './lib/binding-probe.mjs';
 import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
 import { probeSchemaCompat, schemaSkewRemedy } from './lib/schema-skew.mjs';
+import { isDbUnusableError, dbUnusableRemedy } from './lib/db-unusable.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
 import { ORPHAN_EPISODE_AGE_MS } from './lib/time-constants.mjs';
@@ -333,6 +335,135 @@ function isDevInstall() {
   }
 }
 
+// Last-resort recovery command, printed when the signature-verified repair path itself
+// fails. It resolves the latest RELEASE tarball via the GitHub API rather than fetching
+// `/tarball`, which serves the DEFAULT BRANCH — unreleased WIP. That mattered: repair()
+// exists because the old auto-path ran main HEAD unverified, and until 2026-09-08 the
+// fallback it printed on failure handed the user exactly that behaviour back. A shell
+// one-liner cannot check an Ed25519 signature, so this remains a trust decision the user
+// makes explicitly; pinning it to a release at least removes the unreleased-WIP half.
+//
+// FOUR surfaces carry this string — here, scripts/hook-launcher.mjs (pure-`node:` charter,
+// cannot import lib/), README.md and README.zh-CN.md. Exported so
+// tests/manual-fallback-sync.test.mjs can pin the other three to this one and fail if a
+// fifth appears; a string kept in sync by a comment is a string that drifts.
+export const MANUAL_TARBALL_FALLBACK =
+  'T=$(mktemp -d) && U=$(curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/releases/latest | grep -o \'"tarball_url"[^,]*\' | cut -d\'"\' -f4) && curl -sL "$U" | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install';
+
+/**
+ * Whether the local marketplace clone can still be fast-forwarded.
+ *
+ * This is the near cause of the failure v6.3.0 shipped a detector for. Claude Code updates a
+ * git-source marketplace by pulling that clone; a DIRTY working tree blocks the pull, the
+ * plugin silently stops updating, and eventually the database is written by a newer
+ * claude-mem-lite than the code that has to open it. On this machine the clone was pinned 22
+ * commits behind while everything reported green.
+ *
+ * It gets dirty on its own: with a DIRECTORY-source marketplace, `${CLAUDE_PLUGIN_ROOT}`
+ * resolves inside the clone, and `scripts/launch.mjs` runs `npm install` there whenever
+ * `node_modules/better-sqlite3` is missing — which is every materialization of a new version.
+ * That install rewrites **`package-lock.json`**, which IS tracked, and that is what blocks the
+ * pull. So the plugin's own launcher can create the state that stops the plugin updating.
+ *
+ * **Do not add a `node_modules` special case here.** A first cut did, and pre-ship review
+ * measured it dead: the clone is a clone of THIS repo, whose `.gitignore` carries
+ * `/node_modules`, so `git status --porcelain` never sees it — the branch was reachable only
+ * from a fixture that omitted the `.gitignore` the real clone always has. An ignored
+ * `node_modules` also does not block a fast-forward, so reporting it would have been noise
+ * even if it were visible. The tracked-file dirt is the whole signal.
+ *
+ * Five outcomes, and `unknown` is one of them on purpose: "I could not run git" must not be
+ * reported in the same voice as "the tree is clean".
+ *
+ * Exported for tests/marketplace-clone-health.test.mjs.
+ */
+export function marketplaceCloneHealth(
+  dir,
+  run = (args) => execFileSync('git', args, { encoding: 'utf8', timeout: 20000 }),
+) {
+  if (!existsSync(dir)) return { kind: 'absent' };
+  if (!existsSync(join(dir, '.git'))) return { kind: 'not-git' };
+  let porcelain;
+  try {
+    porcelain = run(['-C', dir, 'status', '--porcelain']);
+  } catch (e) {
+    return { kind: 'unknown', reason: e?.code || e?.message || 'git failed' };
+  }
+  const entries = String(porcelain)
+    .split('\n')
+    .filter((l) => l.trim());
+  if (entries.length === 0) return { kind: 'clean' };
+  return { kind: 'dirty', count: entries.length };
+}
+
+/**
+ * The `mem-lite` / `mem` registrations in `claude mcp list` output that are NOT provided by
+ * a plugin manifest.
+ *
+ * `claude mcp list` prints one `<name>: <command>` line per server, and a plugin-provided
+ * one is named `plugin:<plugin>:<server>`. The old test — `list.includes('mem-lite:')` —
+ * matched inside `plugin:claude-mem-lite:mem-lite:`, so it could not tell the two apart and
+ * always answered "registered" for a plugin user.
+ *
+ * Deliberately named for what it MEASURES: a bare-name registration, whatever its scope.
+ * `mcp list` does not label user vs project scope on the line itself, so calling this
+ * "user-scope" would claim more than the output supports.
+ *
+ * Exported for tests/mcp-registration-parse.test.mjs.
+ */
+export function nonPluginMemRegistrations(listOutput) {
+  const names = [];
+  for (const line of String(listOutput ?? '').split('\n')) {
+    // Anchored, no leading whitespace: the diagnostics block below the list is indented, and
+    // its `└ [Warning] [mem-lite] mcpServers.mem-lite: …` lines are not registrations.
+    const m = /^(\S+):\s+\S/.exec(line);
+    if (!m) continue;
+    const name = m[1];
+    if (name.startsWith('plugin:')) continue;
+    if (name === 'mem-lite' || name === 'mem') names.push(name);
+  }
+  return names;
+}
+
+/**
+ * The remedy line for a `doctor` database check that threw — or null when the failure is
+ * one this cannot classify.
+ *
+ * Returning null is deliberate and is the case worth defending: a diagnostic that always
+ * prints a fix eventually prints the wrong one, and the bare error message is a better
+ * answer than a confident irrelevance. The three CLASSIFIED outcomes are kept apart for the
+ * same reason — "restore this snapshot", "there is no snapshot", and "I could not read the
+ * directory to find out" are three different situations, and collapsing the last two ends
+ * the reader's search with a fact nobody checked.
+ *
+ * Shell commands only, no `claude-mem-lite <cmd>`: the remedy for a broken store must not
+ * itself depend on which install shape the user has (the plugin cache has no CLI on PATH).
+ *
+ * Exported for tests/doctor-db-remedy.test.mjs, which also drives the shipped doctor over a
+ * corrupt file — a pure function nothing calls is the wiring gap this repo keeps finding.
+ */
+export function dbCheckRemedy(dbPath, err) {
+  if (isNativeBindingError(err)) return `Repair: ${nativeBindingRepairHint(PROJECT_DIR)}`;
+  // Classification and remedy both live in lib/db-unusable.mjs since v6.5.0, because the hook
+  // path now has to answer the same question in-session and two copies of a SQLite-message
+  // regex is this repo's named twin-drift class. Doctor keeps its own SENTENCE (one line, no
+  // leading banner); only the decision is shared.
+  if (!isDbUnusableError(err)) return null;
+  const remedy = dbUnusableRemedy(dbPath);
+  if (remedy.kind === 'unknown') return remedy.note;
+  if (remedy.kind === 'set-aside') {
+    return (
+      `No backup snapshot exists beside the database. Set the broken file aside so a fresh ` +
+      `store is created on the next session: ${remedy.command} ` +
+      `— memories in that file are not recoverable without a backup.`
+    );
+  }
+  return (
+    `Restore the newest of ${remedy.snapshotCount} backup snapshot(s): ${remedy.command} ` +
+    `— move the broken file aside first if you want to keep it for inspection.`
+  );
+}
+
 // ─── Install ────────────────────────────────────────────────────────────────
 
 // Dynamic-import helpers, resolved against the installed copy at INSTALL_DIR
@@ -512,6 +643,57 @@ function createCliSymlink() {
   }
 }
 
+/**
+ * Which of our MCP names a PROJECT-scoped `.mcp.json` in `cwd` registers.
+ *
+ * This exists because the installer used to run `claude mcp remove -s project <name>` as
+ * part of "purge any pre-existing registration before re-registering". That command edits
+ * `<cwd>/.mcp.json` — a file that belongs to whatever repository the user happens to be
+ * standing in, not to this installer's state. Measured 2026-09-08: running the installer
+ * from a clone of this repo emptied the tracked root `.mcp.json` (the plugin's own MCP
+ * manifest, and a RELEASE_SIGNED_FILES entry), and nothing said so; only a test noticed.
+ * For anyone else it is a silent edit to a checked-in file that breaks the registration
+ * for every teammate who pulls it.
+ *
+ * `uninstall` has always removed `-s user` only, so the scope discipline already existed
+ * on the other half of the lifecycle; this brings install into line with it and reports
+ * the duplicate instead — same doctrine as the README's mixed-install residue section,
+ * where the tool diagnoses and the user decides.
+ *
+ * @param {string} cwd directory to inspect
+ * @returns {{file: string, names: string[]}} names present, empty when there is nothing to say
+ */
+export function projectScopedMemRegistrations(cwd) {
+  const file = join(cwd, '.mcp.json');
+  try {
+    const servers = JSON.parse(readFileSync(file, 'utf8'))?.mcpServers;
+    // Array.isArray is load-bearing: `typeof [] === 'object'`, so without it an array
+    // falls through to the membership filter and the guard cannot fire on its own
+    // named input — which is how the test case for it was passing.
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return { file, names: [] };
+    return { file, names: ['mem', 'mem-lite'].filter((n) => n in servers) };
+  } catch {
+    // Absent, unreadable, or not JSON — nothing we can honestly report.
+    return { file, names: [] };
+  }
+}
+
+/**
+ * Say so when the directory we are standing in registers our server at PROJECT scope.
+ *
+ * Reporting rather than removing is the whole point — see projectScopedMemRegistrations.
+ */
+function warnProjectScopedMcpDuplicate() {
+  const projectScoped = projectScopedMemRegistrations(process.cwd());
+  if (projectScoped.names.length === 0) return;
+  warn(
+    `${projectScoped.file} also registers ${projectScoped.names.map((n) => `"${n}"`).join(' and ')} ` +
+      `at PROJECT scope — that duplicate wins inside this directory. Left untouched: it is your ` +
+      `repo's file. Remove it with \`claude mcp remove -s project <name>\` if you want the ` +
+      `user-scope registration to apply here.`,
+  );
+}
+
 function registerMcpServer() {
   // 3. Register MCP server (skip if plugin system already handles it)
   // Plugin MCP must stay at root .mcp.json so Claude Code registers plugin:*:mem-lite.
@@ -530,6 +712,12 @@ function registerMcpServer() {
     /* not installed via plugin system */
   }
 
+  // The DISCLOSURE is unconditional even though the removal it replaced was not: a
+  // project-scoped `mem`/`mem-lite` entry shadows the user-scope one inside that directory
+  // whichever way this install provides the server, so a plugin-mode user standing in such a
+  // repo has the same problem and used to get the same silence.
+  warnProjectScopedMcpDuplicate();
+
   if (pluginHandlesMcp) {
     log('MCP server: plugin system handles registration (skipping global)');
     // Clean up stale global registrations (both legacy "mem" and current "mem-lite")
@@ -542,14 +730,13 @@ function registerMcpServer() {
   } else {
     log('Registering MCP server...');
     try {
-      // Purge legacy "mem" and any pre-existing "mem-lite" before re-registering
+      // Purge legacy "mem" and any pre-existing "mem-lite" from OUR scope before
+      // re-registering. User scope only — see projectScopedMemRegistrations for why the
+      // project-scope removal that used to sit here was a bug, not a cleanup.
       for (const name of ['mem', 'mem-lite']) {
         try {
           execFileSync('claude', ['mcp', 'remove', '-s', 'user', name], { stdio: 'pipe' });
         } catch {}
-        try {
-          execFileSync('claude', ['mcp', 'remove', '-s', 'project', name], { stdio: 'pipe' });
-        } catch {}
       }
       execFileSync(
         'claude',
@@ -1136,11 +1323,23 @@ async function uninstall() {
     ok('Marketplace directory removed');
   }
 
-  // 5b. Remove cache directory
+  // 5b. Remove cache directories — OURS unconditionally, the marketplace-wide one gated.
+  //
+  // The gate exists so uninstalling this plugin does not delete a sibling plugin published
+  // under the same marketplace. That reasoning covers `cache/<marketplace>/`; it does not
+  // cover `cache/<marketplace>/claude-mem-lite/`, which is ours alone. Because only the
+  // gated branch existed, a user with any other sdsrss plugin installed kept every cached
+  // version of THIS one — measured at 241 MB on a machine where `/plugin uninstall` had
+  // already removed the manifest, i.e. bytes belonging to a plugin that was gone.
+  const ownCacheDir = join(pluginsDir, 'cache', marketplaceKey, PLUGIN_NAME);
+  if (existsSync(ownCacheDir)) {
+    rmSync(ownCacheDir, { recursive: true, force: true });
+    ok('Plugin cache removed');
+  }
   const cacheDir = join(pluginsDir, 'cache', marketplaceKey);
   if (canRemoveMarketplaceArtifacts && existsSync(cacheDir)) {
     rmSync(cacheDir, { recursive: true, force: true });
-    ok('Plugin cache removed');
+    ok('Marketplace cache directory removed');
   }
 
   // 5c. Clean known_marketplaces.json
@@ -1183,12 +1382,90 @@ async function uninstall() {
       }
     }
   } else {
-    log('Data preserved (use --purge to remove)');
+    // "Data preserved" was true and incomplete, and the gap is what a user notices on
+    // disk: the DB here is fractions of a megabyte while the installed code and its
+    // node_modules — which uninstall has just made unreachable (symlink gone, hooks gone,
+    // MCP registration gone) — are tens of megabytes and were never named. Measured on a
+    // sandbox install right after uninstall: 56 MB total, 53 MB of it node_modules,
+    // against a 0.2 MB DB. Report both halves so nothing large is left unnamed.
+    //
+    // These are APPARENT bytes (`statSync().size`), which is what `du --apparent-size`
+    // reports and NOT what a bare `du -sh` does: block rounding over thousands of small
+    // node_modules files put the same tree at 44.4 MB apparent against 54.3 MB of blocks,
+    // a 22% gap. Do not "reconcile" this line against a plain `du` — they are two rulers.
+    const kept = preservedFootprint();
+    const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+    log(`Data preserved: memories in ${MEM_DATA_DIR} (${mb(kept.memoryBytes)}MB)`);
+    if (kept.restBytes > 0) {
+      log(
+        `  Also kept: the installed code + node_modules under ${DATA_DIR} (${mb(kept.restBytes)}MB) — ` +
+          `a later \`install\` reuses them; nothing runs them now.`,
+      );
+    }
+    log('  `uninstall --purge` removes the directory, memories included');
   }
 
   console.log('\n  Done!\n');
 }
 
+/**
+ * Split what a non-purge uninstall leaves behind into the two halves a user cares about:
+ * the memories, and everything else.
+ *
+ * "Memories" is every file whose name starts with `claude-mem-lite.db` in the data dir —
+ * the DB, its WAL/SHM, and the `.db.<tag>.bak` snapshots. That is DELIBERATELY WIDER than
+ * lib/db-backup.mjs::readSnapshots, which additionally requires the trailing dot and a
+ * `.bak` suffix: this wants everything that is the user's data, that wants snapshots only. "Rest" is the whole install directory minus that,
+ * so it covers the source files, node_modules, runtime/ and metrics/ in one number. The
+ * point of the split is the node_modules order-of-magnitude (53 MB against a 0.2 MB DB on
+ * a fresh sandbox install), not a per-subdirectory audit.
+ *
+ * Never throws: a missing dir, a permission error or a symlink loop all degrade to 0, and
+ * the caller prints the shorter sentence. An uninstall must not fail on a size probe.
+ *
+ * @returns {{memoryBytes: number, restBytes: number}} bytes, 0 when unmeasurable
+ */
+function preservedFootprint() {
+  const DB_PREFIX = 'claude-mem-lite.db';
+  const walk = (dir, onFile) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      try {
+        if (e.isDirectory()) walk(p, onFile);
+        else if (e.isFile()) onFile(p, e.name, statSync(p).size);
+      } catch {
+        /* raced deletion / unreadable entry — skip */
+      }
+    }
+  };
+
+  let memoryBytes = 0;
+  let restBytes = 0;
+  // The memories may live outside the install dir (CLAUDE_MEM_DIR), so measure each dir
+  // for what it actually holds rather than assuming the two are the same tree.
+  walk(MEM_DATA_DIR, (_p, name, size) => {
+    if (name.startsWith(DB_PREFIX)) memoryBytes += size;
+    else if (MEM_DATA_DIR === DATA_DIR) restBytes += size;
+  });
+  if (MEM_DATA_DIR !== DATA_DIR) {
+    // A relocated CLAUDE_MEM_DIR may still sit INSIDE the install dir, in which case walking
+    // DATA_DIR would count the DB and its snapshots a second time — reported 9.0MB against a
+    // true 6.0MB on a nested fixture. Skip the memory tree explicitly rather than assume the
+    // two are disjoint; `+ sep` so a sibling named `<dir>-old` is not swallowed too.
+    const memPrefix = MEM_DATA_DIR.endsWith(sep) ? MEM_DATA_DIR : MEM_DATA_DIR + sep;
+    walk(DATA_DIR, (p, _name, size) => {
+      if (p !== MEM_DATA_DIR && !p.startsWith(memPrefix)) restBytes += size;
+    });
+  }
+  return { memoryBytes, restBytes };
+}
+
 // ─── Cleanup Hooks ───────────────────────────────────────────────────────────
 
 async function cleanupHooks() {
@@ -1224,35 +1501,52 @@ async function status() {
   // configured` at a correctly-installed plugin user — two red marks describing
   // the intended state.
   const shape = detectInstallShape({ home: homedir(), projectDir: PROJECT_DIR, installDir: INSTALL_DIR });
-  const pluginProvides = !!shape.activePluginVersion;
-
-  // MCP
-  try {
-    const list = execFileSync('claude', ['mcp', 'list'], { encoding: 'utf8' });
-    // Accept either the current "mem-lite" registration or the legacy "mem"
-    // name (pre-v2.78) so a user mid-upgrade still sees a green status until
-    // setup.sh / install.mjs purges the legacy entry on next run.
-    // v2.79.1: dropped a `/\bmem\b\s/` fallback regex — the `\b` word boundary
-    // also matched "mem-lite" (because `-` is a non-word char), so the regex
-    // was always-true noise (benign only because the mem-lite checks short-
-    // circuited first). `claude mcp list` formats as `<name>: <command>`, so
-    // the two colon-form checks below cover every shape.
-    const registered = list.includes('mem-lite:') || list.includes('mem:');
-    if (registered) {
-      push('ok', 'mcp', 'MCP server: registered', { registered });
-    } else if (pluginProvides) {
-      push(
-        'ok',
-        'mcp',
-        `MCP server: provided by the plugin manifest (v${shape.activePluginVersion.version} .mcp.json) — no user-scope registration expected`,
-        { registered: false, via: 'plugin' },
-      );
-    } else {
-      push('fail', 'mcp', 'MCP server: not registered', { registered });
+  // A cache DIRECTORY is not an installed plugin — `/plugin uninstall` leaves version dirs
+  // behind (this project's own README documents that), and `activePluginVersion` falls back to
+  // "newest cache dir" when nothing recorded an install. Both branches below credit the
+  // manifest with providing something, so both need the registration, not the directory.
+  const pluginProvides =
+    !!shape.activePluginVersion && pluginIsRegistered({ home: homedir(), settings: readSettings() });
+
+  // MCP. A plugin install answers this from the manifest and does NOT shell out.
+  //
+  // Two reasons, and the first is correctness rather than speed. `claude mcp list` prints a
+  // plugin server as `plugin:claude-mem-lite:mem-lite: …`, and the old substring test
+  // `list.includes('mem-lite:')` matched INSIDE that name — so a plugin user was reported as
+  // having a user-scope registration they do not have, and the branch written for them below
+  // was unreachable. That is the same accidental-match class as the `\bmem\b` regex this
+  // comment block used to describe. Second: the official help says approved servers are
+  // "health-checked", i.e. the call STARTS every MCP server configured on the machine —
+  // measured 2026-09-08 at 2.546s wall for three servers, one of them a remote HTTP endpoint.
+  // A status command should not pay that, and a plugin user gains nothing from it.
+  //
+  // `doctor` GAINS the exec instead (it had none before this change) and runs it
+  // unconditionally: it is the deep check, and it is where the duplicate/legacy registration
+  // the README's "Mixed-install residue" section describes now gets detected — nothing
+  // detected it before. That means `doctor` now health-checks every MCP server on the
+  // machine; both READMEs say so under their `doctor` sections.
+  if (pluginProvides) {
+    push(
+      'ok',
+      'mcp',
+      `MCP server: provided by the plugin manifest (v${shape.activePluginVersion.version} .mcp.json) — no user-scope registration expected`,
+      { registered: false, via: 'plugin' },
+    );
+  } else
+    try {
+      const list = execFileSync('claude', ['mcp', 'list'], { encoding: 'utf8', timeout: 60000 });
+      // Accept either the current "mem-lite" registration or the legacy "mem" name
+      // (pre-v2.78) so a user mid-upgrade still sees a green status until setup.sh /
+      // install.mjs purges the legacy entry on next run.
+      const registered = nonPluginMemRegistrations(list).length > 0;
+      if (registered) {
+        push('ok', 'mcp', 'MCP server: registered', { registered });
+      } else {
+        push('fail', 'mcp', 'MCP server: not registered', { registered });
+      }
+    } catch {
+      push('warn', 'mcp', 'Could not check MCP status', { registered: null });
     }
-  } catch {
-    push('warn', 'mcp', 'Could not check MCP status', { registered: null });
-  }
 
   // Hooks
   const settings = readSettings();
@@ -1707,6 +2001,65 @@ async function doctor() {
     ok('Orphan hooks: none (all hook targets present)');
   }
 
+  // MCP registration. This lives in doctor, not status: `claude mcp list` health-checks —
+  // i.e. STARTS — every MCP server configured on the machine (2.546s wall for three servers,
+  // measured 2026-09-08), which is a cost the deep check can carry and a status line cannot.
+  //
+  // What it buys beyond status: the DUPLICATE. The README's "Mixed-install residue" section
+  // has warned since v3 that a plugin user who once ran the npx/git-clone installer keeps a
+  // bare-name registration that double-registers the server — and nothing in the tool
+  // detected it. Orphan hooks had a check; its MCP twin did not.
+  try {
+    const list = execFileSync('claude', ['mcp', 'list'], { encoding: 'utf8', timeout: 60000 });
+    const bare = nonPluginMemRegistrations(list);
+    // Registration, not directory — see pluginIsRegistered. Crediting a leftover cache dir
+    // here told a working npm-channel install to delete its ONLY MCP registration.
+    const viaPlugin =
+      !!shape?.activePluginVersion && pluginIsRegistered({ home: homedir(), settings: readSettings() });
+    if (viaPlugin && bare.length > 0) {
+      dwarn(
+        `MCP registration: the plugin manifest provides the server AND a bare "${bare.join('", "')}" registration exists — the server is registered twice`,
+      );
+      // No `-s` flag, deliberately: `nonPluginMemRegistrations`'s own docblock says `mcp list`
+      // does not label scope, and this repo's tracked `.mcp.json` registers a bare `mem-lite`
+      // at PROJECT scope, which `-s user` cannot remove. `claude mcp remove` without the flag
+      // removes from whichever scope the entry is in. Every name, not just the first.
+      for (const name of bare) log(`    Fix: claude mcp remove ${name}`);
+    } else if (viaPlugin) {
+      ok('MCP registration: provided by the plugin manifest only (no duplicate)');
+    } else if (bare.length > 0) {
+      ok(`MCP registration: "${bare.join('", "')}" registered`);
+    } else {
+      dwarn('MCP registration: no claude-mem-lite MCP server is registered and no plugin provides one');
+    }
+  } catch (e) {
+    // Third outcome, kept apart from "none found" on purpose: the `claude` CLI may not be on
+    // PATH at all, and a green "no duplicate" would end the reader's search on a check that
+    // never ran.
+    dwarn(`MCP registration: could not run \`claude mcp list\` (${e.code || e.message}) — not checked`);
+  }
+
+  // Marketplace clone updatability — see marketplaceCloneHealth for why this is the
+  // precondition behind the schema-skew lock-in v6.3.0 shipped a detector for.
+  const marketplaceClone = join(homedir(), '.claude', 'plugins', 'marketplaces', MARKETPLACE_KEY);
+  const clone = marketplaceCloneHealth(marketplaceClone);
+  if (clone.kind === 'dirty') {
+    dwarn(`Marketplace clone: ${clone.count} uncommitted change(s) in ${marketplaceClone}`);
+    log(
+      '    Claude Code updates a git-source marketplace by pulling this clone, and a dirty tree blocks the pull —',
+    );
+    log(
+      '    the plugin then stops updating silently, which is how a machine ends up running code older than its DB.',
+    );
+    log(`    Inspect: git -C ${marketplaceClone} status`);
+  } else if (clone.kind === 'unknown') {
+    dwarn(`Marketplace clone: could not check ${marketplaceClone} (${clone.reason}) — not checked`);
+  } else if (clone.kind === 'clean') {
+    ok('Marketplace clone: clean (the marketplace updater can fast-forward it)');
+  }
+  // 'absent' / 'not-git' are silent: an npm-channel or npx user has no marketplace clone,
+  // and a check that reports on a thing you do not have is noise.
+
   // Database
   if (existsSync(DB_PATH)) {
     try {
@@ -1750,6 +2103,11 @@ async function doctor() {
       }
     } catch (e) {
       fail('Database: ' + e.message);
+      // Every other ✗ on this screen carries a remedy; this one used to be the exception,
+      // and a corrupt store is the failure a user is least able to diagnose unaided.
+      // dbCheckRemedy returns null rather than invent one for an error it cannot classify.
+      const remedy = dbCheckRemedy(DB_PATH, e);
+      if (remedy) log(`    ${remedy}`);
       issues++;
     }
   } else {
@@ -2356,6 +2714,41 @@ export function hasOtherMarketplacePlugins(
   return Object.keys(plugins).some((key) => key !== pluginKey && key.endsWith(`@${marketplaceKey}`));
 }
 
+/**
+ * Whether Claude Code actually has this plugin INSTALLED — as opposed to a leftover version
+ * directory sitting in its cache.
+ *
+ * `detectInstallShape`'s `activePluginVersion` is not that question. Its own comment calls its
+ * third tier — the newest cache directory — "a guess, and after a rollback the wrong one", and
+ * a terminal has neither of the first two tiers (`CLAUDE_PLUGIN_ROOT`, `installed_plugins.json`)
+ * after `/plugin uninstall`. `/plugin uninstall` leaves the version dirs behind, which this
+ * project's own README now documents — so "a cache directory exists" is true on machines that
+ * have no plugin at all.
+ *
+ * Using it as "the plugin provides the MCP server" was measured to tell a working npm-channel
+ * install that its server was registered twice, with a remedy that removes its ONLY
+ * registration. Read from the two places that RECORD an installation instead.
+ *
+ * Deliberately NOT `!shape.managed`: a mixed install has both, and that is precisely the state
+ * the duplicate check exists for. Over-narrowing here is safe by construction — the caller
+ * falls back to asking `claude mcp list`, which is the pre-fix behaviour and correct.
+ *
+ * Exported for tests/mcp-registration-parse.test.mjs.
+ */
+export function pluginIsRegistered({ home = homedir(), settings = {} } = {}) {
+  if (isPluginExplicitlyDisabled(settings)) return false;
+  if (settings?.enabledPlugins?.[PLUGIN_KEY] === true) return true;
+  try {
+    const installed = JSON.parse(
+      readFileSync(join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8'),
+    );
+    return PLUGIN_KEY in getInstalledPluginEntries(installed);
+  } catch {
+    // Missing or unparseable registry: not evidence of an installation.
+    return false;
+  }
+}
+
 /** Thrown when settings.json exists but is not parseable. Never a reason to write. */
 class SettingsUnparseableError extends Error {}
 
@@ -2624,9 +3017,7 @@ async function repair() {
     console.log('  Automatic repair fails closed rather than run unverified code.');
     console.log('  Manual fallback — run this in any shell (you are choosing to trust it):');
     console.log('');
-    console.log(
-      '  T=$(mktemp -d) && curl -sL https://api.github.com/repos/sdsrss/claude-mem-lite/tarball | tar xz -C "$T" --strip-components=1 && node "$T/install.mjs" install',
-    );
+    console.log(`  ${MANUAL_TARBALL_FALLBACK}`);
     console.log('');
     process.exit(1);
   } finally {

package/lib/data-paths.mjs

@@ -0,0 +1,33 @@
+/**
+ * The three location constants, in a leaf module.
+ *
+ * They lived in `schema.mjs`, which statically imports `better-sqlite3`. That made the
+ * native driver a LOAD-TIME dependency of anything that wanted a path — including
+ * `hook-update.mjs`, which `install.mjs::repair()` imports to reach the Ed25519-verified
+ * release path. Measured 2026-09-08: on a tree with no `node_modules`, that import threw
+ * `ERR_MODULE_NOT_FOUND` from `schema.mjs`, repair() caught it, refused to auto-install
+ * unverified code, and printed the unverified default-branch tarball instead. So the
+ * signature check was unreachable on the one install state the self-heal exists to fix.
+ *
+ * Keep this module free of package imports — `node:` builtins and `lib/resolve-data-dir.mjs`
+ * only. `tests/repair-path-no-native-dep.test.mjs` walks the static import graph from
+ * `hook-update.mjs` and fails on ANY package edge, so a future import here has to argue
+ * with a test rather than silently disarm the repair path.
+ *
+ * `schema.mjs` re-exports all three names, so every existing importer keeps working and
+ * this is not a contract change.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveDataDir } from './resolve-data-dir.mjs';
+
+// DATA location — DB, managed resources, registry DB, runtime/. Honors
+// CLAUDE_MEM_DIR so users can relocate state to a larger/faster volume.
+export const DB_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
+export const DB_PATH = join(DB_DIR, 'claude-mem-lite.db');
+// CODE / install location — server.mjs, hook.mjs, cli.mjs, package.json live
+// here. ALWAYS homedir-rooted: Claude Code's settings.json + MCP registration
+// bake ABSOLUTE paths to server.mjs/hooks, so the code must NOT follow the
+// CLAUDE_MEM_DIR relocation env var (mirrors install.mjs INSTALL_DIR). Equals
+// DB_DIR when CLAUDE_MEM_DIR is unset — the common, non-relocated case.
+export const CODE_DIR = join(homedir(), '.claude-mem-lite');