@meridiona/meridian-darwin-arm64 1.64.0 → 1.66.0

package/VERSION

@@ -1 +1 @@
-1.64.0
+1.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meridiona/meridian-darwin-arm64",
-  "version": "1.64.0",
+  "version": "1.66.0",
   "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/meridian-cli.sh

@@ -11,12 +11,12 @@ REPO_ROOT="$(cd "$(dirname "$SELF")/.." && pwd)"
 # --- constants ---
 LABEL_SCREENPIPE="com.meridiona.screenpipe"
 LABEL_DAEMON="com.meridiona.daemon"
-LABEL_UI="com.meridiona.ui"   # retired (dashboard now embedded in the tray) — kept only to boot out a leftover legacy agent
+LABEL_UI="com.meridiona.ui"
 LABEL_MLX="com.meridiona.mlx-server"
-# Jira worklogs and coding-agent ingest run inside the Rust daemon, and the
-# dashboard is embedded in the tray binary — no separate UI launchd agent. Only
-# these three production services are managed.
-readonly LABELS=("${LABEL_SCREENPIPE}" "${LABEL_DAEMON}" "${LABEL_MLX}")
+# Capture runs in-process in the tray (no screenpipe launchd agent since Bucket-2).
+# Jira worklogs and coding-agent ingest run inside the Rust daemon — no
+# separate launchd agents. Only these two are managed.
+readonly LABELS=("${LABEL_DAEMON}" "${LABEL_MLX}")
 GUI_TARGET="gui/$(id -u)"
 LAUNCH_AGENTS="${HOME}/Library/LaunchAgents"
 LOG_DIR="${HOME}/.meridian/logs"
@@ -41,7 +41,7 @@ Commands:
   restart            Stop, wait 1s, start
   status             Show running state of all daemons
   logs [target]      Tail log files
-                     target: daemon|daemon-error|screenpipe|screenpipe-error|ui|ui-error|mlx-server|mlx-server-error
+                     target: daemon|daemon-error|mlx-server|mlx-server-error|tray|tray-error
     -f               Follow (stream)
     -n N             Last N lines (default 100)
   doctor             Run environment health checks (includes pipeline smoke)
@@ -180,7 +180,12 @@ cmd_logs() {
         ui-error)          log_file="${LOG_DIR}/ui-error.log" ;;
         mlx-server)        log_file="${LOG_DIR}/mlx-server.log" ;;
         mlx-server-error)  log_file="${LOG_DIR}/mlx-server-error.log" ;;
-        *) err "unknown log target: ${target} (daemon|daemon-error|screenpipe|screenpipe-error|ui|ui-error|mlx-server|mlx-server-error)"; exit 1 ;;
+        tray)              log_file="${LOG_DIR}/tray.log" ;;
+        tray-error)        log_file="${LOG_DIR}/tray-error.log" ;;
+        # screenpipe/ui are retired post-v1.64.0 (capture is in-process in the
+        # tray; the dashboard is embedded) — kept here so old log files remain
+        # tailable, but `tray`/`tray-error` are the live targets now.
+        *) err "unknown log target: ${target} (daemon|daemon-error|mlx-server|mlx-server-error|tray|tray-error)"; exit 1 ;;
     esac
 
     if [[ ! -f "$log_file" ]]; then
