ltcai 9.9.3 → 9.9.5

package/latticeai/models/router.py

@@ -78,6 +78,27 @@ If context or old chat history mentions those names, treat them only as legacy a
 You are a Vision-Language Model (VLM). If an image is provided, analyze it.
 Be concise and respond in the user's language."""
 
+# Appended ONLY when retrieved context exists (review 2026-07-25 Wave 2.3):
+# grounded answers should cite their sources and admit gaps. Advisory prompt
+# guidance — grounding assessment stays annotation-only and never blocks.
+CITATION_INSTRUCTION = """The Context section above contains retrieved sources.
+Ground your claims in those sources and cite them inline as [1], [2], ... matching the order they appear in the Context.
+If the context does not cover the question, say so instead of inventing sources.
+Never cite a source that is not in the Context."""
+
+
+def _compose_system(base: str, context: str) -> str:
+    """Compose the system prompt with optional retrieved context.
+
+    Byte-compatible with the historical prompt when ``context`` is empty:
+    the return value is exactly ``base``. When context exists, the Context
+    block plus :data:`CITATION_INSTRUCTION` are appended.
+    """
+    if not context:
+        return base
+    return f"{base}\n\nContext:\n{context}\n\n{CITATION_INSTRUCTION}"
+
+
 def normalize_branding(text: Optional[str]) -> str:
     if not text:
         return ""
@@ -497,10 +518,8 @@ class LLMRouter:
         return raw
 
     def _build_prompt(self, message: str, context: Optional[str], tokenizer) -> str:
-        system = SYSTEM_PROMPT
         context = normalize_branding(context)
-        if context:
-            system += f"\n\nContext:\n{context}"
+        system = _compose_system(SYSTEM_PROMPT, context)
         if hasattr(tokenizer, "apply_chat_template"):
             try:
                 msgs = [{"role": "system", "content": system}, {"role": "user", "content": message}]
@@ -510,10 +529,8 @@ class LLMRouter:
         return f"<|im_start|>system\n{system}<|im_end|>\n<|im_start|>user\n{message}<|im_end|>\n<|im_start|>assistant\n"
 
     def _build_vlm_prompt(self, model, processor, message: str, context: Optional[str], num_images: int) -> str:
-        system = SYSTEM_PROMPT
         context = normalize_branding(context)
-        if context:
-            system += f"\n\nContext:\n{context}"
+        system = _compose_system(SYSTEM_PROMPT, context)
         try:
             from mlx_vlm import apply_chat_template
 
@@ -616,10 +633,8 @@ class LLMRouter:
         return normalize_branding(str(result))
 
     async def _cloud_generate(self, cloud: CloudModel, message: str, context: Optional[str], max_tokens: int, temperature: float) -> str:
-        system = SYSTEM_PROMPT
         context = normalize_branding(context)
