livepilot 1.10.8 → 1.10.9

package/CHANGELOG.md

@@ -1,5 +1,133 @@
 # 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,

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  324 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
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   324 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 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.
+**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/`) — 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 324 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
 
-324 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
 ```
@@ -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 324 tools →](docs/manual/tool-catalog.md)**
+> **[View all 325 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -587,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 324 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/m4l_device/livepilot_bridge.js

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

package/mcp_server/__init__.py

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

package/mcp_server/evaluation/fabric.py

@@ -31,6 +31,66 @@ from .policy import apply_hard_rules
 # ── Sonic Evaluator ──────────────────────────────────────────────────
 
 
+def _compute_taste_fit(
+    dimension_changes: dict[str, dict],
+    outcome_history: Optional[list[dict]],
+) -> float:
+    """Score how well this move aligns with the user's recent taste.
+
+    Shipped in v1.10.9 — previously hardcoded to 0.0.
+
+    For each dimension that moved (in ``dimension_changes``), look at the
+    user's last few kept/undone outcomes for the same dimension:
+      * kept with the same direction of delta → +0.2 per match
+      * undone with the same direction of delta → −0.2 per match
+
+    Returns a value in 0..1 (0.5 = neutral, neither signal). Empty history
+    returns 0.5, which is the correct "no information yet" neutral the
+    composite score already expects.
+
+    ``outcome_history`` entries are dicts of the shape::
+
+        {"dimension": "punch", "delta": 0.12, "kept": True}
+
+    Callers that pass a richer shape should extract those three fields.
+    Malformed entries are skipped silently so a schema bump upstream can't
+    break the evaluator.
+    """
+    if not outcome_history or not dimension_changes:
+        return 0.5
+
+    # Only weigh the most recent slice — taste drifts, and older signals
+    # shouldn't veto a current evaluation.
+    recent = outcome_history[-10:]
+
+    adjustment = 0.0
+    matched = 0
+    for dim, change in dimension_changes.items():
+        current_delta = change.get("delta", 0.0)
+        current_sign = 1 if current_delta > 0 else (-1 if current_delta < 0 else 0)
+        if current_sign == 0:
+            continue
+        for entry in recent:
+            if not isinstance(entry, dict):
+                continue
+            if entry.get("dimension") != dim:
+                continue
+            past_delta = entry.get("delta")
+            if not isinstance(past_delta, (int, float)):
+                continue
+            past_sign = 1 if past_delta > 0 else (-1 if past_delta < 0 else 0)
+            if past_sign != current_sign:
+                continue
+            kept = bool(entry.get("kept", False))
+            adjustment += 0.2 if kept else -0.2
+            matched += 1
+
+    if matched == 0:
+        return 0.5
+    # Neutral baseline 0.5 + averaged adjustment, clamped to [0, 1].
+    return _clamp(0.5 + adjustment / matched)
+
+
 def evaluate_sonic_move(
     request: EvaluationRequest,
     outcome_history: Optional[list[dict]] = None,
@@ -109,12 +169,13 @@ def evaluate_sonic_move(
     measurable_component = _clamp(0.5 + measurable_delta)
     preservation = _clamp(1.0 - collateral_damage * 5)
     confidence = measurable_count / max(len(targets), 1)
+    taste_fit = _compute_taste_fit(dimension_changes, outcome_history)
 
     score = (
         0.30 * goal_fit
         + 0.25 * measurable_component
         + 0.15 * preservation
-        + 0.10 * 0.0   # taste_fit: placeholder, no history in fabric v1
+        + 0.10 * taste_fit
         + 0.10 * confidence
         + 0.10 * 1.0   # reversibility: 1.0 for undo-able moves
     )

package/mcp_server/m4l_bridge.py

@@ -443,17 +443,28 @@ class M4LBridge:
         if not self.cache.is_connected:
             return {"error": "LivePilot Analyzer not connected. Drop it on the master track."}
 
+        # Fail fast if there is no receiver to correlate the reply. Prior
+        # versions sent the OSC packet anyway, never registered a future,
+        # and then waited out the full 35s timeout with a misleading
+        # "device may be busy or removed" diagnosis — the real cause was
+        # "no receiver wired" (UDP 9880 failed to bind at startup).
+        if self.receiver is None:
+            return {
+                "error": "M4L bridge has no active receiver — the UDP 9880 "
+                         "listener did not start. Check server startup logs "
+                         "for a bind failure on port 9880."
+            }
+
         if self._cmd_lock is None:
             self._cmd_lock = asyncio.Lock()
         async with self._cmd_lock:
             # Cancel any stale capture future before creating a new one
-            if self.receiver and self.receiver._capture_future and not self.receiver._capture_future.done():
+            if self.receiver._capture_future and not self.receiver._capture_future.done():
                 self.receiver._capture_future.cancel()
 
             loop = asyncio.get_running_loop()
             future = loop.create_future()
-            if self.receiver:
-                self.receiver.set_capture_future(future)
+            self.receiver.set_capture_future(future)
 
             osc_data = self._build_osc(command, args)
             self._sock.sendto(osc_data, self._m4l_addr)
@@ -463,8 +474,7 @@ class M4LBridge:
                 return result
             except asyncio.TimeoutError:
                 # Clean up the dangling future
-                if self.receiver:
-                    self.receiver._capture_future = None
+                self.receiver._capture_future = None
                 return {"error": "M4L capture timeout — device may be busy or removed"}
 
     async def cancel_capture_future(self) -> None:

package/mcp_server/project_brain/automation_graph.py

@@ -12,6 +12,7 @@ def build_automation_graph(
     track_infos: list[dict],
     sections: list[dict] | None = None,
     clip_automation: list[dict] | None = None,
+    clips_scanned: int = 0,
 ) -> AutomationGraph:
     """Build an AutomationGraph covering both device-parameter automation
     hints and real clip envelopes (BUG-E2).
@@ -27,11 +28,17 @@ def build_automation_graph(
               parameter_name, parameter_type, device_name}].
             This is the ground truth — `device.parameters[i].is_automated`
             only reflects mapping state, not the presence of an envelope.
+        clips_scanned: total number of session clips the caller actually
+            probed for envelopes. Used to compute ``coverage_pct``; pass 0
+            when the caller couldn't enumerate clips (unknown → 0.0).
 
     Returns:
-        AutomationGraph with automated_params and density_by_section.
+        AutomationGraph with automated_params, density_by_section, and
+        the v1.10.9 coverage signals (coverage_pct, clip_envelope_count,
+        clips_scanned).
     """
     graph = AutomationGraph()
+    graph.clips_scanned = max(0, int(clips_scanned))
 
     if not track_infos and not clip_automation:
         return graph
@@ -121,4 +128,19 @@ def build_automation_graph(
             else:
                 graph.density_by_section[section_id] = 0.0
 
+    # BUG-D2 coverage signals.
+    # clip_envelope_count = distinct (track, clip) slots containing any envelope.
+    clip_slots_with_envelope: set[tuple[int, int | None]] = set()
+    for env in clip_automation or []:
+        clip_slots_with_envelope.add(
+            (int(env.get("track_index", -1)), env.get("clip_index"))
+        )
+    graph.clip_envelope_count = len(clip_slots_with_envelope)
+    if graph.clips_scanned > 0:
+        graph.coverage_pct = min(
+            1.0, graph.clip_envelope_count / float(graph.clips_scanned)
+        )
+    else:
+        graph.coverage_pct = 0.0
+
     return graph

package/mcp_server/project_brain/builder.py

@@ -24,6 +24,7 @@ def build_project_state_from_data(
     notes_map: Optional[dict[str, dict[int, list[dict]]]] = None,
     arrangement_clips: Optional[dict] = None,
     clip_automation: Optional[list[dict]] = None,
+    clips_scanned: int = 0,
     analyzer_ok: bool = False,
     flucoma_ok: bool = False,
     plugin_health: Optional[dict[str, Any]] = None,
@@ -107,6 +108,7 @@ def build_project_state_from_data(
         track_infos=track_infos or [],
         sections=section_dicts_for_auto,
         clip_automation=clip_automation or [],
+        clips_scanned=clips_scanned,
     )
     state.automation_graph.freshness.mark_fresh(state.revision)
 

package/mcp_server/project_brain/models.py

@@ -205,16 +205,35 @@ class RoleGraph:
 
 @dataclass
 class AutomationGraph:
-    """Automation presence and gesture density."""
+    """Automation presence and gesture density.
+
+    ``coverage_pct`` is the fraction of scanned clips that have at least
+    one automation envelope (0.0–1.0). Introduced in v1.10.9 to close
+    BUG-D2's "is this session missing automation?" signal — downstream
+    engines (Wonder Mode, Sound Design, etc.) can branch on a low
+    coverage value to recommend filter sweeps, volume crescendos, and
+    dub-style handoffs that the producer hasn't written yet.
+
+    ``clip_envelope_count`` is the raw total of per-clip envelopes
+    discovered; distinguishes "no automation in the project at all"
+    (count=0) from "automation exists but is lightly used" (count>0 but
+    coverage_pct<0.2).
+    """
 
     automated_params: list[dict] = field(default_factory=list)
     density_by_section: dict[str, float] = field(default_factory=dict)
+    coverage_pct: float = 0.0
+    clip_envelope_count: int = 0
+    clips_scanned: int = 0
     freshness: FreshnessInfo = field(default_factory=FreshnessInfo)
 
     def to_dict(self) -> dict:
         return {
             "automated_params": list(self.automated_params),
             "density_by_section": dict(self.density_by_section),
+            "coverage_pct": round(self.coverage_pct, 3),
+            "clip_envelope_count": self.clip_envelope_count,
+            "clips_scanned": self.clips_scanned,
             "freshness": self.freshness.to_dict(),
         }
 

package/mcp_server/project_brain/tools.py

@@ -131,11 +131,15 @@ def build_project_brain(ctx: Context) -> dict:
     # automation actually lives on each clip (session + arrangement). We
     # walk every clip slot that has a clip and ask get_clip_automation, then
     # aggregate into a flat list keyed by section.
+    #
+    # clips_scanned is the denominator for coverage_pct (BUG-D2) — it
+    # counts how many (track, scene) slots we probed, regardless of
+    # whether an envelope came back. Without this, a session with zero
+    # automation would be indistinguishable from a session where we
+    # failed to probe, which is exactly the ambiguity BUG-D2 flagged.
     clip_automation: list[dict] = []
+    clips_scanned = 0
     try:
-        # Iterate session scenes x tracks, plus arrangement clips we already have.
-        # Use the raw enumerate index for section_id so it stays aligned with
-        # arrangement_graph sections (which use the same scheme — see E1 fix).
         for scene_idx, scene in enumerate(scenes or []):
             scene_name = str(scene.get("name", "")).strip()
             if not scene_name:
@@ -143,6 +147,7 @@ def build_project_brain(ctx: Context) -> dict:
             section_id = f"sec_{scene_idx:02d}"
             for track in tracks:
                 t_idx = track.get("index", 0)
+                clips_scanned += 1
                 try:
                     auto_resp = ableton.send_command("get_clip_automation", {
                         "track_index": t_idx,
@@ -196,6 +201,7 @@ def build_project_brain(ctx: Context) -> dict:
         notes_map=notes_map if notes_map else None,
         arrangement_clips=arrangement_clips if arrangement_clips else None,
         clip_automation=clip_automation if clip_automation else None,
+        clips_scanned=clips_scanned,
         analyzer_ok=analyzer_ok,
         flucoma_ok=flucoma_ok,
         session_ok=True,
@@ -230,6 +236,7 @@ def get_project_brain_summary(ctx: Context) -> dict:
         "section_count": len(state.arrangement_graph.sections),
         "role_count": len(state.role_graph.roles),
         "automated_param_count": len(state.automation_graph.automated_params),
+        "automation_coverage_pct": round(state.automation_graph.coverage_pct, 3),
         "tempo": state.session_graph.tempo,
         "time_signature": state.session_graph.time_signature,
         "is_stale": state.is_stale(),