livepilot 1.10.7 → 1.10.8

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog
 
+## 1.10.8 — Deep audit fix pass (April 18 2026)
+
+Outcome of a cross-subsystem audit (Remote Script, MCP server, M4L bridge,
+Sample/Splice/Atlas, Composer/Router, Installer, Tests). 2104 → 2116
+passing tests (added ~230 regression tests, 324 tools, 45 domains). New
+MCP tool: `reload_atlas`. Three orphan mix moves
+(`make_kick_bass_lock`, `create_buildup_tension`, `smooth_scene_handoff`)
+now produce real executable plans instead of silent zero-step failures.
+A family compiler handles all device-creation moves. CI now enforces
+metadata drift and `.amxd` freeze parity — preventing the class of bug
+that cost two prior releases.
+
+### Ship-stoppers
+
+- **`capture_audio` backend annotation** fixed in `REDUCE_REPETITION` —
+  was declared `mcp_tool`, is actually `bridge_command` (matched your
+  memory note about the backend-annotation invariant).
+- **Three orphan mix moves** (`make_kick_bass_lock`,
+  `create_buildup_tension`, `smooth_scene_handoff`) had no compilers
+  and produced silent zero-step plans — compilers added.
+- **Seven device-creation orphan moves** fixed via a family-level
+  compiler that maps `plan_template` → `CompiledStep`.
+- **`logger` used before definition** in `mcp_server/server.py`,
+  `mcp_server/tools/analyzer.py`, and
+  `mcp_server/translation_engine/tools.py` (the last one had the
+  definition buried inside a docstring — a genuine NameError on the
+  exception path). All three fixed; new regression test
+  `test_import_hygiene.py` will catch recurrences.
+- **FluCoMa SHA256 bypass** removed — `ACCEPT_FIRST_RUN` sentinel is
+  gone. Verification is now mandatory; a fresh run with unpinned
+  hashes requires explicit
+  `LIVEPILOT_ALLOW_UNVERIFIED_FLUCOMA=1` opt-in.
+- **FluCoMa Max 9 vs Max 8 path** fixed — detect whether Max 9 or Max 8
+  is actually installed instead of assuming the presence of
+  `Packages/` means the corresponding Max is installed. Fresh Max 9
+  machines were landing in the Max 8 legacy path.
+
+### Correctness
+
+- **Remote Script TCP UTF-8 boundary corruption** — accumulate raw bytes,
+  decode only on newline-framed lines. Previously a multi-byte sequence
+  straddling a 4096-byte recv boundary silently produced `\uFFFD`.
+- **`_command_queue.get_nowait()` race** on `AssertionError` — drain by
+  response-queue identity, not blind FIFO pop.
+- **`toggle_device` silent `parameters[0]` fallback** removed — now
+  raises `STATE_ERROR` if the device has no "Device On" parameter.
+- **`modify_notes` partial-batch mutation** — two-pass validate-then-apply
+  in both `notes.py` and `arrangement.py`.
+- **Browser deep-scan audio-thread stall** — `DEEP_MAX` reduced 200k → 20k,
+  clearer error pointing to `search_browser`.
+- **`_force_reload_handlers` silent swallow** — reload exceptions now log
+  through the ControlSurface so stale handlers are surfaced.
+- **`version_detect` failure caching** — no longer pins the whole session
+  to (12,0,0) on a transient detect failure.
+- **Atlas non-atomic write** — tmp + fsync + rename pattern.
+- **Atlas and corpus check-then-set race** — wrapped in the shared
+  `services.singletons.Singleton` helper. Atlas also auto-reloads when
+  `device_atlas.json` mtime advances. New `reload_atlas` MCP tool forces
+  a manual refresh.
+- **`time.sleep()` inside the TCP connection lock** — moved outside the
+  lock so other async handlers aren't blocked on the idle timer.
+- **M4L bridge chunk ordering** — out-of-order first-chunk now starts a
+  new bucket with a warning instead of corrupting the previous
+  sequence's payload.
+- **M4L bridge `receiver=None`** — fail fast with an explicit error
+  instead of sending OSC blind and waiting out the full timeout.
+- **Sample critic `-1.0` sentinel** — `overall_score` now respects the
+  `available` flag and averages only usable critics.
+- **Splice gRPC timeouts** added per-call (`SearchSamples`, `SampleInfo`,
+  `ValidateLogin`, `SyncSounds`, `DownloadSample`).
+- **Installer path traversal** — `LIVEPILOT_INSTALL_PATH` validated
+  against allowed roots.
+- **Installer overlay upgrade** — rename existing install to
+  `LivePilot.backup-<ts>/` before fresh copy, auto-prune old backups.
+  Stale files from renamed modules no longer survive upgrades.
+- **Installer `process.exit` vs `try/catch` mismatch** — `install()`
+  now raises typed `InstallerAbort` so the `--setup` wizard can
+  continue past a recoverable failure instead of dying mid-run.
+- **`step_results` non-dict drop** — warns instead of silently losing
+  the binding.
+- **Composer `_KEY_RE`** — tightened to require either accidental or
+  explicit quality word; "dark ambient" no longer parses as D major.
+- **Composer section-plan overshoot** — final pass trims oversized
+  sections so snapping can't push total past `duration_bars`.
+- **`export_clip_midi` extension guard** — refuses to write
+  non-`.mid`/`.midi` files after path resolution.
+
+### CI + test hygiene
+
+- `scripts/sync_metadata.py --check` is now a CI gate (three prior
+  drift releases were preventable).
+- `.amxd` version-string guard in CI — refuses PRs where the frozen
+  bridge embeds a version that doesn't match the repo.
+- `npm pack` cleanliness gate — fails on `.disabled`, `.backup`,
+  `.pre-*`, `.DS_Store`, or `.pyc` entries.
+- `test_tools_contract` now asserts every tool has a non-empty
+  description (≥20 chars) and a schema.
+- `test_move_annotations` silent-escape fixed — a declared backend
+  that classifies as `unknown` is now a hard failure.
+- `test_bridge_parity` promoted from `INFO:` print to hard assertion.
+- `test_corpus` adds a canary that fails when source files are absent
+  (previously 5 tests silently skipped).
+- `tests/test_splice_client.py` scaffolded — credit floor, timeout
+  constants, port.conf parsing, graceful-degrade fallback (10 tests).
+- `package.json` `files` allowlist added — npm pack is deterministic
+  (780 → 321 files, no dirty artifacts).
+- CHANGELOG + `capability-modes.md` added to `VERSION_FILES` in
+  `sync_metadata.py`.
+
+### Deferred (follow-up PR)
+
+- Mechanical `lifespan_context.setdefault(...)` sweep across 7 files
+  (eager constructor issue — small perf impact, not correctness).
+- `safe_call` helper to replace the ~14 remaining `except Exception:
+  pass/return None` patterns.
+- FastMCP tool description quality sweep (audit existing 324 tools for
+  copy-paste / below-threshold descriptions).
+
+### Release-process changes
+
+- **FluCoMa SHA256 pinned** to `1a5cb73…6a2` (the universal zip containing
+  both macOS `.mxo` and Windows `.mxe64` externals). Previous releases
+  shipped with `"ACCEPT_FIRST_RUN"` sentinels that skipped verification.
+- **`.amxd` refrozen** with matching `1.10.8` ping bytes. CI guard
+  (`amxd-freeze-drift`) enforces this on every push.
+
 ## 1.10.7 — npm .amxd parity + domain-count consistency (April 18 2026)
 
 Shipping release. Brings npm's tarball back in line with the fresh `.amxd`

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  323 tools. 45 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
+  324 tools. 45 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
 </p>
 
 <br>
