livepilot 1.27.1 → 1.27.3

package/mcp_server/sample_engine/tools.py

@@ -222,15 +222,13 @@ async def search_samples(
 ) -> dict:
     """Search for samples across Splice library, Ableton browser, and local filesystem.
 
-    Searches all enabled sources in parallel and ranks results.
-    Splice results include rich metadata (key, BPM, genre, tags, pack info,
-    is_premium, price, is_free, preview_url).
+    Searches all enabled sources in parallel, ranked Splice-first, then
+    browser, then filesystem. Splice results carry key/BPM/genre/tags/
+    pack/is_premium/price/is_free/preview_url metadata.
 
-    When the Splice desktop app is running AND grpcio is installed, this
-    searches Splice's ONLINE catalog (19,690+ hits for a generic query)
-    and returns un-downloaded items alongside local files. When gRPC is
-    unavailable, it falls back to the local SQLite index and only returns
-    already-downloaded samples.
+    With the Splice desktop app running + grpcio installed: searches
+    Splice's ONLINE catalog, returning un-downloaded items too. Without
+    gRPC: falls back to the local SQLite index (downloaded samples only).
 
     query: search text like "dark vocal", "breakbeat", "foley metal"
     q: alias for `query` (accepts either name for ergonomics)
@@ -776,24 +774,12 @@ async def get_splice_credits(ctx: Context) -> dict:
     Returns both pockets of the Splice subscription model:
       - `credits_remaining`: Splice.com credits for presets/MIDI/Instrument
       - `daily_quota`: sample-download counter (Ableton Live plan only)
+      - `download_gating`: "daily_quota" (Ableton Live plan) or
+        "credit_floor" (Sounds+/Creator/Creator+ — protects the last
+        CREDIT_HARD_FLOOR credits)
 
-    Example (Ableton Live plan):
-      {
-        "connected": true,
-        "username": "user-1367453956",
-        "plan_raw": "subscribed",
-        "plan_kind": "ableton_live",
-        "sounds_plan_id": 12,
-        "features": {"ableton_unmetered": true, ...},
-        "credits_remaining": 80,
-        "credit_floor": 5,
-        "daily_quota": {
-            "used_today": 3, "remaining_today": 97, "daily_limit": 100,
-            "near_limit": false, "at_limit": false,
-        },
-        "can_download_sample": true,
-        "download_gating": "daily_quota",  # or "credit_floor"
-      }
+    Full example response: livepilot-sample-engine references/
+    splice-tools-notes.md#get_splice_credits--full-response-example-ableton-live-plan.
 
     Returns connected=False (with zero credits) when the Splice desktop app
     isn't running or grpcio isn't installed.
@@ -1538,12 +1524,9 @@ async def splice_describe_sound(
     """Natural-language sample search — the Sounds Plugin's "Describe a Sound".
 
     Splice's AI matches free-form descriptions like "dark ambient pad with
-    shimmer" or "tight 90s house hi-hat" to catalog samples. Hits the
-    GraphQL `SamplesSearch` operation on `surfaces-graphql.splice.com`
-    with `semantic=1` + `rephrase=true` enabled.
-
-    **Status: LIVE** as of 2026-04-22. Endpoint captured via mitmproxy
-    against Splice desktop 5.4.9 + Sounds Plugin.
+    shimmer" or "tight 90s house hi-hat" to catalog samples. Endpoint
+    history: livepilot-sample-engine references/splice-tools-notes.md
+    #splice_describe_sound--splice_generate_variation--endpoint-history.
 
     description: free-text prompt ("warm analog bass under 80bpm")
     bpm:         optional BPM filter
@@ -1590,13 +1573,11 @@ async def splice_generate_variation(
     """Find catalog samples similar to a given Splice sample — the "Variations" feature.
 
     Splice's right-click "Variations" menu item surfaces other catalog
-    samples with similar sonic character. The GraphQL operation name
-    is `AssetSimilarSoundsQuery`. Up to 10 results per call. No credit
-    cost (this is a recommender lookup, not AI audio synthesis — the
-    original naming in the handoff was aspirational).
-
-    **Status: LIVE** as of 2026-04-22. Endpoint captured via mitmproxy
-    against Splice desktop v5.4.9.
+    samples with similar sonic character. Up to 10 results per call. No
+    credit cost — a recommender lookup, not AI audio synthesis (the
+    "generate" naming was aspirational). Endpoint history: livepilot-
+    sample-engine references/splice-tools-notes.md
+    #splice_describe_sound--splice_generate_variation--endpoint-history.
 
     uuid:       source sample's catalog uuid (from `splice_describe_sound`
                 results or any other Splice metadata call)

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")