livepilot 1.27.1 → 1.27.3

package/mcp_server/atlas/tools.py

@@ -43,6 +43,59 @@ def _get_atlas():
 # atlas_device_info.
 _ATLAS_SEARCH_DESCRIPTION_CHAR_CAP: int = 400
 
+# ── M4L pack-instrument URI guard (LIVE#3) ────────────────────────────────────
+# These instruments ship as Max for Live (.amxd) devices inside pack bundles
+# (Inspired by Nature, etc.).  The atlas erroneously stores them as
+# `query:Synths#<Name>` — the same scheme used for native Ableton instruments
+# (Operator, Wavetable, Collision, …).  That scheme only resolves in Live's
+# browser for *native* instruments; M4L pack instruments are NOT browsable under
+# "Synths".  Their presets (.adg racks) ARE browsable under "sounds", so agents
+# must fall back to search_browser(path="sounds", name_filter="<preset-name>").
+#
+# A device ID belongs here when ALL of the following hold:
+#   1. Its atlas URI is `query:Synths#<Name>`
+#   2. The device is an M4L / pack instrument (not a native Ableton synth engine)
+#   3. load_browser_item with the Synths# URI returns INVALID_PARAM in Live
+#
+# Do NOT add native instruments (Operator, Wavetable, Drift, Meld, Poli, etc.)
+# even if they were introduced in a later Live version — those resolve fine.
+# Add only IDs that have been *confirmed* broken in a live session.
+_M4L_PACK_SYNTH_IDS: frozenset[str] = frozenset({
+    "tree_tone",    # Inspired by Nature — M4L instrument, presets under sounds
+    "vector_fm",    # Inspired by Nature — M4L instrument, presets under sounds
+    "vector_grain", # Inspired by Nature — M4L instrument, presets under sounds
+    "emit",         # Inspired by Nature — M4L instrument, presets under sounds
+})
+
+
+def _patch_m4l_uri(entry_dict: dict, device: dict) -> dict:
+    """If this atlas entry is a known M4L pack instrument, clear the bogus
+    `query:Synths#` URI and surface a load hint instead.
+
+    Mutates *entry_dict* in-place and returns it for convenience.
+
+    Fields added / changed:
+      uri         → "" (cleared — the Synths# URI is NOT resolvable)
+      load_via    → "preset"
+      browse_hint → {"path": "sounds", "name_filter": "<device name>"}
+                    (tells the agent to call search_browser to resolve a real URI)
+    """
+    dev_id = device.get("id", "")
+    uri = entry_dict.get("uri", "")
+    if dev_id in _M4L_PACK_SYNTH_IDS and uri.startswith("query:Synths#"):
+        entry_dict["uri"] = ""
+        entry_dict["load_via"] = "preset"
+        entry_dict["browse_hint"] = {
+            "path": "sounds",
+            "name_filter": device.get("name", ""),
+            "note": (
+                "M4L pack instrument — not directly loadable via query:Synths#. "
+                "Call search_browser(path='sounds', name_filter='<preset name>') "
+                "to obtain a real URI, then load_browser_item with that URI."
+            ),
+        }
+    return entry_dict
+
 
 def _surface_enriched_fields(device: dict) -> dict:
     """Pull discoverability-critical fields from an enriched atlas entry.
@@ -80,16 +133,16 @@ def _surface_enriched_fields(device: dict) -> dict:
 def atlas_search(ctx: Context, query: str, category: str = "all", limit: int = 10) -> dict:
     """Search the device atlas for instruments, effects, kits, or plugins.
 
