diff --git a/pyproject.toml b/pyproject.toml
index 2e7d5929d..2a970b898 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -76,7 +76,10 @@ all = [
   "hermes-agent[modal]",
   "hermes-agent[daytona]",
   "hermes-agent[messaging]",
-  "hermes-agent[matrix]",
+  # matrix excluded: python-olm (required by matrix-nio[e2e]) is upstream-broken
+  # on modern macOS (archived libolm, C++ errors with Clang 21+). Including it
+  # here causes the entire [all] install to fail, dropping all other extras.
+  # Users who need Matrix can install manually: pip install 'hermes-agent[matrix]'
   "hermes-agent[cron]",
   "hermes-agent[cli]",
   "hermes-agent[dev]",
diff --git a/tests/test_project_metadata.py b/tests/test_project_metadata.py
index 1a377f5f5..476834099 100644
--- a/tests/test_project_metadata.py
+++ b/tests/test_project_metadata.py
@@ -11,8 +11,12 @@ def _load_optional_dependencies():
     return project["optional-dependencies"]
 
 
-def test_all_extra_includes_matrix_dependency():
+def test_matrix_extra_exists_but_excluded_from_all():
+    """matrix-nio[e2e] depends on python-olm which is upstream-broken on modern
+    macOS (archived libolm, C++ errors with Clang 21+).  The [matrix] extra is
+    kept for opt-in install but deliberately excluded from [all] so one broken
+    upstream dep doesn't nuke every other extra during ``hermes update``."""
     optional_dependencies = _load_optional_dependencies()
 
     assert "matrix" in optional_dependencies
-    assert "hermes-agent[matrix]" in optional_dependencies["all"]
+    assert "hermes-agent[matrix]" not in optional_dependencies["all"]