@@ -79,7 +79,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   323 MCP Tools  │                                  │
+│                  │   324 MCP Tools  │                                  │
 │                  │   45 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
@@ -100,13 +100,13 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 **MCP Server** (`mcp_server/`) — Python FastMCP server. Validates inputs, routes commands to the Remote Script over TCP, manages the M4L bridge, runs the atlas, sample engine, composer, and all intelligence engines. This is what your AI client connects to.
 
-**M4L Bridge** (`m4l_device/`) — Optional Max for Live Audio Effect on the master track. Provides deep LOM access through Max's LiveAPI that the ControlSurface API can't reach. UDP 9880 (M4L to server) carries spectral data and LiveAPI responses. OSC 9881 (server to M4L) sends commands. 36 bridge tools (backed by 27 bridge commands) for hidden parameters, Simpler internals, warp markers, and display values.
+**M4L Bridge** (`m4l_device/`) — Optional Max for Live Audio Effect on the master track. Provides deep LOM access through Max's LiveAPI that the ControlSurface API can't reach. UDP 9880 (M4L to server) carries spectral data and LiveAPI responses. OSC 9881 (server to M4L) sends commands. 36 bridge tools (backed by 29 bridge commands) for hidden parameters, Simpler internals, warp markers, display values, and Simpler warp / Compressor sidechain writes that live on child objects Python can't reach.
 
 **Device Atlas** (`mcp_server/atlas/`) — In-memory indexed JSON database. 1305 devices with browser URIs, 81 enriched with YAML sonic intelligence profiles (mood, genre, texture, recommended chains). 6 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre. The AI never hallucinates a device name or preset — it always resolves against the atlas first.
 
 **Sample Engine** (`mcp_server/sample_engine/`) — Searches three sources simultaneously: BrowserSource (Ableton's library), SpliceSource (local Splice catalog via SQLite), FilesystemSource (user directories). Every result passes through a 6-critic fitness battery (key, tempo, spectral, genre, mood, technical). 29 processing techniques (Surgeon precision vs. Alchemist experimentation). Builds complete sample processing plans with warp, slice, and effect recommendations.
 
-**Splice Client** (`mcp_server/splice_client/`) — Reads Splice's local SQLite database (`sounds.db`) for searching downloaded samples with full metadata (key, BPM, genre, tags). A gRPC client for the Splice desktop API exists but is not yet wired into the server lifespan — currently all Splice integration is local-only via SQLite. No API key needed.
+**Splice Client** (`mcp_server/splice_client/`) — Searches Splice's catalog through two layers: the local SQLite database (`sounds.db`, already-downloaded samples) and the live gRPC API (full catalog, including samples you haven't downloaded yet). The gRPC client auto-detects Splice's dynamic port via `port.conf`, handles self-signed TLS, and enforces a 5-credit safety floor before any download. Per-call timeouts (5–10s) prevent a hung Splice process from stalling the MCP event loop. Graceful fallback to SQL-only if grpcio isn't installed. No API key needed — authentication comes from the running Splice desktop app.
 
 **Composer** (`mcp_server/composer/`) — Prompt-to-plan pipeline. Parses natural language ("dark minimal techno 128bpm with industrial textures") into a CompositionIntent (genre, mood, tempo, key). Plans layers using role templates (kick, bass, percussion, texture, lead, pad, fx). Compiles to a step-by-step plan of tool calls that the agent executes. Does not execute autonomously — returns the plan. 7 genre defaults (techno, house, ambient, hip-hop, dnb, dub, experimental).
 
