superlocalmemory 4.1.13 → 4.1.14

package/.claude-plugin/marketplace.json

@@ -21,7 +21,7 @@
       "license": "AGPL-3.0-or-later",
       "name": "superlocalmemory",
       "source": "./plugin",
-      "version": "4.1.13"
+      "version": "4.1.14"
     },
     {
       "author": {
@@ -39,7 +39,7 @@
       "license": "AGPL-3.0-or-later",
       "name": "superlocalmemory-codex",
       "source": "./codex-plugin",
-      "version": "4.1.13"
+      "version": "4.1.14"
     }
   ]
 }

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to SuperLocalMemory will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.14] — Profile-correctness and reliability release
+
+### Added
+
+- **Per-request profile routing.** `remember`/`recall` (engine, daemon, MCP)
+  accept an optional `profile_id` that routes one request to that profile
+  without moving the machine-wide active pointer — two clients on one data
+  root can no longer silently redirect each other. Unknown profiles get
+  `404 unknown_profile`, never implicit creation; the adjacency cache is a
+  profile-keyed LRU. Every response echoes the profile that served it,
+  including degraded and empty paths.
+- **Thinking-model extraction.** Ollama reasoning models (qwen3 family) that
+  answer inside `message.thinking` no longer silently degrade Mode B to
+  Mode A: the trace is parsed for the answer array (schema-fit selection),
+  extraction requests content-only answers with a one-shot downgrade on
+  servers that reject the flag, and empty responses warn instead of
+  vanishing.
+- **Ingestion lease self-healing.** Expired enrichment leases are reaped
+  unconditionally at daemon boot and at the top of every materializer pass
+  — recovery no longer waits on embedder warmth. Kill-simulation tests
+  prove the wedged pipeline unblocks itself.
+- **Migration self-heal.** Every migration ships `repair()` or a written
+  `REPAIR_NOT_APPLICABLE` justification (enforced by a coverage guard);
+  justified drift skips instead of failing while blocking modules still
+  refuse to serve; destructive repairs carry crash-resume round-trip proof.
+  `slm db migrate` runs the same path the daemon uses at startup.
+- **npm single source of truth.** The npm tarball no longer bundles Python
+  sources; the package-owned venv installs the pinned
+  `superlocalmemory==X` wheel (`SLM_LOCAL_WHEEL` override for air-gapped
+  installs). `slm doctor` names the resolved package directory per install
+  and warns when the npm wrapper and its venv wheel disagree.
+
+### Fixed
+
+- Port-conflict startup now probes the configured port and fails fast and
+  loud on an answering foreign occupant (including a stale-pid diagnosis);
+  the probed port travels into the spawned daemon, and restart reuses the
+  owned port.
+- MCP `unknown_profile` answers surface end-to-end instead of collapsing
+  into `DAEMON_UNAVAILABLE`, with no hopeless retries.
+- RABAC `READ` is enforced on routed recalls, permission-before-existence,
+  closing the profile-existence oracle.
+- Daemon identity checks reject stale descriptors on PID reuse; status
+  never reports success without identity agreement.
+- vec0 operator guidance: row deletes by `rowid` are supported, bare
+  full-table `DELETE` is a sqlite-vec limitation (not corruption); the
+  error reference documents the supported clearing paths.
+
 ## [4.1.13] — Hermes public-install compatibility repair
 
 ### Fixed

package/README.md

@@ -5,7 +5,7 @@
   </picture>
 </p>
 
-<h1 align="center">SuperLocalMemory V4.1.13</h1>
+<h1 align="center">SuperLocalMemory V4.1.14</h1>
 
 <h2 align="center">Rent the LLM. Own the memory.</h2>
 
@@ -27,12 +27,12 @@ guarantee here is stated as a falsifiable invariant, tested under an adversarial
 negative control, and shipped with the harness that regenerates the evidence:
 <code>python benchmark/run_all.py --trials 200 --output-dir results/</code>. What each experiment
 does <em>not</em> exercise is stated too.</p>
