superlocalmemory 4.0.10 → 4.1.2

package/src/superlocalmemory/server/routes/v3_api.py

@@ -8,14 +8,45 @@ from __future__ import annotations
 
 import json
 import logging
+from pathlib import Path
 import os
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import JSONResponse
+from superlocalmemory.core.config import CANONICAL_RECALL_LIMIT
+from superlocalmemory.core.status_contract import (
+    COUNT_QUERIES,
+    counts_from_sqlite,
+    projection_queue_depth,
+    store_size_mb,
+)
 from superlocalmemory.server.routes.helpers import SLM_VERSION, get_read_connection
 from superlocalmemory.server.route_mutations import authorize_route_mutation
 
 logger = logging.getLogger(__name__)
 
+def _signal_session_id() -> str:
+    """A name for the caller, for matching an outcome back to this recall.
+
+    The agent id the request arrived under, when it arrived under one. Falls
+    back to the workspace, which keeps dashboard and scripted traffic separable
+    from an agent's. Never empty: an unnamed recall leaves no record.
+    """
+    try:
+        from superlocalmemory.mcp.agent_context import get_current_agent_id
+
+        agent = str(get_current_agent_id() or "").strip()
+        if agent:
+            return f"agent:{agent}"
+    except Exception:  # noqa: BLE001 -- naming the caller must never fail a read
+        pass
+    try:
+        from superlocalmemory.server.routes.helpers import get_active_profile
+
+        return f"api:{get_active_profile()}"
+    except Exception:  # noqa: BLE001
+        return "api:default"
+
+
 router = APIRouter(prefix="/api/v3", tags=["v3"])
 
 
@@ -102,20 +133,15 @@ async def dashboard(request: Request):
 
         # Read stats directly from SQLite (dashboard doesn't load engine)
         memory_count = 0
-        fact_count = 0
+        counts = dict.fromkeys(COUNT_QUERIES, 0)
+        queue_depth = 0
         db_path = config.base_dir / "memory.db"
         if db_path.exists():
             try:
                 conn = get_read_connection(db_path)
+                counts = counts_from_sqlite(conn, active_profile)
+                queue_depth = projection_queue_depth(conn)
                 cursor = conn.cursor()
-                try:
-                    cursor.execute(
-                        "SELECT COUNT(*) FROM atomic_facts WHERE profile_id = ?",
-                        (active_profile,),
-                    )
-                    fact_count = cursor.fetchone()[0]
-                except Exception:
-                    pass
                 try:
                     try:
                         cursor.execute(
@@ -143,10 +169,23 @@ async def dashboard(request: Request):
             "provider": config.llm.provider or "none",
             "model": config.llm.model or "",
             "memory_count": memory_count,
-            "fact_count": fact_count,
             "profile": active_profile,
             "base_dir": str(config.base_dir),
             "version": SLM_VERSION,
+            # The counts and the store's own address were missing here while
+            # every other status surface carried them, so the one surface a
+            # person actually looks at could not answer "is the graph healthy".
+            "db_path": str(db_path),
+            "db_size_mb": store_size_mb(db_path),
+            "profile_generation": get_profile_runtime(
+                request.app.state,
+            ).snapshot.generation,
+            # Facts stored but not yet in the graph and vector projections. A
+            # number that does not fall is a projection that has stopped
+            # keeping up, which is otherwise invisible: nothing errors, the
+            # memory is safely in SQLite, and recall just quietly gets worse.
+            "projection_queue_depth": queue_depth,
+            **counts,
         }
         payload.update(dashboard_mode_fields(config.mode))
         return payload
@@ -495,12 +534,45 @@ async def set_full_config(request: Request):
         _emb_fields = ("embedding_provider", "embedding_endpoint", "embedding_key",
                        "embedding_model", "embedding_dimension")
         if any(k in body for k in _emb_fields):
