ltcai 9.9.4 → 9.9.9

package/latticeai/runtime/permission_mode_wiring.py

@@ -0,0 +1,116 @@
+"""Wire PermissionMode into the running app without a large app_factory rewrite.
+
+Creates one process-wide :class:`PermissionModeService`, points
+``ToolDispatchService.permission_mode`` at it, and registers the HTTP dial.
+Called from ``register_review_and_brain_tail_routers`` (which already has
+``data_dir``, ``require_user``, ``append_audit_event``) and from
+``build_chat_agent_runtime_from_context`` so the agent loop sees the same dial.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from latticeai.core.permission_mode import DEFAULT_MODE, normalize_mode
+from latticeai.services.permission_mode_service import PermissionModeService
+
+_LOCK = threading.Lock()
+_SHARED: Optional[PermissionModeService] = None
+
+
+def _default_data_dir() -> Path:
+    raw = os.environ.get("LATTICEAI_DATA_DIR", "").strip()
+    if raw:
+        return Path(raw)
+    return Path.home() / ".ltcai"
+
+
+def _env_default_mode() -> Any:
+    return normalize_mode(os.environ.get("LATTICEAI_PERMISSION_MODE", DEFAULT_MODE.value))
+
+
+def get_permission_mode_service(
+    *,
+    data_dir: Optional[Path] = None,
+    audit: Optional[Callable[..., None]] = None,
+) -> PermissionModeService:
+    """Process-wide singleton.
+
+    An early lazy caller (a tool dispatch before routers are mounted) would
+    otherwise pin the service to the fallback ``data_dir`` with no audit sink.
+    Explicit arguments therefore *rebind* an already-created service instead of
+    being silently dropped, so the app's real data dir and audit log always win.
+    """
+    global _SHARED
+    with _LOCK:
+        if _SHARED is None:
+            _SHARED = PermissionModeService(
+                data_dir=Path(data_dir) if data_dir is not None else _default_data_dir(),
+                default_mode=_env_default_mode(),
+                audit=audit,
+            )
+            return _SHARED
+        if data_dir is not None:
+            _SHARED.rebind_data_dir(Path(data_dir))
+        if audit is not None:
+            _SHARED.rebind_audit(audit)
+        return _SHARED
+
+
+def resolve_active_permission_mode(
+    *,
+    user_email: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+) -> Any:
+    return get_permission_mode_service().resolve(
+        user_email=user_email, workspace_id=workspace_id,
+    )
+
+
+def bind_dispatch_permission_mode(dispatch_service: Any = None) -> None:
+    """Point tool dispatch at the shared mode resolver.
+
+    The bound callable accepts scope kwargs so per-user and per-workspace
+    overrides actually reach ``enforce_policy`` — an unscoped resolver would
+    always return the process-wide default and make the dial a no-op.
+    """
+    from latticeai.services.tool_dispatch import DEFAULT_TOOL_DISPATCH_SERVICE
+
+    service = dispatch_service or DEFAULT_TOOL_DISPATCH_SERVICE
+    service.permission_mode = resolve_active_permission_mode
+
+
+def register_permission_mode_router(
+    app: Any,
+    *,
+    require_user: Callable[..., str],
+    data_dir: Optional[Path] = None,
+    append_audit_event: Optional[Callable[..., None]] = None,
+) -> Any:
+    """Install GET/POST /api/permission-mode on ``app``. Idempotent by route path."""
+    from latticeai.api.permission_mode import create_permission_mode_router
+
+    svc = get_permission_mode_service(data_dir=data_dir, audit=append_audit_event)
+    bind_dispatch_permission_mode()
+    # Skip if already mounted (re-entrant factory / tests).
+    existing = {
+        getattr(route, "path", None)
+        for route in getattr(app, "routes", ())
+    }
+    if "/api/permission-mode" in existing:
+        return svc
+    app.include_router(
+        create_permission_mode_router(service=svc, require_user=require_user)
+    )
+    return svc
+
+
+__all__ = [
+    "get_permission_mode_service",
+    "resolve_active_permission_mode",
+    "bind_dispatch_permission_mode",
+    "register_permission_mode_router",
+]

package/latticeai/runtime/router_registration.py

@@ -653,4 +653,13 @@ def register_review_and_brain_tail_routers(
             workspace_service=workspace_service,
         ),
     )
+    # Permission mode dial (v9.9.8): mount last so data_dir + audit are known.
+    from latticeai.runtime.permission_mode_wiring import register_permission_mode_router
+
+    register_permission_mode_router(
+        app,
+        require_user=require_user,
+        data_dir=data_dir,
+        append_audit_event=append_audit_event,
+    )
     return brain_network

package/latticeai/services/app_context.py

@@ -33,6 +33,9 @@ class AppContext:
     local_kg_watcher: Any = None
     chat_service: Any = None
     context_assembler: Any = None
+    # Re-search loop (v9.9.6): conversation-scoped ledger of just-written
+    # artifacts, so a follow-up turn sees them before indexing catches up.
+    artifact_ledger: Any = None
     brain_memory: Any = None
     # Unified ingestion gateway (lattice_brain.ingestion.IngestionPipeline);
     # None when the knowledge graph is disabled.

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.4"
+ARCHITECTURE_VERSION_TARGET = "9.9.9"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/brain_intelligence.py

@@ -391,6 +391,111 @@ class BrainIntelligenceService:
             "generated_at": _now(),
         }
 
+    def garden_overview(
+        self, *, user_email: Optional[str] = None, workspace_id: Optional[str] = None,
+        limit: int = 8,
+    ) -> Dict[str, Any]:
+        """The knowledge garden in four beds (v9.9.7).
+
+        Living Brain answers "how healthy is my knowledge?" in aggregate.
+        A gardener asks four concrete questions instead, and this answers all
+        four from one workspace-scoped graph sample plus the memory tier:
+
+        * **recent** — what came in lately (the garden's new growth);
+        * **contradictions** — what disagrees with itself (needs weeding);
+        * **stale** — what has not been touched in a long time;
+        * **frequent** — what the rest of the graph leans on most (by degree).
+
+        Read-only and honest: when the graph is unavailable every bed is empty
+        and ``available`` is false — the view never invents plants.
+        """
+        # Explicit 0 clamps to 1 — `limit or 8` would silently re-expand it.
+        try:
+            limit = max(1, min(int(limit), 50))
+        except (TypeError, ValueError):
+            limit = 8
+        sample = self._graph_sample(workspace_id=workspace_id)
+        nodes, edges = sample["nodes"], sample["edges"]
+        now = datetime.now(timezone.utc)
+        recent_cutoff = now - timedelta(days=_RECENT_DAYS)
+        stale_cutoff = now - timedelta(days=_STALE_DAYS)
+
+        def _slim(node: Dict[str, Any], **extra: Any) -> Dict[str, Any]:
+            return {
+                "id": node.get("id"),
+                "type": node.get("type"),
+                "title": str(node.get("title") or "")[:120],
+                "updated_at": node.get("updated_at"),
+                **extra,
+            }
+
+        recent: List[Dict[str, Any]] = []
+        stale: List[Dict[str, Any]] = []
+        for node in nodes:
+            # Chunks are retrieval plumbing, not knowledge a gardener tends.
+            if str(node.get("type") or "") == "Chunk":
+                continue
+            ts = _parse_ts(node.get("updated_at"))
+            if ts is None:
+                continue
+            if ts >= recent_cutoff:
+                recent.append(node)
+            elif ts < stale_cutoff:
+                stale.append(node)
+        recent.sort(key=lambda n: str(n.get("updated_at") or ""), reverse=True)
+        stale.sort(key=lambda n: str(n.get("updated_at") or ""))
+
+        # "Frequent" is degree, not a guess: how many relations actually point
+        # at a node. Chunks are retrieval plumbing, never garden plants.
+        degree: Dict[str, int] = {}
+        for edge in edges:
+            for key in ("source", "target"):
+                node_id = str(edge.get(key) or "")
+                if node_id:
+                    degree[node_id] = degree.get(node_id, 0) + 1
+        by_id = {str(node.get("id")): node for node in nodes}
+        frequent = [
+            _slim(by_id[node_id], degree=count)
+            for node_id, count in sorted(degree.items(), key=lambda kv: kv[1], reverse=True)
+            if node_id in by_id and str(by_id[node_id].get("type") or "") != "Chunk"
+        ][:limit]
+
+        contradiction_items: List[Dict[str, Any]] = []
+        contradiction_count = 0
+        try:
+            found = self.contradictions(user_email=user_email, workspace_id=workspace_id)
+            items = found.get("items") if isinstance(found, dict) else None
+            if isinstance(items, list):
+                contradiction_count = len(items)
+                contradiction_items = items[:limit]
+        except Exception:  # noqa: BLE001 — one empty bed, never a broken view
+            LOGGER.exception("garden overview contradictions failed")
+
+        return {
+            "available": sample["available"],
+            "window_days": _RECENT_DAYS,
+            "stale_threshold_days": _STALE_DAYS,
+            "beds": {
+                "recent": {
+                    "count": len(recent),
+                    "items": [_slim(node) for node in recent[:limit]],
+                },
+                "contradictions": {
+                    "count": contradiction_count,
+                    "items": contradiction_items,
+                },
+                "stale": {
+                    "count": len(stale),
+                    "items": [_slim(node) for node in stale[:limit]],
+                },
+                "frequent": {
+                    "count": len(frequent),
+                    "items": frequent,
+                },
+            },
+            "generated_at": _now(),
+        }
+
     # ── graph-layer proactive quality (v9.6.x) ───────────────────────────
 
     def graph_duplicates(

package/latticeai/services/evidence_actions.py

@@ -0,0 +1,254 @@
+"""Evidence → action bridge (v9.9.6).
+
+Answers already carry citations and a grounding badge, and clicking a source
+already opens the stored chunk. The loop stopped there: to *use* the evidence
+the user had to retype the request and hope the model retrieved the same
+sources again.
+
+This service closes that gap deterministically. Given the citations an answer
+actually used, it resolves them against the graph and composes ready-to-send,
+evidence-scoped prompts — "이 근거로 요약 만들기", "체크리스트 만들기",
+"문서 파일 만들기", "한 페이지로 만들기". No model runs here: the output is a
+prompt plus the resolved evidence, so the existing chat/file-generation path
+stays the single execution road.
+
+Honesty rules:
+
+* Citations that no longer resolve are reported in ``missing`` — never
+  silently dropped, and never invented.
+* When nothing resolves, ``actions`` is empty and ``reason`` says why. The UI
+  must not offer an action the Brain cannot ground.
+* Every composed prompt tells the model to use only the quoted evidence and
+  to say so when the evidence does not cover the request.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence
+
+LOGGER = logging.getLogger(__name__)
+
+__all__ = ["EvidenceActionService", "EVIDENCE_ACTIONS"]
+
+# Per-source excerpt cap. Long enough to carry the claim, short enough that a
+# four-citation prompt still fits a small local model's context.
+_EXCERPT_CHARS = 600
+_MAX_SOURCES = 8
+
+
+def _phrase(ko: str, en: str) -> Dict[str, str]:
+    return {"ko": ko, "en": en}
+
+
+# The action catalog is closed and deterministic — the UI renders exactly
+# these, and each one names the artifact it produces.
+EVIDENCE_ACTIONS: List[Dict[str, Any]] = [
+    {
+        "id": "summary",
+        "label": _phrase("이 근거로 요약 만들기", "Summarize from this evidence"),
+        "instruction": _phrase(
+            "핵심만 5줄 이내로 요약해 주세요.",
+            "Summarize the key points in five lines or fewer.",
+        ),
+        "kind": "chat",
+    },
+    {
+        "id": "checklist",
+        "label": _phrase("이 근거로 체크리스트 만들기", "Build a checklist"),
+        "instruction": _phrase(
+            "실행 가능한 체크리스트를 만들어 주세요. 각 항목은 한 줄이고, 근거가 있는 항목만 넣으세요.",
+            "Build an actionable checklist. One line per item, only items the evidence supports.",
+        ),
+        "kind": "chat",
+    },
+    {
+        "id": "document",
+        "label": _phrase("이 근거로 문서 파일 만들기", "Write a document file"),
+        "instruction": _phrase(
+            "정리된 마크다운 문서를 만들어 {path} 파일로 저장해 주세요.",
+            "Write a structured markdown document and save it as {path}.",
+        ),
+        "kind": "file",
+        "extension": ".md",
+    },
+    {
+        "id": "page",
+        "label": _phrase("이 근거로 한 페이지 만들기", "Build a one-page view"),
+        "instruction": _phrase(
+            "내용을 한눈에 보는 HTML 한 페이지로 만들어 {path} 파일로 저장해 주세요.",
+            "Build a single self-contained HTML page and save it as {path}.",
+        ),
+        "kind": "file",
+        "extension": ".html",
+    },
+]
+
+_SLUG_STRIP_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(text: str, *, fallback: str = "evidence-note") -> str:
+    """Deterministic, filesystem-safe stem for a suggested artifact path.
+
+    Non-ASCII text (Korean questions are the common case) leaves nothing to
+    slug — the fallback keeps the suggestion predictable instead of producing
+    a mangled or empty filename.
+    """
+    slug = _SLUG_STRIP_RE.sub("-", str(text or "").lower()).strip("-")
+    slug = "-".join(part for part in slug.split("-") if part)[:48].strip("-")
+    return slug or fallback
+
+
+class EvidenceActionService:
+    """Compose evidence-scoped follow-up actions for an answer's citations."""
+
+    def __init__(
+        self,
+        *,
+        node_reader: Optional[Callable[..., Mapping[str, Any]]] = None,
+        excerpt_chars: int = _EXCERPT_CHARS,
+    ) -> None:
+        self._node_reader = node_reader
+        self._excerpt_chars = max(120, int(excerpt_chars))
+
+    # ── evidence resolution ──────────────────────────────────────────────
+
+    def _read_node(self, node_id: str, allowed_workspaces: Any) -> Optional[Mapping[str, Any]]:
+        if self._node_reader is None:
+            return None
+        try:
+            return self._node_reader(node_id, allowed_workspaces=allowed_workspaces)
+        except TypeError:
+            # Readers without scope support (tests, older ports).
+            try:
+                return self._node_reader(node_id)
+            except Exception as exc:  # noqa: BLE001 — resolution is best-effort
+                LOGGER.debug("evidence node read failed for %s: %s", node_id, exc)
+                return None
+        except Exception as exc:  # noqa: BLE001
+            LOGGER.debug("evidence node read failed for %s: %s", node_id, exc)
+            return None
+
+    def resolve(
+        self,
+        source_ids: Sequence[str],
+        *,
+        allowed_workspaces: Any = None,
+    ) -> Dict[str, Any]:
+        """Resolve citation ids to ``{"sources": [...], "missing": [...]}``."""
+        sources: List[Dict[str, Any]] = []
+        missing: List[str] = []
+        seen: set = set()
+        for raw in list(source_ids or [])[:_MAX_SOURCES]:
+            node_id = str(raw or "").strip()
+            if not node_id or node_id in seen:
+                continue
+            seen.add(node_id)
+            node = self._read_node(node_id, allowed_workspaces)
+            if not isinstance(node, Mapping):
+                missing.append(node_id)
+                continue
+            # /api/graph/node wraps the record; get_node returns it directly.
+            record = node.get("node") if isinstance(node.get("node"), Mapping) else node
+            title = str(record.get("title") or record.get("id") or node_id)
+            body = str(record.get("summary") or record.get("content") or "").strip()
+            metadata = record.get("metadata")
+            metadata = metadata if isinstance(metadata, Mapping) else {}
+            origin = ""
+            for key in ("relative_path", "file_path", "filename", "source_uri", "source"):
+                value = metadata.get(key)
+                if value:
+                    origin = str(value)
+                    break
+            sources.append({
+                "id": node_id,
+                "title": title,
+                "type": str(record.get("type") or ""),
+                "origin": origin,
+                "excerpt": body[: self._excerpt_chars],
+                "truncated": len(body) > self._excerpt_chars,
+            })
+        return {"sources": sources, "missing": missing}
+
+    # ── prompt composition ───────────────────────────────────────────────
+
+    def _evidence_block(self, sources: Sequence[Mapping[str, Any]], language: str) -> str:
+        header = "[근거 자료]" if language == "ko" else "[EVIDENCE]"
+        lines = [header]
+        for index, source in enumerate(sources, start=1):
+            origin = f" ({source['origin']})" if source.get("origin") else ""
+            lines.append(f"{index}. {source['title']}{origin}")
+            excerpt = str(source.get("excerpt") or "").strip()
+            if excerpt:
+                suffix = " …" if source.get("truncated") else ""
+                lines.append(f"   {excerpt}{suffix}")
+        return "\n".join(lines)
+
+    def _guard(self, language: str) -> str:
+        if language == "ko":
+            return (
+                "위 근거 자료에 있는 내용만 사용하세요. 근거에 없는 사실은 지어내지 말고, "
+                "근거가 부족하면 '이 부분은 근거가 없습니다'라고 적으세요."
+            )
+        return (
+            "Use only the evidence quoted above. Do not invent facts that are not in it; "
+            "when the evidence does not cover something, say so explicitly."
+        )
+
+    def actions_for(
+        self,
+        *,
+        question: str = "",
+        source_ids: Sequence[str] = (),
+        language: str = "ko",
+        allowed_workspaces: Any = None,
+    ) -> Dict[str, Any]:
+        """Ready-to-send, evidence-scoped follow-up actions for one answer."""
+        language = "ko" if str(language or "ko").lower().startswith("ko") else "en"
+        resolved = self.resolve(source_ids, allowed_workspaces=allowed_workspaces)
+        sources = resolved["sources"]
+        question_text = str(question or "").strip()
+        if not sources:
+            return {
+                "sources": [],
+                "missing": resolved["missing"],
+                "actions": [],
+                "reason": (
+                    "근거로 쓸 출처를 찾지 못했습니다."
+                    if language == "ko"
+                    else "No usable evidence could be resolved."
+                ),
+            }
+
+        evidence = self._evidence_block(sources, language)
+        guard = self._guard(language)
+        stem = slugify(question_text)
+        actions: List[Dict[str, Any]] = []
+        for spec in EVIDENCE_ACTIONS:
+            path = f"{stem}{spec['extension']}" if spec.get("extension") else ""
+            instruction = spec["instruction"][language].replace("{path}", path)
+            question_line = (
+                (f"원래 질문: {question_text}" if language == "ko" else f"Original question: {question_text}")
+                if question_text
+                else ""
+            )
+            prompt = "\n\n".join(
+                part for part in (evidence, instruction, guard, question_line) if part
+            )
+            action: Dict[str, Any] = {
+                "id": spec["id"],
+                "kind": spec["kind"],
+                "label": dict(spec["label"]),
+                "prompt": prompt,
+                "source_ids": [source["id"] for source in sources],
+            }
+            if path:
+                action["suggested_path"] = path
+            actions.append(action)
+        return {
+            "sources": sources,
+            "missing": resolved["missing"],
+            "actions": actions,
+            "reason": "",
+        }

package/latticeai/services/funnel_metrics.py

@@ -181,30 +181,125 @@ class FunnelMetricsService:
         return round(delta, 1) if delta >= 0 else None
 
     def snapshot(self) -> Dict[str, Any]:
-        """Counters + derived rates for the admin surface."""
+        """Counters + derived rates + actionable alerts for the admin surface."""
         with self._lock:
             counters = {name: int(self._state.get(name) or 0) for name in COUNTER_NAMES}
             firsts = {name: self._state.get(name) for name in _FIRST_NAMES}
+        rates = {
+            "real_file_rate": _rate(
+                counters["real_file_delivered"], counters["file_requests"]
+            ),
+            "code_only_rate": _rate(
+                counters["code_only_responses"], counters["file_requests"]
+            ),
+            "needs_review_rate": _rate(
+                counters["needs_review_runs"], counters["agent_runs"]
+            ),
+            "approval_resume_rate": _rate(
+                counters["approval_resumes"], counters["approval_pauses"]
+            ),
+        }
         return {
             "counters": counters,
             "firsts": firsts,
-            "rates": {
-                "real_file_rate": _rate(
-                    counters["real_file_delivered"], counters["file_requests"]
-                ),
-                "code_only_rate": _rate(
-                    counters["code_only_responses"], counters["file_requests"]
-                ),
-                "needs_review_rate": _rate(
-                    counters["needs_review_runs"], counters["agent_runs"]
-                ),
-                "approval_resume_rate": _rate(
-                    counters["approval_resumes"], counters["approval_pauses"]
-                ),
-            },
+            "rates": rates,
+            "alerts": funnel_alerts(counters, rates),
             "ttfv_seconds": self.ttfv_seconds(),
             "generated_at": _utc_now_iso(),
         }
 
 
-__all__ = ["FunnelMetricsService", "COUNTER_NAMES"]
+# ── alerts (review 2026-07-27 P2 #10) ────────────────────────────────────────
+# The funnel already measured the right things; nothing turned a bad number
+# into a decision, so a regression was only visible to whoever opened the
+# admin page. These thresholds convert rates into named, actionable signals.
+#
+# Minimum samples per rule exist so a single unlucky run never raises an
+# alarm — an alert with n=1 is noise, and noisy alerts get ignored.
+
+REAL_FILE_RATE_FLOOR = 0.95
+CODE_ONLY_RATE_CEILING = 0.05
+NEEDS_REVIEW_RATE_CEILING = 0.25
+APPROVAL_RESUME_RATE_FLOOR = 0.5
+MIN_SAMPLES = 10
+
+
+def _alert(
+    key: str, severity: str, ko: str, en: str, **detail: Any
+) -> Dict[str, Any]:
+    return {"key": key, "severity": severity, "ko": ko, "en": en, **detail}
+
+
+def funnel_alerts(
+    counters: Dict[str, int], rates: Dict[str, Optional[float]]
+) -> list:
+    """Turn funnel rates into named signals a person can act on.
+
+    Pure function of the snapshot — no I/O, no clock — so the thresholds are
+    testable and the same numbers always produce the same alerts. Rules stay
+    silent below :data:`MIN_SAMPLES`: an alert nobody can trust is worse than
+    no alert.
+    """
+    alerts: list = []
+    file_requests = int(counters.get("file_requests") or 0)
+    agent_runs = int(counters.get("agent_runs") or 0)
+    approval_pauses = int(counters.get("approval_pauses") or 0)
+
+    real_file_rate = rates.get("real_file_rate")
+    if file_requests >= MIN_SAMPLES and real_file_rate is not None:
+        if real_file_rate < REAL_FILE_RATE_FLOOR:
+            alerts.append(_alert(
+                "real_file_rate_low", "warning",
+                f"파일 요청 중 실제 파일이 나온 비율이 {real_file_rate:.0%}입니다 "
+                f"(목표 {REAL_FILE_RATE_FLOOR:.0%}). 파일 생성 파이프라인을 확인하세요.",
+                f"Only {real_file_rate:.0%} of file requests produced a real file "
+                f"(target {REAL_FILE_RATE_FLOOR:.0%}). Check the file-generation pipeline.",
+                value=real_file_rate, threshold=REAL_FILE_RATE_FLOOR, samples=file_requests,
+            ))
+
+    code_only_rate = rates.get("code_only_rate")
+    if file_requests >= MIN_SAMPLES and code_only_rate is not None:
+        if code_only_rate > CODE_ONLY_RATE_CEILING:
+            alerts.append(_alert(
+                "code_only_rate_high", "warning",
+                f"파일을 요청했는데 코드/설명만 돌아온 비율이 {code_only_rate:.0%}입니다.",
+                f"{code_only_rate:.0%} of file requests came back as code or prose only.",
+                value=code_only_rate, threshold=CODE_ONLY_RATE_CEILING, samples=file_requests,
+            ))
+
+    needs_review_rate = rates.get("needs_review_rate")
+    if agent_runs >= MIN_SAMPLES and needs_review_rate is not None:
+        if needs_review_rate > NEEDS_REVIEW_RATE_CEILING:
+            alerts.append(_alert(
+                "needs_review_rate_high", "warning",
+                f"에이전트 실행의 {needs_review_rate:.0%}가 '검토 필요'로 끝났습니다. "
+                "더 큰 모델을 쓰거나 요청을 작게 나누세요.",
+                f"{needs_review_rate:.0%} of agent runs ended as NEEDS_REVIEW. "
+                "Use a larger model or split requests into smaller steps.",
+                value=needs_review_rate, threshold=NEEDS_REVIEW_RATE_CEILING, samples=agent_runs,
+            ))
+
+    resume_rate = rates.get("approval_resume_rate")
+    if approval_pauses >= MIN_SAMPLES and resume_rate is not None:
+        if resume_rate < APPROVAL_RESUME_RATE_FLOOR:
+            alerts.append(_alert(
+                "approval_resume_rate_low", "info",
+                f"승인 대기 중 실제로 이어서 실행된 비율이 {resume_rate:.0%}입니다. "
+                "승인 카드가 잘 보이는지 확인하세요.",
+                f"Only {resume_rate:.0%} of paused runs were resumed. "
+                "Check that the approval card is actually reaching users.",
+                value=resume_rate, threshold=APPROVAL_RESUME_RATE_FLOOR, samples=approval_pauses,
+            ))
+
+    if int(counters.get("ingest_completions") or 0) > 0 and not counters.get("recall_successes"):
+        alerts.append(_alert(
+            "no_grounded_recall", "warning",
+            "자료는 들어왔지만 근거 있는 회상이 아직 한 번도 없었습니다. 검색/인덱싱을 확인하세요.",
+            "Content was ingested but no answer has ever been grounded in it yet — "
+            "check retrieval and indexing.",
+            samples=int(counters.get("ingest_completions") or 0),
+        ))
+    return alerts
+
+
+__all__ = ["FunnelMetricsService", "COUNTER_NAMES", "funnel_alerts"]