livepilot 1.27.1 → 1.27.3

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## v1.27.3 — 2026-07-10
+
+Deep-review remediation campaign (2026-07-09, on top of the 2026-06-24 fix batch): event-loop
+blocking eliminated tree-wide, release-pipeline gates hardened, atlas scan truncation fixed,
+Splice connection health, state-layer race/replay guards, docs drift automation, and +262 tests
+(4326 → 4597 passing). No change to the tool surface (467 tools / 56 domains).
+
+### Fixed — event loop (systemic)
+- Every remaining blocking call in async tool paths offloaded (~80 sites across 13 files):
+  the composer fast/full/develop apply executors, the shared plan-step executor
+  (`execution_router._execute_step_async`), preview/experiment paths, analyzer helper call
+  sites, automation session-record, agent_os iteration, device-forge/file I/O, and lifespan
+  subprocess probes. New canonical wrapper `AbletonConnection.send_command_async()`.
+- The AST regression guard now scans ALL of `mcp_server/` (was analyzer.py-only) with
+  one-hop transitive detection and file-I/O/subprocess patterns (`scripts/scan_async_blocking.py`).
+
+Live-verified on Ableton 12.4.2 (2026-07-10): per-track volume reporting, force_arrangement
+with return tracks, sidechain name resolution (both casings), analyzer bridge reconnect, and a
+full 40k-device library rescan with zero category truncation.
+
+### Fixed — correctness
+- Sidechain source matching gained a case-insensitive EXACT tier (found live: Live 12.4
+  routing menus can list bare unprefixed track names, where the "-name" suffix fallback
+  never fires); matching ladder extracted into a tested helper.
+- `audit_layer` §5.1 timbre check was a silent double no-op (wrong call signature + uppercase
+  band table vs lowercase producers) — now plumbs cached analyzer spectrum and case-folds.
+- Atlas scans no longer truncate alphabetically at 1000 entries/category (drum kits previously
+  cut off before reaching most of the alphabet); scans record per-category counts + truncation
+  flags, and atlas searches warn when a truncated category is queried. Rescan required to
+  rebuild an existing user atlas (`scan_full_library(force=True)`).
+- Semantic mix/sound-design/transition/performance moves now nudge track volume RELATIVE to the
+  current level (bounded, direction-safe) instead of writing absolute constants; the Remote
+  Script now reports per-track volume in `get_session_info`.
+- Splice client marks itself degraded on RPC failure and self-heals with a one-shot reconnect —
+  a Splice desktop restart no longer yields silent fake "0 results" for the session; quota
+  check-and-record is atomic; HTTP retry no longer sleeps after the final attempt.
+- Preview/wonder cached plans carry a session fingerprint and refuse commit with STATE_ERROR
+  when the session changed shape; shared caches are lock-guarded; persisted taste/project
+  stores back up before any version-mismatch reset; `song_brain` ids are content-aware.
+- `get_emotional_arc` harmonic-instability term computed (was structurally zero);
+  flucoma probe no longer reports empty dirs as installed; composer engine renumbers layers
+  after unresolved-sample drops on the experiment-escalation path.
+
+### Changed — release gates & CI
+- New CI jobs: MCPB bundle build (asset previously shipped missing for 4 releases),
+  Python 3.11 compatibility for `remote_script/` (compileall + vermin), content-level
+  .amxd freeze check (full bridge command set, not just the version string).
+- `bin/livepilot.js` venv staleness keyed on a requirements.txt content hash (hardcoded import
+  list had drifted — upgrading users silently never installed the Splice gRPC dependencies).
+- `sync_metadata.py` validates JSON manifests version-field-by-field (caught a live
+  server.json split-version); docs Domain Map is now generated from the live registry;
+  banner assets and README What's New are drift-guarded.
+
+### Changed — performance & analysis quality
+- Server import ~2.0s → ~0.9s (lazy overlay index + libyaml CSafeLoader); atlas duplicate
+  warnings throttled; test suite wall-clock ~41s → ~32s.
+- Mix-critic confidence values are data-derived (sample size, measured-vs-heuristic basis,
+  margin) instead of hardcoded literals; `analyze_mix`/`get_mix_issues` accept
+  `target_style="loud_master"` to suppress the over-compressed flag for intentionally loud
+  masters; Wonder Mode ranking surfaces a `boldest_executable` slot alongside the safe pick.
+- Security hardening: corpus plugin-id path validation, loopback-only UDP analyzer ingestion,
+  competing-TCP-client identification in eviction errors.
+
+### Changed — dependencies
+- **2026-06-25** — Raised the Python floor to 3.12: numpy>=2.5.0 and scipy>=1.18.0 declare `Requires-Python >=3.12`, so the prior 3.11 floor blocked both dependency bumps across the CI matrix. CI now tests only Python 3.12; the install-time Python-version diagnostic and manifest/docs floor references were updated to match. `remote_script/` stays 3.11-syntax-compatible for Ableton's embedded Python (Live 12.3) — the CI matrix change does not relax that constraint.
+
+## v1.27.2 — 2026-06-23
+
+Maintenance release: M4L bridge response-correlation + chunk-reassembly hardening, plan-routing fixes, a Python 3.11 floor with clearer install diagnostics, and a Remote Script Group-track crash guard. No change to the tool surface (467 tools / 56 domains). Re-frozen LivePilot_Analyzer.amxd (analyzer reports 1.27.2).
+
+### Fixed — M4L bridge
+- Correlate responses by request id across batched reads (`get_params` / `get_hidden_params` / `get_auto_state`): the id is captured per command in the analyzer JS and echoed on both single-packet and chunked responses, so an interleaved or timed-out command can no longer resolve another command's future.
+- Chunk reassembly buckets per request id, bounds-checks the chunk index, and requires every index present before reassembling — fixes a `KeyError` / silent-loss + full-timeout path on duplicate or out-of-range chunks.
+- Non-blocking UDP socket so the miditool response path cannot stall the asyncio event loop; clear the capture future after completion.
+
+### Fixed — routing & Remote Script
+- `compressor_set_sidechain` now classifies as an MCP tool (TCP Remote Script path) instead of being mis-routed to the M4L JS bridge; `get_master_rms` is now dispatchable in plans; removed the dead duplicate `get_simpler_file_path` bridge entry.
+- `get_track_info` no longer crashes on Group/Return tracks (guards the LOM-fragile arm/input properties).
+- `reload_handlers` reports per-module reload errors instead of silently swallowing them.
+- Connection retry tears down the stale socket under the lock.
+
+### Changed — install & docs
+- Raised the Python floor to 3.11 (numpy/scipy publish no wheels for 3.9/3.10) with a clear pre-flight message; pip failures surface captured output + a version hint, and the expected grpcio-tools resolver warning is pre-announced.
+- `consult_ableton_knowledge` docstrings corrected; fast brief now notes the `mcp__Ableton_Knowledge__` prefix and that the knowledge MCP is optional; fixed an over-permissive tool-name test.
+
+
 ## v1.27.1 — 2026-06-21
 
 Maintenance release: 35 verified fixes from a deep multi-agent audit, recursive installed-plugin scanning, and Windows-CI hardening. No change to the tool surface (467 tools / 56 domains).