+            _old_emb = config.embedding
+            _new_provider = body.get("embedding_provider", "")
+            _new_model = body.get("embedding_model", "")
+            _new_dim = int(body.get("embedding_dimension", 0) or 0)
+            # The same range the other save route enforces. Without it a
+            # dashboard save with no dimension field stored a width of zero.
+            if _new_dim and not (64 <= _new_dim <= 8192):
+                return JSONResponse(
+                    {"error": f"Dimension must be 64-8192, got {_new_dim}"},
+                    status_code=400,
+                )
+            # The SECOND way to change the embedding model, and it was
+            # unguarded. Switching mode from the dashboard carries the embedding
+            # fields, so a width that the store cannot hold arrived here
+            # untouched while the other route refused it — one door bolted, the
+            # other open.
+            if not bool(body.get("force")):
+                _refusal = _refuse_incompatible_embedding(
+                    config, config.embedding, _new_model, _new_dim,
+                    new_provider=_new_provider,
+                )
+                if _refusal is not None:
+                    return _refusal
             config.embedding = EmbeddingConfig(
-                provider=body.get("embedding_provider", ""),
+                provider=_new_provider,
                 api_endpoint=body.get("embedding_endpoint", ""),
                 api_key=body.get("embedding_key", ""),
-                model_name=body.get("embedding_model", ""),
-                dimension=int(body.get("embedding_dimension", 0) or 0),
+                model_name=_new_model,
+                dimension=_new_dim or _old_emb.dimension,
+                # Not naming these reset them to defaults, so every embedding
+                # save from the dashboard silently put the local model back to
+                # whatever ships — the exact defect the other route had.
+                ollama_model=(
+                    _new_model if _new_provider == "ollama" and _new_model
+                    else _old_emb.ollama_model
+                ),
+                ollama_base_url=_old_emb.ollama_base_url,
+                api_version=_old_emb.api_version,
+                deployment_name=_old_emb.deployment_name,
             )
 
         # When the mode actually changed, apply the new mode's structural presets
@@ -571,6 +643,85 @@ async def get_embedding_config(request: Request):
         return _internal_error()
 
 
+def _refuse_incompatible_embedding(
+    config, old_emb, new_model, new_dim, new_provider=None,
+):
+    """None when the change is safe, otherwise the 409 to return instead.
+
+    Fail-open on anything it cannot determine: a store with no vectors yet, a
+    model server that is not running, an unreadable database. Refusing on
+    "I could not tell" would block a legitimate first-time setup, and the
+    dimension a caller declares is still checked against the store either way.
+    """
+    from fastapi.responses import JSONResponse as _JSON
+
+    try:
+        from superlocalmemory.core.ollama_validator import (
+            EMBEDDING,
+            stored_embedding_dimension,
+            validate_ollama_model,
+        )
+
+        db_path = Path(config.base_dir) / "memory.db"
+        stored = stored_embedding_dimension(db_path)
+        if stored is None:
+            return None
+
+        # The provider being SAVED, falling back to the current one when the
+        # caller is not changing it. Reading only the current provider meant
+        # that SWITCHING to a local model never probed at all — and switching
+        # is exactly when the width changes.
+        effective_provider = (
+            new_provider
+            if new_provider is not None
+            else getattr(old_emb, "provider", "")
+        )
+        measured = None
+        if effective_provider == "ollama" or getattr(old_emb, "provider", "") == "ollama":
+            # The model being SAVED, not the one already configured. Probing the
+            # old one always matched the stored width and therefore always
+            # allowed the change — the guard measured the thing it was not
+            # protecting against.
+            probe = validate_ollama_model(
+                new_model or getattr(old_emb, "ollama_model", ""),
+                EMBEDDING,
+                base_url=getattr(old_emb, "ollama_base_url", "")
+                or "http://localhost:11434",
+            )
+            measured = probe.dimension if probe.ok else None
+
+        declared = int(new_dim or 0)
+        if measured is None and declared <= 0:
+            # Nothing to compare: the server could not be asked and the caller
+            # named no width. Allowing is the fail-open the first-time setup
+            # needs; the other route's probe still guards the common path.
+            return None
+        effective = measured if measured is not None else declared
+        if effective == stored:
+            return None
+
+        return _JSON(
+            {
+                "error": "embedding_width_mismatch",
+                "stored_dimension": stored,
+                "requested_dimension": effective,
+                "model_name": new_model,
+                "detail": (
+                    f"{new_model} produces {effective}-dimensional vectors and "
+                    f"this store holds {stored}-dimensional ones. Vectors of "
+                    f"different widths cannot be compared, so every memory "
+                    f"already stored would become unfindable by meaning. "
+                    f"Rebuild them first with: slm db migrate — or resend with "
+                    f"force=true if they have already been rebuilt."
+                ),
+            },
+            status_code=409,
+        )
+    except Exception:  # noqa: BLE001 - never block a save on the check failing
+        logger.exception("embedding width pre-check failed; allowing the save")
+        return None
+
+
 @router.put("/embedding/config")
 async def set_embedding_config(request: Request):
     """Update embedding configuration independently of mode switch."""
