superlocalmemory 4.0.2 → 4.0.4

package/src/superlocalmemory/cli/host_upgrades.py

@@ -0,0 +1,175 @@
+"""Consented, non-destructive upgrades for existing host integrations.
+
+Package installation owns the SLM executable.  This module owns the separate
+operator-approved step that refreshes SLM-owned integration assets.  It never
+discovers a host and edits it implicitly: preview is the default and apply
+requires either explicit hosts or an explicit all-detected acknowledgement.
+"""
+
+from __future__ import annotations
+
+from argparse import Namespace
+from pathlib import Path
+from typing import Any
+
+
+def validate_upgrade_request(*, apply: bool, hosts: list[str], all_detected: bool) -> None:
+    """Reject unbounded mutations before any host filesystem access."""
+    if apply and not hosts and not all_detected:
+        raise ValueError("--apply requires at least one --host or --all-detected")
+    if hosts and all_detected:
+        raise ValueError("choose explicit --host values or --all-detected, not both")
+
+
+def cmd_upgrade_hosts(args: Namespace) -> None:
+    """Preview or explicitly apply host integration refreshes."""
+    hosts = list(getattr(args, "hosts", []) or [])
+    apply = bool(getattr(args, "apply", False))
+    all_detected = bool(getattr(args, "all_detected", False))
+    try:
+        validate_upgrade_request(apply=apply, hosts=hosts, all_detected=all_detected)
+    except ValueError as exc:
+        print(f"Error: {exc}")
+        return
+
+    from superlocalmemory.hooks.portable_kit import supported_ides
+
+    detected = set(_detected_hosts())
+    targets = sorted(detected) if all_detected else (hosts or sorted(detected))
+    managed_hosts = set(supported_ides()) | {"claude-code", "hermes"}
+    unknown = sorted(set(targets) - managed_hosts)
+    if unknown:
+        print(f"Error: unsupported host(s): {', '.join(unknown)}")
+        return
+    if not targets:
+        print("No existing SLM host integrations were detected.")
+        print("Run `slm setup` for first-time setup, or use `--host <name>` to target one host.")
+        return
+
+    operation = "Applying" if apply else "Previewing"
+    print(f"{operation} SLM host upgrades: {', '.join(targets)}")
+    if not apply:
+        print("No host files will be changed. Re-run with --apply and explicit targets to proceed.")
+
+    for host in targets:
+        result = _upgrade_host(host, apply=apply, already_integrated=host in detected)
+        status = result.get("status", "error")
+        detail = result.get("detail", "")
+        print(f"  [{status}] {host}: {detail}")
+
+    if apply:
+        print("Restart affected host applications, then run `slm doctor` to verify SLM itself.")
+
+
+def _detected_hosts(home: Path | None = None) -> list[str]:
+    """Return only hosts already containing an SLM-owned integration block."""
+    from superlocalmemory.hooks.portable_kit import (
+        IDE_MATRIX,
+        _load_config,
+        _ParseError,
+    )
+
+    effective_home = home or Path.home()
+    detected: list[str] = []
+    for host, desc in IDE_MATRIX.items():
+        if not desc.fmt:
+            continue
+        path = effective_home / desc.mcp_path_global
+        try:
+            data = _load_config(path, desc.fmt)
+        except _ParseError:
+            continue
+        if _contains_slm_block(data, desc):
+            detected.append(host)
+
+    # Claude Code's plugin is host-managed. A local SLM hook installation is
+    # the durable evidence that its SLM integration exists; upgrading the
+    # plugin remains an explicit Claude Code marketplace action.
+    try:
+        from superlocalmemory.hooks.claude_code_hooks import check_status
+
+        if check_status().get("installed"):
+            detected.append("claude-code")
+    except Exception:
+        pass
+
+    # Hermes has a native YAML mapping rather than the portable-kit schema.
+    # Detect it for reporting, but never overwrite it with an invented format.
+    hermes_path = effective_home / ".hermes" / "config.yaml"
+    try:
+        hermes = _load_config(hermes_path, "yaml")
+        servers = hermes.get("mcp_servers", {})
+        if isinstance(servers, dict) and "superlocalmemory" in servers:
+            detected.append("hermes")
+    except _ParseError:
+        pass
+    return sorted(set(detected))
+
+
+def _contains_slm_block(data: dict[str, Any], desc: Any) -> bool:
+    if desc.fmt == "yaml":
+        providers = data.get(desc.server_key, [])
+        return isinstance(providers, list) and any(
+            isinstance(item, dict)
+            and item.get("params", {}).get("serverName") == "superlocalmemory"
+            for item in providers
+        )
+    servers = data.get(desc.server_key, {})
+    return isinstance(servers, dict) and "superlocalmemory" in servers
+
+
+def _upgrade_host(host: str, *, apply: bool, already_integrated: bool) -> dict[str, str]:
+    """Refresh assets without degrading a working, host-specific MCP block."""
+    if host == "claude-code":
+        return {
+            "status": "plugin-managed",
+            "detail": "run `claude plugin update superlocalmemory@qualixar` in Claude Code",
+        }
+
+    if host == "hermes":
+        if already_integrated:
+            return {
+                "status": "verified",
+                "detail": "existing native Hermes SLM mapping preserved",
+            }
+        return {
+            "status": "blocked",
+            "detail": "Hermes is not connected; follow docs/ide-setup.md before retrying",
+        }
+
+    if host == "codex" and already_integrated:
+        from superlocalmemory.hooks.codex_assets import install_assets
+        from superlocalmemory.hooks.codex_hooks import install_hooks
+
+        assets, hooks = install_assets(dry_run=not apply), install_hooks(dry_run=not apply)
+        if not assets.get("success") or not hooks.get("success"):
+            return {"status": "blocked", "detail": "could not refresh SLM-owned Codex assets"}
+        action = "would refresh" if not apply else "refreshed"
+        return {
+            "status": "updated" if apply else "preview",
+            "detail": (
+                f"{action} SLM-owned Codex skills, agents, and hooks; "
+                "MCP block preserved"
+            ),
+        }
+
+    if already_integrated:
+        return {
+            "status": "verified",
+            "detail": "existing SLM MCP block preserved; no portable host assets require refresh",
+        }
+
+    # An explicitly named, not-yet-connected host is a first-time connection.
+    # This branch is never reached by --all-detected.
+    from superlocalmemory.hooks.portable_kit import connect_ide
+
+    result = connect_ide(host, dry_run=not apply)
+    if result.get("error"):
+        return {"status": "blocked", "detail": str(result["error"])}
+    action = result.get("mcp_config", "unknown")
+    if not apply:
+        return {"status": "preview", "detail": f"would refresh SLM MCP block ({action})"}
+    return {"status": "updated", "detail": f"SLM MCP block {action}"}
+
+
+__all__ = ("cmd_upgrade_hosts", "validate_upgrade_request")

