livepilot 1.21.0 → 1.21.1

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## 1.21.1 — Audit-response patch: experiment-commit safety + doc hygiene + lockfile (April 24 2026)
+
+Small patch release responding to an external audit of v1.21.0 performed
+the same day it shipped. The audit surfaced one real safety bug
+(commit_experiment status allowlist was an exclusion list when the
+intent was an inclusion list) plus several doc-consistency drifts.
+No new features. No API changes beyond the tightened commit_experiment
+contract. v1.21.0 callers already doing the right thing
+(run_experiment → commit the ranked winner) continue to work unchanged.
+
+### P1 — commit_experiment only accepts `status='evaluated'`
+
+Pre-fix (v1.21.0 and all prior versions with commit_experiment), the
+status check was an EXCLUSION list:
+
+```python
+if target.status in ("rejected", "analytical", "failed"):
+    return {"error": ...}
+```
+
+Blocks 3 statuses; implicitly allows the other 6 — including `pending`,
+`running`, `discarded`, and `interesting_but_failed`. Those branches
+can't be ranked by `compare_experiments()`, but `commit_experiment`
+would accept them as long as a compiled plan was attached. The code's
+own inline comment already described the correct contract ("only
+status='evaluated' branches are ranking candidates"); the implementation
+had the wrong polarity. The fix flips it to an INCLUSION check:
+
+```python
+if target.status != "evaluated":
+    return {"error": ...}
+```
+
+Error message updated to enumerate all 9 possible statuses and explain
+which state each represents (pending/running = not yet evaluated;
+rejected/analytical/failed = classifier exclusions; committed =
+already committed; discarded = explicitly thrown out;
+interesting_but_failed = exploration-audit only).
+
+Why this matters: v1.21.0's `commit_experiment` ledger writer records
+every commit into `SessionLedger` where anti-repetition filters read
+it. Without the tighter status check, a caller bypassing the ranking
+layer could pollute the ledger with entries the system explicitly
+classified as non-winners — degrading anti-repetition signal quality.
+
+**Regression tests added (4)** in `tests/test_commit_experiment_ledger.py`:
+`test_commit_on_pending_branch_rejects`,
+`test_commit_on_running_branch_rejects`,
+`test_commit_on_discarded_branch_rejects`,
+`test_commit_on_interesting_but_failed_branch_rejects`. All FAILED
+pre-fix (reproducing the audit's finding), all PASS post-fix.
+
+### P1 — package-lock.json bumped 1.17.5 → 1.21.1
+
+Lockfile's root `.version` and `.packages[""].version` had been stale
+at 1.17.5 since before v1.18. `npm publish` doesn't read these fields
+(it reads package.json), so the npm registry was always correct — but
+the repo-local lockfile misled local `npm install` workflows and any
+release-check tooling that compared package.json vs lockfile. Fixed by
+surgical replace on the 2 stale strings; no dependency tree
+regeneration (keeps dep versions identical to v1.21.0).
+
+### P2 — Analyzer tool count: 32/33 → 38 (actual)
+
+README.md previously said "32 spectral/analyzer tools" in one place
+and "38 analyzer tools" in another — inconsistent within the same file.
+`docs/M4L_BRIDGE.md` said "33 MCP tools in the analyzer domain" in two
+places. Actual `@mcp.tool` count in `mcp_server/tools/analyzer.py` is
+**38** (grep-verified). All stale 32/33 refs corrected to 38.
+
+### P2 — Reversibility language hedge
+
+README's header NOTE block said "Everything is reversible with undo,"
+which is too strong. Live-session mutations (clips, devices, mixer,
+arrangement) do route through Ableton's undo stack and are reversible
+— but Splice downloads, memory/ledger writes, installer actions, atlas
+scans, and filesystem writes persist beyond undo. Hedged the language
+to reflect this.
+
+### Deferred to v1.22
+
+Audit-surfaced items that aren't patch-release material:
+
+- **Atlas statistics reconciliation.** Docs claim "1305 devices / 120
+  enriched / 641 pack-indexed" across 9 description fields, but the
+  shipped `device_atlas.json` has 5264 devices and 135 entries with
+  `.enriched` truthy. The "1305" number appears to be a long-stale
+  cargo-culted count. Requires deciding whether `.devices` contains
+  duplicates, what the canonical "enriched" definition is, and
+  whether to restructure atlas JSON or fix the readers that look for
+  `.meta.version`. v1.22 scope.
+- **`sync_metadata` expansion** to check package-lock.json project
+  version, semantic-move count via `registry.count()`, and
+  analyzer-tool count via grep on `analyzer.py`. Would convert this
+  entire class of drift into CI failures.
+- **Dev-install path** for local contributors hitting missing
+  `soundfile` / `scipy` / `pretty_midi` / `pytest_asyncio` deps during
+  bare-python local runs. CI has these installed via requirements.txt.
+
+### Credits
+
+External audit performed same day v1.21.0 shipped. Findings
+file-linked and reproducible. Response time: ~2 hours from audit
+receipt to v1.21.1 patch shipping.
+
+### Scope stats
+
+- 1 code fix (`mcp_server/experiment/tools.py` — commit_experiment status check)
+- 4 new regression tests (all initially FAILING pre-fix to reproduce
+  the audit, all PASSING post-fix)
+- 3 doc corrections (README.md × 2, docs/M4L_BRIDGE.md × 2, plus the
+  reversibility hedge)
+- 15 version-string sites + `.amxd` binary patch (2 bytes) +
+  package-lock.json (2 version fields)
+- Test suite: 3120 → 3124 pass (+4). Zero regressions.
+
+---
+
 ## 1.21.0 — Consolidation: experiment ledger + preset library + record-readiness + reader audit (April 24 2026)
 
 Consolidation release closing five items from the v1.20 plan §12 non-goals

package/README.md

@@ -25,7 +25,9 @@
 > [!NOTE]
 > LivePilot works with **any MCP client** — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf.
 > All tools execute on Ableton's main thread through the official Live Object Model API.
-> Everything is reversible with undo.
+> Live-session mutations (clips, devices, mixer, arrangement) route through Ableton's undo stack.
+> Side effects that touch state outside the Live project — Splice downloads, memory/ledger writes,
+> installer actions, atlas scans, filesystem writes — persist beyond undo.
 
 <br>
 
@@ -43,7 +45,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 | **Sample Engine** | Three-source sample intelligence — Ableton's browser, your filesystem, and Splice's catalog (plan-aware: Ableton Live plan uses daily quota, Sounds+/Creator uses credits, free samples bypass both). 6 fitness critics. 29 processing techniques. Collections, presets, preview-URL audition, LIVE Describe-a-Sound + Variations via Splice GraphQL |
 | **Spectral Perception** | Real-time ears via M4L — 9-band FFT (with sub_low split at 20-60 Hz for kick fundamentals), RMS/peak metering, Krumhansl-Schmuckler key detection, pitch tracking, FluCoMa mel/chroma/onset. Auto-loaded via `ensure_analyzer_on_master` (v1.20.3) — no more silently-degraded mix moves from forgotten analyzer |
 | **Technique Memory** | Persistent library of production decisions. Save a beat pattern, device chain, or mix template. Recall by mood, genre, or texture across sessions |
-| **Creative Intelligence** | 12 engines on top of the tools: SongBrain, Taste Graph, Wonder Mode, Mix/Sound-Design/Transition/Reference/Translation engines, Hook Hunter, Stuckness Detector, Session Continuity, Preview Studio. **43 semantic moves** (v1.20) — musical intents like "tighten the low end" or "make kick and bass lock" that compile into tool sequences with risk levels and target dimensions |
+| **Creative Intelligence** | 12 engines on top of the tools: SongBrain, Taste Graph, Wonder Mode, Mix/Sound-Design/Transition/Reference/Translation engines, Hook Hunter, Stuckness Detector, Session Continuity, Preview Studio. **44 semantic moves** (v1.21) — musical intents like "tighten the low end" or "make kick and bass lock" that compile into tool sequences with risk levels and target dimensions |
 
 <br>
 
@@ -101,7 +103,7 @@ 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. 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 31 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.
+**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 38 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 31 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, 120 enriched with YAML sonic intelligence profiles (mood, genre, texture, recommended chains). 7 indexes: by_id, by_name, by_uri, by_category, by_tag, by_genre, by_pack (641 devices mapped to their source pack). Reverse-index `device_techniques_index.json` powers `atlas_techniques_for_device` (146 cross-references across 58 devices). The AI never hallucinates a device name or preset — it always resolves against the atlas first.
 
@@ -133,7 +135,7 @@ Learns your production preferences across sessions. Tracks which move families y
 
 ### Semantic Moves — Musical Actions, Not Parameters
 
-**43 high-level intents** across 7 families (mix, arrangement, transition, sound_design, performance, device_creation, sample) — "add contrast," "tighten the low end," "make kick and bass lock," "sample vocal ghost," "destroy then rebuild." Each move compiles into a concrete tool sequence with risk level, target dimensions, and protection thresholds. Analyzer-gated moves (`tighten_low_end`, `make_kick_bass_lock`) mark their spectrum pre-reads as optional so the plan continues even when the analyzer isn't available. The AI knows what it's risking with every action.
+**44 high-level intents** across 7 families (mix, arrangement, transition, sound_design, performance, device_creation, sample) — "add contrast," "tighten the low end," "make kick and bass lock," "sample vocal ghost," "destroy then rebuild." Each move compiles into a concrete tool sequence with risk level, target dimensions, and protection thresholds. Analyzer-gated moves (`tighten_low_end`, `make_kick_bass_lock`) mark their spectrum pre-reads as optional so the plan continues even when the analyzer isn't available. The AI knows what it's risking with every action.
 
 ### Wonder Mode — Stuck-Rescue Workflow
 

package/m4l_device/livepilot_bridge.js

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

package/mcp_server/__init__.py

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

package/mcp_server/experiment/tools.py

@@ -695,23 +695,47 @@ async def commit_experiment(
     if not experiment:
         return {"error": f"Experiment {experiment_id} not found"}
 
-    # Refuse to commit branches the classifier rejected or that were
-    # analytical-only. Those statuses exist specifically so callers
-    # can't route them into re-application, and ranked_branches()
-    # already excludes them — so reaching commit with such a branch
-    # means the caller is bypassing the ranking layer.
+    # v1.21.1 fix (external audit 2026-04-24): accept ONLY status='evaluated'.
+    # Pre-fix, the check was an exclusion list —
+    # `if target.status in ("rejected", "analytical", "failed"):` — which
+    # implicitly allowed 'pending', 'running', 'discarded', and
+    # 'interesting_but_failed' to commit even though
+    # compare_experiments() never ranks them. The code's inline comment
+    # below ("only status='evaluated' branches are ranking candidates")
+    # already described the correct contract; this fix flips the
+    # polarity so the implementation matches. See
+    # docs/plans/v1.21-impl-status.md Appendix C for the audit-response log.
+    #
+    # Status semantics (from ExperimentBranch lifecycle):
+    #   pending                — create_experiment landed; run_experiment hasn't touched it
+    #   running                — run_experiment is mid-flight on this branch
+    #   evaluated              — run_experiment finished; ranking candidate ✓
+    #   rejected               — hard-rule classifier rolled back (protect violation, etc.)
+    #   analytical             — no executable plan (seed was analytical_only)
+    #   failed                 — zero steps applied successfully
+    #   committed              — already committed (re-commit is wrong)
+    #   discarded              — caller explicitly threw it out
+    #   interesting_but_failed — exploration-mode audit trail; not ranked
     target = experiment.get_branch(branch_id)
     if target is None:
         return {"error": f"Branch {branch_id} not found"}
-    if target.status in ("rejected", "analytical", "failed"):
+    if target.status != "evaluated":
         return {
             "error": (
-                f"Cannot commit branch with status '{target.status}'. "
-                f"'rejected' = hard-rule classifier rolled back; "
-                f"'analytical' = no executable plan; "
-                f"'failed' = zero steps applied successfully. "
-                f"Use compare_experiments to see eligible winners "
-                f"(only status='evaluated' branches are ranking candidates)."
+                f"Cannot commit branch with status '{target.status}' — "
+                f"only status='evaluated' branches are commit candidates. "
+                f"Reason depends on current status: "
+                f"'pending' / 'running' = run_experiment hasn't evaluated "
+                f"this branch yet (run it first); "
+                f"'rejected' = hard-rule classifier rolled it back; "
+                f"'analytical' = no executable plan (analytical_only seed); "
+                f"'failed' = zero steps applied successfully during run; "
+                f"'committed' = already committed (don't re-run); "
+                f"'discarded' = caller explicitly threw this branch out; "
+                f"'interesting_but_failed' = kept for audit in "
+                f"exploration mode, but classifier excluded from ranking. "
+                f"Use compare_experiments to see eligible (ranked) "
+                f"winners — they are always status='evaluated'."
             ),
             "branch_id": branch_id,
             "branch_status": target.status,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.21.0",
+  "version": "1.21.1",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 430 tools, 53 domains, 43 semantic moves. Device atlas (1305 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, 12 creative intelligence engines",
+  "description": "Agentic production system for Ableton Live 12 — 430 tools, 53 domains, 44 semantic moves. Device atlas (1305 devices, 120 enriched, 7 indexes), Splice intelligence (gRPC + GraphQL describe-a-sound + preview + collections + presets), 9-band spectral perception auto-loaded via ensure_analyzer_on_master, Creative Director skill, technique memory, 12 creative intelligence engines",
   "author": "Pilot Studio",
   "license": "BSL-1.1",
   "type": "commonjs",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.21.0"
+__version__ = "1.21.1"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.dreamrec/livepilot",
-  "description": "430-tool agentic MCP production system for Ableton Live 12 — 53 domains, 43 semantic moves, device atlas (1305 devices), Splice intelligence (gRPC + GraphQL), 9-band spectral perception auto-loaded, Creative Director skill, technique memory, 12 creative engines",
+  "description": "430-tool agentic MCP production system for Ableton Live 12 — 53 domains, 44 semantic moves, device atlas (1305 devices), Splice intelligence (gRPC + GraphQL), 9-band spectral perception auto-loaded, Creative Director skill, technique memory, 12 creative engines",
   "repository": {
     "url": "https://github.com/dreamrec/LivePilot",
     "source": "github"
   },
-  "version": "1.21.0",
+  "version": "1.21.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.21.0",
+      "version": "1.21.1",
       "transport": {
         "type": "stdio"
       }