livepilot 1.27.2 → 1.27.3

package/livepilot/skills/livepilot-core/references/perception.md

@@ -0,0 +1,125 @@
+# Perception (Analyzer) Reference
+
+Deep-dive detail for `mcp_server/tools/analyzer.py` tools. The tool
+docstrings carry a trimmed operational contract (params, ranges,
+gotchas); this file carries the full band tables, classification
+thresholds, and historical bug context that motivated each behavior.
+Read this before deep spectral/health-check work — the tool docstrings
+point back here for the parts that don't change from call to call.
+
+## `get_master_spectrum` — 9-band table
+
+Band energies (fffb~ center frequencies shown in parens), values 0.0-1.0:
+
+| Band | Range | Center | Use |
+|---|---|---|---|
+| sub_low | 20-60 Hz | ~35 Hz | kick fundamentals, deep sub-bass |
+| 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 Hz-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 |
+
+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.
+
+**BUG-2026-04-22#6 fix — windowed averaging.** Kick transients make
+single snapshots swing wildly (0.45 → 0.05 → 0.16 within a bar). The
+`window_ms` param samples the cache over a time window and mean-pools
+instead of returning one instantaneous frame.
+
+**BUG-2026-04-22#15 fix — sub-band resolution.** `sub_detail=True`
+derives three finer buckets from the FluCoMa 40-band mel spectrum
+(band 0-1 ≈ sub_deep 0-45 Hz — kick fundamental, band 2 ≈ sub_mid
+45-60 Hz — 808 body/kick upper, band 3 ≈ sub_high 60-80 Hz — bass
+guitar low/sub-bass crossover). Mel band edges are perceptual, not
+linear Hz, so these are approximations tight enough for mixing
+decisions ("is energy in the 30 Hz or 60 Hz range?"). Requires FluCoMa
+active — omitted with `sub_detail_warning` otherwise.
+
+## `verify_device_health` / `verify_all_devices_health`
+
+**BUG-2026-04-22#19 fix.** `parameter_count` alone can't tell you
+whether an AU/VST is alive — plenty of "loaded" plugins return N
+params and silence. These tools fire a real test MIDI note and read
+the track meter across a window (`get_track_meters(samples=N)` to
+dodge the BUG-#7 "left=right=0 while level>0" artifact).
+
+Common dead-device causes (surfaced in the `hint` field when
+`alive=False`): (1) plugin waiting for preset/bank selection, (2)
+algorithm/envelope configured for zero output, (3) wrong MIDI channel
+or velocity curve, (4) dead VST (reinstall). Try opening the device UI
+and auditioning manually.
+
+`verify_all_devices_health` (BUG-2026-04-26#1 fix): audio-track
+detection uses `has_midi_input`/`has_audio_input` from
+`get_session_info` (earlier code checked nonexistent `is_audio_track`/
+`type` fields, so detection silently always evaluated False).
+Empty-track detection requires a `get_track_info` round-trip per track
+because `get_session_info` doesn't embed per-track `devices` arrays.
+
+## `classify_simpler_slices` — classification thresholds
+
+Validated on "Break Ghosts 90 bpm" reference material:
+- 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
+
+**Always run this before programming drum patterns on a sliced 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.
+
+File-path resolution order: explicit `file_path` param, then Remote
+Script TCP (`get_simpler_file_path` via direct LOM read — most
+reliable), then M4L bridge UDP fallback (kept registered for
+environments where Remote Script is stale/unavailable; call
+`reload_handlers` to refresh without a full restart).
+
+## `add_drum_rack_pad`
+
+**BUG-2026-04-22#1 fix** — this tool closes a gap where
+`load_browser_item` replaced the existing chain on repeat calls and
+`load_sample_to_simpler` couldn't address nested rack paths. It chains
+six steps atomically: locate/auto-detect the Drum Rack, insert a chain,
+assign the trigger note, insert an empty Simpler into the chain, native
+`replace_sample_native` with nested addressing, Snap=0 hygiene.
+
+## `replace_simpler_sample` / `load_sample_to_simpler`
+
+Prefer `load_browser_item(track, uri)` when the file is browser-indexed
+— the M4L bridge's replace path can silently keep the bootstrap
+placeholder in some conditions (this is why both tools verify by
+reading back the device name post-load and error if the replace didn't
+actually take effect).
+
+Nested addressing (`chain_index` + `nested_device_index`) is Live
+12.4+ only (BUG-#1, 2026-04-22) — resolves at
+`track.devices[device_index].chains[chain_index].devices[nested_device_index or 0]`,
+which is how Drum Rack pad-by-pad construction works. The M4L bridge
+fallback cannot resolve nested paths; only the native 12.4 path honors
+`chain_index`.
+
+`load_sample_to_simpler`'s bootstrap flow (used pre-12.4 or when no
+Simpler exists yet): loads a dummy sample via the browser to force
+Ableton to create a Simpler, replaces it with the target file, then
+runs the same post-load hygiene/verification as `replace_simpler_sample`.
+
+## `simpler_set_warp` / `compressor_set_sidechain` — LOM gap tools
+
+**BUG-A2**: Python's Remote Script ControlSurface API can't reach
+Simpler's `warping`/`warp_mode` — they live on the sample child object
+(`SimplerDevice.sample.*`) that only Max for Live's JavaScript LiveAPI
+can step into. Hence the M4L bridge round-trip.
+
+**BUG-A3**: `compressor_set_sidechain`'s routing properties
+(`sidechain_input_routing_type`/`_channel`) aren't in Compressor's
+automatable parameter list, but Python's Remote Script reaches them
+directly as device properties (same LOM pattern as `set_track_routing`)
+— no M4L bridge needed here, unlike the warp case above.

package/livepilot/skills/livepilot-devices/references/device-parameter-units.md

@@ -0,0 +1,66 @@
+# Device Parameter Units Reference
+
+Full per-device unit table for `set_device_parameter` / `batch_set_parameters`
+(`mcp_server/tools/devices.py`). The tool docstrings carry the most
+commonly-hit gotchas inline; this file is the complete list plus the
+bug history that motivated the error-enrichment behavior.
+
+## Parameter ranges are NOT always 0-1 (BUG-B4 / B9 / 2026-04-26#2)
+
+Ableton devices use MIXED units depending on the parameter. Always read
+the `value_string` in the response (and `min`/`max` from
+`get_device_parameters`) before assuming 0-1 semantics:
+
+- Auto Filter `Frequency`: 20-135 index (NOT normalized)
+- Auto Filter Legacy `LFO Amount`: 0-30 absolute (displays as %)
+- Auto Filter `Resonance`: 0-1.25 on legacy, 0-1 on AutoFilter2
+- Auto Filter `Env. Modulation`: -127..+127 on legacy
+- Compressor I (legacy): pre-2010 units (Threshold dB direct)
+- **Compressor 2 (modern, default)**: 0-1 NORMALIZED. `Threshold 0.85 ≈
+  0 dB`, `Ratio 0.75 = 4:1`, `Release 0.16 = 30 ms`. Setting Threshold
+  to a dB value like -22 will fail. Compute normalized: `(dB + 50) / 50`
+  for typical dB→0-1 mapping, OR read the param's `value_string` after
+  a probe write.
+- **Saturator** `Drive`, `Output`, `Threshold`, `Color *`: 0-1
+  NORMALIZED (Drive 0.5 ≈ 0 dB, Drive 0.6 ≈ +7 dB).
+- Dynamic Tube, Vocoder: pre-2010 units
+- EQ Three `Frequency Hi/Lo`: 50Hz-15kHz absolute
+- Wavetable `Osc 1 Pos`: 0-1 normalized ✓
+- Drift / Analog / Operator macros: 0-1 normalized ✓
+- Pedal `Output`: -20..+20 dB direct
+- Pedal `Bass / Mid / Treble`: -1..+1 direct
+
+## Error enrichment (BUG-2026-04-26#2)
+
+If the Remote Script rejects the value as out-of-range,
+`set_device_parameter` fetches the parameter's actual
+min/max/value_string and re-raises with that context inline — saves a
+follow-up `get_device_parameters` round-trip in the agent loop after
+every miss.
+
+## Silent snapping (BUG #4, v1.20.2)
+
+Quantized-enum params (e.g. Beat Repeat's "Gate" at an integer enum)
+silently snap a caller's float request to the nearest step. Both
+`set_device_parameter` (via the `snapped` field) and
+`batch_set_parameters` (via `snapped_params`, tolerance 1e-5) surface
+this so callers driving deterministic state don't mistake a snap for
+success. `batch_set_parameters` accepts any of `parameter_index`,
+`parameter_name`, `name`, `index`, or the legacy `name_or_index` per
+entry (BUG-F4 / BUG-2026-04-22#3 — the sibling tools originally had
+inconsistent schemas, so all shapes are now normalized so
+`get_device_parameters`'s output can be fed straight back in).
+
+## Drum Rack construction workflow (12.3+)
+
+Shared by `insert_device`, `insert_rack_chain`, and the atomic
+`add_drum_rack_pad` (see `perception.md` for that one's full history):
+
+1. `insert_device(track_index, 'Drum Rack')` — create empty rack
+2. `insert_rack_chain(track_index, device_index)` — add a chain
+3. `set_drum_chain_note(chain_index, note=36)` — assign C1 (kick)
+4. `insert_device(track_index, 'Simpler', device_index=rack_idx,
+   chain_index=0)` — add the instrument into that chain
+
+On Live < 12.3, `insert_device`/`insert_rack_chain` return an error
+suggesting `find_and_load_device` instead.

package/livepilot/skills/livepilot-evaluation/references/capability-modes.md

@@ -173,7 +173,7 @@ Live 12.4 introduces a new capability tier that unlocks native LOM access for sa
 **Tool signatures:** unchanged. Callers do not need to detect the tier —
 routing is transparent.
 
-**Probe-first 12.4 surfaces in v1.27.2:**
+**Probe-first 12.4 surfaces in v1.27.3:**
 - `probe_link_audio()` reports observed peer/input/routing visibility and
   returns `manual_only`, `readable`, `routable`, or `unavailable`.
 - `probe_stem_workflow()` reports observed callable paths and returns

package/livepilot/skills/livepilot-mix-engine/SKILL.md

@@ -27,6 +27,14 @@ If the M4L analyzer bridge is absent, critics fall back to role-based heuristics
 
 For detailed frequency collision data, call `get_masking_report`. For a quick status overview without the full critic pass, call `get_mix_summary`.
 
+Each masking entry carries `measured` and `severity_basis`: `measured=True` /
+`severity_basis="spectral_overlap"` means `severity` came from real per-track
+spectral data; `measured=False` / `severity_basis="role_heuristic"` means it's
+a role-pair prior with no per-track measurement behind it. Treat
+`measured=False` entries as low-confidence hypotheses, not verified problems —
+solo the pair and read `get_master_spectrum` before acting on them. See
+`livepilot-core` SKILL.md → "Response Fields You Must Check".
+
 ### Step 2 — Plan
 
 Pick the highest-severity issue from the `issues` array. Call `plan_mix_move` with the issue data. The planner returns the smallest intervention that addresses the problem — a single parameter change, not a chain of edits.

package/livepilot/skills/livepilot-release/SKILL.md

@@ -31,7 +31,7 @@ Run this checklist EVERY time the user says "update everything", "push", "releas
 Current: **467 tools across 56 domains**.
 Spectral/analyzer (bridge-only): **38**. The remaining tool surface works without the bridge or degrades gracefully. Backed by 32 bridge commands.
 
-Verify: `grep -rc "@mcp.tool" mcp_server/tools/ | grep -v ":0" | awk -F: '{sum+=$2} END{print sum}'`
+Verify: `python3 scripts/sync_metadata.py --check`
 
 Files that reference tool count:
 - [ ] `README.md` — header ("467 tools. 56 domains"), bridge section ("38 spectral/analyzer tools require bridge")

package/livepilot/skills/livepilot-sample-engine/references/splice-tools-notes.md

@@ -0,0 +1,56 @@
+# Splice Tool Notes
+
+Implementation history and worked examples for the Splice-facing tools
+in `mcp_server/sample_engine/tools.py`. The tool docstrings carry the
+operational contract (params, return shape, gating rules); this file
+carries endpoint-capture history and full response examples.
+
+## `get_splice_credits` — full response example (Ableton Live plan)
+
+```json
+{
+  "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"
+}
+```
+
+`download_gating` is `"daily_quota"` on the Ableton Live plan (the
+100/day unmetered quota) or `"credit_floor"` on Sounds+/Creator/
+Creator+ plans (the `CREDIT_HARD_FLOOR` protects the last 5 credits).
+`connected: false` with zero credits means the Splice desktop app isn't
+running or `grpcio` isn't installed.
+
+## `splice_describe_sound` / `splice_generate_variation` — endpoint history
+
+Both hit GraphQL operations on `surfaces-graphql.splice.com`, captured
+via mitmproxy against Splice desktop 5.4.9 + the Sounds Plugin
+(status: LIVE as of 2026-04-22):
+
+- `splice_describe_sound` → `SamplesSearch` with `semantic=1` +
+  `rephrase=true`. This is the Sounds Plugin's "Describe a Sound"
+  feature — Splice's AI matches free-form descriptions like "dark
+  ambient pad with shimmer" to catalog samples.
+- `splice_generate_variation` → `AssetSimilarSoundsQuery` (the
+  right-click "Variations" menu item). Up to 10 results, no credit
+  cost — despite the tool name, this is a similarity-recommender
+  lookup, not AI audio synthesis (the "generate" naming in the original
+  handoff spec was aspirational).
+
+Both tools strip the raw GraphQL response before returning (~270KB of
+noise per call) — only the flattened sample list ships back.
+
+`splice_search_with_sound` was removed 2026-04-22 — the user does this
+in-Splice manually. The capture recipe for resurrecting it is at
+`docs/2026-04-22-splice-https-capture-recipe.md`.

package/livepilot/skills/livepilot-wonder/SKILL.md

@@ -111,6 +111,12 @@ Wonder Mode now serves two callers:
   references/move-family-diversity-rule.md)
 - 1 executable + 2 analytical is an honest, useful result
 - The `variant_count_actual` field tells you how many are real
+- **Check `degraded_reason`** on every `enter_wonder_mode` response — when
+  non-empty, fewer than 3 variants are actually executable (or none matched
+  and the set is cold-start fallback). Do not present a degraded set as
+  "three genuinely different options"; surface the degradation to the user
+  in the same terms the field describes. See `livepilot-core` SKILL.md →
+  "Response Fields You Must Check".
 
 ## Presenting Results
 

package/m4l_device/livepilot_bridge.js

@@ -34,7 +34,7 @@ outlets = 2; // 0: to udpsend (responses), 1: to buffer~/status
 // Single source of truth for the bridge version — bumped alongside the
 // rest of the release manifest. Surfaced in the UI via messnamed("livepilot_version", ...)
 // so the frozen .amxd visibly reports which build it was last exported from.
-var VERSION = "1.27.2";
+var VERSION = "1.27.3";
 
 // ── State ──────────────────────────────────────────────────────────────────
 

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.27.2"
+__version__ = "1.27.3"

package/mcp_server/atlas/__init__.py

@@ -13,6 +13,20 @@ from typing import Any, Dict, List, Optional
 
 logger = logging.getLogger(__name__)
 
+# BUG-B39: the real atlas scanner emits "instruments" / "audio_effects" but
+# older callers and test fixtures sometimes pass the singular "instrument" /
+# "effect". Hoisted to module scope (was previously re-declared inline in
+# search()) so both search() and the truncation-warning helper below share
+# one alias table instead of drifting independently.
+_CATEGORY_ALIASES: Dict[str, set] = {
+    "instrument": {"instrument", "instruments"},
+    "instruments": {"instrument", "instruments"},
+    "effect": {"effect", "effects", "audio_effects"},
+    "effects": {"effect", "effects", "audio_effects"},
+    "audio_effect": {"effect", "effects", "audio_effects", "audio_effect"},
+    "audio_effects": {"effect", "effects", "audio_effects", "audio_effect"},
+}
+
 
 class AtlasManager:
     """In-memory device atlas with indexed lookups."""
@@ -34,15 +48,50 @@ class AtlasManager:
             self._meta["version"] = data["version"]
         self._devices: List[Dict[str, Any]] = data.get("devices", [])
 
+        # P3-47 truncation observability: scan_full_library persists
+        # stats.category_truncated (keyed by atlas device-category, e.g.
+        # "drum_kits"/"sounds"/"samples") whenever the last scan hit its
+        # max_per_category cap — or ran out of the remote script's shared
+        # iteration safety bound — mid-category. Read it once here so
+        # search()/suggest() callers can be warned their results for a
+        # truncated category are a lower bound, not the full inventory.
+        raw_stats = data.get("stats", {})
+        raw_truncated = (
+            raw_stats.get("category_truncated", {})
+            if isinstance(raw_stats, dict) else {}
+        )
+        self._category_truncated: Dict[str, bool] = {
+            str(cat): bool(hit)
+            for cat, hit in raw_truncated.items()
+        } if isinstance(raw_truncated, dict) else {}
+
         # ── Build indexes ───────────────────────────────────────────
-        self._by_id: Dict[str, Dict[str, Any]] = {}
-        self._by_name: Dict[str, Dict[str, Any]] = {}  # lowercase key
+        # P2-12: _by_id / _by_name keep a LIST of every device sharing a
+        # key, in scan order, so colliding ids/names no longer shadow each
+        # other (last-wins). 719 ids + 702 names collide in the shipped
+        # atlas while URIs are 100% unique, so every device stays reachable
+        # via lookup_all() / atlas_device_info's surfaced URIs. lookup()
+        # still returns a single Dict (the first, deterministic match) to
+        # preserve its Optional[Dict] contract for compare()/browser.py/
+        # _research_engine.py.
+        self._by_id: Dict[str, List[Dict[str, Any]]] = {}
+        self._by_name: Dict[str, List[Dict[str, Any]]] = {}  # lowercase key
         self._by_uri: Dict[str, Dict[str, Any]] = {}
         self._by_category: Dict[str, List[Dict[str, Any]]] = {}
         self._by_tag: Dict[str, List[Dict[str, Any]]] = {}
         self._by_genre: Dict[str, List[Dict[str, Any]]] = {}
         self._by_pack: Dict[str, List[Dict[str, Any]]] = {}
 
+        # Perf batch (v1.27.3): a real 40k-device user atlas can carry
+        # ~16k duplicate ids/names/uris, and warning once per duplicate
+        # produced ~16k logger.warning calls (~122ms + multi-MB of stderr)
+        # at index-build time. Cap each category at _DUP_WARN_CAP explicit
+        # warnings and emit one summary line for the rest.
+        _DUP_WARN_CAP = 20
+        _dup_id_count = 0
+        _dup_name_count = 0
+        _dup_uri_count = 0
+
         for dev in self._devices:
             dev_id = dev.get("id", "")
             dev_name = dev.get("name", "")
@@ -50,26 +99,38 @@ class AtlasManager:
             dev_category = dev.get("category", "")
 
             if dev_id:
-                if dev_id in self._by_id and self._by_id[dev_id] is not dev:
-                    logger.warning(
-                        "atlas: duplicate device id %r shadows a prior entry "
-                        "(name=%r); last-wins", dev_id, dev_name,
-                    )
-                self._by_id[dev_id] = dev
+                bucket = self._by_id.setdefault(dev_id, [])
+                if bucket and dev not in bucket:
+                    _dup_id_count += 1
+                    if _dup_id_count <= _DUP_WARN_CAP:
+                        logger.warning(
+                            "atlas: duplicate device id %r (name=%r); both kept, "
+                            "lookup() returns the first — disambiguate by uri %r",
+                            dev_id, dev_name, dev_uri,
+                        )
+                if dev not in bucket:
+                    bucket.append(dev)
             if dev_name:
                 name_key = dev_name.lower()
-                if name_key in self._by_name and self._by_name[name_key] is not dev:
-                    logger.warning(
-                        "atlas: duplicate device name %r shadows a prior entry "
-                        "(id=%r); last-wins", dev_name, dev_id,
-                    )
-                self._by_name[name_key] = dev
+                name_bucket = self._by_name.setdefault(name_key, [])
+                if name_bucket and dev not in name_bucket:
+                    _dup_name_count += 1
+                    if _dup_name_count <= _DUP_WARN_CAP:
+                        logger.warning(
+                            "atlas: duplicate device name %r (id=%r); both kept, "
+                            "lookup() returns the first — disambiguate by uri %r",
+                            dev_name, dev_id, dev_uri,
+                        )
+                if dev not in name_bucket:
+                    name_bucket.append(dev)
             if dev_uri:
                 if dev_uri in self._by_uri and self._by_uri[dev_uri] is not dev:
-                    logger.warning(
-                        "atlas: duplicate device uri %r shadows a prior entry "
-                        "(id=%r); last-wins", dev_uri, dev_id,
-                    )
+                    _dup_uri_count += 1
+                    if _dup_uri_count <= _DUP_WARN_CAP:
+                        logger.warning(
+                            "atlas: duplicate device uri %r shadows a prior entry "
+                            "(id=%r); last-wins", dev_uri, dev_id,
+                        )
                 self._by_uri[dev_uri] = dev
 
             # Category index
@@ -124,6 +185,22 @@ class AtlasManager:
             if pack_name:
                 self._by_pack.setdefault(pack_name, []).append(dev)
 
+        if _dup_id_count > _DUP_WARN_CAP:
+            logger.warning(
+                "atlas: %d more duplicate device ids suppressed",
+                _dup_id_count - _DUP_WARN_CAP,
+            )
+        if _dup_name_count > _DUP_WARN_CAP:
+            logger.warning(
+                "atlas: %d more duplicate device names suppressed",
+                _dup_name_count - _DUP_WARN_CAP,
+            )
+        if _dup_uri_count > _DUP_WARN_CAP:
+            logger.warning(
+                "atlas: %d more duplicate device uris suppressed",
+                _dup_uri_count - _DUP_WARN_CAP,
+            )
+
     # ── Properties ──────────────────────────────────────────────────
 
     @property
@@ -155,6 +232,49 @@ class AtlasManager:
             },
         }
 
+    # ── Truncation observability (P3-47) ──────────────────────────
+    def truncated_categories(self) -> List[str]:
+        """Categories where the atlas's last scan_full_library run hit
+        its max_per_category cap (or the remote script's shared iteration
+        safety bound) mid-category. Devices in these categories are a
+        lower bound, not the full inventory, until a rescan completes."""
+        return sorted(
+            cat for cat, hit in self._category_truncated.items() if hit
+        )
+
+    def truncation_warning(self, category: str = "all") -> Optional[str]:
+        """Return a warning string if `category` overlaps a category
+        flagged truncated in the loaded atlas's scan stats, else None.
+
+        category="all" (the default `atlas_search`/`atlas_suggest` filter)
+        warns if ANY category was truncated, since an unfiltered query
+        silently includes those partial results alongside complete ones.
+        A specific category only warns when it (or an alias — see
+        _CATEGORY_ALIASES) is in the truncated set.
+        """
+        truncated = self.truncated_categories()
+        if not truncated:
+            return None
+
+        if category == "all":
+            hit = truncated
+        else:
+            allowed = _CATEGORY_ALIASES.get(category, {category})
+            hit = [cat for cat in truncated if cat in allowed]
+            if not hit:
+                return None
+
+        return (
+            "Atlas categor%s %s may be incomplete — the last scan hit its "
+            "size cap for %s. Run scan_full_library(force=True) (raise "
+            "max_per_category if your library is unusually large) for a "
+            "complete inventory before trusting an exhaustive search here."
+        ) % (
+            "y" if len(hit) == 1 else "ies",
+            ", ".join(sorted(hit)),
+            "this category" if len(hit) == 1 else "these categories",
+        )
+
     # ── Pack lookup ────────────────────────────────────────────────
     def pack_info(self, pack_name: str) -> Dict[str, Any]:
         """Return summary of a pack — device list + enrichment coverage.
@@ -217,19 +337,52 @@ class AtlasManager:
     # ── Lookup ──────────────────────────────────────────────────────
 
     def lookup(self, name_or_id: str) -> Optional[Dict[str, Any]]:
-        """Exact match by ID, name (case-insensitive), or URI. Returns None on miss."""
+        """Exact match by ID, name (case-insensitive), or URI. Returns None on miss.
+
+        When an id/name collides across devices (719 ids / 702 names in the
+        shipped atlas), this returns the FIRST device in scan order
+        deterministically. Use lookup_all() to reach every colliding device,
+        or pass a unique URI (URIs never collide) to target a specific one.
+        """
         # Try ID first
-        if name_or_id in self._by_id:
-            return self._by_id[name_or_id]
+        bucket = self._by_id.get(name_or_id)
+        if bucket:
+            return bucket[0]
         # Try name (case-insensitive)
-        lower = name_or_id.lower()
-        if lower in self._by_name:
-            return self._by_name[lower]
-        # Try URI
+        name_bucket = self._by_name.get(name_or_id.lower())
+        if name_bucket:
+            return name_bucket[0]
+        # Try URI — the only key that is guaranteed unique
         if name_or_id in self._by_uri:
             return self._by_uri[name_or_id]
         return None
 
+    def lookup_all(self, name_or_id: str) -> List[Dict[str, Any]]:
+        """Return EVERY device matching an id, name, or URI — collision-aware.
+
+        P2-12: lookup() returns a single Dict (its contract), which shadows
+        the ~719 devices sharing a colliding id and ~702 sharing a name. This
+        companion returns all of them so id/name-keyed tools can disambiguate
+        (e.g. surface each candidate's unique URI). Matches are returned in
+        scan order with duplicates removed; an exact URI match alone returns
+        the single device for that URI.
+        """
+        out: List[Dict[str, Any]] = []
+        seen: set[int] = set()
+
+        def _extend(devs: List[Dict[str, Any]]) -> None:
+            for d in devs:
+                if id(d) not in seen:
+                    seen.add(id(d))
+                    out.append(d)
+
+        _extend(self._by_id.get(name_or_id, []))
+        _extend(self._by_name.get(name_or_id.lower(), []))
+        uri_hit = self._by_uri.get(name_or_id)
+        if uri_hit is not None:
+            _extend([uri_hit])
+        return out
+
     # ── Search ──────────────────────────────────────────────────────
 
     def search(
@@ -243,22 +396,10 @@ class AtlasManager:
         query_words = query_lower.split()
         results: List[Dict[str, Any]] = []
 
-        # BUG-B39: the real atlas scanner emits "instruments" /
-        # "audio_effects" but older callers and test fixtures sometimes
-        # pass the singular "instrument" / "effect". Build a tolerant
-        # category alias set so both forms work.
-        _CAT_ALIASES = {
-            "instrument": {"instrument", "instruments"},
-            "instruments": {"instrument", "instruments"},
-            "effect": {"effect", "effects", "audio_effects"},
-            "effects": {"effect", "effects", "audio_effects"},
-            "audio_effect": {"effect", "effects", "audio_effects",
-                             "audio_effect"},
-            "audio_effects": {"effect", "effects", "audio_effects",
-                              "audio_effect"},
-        }
+        # Tolerant category alias set so "instrument" and "instruments"
+        # (etc.) both work — see module-level _CATEGORY_ALIASES.
         allowed_cats = (
-            _CAT_ALIASES.get(category, {category})
+            _CATEGORY_ALIASES.get(category, {category})
             if category != "all" else None
         )