@@ -591,13 +742,34 @@ async def set_embedding_config(request: Request):
         new_key = body.get("api_key", config.embedding.api_key)
 
         old_emb = config.embedding
+
+        # A width that disagrees with what the store already holds is refused
+        # here, at the moment of writing, not merely offered as a check the
+        # caller may or may not have run. Vectors of different widths cannot be
+        # compared, so the store would keep answering similarity questions and
+        # every answer would be noise. ``force=true`` is the escape hatch for
+        # somebody who has already re-embedded.
+        if not bool(body.get("force")):
+            refusal = _refuse_incompatible_embedding(
+                config, old_emb, new_model, new_dim, new_provider=new_provider,
+            )
+            if refusal is not None:
+                return refusal
+
         config.embedding = EmbeddingConfig(
             model_name=new_model,
             dimension=new_dim,
             provider=new_provider,
             api_endpoint=new_endpoint,
             api_key=new_key,
-            ollama_model=old_emb.ollama_model,
+            # In Ollama mode the embedder resolves its model from
+            # ``ollama_model``, so keeping the old value here made a rename a
+            # no-op that still answered "success". A caller naming a model gets
+            # that model.
+            ollama_model=(
+                new_model if new_provider == "ollama" and new_model
+                else old_emb.ollama_model
+            ),
             ollama_base_url=old_emb.ollama_base_url,
             api_version=old_emb.api_version,
             deployment_name=old_emb.deployment_name,
@@ -1018,7 +1190,7 @@ async def recall_trace(request: Request):
     try:
         body = await request.json()
         query = body.get("query", "")
-        limit = body.get("limit", 10)
+        limit = body.get("limit", CANONICAL_RECALL_LIMIT)
         window = body.get("window", "") or ""
         as_of_raw = (body.get("as_of", "") or "").strip()
         raw_known_as_of = body.get("known_as_of", "")
@@ -1073,6 +1245,10 @@ async def recall_trace(request: Request):
                 window=window or None, as_of=_as_of,
                 known_as_of=_known_as_of, valid_at=_valid_at,
                 include_unknown=include_unknown,
+                # Whoever asked, by the name they arrived under. Without a name
+                # the record of this recall is discarded and no outcome
+                # reported afterwards can be matched back to it.
+                session_id=_signal_session_id(),
             ),
         )
         elapsed_ms = round((_time.monotonic() - t0) * 1000, 1)

package/src/superlocalmemory/server/ui.py

@@ -231,14 +231,30 @@ def create_app() -> FastAPI:
                 "<p><a href='/api/docs'>API Documentation</a></p>"
                 "</body></html>"
             )
-        from superlocalmemory.server.asset_versions import render_index
         from superlocalmemory import __version__ as _v
 
         # __SLM_VERSION__ was substituted only by the unified daemon, so the
         # dashboard's upgrade detector did nothing when served from here.
