@meridiona/meridian-darwin-arm64 1.31.1 → 1.31.3

package/VERSION

@@ -1 +1 @@
-1.31.1
+1.31.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meridiona/meridian-darwin-arm64",
-  "version": "1.31.1",
+  "version": "1.31.3",
   "description": "Prebuilt Meridian app for macOS arm64 (daemon binary + dashboard + Python services). Installed via @meridiona/meridian.",
   "homepage": "https://github.com/Meridiona/meridian",
   "repository": {

package/scripts/install-tray-daemon.sh

@@ -6,14 +6,21 @@ set -euo pipefail
 IFS=$'\n\t'
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-TRAY_BIN="${REPO_ROOT}/target/release/meridian-tray"
-PLIST="${HOME}/Library/LaunchAgents/com.meridiona.tray.plist"
-
-if [[ ! -x "${TRAY_BIN}" ]]; then
-    echo "✗ meridian-tray binary not found at ${TRAY_BIN}" >&2
-    echo "  Build it first: cd tray && npm run build" >&2
+# Support both dev mode (target/release) and bundle mode (bin/)
+TRAY_BIN=""
+if [[ -x "${REPO_ROOT}/target/release/meridian-tray" ]]; then
+    # Dev mode: built locally to target/release
+    TRAY_BIN="${REPO_ROOT}/target/release/meridian-tray"
+elif [[ -x "${REPO_ROOT}/bin/meridian-tray" ]]; then
+    # Bundle mode: installed to ~/.meridian/app/bin
+    TRAY_BIN="${REPO_ROOT}/bin/meridian-tray"
+else
+    echo "✗ meridian-tray binary not found" >&2
+    echo "  Dev: build it with: cd tray && npm run tauri build" >&2
+    echo "  Bundle: already included via: meridian update" >&2
     exit 1
 fi
+PLIST="${HOME}/Library/LaunchAgents/com.meridiona.tray.plist"
 
 mkdir -p "$(dirname "${PLIST}")"
 

package/services/agents/README.md

@@ -252,6 +252,29 @@ Example: 28 GB headroom, `LLM_BUDGET_PCT=0.5` → budget = 14 GB → **phi-4** (
 
 When the screen is locked the selector uses `min(0.8, budget_pct × 1.5)` as the effective budget, allowing a larger model to load while the machine is idle.
 
+### In-process MLX model selection (`select_mlx_model_id`)
+
+`select_mlx_model_id` is called by the MLX server (`server.py`) at startup to pick which model to load directly into the process (via mlx_lm + outlines). It uses the same catalog but applies a three-stage priority:
+
+1. **Preferred fits** — return the caller-supplied `preferred_hf_id` if `preferred_min_ram_gb ≤ budget`. This keeps the eval-tuned classifier model on capable machines.
+2. **Largest cached model fits** — if the preferred is too large, return the largest catalog model whose files are already in the HF cache and whose `min_ram_gb ≤ budget`. Avoids surprising multi-GB downloads on constrained machines.
+3. **Largest catalog model that fits (may download)** — if nothing cached fits, return the largest catalog entry where `min_ram_gb ≤ budget`, regardless of cache. This triggers a one-time download of the best available model rather than loading an oversized one that exceeds available memory. Falls back to `preferred_hf_id` only when **no catalog model fits** at all (budget so low even the 1.8 GB model won't load).
+
+**Why stage 3 matters on low-RAM machines:** an M1 Air (8 GB) has Metal headroom ≈ 5.4 GB. At `LLM_BUDGET_PCT=0.5` the budget is ~2.7 GB. The default preferred model is 6.5 GB (`Qwen3.5-9B-OptiQ-4bit`). Without the fix, stage 3 returned the preferred unconditionally — the server then attempted to load a 6.5 GB model into a 2.7 GB budget, causing memory pressure or an outright load failure. With the fix, stage 3 selects `Qwen3.5-4B-MLX-4bit` (2.5 GB) or `Llama-3.2-3B-Instruct-4bit` (1.8 GB) — whichever is largest and fits — and downloads it on first use.
+
+**Check what would be selected:**
+
+```bash
+cd services
+.venv/bin/python -c "
+from agents.llm_selector import select_mlx_model_id, probe_compute
+snap = probe_compute()
+print(f'Headroom: {snap.metal_headroom_gb:.1f} GB  thermal: {snap.thermal_level}')
+model = select_mlx_model_id('mlx-community/Qwen3.5-9B-OptiQ-4bit', 6.5, 0.5)
+print(f'Would load: {model}')
+"
+```
+
 ### Persistent MLX server
 
 `_ensure_mlx_server()` manages a subprocess tracked in `~/.meridian/mlx_lm_server.pid` (JSON: pid, model, port). The model loads once and persists between `run_task_linker.py` invocations (which are fresh subprocesses each tick). If the budget changes and a different model is selected, the old server is killed and the new model loads automatically.

package/services/agents/llm_selector.py

@@ -991,13 +991,29 @@ def select_mlx_model_id(
             )
             return hf_id
 
-        # 3. Nothing cached fits and Apple Intelligence is unavailable (macOS < 26) —
-        #    best effort with the preferred id. (This preserves the pre-existing
-        #    single-model behaviour on older macOS; the load may trigger a download.)
-        span.set_attribute("llm.reason", "nothing_cached_fits_use_preferred")
+        # 3. Nothing cached fits and Apple Intelligence is unavailable (macOS < 26).
+        #    Pick the largest catalog model that fits the budget, ignoring the cache
+        #    (it will trigger a one-time download). This prevents returning an
+        #    oversized preferred model (e.g. 6.5 GB Qwen3.5-9B on an 8 GB machine
+        #    whose Metal budget is ~2.7 GB) that would exceed available memory.
+        #    Only fall back to preferred_hf_id when nothing in the catalog fits.
+        entry = _select_mlx_entry(snap.metal_headroom_gb, effective_pct,
+                                  snap.thermal_level, apple_intelligence)
+        if entry is not None:
+            _, _, min_ram, _, hf_id = entry
+            span.set_attribute("llm.reason", "catalog_fit_uncached")
+            span.set_attribute("llm.selected_model", hf_id or "")
+            log.warning(
+                "llm_selector: no cached MLX model fits budget=%.1f GB — "
+                "selecting %s (min_ram=%.1f GB fits; will download)",
+                budget, hf_id, min_ram,
+            )
+            return hf_id
+        span.set_attribute("llm.reason", "nothing_fits_use_preferred")
         span.set_attribute("llm.selected_model", preferred_hf_id or "")
         log.warning(
-            "llm_selector: no cached MLX model fits budget=%.1f GB — falling back to %s",
+            "llm_selector: no catalog model fits budget=%.1f GB — "
+            "last-resort fallback to preferred %s",
             budget, preferred_hf_id,
         )
         return preferred_hf_id

package/services/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "meridian-agents"
-version = "1.31.1"
+version = "1.31.3"
 description = "Meridian agents — hermes task linking and Jira progress updates for meridian.db"
 requires-python = ">=3.11"
 authors = [{ name = "Meridiona" }]

package/services/tests/test_llm_selector.py

@@ -0,0 +1,223 @@
+"""Tests for select_mlx_model_id in llm_selector.py.
+
+Covers the three-stage selection logic with focus on the low-RAM stage 3 fix:
+previously the function returned the oversized preferred model unconditionally
+when nothing cached fit; it now picks the largest catalog model that fits.
+"""
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_snap(headroom_gb: float, thermal_level: int = 0,
+               screen_locked: bool = False) -> MagicMock:
+    snap = MagicMock()
+    snap.metal_headroom_gb = headroom_gb
+    snap.thermal_level = thermal_level
+    snap.screen_locked = screen_locked
+    return snap
+
+
+# ---------------------------------------------------------------------------
+# Stage 1 — preferred fits
+# ---------------------------------------------------------------------------
+
+class TestStage1PreferredFits:
+    def test_returns_preferred_when_budget_allows(self):
+        """Stage 1: preferred model returned unchanged when budget covers it.
+
+        14.0 GB headroom × 0.5 = 7.0 GB budget ≥ 6.5 GB min_ram → stage 1 fires.
+        """
+        snap = _make_snap(headroom_gb=14.0)
+
+        with (
+            patch("agents.llm_selector.platform") as mock_platform,
+            patch("agents.llm_selector._sysctl", return_value="Apple M2 Pro"),
+            patch("agents.llm_selector._apple_intelligence_available", return_value=False),
+            patch("agents.llm_selector.probe_compute", return_value=snap),
+        ):
+            mock_platform.system.return_value = "Darwin"
+            from agents.llm_selector import select_mlx_model_id
+            result = select_mlx_model_id(
+                preferred_hf_id="mlx-community/Qwen3.5-9B-OptiQ-4bit",
+                preferred_min_ram_gb=6.5,
+                budget_pct=0.5,
+            )
+
+        assert result == "mlx-community/Qwen3.5-9B-OptiQ-4bit"
+
+    def test_returns_preferred_on_large_machine(self):
+        """Stage 1: 64 GB machine, preferred (6.5 GB) trivially fits."""
+        snap = _make_snap(headroom_gb=50.0)
+
+        with (
+            patch("agents.llm_selector.platform") as mock_platform,
+            patch("agents.llm_selector._sysctl", return_value="Apple M2 Ultra"),
+            patch("agents.llm_selector._apple_intelligence_available", return_value=False),
+            patch("agents.llm_selector.probe_compute", return_value=snap),
+        ):
+            mock_platform.system.return_value = "Darwin"
+            from agents.llm_selector import select_mlx_model_id
+            result = select_mlx_model_id(
+                preferred_hf_id="mlx-community/Qwen3.5-9B-OptiQ-4bit",
+                preferred_min_ram_gb=6.5,
+                budget_pct=0.5,
+            )
+
+        # 50.0 × 0.5 = 25 GB budget; 6.5 ≤ 25 → stage 1 fires
+        assert result == "mlx-community/Qwen3.5-9B-OptiQ-4bit"
+
+
+# ---------------------------------------------------------------------------
+# Stage 2 — catalog cached fit
+# ---------------------------------------------------------------------------
+
+class TestStage2CachedFit:
+    def test_returns_largest_cached_model_when_preferred_too_big(self):
+        """Stage 2: preferred doesn't fit but a smaller cached model does."""
+        snap = _make_snap(headroom_gb=5.5)  # budget = 5.5 × 0.5 = 2.75 GB
+
+        def cached_side_effect(hf_id):
+            # Only qwen3.5-4b (2.5 GB) is cached
+            return hf_id == "mlx-community/Qwen3.5-4B-MLX-4bit"
+
+        with (
+            patch("agents.llm_selector.platform") as mock_platform,
+            patch("agents.llm_selector._sysctl", return_value="Apple M1 Air"),
+            patch("agents.llm_selector._apple_intelligence_available", return_value=False),
+            patch("agents.llm_selector.probe_compute", return_value=snap),
+            patch("agents.llm_selector._hf_model_cached",
+                  side_effect=cached_side_effect),
+        ):
+            mock_platform.system.return_value = "Darwin"
+            from agents.llm_selector import select_mlx_model_id
+            result = select_mlx_model_id(
+                preferred_hf_id="mlx-community/Qwen3.5-9B-OptiQ-4bit",
+                preferred_min_ram_gb=6.5,
+                budget_pct=0.5,
+            )
+
+        assert result == "mlx-community/Qwen3.5-4B-MLX-4bit"
+
+    def test_apple_intelligence_returned_when_available(self):
+        """Stage 2 (apple_fm branch): Apple Intelligence chosen over mlx on macOS 26+."""
+        snap = _make_snap(headroom_gb=5.5)
+
+        with (
+            patch("agents.llm_selector.platform") as mock_platform,
+            patch("agents.llm_selector._sysctl", return_value="Apple M1 Air"),
+            patch("agents.llm_selector._apple_intelligence_available", return_value=True),
+            patch("agents.llm_selector.probe_compute", return_value=snap),
+            patch("agents.llm_selector._hf_model_cached", return_value=False),
+        ):
+            mock_platform.system.return_value = "Darwin"
+            from agents.llm_selector import select_mlx_model_id, APPLE_INTELLIGENCE_ID
+            result = select_mlx_model_id(
+                preferred_hf_id="mlx-community/Qwen3.5-9B-OptiQ-4bit",
+                preferred_min_ram_gb=6.5,
+                budget_pct=0.5,
+            )
+
+        assert result == APPLE_INTELLIGENCE_ID
+
+
+# ---------------------------------------------------------------------------
+# Stage 3 — the fixed low-RAM fallback
+# ---------------------------------------------------------------------------
+
+class TestStage3LowRamFallback:
+    def test_returns_fitting_catalog_model_not_preferred_on_low_ram(self):
+        """Stage 3 fix: M1 Air 8 GB — nothing cached, preferred (6.5 GB) doesn't
+        fit the 2.7 GB budget — must return a smaller catalog model, NOT preferred.
+        """
+        snap = _make_snap(headroom_gb=5.4)  # Metal headroom ≈ 5.4 GB on M1 Air 8 GB
+        # budget = 5.4 × 0.5 = 2.7 GB → llama3.2-3b (1.8 GB) fits, qwen3.5-4b (2.5 GB) fits
+
+        with (
+            patch("agents.llm_selector.platform") as mock_platform,
+            patch("agents.llm_selector._sysctl", return_value="Apple M1"),
+            patch("agents.llm_selector._apple_intelligence_available", return_value=False),
+            patch("agents.llm_selector.probe_compute", return_value=snap),
+            patch("agents.llm_selector._hf_model_cached", return_value=False),
+        ):
+            mock_platform.system.return_value = "Darwin"
+            from agents.llm_selector import select_mlx_model_id
+            result = select_mlx_model_id(
+                preferred_hf_id="mlx-community/Qwen3.5-9B-OptiQ-4bit",
+                preferred_min_ram_gb=6.5,
+                budget_pct=0.5,
+            )
+
+        # Must NOT return the oversized preferred model
+        assert result != "mlx-community/Qwen3.5-9B-OptiQ-4bit", (
+            "Stage 3 returned the oversized preferred model on a low-RAM machine"
+        )
+        # Must return a model that fits the budget (largest fitting = qwen3.5-4b at 2.5 GB)
+        assert result == "mlx-community/Qwen3.5-4B-MLX-4bit"
+
+    def test_preferred_returned_only_when_nothing_in_catalog_fits(self):
+        """Stage 3 true last resort: budget so tiny no catalog model fits."""
+        snap = _make_snap(headroom_gb=0.5)  # budget = 0.25 GB — nothing fits
+
+        with (
+            patch("agents.llm_selector.platform") as mock_platform,
+            patch("agents.llm_selector._sysctl", return_value="Apple M1"),
+            patch("agents.llm_selector._apple_intelligence_available", return_value=False),
+            patch("agents.llm_selector.probe_compute", return_value=snap),
+            patch("agents.llm_selector._hf_model_cached", return_value=False),
+        ):
+            mock_platform.system.return_value = "Darwin"
+            from agents.llm_selector import select_mlx_model_id
+            result = select_mlx_model_id(
+                preferred_hf_id="mlx-community/Qwen3.5-9B-OptiQ-4bit",
+                preferred_min_ram_gb=6.5,
+                budget_pct=0.5,
+            )
+
+        # Nothing fits → last-resort returns preferred (preserves old behaviour)
+        assert result == "mlx-community/Qwen3.5-9B-OptiQ-4bit"
+
+    def test_returns_none_when_no_preferred_and_nothing_fits(self):
+        """Stage 3: no preferred given + nothing fits → None."""
+        snap = _make_snap(headroom_gb=0.5)
+
+        with (
+            patch("agents.llm_selector.platform") as mock_platform,
+            patch("agents.llm_selector._sysctl", return_value="Apple M1"),
+            patch("agents.llm_selector._apple_intelligence_available", return_value=False),
+            patch("agents.llm_selector.probe_compute", return_value=snap),
+            patch("agents.llm_selector._hf_model_cached", return_value=False),
+        ):
+            mock_platform.system.return_value = "Darwin"
+            from agents.llm_selector import select_mlx_model_id
+            result = select_mlx_model_id(budget_pct=0.5)
+
+        assert result is None
+
+    def test_picks_largest_fitting_not_smallest(self):
+        """Stage 3: when multiple catalog models fit, the largest (highest quality) wins."""
+        snap = _make_snap(headroom_gb=7.0)  # budget = 3.5 GB
+        # qwen3.5-4b (2.5 GB) and llama3.2-3b (1.8 GB) both fit; qwen3.5-4b should win
+
+        with (
+            patch("agents.llm_selector.platform") as mock_platform,
+            patch("agents.llm_selector._sysctl", return_value="Apple M1 Pro"),
+            patch("agents.llm_selector._apple_intelligence_available", return_value=False),
+            patch("agents.llm_selector.probe_compute", return_value=snap),
+            patch("agents.llm_selector._hf_model_cached", return_value=False),
+        ):
+            mock_platform.system.return_value = "Darwin"
+            from agents.llm_selector import select_mlx_model_id
+            result = select_mlx_model_id(
+                preferred_hf_id="mlx-community/Qwen3.5-9B-OptiQ-4bit",
+                preferred_min_ram_gb=6.5,
+                budget_pct=0.5,
+            )
+
+        assert result == "mlx-community/Qwen3.5-4B-MLX-4bit"