livepilot 1.10.6 → 1.10.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/.claude-plugin/marketplace.json +3 -3
  2. package/.mcp.json.disabled +9 -0
  3. package/.mcpbignore +3 -0
  4. package/AGENTS.md +3 -3
  5. package/BUGS.md +1570 -0
  6. package/CHANGELOG.md +42 -0
  7. package/CONTRIBUTING.md +1 -1
  8. package/README.md +7 -7
  9. package/bin/livepilot.js +28 -8
  10. package/livepilot/.Codex-plugin/plugin.json +2 -2
  11. package/livepilot/.claude-plugin/plugin.json +2 -2
  12. package/livepilot/skills/livepilot-core/SKILL.md +4 -4
  13. package/livepilot/skills/livepilot-core/references/overview.md +2 -2
  14. package/livepilot/skills/livepilot-release/SKILL.md +8 -8
  15. package/m4l_device/LivePilot_Analyzer.amxd +0 -0
  16. package/m4l_device/LivePilot_Analyzer.amxd.pre-presentation-backup +0 -0
  17. package/m4l_device/LivePilot_Analyzer.maxproj +53 -0
  18. package/m4l_device/livepilot_bridge.js +214 -2
  19. package/manifest.json +3 -3
  20. package/mcp_server/__init__.py +1 -1
  21. package/mcp_server/atlas/__init__.py +93 -26
  22. package/mcp_server/creative_constraints/tools.py +206 -33
  23. package/mcp_server/experiment/engine.py +7 -9
  24. package/mcp_server/hook_hunter/analyzer.py +62 -9
  25. package/mcp_server/hook_hunter/tools.py +60 -9
  26. package/mcp_server/m4l_bridge.py +21 -6
  27. package/mcp_server/musical_intelligence/detectors.py +32 -0
  28. package/mcp_server/performance_engine/tools.py +112 -29
  29. package/mcp_server/preview_studio/engine.py +89 -8
  30. package/mcp_server/preview_studio/tools.py +22 -6
  31. package/mcp_server/project_brain/automation_graph.py +71 -19
  32. package/mcp_server/project_brain/builder.py +2 -0
  33. package/mcp_server/project_brain/tools.py +55 -5
  34. package/mcp_server/reference_engine/profile_builder.py +129 -3
  35. package/mcp_server/reference_engine/tools.py +47 -6
  36. package/mcp_server/runtime/execution_router.py +50 -0
  37. package/mcp_server/runtime/mcp_dispatch.py +75 -3
  38. package/mcp_server/runtime/remote_commands.py +4 -2
  39. package/mcp_server/sample_engine/analyzer.py +131 -4
  40. package/mcp_server/sample_engine/critics.py +29 -8
  41. package/mcp_server/sample_engine/models.py +20 -1
  42. package/mcp_server/sample_engine/tools.py +48 -14
  43. package/mcp_server/semantic_moves/sound_design_compilers.py +22 -59
  44. package/mcp_server/semantic_moves/transition_compilers.py +12 -19
  45. package/mcp_server/server.py +68 -2
  46. package/mcp_server/session_continuity/models.py +4 -0
  47. package/mcp_server/session_continuity/tracker.py +14 -1
  48. package/mcp_server/song_brain/builder.py +110 -12
  49. package/mcp_server/song_brain/tools.py +77 -13
  50. package/mcp_server/sound_design/tools.py +112 -1
  51. package/mcp_server/stuckness_detector/detector.py +90 -0
  52. package/mcp_server/stuckness_detector/tools.py +41 -0
  53. package/mcp_server/tools/_agent_os_engine/critics.py +24 -0
  54. package/mcp_server/tools/_composition_engine/__init__.py +2 -2
  55. package/mcp_server/tools/_composition_engine/harmony.py +90 -0
  56. package/mcp_server/tools/_composition_engine/sections.py +47 -4
  57. package/mcp_server/tools/_harmony_engine.py +52 -8
  58. package/mcp_server/tools/_research_engine.py +98 -19
  59. package/mcp_server/tools/_theory_engine.py +138 -9
  60. package/mcp_server/tools/agent_os.py +20 -3
  61. package/mcp_server/tools/analyzer.py +98 -0
  62. package/mcp_server/tools/clips.py +45 -0
  63. package/mcp_server/tools/composition.py +66 -23
  64. package/mcp_server/tools/devices.py +22 -1
  65. package/mcp_server/tools/harmony.py +115 -14
  66. package/mcp_server/tools/midi_io.py +13 -1
  67. package/mcp_server/tools/mixing.py +35 -1
  68. package/mcp_server/tools/motif.py +49 -3
  69. package/mcp_server/tools/research.py +24 -0
  70. package/mcp_server/tools/theory.py +108 -16
  71. package/mcp_server/transition_engine/critics.py +18 -11
  72. package/package.json +2 -2
  73. package/remote_script/LivePilot/__init__.py +57 -2
  74. package/remote_script/LivePilot/clips.py +69 -0
  75. package/remote_script/LivePilot/mixing.py +117 -0
  76. package/remote_script/LivePilot/router.py +13 -1
  77. package/scripts/generate_tool_catalog.py +13 -38
  78. package/scripts/sync_metadata.py +231 -14