-        if context:
-            system += f"\n\nContext:\n{context}"
+        system = _compose_system(SYSTEM_PROMPT, context)
         try:
             response = await cloud.client.chat.completions.create(
                 model=cloud.model,
@@ -703,10 +718,8 @@ class LLMRouter:
             yield chunk
 
     async def _cloud_stream_generate(self, cloud: CloudModel, message: str, context: Optional[str], max_tokens: int, temperature: float) -> AsyncIterator[str]:
-        system = SYSTEM_PROMPT
         context = normalize_branding(context)
-        if context:
-            system += f"\n\nContext:\n{context}"
+        system = _compose_system(SYSTEM_PROMPT, context)
         try:
             stream = await cloud.client.chat.completions.create(
                 model=cloud.model,

package/latticeai/services/architecture_readiness.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, List
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
 
-ARCHITECTURE_VERSION_TARGET = "9.9.3"
+ARCHITECTURE_VERSION_TARGET = "9.9.5"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/command_center.py

@@ -23,9 +23,10 @@ calls a model.
 from __future__ import annotations
 
 import logging
+from datetime import datetime, timedelta
 from typing import Any, Dict, List, Optional
 
-from latticeai.core.timeutil import now_iso as _now
+from latticeai.core.timeutil import local_now, now_iso as _now, parse_iso
 
 LOGGER = logging.getLogger(__name__)
 
@@ -33,6 +34,13 @@ _RECENT_NODE_LIMIT = 6
 _SEARCH_HISTORY_LIMIT = 2000
 _BRIEFING_HISTORY_LIMIT = 2000
 
+# Graph-hygiene advisory (review 2026-07-25 Wave 2.5): once the graph passes
+# this many nodes with no noise-curate pass in the stale window, the briefing
+# suggests a *dry-run* /knowledge-graph/curate/noise. Advisory only — nothing
+# is deleted until the user explicitly applies the job.
+_HYGIENE_MIN_NODES = 200
+_HYGIENE_STALE_DAYS = 7
+
 
 def _clip(text: Any, limit: int = 160) -> str:
     value = str(text or "").strip()
@@ -240,6 +248,73 @@ class CommandCenterService:
         ]
         return {"available": True, "count": len(suggestions), "top": top}
 
+    def _hygiene_section(self) -> Dict[str, Any]:
+        """Advisory graph-hygiene signal (review 2026-07-25 Wave 2.5).
+
+        Suggests a dry-run noise-curate pass when the graph has grown past
+        ``_HYGIENE_MIN_NODES`` nodes and the last applied pass is missing or
+        older than ``_HYGIENE_STALE_DAYS`` days. Fail-open: any backend error
+        degrades to "no suggestion" — the briefing itself never breaks.
+        """
+        section: Dict[str, Any] = {
+            "available": False,
+            "suggest_noise_curate": False,
+            "reason": "",
+            "last_noise_curate_at": None,
+            "node_count": 0,
+        }
+        if not self._enable_graph or not hasattr(self._kg, "stats"):
+            return section
+        try:
+            stats = self._kg.stats() or {}
+            node_count = sum(
+                int(count or 0) for count in (stats.get("nodes") or {}).values()
+            )
+            last = (
+                self._kg.last_noise_curate_at()
+                if hasattr(self._kg, "last_noise_curate_at")
+                else None
+            )
+            section.update(
+                {
+                    "available": True,
+                    "node_count": node_count,
+                    "last_noise_curate_at": last,
+                }
+            )
+            if node_count < _HYGIENE_MIN_NODES:
+                return section
+            if last is not None and not self._older_than_days(
+                last, _HYGIENE_STALE_DAYS
+            ):
+                return section
+            section["suggest_noise_curate"] = True
+            section["reason"] = (
+                f"{node_count} nodes and no noise curation in the last "
+                f"{_HYGIENE_STALE_DAYS} days"
+                if last
+                else f"{node_count} nodes and no noise curation recorded"
+            )
+        except Exception:
+            LOGGER.exception("command center hygiene read failed")
+            return {
+                "available": False,
+                "suggest_noise_curate": False,
+                "reason": "",
+                "last_noise_curate_at": None,
+                "node_count": 0,
+            }
+        return section
+
+    @staticmethod
+    def _older_than_days(stamp: str, days: int) -> bool:
+        parsed = parse_iso(stamp)
+        if parsed is None:
+            # Unreadable stamp → treat as stale; suggesting a dry-run is safe.
+            return True
+        now = datetime.now(parsed.tzinfo) if parsed.tzinfo else local_now()
+        return (now - parsed) > timedelta(days=days)
+
     # ── quick actions ────────────────────────────────────────────────────
 
     def _quick_actions(self, sections: Dict[str, Dict[str, Any]]) -> List[Dict[str, Any]]:
@@ -295,6 +370,19 @@ class CommandCenterService:
                     "target": "/brain/graph",
                 }
             )