package/README.md

@@ -38,14 +38,17 @@
 
 ---
 
-## What's New in v1.27.1
+## What's New in v1.27.3
 
-A maintenance release that fixes 35 issues from a deep audit and restores tools that had silently broken:
+A deep-review remediation release — ~150 fixes across two audit campaigns, no change to the tool surface (467 tools / 56 domains):
 
-- **Restored tools** — `augment_with_samples`, `get_composition_plan`, `propose_composer_branches`, `check_clip_key_consistency`, and `compare_phrase_renders` were crashing or returning empty results; they now work.
-- **Recursive plugin scanning (#44)** — the User Corpus scanner now finds plugins nested in vendor subfolders (e.g. `VST3/<Vendor>/Plugin.vst3`) instead of only the top level.
-- **Truer analysis** — reference-gap, hook-salience, dynamics, drop-detection, harmony-slot, and grader fixes that previously produced fabricated or empty results.
-- **Safer & faster** — Splice credit-gating fixed, blocking sample I/O moved off the event loop, unbounded tool responses capped, and the M4L bridge no longer loses responses on UDP reordering.
+- **Event-loop blocking eliminated tree-wide** — every remaining blocking call in async tool paths (composer apply executors, the shared plan-step executor, preview/experiment paths, ~80 sites in 13 files) now offloads to a worker thread; a repo-wide AST regression guard keeps it that way. Long composes no longer freeze concurrent tools or the analyzer bridge.
+- **Atlas scans no longer truncate** — library scans previously capped each category at 1,000 entries alphabetically (most drum one-shots were unreachable); the cap is now 25,000 with per-category truncation flags and rescan warnings. Run `scan_full_library(force=True)` once to rebuild your atlas.
+- **Splice self-heals** — a Splice desktop restart no longer silently turns every search into fake "0 results"; the client marks itself degraded and reconnects on the next call.
+- **Safer state** — cached preview/wonder plans carry a session fingerprint and refuse to replay against a session that changed shape; persisted taste/project stores back up before any reset.
+- **Stronger release gates** — the MCPB bundle, .amxd freeze content, and Python 3.11 Remote Script compatibility are now all CI-enforced.
+- **Python 3.12 floor** for the MCP server (numpy ≥2.5 / scipy ≥1.18); the Remote Script stays 3.11-compatible for Ableton's embedded Python.
+- **v1.27.1** fixed 35 issues from a deep audit and restored tools that had silently broken (`augment_with_samples`, `get_composition_plan`, `propose_composer_branches`, `check_clip_key_consistency`, `compare_phrase_renders`), plus recursive installed-plugin scanning.
 - **v1.27.0** added two read-only Live 12.4 capability-probe tools (`probe_link_audio`, `probe_stem_workflow`).
 
 Full details in the [CHANGELOG](CHANGELOG.md).
@@ -751,7 +754,7 @@ npx livepilot --version    # Show version
 | Requirement | Minimum |
 |-------------|---------|
 | Ableton Live | **12** (any edition). Suite required for Max for Live bridge and stock instruments |
-| Python | 3.9+ |
+| Python | 3.12+ (numpy>=2.5 / scipy>=1.18 require Python 3.12) |
 | Node.js | 18+ |
 | OS | macOS / Windows |
 | Splice | Desktop app with downloaded samples (optional — enables SQLite metadata search) |

package/bin/livepilot.js

@@ -15,6 +15,13 @@ const REQUIREMENTS = path.join(ROOT, "requirements.txt");
 // Python detection
 // ---------------------------------------------------------------------------
 
+// Minimum Python is 3.12: numpy>=2.5.0 and scipy>=1.18.0 (see requirements.txt)
+// declare requires-python ">=3.12". An older interpreter passes a looser gate,
+// the venv is created, then `pip install` aborts with a cryptic "no matching
+// distribution" — the exact install failure users hit. Gate here so we fail
+// early with a clear message.
+const MIN_PY_MINOR = 12;
+
 function findPython() {
   // On Windows, also try the "py -3" launcher which avoids the
   // Microsoft Store stub that "python3" resolves to.
@@ -22,6 +29,7 @@ function findPython() {
     ? ["python", "python3", "py"]
     : ["python3", "python"];
 
+  let tooOld = null; // highest 3.x below the floor we saw, for a clear error
   for (const cmd of candidates) {
     try {
       const args = cmd === "py" ? ["-3", "--version"] : ["--version"];
@@ -33,17 +41,26 @@ function findPython() {
       if (match) {
         const major = parseInt(match[1], 10);
         const minor = parseInt(match[2], 10);
-        if (major === 3 && minor >= 9) {
+        if (major === 3 && minor >= MIN_PY_MINOR) {
           // For "py" launcher, the actual command to use is "py -3"
           const actualCmd = cmd === "py" ? "py" : cmd;
           const actualArgs = cmd === "py" ? ["-3"] : [];
           return { cmd: actualCmd, version: out, prefixArgs: actualArgs };
         }
+        // Found Python 3 but below 3.12 — remember the newest for diagnostics.
+        if (major === 3 && (!tooOld || minor > tooOld.minor)) {
+          tooOld = { version: out, minor };
+        }
       }
     } catch {
       // command not found or failed — try next
     }
   }
+  // Signal "present but too old" distinctly from "absent" so callers can give
+  // an actionable message instead of a misleading "not found".
+  if (tooOld) {
+    return { tooOld: true, version: tooOld.version };
+  }
   return null;
 }
 
@@ -84,6 +101,83 @@ function findOtherLiveClient(host, port) {
 // Virtual environment bootstrap
 // ---------------------------------------------------------------------------
 
+/**
+ * Run `pip install -r requirements.txt` with captured stderr so a failure
+ * yields an actionable message instead of an opaque "Command failed".
+ */
+function pipInstall(venvPy) {
+  // One pip resolver warning about grpcio-tools / protobuf<7 is EXPECTED and
+  // harmless: LivePilot imports only the pre-generated Splice stubs at runtime,
+  // never grpcio-tools. Pre-announce it so it doesn't read as a failure.
+  console.error("  (a single grpcio-tools/protobuf resolver warning is expected and safe)");
+  try {
+    execFileSync(venvPy, ["-m", "pip", "install", "-q", "-r", REQUIREMENTS], {
+      cwd: ROOT,
+      stdio: ["pipe", "pipe", "pipe"],
+      encoding: "utf-8",
+      timeout: 120000,
+    });
+  } catch (err) {
+    const stderr = (err && err.stderr ? String(err.stderr) : "").trim();
+    console.error("");
+    console.error("LivePilot: dependency installation failed.");
+    if (/No matching distribution|requires-python|Could not find a version/i.test(stderr)) {
+      console.error("  Most likely your Python is too old — LivePilot needs Python >= 3.12");
+      console.error("  (numpy>=2.5 / scipy>=1.18 require Python 3.12). Install 3.12+, delete the");
+      console.error("  .venv folder, and retry.");
+    }
+    const tail = stderr.split("\n").filter(Boolean).slice(-12);
+    if (tail.length) {
+      console.error("");
+      console.error("  pip output (last lines):");
+      for (const line of tail) console.error("    " + line);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Content hash of requirements.txt — the venv staleness signal.
+ *
+ * The previous check was a hardcoded import list that silently drifted from
+ * requirements.txt (grpcio/protobuf were added for the Splice gRPC surface
+ * but never joined the list, so upgrading users kept a venv without them and
+ * the feature silently disabled itself). Hashing the file makes staleness
+ * detection automatically correct for every future dependency change.
+ */
+function requirementsHash() {
+  const crypto = require("crypto");
+  const reqs = fs.readFileSync(path.join(ROOT, "requirements.txt"));
+  return crypto.createHash("sha256").update(reqs).digest("hex");
+}
+
+function venvStampPath() {
+  return path.join(ROOT, VENV_DIR, ".requirements-sha256");
+}
+
+function writeVenvStamp() {
+  try {
+    fs.writeFileSync(venvStampPath(), requirementsHash() + "\n");
+  } catch {
+    // Non-fatal: worst case the next run reinstalls.
+  }
+}
+
+/**
+ * Pure decision function for venv staleness — extracted from ensureVenv so
+ * the reinstall/reuse/create branching can be unit-tested without touching
+ * the filesystem or spawning pip/venv. Behavior-identical to the inline
+ * logic it replaces:
+ *   - no venv on disk                       -> "create"
+ *   - venv exists, stamp matches hash       -> "reuse"
+ *   - venv exists, stamp missing/mismatched -> "update"
+ */
+function decideVenvAction(venvExists, storedStamp, currentHash) {
+  if (!venvExists) return "create";
+  if (storedStamp === currentHash) return "reuse";
+  return "update";
+}
+
 /**
  * Ensure a local .venv exists with dependencies installed.
  * Returns the path to the venv Python binary.
@@ -91,29 +185,31 @@ function findOtherLiveClient(host, port) {
 function ensureVenv(systemPython, prefixArgs) {
   const prefix = prefixArgs || [];
   const venvPy = venvPython();
+  const venvExists = fs.existsSync(venvPy);
 
-  // Check if venv already exists and has our deps
-  if (fs.existsSync(venvPy)) {
+  let stamp = null;
+  if (venvExists) {
     try {
-      execFileSync(venvPy, ["-c", "import fastmcp; import midiutil; import pretty_midi; import numpy; import pyloudnorm; import soundfile; import scipy; import mutagen"], {
-        encoding: "utf-8",
-        timeout: 10000,
-        stdio: "pipe",
-      });
-      return venvPy; // venv exists and all deps importable
+      stamp = fs.readFileSync(venvStampPath(), "utf-8").trim();
     } catch {
-      // venv exists but deps missing — reinstall
-      console.error("LivePilot: reinstalling Python dependencies...");
-      execFileSync(venvPy, ["-m", "pip", "install", "-q", "-r", REQUIREMENTS], {
-        cwd: ROOT,
-        stdio: ["pipe", "pipe", "inherit"],
-        timeout: 120000,
-      });
-      return venvPy;
+      stamp = null; // pre-hash venv (or stamp deleted) — verify by reinstall
     }
   }
 
-  // Create venv from scratch
+  const action = decideVenvAction(venvExists, stamp, requirementsHash());
+
+  if (action === "reuse") {
+    return venvPy; // venv exists and was installed from this exact requirements.txt
+  }
+
+  if (action === "update") {
+    console.error("LivePilot: requirements changed — updating Python dependencies...");
+    pipInstall(venvPy);
+    writeVenvStamp();
+    return venvPy;
+  }
+
+  // action === "create"
   console.error("LivePilot: setting up Python environment (first run)...");
   execFileSync(systemPython, [...prefix, "-m", "venv", VENV_DIR], {
     cwd: ROOT,
@@ -122,11 +218,8 @@ function ensureVenv(systemPython, prefixArgs) {
   });
 
   console.error("LivePilot: installing dependencies...");
-  execFileSync(venvPython(), ["-m", "pip", "install", "-q", "-r", REQUIREMENTS], {
-    cwd: ROOT,
-    stdio: ["pipe", "pipe", "inherit"],
-    timeout: 120000,
-  });
+  pipInstall(venvPython());
+  writeVenvStamp();
 
   return venvPython();
 }
@@ -262,11 +355,15 @@ async function doctor() {
 
   // 1. Python
   const pyInfo = findPython();
-  if (pyInfo) {
+  if (pyInfo && !pyInfo.tooOld) {
     console.log("  Python: %s (%s)", pyInfo.version, pyInfo.cmd);
+  } else if (pyInfo && pyInfo.tooOld) {
+    console.log("  Python: %s found, but LivePilot needs >= 3.12", pyInfo.version);
+    console.log("    Fix: install Python 3.12+ (numpy>=2.5 / scipy>=1.18 require Python 3.12)");
+    ok = false;
   } else {
-    console.log("  Python: NOT FOUND (need >= 3.9)");
-    console.log("    Fix: install Python 3.9+ and add to PATH");
+    console.log("  Python: NOT FOUND (need >= 3.12)");
+    console.log("    Fix: install Python 3.12+ and add to PATH");
     ok = false;
   }
 
@@ -686,10 +783,15 @@ async function setup() {
   // 1. Python
   console.log("Step 1/5: Checking Python...");
   const pyInfo = findPython();
-  if (pyInfo) {
+  if (pyInfo && !pyInfo.tooOld) {
     console.log("  ✓ %s", pyInfo.version);
+  } else if (pyInfo && pyInfo.tooOld) {
+    console.log("  ✗ %s found, but LivePilot needs Python >= 3.12", pyInfo.version);
+    console.log("    (numpy>=2.5 / scipy>=1.18 require Python 3.12 — pip would fail)");
+    console.log("    Install: brew install python@3.12 (macOS) or python.org (Windows)");
+    ok = false;
   } else {
-    console.log("  ✗ Python >= 3.9 not found");
+    console.log("  ✗ Python >= 3.12 not found");
     console.log("    Install: brew install python@3.12 (macOS) or python.org (Windows)");
     ok = false;
   }
@@ -722,7 +824,7 @@ async function setup() {
   // 3. Bootstrap Python venv
   console.log("");
   console.log("Step 3/5: Setting up Python environment...");
-  if (pyInfo) {
+  if (pyInfo && !pyInfo.tooOld) {
     try {
       ensureVenv(pyInfo.cmd, pyInfo.prefixArgs);
       console.log("  ✓ Virtual environment ready");
@@ -730,6 +832,8 @@ async function setup() {
       console.log("  ✗ Failed: %s", err.message);
       ok = false;
     }
+  } else if (pyInfo && pyInfo.tooOld) {
+    console.log("  ⊘ Skipped (%s found, need Python >= 3.12)", pyInfo.version);
   } else {
     console.log("  ⊘ Skipped (no Python)");
   }
@@ -917,12 +1021,18 @@ async function main() {
 
   // Default: start MCP server
   const pyInfo = findPython();
-  if (!pyInfo) {
-    console.error("Error: Python >= 3.9 is required but was not found.");
+  if (!pyInfo || pyInfo.tooOld) {
+    if (pyInfo && pyInfo.tooOld) {
+      console.error("Error: found %s, but LivePilot requires Python >= 3.12.", pyInfo.version);
+      console.error("  numpy>=2.5.0 and scipy>=1.18.0 require Python >= 3.12,");
+      console.error("  so dependency installation would fail. Install Python 3.12 or newer.");
+    } else {
+      console.error("Error: Python >= 3.12 is required but was not found.");
+      console.error("  Install Python 3.12+ and ensure 'python3' or 'python' is on your PATH.");
+    }
     console.error("");
-    console.error("Install Python 3.9+ and ensure 'python3' or 'python' is on your PATH.");
     console.error("  macOS:   brew install python@3.12");
-    console.error("  Ubuntu:  sudo apt install python3");
+    console.error("  Ubuntu:  sudo apt install python3.12");
     console.error("  Windows: https://www.python.org/downloads/");
     process.exit(1);
   }
@@ -965,7 +1075,16 @@ async function main() {
   });
 }
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+// Only auto-run the CLI when this file is executed directly (`node
+// bin/livepilot.js ...` or `npx livepilot ...`). When `require()`d as a
+// module — e.g. from tests exercising `decideVenvAction` in isolation —
+// skip the side-effecting entrypoint. Behavior-identical for real CLI
+// invocations; this guard only matters when the file is `require()`d.
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+module.exports = { decideVenvAction, requirementsHash, venvStampPath };

package/livepilot/.Codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.27.1",
+  "version": "1.27.3",
   "description": "Agentic production system for Ableton Live 12 \u2014 467 tools, 56 domains, 44 semantic moves, device atlas (5264 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"

package/livepilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.27.1",
+  "version": "1.27.3",
   "description": "Agentic production system for Ableton Live 12 \u2014 467 tools, 56 domains, 44 semantic moves, device atlas (5264 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": {
     "name": "Pilot Studio"

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

@@ -47,7 +47,7 @@ Agentic production system for Ableton Live 12. 467 tools across 56 domains, thre
     - **Parameter ranges are NOT always 0-1.** Auto Filter Frequency is 20-135. Bit Depth is 1-16. Always read `value_string` to see actual units.
 16. **NEVER apply automation recipes without understanding the target parameter's range** — recipes generate 0-1 curves that get auto-scaled for device parameters, but always verify the result
 17. **LivePilot_Analyzer must be LAST on master chain** — always place after ALL effects (EQ, Compressor, Utility, etc.) so it measures the final post-processing output, not the raw signal. When loading effects on master, either load them before the analyzer or move the analyzer to end afterward
-18. **Remote Script reload workflow** — after any edit to `remote_script/LivePilot/*.py`: run `npx livepilot --install` (NOT `node installer/install.js` — that raw file only module-exports the install function and silently no-ops as a script), then call `reload_handlers` (MCP tool, domain: diagnostics). NEVER instruct the user to toggle the Control Surface in Live Preferences. The tool uses pkgutil + importlib to re-fire `@register` decorators in-place in <1s while the TCP connection stays open. Standard procedure for every handler change — not just releases
+18. **Remote Script reload workflow** — after any edit to `remote_script/LivePilot/*.py`: install, then call `reload_handlers` (MCP tool, domain: diagnostics). From a LOCAL CHECKOUT the install command is `node bin/livepilot.js --install` — `npx livepilot --install` fetches the PUBLISHED npm package and overwrites local edits with stale code. Use `npx livepilot --install` only for the published package (end-user installs). Either way, NOT `node installer/install.js` — that raw file only module-exports the install function and silently no-ops as a script. NEVER instruct the user to toggle the Control Surface in Live Preferences. The tool uses pkgutil + importlib to re-fire `@register` decorators in-place in <1s while the TCP connection stays open. Standard procedure for every handler change — not just releases
 
 ## Tool Speed Tiers
 
@@ -79,6 +79,38 @@ Report ALL errors to the user immediately. Common failure modes:
 - **M4L Analyzer not connected** — if `get_master_spectrum` errors with "Analyzer not detected", call `ensure_analyzer_on_master`. If it returns `install_required`, call `install_m4l_device(source_path="<repo>/m4l_device/LivePilot_Analyzer.amxd")` and retry. If it errors with "UDP bridge not connected", try `reconnect_bridge` first
 - **Another client connected** — Remote Script only accepts one TCP client on port 9878. If you see this error, the MCP server is already connected. Use MCP tools instead of raw TCP
 
+## Response Fields You Must Check
+
+These fields were added to existing tool responses. They aren't optional
+extras — each one changes what you're allowed to claim to the user.
+
+- **`degraded_reason`** (`enter_wonder_mode` / Wonder Mode) — non-empty when
+  fewer than 3 of the returned variants are actually executable, or when no
+  matching moves were found and variants are cold-start fallbacks. Contract:
+  if `degraded_reason` is set, do NOT present the set as "three genuinely
+  different options" — disclose the degradation honestly. See
+  `livepilot-wonder`.
+- **`unenforced_constraints`** (`apply_creative_constraint_set` / Creative
+  Constraints) — lists constraint names that are advisory-only; the engine
+  cannot mechanically verify them against compiled steps. Contract: for every
+  name in this list, YOU must self-police that constraint manually — the
+  tool returning `valid: true` does not mean an advisory constraint wasn't
+  violated.
+- **`measured` / `severity_basis`** (`get_masking_report` / Mix Engine) — a
+  masking entry's `severity` is either a real per-track spectral-overlap
+  measurement (`measured=True`, `severity_basis="spectral_overlap"`) or a
+  role-pair heuristic constant (`measured=False`,
+  `severity_basis="role_heuristic"`). Contract: treat `measured=False`
+  entries as low-confidence priors, not verified problems — solo the tracks
+  and read `get_master_spectrum` before taking a mixing action based on them
+  (§3 Analysis Before Action). See `livepilot-mix-engine`.
+- **`load_via` / `browse_hint`** (Atlas — `atlas_search`, `atlas_suggest`,
+  `atlas_device_info`, etc.) — set when an atlas entry's `uri` is cleared
+  because it's a known-broken M4L pack-instrument reference. Contract: when
+  `load_via == "preset"`, do NOT call `load_browser_item` with the atlas
+  `uri` (it's empty/invalid) — call `search_browser` with `browse_hint`
+  instead to resolve a real URI first.
+
 ## Technique Memory
 
 Three modes:

package/livepilot/skills/livepilot-core/references/atlas-tool-notes.md

@@ -0,0 +1,69 @@
+# Atlas Tool Notes
+
+Implementation history and rationale for `mcp_server/atlas/tools.py`
+tools. The tool docstrings carry the operational contract (params,
+return shape, behavior); this file carries the bug history and
+step-by-step internals that explain *why* a tool behaves a certain way,
+for when that context is actually needed.
+
+## `scan_full_library` — scan cap history
+
+`max_per_category` defaults to 25000, matching the remote script's own
+default. The original hardcoded 1000 cap silently truncated large
+categories in browser-tree (alphabetical) order — e.g. `drum_kits`
+stopped at "Crash" (0 kicks, 2 hats), and the `samples` category alone
+has ~22,000 items per the browser tree, so a "1000 samples" count was
+wrong by a factor of 22 (BUG-2026-04-22#12). Raise the cap further for
+even bigger libraries; lower it for fast smoke scans.
+
+`truncated_categories` / `stats.category_truncated` are 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 (P3-47).
+
+Scans always write to the user atlas path
+(`~/.livepilot/atlas/device_atlas.json`), never the bundled baseline —
+this keeps personal inventories (packs, user_library, plugins) out of
+the repo and surviving npm updates (v1.22.0). Enrichments are still
+read from the bundled package.
+
+## `atlas_describe_chain` — internals
+
+Free-text → chain proposal pipeline, mirroring `splice_describe_sound`
+for the device library (`atlas_chain_suggest` is the structured-input
+sibling — role + genre instead of a sentence):
+
+1. Parse role hints from the description (bass/lead/pad/keys/
+   percussion/drums/vocal/fx keyword buckets)
+2. Parse aesthetic hints — artist names map to genre/character tags
+   (cross-reference `artist-vocabularies.md`), plus explicit genre
+   names and character words (warm/cold/bright/dark/lush/...)
+3. Search the atlas (factory + user overlay namespaces) with those terms
+4. Propose the top devices per role with brief rationale, then take the
+   top suggestion per role as a simple ordered `chain_proposal`
+
+Does not autoload anything — the caller reviews/adjusts, then executes
+via `load_browser_item` + effects.
+
+## `atlas_techniques_for_device` — index
+
+Backed by the reverse-index file `device_techniques_index.json`
+(auto-generated from the knowledge base — regenerate via the
+post-v1.17 reverse-index builder script when adding new techniques;
+rare, since most additions happen through enrichment YAMLs that the
+index reads directly). `kind` values: `signature_technique` (from the
+device's own atlas entry), `sample_technique` (from
+`sample-techniques.md`), `sound_design_principle` (from
+`sound-design-deep.md`).
+
+## `atlas_search` — overlay budget split
+
+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). When both sources have hits, `limit` splits roughly
+50/50 (factory gets the rounding-up extra slot); a source with zero
+hits doesn't consume budget. M4L pack instruments occasionally carry a
+bogus `query:Synths#` URI in the atlas — `atlas_search` clears it and
+surfaces a `browse_hint` so callers don't hit `INVALID_PARAM` from
+`load_browser_item` (LIVE#3).