-<p align="center"><code>v4.1.13</code> — one control plane: <strong>SLM-Mesh</strong> peer coordination · multi-scope memory (personal / shared / global) · profiles · Cache · Compress · 7-layer retrieval · code graph · Entity Explorer · skill evolution · Modes A/B/C · GDPR retention &amp; audit chain · bounded loops — across CLI, MCP, dashboard, the <strong>Claude plugin</strong>, the <strong>Codex add-on</strong>, and documented IDE integrations.<br/>
+<p align="center"><code>v4.1.14</code> — one control plane: <strong>SLM-Mesh</strong> peer coordination · multi-scope memory (personal / shared / global) · profiles · Cache · Compress · 7-layer retrieval · code graph · Entity Explorer · skill evolution · Modes A/B/C · GDPR retention &amp; audit chain · bounded loops — across CLI, MCP, dashboard, the <strong>Claude plugin</strong>, the <strong>Codex add-on</strong>, and documented IDE integrations.<br/>
 Proxy: <code>slm wrap claude</code> &nbsp;·&nbsp; MCP: add <code>slm_compress</code> to your config &nbsp;·&nbsp; Skill: zero-config</p>
 <p align="center"><strong>Four public arXiv preprints</strong> · V4: <a href="https://arxiv.org/abs/2608.08253">arXiv:2608.08253</a> · companion archive: <a href="https://zenodo.org/records/21853302">Zenodo 21853302</a> (<a href="https://doi.org/10.5281/zenodo.21853302">DOI 10.5281/zenodo.21853302</a>) · prior preprints: <a href="https://arxiv.org/abs/2603.02240">2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">2604.04514</a>.</p>
 
 <p align="center">
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/v4.1.13-Current_Release-2ea44f?style=for-the-badge&logo=checkmarx&logoColor=white" alt="v4.1.13 — Current Release"/></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/v4.1.14-Current_Release-2ea44f?style=for-the-badge&logo=checkmarx&logoColor=white" alt="v4.1.14 — Current Release"/></a>
   <a href="https://arxiv.org/abs/2608.08253"><img src="https://img.shields.io/badge/arXiv-2608.08253-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="SuperLocalMemory 4.0 paper on arXiv:2608.08253"/></a>
   <a href="https://zenodo.org/records/21853302"><img src="https://img.shields.io/badge/Zenodo-10.5281%2Fzenodo.21853302-1682D4?style=for-the-badge&logo=zenodo&logoColor=white" alt="V4 paper on Zenodo: 10.5281/zenodo.21853302"/></a>
   <a href="https://arxiv.org/abs/2603.14588"><img src="https://img.shields.io/badge/arXiv-2603.14588-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv Paper"/></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "4.1.13",
+  "version": "4.1.14",
   "description": "Local-first agent memory with MCP and an agent-native CLI. Documented clients include Claude Code, Cursor, and Windsurf.",
   "keywords": [
     "ai-memory",
@@ -69,12 +69,6 @@
   ],
   "files": [
     "bin/slm-npm",
-    "src/superlocalmemory/",
-    "!src/**/__pycache__/",
-    "!src/**/*.pyc",
-    "!src/**/*.pyo",
-    "!src/superlocalmemory/graphify-out/",
-    "!src/**/graphify-out/**",
     "ide/completions/",
     "ide/configs/",
     "ide/hooks/",
@@ -100,7 +94,6 @@
     "plugin-src/agents/slm-optimize-advisor.md",
     "plugin-src/rules/AGENTS.md",
     "docs/pi-dev-integration.md",
-    "pyproject.toml",
     "README.md",
     "LICENSE",
     "NOTICE",

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

@@ -15,5 +15,5 @@
   "mcpServers": "./.mcp.json",
   "name": "superlocalmemory",
   "repository": "https://github.com/qualixar/superlocalmemory",
-  "version": "4.1.13"
+  "version": "4.1.14"
 }

package/plugin/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- BEGIN SuperLocalMemory v4.1.13 -->
+<!-- BEGIN SuperLocalMemory v4.1.14 -->
 
 ## SuperLocalMemory (SLM) — Agent Rules
 
@@ -39,6 +39,6 @@ slm-recall · slm-remember · slm-session · slm-status · slm-cache · slm-comp
 ### Subagents
 slm-memory-advisor (memory decisions, session hygiene, scope/profile guidance) · slm-optimize-advisor (context compression + KV cache) · slm-governance-advisor (scope/roles/compliance/GDPR)
 
-<!-- END SuperLocalMemory v4.1.13 -->
+<!-- END SuperLocalMemory v4.1.14 -->
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-governance-advisor.md

@@ -77,4 +77,4 @@ slm-scope · slm-governance · slm-profile · slm-remember · slm-recall
 # What NOT to do
 Never session_init twice; never forget without dry-run preview; never store secrets; never bypass role checks; never claim an erasure succeeded without verifying via recall.
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-loop-runner.md

@@ -68,4 +68,4 @@ assessment. The gate is the authority.
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-memory-advisor.md

@@ -46,4 +46,4 @@ slm-recall · slm-remember · slm-session · slm-scope · slm-profile · slm-gov
 # What NOT to do
 Never session_init twice; never forget dry_run=False without reporting preview; never dump a whole file into remember; never invent a memory; never claim "saved" without success:true / clean CLI exit; never bypass scope or governance restrictions.
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/agents/slm-optimize-advisor.md