-        return render_index(
-            index_path, UI_DIR, substitutions={"__SLM_VERSION__": _v},
-        )
+        # Asset versioning is cosmetic. It must never be why this page 500s.
+        #
+        # The import is deferred (house style, keeps startup lean), which means
+        # it resolves at REQUEST time — so when `pip install -e .` replaced the
+        # installed package underneath a running daemon, this route began
+        # answering "Internal Server Error" on the dashboard while every other
+        # endpoint was fine. A stale hand-written version string is a trifle; a
+        # blank page is not. Fall back to the file as written.
+        try:
+            from superlocalmemory.server.asset_versions import render_index
+
+            return render_index(
+                index_path, UI_DIR, substitutions={"__SLM_VERSION__": _v},
+            )
+        except Exception as exc:  # noqa: BLE001 — serve the page regardless
+            logger.warning(
+                "asset version rewrite unavailable, serving index.html as "
+                "written: %s: %s", type(exc).__name__, exc,
+            )
+            return index_path.read_text().replace("__SLM_VERSION__", _v)
 
     @application.get("/favicon.ico", include_in_schema=False)
     async def favicon():

package/src/superlocalmemory/server/unified_daemon.py

@@ -511,6 +511,49 @@ _MIGRATION_EXEMPT_PATH_PREFIXES: tuple[str, ...] = (
 )
 
 
