livepilot 1.10.6 → 1.10.8

package/mcp_server/project_brain/automation_graph.py

@@ -11,8 +11,10 @@ from .models import AutomationGraph
 def build_automation_graph(
     track_infos: list[dict],
     sections: list[dict] | None = None,
+    clip_automation: list[dict] | None = None,
 ) -> AutomationGraph:
-    """Build an AutomationGraph by scanning track device info for automation.
+    """Build an AutomationGraph covering both device-parameter automation
+    hints and real clip envelopes (BUG-E2).
 
     Args:
         track_infos: list of per-track info dicts.  Each may contain:
@@ -20,18 +22,52 @@ def build_automation_graph(
             - name: track name
             - devices: [{name, class_name, parameters: [{name, value, is_automated, ...}]}]
         sections: optional list of section dicts (for density_by_section).
+        clip_automation: optional list of per-clip envelope descriptors:
+            [{section_id, track_index, track_name, clip_index,
+              parameter_name, parameter_type, device_name}].
+            This is the ground truth — `device.parameters[i].is_automated`
+            only reflects mapping state, not the presence of an envelope.
 
     Returns:
         AutomationGraph with automated_params and density_by_section.
     """
     graph = AutomationGraph()
 
-    if not track_infos:
+    if not track_infos and not clip_automation:
         return graph
 
-    automated_params = []
+    automated_params: list[dict] = []
+    # Track which (track_index, device_name, param_name) we've already seen
+    # so device-hint entries don't duplicate clip-envelope entries.
+    seen: set[tuple[int, str, str]] = set()
 
-    for track in track_infos:
+    # 1) Seed with real clip envelopes. These are the source of truth.
+    per_section_counts: dict[str, int] = {}
+    for env in clip_automation or []:
+        t_idx = int(env.get("track_index", 0))
+        dev = str(env.get("device_name") or env.get("parameter_type") or "")
+        name = str(env.get("parameter_name") or "")
+        key = (t_idx, dev, name)
+        if key in seen:
+            continue
+        seen.add(key)
+        automated_params.append({
+            "track_index": t_idx,
+            "track_name": env.get("track_name", ""),
+            "device_name": dev or None,
+            "param_name": name,
+            "parameter_type": env.get("parameter_type", ""),
+            "clip_index": env.get("clip_index"),
+            "section_id": env.get("section_id"),
+            "source": "clip_envelope",
+        })
+        sec = env.get("section_id")
+        if sec:
+            per_section_counts[sec] = per_section_counts.get(sec, 0) + 1
+
+    # 2) Add device-level hints (track-wide is_automated flags) that
+    # aren't already covered by an envelope entry.
+    for track in track_infos or []:
         t_idx = track.get("index", 0)
         t_name = track.get("name", "")
         devices = track.get("devices", [])
@@ -41,29 +77,45 @@ def build_automation_graph(
             parameters = device.get("parameters", [])
 
             for param in parameters:
-                if param.get("is_automated", False) or param.get("automation_state", 0) > 0:
-                    automated_params.append({
-                        "track_index": t_idx,
-                        "track_name": t_name,
-                        "device_name": device_name,
-                        "param_name": param.get("name", ""),
-                        "param_value": param.get("value"),
-                    })
+                is_flagged = (
+                    param.get("is_automated", False)
+                    or param.get("automation_state", 0) > 0
+                )
+                if not is_flagged:
+                    continue
+                p_name = param.get("name", "")
+                key = (t_idx, str(device_name), str(p_name))
+                if key in seen:
+                    continue
+                seen.add(key)
+                automated_params.append({
+                    "track_index": t_idx,
+                    "track_name": t_name,
+                    "device_name": device_name,
+                    "param_name": p_name,
+                    "param_value": param.get("value"),
+                    "source": "device_hint",
+                })
 
     graph.automated_params = automated_params
 
-    # Compute density_by_section if sections are provided
+    # Compute density_by_section.
     if sections:
         total_automated = len(automated_params)
         for sec in sections:
             section_id = sec.get("section_id", "")
-            # Without per-section automation data, distribute evenly
-            # and weight by section density (more active tracks = more automation)
-            sec_density = sec.get("density", 0.0)
-            # Automation density approximation: section density * param count ratio
-            if total_automated > 0:
+            if per_section_counts:
+                # Use real per-section counts when we have them.
+                count = per_section_counts.get(section_id, 0)
+                # Normalize by max(1, largest section count) so the
+                # densest section is 1.0 and others fall below.
+                max_ct = max(per_section_counts.values()) or 1
+                graph.density_by_section[section_id] = round(count / max_ct, 3)
+            elif total_automated > 0:
+                # Fallback: approximate from section density (old behavior)
+                sec_density = sec.get("density", 0.0)
                 graph.density_by_section[section_id] = round(
-                    sec_density * min(total_automated / max(len(track_infos), 1), 1.0),
+                    sec_density * min(total_automated / max(len(track_infos or []), 1), 1.0),
                     3,
                 )
             else:

package/mcp_server/project_brain/builder.py

@@ -23,6 +23,7 @@ def build_project_state_from_data(
     track_infos: Optional[list[dict]] = None,
     notes_map: Optional[dict[str, dict[int, list[dict]]]] = None,
     arrangement_clips: Optional[dict] = None,
+    clip_automation: Optional[list[dict]] = None,
     analyzer_ok: bool = False,
     flucoma_ok: bool = False,
     plugin_health: Optional[dict[str, Any]] = None,
@@ -105,6 +106,7 @@ def build_project_state_from_data(
     state.automation_graph = build_automation_graph(
         track_infos=track_infos or [],
         sections=section_dicts_for_auto,
+        clip_automation=clip_automation or [],
     )
     state.automation_graph.freshness.mark_fresh(state.revision)
 

package/mcp_server/project_brain/tools.py

@@ -88,14 +88,20 @@ def build_project_brain(ctx: Context) -> dict:
     # Shape: {section_id: {track_index: [notes]}}. Without this, role_graph
     # falls back to "assume all tracks active in every section" which destroys
     # section-scoped role confidence.
+    #
+    # BUG-E1: section_id must match what build_section_graph_from_scenes emits.
+    # The composition engine emits `sec_{i:02d}` using the RAW enumerate index
+    # of the scene — it skips unnamed scenes (gap-preserving), so e.g. scenes
+    # ["Intro", "", "Verse"] become sections sec_00 and sec_02, not sec_01.
+    # Our notes_map must mirror that or keys won't align.
     notes_map: dict[str, dict[int, list[dict]]] = {}
     try:
         for scene_idx, scene in enumerate(scenes or []):
-            section_id = str(
-                scene.get("section_id")
-                or scene.get("name")
-                or f"scene_{scene_idx}"
-            )
+            scene_name = str(scene.get("name", "")).strip()
+            if not scene_name:
+                continue  # mirror _ce_build_sections: unnamed scenes skipped
+            section_id = f"sec_{scene_idx:02d}"
+
             per_track: dict[int, list[dict]] = {}
             for track in tracks:
                 t_idx = track.get("index", 0)
@@ -119,6 +125,49 @@ def build_project_brain(ctx: Context) -> dict:
         # Overall failure: empty map, degrade to "all tracks active" fallback
         notes_map = {}
 
+    # 5c. Scan clip automation across the session (BUG-E2).
+    # Device-parameter is_automated flags only reflect whether a parameter
+    # is mapped somewhere — they don't reveal clip envelopes. Ableton's
+    # automation actually lives on each clip (session + arrangement). We
+    # walk every clip slot that has a clip and ask get_clip_automation, then
+    # aggregate into a flat list keyed by section.
+    clip_automation: list[dict] = []
+    try:
+        # Iterate session scenes x tracks, plus arrangement clips we already have.
+        # Use the raw enumerate index for section_id so it stays aligned with
+        # arrangement_graph sections (which use the same scheme — see E1 fix).
+        for scene_idx, scene in enumerate(scenes or []):
+            scene_name = str(scene.get("name", "")).strip()
+            if not scene_name:
+                continue
+            section_id = f"sec_{scene_idx:02d}"
+            for track in tracks:
+                t_idx = track.get("index", 0)
+                try:
+                    auto_resp = ableton.send_command("get_clip_automation", {
+                        "track_index": t_idx,
+                        "clip_index": scene_idx,
+                    })
+                except Exception as exc:
+                    # No clip in slot, or remote script rejected — skip
+                    logger.debug("build_project_brain automation skip: %s", exc)
+                    continue
+                if not isinstance(auto_resp, dict):
+                    continue
+                envs = auto_resp.get("envelopes") or []
+                for env in envs:
+                    clip_automation.append({
+                        "section_id": section_id,
+                        "track_index": t_idx,
+                        "track_name": track.get("name", ""),
+                        "clip_index": scene_idx,
+                        "parameter_name": env.get("parameter_name", ""),
+                        "parameter_type": env.get("parameter_type", ""),
+                        "device_name": env.get("device_name"),
+                    })
+    except Exception as exc:
+        logger.debug("build_project_brain automation scan failed: %s", exc)
+
     # 6. Probe capabilities (direct SpectralCache access, not TCP)
     analyzer_ok = False
     analyzer_fresh = False
@@ -146,6 +195,7 @@ def build_project_brain(ctx: Context) -> dict:
         track_infos=track_infos if track_infos else None,
         notes_map=notes_map if notes_map else None,
         arrangement_clips=arrangement_clips if arrangement_clips else None,
+        clip_automation=clip_automation if clip_automation else None,
         analyzer_ok=analyzer_ok,
         flucoma_ok=flucoma_ok,
         session_ok=True,

package/mcp_server/reference_engine/profile_builder.py

@@ -96,11 +96,22 @@ def build_style_reference_profile(style_tactics: list[dict]) -> ReferenceProfile
     # Estimate density from arrangement pattern count
     density_arc = _estimate_density_from_patterns(style_tactics)
 
+    # BUG-B50 fix: the old code hardcoded loudness_posture=0.0 and
+    # empty spectral_contour / width_depth because StyleTactic entries
+    # don't carry those fields. We now derive them heuristically from
+    # the device_chain (each device's params leak its intended sonic
+    # shape — e.g., Auto Filter at 800Hz low-pass = darker spectrum,
+    # Utility Width > 0.6 = wider stereo). Rough but non-empty values
+    # are better than zeros for downstream reference-gap analysis.
+    loudness_posture = _derive_loudness_posture(style_tactics)
+    spectral_contour = _derive_spectral_contour(style_tactics)
+    width_depth = _derive_width_depth(style_tactics)
+
     return ReferenceProfile(
         source_type="style",
-        loudness_posture=0.0,  # style doesn't specify loudness
-        spectral_contour={},  # style doesn't specify spectrum
-        width_depth={},
+        loudness_posture=loudness_posture,
+        spectral_contour=spectral_contour,
+        width_depth=width_depth,
         density_arc=density_arc,
         section_pacing=section_pacing,
         harmonic_character=harmonic_character,
@@ -147,3 +158,118 @@ def _estimate_density_from_patterns(style_tactics: list[dict]) -> list[float]:
             densities.append(min(0.9, 0.3 + n * 0.15))
 
     return densities
+
+
+# ── BUG-B50 derivations — style → loudness/spectral/width heuristics ──────
+
+
+def _derive_loudness_posture(style_tactics: list[dict]) -> float:
+    """Heuristic: compression / saturation / limiter devices imply a
+    specific loudness posture. Glue / Ratio>3 → loud, saturator drive
+    high → cranked/loud, delay/reverb-heavy → quieter mix."""
+    loud_signals = 0
+    quiet_signals = 0
+    for tactic in style_tactics:
+        for dev in tactic.get("device_chain", []):
+            name = str(dev.get("name", "")).lower()
+            params = dev.get("params", {}) or {}
+            if "glue" in name or "limiter" in name:
+                loud_signals += 2
+            if name == "saturator" or "overdrive" in name:
+                drive = float(params.get("Drive", 0) or 0)
+                if drive >= 6:
+                    loud_signals += 1
+            if name == "compressor":
+                ratio = float(params.get("Ratio", 0) or 0)
+                if ratio >= 4:
+                    loud_signals += 1
+            if name == "reverb":
+                # Heavy reverb tails push the mix quieter
+                wet = float(params.get("Dry/Wet", 0) or 0)
+                if wet >= 0.6:
+                    quiet_signals += 1
+    # Normalize to -1..+1 range (loud=+1, quiet=-1, neutral=0)
+    if loud_signals == 0 and quiet_signals == 0:
+        return 0.0
+    net = (loud_signals - quiet_signals) / max(
+        loud_signals + quiet_signals, 1
+    )
+    return round(net, 2)
+
+
+def _derive_spectral_contour(style_tactics: list[dict]) -> dict:
+    """Heuristic: Auto Filter frequencies + device names leak the
+    target spectrum. Low-pass filters → dark, EQ Eight with no params
+    → neutral, saturators → mid-forward."""
+    brightness = 0.5  # neutral starting point
+    mid_emphasis = 0.5
+    dark_hits = 0
+    bright_hits = 0
+    for tactic in style_tactics:
+        for dev in tactic.get("device_chain", []):
+            name = str(dev.get("name", "")).lower()
+            params = dev.get("params", {}) or {}
+            if "auto filter" in name or name == "autofilter":
+                freq = float(params.get("Frequency", 1500) or 1500)
+                # Ableton Auto Filter Frequency is 20-22000; below 2k hints dark
+                if freq < 2000:
+                    dark_hits += 1
+                elif freq > 5000:
+                    bright_hits += 1
+            if "saturator" in name or "overdrive" in name:
+                mid_emphasis += 0.1
+    if dark_hits > bright_hits:
+        brightness = 0.3
+    elif bright_hits > dark_hits:
+        brightness = 0.75
+    return {
+        "band_balance": {
+            "sub": 0.45,
+            "low": 0.5,
+            "mid": min(1.0, mid_emphasis),
+            "high_mid": round(0.3 + brightness * 0.4, 2),
+            "high": round(0.2 + brightness * 0.5, 2),
+        },
+        "brightness": round(brightness, 2),
+        "centroid_hint": "dark" if brightness < 0.4
+                         else "bright" if brightness > 0.65
+                         else "neutral",
+    }
+
+
+def _derive_width_depth(style_tactics: list[dict]) -> dict:
+    """Heuristic: Utility Width, Chorus-Ensemble, or heavy reverb
+    implies a wider stereo field; dry chains imply narrow."""
+    width_value = 0.5
+    depth_value = 0.5
+    for tactic in style_tactics:
+        for dev in tactic.get("device_chain", []):
+            name = str(dev.get("name", "")).lower()
+            params = dev.get("params", {}) or {}
+            if name == "utility":
+                w = params.get("Width")
+                if w is not None:
+                    try:
+                        width_value = max(width_value, float(w))
+                    except (TypeError, ValueError):
+                        pass
+            if "reverb" in name:
+                wet = float(params.get("Dry/Wet", 0) or 0)
+                if wet > 0.4:
+                    depth_value = max(depth_value, 0.7)
+                    width_value = max(width_value, 0.65)
+            if "chorus" in name or "ensemble" in name:
+                width_value = max(width_value, 0.75)
+            if "delay" in name:
+                wet = float(params.get("Dry/Wet", 0) or 0)
+                if wet > 0.2:
+                    depth_value = max(depth_value, 0.6)
+    return {
+        "stereo_width": round(width_value, 2),
+        "depth": round(depth_value, 2),
+        "depth_hint": (
+            "deep" if depth_value > 0.6 else
+            "intimate" if depth_value < 0.4 else
+            "neutral"
+        ),
+    }

package/mcp_server/reference_engine/tools.py

@@ -30,6 +30,20 @@ def _fetch_comparison_data(ctx: Context, mix_path: str, reference_path: str) ->
     return compare_to_reference(mix_path, reference_path, normalize=True)
 
 
+def _fetch_memory_tactics(style: str) -> list[dict]:
+    """BUG-B19: pull user-saved techniques tagged with *style* so they
+    feed into the reference-profile lookup path. Best-effort — returns
+    empty list when the memory store isn't available."""
+    if not style:
+        return []
+    try:
+        from ..tools.research import _memory_store
+        return _memory_store.search(query=style, limit=10)
+    except Exception as exc:
+        logger.debug("_fetch_memory_tactics failed for %r: %s", style, exc)
+        return []
+
+
 def _fetch_project_snapshot(ctx: Context) -> dict:
     """Build a lightweight project snapshot for gap analysis."""
     ableton = ctx.lifespan_context["ableton"]
@@ -110,10 +124,21 @@ def build_reference_profile(
         return profile.to_dict()
 
     if style:
-        tactics = get_style_tactics(style)
+        # BUG-B19 fix: also pass user-memory tactics so custom styles
+        # (e.g. "prefuse73" saved via memory_learn) resolve to real
+        # profiles instead of NOT_FOUND. Silently ignore if memory
+        # isn't available (keeps the built-in path working).
+        memory_tactics = _fetch_memory_tactics(style)
+        tactics = get_style_tactics(style, memory_tactics=memory_tactics)
         if not tactics:
             return {
-                "error": f"No style tactics found for '{style}'",
+                "error": (
+                    f"No style tactics found for '{style}' — neither in the "
+                    f"built-in library (burial / daft punk / techno / ambient / "
+                    f"trap / lo-fi) nor in your saved memories. Use "
+                    f"memory_learn to save a '{style}' technique or try "
+                    f"reference_path=<audio-file> for an audio-based profile."
+                ),
                 "code": "NOT_FOUND",
             }
         tactic_dicts = [t.to_dict() for t in tactics]
@@ -158,9 +183,17 @@ def analyze_reference_gaps(
             return comparison
         profile = build_audio_reference_profile(comparison)
     elif style:
-        tactics = get_style_tactics(style)
+        # BUG-B19: hydrate from saved memories too
+        memory_tactics = _fetch_memory_tactics(style)
+        tactics = get_style_tactics(style, memory_tactics=memory_tactics)
         if not tactics:
-            return {"error": f"No style tactics found for '{style}'", "code": "NOT_FOUND"}
+            return {
+                "error": (
+                    f"No style tactics found for '{style}' — neither in the "
+                    f"built-in library nor in saved memories."
+                ),
+                "code": "NOT_FOUND",
+            }
         tactic_dicts = [t.to_dict() for t in tactics]
         profile = build_style_reference_profile(tactic_dicts)
     else:
@@ -212,9 +245,17 @@ def plan_reference_moves(
             return comparison
         profile = build_audio_reference_profile(comparison)
     elif style:
-        tactics = get_style_tactics(style)
+        # BUG-B19: hydrate from saved memories too
+        memory_tactics = _fetch_memory_tactics(style)
+        tactics = get_style_tactics(style, memory_tactics=memory_tactics)
         if not tactics:
-            return {"error": f"No style tactics found for '{style}'", "code": "NOT_FOUND"}
+            return {
+                "error": (
+                    f"No style tactics found for '{style}' — neither in the "
+                    f"built-in library nor in saved memories."
+                ),
+                "code": "NOT_FOUND",
+            }
         tactic_dicts = [t.to_dict() for t in tactics]
         profile = build_style_reference_profile(tactic_dicts)
     else:

package/mcp_server/runtime/execution_router.py

@@ -50,6 +50,56 @@ MCP_TOOLS: frozenset[str] = frozenset({
 })
 
 
+# Tools that observe session state without mutating it. Executors use this set
+# to separate "apply pass" steps (writes) from "verification reads". Counting
+# reads toward applied_count and then calling undo that many times walks back
+# earlier user edits — see preview_studio/tools.py and experiment/engine.py.
+READ_ONLY_TOOLS: frozenset[str] = frozenset({
+    "get_track_meters",
+    "get_master_spectrum",
+    "get_master_meters",
+    "get_master_rms",
+    "get_mix_snapshot",
+    "get_session_info",
+    "get_track_info",
+    "get_track_routing",
+    "get_return_tracks",
+    "get_device_info",
+    "get_device_parameters",
+    "get_clip_info",
+    "get_notes",
+    "get_arrangement_notes",
+    "get_arrangement_clips",
+    "get_scenes_info",
+    "get_scene_matrix",
+    "get_playing_clips",
+    "get_cue_points",
+    "get_rack_chains",
+    "get_clip_automation",
+    "analyze_mix",
+    "get_emotional_arc",
+    "get_motif_graph",
+    "get_session_diagnostics",
+    "ping",
+})
+
+
+def filter_apply_steps(steps: list) -> list:
+    """Return only the steps that mutate session state.
+
+    Read-only steps (meters, spectrum, info) do not create undo points in
+    Ableton. Including them in an applied_count and then undoing that many
+    times walks back earlier user edits. Always filter writes from reads
+    before the apply pass and before the undo loop.
+    """
+    out = []
+    for s in steps:
+        tool = (s.get("tool") if isinstance(s, dict) else getattr(s, "tool", "")) or ""
+        if tool and tool not in READ_ONLY_TOOLS:
+            out.append(s)
+    return out
+
+
 @dataclass
 class ExecutionResult:
     """Result of executing a single plan step."""
@@ -276,8 +326,22 @@ async def execute_plan_steps_async(
         results.append(result)
 
         # Record successful step result for future bindings
-        if result.ok and step_id and isinstance(result.result, dict):
-            step_results[step_id] = result.result
+        if result.ok and step_id:
+            if isinstance(result.result, dict):
+                step_results[step_id] = result.result
+            else:
+                # Log but DO NOT silently drop the binding without telling
+                # anyone — the previous version let non-dict results slip
+                # past, which meant any downstream {"$from_step": step_id}
+                # reference blew up with a confusing "step_id not found"
+                # instead of the real "result wasn't a dict" cause.
+                import logging as _logging
+                _logging.getLogger(__name__).warning(
+                    "step_results: dropping non-dict result for "
+                    "step_id=%s tool=%s type=%s. Any $from_step refs to "
+                    "this step_id will fail with 'step_id not found'.",
+                    step_id, tool, type(result.result).__name__,
+                )
 
         if not result.ok and stop_on_failure:
             break

package/mcp_server/runtime/mcp_dispatch.py

@@ -14,18 +14,33 @@ To add a new in-process tool to plans:
   2. Add an _adapter function here that imports the real implementation and
      adapts its kwargs from a plan-style params dict.
   3. Register the adapter in build_mcp_dispatch_registry.
+
+Every entry in MCP_TOOLS must have a matching adapter here — the contract
+test tests/test_mcp_dispatch_contract.py enforces this.
 """
 
 from __future__ import annotations
 
+import inspect
 from typing import Any, Callable
 
 
-async def _load_sample_to_simpler(params: dict, ctx: Any = None) -> dict:
-    """Adapter for mcp_server.tools.analyzer.load_sample_to_simpler.
+async def _call(fn, ctx, params: dict) -> Any:
+    """Call an MCP tool with ctx + kwargs from a plan params dict.
 
-    Accepts the plan-step params dict and unpacks into the real tool's kwargs.
+    Filters params to the tool's declared parameters, awaits if coroutine.
+    Unknown params are dropped silently — plans may carry extra metadata.
     """
+    sig = inspect.signature(fn)
+    accepted = set(sig.parameters.keys())
+    kwargs = {k: v for k, v in params.items() if k in accepted}
+    result = fn(ctx, **kwargs)
+    if inspect.isawaitable(result):
+        result = await result
+    return result
+
+
+async def _load_sample_to_simpler(params: dict, ctx: Any = None) -> dict:
     from ..tools.analyzer import load_sample_to_simpler
     return await load_sample_to_simpler(
         ctx,
@@ -35,12 +50,69 @@ async def _load_sample_to_simpler(params: dict, ctx: Any = None) -> dict:
     )
 
 
+async def _apply_automation_shape(params: dict, ctx: Any = None) -> dict:
+    from ..tools.automation import apply_automation_shape
+    return await _call(apply_automation_shape, ctx, params)
+
+
+async def _apply_gesture_template(params: dict, ctx: Any = None) -> dict:
+    from ..tools.composition import apply_gesture_template
+    return await _call(apply_gesture_template, ctx, params)
+
+
+async def _analyze_mix(params: dict, ctx: Any = None) -> dict:
+    from ..mix_engine.tools import analyze_mix
+    return await _call(analyze_mix, ctx, params)
+
+
+async def _get_master_spectrum(params: dict, ctx: Any = None) -> dict:
+    from ..tools.analyzer import get_master_spectrum
+    return await _call(get_master_spectrum, ctx, params)
+
+
+async def _get_emotional_arc(params: dict, ctx: Any = None) -> dict:
+    from ..tools.research import get_emotional_arc
+    return await _call(get_emotional_arc, ctx, params)
+
+
+async def _get_motif_graph(params: dict, ctx: Any = None) -> dict:
+    from ..tools.motif import get_motif_graph
+    return await _call(get_motif_graph, ctx, params)
+
+
+async def _generate_m4l_effect(params: dict, ctx: Any = None) -> dict:
+    from ..device_forge.tools import generate_m4l_effect
+    return await _call(generate_m4l_effect, ctx, params)
+
+
+async def _install_m4l_device(params: dict, ctx: Any = None) -> dict:
+    from ..device_forge.tools import install_m4l_device
+    return await _call(install_m4l_device, ctx, params)
+
+
+async def _list_genexpr_templates(params: dict, ctx: Any = None) -> dict:
+    from ..device_forge.tools import list_genexpr_templates
+    return await _call(list_genexpr_templates, ctx, params)
+
+
 def build_mcp_dispatch_registry() -> dict[str, Callable]:
     """Return the canonical registry of MCP-only tools for plan execution.
 
     Callers (typically the server lifespan init) should call this once and
     pass the registry to execute_plan_steps_async via the mcp_registry kwarg.
+
+    INVARIANT: the set of keys here must equal MCP_TOOLS in execution_router.
+    Enforced by tests/test_mcp_dispatch_contract.py.
     """
     return {
         "load_sample_to_simpler": _load_sample_to_simpler,
+        "apply_automation_shape": _apply_automation_shape,
+        "apply_gesture_template": _apply_gesture_template,
+        "analyze_mix": _analyze_mix,
+        "get_master_spectrum": _get_master_spectrum,
+        "get_emotional_arc": _get_emotional_arc,
+        "get_motif_graph": _get_motif_graph,
+        "generate_m4l_effect": _generate_m4l_effect,
+        "install_m4l_device": _install_m4l_device,
+        "list_genexpr_templates": _list_genexpr_templates,
     }