livepilot 1.23.2 → 1.23.4

package/mcp_server/mix_engine/state_builder.py

@@ -24,6 +24,47 @@ from .models import (
 # Roles considered "anchor" — should be prominent in the mix.
 _ANCHOR_ROLES = frozenset({"kick", "bass", "vocal", "lead", "drums"})
 
+# BUG-2026-04-26#5: track-name substrings that explicitly mark a track
+# as SUPPORT, even when its role-name maps to an anchor role. Without
+# this filter, a track named "VOX-GHOST" infers role=vocal and gets
+# auto-classified as an anchor, which then triggers `anchor_too_weak`
+# from the balance critic for any volume below the session average —
+# a guaranteed false positive on every ghost / wisp / texture layer.
+#
+# Substring-based (case-insensitive). Add new hints conservatively —
+# any new entry de-promotes a previously-anchor track silently.
+_NON_ANCHOR_NAME_HINTS = (
+    "ghost",   # VOX-GHOST, ghost-snare
+    "wisp",    # vocal-wisp
+    "fx",      # fx-bus, fx-rain
+    "atmos",   # ATMOS, atmosphere
+    "atmosphere",
+    "rain",    # rain-bed
+    "texture",
+    "drone",   # drone-bed
+    "shimmer",
+    "wash",    # reverb-wash, vocal-wash
+    "ambient", # ambient-pad
+    "sublayer",
+    "sub-layer",
+    "sub_layer",
+    "ghosting",
+    "back",    # back-vox, back-pad (background layers)
+)
+
+
+def _name_signals_non_anchor(track_name: str) -> bool:
+    """Return True when the track name marks this layer as SUPPORT.
+
+    Used in build_balance_state to exclude false anchors from the
+    balance critic's `anchor_too_weak` signal. See BUG-2026-04-26#5.
+    """
+    if not track_name:
+        return False
+    name_lower = track_name.lower()
+    return any(hint in name_lower for hint in _NON_ANCHOR_NAME_HINTS)
+
+
 # Frequency bands where masking is most problematic.
 _MASKING_BANDS = ("sub", "low", "low_mid", "mid", "high_mid", "presence", "high")
 
@@ -77,7 +118,9 @@ def build_balance_state(
         )
         states.append(ts)
 
-        if role in _ANCHOR_ROLES:
+        # BUG-2026-04-26#5: don't flag explicit support layers as anchors
+        # even when their role inference returns an anchor-class role.
+        if role in _ANCHOR_ROLES and not _name_signals_non_anchor(name):
             anchor_indices.append(idx)
 
         if not ts.mute:

package/mcp_server/runtime/capability_state.py

@@ -18,7 +18,21 @@ from typing import Optional
 
 @dataclass
 class CapabilityDomain:
-    """A single capability domain's runtime status."""
+    """A single capability domain's runtime status.
+
+    BUG-2026-04-26#4: ``available`` collapses two distinct conditions
+    into one bit (device installed AND data fresh). Callers that wanted
+    "is the analyzer .amxd loaded?" had no way to ask without conflating
+    it with "has the analyzer captured fresh data yet?". The
+    ``device_loaded`` field separates these concerns:
+
+      - ``device_loaded``: True when the optional .amxd / external
+        dependency exists. Independent of data freshness. Defaults to
+        ``available`` when the domain has no installable component
+        (session_access / memory / web / research).
+      - ``available``: True when the domain is ready for use end-to-end
+        (device_loaded AND fresh data, where applicable).
+    """
 
     name: str
     available: bool
@@ -26,10 +40,16 @@ class CapabilityDomain:
     freshness_ms: Optional[int] = None
     mode: str = "unavailable"
     reasons: list[str] = field(default_factory=list)
+    device_loaded: Optional[bool] = None
 
     def __post_init__(self) -> None:
         if not 0.0 <= self.confidence <= 1.0:
             raise ValueError(f"confidence must be 0.0–1.0, got {self.confidence}")
+        # Default device_loaded to mirror `available` for domains that
+        # don't have a separate installable component (memory, web, etc.).
+        # Domains that DO have one (analyzer, flucoma) override explicitly.
+        if self.device_loaded is None:
+            self.device_loaded = self.available
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -119,18 +139,27 @@ def build_capability_state(
     )
 
     # ── analyzer ────────────────────────────────────────────────────
+    # BUG-2026-04-26#4: ``available`` requires both device-loaded AND
+    # fresh data. The new ``device_loaded`` field exposes the .amxd
+    # presence separately, so "I just loaded the analyzer, why does
+    # capability_state still say offline?" can be answered correctly:
+    # device_loaded=True, available=False, reasons=['analyzer_warming_up'].
     analyzer_reasons: list[str] = []
     if not analyzer_ok:
         analyzer_reasons.append("analyzer_offline")
     elif not analyzer_fresh:
-        analyzer_reasons.append("analyzer_stale")
+        # Pre-fix this said `analyzer_stale` even immediately after the
+        # device finished loading. ``analyzer_warming_up`` is more
+        # accurate when the device is present but hasn't streamed a
+        # frame yet — distinguishes cold-start from genuine staleness.
+        analyzer_reasons.append("analyzer_warming_up")
     analyzer_available = analyzer_ok and analyzer_fresh
     if analyzer_available:
         analyzer_conf = 0.9
         analyzer_mode = "measured"
     elif analyzer_ok:
         analyzer_conf = 0.4
-        analyzer_mode = "stale"
+        analyzer_mode = "warming_up"
     else:
         analyzer_conf = 0.0
         analyzer_mode = "unavailable"
@@ -140,6 +169,7 @@ def build_capability_state(
         confidence=analyzer_conf,
         mode=analyzer_mode,
         reasons=analyzer_reasons,
+        device_loaded=analyzer_ok,
     )
 
     # ── memory ──────────────────────────────────────────────────────
@@ -182,6 +212,7 @@ def build_capability_state(
         confidence=0.9 if flucoma_ok else 0.0,
         mode="available" if flucoma_ok else "unavailable",
         reasons=flucoma_reasons,
+        device_loaded=flucoma_ok,
     )
 
     # ── research (composite) ────────────────────────────────────────

package/mcp_server/runtime/remote_commands.py

@@ -122,6 +122,13 @@ REMOTE_COMMANDS: frozenset[str] = frozenset({
     "ping",
     # Live 12.4+ native Simpler sample replacement (Collaborative tier)
     "replace_sample_native",
+    # v1.23.3: read Simpler.sample.file_path directly via Python LOM —
+    # primary path for classify_simpler_slices' auto-resolution. Beats
+    # the M4L bridge round-trip (which had a chunked-response correlation
+    # issue in live testing). The bridge case `get_simpler_file_path`
+    # remains as a forward-compat fallback in case Remote Script is
+    # somehow stale.
+    "get_simpler_file_path",
 })
 
 # M4L bridge commands — routed through TCP but handled by livepilot_bridge.js
@@ -130,6 +137,9 @@ BRIDGE_COMMANDS: frozenset[str] = frozenset({
     "get_params", "get_hidden_params", "get_auto_state", "walk_rack",
     "get_chains_deep", "get_track_cpu", "get_selected", "get_key",
     "get_clip_file_path", "replace_simpler_sample", "get_simpler_slices",
+    "get_simpler_file_path",  # v1.23.3 — closes the v1.12 follow-up that
+                              # left classify_simpler_slices unable to
+                              # auto-resolve the Simpler's sample path
     "crop_simpler", "reverse_simpler", "warp_simpler",
     "get_warp_markers", "add_warp_marker", "move_warp_marker",
     "remove_warp_marker", "capture_audio", "capture_stop",

package/mcp_server/server.py

@@ -307,6 +307,7 @@ from .sample_engine import tools as sample_engine_tools        # noqa: F401, E40
 from .atlas import tools as atlas_tools                        # noqa: F401, E402
 from .composer import tools as composer_tools                  # noqa: F401, E402
 from .synthesis_brain import tools as synthesis_brain_tools    # noqa: F401, E402
+from .user_corpus import tools as user_corpus_tools            # noqa: F401, E402
 from .tools import diagnostics   # noqa: F401, E402
 from .tools import miditool       # noqa: F401, E402
 
@@ -425,6 +426,26 @@ def _get_all_tools():
     return []
 
 
+def _read_expected_tool_count() -> int | None:
+    """Read the expected tool count from tests/test_tools_contract.py."""
+    import re
+    from pathlib import Path
+    try:
+        contract_path = (
+            Path(__file__).resolve().parents[1]
+            / "tests" / "test_tools_contract.py"
+        )
+        if not contract_path.exists():
+            return None
+        match = re.search(
+            r"assert len\(tools\) == (\d+)",
+            contract_path.read_text(encoding="utf-8"),
+        )
+        return int(match.group(1)) if match else None
+    except Exception:  # noqa: BLE001 — must not block startup
+        return None
+
+
 def _assert_tool_registry_accessible() -> None:
     """Loudly fail startup if the FastMCP registry probe returns nothing.
 
@@ -434,31 +455,15 @@ def _assert_tool_registry_accessible() -> None:
     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.
+    Note: only the "registry accessible at all" guard runs at module load.
+    The exact-count check moved to ``_assert_expected_tool_count()`` and
+    runs from main() — at module-load time, circular imports between
+    server.py and tool modules can leave the count temporarily under-
+    reported (a tool module being imported directly by a test or another
+    consumer triggers server.py's self-test before the importing module's
+    own ``@mcp.tool()`` decorators have fired). See BUG fix in v1.23.4.
     """
-    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.
@@ -470,7 +475,19 @@ def _assert_tool_registry_accessible() -> None:
             "(fastmcp>=3.0.0,<3.3.0) matches the installed version.",
             file=sys.stderr,
         )
-        return
+
+
+def _assert_expected_tool_count() -> None:
+    """Verify the registered tool count matches the contract.
+
+    Run from ``main()`` after all tool-module imports have completed. Avoids
+    the false-positive that fires when a tool module is imported directly
+    (which triggers server.py's self-test mid-import, before the importer's
+    own decorators have run).
+    """
+    import sys
+    expected = _read_expected_tool_count()
+    actual = len(_get_all_tools())
     if expected is not None and actual != expected:
         print(
             f"LivePilot: STARTUP SELF-TEST WARNING — _get_all_tools() "
@@ -528,6 +545,10 @@ except Exception as e:
 
 def main():
     """Run the MCP server over stdio."""
+    # Verify tool count matches the contract — runs here (not at module load)
+    # so all tool-module imports have completed regardless of the import path
+    # that brought server.py in. See _assert_tool_registry_accessible() docstring.
+    _assert_expected_tool_count()
     mcp.run(transport="stdio")
 
 if __name__ == "__main__":

package/mcp_server/tools/agent_os.py

@@ -231,20 +231,26 @@ def build_world_model(ctx: Context) -> dict:
 @mcp.tool()
 def evaluate_move(
     ctx: Context,
-    goal_vector: dict | str,
-    before_snapshot: dict | str,
-    after_snapshot: dict | str,
+    goal_vector: Optional[dict | str] = None,
+    before_snapshot: Optional[dict | str] = None,
+    after_snapshot: Optional[dict | str] = None,
+    description: Optional[str] = None,
 ) -> dict:
     """Evaluate whether a production move improved the mix toward the goal.
 
-    Takes before/after sonic snapshots and the active GoalVector.
-    Returns a score and keep/undo recommendation.
+    Two call modes:
+
+    **Structured** (full numeric scoring): supply goal_vector + before_snapshot
+    + after_snapshot. Snapshots must contain spectrum (9-band dict sub_low → air)
+    + rms + peak — capture via get_master_spectrum + get_master_rms before and
+    after the move. Returns a numeric score and keep/undo recommendation.
 
-    Snapshots should contain: spectrum (9-band dict sub_low → air, or
-    8-band from pre-v1.16 .amxd builds), rms, peak. Get these from
-    get_master_spectrum + get_master_rms before and after making changes.
+    **Description-only** (quick log, no snapshots needed): supply only
+    ``description``. Returns {evaluated: false, logged: true} — move is recorded
+    as a session event but no numeric score is computed. Useful for mid-session
+    bookkeeping when you haven't pre-captured snapshots.
 
-    Hard rules enforce undo when:
+    Hard rules (structured mode only) enforce undo when:
     - No measurable improvement (delta <= 0)
     - Protected dimension dropped below its threshold or by > 0.15
     - Total score < 0.40
@@ -255,6 +261,24 @@ def evaluate_move(
     Returns consecutive_undo_hint=true when keep_change=false — the agent
     should track consecutive undos and switch to observe mode after 3.
     """
+    # Description-only (quick-log) mode — no snapshots available
+    if goal_vector is None and before_snapshot is None and after_snapshot is None:
+        if description:
+            return {
+                "evaluated": False,
+                "logged": True,
+                "description": description,
+                "note": (
+                    "No snapshots supplied — move logged but not scored. "
+                    "For numeric evaluation capture get_master_spectrum + "
+                    "get_master_rms before and after the move."
+                ),
+            }
+        raise ValueError(
+            "Provide either goal_vector + before_snapshot + after_snapshot "
+            "for full evaluation, or description for quick logging."
+        )
+
     gv_dict = _parse_json_param(goal_vector, "goal_vector")
     before = _parse_json_param(before_snapshot, "before_snapshot")
     after = _parse_json_param(after_snapshot, "after_snapshot")

package/mcp_server/tools/analyzer.py

@@ -1018,10 +1018,11 @@ async def classify_simpler_slices(
 
     Parameters:
       track_index, device_index: the Simpler to analyze
-      file_path: (optional) explicit WAV path. If omitted, attempts
-        lookup via the bridge. Bridge-native resolution is limited in
-        v1.11 — when the sample lives in the Core Library, pass the
-        absolute path explicitly.
+      file_path: (optional) explicit WAV path. If omitted, the bridge
+        resolves it automatically via ``get_simpler_file_path``
+        (v1.23.3+). Pass explicitly only when running against an .amxd
+        freeze that predates the case (returns the bridge error string
+        in that case so the caller knows to re-freeze).
 
     Returns: dict with ``slices`` list. Each slice entry has:
       index, frame, seconds, midi_pitch (36+index), label, peak, rms,
@@ -1045,25 +1046,54 @@ async def classify_simpler_slices(
     if enriched is None:
         return {"error": "Bridge returned no slice data"}
 
-    # 2. Resolve file path
+    # 2. Resolve file path via Remote Script TCP path (v1.23.3+ — closes
+    # the v1.12 follow-up). Reads ``device.sample.file_path`` directly
+    # via Python LOM, more reliable than the M4L bridge UDP round-trip
+    # (which surfaced a chunked-response correlation issue under live
+    # testing). The bridge case `get_simpler_file_path` is still
+    # registered as a forward-compat fallback for environments where
+    # Remote Script is unavailable.
     wav_path = file_path
+    resolve_error: str | None = None
     if not wav_path:
-        try:
-            file_info = await bridge.send_command(
-                "get_simpler_file_path", track_index, device_index
-            )
-            if isinstance(file_info, dict):
-                wav_path = file_info.get("file_path")
-        except Exception:  # noqa: BLE001 — bridge command may not exist yet
-            wav_path = None
+        ableton = ctx.request_context.lifespan_context.get("ableton")
+        if ableton is not None:
+            try:
+                rs_resp = ableton.send_command(
+                    "get_simpler_file_path",
+                    {"track_index": track_index, "device_index": device_index},
+                )
+                if isinstance(rs_resp, dict):
+                    wav_path = rs_resp.get("file_path")
+                    resolve_error = rs_resp.get("error")
+            except Exception as exc:  # noqa: BLE001
+                resolve_error = f"remote_script unreachable: {exc}"
+                wav_path = None
+        else:
+            resolve_error = "no ableton TCP connection"
+
+        # Fallback: try the M4L bridge if Remote Script didn't yield a path.
+        # Useful if a stale Remote Script install lacks the new handler
+        # (the user can call reload_handlers to refresh without restart).
+        if not wav_path:
+            try:
+                bridge_resp = await bridge.send_command(
+                    "get_simpler_file_path", track_index, device_index
+                )
+                if isinstance(bridge_resp, dict):
+                    bridge_path = bridge_resp.get("file_path")
+                    if bridge_path:
+                        wav_path = bridge_path
+                        resolve_error = None
+            except Exception:  # noqa: BLE001 — defensive
+                pass
 
     if not wav_path:
         return {
             **enriched,
             "error": (
-                "No file_path available — pass file_path= explicitly. "
-                "Bridge-based lookup for Simpler sample paths is a v1.12 "
-                "follow-up."
+                resolve_error
+                or "No file_path available — pass file_path= explicitly."
             ),
         }
 
@@ -1651,16 +1681,44 @@ async def verify_all_devices_health(
         tname = t.get("name", f"Track {tid}")
         if tid is None:
             continue
-        is_audio = bool(t.get("is_audio_track") or t.get("type") == "audio")
+
+        # BUG-2026-04-26#1: detect audio tracks via has_midi_input /
+        # has_audio_input fields that get_session_info actually returns.
+        # Pre-fix the code looked for `is_audio_track` / `type` fields which
+        # don't exist on the session_info payload, so audio detection
+        # silently always evaluated False and ALL tracks fell through to
+        # the empty-tracks check below.
+        has_midi = bool(t.get("has_midi_input"))
+        has_audio = bool(t.get("has_audio_input"))
+        is_audio = has_audio and not has_midi
         if skip_audio_tracks and is_audio:
             skipped.append({"track_index": tid, "track_name": tname,
                             "reason": "audio_track_no_midi_input"})
             continue
-        devices = t.get("devices") or []
-        if skip_empty_tracks and not devices:
-            skipped.append({"track_index": tid, "track_name": tname,
-                            "reason": "no_devices_on_track"})
-            continue
+
+        # BUG-2026-04-26#1: get_session_info does NOT include per-track
+        # `devices` arrays — only get_track_info does. Pre-fix,
+        # `t.get("devices") or []` always returned [], so every MIDI track
+        # was flagged "no_devices_on_track" even when a Simpler / Operator
+        # / synth was loaded. Round-trip per track is the price of correct
+        # detection; the alternative (extending get_session_info to embed
+        # devices) would change a hot-path payload size for every caller.
+        if skip_empty_tracks:
+            try:
+                track_info = ableton.send_command(
+                    "get_track_info", {"track_index": tid},
+                )
+            except Exception:
+                track_info = None
+            devices = (
+                (track_info or {}).get("devices") or []
+                if isinstance(track_info, dict)
+                else []
+            )
+            if not devices:
+                skipped.append({"track_index": tid, "track_name": tname,
+                                "reason": "no_devices_on_track"})
+                continue
 
         # Run the per-track health check.
         result = await verify_device_health(
@@ -1718,7 +1776,10 @@ async def analyze_loudness_live(
     window_sec: float = 10.0,
     sample_interval_ms: int = 200,
 ) -> dict:
-    """Analyze the currently-playing master output's loudness over a window.
+    """Analyze the currently-playing master output's loudness over a window (LIVE).
+
+    Use this tool during a session — no rendered file needed.
+    For offline analysis of an exported audio file use analyze_loudness() instead.
 
     BUG-2026-04-22#8 fix — the offline `analyze_loudness` requires a
     rendered file. This tool samples the LivePilot analyzer's realtime

package/mcp_server/tools/browser.py

@@ -96,6 +96,21 @@ def get_browser_items(
     return result
 
 
+_BROWSER_PATH_ALIASES: dict[str, str] = {
+    "effects": "audio_effects",
+    "fx": "audio_effects",
+    "audio_fx": "audio_effects",
+    "audiofx": "audio_effects",
+    "midi_fx": "midi_effects",
+    "midifx": "midi_effects",
+}
+
+
+def _normalize_browser_path(path: str) -> str:
+    """Normalise common path aliases to their canonical browser category name."""
+    return _BROWSER_PATH_ALIASES.get(path.strip().lower(), path)
+
+
 @mcp.tool()
 def search_browser(
     ctx: Context,
@@ -114,7 +129,10 @@ def search_browser(
 
     path:         top-level category to search under. Valid categories:
                   instruments, audio_effects, midi_effects, sounds, drums,
-                  samples, packs, user_library, plugins, max_for_live, clips
+                  samples, packs, user_library, plugins, max_for_live, clips.
+                  Common aliases are normalised automatically:
+                  "effects" / "fx" → "audio_effects"
+                  "midi_fx"        → "midi_effects"
     name_filter:  case-insensitive substring filter on item name
     query:        alias for name_filter (accepts either)
     max_depth:    how deep to recurse into subfolders (default 8)
@@ -122,6 +140,7 @@ def search_browser(
     """
     if not path.strip():
         raise ValueError("Path cannot be empty")
+    path = _normalize_browser_path(path)
     if max_depth < 1:
         raise ValueError("max_depth must be >= 1")
     if max_results < 1:

package/mcp_server/tools/devices.py

@@ -252,24 +252,40 @@ def set_device_parameter(
 
     track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.
 
-    ⚠️ PARAMETER RANGES ARE NOT ALWAYS 0-1 (BUG-B4 / B9):
+    ⚠️ PARAMETER RANGES ARE NOT ALWAYS 0-1 (BUG-B4 / B9 / 2026-04-26#2):
       Ableton devices use MIXED units depending on the parameter. Always
       read the `value_string` in the response (and the `min`/`max` from
       get_device_parameters) before assuming 0-1 semantics:
 
-        - Auto Filter `Frequency`:      20-135 index (NOT normalized)
+        - Auto Filter `Frequency`:        20-135 index (NOT normalized)
         - Auto Filter Legacy `LFO Amount`: 0-30 absolute (displays as %)
-        - Auto Filter `Resonance`:      0-1.25 on legacy, 0-1 on AutoFilter2
-        - Auto Filter `Env. Modulation`: -127..+127 on legacy
-        - Compressor I, Dynamic Tube, Vocoder: pre-2010 units
-        - EQ Three `Frequency Hi/Lo`:    50Hz-15kHz absolute
-        - Wavetable `Osc 1 Pos`:         0-1 normalized ✓
+        - Auto Filter `Resonance`:        0-1.25 on legacy, 0-1 on AutoFilter2
+        - Auto Filter `Env. Modulation`:  -127..+127 on legacy
+        - Compressor I (legacy):          pre-2010 units (Threshold dB direct)
+        - **Compressor 2 (modern, default)**: 0-1 NORMALIZED.
+          `Threshold 0.85 ≈ 0 dB`, `Ratio 0.75 = 4:1`, `Release 0.16 = 30 ms`.
+          Setting Threshold to a dB value like -22 will fail. Compute
+          normalized: `(dB + 50) / 50` for typical dB→0-1 mapping, OR
+          read the param's value_string after a probe write.
+        - **Saturator** `Drive`, `Output`, `Threshold`, `Color *`: 0-1
+          NORMALIZED (Drive 0.5 ≈ 0 dB, Drive 0.6 ≈ +7 dB).
+        - Dynamic Tube, Vocoder:          pre-2010 units
+        - EQ Three `Frequency Hi/Lo`:     50Hz-15kHz absolute
+        - Wavetable `Osc 1 Pos`:          0-1 normalized ✓
         - Drift / Analog / Operator macros: 0-1 normalized ✓
+        - Pedal `Output`:                 -20..+20 dB direct
+        - Pedal `Bass / Mid / Treble`:    -1..+1 direct
 
       The `value_string` field in the response is the SOURCE OF TRUTH
       for what the user sees. Automation recipes that assume 0-1 will
       clamp on legacy devices. When in doubt, call
       get_device_parameters first to inspect min/max/is_quantized.
+
+    Error enrichment (BUG-2026-04-26#2): if the Remote Script rejects
+    the value as out-of-range, this wrapper fetches the parameter's
+    actual min/max/value_string and re-raises with that context inline.
+    Saves a follow-up get_device_parameters round-trip in the agent
+    loop after every miss.
     """
     _validate_track_index(track_index)
     _validate_device_index(device_index)
@@ -286,7 +302,52 @@ def set_device_parameter(
         params["parameter_name"] = parameter_name
     if parameter_index is not None:
         params["parameter_index"] = parameter_index
-    return _get_ableton(ctx).send_command("set_device_parameter", params)
+    try:
+        return _get_ableton(ctx).send_command("set_device_parameter", params)
+    except Exception as exc:
+        # BUG-2026-04-26#2: enrich out-of-range errors with the actual
+        # min/max/value_string from get_device_parameters so the caller
+        # doesn't need a follow-up probe to learn the unit semantics.
+        # Best-effort — if the enrichment fetch itself fails, re-raise
+        # the original exception untouched.
+        msg = str(exc)
+        looks_like_range_error = (
+            "Invalid value" in msg
+            or "STATE_ERROR" in msg
+            or "out of range" in msg.lower()
+        )
+        if not looks_like_range_error:
+            raise
+        try:
+            param_info = _get_ableton(ctx).send_command(
+                "get_device_parameters",
+                {"track_index": track_index, "device_index": device_index},
+            )
+        except Exception:
+            raise exc
+        params_list = (param_info or {}).get("parameters") if isinstance(param_info, dict) else None
+        if not isinstance(params_list, list):
+            raise exc
+        target = None
+        for p in params_list:
+            if not isinstance(p, dict):
+                continue
+            if parameter_name is not None and p.get("name") == parameter_name:
+                target = p
+                break
+            if parameter_index is not None and p.get("index") == parameter_index:
+                target = p
+                break
+        if target is None:
+            raise exc
+        raise ValueError(
+            f"set_device_parameter rejected value={value} for "
+            f"'{target.get('name')}' (index={target.get('index')}). "
+            f"Accepts min={target.get('min')}, max={target.get('max')}, "
+            f"is_quantized={target.get('is_quantized')}. "
+            f"Current value={target.get('value')} ({target.get('value_string')!r}). "
+            f"Original error: {exc}"
+        ) from exc
 
 
 def _normalize_batch_entry(entry: dict) -> dict:
@@ -428,15 +489,18 @@ def batch_set_parameters(
     ctx: Context,
     track_index: int,
     device_index: int,
-    parameters: Any,
+    parameters: Any = None,
+    operations: Any = None,
 ) -> dict:
     """Set multiple device parameters in one call.
 
-    parameters: JSON array of objects. Each entry uses exactly one of:
+    parameters (or operations): JSON array of objects. Each entry uses exactly one of:
       - {"parameter_index": N, "value": V}        (preferred, aligned with set_device_parameter)
       - {"parameter_name": "Dry/Wet", "value": V} (preferred)
       - {"name_or_index": X, "value": V}          (legacy, still accepted)
 
+    ``operations`` is accepted as an alias for ``parameters`` (either works).
+
     track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.
 
     Response (v1.20.2+): the dict now includes a ``snapped_params`` list
@@ -449,7 +513,10 @@ def batch_set_parameters(
     """
     _validate_track_index(track_index)
     _validate_device_index(device_index)
-    parameters_list = _ensure_list(parameters)
+    effective = parameters if parameters is not None else operations
+    if effective is None:
+        raise ValueError("parameters (or operations) list cannot be empty")
+    parameters_list = _ensure_list(effective)
     if not parameters_list:
         raise ValueError("parameters list cannot be empty")
     normalized = [_normalize_batch_entry(e) for e in parameters_list]