@meridiona/meridian-darwin-arm64 1.64.0 → 1.65.0

package/VERSION

@@ -1 +1 @@
-1.64.0
+1.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meridiona/meridian-darwin-arm64",
-  "version": "1.64.0",
+  "version": "1.65.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,34 @@
+"""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
+prefetch_state: dict[str, Any] = {
+    "state": "idle",
+    "model_id": None,
+    "received": 0,
+    "total": 0,
+    "error": None,
+}
+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,195 @@
+"""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 observability
+
+log = logging.getLogger("agents.mlx_classifier")
+tracer = observability.setup("meridian-mlx-classifier")
+
+# Default model — the agent server runs a single hardcoded model.
+MODEL_ID = "mlx-community/Qwen3.5-2B-OptiQ-4bit"
+
+_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_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("run_task_linker_mlx: 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("run_task_linker_mlx: 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_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(
+            "run_task_linker_mlx: 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("run_task_linker_mlx: 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/observability.py

@@ -257,6 +257,9 @@ def setup(agent_name: str) -> trace.Tracer:
     This compromise matches OTel's "one resource per process" model while
     keeping `setup` idempotent in shared-library imports.
     """
+    import re
+    if not re.fullmatch(r"[A-Za-z0-9_\-]+", agent_name):
+        raise ValueError(f"agent_name must be alphanumeric/dash/underscore only: {agent_name!r}")
     global _PROCESS_SERVICE_NAME
 
     if agent_name in _INITIALISED:
@@ -353,7 +356,12 @@ def _configure_log_export(agent_name: str) -> Optional[logging.Handler]:
 def _configure_logging(agent_name: str) -> None:
     log_dir = Path(os.environ.get("MERIDIAN_LOG_DIR") or DEFAULT_LOG_DIR)
     log_dir.mkdir(parents=True, exist_ok=True)
-    log_path = log_dir / f"{agent_name}.jsonl"
+    # Sanitise agent_name to prevent path traversal — only allow chars that are
+    # safe as a filename component (alphanumeric, hyphen, underscore).
+    safe_name = "".join(c if c.isalnum() or c in "-_" else "_" for c in agent_name)
+    if not safe_name:
+        safe_name = "agent"
+    log_path = log_dir / f"{safe_name}.jsonl"
 
     level_name = os.environ.get("LOG_LEVEL", "INFO").upper()
     level = getattr(logging, level_name, logging.INFO)
@@ -432,4 +440,42 @@ def _configure_logging(agent_name: str) -> None:
         logging.getLogger(noisy).setLevel(logging.WARNING)
 
 
-__all__ = ["setup", "extract_parent_context"]
+def current_traceparent() -> Optional[str]:
+    """Return the W3C traceparent header for the currently active OTel span.
+
+    Returns ``None`` when no span is active or the span context is invalid.
+    Callers pass this to loopback HTTP requests so downstream stages attach
+    their spans to the same trace (same pattern the Rust daemon uses via
+    ``crate::observability::current_traceparent()``).
+    """
+    span = trace.get_current_span()
+    if not span.get_span_context().is_valid:
+        return None
+    carrier: dict[str, str] = {}
+    TraceContextTextMapPropagator().inject(carrier)
+    return carrier.get("traceparent")
+
+
+def instrument_agno() -> None:
+    """Instrument the agno framework for OpenTelemetry tracing.
+
+    No-op when openinference-instrumentation-agno is not installed; the package
+    is optional and the server must start cleanly without it.
+    """
+    try:
+        from opentelemetry.instrumentation.agno import AgnoInstrumentor  # type: ignore[import]
+        AgnoInstrumentor().instrument()
+    except ImportError:
+        logging.getLogger(__name__).debug(
+            "opentelemetry-instrumentation-agno not installed; agno spans will not be exported"
+        )
+
+
+def preview(text: Optional[str], max_chars: int = 200) -> str:
+    """Truncate text to `max_chars` for use as a span attribute value."""
+    if not text:
+        return ""
+    return text[:max_chars] + ("…" if len(text) > max_chars else "")
+
+
+__all__ = ["setup", "extract_parent_context", "instrument_agno", "current_traceparent", "preview"]

package/services/agents/pm_worklog_update/config.py

@@ -2,7 +2,7 @@
 
 All tunables are read from the environment (loaded by the parent
 `agents.config` module). This file exposes them as typed constants so the
-rest of the package can `from agents.pm_worklog_update.config import X`.
+rest of the package can `from agents.pm_worklog_update_legacy.config import X`.
 
 The defaults are chosen for a single-user laptop setup with the local 9B
 MLX server on :7823 and the user's screen-capture history in
@@ -14,7 +14,7 @@ import os
 
 # Re-export the shared paths so callers don't have to know about the parent
 # config module.
-from agents.config import LOG_DIR, MERIDIAN_DB, MERIDIAN_HOME  # noqa: F401
+from agents.config import MERIDIAN_DB, MERIDIAN_HOME  # noqa: F401
 
 # ── Cadence ───────────────────────────────────────────────────────────────────
 # How often the daemon should fire a new PM update cycle, in hours.
@@ -27,7 +27,7 @@ PM_WORKLOG_INTERVAL_HOURS = float(os.environ.get("PM_WORKLOG_INTERVAL_HOURS", "1
 # OpenAILike. The port is the same one the classifier uses.
 MLX_SERVER_HOST   = os.environ.get("MLX_SERVER_HOST", "127.0.0.1")
 MLX_SERVER_PORT   = int(os.environ.get("MLX_SERVER_PORT", "7823"))
-MLX_SERVER_MODEL  = os.environ.get("MLX_SERVER_MODEL", "qwen3.5-9b-instruct")
+MLX_SERVER_MODEL  = os.environ.get("MLX_SERVER_MODEL", "mlx-community/Qwen3.5-2B-OptiQ-4bit")
 
 # Token caps. The MLX model exposes 128-262K context — a single Synthesise
 # call comfortably swallows even the heaviest hour of work.