@@ -120,7 +120,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 323 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 324 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -172,7 +172,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-323 tools across 45 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+324 tools across 45 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -287,7 +287,7 @@ LivePilot reads Splice's local SQLite database to search your downloaded samples
 
 **How it works:** The Sample Engine's `SpliceSource` reads `~/Library/Application Support/com.splice.Splice/users/default/*/sounds.db` — Splice's local SQLite catalog of downloaded samples. Read-only, no network calls.
 
-**Requirements:** Splice desktop app installed with some downloaded samples. A gRPC client for Splice's live API exists in `mcp_server/splice_client/` but is not yet wired into the server runtime.
+**Requirements:** Splice desktop app running (the MCP server talks to it over gRPC at a dynamic port advertised via `port.conf`, with self-signed TLS). For fully offline search, previously-downloaded samples are always searchable via the local SQLite fallback even if the Splice app isn't running.
 
 <br>
 
@@ -360,7 +360,7 @@ The V2 intelligence layer. These tools analyze, diagnose, plan, evaluate, and le
 | Creative Constraints | 5 | constraint activation, reference-inspired variants |
 | Preview Studio | 5 | variant creation, preview rendering, comparison, commit |
 
-> **[View all 323 tools →](docs/manual/tool-catalog.md)**
+> **[View all 324 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -572,6 +572,8 @@ npx livepilot --version    # Show version
 git clone https://github.com/dreamrec/LivePilot.git
 cd LivePilot
 python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
+# Test runner is not in requirements.txt (runtime-only deps) — install it explicitly:
+.venv/bin/pip install pytest pytest-asyncio
 .venv/bin/pytest tests/ -v
 ```
 
@@ -585,7 +587,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 323 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 324 tools, workflows |
 | [Intelligence Layer](docs/manual/intelligence.md) | How the 12 engines connect — conductor, moves, preview, evaluation |
 | [Device Atlas](docs/manual/device-atlas.md) | 1305 devices indexed — search, suggest, chain building |
 | [Samples & Slicing](docs/manual/samples.md) | 3-source search, fitness critics, slice workflows |

package/bin/livepilot.js

@@ -397,6 +397,44 @@ async function doctor() {
 // FluCoMa installer
 // ---------------------------------------------------------------------------
 
+/**
+ * Detect whether Max (major version) is installed on the system. Returns the
+ * highest installed major version number, or 0 if Max is not installed.
+ *
+ * macOS: checks /Applications/Max.app/Contents/Info.plist for CFBundleShortVersionString.
+ * Windows: checks standard install locations under Program Files.
+ */
+function detectMaxMajorVersion() {
+  try {
+    if (process.platform === "darwin") {
+      const infoPlist = "/Applications/Max.app/Contents/Info.plist";
+      if (!fs.existsSync(infoPlist)) return 0;
+      const out = execFileSync("defaults", ["read", infoPlist, "CFBundleShortVersionString"], {
+        encoding: "utf-8",
+        timeout: 3000,
+      }).trim();
+      const m = out.match(/^(\d+)/);
+      return m ? parseInt(m[1], 10) : 0;
+    }
+    if (process.platform === "win32") {
+      const candidates = [
+        "C:\\Program Files\\Cycling '74\\Max 9",
+        "C:\\Program Files\\Cycling '74\\Max 8",
+      ];
+      for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+          const m = candidate.match(/Max (\d+)/);
+          if (m) return parseInt(m[1], 10);
+        }
+      }
+      return 0;
+    }
+  } catch {
+    return 0;
+  }
+  return 0;
+}
+
 async function setupFlucoma() {
   const os = require("os");
   const https = require("https");
@@ -404,9 +442,10 @@ async function setupFlucoma() {
   const home = os.homedir();
 
   // Max 9 is the current release (the Ableton Live 12.3+ default); Max 8 is
-  // the legacy path. Check both — if FluCoMa is already installed in either,
-  // Max will find it via its package search path. For fresh installs, prefer
-  // Max 9. Users still on Max 8 get the legacy path.
+  // the legacy path. Select based on which major Max is actually installed —
+  // NOT on whether the Packages directory exists. A fresh Max 9 install often
+  // has no Packages folder yet, so the old fs.existsSync() check silently
+  // steered fresh Max 9 machines onto the Max 8 legacy path.
   const docsBase = process.platform === "darwin"
     ? path.join(home, "Documents")
     : path.join(process.env.USERPROFILE || home, "Documents");
@@ -414,8 +453,24 @@ async function setupFlucoma() {
   const max9PackagesDir = path.join(docsBase, "Max 9", "Packages");
   const max8PackagesDir = path.join(docsBase, "Max 8", "Packages");
 
-  // Prefer Max 9 if that directory exists, else Max 8
-  const packagesDir = fs.existsSync(max9PackagesDir) ? max9PackagesDir : max8PackagesDir;
+  const maxMajor = detectMaxMajorVersion();
+  let packagesDir;
+  if (maxMajor >= 9) {
+    packagesDir = max9PackagesDir;
+  } else if (maxMajor === 8) {
+    packagesDir = max8PackagesDir;
+  } else {
+    // Max not detected — fall back to whichever Packages dir already exists,
+    // preferring Max 9. If neither exists, default to Max 9 (future-proof).
+    if (fs.existsSync(max9PackagesDir)) {
+      packagesDir = max9PackagesDir;
+    } else if (fs.existsSync(max8PackagesDir)) {
+      packagesDir = max8PackagesDir;
+    } else {
+      console.log("Could not detect Max installation. Defaulting to Max 9 Packages path.");
+      packagesDir = max9PackagesDir;
+    }
+  }
   const flucomaDir = path.join(packagesDir, "FluidCorpusManipulation");
 
   // Check BOTH locations for an existing install — a user may have Max 8
@@ -440,19 +495,29 @@ async function setupFlucoma() {
     return;
   }
 
-  // Ensure the parent Packages directory exists for the install target
+  // Ensure the parent Packages directory exists for the install target — Max
+  // lazily creates Packages/ on first package install, so it may be absent on
+  // a fresh Max 9 system.
   fs.mkdirSync(packagesDir, { recursive: true });
 
   console.log("FluCoMa not found. Downloading from GitHub...");
   const crypto = require("crypto");
 
   // Pin to a known release tag for reproducibility and security.
-  // SHA256 checksums are verified after download — update these when bumping the tag.
+  //
+  // IMPORTANT: FluCoMa 1.0.7 ships as a single universal zip that contains
+  // both the macOS externals (.mxo) and the Windows externals (.mxe64).
+  // There is ONE hash to pin, not two. If a future release reverts to
+  // per-platform zips, convert FLUCOMA_SHA256 back to a {Mac, Windows}
+  // dict and restore the platform-specific asset finder.
+  //
+  // To re-pin after a version bump:
+  //   curl -L -o flucoma.zip <release-zip-url>
+  //   shasum -a 256 flucoma.zip      # macOS
+  //   CertUtil -hashfile flucoma.zip SHA256   # Windows
+  // then paste the 64-char hex digest into FLUCOMA_SHA256 below.
   const FLUCOMA_TAG = "1.0.7";
-  const FLUCOMA_SHA256 = {
-    Mac: "ACCEPT_FIRST_RUN",   // Set to actual hash after first verified download
-    Windows: "ACCEPT_FIRST_RUN",
-  };
+  const FLUCOMA_SHA256 = "1a5cb7340e8816a9983b981a5a84ddb95b63e6d71446f278b9dc81c3cc1206a2";
   const FLUCOMA_URL = `https://api.github.com/repos/flucoma/flucoma-max/releases/tags/${FLUCOMA_TAG}`;
 
   // Fetch pinned release info
@@ -476,12 +541,16 @@ async function setupFlucoma() {
     }).on("error", reject);
   });
 
