livepilot 1.10.7 → 1.10.9

package/mcp_server/semantic_moves/tools.py

@@ -107,16 +107,137 @@ def preview_semantic_move(
     return result
 
 
+def _build_taste_context(ctx: Context) -> dict:
+    """Pull the active taste graph for ranking, with defensive fallbacks.
+
+    Returns a dict with ``dimension_weights``, ``dimension_avoidances``,
+    ``move_family_scores`` (family → score), and ``evidence_count``.
+    Empty dicts when no taste has been recorded yet — the ranker then
+    collapses to pure keyword matching, which is the correct behavior for
+    a cold-start user with no history.
+    """
+    try:
+        from ..memory.taste_graph import build_taste_graph
+        from ..memory.taste_memory import TasteMemoryStore
+        from ..memory.anti_memory import AntiMemoryStore
+
+        taste_store = ctx.lifespan_context.setdefault("taste_memory", TasteMemoryStore())
+        anti_store = ctx.lifespan_context.setdefault("anti_memory", AntiMemoryStore())
+        graph = build_taste_graph(taste_store=taste_store, anti_store=anti_store)
+
+        move_family_scores: dict[str, float] = {}
+        for family, entry in getattr(graph, "move_family_scores", {}).items():
+            score = getattr(entry, "score", None)
+            if isinstance(score, (int, float)):
+                move_family_scores[family] = float(score)
+
+        return {
+            "dimension_weights": dict(getattr(graph, "dimension_weights", {}) or {}),
+            "dimension_avoidances": dict(getattr(graph, "dimension_avoidances", {}) or {}),
+            "move_family_scores": move_family_scores,
+            "evidence_count": int(getattr(graph, "evidence_count", 0) or 0),
+        }
+    except Exception as exc:
+        logger.debug("_build_taste_context failed: %s", exc)
+        return {
+            "dimension_weights": {},
+            "dimension_avoidances": {},
+            "move_family_scores": {},
+            "evidence_count": 0,
+        }
+
+
+def _score_move_for_request(move, request_lower: str, request_words: set, taste: dict) -> tuple[float, dict]:
+    """Compute the composite score for a single move.
+
+    Composition:
+        0.55 × keyword overlap (intent + move_id + targets)
+        0.30 × taste alignment (from taste_graph.dimension_weights on move.targets)
+        0.15 × (1 - anti avoidance penalty) (from dimension_avoidances)
+
+        ± up to 0.10 family bonus/penalty from move_family_scores[family].
+
+    When the user has no recorded taste (evidence_count == 0), the taste
+    and anti-penalty components collapse to neutral 0.5 so cold-start
+    behavior stays identical to the old keyword-only ranker.
+    """
+    # ── Keyword overlap component (0..1) ──────────────────────────────
+    intent_lower = move.intent.lower()
+    move_words = set(move.move_id.replace("_", " ").split())
+    intent_words = set(intent_lower.split())
+
+    overlap = request_words & (move_words | intent_words)
+    keyword_score = min(1.0, len(overlap) * 0.3)
+
+    for dim in move.targets:
+        if dim.lower() in request_lower:
+            keyword_score = min(1.0, keyword_score + 0.2)
+
+    if move.move_id.replace("_", " ") in request_lower:
+        keyword_score = 1.0
+
+    # ── Taste alignment component (0..1) ──────────────────────────────
+    evidence_count = taste["evidence_count"]
+    dim_weights = taste["dimension_weights"]
+    dim_avoid = taste["dimension_avoidances"]
+
+    if evidence_count > 0 and move.targets:
+        # Average dimension_weights for this move's targets; weights are
+        # -1..1 with 0 meaning unknown. Remap to 0..1 so "neutral" is 0.5.
+        raw_taste = [
+            dim_weights.get(dim, 0.0) for dim in move.targets
+        ]
+        taste_alignment = sum((w + 1.0) / 2.0 for w in raw_taste) / len(raw_taste)
+        avoidance = sum(
+            dim_avoid.get(dim, 0.0) for dim in move.targets
+        ) / len(move.targets)
+        avoidance = max(0.0, min(1.0, avoidance))
+    else:
+        taste_alignment = 0.5
+        avoidance = 0.0
+
+    composite = (
+        0.55 * keyword_score
+        + 0.30 * taste_alignment
+        + 0.15 * (1.0 - avoidance)
+    )
+
+    # ── Family bonus/penalty (±0.1) ────────────────────────────────────
+    family_bonus = 0.0
+    family_score = taste["move_family_scores"].get(move.family)
+    if family_score is not None:
+        # family score is 0..1 with 0.5 neutral; remap to -0.1..+0.1
+        family_bonus = (family_score - 0.5) * 0.2
+        composite += family_bonus
+
+    composite = max(0.0, min(1.0, composite))
+
+    breakdown = {
+        "keyword_score": round(keyword_score, 3),
+        "taste_alignment": round(taste_alignment, 3),
+        "avoidance_penalty": round(avoidance, 3),
+        "family_bonus": round(family_bonus, 3),
+        "evidence_count": evidence_count,
+    }
+    return composite, breakdown
+
+
 @mcp.tool()
 def propose_next_best_move(
     ctx: Context,
     request_text: str,
     limit: int = 3,
 ) -> dict:
-    """Propose the best semantic moves for a natural language request.
+    """Propose the best semantic moves for a natural language request, ranked
+    by keyword fit AND the active taste graph.
 
-    Analyzes the request text and ranks available semantic moves by
-    relevance. Returns up to `limit` suggestions with confidence scores.
+    Shipped in v1.10.9: ranking is no longer pure keyword overlap — it now
+    blends keyword match with taste alignment (``dimension_weights`` on each
+    move's targets), an anti-preference penalty (``dimension_avoidances``),
+    and a small family bonus from ``move_family_scores``. Cold-start users
+    with zero recorded evidence get the same ranking as before; users with
+    history see recommendations pulled toward dimensions they've kept and
+    away from ones they've undone.
 
     request_text: what the user wants (e.g., "make this punchier",
                   "tighten the low end", "reduce repetition")
@@ -125,50 +246,37 @@ def propose_next_best_move(
     if not request_text.strip():
         return {"error": "request_text cannot be empty"}
 
-    # Simple keyword matching for now — will be replaced by conductor
-    # routing + taste ranking in V2 Step 7
     request_lower = request_text.lower()
+    request_words = set(request_lower.split())
+    taste = _build_taste_context(ctx)
     all_moves = list(registry._REGISTRY.values())
 
-    scored = []
+    scored: list[tuple[object, float, dict]] = []
     for move in all_moves:
-        score = 0.0
-        # Match keywords from intent and move_id
-        intent_lower = move.intent.lower()
-        move_words = set(move.move_id.replace("_", " ").split())
-        intent_words = set(intent_lower.split())
-        request_words = set(request_lower.split())
-
-        # Word overlap scoring
-        overlap = request_words & (move_words | intent_words)
-        score += len(overlap) * 0.3
-
-        # Dimension matching
-        for dim in move.targets:
-            if dim in request_lower:
-                score += 0.2
-
-        # Boost exact intent matches
-        if move.move_id.replace("_", " ") in request_lower:
-            score += 1.0
-
-        if score > 0:
-            scored.append((move, min(score, 1.0)))
-
-    # Sort by score descending
+        score, breakdown = _score_move_for_request(
+            move, request_lower, request_words, taste,
+        )
+        # Keep only moves that had any keyword signal or strong taste pull —
+        # a move with zero keyword overlap AND neutral taste would be noise.
+        if breakdown["keyword_score"] > 0 or taste["evidence_count"] >= 5:
+            scored.append((move, score, breakdown))
+
     scored.sort(key=lambda x: -x[1])
     top = scored[:limit]
 
     suggestions = []
-    for move, score in top:
+    for move, score, breakdown in top:
         d = move.to_dict()
         d["match_score"] = round(score, 3)
+        d["score_breakdown"] = breakdown
         suggestions.append(d)
 
     return {
         "request": request_text,
         "suggestions": suggestions,
         "count": len(suggestions),
+        "taste_active": taste["evidence_count"] > 0,
+        "taste_evidence_count": taste["evidence_count"],
     }
 
 
@@ -229,10 +337,21 @@ async def apply_semantic_move(
     # explore mode — execute through the async router
     from ..runtime.execution_router import execute_plan_steps_async
 
-    step_dicts = [
-        {"tool": step.tool, "params": step.params, "description": step.description}
-        for step in plan.steps
-    ]
+    # Propagate the optional backend annotation through to the router so a
+    # compiler that's certain about a step's backend (e.g. bridge_command for
+    # capture_audio) can short-circuit classify_step(). Steps without backend
+    # fall back to the classifier as before.
+    def _step_to_dict(step):
+        d = {
+            "tool": step.tool,
+            "params": step.params,
+            "description": step.description,
+        }
+        if getattr(step, "backend", None):
+            d["backend"] = step.backend
+        return d
+
+    step_dicts = [_step_to_dict(step) for step in plan.steps]
     bridge = ctx.lifespan_context.get("m4l")
     mcp_registry = ctx.lifespan_context.get("mcp_dispatch", {})
     exec_results = await execute_plan_steps_async(

package/mcp_server/server.py

@@ -2,6 +2,7 @@
 
 from contextlib import asynccontextmanager
 import asyncio
+import logging
 import os
 import subprocess
 
@@ -10,6 +11,12 @@ from fastmcp import FastMCP, Context  # noqa: F401
 from .connection import AbletonConnection
 from .m4l_bridge import SpectralCache, SpectralReceiver, M4LBridge
 
+# Logger must be defined before any function uses it — several module-level
+# helpers below (e.g. _master_has_livepilot_analyzer) call logger.debug on
+# the import-time code path, so defining logger later raised NameError when
+# those helpers fired from a tool module's module-level init.
+logger = logging.getLogger(__name__)
+
 
 def _identify_port_holder(port: int) -> str | None:
     """Identify which process holds the given UDP port (for logging only).
@@ -137,6 +144,28 @@ async def _warm_analyzer_bridge(
         await asyncio.sleep(0.05)
 
 
+def _bind_session_continuity(ableton: AbletonConnection) -> None:
+    """Hydrate the session-continuity tracker from persistent per-project state.
+
+    Fetches a minimal session fingerprint (tempo, signature, track/scene
+    layout) from the Remote Script, computes a project hash, and asks the
+    tracker to bind the matching ProjectStore + restore any previously-saved
+    creative threads and turn resolutions from disk.
+
+    Never raises: startup must succeed even if Ableton isn't reachable. In
+    that case, the tracker stays in-memory and the first ``record_turn_*`` /
+    ``open_thread`` call will lazy-bind via ``ensure_project_store_bound()``.
+    """
+    try:
+        from .session_continuity.tracker import bind_project_store_from_session
+
+        info = ableton.send_command("get_session_info")
+        if isinstance(info, dict) and not info.get("error"):
+            bind_project_store_from_session(info)
+    except Exception as exc:
+        logger.debug("_bind_session_continuity: lazy-bind (reason: %s)", exc)
+
+
 @asynccontextmanager
 async def lifespan(server):
     """Create and yield the shared AbletonConnection + M4L bridge + registries."""
@@ -196,6 +225,12 @@ async def lifespan(server):
         _check_remote_script_version(ableton)
         if bridge_state["transport"] is not None:
             await _warm_analyzer_bridge(ableton, spectral)
+        # Bind per-project persistent store so creative threads and turn
+        # history survive server restarts. Until v1.10.9 this was plumbed
+        # through the tracker but never called — threads/turns were effectively
+        # in-memory only. If Ableton isn't reachable yet, tools will lazy-bind
+        # on first write via ensure_project_store_bound().
+        _bind_session_continuity(ableton)
         yield {
             "ableton": ableton,
             "spectral": spectral,
@@ -264,9 +299,6 @@ from .device_forge import tools as device_forge_tools          # noqa: F401, E40
 from .sample_engine import tools as sample_engine_tools        # noqa: F401, E402
 from .atlas import tools as atlas_tools                        # noqa: F401, E402
 from .composer import tools as composer_tools                  # noqa: F401, E402
-import logging
-
-logger = logging.getLogger(__name__)
 
 # ---------------------------------------------------------------------------
 # Schema coercion patch — accept strings for numeric parameters
@@ -308,28 +340,125 @@ def _coerce_schema_property(prop: dict) -> None:
 
 
 def _get_all_tools():
-    """Get all registered tools, compatible with FastMCP 0.x and 3.x.
-
-    WARNING: Accesses FastMCP private internals (_tool_manager, _local_provider).
-    Pinned to fastmcp>=3.0.0,<3.3.0 in requirements.txt. If upgrading FastMCP,
-    verify these attributes still exist or update this function.
+    """Get all registered tools — defends against FastMCP internal drift.
+
+    FastMCP's public API doesn't expose the registry as of 3.2.x (see
+    docs/FASTMCP_UPSTREAM_FR.md). Until it does, we probe known internal
+    attribute paths. Each probe fires in try/except so a structural
+    rearrangement (e.g. ``_components`` renamed under 3.3+) falls through
+    to the next path rather than exploding.
+
+    WARNING: Accesses FastMCP private internals. Pinned to
+    fastmcp>=3.0.0,<3.3.0 in requirements.txt. The startup self-test
+    (_assert_tool_registry_accessible) will fail loudly if every probe
+    returns empty — better than silently returning [] and disabling
+    schema coercion.
     """
-    # FastMCP 0.x: mcp._tool_manager._tools (dict of name -> Tool)
-    if hasattr(mcp, "_tool_manager"):
-        return list(mcp._tool_manager._tools.values())
-    # FastMCP 3.x: mcp._local_provider._components (dict of key -> Tool)
-    if hasattr(mcp, "_local_provider") and hasattr(mcp._local_provider, "_components"):
-        return list(mcp._local_provider._components.values())
+    probes = [
+        # FastMCP 0.x: mcp._tool_manager._tools (dict of name -> Tool)
+        ("_tool_manager._tools", lambda: list(mcp._tool_manager._tools.values())),
+        # FastMCP 3.0–3.2: mcp._local_provider._components
+        (
+            "_local_provider._components",
+            lambda: list(mcp._local_provider._components.values()),
+        ),
+        # FastMCP 3.3+ speculative: mcp._local_provider._tools (anticipated
+        # rename based on naming conventions in other providers). Kept here
+        # so a future bump surfaces a partial match rather than a full miss.
+        (
+            "_local_provider._tools",
+            lambda: list(mcp._local_provider._tools.values()),
+        ),
+        # Public-API future path (what we're asking for in the upstream FR);
+        # harmless to probe now so that once it ships we can lift the ceiling
+        # without touching this function again.
+        ("list_tools", lambda: list(mcp.list_tools())),
+    ]
+    for label, fn in probes:
+        try:
+            tools = fn()
+        except (AttributeError, TypeError):
+            continue
+        except Exception:  # noqa: BLE001 — any error from an internal probe means "skip"
+            continue
+        if tools:
+            return tools
+
+    # All probes empty. Surface fastmcp version + attempted paths so the
+    # breakage is diagnosable without re-reading the code.
     import sys
-
+    try:
+        import fastmcp as _fm
+        fm_version = getattr(_fm, "__version__", "unknown")
+    except Exception:  # noqa: BLE001
+        fm_version = "unknown"
     print(
-        "LivePilot: WARNING — could not access FastMCP tool registry, "
-        "string-to-number schema coercion will not work",
+        "LivePilot: ERROR — could not access FastMCP tool registry "
+        f"(fastmcp=={fm_version}). Tried: "
+        + ", ".join(label for label, _ in probes)
+        + ". Schema coercion and tool-catalog generation will be broken. "
+        "If FastMCP updated its internals, see docs/FASTMCP_UPSTREAM_FR.md.",
         file=sys.stderr,
     )
     return []
 
 
+def _assert_tool_registry_accessible() -> None:
+    """Loudly fail startup if the FastMCP registry probe returns nothing.
+
+    Called once at module import, just before schema patching. The schema
+    patch silently no-ops on an empty registry, so without this assertion
+    a FastMCP-internals rename would degrade silently and produce a server
+    with 324 tools but no string-to-number coercion — a subtle, hard-to-
+    diagnose class of failure we've paid for once already.
+
+    Reads the expected count from ``tests/test_tools_contract.py`` (same
+    source of truth sync_metadata.py uses), so no second magic number.
+    """
+    import re
+    import sys
+
+    try:
+        contract_src = (
+            (__file__.rsplit("/", 2)[0] + "/tests/test_tools_contract.py")
+            if "__file__" in globals() else None
+        )
+        # Prefer an absolute path via Path for reliability:
+        from pathlib import Path
+        contract_path = Path(__file__).resolve().parents[1] / "tests" / "test_tools_contract.py"
+        expected = None
+        if contract_path.exists():
+            match = re.search(
+                r"assert len\(tools\) == (\d+)",
+                contract_path.read_text(encoding="utf-8"),
+            )
+            if match:
+                expected = int(match.group(1))
+    except Exception:  # noqa: BLE001 — self-test must not block startup
+        expected = None
+
+    actual = len(_get_all_tools())
+    if actual == 0:
+        # Registry probe returned empty — this is the regression the test guards.
+        # Don't sys.exit (some test harnesses import server.py without a live
+        # FastMCP); print a loud diagnostic and let downstream code react.
+        print(
+            "LivePilot: STARTUP SELF-TEST FAILED — _get_all_tools() returned 0. "
+            "FastMCP internals likely changed. Verify requirements.txt pin "
+            "(fastmcp>=3.0.0,<3.3.0) matches the installed version.",
+            file=sys.stderr,
+        )
+        return
+    if expected is not None and actual != expected:
+        print(
+            f"LivePilot: STARTUP SELF-TEST WARNING — _get_all_tools() "
+            f"returned {actual} tools, tests/test_tools_contract.py expects "
+            f"{expected}. If you've added/removed tools, update the contract "
+            "and run scripts/sync_metadata.py --fix.",
+            file=sys.stderr,
+        )
+
+
 def _patch_tool_schemas() -> None:
     """Post-process all registered tool schemas for string coercion."""
     for tool in _get_all_tools():
@@ -342,6 +471,7 @@ def _patch_tool_schemas() -> None:
             if isinstance(definition, dict):
                 _coerce_schema_property(definition)
 
+_assert_tool_registry_accessible()
 _patch_tool_schemas()
 
 

package/mcp_server/services/singletons.py

@@ -0,0 +1,68 @@
+"""Thread-safe singleton helpers.
+
+The server has several subsystems (atlas, corpus, sample-engine indexes)
+that are loaded lazily into module-level globals via a check-then-set
+pattern. Under FastMCP's async concurrency that pattern races: two
+handlers can both observe ``None`` and both construct the (expensive)
+object. Most of the time the GIL hides the race, but when it doesn't you
+get redundant I/O and, worse, one thread's half-parsed state overwriting
+the other's completed state.
+
+This module provides a small helper that wraps a factory in a lock and
+optionally tracks an on-disk mtime for cache invalidation. Use it in
+place of hand-rolled ``_instance = None`` patterns.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from threading import Lock
+from typing import Callable, TypeVar
+
+T = TypeVar("T")
+
+
+class Singleton:
+    """Lazy, thread-safe singleton with optional mtime-based reload.
+
+    Example:
+        atlas_holder = Singleton(_load_atlas)
+
+        def get_atlas():
+            return atlas_holder.get(reload_if_newer=atlas_path)
+
+        def on_atlas_rebuild():
+            atlas_holder.invalidate()
+    """
+
+    def __init__(self, factory: Callable[[], T]):
+        self._factory = factory
+        self._instance: T | None = None
+        self._mtime: float | None = None
+        self._lock = Lock()
+
+    def get(self, *, reload_if_newer: Path | None = None) -> T:
+        with self._lock:
+            if self._instance is None:
+                self._instance = self._factory()
+                if reload_if_newer is not None:
+                    try:
+                        self._mtime = reload_if_newer.stat().st_mtime
+                    except OSError:
+                        self._mtime = None
+                return self._instance
+
+            if reload_if_newer is not None:
+                try:
+                    current = reload_if_newer.stat().st_mtime
+                except OSError:
+                    return self._instance
+                if self._mtime is None or current > self._mtime:
+                    self._instance = self._factory()
+                    self._mtime = current
+            return self._instance
+
+    def invalidate(self) -> None:
+        """Discard the cached instance. Next .get() will re-run the factory."""
+        with self._lock:
+            self._instance = None
+            self._mtime = None

package/mcp_server/session_continuity/models.py

@@ -22,6 +22,13 @@ class CreativeThread:
     def to_dict(self) -> dict:
         return asdict(self)
 
+    @classmethod
+    def from_dict(cls, data: dict) -> "CreativeThread":
+        """Rehydrate from persisted dict; unknown keys are ignored so a future
+        schema bump won't break load on older on-disk state."""
+        allowed = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in data.items() if k in allowed})
+
     @property
     def is_stale(self) -> bool:
         """A thread is stale if untouched for >30 minutes."""
@@ -44,6 +51,12 @@ class TurnResolution:
     def to_dict(self) -> dict:
         return asdict(self)
 
+    @classmethod
+    def from_dict(cls, data: dict) -> "TurnResolution":
+        """Rehydrate from persisted dict; unknown keys are ignored."""
+        allowed = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in data.items() if k in allowed})
+
 
 @dataclass
 class SessionStory:

package/mcp_server/session_continuity/tools.py

@@ -65,6 +65,7 @@ def record_turn_resolution(
     identity_effect: "preserves", "evolves", "contrasts", or "resets"
     user_sentiment: "loved", "liked", "neutral", "disliked", or "hated"
     """
+    tracker.ensure_project_store_bound(ctx)
     turn = tracker.record_turn_resolution(
         request_text=request_text,
         outcome=outcome,
@@ -130,6 +131,7 @@ def open_creative_thread(
     if not description.strip():
         return {"error": "description cannot be empty"}
 
+    tracker.ensure_project_store_bound(ctx)
     thread = tracker.open_thread(description, domain=domain, priority=priority)
     return thread.to_dict()
 

package/mcp_server/session_continuity/tracker.py

@@ -44,6 +44,99 @@ def reset_story() -> None:
     _project_store = None
 
 
+def bind_project_store_from_session(session_info: dict) -> Optional[str]:
+    """Bind a per-project persistent store and hydrate in-memory state.
+
+    Computes a project fingerprint from ``session_info`` (tempo, time sig,
+    song length, track/scene/return layout), opens the matching
+    ``ProjectStore`` under ``~/.livepilot/projects/<hash>/``, and rehydrates
+    the in-memory ``_threads`` and ``_turns`` from disk so that restarting
+    the MCP server preserves the user's creative threads and turn history.
+
+    Returns the project_id (12-char hash) on success, ``None`` on failure
+    (so callers can log without aborting startup). If the hash hasn't
+    changed since the last bind, this is a no-op — hot path is safe to
+    call on every turn.
+
+    Without this function, ``set_project_store()`` existed but nobody
+    called it, meaning README's "return to a project with prior creative
+    threads intact" was literally false — threads/turns were in-memory
+    only and reset on every server restart.
+    """
+    global _threads, _turns, _project_store
+
+    try:
+        from ..persistence.project_store import ProjectStore, project_hash
+    except Exception as exc:
+        logger.debug("bind_project_store_from_session: import failed: %s", exc)
+        return None
+
+    try:
+        new_id = project_hash(session_info or {})
+    except Exception as exc:
+        logger.debug("bind_project_store_from_session: hash failed: %s", exc)
+        return None
+
+    # Already bound to this project? Nothing to do.
+    if _project_store is not None and getattr(_project_store, "project_id", None) == new_id:
+        return new_id
+
+    try:
+        store = ProjectStore(new_id)
+    except Exception as exc:
+        logger.debug("bind_project_store_from_session: store open failed: %s", exc)
+        return None
+
+    # Hydrate in-memory threads + turns from the persisted store. We only
+    # rebuild what the tracker keeps live — SessionStory is recomputed on
+    # each get_session_story() call, so it doesn't need a direct restore.
+    try:
+        raw_threads = store.get_threads()
+        raw_turns = store.get_turns()
+    except Exception as exc:
+        logger.debug("bind_project_store_from_session: read failed: %s", exc)
+        raw_threads, raw_turns = [], []
+
+    _threads = {
+        t["thread_id"]: CreativeThread.from_dict(t)
+        for t in raw_threads
+        if isinstance(t, dict) and "thread_id" in t
+    }
+    _turns = [
+        TurnResolution.from_dict(t)
+        for t in raw_turns
+        if isinstance(t, dict)
+    ]
+    _project_store = store
+    logger.info(
+        "session_continuity: bound project %s (%d threads, %d turns restored)",
+        new_id, len(_threads), len(_turns),
+    )
+    return new_id
+
+
+def ensure_project_store_bound(ctx) -> Optional[str]:
+    """Lazy bind on first use — for tools called before lifespan could reach Ableton.
+
+    ``ctx`` is a FastMCP Context; reads the ``ableton`` connection from
+    ``ctx.lifespan_context`` and fetches session info to compute the project
+    hash. Safe to call on every turn — if already bound to this project, it's
+    a no-op. Returns the project_id or ``None`` on failure.
+    """
+    if _project_store is not None:
+        return getattr(_project_store, "project_id", None)
+    try:
+        ableton = ctx.lifespan_context.get("ableton")
+        if ableton is None:
+            return None
+        info = ableton.send_command("get_session_info")
+        if isinstance(info, dict) and not info.get("error"):
+            return bind_project_store_from_session(info)
+    except Exception as exc:
+        logger.debug("ensure_project_store_bound: %s", exc)
+    return None
+
+
 # ── Session story ─────────────────────────────────────────────────