@@ -269,11 +274,12 @@ _doctor_fallback() {
     printf "  ════════════════════════════════════════════════════════\n"
     _group "system"
     _row "$([[ "$(uname -s)" == "Darwin" ]] && echo ok || echo fail)" "macOS" ""
-    _row "$([[ -f "${HOME}/.meridian/.env" || -f "${REPO_ROOT}/.env" ]] && echo ok || echo fail)" "config (.env)" ""
+    _row "$([[ -f "${REPO_ROOT}/.env" ]] && echo ok || echo fail)" "config (.env)" ""
     _group "services (plists)"
     _plist_row "$LABEL_DAEMON" "daemon plist"
     _plist_row "$LABEL_SCREENPIPE" "screenpipe plist"
     _plist_row "$LABEL_MLX" "mlx plist"
+    _plist_row "$LABEL_UI" "ui plist"
     _group "builds"
     _row "$([[ -f "${REPO_ROOT}/packages/meridian-mcp/dist/index.js" ]] && echo ok || echo fail)" "mcp built" ""
     _row "$([[ -d "${REPO_ROOT}/ui/.next" ]] && echo ok || echo fail)" "ui built" ""
@@ -288,9 +294,7 @@ _doctor_fallback() {
 #   (no flag)        full run: classification + worklog synthesis
 
 _smoke_read_env() {
-    local key="$1"
-    local env_file="${HOME}/.meridian/.env"
-    [[ -f "$env_file" ]] || env_file="${REPO_ROOT}/.env"
+    local key="$1" env_file="${REPO_ROOT}/.env"
     [[ -f "$env_file" ]] || return 0
     grep -E "^${key}=" "$env_file" 2>/dev/null | tail -1 | cut -d= -f2- || true
 }
@@ -454,10 +458,9 @@ cmd_config() {
         err "usage: meridian config edit"
         exit 1
     fi
-    local env_file="${HOME}/.meridian/.env"
-    [[ -f "$env_file" ]] || env_file="${REPO_ROOT}/.env"
+    local env_file="${REPO_ROOT}/.env"
     if [[ ! -f "$env_file" ]]; then
-        err "~/.meridian/.env not found — run the installer first"
+        err "${env_file} not found — run ./install.sh first"
         exit 1
     fi
     "${EDITOR:-nano}" "$env_file"
@@ -497,9 +500,7 @@ cmd_uninstall() {
     set +e
 
     # 1. Stop and remove all launchd agents
-    # Legacy UI server (retired — dashboard is now in the tray): boot out + remove inline.
-    launchctl bootout "${GUI_TARGET}/${LABEL_UI}" 2>/dev/null || true
-    rm -f "${HOME}/Library/LaunchAgents/${LABEL_UI}.plist" 2>/dev/null || true
+    bash "${REPO_ROOT}/scripts/uninstall-ui-daemon.sh" 2>/dev/null
     bash "${REPO_ROOT}/services/scripts/uninstall-mlx-server-daemon.sh" 2>/dev/null
     bash "${REPO_ROOT}/scripts/uninstall-daemon.sh" 2>/dev/null
     bash "${REPO_ROOT}/scripts/uninstall-screenpipe-daemon.sh" 2>/dev/null
@@ -568,7 +569,7 @@ PYEOF
         "models--mlx-community--phi-4-4bit"
         "models--mlx-community--DeepSeek-R1-Distill-Qwen-14B-4bit"
         "models--mlx-community--gemma-3-12b-it-qat-4bit"
-        "models--mlx-community--Qwen3.5-9B-OptiQ-4bit"
+        "models--mlx-community--Qwen3.5-2B-OptiQ-4bit"
         "models--mlx-community--Qwen3.5-4B-MLX-4bit"
         "models--mlx-community--Llama-3.2-3B-Instruct-4bit"
     )

package/services/README.md

@@ -4,7 +4,7 @@ The model layer that runs alongside the Rust daemon. A persistent MLX inference
 
 The Rust daemon owns all DDL; this service only does SELECT/INSERT/UPDATE on its agent-side tables.
 
-> **Note:** the coding-agent indexer + summariser, and the pm-worklog (Stage 4) driver, all run **inside the Rust daemon** (`src/coding_agent_session_ingest/`, `src/pm_worklog/`). This service is the model layer: `agents/server.py` is the persistent MLX server, which serves `/classify_sessions` (classification), `/summarise` (the summariser's fallback), and `/synthesise_worklog` (the agno worklog synthesiser). The Rust daemon drives all three over HTTP.
+> **Note:** the coding-agent indexer + summariser, and the pm-worklog (Stage 4) driver, all run **inside the Rust daemon** (`src/coding_agent_session_ingest/`, `src/pm_worklog/`). This service is the model layer: `agents/server.py` is the persistent MLX server, which serves `/summarise` (the summariser's fallback) and `/synthesise_worklog` (the agno worklog synthesiser). The Rust daemon drives both over HTTP.
 
 For the deep technical reference (classification logic, schema, recipes), see [`agents/README.md`](agents/README.md).
 
@@ -15,14 +15,8 @@ For the deep technical reference (classification logic, schema, recipes), see [`
 ```
 app_sessions row (Rust ETL writes it)
         │
-        │  Rust daemon calls POST /classify_sessions
-        ▼           on the persistent MLX server
-┌──────────────────────────────────────────────┐
-│ MLX inference server (FastAPI, port 7823)    │ Apple Silicon only
-│   model: mlx-community/Qwen3.5-9B-OptiQ-4bit│
-│   loaded once at startup, served until killed│
-│   returns: task_key, session_type, confidence│
-└──────────────────────────────────────────────┘
+        ▼
+Rust daemon classifies sessions (src/intelligence/task_linker/)
         │
         ▼
 Rust writes ticket_links + session_dimensions → meridian.db
@@ -50,7 +44,7 @@ The `hermes-agent` package is fetched from GitHub at the pinned tag; an internet
 
 ## MLX server
 
-The Rust daemon calls the MLX server for every classification. It must be running before the daemon starts.
+The Rust daemon calls the MLX server for summarisation and worklog synthesis. It must be running before the daemon starts.
 
 ### Install as a launchd daemon (recommended)
 
@@ -74,7 +68,7 @@ RUST_LOG=meridian=debug CLASSIFIER_BACKEND=mlx cargo run --bin meridian
 python -m agents.server --backend mlx --port 7823
 ```
 
-The model (`Qwen3.5-9B-OptiQ-4bit`) is downloaded from Hugging Face on first run (~4 GB). Subsequent starts load from local cache in ~5 s.
+The model (`Qwen3.5-2B-OptiQ-4bit`) is downloaded from Hugging Face on first run. Subsequent starts load from local cache in ~5 s.
 
 ---
 
@@ -96,7 +90,7 @@ Additional variables are documented in [`agents/README.md`](agents/README.md#con
 
 ### Task classifier
 
-The task classifier runs automatically — the Rust daemon calls `POST /classify_sessions` on the MLX server on each intelligence tick. To inspect or re-run classification:
+The task classifier runs automatically inside the Rust daemon on each intelligence tick. To inspect or re-run classification:
 
 ```bash
 # Re-run classification with full logging — does NOT write to DB

package/services/agents/README.md

@@ -11,7 +11,7 @@ For a higher-level overview (installation, daemon ops, configuration), see [`ser
 The Rust daemon owns the pipeline (ETL, coding-agent ingest, classification
 trigger, pm-worklog driver) and the database. This service is the **model
 layer**: one persistent MLX server (`server.py`) that the daemon calls over HTTP
-for the three jobs that need a local LLM.
+for the two jobs that need a local LLM.
 
 ```
 screenpipe.db (read-only)
@@ -29,16 +29,10 @@ meridian.db  →  app_sessions
         │    MLX server's /summarise is the fallback. Rows walk task_method:
         │    coding_agent_live → pending_summariser → pending_classifier.
         │
-        ├── classification  (src/intelligence/task_linker/, Rust → MLX)
+        ├── classification  (src/intelligence/task_linker/, Rust)
         │    Rust reads unclassified rows and the pending_classifier queue,
-        │    then sends:
-        │      POST http://127.0.0.1:7823/classify_sessions
-        │           {session_ids: [...], meridian_db: ...}
-        │    MLX server (Qwen3.5-9B-OptiQ-4bit, FSM-constrained outlines):
-        │      fetch session + pm_tasks + recent context
-        │      → SessionClassification {task_key, session_type, confidence,
-        │                               reasoning, method, dimensions}
-        │    Rust writes ticket_links + session_dimensions, advances cursor.
+        │    classifies them internally, and writes ticket_links +
+        │    session_dimensions, then advances the cursor.
         │
         └── pm-worklog (Stage 4)  (src/pm_worklog/, Rust → MLX)
              The Rust hour-driven driver collects each (task, hour) bundle and
@@ -260,7 +254,7 @@ When the screen is locked the selector uses `min(0.8, budget_pct × 1.5)` as the
 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.
+**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-2B-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:**
 
@@ -270,7 +264,7 @@ cd services
 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)
+model = select_mlx_model_id('mlx-community/Qwen3.5-2B-OptiQ-4bit', 6.5, 0.5)
 print(f'Would load: {model}')
 "
 ```
@@ -350,14 +344,14 @@ pip install -e ".[local-llm]"
    FROM ticket_links WHERE session_id = <ID>;
    ```
 
-2. **Re-run the classifier against a live session** — call the MLX server directly with the session id:
+2. **Re-run the classifier against a live session** using the daemon CLI:
+
    ```bash
-   curl -s -X POST http://127.0.0.1:7823/classify_sessions \
-     -H "Content-Type: application/json" \
-     -d "{\"session_ids\": [<ID>]}" | jq .
+   meridian coding-agent-classify
    ```
 
    Or use the standalone MLX script (reads from stdin, prints JSON to stdout):
+
    ```bash
    cd services
    echo '{"session_ids": [<ID>], "meridian_db": "'"$HOME"'/.meridian/meridian.db"}' \

package/services/agents/_state.py

@@ -0,0 +1,43 @@
+"""Process-global server state shared between the FastAPI app and route modules."""
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Any
+
+# Populated in _lifespan (mlx_module, loaded_at, model_sem, tracer, self_url, …)
+# and read by every route module.
+app_state: dict[str, Any] = {}
+
+# Shared prefetch progress, guarded by prefetch_lock. states: idle|downloading|done|error.
+# `received`/`total` are AGGREGATE byte counts summed across every pipeline model
+# (llm + reranker + embedder), so the wizard's progress bar has a single honest
+# denominator. The wire contract the Rust tray decodes is exactly
+# state/received/total/error (tray/src-tauri/src/mlx_server.rs::PrefetchStatus);
+# `models` is an additive per-model breakdown the tray ignores.
+prefetch_state: dict[str, Any] = {
+    "state": "idle",
+    "received": 0,
+    "total": 0,
+    # Live transfer rate in bytes/sec, sourced from HF's own tqdm progress
+    # (see routes/prefetch._SpeedTqdm); 0 when not actively transferring.
+    "speed": 0.0,
+    "error": None,
+    # Per-model rows: {"role", "model_id", "loader", "received", "total", "state"}.
+    "models": [],
+}
+prefetch_lock = threading.Lock()
+
+
+def model_sem() -> "asyncio.Semaphore":
+    """Return the process-global single-slot model semaphore.
+
+    Created once in _lifespan and stored in app_state. Every endpoint that
+    runs a model inference acquires this before calling run_in_threadpool so
+    that concurrent requests never compete on the GPU.
+    """
+    sem = app_state.get("model_sem")
+    if sem is None:  # fallback if called before lifespan (e.g. tests)
+        sem = asyncio.Semaphore(1)
+        app_state["model_sem"] = sem
+    return sem

package/services/agents/agno_viewer.py

@@ -0,0 +1,60 @@
+"""Minimal AgentOS viewer for browsing worklog pipeline traces.
+
+Run this script to expose the agno_traces.db as an AgentOS runtime, then:
+  1. Open https://os.agno.com, sign in (free account)
+  2. Add new OS → Environment: Local → URL: http://localhost:8000
+  3. Click "CONNECT" → refresh the page
+
+Alternatively, browse directly at http://localhost:8000 without the hosted UI.
+
+The DB path defaults to ~/.meridian/agno_traces.db (set AGNO_TRACE_DB to override).
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+from agno.agent import Agent
+from agno.db.sqlite import SqliteDb
+from agno.os import AgentOS
+from agno.workflow import Workflow
+
+_DEFAULT_DB = Path("~/.meridian/agno_traces.db").expanduser()
+_db_file = Path(os.environ.get("AGNO_TRACE_DB", "") or _DEFAULT_DB).expanduser()
+
+db = SqliteDb(db_file=str(_db_file))
+
+_agent = Agent(
+    name="Meridian Worklog Pipeline",
+    description="Worklog pipeline agent — match sessions to PM tasks and draft worklogs.",
+    db=db,
+)
+
+# Stub workflow registered so os.agno.com marks the OS as active.
+# The real pipeline runs inside server.py; this is traces-only.
+_workflow = Workflow(
+    name="worklog_hour",
+    description="Hour-level worklog pipeline: distil → report → rerank → match → draft/propose.",
+    db=db,
+)
+
+agent_os = AgentOS(
+    id="meridian-worklog",
+    name="Meridian Worklog Traces",
+    description="Viewer for worklog pipeline traces — worklog.hour, match, propose, draft spans.",
+    agents=[_agent],
+    workflows=[_workflow],
+    db=db,
+    tracing=True,
+)
+
+app = agent_os.get_app()
+
+if __name__ == "__main__":
+    log.info("trace DB: %s", _db_file)
+    log.info("dashboard: http://localhost:8000")
+    log.info("control:   https://os.agno.com → Add new OS → http://localhost:8000")
+    agent_os.serve(app="agno_viewer:app", reload=False, port=8000)

package/services/agents/config.py

@@ -54,6 +54,14 @@ MERIDIAN_HOME = Path(os.environ.get("MERIDIAN_HOME", str(Path.home() / ".meridia
 MERIDIAN_DB   = Path(os.environ.get("MERIDIAN_DB",   str(MERIDIAN_HOME / "meridian.db")))
 LOG_DIR       = MERIDIAN_HOME / "logs"
 
+# ── Session distiller ─────────────────────────────────────────────────────────
+DISTILLER_EXCLUDE_APPS: tuple[str, ...] = (
+    "Claude Code", "Codex", "GitHub Copilot", "Cursor Agent",
+)
+DISTILLER_MIN_SESSION_DUR: int   = int(os.environ.get("DISTILLER_MIN_SESSION_DUR", "15"))
+DISTILLER_SEM_DEDUP_THR:   float = float(os.environ.get("DISTILLER_SEM_DEDUP_THR", "0.86"))
+DISTILLER_DF_FRAC:         float = float(os.environ.get("DISTILLER_DF_FRAC", "0.25"))
+
 # ── Loop tunables ─────────────────────────────────────────────────────────────
 CONFIDENCE_THRESHOLD = float(os.environ.get("CONFIDENCE_THRESHOLD", "0.65"))
 MIN_LLM_DURATION_S   = int(os.environ.get("MIN_LLM_DURATION_S", "30"))

package/services/agents/mlx_classifier.py

@@ -0,0 +1,198 @@
+"""MLX model lifecycle — load, session context manager, idle eviction.
+
+Manages a single shared MLX generative model (Qwen3) for the agent server.
+Exposes model_session() for inference, evict_resident_model() for the
+single-slot guarantee (never two models resident simultaneously), and
+_get_tokenizer() for callers that need the HF tokenizer directly.
+"""
+from __future__ import annotations
+
+import gc
+import logging
+import os
+import threading
+import time
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+from agents import model_registry, observability
+
+log = logging.getLogger("agents.mlx_classifier")
+tracer = observability.setup("meridian-mlx-classifier")
+
+# Generative/classifier checkpoint — resolved from the model registry (the single
+# source of truth for all three pipeline models), env-overridable via MERIDIAN_LLM_ID.
+# Exposed as a module attribute for external compatibility; the live value is read
+# from the registry per-call inside _get_model() so a runtime env change is honoured.
+MODEL_ID = model_registry.llm_id()
+
+_IDLE_EVICT_S = float(os.environ.get("MLX_IDLE_EVICT_S", "120"))
+
+
+class _ModelBundle:
+    """Thin wrapper so callers can access model.model and model.mlx_tokenizer."""
+    __slots__ = ("model", "mlx_tokenizer")
+
+    def __init__(self, model: Any, tokenizer: Any) -> None:
+        self.model = model
+        self.mlx_tokenizer = tokenizer
+
+
+_model_cache: dict[str, _ModelBundle] = {}
+_tokenizer_cache: dict[str, Any] = {}
+_model_lock = threading.Lock()
+_in_flight = 0
+_last_used = time.monotonic()
+
+
+def _get_model() -> _ModelBundle:
+    """Return the loaded model bundle, loading from disk on the first call.
+
+    Cache-miss load is done under _model_lock (double-checked) so concurrent
+    callers can't double-load and the idle evictor can't race the load.
+    """
+    model_id = model_registry.llm_id()
+    cached = _model_cache.get(model_id)
+    if cached is not None:
+        return cached
+
+    with _model_lock:
+        cached = _model_cache.get(model_id)
+        if cached is not None:
+            return cached
+        try:
+            import mlx_lm
+        except ImportError as exc:
+            raise ImportError(
+                f"Required package not installed: {exc}. "
+                "Install with: pip install 'mlx-lm>=0.22'"
+            ) from exc
+
+        log.info("mlx_classifier: loading %s (first call this process)", model_id)
+        t0 = time.time()
+        mlx_model, tokenizer = mlx_lm.load(
+            model_id,
+            tokenizer_config={"trust_remote_code": True},
+        )
+        bundle = _ModelBundle(mlx_model, tokenizer)
+        log.info("mlx_classifier: model loaded in %.1fs", time.time() - t0)
+
+        _model_cache[model_id] = bundle
+        _tokenizer_cache[model_id] = tokenizer
+        return bundle
+
+
+def _get_tokenizer() -> Any:
+    """Return the HF tokenizer for the current model, loading the model if needed."""
+    model_id = model_registry.llm_id()
+    tok = _tokenizer_cache.get(model_id)
+    if tok is not None:
+        return tok
+    return _get_model().mlx_tokenizer
+
+
+@contextmanager
+def model_session() -> Iterator[_ModelBundle]:
+    """Yield the loaded model bundle, marking it in-flight so the idle evictor
+    never frees it mid-inference. Wrap every direct model call in this.
+    """
+    global _in_flight, _last_used
+    with _model_lock:
+        _in_flight += 1
+    try:
+        yield _get_model()
+    finally:
+        with _model_lock:
+            _in_flight -= 1
+            _last_used = time.monotonic()
+
+
+def maybe_evict_idle(idle_s: float | None = None) -> float | None:
+    """Evict the model if it's resident, nothing is in flight, and it's been
+    idle longer than ``idle_s`` (default MLX_IDLE_EVICT_S). Returns the GB freed,
+    or None if no eviction happened. Safe to call from a threadpool worker.
+
+    Uses a non-blocking lock acquire: if an inference/load is mutating state we
+    simply skip this tick and try again on the next one.
+    """
+    ttl = _IDLE_EVICT_S if idle_s is None else idle_s
+    if ttl <= 0:
+        return None
+    if not _model_lock.acquire(blocking=False):
+        return None
+    try:
+        if _in_flight > 0 or not _model_cache:
+            return None
+        if (time.monotonic() - _last_used) < ttl:
+            return None
+        try:
+            import mlx.core as mx
+            before = mx.get_active_memory()
+        except Exception:  # noqa: BLE001
+            mx, before = None, 0
+        _model_cache.clear()
+        _tokenizer_cache.clear()
+        gc.collect()
+        freed = 0.0
+        if mx is not None:
+            mx.clear_cache()
+            freed = max(0.0, (before - mx.get_active_memory()) / 1e9)
+        log.info(
+            "mlx_classifier: evicted idle model (idle ≥ %.0fs), freed ~%.1f GB",
+            ttl, freed,
+        )
+        return freed
+    finally:
+        _model_lock.release()
+
+
+def evict_resident_model() -> float | None:
+    """Force-evict the resident generative model NOW, ignoring the idle timer.
+
+    The single-slot guarantee: the reranker must never be resident alongside
+    the generative model. Callers that are about to load a different model
+    call this first. Respects _in_flight — returns None if an inference is
+    running (the worklog pipeline is serialised, so nothing is in flight at a
+    phase boundary). Returns GB freed, or None if nothing was evicted.
+    """
+    if not _model_lock.acquire(blocking=False):
+        return None
+    try:
+        if _in_flight > 0 or not _model_cache:
+            return None
+        try:
+            import mlx.core as mx
+            before = mx.get_active_memory()
+        except Exception:  # noqa: BLE001
+            mx, before = None, 0
+        _model_cache.clear()
+        _tokenizer_cache.clear()
+        gc.collect()
+        freed = 0.0
+        if mx is not None:
+            mx.clear_cache()
+            freed = max(0.0, (before - mx.get_active_memory()) / 1e9)
+        log.info("mlx_classifier: force-evicted resident model, freed ~%.1f GB", freed)
+        return freed
+    finally:
+        _model_lock.release()
+
+
+def model_resident() -> bool:
+    """True if the MLX model is currently loaded in memory."""
+    return bool(_model_cache)
+
+
+def model_active_memory_gb() -> float | None:
+    """Live Metal active-memory footprint in GB, or None if MLX is unavailable.
+
+    Process-wide Metal active memory (≈ the model when resident — the model
+    dominates, though a transient load allocation can briefly inflate it), and
+    the only honest measure: ps/Activity Monitor can't see Metal unified
+    memory (they undercount by ~6.5 GB).
+    """
+    try:
+        import mlx.core as mx
+        return round(mx.get_active_memory() / 1e9, 2)
+    except Exception:  # noqa: BLE001
+        return None

package/services/agents/model_registry.py

@@ -0,0 +1,108 @@
+"""Single source of truth for the on-device models the pipeline needs.
+
+The end-to-end worklog pipeline (classification → worklog update) runs three
+distinct models, each in its own single-slot turn (the runtime never keeps two
+resident at once — see ``mlx_classifier.evict_resident_model``):
+
+    role      default checkpoint                       loader          used by
+    ────────  ───────────────────────────────────────  ──────────────  ──────────────────────────────────
+    llm       mlx-community/Qwen3.5-2B-OptiQ-4bit       mlx_lm          classify · match · /summarise · /activity_report · worklog synth · propose
+    reranker  kerncore/Qwen3-Reranker-0.6B-MLX-4bit    mlx_lm          ticket↔worklog scoring (/rerank)
+    embedder  mlx-community/Qwen3-Embedding-0.6B-8bit   mlx_embeddings  session-distillation SemDeDup (/distill_hour)
+
+There is no separate "classifier" model: classification and matching run on the
+``llm`` checkpoint via the OpenAI-compatible endpoint.
+
+Every checkpoint is env-overridable (defaults below) so eval/experiments can
+swap any role without code edits. This module is the ONLY place these ids and
+their HuggingFace download filesets are declared — ``mlx_classifier``,
+``reranker``, ``session_distiller`` and the ``/prefetch_model`` route all read
+from here, so onboarding can eagerly fetch exactly the set the runtime will load.
+
+# Who reads this
+    agents.mlx_classifier      → MODEL_ID            (llm)
+    agents.reranker            → _RERANKER_ID        (reranker)
+    agents.session_distiller   → embedder load       (embedder)
+    agents.routes.prefetch     → eager multi-model download for the setup wizard
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+# mlx_lm.load()'s default fileset — exactly what a generative or reranker MLX
+# repo resolves on load(). The mlx-community embedding repos are plain
+# transformer encoders shipping the same config/safetensors/tokenizer layout,
+# so this pattern set covers all three roles. Stored as a tuple (immutable) so
+# each ModelSpec gets independent identity — list mutation would silently corrupt
+# all three specs' snapshot_download filters simultaneously.
+_MLX_ALLOW_PATTERNS: tuple[str, ...] = (
+    "*.json", "model*.safetensors", "*.py", "tokenizer.model",
+    "*.tiktoken", "tiktoken.model", "*.txt", "*.jsonl", "*.jinja",
+)
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    """One model role: its env override, default checkpoint, loader, and fileset.
+
+    ``loader`` selects the runtime entry point — ``"mlx_lm"`` for generative /
+    reranker weights (``mlx_lm.load``) and ``"mlx_embeddings"`` for the encoder
+    (``mlx_embeddings.load``). ``allow_patterns`` is the HF download filter the
+    prefetch route applies so it fetches exactly what ``load()`` will resolve.
+    """
+
+    role: str
+    env_var: str
+    default_id: str
+    loader: str
+    allow_patterns: tuple[str, ...]
+
+    @property
+    def model_id(self) -> str:
+        """Resolved checkpoint id — the env override if set, else the default."""
+        return os.environ.get(self.env_var, self.default_id)
+
+
+LLM = ModelSpec(
+    role="llm",
+    env_var="MERIDIAN_LLM_ID",
+    default_id="mlx-community/Qwen3.5-2B-OptiQ-4bit",
+    loader="mlx_lm",
+    allow_patterns=_MLX_ALLOW_PATTERNS,
+)
+
+RERANKER = ModelSpec(
+    role="reranker",
+    env_var="WORKLOG_RERANKER_ID",
+    default_id="kerncore/Qwen3-Reranker-0.6B-MLX-4bit",
+    loader="mlx_lm",
+    allow_patterns=_MLX_ALLOW_PATTERNS,
+)
+
+EMBEDDER = ModelSpec(
+    role="embedder",
+    env_var="MERIDIAN_EMBEDDER_ID",
+    default_id="mlx-community/Qwen3-Embedding-0.6B-8bit",
+    loader="mlx_embeddings",
+    allow_patterns=_MLX_ALLOW_PATTERNS,
+)
+
+# Ordered llm → reranker → embedder: the wizard prefetches in this order, and the
+# llm is largest so its progress dominates the bar first.
+ALL_SPECS: tuple[ModelSpec, ...] = (LLM, RERANKER, EMBEDDER)
+
+
+def llm_id() -> str:
+    """Resolved generative/classifier checkpoint id."""
+    return LLM.model_id
+
+
+def reranker_id() -> str:
+    """Resolved reranker checkpoint id."""
+    return RERANKER.model_id
+
+
+def embedder_id() -> str:
+    """Resolved embedder checkpoint id."""
+    return EMBEDDER.model_id