livepilot 1.9.9 → 1.9.11

package/mcp_server/tools/devices.py

@@ -10,13 +10,16 @@ from typing import Any, Optional
 
 from fastmcp import Context
 
-from ..server import mcp
+from ..server import mcp, _identify_port_holder
 
 
 def _ensure_list(value: Any) -> list:
     """Parse JSON strings into lists. MCP clients may serialize list params as strings."""
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 
@@ -26,6 +29,153 @@ def _get_ableton(ctx: Context):
 
 
 MASTER_TRACK_INDEX = -1000
+_PLUGIN_CLASS_NAMES = {"PluginDevice", "AuPluginDevice"}
+_SAMPLE_DEPENDENT_DEVICE_NAMES = {
+    "idensity": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "tardigrain": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "koala sampler": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "burns audio granular": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "audiolayer": "Requires samples loaded inside the plugin UI before MIDI can produce sound.",
+    "segments": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+    "segments (instr)": "Requires source audio loaded inside the plugin UI before MIDI can produce sound.",
+}
+
+
+def _sample_dependency_reason(device_name: str) -> Optional[str]:
+    lowered = device_name.strip().lower()
+    for candidate, reason in _SAMPLE_DEPENDENT_DEVICE_NAMES.items():
+        if candidate in lowered:
+            return reason
+    return None
+
+
+def _annotate_device_info(result: dict) -> dict:
+    """Attach MCP-focused health hints to raw get_device_info results."""
+    if not isinstance(result, dict):
+        return result
+
+    class_name = str(result.get("class_name") or "")
+    device_name = str(result.get("name") or "")
+    parameter_count = int(result.get("parameter_count") or 0)
+    is_plugin = class_name in _PLUGIN_CLASS_NAMES
+
+    plugin_host_status = "not_plugin"
+    if is_plugin:
+        plugin_host_status = "host_visible" if parameter_count > 1 else "opaque_or_failed"
+
+    flags: list[str] = []
+    warnings: list[str] = []
+
+    sample_reason = _sample_dependency_reason(device_name)
+    if sample_reason:
+        flags.append("sample_dependent")
+        warnings.append(sample_reason)
+
+    if plugin_host_status == "opaque_or_failed":
+        flags.append("opaque_or_failed_plugin")
+        warnings.append(
+            "Ableton only sees %d host parameter(s) for this plugin. "
+            "If auditioning produces no audio, the plugin likely failed to initialize. "
+            "If audio is flowing, the plugin is usable but opaque to MCP sound design."
+            % parameter_count
+        )
+
+    annotated = dict(result)
+    annotated["is_plugin"] = is_plugin
+    annotated["plugin_host_status"] = plugin_host_status
+    annotated["health_flags"] = flags
+    annotated["mcp_sound_design_ready"] = len(flags) == 0
+    if warnings:
+        annotated["warnings"] = warnings
+    return annotated
+
+
+def _annotate_loaded_device_result(result: dict) -> dict:
+    """Attach preflight warnings to load results based on loaded device names."""
+    if not isinstance(result, dict):
+        return result
+
+    loaded_name = str(result.get("loaded") or "")
+    sample_reason = _sample_dependency_reason(loaded_name)
+    if not sample_reason:
+        return result
+
+    annotated = dict(result)
+    annotated["health_flags"] = ["sample_dependent"]
+    annotated["warnings"] = [sample_reason]
+    annotated["mcp_sound_design_ready"] = False
+    return annotated
+
+
+def _merge_unique(base: list[str], extra: list[str]) -> list[str]:
+    merged = list(base)
+    for item in extra:
+        if item not in merged:
+            merged.append(item)
+    return merged
+
+
+def _postflight_loaded_device(ctx: Context, result: dict) -> dict:
+    """Attach post-load health info by inspecting the newly loaded device."""
+    annotated = _annotate_loaded_device_result(result)
+    if not isinstance(annotated, dict):
+        return annotated
+
+    track_index = annotated.get("track_index")
+    loaded_name = str(annotated.get("loaded") or "")
+    if track_index is None or not loaded_name:
+        return annotated
+
+    try:
+        track_info = _get_ableton(ctx).send_command("get_track_info", {
+            "track_index": int(track_index),
+        })
+    except Exception:
+        return annotated
+
+    devices = track_info.get("devices", []) if isinstance(track_info, dict) else []
+    if not isinstance(devices, list) or not devices:
+        return annotated
+
+    match = None
+    for device in reversed(devices):
+        if str(device.get("name") or "") == loaded_name:
+            match = device
+            break
+    if match is None:
+        match = devices[-1]
+
+    device_info = _annotate_device_info({
+        "name": match.get("name"),
+        "class_name": match.get("class_name"),
+        "is_active": match.get("is_active"),
+        "parameter_count": len(match.get("parameters", [])),
+    })
+
+    merged = dict(annotated)
+    merged["device_index"] = match.get("index")
+    merged["class_name"] = device_info.get("class_name")
+    merged["parameter_count"] = device_info.get("parameter_count")
+    merged["is_plugin"] = device_info.get("is_plugin")
+    merged["plugin_host_status"] = device_info.get("plugin_host_status")
+    merged["mcp_sound_design_ready"] = (
+        merged.get("mcp_sound_design_ready", True)
+        and device_info.get("mcp_sound_design_ready", True)
+    )
+
+    merged["health_flags"] = _merge_unique(
+        annotated.get("health_flags", []),
+        device_info.get("health_flags", []),
+    )
+
+    warnings = _merge_unique(
+        annotated.get("warnings", []),
+        device_info.get("warnings", []),
+    )
+    if warnings:
+        merged["warnings"] = warnings
+
+    return merged
 
 
 def _validate_track_index(track_index: int):
