livepilot 1.10.6 → 1.10.8

package/mcp_server/song_brain/tools.py

@@ -187,6 +187,77 @@ def build_song_brain(ctx: Context) -> dict:
     }
 
 
+def classify_energy_shape(arc: list[float]) -> dict:
+    """Classify the shape of an energy arc for user-facing explanation.
+
+    BUG-B13 fix: the old single-max-position classifier labeled
+    [0.7, 0.9, 0.9, 0.5, 0.6, 0.9, 0.4] (peaks at 1-2 AND 5) as
+    "front-loaded" because max()'s first occurrence is at index 1.
+    We now find ALL peaks above a dynamic threshold and classify by
+    count + distribution.
+
+    Returns {"shape": str, "peak_positions": list[int] | None}.
+    """
+    arc = [x for x in (arc or []) if x is not None]
+    if len(arc) < 3:
+        return {"shape": "short form — limited arc data", "peak_positions": None}
+
+    max_energy = max(arc)
+    arc_min = min(arc)
+    dynamic_mid = (arc_min + max_energy) / 2.0
+    peak_threshold = max(max_energy * 0.9, dynamic_mid)
+    peak_indices = [i for i, v in enumerate(arc) if v >= peak_threshold]
+
+    # Collapse runs of adjacent peak indices into their starting index —
+    # [1, 2, 5] has peaks at "position ~1" and "position 5", NOT three
+    # distinct peaks. Without this, front-loaded arcs where bars 0 and 1
+    # are both above threshold would misfire the dual-peak branch.
+    distinct_peaks: list[int] = []
+    for idx in peak_indices:
+        if not distinct_peaks or idx - distinct_peaks[-1] > 1:
+            distinct_peaks.append(idx)
+
+    n = len(arc)
+    first_third = {i for i in range(0, n // 3 + 1)}
+    last_third = {i for i in range(2 * n // 3, n)}
+    in_first = any(i in first_third for i in peak_indices)
+    in_last = any(i in last_third for i in peak_indices)
+    in_middle = any(
+        i not in first_third and i not in last_third
+        for i in peak_indices
+    )
+
+    # Plateau FIRST — when the dynamic range is narrow (<0.3) and most
+    # of the arc sits at/near the max, it's a plateau, not a multi-peak
+    # shape. Has to win over dual-peak so [0.7, 0.8, 0.8, 0.75, 0.8, …]
+    # doesn't get labeled "dual-peak at 2 and 6" when it's clearly flat.
+    if len(peak_indices) >= max(n - 2, 2) and (
+        max_energy - arc_min < 0.3
+    ):
+        shape = "plateau — sustained energy with limited dynamic range"
+    # Multi-peak: at least 2 DISTINCT peaks (after collapsing adjacent runs),
+    # separated by >= n/3 positions. Adjacent peaks are a single plateau, not two.
+    elif len(distinct_peaks) >= 2 and (
+        max(distinct_peaks) - min(distinct_peaks) >= max(n // 3, 2)
+    ):
+        shape = (
+            f"dual-peak — energy peaks at positions "
+            f"{distinct_peaks[0]+1} and {distinct_peaks[-1]+1}"
+        )
+    elif in_first and not in_middle and not in_last:
+        shape = "front-loaded — peaks early"
+    elif in_last and not in_first and not in_middle:
+        shape = "slow burn — builds to late peak"
+    elif in_middle and not in_first and not in_last:
+        shape = "centered arc — peaks in the middle"
+    else:
+        shape = (
+            f"mixed — peaks at positions "
+            f"{', '.join(str(i+1) for i in peak_indices)}"
+        )
+    return {"shape": shape, "peak_positions": peak_indices}
+
+
 @mcp.tool()
 def explain_song_identity(ctx: Context) -> dict:
     """Explain the current song's identity in human musical language.
@@ -228,20 +299,13 @@ def explain_song_identity(ctx: Context) -> dict:
             for s in brain.section_purposes
         ]
 
-    # Energy shape
+    # Energy shape — BUG-B13 fix: dual-peak detection. See
+    # classify_energy_shape() for logic.
     if brain.energy_arc:
-        arc = brain.energy_arc
-        if len(arc) >= 3:
-            peak_idx = arc.index(max(arc))
-            peak_pct = peak_idx / max(len(arc) - 1, 1)
-            if peak_pct < 0.3:
-                explanation["energy_shape"] = "front-loaded — peaks early"
-            elif peak_pct > 0.7:
-                explanation["energy_shape"] = "slow burn — builds to late peak"
-            else:
-                explanation["energy_shape"] = "centered arc — peaks in the middle"
-        else:
-            explanation["energy_shape"] = "short form — limited arc data"
+        shape_info = classify_energy_shape(brain.energy_arc)
+        explanation["energy_shape"] = shape_info["shape"]
+        if shape_info["peak_positions"] is not None:
+            explanation["peak_positions"] = shape_info["peak_positions"]
 
     # Open questions
     if brain.open_questions:

package/mcp_server/sound_design/tools.py

@@ -195,6 +195,46 @@ def _fetch_sound_design_data(ctx: Context, track_index: int) -> dict:
     }
 
 
+# BUG-B35: some roles are SUPPOSED to be simple. A kick, snare, or sub-bass
+# patch with one block + a saturator is textbook electronic drum design —
+# not "weak identity". Gate the "too_few_blocks" + "no_modulation_sources"
+# critics on track role so we don't pester users about their perfectly
+# serviceable DS Kick patches.
+_SIMPLE_ROLE_TOKENS = (
+    "kick", "snare", "clap", "rim", "hat", "hihat", "hi-hat",
+    "drum", "drums", "perc", "percussion", "conga", "shaker",
+    "tambourine", "cowbell", "tom", "crash", "ride", "cymbal",
+    "808", "sub", "sub bass", "sub_bass",
+)
+
+
+def _is_simple_role_track(track_name: str) -> bool:
+    """True when the track name matches a role where simple patches are
+    the correct creative choice (kick/snare/drums/sub)."""
+    if not track_name:
+        return False
+    lowered = str(track_name).lower()
+    return any(tok in lowered for tok in _SIMPLE_ROLE_TOKENS)
+
+
+_ROLE_SUPPRESSIBLE_ISSUES = frozenset({
+    "too_few_blocks",
+    "no_modulation_sources",
+})
+
+
+def _filter_role_appropriate_issues(
+    issues: list,
+    track_name: str,
+) -> list:
+    """Drop issues whose type is in _ROLE_SUPPRESSIBLE_ISSUES when the
+    track role (inferred from name) is one where simplicity is expected.
+    Issues pass through unchanged for pad / lead / synth / bass roles."""
+    if not _is_simple_role_track(track_name):
+        return issues
+    return [i for i in issues if i.issue_type not in _ROLE_SUPPRESSIBLE_ISSUES]
+
+
 # ── MCP Tools ────────────────────────────────────────────────────────
 
 
@@ -217,6 +257,10 @@ def analyze_sound_design(ctx: Context, track_index: int) -> dict:
         layers=layers,
     )
     issues = run_all_sound_design_critics(state)
+    # BUG-B35: gate role-sensitive critics by track name
+    issues = _filter_role_appropriate_issues(
+        issues, data["track_info"].get("name", "")
+    )
     moves = plan_sound_design_moves(issues, state)
 
     return {
@@ -246,6 +290,9 @@ def get_sound_design_issues(ctx: Context, track_index: int) -> dict:
         layers=layers,
     )
     issues = run_all_sound_design_critics(state)
+    issues = _filter_role_appropriate_issues(
+        issues, data["track_info"].get("name", "")
+    )
 
     return {
         "issues": [i.to_dict() for i in issues],
@@ -260,6 +307,11 @@ def plan_sound_design_move(ctx: Context, track_index: int) -> dict:
     Runs critics and planner, returns sorted moves with
     estimated impact and risk scores.
 
+    BUG-B36 fix: when zero sound-design issues but sibling mix/
+    composition engines flag problems on the same track, returns a
+    `cross_engine_hint` pointing the user to the right tool instead
+    of silently reporting empty.
+
     Args:
         track_index: Index of the track to analyze.
     """
@@ -272,14 +324,73 @@ def plan_sound_design_move(ctx: Context, track_index: int) -> dict:
         layers=layers,
     )
     issues = run_all_sound_design_critics(state)
+    issues = _filter_role_appropriate_issues(
+        issues, data["track_info"].get("name", "")
+    )
     moves = plan_sound_design_moves(issues, state)
 
-    return {
+    result: dict = {
         "moves": [m.to_dict() for m in moves],
         "move_count": len(moves),
         "issue_count": len(issues),
     }
 
+    # BUG-B36: when nothing to do on the sound-design side, probe sibling
+    # engines for issues on this track and emit a discoverability hint.
+    if not moves:
+        cross_hint = _cross_engine_hint_for_track(ctx, track_index)
+        if cross_hint:
+            result["cross_engine_hint"] = cross_hint
+
+    return result
+
+
+def _cross_engine_hint_for_track(
+    ctx: Context, track_index: int,
+) -> Optional[str]:
+    """Look at mix issues for this track and emit a hint pointing to
+    the right sibling tool when sound-design has nothing to say.
+
+    Best-effort — any failure returns None so plan_sound_design_move
+    never breaks on telemetry hiccups. Calls into the mix-engine's
+    pure function directly (not an MCP round-trip) to avoid the
+    one-client-per-port contention.
+    """
+    try:
+        from ..mix_engine.critics import run_all_mix_critics
+        from ..mix_engine.state_builder import build_mix_state
+        from ..mix_engine.tools import _fetch_mix_data
+        data = _fetch_mix_data(ctx)
+        mix_state = build_mix_state(
+            session_info=data.get("session_info", {}),
+            track_infos=data.get("track_infos", []),
+            spectrum=data.get("spectrum"),
+            rms_data=data.get("rms_data"),
+        )
+        mix_issues = run_all_mix_critics(mix_state)
+    except Exception:
+        return None
+
+    if not mix_issues:
+        return None
+    track_issues = [
+        i for i in mix_issues
+        if getattr(i, "track_index", None) == track_index
+    ]
+    if not track_issues:
+        return None
+    top = max(
+        track_issues,
+        key=lambda i: float(getattr(i, "severity", 0) or 0),
+    )
+    issue_type = str(getattr(top, "issue_type", None) or getattr(top, "type", "issue"))
+    sev = float(getattr(top, "severity", 0) or 0)
+    return (
+        f"No sound-design issues on this track, but mix critic flagged "
+        f"'{issue_type}' (severity {sev:.2f}). "
+        f"Try plan_mix_move for the same track_index."
+    )
+
 
 @mcp.tool()
 def get_patch_model(ctx: Context, track_index: int) -> dict:

package/mcp_server/splice_client/client.py

@@ -27,6 +27,16 @@ _SPLICE_APP_SUPPORT = os.path.expanduser(
 # Credit safety floor — never drain below this
 CREDIT_HARD_FLOOR = 5
 
+# Per-call gRPC timeouts. The previous implementation passed no timeout, so
+# a hung Splice process could block the MCP event loop until gRPC's default
+# (often infinite) deadline fired. Keep generous enough for cold searches
+# but bounded enough that a dead socket fails the tool call, not the server.
+SEARCH_TIMEOUT = 10.0
+INFO_TIMEOUT = 5.0
+CREDITS_TIMEOUT = 5.0
+SYNC_TIMEOUT = 30.0
+DOWNLOAD_TRIGGER_TIMEOUT = 5.0
+
 
 def _try_import_grpc():
     """Import grpcio lazily — graceful degradation if not installed."""
@@ -148,7 +158,7 @@ class SpliceGRPCClient:
                 Page=page,
                 Purchased=purchased,
             )
-            response = await self.stub.SearchSamples(request)
+            response = await self.stub.SearchSamples(request, timeout=SEARCH_TIMEOUT)
             return self._parse_search_response(response)
         except Exception as exc:
             logger.warning(f"Splice search failed: {exc}")
@@ -213,7 +223,8 @@ class SpliceGRPCClient:
         try:
             # Trigger download
             await self.stub.DownloadSample(
-                pb2.DownloadSampleRequest(FileHash=file_hash)
+                pb2.DownloadSampleRequest(FileHash=file_hash),
+                timeout=DOWNLOAD_TRIGGER_TIMEOUT,
             )
             # Wait for file to appear on disk
             return await self._wait_for_download(file_hash, timeout)
@@ -226,11 +237,16 @@ class SpliceGRPCClient:
     ) -> Optional[str]:
         """Poll SampleInfo until LocalPath is populated."""
         pb2 = self._pb2
-        deadline = asyncio.get_event_loop().time() + timeout
-        while asyncio.get_event_loop().time() < deadline:
+        # asyncio.get_event_loop() is deprecated when called inside an
+        # already-running coroutine on Python 3.10+. Use get_running_loop()
+        # which is the documented replacement.
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout
+        while loop.time() < deadline:
             try:
                 response = await self.stub.SampleInfo(
-                    pb2.SampleInfoRequest(FileHash=file_hash)
+                    pb2.SampleInfoRequest(FileHash=file_hash),
+                    timeout=INFO_TIMEOUT,
                 )
                 if response.Sample.LocalPath:
                     return response.Sample.LocalPath
@@ -250,7 +266,8 @@ class SpliceGRPCClient:
         pb2 = self._pb2
         try:
             response = await self.stub.SampleInfo(
-                pb2.SampleInfoRequest(FileHash=file_hash)
+                pb2.SampleInfoRequest(FileHash=file_hash),
+                timeout=INFO_TIMEOUT,
             )
             s = response.Sample
             return SpliceSample(
@@ -282,7 +299,8 @@ class SpliceGRPCClient:
         pb2 = self._pb2
         try:
             response = await self.stub.ValidateLogin(
-                pb2.ValidateLoginRequest()
+                pb2.ValidateLoginRequest(),
+                timeout=CREDITS_TIMEOUT,
             )
             return SpliceCredits(
                 credits=response.User.Credits,
@@ -315,7 +333,10 @@ class SpliceGRPCClient:
             return False
         pb2 = self._pb2
         try:
-            await self.stub.SyncSounds(pb2.SyncSoundsRequest())
+            await self.stub.SyncSounds(
+                pb2.SyncSoundsRequest(),
+                timeout=SYNC_TIMEOUT,
+            )
             return True
         except Exception as exc:
             logger.debug("sync_sounds failed: %s", exc)

package/mcp_server/stuckness_detector/detector.py

@@ -20,14 +20,30 @@ def detect_stuckness(
     session_info: Optional[dict] = None,
     song_brain: Optional[dict] = None,
     section_count: int = 0,
+    state_signals: Optional[dict] = None,
 ) -> StucknessReport:
     """Detect whether the session is stuck.
 
     Analyzes action history for repeated undos, local tweaking,
     long loops without structural edits, and other stuckness signals.
+
+    BUG-B6 / B20 fix: also accepts `state_signals` — a dict of
+    current-session-state indicators that may reveal stuckness even
+    when the action ledger is empty. Known keys (all optional):
+        fatigue_level: float 0-1  (from detect_repetition_fatigue)
+        motif_overuse_count: int   (motifs exceeding overuse threshold)
+        emotional_arc_issues: list of issue-type strings
+        transition_issues: int
+        support_too_loud: bool     (from analyze_mix)
+        automation_density: float  (0 = no clip automation anywhere)
+
+    When state_signals are provided, they contribute to confidence
+    alongside ledger-based signals (ledger weighting is still
+    dominant — ledger signals indicate active-user-is-stuck behavior).
     """
     session_info = session_info or {}
     song_brain = song_brain or {}
+    state_signals = state_signals or {}
     signals: list[StucknessSignal] = []
 
     # 1. Repeated undos
@@ -60,6 +76,10 @@ def detect_stuckness(
     if identity_signal:
         signals.append(identity_signal)
 
+    # 7. BUG-B6 / B20 — state critics
+    state_derived = _state_signals_to_signal_list(state_signals)
+    signals.extend(state_derived)
+
     # Compute overall confidence
     if not signals:
         return StucknessReport(confidence=0.0, level="flowing")
@@ -98,6 +118,76 @@ def detect_stuckness(
 # ── Signal checkers ───────────────────────────────────────────────
 
 
+def _state_signals_to_signal_list(state: dict) -> list[StucknessSignal]:
+    """Convert a state_signals dict (from sibling critics) into
+    StucknessSignal entries. BUG-B6 / B20: previously the detector
+    ignored session state entirely — so a session with fatigue_level=0.93
+    but an empty action ledger always reported "flowing". Now we surface
+    state-based stuckness but keep the signals at a slightly lower
+    weight than ledger signals (ledger = active-user-is-stuck behavior,
+    state = project-shape-is-stuck).
+    """
+    out: list[StucknessSignal] = []
+    if not state:
+        return out
+
+    # Fatigue / repetition
+    fatigue = state.get("fatigue_level")
+    if isinstance(fatigue, (int, float)) and fatigue >= 0.6:
+        out.append(StucknessSignal(
+            signal_type="state_repetition_fatigue",
+            # Scale from 0.6-1.0 → 0.5-0.85 (sub-ledger weight)
+            strength=min(0.85, 0.5 + (fatigue - 0.6) * 0.875),
+            evidence=(
+                f"repetition fatigue at {fatigue:.2f} — clips/sections "
+                f"overused"
+            ),
+        ))
+
+    motif_overuse = state.get("motif_overuse_count", 0)
+    if isinstance(motif_overuse, int) and motif_overuse >= 3:
+        out.append(StucknessSignal(
+            signal_type="state_motif_overuse",
+            strength=min(0.7, 0.3 + motif_overuse * 0.1),
+            evidence=f"{motif_overuse} motifs flagged as overused",
+        ))
+
+    arc_issues = state.get("emotional_arc_issues") or []
+    if isinstance(arc_issues, (list, tuple)) and arc_issues:
+        out.append(StucknessSignal(
+            signal_type="state_emotional_arc",
+            strength=min(0.7, 0.3 + len(arc_issues) * 0.1),
+            evidence=(
+                f"emotional-arc issues: {', '.join(str(i) for i in arc_issues[:3])}"
+            ),
+        ))
+
+    transition_issues = state.get("transition_issues", 0)
+    if isinstance(transition_issues, int) and transition_issues >= 3:
+        out.append(StucknessSignal(
+            signal_type="state_transition_issues",
+            strength=min(0.7, 0.25 + transition_issues * 0.08),
+            evidence=f"{transition_issues} transition issues detected",
+        ))
+
+    if state.get("support_too_loud"):
+        out.append(StucknessSignal(
+            signal_type="state_mix_imbalance",
+            strength=0.35,
+            evidence="mix critic flagged a support element as too loud",
+        ))
+
+    auto_density = state.get("automation_density")
+    if isinstance(auto_density, (int, float)) and auto_density <= 0.05:
+        out.append(StucknessSignal(
+            signal_type="state_no_automation",
+            strength=0.35,
+            evidence="no clip automation detected — arrangement is static",
+        ))
+
+    return out
+
+
 def _check_repeated_undos(history: list[dict]) -> Optional[StucknessSignal]:
     """Check for repeated undone moves (kept=False in ledger entries)."""
     recent = history[-20:] if len(history) > 20 else history

package/mcp_server/stuckness_detector/tools.py

@@ -62,6 +62,43 @@ def _get_session_and_brain(ctx: Context) -> tuple[dict, dict, int]:
     return session_info, song_brain, section_count
 
 
+def _gather_state_signals(ctx: Context, song_brain: dict) -> dict:
+    """BUG-B6 / B20: collect current-session-state stuckness indicators
+    that the detector can merge with ledger-based signals.
+
+    All lookups are best-effort — if a sibling module isn't available
+    or its data is stale, we omit the signal (don't guess).
+    """
+    signals: dict = {}
+
+    # Repetition fatigue from musical_intelligence.detectors
+    try:
+        from ..musical_intelligence.tools import _current_fatigue_cache  # type: ignore
+        if isinstance(_current_fatigue_cache, dict):
+            fl = _current_fatigue_cache.get("fatigue_level")
+            if isinstance(fl, (int, float)):
+                signals["fatigue_level"] = float(fl)
+            overuse = _current_fatigue_cache.get("motif_overuse_count")
+            if isinstance(overuse, int):
+                signals["motif_overuse_count"] = overuse
+    except Exception as exc:
+        logger.debug("_gather_state_signals fatigue fetch failed: %s", exc)
+
+    # Emotional-arc issues directly from song brain (already fetched)
+    arc_issues = []
+    if isinstance(song_brain, dict):
+        oqs = song_brain.get("open_questions") or []
+        for q in oqs:
+            if isinstance(q, dict):
+                qtype = q.get("question_type") or q.get("type") or ""
+                if "arc" in str(qtype).lower() or "payoff" in str(qtype).lower():
+                    arc_issues.append(qtype)
+    if arc_issues:
+        signals["emotional_arc_issues"] = arc_issues
+
+    return signals
+
+
 @mcp.tool()
 def detect_stuckness(ctx: Context) -> dict:
     """Detect whether the session is losing momentum.
@@ -79,12 +116,14 @@ def detect_stuckness(ctx: Context) -> dict:
     """
     history = _get_action_history(ctx)
     session_info, song_brain, section_count = _get_session_and_brain(ctx)
+    state_signals = _gather_state_signals(ctx, song_brain)
 
     report = detector.detect_stuckness(
         action_history=history,
         session_info=session_info,
         song_brain=song_brain,
         section_count=section_count,
+        state_signals=state_signals,
     )
 
     return report.to_dict()
@@ -110,12 +149,14 @@ def suggest_momentum_rescue(
 
     history = _get_action_history(ctx)
     session_info, song_brain, section_count = _get_session_and_brain(ctx)
+    state_signals = _gather_state_signals(ctx, song_brain)
 
     report = detector.detect_stuckness(
         action_history=history,
         session_info=session_info,
         song_brain=song_brain,
         section_count=section_count,
+        state_signals=state_signals,
     )
 
     if report.level == "flowing":

package/mcp_server/tools/_agent_os_engine/critics.py

@@ -37,6 +37,30 @@ def run_sonic_critic(
     peak = sonic.get("peak")
     target_dims = set(goal.targets.keys())
 
+    # BUG-B42: if every spectrum band is zero AND rms is zero, playback
+    # is stopped (or nothing is routing to master). Spectrum-based
+    # critics (weak_foundation, harsh_highs, low_mid_congestion, etc.)
+    # would fire on zero data, reporting "no bass!" when the real cause
+    # is "no audio". Short-circuit to a playback_required advisory so
+    # callers don't chase phantom mix issues during static inspection.
+    _all_bands = all(float(bands.get(b, 0) or 0) == 0 for b in
+                     ("sub", "low", "low_mid", "mid", "high_mid", "high",
+                      "presence", "air"))
+    _silent = _all_bands and (rms is None or float(rms or 0) == 0)
+    if _silent:
+        return [Issue(
+            type="playback_required",
+            critic="sonic",
+            severity=0.1,
+            confidence=1.0,
+            affected_dimensions=list(MEASURABLE_PROXIES.keys()),
+            evidence=["spectrum and RMS both zero — playback stopped or no signal"],
+            recommended_actions=[
+                "Start playback before calling build_world_model / "
+                "analyze_mix so spectrum-based critics can evaluate.",
+            ],
+        )]
+
     # 1. Mud detection: low_mid congestion
     low_mid = bands.get("low_mid", 0)
     if low_mid > 0.7 and {"clarity", "weight", "warmth"} & target_dims:

package/mcp_server/tools/_composition_engine/__init__.py

@@ -44,7 +44,7 @@ from .gestures import (
     plan_gesture,
     resolve_gesture_template,
 )
-from .harmony import build_harmony_field
+from .harmony import build_harmony_field, harmonic_score
 from .analysis import (
     COMPOSITION_DIMENSIONS,
     analyze_section_outcomes,
@@ -61,7 +61,7 @@ __all__ = [
     "run_form_critic", "run_section_identity_critic", "run_phrase_critic",
     "run_transition_critic", "run_emotional_arc_critic", "run_cross_section_critic",
     "GESTURE_TEMPLATES", "plan_gesture", "resolve_gesture_template",
-    "build_harmony_field",
+    "build_harmony_field", "harmonic_score",
     "COMPOSITION_DIMENSIONS", "analyze_section_outcomes",
     "evaluate_composition_move", "build_composition_taste_model",
 ]

package/mcp_server/tools/_composition_engine/harmony.py

@@ -14,6 +14,96 @@ from typing import Any, Optional
 
 from .models import HarmonyField
 
+
+# ── BUG-E3: harmonic-ness scoring ────────────────────────────────────────
+# get_harmony_field used to take the FIRST track in section.tracks_active
+# that had notes and lock in its key detection. When that track was
+# percussion (all notes at a single pitch, staccato), detect_key would
+# return a bogus "C major" for the whole section. The fix: score every
+# track's notes for harmonic-ness, aggregate notes from tracks that pass
+# a threshold, and run key detection on the combined pool.
+
+_PERC_NAME_TOKENS = (
+    "kick", "snare", "clap", "hat", "hihat", "hi-hat", "hh", "drum",
+    "drums", "perc", "percussion", "rim", "crash", "ride", "tom",
+    "cymbal", "shaker", "tambourine", "cowbell", "808", "909",
+    "breakbeat", "break", "stick", "click",
+)
+_HARMONIC_NAME_TOKENS = (
+    "pad", "pads", "bass", "sub", "lead", "chord", "chords", "keys",
+    "synth", "piano", "rhodes", "organ", "lush", "string", "strings",
+    "brass", "pluck", "arp", "melody", "harmony", "voice", "choir",
+)
+
+
+def harmonic_score(notes: list[dict], track_name: str = "") -> float:
+    """Rate how likely a track's notes carry harmonic content (0.0 - 1.0).
+
+    Used by get_harmony_field to decide which tracks to include in
+    aggregate key detection. Percussion (single-pitch, staccato) scores
+    near 0. Sustained chordal/melodic material scores near 1.
+
+    Signals combined:
+      - unique pitch classes (chords vary, kicks don't)
+      - median note duration (sustain vs staccato)
+      - pitch range (melody moves, drums don't)
+      - minimum pitch (above the GM drum range)
+      - track-name hint tokens (soft nudge)
+
+    Returns a score in [0.0, 1.0]. Callers typically threshold at 0.3 or 0.4.
+    """
+    if not notes:
+        return 0.0
+
+    pitches = [int(n.get("pitch", 60)) for n in notes]
+    durations = [float(n.get("duration", 0.0)) for n in notes]
+    pcs = set(p % 12 for p in pitches)
+
+    # Use statistics.median for a more stable middle value. Falling back
+    # to a manual median keeps this file free of an extra import.
+    sorted_durs = sorted(durations)
+    median_dur = sorted_durs[len(sorted_durs) // 2] if sorted_durs else 0.0
+    unique_pcs = len(pcs)
+    pitch_range = max(pitches) - min(pitches) if pitches else 0
+    min_pitch = min(pitches) if pitches else 0
+
+    score = 0.0
+    # Unique pitch-class diversity: 3+ distinct pcs is a strong harmonic signal
+    if unique_pcs >= 4:
+        score += 0.45
+    elif unique_pcs >= 3:
+        score += 0.35
+    elif unique_pcs >= 2:
+        score += 0.15
+
+    # Duration: sustained notes carry harmony; staccato is rhythmic
+    if median_dur >= 1.0:
+        score += 0.30
+    elif median_dur >= 0.5:
+        score += 0.25
+    elif median_dur >= 0.25:
+        score += 0.10
+
+    # Pitch range: melody spans more than an octave often; drums don't
+    if pitch_range >= 12:
+        score += 0.20
+    elif pitch_range >= 5:
+        score += 0.10
+
+    # Minimum pitch out of the GM drum-map range (35–51) suggests melody
+    if min_pitch >= 48:
+        score += 0.10
+
+    # Track-name hints — mild nudges either way
+    name_lower = str(track_name or "").lower()
+    if any(tok in name_lower for tok in _PERC_NAME_TOKENS):
+        score -= 0.45
+    if any(tok in name_lower for tok in _HARMONIC_NAME_TOKENS):
+        score += 0.20
+
+    return max(0.0, min(1.0, score))
+
+
 def build_harmony_field(
     section_id: str,
     harmony_analysis: Optional[dict] = None,