livepilot 1.14.0 → 1.15.0-beta

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## 1.15.0-beta — Live 12.4 replace_sample native (April 21 2026)
+
+First Live 12.4 beta support release. Adds a native fast path for
+SimplerDevice.replace_sample(path) while preserving 100% backward
+compatibility for 12.0-12.3.x users.
+
+**Tool count**: unchanged at 403.
+**Domain count**: unchanged at 52.
+**Tests**: 2503 passed, 1 skipped, 0 regressions (+13 new from this release).
+
+### Added
+- **Live 12.4 support (beta):** `SimplerDevice.replace_sample(path)` native
+  LOM path is now used automatically on Live 12.4+. Handles empty Simplers —
+  fixes the long-standing workaround documented in
+  `feedback_load_browser_item_is_source_of_truth.md`.
+- New capability tier `"collaborative"` (Live 12.4+) exposed via
+  `LiveVersionCapabilities.capability_tier` and `.has_replace_sample_native`.
+- Remote Script: new `replace_sample_native` handler.
+- MCP server: new `_live_caps(ctx)` helper with lazy version-capability
+  caching on the lifespan context.
+- Registered `replace_sample_native` in `mcp_server/runtime/remote_commands.py`
+  REMOTE_COMMANDS (required by the boundary audit contract).
+
+### Changed
+- `replace_simpler_sample` and `load_sample_to_simpler` now route to the
+  native path when available and fall back to the M4L-bridge path
+  otherwise. Tool signatures, argument names, and return shapes unchanged.
+
+### Backward Compatibility
+- Live 12.0–12.3.x: zero behavior change. All routing still goes through
+  the M4L bridge.
+- Live 12.4+: native path preferred; bridge used only on fallback.
+
+### Verification status
+- Full test suite: 2503 passed, 0 failures.
+- Backward compat on Live 12.4: verified in-session — `replace_simpler_sample`
+  and `load_sample_to_simpler` both work via the bridge path on 12.4 (legacy
+  flow intact).
+- Native E2E on Live 12.4 empty-Simpler case: deferred until the plugin
+  swap activates the worktree's MCP code. Unit tests prove the routing
+  logic and the native handler wiring.
+
+## 1.14.1 — reload_handlers workflow + device/mixing fixes (April 21 2026)
+
+Patch release that lands the post-1.14.0 audit work: one new diagnostics
+tool, three bug fixes, and a new plugin-sync verification script.
+
+**Tool count**: 402 → **403** (added `reload_handlers`).
+**Domain count**: unchanged at 52.
+**Tests**: 2467 → **2485 passing** (+18 new), 0 regressions.
+
+### New tool: `reload_handlers`
+
+- Replaces the manual "toggle Control Surface in Live → Preferences →
+  Link/MIDI" step that every Remote Script edit required. New workflow:
+  after `npx livepilot --install`, call `reload_handlers` via the MCP
+  tool. The Remote Script side uses `pkgutil` + `importlib.reload()` to
+  re-fire all `@register` decorators in place in <1s, without dropping
+  the MCP TCP connection on port 9878.
+- Ships with a pkgutil-based module-discovery helper in
+  `remote_script/LivePilot/__init__.py`, so new handler modules added to
+  `remote_script/LivePilot/` are picked up automatically on reload.
+- Exception: the very first bootstrap (no prior `LivePilot.*` in
+  `sys.modules`) still needs one full Ableton restart. After that,
+  `reload_handlers` works forever.
+- Domain: `diagnostics`. Added to `docs/manual/tool-catalog.md` to keep
+  the CI skill-contract test green.
+
+### Bug fixes
+
+- **`find_and_load_device` duplicate loads** — the tool was no-oping
+  only on exact name match; changed to also treat cases where the
+  target device is already the tail of the chain as a no-op. Prevents
+  the "load Simpler, load Simpler, load Simpler" cascade when the MCP
+  server retries a loader.
+- **`get_device_parameters` "Invalid display value"** — certain Live
+  parameters (especially plugin wrappers on AU/VST) raise
+  `RuntimeError("Invalid display value")` when their
+  `str_for_value()` is queried before the parameter has settled. The
+  handler now swallows that specific error and returns the raw float
+  instead of 500-ing the whole request.
+- **Sidechain LOM reopen (BUG-A3 redux)** — Compressor2 moved its
+  sidechain block into a nested property in a recent Live update, so
+  `compressor_set_sidechain` lost the ability to toggle. The handler
+  now probes the LOM surface at tool-call time and falls back to the
+  flat path when the nested one isn't exposed.
+- **Mixing `channel` lazy-get** — channel objects were resolved eagerly
+  at import time, breaking in edge cases where the Song came up before
+  the mixer. Now resolved on first use.
+
+### New: plugin-sync verification
+
+- `scripts/verify_plugin_sync.py` — catches the v1.14.0 regression
+  class where `.mcp.json` went missing from
+  `~/.claude/plugins/cache/dreamrec-LivePilot/livepilot/$VERSION/`. All
+  four sync targets (active plugin dir, cache version dir, marketplace
+  snapshot, `installed_plugins.json`) are now verified by one command.
+
+---
+
 ## 1.14.0 — Branch-native v2: producer context, synth intelligence, render verify (April 20 2026)
 
 Five-PR follow-up to v1.13.0 that closes the loops the first pass left

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  402 tools. 52 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
+  403 tools. 52 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
 </p>
 
 <br>