@@ -54,10 +204,11 @@ def get_device_info(ctx: Context, track_index: int, device_index: int) -> dict:
     track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
     _validate_track_index(track_index)
     _validate_device_index(device_index)
-    return _get_ableton(ctx).send_command("get_device_info", {
+    result = _get_ableton(ctx).send_command("get_device_info", {
         "track_index": track_index,
         "device_index": device_index,
     })
+    return _annotate_device_info(result)
 
 
 @mcp.tool()
@@ -157,10 +308,11 @@ def load_device_by_uri(ctx: Context, track_index: int, uri: str) -> dict:
     _validate_track_index(track_index)
     if not uri.strip():
         raise ValueError("URI cannot be empty")
-    return _get_ableton(ctx).send_command("load_device_by_uri", {
+    result = _get_ableton(ctx).send_command("load_device_by_uri", {
         "track_index": track_index,
         "uri": uri,
     })
+    return _postflight_loaded_device(ctx, result)
 
 
 @mcp.tool()
@@ -170,10 +322,11 @@ def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> di
     _validate_track_index(track_index)
     if not device_name.strip():
         raise ValueError("device_name cannot be empty")
-    return _get_ableton(ctx).send_command("find_and_load_device", {
+    result = _get_ableton(ctx).send_command("find_and_load_device", {
         "track_index": track_index,
         "device_name": device_name,
     })
+    return _postflight_loaded_device(ctx, result)
 
 
 @mcp.tool()
@@ -263,7 +416,7 @@ def _get_m4l(ctx: Context):
     """Get M4LBridge from lifespan context."""
     bridge = ctx.lifespan_context.get("m4l")
     if not bridge:
-        raise RuntimeError("M4L bridge not initialized")
+        raise ValueError("M4L bridge not initialized — restart the MCP server")
     return bridge
 
 
@@ -271,12 +424,48 @@ def _get_spectral(ctx: Context):
     """Get SpectralCache from lifespan context."""
     cache = ctx.lifespan_context.get("spectral")
     if not cache:
-        raise RuntimeError("Spectral cache not initialized")
+        raise ValueError("Spectral cache not initialized — restart the MCP server")
+    # Keep the active request context attached so analyzer error paths can
+    # distinguish "device missing" from "bridge disconnected".
+    setattr(cache, "_livepilot_ctx", ctx)
     return cache
 
 
 def _require_analyzer(cache) -> None:
     if not cache.is_connected:
+        ctx = getattr(cache, "_livepilot_ctx", None)
+        try:
+            track = (
+                ctx.lifespan_context["ableton"].send_command("get_master_track")
+                if ctx else {}
+            )
+        except Exception:
+            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."
@@ -302,7 +491,7 @@ async def get_plugin_parameters(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_plugin_params", track_index, device_index)
+    return await bridge.send_command("get_plugin_params", track_index, device_index, timeout=20.0)
 
 
 @mcp.tool()
@@ -326,7 +515,7 @@ async def map_plugin_parameter(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("map_plugin_param", track_index, device_index, parameter_index)
+    return await bridge.send_command("map_plugin_param", track_index, device_index, parameter_index, timeout=10.0)
 
 
 @mcp.tool()
@@ -346,4 +535,4 @@ async def get_plugin_presets(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_plugin_presets", track_index, device_index)
+    return await bridge.send_command("get_plugin_presets", track_index, device_index, timeout=15.0)

package/mcp_server/tools/generative.py

@@ -17,7 +17,10 @@ from . import _theory_engine as theory
 
 def _ensure_list(value: Any) -> list:
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 

package/mcp_server/tools/harmony.py

@@ -19,7 +19,10 @@ from . import _theory_engine as theory
 
 def _ensure_list(value: Any) -> list:
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 
@@ -168,8 +171,18 @@ def classify_progression(
     if len(chords) < 2:
         return {"error": "Need at least 2 chords to classify"}
 
+    # Normalize dict inputs like {"root": "F#", "quality": "minor"} to strings
+    normalized = []
+    for c in chords:
+        if isinstance(c, dict):
+            root = c.get("root", "")
+            quality = c.get("quality", "major")
+            normalized.append(f"{root} {quality}")
+        else:
+            normalized.append(str(c))
+
     try:
-        parsed = [harmony.parse_chord(c) for c in chords]
+        parsed = [harmony.parse_chord(c) for c in normalized]
     except ValueError as e:
         return {"error": str(e)}
 
@@ -198,7 +211,7 @@ def classify_progression(
         classification = names.get(clean, classification)
 
     return {
-        "chords": chords,
+        "chords": normalized,
         "transforms": transforms,
         "pattern": pattern,
         "classification": classification,

package/mcp_server/tools/notes.py

@@ -21,7 +21,10 @@ def _get_ableton(ctx: Context):
 def _ensure_list(value: Any) -> list:
     """Parse JSON strings into lists. MCP clients may serialize list params as strings."""
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 

package/mcp_server/tools/perception.py

@@ -34,11 +34,31 @@ _LOSSY_EXTS = {".mp3", ".m4a"}
 _MAX_FILE_SIZE = 500 * 1024 * 1024  # 500 MB
 
 
+def _normalize_audio_path(file_path: str) -> str:
+    """Convert Max-style HFS-ish paths into POSIX paths when possible."""
+    if len(file_path) >= 3 and file_path[1] == ":" and file_path[2] in ("/", "\\"):
+        return file_path
+
+    colon = file_path.find(":")
+    slash = file_path.find("/")
+    if colon <= 0 or (slash != -1 and colon > slash):
+        return file_path
+
+    rest = file_path[colon + 1:]
+    if ":" in rest:
+        rest = rest.replace(":", "/")
+    if not rest.startswith("/"):
+        rest = "/" + rest.lstrip("/\\")
+    return rest
+
+
 def _validate_audio(file_path: str, allow_mp3: bool = False) -> Optional[dict]:
     """Validate that a file exists, has a supported extension, and is < 500 MB.
 
     Returns None if valid, or an error dict if invalid.
     """
+    file_path = _normalize_audio_path(file_path)
+
     if not os.path.exists(file_path):
         return {"error": f"File not found: {file_path}", "code": "INVALID_PARAM"}
 
@@ -84,7 +104,8 @@ def analyze_loudness(
                 array (up to 100 points, mean-pooled).
 
     Returns:
-        On success: dict with integrated_lufs, true_peak_dbtp, rms_dbfs,
+        On success: dict with integrated_lufs, true_peak_dbtp (4x oversampled),
+        sample_peak_dbfs (raw sample peak, kept for backward compat), rms_dbfs,
         crest_factor_db, lra_lu, meets_streaming {spotify, apple, youtube, tidal},
         and optionally short_term_lufs.
         On error: {"error": ..., "code": ...}
@@ -97,6 +118,7 @@ def analyze_loudness(
         return {"error": "detail must be 'summary' or 'full'", "code": "INVALID_PARAM"}
 
     try:
+        file_path = _normalize_audio_path(file_path)
         return compute_loudness(file_path, detail=detail)
     except FileNotFoundError as exc:
         return {"error": str(exc), "code": "INVALID_PARAM"}
@@ -135,6 +157,7 @@ def analyze_spectrum_offline(
         return {"error": "hop_length must be between 1 and n_fft", "code": "INVALID_PARAM"}
 
     try:
+        file_path = _normalize_audio_path(file_path)
         return compute_spectral(file_path, n_fft=n_fft, hop_length=hop_length)
     except FileNotFoundError as exc:
         return {"error": str(exc), "code": "INVALID_PARAM"}
@@ -176,6 +199,8 @@ def compare_to_reference(
         return {"error": f"reference_path: {err['error']}", "code": err["code"]}
 
     try:
+        mix_path = _normalize_audio_path(mix_path)
+        reference_path = _normalize_audio_path(reference_path)
         return _compare(mix_path, reference_path, normalize=normalize)
     except FileNotFoundError as exc:
         return {"error": str(exc), "code": "INVALID_PARAM"}
@@ -207,6 +232,7 @@ def read_audio_metadata(
         return err
 
     try:
+        file_path = _normalize_audio_path(file_path)
         return _read_metadata(file_path)
     except FileNotFoundError as exc:
         return {"error": str(exc), "code": "INVALID_PARAM"}

package/mcp_server/tools/scenes.py

@@ -97,7 +97,10 @@ def set_scene_tempo(ctx: Context, scene_index: int, tempo: float) -> dict:
 
 def _ensure_list(value: Any) -> list:
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 

package/mcp_server/tools/theory.py

@@ -48,7 +48,12 @@ def _detect_or_parse_key(notes: list[dict], key_hint: str | None = None) -> dict
 
 def _key_display(key_info: dict) -> str:
     """Format key info as 'C major' string."""
-    return f"{key_info['tonic_name']} {key_info['mode']}"
+    return f"{key_info['tonic_name']} {key_info['mode'].replace('_', ' ')}"
+
+
+def _mode_display(mode: str) -> str:
+    """Format a canonical mode id for user-facing output."""
+    return mode.replace("_", " ")
 
 
 # -- Tool 1: analyze_harmony ------------------------------------------------
@@ -345,8 +350,9 @@ def identify_scale(
 ) -> dict:
     """Identify the scale/mode of a MIDI clip beyond basic major/minor.
 
-    Uses Krumhansl-Schmuckler algorithm with 7 mode profiles (major, minor,
-    dorian, phrygian, lydian, mixolydian, locrian).
+    Uses Krumhansl-Schmuckler-style profiles with 8 mode profiles (major,
+    minor, dorian, phrygian, lydian, mixolydian, locrian, and phrygian
+    dominant / Hijaz).
 
     Returns ranked key matches with confidence scores.
     """
@@ -357,17 +363,19 @@ def identify_scale(
     detected = engine.detect_key(notes, mode_detection=True)
 
     results = [{
-        "key": f"{detected['tonic_name']} {detected['mode']}",
+        "key": f"{detected['tonic_name']} {_mode_display(detected['mode'])}",
         "confidence": detected["confidence"],
-        "mode": detected["mode"],
+        "mode": _mode_display(detected["mode"]),
+        "mode_id": detected["mode"],
         "tonic": detected["tonic_name"],
     }]
 
     for alt in detected.get("alternatives", [])[:7]:
         results.append({
-            "key": f"{alt['tonic_name']} {alt['mode']}",
+            "key": f"{alt['tonic_name']} {_mode_display(alt['mode'])}",
             "confidence": alt["confidence"],
-            "mode": alt["mode"],
+            "mode": _mode_display(alt["mode"]),
+            "mode_id": alt["mode"],
             "tonic": alt["tonic_name"],
         })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.9.9",
+  "version": "1.9.11",
   "mcpName": "io.github.dreamrec/livepilot",
   "description": "Agentic production system for Ableton Live 12 — 178 tools, 17 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": "Pilot Studio",

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.9.9"
+__version__ = "1.9.11"
 
 from _Framework.ControlSurface import ControlSurface
 from .server import LivePilotServer

package/remote_script/LivePilot/arrangement.py

@@ -494,6 +494,10 @@ def set_arrangement_automation(song, params):
             "parameter_type must be 'device', 'volume', 'panning', or 'send'"
         )
 
+    # Clamp values to parameter range
+    p_min = float(parameter.min)
+    p_max = float(parameter.max)
+
     # Try direct envelope access on the arrangement clip
     envelope = clip.automation_envelope(parameter)
     if envelope is None:
@@ -509,7 +513,7 @@ def set_arrangement_automation(song, params):
             points_written = 0
             for pt in points:
                 time = float(pt["time"])
-                value = float(pt["value"])
+                value = max(p_min, min(p_max, float(pt["value"])))
                 duration = float(pt.get("duration", 0.125))
                 envelope.insert_step(time, duration, value)
                 points_written += 1
@@ -523,121 +527,14 @@ def set_arrangement_automation(song, params):
             "method": "direct",
         }
 
-    # Fallback: session-clip-then-duplicate workaround.
-    # Create a temporary session clip, write automation there,
-    # then duplicate to arrangement. Envelopes may survive the copy.
-    arr_start = clip.start_time
-    arr_length = clip.length
-
-    # Find an empty clip slot for the temporary clip
-    slots = list(track.clip_slots)
-    temp_slot_index = None
-    for si, slot in enumerate(slots):
-        if not slot.has_clip:
-            temp_slot_index = si
-            break
-
-    # If all clip slots are full, create a temporary scene to get an empty slot
-    created_temp_scene = False
-    if temp_slot_index is None:
-        song.create_scene(-1)  # append a new scene at the end
-        created_temp_scene = True
-        # Re-read slots — the new scene added one slot per track
-        slots = list(track.clip_slots)
-        temp_slot_index = len(slots) - 1
-
-    song.begin_undo_step()
-    try:
-        # Create temporary session clip
-        slot = slots[temp_slot_index]
-        slot.create_clip(arr_length)
-        temp_clip = slot.clip
-
-        # Write automation to the session clip
-        temp_envelope = temp_clip.automation_envelope(parameter)
-        if temp_envelope is None:
-            try:
-                temp_envelope = temp_clip.create_automation_envelope(parameter)
-            except (AttributeError, RuntimeError):
-                pass
-
-        if temp_envelope is None:
-            # Neither direct nor session clip approach works
-            slot.delete_clip()
-            if created_temp_scene:
-                song.delete_scene(len(list(song.scenes)) - 1)
-            raise ValueError(
-                "Cannot create automation envelope for parameter '%s' "
-                "(neither arrangement nor session clip supports it)"
-                % parameter.name
-            )
-
-        points_written = 0
-        for pt in points:
-            time = float(pt["time"])
-            value = float(pt["value"])
-            duration = float(pt.get("duration", 0.125))
-            temp_envelope.insert_step(time, duration, value)
-            points_written += 1
-
-        # Copy notes from original arrangement clip to the temp session clip
-        # so the replacement clip has the same musical content.
-        try:
-            orig_notes = clip.get_notes_extended(0, 128, 0.0, arr_length + 1.0)
-            import Live
-            note_specs = []
-            for note in orig_notes:
-                kwargs = dict(
-                    pitch=note.pitch,
-                    start_time=note.start_time,
-                    duration=note.duration,
-                    velocity=note.velocity,
-                    mute=note.mute,
-                )
-                # Preserve per-note expression data
-                if hasattr(note, 'probability') and note.probability is not None:
-                    kwargs['probability'] = note.probability
-                if hasattr(note, 'velocity_deviation') and note.velocity_deviation is not None:
-                    kwargs['velocity_deviation'] = note.velocity_deviation
-                if hasattr(note, 'release_velocity') and note.release_velocity is not None:
-                    kwargs['release_velocity'] = note.release_velocity
-                spec = Live.Clip.MidiNoteSpecification(**kwargs)
-                note_specs.append(spec)
-            if note_specs:
-                temp_clip.add_new_notes(tuple(note_specs))
-        except Exception:
-            pass  # Non-MIDI clips or errors — automation-only is still valid
-
-        # Place the session clip (with automation + notes) into arrangement.
-        # Do this BEFORE deleting the original — if placement fails, the
-        # original clip is preserved (no data loss on partial failure).
-        track.duplicate_clip_to_arrangement(temp_clip, arr_start)
-
-        # Placement succeeded — now safe to remove the original clip
-        # to avoid a second overlapping clip at the same position.
-        try:
-            clip.delete_clip()
-        except (AttributeError, RuntimeError):
-            # delete_clip may not exist on arrangement clips in all versions;
-            # in that case we accept the overlap as a known limitation.
-            pass
-
-        # Clean up the temporary session clip
-        slot.delete_clip()
-
-        # Clean up the temporary scene if we created one
-        if created_temp_scene:
-            song.delete_scene(len(list(song.scenes)) - 1)
-    finally:
-        song.end_undo_step()
-
-    return {
-        "track_index": track_index,
-        "clip_index": clip_index,
-        "parameter_name": parameter.name,
-        "points_written": points_written,
-        "method": "session_workaround",
-    }
+    # No fallback — direct envelope creation is the only safe approach.
+    # Session-clip duplication can silently create overlapping clips.
+    raise ValueError(
+        "Cannot create automation envelope for parameter '%s' on this "
+        "arrangement clip. Direct envelope access is not supported for "
+        "this parameter type or Live version."
+        % parameter.name
+    )
 
 
 @register("transpose_arrangement_notes")