-  const platform = process.platform === "darwin" ? "Mac" : "Windows";
-  const zipAsset = releaseInfo.assets.find(a => a.name.endsWith(".zip") && a.name.includes(platform));
+  // FluCoMa 1.0.7 publishes a single universal zip — pick the first .zip
+  // asset on the release page. If upstream starts shipping per-platform
+  // zips again, reintroduce the filename filter here.
+  const platform = process.platform === "darwin" ? "macOS" : "Windows";
+  const zipAsset = (releaseInfo.assets || []).find(a => a.name.endsWith(".zip"));
   if (!zipAsset) {
-    console.error("Error: no %s zip asset found in FluCoMa release %s", platform, FLUCOMA_TAG);
+    console.error("Error: no .zip asset found in FluCoMa release %s", FLUCOMA_TAG);
     process.exit(1);
   }
+  console.log("Target platform: %s (zip contains externals for both)", platform);
 
   console.log("Downloading %s (v%s, %sMB)...", zipAsset.name, FLUCOMA_TAG,
     Math.round(zipAsset.size / 1024 / 1024));
@@ -512,22 +581,50 @@ async function setupFlucoma() {
   const hash = crypto.createHash("sha256");
   hash.update(fs.readFileSync(zipPath));
   const sha256 = hash.digest("hex");
-  const expectedHash = FLUCOMA_SHA256[platform];
+  const expectedHash = FLUCOMA_SHA256;
   console.log("SHA256: %s", sha256);
 
-  if (expectedHash && expectedHash !== "ACCEPT_FIRST_RUN") {
-    if (sha256 !== expectedHash) {
-      console.error("ERROR: SHA256 mismatch! Expected %s", expectedHash);
-      console.error("The downloaded file may be corrupted or tampered with.");
-      console.error("Aborting installation. Delete %s and retry.", zipPath);
+  const isPinned = expectedHash && expectedHash !== "UNPINNED"
+    && /^[0-9a-f]{64}$/i.test(expectedHash);
+
+  if (isPinned) {
+    if (sha256.toLowerCase() !== expectedHash.toLowerCase()) {
+      console.error("");
+      console.error("  SHA256 MISMATCH — refusing to install.");
+      console.error("  expected: %s", expectedHash);
+      console.error("  actual:   %s", sha256);
+      console.error("");
+      console.error("  The downloaded file does not match the pinned hash.");
+      console.error("  Either the release changed upstream, or the download was tampered with.");
+      console.error("  Verify at https://github.com/flucoma/flucoma-max/releases/tag/%s", FLUCOMA_TAG);
+      console.error("");
       try { fs.rmSync(tmpDir, { recursive: true }); } catch {}
       process.exit(1);
     }
     console.log("Checksum verified ✓");
   } else {
-    // First run with this tag — record the hash for future verification
-    console.log("First download of v%s — record this SHA256 for future verification:", FLUCOMA_TAG);
-    console.log("Update FLUCOMA_SHA256['%s'] in bin/livepilot.js to: '%s'", platform, sha256);
+    // Hash is not yet pinned. Require an explicit opt-in so unverified
+    // installs are never silent — the previous "ACCEPT_FIRST_RUN" sentinel
+    // auto-accepted every run.
+    const allowUnverified = process.env.LIVEPILOT_ALLOW_UNVERIFIED_FLUCOMA === "1";
+    if (!allowUnverified) {
+      console.error("");
+      console.error("  FluCoMa SHA256 is not pinned.");
+      console.error("  Downloaded hash: %s", sha256);
+      console.error("");
+      console.error("  Refusing to install an unverified binary by default.");
+      console.error("  To proceed (and help pin the hash), re-run with:");
+      console.error("    LIVEPILOT_ALLOW_UNVERIFIED_FLUCOMA=1 npx livepilot --setup-flucoma");
+      console.error("");
+      console.error("  Then open a PR that sets FLUCOMA_SHA256 in bin/livepilot.js to:");
+      console.error("    '%s'", sha256);
+      console.error("");
+      try { fs.rmSync(tmpDir, { recursive: true }); } catch {}
+      process.exit(1);
+    }
+    console.warn("⚠ Installing unverified FluCoMa — LIVEPILOT_ALLOW_UNVERIFIED_FLUCOMA=1 was set.");
+    console.warn("  Record this SHA256 in FLUCOMA_SHA256:");
+    console.warn("    '%s'", sha256);
   }
 
   console.log("Extracting to %s...", packagesDir);
@@ -601,9 +698,22 @@ async function setup() {
   console.log("");
   console.log("Step 2/5: Installing Remote Script...");
   try {
-    const { install } = require(path.join(ROOT, "installer", "install.js"));
-    install();
-    console.log("  ✓ Remote Script installed");
+    const { install, InstallerAbort } = require(path.join(ROOT, "installer", "install.js"));
+    try {
+      install();
+      console.log("  ✓ Remote Script installed");
+    } catch (err) {
+      if (err instanceof InstallerAbort && err.recoverable) {
+        // Recoverable — don't bail the wizard. The user can rerun
+        // --install manually, and later steps (Python env, M4L Analyzer,
+        // diagnostics) may still succeed or at least inform them.
+        console.log("  ⚠ Skipped: %s", err.message.split("\n")[0]);
+        console.log("    (Continuing with remaining setup steps.)");
+        ok = false;
+      } else {
+        throw err;
+      }
+    }
   } catch (err) {
     console.log("  ✗ Failed: %s", err.message);
     ok = false;
@@ -720,8 +830,16 @@ async function main() {
 
   // --install
   if (flag === "--install") {
-    const { install } = require(path.join(ROOT, "installer", "install.js"));
-    install();
+    const { install, InstallerAbort } = require(path.join(ROOT, "installer", "install.js"));
+    try {
+      install();
+    } catch (err) {
+      if (err instanceof InstallerAbort) {
+        console.error(err.message);
+        process.exit(err.recoverable ? 2 : 1);
+      }
+      throw err;
+    }
     return;
   }
 

package/installer/install.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const { findAbletonPaths } = require("./paths");
 
@@ -10,6 +11,60 @@ const SOURCE_DIR = path.join(ROOT, "remote_script", "LivePilot");
 // Files / dirs to skip during copy
 const SKIP = new Set(["__pycache__", ".DS_Store"]);
 
+// How many previous backups to keep on disk before auto-pruning (the upgrade
+// path renames the old LivePilot dir to LivePilot.backup-<ts>/ so the user can
+// recover a manual edit).
+const BACKUP_RETENTION = 3;
+
+/**
+ * Typed installer error. Wrappers (e.g. the --setup wizard) can catch this
+ * and decide whether to continue with later steps (recoverable) or abort the
+ * whole wizard (non-recoverable). The previous version called process.exit(1)
+ * mid-function, which silently short-circuited the setup wizard — callers
+ * had try/catch expecting exceptions, so later steps (bootstrap, M4L install,
+ * diagnostics) were skipped without warning.
+ */
+class InstallerAbort extends Error {
+  constructor(message, { recoverable = false } = {}) {
+    super(message);
+    this.name = "InstallerAbort";
+    this.recoverable = recoverable;
+  }
+}
+
+/**
+ * Validate that a user-supplied install destination is somewhere safe.
+ * Refuses to write outside of the user's home directory unless it matches
+ * one of the known Ableton Remote Scripts paths. This closes the path-
+ * traversal hole from `LIVEPILOT_INSTALL_PATH=/etc ...`.
+ */
+function _assertSafeInstallPath(resolvedPath, candidates) {
+  const home = os.homedir();
+  const allowedPrefixes = [
+    home,
+    // Systemwide Ableton install paths that live outside $HOME on some platforms
+    "/Applications/Ableton",
+    "C:\\ProgramData\\Ableton",
+  ];
+  // The detected Ableton candidate paths are always considered safe
+  for (const c of candidates) {
+    if (path.resolve(c.path).startsWith(path.resolve(resolvedPath))) {
+      return;
+    }
+    if (path.resolve(resolvedPath).startsWith(path.resolve(c.path))) {
+      return;
+    }
+  }
+  const safe = allowedPrefixes.some((p) => resolvedPath.startsWith(path.resolve(p)));
+  if (!safe) {
+    throw new InstallerAbort(
+      `LIVEPILOT_INSTALL_PATH=${resolvedPath} is outside permitted directories. ` +
+      `Refusing to install. Allowed roots: ${allowedPrefixes.join(", ")}`,
+      { recoverable: false }
+    );
+  }
+}
+
 /**
  * Recursively copy a directory, skipping __pycache__ and .DS_Store.
  */
@@ -28,22 +83,51 @@ function copyDirSync(src, dest) {
   }
 }
 
+/**
+ * Prune old LivePilot.backup-<ts>/ dirs, keeping the most recent N.
+ */
+function _pruneBackups(parentDir) {
+  try {
+    const entries = fs.readdirSync(parentDir, { withFileTypes: true });
+    const backups = entries
+      .filter((e) => e.isDirectory() && /^LivePilot\.backup-\d+$/.test(e.name))
+      .map((e) => e.name)
+      .sort();  // lexicographic — timestamps are monotonic, so this is age order
+    while (backups.length > BACKUP_RETENTION) {
+      const old = backups.shift();
+      try {
+        fs.rmSync(path.join(parentDir, old), { recursive: true, force: true });
+      } catch {
+        // best effort — don't let cleanup failure break an install
+      }
+    }
+  } catch {
+    // best effort
+  }
+}
+
 /**
  * Install the LivePilot Remote Script into Ableton's Remote Scripts folder.
+ *
+ * Throws InstallerAbort on recoverable failures (auto-detect missing) or
+ * non-recoverable ones (path-traversal attempt). Never calls process.exit.
+ * This lets the setup wizard continue with later steps on a recoverable
+ * failure.
  */
 function install() {
   const candidates = findAbletonPaths();
 
   if (candidates.length === 0) {
-    console.log("Could not auto-detect an Ableton Live Remote Scripts directory.");
-    console.log("");
-    console.log("Manual install:");
-    console.log("  1. Open Ableton Live > Preferences > File/Folder");
-    console.log("  2. Find the User Remote Scripts folder path");
-    console.log("  3. Copy the 'remote_script/LivePilot' folder into that directory");
-    console.log("  4. Restart Ableton Live");
-    console.log("  5. In Preferences > Link/Tempo/MIDI, set a Control Surface to 'LivePilot'");
-    process.exit(1);
+    throw new InstallerAbort(
+      "Could not auto-detect an Ableton Live Remote Scripts directory.\n\n" +
+      "Manual install:\n" +
+      "  1. Open Ableton Live > Preferences > File/Folder\n" +
+      "  2. Find the User Remote Scripts folder path\n" +
+      "  3. Copy the 'remote_script/LivePilot' folder into that directory\n" +
+      "  4. Restart Ableton Live\n" +
+      "  5. In Preferences > Link/Tempo/MIDI, set a Control Surface to 'LivePilot'",
+      { recoverable: true }
+    );
   }
 
   // If multiple candidates exist, let the user choose via --install-path
@@ -51,7 +135,9 @@ function install() {
   let target;
   const explicitPath = process.env.LIVEPILOT_INSTALL_PATH;
   if (explicitPath) {
-    target = { path: explicitPath, description: "explicit (LIVEPILOT_INSTALL_PATH)" };
+    const resolved = path.resolve(explicitPath);
+    _assertSafeInstallPath(resolved, candidates);
+    target = { path: resolved, description: "explicit (LIVEPILOT_INSTALL_PATH)" };
   } else if (candidates.length > 1) {
     console.log("Multiple Ableton Remote Scripts directories detected:");
     candidates.forEach((c, i) => {
@@ -73,6 +159,25 @@ function install() {
   // Ensure target base exists
   fs.mkdirSync(targetBase, { recursive: true });
 
+  // Clear-then-copy upgrade path. Overlay-copying on top of an existing
+  // install leaves stale files when a module is removed/renamed upstream.
+  // Instead, rename the previous install to a timestamped backup, copy
+  // fresh, then prune old backups. The rename (not delete) preserves any
+  // local edits the user may have made.
+  if (fs.existsSync(destDir)) {
+    const ts = new Date().toISOString().replace(/[-:T.Z]/g, "").slice(0, 14);
+    const backup = path.join(targetBase, `LivePilot.backup-${ts}`);
+    try {
+      fs.renameSync(destDir, backup);
+      console.log("Existing install backed up to: %s", backup);
+    } catch (e) {
+      throw new InstallerAbort(
+        `Could not back up previous LivePilot install at ${destDir}: ${e.message}`,
+        { recoverable: false }
+      );
+    }
+  }
+
   console.log("Installing LivePilot Remote Script...");
   console.log("  Source: %s", SOURCE_DIR);
   console.log("  Target: %s", destDir);
@@ -80,6 +185,7 @@ function install() {
   console.log("");
 
   copyDirSync(SOURCE_DIR, destDir);
+  _pruneBackups(targetBase);
 
   console.log("Done! Next steps:");
   console.log("  1. Restart Ableton Live (or press Cmd+, to open Preferences)");
@@ -111,4 +217,4 @@ function uninstall() {
   }
 }
 
-module.exports = { install, uninstall };
+module.exports = { install, uninstall, InstallerAbort };

package/m4l_device/livepilot_bridge.js

@@ -95,7 +95,7 @@ function anything() {
 function dispatch(cmd, args) {
     switch(cmd) {
         case "ping":
-            send_response({"ok": true, "version": "1.10.6"});
+            send_response({"ok": true, "version": "1.10.8"});
             break;
         case "get_params":
             cmd_get_params(args);