livepilot 1.10.7 → 1.10.9

package/CHANGELOG.md

@@ -1,5 +1,259 @@
 # Changelog
 
+## 1.10.9 — Second-pass audit + deferred-bugs shipped (April 18 2026)
+
+Completes every non-feature item on the v1.10.8 audit backlog. 2116 → 2132
+passing tests (+16 regression guards). 324 → 325 tools (`check_clip_key_consistency`
+lands from BUG-D1). Every deferred BUG-C and BUG-D entry either ships or is
+scoped to a follow-up feature; BUG-C4 is filed upstream as
+[PrefectHQ/fastmcp#3967](https://github.com/PrefectHQ/fastmcp/issues/3967).
+
+### Ship-stoppers fixed
+
+- **`send_capture` phantom 35s hang when receiver is None** —
+  [`mcp_server/m4l_bridge.py:441`](mcp_server/m4l_bridge.py). `send_command`
+  had a receiver-None guard; `send_capture` didn't. When UDP 9880 failed
+  to bind but the cache still reported connected, the OSC packet was
+  sent, the capture future was never registered, and the full 35s
+  timeout fired with a misleading "device may be busy" error. Added the
+  matching 5-line guard so the real cause surfaces immediately.
+- **`utils.py` stale after Control Surface toggle** —
+  [`remote_script/LivePilot/__init__.py:43`](remote_script/LivePilot/__init__.py).
+  Every handler does `from .utils import get_track, get_device`.
+  `importlib.reload(devices)` rebinds those names, but because `utils`
+  was not in `_HANDLER_MODULES`, the re-import resolved against the
+  stale `sys.modules["LivePilot.utils"]`. Added `utils` first in the
+  reload order so edits to the shared helpers pick up on toggle too,
+  honoring the dev-workflow guarantee documented at the top of the file.
+
+### New tools
+
+- **`check_clip_key_consistency`** (BUG-D1) — parses Splice-style
+  filename key tokens (`_D#min`, `_Ebmaj`, `_Cm`, …), cross-checks
+  against `get_detected_key`, returns the exact `set_clip_pitch(coarse=±N)`
+  call that would realign on mismatch. Handles `#`/`b` accidentals,
+  `min`/`m`/`maj` suffixes, absent tokens gracefully.
+- **`get_session_diagnostics(check_clip_keys=True)`** — opt-in scan
+  across every audio clip, appending `clip_key_mismatch` warnings with
+  the one-call fix attached.
+
+### Features shipped
+
+- **Session continuity persistence wired at startup** (BUG from external
+  audit). `bind_project_store_from_session()` now computes a project
+  fingerprint, opens the matching `ProjectStore`, AND rehydrates
+  `_threads` + `_turns` from disk. Wired into `server.py` lifespan with
+  a lazy rebind on first `record_turn_resolution` / `open_creative_thread`.
+  Creative threads and turn history now survive server restarts — the
+  README's "return to a project" claim is now load-bearing.
+- **Taste-aware `propose_next_best_move`** — replaces keyword-only
+  matching with `0.55 × keyword + 0.30 × taste_alignment + 0.15 ×
+  (1 − avoidance) ± 0.10 × family_bonus`. Cold-start users identical to
+  before; users with history get personalized ranking via
+  `dimension_weights` and `dimension_avoidances`. New return fields:
+  `score_breakdown`, `taste_active`, `taste_evidence_count`.
+- **Evaluation `taste_fit`** — previously hardcoded to `0.0`. Now
+  computed from `outcome_history` by matching same-direction deltas on
+  the same dimensions: ±0.2 per kept/undone match, neutral 0.5 baseline.
+- **`AutomationGraph.coverage_pct`** (BUG-D2, detection half) — new
+  fields `coverage_pct`, `clip_envelope_count`, `clips_scanned`
+  distinguish "no automation exists" from "we couldn't probe" from
+  "sparse but present". Surfaced in `get_project_brain_summary` as
+  `automation_coverage_pct`.
+
+### Refactor (BUG-C1)
+
+- **`mcp_server/tools/analyzer.py`** 1069 → 913 LOC. All 32
+  `@mcp.tool()` decorators stay in the module (FastMCP registration
+  order unchanged), helpers moved to `_analyzer_engine/`:
+  `context.py` (SpectralCache/bridge accessors, analyzer health check),
+  `sample.py` (Simpler post-load hygiene, filename heuristics),
+  `flucoma.py` (FluCoMa hint text, pitch-name table). Same
+  package-facade pattern as `_composition_engine` and `_agent_os_engine`.
+- **`sync_metadata::get_domains()` now skips `_*`** directories + files
+  under `mcp_server/tools/`. Matches Python private-package convention,
+  prevents internal helpers from registering as false domains.
+
+### Resilience (BUG-C3)
+
+- **`_get_all_tools()` probe chain extended** in `mcp_server/server.py`
+  to 4 paths: existing `_tool_manager._tools` and
+  `_local_provider._components`, plus speculative 3.3+ rename
+  `_local_provider._tools` and the future public `mcp.list_tools()`.
+  Each wrapped in try/except. All-empty fall-through now prints
+  `fastmcp.__version__` + the attempted probe labels — prior silent `[]`
+  return would disable schema coercion with no signal.
+- **New `_assert_tool_registry_accessible()`** self-test runs at module
+  import. Empty registry or a count mismatch against
+  `tests/test_tools_contract.py` fails loudly via stderr.
+
+### Upstream (BUG-C4)
+
+- **FastMCP feature request filed** —
+  [PrefectHQ/fastmcp#3967](https://github.com/PrefectHQ/fastmcp/issues/3967)
+  "Feature request: public tool-enumeration API". Migration is a
+  no-op once upstream lands a `mcp.list_tools()` or `mcp.tools`
+  surface — the probe chain already anticipates both.
+
+### Metadata + docs
+
+- **`sync_metadata.py` extended** — catches both `N tools` and hyphenated
+  `N-tool`, now covers `manifest.json` + `docs/manual/intelligence.md` +
+  `.claude-plugin/marketplace.json`. New prose-claim checks for
+  bridge-command count, enriched-device YAML count, and `GENRE_DEFAULTS`
+  key count — every narrative number now traces to a code derivation.
+- **README / CLAUDE.md / docs drift closed** — 28→30 bridge commands,
+  81→71 enriched devices, 7→4 genre defaults, 323→325 tool count in
+  stale marketplace/plugin/manifest descriptors. Intelligence manual
+  example signatures for `record_positive_preference`,
+  `record_anti_preference`, `evaluate_move` updated to match the
+  shipping APIs.
+- **Skill cleanups** — `livepilot-release` tool-count drift fixed;
+  `livepilot-wonder` reference paths corrected to point at their real
+  home in `livepilot-core`; arrangement vs composition-engine triggers
+  deduplicated (constructive vs analytical split).
+- **New test** `tests/test_claim_consistency.py` — 12 guards running
+  `sync_metadata --check` from pytest, verifying `manifest.json` and
+  `intelligence.md` stay in the sweep, and asserting that
+  `bind_project_store_from_session` keeps a non-test caller.
+
+### Quality-of-life
+
+- **`scripts/test.sh`** — blessed test entrypoint always uses `.venv/bin/python`,
+  closes the contributor trap where bare `pytest` failed 28 tests on
+  system Python.
+- **`.gitignore`** additions: `m4l_device/*.pre-presentation-backup`,
+  `m4l_device/*.pre-*-backup`, `.mcp.json.disabled`.
+- **Stale `livepilot-1.10.5.tgz`** removed from the repo root.
+
+---
+
+## 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.
+  325 tools. 45 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
 </p>
 
 <br>
@@ -38,7 +38,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 | Layer | What it provides |
 |-------|-----------------|
 | **Deterministic Tools** | Direct control: transport, tracks, clips, notes, devices, scenes, mixing, arrangement, browser, automation |
-| **Device Atlas** | Knowledge of every device in Ableton's library — 1305 devices indexed by name, URI, category, tag, and genre. 81 enriched with sonic intelligence. 683 drum kits mapped |
+| **Device Atlas** | Knowledge of every device in Ableton's library — 1305 devices indexed by name, URI, category, tag, and genre. 71 enriched with sonic intelligence. 683 drum kits mapped |
 | **Sample Engine** | Three-source sample intelligence — searches Ableton's browser, your filesystem, and Splice's catalog simultaneously. 6 fitness critics score every result. 29 processing techniques |
 | **Spectral Perception** | Real-time ears via M4L — 8-band FFT, RMS/peak metering, Krumhansl-Schmuckler key detection, pitch tracking. Closes the feedback loop so the AI hears its own changes |
 | **Technique Memory** | Persistent library of production decisions. Save a beat pattern, device chain, or mix template. Recall by mood, genre, or texture across sessions |
@@ -58,7 +58,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │                                                                      │
 │  Device Atlas            8-band FFT              recall by mood,     │
 │  1305 devices            RMS / peak              genre, texture      │
-│  81 enriched             pitch tracking          29 techniques       │
+│  71 enriched             pitch tracking          29 techniques       │
 │  683 drum kits           key detection           replay into session │
 │                                                                      │
 │  Sample Engine           Corpus Intelligence     Taste Graph          │
@@ -79,7 +79,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   323 MCP Tools  │                                  │
+│                  │   325 MCP Tools  │                                  │
 │                  │   45 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
@@ -100,15 +100,15 @@ 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. The 32 spectral/analyzer tools strictly require the bridge; device and sample tools that call the bridge also have graceful fallbacks, so core functionality works without it. Backed by 30 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.
+**Device Atlas** (`mcp_server/atlas/`) — In-memory indexed JSON database. 1305 devices with browser URIs, 71 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).
+**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. 4 genre defaults (house, techno, trap, ambient) — genres outside this set fall back to a neutral layer plan.
 
 **Corpus** (`mcp_server/corpus/`) — Parsed device-knowledge markdown converted to queryable Python structures: EmotionalRecipe, GenreChain, PhysicalModelRecipe, AutomationGesture. Feeds Wonder Mode, Sound Design critics, and the Composer with deep creative knowledge at runtime — not just LLM prompts, actual structured data.
 
@@ -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 325 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -156,7 +156,7 @@ When a session is stuck — repeated undos, overpolished loops, no structural pr
 
 ### Hook Hunter
 
-Identifies the most salient musical idea — ranks by rhythmic distinctiveness, melodic contour, repetition. Tracks whether hooks are developed, neglected, or undermined. Flags when a transition fails to deliver expected payoff.
+Identifies the most salient musical idea — ranks candidates by recurrence across scenes, motif salience, and section placement (payoff-section boost). Tracks whether hooks are developed, neglected, or undermined, and flags when a transition fails to deliver expected payoff. Rhythm-side ranking is currently heuristic (drum-track detection + clip reuse); true onset-based rhythmic features are on the roadmap.
 
 ### Session Continuity
 
@@ -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).
+325 tools across 45 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -204,7 +204,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 The M4L Analyzer sits on the master track. UDP 9880 carries spectral data to the server. OSC 9881 sends commands back.
 
 > [!TIP]
-> All 281 core tools work without the analyzer — it adds 36 bridge tools and closes the feedback loop.
+> Most tools work without the analyzer — it adds 32 spectral/analyzer tools (frequency, loudness, perception) and closes the feedback loop.
 
 ```
 SPECTRAL ─────── 8-band frequency decomposition (sub → air)
@@ -232,7 +232,7 @@ The atlas is an in-memory indexed database of Ableton's entire device library.
 
 ```
 1305 devices total
-  81 enriched with sonic intelligence (mood, genre, texture, chains)
+  71 enriched with sonic intelligence (mood, genre, texture, chains)
  683 drum kits mapped with note assignments
    6 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre
 ```
@@ -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>
 
@@ -317,7 +317,7 @@ Prompt-to-plan auto-composition engine.
 └─────────────────┘
 ```
 
-- 7 genre defaults: techno, house, ambient, hip-hop, dnb, dub, experimental
+- 4 genre defaults: house, techno, trap, ambient (unknown genres fall back to a neutral plan)
 - Returns step-by-step plans — the agent executes each tool call in sequence
 - `compose` — plan a multi-layer composition from text prompt
 - `augment_with_samples` — plan sample-based layers for existing session
@@ -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 325 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 325 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;
   }