@@ -127,6 +127,14 @@ def _infer_identity_core(
127
127
  """Infer the single strongest defining idea in the session.
128
128
 
129
129
  Returns (description, confidence).
130
+
131
+ BUG-B10 fix: the old logic picked "Dominant texture: drums" at
132
+ confidence 0.5 for almost every session — because drum tracks
133
+ typically have the most notes. We now consider richer signals:
134
+ featured vocals, scene-name aesthetics, tempo+key context, and
135
+ single-instrument dominance. When multiple low-confidence signals
136
+ align (e.g. "dust" aesthetic + vocal hook + D minor key), we
137
+ combine them into a compound identity string.
130
138
  """
131
139
  candidates: list[tuple[str, float]] = []
132
140
 
@@ -144,7 +152,7 @@ def _infer_identity_core(
144
152
  if arc_type:
145
153
  candidates.append((f"Emotional arc: {arc_type}", 0.6))
146
154
 
147
- # From role graph — dominant texture
155
+ # From role graph — dominant texture (kept but gently deranked)
148
156
  # role_graph format: {track_name: {index: int, role: str}}
149
157
  if role_graph:
150
158
  role_counts = Counter(
@@ -153,9 +161,15 @@ def _infer_identity_core(
153
161
  if isinstance(info, dict)
154
162
  )
155
163
  role_counts.pop("unknown", None)
156
- if role_counts:
157
- dominant_role = role_counts.most_common(1)[0]
158
- candidates.append((f"Dominant texture: {dominant_role[0]}", 0.5))
164
+ # B10 fix: drums being the "dominant texture" is almost never
165
+ # what the song is ABOUT — it's just that drum tracks have the
166
+ # most notes. Skip drums/perc from this candidate stream.
167
+ _BORING_DOMINANT = {"drums", "percussion", "kick", "snare", "hat"}
168
+ for role, _ in role_counts.most_common(3):
169
+ if role.lower() in _BORING_DOMINANT:
170
+ continue
171
+ candidates.append((f"Dominant texture: {role}", 0.55))
172
+ break
159
173
 
160
174
  # From track analysis — genre/style cues
161
175
  track_names = [t.get("name", "").lower() for t in tracks]
@@ -163,12 +177,65 @@ def _infer_identity_core(
163
177
  if genre_cues:
164
178
  candidates.append((f"Style: {genre_cues}", 0.4))
165
179
 
180
+ # BUG-B10: featured instrument — a named vocal/pad/lead track with
181
+ # an explicit function is usually more identity-defining than
182
+ # "dominant texture: drums".
183
+ _FEATURED_TOKENS = (
184
+ ("vocal", "vocal hook", 0.75),
185
+ ("vox", "vocal hook", 0.72),
186
+ ("pad", "pad-led atmosphere", 0.55),
187
+ ("lead", "lead synth melody", 0.65),
188
+ ("rhodes", "rhodes-keys texture", 0.60),
189
+ ("piano", "piano-led harmony", 0.60),
190
+ ("guitar", "guitar-led", 0.60),
191
+ ("saxophone", "saxophone solo", 0.65),
192
+ ("brass", "brass section", 0.55),
193
+ )
194
+ for name in track_names:
195
+ for token, label, conf in _FEATURED_TOKENS:
196
+ if token in name:
197
+ candidates.append((f"Featured element: {label}", conf))
198
+ break
199
+
200
+ # BUG-B10: scene-name aesthetic cues. A scene named "Intro Dust" /
201
+ # "Outro Dust" signals a deliberate dust/lo-fi aesthetic; "Sun Peak"
202
+ # / "Peak" signals a climax-oriented structure. Pull these from the
203
+ # composition-analysis section list if present.
204
+ _AESTHETIC_TOKENS = (
205
+ ("dust", "dust-toned lo-fi"),
206
+ ("sun", "warm/sun-peaked"),
207
+ ("fog", "foggy/dreamy"),
208
+ ("glass", "brittle/glass-like"),
209
+ ("void", "void/ambient-spatial"),
210
+ ("haze", "hazy/nostalgic"),
211
+ ("bloom", "blooming/evolving"),
212
+ )
213
+ sections = composition.get("sections", []) or []
214
+ section_names = " ".join(
215
+ str(s.get("name", "") or s.get("label", "")).lower()
216
+ for s in sections
217
+ )
218
+ for token, label in _AESTHETIC_TOKENS:
219
+ if token in section_names:
220
+ candidates.append((f"Aesthetic: {label}", 0.55))
221
+ break
222
+
166
223
  if not candidates:
167
224
  # Fallback: describe by track count and tempo
168
225
  return ("Emerging piece — identity not yet established", 0.2)
169
226
 
170
- best = max(candidates, key=lambda c: c[1])
171
- return best
227
+ # BUG-B10: when no single candidate is confident (>0.6), blend the
228
+ # top 2 into a compound identity — captures "vocal hook + dust
229
+ # aesthetic" style identity rather than picking one weak signal.
230
+ candidates.sort(key=lambda c: c[1], reverse=True)
231
+ top = candidates[0]
232
+ if top[1] >= 0.6 or len(candidates) < 2:
233
+ return top
234
+ # Blend top 2
235
+ second = candidates[1]
236
+ blended_desc = f"{top[0]} + {second[0].lower()}"
237
+ blended_conf = min(0.85, (top[1] + second[1]) / 2 + 0.1)
238
+ return (blended_desc, blended_conf)
172
239
 
173
240
 
174
241
  def _detect_genre_cues(track_names: list[str]) -> str:
@@ -260,6 +327,12 @@ def _detect_sacred_elements(
260
327
  # ── Section purposes ──────────────────────────────────────────────
261
328
 
262
329
 
330
+ # Section intents that imply this is a "payoff" / arrival moment.
331
+ # Used by _infer_section_purposes to derive is_payoff consistently
332
+ # when composition returns an intent label without the explicit flag.
333
+ _PAYOFF_INTENTS = frozenset({"payoff", "drop", "chorus", "hook"})
334
+
335
+
263
336
  def _infer_section_purposes(
264
337
  scenes: list[dict],
265
338
  composition: dict,
@@ -271,12 +344,27 @@ def _infer_section_purposes(
271
344
  comp_sections = composition.get("sections", [])
272
345
  if comp_sections:
273
346
  for sec in comp_sections:
347
+ name = str(sec.get("name", ""))
348
+ # BUG-B12: skip empty placeholder sections that pollute the
349
+ # energy_arc and section_purposes list. A section with no name
350
+ # AND zero energy corresponds to an unnamed empty scene slot.
351
+ if not name.strip() and not sec.get("energy", 0):
352
+ continue
353
+ intent = sec.get("intent", sec.get("purpose", "")) or ""
354
+ # BUG-B11: derive is_payoff from the intent label when the
355
+ # explicit flag isn't set. Composition engine returns
356
+ # intent="drop"/"chorus"/"hook"/"payoff" — these all mean the
357
+ # section IS a payoff, so is_payoff must reflect that.
358
+ is_payoff = bool(
359
+ sec.get("is_payoff", False)
360
+ or intent.lower() in _PAYOFF_INTENTS
361
+ )
274
362
  sections.append(SectionPurpose(
275
- section_id=sec.get("id", sec.get("name", "")),
276
- label=sec.get("label", sec.get("name", "")),
277
- emotional_intent=sec.get("intent", sec.get("purpose", "")),
363
+ section_id=sec.get("id", name),
364
+ label=sec.get("label", name),
365
+ emotional_intent=intent,
278
366
  energy_level=sec.get("energy", 0.5),
279
- is_payoff=sec.get("is_payoff", False),
367
+ is_payoff=is_payoff,
280
368
  confidence=0.7,
281
369
  ))
282
370
  return sections
@@ -284,6 +372,10 @@ def _infer_section_purposes(
284
372
  # Fallback: infer from scene names
285
373
  for i, scene in enumerate(scenes):
286
374
  name = scene.get("name", f"Scene {i}")
375
+ # BUG-B12 (fallback path): skip empty scenes so they don't pollute
376
+ # the output even when no composition data is available.
377
+ if not str(name).strip():
378
+ continue
287
379
  label, intent, energy, is_payoff = _classify_scene_name(name, i, len(scenes))
288
380
  sections.append(SectionPurpose(
289
381
  section_id=f"scene_{i}",
@@ -389,8 +481,14 @@ def _detect_open_questions(
389
481
  ))
390
482
 
391
483
  # Missing sections (common gaps)
392
- labels = {s.label for s in sections}
393
- if len(sections) > 3 and "intro" not in labels:
484
+ # BUG-B14: check substrings across labels AND emotional intents
485
+ # (case-insensitive) so scene names like "Intro Dust" or intent "intro"
486
+ # both satisfy the check. Exact-match on the label set missed those.
487
+ signal_text = " ".join(
488
+ f"{s.label} {s.emotional_intent}".lower() for s in sections
489
+ )
490
+ has_intro = any(kw in signal_text for kw in ("intro", "opening", "opener"))
491
+ if len(sections) > 3 and not has_intro:
394
492
  questions.append(OpenQuestion(
395
493
  question="No intro section — does the track need an opening?",
396
494
  domain="arrangement",
@@ -187,6 +187,77 @@ def build_song_brain(ctx: Context) -> dict:
187
187
  }
188
188
 
189
189
 
190
+ def classify_energy_shape(arc: list[float]) -> dict:
191
+ """Classify the shape of an energy arc for user-facing explanation.
192
+
193
+ BUG-B13 fix: the old single-max-position classifier labeled
194
+ [0.7, 0.9, 0.9, 0.5, 0.6, 0.9, 0.4] (peaks at 1-2 AND 5) as
195
+ "front-loaded" because max()'s first occurrence is at index 1.
196
+ We now find ALL peaks above a dynamic threshold and classify by
197
+ count + distribution.
198
+
199
+ Returns {"shape": str, "peak_positions": list[int] | None}.
200
+ """
201
+ arc = [x for x in (arc or []) if x is not None]
202
+ if len(arc) < 3:
203
+ return {"shape": "short form — limited arc data", "peak_positions": None}
204
+
205
+ max_energy = max(arc)
206
+ arc_min = min(arc)
207
+ dynamic_mid = (arc_min + max_energy) / 2.0
208
+ peak_threshold = max(max_energy * 0.9, dynamic_mid)
209
+ peak_indices = [i for i, v in enumerate(arc) if v >= peak_threshold]
210
+
211
+ # Collapse runs of adjacent peak indices into their starting index —
212
+ # [1, 2, 5] has peaks at "position ~1" and "position 5", NOT three
213
+ # distinct peaks. Without this, front-loaded arcs where bars 0 and 1
214
+ # are both above threshold would misfire the dual-peak branch.
215
+ distinct_peaks: list[int] = []
216
+ for idx in peak_indices:
217
+ if not distinct_peaks or idx - distinct_peaks[-1] > 1:
218
+ distinct_peaks.append(idx)
219
+
220
+ n = len(arc)
221
+ first_third = {i for i in range(0, n // 3 + 1)}
222
+ last_third = {i for i in range(2 * n // 3, n)}
223
+ in_first = any(i in first_third for i in peak_indices)
224
+ in_last = any(i in last_third for i in peak_indices)
225
+ in_middle = any(
226
+ i not in first_third and i not in last_third
227
+ for i in peak_indices
228
+ )
229
+
230
+ # Plateau FIRST — when the dynamic range is narrow (<0.3) and most
231
+ # of the arc sits at/near the max, it's a plateau, not a multi-peak
232
+ # shape. Has to win over dual-peak so [0.7, 0.8, 0.8, 0.75, 0.8, …]
233
+ # doesn't get labeled "dual-peak at 2 and 6" when it's clearly flat.
234
+ if len(peak_indices) >= max(n - 2, 2) and (
235
+ max_energy - arc_min < 0.3
236
+ ):
237
+ shape = "plateau — sustained energy with limited dynamic range"
238
+ # Multi-peak: at least 2 DISTINCT peaks (after collapsing adjacent runs),
239
+ # separated by >= n/3 positions. Adjacent peaks are a single plateau, not two.
240
+ elif len(distinct_peaks) >= 2 and (
241
+ max(distinct_peaks) - min(distinct_peaks) >= max(n // 3, 2)
242
+ ):
243
+ shape = (
244
+ f"dual-peak — energy peaks at positions "
245
+ f"{distinct_peaks[0]+1} and {distinct_peaks[-1]+1}"
246
+ )
247
+ elif in_first and not in_middle and not in_last:
248
+ shape = "front-loaded — peaks early"
249
+ elif in_last and not in_first and not in_middle:
250
+ shape = "slow burn — builds to late peak"
251
+ elif in_middle and not in_first and not in_last:
252
+ shape = "centered arc — peaks in the middle"
253
+ else:
254
+ shape = (
255
+ f"mixed — peaks at positions "
256
+ f"{', '.join(str(i+1) for i in peak_indices)}"
257
+ )
258
+ return {"shape": shape, "peak_positions": peak_indices}
259
+
260
+
190
261
  @mcp.tool()
191
262
  def explain_song_identity(ctx: Context) -> dict:
192
263
  """Explain the current song's identity in human musical language.
@@ -228,20 +299,13 @@ def explain_song_identity(ctx: Context) -> dict:
228
299
  for s in brain.section_purposes
229
300
  ]
230
301
 
231
- # Energy shape
302
+ # Energy shape — BUG-B13 fix: dual-peak detection. See
303
+ # classify_energy_shape() for logic.
232
304
  if brain.energy_arc:
233
- arc = brain.energy_arc
234
- if len(arc) >= 3:
235
- peak_idx = arc.index(max(arc))
236
- peak_pct = peak_idx / max(len(arc) - 1, 1)
237
- if peak_pct < 0.3:
238
- explanation["energy_shape"] = "front-loaded — peaks early"
239
- elif peak_pct > 0.7:
240
- explanation["energy_shape"] = "slow burn — builds to late peak"
241
- else:
242
- explanation["energy_shape"] = "centered arc — peaks in the middle"
243
- else:
244
- explanation["energy_shape"] = "short form — limited arc data"
305
+ shape_info = classify_energy_shape(brain.energy_arc)
306
+ explanation["energy_shape"] = shape_info["shape"]
307
+ if shape_info["peak_positions"] is not None:
308
+ explanation["peak_positions"] = shape_info["peak_positions"]
245
309
 
246
310
  # Open questions
247
311
  if brain.open_questions:
@@ -195,6 +195,46 @@ def _fetch_sound_design_data(ctx: Context, track_index: int) -> dict:
195
195
  }
196
196
 
197
197
 
198
+ # BUG-B35: some roles are SUPPOSED to be simple. A kick, snare, or sub-bass
199
+ # patch with one block + a saturator is textbook electronic drum design —
200
+ # not "weak identity". Gate the "too_few_blocks" + "no_modulation_sources"
201
+ # critics on track role so we don't pester users about their perfectly
202
+ # serviceable DS Kick patches.
203
+ _SIMPLE_ROLE_TOKENS = (
204
+ "kick", "snare", "clap", "rim", "hat", "hihat", "hi-hat",
205
+ "drum", "drums", "perc", "percussion", "conga", "shaker",
206
+ "tambourine", "cowbell", "tom", "crash", "ride", "cymbal",
207
+ "808", "sub", "sub bass", "sub_bass",
208
+ )
209
+
210
+
211
+ def _is_simple_role_track(track_name: str) -> bool:
212
+ """True when the track name matches a role where simple patches are
213
+ the correct creative choice (kick/snare/drums/sub)."""
214
+ if not track_name:
215
+ return False
216
+ lowered = str(track_name).lower()
217
+ return any(tok in lowered for tok in _SIMPLE_ROLE_TOKENS)
218
+
219
+
220
+ _ROLE_SUPPRESSIBLE_ISSUES = frozenset({
221
+ "too_few_blocks",
222
+ "no_modulation_sources",
223
+ })
224
+
225
+
226
+ def _filter_role_appropriate_issues(
227
+ issues: list,
228
+ track_name: str,
229
+ ) -> list:
230
+ """Drop issues whose type is in _ROLE_SUPPRESSIBLE_ISSUES when the
231
+ track role (inferred from name) is one where simplicity is expected.
232
+ Issues pass through unchanged for pad / lead / synth / bass roles."""
233
+ if not _is_simple_role_track(track_name):
234
+ return issues
235
+ return [i for i in issues if i.issue_type not in _ROLE_SUPPRESSIBLE_ISSUES]
236
+
237
+
198
238
  # ── MCP Tools ────────────────────────────────────────────────────────
199
239
 
200
240
 
@@ -217,6 +257,10 @@ def analyze_sound_design(ctx: Context, track_index: int) -> dict:
217
257
  layers=layers,
218
258
  )
219
259
  issues = run_all_sound_design_critics(state)
260
+ # BUG-B35: gate role-sensitive critics by track name
261
+ issues = _filter_role_appropriate_issues(
262
+ issues, data["track_info"].get("name", "")
263
+ )
220
264
  moves = plan_sound_design_moves(issues, state)
221
265
 
222
266
  return {
@@ -246,6 +290,9 @@ def get_sound_design_issues(ctx: Context, track_index: int) -> dict:
246
290
  layers=layers,
247
291
  )
248
292
  issues = run_all_sound_design_critics(state)
293
+ issues = _filter_role_appropriate_issues(
294
+ issues, data["track_info"].get("name", "")
295
+ )
249
296
 
250
297
  return {
251
298
  "issues": [i.to_dict() for i in issues],
@@ -260,6 +307,11 @@ def plan_sound_design_move(ctx: Context, track_index: int) -> dict:
260
307
  Runs critics and planner, returns sorted moves with
261
308
  estimated impact and risk scores.
262
309
 
310
+ BUG-B36 fix: when zero sound-design issues but sibling mix/
311
+ composition engines flag problems on the same track, returns a
312
+ `cross_engine_hint` pointing the user to the right tool instead
313
+ of silently reporting empty.
314
+
263
315
  Args:
264
316
  track_index: Index of the track to analyze.
265
317
  """
@@ -272,14 +324,73 @@ def plan_sound_design_move(ctx: Context, track_index: int) -> dict:
272
324
  layers=layers,
273
325
  )
274
326
  issues = run_all_sound_design_critics(state)
327
+ issues = _filter_role_appropriate_issues(
328
+ issues, data["track_info"].get("name", "")
329
+ )
275
330
  moves = plan_sound_design_moves(issues, state)
276
331
 
277
- return {
332
+ result: dict = {
278
333
  "moves": [m.to_dict() for m in moves],
279
334
  "move_count": len(moves),
280
335
  "issue_count": len(issues),
281
336
  }
282
337
 
338
+ # BUG-B36: when nothing to do on the sound-design side, probe sibling
339
+ # engines for issues on this track and emit a discoverability hint.
340
+ if not moves:
341
+ cross_hint = _cross_engine_hint_for_track(ctx, track_index)
342
+ if cross_hint:
343
+ result["cross_engine_hint"] = cross_hint
344
+
345
+ return result
346
+
347
+
348
+ def _cross_engine_hint_for_track(
349
+ ctx: Context, track_index: int,
350
+ ) -> Optional[str]:
351
+ """Look at mix issues for this track and emit a hint pointing to
352
+ the right sibling tool when sound-design has nothing to say.
353
+
354
+ Best-effort — any failure returns None so plan_sound_design_move
355
+ never breaks on telemetry hiccups. Calls into the mix-engine's
356
+ pure function directly (not an MCP round-trip) to avoid the
357
+ one-client-per-port contention.
358
+ """
359
+ try:
360
+ from ..mix_engine.critics import run_all_mix_critics
361
+ from ..mix_engine.state_builder import build_mix_state
362
+ from ..mix_engine.tools import _fetch_mix_data
363
+ data = _fetch_mix_data(ctx)
364
+ mix_state = build_mix_state(
365
+ session_info=data.get("session_info", {}),
366
+ track_infos=data.get("track_infos", []),
367
+ spectrum=data.get("spectrum"),
368
+ rms_data=data.get("rms_data"),
369
+ )
370
+ mix_issues = run_all_mix_critics(mix_state)
371
+ except Exception:
372
+ return None
373
+
374
+ if not mix_issues:
375
+ return None
376
+ track_issues = [
377
+ i for i in mix_issues
378
+ if getattr(i, "track_index", None) == track_index
379
+ ]
380
+ if not track_issues:
381
+ return None
382
+ top = max(
383
+ track_issues,
384
+ key=lambda i: float(getattr(i, "severity", 0) or 0),
385
+ )
386
+ issue_type = str(getattr(top, "issue_type", None) or getattr(top, "type", "issue"))
387
+ sev = float(getattr(top, "severity", 0) or 0)
388
+ return (
389
+ f"No sound-design issues on this track, but mix critic flagged "
390
+ f"'{issue_type}' (severity {sev:.2f}). "
391
+ f"Try plan_mix_move for the same track_index."
392
+ )
393
+
283
394
 
284
395
  @mcp.tool()
285
396
  def get_patch_model(ctx: Context, track_index: int) -> dict:
@@ -20,14 +20,30 @@ def detect_stuckness(
20
20
  session_info: Optional[dict] = None,
21
21
  song_brain: Optional[dict] = None,
22
22
  section_count: int = 0,
23
+ state_signals: Optional[dict] = None,
23
24
  ) -> StucknessReport:
24
25
  """Detect whether the session is stuck.
25
26
 
26
27
  Analyzes action history for repeated undos, local tweaking,
27
28
  long loops without structural edits, and other stuckness signals.
29
+
30
+ BUG-B6 / B20 fix: also accepts `state_signals` — a dict of
31
+ current-session-state indicators that may reveal stuckness even
32
+ when the action ledger is empty. Known keys (all optional):
33
+ fatigue_level: float 0-1 (from detect_repetition_fatigue)
34
+ motif_overuse_count: int (motifs exceeding overuse threshold)
35
+ emotional_arc_issues: list of issue-type strings
36
+ transition_issues: int
37
+ support_too_loud: bool (from analyze_mix)
38
+ automation_density: float (0 = no clip automation anywhere)
39
+
40
+ When state_signals are provided, they contribute to confidence
41
+ alongside ledger-based signals (ledger weighting is still
42
+ dominant — ledger signals indicate active-user-is-stuck behavior).
28
43
  """
29
44
  session_info = session_info or {}
30
45
  song_brain = song_brain or {}
46
+ state_signals = state_signals or {}
31
47
  signals: list[StucknessSignal] = []
32
48
 
33
49
  # 1. Repeated undos
@@ -60,6 +76,10 @@ def detect_stuckness(
60
76
  if identity_signal:
61
77
  signals.append(identity_signal)
62
78
 
79
+ # 7. BUG-B6 / B20 — state critics
80
+ state_derived = _state_signals_to_signal_list(state_signals)
81
+ signals.extend(state_derived)
82
+
63
83
  # Compute overall confidence
64
84
  if not signals:
65
85
  return StucknessReport(confidence=0.0, level="flowing")
@@ -98,6 +118,76 @@ def detect_stuckness(
98
118
  # ── Signal checkers ───────────────────────────────────────────────
99
119
 
100
120
 
121
+ def _state_signals_to_signal_list(state: dict) -> list[StucknessSignal]:
122
+ """Convert a state_signals dict (from sibling critics) into
123
+ StucknessSignal entries. BUG-B6 / B20: previously the detector
124
+ ignored session state entirely — so a session with fatigue_level=0.93
125
+ but an empty action ledger always reported "flowing". Now we surface
126
+ state-based stuckness but keep the signals at a slightly lower
127
+ weight than ledger signals (ledger = active-user-is-stuck behavior,
128
+ state = project-shape-is-stuck).
129
+ """
130
+ out: list[StucknessSignal] = []
131
+ if not state:
132
+ return out
133
+
134
+ # Fatigue / repetition
135
+ fatigue = state.get("fatigue_level")
136
+ if isinstance(fatigue, (int, float)) and fatigue >= 0.6:
137
+ out.append(StucknessSignal(
138
+ signal_type="state_repetition_fatigue",
139
+ # Scale from 0.6-1.0 → 0.5-0.85 (sub-ledger weight)
140
+ strength=min(0.85, 0.5 + (fatigue - 0.6) * 0.875),
141
+ evidence=(
142
+ f"repetition fatigue at {fatigue:.2f} — clips/sections "
143
+ f"overused"
144
+ ),
145
+ ))
146
+
147
+ motif_overuse = state.get("motif_overuse_count", 0)
148
+ if isinstance(motif_overuse, int) and motif_overuse >= 3:
149
+ out.append(StucknessSignal(
150
+ signal_type="state_motif_overuse",
151
+ strength=min(0.7, 0.3 + motif_overuse * 0.1),
152
+ evidence=f"{motif_overuse} motifs flagged as overused",
153
+ ))
154
+
155
+ arc_issues = state.get("emotional_arc_issues") or []
156
+ if isinstance(arc_issues, (list, tuple)) and arc_issues:
157
+ out.append(StucknessSignal(
158
+ signal_type="state_emotional_arc",
159
+ strength=min(0.7, 0.3 + len(arc_issues) * 0.1),
160
+ evidence=(
161
+ f"emotional-arc issues: {', '.join(str(i) for i in arc_issues[:3])}"
162
+ ),
163
+ ))
164
+
165
+ transition_issues = state.get("transition_issues", 0)
166
+ if isinstance(transition_issues, int) and transition_issues >= 3:
167
+ out.append(StucknessSignal(
168
+ signal_type="state_transition_issues",
169
+ strength=min(0.7, 0.25 + transition_issues * 0.08),
170
+ evidence=f"{transition_issues} transition issues detected",
171
+ ))
172
+
173
+ if state.get("support_too_loud"):
174
+ out.append(StucknessSignal(
175
+ signal_type="state_mix_imbalance",
176
+ strength=0.35,
177
+ evidence="mix critic flagged a support element as too loud",
178
+ ))
179
+
180
+ auto_density = state.get("automation_density")
181
+ if isinstance(auto_density, (int, float)) and auto_density <= 0.05:
182
+ out.append(StucknessSignal(
183
+ signal_type="state_no_automation",
184
+ strength=0.35,
185
+ evidence="no clip automation detected — arrangement is static",
186
+ ))
187
+
188
+ return out
189
+
190
+
101
191
  def _check_repeated_undos(history: list[dict]) -> Optional[StucknessSignal]:
102
192
  """Check for repeated undone moves (kept=False in ledger entries)."""
103
193
  recent = history[-20:] if len(history) > 20 else history
@@ -62,6 +62,43 @@ def _get_session_and_brain(ctx: Context) -> tuple[dict, dict, int]:
62
62
  return session_info, song_brain, section_count
63
63
 
64
64
 
65
+ def _gather_state_signals(ctx: Context, song_brain: dict) -> dict:
66
+ """BUG-B6 / B20: collect current-session-state stuckness indicators
67
+ that the detector can merge with ledger-based signals.
68
+
69
+ All lookups are best-effort — if a sibling module isn't available
70
+ or its data is stale, we omit the signal (don't guess).
71
+ """
72
+ signals: dict = {}
73
+
74
+ # Repetition fatigue from musical_intelligence.detectors
75
+ try:
76
+ from ..musical_intelligence.tools import _current_fatigue_cache # type: ignore
77
+ if isinstance(_current_fatigue_cache, dict):
78
+ fl = _current_fatigue_cache.get("fatigue_level")
79
+ if isinstance(fl, (int, float)):
80
+ signals["fatigue_level"] = float(fl)
81
+ overuse = _current_fatigue_cache.get("motif_overuse_count")
82
+ if isinstance(overuse, int):
83
+ signals["motif_overuse_count"] = overuse
84
+ except Exception as exc:
85
+ logger.debug("_gather_state_signals fatigue fetch failed: %s", exc)
86
+
87
+ # Emotional-arc issues directly from song brain (already fetched)
88
+ arc_issues = []
89
+ if isinstance(song_brain, dict):
90
+ oqs = song_brain.get("open_questions") or []
91
+ for q in oqs:
92
+ if isinstance(q, dict):
93
+ qtype = q.get("question_type") or q.get("type") or ""
94
+ if "arc" in str(qtype).lower() or "payoff" in str(qtype).lower():
95
+ arc_issues.append(qtype)
96
+ if arc_issues:
97
+ signals["emotional_arc_issues"] = arc_issues
98
+
99
+ return signals
100
+
101
+
65
102
  @mcp.tool()
66
103
  def detect_stuckness(ctx: Context) -> dict:
67
104
  """Detect whether the session is losing momentum.
@@ -79,12 +116,14 @@ def detect_stuckness(ctx: Context) -> dict:
79
116
  """
80
117
  history = _get_action_history(ctx)
81
118
  session_info, song_brain, section_count = _get_session_and_brain(ctx)
119
+ state_signals = _gather_state_signals(ctx, song_brain)
82
120
 
83
121
  report = detector.detect_stuckness(
84
122
  action_history=history,
85
123
  session_info=session_info,
86
124
  song_brain=song_brain,
87
125
  section_count=section_count,
126
+ state_signals=state_signals,
88
127
  )
89
128
 
90
129
  return report.to_dict()
@@ -110,12 +149,14 @@ def suggest_momentum_rescue(
110
149
 
111
150
  history = _get_action_history(ctx)
112
151
  session_info, song_brain, section_count = _get_session_and_brain(ctx)
152
+ state_signals = _gather_state_signals(ctx, song_brain)
113
153
 
114
154
  report = detector.detect_stuckness(
115
155
  action_history=history,
116
156
  session_info=session_info,
117
157
  song_brain=song_brain,
118
158
  section_count=section_count,
159
+ state_signals=state_signals,
119
160
  )
120
161
 
121
162
  if report.level == "flowing":
@@ -37,6 +37,30 @@ def run_sonic_critic(
37
37
  peak = sonic.get("peak")
38
38
  target_dims = set(goal.targets.keys())
39
39
 
40
+ # BUG-B42: if every spectrum band is zero AND rms is zero, playback
41
+ # is stopped (or nothing is routing to master). Spectrum-based
42
+ # critics (weak_foundation, harsh_highs, low_mid_congestion, etc.)
43
+ # would fire on zero data, reporting "no bass!" when the real cause
44
+ # is "no audio". Short-circuit to a playback_required advisory so
45
+ # callers don't chase phantom mix issues during static inspection.
46
+ _all_bands = all(float(bands.get(b, 0) or 0) == 0 for b in
47
+ ("sub", "low", "low_mid", "mid", "high_mid", "high",
48
+ "presence", "air"))
49
+ _silent = _all_bands and (rms is None or float(rms or 0) == 0)
50
+ if _silent:
51
+ return [Issue(
52
+ type="playback_required",
53
+ critic="sonic",
54
+ severity=0.1,
55
+ confidence=1.0,
56
+ affected_dimensions=list(MEASURABLE_PROXIES.keys()),
57
+ evidence=["spectrum and RMS both zero — playback stopped or no signal"],
58
+ recommended_actions=[
59
+ "Start playback before calling build_world_model / "
60
+ "analyze_mix so spectrum-based critics can evaluate.",
61
+ ],
62
+ )]
63
+
40
64
  # 1. Mud detection: low_mid congestion
41
65
  low_mid = bands.get("low_mid", 0)
42
66
  if low_mid > 0.7 and {"clarity", "weight", "warmth"} & target_dims: