livepilot 1.9.19 → 1.9.20

package/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "dreamrec-LivePilot",
-  "description": "Agentic MCP production system for Ableton Live 12 — 236 tools, 32 domains",
+  "description": "Agentic MCP production system for Ableton Live 12 — 237 tools, 32 domains",
   "owner": {
     "name": "dreamrec",
     "email": "dreamrec@users.noreply.github.com"
@@ -9,8 +9,8 @@
   "plugins": [
     {
       "name": "livepilot",
-      "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
-      "version": "1.9.19",
+      "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+      "version": "1.9.20",
       "author": {
         "name": "Pilot Studio"
       },

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.9.20 — Deep Production Test Pass (April 2026)
+
+### New Tool
+- **feat(analyzer):** `reconnect_bridge` — rebind UDP 9880 mid-session after port conflict clears, without restarting the MCP server
+
+### Bug Fixes
+- **fix(arrangement):** `set_arrangement_automation` now returns `STATE_ERROR` (not `INVALID_PARAM`) with clear workaround suggestions for the known Live API limitation
+- **fix(router):** added `RuntimeError` → `STATE_ERROR` mapping so state-related errors don't masquerade as parameter validation failures
+- **fix(browser):** `load_browser_item` now accepts negative track_index (-1/-2 for returns, -1000 for master) — was incorrectly rejected by MCP-side validator
+- **fix(tracks):** `set_track_name` on return tracks strips auto-prefix letter to prevent doubling (e.g. "C-Resonators" stays as-is, not "C-C-Resonators")
+- **fix(theory):** `suggest_next_chord` now uses mode-aware progression maps — separate major/minor chord tables for common_practice, jazz, modal, and pop styles
+- **fix(research):** `research_technique` now searches instruments, audio_effects, AND drums categories (was instruments-only); deep scope notes that web search is agent-layer responsibility
+- **fix(server):** improved port competition error messages — directs users to `reconnect_bridge` tool instead of requiring server restart
+- **fix(analyzer):** M4L Analyzer User Library copy synced to latest version (presentation mode enabled, bridge JS updated)
+
+### Documentation
+- **docs(skill):** added "Volume reset on scene fire" and "M4L Analyzer auto-load" to error handling protocol in livepilot-core skill
+- **docs(CLAUDE.md):** tool count updated from 236 to 237
+
 ## 1.9.19 — Theory Engine & Meters Fix Pass (April 2026)
 
 ### Bug Fixes

package/livepilot/.Codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "livepilot",
-  "version": "1.9.19",
-  "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "version": "1.9.20",
+  "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"
   }

package/livepilot/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "livepilot",
-  "version": "1.9.19",
-  "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "version": "1.9.20",
+  "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"
   }

package/livepilot/skills/livepilot-core/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: livepilot-core
-description: Core discipline for LivePilot — agentic production system for Ableton Live 12. 236 tools across 32 domains. This skill should be used whenever working with Ableton Live through MCP tools. Provides golden rules, tool speed tiers, error handling protocol, and pointers to domain and engine skills.
+description: Core discipline for LivePilot — agentic production system for Ableton Live 12. 237 tools across 32 domains. This skill should be used whenever working with Ableton Live through MCP tools. Provides golden rules, tool speed tiers, error handling protocol, and pointers to domain and engine skills.
 ---
 
 # LivePilot Core — Ableton Live 12
 
-Agentic production system for Ableton Live 12. 236 tools across 32 domains, three layers:
+Agentic production system for Ableton Live 12. 237 tools across 32 domains, three layers:
 
 - **Device Atlas** — 280+ instruments, 139 drum kits, 350+ impulse responses. Consult `references/device-atlas/` before loading any device. Never guess a device name.
 - **M4L Analyzer** — Real-time audio analysis on the master bus (8-band spectrum, RMS/peak, key detection). Optional — all core tools work without it.
@@ -54,6 +54,8 @@ Report ALL errors to the user immediately. Common failure modes:
 - **Empty Drum Rack** — bare rack = silence → always load a kit preset
 - **M4L bridge timeout** — device may be busy or removed → retry or skip analyzer features
 - **Connection timeout** — Ableton unresponsive → check if session is heavy
+- **Volume reset on scene fire** — Ableton restores mixer state when firing scenes. Always re-apply `set_track_volume`/`set_track_pan` after `fire_scene` if your mix settings differ from what was stored in the clips
+- **M4L Analyzer not connected** — if `get_master_spectrum` errors with "Analyzer not detected", auto-load it: `find_and_load_device(track_index=-1000, device_name="LivePilot_Analyzer")`. If it errors with "UDP bridge not connected", try `reconnect_bridge` first
 
 ## Technique Memory
 
@@ -91,7 +93,7 @@ Deep production knowledge in `references/`:
 
 | File | Content |
 |------|---------|
-| `references/overview.md` | All 236 tools with params and ranges |
+| `references/overview.md` | All 237 tools with params and ranges |
 | `references/device-atlas/` | 280+ device corpus with URIs and presets |
 | `references/midi-recipes.md` | Drum patterns, chord voicings, humanization |
 | `references/sound-design.md` | Synth recipes, device chain patterns |

package/livepilot/skills/livepilot-core/references/overview.md

@@ -1,6 +1,6 @@
-# LivePilot v1.9.19 — Architecture & Tool Reference
+# LivePilot v1.9.20 — Architecture & Tool Reference
 
-Agentic production system for Ableton Live 12. 236 tools across 32 domains. Device atlas (280+ devices), spectral perception (M4L analyzer), technique memory, automation intelligence (16 curve types, 15 recipes), music theory (Krumhansl-Schmuckler, species counterpoint), generative algorithms (Euclidean rhythm, tintinnabuli, phase shift, additive process), neo-Riemannian harmony (PRL transforms, Tonnetz), MIDI file I/O.
+Agentic production system for Ableton Live 12. 237 tools across 32 domains. Device atlas (280+ devices), spectral perception (M4L analyzer), technique memory, automation intelligence (16 curve types, 15 recipes), music theory (Krumhansl-Schmuckler, species counterpoint), generative algorithms (Euclidean rhythm, tintinnabuli, phase shift, additive process), neo-Riemannian harmony (PRL transforms, Tonnetz), MIDI file I/O.
 
 ## Architecture
 

package/m4l_device/livepilot_bridge.js

@@ -84,7 +84,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.9.19"});
+            send_response({"ok": true, "version": "1.9.20"});
             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.9.19"
+__version__ = "1.9.20"

package/mcp_server/server.py

@@ -58,27 +58,37 @@ async def lifespan(server):
         )
     except OSError:
         # Port 9880 already bound — another LivePilot instance is running.
-        # Do NOT kill the holder; degrade gracefully instead.
+        # Degrade gracefully. The reconnect_bridge tool can retry later
+        # if the other instance is stopped.
         import sys
         holder_info = _identify_port_holder(9880)
         print(
             "LivePilot: UDP port 9880 already in use%s — "
-            "analyzer/bridge tools will be unavailable. "
-            "Stop the other LivePilot instance to enable them."
+            "analyzer/bridge tools unavailable at startup. "
+            "Use the reconnect_bridge tool after stopping the other instance, "
+            "or restart this server."
             % (f" (PID {holder_info})" if holder_info else ""),
             file=sys.stderr,
         )
         transport = None
 
+    # Store transport + loop so tools can attempt reconnection mid-session
+    bridge_state = {
+        "transport": transport,
+        "loop": loop,
+        "receiver": receiver,
+    }
+
     try:
         yield {
             "ableton": ableton,
             "spectral": spectral,
             "m4l": m4l,
+            "_bridge_state": bridge_state,
         }
     finally:
-        if transport:
-            transport.close()
+        if bridge_state["transport"]:
+            bridge_state["transport"].close()
         m4l.close()
         ableton.disconnect()
 

package/mcp_server/tools/analyzer.py

@@ -77,6 +77,42 @@ def _require_analyzer(cache) -> None:
         )
 
 
