livepilot 1.13.0 → 1.14.1

package/CHANGELOG.md

@@ -1,5 +1,200 @@
 # Changelog
 
+## 1.14.1 — reload_handlers workflow + device/mixing fixes (April 21 2026)
+
+Patch release that lands the post-1.14.0 audit work: one new diagnostics
+tool, three bug fixes, and a new plugin-sync verification script.
+
+**Tool count**: 402 → **403** (added `reload_handlers`).
+**Domain count**: unchanged at 52.
+**Tests**: 2467 → **2485 passing** (+18 new), 0 regressions.
+
+### New tool: `reload_handlers`
+
+- Replaces the manual "toggle Control Surface in Live → Preferences →
+  Link/MIDI" step that every Remote Script edit required. New workflow:
+  after `node installer/install.js`, call `reload_handlers` via the MCP
+  tool. The Remote Script side uses `pkgutil` + `importlib.reload()` to
+  re-fire all `@register` decorators in place in <1s, without dropping
+  the MCP TCP connection on port 9878.
+- Ships with a pkgutil-based module-discovery helper in
+  `remote_script/LivePilot/__init__.py`, so new handler modules added to
+  `remote_script/LivePilot/` are picked up automatically on reload.
+- Exception: the very first bootstrap (no prior `LivePilot.*` in
+  `sys.modules`) still needs one full Ableton restart. After that,
+  `reload_handlers` works forever.
+- Domain: `diagnostics`. Added to `docs/manual/tool-catalog.md` to keep
+  the CI skill-contract test green.
+
+### Bug fixes
+
+- **`find_and_load_device` duplicate loads** — the tool was no-oping
+  only on exact name match; changed to also treat cases where the
+  target device is already the tail of the chain as a no-op. Prevents
+  the "load Simpler, load Simpler, load Simpler" cascade when the MCP
+  server retries a loader.
+- **`get_device_parameters` "Invalid display value"** — certain Live
+  parameters (especially plugin wrappers on AU/VST) raise
+  `RuntimeError("Invalid display value")` when their
+  `str_for_value()` is queried before the parameter has settled. The
+  handler now swallows that specific error and returns the raw float
+  instead of 500-ing the whole request.
+- **Sidechain LOM reopen (BUG-A3 redux)** — Compressor2 moved its
+  sidechain block into a nested property in a recent Live update, so
+  `compressor_set_sidechain` lost the ability to toggle. The handler
+  now probes the LOM surface at tool-call time and falls back to the
+  flat path when the nested one isn't exposed.
+- **Mixing `channel` lazy-get** — channel objects were resolved eagerly
+  at import time, breaking in edge cases where the Song came up before
+  the mixer. Now resolved on first use.
+
+### New: plugin-sync verification
+
+- `scripts/verify_plugin_sync.py` — catches the v1.14.0 regression
+  class where `.mcp.json` went missing from
+  `~/.claude/plugins/cache/dreamrec-LivePilot/livepilot/$VERSION/`. All
+  four sync targets (active plugin dir, cache version dir, marketplace
+  snapshot, `installed_plugins.json`) are now verified by one command.
+
+---
+
+## 1.14.0 — Branch-native v2: producer context, synth intelligence, render verify (April 20 2026)
+
+Five-PR follow-up to v1.13.0 that closes the loops the first pass left
+open. Producer context flows through the branch lifecycle via a versioned
+`producer_payload`; synthesis adapters decode algorithm topology instead
+of always targeting the same operator; composer winners commit the full
+resolved plan instead of the audition scaffold; render-verify captures
+audio before/after each branch and feeds spectral movement into the
+hard-rule classifier; and four dedicated MCP tools expose the new
+producers to the LLM.
+
+**Tool count**: 398 → **402** (added `analyze_synth_patch`,
+`propose_synth_branches`, `extract_timbre_fingerprint`,
+`propose_composer_branches`). **Domain count**: unchanged at 52.
+**Tests**: 2409 → **2467 passing** (+58 new), 0 regressions.
+
+### New substrate
+
+- **`producer_payload: dict` on `BranchSeed`** (PR1) — versioned
+  opaque dict producers populate with regeneration / provenance /
+  winner-escalation context. Always carries `schema_version` (default 1)
+  so older payloads don't break newer readers. Lives on the seed, not
+  `compiled_plan`, so analytical-only branches can carry context too.
+  Canonical shapes documented per producer (synthesis / composer /
+  semantic_move / freeform / technique).
+
+- **`BranchSnapshot` gains render-based fields** (PR4) —
+  `capture_path`, `loudness`, `spectral_shape`, `fingerprint`. Populated
+  only when `run_experiment(render_verify=True)` opts in. Pre-v2
+  consumers see no shape change when render-verify is off.
+
+### Synthesis adapters get topology awareness (PR2)
+
+- **Wavetable**: position→region classification (sub / mid / bright /
+  complex) drives shift direction. Target brightness biases the chosen
+  target region — not just freshness scaling.
+
+- **Operator**: static `_ALGO_TOPOLOGY` table maps all 11 algorithms
+  to their carrier/modulator roles. Targeting picks the modulator with
+  the highest Level for the ratio shift; additive algorithms (5, 9)
+  fall back to the dominant carrier. No more "always Osc B".
+
+- **Analog / Drift / Meld**: single fixed proposers become strategy
+  registries. Gates honor `role_hint` ("bass" skips `detune_warmth`,
+  "pad" skips `filter_pluck`, silent engines skip `engine_mix_shift`)
+  and target fingerprint dimensions (`target.brightness` picks
+  `filter_sweep_open` vs `filter_sweep_close`).
+
+### Composer winner escalation (PR3)
+
+- Composer seeds now carry their `CompositionIntent` in
+  `producer_payload` at emit time. On `commit_experiment`,
+  `escalate_composer_branch` rehydrates the intent and runs the full
+  `ComposerEngine.compose()` pipeline — Splice / filesystem / browser
+  sample resolution — then swaps the scaffold plan for the resolved one
+  BEFORE `commit_branch_async` runs it through the async router. The
+  scaffold is preserved on `branch.evaluation` for audit.
+
+- Graceful fallback when compose yields zero executable layers:
+  commit runs the scaffold instead of erroring. User gets tracks +
+  scenes they can populate manually, with `composer_escalation.error`
+  explaining why escalation couldn't complete.
+
+- **Latency note**: composer winner commit now takes 10-30s (Splice +
+  filesystem resolution) vs ~0.5s pre-v2. Documented; a progress
+  callback version is future work.
+
+### Render-verify + classifier wiring (PR4)
+
+- `run_experiment(render_verify=False, render_duration_seconds=2.0)` —
+  opt-in per-branch audio capture → offline loudness + spectrum
+  analysis → `TimbralFingerprint` extraction. ~2 * duration seconds +
+  ~1-2s analysis overhead per branch; default off preserves speed.
+
+- New `derive_goal_progress_from_fingerprint(diff, target?)` turns
+  TimbralFingerprint diffs into `(goal_progress, measurable_count)`.
+  Dimensions below 0.02 epsilon are dropped as noise. With a target:
+  sign(target) * diff gives signed progress. Without: magnitude-only
+  contribution (branch moved = measurable).
+
+- `classify_branch_outcome` accepts `fingerprint_diff` + `timbral_target`
+  kwargs. When set and caller didn't supply their own measurable inputs,
+  the classifier derives them from the diff. Caller-supplied values
+  still take precedence (back-compat). Protection violations still
+  trump fingerprint evidence — safety invariant preserved.
+
+- `compare_experiments` automatically surfaces `fingerprint_diff` +
+  `fingerprint_before` + `fingerprint_after` on each branch's
+  `evaluation` dict via the existing pass-through.
+
+### Four new MCP tools (PR5, 398 → 402)
+
+- **`analyze_synth_patch(track_index, device_index, role_hint="")`** —
+  SynthProfile for any supported native synth. Fetches parameter state
+  + display values, hands to the adapter. Opaque fallback for
+  non-supported devices.
+
+- **`propose_synth_branches(track_index, device_index, target?,
+  freshness?, role_hint?)`** — algorithm/topology-aware branch seeds
+  with pre-compiled plans. Feeds directly to
+  `create_experiment(seeds=..., compiled_plans=...)`.
+
+- **`extract_timbre_fingerprint(spectrum?, loudness?, spectral_shape?)`**
+  — pure transform from analysis dicts to 9-dimensional
+  `TimbralFingerprint`. For callers that already have analysis data.
+
+- **`propose_composer_branches(request_text, count=2, freshness=0.65)`**
+  — N compositional hypotheses (canonical / energy_shift /
+  layer_contrast) with producer_payload-captured intents for
+  winner-commit escalation.
+
+### Migration notes for callers
+
+- All additions are optional-param / new-function shaped. Pre-v2
+  callers see no behavior change unless they opt in.
+- Pre-v2 serialized branches deserialize fine: `producer_payload`
+  defaults to `{"schema_version": 1}` when absent.
+- `create_experiment(move_ids=...)` identical behavior.
+- `enter_wonder_mode` response shape stable; `branch_seeds` /
+  `compiled_plans_by_seed_id` still additive.
+- `run_experiment(render_verify=False)` default matches v1.13.0
+  behavior exactly.
+
+### Known limitations
+
+See [`docs/manual/branch-native-migration.md`](docs/manual/branch-native-migration.md#known-limitations)
+for the full list. Headlines:
+
+- Wavetable region classification is a coarse heuristic on raw
+  `Osc 1 Pos`. Future work: render-based per-wavetable mapping.
+- Composer commit latency (10-30s) with no progress callback yet.
+- Render-verify requires the M4L analyzer bridge + LivePilot_Analyzer
+  on master; silently degrades to fast-path when either is missing.
+- End-to-end render-verify path (capture_audio + bridge) is hardware-
+  dependent and not unit-tested; wiring is covered via classifier +
+  fingerprint derivation tests.
+
 ## 1.13.0 — Branch-native architecture (April 20 2026)
 
 Twelve-PR migration from "match request → pick move → compile move" to

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  398 tools. 52 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
+  403 tools. 52 domains. Device atlas. Splice integration. Auto-composition. Spectral perception. Technique memory.
 </p>
 
 <br>
@@ -79,7 +79,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   398 MCP Tools  │                                  │
+│                  │   403 MCP Tools  │                                  │
 │                  │   52 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
@@ -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 398 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 403 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -172,7 +172,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-398 tools across 52 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+403 tools across 52 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -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 398 tools →](docs/manual/tool-catalog.md)**
+> **[View all 403 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 398 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 403 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.13.0"});
+            send_response({"ok": true, "version": "1.14.1"});
             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.13.0"
+__version__ = "1.14.1"

package/mcp_server/branches/__init__.py

@@ -15,6 +15,7 @@ from .types import (
     BranchSource,
     RiskLabel,
     NoveltyLabel,
+    PRODUCER_PAYLOAD_SCHEMA_VERSION,
     seed_from_move_id,
     freeform_seed,
     analytical_seed,
@@ -26,6 +27,7 @@ __all__ = [
     "BranchSource",
     "RiskLabel",
     "NoveltyLabel",
+    "PRODUCER_PAYLOAD_SCHEMA_VERSION",
     "seed_from_move_id",
     "freeform_seed",
     "analytical_seed",

package/mcp_server/branches/types.py

@@ -38,6 +38,9 @@ RiskLabel = Literal["low", "medium", "high"]
 NoveltyLabel = Literal["safe", "strong", "unexpected"]
 
 
+PRODUCER_PAYLOAD_SCHEMA_VERSION = 1
+
+
 @dataclass
 class BranchSeed:
     """Pre-compilation creative intent.
@@ -52,10 +55,32 @@ class BranchSeed:
       hypothesis: one-line human-readable prediction of what the branch does.
       protected_qualities: dimension names the producer promises not to regress.
       affected_scope: {track_indices, device_paths, section_ids, clip_slots}.
+        Session-scope information: which tracks/devices/sections the branch
+        affects. Distinct from ``producer_payload`` which carries regeneration
+        context.
       distinctness_reason: why this seed is different from siblings in a set.
       risk_label: execution safety tier.
       novelty_label: creative novelty tier — maps to the safe/strong/unexpected UX triptych.
       analytical_only: true ⇒ no plan will be compiled; branch is directional only.
+      producer_payload: free-form dict the emitting producer populates with
+        whatever it needs for regeneration / provenance / winner escalation.
+        Consumers must check ``schema_version`` (defaults to 1) before reading
+        specific keys so older serialized branches don't break newer readers.
+
+        Canonical shapes per producer:
+          semantic_move: {schema_version: 1}  (empty — move_id is the key)
+          freeform / technique: {schema_version: 1}  (optional)
+          synthesis:
+            {schema_version: 1,
+             device_name: "Wavetable",
+             track_index: int, device_index: int,
+             strategy: "osc_position_shift" | "voice_width_variant" | ...,
+             topology_hint: {...}}  (used by PR4 render-verify to re-target)
+          composer:
+            {schema_version: 1,
+             strategy: "canonical" | "energy_shift" | "layer_contrast",
+             intent: {<CompositionIntent.to_dict()>}}  (used by PR3 to
+             rehydrate for winner-commit escalation)
     """
 
     seed_id: str
@@ -68,9 +93,20 @@ class BranchSeed:
     risk_label: RiskLabel = "low"
     novelty_label: NoveltyLabel = "strong"
     analytical_only: bool = False
+    producer_payload: dict = field(
+        default_factory=lambda: {"schema_version": PRODUCER_PAYLOAD_SCHEMA_VERSION}
+    )
 
     def to_dict(self) -> dict:
-        return asdict(self)
+        d = asdict(self)
+        # Guarantee schema_version in the payload even if the dict was
+        # mutated to empty by a caller.
+        payload = d.get("producer_payload") or {}
+        if "schema_version" not in payload:
+            payload = dict(payload)
+            payload["schema_version"] = PRODUCER_PAYLOAD_SCHEMA_VERSION
+            d["producer_payload"] = payload
+        return d
 
 
 @dataclass
@@ -158,6 +194,7 @@ def seed_from_move_id(
     risk_label: RiskLabel = "low",
     protected_qualities: Optional[list[str]] = None,
     distinctness_reason: str = "",
+    producer_payload: Optional[dict] = None,
 ) -> BranchSeed:
     """Build a semantic_move seed — the baseline producer path.
 
@@ -176,6 +213,7 @@ def seed_from_move_id(
         risk_label=risk_label,
         protected_qualities=protected_qualities or [],
         distinctness_reason=distinctness_reason,
+        producer_payload=_normalize_payload(producer_payload),
     )
 
 
@@ -188,6 +226,7 @@ def freeform_seed(
     novelty_label: NoveltyLabel = "strong",
     risk_label: RiskLabel = "medium",
     source: BranchSource = "freeform",
+    producer_payload: Optional[dict] = None,
 ) -> BranchSeed:
     """Build a freeform seed — producer has a concrete hypothesis without a move.
 
@@ -204,6 +243,7 @@ def freeform_seed(
         distinctness_reason=distinctness_reason,
         novelty_label=novelty_label,
         risk_label=risk_label,
+        producer_payload=_normalize_payload(producer_payload),
     )
 
 
@@ -212,6 +252,7 @@ def analytical_seed(
     hypothesis: str,
     source: BranchSource = "freeform",
     protected_qualities: Optional[list[str]] = None,
+    producer_payload: Optional[dict] = None,
 ) -> BranchSeed:
     """Build an analytical-only seed — no plan will be compiled.
 
@@ -227,4 +268,19 @@ def analytical_seed(
         hypothesis=hypothesis,
         protected_qualities=protected_qualities or [],
         analytical_only=True,
+        producer_payload=_normalize_payload(producer_payload),
     )
+
+
+def _normalize_payload(payload: Optional[dict]) -> dict:
+    """Ensure a producer_payload always has schema_version set.
+
+    Producers that don't care about versioning pass None / empty dict and
+    get the default schema_version=PRODUCER_PAYLOAD_SCHEMA_VERSION back.
+    Producers that carry their own version number have it preserved.
+    """
+    if not payload:
+        return {"schema_version": PRODUCER_PAYLOAD_SCHEMA_VERSION}
+    out = dict(payload)
+    out.setdefault("schema_version", PRODUCER_PAYLOAD_SCHEMA_VERSION)
+    return out

package/mcp_server/composer/__init__.py

@@ -5,6 +5,6 @@ multiple section-hypothesis BranchSeeds alongside the existing
 single-plan compose() entry point.
 """
 
-from .branch_producer import propose_composer_branches
+from .branch_producer import propose_composer_branches, escalate_composer_branch
 
-__all__ = ["propose_composer_branches"]
+__all__ = ["propose_composer_branches", "escalate_composer_branch"]

package/mcp_server/composer/branch_producer.py

@@ -29,6 +29,7 @@ from typing import Optional
 from ..branches import BranchSeed, freeform_seed
 from .prompt_parser import parse_prompt, CompositionIntent
 from .layer_planner import plan_layers, plan_sections
+from .engine import ComposerEngine, CompositionResult
 
 
 # Strategy registry — each function takes an intent and returns (modified
@@ -146,6 +147,15 @@ def propose_composer_branches(
                 novelty_label=novelty,
                 risk_label=risk,
                 distinctness_reason=reason,
+                # PR3 — carry the variant intent + strategy so commit_experiment
+                # can rehydrate and run the full ComposerEngine.compose()
+                # pipeline on the winner instead of committing the scaffold.
+                producer_payload={
+                    "strategy": name,
+                    "intent": variant_intent.to_dict(),
+                    "request_text": request_text,
+                    "reason": reason,
+                },
             )
             results.append((seed, plan))
         except Exception as exc:
@@ -159,6 +169,116 @@ def propose_composer_branches(
     return results
 
 
+async def escalate_composer_branch(
+    producer_payload: dict,
+    search_roots: Optional[list] = None,
+    splice_client: object = None,
+    browser_client: object = None,
+    max_credits: int = 10,
+) -> dict:
+    """Run the full ComposerEngine.compose() pipeline on a committed
+    composer branch, using the CompositionIntent captured in the seed's
+    producer_payload at emit time.
+
+    Returns a dict with:
+      ok: bool
+      plan: list of executable steps (the full resolved plan, not the
+            scaffolding the branch was auditioned with)
+      step_count: int
+      layer_count: int
+      resolved_samples: dict (role → local_path)
+      warnings: list (unresolved layers, missing samples, etc.)
+      error: str (when ok=False)
+
+    When ok=False, callers should fall back to committing the scaffold
+    plan instead of dropping the branch — the scaffolding is still
+    useful as a track/scene skeleton the user can populate manually.
+
+    This function is async because ComposerEngine.compose() is async
+    (it awaits Splice / filesystem sample resolution).
+    """
+    import logging
+    logger = logging.getLogger(__name__)
+
+    schema_version = producer_payload.get("schema_version") if producer_payload else None
+    intent_dict = (producer_payload or {}).get("intent")
+
+    if not intent_dict:
+        return {
+            "ok": False,
+            "error": (
+                "Composer branch producer_payload missing 'intent'. "
+                "This branch was likely emitted before PR3/v2 and cannot "
+                "be escalated — commit the scaffold plan instead."
+            ),
+        }
+
+    # Rehydrate CompositionIntent from the payload dict. Tolerate unknown
+    # keys by only pulling the fields CompositionIntent understands — older
+    # schemas may have fewer fields, newer may have more.
+    try:
+        intent_fields = {
+            k: v for k, v in intent_dict.items()
+            if k in (
+                "genre", "sub_genre", "mood", "tempo", "key",
+                "descriptors", "explicit_elements", "energy",
+                "layer_count", "duration_bars",
+            )
+        }
+        intent = CompositionIntent(**intent_fields)
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error": (
+                f"Failed to rehydrate CompositionIntent from producer_payload "
+                f"(schema_version={schema_version}): {exc}"
+            ),
+        }
+
+    engine = ComposerEngine()
+    try:
+        result: CompositionResult = await engine.compose(
+            intent=intent,
+            dry_run=False,
+            max_credits=max_credits,
+            search_roots=search_roots or [],
+            splice_client=splice_client,
+            browser_client=browser_client,
+        )
+    except Exception as exc:
+        return {
+            "ok": False,
+            "error": f"ComposerEngine.compose() raised: {exc}",
+        }
+
+    # Fallback when no layers resolved — explicit signal so callers can
+    # fall back to the scaffold instead of silently shipping an empty
+    # plan.
+    if not result.plan or len(result.layers) == 0:
+        return {
+            "ok": False,
+            "error": (
+                "ComposerEngine.compose() produced zero executable layers. "
+                "Sample resolution likely failed — check Splice credits, "
+                "filesystem roots, or browser connectivity. Falling back "
+                "to scaffold commit is the correct action."
+            ),
+            "warnings": list(result.warnings),
+            "resolved_samples": dict(result.resolved_samples),
+        }
+
+    return {
+        "ok": True,
+        "plan": list(result.plan),
+        "step_count": len(result.plan),
+        "layer_count": len(result.layers),
+        "resolved_samples": dict(result.resolved_samples),
+        "credits_estimated": result.credits_estimated,
+        "warnings": list(result.warnings),
+        "intent_used": intent.to_dict(),
+    }
+
+
 def _build_section_hypothesis_plan(intent: CompositionIntent, strategy_name: str) -> dict:
     """Build a lightweight, executable plan from an intent.
 

package/mcp_server/composer/tools.py

@@ -1,8 +1,10 @@
-"""Composer Engine MCP tools — 3 tools for auto-composition.
+"""Composer Engine MCP tools — 4 tools for auto-composition.
 
 compose: full multi-layer composition from text prompt
 augment_with_samples: add layers to existing session
 get_composition_plan: dry run preview
+propose_composer_branches (PR5/v2): multi-strategy branch hypotheses for
+    exploratory workflows (feeds create_experiment(seeds=...))
 """
 
 from __future__ import annotations
@@ -213,3 +215,58 @@ async def get_composition_plan(
         "then step through each tool call in sequence."
     )
     return plan
+
+
+@mcp.tool()
+def propose_composer_branches(
+    ctx: Context,
+    request_text: str,
+    count: int = 2,
+    freshness: float = 0.65,
+) -> dict:
+    """Emit N distinct compositional hypotheses for a single prompt (PR5/v2).
+
+    Branch-native companion to compose(): instead of one deterministic
+    layer plan, produces up to ``count`` BranchSeeds with different
+    strategic angles the user can audition via create_experiment +
+    run_experiment. Each seed carries a pre-compiled scaffolding plan
+    (set_tempo + create_midi_track per layer + create_scene per section)
+    that gets escalated to a fully resolved plan by commit_experiment
+    when the winning branch is chosen.
+
+    Strategies (gated on freshness):
+      canonical      — intent unchanged, genre defaults
+                       (shipped at every freshness level)
+      energy_shift   — intent.energy inverted around 0.5
+                       (freshness >= 0.4)
+      layer_contrast — one role swapped (pad-anchor instead of bass)
+                       (freshness >= 0.7)
+
+    Returns:
+      {
+        "request_text": str,
+        "branch_count": int,
+        "seeds": [BranchSeed.to_dict(), ...],
+        "compiled_plans": [plan_dict, ...]   (parallel to seeds; scaffold),
+      }
+
+    Each seed's producer_payload carries {strategy, intent,
+    request_text, reason} so commit_experiment can rehydrate the
+    CompositionIntent and run the full ComposerEngine.compose() for
+    the winner.
+    """
+    from .branch_producer import propose_composer_branches as _propose
+
+    pairs = _propose(
+        request_text=request_text,
+        kernel={"freshness": float(freshness)},
+        count=int(count),
+    )
+    seeds = [s.to_dict() for s, _ in pairs]
+    plans = [p for _, p in pairs]
+    return {
+        "request_text": request_text,
+        "branch_count": len(seeds),
+        "seeds": seeds,
+        "compiled_plans": plans,
+    }