package/src/superlocalmemory/cli/main.py

@@ -69,7 +69,7 @@ documentation:
 
 
 _NO_DAEMON_COMMANDS = {
-    "setup", "mode", "provider", "connect", "migrate", "mcp", "warmup", "hooks", "codex",
+    "setup", "mode", "provider", "connect", "upgrade-hosts", "migrate", "mcp", "warmup", "hooks", "codex",
     "config", "evolve", "db",
     # v3.4.22 escape hatches — never auto-start the daemon on these.
     "disable", "enable", "clear-cache", "reconfigure", "benchmark",
@@ -123,12 +123,17 @@ def main() -> None:
         and sys.argv[1] == "connect"
         and "--dry-run" in sys.argv[2:]
     )
+    _is_host_upgrade_preview = (
+        len(sys.argv) >= 2
+        and sys.argv[1] == "upgrade-hosts"
+        and "--apply" not in sys.argv[2:]
+    )
 
     # WP-07: lazy first-run init — runs after hook/mcp fast-paths so stdout
     # is never polluted on those paths (CRIT-3, MCP JSON-RPC purity).
     # Guarded: any failure must not crash the CLI (AC4).
     _is_mcp_cmd = len(sys.argv) >= 2 and sys.argv[1] == "mcp"
-    if not _is_mcp_cmd and not _is_metadata_cmd and not _is_connect_dry_run:
+    if not _is_mcp_cmd and not _is_metadata_cmd and not _is_connect_dry_run and not _is_host_upgrade_preview:
         try:
             from superlocalmemory.cli._lazy_init import _ensure_initialized
             _ensure_initialized()
@@ -148,7 +153,7 @@ def main() -> None:
 
     # One-time post-upgrade banner — silent for fresh installs and
     # same-version runs. Guarded against I/O errors internally.
