livepilot 1.10.6 → 1.10.7

package/mcp_server/tools/analyzer.py

@@ -7,6 +7,7 @@ These tools are optional — all core tools work without the device.
 from __future__ import annotations
 
 import os
+from typing import Optional
 
 from fastmcp import Context
 
@@ -968,3 +969,100 @@ def check_flucoma(ctx: Context) -> dict:
         streams[key] = cache.get(key) is not None
     active = sum(1 for v in streams.values() if v)
     return {"flucoma_available": active > 0, "active_streams": active, "streams": streams}
+
+
+# ── BUG-A2 + A3: deep-LOM properties via M4L bridge ──────────────────
+
+
+@mcp.tool()
+async def simpler_set_warp(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    warping: bool,
+    warp_mode: Optional[int] = None,
+) -> dict:
+    """Toggle a Simpler's sample warping + set the warp algorithm (BUG-A2).
+
+    Python's Remote Script ControlSurface API can't reach Simpler's
+    `warping` or `warp_mode` — they live on the sample child object
+    (SimplerDevice.sample.*) that only Max for Live's JavaScript LiveAPI
+    can step into. This tool routes through the M4L bridge to do the
+    write.
+
+    When enabling warping, pass the desired warp_mode too so Live doesn't
+    default to whatever was there last:
+
+        warp_mode 0 = Beats      (good for drums / percussive loops)
+        warp_mode 1 = Tones      (mono harmonic material)
+        warp_mode 2 = Texture    (poly / ambient material)
+        warp_mode 3 = Re-Pitch   (classic pitch-shift feel)
+        warp_mode 4 = Complex    (music / full mixes — higher CPU)
+        warp_mode 6 = Complex Pro (highest quality — highest CPU)
+
+    Args:
+        track_index: 0+ for regular tracks
+        device_index: Simpler device's position in the chain
+        warping: True → enable sample warp; False → disable
+        warp_mode: 0-6 (omit to leave the current mode unchanged)
+
+    Requires LivePilot Analyzer on master track.
+    """
+    if warp_mode is not None and warp_mode not in (0, 1, 2, 3, 4, 6):
+        raise ValueError("warp_mode must be 0,1,2,3,4,6 (no 5 — Live skips it)")
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    return await bridge.send_command(
+        "simpler_set_warp",
+        int(track_index),
+        int(device_index),
+        1 if warping else 0,
+        -1 if warp_mode is None else int(warp_mode),
+        timeout=10.0,
+    )
+
+
+@mcp.tool()
+async def compressor_set_sidechain(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    source_type: str = "",
+    source_channel: str = "",
+) -> dict:
+    """Configure a Compressor's sidechain INPUT ROUTING (BUG-A3).
+
+    Complements set_device_parameter's `S/C On` toggle: that enables the
+    sidechain, this picks WHICH track/channel feeds the detector. The
+    routing properties (`sidechain_input_routing_type`,
+    `sidechain_input_routing_channel`) aren't in Compressor's automatable
+    parameter list, but Python's Remote Script reaches them directly as
+    device properties (same LOM pattern as set_track_routing).
+
+    Args:
+        track_index: 0+ regular, -1/-2 returns, -1000 master
+        device_index: Compressor position in the chain
+        source_type: sidechain source display name
+            (e.g. "1-Kick", "Ext. In", "No Input")
+        source_channel: tap point on the source
+            (e.g. "Post FX", "Pre FX", "Post Mixer")
+
+    Omit a param to leave that property unchanged. If a display name
+    doesn't match, the error message includes the full list of available
+    options from the running Live session.
+
+    Routes through the Remote Script (TCP) — does NOT require the M4L
+    analyzer. This is the Python-side path introduced after the M4L
+    bridge approach hit LiveAPI shape issues in Live 12.3.6.
+    """
+    params: dict = {
+        "track_index": int(track_index),
+        "device_index": int(device_index),
+    }
+    if source_type:
+        params["source_type"] = str(source_type)
+    if source_channel:
+        params["source_channel"] = str(source_channel)
+    ableton = ctx.lifespan_context["ableton"]
+    return ableton.send_command("set_compressor_sidechain", params)

package/mcp_server/tools/clips.py

