livepilot 1.9.9 → 1.9.12

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "livepilot",
       "description": "Agentic production system for Ableton Live 12 — 178 tools, 17 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
-      "version": "1.9.9",
+      "version": "1.9.12",
       "author": {
         "name": "Pilot Studio"
       },

package/AGENTS.md

@@ -1,4 +1,4 @@
-# LivePilot v1.9.9 — Ableton Live 12
+# LivePilot v1.9.12 — Ableton Live 12
 
 ## Project
 - **Repo:** This directory (LivePilot)

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 1.9.12 — Deep Audit: 21 Fixes Across 15 Files (April 2026)
+
+**Full codebase audit — 5 critical, 10 important, 6 doc/test fixes.**
+
+### Critical Fixes
+- Fix(P1): `capture_stop` no longer deadlocks — `cancel_capture_future` removed lock acquisition that blocked behind `send_capture`
+- Fix(P1): `import_midi_to_clip` now distinguishes empty-slot NOT_FOUND from INDEX_ERROR/TIMEOUT instead of swallowing all AbletonConnectionErrors
+- Fix(P1): capture audio files now write to `~/Documents/LivePilot/captures/` (stable path) instead of beside the .amxd preset
+- Fix(P1): `check_flucoma` now uses `Folder.end` to detect FluCoMa — `typelist` check was always true
+- Fix(P1): CI workflow updated to `actions/checkout@v4` + `actions/setup-python@v5` (v6 doesn't exist)
+
+### Safety & Validation
+- Fix(P2): 5 automation tools now validate `track_index >= 0` and `clip_index >= 0` (matching all peer modules)
+- Fix(P2): `cmd_stop_scrub` now checks `cursor_a.id === 0` for empty clip slots (matching all peer bridge functions)
+- Fix(P2): `cmd_get_selected` now resolves return tracks (negative indices) and master track (-1000)
+- Fix(P2): `duplicate_track` uses count-before/after delta for correct group track duplication index
+- Fix(P2): `create_arrangement_clip` locates first clip by `start_time` instead of stale index after trim pass
+- Fix(P2): `get_session_info` reuses already-built lists instead of re-iterating `song.tracks`/`song.scenes`
+- Fix(P2): client disconnect race — socket now closes before clearing `_client_connected` flag
+
+### Tests
+- Fix: transport validation tests now import production `_validate_tempo`/`_validate_time_signature` instead of testing local copies
+- Fix: added `load_sample_to_simpler` to analyzer tool contract (was 28/29)
+- Fix: removed duplicate `test_release_quick_verify_checks_both_plugin_manifests`
+- New: 5 automation negative tests (index validation, parameter_type validation)
+
+### Documentation
+- Fix: `docs/manual/index.md` domain map — Tracks 14→17, Devices 12→15, Scenes 8→12
+- Fix: README perception split — 145+33 → 149+29 (actual analyzer tool count is 29)
+- Fix: M4L_BRIDGE.md command count — 22→28 (6 commands undocumented)
+- Fix: tool-reference.md MIDI docs — `export_clip_midi` and `import_midi_to_clip` parameter tables matched to actual signatures
+
+### Deferred (documented, low-impact)
+- Timed-out commands still execute on main thread (needs cancellation token redesign)
+- Chunked UDP reassembly fragile on packet loss (loopback mitigates)
+- Diatonic transpose octave correction edge case (needs musical test suite)
+- `cmd_map_plugin_param` reports false success (LiveAPI lacks Configure mapping API)
+
+Verification: 145 tests passing (non-fastmcp), 178 tools confirmed, 15 files changed
+
+## 1.9.11 — Session Diagnostics + Client Conflict Clarity (March 2026)
+
+**Live-tested against the open Ableton set after reloading the updated Remote Script.**
+
+- Fix(P1): device loading now surfaces post-load plugin health hints, including `opaque_or_failed_plugin`, `sample_dependent`, `plugin_host_status`, and `mcp_sound_design_ready`
+- Fix(P1): `get_session_diagnostics` now flags opaque/sample-dependent plugins and no longer crashes on track types that omit standard `arm`/`mute`/`solo` properties
+- Fix(P1): analyzer tools now distinguish between “analyzer missing” and “analyzer loaded but bridge/client conflict” when UDP 9880 is unavailable
+- Fix(P1): add Hijaz / Phrygian Dominant theory support across key parsing, scale construction, chord building, and `identify_scale`
+- Fix(P2): `--status` and TCP timeout paths now explain when another LivePilot client appears to be connected instead of only reporting a generic timeout
+- Docs: beat/sounddesign/core skill guidance now includes device-health checks, sample-dependent plugin cautions, and pitch-audit discipline from the live stress-test sessions
+- Verification: `292 passed`, `npm pack --dry-run` passed, live set diagnostics succeeded, analyzer bridge streamed on the master track, and conflict reproduction now reports the competing client PID
+- Fix(P1): brownian automation curve reflection loop now has 100-iteration guard with hard clamp fallback — high volatility values could previously hang the server
+- Fix(P1): schema coercion now recurses into array `items` so `list[float]` params benefit from string-to-number widening for MCP clients that serialize as strings
+- Fix(P1): `apply_automation_shape` and `apply_automation_recipe` now validate `parameter_type` and required companion params before sending to Ableton
+- Fix(P2): Remote Script `AssertionError` fallbacks now return STATE_ERROR instead of running LOM calls on the TCP thread during ControlSurface disconnection
+- Fix(P2): M4L bridge ping version corrected to 1.9.11; `check_flucoma` now probes disk for FluCoMa package instead of returning hardcoded `true`
+- Verification: deep audit across 45+ files (3 parallel agents), 292 unit tests + 15 live integration tests against Ableton session, all passing
+
+## 1.9.10 — Analyzer Capture Finalization + Release Sync (March 2026)
+
+**Live-tested in Ableton after a full analyzer rebuild and master-track validation.**
+
+- Fix(P1): `capture_audio` now writes finalized WAV files instead of header-only stubs by correcting the `sfrecord~` start/stop messages in the analyzer patch
+- Fix(P1): add a small delayed record start in `LivePilot_Analyzer.maxpat` to avoid the open/start race on fresh capture writes
+- Fix(P2): normalize Max-style `Macintosh HD:/Users/...` file paths to POSIX paths in the Python bridge and offline perception tools
+- Fix(P2): make OSC string args Unicode-safe end to end with ASCII-safe `b64:` transport and Max-side UTF-8 decode
+- Fix(P2): arrangement automation unsupported cases now surface as outer MCP errors instead of fake success payloads
+- Fix(P2): missing required Remote Script params now return `INVALID_PARAM` consistently
+- Fix(P3): release metadata now treats Codex as the primary plugin manifest with Claude as a mirrored manifest
+- Verification: live `capture_audio` wrote a 1.48s WAV from the master track; offline loudness + metadata reads succeeded on the returned path
+
+## 1.9.9 — M4L Bridge Hardening + Deep Audit (March 2026)
+
+**87 tools tested live, 0 failures. 13 bugs fixed across JS bridge + Python tools.**
+
+### M4L Bridge (livepilot_bridge.js)
+- Fix(P0): Remove `str_for_value` from all batched JS readers — Auto Filter hangs Max's JS engine (uncatchable), binary-patched .amxd
+- Fix(P1): Deferred `udpsend` socket re-initialization via `deferlow` — fixes UDP not sending when device loads from a saved Live Set (socket fails to bind on frozen device restore)
+- Fix(P1): Add try-catch to ALL Task.schedule batch functions: cmd_get_params, cmd_get_hidden_params, cmd_get_display_values, cmd_get_auto_state, cmd_get_plugin_params — prevents silent crash on parameter read errors
+- Fix(P1): cmd_get_chains_deep, cmd_get_track_cpu, cmd_map_plugin_param — added missing error handling
+- Fix(P2): Add `dspstate~` → JS inlet 1 for sample rate reporting (was declared in JS but missing from patcher)
+- Fix(P2): Deferred `snapshot~` re-activation via `live.thisdevice` → `deferlow` — safety net for frozen device reload
+- Perf: Batch size 4→8, delay 50→20ms (2.5× faster parameter reads)
+- Fix: Binary-patch openinpresentation 0→1 in .amxd
+
+### Python MCP Server
+- Fix(P1): classify_progression accepts dict inputs `{"root": "F#", "quality": "minor"}` in addition to strings
+- Fix(P1): Higher bridge timeouts — hidden_params 15s, display_values 15s, auto_state 10s, plugin_params 20s, plugin_presets 15s, map_plugin 10s
+- Fix(P1): load_sample_to_simpler wraps send_command calls in try-except (prevents AbletonConnectionError propagation)
+- Fix(P2): _ensure_list catches json.JSONDecodeError → ValueError (6 files: notes, devices, generative, scenes, harmony, automation)
+- Fix(P2): _get_m4l/_get_spectral raise ValueError instead of RuntimeError (FastMCP compatibility)
+
 ## 1.9.7 — Safe automation fallback + correct clip length reporting (March 2026)
 
 - Fix(P1): set_arrangement_automation places replacement BEFORE deleting original — no data loss if placement fails

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a welcoming and respectful experience for everyone, regardless of background or experience level.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy toward other community members
+
+## Enforcement
+
+Project maintainers are responsible for clarifying standards of acceptable behavior and will take appropriate and fair corrective action in response to any unacceptable behavior.
+
+Instances of unacceptable behavior may be reported by opening an issue or contacting the maintainers directly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.
+
+For the full text, see <https://www.contributor-covenant.org/version/2/1/code_of_conduct/>.

package/CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to LivePilot
+
+Thank you for your interest in contributing to LivePilot. This guide will help you get started.
+
+## Quick Links
+
+- [Bug reports](https://github.com/dreamrec/LivePilot/issues/new?template=bug_report.yml)
+- [Feature requests](https://github.com/dreamrec/LivePilot/issues/new?template=feature_request.yml)
+- [Questions & help](https://github.com/dreamrec/LivePilot/discussions)
+
+## Development Setup
+
+```bash
+git clone https://github.com/dreamrec/LivePilot.git
+cd LivePilot
+python3 -m venv .venv
+source .venv/bin/activate          # macOS/Linux
+.venv/bin/pip install -r requirements.txt
+.venv/bin/pip install pytest pytest-asyncio
+```
+
+### Install the Remote Script
+
+```bash
+npx livepilot --install
+```
+
+Restart Ableton → Preferences → Link, Tempo & MIDI → Control Surface → **LivePilot**
+
+### Run Tests
+
+```bash
+pytest tests/ -v
+```
+
+Tests run without Ableton — they validate tool contracts, schema, and pure Python logic.
+Integration testing with a live session is done manually.
+
+## Architecture Overview
+
+```
+remote_script/LivePilot/   Python ControlSurface inside Ableton (main thread)
+mcp_server/                FastMCP server — validates inputs, sends TCP to Ableton
+m4l_device/                Max for Live analyzer — UDP/OSC bridge for deep LOM access
+livepilot/                 Plugin — skills, slash commands, producer agent
+installer/                 Auto-detects Ableton path, copies Remote Script
+```
+
+All Live Object Model (LOM) calls execute on Ableton's main thread via `schedule_message`.
+Communication is JSON over TCP, newline-delimited, port 9878.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Use the [bug report template](https://github.com/dreamrec/LivePilot/issues/new?template=bug_report.yml).
+Include:
+
+- LivePilot version (`npx livepilot --version`)
+- Ableton Live version
+- Diagnostics output (`npx livepilot --doctor`)
+- Steps to reproduce
+
+### Suggesting Features
+
+Use the [feature request template](https://github.com/dreamrec/LivePilot/issues/new?template=feature_request.yml).
+Explain the workflow problem before describing the solution.
+
+### Submitting Code
+
+1. **Fork** the repository
+2. **Create a branch** from `main` (`git checkout -b feat/your-feature`)
+3. **Make your changes** — keep commits focused and atomic
+4. **Run tests** — `pytest tests/ -v` must pass
+5. **Update documentation** if you add or remove tools:
+   - Update tool count in `README.md`, `CLAUDE.md`, `package.json`
+   - Add an entry to `CHANGELOG.md`
+6. **Open a PR** against `main`
+
+### Code Style
+
+- **Python:** Follow existing conventions in `mcp_server/`. No linter is enforced yet, but keep it clean.
+- **Remote Script:** All LOM calls must use `schedule_message` — never call the LOM directly from a non-main thread.
+- **M4L Bridge (JS):** Changes to `livepilot_bridge.js` must be tested with the analyzer loaded on the master track in a live Ableton session.
+- **Error codes:** Use structured errors: `INDEX_ERROR`, `NOT_FOUND`, `INVALID_PARAM`, `STATE_ERROR`, `TIMEOUT`, `INTERNAL`.
+
+### Commit Messages
+
+Use concise, descriptive messages:
+
+```
+fix: bridge UTF-8 OSC args, KeyError→INVALID_PARAM
+feat: add per-track loudness analysis
+docs: update tool reference for v1.9.11
+```
+
+Prefix with `fix:`, `feat:`, `docs:`, `refactor:`, `test:`, or `chore:`.
+
+## Tool Count Discipline
+
+Currently **178 tools**. If you add or remove a `@mcp.tool()` decorator, update all of these files:
+
+- `README.md`
+- `CLAUDE.md`
+- `package.json` description
+- `livepilot/.Codex-plugin/plugin.json`
+- `livepilot/.claude-plugin/plugin.json`
+- `server.json`
+- `livepilot/skills/livepilot-core/SKILL.md`
+- `livepilot/skills/livepilot-core/references/overview.md`
+- `CHANGELOG.md`
+- `tests/test_tools_contract.py`
+- `docs/manual/index.md`
+- `docs/manual/tool-reference.md`
+
+## Areas Where Help Is Welcome
+
+- **Windows testing** — The installer and Remote Script are tested primarily on macOS
+- **Documentation** — Guides, tutorials, workflow examples
+- **New automation recipes** — Add to the 15 built-in recipes
+- **Theory tools** — Additional modes, non-Western scales, extended harmony
+- **Test coverage** — More contract tests, edge cases
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+By participating, you agree to uphold this code.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).