-    if not _is_mcp_stdio and not _is_metadata_cmd and not _is_connect_dry_run:
+    if not _is_mcp_stdio and not _is_metadata_cmd and not _is_connect_dry_run and not _is_host_upgrade_preview:
         from superlocalmemory.cli.version_banner import check_and_emit_upgrade_banner
         if check_and_emit_upgrade_banner(_ver):
             # First post-upgrade invocation: apply the data-dir migration if
@@ -285,6 +290,23 @@ def main() -> None:
         ),
     )
 
+    upgrade_p = sub.add_parser(
+        "upgrade-hosts",
+        help="Preview or explicitly refresh installed SLM host integrations",
+    )
+    upgrade_p.add_argument(
+        "--host", action="append", dest="hosts", default=[],
+        help="Explicit host to refresh (repeatable; for example: codex, cursor)",
+    )
+    upgrade_p.add_argument(
+        "--all-detected", action="store_true", default=False,
+        help="Target only hosts that already contain an SLM integration",
+    )
+    upgrade_p.add_argument(
+        "--apply", action="store_true", default=False,
+        help="Apply the previewed changes; default is read-only preview",
+    )
+
     migrate_p = sub.add_parser("migrate", help="Migrate data from V2 to V3 schema")
     migrate_p.add_argument(
         "--rollback", action="store_true", help="Rollback migration",
@@ -966,7 +988,10 @@ def main() -> None:
         sys.exit(0)
 
     # V3.3.19: Auto-trigger setup wizard on first use
-    if not (args.command == "connect" and getattr(args, "dry_run", False)):
+    if not (
+        (args.command == "connect" and getattr(args, "dry_run", False))
+        or (args.command == "upgrade-hosts" and not getattr(args, "apply", False))
+    ):
         from superlocalmemory.cli.setup_wizard import check_first_use
         check_first_use(args.command)
 

package/src/superlocalmemory/integrations/bounded_loops_mcp.py

@@ -0,0 +1,184 @@
+"""Versioned, read-only contract boundary for Bounded Loops MCP evidence."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import stat
+from collections.abc import Awaitable, Callable
+from copy import deepcopy
+from datetime import timedelta
+from pathlib import Path
+from typing import Any
+
+CONTRACT_ID = "bounded-loops.dev/slm-bridge/v1"
+_OBSERVATION_TIMEOUT_SECONDS = 5.0
+_MAX_MCP_TEXT_BYTES = 2 * 1024 * 1024
+_ADVERTISEMENT = {
+    "id": CONTRACT_ID,
+    "tool": "bl_graph_evidence",
+    "operation": "observe_terminal_run",
+}
+
+
+class BridgeUnavailable(ValueError):
+    """The installed producer does not advertise a compatible bridge contract."""
+
+
+def supports_bridge(capabilities: dict[str, Any]) -> bool:
+    """Negotiate on the declared public contract, never producer semver."""
+    advertised = capabilities.get("evidence_contracts")
+    return isinstance(advertised, list) and any(
+        isinstance(item, dict)
+        and all(item.get(key) == value for key, value in _ADVERTISEMENT.items())
+        for item in advertised
+    )
+
+
+def bridge_payload(evidence: dict[str, Any], *, profile_id: str) -> dict[str, Any]:
+    """Attach active-profile identity after refusing incompatible evidence."""
+    if evidence.get("contract") != CONTRACT_ID:
+        raise BridgeUnavailable("unsupported bounded-loops evidence contract")
+    if evidence.get("eligible_for_learning") is not False:
+        raise BridgeUnavailable("bounded-loops evidence is not observation-only")
+    # The producer has organisation/project metadata for its own control plane.
+    # SLM stores only the v1 observation receipt needed by its profile-scoped
+    # learning database; retaining arbitrary producer extensions would turn a
+    # versioned contract into an unbounded schema sink.
+    fields = (
+        "contract",
+        "workspace_id",
+        "run_ref",
+        "run_id",
+        "outcome",
+        "run_state",
+        "demonstration",
+        "eligible_for_learning",
+        "terminal_at",
+        "graph_digest",
+        "plan_digest",
+        "policy_digest",
+        "receipt",
+        "nodes",
+    )
+    if any(field not in evidence for field in fields):
+        raise BridgeUnavailable("bounded-loops evidence is missing required v1 fields")
+    return {field: deepcopy(evidence[field]) for field in fields} | {"profile_id": profile_id}
+
+
+async def observe_terminal_runs(
+    call_tool: Callable[[str, dict[str, Any]], Awaitable[dict[str, Any]]], *, profile_id: str
+) -> list[dict[str, Any]]:
+    """Collect only producer-advertised terminal evidence over an injected MCP transport."""
+    discovery = await call_tool("bl_capabilities", {})
+    if discovery.get("status") != "ok" or not supports_bridge(discovery.get("capabilities", {})):
+        raise BridgeUnavailable("bounded-loops does not advertise slm-bridge/v1")
+    listing = await call_tool("bl_graph_terminal_runs", {"limit": 100})
+    if listing.get("status") != "ok" or listing.get("contract") != CONTRACT_ID:
+        raise BridgeUnavailable("bounded-loops terminal listing is unavailable")
+    runs = listing.get("runs")
+    if not isinstance(runs, list):
+        raise BridgeUnavailable("bounded-loops terminal listing is malformed")
+    # The producer's limit is advisory.  Keep this explicit operation bounded
+    # even against a compatible but faulty/malicious producer.
+    runs = runs[:100]
+    observed: list[dict[str, Any]] = []
+    for run in runs:
+        if not isinstance(run, dict) or not isinstance(run.get("run_ref"), str):
+            raise BridgeUnavailable("bounded-loops terminal listing is malformed")
+        response = await call_tool("bl_graph_evidence", {"run_ref": run["run_ref"]})
+        if response.get("status") == "unavailable":
+            continue
+        if response.get("status") != "ok" or not isinstance(response.get("evidence"), dict):
+            raise BridgeUnavailable("bounded-loops evidence response is malformed")
+        observed.append(bridge_payload(response["evidence"], profile_id=profile_id))
+    return observed
+
+
+async def observe_from_stdio(*, command: str, cwd: str, profile_id: str) -> list[dict[str, Any]]:
+    """Run one bounded, explicit MCP 2 observation; never call from recall or remember."""
+    executable, workspace = Path(command), Path(cwd)
+    if (
+        not executable.is_absolute()
+        or not executable.is_file()
+        or not workspace.is_absolute()
+        or not workspace.is_dir()
+        or workspace.is_symlink()
+    ):
+        raise BridgeUnavailable(
+            "bounded-loops bridge requires an approved executable and workspace"
+        )
+    try:
+        executable = executable.resolve(strict=True)
+        workspace = workspace.resolve(strict=True)
+        mode = executable.stat().st_mode
+    except OSError as exc:
+        raise BridgeUnavailable("bounded-loops bridge path is unavailable") from exc
+    if not stat.S_ISREG(mode) or (
+        os.name != "nt" and mode & (stat.S_IWGRP | stat.S_IWOTH)
+    ):
+        raise BridgeUnavailable("bounded-loops executable is not a trusted regular file")
+    if executable.stat().st_uid not in {0, os.geteuid()}:
+        raise BridgeUnavailable("bounded-loops executable owner is not trusted")
+
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+
+    try:
+        parameters = StdioServerParameters(
+            command=str(executable), args=[], cwd=str(workspace)
+        )
+        async with stdio_client(parameters) as (read, write):
+            async with ClientSession(
+                read,
+                write,
+                read_timeout_seconds=timedelta(seconds=_OBSERVATION_TIMEOUT_SECONDS),
+            ) as session:
+                async def observe() -> list[dict[str, Any]]:
+                    await session.initialize()
+
+                    async def call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+                        result = await session.call_tool(name, arguments)
+                        if result.isError:
+                            raise BridgeUnavailable(
+                                "bounded-loops rejected the observation request"
+                            )
+                        texts = [item.text for item in result.content if hasattr(item, "text")]
+                        if len(texts) != 1 or len(texts[0].encode("utf-8")) > _MAX_MCP_TEXT_BYTES:
+                            raise BridgeUnavailable("bounded-loops returned an invalid MCP payload")
+                        try:
+                            payload = json.loads(texts[0])
+                        except json.JSONDecodeError as exc:
+                            raise BridgeUnavailable("bounded-loops returned invalid JSON") from exc
+                        if not isinstance(payload, dict):
+                            raise BridgeUnavailable("bounded-loops returned an invalid MCP payload")
+                        return payload
+
+                    return await observe_terminal_runs(call, profile_id=profile_id)
+                return await asyncio.wait_for(observe(), timeout=_OBSERVATION_TIMEOUT_SECONDS)
+    except BridgeUnavailable:
+        raise
+    except Exception as exc:
+        raise BridgeUnavailable("bounded-loops observation timed out or could not start") from exc
+
+
+async def observe_installed(*, workspace: str, profile_id: str) -> list[dict[str, Any]]:
+    """Observe a user-installed producer without accepting an agent command.
+
+    Discovery deliberately resolves exactly the public ``bounded-loops-mcp``
+    executable.  It does not accept a command, shell fragment, or arguments
+    from an MCP caller; the only caller-supplied value is the existing project
+    workspace whose Bounded Loops state is to be read.
+    """
+    command = shutil.which("bounded-loops-mcp")
+    if command is None:
+        raise BridgeUnavailable("bounded-loops-mcp is not installed")
+    if not Path(command).is_absolute():
+        raise BridgeUnavailable("bounded-loops-mcp discovery returned an unsafe path")
+    if Path(command).resolve().name not in {"bounded-loops-mcp", "bounded-loops-mcp.exe"}:
+        raise BridgeUnavailable("bounded-loops-mcp discovery returned an unsafe executable")
+    return await observe_from_stdio(
+        command=str(Path(command).resolve()), cwd=workspace, profile_id=profile_id
+    )

package/src/superlocalmemory/learning/database.py

@@ -613,7 +613,8 @@ class LearningDatabase:
                     row[0]
                     for row in conn.execute(
                         "SELECT name FROM sqlite_master WHERE type='table' "
-                        "AND name IN ('agent_experiences', 'cognitive_turn_receipts')"
+                        "AND name IN ('agent_experiences', 'cognitive_turn_receipts', "
+                        "'external_evidence_receipts')"
                     )
                 }
                 if profile_id is None:

package/src/superlocalmemory/mcp/profiles.py

@@ -23,7 +23,15 @@ _PROFILE_CORE: frozenset[str] = frozenset({  # 14
     "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
 })
 
-_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | frozenset({  # 24
+# Portable Brain evidence must reach the coding-host profile shipped by the
+# Claude/Codex plugins, not only an unrestricted server.
+_PROFILE_BRAIN: frozenset[str] = frozenset({
+    "get_brain_evidence_status", "record_agent_experience",
+    "record_cognitive_turn", "finalize_cognitive_turn",
+    "observe_bounded_loop_evidence",
+})
+
+_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | _PROFILE_BRAIN | frozenset({  # 29
     "build_code_graph", "get_blast_radius", "query_graph",
     "semantic_search_code", "get_review_context", "detect_changes",
     # switch_profile lets a plugin/IDE session change the active workspace over
@@ -40,23 +48,22 @@ _PROFILE_FULL_MESH: frozenset[str] = frozenset({  # 8
     "mesh_state", "mesh_lock", "mesh_events", "mesh_status",
 })
 
-_PROFILE_FULL: frozenset[str] = frozenset({  # 34 base — EXPLICIT literal, NOT runtime _ESSENTIAL_TOOLS (OQ-2)
+_PROFILE_FULL: frozenset[str] = frozenset({  # 39 base — EXPLICIT literal, NOT runtime _ESSENTIAL_TOOLS (OQ-2)
     "remember", "recall", "search", "fetch", "list_recent", "delete_memory", "update_memory",
     "get_status", "session_init", "observe", "close_session", "report_feedback", "forget",
     "run_maintenance", "consolidate_cognitive", "get_soft_prompts", "set_mode", "report_outcome",
     "log_tool_event", "get_assertions", "reinforce_assertion", "contradict_assertion",
+    "get_brain_evidence_status", "record_agent_experience",
+    "record_cognitive_turn", "finalize_cognitive_turn",
+    "observe_bounded_loop_evidence",
     "evolve_skill", "skill_health", "skill_lineage", "switch_profile",
     "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
     # v3.8.0: bounded-loop tools (CLI + /slm-loop command + MCP).
     "slm_loop_run", "slm_loop_history", "slm_loop_show",
-    # v4: prestage_context IS registered (see mcp/server.py) but is deliberately
-    # NOT in full/power. The profile names are a user-facing config contract
-    # (SLM_MCP_PROFILE=full42) and the published tool-count table depends on
-    # them; adding a tool here would make "full42" serve 43 tools. New tools
-    # reach users through the `whole` profile until a profile rename is shipped.
-}) | _PROFILE_FULL_MESH  # 42
+    # prestage_context remains registered but deliberately raw-server-only.
+}) | _PROFILE_FULL_MESH  # 47
 
-_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 54
+_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 59
     "get_version", "get_mode", "health", "consistency_check", "recall_trace",
     "get_lifecycle_status", "set_retention_policy", "compact_memories",
     "get_behavioral_patterns", "audit_trail", "quantize", "get_retention_stats",
@@ -79,21 +86,29 @@ _PROFILE_DEFINITIONS: dict[str, frozenset[str]] = {
 # at server startup.  Any other value is a configuration error (fail closed).
 _PROFILE_ALIASES: dict[str, str] = {
     "core14": "core",
-    # 3.8.0: switch_profile (+1) then bounded-loop tools (+3) grew code/full/
+    # 3.8.0 and later additions grew code/full/power; every historical count
     # power. Every historical count-suffixed name is kept so a v3.6/3.7/early-
     # 3.8 config still resolves (back-compat); new 3.8.0 counts added alongside.
     "code20": "code",
     "code21": "code",
     "code24": "code",
+    "code28": "code",
+    "code29": "code",
     "full38": "full",
     "full39": "full",
     "full42": "full",
+    "full46": "full",
+    "full47": "full",
     "power50": "power",
     "power51": "power",
     "power54": "power",
+    "power58": "power",
+    "power59": "power",
     "mesh8": "mesh",
     "whole81": "whole",
     "whole84": "whole",
+    "whole91": "whole",
+    "whole92": "whole",
 }
 
 # Plain-English descriptions for UI display.
@@ -101,8 +116,8 @@ _PROFILE_ALIASES: dict[str, str] = {
 # one sentence, user-facing language only.
 PROFILE_DESCRIPTIONS: dict[str, str] = {
     "core": "Essential memory: store, recall, search, sessions",
-    "code": "Core + code-graph tools + profile switching (default for IDE coding agents)",
-    "full": "All everyday memory, optimization, and mesh tools",
-    "power": "Everything in full plus advanced governance/behavioral tools",
+    "code": "Core + code graph, portable Brain evidence, and profile switching (default for IDE coding agents)",
+    "full": "All everyday memory, portable Brain evidence, optimization, and mesh tools",
+    "power": "Everything in full plus advanced governance and behavioral tools",
     "mesh": "Cross-device mesh coordination only",
 }

package/src/superlocalmemory/mcp/server.py

@@ -77,13 +77,13 @@ def reset_engine():
 
 # Register tools and resources -------------------------------------------------
 #
-# Essential-only default: 34 base tools + 8 mesh tools = 42 registered
+# Essential-only default: 39 base tools + 8 mesh tools = 47 registered.
 # when mesh is enabled. Set ``SLM_MCP_ALL_TOOLS=1`` to expose the full
 # toolset. Rationale: IDEs cap at 50-100 tools total (Cursor,
 # Antigravity, Windsurf) and a maximal SLM registration crowds out
 # other MCP servers the user may have installed.
 # Admin/diagnostics tools remain available via CLI (`slm <command>`).
-# Set SLM_MCP_ALL_TOOLS=1 to enable all 87 tools (power users).
+# Set SLM_MCP_ALL_TOOLS=1 to enable all 92 tools (power users).
 
 import os as _os_reg
 
@@ -100,13 +100,14 @@ _ESSENTIAL_TOOLS: set[str] = {
     # v4.0.2 portable Brain evidence: profile-scoped receipt reads/writes.
     "get_brain_evidence_status", "record_agent_experience",
     "record_cognitive_turn", "finalize_cognitive_turn",
+    # v4.0.4: explicit, optional observation from the separately installed
+    # Bounded Loops MCP producer. It never participates in recall/ranking.
+    "observe_bounded_loop_evidence",
     # Memory management (2)
     "forget", "run_maintenance",
     # NOTE: prestage_context IS registered (see register_prestage_tool below)
-    # but is deliberately absent from the default surface. _ESSENTIAL_TOOLS must
-    # stay at 42 to match the full42 profile: the profile names are a
-    # user-facing config contract and the published tool-count table depends on
-    # them. New tools reach users via the `whole` profile until a rename ships.
+    # but is deliberately absent from the default surface. Brain evidence is
+    # intentionally present: it is the portable contract for installed agents.
     # Infinite memory + learning (4)
     "consolidate_cognitive", "get_soft_prompts",
     "set_mode", "report_outcome",