@@ -41,4 +41,4 @@ slm-compress · slm-cache · slm-status · slm-profile
 # What NOT to do
 Never compress code-for-edit/JSON-to-parse/<500 chars; never store secrets/ccr_ids; never let optimize failure block/alter the task; never claim a specific savings %; never carry ccr_ids across profile switches.
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/requirements.txt

@@ -1 +1 @@
-superlocalmemory==4.1.13
+superlocalmemory==4.1.14

package/plugin/skills/slm-cache/SKILL.md

@@ -145,4 +145,4 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-compress/SKILL.md

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-governance/SKILL.md

@@ -245,4 +245,4 @@ Before running any destructive operation (`forget`, `compact_memories`):
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-graph/SKILL.md

@@ -312,4 +312,4 @@ profile. See `slm-profile` for the full profile switching workflow.
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-loop/SKILL.md

@@ -96,4 +96,4 @@ paused, name the approval needed; when errored, quote the short detail.
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-mesh/SKILL.md

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-profile/SKILL.md

@@ -146,4 +146,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-recall/SKILL.md

@@ -323,4 +323,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-remember/SKILL.md

@@ -270,4 +270,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-scope/SKILL.md

@@ -173,4 +173,4 @@ to review the impact. See `slm-remember` for the full deletion discipline.
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-session/SKILL.md

@@ -253,4 +253,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin/skills/slm-status/SKILL.md

@@ -163,4 +163,4 @@ multi-profile setup. To switch the active profile, see `slm-profile`.
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin-src/agents/slm-memory-advisor.md

@@ -46,4 +46,4 @@ slm-recall · slm-remember · slm-session · slm-scope · slm-profile · slm-gov
 # What NOT to do
 Never session_init twice; never forget dry_run=False without reporting preview; never dump a whole file into remember; never invent a memory; never claim "saved" without success:true / clean CLI exit; never bypass scope or governance restrictions.
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin-src/agents/slm-optimize-advisor.md

@@ -41,4 +41,4 @@ slm-compress · slm-cache · slm-status · slm-profile
 # What NOT to do
 Never compress code-for-edit/JSON-to-parse/<500 chars; never store secrets/ccr_ids; never let optimize failure block/alter the task; never claim a specific savings %; never carry ccr_ids across profile switches.
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin-src/rules/AGENTS.md

@@ -137,4 +137,4 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 - **slm-optimize-advisor** — context compression and KV cache
 - **slm-governance-advisor** — scope/role compliance, retention policies, GDPR
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-cache/SKILL.md

@@ -145,4 +145,4 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-compress/SKILL.md

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-governance/SKILL.md

@@ -245,4 +245,4 @@ Before running any destructive operation (`forget`, `compact_memories`):
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-graph/SKILL.md

@@ -312,4 +312,4 @@ profile. See `slm-profile` for the full profile switching workflow.
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-loop/SKILL.md

@@ -96,4 +96,4 @@ paused, name the approval needed; when errored, quote the short detail.
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-mesh/SKILL.md

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-profile/SKILL.md

@@ -146,4 +146,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-recall/SKILL.md

@@ -323,4 +323,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-remember/SKILL.md

@@ -270,4 +270,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-scope/SKILL.md

@@ -173,4 +173,4 @@ to review the impact. See `slm-remember` for the full deletion discipline.
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-session/SKILL.md

@@ -253,4 +253,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-status/SKILL.md

@@ -163,4 +163,4 @@ multi-profile setup. To switch the active profile, see `slm-profile`.
 
 ---
 
-SuperLocalMemory v4.1.13 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.14 · Qualixar · AGPL-3.0-or-later

package/scripts/postinstall.js

@@ -83,6 +83,47 @@ function runtimePythonPath(packageRoot, platform = os.platform()) {
     : path.join(packageRoot, '.slm-venv', 'bin', 'python');
 }
 
