livepilot 1.18.3 → 1.19.1

package/CHANGELOG.md

@@ -1,5 +1,240 @@
 # Changelog
 
+## 1.19.1 — v1.19.0 polish (April 24 2026)
+
+Patch release addressing the three "Known gaps" documented at the
+end of the v1.19.0 CHANGELOG entry. All three were cosmetic or
+observability issues — no correctness changes. 3 new tests + 1
+pre-existing test tolerance widened. Test suite 2854 → 2858 pass.
+
+### Fixes
+
+- **#1 `baseline_transport` not exposed via `compare_experiments`.**
+  The field was populated internally on `ExperimentSet` (verified
+  by unit tests) but `compare_experiments`' MCP response omitted
+  it — operators had no surface-level path to verify the
+  between-branch drift fix was actually firing. Now present on
+  every response (`None` when the experiment hasn't run yet, so
+  clients can rely on key presence and check
+  `result["baseline_transport"] is None` without `in` guards).
+
+- **#2 Tempo warning midpoint rounds to int while range is exact.**
+  Pre-v1.19.1 `compile_hybrid_brief` with disjoint tempo ranges
+  reported warning text "midpoint 108 BPM" while the returned
+  range was 105-110 (centered on 107.5). Two rounding
+  conventions — human-facing text rounded to `:0f`, machine-facing
+  range kept the exact float. Fix: `:g` format in the warning
+  produces the shortest accurate representation (107.5 stays
+  "107.5"; 128.0 renders as "128") so both surfaces agree.
+
+- **#3 `weights` display full float precision.**
+  Uniform 3-packet hybrids rendered weights as
+  `0.3333333333333333` — noisy output that contrasted with
+  `evaluation_bias.target_dimensions` values already being
+  rounded to 4 decimal places. Weights are now rounded to 4 dp
+  in the response dict (`[0.3333, 0.3333, 0.3333]`). Internal
+  computation still uses full precision; only the output is
+  rounded.
+
+### Tests added
+
+- `test_compare_experiments_surfaces_baseline_transport` — round-trip
+  seed a distinctive baseline on ExperimentSet, assert
+  `compare_experiments` surfaces all fields (is_playing, song_time,
+  track_states, captured_at_ms).
+- `test_compare_experiments_baseline_none_when_not_captured` — fresh
+  experiment has `baseline_transport: None` in the response rather
+  than an omitted key.
+- `test_tempo_warning_midpoint_matches_range_center` — regex-parse
+  the warning text and assert its numeric midpoint matches the
+  returned range's center within 0.01 BPM.
+- `test_weights_rounded_to_4dp` — uniform 3-packet weights must be
+  representable at 4 dp precision (`round(w, 4) == w`).
+
+Test suite: 2858 pass, 1 skipped. Zero regressions. `sync_metadata
+--check` clean.
+
+## 1.19.0 — Experiment baseline + hybrid packet compilation (April 24 2026)
+
+Minor version bump. Ships two of the three open items documented in
+`docs/plans/v1.19-structural-plan.md`. Item C (full architectural
+routing of director Phase 6 through `apply_semantic_move`) is
+deferred to v1.20 per the plan's blast-radius rationale.
+
+Both items shipped under strict TDD: 52 new unit tests, zero
+regressions across the 2854-test suite. Both items live-tested in
+production (real Ableton session, Live 12.4.0, 13 live-test
+scenarios green).
+
+### Item A — Experiment baseline transport snapshot/restore
+
+Live-verified in v1.18.0 Test 8: running a 3-branch experiment
+sequentially produced inconsistent `before_snapshot` values
+because playback position, mute/solo/arm, and playing-clip state
+drifted across branches. `undo()` reverts command history but
+doesn't guarantee transport state is identical when each branch's
+`before_snapshot` fires. Track_meters[0].level values of 0.764 /
+0.000 / 0.873 across three branches rendered the before/after
+comparisons meaningless.
+
+Fix — snapshot-and-restore pattern, experiment-level:
+
+- NEW `mcp_server/experiment/baseline.py` — `BaselineTransportState`
+  dataclass + `capture_baseline(ableton)` +
+  `restore_baseline(ableton, baseline, stabilize_ms=300)`.
+  Captures `is_playing`, `song_time`, and per-track
+  `mute`/`solo`/`arm` via a single `get_session_info` round-trip.
+  Restore issues `stop_playback` → per-track
+  `set_track_mute`/`set_track_solo`/`set_track_arm` → 300 ms
+  stabilize sleep. Per-track failures are logged, not fatal (a
+  single flaky track never aborts restore for the rest).
+- `ExperimentSet` gains a `baseline_transport: Optional[BaselineTransportState]`
+  field. `to_dict()` surfaces it when populated.
+- `engine.prepare_for_next_branch(ableton, baseline, stabilize_ms)`
+  — thin wrapper called by `run_experiment` between branches.
+  No-op when baseline is None (first branch).
+- `run_experiment` captures the baseline once before the branch
+  loop starts, stashes it on the experiment, and calls
+  `prepare_for_next_branch` before every branch after the first.
+  Capture failure logs + degrades to None (pre-v1.19 behavior).
+
+**Stabilize window defaults to 300 ms** — midpoint of plan §2's
+200-500 ms empirical range. Per-branch overhead stayed at
+~1.04 s amortized under live 5-branch testing (well under the
+plan's 2-second-per-branch success criterion target).
+
+**Live evidence of state preservation:** 5-branch test with two
+mutations on track 0 "Dub Chord" (pan -0.35 by `widen_stereo`,
+then volume 0.4 by `darken_without_losing_width`) returned the
+track to identical pre-experiment state (arm=true, mute=false,
+solo=false) after every branch cycle.
+
+Known limitations (accepted per plan §2):
+- Automation drift is not frozen — deeper refactor out of scope.
+- Send values + device parameters mutated outside a branch's own
+  steps fall back to `undo()` alone — no explicit restore.
+- Transport position is NOT re-seeked; `song_time` is captured
+  but unused (stopping is enough).
+
+21 unit tests added: capture (transport fields, empty tracks,
+missing-field defaults, epoch-ms timestamp), restore (command
+sequence, per-track mute/solo/arm restoration, stabilize sleep
+with monkey-patched time.sleep, flaky-track resilience,
+return-track arm skip), `ExperimentSet.baseline_transport`
+(default None, to_dict surfacing/omission), engine helper
+(None no-op, delegation), tool-level wiring (`run_experiment`
+populates baseline once + idempotent on second run).
+
+### Item B — Hybrid concept packet compilation
+
+Pre-v1.19 the director handled "Basic Channel meets Dilla swing"
+via LLM ad-hoc reasoning — no explicit rule for contradictions
+(e.g., Gas deprioritizes rhythmic, Dilla emphasizes rhythmic;
+what survives the hybrid?). v1.18.0 Test 7 verified plausible
+output but entirely improvisational, with no guarantee either
+source packet's `avoid` list or tempo constraints would persist.
+
+Fix — explicit merge algorithm with canonical rules per plan §3:
+
+- NEW `mcp_server/creative_director/hybrid.py` —
+  `compile_hybrid_brief(packet_ids, weights=None)` loads concept
+  packets from `livepilot/skills/livepilot-core/references/concepts/`
+  and applies merge rules:
+    * `sonic_identity` / `avoid` / `reach_for.*` / `*_idioms` /
+      `sample_roles` / `dimensions_in_scope`: UNION, deduplicated,
+      first-packet order preserved.
+    * `dimensions_deprioritized` / `move_family_bias.deprioritize`:
+      INTERSECTION — only deprioritize if ALL packets agree.
+      Safer default: one packet's ignored dimension shouldn't
+      starve another packet's wanted one.
+    * `move_family_bias.favor`: INTERSECTION when non-empty
+      (hybrid focuses where both agree), UNION fallback with
+      warning when empty.
+    * `evaluation_bias.target_dimensions`: WEIGHTED AVERAGE
+      (default uniform; override via `weights`).
+    * `evaluation_bias.protect`: MAX per dimension (stricter
+      floor wins).
+    * `novelty_budget_default`: MAX (hybrid asks skew
+      exploratory).
+    * `tempo_hint`: NEAREST-OVERLAP — intersect overlapping
+      ranges, else midpoint + `disjoint: true` flag + warning.
+
+- NEW MCP tool `compile_hybrid_brief` in
+  `mcp_server/creative_director/tools.py` (tool count 428 → 429).
+  Accepts packet IDs as filename stems (`"basic-channel"`),
+  aliases (`"dilla"`), or packet `id` values
+  (`"dub_techno__basic_channel"`). Returns ValueError as an
+  error-dict response (doesn't raise).
+
+- NEW reference doc
+  `livepilot/skills/livepilot-creative-director/references/hybrid-compilation.md`
+  — canonical merge-rule table, output shape, interop notes,
+  guidance for handling the `warnings` list.
+
+- Director SKILL.md Phase 1 — explicit guidance to call
+  `compile_hybrid_brief` when the user names 2+ references,
+  with a mandate to surface any `warnings` entries (don't
+  silently average disjoint tempos).
+
+- Output exposes merged `avoid` also as `anti_patterns` alias
+  for drop-in compat with `check_brief_compliance` (v1.18.3).
+  Live interop test: Basic Channel × J Dilla hybrid correctly
+  flagged a Hi Gain boost via `check_brief_compliance`.
+
+31 unit tests added: packet loading (stem / alias / id /
+underscore-to-hyphen normalization / missing), input validation
+(min 2 packets / missing packet / weights length mismatch),
+UNION rules (avoid / sonic_identity / reach_for /
+dimensions_in_scope), INTERSECTION rules (deprioritized
+dimensions / `move_family_bias.deprioritize` /
+`move_family_bias.favor` non-empty case / UNION fallback with
+warning), WEIGHTED AVERAGE (default + custom weights), MAX rules
+(protect / novelty_budget), tempo_hint (overlap intersection /
+disjoint midpoint with warning), 3+ packet composition, output
+metadata (`type` / `source_packets` / hybrid name /
+`locked_dimensions=[]` / warnings list), and interoperability
+(hybrid brief passed through `check_brief_compliance`).
+
+### Live test coverage (13 scenarios)
+
+Item B: BC × Dilla (disjoint tempos) · BC × Villalobos
+(overlapping tempos, NO disjoint flag) · alias + spaced-name
+resolution · invalid packet error · 3-packet hybrid
+(BC + Dilla + Villalobos) · weighted average 75/25 · genre ×
+artist (ambient × basinski, tempo=0 case) · full hybrid brief
+→ `check_brief_compliance` interop (quantize_clip flagged).
+
+Item A: 3-branch experiment (all snapshots populated, ranking
+produced) · 5-branch experiment (1.04s/branch amortized
+overhead) · state preservation under 2 mutations on track 0
+(Dub Chord) across 5-branch cycle · `discard_experiment` cleanup.
+
+### Known gaps deferred to v1.19.1
+
+- `experiment.baseline_transport` populated internally but not
+  surfaced through `compare_experiments` response. 3-line fix
+  for operator visibility; not a correctness issue.
+- `warnings` message rounds tempo midpoint to int display (128
+  BPM) while range returned is exact (125-130, centered 127.5).
+  Two rounding conventions. Cosmetic.
+- `weights` in response show full float precision
+  (`0.3333333333333333`) instead of rounding to 4 dp like
+  `target_dimensions` already does. Cosmetic.
+
+### Still open for v1.20 (Item C from the plan)
+
+- Route director's Phase 6 execution through `apply_semantic_move`
+  / `create_experiment + commit_experiment` so the action ledger
+  populates automatically and anti-repetition becomes reliable.
+  Doc-level fix shipped in v1.18.1; architectural fix deferred
+  to v1.20 per plan §5 blast-radius rationale. Requires 5-10
+  new semantic_moves to cover current Phase 6 patterns
+  (return-chain builds, multi-param device presets, chord
+  source loading, send routing, etc.).
+
+Test suite: 2854 pass, 1 skipped (from 2792 pre-v1.19). Zero
+regressions. sync_metadata --check clean.
+
 ## 1.18.3 — Brief compliance runtime check (#7 + #8) (April 24 2026)
 
 Third v1.18.x patch. Bundles two Known Issues items (#7 + #8) that

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  428 tools. 53 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
+  429 tools. 53 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
 </p>
 
 <br>
@@ -80,7 +80,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   428 MCP Tools  │                                  │
+│                  │   429 MCP Tools  │                                  │
 │                  │   53 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
@@ -121,7 +121,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 428 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 429 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -173,7 +173,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-428 tools across 53 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+429 tools across 53 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -362,7 +362,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 428 tools →](docs/manual/tool-catalog.md)**
+> **[View all 429 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -589,7 +589,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 428 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 429 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/mcp_server/__init__.py

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

package/mcp_server/creative_director/hybrid.py

@@ -0,0 +1,438 @@
+"""Hybrid concept packet compilation (v1.19 Item B).
+
+When the user says "Basic Channel meets Dilla swing" or
+"Villalobos but sparse like Gas", the director needs to merge
+two (or more) concept packets into a single brief. Pre-v1.19
+this was LLM ad-hoc reasoning with no guarantees about
+contradiction handling.
+
+``compile_hybrid_brief(packet_ids, weights=None)`` loads the
+named packets from
+``livepilot/skills/livepilot-core/references/concepts/`` and
+merges them per the rules in
+``docs/plans/v1.19-structural-plan.md §3``.
+
+Design invariants:
+
+1. **UNION** the descriptive fields (sonic_identity, avoid,
+   reach_for.*, *_idioms) — hybrids describe the envelope of
+   BOTH sources, not the intersection.
+2. **INTERSECTION** the deprioritization fields
+   (dimensions_deprioritized, move_family_bias.deprioritize) —
+   a hybrid only deprioritizes something if BOTH sources agree
+   it should be deprioritized. Otherwise the other packet is
+   asking for it and the hybrid must honor that.
+3. **INTERSECTION (with UNION fallback + warning)** for
+   move_family_bias.favor — hybrids focus where both packets
+   agree when possible; when they don't overlap at all, fall
+   back to UNION but warn (the hybrid spans more families
+   than either source intends).
+4. **MAX** for stricter-wins fields (protect floors,
+   novelty_budget_default).
+5. **WEIGHTED AVERAGE** for continuous blends
+   (target_dimensions weights).
+6. **NEAREST-OVERLAP** for tempo_hint — intersect when ranges
+   overlap; warn and use midpoint when they don't.
+7. **Surface ambiguity** — all warnings go on the ``warnings``
+   list so the caller (director) can read them back to the
+   user.
+
+Output is a dict that is structurally compatible with
+:func:`mcp_server.creative_director.compliance.check_brief_compliance`:
+the merged ``avoid`` list is also exposed as ``anti_patterns``,
+and ``locked_dimensions`` defaults to ``[]`` (hybrids don't lock
+dimensions by default — that's a per-turn choice).
+"""
+
+from __future__ import annotations
+
+import logging
+import pathlib
+from typing import Iterable, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+# Resolve the concepts root relative to this file. Layout:
+#   mcp_server/creative_director/hybrid.py
+#   livepilot/skills/livepilot-core/references/concepts/
+# Three parents up from this file → repo root.
+_REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
+_CONCEPTS_ROOT = (
+    _REPO_ROOT / "livepilot" / "skills" / "livepilot-core"
+    / "references" / "concepts"
+)
+
+
+# ── Packet loader ────────────────────────────────────────────────────────────
+
+
+def _normalize(s: str) -> str:
+    """Lowercase, hyphenate whitespace and underscores for lookup."""
+    return s.strip().lower().replace("_", "-").replace(" ", "-")
+
+
+def load_packet(packet_id: str) -> Optional[dict]:
+    """Load a concept packet by filename stem, alias, or packet.id.
+
+    Resolution order (first hit wins):
+      1. Normalize the given id (lowercase, underscores → hyphens).
+      2. Try ``artists/<norm>.yaml`` then ``genres/<norm>.yaml``.
+      3. If still not found, scan all packets and match on ``id``
+         or any alias (normalized).
+      4. Return None on miss.
+    """
+    norm = _normalize(packet_id)
+
+    for subdir in ("artists", "genres"):
+        candidate = _CONCEPTS_ROOT / subdir / f"{norm}.yaml"
+        if candidate.exists():
+            try:
+                return yaml.safe_load(candidate.read_text())
+            except Exception as exc:
+                logger.debug("load_packet parse failed for %s: %s", candidate, exc)
+                return None
+
+    # Fallback: scan for alias / id match
+    for subdir in ("artists", "genres"):
+        subpath = _CONCEPTS_ROOT / subdir
+        if not subpath.is_dir():
+            continue
+        for p in sorted(subpath.glob("*.yaml")):
+            try:
+                d = yaml.safe_load(p.read_text())
+            except Exception as exc:
+                logger.debug("load_packet scan-parse failed for %s: %s", p, exc)
+                continue
+            if not isinstance(d, dict):
+                continue
+            if d.get("id") == packet_id:
+                return d
+            aliases = [_normalize(a) for a in (d.get("aliases") or []) if isinstance(a, str)]
+            if norm in aliases:
+                return d
+
+    return None
+
+
+# ── Merge helpers ────────────────────────────────────────────────────────────
+
+
+def _union_preserve_order(lists: Iterable[Iterable[str]]) -> list[str]:
+    seen: set = set()
+    out: list[str] = []
+    for lst in lists:
+        for item in (lst or []):
+            if item not in seen:
+                seen.add(item)
+                out.append(item)
+    return out
+
+
+def _intersection_preserve_order(
+    lists: list[list[str]], reference_order: list[str],
+) -> list[str]:
+    """Intersect across all lists; ordering follows ``reference_order``
+    (typically the first packet's list)."""
+    if not lists:
+        return []
+    sets = [set(lst or []) for lst in lists]
+    intersection = sets[0]
+    for s in sets[1:]:
+        intersection = intersection & s
+    return [item for item in (reference_order or []) if item in intersection]
+
+
+# ── Core compile function (packet-level, no disk I/O) ───────────────────────
+
+
+def _compile_from_packets(
+    packets: list[dict],
+    packet_ids: list[str],
+    weights: Optional[list[float]] = None,
+) -> dict:
+    """Compile a hybrid brief from already-loaded packet dicts.
+
+    Public callers should use :func:`compile_hybrid_brief`. This split
+    exists so tests can inject synthetic packets (e.g., to force an
+    empty favor-intersection and exercise the UNION fallback).
+    """
+    if len(packets) < 2:
+        raise ValueError("Hybrid requires at least 2 packets")
+    if weights is not None and len(weights) != len(packets):
+        raise ValueError(
+            f"weights length ({len(weights)}) must match packets "
+            f"length ({len(packets)})"
+        )
+
+    if weights is None:
+        weights = [1.0 / len(packets)] * len(packets)
+    else:
+        total = sum(weights) or 1.0
+        weights = [w / total for w in weights]
+
+    warnings: list[str] = []
+
+    # ── UNION fields ─────────────────────────────────────────────────────
+    sonic_identity = _union_preserve_order(
+        p.get("sonic_identity") or [] for p in packets
+    )
+    avoid = _union_preserve_order(p.get("avoid") or [] for p in packets)
+    rhythm_idioms = _union_preserve_order(p.get("rhythm_idioms") or [] for p in packets)
+    harmony_idioms = _union_preserve_order(p.get("harmony_idioms") or [] for p in packets)
+    arrangement_idioms = _union_preserve_order(
+        p.get("arrangement_idioms") or [] for p in packets
+    )
+    texture_idioms = _union_preserve_order(p.get("texture_idioms") or [] for p in packets)
+    sample_roles = _union_preserve_order(p.get("sample_roles") or [] for p in packets)
+    dimensions_in_scope = _union_preserve_order(
+        p.get("dimensions_in_scope") or [] for p in packets
+    )
+
+    reach_for = {
+        "instruments": _union_preserve_order(
+            (p.get("reach_for") or {}).get("instruments") or [] for p in packets
+        ),
+        "effects": _union_preserve_order(
+            (p.get("reach_for") or {}).get("effects") or [] for p in packets
+        ),
+        "packs": _union_preserve_order(
+            (p.get("reach_for") or {}).get("packs") or [] for p in packets
+        ),
+        "utilities": _union_preserve_order(
+            (p.get("reach_for") or {}).get("utilities") or [] for p in packets
+        ),
+    }
+
+    # ── INTERSECTION fields (safety defaults — be cautious) ─────────────
+    # deprioritize only if ALL packets agree → a hybrid with one packet
+    # asking for rhythmic must NOT deprioritize rhythmic just because the
+    # other packet's aesthetic does.
+    dimensions_deprioritized = _intersection_preserve_order(
+        [p.get("dimensions_deprioritized") or [] for p in packets],
+        packets[0].get("dimensions_deprioritized") or [],
+    )
+
+    deprioritize = _intersection_preserve_order(
+        [(p.get("move_family_bias") or {}).get("deprioritize") or []
+         for p in packets],
+        (packets[0].get("move_family_bias") or {}).get("deprioritize") or [],
+    )
+
+    # ── favor: INTERSECTION preferred, UNION fallback with warning ──────
+    favor_lists = [
+        (p.get("move_family_bias") or {}).get("favor") or [] for p in packets
+    ]
+    favor_intersection = _intersection_preserve_order(
+        favor_lists, favor_lists[0],
+    )
+    if favor_intersection:
+        favor = favor_intersection
+    else:
+        favor = _union_preserve_order(favor_lists)
+        warnings.append(
+            "move_family_bias.favor intersection was empty — falling back "
+            "to UNION. Hybrid plans may span more families than either "
+            "source packet intends; prioritize explicit user framing."
+        )
+
+    # ── Numeric rules ───────────────────────────────────────────────────
+    # target_dimensions: WEIGHTED AVERAGE
+    all_dim_keys: set = set()
+    for p in packets:
+        td = (p.get("evaluation_bias") or {}).get("target_dimensions") or {}
+        all_dim_keys.update(td.keys())
+    target_dimensions: dict[str, float] = {}
+    for dim in sorted(all_dim_keys):
+        accum = 0.0
+        for w, p in zip(weights, packets):
+            td = (p.get("evaluation_bias") or {}).get("target_dimensions") or {}
+            val = td.get(dim, 0.0)
+            try:
+                accum += float(w) * float(val)
+            except (TypeError, ValueError):
+                continue
+        if accum > 0:
+            target_dimensions[dim] = round(accum, 4)
+
+    # protect: MAX per dimension (stricter wins)
+    all_protect_keys: set = set()
+    for p in packets:
+        pr = (p.get("evaluation_bias") or {}).get("protect") or {}
+        all_protect_keys.update(pr.keys())
+    protect: dict[str, float] = {}
+    for dim in sorted(all_protect_keys):
+        values = []
+        for p in packets:
+            pr = (p.get("evaluation_bias") or {}).get("protect") or {}
+            val = pr.get(dim, 0.0)
+            try:
+                values.append(float(val))
+            except (TypeError, ValueError):
+                continue
+        if values:
+            protect[dim] = max(values)
+
+    # novelty_budget_default: MAX (hybrids lean exploratory)
+    novelty_values: list[float] = []
+    for p in packets:
+        nb = p.get("novelty_budget_default")
+        if nb is None:
+            continue
+        try:
+            novelty_values.append(float(nb))
+        except (TypeError, ValueError):
+            continue
+    novelty_budget = max(novelty_values) if novelty_values else 0.5
+
+    # ── tempo_hint: NEAREST-OVERLAP ─────────────────────────────────────
+    tempo_ranges: list[tuple[float, float, str]] = []
+    for p in packets:
+        th = p.get("tempo_hint") or {}
+        lo, hi = th.get("min"), th.get("max")
+        if lo is None or hi is None:
+            continue
+        try:
+            tempo_ranges.append((float(lo), float(hi), p.get("name", "")))
+        except (TypeError, ValueError):
+            continue
+
+    tempo_hint: Optional[dict]
+    if not tempo_ranges:
+        tempo_hint = None
+    elif len(tempo_ranges) == 1:
+        lo, hi, _ = tempo_ranges[0]
+        tempo_hint = {"min": lo, "max": hi, "time_signature": "4/4"}
+    else:
+        overlap_lo = max(r[0] for r in tempo_ranges)
+        overlap_hi = min(r[1] for r in tempo_ranges)
+        if overlap_lo <= overlap_hi:
+            tempo_hint = {
+                "min": overlap_lo, "max": overlap_hi,
+                "time_signature": "4/4",
+            }
+        else:
+            # Disjoint ranges — compute gap midpoint, surface warning.
+            # The gap is between the highest range-max and the lowest
+            # range-min that exceeds it. For 2 ranges this is
+            # (max of all his, min of all los). For 3+ ranges this still
+            # reads as "the gap in the middle of the sorted range set".
+            sorted_ranges = sorted(tempo_ranges, key=lambda r: r[0])
+            gap_lo = max(r[1] for r in sorted_ranges if r[0] < sorted_ranges[-1][0])
+            gap_hi = sorted_ranges[-1][0]
+            midpoint = (gap_lo + gap_hi) / 2.0
+            tempo_hint = {
+                "min": midpoint - 2.5,
+                "max": midpoint + 2.5,
+                "time_signature": "4/4",
+                "disjoint": True,
+            }
+            range_desc = "; ".join(
+                f"{name or 'packet'} {lo:.0f}-{hi:.0f}"
+                for lo, hi, name in tempo_ranges
+            )
+            # v1.19.1 #2 — :g format keeps warning midpoint consistent with
+            # the returned range center. Pre-v1.19.1 used :.0f (int-rounded)
+            # so BC+Dilla reported 'midpoint 108 BPM' while range was
+            # 105-110 centered on 107.5 — two rounding conventions.
+            # :g gives the shortest accurate representation: 107.5 stays
+            # "107.5", 128.0 becomes "128".
+            warnings.append(
+                f"Tempo ranges don't overlap ({range_desc}) — defaulting "
+                f"to midpoint {midpoint:g} BPM. Specify which anchor "
+                f"you want or pick a single packet."
+            )
+
+    # ── Output ───────────────────────────────────────────────────────────
+    names = [p.get("name") or pid for p, pid in zip(packets, packet_ids)]
+    hybrid_name = " × ".join(names)
+
+    return {
+        "type": "hybrid",
+        "source_packets": list(packet_ids),
+        # v1.19.1 #3 — round weights to 4 dp for clean display, matching the
+        # convention target_dimensions already uses. Pre-v1.19.1 uniform
+        # 3-packet weights rendered as 0.3333333333333333 — noisy output.
+        "weights": [round(w, 4) for w in weights],
+        "name": hybrid_name,
+        "sonic_identity": sonic_identity,
+        "reach_for": reach_for,
+        "avoid": avoid,
+        # Alias for compatibility with check_brief_compliance, which reads
+        # "anti_patterns". The semantics are identical — "avoid" at the
+        # packet layer, "anti_patterns" at the brief layer.
+        "anti_patterns": list(avoid),
+        "rhythm_idioms": rhythm_idioms,
+        "harmony_idioms": harmony_idioms,
+        "arrangement_idioms": arrangement_idioms,
+        "texture_idioms": texture_idioms,
+        "sample_roles": sample_roles,
+        "evaluation_bias": {
+            "target_dimensions": target_dimensions,
+            "protect": protect,
+        },
+        "move_family_bias": {
+            "favor": favor,
+            "deprioritize": deprioritize,
+        },
+        "dimensions_in_scope": dimensions_in_scope,
+        "dimensions_deprioritized": dimensions_deprioritized,
+        # Hybrids do not lock dimensions by default — locking is a per-turn
+        # user choice (e.g., "don't touch structure"). Included here for
+        # compat with check_brief_compliance which reads this field.
+        "locked_dimensions": [],
+        "novelty_budget_default": novelty_budget,
+        "tempo_hint": tempo_hint,
+        "warnings": warnings,
+    }
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+
+def compile_hybrid_brief(
+    packet_ids: list[str],
+    weights: Optional[list[float]] = None,
+) -> dict:
+    """Merge N concept packets into a single hybrid brief.
+
+    packet_ids: filename stems (``'basic-channel'``), aliases
+      (``'dilla'``), or packet ``id`` values (``'dub_techno__basic_channel'``).
+      At least 2 required.
+    weights: optional per-packet weighting for the target_dimensions
+      weighted-average step. If None, uniform weights are used.
+      Must match ``packet_ids`` length when provided. Normalized to
+      sum to 1.0 internally.
+
+    Raises:
+      ValueError: on fewer than 2 packets, an unresolvable packet id,
+        or a weights-length mismatch.
+
+    Returns:
+      A dict structurally compatible with the packet schema plus:
+        - ``type``: always ``"hybrid"``
+        - ``source_packets``: ``packet_ids`` echoed back
+        - ``weights``: normalized weights
+        - ``name``: ``"Packet A × Packet B"`` for user-facing display
+        - ``anti_patterns``: alias of ``avoid`` (compat with
+          ``check_brief_compliance``)
+        - ``locked_dimensions``: empty by default (hybrids don't lock)
+        - ``warnings``: list of human-readable ambiguity notes (tempo
+          disjunction, empty favor intersection fallback, etc.). Empty
+          when all merge rules resolved cleanly.
+    """
+    packets: list[dict] = []
+    missing: list[str] = []
+    for pid in packet_ids:
+        p = load_packet(pid)
+        if p is None:
+            missing.append(pid)
+        else:
+            packets.append(p)
+
+    if missing:
+        raise ValueError(f"Packets not found: {missing}")
+
+    return _compile_from_packets(packets, list(packet_ids), weights=weights)

package/mcp_server/creative_director/tools.py

@@ -18,6 +18,7 @@ from fastmcp import Context
 
 from ..server import mcp
 from .compliance import check_brief_compliance as _check_brief_compliance
+from .hybrid import compile_hybrid_brief as _compile_hybrid_brief
 
 
 @mcp.tool()
@@ -70,3 +71,65 @@ def check_brief_compliance(
         tool_args=tool_args or {},
     )
     return result
+
+
+@mcp.tool()
+def compile_hybrid_brief(
+    ctx: Context,
+    packet_ids: list,
+    weights: Optional[list] = None,
+) -> dict:
+    """Merge 2+ concept packets into a single hybrid brief (v1.19 Item B).
+
+    When the user says "Basic Channel meets Dilla swing" or
+    "Villalobos but sparse like Gas", the director needs an explicit
+    merge algorithm — not LLM ad-hoc reasoning. This tool loads the
+    named concept packets from
+    ``livepilot/skills/livepilot-core/references/concepts/`` and merges
+    them per the rules in
+    ``livepilot/skills/livepilot-creative-director/references/hybrid-compilation.md``.
+
+    Merge rule summary:
+      - ``sonic_identity`` / ``avoid`` / ``reach_for.*`` / ``*_idioms``:
+        UNION, deduplicated, first-packet order preserved.
+      - ``dimensions_deprioritized`` and
+        ``move_family_bias.deprioritize``: INTERSECTION — only
+        deprioritize if ALL source packets do. Safer default for
+        hybrids where one packet may want what the other ignores.
+      - ``move_family_bias.favor``: INTERSECTION when non-empty
+        (hybrid focuses where both agree); UNION fallback otherwise
+        with a warning.
+      - ``evaluation_bias.target_dimensions``: WEIGHTED AVERAGE
+        (default uniform weights).
+      - ``evaluation_bias.protect``: MAX per dimension — stricter
+        floor wins.
+      - ``novelty_budget_default``: MAX (hybrids skew exploratory).
+      - ``tempo_hint``: NEAREST-OVERLAP — intersect overlapping
+        ranges, or warn + midpoint on disjoint ranges.
+
+    Args:
+      packet_ids: list of ≥2 packet IDs. Accepts filename stems
+        (``"basic-channel"``), aliases (``"dilla"``), or packet ``id``
+        values (``"dub_techno__basic_channel"``).
+      weights: optional per-packet weights for the
+        ``target_dimensions`` average. Must match ``packet_ids``
+        length. Normalized internally; defaults to uniform.
+
+    Returns:
+      A brief dict structurally compatible with
+      ``check_brief_compliance``. Exposes the merged ``avoid`` list
+      both as ``avoid`` (packet semantic) and ``anti_patterns``
+      (brief semantic). Includes a ``warnings`` list surfacing any
+      ambiguity the merge algorithm couldn't resolve cleanly.
+
+    Raises:
+      ValueError (surfaced as an error-dict response) on fewer than
+      2 packets, an unresolvable packet id, or a weights-length
+      mismatch.
+    """
+    try:
+        pid_list = [str(x) for x in (packet_ids or [])]
+        w_list = [float(x) for x in weights] if weights else None
+        return _compile_hybrid_brief(packet_ids=pid_list, weights=w_list)
+    except ValueError as exc:
+        return {"error": str(exc)}

package/mcp_server/experiment/baseline.py

@@ -0,0 +1,138 @@
+"""Experiment baseline transport state — capture once, restore between branches.
+
+v1.19 Item A: running N branches sequentially produces inconsistent
+``before_snapshot`` values because playback position, mute/solo/arm, and
+playing-clip state drift across branches. ``undo()`` reverts command
+history but doesn't guarantee transport state is identical at the start
+of each branch's capture window.
+
+Flow in ``run_experiment``:
+
+1. Before the first branch: ``capture_baseline(ableton)`` and stash on
+   the :class:`ExperimentSet`.
+2. Between branches (before capturing the next before_snapshot): call
+   ``restore_baseline(ableton, baseline)`` to stop transport, reset
+   mute/solo/arm, and pause briefly for meters to settle.
+
+The module is deliberately thin — no LOM subscription, no state
+monitoring. Just a snapshot dataclass + two functions.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BaselineTransportState:
+    """Transport + per-track state captured before the first experiment branch.
+
+    Kept deliberately shallow: we don't try to freeze automation or scene
+    state. Those are out of scope (plan §2 "What NOT to do" — automation
+    drift is an accepted limitation).
+    """
+
+    is_playing: bool = False
+    song_time: float = 0.0
+    track_states: list[dict] = field(default_factory=list)
+    captured_at_ms: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "is_playing": self.is_playing,
+            "song_time": self.song_time,
+            "track_states": list(self.track_states),
+            "captured_at_ms": self.captured_at_ms,
+        }
+
+
+def capture_baseline(ableton) -> BaselineTransportState:
+    """Capture current transport + per-track state.
+
+    Uses ``get_session_info`` (single round-trip for all fields we need).
+    Returns a frozen-in-time snapshot; subsequent state drift doesn't
+    affect it.
+    """
+    info = ableton.send_command("get_session_info")
+    if not isinstance(info, dict):
+        info = {}
+
+    tracks = info.get("tracks") or []
+    track_states: list[dict] = []
+    for i, t in enumerate(tracks):
+        if not isinstance(t, dict):
+            continue
+        track_states.append({
+            "index": int(t.get("index", i)),
+            "mute": bool(t.get("mute", False)),
+            "solo": bool(t.get("solo", False)),
+            "arm": bool(t.get("arm", False)),
+        })
+
+    return BaselineTransportState(
+        is_playing=bool(info.get("is_playing", False)),
+        song_time=float(info.get("current_song_time", 0.0) or 0.0),
+        track_states=track_states,
+        captured_at_ms=int(time.time() * 1000),
+    )
+
+
+def restore_baseline(
+    ableton,
+    baseline: BaselineTransportState,
+    stabilize_ms: int = 300,
+) -> None:
+    """Restore transport + per-track state to the captured baseline.
+
+    Sequence:
+      1. ``stop_playback`` (halt transport — also stops any live clips)
+      2. For each track: ``set_track_mute`` / ``set_track_solo`` /
+         ``set_track_arm`` (best-effort; per-track failure is logged,
+         not fatal — a single flaky track should never abort restore
+         for the rest).
+      3. Sleep ``stabilize_ms`` milliseconds so meters settle before the
+         next ``before_snapshot`` reads them. Pass ``0`` in tests.
+
+    We deliberately do NOT seek the transport to ``baseline.song_time``.
+    Returning from stopped transport is enough — re-seeking a stopped
+    transport is equivalent to not moving, and on a playing transport it
+    introduces its own stutter artefact. If a future branch needs timeline
+    position consistency, add a ``jump_to_time`` call here.
+
+    Return-track arms are skipped — ``set_track_arm`` on a negative index
+    raises (return tracks aren't armable in Live).
+    """
+    try:
+        ableton.send_command("stop_playback")
+    except Exception as exc:
+        logger.debug("restore_baseline stop_playback failed: %s", exc)
+
+    for ts in baseline.track_states:
+        idx = ts.get("index", -1)
+        try:
+            ableton.send_command("set_track_mute", {
+                "track_index": idx, "mute": bool(ts.get("mute", False)),
+            })
+        except Exception as exc:
+            logger.debug("restore_baseline set_track_mute(%s) failed: %s", idx, exc)
+        try:
+            ableton.send_command("set_track_solo", {
+                "track_index": idx, "solo": bool(ts.get("solo", False)),
+            })
+        except Exception as exc:
+            logger.debug("restore_baseline set_track_solo(%s) failed: %s", idx, exc)
+        if idx >= 0:
+            try:
+                ableton.send_command("set_track_arm", {
+                    "track_index": idx, "arm": bool(ts.get("arm", False)),
+                })
+            except Exception as exc:
+                logger.debug("restore_baseline set_track_arm(%s) failed: %s", idx, exc)
+
+    if stabilize_ms > 0:
+        time.sleep(stabilize_ms / 1000.0)

package/mcp_server/experiment/engine.py

@@ -445,3 +445,23 @@ def discard_experiment(experiment_id: str) -> dict:
     exp.status = "discarded"
 
     return {"discarded": True, "experiment_id": experiment_id}
+
+
+# ── v1.19 Item A — between-branch baseline restore ───────────────────────────
+
+
+def prepare_for_next_branch(ableton, baseline, stabilize_ms: int = 300) -> None:
+    """Restore baseline transport state before capturing the next branch.
+
+    Called by ``run_experiment`` between branches so each branch's
+    ``before_snapshot`` reads from identical starting conditions. No-op
+    when ``baseline`` is None (first branch — the baseline was just
+    captured, no drift to correct).
+
+    Thin wrapper around ``baseline.restore_baseline``; exists so the
+    MCP tool body stays small and the wiring is testable in isolation.
+    """
+    if baseline is None:
+        return
+    from .baseline import restore_baseline
+    restore_baseline(ableton, baseline, stabilize_ms=stabilize_ms)

package/mcp_server/experiment/models.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass, field
 from typing import Any, Optional
 
 from ..branches import BranchSeed
+from .baseline import BaselineTransportState
 
 
 @dataclass
@@ -249,6 +250,10 @@ class ExperimentSet:
     status: str = "open"  # open | evaluated | committed | discarded
     winner_branch_id: Optional[str] = None
     created_at_ms: int = 0
+    # v1.19 Item A — transport state captured before the first branch runs
+    # and used to restore identical starting conditions between branches.
+    # See mcp_server.experiment.baseline for the snapshot / restore pair.
+    baseline_transport: Optional[BaselineTransportState] = None
 
     @property
     def branch_count(self) -> int:
@@ -290,7 +295,7 @@ class ExperimentSet:
         return _branch_rank_key(branch)
 
     def to_dict(self) -> dict:
-        return {
+        d = {
             "experiment_id": self.experiment_id,
             "request_text": self.request_text,
             "status": self.status,
@@ -302,3 +307,6 @@ class ExperimentSet:
                 for b in self.ranked_branches()
             ],
         }
+        if self.baseline_transport is not None:
+            d["baseline_transport"] = self.baseline_transport.to_dict()
+        return d

package/mcp_server/experiment/tools.py

@@ -343,11 +343,33 @@ async def run_experiment(
     # Import compiler
     from ..semantic_moves import registry, compiler
 
+    # v1.19 Item A — capture baseline transport state BEFORE any branch runs.
+    # Each branch's before_snapshot is only comparable if it starts from the
+    # same reference state. Without this, live testing (v1.18.0 Test 8) showed
+    # 3 branches produce wildly inconsistent before_snapshot.track_meters[0].level
+    # values — clip stopped mid-experiment between branches.
+    if experiment.baseline_transport is None:
+        from .baseline import capture_baseline
+        try:
+            experiment.baseline_transport = capture_baseline(ableton)
+        except Exception as exc:
+            logger.debug("baseline capture failed: %s", exc)
+            experiment.baseline_transport = None
+
     results = []
+    pending_seen = 0
     for branch in experiment.branches:
         if branch.status != "pending":
             continue
 
+        # Between branches (not before the first), restore the baseline so
+        # the next before_snapshot reads from the same reference state.
+        if pending_seen > 0:
+            engine.prepare_for_next_branch(
+                ableton, experiment.baseline_transport, stabilize_ms=300,
+            )
+        pending_seen += 1
+
         # PR3: respect a pre-existing compiled_plan on the branch (freeform /
         # synthesis / composer producers bring their own). Only compile from
         # move_id when the branch arrived without a plan — which requires a
@@ -579,10 +601,21 @@ def compare_experiments(
             "evaluation": b.evaluation,
         }
 
+    # v1.19.1 #1 — surface baseline_transport for operator observability.
+    # Always present in the response (None when not captured) so clients
+    # can `result["baseline_transport"] is None` instead of checking for
+    # key presence first. Populated during run_experiment's first pass.
+    baseline_dict = (
+        experiment.baseline_transport.to_dict()
+        if experiment.baseline_transport is not None
+        else None
+    )
+
     return {
         "experiment_id": experiment_id,
         "request": experiment.request_text,
         "branch_count": experiment.branch_count,
+        "baseline_transport": baseline_dict,
         "ranking": [
             {
                 "rank": i + 1,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.18.3",
+  "version": "1.19.1",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 428 tools, 53 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
+  "description": "Agentic production system for Ableton Live 12 — 429 tools, 53 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 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.18.3"
+__version__ = "1.19.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": "428-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
+  "description": "429-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
   "repository": {
     "url": "https://github.com/dreamrec/LivePilot",
     "source": "github"
   },
-  "version": "1.18.3",
+  "version": "1.19.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.18.3",
+      "version": "1.19.1",
       "transport": {
         "type": "stdio"
       }