@@ -196,6 +196,51 @@ def set_clip_launch(
     return _get_ableton(ctx).send_command("set_clip_launch", params)
 
 
+@mcp.tool()
+def set_clip_pitch(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    coarse: Optional[int] = None,
+    fine: Optional[float] = None,
+    gain: Optional[float] = None,
+) -> dict:
+    """Set pitch transposition and/or gain on an audio clip (BUG-A5).
+
+    Audio clips only. Use this to correct sample pitch to match session key
+    (e.g. a D#min Splice clip in a Dm session -> coarse=-1).
+
+    coarse: semitones, -48..+48
+    fine:   cents, -50..+50
+    gain:   linear, 0..1 (Live's internal scale, not dB)
+
+    At least one of coarse/fine/gain must be provided.
+    """
+    _validate_track_index(track_index)
+    _validate_clip_index(clip_index)
+    if coarse is None and fine is None and gain is None:
+        raise ValueError(
+            "Provide at least one of: coarse (semitones), fine (cents), gain (0-1)"
+        )
+    if coarse is not None and not -48 <= coarse <= 48:
+        raise ValueError("coarse must be in -48..+48 semitones")
+    if fine is not None and not -50.0 <= fine <= 50.0:
+        raise ValueError("fine must be in -50..+50 cents")
+    if gain is not None and not 0.0 <= gain <= 1.0:
+        raise ValueError("gain must be in 0..1")
+    params: dict = {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    }
+    if coarse is not None:
+        params["coarse"] = coarse
+    if fine is not None:
+        params["fine"] = fine
+    if gain is not None:
+        params["gain"] = gain
+    return _get_ableton(ctx).send_command("set_clip_pitch", params)
+
+
 _VALID_WARP_MODES = {0, 1, 2, 3, 4, 6}
 
 

package/mcp_server/tools/composition.py

@@ -388,8 +388,13 @@ def get_harmony_field(
 
     section = sections[section_index]
 
-    # Find a track with notes to analyze harmony
-    # Use theory engine functions directly instead of TCP calls to MCP tools
+    # Find a track with notes to analyze harmony.
+    # BUG-E3 fix: score each active track for harmonic-ness and aggregate
+    # notes across all tracks that pass a threshold. Percussion tracks
+    # (all-single-pitch staccato stabs) scramble key detection when treated
+    # as the canonical harmonic source. Aggregating pad + bass notes yields
+    # the true key, and picking the highest-scoring single track for chord
+    # extraction gives the cleanest chord groupings.
     from . import _theory_engine as theory_engine
     from . import _harmony_engine as harmony_engine
 
@@ -398,27 +403,65 @@ def get_harmony_field(
     progression_info = None
     voice_leading_info = None
 
+    # Name lookup for track-name-based harmonic scoring hints
+    track_names = {t.get("index", i): t.get("name", "")
+                   for i, t in enumerate(tracks)}
+
+    # Per-track scan: fetch notes + score, then sort by score desc.
+    HARMONIC_THRESHOLD = 0.3
+    candidates: list[tuple[float, int, list[dict]]] = []
     for t_idx in section.tracks_active:
         try:
-            # Get notes via TCP (valid Remote Script command)
             result = ableton.send_command("get_notes", {
                 "track_index": t_idx, "clip_index": section_index,
             })
-            notes = result.get("notes", [])
-            if not notes:
-                continue
-
-            # identify_scale: run key detection directly
-            if not scale_info:
-                detected = theory_engine.detect_key(notes, mode_detection=True)
-                top = {
-                    "key": f"{detected['tonic_name']} {detected['mode'].replace('_', ' ')}",
-                    "confidence": detected["confidence"],
-                    "mode": detected["mode"].replace("_", " "),
-                    "mode_id": detected["mode"],
-                    "tonic": detected["tonic_name"],
-                }
-                scale_info = {"top_match": top}
+        except Exception as exc:
+            logger.debug("harmony scan track %d: %s", t_idx, exc)
+            continue
+        notes = result.get("notes", []) if isinstance(result, dict) else []
+        if not notes:
+            continue
+        score = engine.harmonic_score(notes, track_names.get(t_idx, ""))
+        candidates.append((score, t_idx, notes))
+
+    # Sort highest score first; ties broken by track index for stability.
+    candidates.sort(key=lambda c: (-c[0], c[1]))
+
+    # Aggregate harmonic notes for key detection; pick the top candidate
+    # for chord extraction.
+    harmonic_notes: list[dict] = []
+    harmonic_track_idx: Optional[int] = None
+    for score, t_idx, notes in candidates:
+        if score < HARMONIC_THRESHOLD:
+            continue
+        harmonic_notes.extend(notes)
+        if harmonic_track_idx is None:
+            harmonic_track_idx = t_idx
+
+    # If nothing passed the threshold, fall back to the highest-scoring
+    # track (or the first with any notes) to stay honest on edge cases.
+    if not harmonic_notes and candidates:
+        _, harmonic_track_idx, fallback_notes = candidates[0]
+        harmonic_notes = fallback_notes
+
+    if harmonic_notes and harmonic_track_idx is not None:
+        try:
+            # identify_scale on the AGGREGATED harmonic pool
+            detected = theory_engine.detect_key(harmonic_notes, mode_detection=True)
+            top = {
+                "key": f"{detected['tonic_name']} {detected['mode'].replace('_', ' ')}",
+                "confidence": detected["confidence"],
+                "mode": detected["mode"].replace("_", " "),
+                "mode_id": detected["mode"],
+                "tonic": detected["tonic_name"],
+            }
+            scale_info = {"top_match": top}
+
+            # Chord extraction: use the notes from the top-scoring track
+            # so chord groups don't get polluted by simultaneous notes
+            # across unrelated tracks (bass + pad + lead would fuse into
+            # chord aggregates that no single instrument actually plays).
+            notes = next(n for s, t, n in candidates if t == harmonic_track_idx)
 
             # analyze_harmony: chordify + roman numeral analysis directly
             if not harmony_analysis:
@@ -491,12 +534,12 @@ def get_harmony_field(
                         }
                 except Exception as exc:
                     logger.warning("voice_leading analysis failed: %s", exc)
-
-            if scale_info and harmony_analysis:
-                break
         except Exception as exc:
-            logger.debug("harmony scan on track %d skipped: %s", t_idx, exc)
-            continue
+            # Any per-track analysis failure — log and emit whatever we
+            # have. Unlike the old loop we're not iterating further, so
+            # there's nowhere to continue to.
+            logger.debug("harmony analysis on track %s failed: %s",
+                         harmonic_track_idx, exc)
 
     hf = engine.build_harmony_field(
         section_id=section.section_id,

package/mcp_server/tools/devices.py

@@ -249,7 +249,28 @@ def set_device_parameter(
     parameter_index: Optional[int] = None,
 ) -> dict:
     """Set a device parameter by name or index.
-    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master."""
+
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks (A/B/...), -1000 for master.
+
+    ⚠️ PARAMETER RANGES ARE NOT ALWAYS 0-1 (BUG-B4 / B9):
+      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 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 ✓
+        - Drift / Analog / Operator macros: 0-1 normalized ✓
+
+      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.
+    """
     _validate_track_index(track_index)
     _validate_device_index(device_index)
     if parameter_name is None and parameter_index is None:

package/mcp_server/tools/harmony.py

@@ -129,19 +129,37 @@ def find_voice_leading_path(
         }
 
     path_strs = [harmony.chord_to_str(*c) for c in result["path"]]
+
+    # BUG-B25 fix: optimize voice assignment. The old code emitted each
+    # chord at its root-position octave-4 voicing, so moving D minor →
+    # Bb major (D F A → Bb D F) appeared as a minor-6th jump instead of
+    # the smooth D→D / F→F / A→Bb voice leading a pianist would pick.
+    # We now walk the path keeping the FIRST chord at its default
+    # voicing and, for each subsequent chord, pick the permutation
+    # (inversion + octave offsets) that minimizes total semitone
+    # movement from the previous voicing.
     voice_leading = []
+    prev_voicing = harmony.chord_to_midi(*result["path"][0]) if result["path"] else []
+
     for i in range(len(result["path"]) - 1):
-        from_midi = harmony.chord_to_midi(*result["path"][i])
-        to_midi = harmony.chord_to_midi(*result["path"][i + 1])
+        next_chord = result["path"][i + 1]
+        candidate_voicing = harmony.chord_to_midi(*next_chord)
+        optimized_voicing = _optimize_voicing(prev_voicing, candidate_voicing)
+
         movements = []
-        for f, t in zip(from_midi, to_midi):
+        for f, t in zip(prev_voicing, optimized_voicing):
             if f != t:
                 movements.append(f"{theory.pitch_name(f)}→{theory.pitch_name(t)}")
+
         voice_leading.append({
-            "from": from_midi,
-            "to": to_midi,
+            "from": list(prev_voicing),
+            "to": list(optimized_voicing),
             "movement": ", ".join(movements) if movements else "no movement",
+            "total_semitone_movement": sum(
+                abs(t - f) for f, t in zip(prev_voicing, optimized_voicing)
+            ),
         })
+        prev_voicing = optimized_voicing
 
     return {
         "from": from_chord,
@@ -154,6 +172,40 @@ def find_voice_leading_path(
     }
 
 
+def _optimize_voicing(prev_voicing: list[int], target_pitches: list[int]) -> list[int]:
+    """Pick an inversion/octave arrangement of *target_pitches* that
+    minimizes total semitone movement from *prev_voicing*.
+
+    Search space: for each permutation of target_pitches (3 voices →
+    6 permutations), for each voice try octave offsets in ±2 octaves.
+    That's 6 * 5^3 = 750 combinations per transition — trivial at runtime
+    but dramatically smoother output than fixed-octave voicings.
+
+    Assumes same voice-count on both sides; falls back to target_pitches
+    unchanged if lengths differ.
+    """
+    import itertools
+
+    if len(prev_voicing) != len(target_pitches) or not target_pitches:
+        return list(target_pitches)
+
+    best_voicing = list(target_pitches)
+    best_cost = sum(abs(t - f) for f, t in zip(prev_voicing, best_voicing))
+
+    # Each voice can float ±2 octaves (±24 semitones) from the base pitch
+    octave_offsets = (-24, -12, 0, 12, 24)
+
+    for perm in itertools.permutations(target_pitches):
+        for offs in itertools.product(octave_offsets, repeat=len(perm)):
+            candidate = [p + o for p, o in zip(perm, offs)]
+            cost = sum(abs(t - f) for f, t in zip(prev_voicing, candidate))
+            if cost < best_cost:
+                best_cost = cost
+                best_voicing = candidate
+
+    return best_voicing
+
+
 # -- Tool 3: classify_progression --------------------------------------------
 
 @mcp.tool()
@@ -191,24 +243,72 @@ def classify_progression(
 
     classification = "free neo-Riemannian progression"
     notable_usage = None
-    clean = pattern.replace("?", "")
 
-    if len(clean) >= 2:
-        pair = clean[:2]
-        if pair in ("PL", "LP") and all(c in "PL" for c in clean):
+    # BUG-B24: the old code did `clean = pattern.replace("?", "")` and
+    # then checked alphabet purity on the cleaned string. That gave
+    # a cheerful "diatonic cycle fragment" label to a pattern like
+    # "LR?LR" — silently ignoring the middle step motion.
+    # Now we check alphabet purity on the FULL pattern (only counting
+    # transforms that landed in the target alphabet) AND track whether
+    # any transforms were unclassified OR were step primitives that
+    # aren't part of the target cycle alphabet.
+
+    def _primitives(pat: str) -> list[str]:
+        """Split a concatenated pattern into its atomic tokens.
+
+        Tokens: P / L / R single letters, S1u/S1d/S2u/S2d step markers,
+        and ? for unknown. The tokenizer walks left-to-right matching
+        the longest known token at each position.
+        """
+        known = ("S1u", "S1d", "S2u", "S2d")
+        out = []
+        i = 0
+        while i < len(pat):
+            matched = None
+            for tok in known:
+                if pat.startswith(tok, i):
+                    matched = tok
+                    break
+            if matched is None:
+                out.append(pat[i])
+                i += 1
+            else:
+                out.append(matched)
+                i += len(matched)
+        return out
+
+    tokens = _primitives(pattern)
+    core_tokens = [t for t in tokens if t in ("P", "L", "R")]
+    step_tokens = [t for t in tokens if t.startswith("S")]
+    unknown_count = sum(1 for t in tokens if t == "?")
+
+    if len(core_tokens) >= 2:
+        alphabet = set(core_tokens)
+        if alphabet.issubset({"P", "L"}):
             classification = "hexatonic cycle fragment"
             notable_usage = "Radiohead, film scores (Zimmer, Howard)"
-        elif pair in ("PR", "RP") and all(c in "PR" for c in clean):
+        elif alphabet.issubset({"P", "R"}):
             classification = "octatonic cycle fragment"
             notable_usage = "late Romantic (Wagner, Strauss), horror film scores"
-        elif pair in ("LR", "RL") and all(c in "LR" for c in clean):
+        elif alphabet.issubset({"L", "R"}):
             classification = "diatonic cycle fragment"
             notable_usage = "functional harmony, common in classical and pop"
-
-    if len(clean) == 1:
+    elif len(core_tokens) == 1:
         names = {"P": "parallel transform", "L": "leading-tone transform",
                  "R": "relative transform"}
-        classification = names.get(clean, classification)
+        classification = names.get(core_tokens[0], classification)
+
+    # Annotate when the progression isn't purely in the classified alphabet
+    annotations = []
+    if step_tokens:
+        annotations.append("with diatonic step motion")
+    if unknown_count:
+        annotations.append(
+            f"with {unknown_count} unclassified transition"
+            + ("s" if unknown_count != 1 else "")
+        )
+    if annotations:
+        classification = f"{classification} ({', '.join(annotations)})"
 
     return {
         "chords": normalized,
@@ -216,6 +316,7 @@ def classify_progression(
         "pattern": pattern,
         "classification": classification,
         "notable_usage": notable_usage,
+        "unknown_transitions": unknown_count,
     }
 
 

package/mcp_server/tools/midi_io.py

@@ -130,7 +130,19 @@ def export_clip_midi(
     if not filename.endswith((".mid", ".midi")):
         filename += ".mid"
 
-    out_path = _safe_output_path(_output_dir(), filename)
+    # BUG-B52: honor user-provided absolute paths. Previously the tool
+    # stripped the directory component and always wrote to the default
+    # output dir — a security posture meant to block path traversal but
+    # over-broad for legitimate absolute paths the user explicitly chose.
+    # Now: absolute paths are honored (creating parent dirs if needed);
+    # bare filenames / relative paths still get containment via
+    # _safe_output_path.
+    user_path = Path(filename)
+    if user_path.is_absolute():
+        user_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path = user_path.resolve()
+    else:
+        out_path = _safe_output_path(_output_dir(), filename)
 
     midi = MIDIFile(1)
     midi.addTempo(0, 0, tempo)

package/mcp_server/tools/mixing.py

@@ -100,13 +100,47 @@ def get_track_meters(
 
     track_index:    specific track (omit for all tracks)
     include_stereo: include left/right channel meters (adds GUI load)
+
+    BUG-B3: when playback is stopped, `level` reports peak-hold from the
+    last loud moment while `left`/`right` report instantaneous channel
+    levels (which decay to 0). The two fields then visibly disagree, and
+    callers debugging "is my filter killing the signal?" get false alarms.
+    We now tag each response with `is_playing` so callers can interpret
+    the levels correctly, and — when include_stereo=True AND playback is
+    stopped — we mark left/right as `null` instead of 0 so the semantic
+    is explicit.
     """
     params: dict = {}
     if track_index is not None:
         params["track_index"] = track_index
     if include_stereo:
         params["include_stereo"] = include_stereo
-    return _get_ableton(ctx).send_command("get_track_meters", params)
+    ableton = _get_ableton(ctx)
+    result = ableton.send_command("get_track_meters", params)
+
+    # Probe playback state once so we can annotate the response
+    try:
+        session = ableton.send_command("get_session_info", {})
+        is_playing = bool(session.get("is_playing", False))
+    except Exception:
+        is_playing = None  # unknown — leave left/right as reported
+
+    if not isinstance(result, dict):
+        return result
+    result["is_playing"] = is_playing
+    # When stopped AND stereo was requested, mark l/r as None so they
+    # don't look like a killed signal
+    if include_stereo and is_playing is False:
+        for t in result.get("tracks", []):
+            if isinstance(t, dict):
+                if t.get("left") == 0 and t.get("right") == 0:
+                    t["left"] = None
+                    t["right"] = None
+                    t["_stereo_note"] = (
+                        "left/right suppressed because playback is stopped; "
+                        "`level` is peak-hold from the last audio event"
+                    )
+    return result
 
 
 @mcp.tool()

package/mcp_server/tools/motif.py

@@ -22,7 +22,12 @@ def _get_ableton(ctx: Context):
 
 
 @mcp.tool()
-def get_motif_graph(ctx: Context) -> dict:
+def get_motif_graph(
+    ctx: Context,
+    limit: int = 50,
+    offset: int = 0,
+    summary_only: bool = False,
+) -> dict:
     """Detect recurring melodic and rhythmic patterns across all tracks.
 
     Scans note data from all session clips to find repeated interval
@@ -31,7 +36,27 @@ def get_motif_graph(ctx: Context) -> dict:
 
     Use this to understand what musical ideas are present and which
     ones need development or variation.
+
+    BUG-B7 fix: sessions with many clips produced 90 KB+ payloads that
+    exceeded inline-tool-response limits. Callers now page the list and
+    can opt into a compact summary view that drops per-motif occurrence
+    arrays and suggested_developments.
+
+    Args:
+        limit: maximum motifs returned per call (default 50, max 500).
+        offset: skip this many of the highest-salience motifs (for paging).
+        summary_only: return only motif_id + kind + salience + fatigue_risk
+                      + occurrence_count per motif, dropping occurrences
+                      and other lists. Use when you need a bird's-eye view.
     """
+    # Cheap input validation — these bounds match the tool contract the
+    # rest of the server relies on for inline responses.
+    if limit < 0:
+        raise ValueError("limit must be >= 0")
+    if offset < 0:
+        raise ValueError("offset must be >= 0")
+    limit = min(limit, 500)
+
     ableton = _get_ableton(ctx)
     session = ableton.send_command("get_session_info")
     tracks = session.get("tracks", [])
@@ -57,10 +82,31 @@ def get_motif_graph(ctx: Context) -> dict:
             notes_by_track[t_idx] = track_notes
 
     motifs = motif_engine.detect_motifs(notes_by_track)
+    total = len(motifs)
+    page = motifs[offset:offset + limit] if limit > 0 else []
+
+    if summary_only:
+        # Compact per-motif record: keep identity + scoring signals, drop
+        # occurrences / developments / pitch/rhythm payloads that balloon
+        # the response on complex sessions.
+        motif_dicts = [{
+            "motif_id": m.motif_id,
+            "kind": m.kind,
+            "salience": m.salience,
+            "fatigue_risk": m.fatigue_risk,
+            "occurrence_count": len(m.occurrences),
+        } for m in page]
+    else:
+        motif_dicts = [m.to_dict() for m in page]
 
     return {
-        "motifs": [m.to_dict() for m in motifs],
-        "motif_count": len(motifs),
+        "motifs": motif_dicts,
+        "motif_count": len(motif_dicts),
+        "total_motifs": total,
+        "offset": offset,
+        "limit": limit,
+        "summary_only": summary_only,
+        "has_more": offset + len(motif_dicts) < total,
         "tracks_analyzed": len(notes_by_track),
     }
 

package/mcp_server/tools/research.py

@@ -121,6 +121,30 @@ def get_emotional_arc(ctx: Context) -> dict:
     no resolution at the end, peak too early.
 
     Returns: tension curve and issues with recommended composition moves.
+
+    📌 On the `tension_curve` vs other energy metrics (BUG-B21 clarification):
+      LivePilot exposes THREE intentionally different "energy-like"
+      signals — they are NOT scaled versions of each other:
+
+        1. `get_section_graph.energy` / `get_performance_state.energy_level`
+           → density-based (active-track ratio per section). After the
+           Batch 6 cross-engine unification these two are identical.
+           Use when asking "how busy is this section?"
+
+        2. `get_emotional_arc.tension` (this tool)
+           → narrative-arc signal weighted by harmonic instability,
+           section placement, and payoff/contrast. Use when asking
+           "where does the song want to go emotionally?" — tension
+           can be HIGH in a sparse-but-anticipatory section (low
+           density) and LOW in a busy-but-resolved section (high
+           density).
+
+        3. `get_performance_state.energy_window.target_energy`
+           → forward-looking — next-scene target, not current state.
+
+      If the three readings disagree for the same section, that's the
+      DESIGN: density ≠ tension ≠ intended destination. Pick the one
+      that matches your question.
     """
     from . import _composition_engine as engine