-    Searches BOTH:
-      1. The bundled factory atlas (5,264 devices across 33 packs)
-      2. The user-local overlay corpus (~/.livepilot/atlas-overlays/) — including
-         user-scanned Max devices, racks, plugin presets, and AI-synthesized
-         plugin identity yamls. This is the wiring that lets LivePilot reason
-         over the user's PERSONAL library, not just Ableton's defaults.
+    Searches BOTH the bundled factory atlas (5,264 devices/33 packs) AND
+    the user-local overlay corpus (~/.livepilot/atlas-overlays/ — user-
+    scanned Max devices, racks, plugin presets, AI-synthesized plugin
+    identity yamls), so results cover the user's PERSONAL library too,
+    not just Ableton's defaults. Budget-split details: livepilot-core
+    references/atlas-tool-notes.md#atlas_search--overlay-budget-split.
 
-    query:    natural language search — name, sonic character, use case, or genre
-              Examples: "warm analog bass", "reverb", "808 kit", "granular",
-                        "my arpeggiator", "the polyrhythmic sequencer in my user library"
+    query:    natural language search — name, sonic character, use case,
+              or genre. Examples: "warm analog bass", "granular",
+              "my arpeggiator in user library".
     category: filter by category (all, instruments, audio_effects, midi_effects,
               max_for_live, drum_kits, plugins). For user-corpus content, pass
               "all" — overlay entity_types are surfaced regardless of category.
