livepilot 1.10.8 → 1.12.2

package/mcp_server/server.py

@@ -9,7 +9,7 @@ import subprocess
 from fastmcp import FastMCP, Context  # noqa: F401
 
 from .connection import AbletonConnection
-from .m4l_bridge import SpectralCache, SpectralReceiver, M4LBridge
+from .m4l_bridge import SpectralCache, SpectralReceiver, M4LBridge, MidiToolCache
 
 # Logger must be defined before any function uses it — several module-level
 # helpers below (e.g. _master_has_livepilot_analyzer) call logger.debug on
@@ -144,6 +144,28 @@ async def _warm_analyzer_bridge(
         await asyncio.sleep(0.05)
 
 
+def _bind_session_continuity(ableton: AbletonConnection) -> None:
+    """Hydrate the session-continuity tracker from persistent per-project state.
+
+    Fetches a minimal session fingerprint (tempo, signature, track/scene
+    layout) from the Remote Script, computes a project hash, and asks the
+    tracker to bind the matching ProjectStore + restore any previously-saved
+    creative threads and turn resolutions from disk.
+
+    Never raises: startup must succeed even if Ableton isn't reachable. In
+    that case, the tracker stays in-memory and the first ``record_turn_*`` /
+    ``open_thread`` call will lazy-bind via ``ensure_project_store_bound()``.
+    """
+    try:
+        from .session_continuity.tracker import bind_project_store_from_session
+
+        info = ableton.send_command("get_session_info")
+        if isinstance(info, dict) and not info.get("error"):
+            bind_project_store_from_session(info)
+    except Exception as exc:
+        logger.debug("_bind_session_continuity: lazy-bind (reason: %s)", exc)
+
+
 @asynccontextmanager
 async def lifespan(server):
     """Create and yield the shared AbletonConnection + M4L bridge + registries."""
@@ -152,8 +174,9 @@ async def lifespan(server):
 
     ableton = AbletonConnection()
     spectral = SpectralCache()
-    receiver = SpectralReceiver(spectral)
-    m4l = M4LBridge(spectral, receiver)
+    miditool = MidiToolCache()
+    receiver = SpectralReceiver(spectral, miditool_cache=miditool)
+    m4l = M4LBridge(spectral, receiver, miditool_cache=miditool)
     mcp_dispatch = build_mcp_dispatch_registry()
 
     # Splice gRPC client — graceful degradation if Splice desktop isn't
@@ -203,9 +226,16 @@ async def lifespan(server):
         _check_remote_script_version(ableton)
         if bridge_state["transport"] is not None:
             await _warm_analyzer_bridge(ableton, spectral)
+        # Bind per-project persistent store so creative threads and turn
+        # history survive server restarts. Until v1.10.9 this was plumbed
+        # through the tracker but never called — threads/turns were effectively
+        # in-memory only. If Ableton isn't reachable yet, tools will lazy-bind
+        # on first write via ensure_project_store_bound().
+        _bind_session_continuity(ableton)
         yield {
             "ableton": ableton,
             "spectral": spectral,
+            "miditool": miditool,
             "m4l": m4l,
             "_bridge_state": bridge_state,
             "mcp_dispatch": mcp_dispatch,
@@ -229,6 +259,10 @@ from .tools import clips        # noqa: F401, E402
 from .tools import notes        # noqa: F401, E402
 from .tools import devices      # noqa: F401, E402
 from .tools import scenes       # noqa: F401, E402
+from .tools import scales       # noqa: F401, E402
+from .tools import follow_actions  # noqa: F401, E402
+from .tools import grooves      # noqa: F401, E402
+from .tools import take_lanes   # noqa: F401, E402
 from .tools import mixing       # noqa: F401, E402
 from .tools import browser      # noqa: F401, E402
 from .tools import arrangement  # noqa: F401, E402
@@ -271,6 +305,8 @@ from .device_forge import tools as device_forge_tools          # noqa: F401, E40
 from .sample_engine import tools as sample_engine_tools        # noqa: F401, E402
 from .atlas import tools as atlas_tools                        # noqa: F401, E402
 from .composer import tools as composer_tools                  # noqa: F401, E402
+from .tools import diagnostics   # noqa: F401, E402
+from .tools import miditool       # noqa: F401, E402
 
 # ---------------------------------------------------------------------------
 # Schema coercion patch — accept strings for numeric parameters
@@ -312,28 +348,125 @@ def _coerce_schema_property(prop: dict) -> None:
 
 
 def _get_all_tools():
-    """Get all registered tools, compatible with FastMCP 0.x and 3.x.
-
-    WARNING: Accesses FastMCP private internals (_tool_manager, _local_provider).
-    Pinned to fastmcp>=3.0.0,<3.3.0 in requirements.txt. If upgrading FastMCP,
-    verify these attributes still exist or update this function.
+    """Get all registered tools — defends against FastMCP internal drift.
+
+    FastMCP's public API doesn't expose the registry as of 3.2.x (see
+    docs/FASTMCP_UPSTREAM_FR.md). Until it does, we probe known internal
+    attribute paths. Each probe fires in try/except so a structural
+    rearrangement (e.g. ``_components`` renamed under 3.3+) falls through
+    to the next path rather than exploding.
+
+    WARNING: Accesses FastMCP private internals. Pinned to
+    fastmcp>=3.0.0,<3.3.0 in requirements.txt. The startup self-test
+    (_assert_tool_registry_accessible) will fail loudly if every probe
+    returns empty — better than silently returning [] and disabling
+    schema coercion.
     """
-    # FastMCP 0.x: mcp._tool_manager._tools (dict of name -> Tool)
-    if hasattr(mcp, "_tool_manager"):
-        return list(mcp._tool_manager._tools.values())
-    # FastMCP 3.x: mcp._local_provider._components (dict of key -> Tool)
-    if hasattr(mcp, "_local_provider") and hasattr(mcp._local_provider, "_components"):
-        return list(mcp._local_provider._components.values())
+    probes = [
+        # FastMCP 0.x: mcp._tool_manager._tools (dict of name -> Tool)
+        ("_tool_manager._tools", lambda: list(mcp._tool_manager._tools.values())),
+        # FastMCP 3.0–3.2: mcp._local_provider._components
+        (
+            "_local_provider._components",
+            lambda: list(mcp._local_provider._components.values()),
+        ),
+        # FastMCP 3.3+ speculative: mcp._local_provider._tools (anticipated
+        # rename based on naming conventions in other providers). Kept here
+        # so a future bump surfaces a partial match rather than a full miss.
+        (
+            "_local_provider._tools",
+            lambda: list(mcp._local_provider._tools.values()),
+        ),
+        # Public-API future path (what we're asking for in the upstream FR);
+        # harmless to probe now so that once it ships we can lift the ceiling
+        # without touching this function again.
+        ("list_tools", lambda: list(mcp.list_tools())),
+    ]
+    for label, fn in probes:
+        try:
+            tools = fn()
+        except (AttributeError, TypeError):
+            continue
+        except Exception:  # noqa: BLE001 — any error from an internal probe means "skip"
+            continue
+        if tools:
+            return tools
+
+    # All probes empty. Surface fastmcp version + attempted paths so the
+    # breakage is diagnosable without re-reading the code.
     import sys
-
+    try:
+        import fastmcp as _fm
+        fm_version = getattr(_fm, "__version__", "unknown")
+    except Exception:  # noqa: BLE001
+        fm_version = "unknown"
     print(
-        "LivePilot: WARNING — could not access FastMCP tool registry, "
-        "string-to-number schema coercion will not work",
+        "LivePilot: ERROR — could not access FastMCP tool registry "
+        f"(fastmcp=={fm_version}). Tried: "
+        + ", ".join(label for label, _ in probes)
+        + ". Schema coercion and tool-catalog generation will be broken. "
+        "If FastMCP updated its internals, see docs/FASTMCP_UPSTREAM_FR.md.",
         file=sys.stderr,
     )
     return []
 
 
+def _assert_tool_registry_accessible() -> None:
+    """Loudly fail startup if the FastMCP registry probe returns nothing.
+
+    Called once at module import, just before schema patching. The schema
+    patch silently no-ops on an empty registry, so without this assertion
+    a FastMCP-internals rename would degrade silently and produce a server
+    with 324 tools but no string-to-number coercion — a subtle, hard-to-
+    diagnose class of failure we've paid for once already.
+
+    Reads the expected count from ``tests/test_tools_contract.py`` (same
+    source of truth sync_metadata.py uses), so no second magic number.
+    """
+    import re
+    import sys
+
+    try:
+        contract_src = (
+            (__file__.rsplit("/", 2)[0] + "/tests/test_tools_contract.py")
+            if "__file__" in globals() else None
+        )
+        # Prefer an absolute path via Path for reliability:
+        from pathlib import Path
+        contract_path = Path(__file__).resolve().parents[1] / "tests" / "test_tools_contract.py"
+        expected = None
+        if contract_path.exists():
+            match = re.search(
+                r"assert len\(tools\) == (\d+)",
+                contract_path.read_text(encoding="utf-8"),
+            )
+            if match:
+                expected = int(match.group(1))
+    except Exception:  # noqa: BLE001 — self-test must not block startup
+        expected = None
+
+    actual = len(_get_all_tools())
+    if actual == 0:
+        # Registry probe returned empty — this is the regression the test guards.
+        # Don't sys.exit (some test harnesses import server.py without a live
+        # FastMCP); print a loud diagnostic and let downstream code react.
+        print(
+            "LivePilot: STARTUP SELF-TEST FAILED — _get_all_tools() returned 0. "
+            "FastMCP internals likely changed. Verify requirements.txt pin "
+            "(fastmcp>=3.0.0,<3.3.0) matches the installed version.",
+            file=sys.stderr,
+        )
+        return
+    if expected is not None and actual != expected:
+        print(
+            f"LivePilot: STARTUP SELF-TEST WARNING — _get_all_tools() "
+            f"returned {actual} tools, tests/test_tools_contract.py expects "
+            f"{expected}. If you've added/removed tools, update the contract "
+            "and run scripts/sync_metadata.py --fix.",
+            file=sys.stderr,
+        )
+
+
 def _patch_tool_schemas() -> None:
     """Post-process all registered tool schemas for string coercion."""
     for tool in _get_all_tools():
@@ -346,6 +479,7 @@ def _patch_tool_schemas() -> None:
             if isinstance(definition, dict):
                 _coerce_schema_property(definition)
 
+_assert_tool_registry_accessible()
 _patch_tool_schemas()
 
 

package/mcp_server/session_continuity/models.py

@@ -22,6 +22,13 @@ class CreativeThread:
     def to_dict(self) -> dict:
         return asdict(self)
 
+    @classmethod
+    def from_dict(cls, data: dict) -> "CreativeThread":
+        """Rehydrate from persisted dict; unknown keys are ignored so a future
+        schema bump won't break load on older on-disk state."""
+        allowed = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in data.items() if k in allowed})
+
     @property
     def is_stale(self) -> bool:
         """A thread is stale if untouched for >30 minutes."""
