livepilot 1.27.2 → 1.27.3

package/mcp_server/semantic_moves/mix_compilers.py

@@ -14,6 +14,53 @@ from .models import SemanticMove
 from . import resolvers
 
 
+def _kernel_track(kernel: dict, track_index: int) -> dict:
+    """Return the raw kernel track dict (with its `devices`) for an index.
+
+    resolvers.find_tracks_by_role returns a slimmed dict without `devices`, so
+    device resolution must reach back into the raw session_info track to see the
+    chain. Returns {} when not found.
+    """
+    for t in kernel.get("session_info", {}).get("tracks", []) or []:
+        if isinstance(t, dict) and t.get("index") == track_index:
+            return t
+    return {}
+
+
+def _find_eq_device_index(track: dict) -> int | None:
+    """Return the chain index of an EQ device on this track, or None.
+
+    Only inspects device data the kernel already carries — never assumes a
+    device that hasn't been confirmed present. Used so frequency-carve writes
+    target a resolved device rather than a blind device_index=0 (the
+    wrong-device hazard guarded by tests/test_compiler_safety_contract.py).
+    """
+    for i, dev in enumerate(track.get("devices", []) or []):
+        if not isinstance(dev, dict):
+            continue
+        name = str(dev.get("name", "")).lower()
+        class_name = str(dev.get("class_name", "")).lower()
+        if "eq" in name or "eq8" in class_name or "eqeight" in class_name:
+            return dev.get("index", i)
+    return None
+
+
+def _find_compressor_device_index(track: dict) -> int | None:
+    """Return the chain index of a Compressor on this track, or None.
+
+    Same kernel-snapshot-only discipline as _find_eq_device_index — used so the
+    sidechain routing targets a resolved compressor rather than a blind index.
+    """
+    for i, dev in enumerate(track.get("devices", []) or []):
+        if not isinstance(dev, dict):
+            continue
+        name = str(dev.get("name", "")).lower()
+        class_name = str(dev.get("class_name", "")).lower()
+        if "compressor" in name or "compressor" in class_name:
+            return dev.get("index", i)
+    return None
+
+
 def _compile_make_punchier(move: SemanticMove, kernel: dict) -> CompiledPlan:
     """Compile 'make_punchier': push drums, pull pads, tighten master bus."""
     steps = []
@@ -39,25 +86,33 @@ def _compile_make_punchier(move: SemanticMove, kernel: dict) -> CompiledPlan:
         verify_after=False,
     ))
 
-    # Step 2: Push drum volume
+    # Step 2: Push drum volume — RELATIVE nudge (P2-21), not an absolute
+    # overwrite. A hot drum bus must get louder, not slammed down to 0.75.
     for dt in drum_tracks[:1]:  # Only first drum track
         idx = dt["index"]
+        target = resolvers.compile_relative_volume(
+            dt.get("volume"), 8, cap=0.85, fallback=0.75
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": idx, "volume": 0.75},
-            description=f"Push {dt['name']} (track {idx}) to 0.75 for transient punch",
+            params={"track_index": idx, "volume": target},
+            description=f"Push {dt['name']} (track {idx}) to {target:.2f} for transient punch",
         ))
-        descriptions.append(f"Push {dt['name']} volume to 0.75")
+        descriptions.append(f"Push {dt['name']} volume to {target:.2f}")
 
-    # Step 3: Pull back pads
+    # Step 3: Pull back pads — RELATIVE nudge, floored so a quiet pad
+    # doesn't get muted outright.
     for pt in pad_tracks:
         idx = pt["index"]
+        target = resolvers.compile_relative_volume(
+            pt.get("volume"), -10, floor=0.15, fallback=0.25
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": idx, "volume": 0.25},
-            description=f"Pull {pt['name']} (track {idx}) to 0.25 for contrast",
+            params={"track_index": idx, "volume": target},
+            description=f"Pull {pt['name']} (track {idx}) to {target:.2f} for contrast",
         ))
-        descriptions.append(f"Pull {pt['name']} volume to 0.25")
+        descriptions.append(f"Pull {pt['name']} volume to {target:.2f}")
 
     # Step 4: Verify
     steps.append(CompiledStep(
@@ -114,13 +169,17 @@ def _compile_tighten_low_end(move: SemanticMove, kernel: dict) -> CompiledPlan:
         optional=True,
     ))
 
