superlocalmemory 3.8.11 → 3.8.13

package/src/superlocalmemory/cli/daemon.py

@@ -41,6 +41,10 @@ from superlocalmemory.infra.data_root import (
     assert_no_durable_root_conflict,
     state_path,
 )
+from superlocalmemory.infra.process_identity import (
+    compare_start_tokens,
+    process_start_token_for,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -72,25 +76,91 @@ def _is_pid_alive(pid: int) -> bool:
             return False
 
 
-def _descriptor_process_is_alive(descriptor) -> bool:
-    """Reject stale descriptors when a PID has been reused by another process."""
-    if not _is_pid_alive(descriptor.pid):
+_CREATE_TIME_TOLERANCE_SECONDS = 1.0
+
+
+def _health_proves_descriptor_ownership(descriptor) -> bool:
+    """Return whether the live health endpoint proves this exact daemon.
+
+    This is a *stronger* ownership proof than any process-table comparison. To
+    pass, a process listening on the descriptor's port must echo the random
+    128-bit ``instance_id`` and the SHA-256 fingerprint of the 256-bit
+    capability token -- both of which exist only inside the mode-0600
+    ``daemon.json`` -- alongside its own PID, namespace, owner and port. A
+    process that merely inherited a recycled PID cannot produce any of that.
+    """
+    health = _fetch_health(descriptor.port)
+    if health is None:
         return False
+    return descriptor_matches_health(descriptor, health)
+
+
+def _resolve_descriptor_liveness(descriptor) -> tuple[bool, str]:
+    """Return ``(is_alive, evidence)`` for the descriptor's recorded process.
+
+    Ownership is decided by the strongest available evidence, never by the
+    wall clock alone:
+
+    1. The PID must exist and must not be a zombie.
+    2. A clock-independent start token settles it exactly, with no tolerance.
+       This is the path that fixes issue #104: under WSL2 the boot time behind
+       ``psutil.create_time`` drifts against the wall clock during a session,
+       so a recorded creation time stops matching the *same* live process
+       (~35s after ~4 minutes).  A start token cannot drift, so no tolerance
+       constant is needed and none can silently expire.
+    3. Otherwise fall back to comparing creation times, for descriptors written
+       by an older release and for platforms with no token (Windows, where the
+       kernel creation time is already immune to clock adjustment).
+    4. A creation-time mismatch is *not* proof of PID reuse -- it is exactly
+       what a stepped clock looks like -- so before condemning a running
+       daemon, ask the daemon to prove its identity over loopback. Only if that
+       cryptographic proof also fails is the process declared foreign.
+    """
+    if not _is_pid_alive(descriptor.pid):
+        return False, "process_exited"
     try:
         import psutil
-
+    except ImportError:
+        # Without psutil, PID existence is the only signal there is.
+        return True, "pid_exists_without_psutil"
+    try:
         process = psutil.Process(descriptor.pid)
         # A terminated daemon can remain in the process table briefly as a
         # zombie while its parent reaps it.  PID existence is therefore not
         # liveness and must not block a namespace-owned restart.
         if not process.is_running() or process.status() == psutil.STATUS_ZOMBIE:
-            return False
-        actual = float(process.create_time())
-    except ImportError:
-        return True
+            return False, "process_zombie"
+        actual_create_time = float(process.create_time())
     except Exception:
-        return False
-    return abs(actual - float(descriptor.process_create_time)) <= 1.0
+        return False, "process_unreadable"
+
+    recorded_token = getattr(descriptor, "process_start_token", None)
+    if recorded_token:
+        verdict = compare_start_tokens(
+            recorded_token, process_start_token_for(descriptor.pid),
+        )
+        if verdict is True:
+            return True, "start_token_match"
+        if verdict is False:
+            return False, "start_token_mismatch"
+
+    drift = abs(actual_create_time - float(descriptor.process_create_time))
+    if drift <= _CREATE_TIME_TOLERANCE_SECONDS:
+        return True, "create_time_match"
+
+    if _health_proves_descriptor_ownership(descriptor):
+        logger.debug(
+            "descriptor creation time drifted by %.3fs for pid %s; owned "
+            "daemon confirmed by health identity instead",
+            drift, descriptor.pid,
+        )
+        return True, "health_identity_match"
+    return False, "identity_mismatch"
+
+
+def _descriptor_process_is_alive(descriptor) -> bool:
+    """Reject stale descriptors when a PID has been reused by another process."""
+    return _resolve_descriptor_liveness(descriptor)[0]
 
 
 def _is_port_available(port: int) -> bool:
@@ -420,6 +490,7 @@ def _start_daemon_subprocess() -> bool:
         bootstrap_descriptor,
         pid=proc.pid,
         process_create_time=process_create_time_for(proc.pid),
+        process_start_token=process_start_token_for(proc.pid),
     )
     current = read_descriptor()
     if not (
@@ -545,6 +616,144 @@ def _wait_for_daemon(timeout: int = 60) -> bool:
     return False
 
 
+_GENERIC_UNAVAILABLE = {
+    "reason": "unknown",
+    "message": "Owned daemon is unavailable; retry later.",
+    "hint": "Run `slm doctor`, then `slm restart` if it stays down.",
+}
+
+_LIVENESS_DIAGNOSIS = {
+    "process_exited": (
+        "daemon_process_exited",
+        "the recorded daemon process (pid {pid}) is no longer running",
+        "Start it again with `slm start`.",
+    ),
+    "process_zombie": (
+        "daemon_process_exited",
+        "the recorded daemon process (pid {pid}) has exited and is awaiting "
+        "reaping by its parent",
+        "Start it again with `slm start`.",
+    ),
+    "process_unreadable": (
+        "daemon_process_unreadable",
+        "the recorded daemon process (pid {pid}) could not be inspected; it "
+        "may belong to another user",
+        "Run `slm restart` to publish a fresh descriptor.",
+    ),
+    "start_token_mismatch": (
+        "pid_reused_by_another_process",
+        "pid {pid} is alive but is a different process than the daemon that "
+        "wrote {path}; the daemon exited and its pid was recycled",
+        "Run `slm restart` to publish a fresh descriptor.",
+    ),
+    "identity_mismatch": (
+        "daemon_identity_mismatch",
+        "pid {pid} did not match the process identity recorded in {path} and "
+        "the process on port {port} did not prove it owns that identity; the "
+        "recorded creation time can also diverge on its own if this machine's "
+        "clock is stepped (common under WSL2)",
+        "Run `slm restart` to publish a fresh descriptor.",
+    ),
+}
+
+
+def describe_daemon_unavailability() -> dict[str, str]:
+    """Explain *why* the owned daemon cannot be used, in actionable terms.
+
+    "Owned daemon is unavailable" is true of a stopped daemon, a recycled PID,
+    an unreachable port and an identity mismatch alike, which left issue #104's
+    reporter with nothing to act on. This names the specific evidence instead.
+    Diagnosis is best-effort and never raises: a broken diagnosis must not
+    replace the caller's real error.
+    """
+    try:
+        return _describe_daemon_unavailability()
+    except Exception:  # noqa: BLE001 - diagnosis is advisory only
+        return dict(_GENERIC_UNAVAILABLE)
+
+
+def _describe_daemon_unavailability() -> dict[str, str]:
+    path = descriptor_path()
+    descriptor = read_descriptor()
+    if descriptor is None:
+        if path.exists():
+            return {
+                "reason": "descriptor_unusable",
+                "message": (
+                    f"{path} is unreadable, malformed, or belongs to another "
+                    f"data root or user."
+                ),
+                "hint": "Run `slm restart` to publish a fresh descriptor.",
+            }
+        if _verified_legacy_health() is not None:
+            return {
+                "reason": "legacy_daemon_request_failed",
+                "message": (
+                    "a pre-descriptor daemon answered health but rejected or "
+                    "dropped the request."
+                ),
+                "hint": "Run `slm restart` to upgrade it to an owned daemon.",
+            }
+        return {
+            "reason": "no_daemon",
+            "message": f"no daemon is registered for this data root ({path} is absent).",
+            "hint": "Run `slm start`.",
+        }
+
+    alive, evidence = _resolve_descriptor_liveness(descriptor)
+    if not alive:
+        reason, template, hint = _LIVENESS_DIAGNOSIS.get(
+            evidence,
+            (
+                "daemon_identity_mismatch",
+                "pid {pid} did not match the identity recorded in {path}",
+                "Run `slm restart` to publish a fresh descriptor.",
+            ),
+        )
+        return {
+            "reason": reason,
+            "message": template.format(
+                pid=descriptor.pid, port=descriptor.port, path=path,
+            ) + ".",
+            "hint": hint,
+        }
+
+    health = _fetch_health(descriptor.port)
+    if health is None:
+        return {
+            "reason": "daemon_unreachable",
+            "message": (
+                f"the owned daemon (pid {descriptor.pid}) is running but did "
+                f"not answer http://127.0.0.1:{descriptor.port}/health within "
+                f"2s."
+            ),
+            "hint": (
+                "Check `slm logs` for a stalled request, or `slm restart` if "
+                "it stays unresponsive."
+            ),
+        }
+    if not descriptor_matches_health(descriptor, health):
+        return {
+            "reason": "port_owned_by_another_daemon",
+            "message": (
+                f"port {descriptor.port} answered health but with a different "
+                f"daemon identity than {path} records."
+            ),
+            "hint": (
+                "Another SuperLocalMemory instance holds that port. Stop it, "
+                "or set SLM_DAEMON_PORT to a free port."
+            ),
+        }
+    return {
+        "reason": "request_rejected",
+        "message": (
+            f"the owned daemon (pid {descriptor.pid}) is healthy but rejected "
+            f"or dropped this request."
+        ),
+        "hint": "Check `slm logs` for the failing request.",
+    }
+
+
 def stop_daemon() -> bool:
     """Stop only the daemon proven to belong to this data namespace.
 

package/src/superlocalmemory/cli/setup_wizard.py

@@ -274,6 +274,35 @@ def _embedding_is_remote(config: Any) -> bool:
     return provider in ("openai", "openai-compatible", "remote") or bool(endpoint)
 
 
+def _reranker_is_remote(config: Any) -> bool:
+    """True when reranking runs against a remote endpoint (v3.8.12, #105).
+
+    In that case the local ~130MB English cross-encoder download is pointless
+    — and worse, misleading, since it is not the model that will score recall.
+    Unlike embeddings, the endpoint alone is NOT sufficient: a stray endpoint
+    against a local backend is a misconfiguration the engine reports, not a
+    remote setup.
+    """
+    rt = getattr(config, "retrieval", None)
+    if rt is None:
+        return False
+    backend = (getattr(rt, "cross_encoder_backend", "") or "").strip().lower()
+    endpoint = getattr(rt, "cross_encoder_endpoint", "") or ""
+    return backend in ("openai", "remote") and bool(endpoint)
+
+
+# Remote-reranker keys the wizard never asks about. ``retrieval`` is otherwise
+# a mode-owned block that the wizard resets from the template, which would
+# silently delete a working remote endpoint on every re-run (#105).
+_USER_OWNED_RETRIEVAL_KEYS = (
+    "cross_encoder_backend",
+    "cross_encoder_endpoint",
+    "cross_encoder_api_key",
+    "cross_encoder_model",
+    "cross_encoder_timeout_seconds",
+)
+
+
 def _build_wizard_config(mode):
     """Apply mode-owned presets without erasing existing user-owned blocks."""
     from superlocalmemory.core.config import SLMConfig
@@ -285,7 +314,14 @@ def _build_wizard_config(mode):
     existing = SLMConfig.load()
     existing.mode = mode
     existing.llm = template.llm
+    preserved = {
+        key: getattr(existing.retrieval, key)
+        for key in _USER_OWNED_RETRIEVAL_KEYS
+        if hasattr(existing.retrieval, key)
+    }
     existing.retrieval = template.retrieval
+    for key, value in preserved.items():
+        setattr(existing.retrieval, key, value)
     existing.math = template.math
     existing.channel_weights = template.channel_weights
     return existing
@@ -566,7 +602,15 @@ def run_wizard(auto: bool = False) -> None:
     print()
     print("─── Step 4b/10: Download Reranker Model ───")
 
-    if not st_ok:
+    if _reranker_is_remote(config):
+        # v3.8.12 (#105): a remote /v1/rerank endpoint scores the results, so
+        # the local English cross-encoder would be dead weight on disk.
+        rt = config.retrieval
+        print("  ✓ Skipped — remote rerank endpoint configured")
+        print(f"    backend={getattr(rt, 'cross_encoder_backend', '?')}, "
+              f"model={getattr(rt, 'cross_encoder_model', '?')}")
+        print("    No local reranker model needed.")
+    elif not st_ok:
         print("  ⚠ Skipped (sentence-transformers not installed)")
     else:
         _download_reranker(_RERANKER_MODEL)

package/src/superlocalmemory/core/component_registry.py

@@ -164,6 +164,20 @@ def _embedding_is_remote(config: Any) -> bool:
         return False
 
 
+def _reranker_is_remote(config: Any) -> bool:
+    """True when reranking is served by a remote endpoint (v3.8.12, #105).
+
+    Same shape as ``_embedding_is_remote``: conservative False on any
+    import/attribute error so a local reranker is still probed.
+    """
+    try:
+        from superlocalmemory.cli.setup_wizard import _reranker_is_remote as _r
+
+        return bool(_r(config))
+    except Exception:
+        return False
+
+
 # --------------------------------------------------------------------------
 # Individual probes — each returns a Component (never raises)
 # --------------------------------------------------------------------------
@@ -259,6 +273,17 @@ def probe_reranker_model(config: Any = None) -> Component:
             if config is not None else True
     except Exception:
         enabled = True
+    if enabled and config is not None and _reranker_is_remote(config):
+        # v3.8.12 (#105): a remote /v1/rerank endpoint supplies the scores, so
+        # the local 130MB English cross-encoder is neither downloaded nor used.
+        # Reporting it MISSING would push the operator to "fix" a component the
+        # configured runtime never touches.
+        return Component(
+            key="reranker_model", label="Reranker model",
+            category=CATEGORY_RECOMMENDED, status=STATUS_OK,
+            detail="remote rerank endpoint (no local model required)",
+            last_checked=time.time(),
+        )
     comp = _probe_hf_model(
         "reranker_model", "Reranker model", _RERANKER_MODEL,
         category=CATEGORY_RECOMMENDED if enabled else CATEGORY_OPTIONAL,

package/src/superlocalmemory/core/config.py

@@ -267,7 +267,41 @@ class RetrievalConfig:
     # relevant facts before reranking. See bench-v342-locomo.md.
     use_cross_encoder: bool = True
     cross_encoder_model: str = "cross-encoder/ms-marco-MiniLM-L-12-v2"
-    cross_encoder_backend: str = ""  # "" = PyTorch (~500MB stable), "onnx" = ONNX (leaks on ARM64 CoreML)
+    # "" = PyTorch (~500MB stable), "onnx" = ONNX (leaks on ARM64 CoreML),
+    # "openai"/"remote" = v3.8.12 (issue #105) OpenAI-compatible /v1/rerank
+    # endpoint (llama-server, TEI, Infinity, vLLM, Cohere-shaped services).
+    cross_encoder_backend: str = ""
+
+    # v3.8.12 (issue #105): remote reranker endpoint. The bundled default
+    # cross-encoder (ms-marco-MiniLM-L-12-v2) is ENGLISH-ONLY, so non-English
+    # deployments scored their own language with a model that cannot read it.
+    # Pointing this at a multilingual reranker (bge-reranker-v2-m3, a Qwen
+    # reranker, …) is the same escape hatch remote embeddings got in v3.4.24.
+    #
+    # This key was accepted-and-ignored before 3.8.12 (issue #103): it was not
+    # a dataclass field, so ``SLMConfig.load`` filtered it out without a word.
+    # It is now read, validated, and — when it disagrees with the backend —
+    # reported as a loud configuration error instead of nothing at all.
+    cross_encoder_endpoint: str = ""
+    # Optional bearer token. Prefer the SLM_CROSS_ENCODER_API_KEY environment
+    # variable — it takes precedence and keeps the secret out of config.json.
+    cross_encoder_api_key: str = ""
+    # Per-request read budget for the remote reranker. Recall is interactive,
+    # so this stays tight: a slow reranker degrades to fusion scores rather
+    # than holding the recall open.
+    cross_encoder_timeout_seconds: float = 15.0
+
+    @property
+    def is_remote_cross_encoder(self) -> bool:
+        """True when reranking is served by a remote HTTP endpoint."""
+        from superlocalmemory.retrieval.remote_reranker import (
+            is_remote_cross_encoder_backend,
+        )
+
+        return (
+            is_remote_cross_encoder_backend(self.cross_encoder_backend)
+            and bool(self.cross_encoder_endpoint)
+        )
 
     # Agentic (Mode C only)
     agentic_max_rounds: int = 3

package/src/superlocalmemory/core/engine_wiring.py

@@ -22,8 +22,88 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def init_reranker(retrieval_config: Any) -> Any:
+    """Build the reranker the config asks for — remote endpoint or local worker.
+
+    v3.8.12 (issue #105). The remote branch is decided HERE, in the parent
+    process, before any subprocess exists. Spawning a worker whose only job
+    would be to forward an HTTP POST costs a fork, a machine-wide PID
+    singleton, and a warmup handshake for nothing — and issue #103 showed that
+    singleton blocking a reranker that was never local in the first place.
+
+    Misconfiguration is reported, never absorbed:
+      * remote backend with no/invalid endpoint -> reranking is DISABLED with
+        an error naming the fix. Quietly loading the English local model
+        instead would recreate the exact silent degradation #105 is about.
+      * endpoint set against a LOCAL backend -> error naming both keys, then
+        the local reranker runs as the backend actually requested. Before
+        3.8.12 this combination was dropped in silence (issue #103).
+
+    Returns the reranker, or None when reranking must stay off.
+    """
+    from superlocalmemory.retrieval.remote_reranker import (
+        RemoteReranker,
+        RemoteRerankerConfigError,
+        is_remote_cross_encoder_backend,
+        validate_remote_reranker_config,
+    )
+    from superlocalmemory.retrieval.reranker import CrossEncoderReranker
+
+    backend = getattr(retrieval_config, "cross_encoder_backend", "") or ""
+    endpoint = getattr(retrieval_config, "cross_encoder_endpoint", "") or ""
+    model = getattr(
+        retrieval_config, "cross_encoder_model",
+        "cross-encoder/ms-marco-MiniLM-L-12-v2",
+    )
+    remote_requested = is_remote_cross_encoder_backend(backend)
+
+    error = validate_remote_reranker_config(backend, endpoint)
+    if error and remote_requested:
+        logger.error(
+            "Remote reranker not started — %s Reranking is DISABLED; recall "
+            "returns fusion-ranked results.", error,
+        )
+        return None
+    if error:
+        logger.error(
+            "Reranker configuration conflict — %s Continuing with the local "
+            "cross-encoder as configured.", error,
+        )
+    elif remote_requested:
+        try:
+            return RemoteReranker(
+                model,
+                endpoint,
+                api_key=getattr(retrieval_config, "cross_encoder_api_key", ""),
+                backend=backend,
+                timeout_seconds=getattr(
+                    retrieval_config, "cross_encoder_timeout_seconds", 15.0,
+                ),
+            )
+        except RemoteRerankerConfigError as exc:
+            logger.error(
+                "Remote reranker not started — %s Reranking is DISABLED.", exc,
+            )
+            return None
+
+    return CrossEncoderReranker(model, backend=backend)
+
+
 def _log_reranker_warmup_status(reranker: Any) -> None:
     """Record non-blocking reranker warmup state without alarming first-run users."""
+    from superlocalmemory.retrieval.remote_reranker import RemoteReranker
+
+    # isinstance, not a duck-typed attribute probe: MagicMock fabricates any
+    # attribute on demand, so ``getattr(reranker, "is_remote", False)`` would
+    # route every mocked reranker in the suite down the remote branch. Same
+    # hazard RetrievalEngine guards against when it checks the TYPE for
+    # ``rerank_with_status``.
+    if isinstance(reranker, RemoteReranker):
+        # The remote reranker logs its own probe outcome (endpoint, model, and
+        # the precise transport error). A second generic line about a local
+        # worker singleton would be noise at best and misleading at worst.
+        reranker.warmup_sync()
+        return
     ready = reranker.warmup_sync(timeout=180)
     if ready:
         logger.info("Cross-encoder reranker warm and ready")
@@ -508,7 +588,6 @@ def init_retrieval(
     from superlocalmemory.retrieval.bm25_channel import BM25Channel
     from superlocalmemory.retrieval.entity_channel import EntityGraphChannel
     from superlocalmemory.retrieval.temporal_channel import TemporalChannel
-    from superlocalmemory.retrieval.reranker import CrossEncoderReranker
     from superlocalmemory.retrieval.profile_channel import ProfileChannel
     from superlocalmemory.retrieval.bridge_discovery import BridgeDiscovery
 
@@ -541,10 +620,7 @@ def init_retrieval(
 
     reranker = None
     if config.retrieval.use_cross_encoder:
-        reranker = CrossEncoderReranker(
-            config.retrieval.cross_encoder_model,
-            backend=config.retrieval.cross_encoder_backend,
-        )
+        reranker = init_reranker(config.retrieval)
 
     profile_ch = ProfileChannel(db)
     bridge = BridgeDiscovery(db)

package/src/superlocalmemory/core/recall_pipeline.py

@@ -283,7 +283,14 @@ class _ReadOnlyLearningView:
             connection.close()
 
     def count_feedback(self, profile_id: str) -> int:
-        """Count legacy feedback without running schema initialization."""
+        """Count legacy feedback without running schema initialization.
+
+        Reports the raw ``learning_feedback`` table, which the dashboard
+        surfaces as ``legacy_feedback_rows`` alongside a pending-migration
+        card. Do NOT gate a ranking phase on this — use ``count_signals``,
+        which is the counter every other surface resolves its phase from
+        (issue #106).
+        """
         connection = self._connection()
         try:
             row = connection.execute(
@@ -408,17 +415,31 @@ def apply_adaptive_ranking(
     if not learning_db.exists():
         return response
 
+    # issue #106: count the CANONICAL store, not the legacy one. The
+    # dashboard's Living Brain panel and ranker-phase card both resolve their
+    # phase from ``learning_signals``; this gate read ``learning_feedback``,
+    # so the phase a user was shown and the phase that actually ranked their
+    # results were computed from different tables and could disagree without
+    # limit. ``learning_feedback`` rows reach this counter through
+    # ``legacy_migration``, which copies them forward.
     try:
-        signal_count = _ReadOnlyLearningView(learning_db).count_feedback(pid)
+        signal_count = _ReadOnlyLearningView(learning_db).count_signals(pid)
     except sqlite3.Error:
         # A pre-learning database may not have this optional table yet.
         # Recall remains a query and cannot create it on demand.
         return response
 
-    if signal_count < 50:
+    from superlocalmemory.learning.ranker import (
+        PHASE_2_THRESHOLD,
+        AdaptiveRanker,
+    )
+
+    # Thresholds come from ``learning.ranker`` — the same constants the
+    # dashboard gates on. Duplicating the literals here is how the two
+    # surfaces drifted apart in the first place.
+    if signal_count < PHASE_2_THRESHOLD:
         return response  # Phase 1: no change
 
-    from superlocalmemory.learning.ranker import AdaptiveRanker
     ranker = AdaptiveRanker(signal_count=signal_count)
 
     from datetime import UTC

package/src/superlocalmemory/core/reranker_worker.py

@@ -230,6 +230,11 @@ def _worker_main() -> None:
 
 
 _KNOWN_BACKENDS = ("onnx", "", "pytorch", "torch")
+# Backends this worker can never serve — they are handled over HTTP by
+# superlocalmemory.retrieval.remote_reranker in the parent process (#105).
+# Duplicated as a literal on purpose: this module runs as a bare subprocess
+# and must not import the retrieval package (or, transitively, httpx).
+_REMOTE_BACKENDS = ("openai", "remote")
 
 
 def _load_model(
@@ -253,12 +258,26 @@ def _load_model(
     # the PyTorch tier and fail there with a confusing model-load error. A
     # user who set backend="openai" expecting a remote reranker got five
     # silent failures and no hint that the value meant nothing. Name it.
+    #
+    # v3.8.12 (issue #105): remote reranking now EXISTS, but it is served in
+    # the parent process — this worker holds torch/ONNX and cannot forward an
+    # HTTP request. Reaching here with a remote backend means the parent
+    # routed wrong (or a caller drove the worker directly), so the message
+    # points at the config keys that select the remote path.
+    if backend in _REMOTE_BACKENDS:
+        return None, "", "", (
+            f"unknown backend {backend!r} for the LOCAL reranker worker. "
+            f"{backend!r} selects the remote reranker, which runs in the "
+            f"parent process — set retrieval.cross_encoder_endpoint (e.g. "
+            f"\"http://127.0.0.1:8041/v1/rerank\") so SuperLocalMemory routes "
+            f"reranking over HTTP instead of spawning this worker."
+        )
     if backend not in _KNOWN_BACKENDS:
         return None, "", "", (
-            f"unknown backend {backend!r}; supported values are "
-            f"'onnx' or '' (PyTorch). SuperLocalMemory has no remote/"
-            f"OpenAI-compatible reranker backend — the cross-encoder always "
-            f"runs locally, so 'cross_encoder_endpoint' has no effect."
+            f"unknown backend {backend!r}; supported values are 'onnx' or ''"
+            f" (PyTorch) for local reranking, or 'openai'/'remote' with "
+            f"retrieval.cross_encoder_endpoint set for a remote "
+            f"OpenAI-compatible /v1/rerank endpoint."
         )
 
     tier_errors: list[str] = []

package/src/superlocalmemory/infra/daemon_identity.py

@@ -26,6 +26,7 @@ from pathlib import Path
 from typing import Any, Mapping
 
 from superlocalmemory.infra.data_root import canonical_data_root
+from superlocalmemory.infra.process_identity import process_start_token_for
 
 DAEMON_DESCRIPTOR_SCHEMA = 1
 DAEMON_PROTOCOL = 1
@@ -88,6 +89,11 @@ class DaemonDescriptor:
     state: str
     version: str
     started_at: float
+    # Clock-independent process identity. Optional and defaulted so a
+    # descriptor written by an older release still parses; platforms without a
+    # boot-relative start time (Windows) legitimately store None and fall back
+    # to the creation-time comparison. See infra/process_identity.py.
+    process_start_token: str | None = None
 
     def public_health_fields(self) -> dict[str, Any]:
         """Identity fields safe to expose on the loopback health endpoint."""
@@ -112,6 +118,7 @@ def build_descriptor(
     version: str,
     pid: int | None = None,
     process_create_time: float | None = None,
+    process_start_token: str | None = None,
     instance_id: str | None = None,
     capability: str | None = None,
     state: str = "starting",
@@ -141,6 +148,11 @@ def build_descriptor(
         state=state,
         version=version,
         started_at=float(started_at if started_at is not None else time.time()),
+        process_start_token=(
+            process_start_token
+            if process_start_token is not None
+            else process_start_token_for(actual_pid)
+        ),
     )
 
 
@@ -238,6 +250,10 @@ def read_descriptor(
         return None
     if not (1 <= descriptor.port <= 65535) or descriptor.pid <= 0:
         return None
+    if descriptor.process_start_token is not None and not isinstance(
+        descriptor.process_start_token, str
+    ):
+        return None
     return descriptor