+def _serving_blocked_by(migration_result: dict) -> list[str]:
+    """Failed migrations that should stop this daemon serving. Fail-closed.
+
+    A failed migration used to 503 every route without asking what had failed.
+    For a missing table that is right. For a data invariant that ordinary use can
+    re-violate it is not: one drifted row made the whole store unreachable until
+    somebody restarted it by hand, and the restart fixed nothing that a
+    background repair would not have fixed on its own.
+
+    A migration may answer for itself by exposing ``blocks_serving(conn)``.
+    Anything that does not is treated as blocking, so this cannot quietly open a
+    door for a migration nobody has thought about.
+    """
+    failed = list(migration_result.get("failed") or [])
+    if not failed:
+        return []
+    try:
+        import sqlite3
+
+        from superlocalmemory.infra.data_root import state_path
+        from superlocalmemory.storage._migration_internals import _MODULES
+    except Exception:  # noqa: BLE001 — never let this decide by crashing
+        return failed
+
+    blocking: list[str] = []
+    for name in failed:
+        decide = getattr(_MODULES.get(name), "blocks_serving", None)
+        if not callable(decide):
+            blocking.append(name)
+            continue
+        try:
+            db = state_path("memory.db")
+            conn = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+            try:
+                if decide(conn):
+                    blocking.append(name)
+            finally:
+                conn.close()
+        except Exception:  # noqa: BLE001 — unknown means blocking
+            blocking.append(name)
+    return blocking
+
+
 def _is_migration_exempt_path(path: str) -> bool:
     """Return True for health, status, and repair paths that must stay reachable
     even when the daemon reports a schema migration failure.
@@ -1804,6 +1847,41 @@ def _stop_deployment_retention(application) -> bool:
     return True
 
 
+def _start_embedder_warmup(engine: object) -> "threading.Thread | None":
+    """Load the embedding model in the background. Never blocks startup.
+
+    Returns the thread so a test can join it; ``None`` when there is nothing to
+    warm. Every failure is "not warmed", never a failed startup: a daemon that
+    cannot embed still serves keyword recall and still stores memories, and the
+    materializer fills the vectors in afterwards either way.
+    """
+    embedder = getattr(engine, "_embedder", None)
+    if embedder is None or not hasattr(embedder, "embed"):
+        return None
+
+    from superlocalmemory.core.engine import _is_remote_embedder
+
+    if _is_remote_embedder(embedder):
+        # A hosted embedder has no model to load and warming it would spend a
+        # request, and money, on a sentence nobody asked about.
+        return None
+
+    def _warm() -> None:
+        started = time.time()
+        try:
+            embedder.embed("slm embedder warm-up")
+        except Exception as exc:  # pragma: no cover — warming is best effort
+            logger.debug("embedder warm-up failed (%s) — writes will defer", exc)
+            return
+        logger.info(
+            "Embedding model warm and ready (%.1fs)", time.time() - started,
+        )
+
+    thread = threading.Thread(target=_warm, daemon=True, name="slm-embed-warmup")
+    thread.start()
+    return thread
+
+
 @asynccontextmanager
 async def lifespan(application: FastAPI):
     """Initialize engine, workers, and optional services on startup."""
@@ -2088,6 +2166,40 @@ async def lifespan(application: FastAPI):
         engine = MemoryEngine(config)
         engine.initialize()
 
+        # Load the embedding model now, off the request path, the way the
+        # cross-encoder is already warmed at startup.
+        #
+        # A write embeds inline so the memory it stores can be found by asking a
+        # question rather than only by quoting its own words, and it gives that
+        # one second before deferring to the materializer. Loading the model
+        # takes 9.9-11.0 s here; once loaded an embed is 42 ms. So on a daemon
+        # that had not embedded yet, the first writes each waited the full second
+        # and stored no vector regardless -- and the model only ever loaded
+        # because some *recall* eventually paid for it. Whoever recalled first
+        # wore the cold start.
+        #
+        # This belongs to the daemon and not to engine wiring: the worker is a
+        # subprocess per engine, so warming from wiring would have every `slm
+        # status` spawn one and load a model it will never use.
+        _start_embedder_warmup(engine)
+
+        # Tell the hook subprocesses that skill evolution is on. The hook reads
+        # this env var as its fast-path signal and nothing ever set it, so the
+        # feature was off for everyone who had switched it on in config: the
+        # hook checked, found nothing, and returned False. Hooks are launched as
+        # children of this process and inherit its environment, which is the
+        # only channel between the two.
+        try:
+            if getattr(getattr(config, "evolution", None), "enabled", False):
+                os.environ["SLM_EVOLUTION_ENABLED"] = "1"
+            else:
+                # Cleared as well as set: a daemon restarted with the setting
+                # turned off must not leave the previous run's answer behind in
+                # an environment the next hook inherits.
+                os.environ.pop("SLM_EVOLUTION_ENABLED", None)
+        except Exception as _evo_exc:  # pragma: no cover — never block startup
+            logger.debug("evolution flag not exported: %s", _evo_exc)
+
         # Refresh migration state now that the engine is initialised.  Any
         # schema work the engine's own bootstrap may have applied (e.g.
         # runtime-table creation) is captured here so the dashboard and
@@ -2175,6 +2287,30 @@ async def lifespan(application: FastAPI):
                 "deferred migration runner crashed (non-fatal): %s", _dexc,
             )
 
+        # Move an existing store onto the graph and vector backends on the
+        # first start after an upgrade. They have shipped as required
+        # dependencies since 3.7 and sat unused, because building the
+        # projections was three manual commands almost nobody ran. Runs after
+        # the deferred migrations so it projects the converted store, and never
+        # fatal: if the libraries will not import or the projection does not
+        # match, the daemon serves from SQLite and says so.
+        try:
+            from superlocalmemory.core.scale_autopromote import (
+                auto_promote_scale_backends,
+            )
+            _promotion = auto_promote_scale_backends(config)
+            application.state.scale_autopromotion = _promotion.as_dict()
+            if _promotion.promoted and _promotion.restart_required:
+                logger.info(
+                    "graph and vector backends are promoted and serve after the "
+                    "next restart",
+                )
+        except Exception as _pexc:  # pragma: no cover — defensive
+            logger.warning("automatic backend promotion crashed (non-fatal): %s", _pexc)
+            application.state.scale_autopromotion = {
+                "attempted": True, "promoted": False, "reason": str(_pexc),
+            }
+
         # S9-DASH-02: start the outcome-queue worker so recall →
         # pending_outcomes is actually produced. Before v3.4.22 this
         # producer had zero callers and the closed-loop pipeline was
@@ -3041,6 +3177,18 @@ async def lifespan(application: FastAPI):
             await _cancel_fact_entity_association_repair(application)
             await _cancel_source_quality_repair(application)
 
+    # Stop the projection drain. Its queue is durable, so an interrupted pass
+    # costs a repeat of idempotent work and nothing else — but a live worker
+    # writing into RocksDB and Lance while the process tears down around it has
+    # no upside.
+    try:
+        from superlocalmemory.core.backend_orchestrator import get_orchestrator
+        _orch = get_orchestrator()
+        if _orch is not None:
+            _orch.stop()
+    except Exception as exc:  # pragma: no cover — defensive
+        logger.warning("projection drain shutdown failed: %s", exc)
+
     # Cancel the cross-platform sync loop (H-CONC-2) so adapter file I/O does
     # not outlive the daemon.
     try:
@@ -3904,7 +4052,7 @@ def _register_dashboard_routes(application: FastAPI) -> None:
     @application.middleware("http")
     async def _migration_readiness_gate(request, call_next):
         migration_result = getattr(application.state, "migration_result", None)
-        if migration_result and migration_result.get("failed"):
+        if migration_result and _serving_blocked_by(migration_result):
             if not _is_migration_exempt_path(request.url.path):
                 from fastapi.responses import JSONResponse
                 return JSONResponse(
@@ -4072,12 +4220,26 @@ def _register_dashboard_routes(application: FastAPI) -> None:
         # 4.0.10: asset ?v= strings are now derived from file content instead of
         # being hand-written literals that tracked nothing. See
         # server/asset_versions.py — including what that does and does not fix.
-        from superlocalmemory.server.asset_versions import render_index
+        # Asset versioning is cosmetic. It must never be why this page 500s.
+        #
+        # The import is deferred (house style, keeps startup lean), which means
+        # it resolves at REQUEST time — so when `pip install -e .` replaced the
+        # installed package underneath a running daemon, this route began
+        # answering "Internal Server Error" on the dashboard while every other
+        # endpoint was fine. A stale hand-written version string is a trifle; a
+        # blank page is not. Fall back to the file as written.
+        try:
+            from superlocalmemory.server.asset_versions import render_index
 
-        return render_index(
-            index_path, UI_DIR,
-            substitutions={"__SLM_VERSION__": _SLM_VERSION},
-        )
+            return render_index(
+                index_path, UI_DIR, substitutions={"__SLM_VERSION__": _SLM_VERSION},
+            )
+        except Exception as exc:  # noqa: BLE001 — serve the page regardless
+            logger.warning(
+                "asset version rewrite unavailable, serving index.html as "
+                "written: %s: %s", type(exc).__name__, exc,
+            )
+            return index_path.read_text().replace("__SLM_VERSION__", _SLM_VERSION)
 
     @application.get("/favicon.ico", include_in_schema=False)
     async def favicon():
@@ -4159,7 +4321,14 @@ def _register_daemon_routes(application: FastAPI) -> None:
             (migration_result or {}).get("failed", []) or []
         )
         migration_details = (migration_result or {}).get("details", {}) or {}
-        migrations_ready = bool(migration_result) and not migration_failures
+        # Ready means "can serve", so it keys off the failures that actually
+        # stop this daemon serving -- not off every failure. A data invariant
+        # that ordinary use re-violated leaves every route working; reporting
+        # not-ready for it told operators to restart, which fixed nothing a
+        # background repair would not have fixed. Everything still shows up in
+        # migration_failures and migration_failure_reasons below, named.
+        migration_blocking = _serving_blocked_by(migration_result or {})
+        migrations_ready = bool(migration_result) and not migration_blocking
         if migration_details.get("_crash"):
             migrations_ready = False
         writer_runtime = getattr(
@@ -4177,6 +4346,23 @@ def _register_daemon_routes(application: FastAPI) -> None:
             "embedding": embedding_ready,
             "recall_health": recall_health.get("recall_healthy") is True,
             "migration_failures": migration_failures,
+            # Which of those are the reason this daemon will not serve, as
+            # opposed to the ones it is reporting while serving normally.
+            "migration_blocking": migration_blocking,
+            # WHY each one failed, not just which. The runner already produces
+            # a precise sentence per migration -- "safe repair did not restore
+            # M043_...", "schema verification failed ... : <sqlite error>" --
+            # and this endpoint computed it and then dropped it on the floor.
+            # A migration recorded ``complete`` in migration_log can still be
+            # reported failed here, because a completed migration is re-checked
+            # by its own verify() on every start; with only a name to go on,
+            # that reads as the health check contradicting the database. It is
+            # not: they are answering different questions, and this is the
+            # sentence that says which. Reported as #125.
+            "migration_failure_reasons": {
+                name: str(migration_details.get(name, "(no detail recorded)"))
+                for name in migration_failures
+            },
         }
         readiness["retrieval"] = bool(
             readiness["embedding"] and readiness["recall_health"]
@@ -4255,6 +4441,12 @@ def _register_daemon_routes(application: FastAPI) -> None:
             # reveal staleness on its own. Loopback-only, alongside the other
             # operational metadata.
             "version_integrity": _version_integrity_payload(),
+            # How far behind the second graph store is. A drain that stops
+            # advancing is the failure that does not announce itself: every
+            # other signal here stays green while the graph quietly diverges
+            # from the record, and the only symptom is answers that are subtly
+            # worse. A depth that does not fall is the thing to alert on.
+            "projection": _projection_health(),
         }
 
     @application.get("/recall")
@@ -4909,6 +5101,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
         fact_count = 0
         entity_count = 0
         edge_count = 0
+        projection_queue_depth = 0
         if engine is not None:
             try:
                 fact_count = engine._db.get_fact_count(profile_snapshot.profile_id)
@@ -4925,6 +5118,11 @@ def _register_daemon_routes(application: FastAPI) -> None:
                 edge_count = int(dict(edges[0])["c"]) if edges else 0
             except Exception:
                 logger.debug("daemon status count query failed", exc_info=True)
+            try:
+                from superlocalmemory.storage import projection_outbox
+                projection_queue_depth = projection_outbox.depth(engine._db)
+            except Exception:
+                logger.debug("projection queue depth unavailable", exc_info=True)
         db_path = getattr(config, "db_path", None)
         db_size_mb = (
             round(db_path.stat().st_size / 1024 / 1024, 2)
@@ -4950,6 +5148,10 @@ def _register_daemon_routes(application: FastAPI) -> None:
             "legacy_port": _LEGACY_PORT,
             "profile": profile_snapshot.profile_id,
             "profile_generation": profile_snapshot.generation,
+            # Facts stored but not yet in the graph and vector projections. The
+            # CLI and MCP read their own status from here, so this is where the
+            # number has to be for all three surfaces to agree.
+            "projection_queue_depth": projection_queue_depth,
             # F2 fix: expose M028 backfill progress so operators can monitor
             # the post-upgrade fact/entity association repair state.
             "m028_backfill": getattr(
@@ -5561,6 +5763,38 @@ def _terminalize_orphan_operation(engine, operation_id: str) -> None:
         )
 
 
+def _projection_health() -> dict:
+    """Queue depth, stall count, and whether the worker is running.
+
+    Never raises: a health endpoint that fails because one of its fields could
+    not be computed is worse than the missing field.
+
+    Takes no application. It used to accept one and never read it -- the
+    orchestrator is a process singleton -- which made the signature claim a
+    dependency the body did not have, and made a test that handed it a broken
+    application look like it was exercising the failure path when it was only
+    observing whatever the process had already built. Compare
+    ``_ops_failure_counts`` directly below, which takes an application because it
+    genuinely reads one.
+    """
+    try:
+        from superlocalmemory.core.backend_orchestrator import get_orchestrator
+
+        orchestrator = get_orchestrator()
+        if orchestrator is None:
+            return {"available": False}
+        health = dict(orchestrator.outbox_health())
+        health["available"] = True
+        # One boolean an alert can key on without knowing what a healthy depth
+        # looks like on this store.
+        health["behind"] = bool(health.get("depth", 0)) or bool(
+            health.get("stalled", 0)
+        )
+        return health
+    except Exception as exc:  # noqa: BLE001
+        return {"available": False, "error": str(exc)[:120]}
+
+
 def _ops_failure_counts(engine, application) -> dict:
     """Return operational failure counts for /status and /health.