@@ -79,7 +79,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   402 MCP Tools  │                                  │
+│                  │   403 MCP Tools  │                                  │
 │                  │   52 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
@@ -120,7 +120,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 402 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 403 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -172,7 +172,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-402 tools across 52 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+403 tools across 52 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -360,7 +360,7 @@ The V2 intelligence layer. These tools analyze, diagnose, plan, evaluate, and le
 | Creative Constraints | 5 | constraint activation, reference-inspired variants |
 | Preview Studio | 5 | variant creation, preview rendering, comparison, commit |
 
-> **[View all 402 tools →](docs/manual/tool-catalog.md)**
+> **[View all 403 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -587,7 +587,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 402 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 403 tools, workflows |
 | [Intelligence Layer](docs/manual/intelligence.md) | How the 12 engines connect — conductor, moves, preview, evaluation |
 | [Device Atlas](docs/manual/device-atlas.md) | 1305 devices indexed — search, suggest, chain building |
 | [Samples & Slicing](docs/manual/samples.md) | 3-source search, fitness critics, slice workflows |

package/m4l_device/livepilot_bridge.js

@@ -95,7 +95,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.14.0"});
+            send_response({"ok": true, "version": "1.14.1"});
             break;
         case "get_params":
             cmd_get_params(args);

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.14.0"
+__version__ = "1.15.0-beta"

package/mcp_server/runtime/live_version.py

@@ -79,8 +79,10 @@ class LiveVersionCapabilities:
 
     @property
     def capability_tier(self) -> str:
-        """Human-readable tier: core | enhanced_arrangement | full_intelligence."""
-        if self._version_tuple >= (12, 3, 0):
+        """Human-readable tier: core | enhanced_arrangement | full_intelligence | collaborative."""
+        if self._version_tuple >= (12, 4, 0):
+            return "collaborative"
+        elif self._version_tuple >= (12, 3, 0):
             return "full_intelligence"
         elif self._version_tuple >= (12, 1, 10):
             return "enhanced_arrangement"

package/mcp_server/runtime/remote_commands.py

@@ -105,6 +105,8 @@ REMOTE_COMMANDS: frozenset[str] = frozenset({
     "get_session_diagnostics",
     # control surfaces (diagnostic)
     "list_control_surfaces", "get_control_surface_info",
+    # dev-loop helper — reloads handler submodules without a UI toggle
+    "reload_handlers",
     # song primitives — transport/link
     "tap_tempo", "nudge_tempo",
     "set_exclusive_arm", "set_exclusive_solo",
@@ -115,6 +117,8 @@ REMOTE_COMMANDS: frozenset[str] = frozenset({
     "get_appointed_device",
     # ping (built-in)
     "ping",
+    # Live 12.4+ native Simpler sample replacement (Collaborative tier)
+    "replace_sample_native",
 })
 
 # M4L bridge commands — routed through TCP but handled by livepilot_bridge.js

package/mcp_server/tools/analyzer.py

@@ -64,6 +64,71 @@ def _enrich_slice_response(response: Optional[dict]) -> Optional[dict]:
     return enriched
 
 
+def _live_caps(ctx):
+    """Read (or lazily compute + cache) LiveVersionCapabilities on the context.
+
+    On first call, queries Ableton via get_session_info and caches the
+    result in ``ctx.lifespan_context["_live_caps"]``. Subsequent calls
+    short-circuit to the cache. If Ableton is unreachable, falls back to
+    12.0.0 (conservative — all new-version gates return False).
+
+    This mirrors the on-demand pattern in
+    mcp_server/runtime/capability_probe.py and avoids adding a startup
+    round-trip to the lifespan.
+    """
+    from mcp_server.runtime.live_version import LiveVersionCapabilities
+
+    lsc = ctx.lifespan_context
+    cached = lsc.get("_live_caps")
+    if cached is not None:
+        return cached
+
+    version_str = "12.0.0"
+    ableton = lsc.get("ableton")
+    if ableton is not None:
+        try:
+            info = ableton.send_command("get_session_info") or {}
+            version_str = info.get("live_version", "12.0.0")
+        except Exception:
+            pass
+
+    caps = LiveVersionCapabilities.from_version_string(version_str)
+    lsc["_live_caps"] = caps
+    return caps
+
+
+async def _try_native_replace_sample(ctx, track_index: int, device_index: int,
+                                      file_path: str):
+    """Attempt the Live 12.4+ native SimplerDevice.replace_sample path.
+
+    Returns the remote-script response dict on success, or None if the
+    native path is unavailable (pre-12.4) or failed (caller should fall
+    back to the M4L-bridge path).
+
+    A native "failure" is any of: gate closed, dispatch exception, non-dict
+    response, error field present, or missing sample_loaded flag.
+    """
+    caps = _live_caps(ctx)
+    if not caps.has_replace_sample_native:
+        return None
+    ableton = ctx.lifespan_context["ableton"]
+    try:
+        resp = ableton.send_command("replace_sample_native", {
+            "track_index": track_index,
+            "device_index": device_index,
+            "file_path": file_path,
+        })
+    except Exception:
+        return None
+    if not isinstance(resp, dict):
+        return None
+    if "error" in resp:
+        return None
+    if not resp.get("sample_loaded"):
+        return None
+    return resp
+
+
 @mcp.tool()
 async def reconnect_bridge(ctx: Context) -> dict:
     """Attempt to reconnect the M4L UDP bridge (port 9880).
@@ -350,12 +415,27 @@ async def replace_simpler_sample(
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
     ableton = ctx.lifespan_context["ableton"]
+
+    # Live 12.4+: prefer the native SimplerDevice.replace_sample path.
+    native = await _try_native_replace_sample(
+        ctx, track_index, device_index, file_path
+    )
+    if native is not None:
+        hygiene = await _simpler_post_load_hygiene(
+            bridge, ableton, track_index, device_index, file_path
+        )
+        if not hygiene.get("verified"):
+            return hygiene
+        result = dict(native)
+        result.update(hygiene)
+        result["method"] = "native_12_4"  # preserved in case hygiene ever adds its own key
+        return result
+
+    # Pre-12.4 fallback: M4L bridge path (unchanged behavior).
     result = await bridge.send_command(
         "replace_simpler_sample", track_index, device_index, file_path
     )
 
-    # Validate the response — the bridge may report success even when the
-    # sample silently failed to load (e.g., empty Simpler, bad path)
     if "error" in result:
         return result
     if not result.get("sample_loaded"):
@@ -364,8 +444,6 @@ async def replace_simpler_sample(
             "has a sample loaded — replace_sample silently fails on empty Simplers."
         }
 
-    # Verify by reading back the device name — guards against the silent
-    # failure mode where the bridge reports success but keeps the placeholder.
     hygiene = await _simpler_post_load_hygiene(
         bridge, ableton, track_index, device_index, file_path
     )
@@ -405,9 +483,39 @@ async def load_sample_to_simpler(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
+    ableton = ctx.lifespan_context["ableton"]
+
+    # Live 12.4+: create an empty Simpler via insert_device, then use the
+    # native replace_sample path. Skips the dummy-sample bootstrap entirely.
+    caps = _live_caps(ctx)
+    if caps.has_replace_sample_native:
+        try:
+            ins = ableton.send_command("insert_device", {
+                "track_index": track_index,
+                "device_name": "Simpler",
+            })
+        except Exception:
+            ins = None
+        if isinstance(ins, dict) and "error" not in ins:
+            actual_device_index = ins.get("device_index", device_index)
+            native = await _try_native_replace_sample(
+                ctx, track_index, actual_device_index, file_path
+            )
+            if native is not None:
+                hygiene = await _simpler_post_load_hygiene(
+                    bridge, ableton, track_index, actual_device_index, file_path
+                )
+                if not hygiene.get("verified"):
+                    return hygiene
+                result = dict(native)
+                result.update(hygiene)
+                result["method"] = "native_12_4"
+                result["device_index"] = actual_device_index
+                result["track_index"] = track_index
+                return result
+        # Fall through to the legacy bootstrap path below on any failure.
 
     # Step 1: Load a sample from the browser to create Simpler with content
-    ableton = ctx.lifespan_context["ableton"]
     try:
         search = ableton.send_command("search_browser", {
             "path": "samples",

package/mcp_server/tools/devices.py

@@ -426,9 +426,20 @@ def move_device(
 
 
 @mcp.tool()
-def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> dict:
+def find_and_load_device(
+    ctx: Context,
+    track_index: int,
+    device_name: str,
+    allow_duplicate: bool = False,
+) -> dict:
     """Search the browser for a device by name and load it onto a track.
-    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.
+
+    allow_duplicate (default False): if a device with the same name is
+    already on the track's chain, the default behavior is to NO-OP and
+    return the existing device's location with `already_present: True`.
+    Pass allow_duplicate=True to force a second instance (e.g., parallel
+    processing chains where you genuinely want two of the same device)."""
     _validate_track_index(track_index)
     if not device_name.strip():
         raise ValueError("device_name cannot be empty")
@@ -447,6 +458,7 @@ def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> di
     result = _get_ableton(ctx).send_command("find_and_load_device", {
         "track_index": track_index,
         "device_name": device_name,
+        "allow_duplicate": allow_duplicate,
     })
     return _postflight_loaded_device(ctx, result)
 

package/mcp_server/tools/diagnostics.py

@@ -40,3 +40,24 @@ def get_control_surface_info(ctx: Context, index: int) -> dict:
     """
     return _get_ableton(ctx).send_command("get_control_surface_info",
                                           {"index": index})
+
+
+@mcp.tool()
+def reload_handlers(ctx: Context) -> dict:
+    """Reload every Remote Script handler module in Ableton — dev-loop helper.
+
+    Client-side wrapper for the `reload_handlers` TCP command exposed by the
+    Remote Script (see `remote_script/LivePilot/__init__.py`). Re-discovers
+    handler submodules via pkgutil.iter_modules and reloads each one,
+    re-firing @register decorators against a freshly-cleared router. Lets
+    you edit a handler file → run installer → call this tool, without a
+    Control Surface toggle or Ableton restart.
+
+    Does NOT reload `router`, `server`, or `__init__.py` — Ableton's
+    embedded Python handles only leaf-submodule reloads correctly.
+
+    Returns {reloaded: True, handler_count: int} so callers can assert the
+    post-reload registration surface. Raises if the Remote Script is
+    pre-PR#16 (will surface as `[NOT_FOUND] Unknown command type`).
+    """
+    return _get_ableton(ctx).send_command("reload_handlers", {})

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.14.0",
+  "version": "1.15.0-beta",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 402 tools, 52 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
+  "description": "Agentic production system for Ableton Live 12 — 403 tools, 52 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
   "author": "Pilot Studio",
   "license": "BSL-1.1",
   "type": "commonjs",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.14.0"
+__version__ = "1.15.0-beta"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router
@@ -26,52 +26,70 @@ from . import follow_actions    # noqa: F401  — registers follow action handle
 from . import grooves           # noqa: F401  — registers groove pool handlers (11+)
 from . import take_lanes        # noqa: F401  — registers take lane handlers (12.0+ read, 12.2+ write)
 from . import clip_automation   # noqa: F401  — registers clip automation handlers
+from . import simpler_sample    # noqa: F401  — registers replace_sample_native (12.4+)
 from . import version_detect    # noqa: F401  — version detection
 
 
 # ── Reload plumbing (BUG-B-reload, Batch 20) ──────────────────────────────
 # Ableton keeps `sys.modules["LivePilot.*"]` cached across Control Surface
 # toggles. Without intervention, edits to handler files don't take effect
-# until a full Ableton restart — the toggle just re-instantiates the
-# ControlSurface class without re-importing submodules.
+# until a full Ableton restart.
 #
-# Fix: track whether this is the first create_instance call per
-# interpreter lifetime. On subsequent calls, force-reload the router
-# (which clears _handlers) and every handler module (which re-fires
-# @register decorators with the updated code). Result: a Control Surface
-# toggle now behaves like a fresh module reload, so live-editing mixing.py
-# / devices.py / etc. and re-toggling is enough — no Ableton restart.
+# Fix: on every create_instance() except the first, re-discover every
+# handler module on disk via pkgutil.iter_modules() and reload it. This
+# side-steps two separate issues: (1) the old hardcoded _HANDLER_MODULES
+# tuple that had to be manually updated for every new handler file, and
+# (2) Ableton's embedded Python silently no-op'ing importlib.reload() on
+# the package itself — a behavior confirmed empirically by observing
+# that a module-level file write in __init__.py never fires across
+# toggles, only at initial Live boot. pkgutil.iter_modules reads the
+# filesystem directly and relies only on reloading leaf submodules
+# (which Ableton handles correctly), so NEW handler files are picked up
+# on the next toggle / TCP reload_handlers call.
 #
-# Order matters: utils comes first because every handler imports
-# ``from .utils import get_track, get_device``. If utils isn't reloaded
-# first, those re-imports during ``importlib.reload(devices)`` still
-# resolve to the stale ``utils`` module object in ``sys.modules``.
+# In addition, a `reload_handlers` TCP command is exposed so the dev
+# loop becomes: edit source → sync → TCP reload_handlers → done. No
+# more UI toggles required during iteration.
+#
+# Order matters:
+#   1. Reload router first — clears _handlers so re-register is clean.
+#   2. Reload utils next — every handler imports get_track/get_device
+#      from it; must be fresh before handlers that depend on it reload.
+#   3. Discover + reload everything else via pkgutil.
 
 _FIRST_CREATE_INSTANCE = True
 
-_HANDLER_MODULES = (
-    utils,
-    transport, tracks, clips, notes, devices, scenes, scales,
-    mixing, browser, arrangement, diagnostics, follow_actions,
-    grooves, take_lanes, clip_automation, version_detect,
-)
+# Modules excluded from auto-reload. router is reloaded first (separately)
+# because clearing its _handlers must precede re-register. server owns the
+# TCP listener — reloading it mid-run would drop the socket.
+_RELOAD_EXCLUDE = {"router", "server"}
 
 
 def _force_reload_handlers(cs=None):
-    """Force Python to re-read the handler modules from disk.
-
-    Called on every create_instance() except the first, so edits to
-    handler files take effect via Control Surface toggle without
-    restarting Ableton. Order matters: router first (clears _handlers),
-    then each handler module (re-registers its @register decorators).
-
-    When ``cs`` is provided, reload exceptions are logged through the
-    ControlSurface so a SyntaxError / NameError in an edited handler is
-    surfaced in Live's status log instead of silently swallowed. The
-    previous ``except Exception: pass`` turned any bad handler into a
-    silent NOT_FOUND at dispatch time with no hint that reload had failed.
+    """Re-discover and reload every handler submodule on disk.
+
+    Uses pkgutil.iter_modules so NEW handler files added after Live boot
+    are picked up on the next call without any hand-maintained tuple.
+    Only touches leaf submodules — the one reload operation Ableton's
+    embedded Python handles correctly. Reloading the package itself was
+    tried and empirically no-ops in Ableton's Python.
+
+    Order:
+      1. Reload router → clears _handlers.
+      2. Reload utils → every handler imports get_track/get_device from it.
+      3. Discover + import/reload every other submodule. First-time imports
+         fire @register once; reloads re-fire it after the router reset.
+      4. Re-register reload_handlers_cmd (defined in __init__.py, not a
+         handler module, so not covered by step 3).
+
+    When ``cs`` is provided, reload exceptions log to the ControlSurface so
+    a SyntaxError / NameError in an edited handler is surfaced in Live's
+    status log instead of silently swallowed.
     """
     import importlib
+    import pkgutil
+    import sys as _sys
+
     def _log(msg):
         if cs is None:
             return
@@ -83,20 +101,60 @@ def _force_reload_handlers(cs=None):
     try:
         importlib.reload(router)
     except Exception as exc:
-        _log("reload(router) FAILED — %s: %s. Handlers will be "
-             "stale until Ableton restart." % (type(exc).__name__, exc))
-    for mod in _HANDLER_MODULES:
+        _log("reload(router) FAILED — %s: %s" % (type(exc).__name__, exc))
+
+    try:
+        importlib.reload(utils)
+    except Exception as exc:
+        _log("reload(utils) FAILED — %s: %s" % (type(exc).__name__, exc))
+
+    # Invalidate caches so iter_modules sees newly-added files even if
+    # an importer cached the previous directory listing.
+    importlib.invalidate_caches()
+    pkg = _sys.modules.get("LivePilot")
+    if pkg is None or getattr(pkg, "__path__", None) is None:
+        return
+
+    discovered = reloaded = first_imported = 0
+    for _finder, modname, _is_pkg in pkgutil.iter_modules(pkg.__path__):
+        if modname in _RELOAD_EXCLUDE or modname == "utils":
+            continue
+        discovered += 1
+        full_name = "LivePilot." + modname
         try:
-            importlib.reload(mod)
+            cached = _sys.modules.get(full_name)
+            if cached is not None:
+                importlib.reload(cached)
+                reloaded += 1
+            else:
+                importlib.import_module(full_name)
+                first_imported += 1
         except Exception as exc:
-            # Don't block Ableton startup on a single bad reload, but do
-            # tell the user what happened — the stale handler will keep
-            # serving the OLD code until a full restart.
-            _log("reload(%s) FAILED — %s: %s. Handler is stale." % (
-                getattr(mod, "__name__", "?"),
-                type(exc).__name__,
-                exc,
-            ))
+            _log("reload(%s) FAILED — %s: %s" % (
+                full_name, type(exc).__name__, exc))
+
+    # reload_handlers_cmd lives in __init__.py (not a handler module),
+    # so the step-3 loop does not cover it. Re-register manually.
+    router._handlers["reload_handlers"] = reload_handlers_cmd
+
+    _log("reload complete — %d discovered (%d reloaded, %d first-imported)" % (
+        discovered, reloaded, first_imported))
+
+
+def reload_handlers_cmd(song, params):
+    """TCP-accessible reload trigger. Lets automation refresh handlers
+    without a UI Control Surface toggle — the core dev-loop improvement.
+    Returns the handler count so the caller can assert before/after."""
+    _force_reload_handlers(cs=None)
+    return {
+        "reloaded": True,
+        "handler_count": len(router._handlers),
+    }
+
+
+# Register the TCP-triggered reload command for initial boot.
+# _force_reload_handlers re-registers it after each reload cycle.
+router._handlers["reload_handlers"] = reload_handlers_cmd
 
 
 def create_instance(c_instance):

package/remote_script/LivePilot/devices.py

@@ -46,21 +46,29 @@ def get_device_parameters(song, params):
 
     parameters = []
     for i, param in enumerate(device.parameters):
-        info = {
+        # Live raises RuntimeError("Invalid display value") from
+        # str_for_value / display_value when a parameter's internal
+        # display string is unset or NaN — seen on Operator,
+        # Compressor2, AutoFilter2. Serialize best-effort so one bad
+        # parameter does not abort the whole device read.
+        try:
+            value_string = param.str_for_value(param.value)
+        except Exception:
+            value_string = None
+        try:
+            display_value = param.display_value
+        except Exception:
+            display_value = None
+        parameters.append({
             "index": i,
             "name": param.name,
             "value": param.value,
             "min": param.min,
             "max": param.max,
             "is_quantized": param.is_quantized,
-            "value_string": param.str_for_value(param.value),
-        }
-        # 12.2+ feature: native display_value
-        try:
-            info["display_value"] = param.display_value
-        except AttributeError:
-            pass
-        parameters.append(info)
+            "value_string": value_string,
+            "display_value": display_value,
+        })
     return {"parameters": parameters}
 
 
@@ -633,16 +641,74 @@ def set_drum_chain_note(song, params):
     }
 
 
+def _normalize_device_name(name):
+    """Case/space/underscore/dash-insensitive normalization for device names.
+
+    Matches the convention used by _require_analyzer in the MCP layer —
+    the frozen .amxd ships different names across versions
+    ('LivePilot_Analyzer' vs 'LivePilot Analyzer'), and user devices are
+    freely renamed with mixed casing. Collapsing to a canonical form lets
+    the duplicate check survive those variants.
+    """
+    return " ".join(str(name).replace("_", " ").replace("-", " ").lower().split())
+
+
+def _find_existing_on_track(track, target_name):
+    """Return (index, device) of the first existing device on `track`
+    whose normalized name matches `target_name`, or None.
+
+    Caller passes `target_name` already lowercased (the handler does
+    .lower() on params['device_name']). We normalize again on both sides
+    because the existing device name may have extra whitespace or the
+    user may have typed with different separators.
+    """
+    try:
+        devices = list(track.devices)
+    except AttributeError:
+        return None
+    target = _normalize_device_name(target_name)
+    for i, dev in enumerate(devices):
+        try:
+            name = dev.name
+        except AttributeError:
+            continue
+        if _normalize_device_name(name) == target:
+            return (i, dev)
+    return None
+
+
 @register("find_and_load_device")
 def find_and_load_device(song, params):
     """Find a device by name in the browser and load it onto a track.
 
     Searches all browser categories including user_library for M4L devices.
     Supports partial matching: 'Kickster' matches 'trnr.Kickster'.
+
+    If a device with the same (normalized) name already exists on the
+    target track's chain, returns the existing device's location without
+    loading a second copy. Set `allow_duplicate=True` to force-load a
+    second instance (e.g. parallel processing chains).
     """
     track_index = int(params["track_index"])
     device_name = str(params["device_name"]).lower()
+    allow_duplicate = bool(params.get("allow_duplicate", False))
     track = get_track(song, track_index)
+
+    # Duplicate check — runs BEFORE any load path (12.3 native fast path
+    # AND browser search) so both are protected. Previously the analyzer
+    # auto-load at session start produced two analyzers on the master if
+    # one was already present from a prior session, doubling CPU cost.
+    if not allow_duplicate:
+        existing = _find_existing_on_track(track, device_name)
+        if existing is not None:
+            idx, dev = existing
+            return {
+                "loaded": dev.name,
+                "track_index": track_index,
+                "device_index": idx,
+                "already_present": True,
+            }
+
     browser = _get_browser()
 
     # 12.3+ fast path: try insert_device for native devices

package/remote_script/LivePilot/mixing.py

@@ -295,16 +295,122 @@ def set_track_routing(song, params):
     return result
 
 
+def _find_sidechain_surface(device):
+    """Probe a Compressor device for its sidechain-routing LOM surface.
+
+    Legacy Compressor (I) exposes flat properties directly on the device:
+        available_sidechain_input_routing_types / _channels
+        sidechain_input_routing_type / _channel
+    Live 12.3.6's Compressor2 may not have those flat attrs (confirmed
+    via Batch 18's Max JS probe and Batch 19's Python fallback both
+    hitting the same gap in the flat surface). This probe tries a few
+    known shapes in order and returns the first that matches.
+
+    Returns a dict:
+        desc:      string describing which shape matched
+        types:     list of RoutingType candidates for input source
+        channels:  list of RoutingChannel candidates, or None if the
+                   shape doesn't expose a channel list
+        set_type:  callable(RoutingType) — assigns the input type
+        set_chan:  callable(RoutingChannel) — assigns the channel
+        read_type: callable() -> RoutingType or None
+        read_chan: callable() -> RoutingChannel or None
+    Or None if no known shape matches — caller should emit a diagnostic.
+    """
+    def _shape(obj, types_attr, chans_attr, type_prop, chan_prop, desc):
+        # Channels MUST be read lazily — on Compressor2's input_routing_*
+        # shape, available_input_routing_channels depends on the currently
+        # selected input_routing_type. Snapshotting at probe time made
+        # combined (type + channel) calls fail because the snapshot was
+        # taken BEFORE the new type was written. A fresh read per query
+        # also keeps us honest against UI-side changes mid-call.
+        def _get_channels():
+            if not hasattr(obj, chans_attr):
+                return None
+            return list(getattr(obj, chans_attr))
+
+        return {
+            "desc": desc,
+            "types": list(getattr(obj, types_attr)),
+            "get_channels": _get_channels,
+            "set_type": lambda rt: setattr(obj, type_prop, rt),
+            "set_chan": lambda rc: setattr(obj, chan_prop, rc),
+            "read_type": lambda: getattr(obj, type_prop, None),
+            "read_chan": lambda: getattr(obj, chan_prop, None),
+        }
+
+    if hasattr(device, "available_sidechain_input_routing_types"):
+        return _shape(
+            device,
+            "available_sidechain_input_routing_types",
+            "available_sidechain_input_routing_channels",
+            "sidechain_input_routing_type",
+            "sidechain_input_routing_channel",
+            "flat device.sidechain_input_routing_*",
+        )
+    sc_input = getattr(device, "sidechain_input", None)
+    if sc_input is not None and hasattr(sc_input, "available_routing_types"):
+        return _shape(
+            sc_input,
+            "available_routing_types",
+            "available_routing_channels",
+            "routing_type",
+            "routing_channel",
+            "nested device.sidechain_input.routing_*",
+        )
+    if hasattr(device, "available_input_routing_types"):
+        return _shape(
+            device,
+            "available_input_routing_types",
+            "available_input_routing_channels",
+            "input_routing_type",
+            "input_routing_channel",
+            "flat device.input_routing_* (no sidechain_ prefix)",
+        )
+    return None
+
+
+def _collect_routing_diagnostic(device):
+    """Return a CSV of routing/sidechain attrs on device + likely children.
+
+    Used as a breadcrumb in the error message when _find_sidechain_surface
+    returns None, so the first failing call tells us what the current Live
+    build actually exposes without a separate probe session.
+    """
+    def _attrs(obj, prefix):
+        try:
+            names = sorted(
+                a for a in dir(obj)
+                if ("routing" in a.lower() or "sidechain" in a.lower())
+                and not a.startswith("_")
+            )
+        except Exception:
+            return []
+        return [prefix + n for n in names]
+
+    found = list(_attrs(device, "device."))
+    for child_name in ("sidechain_input", "input", "sidechain", "routing"):
+        try:
+            child = getattr(device, child_name, None)
+        except Exception:
+            child = None
+        if child is None:
+            continue
+        found.extend(_attrs(child, "device.%s." % child_name))
+    return ", ".join(found) if found else "<none>"
+
+
 @register("set_compressor_sidechain")
 def set_compressor_sidechain(song, params):
     """Configure a Compressor's sidechain input routing (BUG-A3).
 
-    Same LOM pattern as set_track_routing — the sidechain properties
-    (available_sidechain_input_routing_types / _channels) are on the
-    device object and Python's Remote Script accesses them cleanly.
-    This used to be routed through the M4L bridge (v1.10.6) but Max JS
-    LiveAPI couldn't read the available_* lists in Live 12.3.6, so it's
-    back on the Python side where it belongs.
+    Probes the LOM sidechain-routing surface — legacy Compressor (I)
+    exposes `available_sidechain_input_routing_types` directly, but
+    Live 12.3.6's Compressor2 doesn't, so we fall back to a small set of
+    known shapes via _find_sidechain_surface. On no match the error
+    message embeds a dir() audit of routing/sidechain attrs on the
+    device and its likely children so future Live builds reveal
+    themselves without a separate probe.
 
     Params:
         track_index: 0+ regular, -1/-2 returns, -1000 master
@@ -338,12 +444,9 @@ def set_compressor_sidechain(song, params):
 
     # Older Compressor builds may not expose `sidechain_enabled` as a
     # property; the automatable "S/C On" parameter is the fallback.
-    # Try both paths so the sidechain gets enabled whichever surface is
-    # available on this Live version.
     try:
         device.sidechain_enabled = True
     except AttributeError:
-        # Fallback: find the "S/C On" parameter and toggle it
         for param in device.parameters:
             if param.name == "S/C On":
                 param.value = 1
@@ -355,13 +458,19 @@ def set_compressor_sidechain(song, params):
         "device_index": device_index,
     }
 
-    if source_type is not None and source_type != "":
-        if not hasattr(device, "available_sidechain_input_routing_types"):
-            raise ValueError(
-                "This Live build doesn't expose "
-                "device.available_sidechain_input_routing_types"
-            )
-        available = list(device.available_sidechain_input_routing_types)
+    want_type = source_type is not None and source_type != ""
+    want_channel = source_channel is not None and source_channel != ""
+    surface = _find_sidechain_surface(device)
+
+    if (want_type or want_channel) and surface is None:
+        raise ValueError(
+            "This Live build doesn't expose a sidechain routing surface "
+            "on %s. Inspected attrs: %s"
+            % (class_name, _collect_routing_diagnostic(device))
+        )
+
+    if want_type:
+        available = surface["types"]
         matched = None
         for rt in available:
             if rt.display_name == source_type:
@@ -370,40 +479,51 @@ def set_compressor_sidechain(song, params):
         if matched is None:
             options = [rt.display_name for rt in available]
             raise ValueError(
-                "Sidechain input type '%s' not found. Available: %s"
-                % (source_type, ", ".join(options))
+                "Sidechain input type '%s' not found (surface=%s). "
+                "Available: %s"
+                % (source_type, surface["desc"], ", ".join(options))
             )
-        device.sidechain_input_routing_type = matched
-
-    if source_channel is not None and source_channel != "":
-        if not hasattr(device, "available_sidechain_input_routing_channels"):
+        surface["set_type"](matched)
+
+    if want_channel:
+        # Lazy fetch — on Compressor2 the channel list depends on the
+        # currently-set input_routing_type, so combined calls need the
+        # post-type-write state, not the probe-time snapshot.
+        channels = surface["get_channels"]()
+        if channels is None:
             raise ValueError(
-                "This Live build doesn't expose "
-                "device.available_sidechain_input_routing_channels"
+                "Sidechain surface on %s (%s) exposes input types but no "
+                "channel list. Inspected attrs: %s"
+                % (class_name, surface["desc"],
+                   _collect_routing_diagnostic(device))
             )
-        available = list(device.available_sidechain_input_routing_channels)
         matched = None
-        for ch in available:
+        for ch in channels:
             if ch.display_name == source_channel:
                 matched = ch
                 break
         if matched is None:
-            options = [ch.display_name for ch in available]
+            options = [ch.display_name for ch in channels]
             raise ValueError(
-                "Sidechain input channel '%s' not found. Available: %s"
-                % (source_channel, ", ".join(options))
+                "Sidechain input channel '%s' not found (surface=%s). "
+                "Available: %s"
+                % (source_channel, surface["desc"], ", ".join(options))
             )
-        device.sidechain_input_routing_channel = matched
+        surface["set_chan"](matched)
 
-    # Read back canonical display names
+    # Read back via the same surface used to write. Fall back to the
+    # input params if the surface isn't exposed or raises on read.
     try:
+        if surface is None:
+            raise AttributeError("no sidechain surface for readback")
+        type_obj = surface["read_type"]()
+        chan_obj = surface["read_chan"]()
         result["sidechain"] = {
-            "type": device.sidechain_input_routing_type.display_name,
-            "channel": device.sidechain_input_routing_channel.display_name,
+            "type": type_obj.display_name if type_obj is not None else "",
+            "channel": chan_obj.display_name if chan_obj is not None else "",
             "enabled": bool(getattr(device, "sidechain_enabled", True)),
         }
     except AttributeError:
-        # Very old Compressor — fall back to whatever we set above
         result["sidechain"] = {
             "type": source_type or "",
             "channel": source_channel or "",

package/remote_script/LivePilot/simpler_sample.py

@@ -0,0 +1,98 @@
+# remote_script/LivePilot/simpler_sample.py
+"""
+LivePilot — Simpler sample replacement via the native Live 12.4 LOM API.
+
+Exposes a ``replace_sample_native`` command that calls
+``SimplerDevice.replace_sample(absolute_path)`` directly on the main thread.
+Unlike the M4L-bridge path, this handler works on empty Simplers (the whole
+reason 12.4 added the native API) and does not require a Max for Live
+device in the Set.
+
+Version-gated on ``replace_sample_native`` (12.4.0+). On earlier versions
+the handler returns a STATE_ERROR; callers (MCP tools) are expected to
+fall back to the bridge path.
+"""
+
+from .router import register
+from .version_detect import has_feature, version_string
+
+
+@register("replace_sample_native")
+def replace_sample_native(song, params):
+    """Replace the sample in a Simpler device using the Live 12.4+ native API.
+
+    params dict keys:
+        track_index (int): 0-based index into song.tracks.
+        device_index (int): 0-based index into the track's devices.
+        file_path (str): absolute path to the audio file to load.
+
+    Returns on success:
+        sample_loaded (bool): True.
+        track_index (int): echoed from input.
+        device_index (int): echoed from input.
+        method (str): "native_12_4".
+        live_version (str): detected Live version at call time.
+
+    Returns on error:
+        error (str): human-readable message.
+        code (str): STATE_ERROR | INDEX_ERROR | INVALID_PARAM | INTERNAL.
+    """
+    if not has_feature("replace_sample_native"):
+        return {
+            "error": (
+                "replace_sample_native requires Live 12.4+. "
+                "Detected: " + version_string() + ". "
+                "Use the M4L-bridge replace_simpler_sample path instead."
+            ),
+            "code": "STATE_ERROR",
+        }
+
+    try:
+        track_index = int(params["track_index"])
+        device_index = int(params["device_index"])
+        file_path = str(params["file_path"])
+    except (KeyError, TypeError, ValueError) as exc:
+        return {
+            "error": "Invalid params: " + str(exc),
+            "code": "INVALID_PARAM",
+        }
+
+    tracks = list(song.tracks)
+    if track_index < 0 or track_index >= len(tracks):
+        return {
+            "error": "track_index " + str(track_index) + " out of range",
+            "code": "INDEX_ERROR",
+        }
+
+    track = tracks[track_index]
+    devices = list(track.devices)
+    if device_index < 0 or device_index >= len(devices):
+        return {
+            "error": "device_index " + str(device_index) + " out of range",
+            "code": "INDEX_ERROR",
+        }
+
+    device = devices[device_index]
+    class_name = getattr(device, "class_name", "")
+    if class_name != "SimplerDevice":
+        return {
+            "error": "Device at [" + str(track_index) + "][" + str(device_index) + "] is "
+                     + class_name + ", not Simpler",
+            "code": "INVALID_PARAM",
+        }
+
+    try:
+        device.replace_sample(file_path)
+    except Exception as exc:
+        return {
+            "error": "SimplerDevice.replace_sample failed: " + str(exc),
+            "code": "INTERNAL",
+        }
+
+    return {
+        "sample_loaded": True,
+        "track_index": track_index,
+        "device_index": device_index,
+        "method": "native_12_4",
+        "live_version": version_string(),
+    }

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.dreamrec/livepilot",
-  "description": "402-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
+  "description": "403-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
   "repository": {
     "url": "https://github.com/dreamrec/LivePilot",
     "source": "github"
   },
-  "version": "1.14.0",
+  "version": "1.15.0-beta",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.14.0",
+      "version": "1.15.0-beta",
       "transport": {
         "type": "stdio"
       }