livepilot 1.27.1 → 1.27.3

package/mcp_server/tools/analyzer.py

@@ -140,7 +140,7 @@ async def _try_native_replace_sample(
 
     ctx.lifespan_context.pop("_native_replace_skip_reason", None)
 
-    caps = _live_caps(ctx)
+    caps = await asyncio.to_thread(_live_caps, ctx)
     if not caps.has_replace_sample_native:
         _record_skip("gate_closed: tier=%s (need collaborative/12.4+)" % caps.capability_tier)
         return None
@@ -155,7 +155,9 @@ async def _try_native_replace_sample(
     if nested_device_index is not None:
         params["nested_device_index"] = int(nested_device_index)
     try:
-        resp = ableton.send_command("replace_sample_native", params)
+        resp = await asyncio.to_thread(
+            ableton.send_command, "replace_sample_native", params
+        )
     except Exception as exc:
         _record_skip("dispatch_raised: %s: %s" % (type(exc).__name__, exc))
         return None
@@ -196,7 +198,7 @@ async def reconnect_bridge(ctx: Context) -> dict:
 
     bridge_state = ctx.lifespan_context.get("_bridge_state")
     if not bridge_state:
-        return {"error": "Bridge state not available — restart the MCP server"}
+        return {"error": "Bridge state not available — restart the MCP server", "code": "STATE_ERROR"}
 
     if bridge_state["transport"] is not None:
         return {"ok": True, "message": "Bridge already connected on UDP 9880"}
@@ -214,6 +216,7 @@ async def reconnect_bridge(ctx: Context) -> dict:
         holder = _identify_port_holder(9880)
         return {
             "ok": False,
+            "code": "STATE_ERROR",
             "error": f"UDP port 9880 still in use{f' (PID {holder})' if holder else ''}. "
                      "Close the other LivePilot instance first.",
         }
@@ -226,50 +229,28 @@ async def get_master_spectrum(
     samples: int = 0,
     sub_detail: bool = False,
 ) -> dict:
-    """Get 9-band frequency analysis of the master bus.
-
-    Returns band energies (fffb~ center frequencies shown in parens):
-      sub_low   20-60 Hz   (~35 Hz center)  — kick fundamentals, Villalobos subs
-      sub       60-120 Hz  (~85 Hz)         — 808s, sub-bass body
-      low       120-250 Hz (~175 Hz)        — bass body, warmth
-      low_mid   250-500 Hz (~350 Hz)        — mud zone, male vocal lows
-      mid       500-1 kHz  (~700 Hz)        — vocal presence, snare body
-      high_mid  1-2 kHz    (~1.4 kHz)       — consonants, pick attack
-      high      2-4 kHz    (~2.8 kHz)       — presence, vocal intelligibility
-      presence  4-8 kHz    (~5.6 kHz)       — cymbal definition, air of breath
-      air       8-20 kHz   (~12 kHz)        — shimmer, sparkle
-    Values 0.0-1.0.
-
-    Older .amxd builds (pre-v1.16) emit the legacy 8-band layout without the
-    explicit `sub_low` split — the server auto-detects band count from the OSC
-    payload and picks the right name set. Re-freeze the Max device to get the
-    9-band resolution.
+    """Get 9-band frequency analysis of the master bus. Values 0.0-1.0.
+
+    Bands (low->high): sub_low (20-60Hz), sub (60-120Hz), low (120-250Hz),
+    low_mid (250-500Hz), mid (500Hz-1kHz), high_mid (1-2kHz), high (2-4kHz),
+    presence (4-8kHz), air (8-20kHz). Full Hz-range/use-case table:
+    livepilot-core references/perception.md#get_master_spectrum-9-band-table.
+    Legacy pre-v1.16 .amxd builds emit 8 bands (no sub_low split) —
+    auto-detected from the OSC payload.
 
     Also returns detected key/scale if enough audio has been analyzed.
     Requires LivePilot Analyzer on master track.
 
-    BUG-2026-04-22#6 fix — windowed averaging:
-      Kick transients make single snapshots swing wildly (0.45 → 0.05 →
-      0.16 within a bar). When mixing, you want a STABLE band profile,
-      not an instantaneous frame. Pass `window_ms` to sample the cache
-      over a time window and mean-pool:
-        - window_ms=500 → sample over 500ms (common for mix reads)
-        - window_ms=2000 → sample over 2 seconds (long-tail stability)
-      When `window_ms=0` (default), returns a single instantaneous snapshot
-      — the legacy behavior. `samples` overrides the auto-computed sample
-      count (defaults to window_ms / 50, minimum 3).
-
-    The sampled bands are also returned as `bands_min`, `bands_max` and
-    `bands_std` so callers can see variance within the window — useful
-    for detecting transient-heavy content vs. sustained material.
-
-    BUG-2026-04-22#15 fix — sub-band resolution:
-      Pass `sub_detail=True` to attach a `sub_detail` dict with three
-      finer buckets: `sub_deep` (20-45 Hz), `sub_mid` (45-60 Hz),
-      `sub_high` (60-80 Hz). Derived from the FluCoMa mel spectrum
-      (40 bands) rather than the 9-band cache, so it requires FluCoMa
-      to be active. When FluCoMa is unavailable, sub_detail is omitted
-      with a `sub_detail_warning` field explaining why.
+    window_ms (default 0): 0 returns a single instantaneous snapshot.
+    >0 (max 10000) mean-pools `samples` readings (default window_ms/50,
+    min 3, max 100) over that window instead — use for a stable mix read
+    since single frames swing wildly on transients. Also returns
+    bands_min/bands_max/bands_std for variance across the window.
+
+    sub_detail=True: attaches sub_detail {sub_deep 20-45Hz, sub_mid
+    45-60Hz, sub_high 60-80Hz} derived from the FluCoMa 40-band mel
+    spectrum (requires FluCoMa active; omitted with sub_detail_warning
+    otherwise).
     """
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
@@ -279,7 +260,7 @@ async def get_master_spectrum(
         # Each cache read is ~free; we sleep between reads to let the
         # analyzer update its internal buffer.
         if window_ms > 10000:
-            return {"error": "window_ms must be <= 10000 (10 seconds)"}
+            return {"error": "window_ms must be <= 10000 (10 seconds)", "code": "INVALID_PARAM"}
         n = samples if samples > 0 else max(3, window_ms // 50)
         n = min(n, 100)
         interval = (window_ms / 1000.0) / max(n - 1, 1)
@@ -292,6 +273,7 @@ async def get_master_spectrum(
                 await asyncio.sleep(interval)
         if not bands_acc:
             return {
+                "code": "STATE_ERROR",
                 "error": "No spectrum data captured — analyzer may be stale",
                 "analyzer_hint": "Ensure LivePilot_Analyzer is active on master",
             }
@@ -467,7 +449,7 @@ async def get_detected_key(ctx: Context) -> dict:
     if "error" in result:
         return result
     if not result.get("key"):
-        return {"error": "Not enough audio analyzed yet. Play 4-8 bars for key detection."}
+        return {"error": "Not enough audio analyzed yet. Play 4-8 bars for key detection.", "code": "STATE_ERROR"}
     return result
 
 
@@ -590,25 +572,22 @@ async def replace_simpler_sample(
     """Load an audio file into a Simpler device by absolute file path.
 
     Replaces the currently loaded sample. The Simpler must already have
-    a sample loaded — this replaces it, it cannot load into an empty Simpler.
-    If the Simpler is empty (freshly created with no sample), load a sample
-    manually first or use find_and_load_device to load a preset that already
-    contains a sample.
-
-    **Prefer `load_browser_item(track, uri)` when possible** — see P0-1 in
-    docs/2026-04-14-bugs-discovered.md. The M4L bridge's replace path can
-    silently keep the bootstrap placeholder in some conditions; this tool
-    now verifies by reading back the device name and will return an error
-    if the replace didn't actually take effect.
-
-    Nested addressing (Live 12.4+ only, BUG-#1 fix from 2026-04-22):
-      - When `chain_index` is provided, the device is resolved at
-        `track.devices[device_index].chains[chain_index]
-         .devices[nested_device_index or 0]`. This is how Drum Rack
-        pad-by-pad construction works — see `add_drum_rack_pad` for the
-        high-level workflow.
-      - chain_index is only honored by the native 12.4 path; the M4L
-        bridge fallback cannot resolve nested paths.
+    a sample loaded — this cannot load into an empty Simpler. If empty,
+    load a sample manually first or use find_and_load_device to load a
+    preset that already contains a sample.
+
+    **Prefer `load_browser_item(track, uri)` when the file is browser-
+    indexed** — more reliable (see livepilot-core references/
+    perception.md#replace_simpler_sample--load_sample_to_simpler). This
+    tool verifies by reading back the device name post-load and returns
+    an error if the replace didn't actually take effect.
+
+    Nested addressing (Live 12.4+ only): when `chain_index` is provided,
+    the device is resolved at `track.devices[device_index]
+    .chains[chain_index].devices[nested_device_index or 0]` — how Drum
+    Rack pad-by-pad construction works (see `add_drum_rack_pad` for the
+    high-level workflow). Only the native 12.4 path honors chain_index;
+    the M4L bridge fallback cannot resolve nested paths.
 
     Also auto-applies post-load hygiene:
       - Sets Simpler Snap=0 (required for playback after replace)
@@ -657,6 +636,7 @@ async def replace_simpler_sample(
         return result
     if not result.get("sample_loaded"):
         return {
+            "code": "STATE_ERROR",
             "error": "Sample may not have loaded. Ensure the Simpler already "
             "has a sample loaded — replace_sample silently fails on empty Simplers.",
             "native_attempted": _native_dispatch_was_attempted(skip_reason),
@@ -691,20 +671,20 @@ async def load_sample_to_simpler(
 ) -> dict:
     """Load an audio file into a NEW Simpler device on a track.
 
-    This is the full workflow for programmatic sample loading:
-    1. Loads a dummy sample via the browser (creates Simpler with a sample)
-    2. Replaces the dummy with your audio file
-    3. Applies post-load hygiene (Snap=0, loop defaults for warped loops)
-    4. Verifies by reading back the device name — returns an error if
-       the Simpler still has the bootstrap placeholder (P0-1 guard)
+    Creates a Simpler (native insert+replace on Live 12.4+; a
+    bootstrap-sample-then-replace workaround on earlier versions),
+    applies post-load hygiene (Snap=0, loop defaults for warped loops),
+    then verifies by reading back the device name — errors if the
+    Simpler still has the bootstrap placeholder. Full rationale:
+    livepilot-core references/perception.md
+    #replace_simpler_sample--load_sample_to_simpler.
 
-    Use this instead of replace_simpler_sample when the track has no Simpler
-    or the Simpler is empty. Works with any audio file path.
+    Use this instead of replace_simpler_sample when the track has no
+    Simpler or the Simpler is empty. Works with any audio file path.
 
-    **For files that exist in Ableton's browser index** (Samples, User Library,
-    Packs), PREFER `load_browser_item(track, uri)` — it goes through Ableton's
-    native loading path and is more reliable. This tool is a workaround for
-    files that aren't browser-indexed.
+    **For files that exist in Ableton's browser index** (Samples, User
+    Library, Packs), PREFER `load_browser_item(track, uri)` — more
+    reliable. This tool is a workaround for non-browser-indexed files.
 
     Requires LivePilot Analyzer on master track.
     """
@@ -715,13 +695,13 @@ async def load_sample_to_simpler(
 
     # Live 12.4+: create an empty Simpler via insert_device, then use the
     # native replace_sample path. Skips the dummy-sample bootstrap entirely.
-    caps = _live_caps(ctx)
+    caps = await asyncio.to_thread(_live_caps, ctx)
     native_attempted = False
     fallback_reason = "live_version_below_12_4"
     if caps.has_replace_sample_native:
         fallback_reason = "native_insert_device_unavailable"
         try:
-            ins = ableton.send_command("insert_device", {
+            ins = await asyncio.to_thread(ableton.send_command, "insert_device", {
                 "track_index": track_index,
                 "device_name": "Simpler",
             })
@@ -756,33 +736,35 @@ async def load_sample_to_simpler(
 
     # Step 1: Load a sample from the browser to create Simpler with content
     try:
-        search = ableton.send_command("search_browser", {
+        search = await asyncio.to_thread(ableton.send_command, "search_browser", {
             "path": "samples",
             "name_filter": "kick",
             "loadable_only": True,
             "max_results": 1,
         })
     except Exception as exc:
-        return {"error": f"Browser search failed: {exc}"}
+        return {"error": f"Browser search failed: {exc}", "code": "INTERNAL"}
     results = search.get("results", [])
     if not results:
-        return {"error": "No samples found in browser to bootstrap Simpler"}
+        return {"error": "No samples found in browser to bootstrap Simpler", "code": "NOT_FOUND"}
 
     # Load the dummy sample — Ableton auto-creates Simpler
     uri = results[0]["uri"]
     try:
-        ableton.send_command("load_browser_item", {
+        await asyncio.to_thread(ableton.send_command, "load_browser_item", {
             "track_index": track_index,
             "uri": uri,
         })
     except Exception as exc:
-        return {"error": f"Failed to load bootstrap sample: {exc}"}
+        return {"error": f"Failed to load bootstrap sample: {exc}", "code": "INTERNAL"}
 
     # Step 2: Find the newly created device (it's at the end of the chain)
     try:
-        track_info = ableton.send_command("get_track_info", {"track_index": track_index})
+        track_info = await asyncio.to_thread(
+            ableton.send_command, "get_track_info", {"track_index": track_index}
+        )
     except Exception as exc:
-        return {"error": f"Failed to read track after loading sample: {exc}"}
+        return {"error": f"Failed to read track after loading sample: {exc}", "code": "INTERNAL"}
     actual_device_index = len(track_info.get("devices", [])) - 1
     if actual_device_index < 0:
         actual_device_index = 0
@@ -794,7 +776,7 @@ async def load_sample_to_simpler(
     if "error" in result:
         return result
     if not result.get("sample_loaded"):
-        return {"error": "Sample replacement failed after bootstrap"}
+        return {"error": "Sample replacement failed after bootstrap", "code": "INTERNAL"}
 
     # Step 4: Verify by reading back the device name (P0-1 guard)
     hygiene = await _simpler_post_load_hygiene(
@@ -823,26 +805,19 @@ async def add_drum_rack_pad(
     rack_device_index: Optional[int] = None,
     chain_name: Optional[str] = None,
 ) -> dict:
-    """Add a new pad (chain) to a Drum Rack and load a sample into it.
-
-    **BUG-2026-04-22#1 FIX** — this is the tool that was missing.
-    Previously `load_browser_item` replaced the existing chain on repeat
-    calls, and `load_sample_to_simpler` couldn't address nested paths.
-    This single tool does the full drum-rack pad build atomically:
-
-      1. Locates the Drum Rack on the track (auto-finds if
-         `rack_device_index` is None — searches for class_name containing
-         "DrumGroupDevice").
-      2. Inserts a new chain on the rack (`insert_rack_chain`).
-      3. Assigns the chain's trigger note (`set_drum_chain_note`).
-      4. Inserts an empty Simpler into the chain (`insert_device` with
-         `chain_index`).
-      5. Calls the native Live 12.4 `replace_sample_native` with nested
-         addressing to load the sample.
-      6. Sets Snap=0 post-load (playback hygiene).
-
-    Requires Live 12.4+ for step 5. On earlier versions returns an error
-    directing the caller to the bridge-based workaround.
+    """Add a new pad (chain) to a Drum Rack and load a sample into it — atomic.
+
+    One call does the full build: locate/auto-detect the Drum Rack
+    (auto-detect searches for class_name containing "DrumGroupDevice"),
+    insert a new chain, assign the trigger note, insert an empty Simpler
+    into that chain, native-replace the sample with nested addressing,
+    Snap=0 post-load. Full history: livepilot-core references/
+    perception.md#add_drum_rack_pad.
+
+    Requires Live 12.4+ for the nested-addressing sample load. On
+    earlier versions returns an error directing to the bridge-based
+    workaround (call insert_rack_chain / set_drum_chain_note /
+    insert_device / replace_simpler_sample individually).
 
     track_index:       track containing the Drum Rack
     pad_note:          MIDI note for the pad (0..127). Standard drum map:
@@ -852,26 +827,20 @@ async def add_drum_rack_pad(
                        If None, auto-detects the first Drum Rack.
     chain_name:        optional display name for the new chain.
 
-    Returns: {
-      "ok": bool,
-      "track_index": int,
-      "rack_device_index": int,
-      "chain_index": int,
-      "pad_note": int,
-      "nested_device_index": int,   # where the Simpler landed
-      "device_name": str,
-      "method": "native_12_4",
-    }
+    Returns {ok, track_index, rack_device_index, chain_index, pad_note,
+    nested_device_index (where the Simpler landed), device_name,
+    method:"native_12_4"}.
     """
     # _simpler_post_load_hygiene is already imported at module scope
     # (line 29). Do not re-import inline — the earlier inline form used
     # the wrong relative path (..; should've been .) and crashed at
     # runtime with "No module named 'mcp_server._analyzer_engine'".
     ableton = ctx.lifespan_context["ableton"]
-    caps = _live_caps(ctx)
+    caps = await asyncio.to_thread(_live_caps, ctx)
     if not caps.has_replace_sample_native:
         return {
             "ok": False,
+            "code": "STATE_ERROR",
             "error": (
                 "add_drum_rack_pad requires Live 12.4+ for native nested "
                 "sample loading. Detected tier: " + caps.capability_tier +
@@ -881,18 +850,19 @@ async def add_drum_rack_pad(
         }
 
     if not (0 <= pad_note <= 127):
-        return {"ok": False, "error": "pad_note must be 0..127"}
+        return {"ok": False, "error": "pad_note must be 0..127", "code": "INVALID_PARAM"}
     if not file_path or not isinstance(file_path, str):
-        return {"ok": False, "error": "file_path (absolute path) is required"}
+        return {"ok": False, "error": "file_path (absolute path) is required", "code": "INVALID_PARAM"}
 
     # Step 1: locate the Drum Rack if not provided.
     if rack_device_index is None:
         try:
-            info = ableton.send_command(
+            info = await asyncio.to_thread(
+                ableton.send_command,
                 "get_track_info", {"track_index": track_index},
             )
         except Exception as exc:
-            return {"ok": False, "error": f"get_track_info failed: {exc}"}
+            return {"ok": False, "error": f"get_track_info failed: {exc}", "code": "INTERNAL"}
         devices = info.get("devices", []) if isinstance(info, dict) else []
         found_idx = None
         for idx, d in enumerate(devices):
@@ -907,52 +877,55 @@ async def add_drum_rack_pad(
                     "No Drum Rack found on track. Pass `rack_device_index` "
                     "explicitly, or use `insert_device('Drum Rack')` first."
                 ),
+                "code": "NOT_FOUND",
             }
         rack_device_index = found_idx
 
     # Step 2: insert a new chain on the rack.
     try:
-        chain_result = ableton.send_command("insert_rack_chain", {
+        chain_result = await asyncio.to_thread(ableton.send_command, "insert_rack_chain", {
             "track_index": track_index,
             "device_index": rack_device_index,
             "position": -1,  # append to end
         })
     except Exception as exc:
-        return {"ok": False, "error": f"insert_rack_chain failed: {exc}"}
+        return {"ok": False, "error": f"insert_rack_chain failed: {exc}", "code": "INTERNAL"}
     if not isinstance(chain_result, dict) or "error" in chain_result:
         return {
             "ok": False,
             "error": f"insert_rack_chain returned: {chain_result}",
+            "code": "INTERNAL",
         }
     chain_index = int(chain_result.get("chain_index", chain_result.get("index", 0)))
 
     # Step 3: assign pad note to the new chain.
     try:
-        note_result = ableton.send_command("set_drum_chain_note", {
+        note_result = await asyncio.to_thread(ableton.send_command, "set_drum_chain_note", {
             "track_index": track_index,
             "device_index": rack_device_index,
             "chain_index": chain_index,
             "note": pad_note,
         })
     except Exception as exc:
-        return {"ok": False, "error": f"set_drum_chain_note failed: {exc}"}
+        return {"ok": False, "error": f"set_drum_chain_note failed: {exc}", "code": "INTERNAL"}
     if isinstance(note_result, dict) and "error" in note_result:
-        return {"ok": False, "error": f"set_drum_chain_note: {note_result['error']}"}
+        return {"ok": False, "error": f"set_drum_chain_note: {note_result['error']}", "code": "INTERNAL"}
 
     # Step 4: insert an empty Simpler into the chain.
     try:
-        insert_result = ableton.send_command("insert_device", {
+        insert_result = await asyncio.to_thread(ableton.send_command, "insert_device", {
             "track_index": track_index,
             "device_index": rack_device_index,
             "chain_index": chain_index,
             "device_name": "Simpler",
         })
     except Exception as exc:
-        return {"ok": False, "error": f"insert_device(Simpler, chain) failed: {exc}"}
+        return {"ok": False, "error": f"insert_device(Simpler, chain) failed: {exc}", "code": "INTERNAL"}
     if not isinstance(insert_result, dict) or "error" in insert_result:
         return {
             "ok": False,
             "error": f"insert_device into chain failed: {insert_result}",
+            "code": "INTERNAL",
         }
     nested_idx = int(insert_result.get("device_index", 0))
 
@@ -968,6 +941,7 @@ async def add_drum_rack_pad(
     if native is None:
         return {
             "ok": False,
+            "code": "INTERNAL",
             "error": "Native replace_sample failed — see logs for reason",
             "track_index": track_index,
             "rack_device_index": rack_device_index,
@@ -979,7 +953,7 @@ async def add_drum_rack_pad(
     applied_name = None
     if chain_name:
         try:
-            rename_result = ableton.send_command("set_chain_name", {
+            rename_result = await asyncio.to_thread(ableton.send_command, "set_chain_name", {
                 "track_index": track_index,
                 "device_index": rack_device_index,
                 "chain_index": chain_index,
@@ -1051,21 +1025,20 @@ async def classify_simpler_slices(
     break.** Slice content depends on transient detection order in the
     source audio — slice 0 is NOT guaranteed to be a kick. Assuming
     drum-rack convention produces wrong grooves that take iterations to
-    diagnose (see 2026-04-18 creative session for the canonical case).
+    diagnose.
 
-    Classification rules (validated on "Break Ghosts 90 bpm"):
-      - KICK: sub+low >= 45%, high < 40%
-      - HAT: high >= 70% AND mid < 25% (thin metal disc = no drum body)
-      - SNARE: mid >= 25% AND high >= 40% AND peak >= 0.6 (broadband loud)
-      - ghost: peak < 0.35
+    Classification thresholds: livepilot-core references/
+    perception.md#classify_simpler_slices--classification-thresholds
+    (KICK: sub+low >= 45%, high < 40%. HAT: high >= 70% AND mid < 25%.
+    SNARE: mid >= 25% AND high >= 40% AND peak >= 0.6. ghost: peak < 0.35).
 
     Parameters:
       track_index, device_index: the Simpler to analyze
-      file_path: (optional) explicit WAV path. If omitted, the bridge
-        resolves it automatically via ``get_simpler_file_path``
-        (v1.23.3+). Pass explicitly only when running against an .amxd
-        freeze that predates the case (returns the bridge error string
-        in that case so the caller knows to re-freeze).
+      file_path: (optional) explicit WAV path. If omitted, resolved
+        automatically via Remote Script then M4L bridge fallback. Pass
+        explicitly only against a stale .amxd freeze that predates
+        auto-resolution (returns the bridge error string so the caller
+        knows to re-freeze).
 
     Returns: dict with ``slices`` list. Each slice entry has:
       index, frame, seconds, midi_pitch (36+index), label, peak, rms,
@@ -1087,7 +1060,7 @@ async def classify_simpler_slices(
     )
     enriched = _enrich_slice_response(raw_slices)
     if enriched is None:
-        return {"error": "Bridge returned no slice data"}
+        return {"error": "Bridge returned no slice data", "code": "STATE_ERROR"}
 
     # 2. Resolve file path via Remote Script TCP path (v1.23.3+ — closes
     # the v1.12 follow-up). Reads ``device.sample.file_path`` directly
@@ -1102,7 +1075,8 @@ async def classify_simpler_slices(
         ableton = ctx.request_context.lifespan_context.get("ableton")
         if ableton is not None:
             try:
-                rs_resp = ableton.send_command(
+                rs_resp = await asyncio.to_thread(
+                    ableton.send_command,
                     "get_simpler_file_path",
                     {"track_index": track_index, "device_index": device_index},
                 )
@@ -1134,28 +1108,32 @@ async def classify_simpler_slices(
     if not wav_path:
         return {
             **enriched,
+            "code": "STATE_ERROR",
             "error": (
                 resolve_error
                 or "No file_path available — pass file_path= explicitly."
             ),
         }
 
-    # 3. Load WAV and build frame boundaries
+    # 3. Load WAV and build frame boundaries (decode off the event loop)
     try:
-        audio, sr = sf.read(wav_path)
+        audio, sr = await asyncio.to_thread(sf.read, wav_path)
     except (sf.LibsndfileError, sf.SoundFileError, RuntimeError, OSError) as exc:
         # BUG-audit-C3: corrupt / missing / non-audio files must return a
         # structured error dict instead of raising through the MCP framework
         # (inconsistent with every other tool in this module).
         return {
             **enriched,
+            "code": "INTERNAL",
             "error": f"Could not load WAV at {wav_path!r}: {exc}",
         }
     slices = enriched["slices"]
     frame_boundaries = [s["frame"] for s in slices] + [len(audio)]
 
-    # 4. Classify
-    classifications = classify_slices(audio, sr, frame_boundaries)
+    # 4. Classify (per-slice FFT loop — offload off the event loop)
+    classifications = await asyncio.to_thread(
+        classify_slices, audio, sr, frame_boundaries
+    )
 
     # 5. Merge classification into each slice entry
     merged_slices = []
@@ -1372,6 +1350,30 @@ async def get_display_values(
 # ── Phase 3: Audio Capture ─────────────────────────────────────────────
 
 
+def _relocate_capture_file(src: str) -> Optional[str]:
+    """Move a bridge-captured audio file into CAPTURE_DIR (blocking file I/O).
+
+    Tries common extensions the bridge might have produced. Returns the
+    new path on success, or None if no matching file was found or the
+    move failed (caller should leave the original path unchanged in the
+    latter case). Run via asyncio.to_thread — never call directly from
+    an async def.
+    """
+    for ext in ("", ".aiff", ".wav", ".aif"):
+        src_path = src + ext if not src.endswith(ext) else src
+        if os.path.isfile(src_path):
+            dst_name = os.path.basename(src_path)
+            dst_path = os.path.join(CAPTURE_DIR, dst_name)
+            try:
+                import shutil
+
+                shutil.move(src_path, dst_path)
+                return dst_path
+            except OSError:
+                return None
+    return None
+
+
 @mcp.tool()
 async def capture_audio(
     ctx: Context,
@@ -1407,7 +1409,7 @@ async def capture_audio(
 
     bridge = _get_m4l(ctx)
     # Ensure captures directory exists before sending to bridge
-    os.makedirs(CAPTURE_DIR, exist_ok=True)
+    await asyncio.to_thread(os.makedirs, CAPTURE_DIR, exist_ok=True)
     duration_ms = duration_seconds * 1000
     result = await bridge.send_capture(
         "capture_audio",
@@ -1418,21 +1420,9 @@ async def capture_audio(
 
     # Move captured file from M4L device directory to CAPTURE_DIR
     if result.get("ok") and result.get("file_path"):
-        src = result["file_path"]
-        # Try common extensions the bridge might produce
-        for ext in ("", ".aiff", ".wav", ".aif"):
-            src_path = src + ext if not src.endswith(ext) else src
-            if os.path.isfile(src_path):
-                dst_name = os.path.basename(src_path)
-                dst_path = os.path.join(CAPTURE_DIR, dst_name)
-                try:
-                    import shutil
-
-                    shutil.move(src_path, dst_path)
-                    result["file_path"] = dst_path
-                except OSError:
-                    pass  # Leave in original location if move fails
-                break
+        new_path = await asyncio.to_thread(_relocate_capture_file, result["file_path"])
+        if new_path:
+            result["file_path"] = new_path
 
     return result
 
@@ -1471,7 +1461,7 @@ def get_spectral_shape(ctx: Context) -> dict:
     data = cache.get("spectral_shape")
     if not data:
         hint = _flucoma_hint(cache)
-        return {"error": f"No spectral shape data — {hint}"}
+        return {"error": f"No spectral shape data — {hint}", "code": "STATE_ERROR"}
     return {**data["value"], "age_ms": data["age_ms"]}
 
 
@@ -1486,7 +1476,7 @@ def get_mel_spectrum(ctx: Context) -> dict:
     data = cache.get("mel_bands")
     if not data:
         hint = _flucoma_hint(cache)
-        return {"error": f"No mel data — {hint}"}
+        return {"error": f"No mel data — {hint}", "code": "STATE_ERROR"}
     return {"mel_bands": data["value"], "band_count": len(data["value"]), "age_ms": data["age_ms"]}
 
 
@@ -1501,7 +1491,7 @@ def get_chroma(ctx: Context) -> dict:
     data = cache.get("chroma")
     if not data:
         hint = _flucoma_hint(cache)
-        return {"error": f"No chroma data — {hint}"}
+        return {"error": f"No chroma data — {hint}", "code": "STATE_ERROR"}
     values = data["value"]
     chroma_dict = {PITCH_NAMES[i]: round(v, 3) for i, v in enumerate(values[:12])}
     max_val = max(values[:12]) if values else 0
@@ -1521,7 +1511,7 @@ def get_onsets(ctx: Context) -> dict:
     data = cache.get("onset")
     if not data:
         hint = _flucoma_hint(cache)
-        return {"error": f"No onset data — {hint}"}
+        return {"error": f"No onset data — {hint}", "code": "STATE_ERROR"}
     return {**data["value"], "age_ms": data["age_ms"]}
 
 
@@ -1536,7 +1526,7 @@ def get_novelty(ctx: Context) -> dict:
     data = cache.get("novelty")
     if not data:
         hint = _flucoma_hint(cache)
-        return {"error": f"No novelty data — {hint}"}
+        return {"error": f"No novelty data — {hint}", "code": "STATE_ERROR"}
     return {**data["value"], "age_ms": data["age_ms"]}
 
 
@@ -1551,17 +1541,13 @@ async def verify_device_health(
 ) -> dict:
     """Fire a test MIDI note at a track's instrument and check for output.
 
-    BUG-2026-04-22#19 fix — parameter_count alone can't tell you whether
-    an AU/VST is alive. Plenty of "loaded" plugins return 19 params and
-    silence. This tool does the real-world check:
-
-      1. Snapshot the track meter.
-      2. Emit a MIDI note at the specified pitch/velocity.
-      3. Sample the track meter for `test_duration_ms` (peak across samples).
-      4. Compare the peak to a threshold; report alive vs dead.
-
-    The meter readout is taken with `get_track_meters(samples=N)` so the
-    BUG-#7 "left=right=0 while level>0" artifact can't cause false negatives.
+    parameter_count alone can't tell you whether an AU/VST is alive —
+    plenty of "loaded" plugins return N params and silence. Real-world
+    check: snapshot the track meter, emit a MIDI note at the specified
+    pitch/velocity, sample the meter for `test_duration_ms` (peak across
+    samples, dodging a left=right=0-while-level>0 meter artifact), and
+    compare the peak to `threshold`. Common dead-device causes and
+    history: livepilot-core references/perception.md#verify_device_health--verify_all_devices_health.
 
     track_index:      track with the instrument to verify
     test_midi_note:   pitch to fire (default C3 / 60 — safe for most samples)
@@ -1570,14 +1556,8 @@ async def verify_device_health(
     threshold:        peak level below which the device is considered dead
                       (default 0.005 — roughly -46 dBFS)
 
-    Returns: {
-      "ok": bool,
-      "alive": bool,
-      "peak_level": float,
-      "threshold": float,
-      "samples_taken": int,
-      "hint": str,     # actionable advice when dead
-    }
+    Returns {ok, alive, peak_level, threshold, samples_taken, hint
+    (actionable advice when dead)}.
 
     Requires LivePilot Analyzer on master track and a playable instrument
     on the target track. Prefer this over trying to eyeball parameter_count.
@@ -1590,15 +1570,15 @@ async def verify_device_health(
     if test_duration_ms > 2000:
         test_duration_ms = 2000
     if not 1 <= test_velocity <= 127:
-        return {"ok": False, "error": "test_velocity must be 1-127"}
+        return {"ok": False, "error": "test_velocity must be 1-127", "code": "INVALID_PARAM"}
     if not 0 <= test_midi_note <= 127:
-        return {"ok": False, "error": "test_midi_note must be 0-127"}
+        return {"ok": False, "error": "test_midi_note must be 0-127", "code": "INVALID_PARAM"}
 
     # Fire the test note via the remote script's play_note helper. Fall back
     # to a raw MIDI event if the helper isn't available.
     fired = False
     try:
-        resp = ableton.send_command("fire_test_note", {
+        resp = await asyncio.to_thread(ableton.send_command, "fire_test_note", {
             "track_index": track_index,
             "midi_note": test_midi_note,
             "velocity": test_velocity,
@@ -1613,6 +1593,7 @@ async def verify_device_health(
         # Graceful degradation when the remote-script helper isn't present.
         return {
             "ok": False,
+            "code": "STATE_ERROR",
             "error": (
                 "fire_test_note handler not available on this remote script. "
                 "Update LivePilot's remote script (npx livepilot --install + "
@@ -1628,7 +1609,7 @@ async def verify_device_health(
     samples_taken = 0
     for i in range(n):
         try:
-            snap = ableton.send_command("get_track_meters", {
+            snap = await asyncio.to_thread(ableton.send_command, "get_track_meters", {
                 "track_index": track_index,
             })
         except Exception as exc:
@@ -1650,7 +1631,9 @@ async def verify_device_health(
 
     # Always clean up the scratch clip, even on errors.
     try:
-        ableton.send_command("cleanup_test_note", {"track_index": track_index})
+        await asyncio.to_thread(
+            ableton.send_command, "cleanup_test_note", {"track_index": track_index}
+        )
     except Exception as exc:
         logger.debug("cleanup_test_note failed: %s", exc)
 
@@ -1708,11 +1691,11 @@ async def verify_all_devices_health(
     """
     ableton = ctx.lifespan_context["ableton"]
     try:
-        session = ableton.send_command("get_session_info", {})
+        session = await asyncio.to_thread(ableton.send_command, "get_session_info", {})
     except Exception as exc:
-        return {"ok": False, "error": f"get_session_info failed: {exc}"}
+        return {"ok": False, "error": f"get_session_info failed: {exc}", "code": "INTERNAL"}
     if not isinstance(session, dict):
-        return {"ok": False, "error": "Unexpected get_session_info response"}
+        return {"ok": False, "error": "Unexpected get_session_info response", "code": "INTERNAL"}
 
     tracks = session.get("tracks", []) or []
     alive: list = []
@@ -1748,7 +1731,8 @@ async def verify_all_devices_health(
         # devices) would change a hot-path payload size for every caller.
         if skip_empty_tracks:
             try:
-                track_info = ableton.send_command(
+                track_info = await asyncio.to_thread(
+                    ableton.send_command,
                     "get_track_info", {"track_index": tid},
                 )
             except Exception:
@@ -1809,7 +1793,7 @@ def get_momentary_loudness(ctx: Context) -> dict:
     data = cache.get("loudness")
     if not data:
         hint = _flucoma_hint(cache)
-        return {"error": f"No loudness data — {hint}"}
+        return {"error": f"No loudness data — {hint}", "code": "STATE_ERROR"}
     return {**data["value"], "age_ms": data["age_ms"]}
 
 
@@ -1821,13 +1805,11 @@ async def analyze_loudness_live(
 ) -> dict:
     """Analyze the currently-playing master output's loudness over a window (LIVE).
 
-    Use this tool during a session — no rendered file needed.
-    For offline analysis of an exported audio file use analyze_loudness() instead.
-
-    BUG-2026-04-22#8 fix — the offline `analyze_loudness` requires a
-    rendered file. This tool samples the LivePilot analyzer's realtime
-    momentary LUFS / true peak stream over `window_sec` and reports
-    integrated + max statistics. No render required.
+    Use this tool during a session — no rendered file needed. For
+    offline analysis of an exported audio file use analyze_loudness()
+    instead. Samples the LivePilot analyzer's realtime momentary LUFS /
+    true peak stream over `window_sec` and reports integrated + max
+    statistics.
 
     Requires FluCoMa package in Max and playback to be running. Best
     called while the section you want to measure is actually playing.
@@ -1847,9 +1829,9 @@ async def analyze_loudness_live(
     }
     """
     if window_sec <= 0 or window_sec > 120:
-        return {"error": "window_sec must be > 0 and <= 120"}
+        return {"error": "window_sec must be > 0 and <= 120", "code": "INVALID_PARAM"}
     if sample_interval_ms < 50 or sample_interval_ms > 5000:
-        return {"error": "sample_interval_ms must be 50..5000"}
+        return {"error": "sample_interval_ms must be 50..5000", "code": "INVALID_PARAM"}
 
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
@@ -1859,10 +1841,10 @@ async def analyze_loudness_live(
     preview = cache.get("loudness")
     if not preview:
         hint = _flucoma_hint(cache)
-        return {"error": f"No live loudness stream — {hint}"}
+        return {"error": f"No live loudness stream — {hint}", "code": "STATE_ERROR"}
 
     try:
-        session = ableton.send_command("get_session_info", {})
+        session = await asyncio.to_thread(ableton.send_command, "get_session_info", {})
         is_playing = bool(session.get("is_playing", False))
     except Exception:
         is_playing = None
@@ -1888,7 +1870,7 @@ async def analyze_loudness_live(
             await asyncio.sleep(interval_s)
 
     if not lufs_vals:
-        return {"error": "No valid loudness samples captured over the window"}
+        return {"error": "No valid loudness samples captured over the window", "code": "STATE_ERROR"}
 
     integrated = sum(lufs_vals) / len(lufs_vals)
     result = {
@@ -2016,7 +1998,11 @@ async def compressor_set_sidechain(
     if source_channel:
         params["source_channel"] = str(source_channel)
     ableton = ctx.lifespan_context["ableton"]
-    return ableton.send_command("set_compressor_sidechain", params)
+    # Offload the blocking TCP round-trip off the asyncio event loop so this
+    # async tool doesn't freeze every other concurrent handler + the bridge.
+    return await asyncio.to_thread(
+        ableton.send_command, "set_compressor_sidechain", params
+    )
 
 
 # ──────────────────────────────────────────────────────────────────────
@@ -2100,6 +2086,7 @@ def ensure_analyzer_on_master(ctx: Context) -> dict:
     except Exception as exc:
         return {
             "status": "failed",
+            "code": "INTERNAL",
             "error": f"Could not read master track: {exc}",
             "hint": "Verify MCP connection to Ableton; retry with get_session_info first.",
         }
@@ -2154,6 +2141,7 @@ def ensure_analyzer_on_master(ctx: Context) -> dict:
         if _analyzer_amxd_installed_at_user_library():
             return {
                 "status": "cache_cold",
+                "code": "STATE_ERROR",
                 "error": str(exc),
                 "hint": (
                     "LivePilot_Analyzer.amxd is installed at "
@@ -2169,6 +2157,7 @@ def ensure_analyzer_on_master(ctx: Context) -> dict:
             }
         return {
             "status": "install_required",
+            "code": "STATE_ERROR",
             "error": str(exc),
             "hint": (
                 "LivePilot_Analyzer not found in Ableton's browser. Install "