@@ -44,6 +51,12 @@ class TurnResolution:
     def to_dict(self) -> dict:
         return asdict(self)
 
+    @classmethod
+    def from_dict(cls, data: dict) -> "TurnResolution":
+        """Rehydrate from persisted dict; unknown keys are ignored."""
+        allowed = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in data.items() if k in allowed})
+
 
 @dataclass
 class SessionStory:

package/mcp_server/session_continuity/tools.py

@@ -65,6 +65,7 @@ def record_turn_resolution(
     identity_effect: "preserves", "evolves", "contrasts", or "resets"
     user_sentiment: "loved", "liked", "neutral", "disliked", or "hated"
     """
+    tracker.ensure_project_store_bound(ctx)
     turn = tracker.record_turn_resolution(
         request_text=request_text,
         outcome=outcome,
@@ -130,6 +131,7 @@ def open_creative_thread(
     if not description.strip():
         return {"error": "description cannot be empty"}
 
+    tracker.ensure_project_store_bound(ctx)
     thread = tracker.open_thread(description, domain=domain, priority=priority)
     return thread.to_dict()
 

package/mcp_server/session_continuity/tracker.py

@@ -44,6 +44,99 @@ def reset_story() -> None:
     _project_store = None
 
 
+def bind_project_store_from_session(session_info: dict) -> Optional[str]:
+    """Bind a per-project persistent store and hydrate in-memory state.
+
+    Computes a project fingerprint from ``session_info`` (tempo, time sig,
+    song length, track/scene/return layout), opens the matching
+    ``ProjectStore`` under ``~/.livepilot/projects/<hash>/``, and rehydrates
+    the in-memory ``_threads`` and ``_turns`` from disk so that restarting
+    the MCP server preserves the user's creative threads and turn history.
+
+    Returns the project_id (12-char hash) on success, ``None`` on failure
+    (so callers can log without aborting startup). If the hash hasn't
+    changed since the last bind, this is a no-op — hot path is safe to
+    call on every turn.
+
+    Without this function, ``set_project_store()`` existed but nobody
+    called it, meaning README's "return to a project with prior creative
+    threads intact" was literally false — threads/turns were in-memory
+    only and reset on every server restart.
+    """
+    global _threads, _turns, _project_store
+
+    try:
+        from ..persistence.project_store import ProjectStore, project_hash
+    except Exception as exc:
+        logger.debug("bind_project_store_from_session: import failed: %s", exc)
+        return None
+
+    try:
+        new_id = project_hash(session_info or {})
+    except Exception as exc:
+        logger.debug("bind_project_store_from_session: hash failed: %s", exc)
+        return None
+
+    # Already bound to this project? Nothing to do.
+    if _project_store is not None and getattr(_project_store, "project_id", None) == new_id:
+        return new_id
+
+    try:
+        store = ProjectStore(new_id)
+    except Exception as exc:
+        logger.debug("bind_project_store_from_session: store open failed: %s", exc)
+        return None
+
+    # Hydrate in-memory threads + turns from the persisted store. We only
+    # rebuild what the tracker keeps live — SessionStory is recomputed on
+    # each get_session_story() call, so it doesn't need a direct restore.
+    try:
+        raw_threads = store.get_threads()
+        raw_turns = store.get_turns()
+    except Exception as exc:
+        logger.debug("bind_project_store_from_session: read failed: %s", exc)
+        raw_threads, raw_turns = [], []
+
+    _threads = {
+        t["thread_id"]: CreativeThread.from_dict(t)
+        for t in raw_threads
+        if isinstance(t, dict) and "thread_id" in t
+    }
+    _turns = [
+        TurnResolution.from_dict(t)
+        for t in raw_turns
+        if isinstance(t, dict)
+    ]
+    _project_store = store
+    logger.info(
+        "session_continuity: bound project %s (%d threads, %d turns restored)",
+        new_id, len(_threads), len(_turns),
+    )
+    return new_id
+
+
+def ensure_project_store_bound(ctx) -> Optional[str]:
+    """Lazy bind on first use — for tools called before lifespan could reach Ableton.
+
+    ``ctx`` is a FastMCP Context; reads the ``ableton`` connection from
+    ``ctx.lifespan_context`` and fetches session info to compute the project
+    hash. Safe to call on every turn — if already bound to this project, it's
+    a no-op. Returns the project_id or ``None`` on failure.
+    """
+    if _project_store is not None:
+        return getattr(_project_store, "project_id", None)
+    try:
+        ableton = ctx.lifespan_context.get("ableton")
+        if ableton is None:
+            return None
+        info = ableton.send_command("get_session_info")
+        if isinstance(info, dict) and not info.get("error"):
+            return bind_project_store_from_session(info)
+    except Exception as exc:
+        logger.debug("ensure_project_store_bound: %s", exc)
+    return None
+
+
 # ── Session story ─────────────────────────────────────────────────
 
 

package/mcp_server/tools/_analyzer_engine/__init__.py

@@ -0,0 +1,39 @@
+"""Analyzer helpers — pure-computation + context accessors split out from analyzer.py.
+
+The public tool surface (32 ``@mcp.tool()`` functions) still lives in
+``mcp_server/tools/analyzer.py`` — moving decorators across files risks
+reordering FastMCP's tool registration. This package only holds the
+supporting code that ``analyzer.py`` used to carry inline:
+
+- ``context``  — SpectralCache + M4LBridge accessors and the analyzer
+                 health check that formats user-facing error messages.
+- ``sample``   — Simpler post-load hygiene (Snap=0, warped-loop defaults,
+                 sample-name verification) + filename helpers.
+- ``flucoma``  — FluCoMa-specific hint formatting + pitch-name tables.
+
+Re-exports the public-ish helpers (``_`` prefix is intentional — these
+are implementation details of ``analyzer.py``, not tools in their own
+right) so existing ``from .tools.analyzer import _foo`` imports in tests
+continue to resolve via the thin analyzer module.
+"""
+
+from .context import _get_spectral, _get_m4l, _require_analyzer
+from .sample import (
+    _BPM_IN_FILENAME_RE,
+    _filename_stem,
+    _is_warped_loop,
+    _simpler_post_load_hygiene,
+)
+from .flucoma import PITCH_NAMES, _flucoma_hint
+
+__all__ = [
+    "_get_spectral",
+    "_get_m4l",
+    "_require_analyzer",
+    "_BPM_IN_FILENAME_RE",
+    "_filename_stem",
+    "_is_warped_loop",
+    "_simpler_post_load_hygiene",
+    "PITCH_NAMES",
+    "_flucoma_hint",
+]

package/mcp_server/tools/_analyzer_engine/context.py

@@ -0,0 +1,103 @@
+"""Analyzer lifespan-context accessors + health check.
+
+These were inline in ``analyzer.py`` pre-v1.10.9. Split out as part of
+BUG-C1 so the tool file contains only ``@mcp.tool()`` definitions.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from fastmcp import Context
+
+if TYPE_CHECKING:  # pragma: no cover — type-only imports
+    from ...m4l_bridge import M4LBridge, SpectralCache
+
+logger = logging.getLogger(__name__)
+
+
+def _get_spectral(ctx: Context):
+    """Get the SpectralCache from the lifespan context.
+
+    Attaches the active FastMCP ``Context`` to the cache so the analyzer
+    error path can distinguish "device missing" from "bridge disconnected"
+    — needed for the actionable error messages in ``_require_analyzer``.
+    """
+    cache = ctx.lifespan_context.get("spectral")
+    if not cache:
+        raise ValueError("Spectral cache not initialized — restart the MCP server")
+    setattr(cache, "_livepilot_ctx", ctx)
+    return cache
+
+
+def _get_m4l(ctx: Context):
+    """Get the M4LBridge from the lifespan context."""
+    bridge = ctx.lifespan_context.get("m4l")
+    if not bridge:
+        raise ValueError("M4L bridge not initialized — restart the MCP server")
+    return bridge
+
+
+def _require_analyzer(cache) -> None:
+    """Raise a user-actionable error if the analyzer device isn't reachable.
+
+    The error text is the most user-visible surface of the analyzer layer,
+    so it spends effort distinguishing:
+
+      * "not loaded on master" → concrete drag-and-drop instructions
+      * "loaded but UDP port 9880 held by another instance" → show the
+        PID/command of the holder so the user can close it
+      * "loaded but bridge disconnected for some other reason" → generic
+        reload/restart hint
+
+    The ``_livepilot_ctx`` attribute attached by ``_get_spectral`` is what
+    lets us probe the master-track devices here; without it, the caller
+    would have to pass ``ctx`` through every ``_require_analyzer`` site.
+    """
+    if cache.is_connected:
+        return
+
+    # Imported lazily to avoid a circular import: server.py imports this
+    # package's parent during tool registration.
+    from ...server import _identify_port_holder
+
+    ctx = getattr(cache, "_livepilot_ctx", None)
+    try:
+        track = (
+            ctx.lifespan_context["ableton"].send_command("get_master_track")
+            if ctx else {}
+        )
+    except Exception as exc:
+        logger.debug("_require_analyzer failed: %s", exc)
+        track = {}
+
+    devices = track.get("devices", []) if isinstance(track, dict) else []
+    analyzer_loaded = False
+    for device in devices:
+        normalized = " ".join(
+            str(device.get("name") or "").replace("_", " ").replace("-", " ").lower().split()
+        )
+        if normalized == "livepilot analyzer":
+            analyzer_loaded = True
+            break
+
+    if analyzer_loaded:
+        holder = _identify_port_holder(9880)
+        detail = (
+            "LivePilot Analyzer is loaded on the master track, but its UDP bridge is not connected. "
+        )
+        if holder:
+            detail += (
+                "UDP port 9880 is currently held by another LivePilot instance "
+                f"({holder}). Close the other client/server, then retry."
+            )
+        else:
+            detail += "Reload the analyzer device or restart the MCP server."
+        raise ValueError(detail)
+
+    raise ValueError(
+        "LivePilot Analyzer not detected. "
+        "Drag 'LivePilot Analyzer' onto the master track from "
+        "Audio Effects > Max Audio Effect."
+    )

package/mcp_server/tools/_analyzer_engine/flucoma.py

@@ -0,0 +1,23 @@
+"""FluCoMa-specific helpers (hints + pitch-name table).
+
+Extracted from ``analyzer.py`` as part of BUG-C1. Purely about formatting
+hints for the FluCoMa real-time streams — no Ableton or bridge access.
+"""
+
+from __future__ import annotations
+
+
+PITCH_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+
+
+def _flucoma_hint(cache) -> str:
+    """Return an error hint if no FluCoMa data has arrived on ``cache``.
+
+    If ANY stream has data, FluCoMa is working and the specific stream just
+    hasn't updated yet — return a 'play audio' hint. If NO streams have
+    data, FluCoMa may not be installed — return an install hint.
+    """
+    for key in ("spectral_shape", "mel_bands", "chroma", "loudness"):
+        if cache.get(key):
+            return "play some audio"
+    return "FluCoMa may not be installed. Install via: npx livepilot --setup-flucoma"

package/mcp_server/tools/_analyzer_engine/sample.py

@@ -0,0 +1,122 @@
+"""Simpler post-load hygiene + filename heuristics.
+
+Extracted from ``analyzer.py`` as part of BUG-C1. Covers:
+
+  * BPM-in-filename detection (used to tell warped loops from one-shots)
+  * Post-load verification + Snap=0 + warped-loop defaults for Simpler
+
+Context (docs/2026-04-14-bugs-discovered.md):
+
+The M4L bridge's ``replace_simpler_sample`` command can report success
+even when the sample is still the bootstrap placeholder. Simpler's
+display name also doesn't refresh after a replace. After loading, the
+``Snap`` parameter is ON by default which causes the Sample Start
+position to snap to a location outside the new sample's valid audio —
+resulting in silent playback. The hygiene here fixes both.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+
+logger = logging.getLogger(__name__)
+
+
+_BPM_IN_FILENAME_RE = re.compile(r"(\d{2,3})\s*bpm", re.IGNORECASE)
+
+
+def _is_warped_loop(file_path: str) -> bool:
+    """Return True if the filename contains a BPM marker (likely a tempo-locked loop)."""
+    stem = os.path.splitext(os.path.basename(file_path))[0]
+    return bool(_BPM_IN_FILENAME_RE.search(stem))
+
+
+def _filename_stem(file_path: str) -> str:
+    return os.path.splitext(os.path.basename(file_path))[0]
+
+
+async def _simpler_post_load_hygiene(
+    bridge,
+    ableton,
+    track_index: int,
+    device_index: int,
+    file_path: str,
+) -> dict:
+    """Apply post-load hygiene to a newly loaded Simpler and verify success.
+
+    Steps:
+      1. Read track info to verify the device's actual name matches the
+         expected sample stem. If it doesn't, return an error.
+      2. Set Snap=0 (Off) — required so sample playback works.
+      3. If filename indicates a warped loop, set S Start=0, S Length=1,
+         S Loop On=1 so the loop plays fully instead of being cropped.
+      4. Return a verified response dict.
+    """
+    expected_stem = _filename_stem(file_path)
+
+    # Step 1: verify device name matches expected file
+    try:
+        track_info = ableton.send_command(
+            "get_track_info", {"track_index": track_index}
+        )
+    except Exception as exc:
+        return {"error": f"Verification read failed: {exc}"}
+
+    devices = track_info.get("devices", []) or []
+    if device_index < 0 or device_index >= len(devices):
+        return {
+            "error": (
+                f"Device index {device_index} out of range after load "
+                f"(track has {len(devices)} devices)"
+            ),
+            "verified": False,
+        }
+    device = devices[device_index]
+    actual_name = str(device.get("name") or "")
+    verified = expected_stem in actual_name or actual_name in expected_stem
+    if not verified:
+        return {
+            "error": (
+                f"Sample verification FAILED — Simpler name '{actual_name}' "
+                f"does not match requested file '{expected_stem}'. The bridge "
+                f"reported success but the actual sample is different. "
+                f"Try `load_browser_item` with a user_library URI instead."
+            ),
+            "verified": False,
+            "actual_device_name": actual_name,
+            "expected_stem": expected_stem,
+        }
+
+    # Step 2: turn Snap OFF — required for reliable playback after replace
+    hygiene_params: list[dict] = [
+        {"name_or_index": "Snap", "value": 0},
+    ]
+
+    # Step 3: smart defaults for warped loops
+    if _is_warped_loop(file_path):
+        hygiene_params.extend([
+            {"name_or_index": "S Start", "value": 0.0},
+            {"name_or_index": "S Length", "value": 1.0},
+            {"name_or_index": "S Loop On", "value": 1},
+        ])
+
+    try:
+        ableton.send_command("batch_set_parameters", {
+            "track_index": track_index,
+            "device_index": device_index,
+            "parameters": hygiene_params,
+        })
+    except Exception as exc:
+        logger.debug("_simpler_post_load_hygiene failed: %s", exc)
+        # non-fatal — verification already succeeded
+        pass
+
+    return {
+        "verified": True,
+        "device_name": actual_name,
+        "track_index": track_index,
+        "device_index": device_index,
+        "warped_loop_defaults_applied": _is_warped_loop(file_path),
+    }