+        hygiene = sections.get("hygiene") or {}
+        if hygiene.get("suggest_noise_curate"):
+            actions.append(
+                {
+                    "id": "curate-noise",
+                    "kind": "hygiene",
+                    "count": int(hygiene.get("node_count") or 0),
+                    "target": "/brain/graph",
+                    # Dry-run by default on the API side: this endpoint only
+                    # *reports* removals until dry_run=false is sent explicitly.
+                    "endpoint": "/knowledge-graph/curate/noise",
+                }
+            )
         if not actions:
             actions.append(
                 {"id": "ask-brain", "kind": "chat", "count": 0, "target": "/brain"}
@@ -319,6 +407,7 @@ class CommandCenterService:
             "suggestions": self._suggestion_section(
                 user_email=user_email, workspace_id=workspace_id
             ),
+            "hygiene": self._hygiene_section(),
         }
         return {
             "generated_at": _now(),

package/latticeai/services/folder_watch.py

@@ -303,6 +303,10 @@ class FolderWatchService:
                 for key in ("status", "new", "changed", "removed", "ingested", "duplicate", "failed")
                 if key in result
             }
+            # Watch trust UI (review Wave 1.3): keep a small sample of the
+            # latest scan's failures so the home health card can show *why*
+            # a watch is unhealthy, not just a count.
+            watch["last_errors"] = list(result.get("errors") or [])[:3]
             if snapshot is not None:
                 watch["snapshot"] = snapshot
             self._save_config()
@@ -353,6 +357,7 @@ class FolderWatchService:
             "created_at": watch.get("created_at"),
             "last_scan_at": watch.get("last_scan_at"),
             "last_result": watch.get("last_result"),
+            "last_errors": list(watch.get("last_errors") or []),
             "tracked_files": len(watch.get("snapshot") or {}),
         }
 

package/latticeai/services/funnel_metrics.py

@@ -10,7 +10,10 @@ Tracks the product's core value funnel with honest, local-only counters:
 * ``needs_review_runs``      — agent runs that ended in ``NEEDS_REVIEW``;
 * ``ingest_completions``     — successful ingestion pipeline completions;
 * ``recall_successes``       — chat turns whose context was grounded in at
-  least one Brain node.
+  least one Brain node;
+* ``approval_pauses``        — agent/workflow runs paused for human approval;
+* ``approval_resumes``       — paused runs a human explicitly resumed
+  (approved), the ``approval_resume_rate`` numerator.
 
 TTFV ("time to first value") derives from two first-occurrence timestamps:
 the first successful ingest and the first grounded recall/answer.
@@ -44,6 +47,8 @@ COUNTER_NAMES = (
     "needs_review_runs",
     "ingest_completions",
     "recall_successes",
+    "approval_pauses",
+    "approval_resumes",
 )
 
 _FIRST_NAMES = ("first_ingest_at", "first_value_at")
@@ -193,6 +198,9 @@ class FunnelMetricsService:
                 "needs_review_rate": _rate(
                     counters["needs_review_runs"], counters["agent_runs"]
                 ),
+                "approval_resume_rate": _rate(
+                    counters["approval_resumes"], counters["approval_pauses"]
+                ),
             },
             "ttfv_seconds": self.ttfv_seconds(),
             "generated_at": _utc_now_iso(),

package/latticeai/services/product_readiness.py

@@ -18,7 +18,7 @@ from typing import Any, Dict, List
 
 from latticeai.services.architecture_readiness import architecture_readiness
 
-PRODUCT_VERSION_TARGET = "9.9.3"
+PRODUCT_VERSION_TARGET = "9.9.5"
 
 
 @dataclass(frozen=True)

package/latticeai/services/search_service.py

@@ -7,9 +7,11 @@ keyword search into UI-ready contracts without tying routers to store internals.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Dict, Mapping, Optional
+from datetime import datetime
+from typing import Any, Dict, List, Mapping, Optional
 