+/**
+ * Single source of truth for the Python payload (4.1.14 #134, Option A).
+ *
+ * The npm tarball carries NO Python sources. The package-owned venv is
+ * populated from the pinned PyPI wheel `superlocalmemory==<npm version>`,
+ * so there is exactly one copy of the package and patching any other
+ * tree cannot shadow it. `SLM_LOCAL_WHEEL=/path/to/file.whl` overrides
+ * the specifier for air-gapped installs: it must be an existing local
+ * `.whl` file (directories, sdists and URLs are refused) and it still
+ * passes the version identity check below. Note the boundary honestly:
+ * the wheel itself comes from the file, but pip still resolves its
+ * *dependencies* from the index unless PIP_FIND_LINKS/PIP_NO_INDEX say
+ * otherwise — never a source tree, but not fully offline either.
+ */
+function pypiSpecifier(packageRoot) {
+  const rawWheel = String(process.env.SLM_LOCAL_WHEEL || '').trim();
+  if (rawWheel) {
+    // 4.1.14 audit: resolve relative paths against the package root (not
+    // the caller's cwd), require an existing FILE (a directory named
+    // *.whl is refused), and require the .whl suffix (sdists, URLs and
+    // directories cannot pass).
+    const localWheel = path.isAbsolute(rawWheel)
+      ? rawWheel
+      : path.resolve(packageRoot, rawWheel);
+    let isFile = false;
+    try {
+      isFile = fs.statSync(localWheel).isFile();
+    } catch {
+      isFile = false;
+    }
+    if (!localWheel.toLowerCase().endsWith('.whl') || !isFile) {
+      throw new Error(
+        `SLM_LOCAL_WHEEL must be an existing local .whl file, got: ${rawWheel}`,
+      );
+    }
+    return localWheel;
+  }
+  const packageVersion = require(path.join(packageRoot, 'package.json')).version;
+  return `superlocalmemory==${packageVersion}`;
+}
+
 function validateRuntimeLocation(venvRoot) {
   if (!fs.existsSync(venvRoot)) return { ok: true };
   try {
@@ -145,6 +186,17 @@ function main(argv = process.argv.slice(2)) {
 
   console.log(`  Python ${python.version.join('.')} (${[python.command, ...python.prefixArgs].join(' ')})`);
 
+  // Fail fast on a bad package source BEFORE creating any venv, so a
+  // misconfigured SLM_LOCAL_WHEEL never leaves a half-built runtime behind.
+  let packageSource;
+  try {
+    packageSource = pypiSpecifier(packageRoot);
+  } catch (error) {
+    console.error(`SuperLocalMemory: ${error.message}`);
+    console.error('Unset SLM_LOCAL_WHEEL to install from PyPI, or point it at a real wheel file.');
+    return 1;
+  }
+
   const createVenv = spawnSync(
     python.command,
     [...python.prefixArgs, '-m', 'venv', venvRoot],
@@ -169,12 +221,15 @@ function main(argv = process.argv.slice(2)) {
       '--disable-pip-version-check',
       '--no-input',
       '--upgrade',
-      packageRoot,
+      packageSource,
     ],
     { stdio: 'inherit', timeout: INSTALL_TIMEOUT_MS, env: process.env },
   );
   if (installPackage.status !== 0) {
     console.error(`SuperLocalMemory: private-runtime installation failed (${failureDetail(installPackage)}).`);
+    console.error(`Tried Python source: ${packageSource}`);
+    console.error('This install needs network access to PyPI, or set SLM_LOCAL_WHEEL=/path/to/superlocalmemory-<version>-py3-none-any.whl for air-gapped installs, then run:');
+    console.error('  npm rebuild superlocalmemory');
     console.error('Check network access, available disk space, and Python build prerequisites, then run:');
     console.error('  npm rebuild superlocalmemory');
     console.error('No system Python packages or SLM durable data were modified.');
@@ -190,7 +245,16 @@ function main(argv = process.argv.slice(2)) {
     { stdio: 'pipe', timeout: 15000, env: process.env },
   );
   const installedVersion = (verify.stdout || '').toString().trim();
-  if (verify.status !== 0 || installedVersion !== packageVersion) {
+  // 4.1.14 audit: normalize across npm-semver and PEP 440 spellings
+  // ("4.1.14-rc.1" vs "4.1.14rc1") before comparing — a strict strcmp
+  // would fail a good wheel on pre-releases.
+  const normalizeVersion = (value) => String(value || '')
+    .trim().toLowerCase().replace(/^v/, '')
+    .replace(/[-_.]+/g, '');
+  if (
+    verify.status !== 0
+    || normalizeVersion(installedVersion) !== normalizeVersion(packageVersion)
+  ) {
     console.error(
       `SuperLocalMemory: runtime identity check failed (npm=${packageVersion}, python=${installedVersion || 'unavailable'}).`,
     );
@@ -199,6 +263,10 @@ function main(argv = process.argv.slice(2)) {
   }
 
   console.log(`SuperLocalMemory ${packageVersion}: isolated runtime verified.`);
+  console.log(`Single source of truth for this npm installation: the PyPI wheel superlocalmemory==${packageVersion} in .slm-venv;`);
+  console.log('the npm tarball carries no Python sources, so no second copy can shadow it.');
+  console.log('(The Claude Code plugin keeps its own separate pinned runtime for its host;');
+  console.log(' that scope is independent of this npm installation — see plugin/requirements.txt.)');
   console.log('No memory database, IDE hooks, daemon, configuration, or models were changed.');
   console.log('');
   console.log('  Your database will be automatically migrated on first run.');
@@ -228,6 +296,7 @@ module.exports = {
   isSupportedPython,
   main,
   parsePythonVersion,
+  pypiSpecifier,
   pythonCandidates,
   runtimePythonPath,
   validateRuntimeLocation,