livepilot 1.10.6 → 1.10.8

package/CHANGELOG.md

@@ -1,5 +1,173 @@
 # 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`
+freeze that landed on `main` after v1.10.6 tagged, and unifies the three
+formerly-disagreeing sources of the domain count.
+
+### Fixed
+
+- **npm tarball parity with the GitHub release.** v1.10.6's npm publish
+  predated commit `b0463ea` (the real fat `.amxd` freeze with matching ping
+  bytes), so `npm install livepilot@1.10.6` shipped the stale Batch-22
+  `.amxd` and `simpler_set_warp` silently no-op'd. v1.10.7 republishes with
+  the fresh `.amxd` already present in the GitHub release assets.
+- **Domain count unified at 45.** Three formerly-disagreeing sources: prose
+  docs claimed "43 domains", `generate_tool_catalog.py` inferred "36" (via
+  a hand-maintained whitelist that silently dropped ~10 domains —
+  `atlas`, `composer`, `creative_constraints`, `device_forge`,
+  `hook_hunter`, `preview_studio`, `sample_engine`, `session_continuity`,
+  `song_brain`, `stuckness_detector`, `wonder_mode` — into an "Other"
+  bucket), runtime module layout has 45. All three now agree.
+- **Inline domain lists completed.** `CLAUDE.md:31` was missing
+  `experiment`, `musical_intelligence`, and `semantic_moves`;
+  `livepilot/skills/livepilot-release/SKILL.md:63` was missing
+  `semantic_moves`.
+
+### Infra
+
+- **`scripts/sync_metadata.py` extended** with `check_domain_count()` and
+  `check_domain_list()` that derive truth from `mcp_server` module paths.
+  `--fix` mode now auto-corrects stale tool/domain counts and appends
+  missing inline-list entries; extra entries are never auto-removed so a
+  pattern miss can't silently delete a legitimate domain.
+- **`scripts/generate_tool_catalog.py`** now uses the same module-layout
+  rule (`mcp_server.<X>` / `mcp_server.tools.<Y>`) as `sync_metadata.py`
+  so the two tools can't disagree on the domain set again.
+- **`.mcpbignore`** excludes `m4l_device/*.pre-*-backup` rollback artifacts
+  from the packaged `.mcpb`, keeping release bundles pristine across
+  future freeze cycles.
+- **`CLAUDE.md` gains `## Domain Count` section** documenting the drift
+  enforcer alongside the existing `## Tool Count` and `## Version Bump`
+  sections.
+
 ## 1.10.6 — Debuggability + Engine Modularization (April 17 2026)
 
 Defensive-programming release. Zero behavior change for users; substantial

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  320 tools. 43 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,8 +79,8 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   320 MCP Tools  │                                  │
-│                  │   43 domains     │                                  │
+│                  │   324 MCP Tools  │                                  │
+│                  │   45 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
 │           Remote Script ──┤── TCP 9878                                │
@@ -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 320 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
 
-320 tools across 43 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 320 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 320 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,42 +397,127 @@ 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");
 
   const home = os.homedir();
-  const packagesDir = process.platform === "darwin"
-    ? path.join(home, "Documents", "Max 8", "Packages")
-    : path.join(process.env.USERPROFILE || home, "Documents", "Max 8", "Packages");
 
+  // Max 9 is the current release (the Ableton Live 12.3+ default); Max 8 is
+  // 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");
+
+  const max9PackagesDir = path.join(docsBase, "Max 9", "Packages");
+  const max8PackagesDir = path.join(docsBase, "Max 8", "Packages");
+
+  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");
 
-  if (fs.existsSync(flucomaDir)) {
-    // Check version
-    const pkgInfo = path.join(flucomaDir, "package-info.json");
+  // Check BOTH locations for an existing install — a user may have Max 8
+  // FluCoMa from a prior install that still works
+  const altFlucomaDir = path.join(
+    packagesDir === max9PackagesDir ? max8PackagesDir : max9PackagesDir,
+    "FluidCorpusManipulation"
+  );
+
+  for (const candidateDir of [flucomaDir, altFlucomaDir]) {
+    if (!fs.existsSync(candidateDir)) continue;
+    const pkgInfo = path.join(candidateDir, "package-info.json");
     if (fs.existsSync(pkgInfo)) {
       try {
         const info = JSON.parse(fs.readFileSync(pkgInfo, "utf-8"));
         console.log("FluCoMa already installed: v%s", info.version || "unknown");
-        console.log("Location: %s", flucomaDir);
+        console.log("Location: %s", candidateDir);
         return;
       } catch {}
     }
-    console.log("FluCoMa already installed at %s", flucomaDir);
+    console.log("FluCoMa already installed at %s", candidateDir);
     return;
   }
 
+  // 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
@@ -456,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));
@@ -492,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);
@@ -581,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;
@@ -700,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;
   }