-from lattice_brain.graph.fusion import fusion_profile
+from lattice_brain.graph._kg_fsutil import _parse_iso, _recency_score
+from lattice_brain.graph.retrieval_policy import resolve_policy
 
 
 DEFAULT_HYBRID_WEIGHTS = {
@@ -404,35 +406,44 @@ class SearchService:
         allowed_workspaces=None,
         include_legacy_global: bool = False,
     ) -> Dict[str, Any]:
-        # Query-class fusion (backlog #5): when the caller does not pin
-        # explicit weights, detect the query class (fact/code/person/recency)
-        # and use its per-class channel weights. Explicit weights still win,
-        # and the "fact" class equals DEFAULT_HYBRID_WEIGHTS, so pinned-weight
-        # callers and fact-class queries behave exactly as before.
+        # Single retrieval policy (review Wave 0.2): when the caller does not
+        # pin explicit weights, resolve the query class + per-class channel
+        # weights + deterministic rewrite from lattice_brain.graph.
+        # retrieval_policy (the same policy the graph-layer hybrid consults).
+        # Explicit weights still win (and disable rewrite/decay), and the
+        # "fact" class equals DEFAULT_HYBRID_WEIGHTS, so pinned-weight callers
+        # and fact-class queries behave exactly as before.
         query_class: Optional[str] = None
+        search_query = query
+        rewrite_rules: List[str] = []
+        recency_half_life_days: Optional[float] = None
         if weights is None:
-            profile = fusion_profile(query)
-            query_class = profile["query_class"]
-            weights = dict(profile["weights"])
+            policy = resolve_policy(query)
+            query_class = policy["query_class"]
+            weights = dict(policy["weights"])
+            rewrite_rules = list(policy["rewrite_rules"])
+            recency_half_life_days = policy["recency_half_life_days"]
+            if policy["search_query"] and policy["search_query"] != policy["original_query"]:
+                search_query = policy["search_query"]
         else:
             weights = {**DEFAULT_HYBRID_WEIGHTS, **dict(weights)}
         # Scope each channel at the source so out-of-scope rows never enter the
         # fusion set (defense-in-depth — the fused result is re-scoped below too).
         channels = {
             "keyword": self.keyword_search(
-                query,
+                search_query,
                 limit=keyword_limit,
                 allowed_workspaces=allowed_workspaces,
                 include_legacy_global=include_legacy_global,
             ),
             "vector": self.vector_search(
-                query,
+                search_query,
                 limit=vector_limit,
                 allowed_workspaces=allowed_workspaces,
                 include_legacy_global=include_legacy_global,
             ),
             "graph": self.graph_search(
-                query,
+                search_query,
                 limit=graph_limit,
                 allowed_workspaces=allowed_workspaces,
                 include_legacy_global=include_legacy_global,
@@ -465,6 +476,24 @@ class SearchService:
                     current.setdefault("graph_context", [])
                     current["graph_context"].extend(result.get("graph_context") or [])
 
+        # Recency-class age decay (retrieval_policy): dampen each fused score
+        # into the [0.5, 1.0] band so old-but-relevant items sink without ever
+        # being zeroed. Missing/unparseable updated_at keeps multiplier 1.0 —
+        # unknown age is not evidence of staleness. Other classes skip this
+        # block byte-identically.
+        if recency_half_life_days is not None:
+            decay_now = datetime.now()
+            for item in fused.values():
+                stamp = item.get("updated_at")
+                if _parse_iso(stamp):
+                    multiplier = 0.5 + 0.5 * _recency_score(
+                        stamp, now=decay_now, half_life_days=recency_half_life_days
+                    )
+                else:
+                    multiplier = 1.0
+                item["source_scores"]["age_decay"] = round(multiplier, 6)
+                item["score"] = float(item["score"]) * multiplier
+
         matches = self._scope(
             sorted(fused.values(), key=lambda item: item["score"], reverse=True),
             allowed_workspaces,
@@ -484,6 +513,7 @@ class SearchService:
             "mode": "hybrid",
             "query_class": query_class,
             "weights": weights,
+            "policy": {"search_query": search_query, "rewrite_rules": rewrite_rules},
             "channels": {
                 name: {
                     key: value

package/latticeai/services/tool_dispatch.py

@@ -220,6 +220,60 @@ class ToolDispatchService:
         )
         return {"path": path, "ok": r.returncode == 0, "stderr": r.stderr[:200]}
 
+    # ── snapshot rollback ports (review L7) ──────────────────────────────
+    # Pre-write capture + restore for workspaces where git rollback does not
+    # apply (untracked new files, no git). Strictly confined to AGENT_ROOT.
+
+    _SNAPSHOT_MAX_BYTES = 512 * 1024
+
+    def _workspace_path(self, path: str) -> Optional[Path]:
+        raw = Path(path)
+        candidate = raw if raw.is_absolute() else AGENT_ROOT / raw
+        try:
+            resolved = candidate.resolve()
+            root = AGENT_ROOT.resolve()
+        except OSError:
+            return None
+        if resolved != root and root not in resolved.parents:
+            return None
+        return resolved
+
+    def snapshot_file(self, path: str) -> Dict[str, Any]:
+        """Pre-write state of a workspace file: existence + bounded content."""
+        target = self._workspace_path(path)
+        if target is None:
+            return {"existed": False, "content": None, "too_large": False,
+                    "error": "path escapes the agent workspace"}
+        if not target.exists() or not target.is_file():
+            return {"existed": False, "content": None, "too_large": False}
+        try:
+            if target.stat().st_size > self._SNAPSHOT_MAX_BYTES:
+                return {"existed": True, "content": None, "too_large": True}
+            return {
+                "existed": True,
+                "content": target.read_text(encoding="utf-8", errors="replace"),
+                "too_large": False,
+            }
+        except OSError as exc:
+            return {"existed": True, "content": None, "too_large": True,
+                    "error": str(exc)}
+
+    def restore_snapshot(self, path: str, content: Optional[str]) -> Dict[str, Any]:
+        """Restore a pre-write snapshot: rewrite prior content, or delete a
+        file the run created (``content=None``)."""
+        target = self._workspace_path(path)
+        if target is None:
+            return {"path": path, "ok": False, "error": "path escapes the agent workspace"}
+        try:
+            if content is None:
+                target.unlink(missing_ok=True)
+                return {"path": path, "ok": True, "action": "deleted"}
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+            return {"path": path, "ok": True, "action": "restored"}
+        except OSError as exc:
+            return {"path": path, "ok": False, "error": str(exc)}
+
 
 DEFAULT_TOOL_DISPATCH_SERVICE = ToolDispatchService()
 
@@ -375,6 +429,8 @@ def build_agent_runtime(
         memory_updater_prompt=MEMORY_UPDATER_PROMPT,
         agent_root=AGENT_ROOT,
         rollback_file=dispatch_service.rollback_file,
+        snapshot_file=dispatch_service.snapshot_file,
+        restore_snapshot=dispatch_service.restore_snapshot,
         hooks=hooks,
         brain_memory=brain_memory,
     )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "9.9.3",
+  "version": "9.9.5",
   "description": "Lattice AI — local-first Digital Brain that keeps your knowledge durable across any AI model.",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
@@ -41,6 +41,7 @@
     "test:integration": "node scripts/run_integration_tests.mjs",
     "test:browser-extension": "node --check browser-extension/popup.js && node --check browser-extension/capture-page.js && node --test tests/browser-extension.test.cjs",
     "test:visual": "playwright test",
+    "test:e2e:sidecar": "node scripts/run_sidecar_e2e.mjs",
     "vercel:build": "node scripts/build_vercel_static.mjs",
     "desktop:tauri": "tauri dev",
     "desktop:tauri:build": "tauri build",