@@ -155,6 +208,10 @@ def atlas_search(ctx: Context, query: str, category: str = "all", limit: int = 1
             # agent doesn't need a second atlas_device_info round-trip just
             # to find out e.g. that Granulator III isn't self-contained.
             entry_dict.update(_surface_enriched_fields(dev))
+        # LIVE#3: M4L pack instruments have a bogus query:Synths# URI in the
+        # atlas — clear it and surface a browse_hint so the caller doesn't get
+        # an INVALID_PARAM from load_browser_item.
+        _patch_m4l_uri(entry_dict, dev)
         results.append(entry_dict)
     for entry in overlay_results[:overlay_budget]:
         results.append({
@@ -169,7 +226,7 @@ def atlas_search(ctx: Context, query: str, category: str = "all", limit: int = 1
             "source": f"user_overlay:{entry.namespace}",
         })
 
-    return {
+    response: dict = {
         "query": query,
         "category": category,
         "count": len(results),
@@ -177,6 +234,14 @@ def atlas_search(ctx: Context, query: str, category: str = "all", limit: int = 1
         "overlay_count": len(overlay_results),
         "results": results,
     }
+    # P3-47: warn when this query's category overlaps a category the last
+    # scan_full_library run had to truncate — the factory results above
+    # are a lower bound for that category, not the full inventory.
+    if atlas is not None:
+        warning = atlas.truncation_warning(category)
+        if warning:
+            response["warning"] = warning
+    return response
 
 
 @mcp.tool()
@@ -195,8 +260,39 @@ def atlas_device_info(ctx: Context, device_id: str, verbose: bool = True) -> dic
     entry = atlas.lookup(device_id)
     if entry is None:
         return {"error": f"Device '{device_id}' not found in atlas", "suggestion": "Use atlas_search to find devices"}
+
+    # P2-12: an id/name can collide across multiple distinct devices (719
+    # ids / 702 names in the shipped atlas). lookup() deterministically
+    # returns the first; surface the others by their unique URI so the
+    # agent can re-query the exact variant it wants instead of getting one
+    # arbitrary match silently.
+    all_matches = atlas.lookup_all(device_id)
+    ambiguous_matches = None
+    if len(all_matches) > 1:
+        ambiguous_matches = [
+            {
+                "id": d.get("id", ""),
+                "name": d.get("name", ""),
+                "uri": d.get("uri", ""),
+                "category": d.get("category", ""),
+            }
+            for d in all_matches
+        ]
+
     if verbose:
-        return entry
+        # Patch a COPY — `entry` is the live in-memory atlas record; mutating it
+        # would corrupt the shared atlas. _patch_m4l_uri clears the bogus
+        # query:Synths# URI for M4L pack instruments (LIVE#3) so a direct
+        # atlas_device_info lookup doesn't hand the agent an unloadable URI.
+        if ambiguous_matches is not None:
+            result = _patch_m4l_uri(dict(entry), entry)
+            result["ambiguous_matches"] = ambiguous_matches
+            result["ambiguous_note"] = (
+                f"'{device_id}' matches {len(all_matches)} devices; showing the "
+                "first. Re-query by a unique uri to target a specific one."
+            )
+            return result
+        return _patch_m4l_uri(dict(entry), entry)
     # Compact mode: the common case doesn't need the full multi-KB record.
     # Truncate the longest free-text fields the way atlas_search already caps
     # sonic_description, and report counts for list-heavy fields so the caller
@@ -217,6 +313,14 @@ def atlas_device_info(ctx: Context, device_id: str, verbose: bool = True) -> dic
     }
     summary.update(_surface_enriched_fields(entry))
     summary["verbose_available"] = True
+    # LIVE#3: clear bogus query:Synths# URI for M4L pack instruments here too.
+    _patch_m4l_uri(summary, entry)
+    if ambiguous_matches is not None:
+        summary["ambiguous_matches"] = ambiguous_matches
+        summary["ambiguous_note"] = (
+            f"'{device_id}' matches {len(all_matches)} devices; showing the "
+            "first. Re-query by a unique uri to target a specific one."
+        )
     return summary
 
 
@@ -240,21 +344,32 @@ def atlas_suggest(
         return {"error": "Atlas not loaded. Run scan_full_library first."}
 
     results = atlas.suggest(intent, genre=genre, energy=energy)
-    return {
+    suggestions = []
+    for r in results:
+        dev = r["device"]
+        suggestion: dict = {
+            "device_id": dev["id"],
+            "device_name": dev["name"],
+            "uri": dev.get("uri", ""),
+            "rationale": r["rationale"],
+            "recipe": r.get("recipe"),
+        }
+        # LIVE#3: patch out bogus query:Synths# URIs for M4L pack instruments
+        _patch_m4l_uri(suggestion, dev)
+        suggestions.append(suggestion)
+    response: dict = {
         "intent": intent,
         "genre": genre,
         "energy": energy,
-        "suggestions": [
-            {
-                "device_id": r["device"]["id"],
-                "device_name": r["device"]["name"],
-                "uri": r["device"].get("uri", ""),
-                "rationale": r["rationale"],
-                "recipe": r.get("recipe"),
-            }
-            for r in results
-        ],
+        "suggestions": suggestions,
     }
+    # P3-47: suggest() searches across every category internally, so warn
+    # like an unfiltered ("all") search would if the last scan truncated
+    # any category — the ranked candidates above may be missing devices.
+    warning = atlas.truncation_warning("all")
+    if warning:
+        response["warning"] = warning
+    return response
 
 
 @mcp.tool()
@@ -332,33 +447,25 @@ def atlas_describe_chain(
     genre: str = "",
     limit_per_role: int = 3,
 ) -> dict:
-    """Free-text describe-a-chain: "a granular pad that sounds like Tim Hecker"
-    → device chain proposal.
+    """Free-text describe-a-chain: a sentence like "a warm analog bass for
+    deep dubby techno" → device chain proposal.
 
     The mirror of `splice_describe_sound` for the device library. Where
-    `atlas_chain_suggest(role, genre)` takes structured inputs, this takes
-    a free-form sentence and proposes a chain by:
-
-      1. Parsing role hints from the description ("bass", "pad", "lead",
-         "percussion", "drum", "texture", "vocal", "keys")
-      2. Parsing aesthetic hints (artist names → `artist-vocabularies.md`,
-         genre names → `genre-vocabularies.md`, character words → atlas tags)
-      3. Searching the atlas with those terms
-      4. Proposing the top devices per role with brief rationale
-
-    This does NOT autoload anything — it returns a proposal the caller can
-    review, adjust, then execute with `load_browser_item` + a chain of FX.
-
-    description: free text. Examples:
-        "a granular pad that sounds like Tim Hecker"
-        "warm analog bass for minimal techno, deep and dubby"
-        "chopped vocal melody, Akufen-style microhouse"
-        "brittle mallet percussion with long reverb, Stars of the Lid territory"
+    `atlas_chain_suggest(role, genre)` takes structured inputs, this
+    detects role + aesthetic cues from free text, searches the atlas,
+    and proposes top devices per role. Internals: livepilot-core
+    references/atlas-tool-notes.md#atlas_describe_chain--internals.
+
+    This does NOT autoload anything — it returns a proposal the caller
+    reviews/adjusts, then executes with `load_browser_item` + FX.
+
+    description: free text mixing role + aesthetic cues, e.g. "a granular
+        pad, dark and dubby" or "chopped vocal melody, microhouse".
     genre:       optional genre bias if the description is genre-agnostic
     limit_per_role: max devices to suggest per detected role (default 3)
 
     Returns {description, detected_roles, detected_aesthetic,
-             per_role_suggestions: [...], chain_proposal: [...]}.
+             per_role_suggestions: [...], chain_proposal: [...], next_steps}.
     """
     atlas = _get_atlas()
     if atlas is None:
@@ -461,17 +568,23 @@ def atlas_describe_chain(
             energy="medium",
             limit=int(limit_per_role),
         )
-        factory_suggestions = [
-            {
-                "device_id": r["device"].get("id", ""),
-                "device_name": r["device"].get("name", ""),
-                "uri": r["device"].get("uri", ""),
+        factory_suggestions = []
+        for r in results:
+            dev = r["device"]
+            entry = {
+                "device_id": dev.get("id", ""),
+                "device_name": dev.get("name", ""),
+                "uri": dev.get("uri", ""),
                 "rationale": r.get("rationale", ""),
                 "recipe": r.get("recipe"),
                 "source": "factory_atlas",
             }
-            for r in results
-        ]
+            # LIVE#3: clear the bogus query:Synths# URI for M4L pack instruments
+            # here too (same atlas.suggest backend atlas_suggest sanitizes). The
+            # chain_proposal block below reads top["uri"] from these entries, so
+            # patching here propagates automatically.
+            _patch_m4l_uri(entry, dev)
+            factory_suggestions.append(entry)
 
         # Query overlay namespaces for matching user-corpus devices
         overlay_hits = []
@@ -553,29 +666,22 @@ def atlas_describe_chain(
 def atlas_techniques_for_device(ctx: Context, device_id: str) -> dict:
     """Reverse-lookup: what techniques / principles reference this device?
 
-    Answers questions like "what can I do with Granulator III?" by returning
-    every technique across the knowledge base that mentions this device —
-    the device's own `signature_techniques`, sample-manipulation principles
-    that use it, sound-design-deep.md references. Complements
-    `atlas_device_info` (which returns the device's own curated fields) by
-    showing the device's OUTWARD connections — how it fits into techniques
-    that weren't written from the device's perspective.
+    Answers "what can I do with this device?" by returning every
+    technique across the knowledge base that mentions it. Complements
+    `atlas_device_info` (the device's own curated fields) by showing its
+    OUTWARD connections. Index details: livepilot-core references/
+    atlas-tool-notes.md#atlas_techniques_for_device--index.
 
     device_id: atlas ID (e.g. "granulator_iii", "simpler", "analog"). Use
                `atlas_search` or `atlas_device_info` to discover IDs.
 
     Returns {device_id, technique_count, techniques: [...]}, where each
     technique entry has:
-      - technique: short name (e.g. "Vocal micro-chop (Akufen)")
-      - description: one-line
+      - technique: short name, description: one-line
       - aesthetic: list of aesthetic/genre tags
-      - source: where this technique lives (`atlas/<id>`,
-                `sample-techniques.md`, `sound-design-deep.md`)
+      - source: originating doc (`atlas/<id>`, `sample-techniques.md`,
+                `sound-design-deep.md`)
       - kind: signature_technique | sample_technique | sound_design_principle
-
-    Index is auto-generated from the knowledge base; regenerate via the
-    companion script when adding new techniques (rare — most additions
-    happen through enrichment YAMLs, which the index reads directly).
     """
     import json, os
     index_path = os.path.join(
@@ -653,27 +759,31 @@ def atlas_pack_info(ctx: Context, pack_name: str = "") -> dict:
 def scan_full_library(
     ctx: Context,
     force: bool = False,
-    max_per_category: int = 5000,
+    max_per_category: int = 25000,
 ) -> dict:
     """Scan the full Ableton browser and rebuild the device atlas.
 
     Walks every category (instruments, audio_effects, midi_effects, max_for_live,
     drums, plugins, packs) and records every loadable item with its URI.
-    Results are merged with curated enrichments and saved to device_atlas.json.
+    Results are merged with curated enrichments and saved to the user
+    atlas path (~/.livepilot/atlas/device_atlas.json — never the bundled
+    baseline).
 
-    force: if True, rescan even if atlas already exists (default False)
-    max_per_category: ceiling per category (default 5000). The previous
-        hardcoded 1000 cap silently truncated large categories — for
-        example, the samples category alone has ~22,000 items per the
-        browser tree, so the reported count "1000 samples" was wrong by
-        a factor of 22 (BUG-2026-04-22 #12). Raise this if your library
-        is huge; lower it for fast smoke scans.
+    force: if True, rescan even if a recent (<24h) atlas already exists
+        (default False)
+    max_per_category: ceiling per category (default 25000). Raise this
+        further for very large libraries; lower it for fast smoke scans.
+        Cap-sizing history: livepilot-core references/
+        atlas-tool-notes.md#scan_full_library--scan-cap-history.
 
     Returns a stats dict including `truncated_categories` listing any
     category that hit the cap (so callers know the count is a lower
-    bound rather than the true total).
+    bound rather than the true total), also folded into
+    `stats.category_truncated` and persisted into device_atlas.json so
+    AtlasManager can warn future atlas_search/atlas_suggest calls that
+    touch a truncated category without requiring a fresh scan first.
     """
-    from .scanner import normalize_scan_results
+    from .scanner import normalize_scan_results, _CATEGORY_MAP
     from .enrichments import load_enrichments, merge_enrichments
     from . import AtlasManager, USER_ATLAS_DIR, USER_ATLAS_PATH
 
@@ -711,17 +821,34 @@ def scan_full_library(
     # Normalize
     devices = normalize_scan_results(raw)
 
-    # Detect truncation: per-category count == cap means we likely hit it.
-    truncated_categories = []
+    # Detect truncation (P3-47). Prefer the explicit `category_truncated`
+    # map emitted by scan_browser_deep on updated remote scripts — it
+    # correctly flags a category as truncated both when it hit
+    # max_per_category directly AND when the shared iteration safety bound
+    # cut the scan short mid-category. Older (pre-update) remote scripts
+    # only echo a `counts`/`stats` mapping of ints, so fall back to the
+    # count>=cap heuristic in that case.
+    truncated_categories: list = []
+    raw_category_truncated: dict = {}
     if isinstance(raw, dict):
-        per_cat = raw.get("counts") or raw.get("stats") or {}
-        if isinstance(per_cat, dict):
-            for cat, count in per_cat.items():
-                try:
-                    if int(count) >= max_per_category:
-                        truncated_categories.append(cat)
-                except (TypeError, ValueError):
-                    continue
+        explicit_truncated = raw.get("category_truncated")
+        if isinstance(explicit_truncated, dict):
+            raw_category_truncated = {
+                cat: bool(hit) for cat, hit in explicit_truncated.items()
+            }
+            truncated_categories = [
+                cat for cat, hit in raw_category_truncated.items() if hit
+            ]
+        else:
+            per_cat = raw.get("counts") or raw.get("stats") or {}
+            if isinstance(per_cat, dict):
+                for cat, count in per_cat.items():
+                    try:
+                        if int(count) >= max_per_category:
+                            truncated_categories.append(cat)
+                            raw_category_truncated[cat] = True
+                    except (TypeError, ValueError):
+                        continue
 
     # Load and merge enrichments
     enrichments = load_enrichments(enrichments_dir)
@@ -734,6 +861,19 @@ def scan_full_library(
         stats[cat] = stats.get(cat, 0) + 1
     stats["enriched_devices"] = sum(1 for d in devices if d.get("enriched"))
 
+    # Truncation observability persisted into device_atlas.json so
+    # AtlasManager can warn callers later without needing the raw scan
+    # payload. Raw browser category names (e.g. "drums", "sounds") are
+    # remapped through the scanner's category vocabulary (e.g.
+    # "drum_kits") so the flags line up with the same `category` values
+    # atlas_search / atlas_suggest actually filter on.
+    stats["category_counts"] = dict(raw.get("counts", {})) if isinstance(raw, dict) else {}
+    stats["category_truncated"] = {
+        _CATEGORY_MAP.get(raw_cat, raw_cat): True
+        for raw_cat, hit in raw_category_truncated.items()
+        if hit
+    }
+
     # Read the actual running Live version from the session rather than
     # hardcoding "12.3.6" — the hardcoded string was baking last year's
     # version into every new user's atlas until they forced a rescan.

package/mcp_server/audit/checks.py

@@ -53,18 +53,21 @@ def infer_role(track_name: str, devices: list[dict]) -> str:
 # ── §5.1 Timbre via spectrum ─────────────────────────────────────────
 
 # Loose role → expected spectrum-band dominance.
-# Uses 7-band convention: SUB_LOW, LOW, LOW_MID, MID, PRESENCE, HIGH, AIR.
+# Uses the canonical lowercase 9-band vocabulary every spectrum producer
+# emits (m4l_bridge BAND_NAMES_9 / synthesis_brain.timbre._BANDS):
+# sub_low, sub, low, low_mid, mid, high_mid, high, presence, air.
+# Comparison in check_timbre is case-folded defensively.
 _ROLE_BAND_EXPECTATIONS: dict[str, tuple[str, ...]] = {
-    "kick": ("SUB_LOW", "LOW", "MID"),
-    "snare": ("MID", "PRESENCE", "HIGH"),
-    "hat": ("PRESENCE", "HIGH", "AIR"),
-    "perc": ("MID", "PRESENCE", "HIGH"),
-    "bass": ("SUB_LOW", "LOW", "LOW_MID"),
-    "pad": ("LOW_MID", "MID", "PRESENCE"),
-    "lead": ("MID", "PRESENCE", "HIGH"),
-    "atmos": ("LOW_MID", "MID", "PRESENCE", "HIGH"),
-    "vox": ("MID", "PRESENCE", "HIGH"),
-    "fx": ("PRESENCE", "HIGH", "AIR"),
+    "kick": ("sub_low", "sub", "low", "mid"),
+    "snare": ("mid", "high_mid", "presence", "high"),
+    "hat": ("presence", "high", "air"),
+    "perc": ("mid", "high_mid", "presence", "high"),
+    "bass": ("sub_low", "sub", "low", "low_mid"),
+    "pad": ("low_mid", "mid", "high_mid", "presence"),
+    "lead": ("mid", "high_mid", "presence", "high"),
+    "atmos": ("low_mid", "mid", "high_mid", "presence", "high"),
+    "vox": ("mid", "high_mid", "presence", "high"),
+    "fx": ("presence", "high", "air"),
 }
 
 
@@ -93,10 +96,11 @@ def check_timbre(role: str, fingerprint: dict | None) -> dict:
             "issues": [],
             "evidence": {"bands": bands},
         }
-    # Find dominant band(s) — top1 is the discriminator
-    sorted_bands = sorted(bands.items(), key=lambda kv: kv[1], reverse=True)
-    top2 = [b for b, _ in sorted_bands[:2]]
-    expected_set = set(expected)
+    # Find dominant band(s) — top1 is the discriminator. Case-fold so an
+    # uppercase-emitting producer can never silently fail every comparison.
+    sorted_bands = sorted(bands.items(), key=lambda kv: float(kv[1] or 0.0), reverse=True)
+    top2 = [str(b).lower() for b, _ in sorted_bands[:2]]
+    expected_set = {e.lower() for e in expected}
     if top2[0] in expected_set:
         return {
             "severity": "pass",
@@ -264,16 +268,31 @@ def check_masking(track_index: int, masking_report: dict | None) -> dict:
             "issues": [],
             "evidence": {"collision_count": 0},
         }
+    # MaskingEntry.severity is a float 0.0-1.0 (base 0.7 kick/bass-sub down to
+    # 0.3), and the band lives under the "overlap_band" key (MaskingEntry.to_dict
+    # via asdict). Treat >= 0.65 as a FAIL-grade collision.
+    _FAIL_THRESHOLD = 0.65
+
+    def _sev(c: dict) -> float:
+        try:
+            return float(c.get("severity", 0.0))
+        except (TypeError, ValueError):
+            return 0.0
+
     issues = []
     for c in my_collisions:
-        sev = c.get("severity", "warn")
+        sev = _sev(c)
         other = c.get("track_b") if c.get("track_a") == track_index else c.get("track_a")
-        band = c.get("band") or c.get("frequency_band") or "?"
+        band = c.get("overlap_band") or "?"
         issues.append({
             "code": "masking_collision",
-            "detail": f"Frequency clash with track {other} in band {band} (severity={sev})",
+            "detail": f"Frequency clash with track {other} in band {band} (severity={sev:.2f})",
         })
-    severity = "fail" if any(c.get("severity") == "high" for c in my_collisions) else "warn"
+    severity = (
+        "fail"
+        if any(_sev(c) >= _FAIL_THRESHOLD for c in my_collisions)
+        else "warn"
+    )
     return {
         "severity": severity,
         "summary": f"{len(my_collisions)} masking collision(s) involving this track",
@@ -649,10 +668,19 @@ def check_samples(role: str, devices: list[dict], slice_classifications: list[di
     # Read Volume param if present.
     params = simpler.get("parameters", []) or []
     vol = next((p for p in params if (p.get("name") or "").lower() == "volume"), None)
-    if vol and float(vol.get("value", 0.0)) < -10.0 and role in ("pad", "lead", "bass", "vox"):
+    # `value` is normally a float, but some LOM param shapes serialize it as a
+    # formatted string (e.g. "-12.0 dB"); float() / :.1f would then raise and
+    # take down the whole audit_layer call. Convert defensively.
+    vol_db = None
+    if vol is not None:
+        try:
+            vol_db = float(vol.get("value", 0.0))
+        except (TypeError, ValueError):
+            vol_db = None
+    if vol_db is not None and vol_db < -10.0 and role in ("pad", "lead", "bass", "vox"):
         issues.append({
             "code": "simpler_default_volume",
-            "detail": f"Simpler Volume at {vol.get('value'):.1f} dB (default -12). Set to 0 for sustained roles.",
+            "detail": f"Simpler Volume at {vol_db:.1f} dB (default -12). Set to 0 for sustained roles.",
         })
     if slice_classifications:
         unclassified = sum(1 for s in slice_classifications if s.get("classification") in (None, "unknown"))
@@ -667,7 +695,7 @@ def check_samples(role: str, devices: list[dict], slice_classifications: list[di
         "summary": f"Simpler/Sampler present; {len(issues)} issue(s)",
         "issues": issues,
         "evidence": {
-            "has_volume_default": bool(vol and float(vol.get("value", 0.0)) < -10.0),
+            "has_volume_default": bool(vol_db is not None and vol_db < -10.0),
             "slice_count": len(slice_classifications) if slice_classifications else 0,
         },
     }

package/mcp_server/audit/state.py

@@ -70,7 +70,11 @@ def count_wavetable_routings(ableton, track_index: int, devices: list[dict]) ->
     """Sum non-zero mod-matrix routings across any Wavetable on the track."""
     total = 0
     for i, dev in enumerate(devices or []):
-        if dev.get("class_name") != "Wavetable":
+        # Accept both "Wavetable" (most Live versions) and "InstrumentVector"
+        # (how Ableton reports the Wavetable instrument in some builds).
+        # Param-level disambiguation (Osc 1 Pos) is enforced inside the remote
+        # script _get_wavetable guard; the audit dict only carries class_name.
+        if dev.get("class_name") not in ("Wavetable", "InstrumentVector"):
             continue
         mod = safe_call(ableton, "get_wavetable_mod_matrix", {
             "track_index": track_index,
@@ -78,7 +82,11 @@ def count_wavetable_routings(ableton, track_index: int, devices: list[dict]) ->
         })
         if not mod:
             continue
-        entries = mod.get("matrix") or mod.get("entries") or []
+        # The remote get_wavetable_mod_matrix handler returns {"routings": [...]}
+        # (remote_script/LivePilot/devices.py). Read that real key FIRST; keep
+        # the matrix/entries aliases only as defensive fallbacks. Reading the
+        # wrong key here left this metric silently 0 against every real device.
+        entries = mod.get("routings") or mod.get("matrix") or mod.get("entries") or []
         for e in entries:
             try:
                 if abs(float(e.get("amount", 0.0))) > 0.001:

package/mcp_server/audit/tools.py

@@ -40,19 +40,40 @@ def _get_ableton(ctx: Context):
 
 
 def _maybe_get_timbre_fingerprint(ctx: Context, track_index: int) -> dict | None:
-    """Pull a per-track timbre fingerprint via the synthesis_brain timbre helper.
+    """Build a timbre fingerprint from the M4L analyzer's cached spectral data.
 
-    Returns None when the M4L bridge is offline or no fingerprint is available.
-    Does NOT solo the track — uses cached spectral data only.
+    Returns None when the M4L bridge is offline or no spectrum is cached.
+    Does NOT solo the track — the bands come from the MASTER bus, so with
+    other tracks playing the read is approximate. The returned dict carries
+    source="master_bus_unsoloed" so downstream consumers can label it.
+
+    extract_timbre_fingerprint is a pure function over already-fetched
+    spectrum/loudness/spectral_shape dicts — the data plumbing lives here.
     """
     try:
         from ..synthesis_brain.timbre import extract_timbre_fingerprint  # type: ignore
     except Exception:
         return None
     try:
-        result = extract_timbre_fingerprint(ctx, track_index)  # type: ignore[arg-type]
-        if isinstance(result, dict) and result.get("bands"):
-            return result
+        cache = ctx.lifespan_context.get("spectral")
+        if cache is None:
+            return None
+        snap = cache.get("spectrum")
+        bands = (snap or {}).get("value") if isinstance(snap, dict) else None
+        if not bands:
+            return None
+        loud = cache.get("loudness")
+        shape = cache.get("spectral_shape")
+        fp = extract_timbre_fingerprint(
+            spectrum={"bands": bands},
+            loudness=(loud or {}).get("value") if isinstance(loud, dict) else None,
+            spectral_shape=(shape or {}).get("value") if isinstance(shape, dict) else None,
+        )
+        return {
+            "bands": dict(bands),
+            "dimensions": fp.to_dict(),
+            "source": "master_bus_unsoloed",
+        }
     except Exception as exc:
         logger.debug("audit_layer timbre fetch failed: %s", exc)
     return None