-    # Step 2: Reduce bass volume slightly
+    # Step 2: Reduce bass volume slightly — RELATIVE nudge (P2-21), floored
+    # so a bass already sitting quiet doesn't get pulled toward silence.
+    target = resolvers.compile_relative_volume(
+        bass.get("volume"), -10, floor=0.35, fallback=0.58
+    )
     steps.append(CompiledStep(
         tool="set_track_volume",
-        params={"track_index": idx, "volume": 0.58},
-        description=f"Reduce {bass['name']} volume to 0.58 (tighten sub)",
+        params={"track_index": idx, "volume": target},
+        description=f"Reduce {bass['name']} volume to {target:.2f} (tighten sub)",
     ))
-    descriptions.append(f"Reduce {bass['name']} volume to 0.58")
+    descriptions.append(f"Reduce {bass['name']} volume to {target:.2f}")
 
     # Step 3: Verify
     steps.append(CompiledStep(
@@ -146,7 +205,13 @@ def _compile_tighten_low_end(move: SemanticMove, kernel: dict) -> CompiledPlan:
 
 
 def _compile_widen_stereo(move: SemanticMove, kernel: dict) -> CompiledPlan:
-    """Compile 'widen_stereo': pan harmonic elements wider, add depth."""
+    """Compile 'widen_stereo': pan harmonic elements wider, add depth.
+
+    Fallback: when no lead/harmonic tracks are role-classified (e.g., tracks
+    are named "Q-Call"/"A-Answer" which don't match role keywords), fall back
+    to widening prominent non-drum / non-bass tracks. This prevents the move
+    from no-opping on mixes with unusually-named tracks.
+    """
     steps = []
     warnings = []
     descriptions = []
@@ -155,35 +220,73 @@ def _compile_widen_stereo(move: SemanticMove, kernel: dict) -> CompiledPlan:
     lead_tracks = resolvers.find_tracks_by_role(kernel, ["lead"])
     perc_tracks = resolvers.find_tracks_by_role(kernel, ["percussion"])
 
+    # Fallback: if no harmonic/lead tracks found via role, use prominent
+    # non-drum/non-bass tracks (any role except drums/bass/fx/unknown=skip).
+    # This covers real-world mixes where melodic tracks are named after their
+    # musical function ("Q-Call", "A-Answer", "Melody 1") rather than role keywords.
+    using_fallback = False
     if not chord_tracks and not lead_tracks:
-        warnings.append("No harmonic or lead tracks found for stereo widening")
-
-    # Pan chords left
+        all_tracks = resolvers.find_tracks_by_role(
+            kernel, ["chords", "pad", "lead", "percussion", "fx", "unknown"]
+        )
+        # Exclude drums and bass by collecting everything non-drum/non-bass
+        exclude_roles = {"drums", "bass"}
+        all_raw_tracks = kernel.get("session_info", {}).get("tracks", [])
+        fallback_tracks = [
+            {
+                "index": t.get("index", 0),
+                "name": t.get("name", ""),
+                "role": resolvers.infer_role(t.get("name", "")),
+                "volume": t.get("volume"),
+                "pan": t.get("pan"),
+                "mute": t.get("mute", False),
+                "solo": t.get("solo", False),
+            }
+            for t in all_raw_tracks
+            if resolvers.infer_role(t.get("name", "")) not in exclude_roles
+        ]
+        if fallback_tracks:
+            # Use up to first 2 as a left/right pair
+            chord_tracks = fallback_tracks[:1]
+            lead_tracks = fallback_tracks[1:2]
+            using_fallback = True
+            warnings.append(
+                "No harmonic or lead tracks found by role — "
+                "falling back to widening prominent non-drum/non-bass tracks: "
+                + ", ".join(t["name"] for t in fallback_tracks[:2])
+            )
+        else:
+            warnings.append("No harmonic, lead, or wideable tracks found — no changes")
+
+    # Pan chords/first-fallback left
     for ct in chord_tracks[:1]:
         steps.append(CompiledStep(
             tool="set_track_pan",
             params={"track_index": ct["index"], "pan": -0.35},
-            description=f"Pan {ct['name']} left (-35%) for width",
+            description=f"Pan {ct['name']} left (-35%) for width"
+            + (" [fallback]" if using_fallback else ""),
         ))
         descriptions.append(f"Pan {ct['name']} left 35%")
 
-    # Pan lead right
+    # Pan lead/second-fallback right
     for lt in lead_tracks[:1]:
         steps.append(CompiledStep(
             tool="set_track_pan",
             params={"track_index": lt["index"], "pan": 0.30},
-            description=f"Pan {lt['name']} right (+30%) for width",
+            description=f"Pan {lt['name']} right (+30%) for width"
+            + (" [fallback]" if using_fallback else ""),
         ))
         descriptions.append(f"Pan {lt['name']} right 30%")
 
-    # Pan perc slightly
-    for pt in perc_tracks[:1]:
-        steps.append(CompiledStep(
-            tool="set_track_pan",
-            params={"track_index": pt["index"], "pan": 0.15},
-            description=f"Pan {pt['name']} slightly right (+15%)",
-        ))
-        descriptions.append(f"Pan {pt['name']} slightly right")
+    # Pan perc slightly (only when using primary role classification)
+    if not using_fallback:
+        for pt in perc_tracks[:1]:
+            steps.append(CompiledStep(
+                tool="set_track_pan",
+                params={"track_index": pt["index"], "pan": 0.15},
+                description=f"Pan {pt['name']} slightly right (+15%)",
+            ))
+            descriptions.append(f"Pan {pt['name']} slightly right")
 
     # Verify
     steps.append(CompiledStep(
@@ -217,13 +320,17 @@ def _compile_darken_mix(move: SemanticMove, kernel: dict) -> CompiledPlan:
     bright_tracks = resolvers.find_tracks_by_role(kernel, ["lead", "chords", "percussion"])
 
     for bt in bright_tracks[:2]:  # Max 2 tracks
-        # Reduce volume slightly to darken
+        # Reduce volume slightly to darken — RELATIVE nudge (P2-21), floored
+        # so an already-quiet bright track doesn't get pulled to silence.
+        target = resolvers.compile_relative_volume(
+            bt.get("volume"), -10, floor=0.20, fallback=0.40
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": bt["index"], "volume": 0.40},
-            description=f"Pull {bt['name']} to 0.40 for darker tone",
+            params={"track_index": bt["index"], "volume": target},
+            description=f"Pull {bt['name']} to {target:.2f} for darker tone",
         ))
-        descriptions.append(f"Darken {bt['name']} to 0.40")
+        descriptions.append(f"Darken {bt['name']} to {target:.2f}")
 
     steps.append(CompiledStep(
         tool="get_track_meters",
@@ -288,12 +395,16 @@ def _compile_reduce_repetition(move: SemanticMove, kernel: dict) -> CompiledPlan
 
 
 def _compile_make_kick_bass_lock(move: SemanticMove, kernel: dict) -> CompiledPlan:
-    """Compile 'make_kick_bass_lock': carve space between kick and bass.
-
-    Strategy: reduce bass level slightly (clears sub for kick), verify both
-    tracks remain active. Sidechain compressor insertion is left as a future
-    step — it requires device selection + parameter mapping that varies too
-    much across projects to hardcode safely.
+    """Compile 'make_kick_bass_lock': carve frequency space between kick and bass.
+
+    Strategy (real frequency separation + timing):
+      1. Read bass EQ/filter state first so we know what's already there.
+      2. Insert an EQ Eight on the bass track (or use an existing one) and
+         apply a high-pass shelf dip in the kick's fundamental band (40-80 Hz)
+         to clear sub space for the kick.
+      3. Set up a sidechain compressor on the bass keyed from the kick track
+         so bass ducks on every kick hit — the defining "lock" gesture.
+      4. Optional: minor volume trim only if needed after the above two steps.
     """
     steps: list[CompiledStep] = []
     warnings: list[str] = []
@@ -319,18 +430,124 @@ def _compile_make_kick_bass_lock(move: SemanticMove, kernel: dict) -> CompiledPl
 
     if bass_tracks:
         bass = bass_tracks[0]
-        idx = bass["index"]
+        bass_idx = bass["index"]
+
+        # Step: read bass device chain state before touching it
         steps.append(CompiledStep(
-            tool="set_track_volume",
-            params={"track_index": idx, "volume": 0.60},
-            description=f"Pull {bass['name']} to 0.60 to clear sub for kick",
+            tool="get_device_parameters",
+            params={"track_index": bass_idx, "device_index": 0},
+            description=f"Read {bass['name']} device chain state before carving",
+            verify_after=False,
+            optional=True,
         ))
-        descriptions.append(f"Pull {bass['name']} to 0.60")
+
+        # Frequency separation: carve a high-pass into an EQ on the bass so the
+        # kick's sub-fundamental has room. We only write EQ band parameters when
+        # the kernel already exposes a resolvable EQ device on this track — a
+        # device inserted in THIS plan has no known index at compile time, so a
+        # device_index=0 write would be a blind (wrong-device) target. See
+        # tests/test_compiler_safety_contract.py for the invariant this honors.
+        eq_idx = _find_eq_device_index(_kernel_track(kernel, bass_idx))
+        if eq_idx is not None:
+            # EQ confirmed present in the kernel snapshot → safe to carve it.
+            # EQ Eight band 1: "1 FilterType" (0 = Low Cut / High-pass),
+            # "1 Frequency" (Hz).
+            steps.append(CompiledStep(
+                tool="set_device_parameter",
+                params={
+                    "track_index": bass_idx,
+                    "device_index": eq_idx,
+                    "parameter_name": "1 FilterType",
+                    "value": 0.0,  # Low Cut / High-pass
+                },
+                description=f"Set EQ band 1 to High-Pass on {bass['name']} (device {eq_idx})",
+            ))
+            steps.append(CompiledStep(
+                tool="set_device_parameter",
+                params={
+                    "track_index": bass_idx,
+                    "device_index": eq_idx,
+                    "parameter_name": "1 Frequency",
+                    "value": 60.0,   # 60 Hz — clears kick sub without losing bass body
+                },
+                description=f"Set HP cutoff to 60 Hz on {bass['name']} EQ (device {eq_idx})",
+            ))
+            descriptions.append("HP carve @ 60 Hz on existing EQ")
+        else:
+            # No resolvable EQ → insert one as a scaffold. The HP-carve must be
+            # applied AFTER insertion (the new device's index isn't known until
+            # runtime); the sidechain below provides the timing lock regardless.
+            steps.append(CompiledStep(
+                tool="insert_device",
+                params={
+                    "track_index": bass_idx,
+                    "device_name": "EQ Eight",
+                    "position": 0,
+                },
+                description=f"Insert EQ Eight on {bass['name']} for kick-sub carve",
+            ))
+            descriptions.append(f"EQ Eight on {bass['name']}")
+            warnings.append(
+                f"Apply a band-1 high-pass (~60 Hz) to the new EQ on "
+                f"{bass['name']} after insertion — device index is not "
+                "resolvable at plan time."
+            )
+
+        # Timing lock: sidechain a compressor on the bass, keyed from the kick,
+        # so the bass ducks on every kick hit. The real compressor_set_sidechain
+        # tool only ROUTES the detector input on an EXISTING compressor
+        # (signature: track_index, device_index, source_type, source_channel —
+        # it does NOT set threshold/ratio/attack/release). So resolve a
+        # compressor from the kernel snapshot or insert one as a scaffold (its
+        # post-insert index isn't known at plan time → no blind device writes).
+        if kick_tracks:
+            kick = kick_tracks[0]
+            comp_idx = _find_compressor_device_index(_kernel_track(kernel, bass_idx))
+            if comp_idx is not None:
+                steps.append(CompiledStep(
+                    tool="set_device_parameter",
+                    params={
+                        "track_index": bass_idx,
+                        "device_index": comp_idx,
+                        "parameter_name": "S/C On",
+                        "value": 1.0,
+                    },
+                    description=f"Enable sidechain on {bass['name']} compressor (device {comp_idx})",
+                ))
+                steps.append(CompiledStep(
+                    tool="compressor_set_sidechain",
+                    params={
+                        "track_index": bass_idx,
+                        "device_index": comp_idx,
+                        "source_type": kick["name"],
+                        "source_channel": "Post FX",
+                    },
+                    description=(
+                        f"Route {kick['name']} into {bass['name']} compressor "
+                        "sidechain — bass ducks on every kick hit"
+                    ),
+                ))
+                descriptions.append(f"Sidechain {bass['name']} ← {kick['name']}")
+            else:
+                steps.append(CompiledStep(
+                    tool="insert_device",
+                    params={
+                        "track_index": bass_idx,
+                        "device_name": "Compressor",
+                    },
+                    description=f"Insert Compressor on {bass['name']} for kick sidechain",
+                ))
+                descriptions.append(f"Compressor on {bass['name']}")
+                warnings.append(
+                    f"After inserting the Compressor on {bass['name']}, enable "
+                    f"'S/C On' and route {kick['name']} (Post FX) into its "
+                    "sidechain — device index is not resolvable at plan time."
+                )
 
     steps.append(CompiledStep(
         tool="get_track_meters",
         params={"include_stereo": True},
-        description="Verify kick and bass both still producing audio",
+        description="Verify kick and bass both still producing audio after carve",
     ))
 
     return CompiledPlan(
@@ -367,23 +584,31 @@ def _compile_create_buildup_tension(move: SemanticMove, kernel: dict) -> Compile
     if not perc_tracks and not harmony_tracks:
         warnings.append("No percussion or harmony tracks found — cannot build tension")
 
-    # Raise perc for energy
+    # Raise perc for energy — RELATIVE nudge (P2-21), capped so an already
+    # hot perc bus doesn't clip.
     for pt in perc_tracks[:1]:
+        target = resolvers.compile_relative_volume(
+            pt.get("volume"), 10, cap=0.90, fallback=0.78
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": pt["index"], "volume": 0.78},
-            description=f"Push {pt['name']} to 0.78 for rising energy",
+            params={"track_index": pt["index"], "volume": target},
+            description=f"Push {pt['name']} to {target:.2f} for rising energy",
         ))
-        descriptions.append(f"Push {pt['name']} to 0.78")
+        descriptions.append(f"Push {pt['name']} to {target:.2f}")
 
-    # Pull harmony slightly to amplify perc contrast
+    # Pull harmony slightly to amplify perc contrast — RELATIVE nudge,
+    # floored so a quiet harmony bed doesn't get pulled to silence.
     for ht in harmony_tracks[:1]:
+        target = resolvers.compile_relative_volume(
+            ht.get("volume"), -12, floor=0.20, fallback=0.35
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": ht["index"], "volume": 0.35},
-            description=f"Pull {ht['name']} to 0.35 to create harmonic vacuum before drop",
+            params={"track_index": ht["index"], "volume": target},
+            description=f"Pull {ht['name']} to {target:.2f} to create harmonic vacuum before drop",
         ))
-        descriptions.append(f"Pull {ht['name']} to 0.35")
+        descriptions.append(f"Pull {ht['name']} to {target:.2f}")
 
     steps.append(CompiledStep(
         tool="get_track_meters",

package/mcp_server/semantic_moves/performance_compilers.py

@@ -19,21 +19,33 @@ def _compile_recover_energy(move: SemanticMove, kernel: dict) -> CompiledPlan:
     drum_tracks = resolvers.find_tracks_by_role(kernel, ["drums", "percussion"])
     bass_tracks = resolvers.find_tracks_by_role(kernel, ["bass"])
 
+    # RELATIVE nudge (P2-21 pattern, ported from resolvers.compile_relative_volume
+    # / mix_compilers.py): "recover" means push UP from wherever the track
+    # already sits, not overwrite it with a flat absolute level — a drum bus
+    # already sitting hot must not get pulled DOWN to 0.70. Live-set-safe:
+    # small +12% nudge, capped just above the historical fallback so a
+    # recovering track lands in the same ballpark it always did.
     for dt in drum_tracks[:1]:
+        target = resolvers.compile_relative_volume(
+            dt.get("volume"), 12, cap=0.78, fallback=0.70
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": dt["index"], "volume": 0.70},
-            description=f"Restore {dt['name']} to 0.70 for energy recovery",
+            params={"track_index": dt["index"], "volume": target},
+            description=f"Restore {dt['name']} to {target:.2f} for energy recovery",
         ))
-        descriptions.append(f"Restore {dt['name']} to 0.70")
+        descriptions.append(f"Restore {dt['name']} to {target:.2f}")
 
     for bt in bass_tracks[:1]:
+        target = resolvers.compile_relative_volume(
+            bt.get("volume"), 12, cap=0.68, fallback=0.60
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": bt["index"], "volume": 0.60},
-            description=f"Restore {bt['name']} to 0.60",
+            params={"track_index": bt["index"], "volume": target},
+            description=f"Restore {bt['name']} to {target:.2f}",
         ))
-        descriptions.append(f"Restore {bt['name']} to 0.60")
+        descriptions.append(f"Restore {bt['name']} to {target:.2f}")
 
     # Pull reverb back to tighten
     pad_tracks = resolvers.find_tracks_by_role(kernel, ["pad", "chords"])
@@ -69,13 +81,19 @@ def _compile_decompress_tension(move: SemanticMove, kernel: dict) -> CompiledPla
     lead_tracks = resolvers.find_tracks_by_role(kernel, ["lead", "chords"])
     pad_tracks = resolvers.find_tracks_by_role(kernel, ["pad"])
 
+    # RELATIVE nudge (P2-21 pattern) — "decompress" means pull DOWN from the
+    # current level, floored so an already-quiet lead doesn't get pulled
+    # toward silence. Small -12% nudge, live-set-safe.
     for lt in lead_tracks[:2]:
+        target = resolvers.compile_relative_volume(
+            lt.get("volume"), -12, floor=0.20, fallback=0.35
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": lt["index"], "volume": 0.35},
-            description=f"Pull {lt['name']} to 0.35 for decompression",
+            params={"track_index": lt["index"], "volume": target},
+            description=f"Pull {lt['name']} to {target:.2f} for decompression",
         ))
-        descriptions.append(f"Pull {lt['name']} to 0.35")
+        descriptions.append(f"Pull {lt['name']} to {target:.2f}")
 
     for pt in pad_tracks[:1]:
         steps.append(CompiledStep(
@@ -121,7 +139,9 @@ def _compile_safe_spotlight(move: SemanticMove, kernel: dict) -> CompiledPlan:
     spotlight_idx = spotlight.get("index", 0)
     spotlight_name = spotlight.get("name", f"Track {spotlight_idx}")
 
-    # Pull non-spotlight audio tracks
+    # Pull non-spotlight audio tracks — RELATIVE nudge (P2-21 pattern),
+    # floored so an already-quiet background track doesn't get pulled
+    # toward silence.
     for track in all_tracks:
         idx = track.get("index", 0)
         name = track.get("name", "")
@@ -129,17 +149,24 @@ def _compile_safe_spotlight(move: SemanticMove, kernel: dict) -> CompiledPlan:
             continue
         if track.get("type") in ("return", "master"):
             continue
+        target = resolvers.compile_relative_volume(
+            track.get("volume"), -15, floor=0.15, fallback=0.30
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": idx, "volume": 0.30},
-            description=f"Pull {name} to 0.30 (background)",
+            params={"track_index": idx, "volume": target},
+            description=f"Pull {name} to {target:.2f} (background)",
         ))
 
-    # Push spotlight
+    # Push spotlight — RELATIVE nudge, capped just above the historical
+    # fallback so the spotlight lands in the same ballpark it always did.
+    spotlight_target = resolvers.compile_relative_volume(
+        spotlight.get("volume"), 10, cap=0.85, fallback=0.82
+    )
     steps.append(CompiledStep(
         tool="set_track_volume",
-        params={"track_index": spotlight_idx, "volume": 0.82},
-        description=f"Push spotlight {spotlight_name} to 0.82",
+        params={"track_index": spotlight_idx, "volume": spotlight_target},
+        description=f"Push spotlight {spotlight_name} to {spotlight_target:.2f}",
     ))
     descriptions.append(f"Spotlight {spotlight_name}")
 
@@ -176,10 +203,17 @@ def _compile_emergency_simplify(move: SemanticMove, kernel: dict) -> CompiledPla
             continue
         if idx in keep_indices:
             continue
+        # RELATIVE nudge (P2-21 pattern) — "emergency simplify" genuinely
+        # means strip aggressively, so the delta is intentionally large
+        # (-25%), but still bounded (floor=0.05) and direction-safe: a
+        # track already quieter than 0.05 doesn't get nudged back UP.
+        target = resolvers.compile_relative_volume(
+            track.get("volume"), -25, floor=0.05, fallback=0.10
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": idx, "volume": 0.10},
-            description=f"Strip {name} to 0.10 (emergency simplify)",
+            params={"track_index": idx, "volume": target},
+            description=f"Strip {name} to {target:.2f} (emergency simplify)",
         ))
 
     descriptions.append("Strip to drums+bass only")

package/mcp_server/semantic_moves/resolvers.py

@@ -124,3 +124,48 @@ def adjust_volume(current: float, delta_percent: float) -> float:
     """Adjust a volume by a percentage. delta_percent=5 means +5%."""
     new = current + (delta_percent / 100.0)
     return clamp_volume(new)
+
+
+def compile_relative_volume(
+    current: Optional[float],
+    delta_percent: float,
+    *,
+    cap: Optional[float] = None,
+    floor: Optional[float] = None,
+    fallback: float,
+) -> float:
+    """Compile a bounded RELATIVE volume nudge from a track's current level.
+
+    P2-21 fix: mix/sound-design/transition compilers used to write an
+    ABSOLUTE volume regardless of what was already on the track — e.g.
+    "make it punchier" could turn a hot drum bus DOWN by blindly writing
+    a flat 0.75. This computes current + delta_percent% instead (via
+    adjust_volume), then clamps to an optional cap/floor so the move's
+    musical intent (push toward louder / pull toward quieter) still holds
+    even when starting from an unusual level.
+
+    `current` is None when the connected Remote Script predates the
+    `volume` field in get_session_info (see transport.py get_session_info)
+    — in that case this falls back to the historical absolute value so
+    the compiler degrades gracefully instead of crashing or guessing.
+
+    The cap/floor bound the SIZE of the nudge — they must never flip its
+    DIRECTION. A track already louder than `cap` must not get pulled back
+    down to the cap when the move means to push it UP (that would
+    reintroduce the P2-21 bug in a smaller way); symmetrically a track
+    already quieter than `floor` must not get nudged back UP when the
+    move means to pull it DOWN. So after clamping to [floor, cap], the
+    result is re-clamped against `current` in the direction of travel.
+    """
+    if current is None:
+        return fallback
+    target = adjust_volume(current, delta_percent)
+    if cap is not None:
+        target = min(target, cap)
+    if floor is not None:
+        target = max(target, floor)
+    if delta_percent > 0:
+        target = max(target, current)
+    elif delta_percent < 0:
+        target = min(target, current)
+    return clamp_volume(target)

package/mcp_server/semantic_moves/sound_design_compilers.py

@@ -33,11 +33,15 @@ def _compile_add_warmth(move: SemanticMove, kernel: dict) -> CompiledPlan:
         idx = t["index"]
         name = t["name"]
 
-        # Boost volume slightly for perceived warmth
+        # Boost volume slightly for perceived warmth — RELATIVE nudge
+        # (P2-21), capped so an already-hot track isn't pushed toward clip.
+        target = resolvers.compile_relative_volume(
+            t.get("volume"), 6, cap=0.80, fallback=0.65
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": idx, "volume": 0.65},
-            description=f"Boost {name} slightly for warmth",
+            params={"track_index": idx, "volume": target},
+            description=f"Boost {name} to {target:.2f} for warmth",
         ))
 
         # Add reverb send for depth/warmth perception
@@ -138,11 +142,15 @@ def _compile_shape_transients(move: SemanticMove, kernel: dict) -> CompiledPlan:
         idx = dt["index"]
         name = dt["name"]
 
-        # Push volume for transient punch
+        # Push volume for transient punch — RELATIVE nudge (P2-21), capped
+        # so an already-hot drum bus isn't pushed toward clip.
+        target = resolvers.compile_relative_volume(
+            dt.get("volume"), 8, cap=0.85, fallback=0.75
+        )
         steps.append(CompiledStep(
             tool="set_track_volume",
-            params={"track_index": idx, "volume": 0.75},
-            description=f"Push {name} to 0.75 for transient punch",
+            params={"track_index": idx, "volume": target},
+            description=f"Push {name} to {target:.2f} for transient punch",
         ))
         descriptions.append(f"Push {name} for punch")