+@mcp.tool()
+async def reconnect_bridge(ctx: Context) -> dict:
+    """Attempt to reconnect the M4L UDP bridge (port 9880).
+
+    Use this when the bridge was unavailable at server startup (port
+    conflict) but is now free. Binds the UDP listener so spectral
+    analysis and bridge commands become available without restarting
+    the MCP server.
+    """
+    import asyncio
+
+    bridge_state = ctx.lifespan_context.get("_bridge_state")
+    if not bridge_state:
+        return {"error": "Bridge state not available — restart the MCP server"}
+
+    if bridge_state["transport"] is not None:
+        return {"ok": True, "message": "Bridge already connected on UDP 9880"}
+
+    loop = bridge_state["loop"]
+    receiver = bridge_state["receiver"]
+    try:
+        transport, _ = await loop.create_datagram_endpoint(
+            lambda: receiver,
+            local_addr=('127.0.0.1', 9880),
+        )
+        bridge_state["transport"] = transport
+        return {"ok": True, "message": "Bridge reconnected on UDP 9880"}
+    except OSError:
+        holder = _identify_port_holder(9880)
+        return {
+            "ok": False,
+            "error": f"UDP port 9880 still in use{f' (PID {holder})' if holder else ''}. "
+                     "Close the other LivePilot instance first.",
+        }
+
+
 @mcp.tool()
 def get_master_spectrum(ctx: Context) -> dict:
     """Get 8-band frequency analysis of the master bus.

package/mcp_server/tools/browser.py

@@ -18,9 +18,16 @@ def _get_ableton(ctx: Context):
 
 
 def _validate_track_index(track_index: int):
-    """Validate track index. Must be >= 0 for regular tracks."""
-    if track_index < 0:
-        raise ValueError("track_index must be >= 0")
+    """Validate track index.
+
+    0+ for regular tracks, -1/-2/... for return tracks (A/B/...),
+    -1000 for master track.
+    """
+    if track_index < 0 and track_index != -1000 and track_index < -20:
+        raise ValueError(
+            "track_index must be >= 0 for regular tracks, "
+            "-1/-2/... for return tracks, or -1000 for master"
+        )
 
 
 @mcp.tool()

package/mcp_server/tools/research.py

@@ -53,18 +53,21 @@ def research_technique(
     # 1. Analyze query to predict relevant devices
     query_info = research_engine.analyze_query(query)
 
-    # 2. Search device atlas for relevant devices (Fix 2: correct params)
+    # 2. Search device atlas for relevant devices across all categories
     device_atlas_results = []
     for device_name in query_info.get("likely_devices", [])[:5]:
-        try:
-            ref = ableton.send_command("search_browser", {
-                "path": "instruments",
-                "name_filter": device_name,
-            })
-            if ref and not ref.get("error"):
-                device_atlas_results.append(ref)
-        except Exception:
-            pass
+        for search_path in ("instruments", "audio_effects", "drums"):
+            try:
+                ref = ableton.send_command("search_browser", {
+                    "path": search_path,
+                    "name_filter": device_name,
+                    "max_results": 5,
+                })
+                if ref and not ref.get("error") and ref.get("count", 0) > 0:
+                    device_atlas_results.append(ref)
+                    break  # Found in this category, skip others
+            except Exception:
+                pass
 
     # 3. Search memory for related techniques (direct TechniqueStore)
     memory_results = []
@@ -88,14 +91,21 @@ def research_technique(
             query, device_atlas_results, memory_results,
         )
     else:
-        # Deep research — try to get web results
-        # Note: web search requires external integration (graceful degradation)
+        # Deep research — web search is delegated to the agent (LLM) layer.
+        # The MCP server cannot perform web searches directly. When scope
+        # is "deep", we still return device atlas + memory results and flag
+        # that the agent should supplement with its own web search.
         result = research_engine.deep_research(
             query,
-            web_results=[],  # Web search injected by agent if available
+            web_results=[],  # Agent supplements with WebSearch tool
             device_atlas_results=device_atlas_results,
             memory_results=memory_results,
         )
+        # Flag to the caller that web results should be sourced externally
+        result.web_search_note = (
+            "Deep scope requested but web search is handled by the agent layer. "
+            "Use WebSearch or web browsing tools to supplement these device atlas findings."
+        )
 
     return result.to_dict()
 

package/mcp_server/tools/theory.py

@@ -161,8 +161,9 @@ def suggest_next_chord(
     last_rn = engine.roman_numeral(last_group["pitch_classes"], tonic, mode)
     last_figure = last_rn["figure"]
 
-    # Progression maps by style
-    _progressions = {
+    # Progression maps by style — separate major/minor variants where needed.
+    # Minor key maps use lowercase i for tonic and scale-derived numerals.
+    _progressions_major = {
         "common_practice": {
             "I": ["IV", "V", "vi", "ii"],
             "ii": ["V", "vii\u00b0", "IV"],
@@ -173,10 +174,10 @@ def suggest_next_chord(
             "vii\u00b0": ["I", "iii"],
         },
         "jazz": {
-            "I": ["IV7", "ii7", "vi7", "bVII7"],
-            "ii7": ["V7", "bII7"],
-            "IV7": ["V7", "#ivo7", "bVII7"],
-            "V7": ["I", "vi", "bVI"],
+            "I": ["IV7", "ii7", "vi7", "V7"],
+            "ii7": ["V7", "IV7"],
+            "IV7": ["V7", "I", "ii7"],
+            "V7": ["I", "vi", "IV"],
             "vi7": ["ii7", "IV7"],
         },
         "modal": {
@@ -194,8 +195,47 @@ def suggest_next_chord(
             "vi": ["IV", "V", "I"],
         },
     }
+    _progressions_minor = {
+        "common_practice": {
+            "i": ["iv", "v", "VI", "III"],
+            "ii\u00b0": ["v", "VII", "iv"],
+            "III": ["VI", "iv", "VII"],
+            "iv": ["v", "i", "VII"],
+            "v": ["i", "VI", "iv"],
+            "VI": ["iv", "ii\u00b0", "v", "VII"],
+            "VII": ["III", "i"],
+        },
+        "jazz": {
+            "i": ["iv7", "v", "VI7", "VII7"],
+            "i7": ["iv7", "v", "VI7", "VII7"],
+            "ii\u00b07": ["v", "VII7"],
+            "iv7": ["VII7", "v", "i"],
+            "v": ["i", "VI", "iv"],
+            "VI7": ["ii\u00b07", "iv7", "VII7"],
+            "VImaj7": ["ii\u00b07", "iv7", "VII7"],
+            "VII7": ["III", "i", "VI"],
+        },
+        "modal": {
+            "i": ["VII", "iv", "v", "III"],
+            "iv": ["i", "VII", "v"],
+            "v": ["VII", "iv", "i"],
+            "VII": ["i", "iv", "v"],
+            "III": ["iv", "VII"],
+        },
+        "pop": {
+            "i": ["VII", "VI", "iv"],
+            "iv": ["i", "VII", "VI"],
+            "v": ["i", "VI", "iv"],
+            "VI": ["iv", "VII", "i"],
+            "VII": ["i", "VI", "III"],
+        },
+    }
 
-    style_map = _progressions.get(style, _progressions["common_practice"])
+    # Select the right map based on mode
+    is_minor = mode in ("minor", "dorian", "phrygian", "aeolian",
+                        "phrygian_dominant")
+    prog_set = _progressions_minor if is_minor else _progressions_major
+    style_map = prog_set.get(style, prog_set.get("common_practice", {}))
 
     # Match the last chord to the closest key in the map
     candidates = style_map.get(last_figure)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.9.19",
+  "version": "1.9.20",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 236 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "description": "Agentic production system for Ableton Live 12 — 237 tools, 32 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": "Pilot Studio",
   "license": "MIT",
   "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.9.19"
+__version__ = "1.9.20"
 
 from _Framework.ControlSurface import ControlSurface
 from .server import LivePilotServer

package/remote_script/LivePilot/arrangement.py

@@ -543,13 +543,15 @@ def set_arrangement_automation(song, params):
     # arming the track and playing back with parameter changes,
     # or use session-clip automation (set_clip_automation) and then
     # record the session performance to arrangement.
-    raise ValueError(
+    raise RuntimeError(
         "Cannot create automation envelope for parameter '%s' on this "
-        "arrangement clip. This is a known Live API limitation for "
-        "programmatically-created arrangement clips. Workarounds: "
-        "(1) use set_clip_automation on a session clip instead, "
-        "(2) record automation by arming the track during playback, "
-        "or (3) use the M4L bridge for deeper LOM envelope access."
+        "arrangement clip. Direct envelope access is not supported for "
+        "programmatically-created arrangement clips (known Live API limitation). "
+        "Workarounds: "
+        "(1) use set_clip_automation on a session clip instead, then fire "
+        "the scene and record to arrangement; "
+        "(2) use arrangement-level volume/pan fades by creating separate "
+        "clips at different volumes for each section."
         % parameter.name
     )
 

package/remote_script/LivePilot/router.py

@@ -11,6 +11,7 @@ from .utils import (
     INDEX_ERROR,
     INVALID_PARAM,
     NOT_FOUND,
+    STATE_ERROR,
     INTERNAL,
 )
 
@@ -92,5 +93,7 @@ def dispatch(song, command):
         return error_response(request_id, str(exc), INDEX_ERROR)
     except ValueError as exc:
         return error_response(request_id, str(exc), INVALID_PARAM)
+    except RuntimeError as exc:
+        return error_response(request_id, str(exc), STATE_ERROR)
     except Exception as exc:
         return error_response(request_id, str(exc), INTERNAL)

package/remote_script/LivePilot/tracks.py

@@ -193,10 +193,29 @@ def duplicate_track(song, params):
 
 @register("set_track_name")
 def set_track_name(song, params):
-    """Rename a track."""
+    """Rename a track.
+
+    For return tracks, Ableton auto-prefixes with a letter (A-, B-, C-).
+    If the requested name already starts with that prefix, strip it to
+    avoid doubling (e.g. "C-Resonators" stays as "C-Resonators" not
+    "C-C-Resonators").
+    """
     track_index = int(params["track_index"])
     track = get_track(song, track_index)
-    track.name = str(params["name"])
+    new_name = str(params["name"])
+
+    # For return tracks, strip auto-prefix from user's name if it matches
+    if track_index < 0 and track_index != -1000:
+        return_tracks = list(song.return_tracks)
+        ri = abs(track_index) - 1
+        if ri < len(return_tracks):
+            # Return tracks have letter prefixes: "A-", "B-", "C-", etc.
+            letter = chr(ord('A') + ri)
+            prefix = letter + "-"
+            if new_name.startswith(prefix):
+                new_name = new_name[len(prefix):]
+
+    track.name = new_name
     return {"index": track_index, "name": track.name}