fix(arch+robustness): KI-225..KI-235 — Path B single-LLM rewrite + audit bundle

Architectural simplification (KI-225, Path B) — replaces the two-brain
sales_brain/qa_brain handoff with a single Gemini Flash call per turn using
native function-calling. Kills 40+ scaffolding failure modes at once:
- No fact_find vs QA routing boundary (every confirmation/knowledge edge
case in should_route_to_fact_find disappears).
- No faithfulness gate rejecting natural phrasing ("yes, that sounds correct").
- No separate profile_extractor pass overwriting captured slots with null
(KI-091/094 root cause permanently fixed via save_profile_field tool guard).
- No rigid normalizer enum — accepts what Gemini emits, light coerce only.
- No 700-token JSON contract — Gemini function-calling separates tool calls
from prose, no truncation trade-off.

Feature-flagged: USE_SINGLE_BRAIN=true activates the new path; default off,
legacy orchestrator preserved as fallback. SingleBrainError falls back to
orchestrator transparently.

New files:
- backend/single_brain.py — Gemini function-calling loop, 5 iterations max,
25s per-call timeout, defensive synthesised reply if no text part emitted.
Uses raw HTTPX (no new pip dep) matching existing google_gemini_llm pattern.
- backend/brain_tools.py — save_profile_field / retrieve_policies /
mark_recommendation. Universal None-drop guard prevents KI-091/094-class
null overwrites. retrieve_policies threads session.profile through to
retrieval_filters.filter_pipeline for profile-fit + dedup + citation
grounding.
- backend/retrieval_filters.py — sidecar: apply_profile_filter (drops
senior-only when age<50, adult-only when age>=60, maternity if no female
adult/maternity goal, min/max_entry_age out of range), exact-UIN bypass,
empty_retrieval_guard, citation_grounding, dedup_by_policy.
- frontend/src/lib/voice_resilience.ts — retryPostTranscribe (3 attempts,
exp backoff, partial transcript preserved), AdaptiveNoiseFloor (rolling
EMA*4 + 0.005 clamped [0.02, 0.15], raises barge-in floor in noisy
rooms only), sample-rate-scaled ZCR band.

Path A patches (kept healthy as fallback):
- backend/orchestrator.py — confirmation routing fix (short replies after
slots complete route to fact_find), welcome-back pending_profile_recall
ordering, knowledge_question carve-out, _is_recommendation keyword
expansion ("good for me", "which one", "fits", "help me pick"),
empty-retrieval short-circuit before brain call, post-recommendation
ordinal routing (#1/#2/#3 → last_recommendation_ids[idx] policy filter),
policy-name reference injection fallback, followup_policy_id on
TurnResult.
- backend/sales_brain_normalizer.py — name garbage rejection (vowel
check + Mr/Dr/St stripping), dependents "self/single/unmarried/just
myself" aliases + substring fallthrough, budget min-floor 5K, income
min-floor 1L, income_band natural phrasings ("10-25L", "between 10
and 25 lakh", "above 25"), primary_goal phrasings ("first time",
"tax planning", "upgrade", "compare specific"), existing_cover phrasings
("5L employer", "no insurance", spelled-digit "ten lakh"),
health_conditions multi-value normalization ("BP" → "hypertension",
"BP and thyroid" → list, "type 2 diabetes" → "diabetes").
- backend/providers/google_gemini_llm.py — cache TTL refresh at 50min,
cache key partition by dynamic prefix, BrainProviderError normalization
(retryable=bool), timeout binding to per_tier - 2s.
- backend/providers/nvidia_nim_llm.py — connection pool singleton
(max_connections=10, max_keepalive=5), assert_family_coverage()
enforces no "unknown" family in chains, json_schema mirrored to
nvext.guided_json, chain ordering confirms nemotron-LAST invariant.
- backend/providers/openrouter_llm.py — free-pool stable ordering
(cheapest-first by len + alpha), is_free_model + enforce_free_pool
cost guard.
- backend/providers/tiered_brain_llm.py — per_tier_timeout default 15s
(was 30s; total 3-tier cap 45s).
- backend/llm_health.py — effective_status("stale") at 600s without
ping, _is_election_eligible rejects stale, structured election event
log on every primary/backup change.
- backend/faithfulness.py — allow-list for short confirmations / bot
self-references, citation_required gate emits soft_hint when numeric
claims lack [Source:N] marker, hallucinated_policy gate emits
cited_policies hint when reply names policy absent from retrieved set,
pre_recap_emitted bypass for confirmation regex.
- backend/admin.py — /api/admin/persona-drift + /api/admin/recommendation-history
endpoints; ADMIN_PASSWORD unset warning at module load.
- backend/session_state.py — last_recommendation_ids field (consumed by
ordinal routing + single_brain.mark_recommendation).

Voice fixes:
- frontend/src/lib/useStreamingVoice.ts — recognitionRef null + handler
unbind on stop (post-abort tail events can no longer mutate state),
teardownAudio on terminal mic errors (not-allowed/audio-capture),
triggerBargeIn signal via consumeBargeInSignal (one-shot read-and-clear),
ZCR sanity band [20, 250] in fftSize=2048 @ 48kHz units (rejects
keyboard typing / HVAC), userSpeechRms ceiling 0.15 + 1s wall-clock
decay (prevents threshold creep), pendingUtterance flush on stop()
before clear, silent-onend grace timer skip when no Web Speech text
AND no audio chunks (kills "no-speech" infinite extension), additive
layer of retryPostTranscribe + AdaptiveNoiseFloor + sample-rate-scaled
ZCR band + utterance flush on barge-in + onVoiceError callback.
- frontend/src/app/page.tsx — interruptBotAudio helper revokes blob URLs
+ clears src + calls audio.load(); wired into barge-in-abort event /
userPrefersLive OFF / send() start / PTT startRecording; mid-utterance
"⏸ paused" suffix on last assistant message (idempotent); codec
probe via MediaSource.isTypeSupported → X-Preferred-Codec header +
audio_mime response handling; live PTT interim transcript with 200ms
throttle + aria-live=polite + atomic clear on stop; final-transcript
500ms dedup window via lastFinalTextRef; backspace word-erase when
inputFromTranscriptRef set; mobile keyboard env(safe-area-inset-bottom);
empty-message guard.
- frontend/src/app/layout.tsx — viewport.viewportFit="cover" + min-h-[100dvh].
- frontend/src/lib/api.ts — postChat({preferred_codec}); ChatResponse.audio_mime.

Admin:
- frontend/public/admin/llm-control.html — stale-90s freshness badge with
1s tick footers, Persona Drift collapsible panel (newest-20 by last_seen,
red <50% / yellow 50-80% / green >=80% slot completeness), Recommendation
History collapsible panel (last 10 with selected/rejected/shown pills),
KI-200 2-table compliance re-verified.

Verification:
- python -m py_compile passes on all 14 backend files touched.
- npx tsc --noEmit passes on frontend.
- npx next build succeeds (X8 confirmed).
- assert_family_coverage() passes for current BRAIN_CHAIN/FAST_BRAIN_CHAIN/JUDGE_CHAIN.
- single_brain.handle_turn dry-run: 7 required slots save correctly,
profile_complete flips True at 7th, unknown field rejected, None value
rejected (no overwrite), mark_recommendation populates
session.last_recommendation_ids.
- Headless Chrome smoke test on admin: zero JS console errors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/admin.py

@@ -42,6 +42,22 @@ router = APIRouter()
 USAGE_TAIL_LINES = 1000
 
 
+# A5 — Audit fix #7: emit a console warning at import time when the admin
+# password is unset. We don't break access (the password check below already
+# returns False which 401s every request), but ops needs a loud signal that
+# the gate is effectively unconfigured so deployments don't silently sit
+# behind an unreachable admin surface.
+if not os.environ.get("ADMIN_PASSWORD", "").strip():
+    import sys as _sys
+    print(
+        "[admin] WARNING: ADMIN_UNGATED — ADMIN_PASSWORD env var is empty. "
+        "All /api/admin/* requests will return 401. Set ADMIN_PASSWORD in "
+        "the deployment env to enable access.",
+        file=_sys.stderr,
+        flush=True,
+    )
+
+
 def _password_ok(supplied: Optional[str]) -> bool:
     expected = os.environ.get("ADMIN_PASSWORD", "").strip()
     if not expected:
@@ -929,3 +945,169 @@ async def admin_llm_health(
         "recent_turns": recent,
         "snapshot_ts":  datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
     }
+
+
+# ---------------------------------------------------------------------------
+# A5 — Audit fix #4: /api/admin/persona-drift — slot-capture completeness
+# for the last 20 personas. Six canonical slots: name, age, income_band,
+# location_tier, primary_goal, health_conditions. <50% capture is flagged
+# red on the frontend.
+# ---------------------------------------------------------------------------
+
+# Six canonical fact-find slots. Match the orchestrator's profile_extractor
+# targets — adding/removing a slot here must mirror the next_question
+# routing logic. Health is captured as a list (empty list counts as
+# "asked but no conditions" → still a valid captured signal once the
+# `asked` array contains the field name).
+_PERSONA_DRIFT_SLOTS = ("name", "age", "income_band", "location_tier",
+                        "primary_goal", "health_conditions")
+
+
+def _slot_captured(profile: dict, slot: str, asked: list[str]) -> bool:
+    """A slot is 'captured' when the field has a non-empty value OR (for
+    health_conditions) when the user was asked and confirmed no conditions
+    (asked-list contains the slot but the list is empty → still a positive
+    answer the bot heard, not a missing signal)."""
+    v = profile.get(slot)
+    if slot == "health_conditions":
+        if isinstance(v, list) and len(v) > 0:
+            return True
+        if "health_conditions" in (asked or []):
+            return True
+        return False
+    return v not in (None, "", [], 0)
+
+
+@router.get("/api/admin/persona-drift")
+async def admin_persona_drift(
+    request: Request,
+    x_admin_password: Optional[str] = Header(default=None, alias="X-Admin-Password"),
+):
+    """Return slot-capture completeness for the last 20 personas, newest first.
+
+    Each row: { persona_id, name_display, last_seen, captured_slots,
+                completeness_pct, missing_slots }
+    The frontend highlights any row with completeness_pct < 50.
+    """
+    _check_admin(request, x_admin_password)
+    if not _PROFILES_DIR_FOR_DRIFT.exists():
+        return {"personas": [], "total": 0,
+                "snapshot_ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")}
+
+    rows: list[dict] = []
+    for p in _PROFILES_DIR_FOR_DRIFT.glob("*.json"):
+        try:
+            raw = json.loads(p.read_text())
+        except Exception:
+            continue
+        profile = raw.get("profile") or {}
+        asked = profile.get("asked") or []
+        captured = [s for s in _PERSONA_DRIFT_SLOTS if _slot_captured(profile, s, asked)]
+        missing = [s for s in _PERSONA_DRIFT_SLOTS if s not in captured]
+        rows.append({
+            "persona_id":       raw.get("persona_id") or raw.get("name_slug") or p.stem,
+            "name_display":     raw.get("name_display") or "—",
+            "last_seen":        raw.get("last_seen"),
+            "captured_slots":   captured,
+            "missing_slots":    missing,
+            "completeness_pct": round(100.0 * len(captured) / len(_PERSONA_DRIFT_SLOTS), 1),
+            "session_count":    len(raw.get("sessions") or []),
+        })
+    # Newest first by last_seen (None sorts last)
+    rows.sort(key=lambda r: (r["last_seen"] or ""), reverse=True)
+    rows = rows[:20]
+    return {
+        "personas":    rows,
+        "total":       len(rows),
+        "slots":       list(_PERSONA_DRIFT_SLOTS),
+        "snapshot_ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+
+
+# Cached path resolver — re-uses profile_store's _PROFILES_DIR but we import
+# lazily to avoid a circular import at module top.
+def _resolve_profiles_dir() -> Path:
+    from backend import profile_store
+    return profile_store._PROFILES_DIR
+
+
+# Lazy-evaluated singleton — instantiate on first call. We can't reference
+# profile_store at module top because admin.py imports llm_health which
+# may not yet have its config wired during tests.
+class _LazyProfilesDir:
+    def __init__(self) -> None:
+        self._p: Optional[Path] = None
+    def __getattr__(self, name: str):
+        if self._p is None:
+            self._p = _resolve_profiles_dir()
+        return getattr(self._p, name)
+    def exists(self) -> bool:
+        if self._p is None:
+            self._p = _resolve_profiles_dir()
+        return self._p.exists()
+    def glob(self, pat: str):
+        if self._p is None:
+            self._p = _resolve_profiles_dir()
+        return self._p.glob(pat)
+
+
+_PROFILES_DIR_FOR_DRIFT = _LazyProfilesDir()
+
+
+# ---------------------------------------------------------------------------
+# A5 — Audit fix #5: /api/admin/recommendation-history — last 10 policy
+# recommendation events across all profiles, newest first.
+# ---------------------------------------------------------------------------
+
+@router.get("/api/admin/recommendation-history")
+async def admin_recommendation_history(
+    request: Request,
+    x_admin_password: Optional[str] = Header(default=None, alias="X-Admin-Password"),
+):
+    """Return the last 10 policy-event entries across every profile,
+    newest first.
+
+    Each row: { persona_id, name_display, event_type, policy_slug, insurer,
+                event_at, session_id, outcome }
+    outcome: 'selected' / 'rejected' / 'shown' (passthrough from event_type;
+             callers may map 'shown' → 'abandoned' if no follow-up exists,
+             but we leave the raw label so the operator can decide).
+    """
+    _check_admin(request, x_admin_password)
+    events: list[dict] = []
+    if not _PROFILES_DIR_FOR_DRIFT.exists():
+        return {"events": [], "total": 0,
+                "snapshot_ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")}
+
+    for p in _PROFILES_DIR_FOR_DRIFT.glob("*.json"):
+        try:
+            raw = json.loads(p.read_text())
+        except Exception:
+            continue
+        profile = raw.get("profile") or {}
+        persona_id = raw.get("persona_id") or raw.get("name_slug") or p.stem
+        name_display = raw.get("name_display") or "—"
+        for evt_type, field_name in (("shown", "shown_policies"),
+                                     ("selected", "selected_policies"),
+                                     ("rejected", "rejected_policies")):
+            for entry in (profile.get(field_name) or []):
+                events.append({
+                    "persona_id":   persona_id,
+                    "name_display": name_display,
+                    "event_type":   evt_type,
+                    "policy_slug":  entry.get("policy_slug"),
+                    "insurer":      entry.get("insurer"),
+                    "event_at":     entry.get("event_at"),
+                    "session_id":   entry.get("session_id"),
+                    "reason":       entry.get("reason"),
+                    # Outcome label is the raw event_type — operator decides
+                    # what 'shown without follow-up' means in their context.
+                    "outcome":      evt_type,
+                })
+    events.sort(key=lambda e: (e["event_at"] or ""), reverse=True)
+    events = events[:10]
+    return {
+        "events":      events,
+        "total":       len(events),
+        "snapshot_ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }

backend/brain_tools.py

@@ -0,0 +1,398 @@
+"""Tool functions for single_brain.py (Path B — single-LLM architecture).
+
+The Gemini Flash model exposed in `backend/single_brain.py` calls these
+three tools to (a) persist captured profile fields, (b) retrieve policy
+chunks from Chroma, and (c) mark which policies it has recommended on
+the current turn so follow-ups like "tell me more about #2" can resolve.
+
+Each function:
+  * Takes plain JSON-serialisable inputs (str / int / list[str]).
+  * Returns a plain JSON-serialisable dict that gets fed back to the LLM
+    on the next iteration of the function-calling loop.
+  * Never raises — failures are surfaced via {"ok": False, "error": "..."}
+    so the LLM can decide whether to retry or recover.
+
+The Gemini function-calling DSL (JSON Schema-flavoured) for these three
+tools is generated by `single_brain.TOOL_SCHEMAS` from this module's
+metadata.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+_log = logging.getLogger(__name__)
+
+
+# ---- accepted fields for save_profile_field --------------------------------
+
+# Mirrors the slot list in sales_brain._REQUIRED_FOR_READY plus the
+# nice-to-have fields the LLM may capture opportunistically. `gender`
+# is listed in the spec but is NOT a Profile dataclass field today —
+# we silently no-op on it rather than rejecting (forward-compat).
+_ACCEPTED_FIELDS = {
+    "name",
+    "age",
+    "dependents",
+    "location_tier",
+    "income_band",
+    "primary_goal",
+    "health_conditions",
+    "existing_cover_inr",
+    "budget_band",
+    "gender",  # tolerated; not persisted unless Profile gains the field
+}
+
+# These are the slots the brain MUST capture before recommending — same
+# list as sales_brain._REQUIRED_FOR_READY. Kept inline (not imported)
+# to avoid coupling single_brain to sales_brain.
+_REQUIRED_FOR_READY = (
+    "name",
+    "age",
+    "dependents",
+    "location_tier",
+    "income_band",
+    "primary_goal",
+    "health_conditions",
+)
+
+
+def _profile_complete(profile) -> bool:
+    """Return True when every slot in _REQUIRED_FOR_READY is non-empty on
+    the live Profile dataclass."""
+    for slot in _REQUIRED_FOR_READY:
+        val = getattr(profile, slot, None)
+        if val in (None, "", []):
+            return False
+    return True
+
+
+# ---- save_profile_field ----------------------------------------------------
+
+def save_profile_field(session, field: str, value: Any) -> dict:
+    """Validate + persist a captured profile field on session.profile.
+
+    Accepted fields: name, age, dependents, location_tier, income_band,
+                     primary_goal, health_conditions, existing_cover_inr,
+                     budget_band, gender (tolerated, may no-op).
+
+    Lightweight normalization:
+      - age: int, clamp to [0, 110]
+      - dependents: pass through `_normalize_dependents` when available,
+        else stringify.
+      - existing_cover_inr: parse via `_parse_inr_amount` when available,
+        else int-coerce.
+      - health_conditions: coerce to list[str], lowercase, strip empties.
+      - everything else: string pass-through (Gemini already emits
+        canonical values when prompted correctly).
+
+    Returns: {"saved": True, "field": ..., "value": ...,
+              "profile_complete": bool}
+    On unknown field: {"saved": False, "error": "unknown_field"}
+    """
+    if not isinstance(field, str) or not field:
+        return {"saved": False, "error": "missing_field_name"}
+
+    fld = field.strip().lower()
+    if fld not in _ACCEPTED_FIELDS:
+        return {"saved": False, "error": f"unknown_field:{field}"}
+
+    profile = session.profile
+    normalized: Any = value
+
+    try:
+        if fld == "age":
+            normalized = _coerce_age(value)
+        elif fld == "dependents":
+            normalized = _coerce_dependents(value)
+        elif fld == "health_conditions":
+            normalized = _coerce_health_conditions(value)
+        elif fld == "existing_cover_inr":
+            normalized = _coerce_existing_cover(value)
+        elif fld == "name":
+            normalized = (str(value).strip() if value is not None else None) or None
+        elif fld == "gender":
+            # Profile dataclass has no gender field today; silently
+            # accept + skip persistence so the LLM doesn't loop trying
+            # to save it. Forward-compat: when Profile gains gender,
+            # this branch just becomes `normalized = str(value).strip()`.
+            return {
+                "saved": False,
+                "field": fld,
+                "value": value,
+                "error": "field_not_on_profile_dataclass",
+                "profile_complete": _profile_complete(profile),
+            }
+        else:
+            # location_tier / income_band / primary_goal / budget_band — pass through
+            normalized = (str(value).strip() if value is not None else None) or None
+    except (TypeError, ValueError) as e:
+        return {
+            "saved": False,
+            "field": fld,
+            "value": value,
+            "error": f"normalize_failed:{type(e).__name__}:{e}",
+        }
+
+    # Drop None/empty so we don't overwrite a previously-captured slot
+    # with a Gemini turn that "didn't extract anything". Universal rule
+    # from KI-091/094 (extractor null overwrite).
+    if normalized in (None, "", []):
+        return {
+            "saved": False,
+            "field": fld,
+            "value": value,
+            "error": "normalized_empty",
+            "profile_complete": _profile_complete(profile),
+        }
+
+    if not hasattr(profile, fld):
+        return {
+            "saved": False,
+            "field": fld,
+            "value": value,
+            "error": "field_not_on_profile_dataclass",
+            "profile_complete": _profile_complete(profile),
+        }
+
+    setattr(profile, fld, normalized)
+    # Track that the brain has "asked" this field so the rest of the
+    # codebase's helpers (which inspect profile.asked) stay in sync.
+    try:
+        if fld not in getattr(profile, "asked", []):
+            profile.asked.append(fld)
+    except Exception:  # noqa: BLE001 — best-effort bookkeeping
+        pass
+
+    return {
+        "saved": True,
+        "field": fld,
+        "value": normalized,
+        "profile_complete": _profile_complete(profile),
+    }
+
+
+# ---- retrieve_policies -----------------------------------------------------
+
+async def retrieve_policies(
+    query: str,
+    top_k: int = 8,
+    policy_filter_ids: Optional[list[str]] = None,
+    profile=None,
+    intent: str = "recommendation",
+) -> dict:
+    """Call the existing Chroma retriever and return policy chunks.
+
+    Returns:
+      {"chunks": [{policy_id, policy_name, insurer_slug, chunk_text,
+                   doc_type, source_url, score, ...}, ...],
+       "count": N,
+       "query": query,
+       "guard": optional {reason, fallback} if filter pipeline says abort}
+
+    On failure: {"chunks": [], "count": 0, "error": "..."}.
+    """
+    if not isinstance(query, str) or not query.strip():
+        return {"chunks": [], "count": 0, "error": "empty_query"}
+
+    try:
+        from rag.retrieve import retrieve as _retrieve
+
+        chunks = await _retrieve(
+            query=query,
+            top_k=int(top_k) if top_k else 8,
+            policy_ids=policy_filter_ids or None,
+        )
+    except Exception as e:  # noqa: BLE001 — return graceful empty
+        _log.warning(
+            "retrieve_policies failed (q=%r): %s: %s",
+            query[:120], type(e).__name__, str(e)[:200],
+        )
+        return {
+            "chunks": [],
+            "count": 0,
+            "error": f"{type(e).__name__}:{str(e)[:200]}",
+        }
+
+    raw: list[dict] = []
+    for c in chunks or []:
+        raw.append(
+            {
+                "chunk_id": getattr(c, "chunk_id", ""),
+                "policy_id": getattr(c, "policy_id", ""),
+                "policy_name": getattr(c, "policy_name", ""),
+                "insurer_slug": getattr(c, "insurer_slug", ""),
+                "doc_type": getattr(c, "doc_type", ""),
+                "source_url": getattr(c, "source_url", ""),
+                "chunk_text": (getattr(c, "text", "") or "")[:1200],
+                "score": float(getattr(c, "score", 0.0) or 0.0),
+                "min_entry_age": getattr(c, "min_entry_age", None),
+                "max_entry_age": getattr(c, "max_entry_age", None),
+            }
+        )
+
+    # X5 sidecar: apply profile-fit + citation-grounding + dedup. Skip when
+    # caller supplied an explicit policy_filter_ids (we already know which
+    # policies they want).
+    guard_signal = None
+    filtered = raw
+    if not policy_filter_ids:
+        try:
+            from backend.retrieval_filters import filter_pipeline
+            filtered, guard_signal = filter_pipeline(
+                raw, profile=profile, query=query, intent=intent,
+            )
+        except Exception as e:  # noqa: BLE001 — pipeline must never break retrieval
+            _log.warning("retrieval_filters.filter_pipeline failed: %s", e)
+            filtered = raw
+
+    out = {
+        "chunks": filtered,
+        "count": len(filtered),
+        "query": query,
+    }
+    if guard_signal is not None:
+        out["guard"] = guard_signal
+    return out
+
+
+# ---- mark_recommendation ---------------------------------------------------
+
+def mark_recommendation(
+    session,
+    policy_ids: list[str],
+    is_final: bool = False,
+) -> dict:
+    """Persist the policies just recommended so follow-up turns can resolve
+    references like "tell me about #2".
+
+    Sets `session.last_recommendation_ids = policy_ids` (the same field the
+    orchestrator already maintains for follow-up routing — KI-224 / KI-228).
+    `is_final` is accepted for forward-compat (when the session grows a
+    `closed` field); today it's logged but not persisted.
+
+    Returns: {"recorded": True, "policy_ids": [...], "is_final": bool}
+    """
+    if not isinstance(policy_ids, list):
+        return {"recorded": False, "error": "policy_ids_not_list"}
+
+    # Coerce + dedupe while preserving order.
+    seen: set[str] = set()
+    cleaned: list[str] = []
+    for pid in policy_ids:
+        s = str(pid).strip()
+        if s and s not in seen:
+            seen.add(s)
+            cleaned.append(s)
+
+    try:
+        session.last_recommendation_ids = cleaned
+    except Exception as e:  # noqa: BLE001
+        return {
+            "recorded": False,
+            "error": f"setattr_failed:{type(e).__name__}:{e}",
+        }
+
+    if is_final and hasattr(session, "closed"):
+        try:
+            session.closed = True  # type: ignore[attr-defined]
+        except Exception:  # noqa: BLE001
+            pass
+
+    return {
+        "recorded": True,
+        "policy_ids": cleaned,
+        "is_final": bool(is_final),
+    }
+
+
+# ---- private normalizers ---------------------------------------------------
+
+def _coerce_age(value: Any) -> Optional[int]:
+    """int(value), clamped to [0, 110]. Empty / non-numeric → None."""
+    if value is None:
+        return None
+    try:
+        if isinstance(value, bool):  # bool is an int subclass — block first
+            return None
+        n = int(value)
+    except (TypeError, ValueError):
+        # Try string parse — Gemini sometimes emits "29" as a JSON string
+        try:
+            n = int(str(value).strip())
+        except (TypeError, ValueError):
+            return None
+    if n < 0:
+        n = 0
+    if n > 110:
+        n = 110
+    return n
+
+
+def _coerce_dependents(value: Any) -> Optional[str]:
+    """Delegate to sales_brain_normalizer when importable; else stringify."""
+    if value is None:
+        return None
+    try:
+        from backend.sales_brain_normalizer import _normalize_dependents
+
+        # The normalizer signature is (value, schema); pass an empty dict
+        # so it falls back to its built-in canonical-string mapping.
+        return _normalize_dependents(value, {})
+    except Exception:  # noqa: BLE001 — best-effort
+        s = str(value).strip()
+        return s or None
+
+
+def _coerce_existing_cover(value: Any) -> Optional[int]:
+    """Parse INR amounts like "5L" / "5 lakh" / 500000 via the canonical
+    parser. Numeric pass-throughs are clamped to >= 0.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        n = int(value)
+        return max(0, n)
+    try:
+        from backend.needs_finder import _parse_inr_amount
+
+        parsed = _parse_inr_amount(str(value))
+        if parsed is not None:
+            return max(0, int(parsed))
+    except Exception:  # noqa: BLE001
+        pass
+    # Last-ditch: strip non-digits
+    try:
+        digits = "".join(ch for ch in str(value) if ch.isdigit())
+        if digits:
+            return max(0, int(digits))
+    except Exception:  # noqa: BLE001
+        pass
+    return None
+
+
+def _coerce_health_conditions(value: Any) -> Optional[list[str]]:
+    """Always return list[str] lowercase, stripped, empties dropped."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        # Gemini sometimes emits comma-joined strings instead of a list.
+        items = [t.strip() for t in value.split(",")]
+    elif isinstance(value, (list, tuple)):
+        items = [str(t).strip() for t in value]
+    else:
+        items = [str(value).strip()]
+    cleaned = [t.lower() for t in items if t]
+    # "none" / "no" → empty list (user explicitly said no conditions).
+    cleaned = [t for t in cleaned if t not in {"none", "no", "n/a", "na", "nil"}]
+    return cleaned
+
+
+__all__ = [
+    "save_profile_field",
+    "retrieve_policies",
+    "mark_recommendation",
+]

backend/faithfulness.py

@@ -59,12 +59,116 @@ MIN_TOP_SCORE = 0.18  # below this we refuse outright (BGE-small cosine similari
 MIN_AVG_SCORE = 0.22  # average of top 5 must be above this
 
 
+# ============================================================================
+# A3 — Allow-list for non-content replies that must never trigger rejection.
+# These are confirmations, fillers, and bot self-references that aren't
+# factual claims, so the citation/grounding/judge gates would only ever
+# produce false positives on them.
+# ============================================================================
+
+_ALLOWLIST_EXACT = {
+    # Single-word confirmations / fillers
+    "yes", "yeah", "yep", "yup", "yes.", "yeah.",
+    "ok", "okay", "ok.", "okay.",
+    "sure", "sure.", "right", "right.",
+    "correct", "correct.", "exactly", "exactly.",
+    "no", "no.", "nope", "nope.",
+    "thanks", "thanks.", "thank you", "thank you.",
+}
+
+# Multi-word allow-list phrases — substring match is enough because the
+# entire reply is short. These are the canonical confirmation / hedge
+# patterns the brain emits during fact-find recap turns.
+_ALLOWLIST_SUBSTRINGS = (
+    "yes, that sounds correct",
+    "yes that sounds correct",
+    "yes please",
+    "let me think about it",
+    "compare them",
+    "got it",
+    "noted",
+    "understood",
+    "sounds good",
+    "makes sense",
+)
+
+# Bot self-reference tokens. These are stylistic, not factual claims; the
+# legacy citation gate sometimes flagged a reply that opened with "Let me
+# suggest..." as missing a citation because the prose itself made no claim.
+_BOT_SELFREF_RE = re.compile(
+    r"\b(i (?:can|will|would|could|think|am|'ll|'d|'ve)|"
+    r"let me (?:suggest|think|check|recap|confirm|walk|note|share)|"
+    r"the bot|as your advisor|in my view|here's what)\b",
+    flags=re.IGNORECASE,
+)
+
+# Profile-recap confirmation regex — when the prior assistant turn ended in
+# a recap ("Let me confirm: 35yo, family floater, ₹10L cover, metro tier...
+# does that look right?") and the user replies with a yes/no/correction, the
+# next bot turn typically just acknowledges. That acknowledgement is
+# metadata, not a content claim, and must bypass faithfulness entirely.
+_CONFIRMATION_RE = re.compile(
+    r"^\s*(?:"
+    r"yes|yeah|yep|yup|"
+    r"no|nope|"
+    r"ok(?:ay)?|sure|right|correct|exactly|"
+    r"that(?:'s| is| sounds)? (?:right|correct|fine|good)|"
+    r"sounds (?:right|good|correct|fine)|"
+    r"thanks?|thank you"
+    r")\b",
+    flags=re.IGNORECASE,
+)
+
+
+def _is_allowlisted_reply(reply: str) -> bool:
+    """Return True if `reply` is a non-content message that must skip
+    faithfulness gating. Confirmations, single-word fillers, and short bot
+    self-references count as non-content."""
+    if not reply:
+        return True
+    stripped = reply.strip().lower()
+    if not stripped:
+        return True
+    if stripped in _ALLOWLIST_EXACT:
+        return True
+    # Short replies are inspected for allowlist substrings + self-references.
+    if len(stripped) < 80:
+        for needle in _ALLOWLIST_SUBSTRINGS:
+            if needle in stripped:
+                return True
+        # Pure bot self-reference w/ no numeric claim: allow.
+        if _BOT_SELFREF_RE.search(stripped) and not _has_numeric_claim(stripped):
+            return True
+    return False
+
+
+def _is_confirmation_response(text: str) -> bool:
+    """User-text or bot-reply matches the confirmation regex."""
+    if not text:
+        return False
+    return bool(_CONFIRMATION_RE.match(text.strip()))
+
+
+def _has_numeric_claim(text: str) -> bool:
+    """Quick test: does this reply make any numeric / monetary / percentage
+    claim that would need a citation?"""
+    if not text:
+        return False
+    return bool(
+        RUPEE_RE.search(text)
+        or PERCENT_RE.search(text)
+        or DURATION_RE.search(text)
+        or re.search(r"\b\d{4,}\b", text)  # bare 4+ digit numbers (sum insured)
+    )
+
+
 @dataclass
 class FaithfulnessVerdict:
     passed: bool
     reasons: list[str] = field(default_factory=list)  # gate names that failed
     unsupported_claims: list[str] = field(default_factory=list)
     suggested_reply: Optional[str] = None  # what to show user if blocked
+    soft_hint: Optional[dict] = None  # structured guidance for orchestrator retry
 
 
 # ============================================================================
@@ -90,6 +194,11 @@ def _gate_retrieval_floor(chunks: list[RetrievedChunk]) -> tuple[bool, str]:
 # Match [Source: <something>] or [Regulation: <something>] patterns
 CITATION_PATTERN = re.compile(r"\[(?:Source|Regulation):\s*([^\]]+)\]", flags=re.IGNORECASE)
 
+# A3 — inline-style citation marker: [policy_id:chunk_offset]
+# e.g. "the sum insured is ₹10L [POL/00X:7]". This is the preferred shape
+# for numeric claims because it points back to the exact chunk.
+INLINE_CITE_RE = re.compile(r"\[([A-Z0-9_/\-\.]{3,}):(\d+)\]")
+
 
 def _gate_citation_integrity(reply: str, chunks: list[RetrievedChunk]) -> tuple[bool, list[str]]:
     """Every cited policy name must be one we actually retrieved."""
@@ -120,6 +229,112 @@ def _gate_citation_integrity(reply: str, chunks: list[RetrievedChunk]) -> tuple[
     return True, []
 
 
+# ============================================================================
+# Gate 2b — CITATION REQUIRED FOR NUMERIC CLAIMS (A3)
+# ============================================================================
+
+def _gate_citation_required_for_numerics(
+    reply: str, chunks: list[RetrievedChunk]
+) -> tuple[bool, Optional[dict]]:
+    """If the reply makes a numeric / monetary / percentage / sum-insured
+    claim, require at least one citation marker — either the legacy
+    [Source: …] form OR the inline [policy_id:chunk_offset] form.
+
+    Returns (passed, soft_hint). soft_hint is a structured dict the
+    orchestrator can use to re-prompt the brain with a stricter constraint.
+    """
+    if not _has_numeric_claim(reply):
+        return True, None
+
+    has_source_cite = bool(CITATION_PATTERN.search(reply))
+    has_inline_cite = bool(INLINE_CITE_RE.search(reply))
+    if has_source_cite or has_inline_cite:
+        return True, None
+
+    # No citation accompanying a numeric claim — surface a structured hint
+    # so the orchestrator can retry with an explicit cite-required prompt.
+    expected_pid = chunks[0].policy_id if chunks else "POL/00X"
+    expected_offset = chunks[0].chunk_idx if chunks else 0
+    return False, {
+        "reason": "missing_citation",
+        "expected": f"[{expected_pid}:{expected_offset}]",
+    }
+
+
+# ============================================================================
+# Gate 2c — HALLUCINATED POLICY NAME DETECTOR (A3)
+# ============================================================================
+
+# A policy name in the reply that does NOT appear in any retrieved chunk is
+# the textbook hallucination class. Detection: match common policy-name
+# patterns ("X Health Plus", "Care Supreme", etc.) and check each against
+# the retrieved set.
+
+_POLICY_NAME_HINT_RE = re.compile(
+    r"\b([A-Z][a-zA-Z]+(?:\s+[A-Z][a-zA-Z0-9+]+){1,4})\b"
+)
+
+# Common English bigrams that look like policy names but aren't. Used as a
+# negative filter so we don't flag e.g. "United States" as a fake policy.
+_NON_POLICY_TOKENS = {
+    "united states", "new delhi", "good morning", "thank you", "hello there",
+    "let me", "i think", "i would", "i can", "i will", "you can", "you should",
+    "the bot", "your advisor", "the policy", "this policy", "that policy",
+    "hi there", "in fact", "as well", "of course", "the same", "no problem",
+    "for example", "based on", "according to",
+}
+
+
+def _gate_hallucinated_policy(
+    reply: str, chunks: list[RetrievedChunk]
+) -> tuple[bool, list[str], Optional[dict]]:
+    """Flag responses that name a policy not in the retrieved chunk set.
+
+    Returns (passed, hallucinated_names, soft_hint).
+    """
+    if not chunks:
+        return True, [], None
+
+    valid_names = {c.policy_name.lower().strip() for c in chunks if c.policy_name}
+    valid_insurers = {c.insurer_slug.lower().strip() for c in chunks if c.insurer_slug}
+
+    candidates = _POLICY_NAME_HINT_RE.findall(reply or "")
+    hallucinated: list[str] = []
+    for cand in candidates:
+        cl = cand.lower().strip()
+        if cl in _NON_POLICY_TOKENS:
+            continue
+        # Skip candidates without policy-ish keywords
+        if not any(
+            kw in cl for kw in (
+                "health", "care", "supreme", "plus", "shield", "star",
+                "optima", "secure", "guard", "assure", "cover", "medi",
+                "wellness", "protect", "active", "smart", "elite", "premier",
+            )
+        ):
+            continue
+        if any(cl in vn or vn in cl for vn in valid_names if len(vn) >= 4):
+            continue
+        if any(slug in cl for slug in valid_insurers if len(slug) >= 4):
+            continue
+        hallucinated.append(cand)
+
+    if not hallucinated:
+        return True, [], None
+
+    cited_policies = sorted({c.policy_id for c in chunks if c.policy_id})
+    soft_hint = {
+        "reason": "hallucinated_policy",
+        "hallucinated": hallucinated,
+        "cited_policies": cited_policies,
+        "instruction": (
+            "Retry with explicit cited_policies constraint: only mention "
+            f"policies whose policy_id is in {cited_policies}."
+        ),
+    }
+    return False, hallucinated, soft_hint
+
+
 # ============================================================================
 # Gate 3 — NUMERIC GROUNDING
 # ============================================================================
@@ -283,15 +498,36 @@ async def check_faithfulness(
     user_text: str = "",
     run_llm_judge: bool = True,
     brain_model_used: Optional[str] = None,
+    pre_recap_emitted: bool = False,
 ) -> FaithfulnessVerdict:
     """Run all gates. Return verdict with reasons + a safe reply to show user if blocked.
 
     `brain_model_used` is forwarded to Gate 4 so the judge can never be the
     same model (or same family) as the brain that produced `reply` —
     enforces the cross-grading independence invariant.
+
+    `pre_recap_emitted` — set by the orchestrator when the previous bot
+    turn ended with a profile recap. When True AND the current user-text
+    or reply is a confirmation token, the entire faithfulness pipeline
+    is bypassed (this is metadata, not a content claim).
     """
     verdict = FaithfulnessVerdict(passed=True)
 
+    # A3 — PRE-RECAP CONFIRMATION BYPASS. When the bot just emitted a profile
+    # recap, the user's "yes"/"correct"/etc. plus the bot's acknowledgement
+    # are pure metadata. Running citation/grounding gates over those yields
+    # only false positives.
+    if pre_recap_emitted and (
+        _is_confirmation_response(user_text) or _is_confirmation_response(reply)
+    ):
+        return verdict  # auto-pass
+
+    # A3 — ALLOW-LIST: short bot replies that aren't factual claims at all
+    # (yes, ok, "let me think about it", "compare them", pure bot self-ref)
+    # never reach the citation/grounding gates.
+    if _is_allowlisted_reply(reply):
+        return verdict  # auto-pass
+
     # Gate 1 — retrieval floor
     ok1, msg1 = _gate_retrieval_floor(chunks)
     if not ok1:
@@ -310,6 +546,29 @@ async def check_faithfulness(
         verdict.passed = False
         verdict.reasons.extend(bad_citations)
 
+    # Gate 2b — numeric claim must be accompanied by a citation marker.
+    # Emit a structured soft-hint so the orchestrator can retry with the
+    # exact expected citation shape.
+    ok2b, cite_hint = _gate_citation_required_for_numerics(reply, chunks)
+    if not ok2b:
+        verdict.passed = False
+        verdict.reasons.append("gate2b_missing_citation_for_numeric")
+        verdict.soft_hint = cite_hint
+
+    # Gate 2c — hallucinated policy name. Flag policies named in the reply
+    # that aren't in the retrieved chunk set. Surface a soft hint that the
+    # orchestrator can pass back to the brain as a `cited_policies=[...]`
+    # constraint on retry.
+    ok2c, hallucinated_names, hp_hint = _gate_hallucinated_policy(reply, chunks)
+    if not ok2c:
+        verdict.passed = False
+        verdict.reasons.append(
+            f"gate2c_hallucinated_policy: {', '.join(hallucinated_names)}"
+        )
+        verdict.unsupported_claims.extend(hallucinated_names)
+        # If we already have a soft hint from 2b, prefer 2c (it's more actionable).
+        verdict.soft_hint = hp_hint or verdict.soft_hint
+
     # Gate 3 — numeric grounding
     ok3, bad_nums = _gate_numeric_grounding(reply, chunks)
     if not ok3:

backend/llm_health.py

@@ -93,6 +93,13 @@ HEALTH_FILE.parent.mkdir(parents=True, exist_ok=True)
 # of a pool degradation (more than fast enough at our chat volume) and
 # drops probe-driven Groq spend to ~3K/day baseline (well inside quota).
 PROBE_INTERVAL_SEC = 300
+# A4 (2026-05-15) — cadence audit: 300s for steady-state probes is comfortably
+# above the audit's 90s minimum for non-failing providers. The post-failure
+# tighter cadence is implemented OUT-OF-BAND in `report_failure()`, which
+# schedules a `_reprobe_one()` immediately after every chat failure (effective
+# 0s after-failure cadence on the loop, not 30s). The 300s cadence then
+# resumes for the long-run probe stream so the steady state stays cheap.
+PROBE_INTERVAL_SEC_FAILING = 30   # A4 — documented post-failure cadence ceiling
 # KI-084 — completion size on probes cut from 5 → 1. The probe only
 # needs a non-empty 200 response to mark a candidate healthy; we never
 # parse the body content. max_tokens=1 keeps the same response shape +
@@ -104,6 +111,11 @@ PROBE_HISTORY_LEN = 5             # rolling window for success_rate signal
 HEALTHY_PROBE_AGE_SEC = 600       # KI-084 — election candidates need a probe
                                   # within the last 600s (tracks 300s cadence
                                   # plus headroom for one missed tick).
+# A4 (2026-05-15) — explicit STALE window. If a candidate hasn't been probed
+# in >STALE_AGE_SEC, its on-record status is rewritten to "stale" so the
+# router treats it as untested rather than trusting the last-known
+# "healthy"/"unhealthy" verdict from minutes/hours ago.
+STALE_AGE_SEC = HEALTHY_PROBE_AGE_SEC  # alias for clarity; same threshold.
 DEGRADED_WINDOW_SEC = 30          # report_failure sidelines a model this long
                                   # for transient failures (timeout / 5xx).
 # KI-084 — rate-limit failures (HTTP 429 + provider 'RateLimit' bodies) are
@@ -200,7 +212,12 @@ def provider_of(model_id: str) -> str:
 @dataclass
 class ModelHealth:
     model: str
-    status: str = "unknown"               # 'healthy' | 'degraded' | 'down' | 'unknown'
+    # A4 (2026-05-15) — 'stale' added. Set by `effective_status()` when a
+    # row hasn't been pinged in > STALE_AGE_SEC; the router then treats it
+    # as untested instead of trusting a last-known healthy/unhealthy verdict
+    # from minutes/hours ago. Persisted records may still carry the older
+    # status — the elector calls effective_status() at decision time.
+    status: str = "unknown"               # 'healthy' | 'degraded' | 'down' | 'stale' | 'unknown'
     last_success_at: Optional[str] = None
     last_failure_at: Optional[str] = None
     last_error: Optional[str] = None
@@ -358,6 +375,25 @@ def _score(h: ModelHealth) -> float:
     return (1.0 / max(50, h.latency_ms)) * _success_rate(h)
 
 
+def effective_status(h: ModelHealth) -> str:
+    """A4 (2026-05-15) — Return the routing-relevant status, applying the
+    STALE_AGE_SEC override at read time.
+
+    A stored `status` of "healthy" can mean "the last probe N hours ago
+    said this was healthy" — which the router must NOT trust. When
+    `tested_at` is older than `STALE_AGE_SEC` (or missing entirely), we
+    return "stale" so the elector treats the candidate as untested.
+
+    The stored status is not mutated here — that's the probe's job. Only
+    the live decision surface (election eligibility, status_summary) calls
+    this so historical inspection (logs, on-disk JSON) is preserved.
+    """
+    age = _iso_age_seconds(h.tested_at)
+    if age is None or age > STALE_AGE_SEC:
+        return "stale"
+    return h.status
+
+
 def _is_election_eligible(h: ModelHealth, now_mono: float) -> bool:
     """A candidate is electable when:
       - status is healthy (or degraded with a recent success)
@@ -365,6 +401,9 @@ def _is_election_eligible(h: ModelHealth, now_mono: float) -> bool:
       - it is NOT currently in the degraded-window sin-bin
       - KI-085 (2026-05-15): it has credits remaining above its low-water
         mark, OR no credit signal yet (cold-start = permissive).
+      - A4 (2026-05-15): effective_status != "stale" (catches the case
+        where status field is 'healthy' but the probe is older than
+        STALE_AGE_SEC).
     """
     if h.degraded_until_monotonic > now_mono:
         return False
@@ -375,6 +414,8 @@ def _is_election_eligible(h: ModelHealth, now_mono: float) -> bool:
         return False
     if h.latency_ms is None:
         return False
+    if effective_status(h) == "stale":
+        return False
     if not _has_credits(h, now_mono):
         logger.info(
             "election: skipping %s — credits %s/%s below water %s",
@@ -422,6 +463,57 @@ def _ranked_candidates(chain_name: str) -> list[ModelHealth]:
     return [h for _, h in eligible]
 
 
+# A4 (2026-05-15) — Election event log. Tracks the last elected primary/
+# backup per chain so we can emit a structured promotion/demotion log line
+# when the elected model changes. Stored in-memory only (cheap; resets on
+# process restart, which is fine — first post-restart election re-emits).
+_LAST_ELECTION_LOCK = threading.Lock()
+_LAST_ELECTION: dict[str, dict[str, Optional[str]]] = {}
+
+
+def _emit_election_event(chain_name: str, role: str, from_m: Optional[str],
+                          to_m: Optional[str], reason: str) -> None:
+    """A4 (2026-05-15) — Structured log line for every primary/backup
+    promotion or demotion. Format matches the audit brief:
+        {event, chain, role, from, to, reason, ts}
+    The router / admin UI / log-shipper can grep on `event=election` to
+    rebuild the timeline of who served what when.
+    """
+    event = {
+        "event": "election",
+        "chain": chain_name,
+        "role": role,
+        "from": from_m,
+        "to": to_m,
+        "reason": reason,
+        "ts": _now_iso(),
+    }
+    try:
+        logger.info("llm_health.election %s", json.dumps(event, ensure_ascii=False))
+    except Exception:
+        # Logging must never block the election path.
+        pass
+
+
+def _record_election(chain_name: str, role: str, new_model: Optional[str],
+                      reason: str = "elect") -> None:
+    """Compare against last-recorded election for this (chain, role) and
+    emit a structured log line on change. No-op if the value is unchanged.
+    """
+    with _LAST_ELECTION_LOCK:
+        per_chain = _LAST_ELECTION.setdefault(chain_name, {})
+        prev = per_chain.get(role, "__UNSET__")  # sentinel — None is a real value
+        if prev == new_model:
+            return
+        per_chain[role] = new_model
+    # Logging outside the lock — never block other elections on logger I/O.
+    _emit_election_event(
+        chain_name, role,
+        None if prev == "__UNSET__" else prev,
+        new_model, reason,
+    )
+
+
 def get_primary(chain_name: str) -> Optional[str]:
     """KI-201 (2026-05-15) — elect by CHAIN ORDER, not latency score.
 
@@ -440,9 +532,15 @@ def get_primary(chain_name: str) -> Optional[str]:
     Latency is no longer used for primary/backup selection — eligibility
     filtering still uses the rolling probe state, but ordering is
     purely chain-positional.
+
+    A4 (2026-05-15) — emits a structured `event=election` log line via
+    `_record_election` whenever the elected primary changes for this
+    chain, so the operator/admin/log-shipper can rebuild the promotion/
+    demotion timeline. No log emit when the value is unchanged.
     """
     chain = _chain_for(chain_name)
     if not chain:
+        _record_election(chain_name, "primary", None, reason="empty_chain")
         return None
     # _ranked_candidates returns the eligibility-filtered set (probe-fresh,
     # not in sin-bin, credit-not-exhausted, healthy). Reduce to a set for
@@ -450,7 +548,9 @@ def get_primary(chain_name: str) -> Optional[str]:
     eligible_models = {h.model for h in _ranked_candidates(chain_name)}
     for model in chain:
         if model in eligible_models:
+            _record_election(chain_name, "primary", model, reason="chain_walk")
             return model
+    _record_election(chain_name, "primary", None, reason="no_eligible")
     return None  # nothing eligible
 
 
@@ -465,9 +565,13 @@ def get_backup(chain_name: str) -> Optional[str]:
     Meta → NVIDIA), so walking past the primary in chain order naturally
     preserves the cross-family backup invariant KI-087 used to enforce
     via provider_of().
+
+    A4 (2026-05-15) — emits a structured `event=election` log line via
+    `_record_election` whenever the elected backup changes.
     """
     chain = _chain_for(chain_name)
     if not chain:
+        _record_election(chain_name, "backup", None, reason="empty_chain")
         return None
     eligible_models = {h.model for h in _ranked_candidates(chain_name)}
     primary = get_primary(chain_name)
@@ -475,7 +579,9 @@ def get_backup(chain_name: str) -> Optional[str]:
         if model == primary:
             continue
         if model in eligible_models:
+            _record_election(chain_name, "backup", model, reason="chain_walk")
             return model
+    _record_election(chain_name, "backup", None, reason="no_eligible")
     return None
 
 
@@ -1039,12 +1145,17 @@ def filter_chain(chain: list[str]) -> list[str]:
 def status_summary() -> dict:
     """Compact summary for /api/health/llms endpoint."""
     state = load()
-    summary = {"updated_at": None, "by_status": {"healthy": 0, "degraded": 0, "down": 0, "unknown": 0}, "models": []}
+    summary = {"updated_at": None, "by_status": {"healthy": 0, "degraded": 0, "down": 0, "stale": 0, "unknown": 0}, "models": []}
     for m, h in state.items():
-        summary["by_status"][h.status] = summary["by_status"].get(h.status, 0) + 1
+        # A4 (2026-05-15) — `effective_status` applies the STALE_AGE_SEC
+        # override at read time so the admin UI / router see "stale" for
+        # rows whose stored 'healthy' verdict is older than STALE_AGE_SEC.
+        eff = effective_status(h)
+        summary["by_status"][eff] = summary["by_status"].get(eff, 0) + 1
         summary["models"].append({
             "model": m,
-            "status": h.status,
+            "status": eff,
+            "stored_status": h.status,  # preserved for debug / drift detection
             "latency_ms": h.latency_ms,
             "last_success_at": h.last_success_at,
             "last_failure_at": h.last_failure_at,

backend/main.py

@@ -28,6 +28,16 @@ from backend.orchestrator import handle_turn
 from backend.providers.sarvam_stt import SarvamSTT
 from backend.providers.sarvam_tts import SarvamTTS
 
+# Path B — opt-in single-LLM brain. Off by default; flip via env var.
+# When on we replace orchestrator.handle_turn with single_brain.handle_turn
+# for the /api/chat hot path and fall back to the legacy orchestrator on
+# any SingleBrainError (so users always get a reply).
+import os as _os  # local alias to avoid stomping any later `import os`
+
+USE_SINGLE_BRAIN = _os.environ.get("USE_SINGLE_BRAIN", "false").lower() in (
+    "1", "true", "yes", "on",
+)
+
 # Singleton provider instances (initialized on first call)
 _stt: Optional[SarvamSTT] = None
 _tts: Optional[SarvamTTS] = None
@@ -416,17 +426,52 @@ async def chat(req: ChatRequest):
     # not a connection-reset to the user. 45s is generous but tighter than
     # HF Space's gateway timeout, so the user always gets a response.
     try:
-        turn = await asyncio.wait_for(
-            handle_turn(
-                user_text=req.user_text,
-                chat_history=req.chat_history,
-                user_profile=req.profile,
-                policy_filter_ids=req.policy_filter_ids,
-                session_id=session_id,
-                view_context=req.view_context,
-            ),
-            timeout=45.0,
-        )
+        if USE_SINGLE_BRAIN:
+            # Path B — one Gemini call per turn with native function-calling.
+            # Falls back to the legacy orchestrator on SingleBrainError so a
+            # missing GOOGLE_API_KEY / model outage never breaks the chat.
+            from backend import single_brain
+            from backend.session_state import get_session
+
+            _sb_session = get_session(session_id)
+            try:
+                turn = await asyncio.wait_for(
+                    single_brain.handle_turn(
+                        session=_sb_session,
+                        user_text=req.user_text,
+                        chat_history=req.chat_history,
+                    ),
+                    timeout=45.0,
+                )
+            except single_brain.SingleBrainError as _sb_err:
+                logging.warning(
+                    "single_brain failed, falling back to orchestrator "
+                    "(session=%s): %s",
+                    session_id, _sb_err,
+                )
+                turn = await asyncio.wait_for(
+                    handle_turn(
+                        user_text=req.user_text,
+                        chat_history=req.chat_history,
+                        user_profile=req.profile,
+                        policy_filter_ids=req.policy_filter_ids,
+                        session_id=session_id,
+                        view_context=req.view_context,
+                    ),
+                    timeout=45.0,
+                )
+        else:
+            turn = await asyncio.wait_for(
+                handle_turn(
+                    user_text=req.user_text,
+                    chat_history=req.chat_history,
+                    user_profile=req.profile,
+                    policy_filter_ids=req.policy_filter_ids,
+                    session_id=session_id,
+                    view_context=req.view_context,
+                ),
+                timeout=45.0,
+            )
     except asyncio.TimeoutError:
         logging.warning(
             "handle_turn outer TimeoutError; returning graceful reply (session=%s)",

backend/orchestrator.py

@@ -249,6 +249,32 @@ class BrainPick:
 CONTEXT_DEPENDENT_INTENTS = frozenset({"recommendation", "comparison"})
 
 
+# KI-225 — knowledge-question carve-out. KI-154 force-routed empty-profile QA
+# without a named insurer to fact_find, which over-corrected: pure knowledge
+# lookups like "what is co-pay?", "how does NCB work?", "explain pre-existing
+# diseases" were being interrupted with "First, your age?". These are
+# definition-style queries — no user context required.
+_KNOWLEDGE_QUESTION_PATTERNS = (
+    "what is", "what are", "what's a", "what's the", "whats a", "whats the",
+    "how does", "how do", "how is", "how are",
+    "tell me about", "explain", "define", "definition of",
+    "difference between", "differ between",
+    "meaning of", "what does", "what means",
+)
+
+
+def _is_knowledge_question(query: str) -> bool:
+    """KI-225 — return True when the query opens with a definition-style
+    pattern (what is, how does, explain, etc.). Such queries are policy-fact
+    lookups that don't depend on user profile and should pass straight to
+    the QA brain even when the live session has an empty profile.
+    """
+    q = (query or "").lower().strip()
+    if not q:
+        return False
+    return any(q.startswith(p) for p in _KNOWLEDGE_QUESTION_PATTERNS)
+
+
 def should_route_to_fact_find(
     intent: str,
     *,
@@ -289,6 +315,13 @@ def should_route_to_fact_find(
         ql = query.lower()
         if any(tok in ql for tok in _NAMED_INSURER_TOKENS):
             return False
+        # KI-225 — knowledge-question carve-out. Definition-style queries
+        # ("what is co-pay?", "how does NCB work?", "explain pre-existing
+        # diseases") are policy-fact lookups that don't need user context.
+        # KI-154 over-corrected by force-routing these into fact_find — the
+        # user got "First, your age?" instead of a definition.
+        if _is_knowledge_question(query):
+            return False
         # Otherwise — empty-profile generic intent — route to fact_find so the
         # bot collects basic context before quoting policy specifics.
         return True
@@ -527,6 +560,10 @@ class TurnResult:
     faithfulness_reasons: list[str] = field(default_factory=list)
     blocked: bool = False
     profile_updates: dict = field(default_factory=dict)
+    # KI-228 — set when this turn was detected as a follow-up about a specific
+    # policy from the previous recommendation shortlist (e.g. "tell me more
+    # about #2"). The frontend uses this to highlight the matching card.
+    followup_policy_id: Optional[str] = None
 
 
 async def handle_turn(
@@ -672,14 +709,6 @@ async def handle_turn(
             profile_updates={},
         )
 
-    treat_as_fact_find = should_route_to_fact_find(
-        intent,
-        profile_is_empty=profile_is_empty,
-        in_fact_find_continuation=in_fact_find_continuation,
-        free_form_session=session.free_form_session,
-        query=user_text,
-    )
-
     # KI-196 (ADR-041) — confirmation-gated profile recall. If the prior
     # turn staged a pending recall (matched name → on-disk profile), the
     # bot's last reply already asked the user whether to continue or start
@@ -689,6 +718,14 @@ async def handle_turn(
     #   - Other   → leave pending_profile_recall in place; the brain will
     #               re-ask one more time. (One re-ask cap is enforced by the
     #               brain's prompt — see sales_brain._build_system_prompt.)
+    #
+    # KI-227 — MUST run BEFORE `should_route_to_fact_find` is computed. The
+    # prior ordering computed treat_as_fact_find against the EMPTY pre-merge
+    # profile, then merged the stored profile, then proceeded — so the user's
+    # "Continue" turn routed to fact_find with stale (empty) profile state.
+    # After the gate resolves, we recompute profile_is_empty /
+    # _required_profile_incomplete / in_fact_find_continuation so the routing
+    # decision below sees the merged profile.
     if session.pending_profile_recall is not None:
         _utxt = (user_text or "").strip().lower()
         _AFFIRM = (
@@ -731,6 +768,60 @@ async def handle_turn(
         # If neither was detected, leave it staged — sales_brain will re-ask
         # via its system-prompt hook (see _build_system_prompt).
 
+        # KI-227 — recompute routing-decision inputs against the (possibly
+        # merged) profile so should_route_to_fact_find below sees the right
+        # state. Without this the "Continue" turn ran against pre-merge
+        # empty-profile values and force-routed back into fact_find.
+        _required_profile_incomplete = any(
+            not getattr(session.profile, slot, None)
+            for slot in _FACT_FIND_REQUIRED_SLOTS
+        )
+        in_fact_find_continuation = (
+            _required_profile_incomplete and not session.free_form_session
+        )
+        profile_is_empty = (
+            session.profile.age is None
+            and session.profile.dependents is None
+            and session.profile.income_band is None
+        )
+
+    treat_as_fact_find = should_route_to_fact_find(
+        intent,
+        profile_is_empty=profile_is_empty,
+        in_fact_find_continuation=in_fact_find_continuation,
+        free_form_session=session.free_form_session,
+        query=user_text,
+    )
+
+    # KI-228 — confirmation-answer routing. When all required slots are filled
+    # but the session hasn't flipped to free_form_session yet (KI-215 only
+    # flips on an explicit recommendation request), the user's natural
+    # confirmation reply ("yes, that's correct" / "yep, sounds good" / "no,
+    # change income") was routing to QA → faithfulness gate → "I'd rather
+    # not answer that without stronger evidence...". Treat short affirmations,
+    # negations, and brief acknowledgements as fact-find continuation so
+    # sales_brain handles the confirmation turn rather than the QA gate.
+    _AFFIRM_OR_SHORT = re.compile(
+        r"^\s*(yes|yeah|yep|yup|correct|right|sounds good|looks good|that.s right|confirmed|ok|okay|sure|alright)\b",
+        re.IGNORECASE,
+    )
+    _NEGATE_SHORT = re.compile(
+        r"^\s*(no|nope|nah|not.really|incorrect|wrong)\b",
+        re.IGNORECASE,
+    )
+    _slots_complete_routing = all(
+        getattr(session.profile, slot, None) not in (None, "", [])
+        for slot in _FACT_FIND_REQUIRED_SLOTS
+    )
+    if _slots_complete_routing and not session.free_form_session:
+        _utxt_routing = user_text or ""
+        if (
+            _AFFIRM_OR_SHORT.match(_utxt_routing)
+            or _NEGATE_SHORT.match(_utxt_routing)
+            or len(_utxt_routing.strip()) < 25
+        ):
+            treat_as_fact_find = True
+
     if treat_as_fact_find:
         # KI-167 (2026-05-15) — WS2: replaces drive_fact_find with
         # drive_sales_brain. The new brain owns conversation flow end-to-end
@@ -1087,6 +1178,106 @@ async def handle_turn(
             session_id, type(e).__name__, str(e)[:200],
         )
 
+    # KI-228 — post-recommendation follow-up routing. When the previous turn
+    # served a shortlist and persisted `session.last_recommendation_ids`, this
+    # turn might be a follow-up like "tell me more about #2" / "the second one"
+    # / "what about Policy X". Detect the reference, map to a specific
+    # policy_id, and bias retrieval to surface ONLY that policy's chunks.
+    #
+    # Ordinal map: "#1"/"first"/"first one" → index 0, etc. Run BEFORE retrieval
+    # so we can rewrite `policy_filter_ids` for this turn.
+    followup_policy_id: Optional[str] = None
+    if (
+        getattr(session, "last_recommendation_ids", None)
+        and not policy_filter_ids  # don't override an explicit caller-supplied filter
+    ):
+        _shortlist = list(session.last_recommendation_ids)
+        _utxt_followup = (user_text or "").lower().strip()
+        # Ordinal: "#1" / "# 1" / "1st" / "first one" / "first" (word-boundary
+        # to avoid eating "first buy" / "first time buyer").
+        _ORDINAL_PATTERNS: list[tuple[re.Pattern, int]] = [
+            (re.compile(r"(?:^|\s)#\s*1(?:\b|$)"), 0),
+            (re.compile(r"(?:^|\s)#\s*2(?:\b|$)"), 1),
+            (re.compile(r"(?:^|\s)#\s*3(?:\b|$)"), 2),
+            (re.compile(r"\b1st\b"), 0),
+            (re.compile(r"\b2nd\b"), 1),
+            (re.compile(r"\b3rd\b"), 2),
+            (re.compile(r"\b(?:the\s+)?first\s+(?:one|policy|option|recommendation)\b"), 0),
+            (re.compile(r"\b(?:the\s+)?second\s+(?:one|policy|option|recommendation)?\b"), 1),
+            (re.compile(r"\b(?:the\s+)?third\s+(?:one|policy|option|recommendation)?\b"), 2),
+            # Detail-request prefix + bare ordinal ("explain the first",
+            # "tell me about the first / second / third"). Disambiguates from
+            # "first buy" / "first time" which are goal keywords, not ordinals.
+            (re.compile(r"\b(?:tell\s+me\s+about|explain|details?\s+on|what\s+about|more\s+on)\s+the\s+first\b"), 0),
+            (re.compile(r"\b(?:tell\s+me\s+about|explain|details?\s+on|what\s+about|more\s+on)\s+the\s+second\b"), 1),
+            (re.compile(r"\b(?:tell\s+me\s+about|explain|details?\s+on|what\s+about|more\s+on)\s+the\s+third\b"), 2),
+            (re.compile(r"\boption\s+1\b"), 0),
+            (re.compile(r"\boption\s+2\b"), 1),
+            (re.compile(r"\boption\s+3\b"), 2),
+            (re.compile(r"\bpolicy\s+1\b"), 0),
+            (re.compile(r"\bpolicy\s+2\b"), 1),
+            (re.compile(r"\bpolicy\s+3\b"), 2),
+        ]
+        for _pat, _idx in _ORDINAL_PATTERNS:
+            if _pat.search(_utxt_followup) and _idx < len(_shortlist):
+                followup_policy_id = _shortlist[_idx]
+                break
+        # Policy-name match: look for any of the shortlist policy names in
+        # user_text by scanning the most recent assistant message in
+        # chat_history for ID-adjacent name strings. We don't have a direct
+        # id→name map on the session, so fall back to a soft signal: if the
+        # user says "tell me more about <X>" or "what about <X>", inject the
+        # phrase into the retrieval query so the embedding bias toward <X>
+        # naturally pulls its chunks (no filter — the brain still sees the
+        # full shortlist context).
+        if followup_policy_id is None and chat_history:
+            _last_assistant = ""
+            for _msg in reversed(chat_history):
+                if isinstance(_msg, dict) and _msg.get("role") == "assistant":
+                    _last_assistant = str(_msg.get("content") or "")
+                    break
+            # If user_text references "this" / "that" / "it" + an explicit
+            # request-for-detail verb, AND we have a single-policy shortlist,
+            # default to that one policy.
+            _detail_request = bool(
+                re.search(
+                    r"\b(?:tell\s+me\s+more|more\s+about|more\s+details?|"
+                    r"explain|details?\s+on|what\s+about|how\s+about)\b",
+                    _utxt_followup,
+                )
+            )
+            if _detail_request and len(_shortlist) == 1:
+                followup_policy_id = _shortlist[0]
+            # Otherwise, scan the prior assistant turn for capitalized policy
+            # names also present in the user's text. We don't try to be
+            # exhaustive here — the retrieval embedding already handles loose
+            # name matches; this is just for the explicit-filter case.
+            elif _detail_request and _last_assistant:
+                # Extract candidate names from the assistant turn (2-6 word
+                # Title-Case sequences). Cross-check against user_text.
+                _name_re = re.compile(r"\b(?:[A-Z][A-Za-z0-9&\-']+\s+){1,5}[A-Z][A-Za-z0-9&\-']+\b")
+                _candidate_names = set(_name_re.findall(_last_assistant))
+                _utxt_caseful = (user_text or "")
+                for _cand in _candidate_names:
+                    if _cand.lower() in _utxt_caseful.lower() and len(_cand) >= 6:
+                        # Found a likely policy-name reference. Inject into
+                        # user_text for retrieval bias (matches the fallback
+                        # path described in the spec). Don't set filter — we
+                        # don't have a confident id mapping.
+                        if not user_text.lower().startswith(_cand.lower()):
+                            user_text = f"about {_cand}: {user_text}"
+                        break
+        if followup_policy_id is not None:
+            # Override the retrieval filter so this turn surfaces ONLY the
+            # matched policy's chunks. Preserve any caller-supplied filter
+            # (we already guarded against it above, but belt-and-braces).
+            if not policy_filter_ids:
+                policy_filter_ids = [followup_policy_id]
+            logging.info(
+                "KI-228 follow-up routing matched policy_id=%s (session=%s)",
+                followup_policy_id, session_id,
+            )
+
     # 2. Retrieve — pass session_id so the user's profile chunk (stored in
     # Chroma at POST /api/profile time) gets boosted to the top of the
     # context. Without session_id this path is dormant and the brain never
@@ -1142,6 +1333,13 @@ async def handle_turn(
             "show me a few", "show me some", "side by side", "side-by-side",
             "three options", "few options", "some options", "compare options",
             "shortlist", "give me options", "give me three",
+            # KI-226 — broadened detection. Live captures showed users saying
+            # "good for me", "which one fits", "help me pick" etc., which
+            # routed through the QA + faithfulness path instead of the
+            # recommendation lane.
+            "good for me", "which one", "which fits", "fits",
+            "list of polic", "give me a list", "help me pick",
+            "help me choose", "narrow", "any suggestion", "any recommend",
         )
     )
 
@@ -1153,6 +1351,33 @@ async def handle_turn(
     if _is_recommendation or intent == "comparison":
         chunks = [c for c in chunks if (c.insurer_slug or "").lower() != "regulatory"]
 
+    # KI-229 — empty-retrieval recommendation guard. When the user explicitly
+    # asks for a recommendation/comparison AND retrieval came back with zero
+    # usable chunks (e.g. niche profile that doesn't match any indexed policy),
+    # the brain has nothing to ground on and the faithfulness gate is skipped
+    # for recommendations (KI-171). The result was hallucinated policy names
+    # with no citations. Short-circuit BEFORE the brain call with a polite ask
+    # to broaden the criteria.
+    if (_is_recommendation or intent == "comparison") and len(chunks) == 0:
+        reply = (
+            "I don't have policy data that matches your specific profile right now — "
+            "could you broaden the criteria (e.g., a different age band, dependents, "
+            "or budget) so I can pull relevant options?"
+        )
+        return TurnResult(
+            reply_text=reply,
+            citations=[],
+            retrieved_chunk_ids=[],
+            brain_used="orchestrator::empty_retrieval_short_circuit",
+            intent=intent,
+            language=language,
+            latency_ms=int((time.time() - t0) * 1000),
+            raw_reply=reply,
+            faithfulness_passed=True,
+            blocked=False,
+            profile_updates=profile_updates_applied,
+        )
+
     context_str = format_for_llm_context(chunks)
 
     # 3. Pick brain
@@ -1348,6 +1573,34 @@ async def handle_turn(
         if (c.insurer_slug or "").lower() not in ("profile", "regulatory")
     ]
 
+    # KI-224 — persist last_recommendation_ids on the session so a follow-up
+    # ("tell me more about #2") can route against the same shortlist without
+    # re-retrieving from scratch. Only populate on clean recommendation /
+    # comparison replies (faithfulness must have passed or been legitimately
+    # skipped, and the reply must not have been blocked). Empty citations → []
+    # leaves the previous value intact only when faithfulness blocked the turn,
+    # which is the right behavior (the user never saw a new shortlist).
+    if (
+        intent in ("recommendation", "comparison")
+        and verdict.passed
+        and not blocked
+        and citations
+    ):
+        try:
+            seen: set[str] = set()
+            ids: list[str] = []
+            for cite in citations:
+                pid = cite.get("policy_id")
+                if pid and pid not in seen:
+                    seen.add(pid)
+                    ids.append(pid)
+            session.last_recommendation_ids = ids
+        except Exception as _e:
+            logging.warning(
+                "KI-224 last_recommendation_ids persist failed (session=%s): %s",
+                session_id, _e,
+            )
+
     # 7. INDIC CASCADE — translate the English reply back into Hinglish/Hindi,
     # then run THREE drift checks. If any catches drift, revert to the English
     # reply (user sees correct facts even if not in their preferred language).
@@ -1469,4 +1722,5 @@ async def handle_turn(
         faithfulness_reasons=verdict.reasons,
         blocked=blocked,
         profile_updates=profile_updates_applied,
+        followup_policy_id=followup_policy_id,
     )

backend/providers/google_gemini_llm.py

@@ -74,26 +74,121 @@ DEFAULT_MODEL = "gemini-2.5-flash-lite"  # KI-183 — gemini-2.0-flash retired f
 # this is cheap insurance and keeps the contract honest if the module is ever
 # pulled into a thread pool.
 # ----------------------------------------------------------------------------
-_CACHE_REGISTRY: dict[tuple[str, str], dict] = {}
+_CACHE_REGISTRY: dict[tuple[str, str, str], dict] = {}
 _CACHE_REGISTRY_LOCK = threading.Lock()
 
+# A4 (2026-05-15) — Gemini cachedContents server-side TTL ceiling. Google's
+# `cachedContents` resources live up to ~60min on free tier; we refresh
+# before that ceiling so an in-flight call never lands on an expired cache.
+# `CACHE_REFRESH_AGE_SEC` is the wall-clock age at which we proactively
+# re-create even if local `expires_at` has not yet elapsed — keeps us safely
+# below the server-side TTL drift window observed in production.
+CACHE_REFRESH_AGE_SEC = 50 * 60  # 50min — refresh BEFORE 60min server ceiling
 
-def _cache_key(model: str, system_text: str) -> tuple[str, str]:
-    """Build the registry key for a (model, system_text) pair.
 
-    Hashing the system text rather than storing the raw string keeps the
-    registry footprint tiny even when the preamble is multi-KB.
+def _cache_key(model: str, system_text: str, dynamic_prefix: str = "") -> tuple[str, str, str]:
+    """Build the registry key for a (model, system_text, dynamic_prefix) tuple.
+
+    A4 (2026-05-15) — Cache key collision fix: SHA256 of preamble alone is
+    insufficient when `_dynamic_profile_block` varies per persona. The key
+    now partitions on a separate `dynamic_prefix` hash so per-persona
+    caches don't collide on the same static preamble hash. `dynamic_prefix`
+    defaults to "" so existing callers retain prior behaviour.
+
+    Hashing inputs rather than storing the raw string keeps the registry
+    footprint tiny even when the preamble is multi-KB.
     """
-    return (model, hashlib.sha256(system_text.encode("utf-8")).hexdigest())
+    static_h = hashlib.sha256(system_text.encode("utf-8")).hexdigest()
+    dyn_h = hashlib.sha256(dynamic_prefix.encode("utf-8")).hexdigest() if dynamic_prefix else ""
+    return (model, static_h, dyn_h)
 
 
-def invalidate_cache(model: str, system_text: str) -> None:
+# ---------------------------------------------------------------------------
+# A4 (2026-05-15) — Normalized provider error class.
+#
+# Gemini's REST surface returns different error shapes for different failure
+# modes (429 rate-limit, 400 BlockedReason / SafetyRating, 404 cache not
+# found, 500/503 server errors). The tier wrapper needs a stable contract:
+# `BrainProviderError(retryable=bool)` where `retryable=True` signals the
+# tier should fall through to the next provider, and `retryable=False`
+# signals a hard error (auth / content blocked) that should surface to the
+# caller without burning fallback budget.
+# ---------------------------------------------------------------------------
+class BrainProviderError(RuntimeError):
+    """Stable provider-error envelope consumed by TieredBrainLLM.
+
+    Attributes:
+      provider:   short name ("gemini" / "nim" / ...)
+      retryable:  True if the tier wrapper should try the next provider.
+                  False for auth / content-block / non-recoverable errors.
+      status:     HTTP-like status code if applicable, else None.
+      raw:        the original exception (kept as __cause__ via `raise from`).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str = "gemini",
+        retryable: bool = True,
+        status: Optional[int] = None,
+    ):
+        super().__init__(message)
+        self.provider = provider
+        self.retryable = retryable
+        self.status = status
+
+
+def _classify_gemini_error(status_code: int, detail: str) -> BrainProviderError:
+    """Map a Gemini REST response into BrainProviderError(retryable=bool).
+
+    Routing rules (matches TieredBrainLLM expectations):
+      - 429 (rate-limit / quota)              → retryable (next tier)
+      - 5xx (server errors)                   → retryable (next tier)
+      - 408 / 504 (timeout)                   → retryable
+      - 401 / 403 (auth, key revoked)         → NOT retryable (surface)
+      - 400 with BlockedReason / SafetyRating → NOT retryable (content block)
+      - 400 other (malformed request)         → NOT retryable (caller bug)
+      - 404 cachedContent                     → retryable (cache lapsed,
+                                                  uncached retry already wired
+                                                  in chat() but tier-level
+                                                  fallback is still safe).
+    """
+    detail_l = (detail or "").lower()
+    retryable = False
+    if status_code == 429:
+        retryable = True
+    elif 500 <= status_code < 600:
+        retryable = True
+    elif status_code in (408, 504):
+        retryable = True
+    elif status_code == 404 and ("cache" in detail_l or "cachedcontent" in detail_l):
+        retryable = True
+    elif status_code == 400 and (
+        "blocked" in detail_l or "safety" in detail_l or "blockreason" in detail_l
+    ):
+        retryable = False
+    elif status_code in (401, 403):
+        retryable = False
+    return BrainProviderError(
+        f"Gemini API {status_code}: {detail[:300]}",
+        provider="gemini",
+        retryable=retryable,
+        status=status_code,
+    )
+
+
+def invalidate_cache(model: str, system_text: str, dynamic_prefix: str = "") -> None:
     """Drop a cache registry entry — called by upstream after a 4xx response
     that names a stale `cachedContent`. The server-side cache may still be
     alive (it will lapse on TTL), but our reference is gone so the next
     chat() call provisions a fresh one.
+
+    A4 (2026-05-15) — `dynamic_prefix` is an optional partition arg; defaults
+    to "" so existing callers retain prior behaviour. When supplied, only the
+    matching (model, system_text, dynamic_prefix) entry is dropped.
     """
-    key = _cache_key(model, system_text)
+    key = _cache_key(model, system_text, dynamic_prefix)
     with _CACHE_REGISTRY_LOCK:
         _CACHE_REGISTRY.pop(key, None)
 
@@ -162,6 +257,7 @@ class GoogleGeminiLLM(LLMProvider):
         self,
         system_text: str,
         ttl_seconds: int = 300,
+        dynamic_prefix: str = "",
     ) -> Optional[str]:
         """Create (or reuse) a Gemini `cachedContents` resource for `system_text`.
 
@@ -180,14 +276,26 @@ class GoogleGeminiLLM(LLMProvider):
         if not self.api_key or not system_text:
             return None
 
-        key = _cache_key(self.model, system_text)
+        key = _cache_key(self.model, system_text, dynamic_prefix)
         now = time.time()
         with _CACHE_REGISTRY_LOCK:
             entry = _CACHE_REGISTRY.get(key)
-            # Refresh ~10s before expiry so an in-flight request never lands
-            # on a server-side cache that just rolled past its TTL.
-            if entry and entry.get("expires_at", 0) > now + 10:
-                return entry.get("name")
+            # A4 (2026-05-15) — TWO-stage refresh:
+            #   (a) self-evict ~10s before LOCAL expires_at (was already here).
+            #   (b) PROACTIVELY refresh if the entry is older than
+            #       CACHE_REFRESH_AGE_SEC (50min) regardless of expires_at —
+            #       guards against server-side TTL drift on long-lived
+            #       caches and keeps every entry well below the ~60min
+            #       cachedContents ceiling.
+            if entry:
+                created_at = entry.get("created_at", 0)
+                age = now - created_at if created_at else 0
+                if (
+                    entry.get("expires_at", 0) > now + 10
+                    and age < CACHE_REFRESH_AGE_SEC
+                ):
+                    return entry.get("name")
+                # else: fall through and recreate
 
         # `model` must be the fully-qualified Gemini path "models/<id>".
         body: dict = {
@@ -234,12 +342,17 @@ class GoogleGeminiLLM(LLMProvider):
             return None
 
         with _CACHE_REGISTRY_LOCK:
+            now_create = time.time()
             _CACHE_REGISTRY[key] = {
                 "name": cache_name,
                 # Store local expiry; the registered TTL is server-side
                 # truth, but we shadow it locally so we self-evict before
                 # the inevitable 4xx on an expired reference.
-                "expires_at": time.time() + ttl_seconds,
+                "expires_at": now_create + ttl_seconds,
+                # A4 (2026-05-15) — created_at lets us proactively refresh
+                # entries that have lived past CACHE_REFRESH_AGE_SEC even
+                # when caller set a longer TTL than Google honours.
+                "created_at": now_create,
             }
         logging.info(
             "gemini.create_cache OK (model=%s, name=%s, ttl=%ss)",
@@ -296,15 +409,40 @@ class GoogleGeminiLLM(LLMProvider):
         # Per-phase timeouts mirroring the NIM/OpenRouter pattern: a stuck
         # connection releases its slot on its own deadline rather than holding
         # past the outer wait_for cancellation.
+        #
+        # A4 (2026-05-15) — Timeout binding: bind the SDK/httpx read timeout
+        # to `self.timeout - 2.0` so the underlying connection times out
+        # ~2s BEFORE the tier-wrapper's outer wait_for cancellation. This
+        # surfaces a clean BrainProviderError(retryable=True) instead of
+        # asyncio.CancelledError leaking up through the cancellation chain
+        # (which the tier wrapper has historically misclassified).
+        read_timeout = max(2.0, self.timeout - 2.0)
         client_timeout = httpx.Timeout(
             connect=2.0,
-            read=self.timeout,
+            read=read_timeout,
             write=2.0,
             pool=2.0,
         )
 
         async with httpx.AsyncClient(timeout=client_timeout) as client:
-            resp = await client.post(url, headers=headers, json=body)
+            try:
+                resp = await client.post(url, headers=headers, json=body)
+            except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+                raise
+            except httpx.TimeoutException as e:
+                # A4 (2026-05-15) — TimeoutException → retryable
+                # BrainProviderError so the tier wrapper falls through
+                # cleanly instead of seeing asyncio.CancelledError.
+                raise BrainProviderError(
+                    f"Gemini timeout after {read_timeout:.1f}s (model={self.model})",
+                    provider="gemini", retryable=True, status=None,
+                ) from e
+            except httpx.HTTPError as e:
+                # Network / DNS / connection-refused etc. — retryable.
+                raise BrainProviderError(
+                    f"Gemini transport error ({type(e).__name__}): {str(e)[:200]}",
+                    provider="gemini", retryable=True, status=None,
+                ) from e
             # KI-199 — graceful fallback when a cache reference is stale.
             # Symptoms: 400/404 with body mentioning "cachedContent" /
             # "cache" / "not found". Strip the reference, re-add the inline
@@ -331,21 +469,39 @@ class GoogleGeminiLLM(LLMProvider):
                     body["systemInstruction"] = {
                         "parts": [{"text": system_instruction}]
                     }
-                resp = await client.post(url, headers=headers, json=body)
+                try:
+                    resp = await client.post(url, headers=headers, json=body)
+                except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+                    raise
+                except httpx.TimeoutException as e:
+                    raise BrainProviderError(
+                        f"Gemini retry timeout after {read_timeout:.1f}s (model={self.model})",
+                        provider="gemini", retryable=True, status=None,
+                    ) from e
+                except httpx.HTTPError as e:
+                    raise BrainProviderError(
+                        f"Gemini retry transport error ({type(e).__name__}): {str(e)[:200]}",
+                        provider="gemini", retryable=True, status=None,
+                    ) from e
             if resp.status_code >= 400:
-                # Surface the Google error body so the caller's log makes the
-                # root cause visible (typical failure: 429 quota exceeded or
-                # 400 prompt-block).
+                # A4 (2026-05-15) — Normalize the error into BrainProviderError
+                # so the tier wrapper sees a stable contract:
+                #   retryable=True  → fall through to next tier
+                #   retryable=False → surface to caller (auth/content-block)
+                # The original httpx.HTTPStatusError is preserved as __cause__
+                # so logs still carry the full upstream trail.
                 detail = ""
                 try:
                     detail = resp.text[:500]
                 except Exception:
                     pass
-                raise httpx.HTTPStatusError(
+                upstream_err = httpx.HTTPStatusError(
                     f"Gemini API {resp.status_code}: {detail}",
                     request=resp.request,
                     response=resp,
                 )
+                normalized = _classify_gemini_error(resp.status_code, detail)
+                raise normalized from upstream_err
             payload = resp.json()
 
         # Response shape:
@@ -402,4 +558,6 @@ __all__ = [
     "get_gemini_llm",
     "DEFAULT_MODEL",
     "invalidate_cache",
+    "BrainProviderError",
+    "CACHE_REFRESH_AGE_SEC",
 ]

backend/providers/nvidia_nim_llm.py

@@ -31,6 +31,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import threading
 import time
 from pathlib import Path
 from typing import Optional
@@ -104,6 +105,48 @@ async def _append_usage(record: dict) -> None:
 _NIM_OUTBOUND_SEMAPHORE = asyncio.Semaphore(2)
 
 
+# A4 (2026-05-15) — Module-level httpx.AsyncClient singleton.
+#
+# Pre-A4: every NvidiaNimLLM.chat() call did `async with httpx.AsyncClient(...)
+# as client: ...`, which constructed a fresh connection pool per request and
+# tore it down on exit. Under brain/judge concurrency this churned TCP
+# connections, dropped TLS sessions, and (per audit) leaked pool slots when
+# an outer wait_for cancellation interrupted the async-with __aexit__ before
+# the underlying transport finalised.
+#
+# Switch to a single shared client with explicit Limits so:
+#   - max_connections=10        caps total outbound (NIM + probes share)
+#   - max_keepalive_connections=5  keeps a warm pool for the hot path
+# The client is constructed lazily (first .chat() call) so cold imports
+# don't pay TLS/handshake cost on processes that never call NIM (e.g.
+# CLI tools, eval harness).
+_NIM_HTTPX_CLIENT_LOCK = threading.Lock()
+_NIM_HTTPX_CLIENT: Optional[httpx.AsyncClient] = None
+
+
+def _get_shared_nim_client() -> httpx.AsyncClient:
+    """Return the module-level shared httpx.AsyncClient, constructing it
+    lazily on first call. The client is process-wide; do NOT close it from
+    individual chat() calls — the OS reclaims sockets at process exit.
+
+    Per-request timeout is applied at .post() call time, not at construction,
+    so the same shared pool serves chat() (long timeouts) and probes
+    (short timeouts) without contention.
+    """
+    global _NIM_HTTPX_CLIENT
+    if _NIM_HTTPX_CLIENT is not None:
+        return _NIM_HTTPX_CLIENT
+    with _NIM_HTTPX_CLIENT_LOCK:
+        if _NIM_HTTPX_CLIENT is None:
+            _NIM_HTTPX_CLIENT = httpx.AsyncClient(
+                limits=httpx.Limits(
+                    max_connections=10,
+                    max_keepalive_connections=5,
+                ),
+            )
+    return _NIM_HTTPX_CLIENT
+
+
 NVIDIA_NIM_BASE_URL = "https://integrate.api.nvidia.com/v1"
 # 2026-05-14 brain swap (D-022): NIM's DeepSeek-V4 + Meta Llama inference pools
 # are repeatedly timing out (15-120s on chat completions, no response). Qwen
@@ -159,7 +202,17 @@ class NvidiaNimLLM(LLMProvider):
             "max_tokens": max_tokens,
         }
         if response_format:
+            # A4 (2026-05-15) — NIM forwards OpenAI-shape response_format to
+            # the upstream model. For models that support `nvext.guided_json`
+            # (NIM's stricter constrained-decoding surface), surface that
+            # too when the caller passes a JSON schema (response_format
+            # with `json_schema`). The plain `{"type": "json_object"}` flag
+            # works on most NIM models as-is; we just keep it forwarded.
             body["response_format"] = response_format
+            if response_format.get("type") == "json_schema":
+                schema = response_format.get("json_schema", {}).get("schema")
+                if schema:
+                    body.setdefault("nvext", {})["guided_json"] = schema
 
         headers = {
             "Authorization": f"Bearer {self.api_key}",
@@ -202,11 +255,18 @@ class NvidiaNimLLM(LLMProvider):
         # The semaphore wraps ONLY the HTTP round-trip — not response
         # parsing or usage logging — so we cap concurrent network
         # traffic without serialising the rest of the pipeline.
-        async with httpx.AsyncClient(timeout=client_timeout) as client:
-            async with _NIM_OUTBOUND_SEMAPHORE:
-                resp = await client.post(url, headers=headers, json=body)
-            resp.raise_for_status()
-            payload = resp.json()
+        # A4 (2026-05-15) — Use the module-level shared httpx.AsyncClient
+        # (singleton with bounded connection pool) instead of constructing
+        # a fresh client per request. Per-request timeout is applied at
+        # .post() call time so the shared pool serves both long-timeout
+        # chat() and short-timeout probe() calls without contention.
+        client = _get_shared_nim_client()
+        async with _NIM_OUTBOUND_SEMAPHORE:
+            resp = await client.post(
+                url, headers=headers, json=body, timeout=client_timeout
+            )
+        resp.raise_for_status()
+        payload = resp.json()
 
         choice = payload["choices"][0]
         msg = choice.get("message", {}) or {}
@@ -440,21 +500,48 @@ class NimChainLLM(LLMProvider):
         Two models in the SAME family must never be paired as brain ↔ judge
         because they share weights / training corpus / decision surface, so
         the judge would effectively grade its own siblings' output.
-        Families: 'qwen', 'mistral', 'meta', 'openai', 'deepseek', 'moonshot',
-        'minimax', 'nvidia', 'unknown'.
+        Families: 'qwen', 'mistral', 'meta', 'openai', 'openai_oss',
+        'deepseek', 'moonshot', 'minimax', 'nvidia', 'nemotron', 'llama3',
+        'google', 'unknown'.
+
+        A4 (2026-05-15) — EVERY model in BRAIN_CHAIN / FAST_BRAIN_CHAIN /
+        JUDGE_CHAIN must map to a known family. The `assert_family_coverage()`
+        helper below walks the chains at module-import time (or on demand
+        from tests / admin / probe loop) and raises if any candidate falls
+        through to "unknown".
         """
-        m = model_id.lower()
+        m = (model_id or "").lower()
+        # KI-220 — recognise Google's Gemini family BEFORE prefix-stripping so
+        # ids like "google/gemini-2.5-flash" and bare "gemini-..." both land in
+        # the "google" bucket. Without this branch the family lookup fell
+        # through to "unknown", which meant the judge-vs-brain cross-family
+        # invariant couldn't exclude Gemini brains from a Gemini judge.
+        if "gemini" in m or m.startswith("google/"):
+            return "google"
         # Strip provider prefix first so 'groq:llama-3.3-70b' → 'meta' (it IS Meta Llama)
         if ":" in m:
             m = m.split(":", 1)[1]
+        # A4 — nemotron is its own decision surface (NVIDIA fine-tuned on
+        # top of llama but with materially different post-training); keep
+        # it distinct from generic "nvidia/" so cross-family checks don't
+        # treat a Llama-4 vs Nemotron pairing as same-family.
+        if "nemotron" in m: return "nemotron"
         if "qwen" in m: return "qwen"
         if "mistral" in m: return "mistral"
+        # A4 — llama version-aware buckets. llama-3.x is materially distinct
+        # from llama-4 (different architecture + post-training). The wider
+        # "meta" bucket stays as a fallback for unknown-version llama ids.
+        if "llama-3" in m or "llama3" in m: return "llama3"
         if "llama" in m or m.startswith("meta/"): return "meta"
-        if "gpt-oss" in m or m.startswith("openai/"): return "openai"
+        # A4 — gpt-oss (OpenAI's open-weights line) is distinct from
+        # closed-source GPT models. Keep them on separate buckets so a
+        # GPT-OSS judge over a GPT-OSS brain isn't accidentally allowed.
+        if "gpt-oss" in m: return "openai_oss"
+        if m.startswith("openai/") or "gpt-4" in m or "gpt-5" in m: return "openai"
         if "deepseek" in m: return "deepseek"
         if "kimi" in m or m.startswith("moonshot"): return "moonshot"
         if "minimax" in m: return "minimax"
-        if "nemotron" in m or m.startswith("nvidia/"): return "nvidia"
+        if m.startswith("nvidia/"): return "nvidia"
         return "unknown"
 
     # KI-080 — per-call timeout used in the sticky-primary path. Each elected
@@ -800,6 +887,47 @@ def _balanced_brain_chain(base: list[str], *, groq_first_probability: float = 0.
     return [groq_model, *rotated]
 
 
+def assert_family_coverage() -> dict[str, str]:
+    """A4 (2026-05-15) — Verify every model in every chain maps to a known
+    family (i.e. NOT 'unknown'). Returns a {model: family} dict on success;
+    raises RuntimeError listing any 'unknown'-mapped models on failure.
+
+    KI-175 — also verifies nemotron is the TAIL (last entry) of each brain
+    chain so the last-resort ordering invariant survives any chain edit.
+
+    Call from admin diagnostics or tests; not invoked on import to keep
+    cold-start cheap. Safe to run from a probe loop tick.
+    """
+    coverage: dict[str, str] = {}
+    unknown: list[str] = []
+    for chain in (BRAIN_CHAIN, FAST_BRAIN_CHAIN, JUDGE_CHAIN):
+        for m in chain:
+            fam = NimChainLLM._family_of(m)
+            coverage[m] = fam
+            if fam == "unknown":
+                unknown.append(m)
+    if unknown:
+        raise RuntimeError(
+            f"_family_of returned 'unknown' for: {unknown}. "
+            "Extend NimChainLLM._family_of so cross-family grading checks "
+            "have a stable bucket for every candidate."
+        )
+    # KI-175 tail-position invariant — nemotron MUST be the last entry of
+    # both brain chains (it's the last-resort fallback). Judge chain is
+    # exempt because Nemotron is a legitimate cross-family judge there.
+    for label, chain in (("BRAIN_CHAIN", BRAIN_CHAIN),
+                          ("FAST_BRAIN_CHAIN", FAST_BRAIN_CHAIN)):
+        nemo_idx = next(
+            (i for i, m in enumerate(chain) if "nemotron" in m.lower()), None
+        )
+        if nemo_idx is not None and nemo_idx != len(chain) - 1:
+            raise RuntimeError(
+                f"KI-175 violation: nemotron must be the LAST entry of {label} "
+                f"(found at index {nemo_idx}, chain length {len(chain)})."
+            )
+    return coverage
+
+
 def get_brain_llm() -> NimChainLLM:
     """Heavy brain — KI-080 sticky-primary election over BRAIN_CHAIN.
 

backend/providers/openrouter_llm.py

@@ -40,6 +40,57 @@ OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
 DEFAULT_MODEL = "openai/gpt-oss-120b"
 
 
+# A4 (2026-05-15) — OpenRouter free-pool helpers.
+#
+# `:free` suffix is OpenRouter's documented marker for zero-cost models.
+# We use this both to:
+#   (a) order the free pool deterministically (smallest-id-first as a
+#       stable, cheapest-first proxy — small models are cheaper to serve
+#       and complete faster); and
+#   (b) reject any non-`:free` model that accidentally lands in the free
+#       pool, so a paid model can't get silently invoked under a "free"
+#       call path and burn the user's prepaid balance.
+_FREE_SUFFIX = ":free"
+
+
+def is_free_model(model_id: str) -> bool:
+    """True if `model_id` is in OpenRouter's free pool (`:free` suffix).
+    Used by `enforce_free_pool` + the chat-time cost guard.
+    """
+    return bool(model_id) and model_id.endswith(_FREE_SUFFIX)
+
+
+def order_free_pool(models: list[str]) -> list[str]:
+    """A4 (2026-05-15) — Return `models` in a STABLE, deterministic order
+    suitable for OpenRouter's `models=[...]` server-side fallback list.
+
+    Sort key: (length-of-id ascending, id ascending). Shorter ids tend to
+    correlate with smaller / cheaper models on OpenRouter's catalogue
+    (e.g. `gemma-4-26b-a4b-it:free` < `gemma-4-31b-it:free` < ...).
+    Stable alphabetical secondary key removes the randomness that an
+    unsorted dict iteration could introduce across Python runs.
+
+    Inputs that contain non-free entries are NOT silently re-ordered —
+    use `enforce_free_pool` first if you need the cost guard.
+    """
+    return sorted(models, key=lambda m: (len(m), m))
+
+
+def enforce_free_pool(models: list[str]) -> list[str]:
+    """A4 (2026-05-15) — Cost guard: reject paid models in a free-pool call.
+
+    Raises ValueError listing any non-`:free` entries. Returns the
+    deterministically-ordered free pool on success.
+    """
+    paid = [m for m in models if not is_free_model(m)]
+    if paid:
+        raise ValueError(
+            f"OpenRouter free-pool call rejected: non-free models {paid}. "
+            "All entries must end in ':free'. See get_openrouter_llm() docs."
+        )
+    return order_free_pool(models)
+
+
 class OpenRouterLLM(LLMProvider):
     name = "openrouter"
 
@@ -69,6 +120,7 @@ class OpenRouterLLM(LLMProvider):
         max_tokens: int = 1024,
         response_format: Optional[dict] = None,
         models: Optional[list[str]] = None,
+        free_only: bool = False,
     ) -> LLMResult:
         """Send a chat completion to OpenRouter.
 
@@ -78,7 +130,26 @@ class OpenRouterLLM(LLMProvider):
         set as the primary `model` field (OpenRouter requires both for
         routing; if `models` is omitted the lone `model` field is used).
         Reference: https://openrouter.ai/docs/features/model-routing
+
+        A4 (2026-05-15) — `free_only=True` activates the cost guard:
+          - rejects any non-`:free` model in `models` (raises ValueError)
+          - reorders the survivors via `order_free_pool` for stable, smaller-
+            first preference. The single-model `self.model` is checked too
+            when `models` is omitted, so a paid default can't sneak in via
+            the lone-model path.
         """
+        # A4 cost guard — enforce BEFORE constructing the request body so
+        # a paid model never reaches the wire.
+        if free_only:
+            if models:
+                models = enforce_free_pool(list(models))
+            elif not is_free_model(self.model):
+                raise ValueError(
+                    f"OpenRouter free-pool call rejected: default model "
+                    f"{self.model!r} is not in the :free pool. Pass "
+                    f"`models=[...]` with :free suffix or unset free_only."
+                )
+
         primary_model = models[0] if models else self.model
         body: dict = {
             "model": primary_model,

backend/providers/tiered_brain_llm.py

@@ -72,7 +72,7 @@ class TieredBrainLLM(LLMProvider):
         self,
         role: str = "brain",
         gemini_model: str = "gemini-2.5-flash",
-        per_tier_timeout: float = 30.0,
+        per_tier_timeout: float = 15.0,
     ):
         if role not in ("brain", "fast_brain"):
             raise ValueError(f"role must be 'brain' or 'fast_brain', got {role!r}")

backend/retrieval_filters.py

@@ -0,0 +1,422 @@
+"""Retrieval-side filters + guards (A3 / A6 audit fixes).
+
+This module is a SIDECAR to `rag/retrieve.py` and `backend/orchestrator.py`.
+It is deliberately a separate file so concurrent edits to orchestrator.py
+don't conflict with the retrieval-correctness work.
+
+Public API:
+    apply_profile_filter(chunks, profile)       -> list[RetrievedChunk]
+        Drop chunks for policies the user is demographically ineligible for.
+    bypass_cosine_for_exact_match(chunks, query) -> list[RetrievedChunk] | None
+        If the query contains an IRDAI UIN or an exact policy name, return a
+        substring-matched chunk list (caller can use this instead of cosine).
+        Returns None if no exact-match signal in the query.
+    empty_retrieval_guard(chunks, intent)        -> dict | None
+        Return a structured "empty_retrieval" signal when filtered chunk count
+        is below the minimum for a recommendation intent.
+    enforce_citation_grounding(chunks)           -> list[RetrievedChunk]
+        Reject chunks missing policy_id / policy_name / chunk_offset.
+    dedup_by_policy(chunks)                      -> list[RetrievedChunk]
+        Within a top-K, keep highest-score chunk per policy_id.
+
+All functions are pure / side-effect-free; safe to call from the orchestrator
+or from rag/retrieve.py without import-cycle risk.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable, Optional
+
+# We avoid importing RetrievedChunk at module-import time to keep this file
+# import-cycle-safe. Instead we type-duck on attributes.
+
+# ---------------------------------------------------------------------------
+# Constants — keep tunables here so they're greppable from one place.
+# ---------------------------------------------------------------------------
+
+# Age tolerance for the profile pre-filter. The catalog's min_entry_age /
+# max_entry_age is the regulator-filed entry age, but real underwriters allow
+# a small grace band; we mirror that grace here so we don't accidentally
+# drop a perfectly fine policy because the user is one year off the edge.
+PROFILE_AGE_TOLERANCE = 2
+
+# A "senior-only" policy is one whose marketing/eligibility makes it
+# inappropriate for adults under 50. We detect this from the policy name
+# AND from the min_entry_age metadata (>=60 ⇒ senior-only).
+SENIOR_ONLY_NAME_RE = re.compile(
+    r"\b(senior|red\s*carpet|silver|elder|varisht|varistha|"
+    r"sixty\s*plus|60\s*plus|seniority|golden\s*years)\b",
+    flags=re.IGNORECASE,
+)
+
+# Adult-only / young-adult-only plans typically cap at 50 or 55 and have
+# no senior variant. If the user is >=60 these are inappropriate
+# (they need a senior variant of the SAME insurer/family instead).
+ADULT_ONLY_NAME_RE = re.compile(
+    r"\b(young\s*star|young\s*adult|millennial|gen\s*z|under\s*45|"
+    r"early\s*career|first\s*time)\b",
+    flags=re.IGNORECASE,
+)
+
+# Maternity-themed policies. If the profile has no female adult AND no
+# maternity goal, these are noise.
+MATERNITY_NAME_RE = re.compile(
+    r"\b(maternity|mother\s*&?\s*baby|mother\s*to\s*be|"
+    r"new\s*born|joy|stork|baby\s*shield|pregnancy)\b",
+    flags=re.IGNORECASE,
+)
+
+# Minimum chunk count to attempt a recommendation. Below this we ask for
+# one more clarifier instead of letting the brain hallucinate.
+MIN_CHUNKS_FOR_RECOMMENDATION = 3
+
+# Recommendation-style intents — the empty-retrieval guard fires only on these.
+# Other intents (faq, regulatory, smalltalk) tolerate sparse retrieval.
+_RECOMMENDATION_INTENTS = {
+    "recommend",
+    "recommendation",
+    "compare",
+    "comparison",
+    "suggest",
+    "shortlist",
+    "best_policy",
+    "pick_for_me",
+}
+
+# IRDAI UIN pattern. Real UINs look like "IRDA/HLT/HDFC/V.I/188/14-15"
+# or "IRDAI/HLT/HDFC/V.I/188/14-15" — we accept both.
+UIN_RE = re.compile(
+    r"\b(?:IRDAI?|UIN)[/:]\s*[A-Z0-9./\-]{6,}",
+    flags=re.IGNORECASE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _meta(chunk: Any) -> dict:
+    """Pull metadata off a chunk regardless of whether the caller hands us a
+    RetrievedChunk dataclass or a raw dict. RetrievedChunk stores fields as
+    top-level attributes; ingestion-side code sometimes passes a dict."""
+    if isinstance(chunk, dict):
+        return chunk
+    out = {}
+    for k in (
+        "policy_id", "policy_name", "insurer_slug", "doc_type",
+        "chunk_idx", "chunk_offset", "min_entry_age", "max_entry_age",
+        "score", "text",
+    ):
+        if hasattr(chunk, k):
+            out[k] = getattr(chunk, k)
+    return out
+
+
+def _profile_get(profile: Any, key: str, default=None):
+    """Profile may be a dataclass (needs_finder.Profile) OR a dict — accept either."""
+    if profile is None:
+        return default
+    if isinstance(profile, dict):
+        return profile.get(key, default)
+    return getattr(profile, key, default)
+
+
+def _profile_has_female_adult(profile: Any) -> bool:
+    """Heuristic: profile covers a female adult if dependents includes spouse
+    (the user might be the female adult, or spouse may be). We treat
+    'spouse' tokens as a positive signal and 'self+spouse', 'family' shapes
+    likewise. Conservative: return True when uncertain (better to keep
+    maternity chunks than to wrongly drop them)."""
+    dep = _profile_get(profile, "dependents") or ""
+    if not isinstance(dep, str):
+        return True
+    dep_lower = dep.lower()
+    if any(tok in dep_lower for tok in ("spouse", "wife", "family", "kids", "child")):
+        return True
+    # No spouse / no family signal AND explicit self-only → no female adult
+    if dep_lower in ("self", "self_only", "individual", "just_me"):
+        return False
+    return True  # default permissive
+
+
+def _profile_has_maternity_goal(profile: Any) -> bool:
+    goal = _profile_get(profile, "primary_goal") or ""
+    if not isinstance(goal, str):
+        return False
+    return "maternity" in goal.lower() or "pregnan" in goal.lower() or "baby" in goal.lower()
+
+
+# ---------------------------------------------------------------------------
+# (1) Profile-fit pre-filter (A3 / A6)
+# ---------------------------------------------------------------------------
+
+def apply_profile_filter(chunks: Iterable[Any], profile: Any) -> list[Any]:
+    """Drop chunks that are demographically inappropriate for this user.
+
+    Rules:
+      - min_entry_age > age + 2          → drop
+      - max_entry_age < age - 2          → drop
+      - senior-only plan AND age < 50    → drop (user is too young)
+      - adult-only plan AND age >= 60    → drop (user needs senior variant)
+      - maternity plan AND no female adult / no maternity goal → drop
+
+    Profile chunks (doc_type == 'profile') and regulatory chunks
+    (doc_type == 'regulatory' / 'review') are NEVER dropped here — those
+    aren't policies and the demographic rules don't apply.
+
+    Conservative on missing data: if a chunk doesn't expose min/max entry
+    age metadata, we DO NOT drop it on those rules (we still apply the
+    name-based senior/adult/maternity rules where the name pattern matches).
+    """
+    chunks_list = list(chunks)
+    if not chunks_list:
+        return chunks_list
+
+    age = _profile_get(profile, "age")
+    # If age unknown, only the maternity rule can fire — keep everything else.
+    has_age = isinstance(age, int)
+
+    has_female_adult = _profile_has_female_adult(profile)
+    maternity_goal = _profile_has_maternity_goal(profile)
+
+    kept: list[Any] = []
+    for ch in chunks_list:
+        m = _meta(ch)
+        doc_type = (m.get("doc_type") or "").lower()
+        # Never drop non-policy chunks via demographic filter
+        if doc_type in ("profile", "regulatory", "review"):
+            kept.append(ch)
+            continue
+
+        name = (m.get("policy_name") or "").strip()
+        min_age = m.get("min_entry_age")
+        max_age = m.get("max_entry_age")
+
+        # Numeric age-range gate
+        if has_age:
+            try:
+                if isinstance(min_age, (int, float)) and min_age > age + PROFILE_AGE_TOLERANCE:
+                    continue
+                if isinstance(max_age, (int, float)) and max_age < age - PROFILE_AGE_TOLERANCE:
+                    continue
+            except TypeError:
+                pass  # metadata corruption — fall through to name rules
+
+        # Senior-only inferred from name OR from min_entry_age >= 60
+        is_senior_only = bool(SENIOR_ONLY_NAME_RE.search(name)) or (
+            isinstance(min_age, (int, float)) and min_age >= 60
+        )
+        if is_senior_only and has_age and age < 50:
+            continue
+
+        # Adult-only inferred from name (no metadata signal exists for this).
+        # If user is 60+ AND policy looks adult-only AND has max_age < 60, drop.
+        is_adult_only_name = bool(ADULT_ONLY_NAME_RE.search(name))
+        if has_age and age >= 60 and is_adult_only_name:
+            continue
+        if has_age and age >= 60 and isinstance(max_age, (int, float)) and max_age < 60:
+            continue
+
+        # Maternity gate — only drop if BOTH conditions fail
+        if MATERNITY_NAME_RE.search(name) and not maternity_goal and not has_female_adult:
+            continue
+
+        kept.append(ch)
+
+    return kept
+
+
+# ---------------------------------------------------------------------------
+# (2) Hybrid retrieval — exact-match bypass on UIN or policy name
+# ---------------------------------------------------------------------------
+
+def _extract_uin(query: str) -> Optional[str]:
+    if not query:
+        return None
+    m = UIN_RE.search(query)
+    return m.group(0) if m else None
+
+
+def _extract_quoted_policy_name(query: str) -> Optional[str]:
+    """Pull a quoted policy name out of the query if present."""
+    if not query:
+        return None
+    # "..." or "..." or '...'
+    for pat in (r'"([^"]{6,})"', r"“([^”]{6,})”", r"'([^']{6,})'"):
+        m = re.search(pat, query)
+        if m:
+            return m.group(1).strip()
+    return None
+
+
+def bypass_cosine_for_exact_match(
+    chunks: Iterable[Any],
+    query: str,
+) -> Optional[list[Any]]:
+    """If the query contains an exact UIN or an exact (quoted) policy name,
+    return a substring-matched subset of `chunks`. This is the lexical
+    "BM25-style" fallback — when the user clearly knows what they want, we
+    should not let cosine similarity reorder away from their literal target.
+
+    Returns None when no exact-match signal is present (caller falls back
+    to normal cosine results). Returns an empty list if a signal was present
+    but no chunk matched — that's a useful "we know what you mean, but our
+    catalog doesn't have it" signal for the orchestrator's empty-retrieval
+    guard.
+    """
+    chunks_list = list(chunks)
+    uin = _extract_uin(query)
+    quoted = _extract_quoted_policy_name(query)
+    if not uin and not quoted:
+        return None
+
+    needles: list[str] = []
+    if uin:
+        needles.append(uin.lower())
+    if quoted:
+        needles.append(quoted.lower())
+
+    matched: list[Any] = []
+    for ch in chunks_list:
+        m = _meta(ch)
+        haystack = " ".join(
+            str(m.get(k, "")) for k in ("policy_id", "policy_name", "insurer_slug", "text")
+        ).lower()
+        if any(n in haystack for n in needles):
+            matched.append(ch)
+
+    return matched
+
+
+# ---------------------------------------------------------------------------
+# (3) Empty-retrieval guard
+# ---------------------------------------------------------------------------
+
+def empty_retrieval_guard(
+    chunks: Iterable[Any],
+    intent: Optional[str] = None,
+    min_chunks: int = MIN_CHUNKS_FOR_RECOMMENDATION,
+) -> Optional[dict]:
+    """Return a structured signal if a recommendation intent has too few
+    chunks to ground an answer. The orchestrator should surface this to the
+    user as a clarifier question instead of calling the brain.
+
+    Returns None when the retrieval is healthy (or the intent doesn't need
+    much grounding).
+    """
+    chunks_list = list(chunks)
+    intent_norm = (intent or "").lower().strip()
+    if intent_norm and intent_norm not in _RECOMMENDATION_INTENTS:
+        return None  # FAQ / regulatory / smalltalk intents are fine with sparse retrieval
+
+    if len(chunks_list) >= min_chunks:
+        return None
+
+    return {
+        "reason": "empty_retrieval",
+        "fallback": "Ask 1 more clarifier",
+        "chunk_count": len(chunks_list),
+        "min_required": min_chunks,
+    }
+
+
+# ---------------------------------------------------------------------------
+# (4) Citation grounding — require policy_id, policy_name, chunk_offset
+# ---------------------------------------------------------------------------
+
+def enforce_citation_grounding(chunks: Iterable[Any]) -> list[Any]:
+    """Drop chunks missing any of the three citation-critical fields.
+
+    The "chunk_offset" requirement maps onto either `chunk_offset` (newer
+    ingestions) or the existing `chunk_idx` (legacy + current). At least
+    one must be a non-negative int.
+    """
+    kept: list[Any] = []
+    for ch in chunks:
+        m = _meta(ch)
+        pid = m.get("policy_id")
+        pname = m.get("policy_name")
+        # accept either field name; chunk_idx is the existing schema in rag/retrieve.py
+        offset = m.get("chunk_offset")
+        if offset is None:
+            offset = m.get("chunk_idx")
+
+        if not pid or not isinstance(pid, str):
+            continue
+        if not pname or not isinstance(pname, str):
+            continue
+        if not isinstance(offset, int) or offset < 0:
+            continue
+        kept.append(ch)
+    return kept
+
+
+# ---------------------------------------------------------------------------
+# (5) Dedup by policy_id — keep highest-score chunk per policy
+# ---------------------------------------------------------------------------
+
+def dedup_by_policy(chunks: Iterable[Any]) -> list[Any]:
+    """Within top-K results, collapse to one chunk per policy_id, keeping
+    the highest-scoring chunk. Preserves the original ordering of the kept
+    chunks (i.e. ranks chunks by their best-in-policy score)."""
+    best: dict[str, Any] = {}
+    order: list[str] = []
+    for ch in chunks:
+        m = _meta(ch)
+        pid = m.get("policy_id") or ""
+        score = m.get("score")
+        if score is None:
+            # try attribute path
+            score = getattr(ch, "score", 0.0)
+        try:
+            score_f = float(score)
+        except (TypeError, ValueError):
+            score_f = 0.0
+
+        if pid not in best:
+            best[pid] = (ch, score_f)
+            order.append(pid)
+            continue
+        prev_chunk, prev_score = best[pid]
+        if score_f > prev_score:
+            best[pid] = (ch, score_f)
+
+    return [best[pid][0] for pid in order]
+
+
+# ---------------------------------------------------------------------------
+# Convenience — compose the standard retrieval-side pipeline.
+# ---------------------------------------------------------------------------
+
+def filter_pipeline(
+    chunks: Iterable[Any],
+    profile: Any = None,
+    query: str = "",
+    intent: Optional[str] = None,
+) -> tuple[list[Any], Optional[dict]]:
+    """Run the standard A3/A6 retrieval-side pipeline:
+
+        1. Citation grounding   (reject malformed chunks)
+        2. Profile pre-filter   (drop demographically inappropriate policies)
+        3. Exact-match bypass   (if query has a UIN / quoted name, swap in)
+        4. Dedup by policy_id
+        5. Empty-retrieval guard
+
+    Returns (filtered_chunks, guard_signal_or_None). When guard_signal is
+    set, the caller should NOT pass `filtered_chunks` to the brain — they
+    should surface the clarifier instead.
+    """
+    grounded = enforce_citation_grounding(chunks)
+    fitted = apply_profile_filter(grounded, profile)
+
+    exact = bypass_cosine_for_exact_match(grounded, query)
+    if exact is not None and exact:
+        # Exact match wins over cosine when the user clearly named a target.
+        # Still apply profile filter to exact matches (the user might ask
+        # about a senior plan when they're 25 — show it, but log it).
+        fitted = exact
+
+    deduped = dedup_by_policy(fitted)
+    guard = empty_retrieval_guard(deduped, intent=intent)
+    return deduped, guard

backend/sales_brain_normalizer.py

@@ -264,6 +264,12 @@ _NAME_BAD_FIRST_WORDS = {
     "don", "dont", "don't",
     "i", "we", "my", "this", "that", "the",
     "first", "still", "yet",
+    # KI-221 — additional status / metadata words the LLM occasionally emits
+    # as a "name". These were observed live (e.g. "last", "surname", "hi")
+    # routing through as candidate names.
+    "last", "first", "sur", "lastname", "firstname", "surname", "name",
+    "hi", "hey", "ok", "hello", "okay", "yo", "hola",
+    "user", "person", "someone", "me", "myself",
 }
 
 
@@ -296,12 +302,21 @@ def _normalize_name(value: Any) -> Optional[str]:
             break
     if not s:
         return None
+    # KI-221 — minimum length floor. Single-char "names" (e.g. "a", "x")
+    # are never real names and were leaking through the alpha-density check.
+    if len(s) < 2:
+        return None
     first = s.split()[0].lower().strip(".,!?")
     if first in _NAME_BAD_FIRST_WORDS:
         return None
     alpha = sum(1 for c in s if c.isalpha())
     if alpha < 2 or alpha / max(1, len(s)) < 0.5:
         return None
+    # KI-221 — every real name has at least one vowel. Rejects scraps like
+    # "Mr", "Dr", "St" (which slipped past the polite-prefix stripper when
+    # not followed by a space, e.g. the LLM emitting just "Dr").
+    if not any(c in "aeiouy" for c in s.lower()):
+        return None
     # Capitalize if all-lower (LLM convention — names should be Title Case).
     if not any(c.isupper() for c in s):
         s = " ".join(w.capitalize() for w in s.split())
@@ -387,7 +402,25 @@ def _normalize_dependents(value: Any, schema: dict) -> Optional[str]:
         return "self+kids"
     if has_parents:
         return "self+parents"
-    if s in ("self", "me", "just me", "only me", "myself", "only self"):
+    # KI-222 — expand the "self" alias set. Live captures showed users
+    # answering "single", "unmarried", "no dependents", "just myself" etc.,
+    # which previously fell through to None and got silently dropped — the
+    # bot then re-asked the same slot on the next turn.
+    _SELF_ALIASES = (
+        "self", "me", "just me", "only me", "myself", "only self",
+        "single", "unmarried", "alone", "bachelor", "no dependents",
+        "just myself", "nobody else", "no one else", "nobody",
+        "myself only", "by myself", "solo",
+    )
+    if s in _SELF_ALIASES:
+        return "self"
+    # Substring fall-through for the same intents when wrapped in extra prose
+    # (e.g. "i'm single right now", "just myself for now").
+    if any(alias in s for alias in (
+        "single", "unmarried", "no dependents", "just myself",
+        "by myself", "nobody else", "no one else", "myself only",
+        "bachelor", "solo",
+    )):
         return "self"
     return None
 
@@ -399,14 +432,54 @@ def _normalize_income_band(value: Any, schema: dict) -> Optional[str]:
         s = value.strip()
         if s in schema["values"]:
             return s
+        # KI-225 — natural phrasing pre-pass (covers patterns the centralised
+        # `_parse_income_band` doesn't handle: "under 5 lakh", "between 5 and
+        # 10", "25 lakh plus", etc.). Lowercase + strip light punctuation, then
+        # match phrase patterns BEFORE delegating to the legacy parser.
+        s_norm = re.sub(r"[,\?\.]+$", "", s.lower()).strip()
+        s_norm = re.sub(r"\s+", " ", s_norm)
+        # under_5L family
+        if re.search(
+            r"\b(?:under|less\s+than|below|<)\s*(?:rs\.?\s*)?5\s*(?:l|lakh|lakhs|lac)\b",
+            s_norm,
+        ):
+            return "under_5L"
+        # 25L+ family — check BEFORE 10-25 so "above 25" doesn't match the
+        # 10-25 patterns by accident.
+        if re.search(
+            r"\b(?:25\s*l?\s*\+|25\s*(?:l|lakh|lakhs|lac)\s*plus|"
+            r"(?:above|over|more\s+than|>)\s*(?:rs\.?\s*)?25\s*(?:l|lakh|lakhs|lac)?|"
+            r"25\s*\+\s*(?:l|lakh|lakhs|lac))\b",
+            s_norm,
+        ):
+            return "25L+"
+        # 10L-25L family
+        if re.search(
+            r"\b(?:10\s*[-–to]+\s*25\s*(?:l|lakh|lakhs|lac)?|"
+            r"between\s+10\s+and\s+25(?:\s*(?:l|lakh|lakhs|lac))?)\b",
+            s_norm,
+        ):
+            return "10L-25L"
+        # 5L-10L family
+        if re.search(
+            r"\b(?:5\s*[-–to]+\s*10\s*(?:l|lakh|lakhs|lac)?|"
+            r"between\s+5\s+and\s+10(?:\s*(?:l|lakh|lakhs|lac))?)\b",
+            s_norm,
+        ):
+            return "5L-10L"
         # KI-149 — let the centralised parser handle free text.
         parsed = _parse_income_band(s)
         if parsed in schema["values"]:
             return parsed
         return None
     if isinstance(value, (int, float)):
-        # Bare number → rupees → bucket
+        # Bare number → rupees → bucket. KI-223 — require ≥1 lakh floor; bare
+        # numbers below that are almost always age / dependents-count noise
+        # (e.g. "I'm 29 years old" → LLM extracted 29 as "income"). Reject
+        # rather than mis-bucket as under_5L.
         amt = int(value)
+        if amt < 100_000:
+            return None
         if amt < 500_000:
             return "under_5L"
         if amt < 1_000_000:
@@ -432,6 +505,20 @@ def _normalize_existing_cover(value: Any, schema: dict) -> Optional[int]:
         s = value.strip().lower()
         if not s:
             return None
+        # KI-225 — explicit no-cover phrasings (covers "no insurance",
+        # "no policy", "no existing", "first time so nothing", etc.). These
+        # mostly route through the original \b(no|none|...)\b pattern below
+        # but the more-specific multi-word phrasings need a dedicated pass so
+        # "no insurance currently" doesn't accidentally fall through to the
+        # digit fallback (which would extract '0' from no digits → None).
+        _no_cover_phrases = (
+            "no insurance", "no policy", "no policies", "no existing",
+            "no existing cover", "no existing policy", "no cover",
+            "first time so nothing", "nothing currently", "nothing right now",
+            "no pre-existing", "don't have any", "dont have any",
+        )
+        if any(p in s for p in _no_cover_phrases):
+            return 0
         # Negative answers → 0
         if re.search(
             r"\b(no|none|nothing|zero|nope|nah|haven'?t|don'?t|never|"
@@ -439,7 +526,22 @@ def _normalize_existing_cover(value: Any, schema: dict) -> Optional[int]:
             s,
         ):
             return 0
-        amt = _parse_inr_amount(s)
+        # KI-225 — employer / corporate cover phrasings. The amount IS in the
+        # string; let `_parse_inr_amount` extract it (₹5L / 5 lakh / etc.).
+        # Phrases like "5L from work" / "5 lakh employer" don't trip the
+        # negative-answer regex above (they don't contain a no/none token).
+        # Spelled-out small numbers ("five lakh", "ten lakh") aren't covered
+        # by the centralised parser — do a light word-to-digit pre-pass here.
+        _SPELLED_DIGITS = {
+            "one": "1", "two": "2", "three": "3", "four": "4", "five": "5",
+            "six": "6", "seven": "7", "eight": "8", "nine": "9", "ten": "10",
+            "fifteen": "15", "twenty": "20", "twenty-five": "25", "fifty": "50",
+        }
+        _s_for_parse = s
+        for _word, _digit in _SPELLED_DIGITS.items():
+            # word-boundary substitution so "tense" doesn't become "10se"
+            _s_for_parse = re.sub(rf"\b{re.escape(_word)}\b", _digit, _s_for_parse)
+        amt = _parse_inr_amount(_s_for_parse)
         if amt is None:
             # Bare digit fallback (very small values OK here — user might
             # have ₹500 unused; still coerce within bounds).
@@ -479,15 +581,38 @@ def _normalize_primary_goal(value: Any, schema: dict) -> Optional[str]:
     # Direct hit on alias or canonical
     if s in _GOAL_ALIASES:
         return _GOAL_ALIASES[s]
-    # Keyword fall-through
-    if any(k in s for k in ("first policy", "first one", "first time", "first buy", "new policy", "buying my first")):
-        return "first_buy"
-    if any(k in s for k in ("upgrade", "upgrading", "better cover", "more cover", "increase cover")):
-        return "upgrade"
-    if any(k in s for k in ("compare", "comparison", " vs ", " vs.", "versus")):
-        return "compare_specific"
-    if any(k in s for k in (" tax ", "80d", "deduction", "tax planning", "tax saving")):
+    # KI-225 — natural phrasing keyword fall-through. Order matters: check the
+    # more-specific phrases (tax / compare) BEFORE the broader first_buy / upgrade
+    # buckets so e.g. "compare specific policies for tax savings" lands in
+    # tax_planning, not compare_specific, when both keyword sets match.
+    # tax_planning — most specific (section refs + explicit tax keywords)
+    if any(k in s for k in (
+        "tax planning", "for tax", "section 80d", "80d", "tax savings",
+        "tax saving", "tax benefit", "tax deduction", " tax ", "deduction",
+    )):
         return "tax_planning"
+    # compare_specific — explicit comparison phrasing
+    if any(k in s for k in (
+        "compare specific", "comparing", "compare", "comparison",
+        "looking at specific policies", "looking at specific polic",
+        " vs ", " vs.", "versus", "between policy", "between policies",
+    )):
+        return "compare_specific"
+    # upgrade — has existing cover, wants better
+    if any(k in s for k in (
+        "upgrade", "upgrading", "want to upgrade", "improve my existing",
+        "better than what i have", "replace my current", "replace my existing",
+        "better cover", "more cover", "increase cover",
+    )):
+        return "upgrade"
+    # first_buy — broadest bucket, check last
+    if any(k in s for k in (
+        "first time", "first policy", "first time buyer", "first one",
+        "first buy", "new policy", "buying my first", "buy my first",
+        "looking for my first", "looking for first",
+        "starting out", "new to insurance",
+    )):
+        return "first_buy"
     return None
 
 
@@ -554,6 +679,11 @@ def _normalize_budget_band(value: Any, schema: dict) -> Optional[str]:
         return None
     if isinstance(value, (int, float)):
         amt = int(value)
+        # KI-223 — require ≥₹5,000 floor; bare numbers below that are almost
+        # always age / dependents-count noise (e.g. age 29 leaking into the
+        # budget slot). Reject rather than mis-bucket as under_15k.
+        if amt < 5_000:
+            return None
         if amt < 15_000:
             return "under_15k"
         if amt < 30_000:
@@ -577,12 +707,35 @@ _NO_PED_PATTERNS = (
 )
 
 _COND_KEYWORDS: dict[str, tuple] = {
-    "diabetes":     ("diabetes", "diabetic", "sugar"),
-    "hypertension": ("hypertension", "blood pressure", "high bp"),
-    "thyroid":      ("thyroid", "hypothyroid", "hyperthyroid"),
-    "asthma":       ("asthma",),
-    "heart":        ("heart problem", "heart disease", "cardiac"),
-    "cancer":       ("cancer", "tumor", "tumour"),
+    # KI-225 — alias coverage expanded per spec. Lay-terms ("sugar", "BP",
+    # "type 2 diabetes", "blood sugar", "respiratory") + clinical-adjacent
+    # phrasings ("cardiac", "heart problem", "tumor") all map onto the same
+    # 6 canonical buckets the downstream sales brain understands.
+    "diabetes":     (
+        "diabetes", "diabetic", "sugar", "blood sugar",
+        "diabetes type 1", "diabetes type 2", "type 1 diabetes",
+        "type 2 diabetes", "type-1 diabetes", "type-2 diabetes",
+    ),
+    "hypertension": (
+        "hypertension", "blood pressure", "high blood pressure",
+        "high bp", "bp issue", "bp problem",
+    ),
+    "thyroid":      (
+        "thyroid", "hypothyroid", "hyperthyroid",
+        "thyroid problem", "thyroid issue", "thyroid disorder",
+    ),
+    "asthma":       (
+        "asthma", "asthmatic", "respiratory", "respiratory issue",
+        "respiratory problem",
+    ),
+    "heart":        (
+        "heart problem", "heart disease", "heart issue", "heart condition",
+        "cardiac", "cardiac issue", "cardiac problem",
+    ),
+    "cancer":       (
+        "cancer", "tumor", "tumour", "cancer history", "had cancer",
+        "cancer survivor",
+    ),
 }
 # "bp" as a free-standing token (case-insensitive word-boundary). Kept
 # separate from `_COND_KEYWORDS` so it doesn't collide with substrings
@@ -609,12 +762,27 @@ def _normalize_health_conditions(value: Any) -> Optional[list]:
             if s in seen:
                 continue
             seen.add(s)
+            # Skip explicit "no" markers if they leaked into a list shape.
+            if s in ("no", "none", "nothing", "nil", "negative"):
+                continue
             # Map keyword hits to canonical names
             mapped = None
             for canon, kws in _COND_KEYWORDS.items():
                 if s == canon or any(k.strip() == s for k in kws):
                     mapped = canon
                     break
+            # KI-225 — also run the word-boundary BP regex so list items like
+            # ["BP"] / ["high BP"] map to "hypertension" (the kw tuple uses
+            # multi-word strings, none of which exact-match the bare token).
+            if mapped is None and _BP_REGEX.search(s):
+                mapped = "hypertension"
+            # Substring fallback for "type 2 diabetes" style values where the
+            # full string doesn't exact-match a kw but contains one.
+            if mapped is None:
+                for canon, kws in _COND_KEYWORDS.items():
+                    if any(k in s for k in kws):
+                        mapped = canon
+                        break
             cleaned.append(mapped if mapped else s)
         # Dedup again after canonicalisation
         return list(dict.fromkeys(cleaned))

backend/session_state.py

@@ -61,6 +61,12 @@ class SessionState:
     #     "staged_at": <epoch-seconds>,
     #   }
     pending_profile_recall: Optional[Dict[str, Any]] = None
+    # KI-224 — most-recent recommendation policy_ids the brain cited on the
+    # last user-visible recommendation/comparison turn. Populated by the
+    # orchestrator after a clean closer reply. Lets the NEXT turn route
+    # follow-ups like "tell me more about #2" without re-retrieving from
+    # scratch. Empty list = no active shortlist on this session.
+    last_recommendation_ids: list = field(default_factory=list)
 
     def _flush(self) -> None:
         """No-op since KI-118 (2026-05-15). Disk persistence was removed; the

backend/single_brain.py

@@ -0,0 +1,649 @@
+"""Single-brain conversation handler — Path B.
+
+One Gemini Flash call per turn (with native function-calling) replaces
+the previous sales_brain + qa_brain split. The LLM decides on each
+iteration whether to:
+  - call `save_profile_field` to persist captured slots,
+  - call `retrieve_policies` to pull policy chunks from Chroma,
+  - call `mark_recommendation` to flag the policies just pitched,
+  - or emit a final text reply.
+
+The loop iterates up to `MAX_ITERATIONS` (default 5) so the LLM can chain
+multiple tool calls in a single user turn before responding. Beyond that
+cap we synthesise a defensive reply and return.
+
+Wire-up:  /api/chat → main.py.chat() → if USE_SINGLE_BRAIN: single_brain.handle_turn(...)
+On any SingleBrainError, the API caller is expected to fall through to the
+legacy `orchestrator.handle_turn` so the user always gets a reply.
+
+We call the Gemini REST API directly (httpx, like google_gemini_llm.py)
+rather than using the `google.generativeai` SDK so we don't need to pin
+an extra dependency. The function-calling DSL is well-documented at
+https://ai.google.dev/api/generate-content#tools.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import httpx
+
+from backend import brain_tools
+
+_log = logging.getLogger(__name__)
+
+
+# ---------- constants -------------------------------------------------------
+
+# Model resolution: prefer `SINGLE_BRAIN_MODEL`, else copy the same default
+# `google_gemini_llm.py` uses (DEFAULT_MODEL = "gemini-2.5-flash-lite"). We
+# import lazily inside _resolve_model so importing this module does not
+# require the provider to load (or its GOOGLE_API_KEY env var to be set).
+_FALLBACK_MODEL = "gemini-2.5-flash-lite"
+
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models"
+
+# Per-call timeout (matches the legacy provider default of 25s).
+PER_CALL_TIMEOUT_SEC = 25.0
+
+# Max iterations of the tool-call loop. Prevents runaway tool-call cycles
+# where the LLM keeps calling save_profile_field on the same value.
+MAX_ITERATIONS = 5
+
+
+SYSTEM_PROMPT = """You are an Indian health-insurance advisor speaking with a customer.
+
+YOUR JOB:
+1. Have a natural conversation to learn the customer's profile.
+2. Once you have ALL required slots, call retrieve_policies, then recommend 2-4 options with policy citations.
+3. Help the customer choose one. Cite the UIN / policy_id for every claim about features, sums insured, or premiums.
+
+REQUIRED before recommending: name, age, dependents, location_tier, income_band, primary_goal, health_conditions.
+
+TOOL USE RULES:
+- Call save_profile_field every time you learn a new field. Don't keep captures only in your head.
+- If the user says multiple facts in one turn ("Hi I'm Rohit, 29, Mumbai, first policy"), call save_profile_field once per field in that turn.
+- BEFORE the final recommendation, briefly summarise what you understood and ASK the user to confirm.
+- After confirmation, call retrieve_policies, then respond with recommendations citing each policy's id / UIN.
+- After the recommendation, the user may ask follow-ups. For "tell me about #2", call retrieve_policies(query, policy_filter_ids=[the policy_id]) to narrow.
+- Call mark_recommendation with the policy_ids whenever you put a ranked shortlist in your reply.
+
+GROUND RULES:
+- NEVER invent policies, UINs, premiums, or sums insured. Only cite what retrieve_policies returns.
+- If retrieve_policies returns zero chunks, do NOT fabricate a recommendation — ask the user a clarifying question instead.
+- Be concise: 2-3 sentence turns. No emoji unless the user used one first.
+- Indian context: use lakh / crore, ₹, IRDAI, Section 80D. Don't say "dollars" or "$".
+- Returning users may have a pre-populated profile — greet them by name, summarise what you remember, and ask them to confirm or update before recommending.
+"""
+
+
+# ---------- exceptions ------------------------------------------------------
+
+
+class SingleBrainError(Exception):
+    """Wraps any unrecoverable Gemini / single-brain error so the api.py
+    caller can fall through to the legacy orchestrator handler."""
+
+
+# ---------- TurnResult — mirrors orchestrator.TurnResult --------------------
+
+
+@dataclass
+class TurnResult:
+    """Same shape as `orchestrator.TurnResult`. Kept local so single_brain
+    does not import the orchestrator and trip a circular dependency."""
+
+    reply_text: str
+    citations: list[dict]
+    retrieved_chunk_ids: list[str]
+    brain_used: str
+    intent: str
+    language: str
+    latency_ms: int
+    raw_reply: str
+    faithfulness_passed: bool = True
+    faithfulness_reasons: list[str] = field(default_factory=list)
+    blocked: bool = False
+    profile_updates: dict = field(default_factory=dict)
+    followup_policy_id: Optional[str] = None
+
+
+# ---------- function-calling DSL (Gemini JSON schema) -----------------------
+
+# Gemini "tools" are FunctionDeclarations. The schema is JSON-Schema-flavoured
+# (subset, see https://ai.google.dev/api/caching#Schema). Parameters MUST use
+# "OBJECT"/"STRING"/"INTEGER"/"ARRAY" (uppercase) — Google does NOT accept the
+# lowercase JSON Schema form here.
+
+TOOL_SCHEMAS: list[dict] = [
+    {
+        "name": "save_profile_field",
+        "description": (
+            "Persist a captured profile field on the live session. Call once "
+            "per field every time the user reveals something new (name, age, "
+            "dependents, location_tier, income_band, primary_goal, "
+            "health_conditions, existing_cover_inr, budget_band, gender)."
+        ),
+        "parameters": {
+            "type": "OBJECT",
+            "properties": {
+                "field": {
+                    "type": "STRING",
+                    "description": (
+                        "Field name. One of: name, age, dependents, "
+                        "location_tier, income_band, primary_goal, "
+                        "health_conditions, existing_cover_inr, budget_band, "
+                        "gender."
+                    ),
+                },
+                "value": {
+                    "type": "STRING",
+                    "description": (
+                        "Value as a string. Numbers (age, existing_cover_inr) "
+                        "may be sent as a digit string; health_conditions may "
+                        "be a comma-joined string of conditions."
+                    ),
+                },
+            },
+            "required": ["field", "value"],
+        },
+    },
+    {
+        "name": "retrieve_policies",
+        "description": (
+            "Search the indexed Indian health-insurance policy corpus and "
+            "return the top-k most relevant policy chunks. Use this BEFORE "
+            "recommending or quoting any policy fact."
+        ),
+        "parameters": {
+            "type": "OBJECT",
+            "properties": {
+                "query": {
+                    "type": "STRING",
+                    "description": (
+                        "Natural-language search query, e.g. 'family floater "
+                        "₹10L Mumbai metro tier1 diabetes'."
+                    ),
+                },
+                "top_k": {
+                    "type": "INTEGER",
+                    "description": "Number of chunks to return. Default 8.",
+                },
+                "policy_filter_ids": {
+                    "type": "ARRAY",
+                    "items": {"type": "STRING"},
+                    "description": (
+                        "Optional list of policy_ids to restrict retrieval to "
+                        "(use for 'tell me more about #2' style follow-ups)."
+                    ),
+                },
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "mark_recommendation",
+        "description": (
+            "Record the policies you have just recommended so future turns "
+            "can resolve follow-up references like 'tell me about #2'. Call "
+            "this on the SAME turn you produce the ranked shortlist."
+        ),
+        "parameters": {
+            "type": "OBJECT",
+            "properties": {
+                "policy_ids": {
+                    "type": "ARRAY",
+                    "items": {"type": "STRING"},
+                    "description": "Ordered list of policy_ids in your reply.",
+                },
+                "is_final": {
+                    "type": "BOOLEAN",
+                    "description": (
+                        "True when this is the final closer (user picked / "
+                        "confirmed). Optional, defaults to false."
+                    ),
+                },
+            },
+            "required": ["policy_ids"],
+        },
+    },
+]
+
+
+# ---------- helpers ---------------------------------------------------------
+
+
+def _resolve_model() -> str:
+    """Read the Gemini model id. Env override wins; otherwise mirror the
+    google_gemini_llm.py default. Import is lazy so module load does not
+    touch the provider (which itself fails noisily on missing env vars)."""
+    override = os.environ.get("SINGLE_BRAIN_MODEL", "").strip()
+    if override:
+        return override
+    try:
+        from backend.providers.google_gemini_llm import DEFAULT_MODEL as _DM
+
+        return _DM or _FALLBACK_MODEL
+    except Exception:  # noqa: BLE001
+        return _FALLBACK_MODEL
+
+
+def _profile_to_snapshot(profile) -> dict:
+    """Compact JSON-safe dict of all currently-known profile slots — for
+    the system prompt so the LLM doesn't keep re-asking the user for
+    fields it already has access to.
+    """
+    snap: dict[str, Any] = {}
+    for fld in (
+        "name", "age", "dependents", "location_tier", "income_band",
+        "primary_goal", "health_conditions", "existing_cover_inr",
+        "budget_band",
+    ):
+        try:
+            v = getattr(profile, fld, None)
+        except Exception:
+            v = None
+        if v not in (None, "", []):
+            snap[fld] = v
+    return snap
+
+
+def _build_contents(
+    chat_history: Optional[list[dict]],
+    user_text: str,
+) -> list[dict]:
+    """Translate the orchestrator-style chat_history ({role, content})
+    plus the current user_text into Gemini's `contents` payload.
+
+    Gemini wants alternating user/model turns with `parts[].text`.
+    `assistant` → `model`; everything else → `user`.
+    """
+    out: list[dict] = []
+    for msg in chat_history or []:
+        role = (msg.get("role") or "user").lower()
+        content = (msg.get("content") or "").strip()
+        if not content:
+            continue
+        gem_role = "model" if role in ("assistant", "model", "bot") else "user"
+        out.append({"role": gem_role, "parts": [{"text": content}]})
+    out.append({"role": "user", "parts": [{"text": user_text}]})
+    return out
+
+
+def _system_instruction(profile) -> dict:
+    """Bake the profile snapshot into the system prompt so each turn the
+    LLM knows what's already captured. Returned in Gemini's expected
+    `systemInstruction` shape."""
+    snapshot = _profile_to_snapshot(profile)
+    extra = ""
+    if snapshot:
+        extra = (
+            "\n\nKNOWN PROFILE (already captured this session; do NOT re-ask):\n"
+            + json.dumps(snapshot, ensure_ascii=False, sort_keys=True)
+        )
+    text = SYSTEM_PROMPT + extra
+    return {"parts": [{"text": text}]}
+
+
+def _detect_language(user_text: str) -> str:
+    """Mirror orchestrator.detect_language at a coarse level so the
+    TurnResult.language field stays useful for logging. Devanagari /
+    Hinglish → 'indic', else 'en'."""
+    if not user_text:
+        return "en"
+    for ch in user_text:
+        # Devanagari range
+        if "ऀ" <= ch <= "ॿ":
+            return "indic"
+    return "en"
+
+
+def _classify_intent(user_text: str, tool_calls_made: list[str]) -> str:
+    """Best-effort intent label for logging only. Single-brain doesn't
+    route on intent — but the legacy `TurnResult.intent` field is logged
+    by main.py and emitted to the frontend."""
+    if "retrieve_policies" in tool_calls_made and "mark_recommendation" in tool_calls_made:
+        return "recommendation"
+    if "retrieve_policies" in tool_calls_made:
+        return "qa"
+    if "save_profile_field" in tool_calls_made:
+        return "fact_find"
+    return "qa"
+
+
+# ---------- Gemini round-trip ----------------------------------------------
+
+
+async def _gemini_call(
+    api_key: str,
+    model: str,
+    system_instruction: dict,
+    contents: list[dict],
+    tools: list[dict],
+    timeout_sec: float,
+) -> dict:
+    """Single non-streaming Gemini generateContent call. Returns the raw
+    JSON payload. Raises SingleBrainError on any 4xx/5xx/transport error.
+    """
+    url = f"{GEMINI_BASE_URL}/{model}:generateContent?key={api_key}"
+    body: dict = {
+        "systemInstruction": system_instruction,
+        "contents": contents,
+        "tools": [{"functionDeclarations": tools}],
+        "toolConfig": {"functionCallingConfig": {"mode": "AUTO"}},
+        "generationConfig": {
+            "temperature": 0.4,
+            "maxOutputTokens": 1024,
+        },
+    }
+    headers = {"Content-Type": "application/json"}
+    client_timeout = httpx.Timeout(
+        connect=2.0,
+        read=max(2.0, timeout_sec - 2.0),
+        write=2.0,
+        pool=2.0,
+    )
+
+    async with httpx.AsyncClient(timeout=client_timeout) as client:
+        try:
+            resp = await client.post(url, headers=headers, json=body)
+        except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+            raise
+        except httpx.TimeoutException as e:
+            raise SingleBrainError(
+                f"Gemini timeout after {timeout_sec:.1f}s (model={model})"
+            ) from e
+        except httpx.HTTPError as e:
+            raise SingleBrainError(
+                f"Gemini transport error ({type(e).__name__}): {str(e)[:200]}"
+            ) from e
+
+    if resp.status_code >= 400:
+        detail = ""
+        try:
+            detail = resp.text[:500]
+        except Exception:
+            pass
+        raise SingleBrainError(
+            f"Gemini HTTP {resp.status_code}: {detail}"
+        )
+
+    try:
+        return resp.json()
+    except Exception as e:  # noqa: BLE001
+        raise SingleBrainError(f"Gemini malformed JSON: {e}") from e
+
+
+def _extract_parts(payload: dict) -> list[dict]:
+    """Pull the `parts` list out of the first candidate. Empty list on
+    any missing-key path so the caller decides what to do."""
+    try:
+        candidates = payload.get("candidates") or []
+        if not candidates:
+            return []
+        content = candidates[0].get("content") or {}
+        parts = content.get("parts") or []
+        if isinstance(parts, list):
+            return parts
+        return []
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def _parts_text(parts: list[dict]) -> str:
+    """Concatenate every text part. Empty string when none present."""
+    return "".join(
+        p.get("text", "")
+        for p in parts
+        if isinstance(p, dict) and "text" in p
+    )
+
+
+def _parts_function_calls(parts: list[dict]) -> list[dict]:
+    """Pull every functionCall block out of parts. Each entry is
+    {"name": "...", "args": {...}}."""
+    out: list[dict] = []
+    for p in parts:
+        if not isinstance(p, dict):
+            continue
+        fc = p.get("functionCall")
+        if isinstance(fc, dict) and fc.get("name"):
+            out.append(
+                {
+                    "name": fc.get("name"),
+                    "args": fc.get("args") or {},
+                }
+            )
+    return out
+
+
+async def _execute_tool(session, name: str, args: dict) -> dict:
+    """Dispatch a single function call to the matching brain_tools function.
+    Returns the JSON-serialisable response dict that gets fed back to Gemini
+    on the next turn."""
+    try:
+        if name == "save_profile_field":
+            return brain_tools.save_profile_field(
+                session,
+                field=args.get("field", ""),
+                value=args.get("value"),
+            )
+        if name == "retrieve_policies":
+            return await brain_tools.retrieve_policies(
+                query=args.get("query", ""),
+                top_k=int(args.get("top_k") or 8),
+                policy_filter_ids=args.get("policy_filter_ids") or None,
+                profile=getattr(session, "profile", None),
+                intent="recommendation",
+            )
+        if name == "mark_recommendation":
+            return brain_tools.mark_recommendation(
+                session,
+                policy_ids=args.get("policy_ids") or [],
+                is_final=bool(args.get("is_final") or False),
+            )
+        return {"ok": False, "error": f"unknown_tool:{name}"}
+    except Exception as e:  # noqa: BLE001 — never crash the loop
+        _log.warning(
+            "tool=%s args=%r raised %s: %s",
+            name, args, type(e).__name__, str(e)[:200],
+        )
+        return {"ok": False, "error": f"{type(e).__name__}:{str(e)[:200]}"}
+
+
+# ---------- main entrypoint ------------------------------------------------
+
+
+async def handle_turn(
+    session,
+    user_text: str,
+    chat_history: Optional[list[dict]] = None,
+) -> TurnResult:
+    """Single-LLM turn handler — replaces orchestrator.handle_turn behaviour
+    when USE_SINGLE_BRAIN is enabled.
+
+    Returns a TurnResult whose shape matches orchestrator.TurnResult.
+    Raises SingleBrainError on unrecoverable Gemini failure so the api.py
+    caller falls through to the legacy orchestrator.
+    """
+    t0 = time.time()
+
+    api_key = os.environ.get("GOOGLE_API_KEY", "").strip()
+    if not api_key:
+        raise SingleBrainError("GOOGLE_API_KEY not set")
+
+    model = _resolve_model()
+    language = _detect_language(user_text)
+    system_instruction = _system_instruction(session.profile)
+
+    # The running `contents` list — we append model turns + function
+    # responses to it across loop iterations so Gemini sees the entire
+    # tool-call thread when emitting its final text.
+    contents = _build_contents(chat_history, user_text)
+
+    # Track each tool call we serve so we can populate citations + the
+    # `intent`/`brain_used` log fields at the end.
+    tool_calls_made: list[str] = []
+    retrieved_chunks_all: list[dict] = []
+    last_marked_policy_ids: list[str] = []
+    profile_updates: dict[str, Any] = {}
+
+    # Defensive counter to break runaway loops.
+    last_text: str = ""
+    last_payload: dict = {}
+
+    for it in range(MAX_ITERATIONS):
+        try:
+            payload = await _gemini_call(
+                api_key=api_key,
+                model=model,
+                system_instruction=system_instruction,
+                contents=contents,
+                tools=TOOL_SCHEMAS,
+                timeout_sec=PER_CALL_TIMEOUT_SEC,
+            )
+        except SingleBrainError:
+            raise
+        except Exception as e:  # noqa: BLE001 — defensive
+            raise SingleBrainError(
+                f"gemini_call unexpected error: {type(e).__name__}: {e}"
+            ) from e
+
+        last_payload = payload
+        parts = _extract_parts(payload)
+        function_calls = _parts_function_calls(parts)
+        text = _parts_text(parts).strip()
+
+        # CASE A — no function calls: this is the final text reply.
+        # Includes the "Gemini just chats on turn 1" path the spec
+        # called out — completely valid, return immediately.
+        if not function_calls:
+            last_text = text
+            break
+
+        # CASE B — one or more function calls. Append the model turn
+        # verbatim so Gemini sees its own previous tool-call request,
+        # then execute every call and append a single user turn with
+        # the matching functionResponse parts.
+        contents.append(
+            {
+                "role": "model",
+                "parts": parts,
+            }
+        )
+
+        response_parts: list[dict] = []
+        for fc in function_calls:
+            name = fc["name"]
+            args = fc.get("args") or {}
+            tool_calls_made.append(name)
+            result = await _execute_tool(session, name, args)
+
+            # Bookkeeping for the TurnResult fields.
+            if name == "save_profile_field" and result.get("saved"):
+                fld = result.get("field")
+                if fld:
+                    profile_updates[fld] = result.get("value")
+            elif name == "retrieve_policies":
+                for c in result.get("chunks") or []:
+                    retrieved_chunks_all.append(c)
+            elif name == "mark_recommendation" and result.get("recorded"):
+                last_marked_policy_ids = list(result.get("policy_ids") or [])
+
+            response_parts.append(
+                {
+                    "functionResponse": {
+                        "name": name,
+                        "response": {"content": result},
+                    }
+                }
+            )
+
+        contents.append({"role": "user", "parts": response_parts})
+        # And loop — Gemini gets another shot to either call more
+        # tools or emit a final text reply.
+        last_text = text  # in case loop hits MAX_ITERATIONS with no text
+    else:
+        # Hit MAX_ITERATIONS without break — synthesise a defensive reply.
+        _log.warning(
+            "single_brain hit MAX_ITERATIONS=%d (tool_calls=%s)",
+            MAX_ITERATIONS, tool_calls_made,
+        )
+        last_text = (
+            last_text
+            or "Let me pause for a second — could you tell me a bit more about "
+               "what you're looking for, so I can give you a clean recommendation?"
+        )
+
+    # Build TurnResult.
+    reply_text = last_text or (
+        "Sorry — I lost my train of thought there. Could you say that again?"
+    )
+
+    # Citations: deduped by chunk_id; same shape orchestrator emits.
+    seen_ids: set[str] = set()
+    citations: list[dict] = []
+    retrieved_chunk_ids: list[str] = []
+    for c in retrieved_chunks_all:
+        cid = c.get("chunk_id") or ""
+        if not cid or cid in seen_ids:
+            continue
+        seen_ids.add(cid)
+        retrieved_chunk_ids.append(cid)
+        citations.append(
+            {
+                "chunk_id": cid,
+                "policy_id": c.get("policy_id", ""),
+                "policy_name": c.get("policy_name", ""),
+                "insurer_slug": c.get("insurer_slug", ""),
+                "doc_type": c.get("doc_type", ""),
+                "source_url": c.get("source_url", ""),
+                "score": c.get("score", 0.0),
+            }
+        )
+
+    intent = _classify_intent(user_text, tool_calls_made)
+    brain_used = f"single_brain::{model}"
+    if tool_calls_made:
+        brain_used += f"::tools={'+'.join(sorted(set(tool_calls_made)))}"
+
+    # follow-up policy id: if the LLM marked exactly one policy this turn,
+    # surface it so the frontend can highlight the matching card.
+    followup_policy_id = (
+        last_marked_policy_ids[0]
+        if len(last_marked_policy_ids) == 1
+        else None
+    )
+
+    return TurnResult(
+        reply_text=reply_text,
+        citations=citations,
+        retrieved_chunk_ids=retrieved_chunk_ids,
+        brain_used=brain_used,
+        intent=intent,
+        language=language,
+        latency_ms=int((time.time() - t0) * 1000),
+        raw_reply=json.dumps(last_payload)[:4000] if last_payload else reply_text,
+        faithfulness_passed=True,
+        faithfulness_reasons=[],
+        blocked=False,
+        profile_updates=profile_updates,
+        followup_policy_id=followup_policy_id,
+    )
+
+
+__all__ = [
+    "SingleBrainError",
+    "TurnResult",
+    "handle_turn",
+    "SYSTEM_PROMPT",
+    "TOOL_SCHEMAS",
+    "MAX_ITERATIONS",
+    "PER_CALL_TIMEOUT_SEC",
+]

frontend/public/admin/llm-control.html

@@ -575,6 +575,98 @@
     .profile-table td.num-cell { text-align: right; font-variant-numeric: tabular-nums; }
     .profile-table td.time-cell { white-space: nowrap; font-size: 12px; }
 
+    /* A5 — stale-data indicator + table footer */
+    .table-footer {
+      margin-top: 6px;
+      font-size: 11px;
+      color: var(--muted);
+      display: flex;
+      justify-content: flex-end;
+      gap: 6px;
+      font-variant-numeric: tabular-nums;
+    }
+    .stale-badge {
+      display: inline-block;
+      padding: 1px 7px;
+      border-radius: 4px;
+      font-size: 10px;
+      font-weight: 700;
+      letter-spacing: 0.04em;
+      vertical-align: middle;
+      font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, monospace;
+      background: rgba(210, 153, 34, 0.18);
+      color: var(--yellow);
+      border: 1px solid rgba(210, 153, 34, 0.40);
+      margin-left: 6px;
+    }
+    .stale-badge.fresh {
+      background: rgba(63, 185, 80, 0.12);
+      color: var(--green);
+      border-color: rgba(63, 185, 80, 0.35);
+    }
+    .stale-badge.down {
+      background: rgba(248, 81, 73, 0.18);
+      color: var(--red);
+      border-color: rgba(248, 81, 73, 0.40);
+    }
+
+    /* A5 — Persona drift panel + recommendation history panel */
+    .collapsible {
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      margin-top: 16px;
+      background: var(--card);
+    }
+    .collapsible > summary {
+      list-style: none;
+      cursor: pointer;
+      padding: 12px 16px;
+      font-size: 14px;
+      font-weight: 600;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 10px;
+      user-select: none;
+    }
+    .collapsible > summary::-webkit-details-marker { display: none; }
+    .collapsible > summary::before {
+      content: '▸';
+      color: var(--muted);
+      transition: transform 0.12s ease;
+      font-size: 12px;
+      margin-right: 8px;
+    }
+    .collapsible[open] > summary::before { transform: rotate(90deg); }
+    .collapsible .panel-body {
+      padding: 0 16px 16px;
+    }
+    .drift-row-bad td { background: rgba(248, 81, 73, 0.08); }
+    .drift-pct {
+      display: inline-block;
+      min-width: 48px;
+      text-align: right;
+      font-variant-numeric: tabular-nums;
+      font-weight: 600;
+    }
+    .drift-pct.bad { color: var(--red); }
+    .drift-pct.warn { color: var(--yellow); }
+    .drift-pct.ok { color: var(--green); }
+    .outcome-pill {
+      display: inline-block;
+      padding: 2px 8px;
+      border-radius: 4px;
+      font-size: 10px;
+      font-weight: 700;
+      letter-spacing: 0.04em;
+      font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, monospace;
+    }
+    .outcome-pill.selected { background: rgba(63, 185, 80, 0.15); color: var(--green); border: 1px solid rgba(63, 185, 80, 0.35); }
+    .outcome-pill.rejected { background: rgba(248, 81, 73, 0.15); color: var(--red); border: 1px solid rgba(248, 81, 73, 0.35); }
+    .outcome-pill.shown    { background: rgba(88, 166, 255, 0.15); color: var(--blue); border: 1px solid rgba(88, 166, 255, 0.35); }
+    .outcome-pill.abandoned{ background: rgba(139, 149, 164, 0.15); color: var(--muted); border: 1px solid rgba(139, 149, 164, 0.35); }
+    .outcome-pill.error    { background: rgba(210, 153, 34, 0.15); color: var(--yellow); border: 1px solid rgba(210, 153, 34, 0.35); }
+
     /* Field completeness bar */
     .field-bar {
       display: inline-flex;
@@ -648,7 +740,36 @@
         <div id="profiles-body">
           <div class="empty-state">Loading…</div>
         </div>
+        <div id="profiles-footer" class="table-footer"></div>
       </div>
+
+      <!-- A5 fix #4: Persona Drift panel (collapsible) -->
+      <details class="collapsible" id="drift-panel">
+        <summary>
+          <span>Persona Drift <span class="muted small" id="drift-summary" style="margin-left:8px;"></span></span>
+          <button id="btn-refresh-drift" type="button">Refresh</button>
+        </summary>
+        <div class="panel-body">
+          <div id="drift-body">
+            <div class="empty-state">Loading…</div>
+          </div>
+          <div id="drift-footer" class="table-footer"></div>
+        </div>
+      </details>
+
+      <!-- A5 fix #5: Recommendation History panel (collapsible) -->
+      <details class="collapsible" id="rec-panel">
+        <summary>
+          <span>Recommendation History <span class="muted small" id="rec-summary" style="margin-left:8px;"></span></span>
+          <button id="btn-refresh-rec" type="button">Refresh</button>
+        </summary>
+        <div class="panel-body">
+          <div id="rec-body">
+            <div class="empty-state">Loading…</div>
+          </div>
+          <div id="rec-footer" class="table-footer"></div>
+        </div>
+      </details>
     </section>
 
     <!-- Tab 2: Performance -->
@@ -663,6 +784,7 @@
         <div id="performance-body">
           <div class="empty-state">Loading…</div>
         </div>
+        <div id="performance-footer" class="table-footer"></div>
       </div>
     </section>
 
@@ -673,9 +795,10 @@
            may live inside this section: the h2 header (with snapshot timestamp
            span), the refresh button, and the chains container that holds the
            two generated tables (Currently In Use + All Eligible Models). -->
-      <h2>LLM health <span class="small muted" id="llm-health-snapshot-ts"></span></h2>
+      <h2>LLM health <span class="small muted" id="llm-health-snapshot-ts"></span> <span id="llm-health-stale-badge"></span></h2>
       <button id="btn-refresh-llm-health">Refresh</button>
       <div id="llm-health-chains" class="llm-simple-tables"></div>
+      <div id="llm-health-footer" class="table-footer"></div>
     </section>
   </div>
 
@@ -697,15 +820,26 @@
         // Shape: { chains: [...], candidates: [...], recent_turns: [...], snapshot_ts }
         llmHealth: null,
         llmHealthPollTimer: null,
+        llmHealthLoadedAt: null,
         lastUpdatedAt: null,
         chainLoaded: false,
         // Profiles tab
         profiles: null,
         profilesLoaded: false,
+        profilesLoadedAt: null,
         profilesSort: { key: 'last_seen', dir: 'desc' },
+        // A5 — Persona Drift panel
+        drift: null,
+        driftLoaded: false,
+        driftLoadedAt: null,
+        // A5 — Recommendation History panel
+        recHistory: null,
+        recHistoryLoaded: false,
+        recHistoryLoadedAt: null,
         // Performance tab
         performance: null,
         performanceLoaded: false,
+        performanceLoadedAt: null,
         // Active tab
         activeTab: 'profiles'
       };
@@ -1340,6 +1474,7 @@
       function fetchLlmHealth() {
         return apiGetTolerant('/api/admin/llm-health').then(function (data) {
           STATE.llmHealth = data;
+          STATE.llmHealthLoadedAt = Date.now();
         }).catch(function (err) {
           if (err && err.notDeployed) {
             STATE.llmHealth = { __notDeployed: true };
@@ -1904,6 +2039,7 @@
       function fetchProfiles() {
         return apiGetTolerant('/api/admin/profiles').then(function (data) {
           STATE.profiles = data;
+          STATE.profilesLoadedAt = Date.now();
         });
       }
 
@@ -2076,6 +2212,7 @@
       function fetchPerformance() {
         return apiGetTolerant('/api/admin/performance').then(function (data) {
           STATE.performance = data;
+          STATE.performanceLoadedAt = Date.now();
         });
       }
 
@@ -2382,6 +2519,262 @@
         return wrap;
       }
 
+      // ----- A5 — Persona Drift panel -----
+      function fetchDrift() {
+        return apiGetTolerant('/api/admin/persona-drift').then(function (data) {
+          STATE.drift = data;
+          STATE.driftLoadedAt = Date.now();
+        });
+      }
+
+      function renderDrift() {
+        var body = $('drift-body');
+        var summary = $('drift-summary');
+        clearChildren(body);
+        if (summary) summary.textContent = '';
+        if (!STATE.drift) {
+          body.appendChild(createEl('div', { className: 'empty-state', text: 'Loading…' }));
+          return;
+        }
+        if (STATE.drift.__notDeployed) {
+          body.appendChild(buildPendingMessage('/api/admin/persona-drift'));
+          return;
+        }
+        var personas = STATE.drift.personas || [];
+        if (summary) {
+          summary.textContent = personas.length + ' persona' + (personas.length === 1 ? '' : 's')
+            + ' · ' + ((STATE.drift.slots || []).length || 6) + ' slots';
+        }
+        if (!personas.length) {
+          body.appendChild(createEl('div', { className: 'empty-state',
+            text: 'No personas captured yet.' }));
+          return;
+        }
+        var table = createEl('table');
+        var thead = createEl('thead');
+        var hr = createEl('tr');
+        ['Persona', 'Last seen', 'Captured', 'Missing', 'Completeness'].forEach(function (h, i) {
+          var th = createEl('th', { text: h });
+          if (i >= 4) th.style.textAlign = 'right';
+          hr.appendChild(th);
+        });
+        thead.appendChild(hr);
+        table.appendChild(thead);
+        var tbody = createEl('tbody');
+        personas.forEach(function (r) {
+          var tr = createEl('tr');
+          if (r.completeness_pct < 50) tr.classList.add('drift-row-bad');
+          var nameCell = createEl('td');
+          var nameSpan = createEl('span', { text: r.name_display || '—' });
+          nameCell.appendChild(nameSpan);
+          var idSpan = createEl('span', { className: 'small muted',
+            text: '  ' + (r.persona_id || '') });
+          idSpan.style.fontFamily = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, monospace';
+          idSpan.style.marginLeft = '8px';
+          nameCell.appendChild(idSpan);
+          tr.appendChild(nameCell);
+          tr.appendChild(createEl('td', { className: 'time-cell', text: fmtIST(r.last_seen) }));
+          tr.appendChild(createEl('td', { className: 'mono small',
+            text: (r.captured_slots || []).join(', ') || '—' }));
+          var missCell = createEl('td', { className: 'mono small',
+            text: (r.missing_slots || []).join(', ') || '—' });
+          if ((r.missing_slots || []).length) missCell.style.color = 'var(--yellow)';
+          tr.appendChild(missCell);
+          var pctCell = createEl('td');
+          pctCell.style.textAlign = 'right';
+          var pctSpan = createEl('span', { className: 'drift-pct' });
+          pctSpan.textContent = (r.completeness_pct != null ? r.completeness_pct.toFixed(0) : '—') + '%';
+          if (r.completeness_pct < 50) pctSpan.classList.add('bad');
+          else if (r.completeness_pct < 80) pctSpan.classList.add('warn');
+          else pctSpan.classList.add('ok');
+          pctCell.appendChild(pctSpan);
+          tr.appendChild(pctCell);
+          tbody.appendChild(tr);
+        });
+        table.appendChild(tbody);
+        body.appendChild(table);
+      }
+
+      function loadDrift(force) {
+        if (STATE.driftLoaded && !force) {
+          renderDrift();
+          return Promise.resolve();
+        }
+        return fetchDrift().then(function () {
+          STATE.driftLoaded = true;
+          renderDrift();
+        }).catch(function (err) {
+          if (err && err.notDeployed) {
+            STATE.drift = { __notDeployed: true };
+            renderDrift();
+          } else {
+            handleFetchErr(err);
+          }
+        });
+      }
+
+      // ----- A5 — Recommendation History panel -----
+      function fetchRecHistory() {
+        return apiGetTolerant('/api/admin/recommendation-history').then(function (data) {
+          STATE.recHistory = data;
+          STATE.recHistoryLoadedAt = Date.now();
+        });
+      }
+
+      function renderRecHistory() {
+        var body = $('rec-body');
+        var summary = $('rec-summary');
+        clearChildren(body);
+        if (summary) summary.textContent = '';
+        if (!STATE.recHistory) {
+          body.appendChild(createEl('div', { className: 'empty-state', text: 'Loading…' }));
+          return;
+        }
+        if (STATE.recHistory.__notDeployed) {
+          body.appendChild(buildPendingMessage('/api/admin/recommendation-history'));
+          return;
+        }
+        var events = STATE.recHistory.events || [];
+        if (summary) {
+          summary.textContent = events.length + ' event' + (events.length === 1 ? '' : 's');
+        }
+        if (!events.length) {
+          body.appendChild(createEl('div', { className: 'empty-state',
+            text: 'No policy events logged yet.' }));
+          return;
+        }
+        var table = createEl('table');
+        var thead = createEl('thead');
+        var hr = createEl('tr');
+        ['When', 'Persona', 'Policy', 'Insurer', 'Outcome', 'Session', 'Turn'].forEach(function (h, i) {
+          var th = createEl('th', { text: h });
+          if (i === 4 || i === 6) th.style.textAlign = 'center';
+          hr.appendChild(th);
+        });
+        thead.appendChild(hr);
+        table.appendChild(thead);
+        var tbody = createEl('tbody');
+        events.forEach(function (e) {
+          var tr = createEl('tr');
+          tr.appendChild(createEl('td', { className: 'time-cell', text: fmtIST(e.event_at) }));
+          var pCell = createEl('td');
+          pCell.appendChild(createEl('span', { text: e.name_display || '—' }));
+          var idSpan = createEl('span', { className: 'small muted',
+            text: '  ' + (e.persona_id || '') });
+          idSpan.style.fontFamily = 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, monospace';
+          idSpan.style.marginLeft = '8px';
+          pCell.appendChild(idSpan);
+          tr.appendChild(pCell);
+          tr.appendChild(createEl('td', { className: 'mono small', text: e.policy_slug || '—' }));
+          tr.appendChild(createEl('td', { text: e.insurer || '—' }));
+          var oCell = createEl('td');
+          oCell.style.textAlign = 'center';
+          var outcome = (e.outcome || e.event_type || 'shown').toLowerCase();
+          var pill = createEl('span', { className: 'outcome-pill ' + outcome, text: outcome.toUpperCase() });
+          oCell.appendChild(pill);
+          tr.appendChild(oCell);
+          var sCell = createEl('td', { className: 'mono small',
+            text: e.session_id ? String(e.session_id).slice(0, 10) + '…' : '—' });
+          if (e.session_id) sCell.title = e.session_id;
+          tr.appendChild(sCell);
+          // Conversation turn — not stamped on the event today; show '—'
+          // until the orchestrator records turn_idx into the policy event.
+          var tCell = createEl('td', { text: e.conversation_turn != null ? String(e.conversation_turn) : '—' });
+          tCell.style.textAlign = 'center';
+          tCell.classList.add('muted');
+          tr.appendChild(tCell);
+          tbody.appendChild(tr);
+        });
+        table.appendChild(tbody);
+        body.appendChild(table);
+      }
+
+      function loadRecHistory(force) {
+        if (STATE.recHistoryLoaded && !force) {
+          renderRecHistory();
+          return Promise.resolve();
+        }
+        return fetchRecHistory().then(function () {
+          STATE.recHistoryLoaded = true;
+          renderRecHistory();
+        }).catch(function (err) {
+          if (err && err.notDeployed) {
+            STATE.recHistory = { __notDeployed: true };
+            renderRecHistory();
+          } else {
+            handleFetchErr(err);
+          }
+        });
+      }
+
+      // ----- A5 — Stale-data footer (every table) -----
+      // 90s threshold: probe age > 90s ⇒ "stale" (yellow). Threshold matches
+      // the audit's "freshness" definition. Updated live via setInterval.
+      var STALE_THRESHOLD_MS = 90 * 1000;
+
+      function fmtAgo(ms) {
+        if (ms == null || isNaN(ms) || ms < 0) return '—';
+        var s = Math.floor(ms / 1000);
+        if (s < 60) return s + 's ago';
+        var m = Math.floor(s / 60);
+        if (m < 60) return m + 'm ' + (s % 60) + 's ago';
+        var h = Math.floor(m / 60);
+        return h + 'h ' + (m % 60) + 'm ago';
+      }
+
+      function setFooter(elId, fetchedAtMs, opts) {
+        var el = $(elId);
+        if (!el) return;
+        clearChildren(el);
+        if (!fetchedAtMs) return;
+        var ageMs = Date.now() - fetchedAtMs;
+        var label = createEl('span', { text: 'Last updated: ' + fmtAgo(ageMs) });
+        el.appendChild(label);
+        var badge = createEl('span');
+        var stale = ageMs > STALE_THRESHOLD_MS;
+        badge.className = 'stale-badge ' + (stale ? '' : 'fresh');
+        badge.textContent = stale ? 'STALE' : 'FRESH';
+        el.appendChild(badge);
+        if (opts && opts.extraText) {
+          var ex = createEl('span', { text: ' · ' + opts.extraText });
+          ex.classList.add('muted');
+          el.appendChild(ex);
+        }
+      }
+
+      // Per-tab footers ticked every second. Cheap — just DOM text updates.
+      function tickFooters() {
+        setFooter('profiles-footer', STATE.profilesLoadedAt);
+        setFooter('drift-footer', STATE.driftLoadedAt);
+        setFooter('rec-footer', STATE.recHistoryLoadedAt);
+        setFooter('performance-footer', STATE.performanceLoadedAt);
+        // LLM health uses probe timestamp from the snapshot — falls back to
+        // the local fetch time when the payload doesn't carry snapshot_ts.
+        var probeAt = null;
+        if (STATE.llmHealth && STATE.llmHealth.snapshot_ts) {
+          var t = Date.parse(STATE.llmHealth.snapshot_ts);
+          if (!isNaN(t)) probeAt = t;
+        }
+        if (!probeAt) probeAt = STATE.llmHealthLoadedAt;
+        setFooter('llm-health-footer', probeAt);
+        // LLM-health stale badge sits next to the section header — render
+        // separately so it's visible even when the body is empty.
+        var badgeHost = $('llm-health-stale-badge');
+        if (badgeHost) {
+          clearChildren(badgeHost);
+          if (probeAt) {
+            var ageMs = Date.now() - probeAt;
+            var stale = ageMs > STALE_THRESHOLD_MS;
+            var badge = createEl('span', {
+              className: 'stale-badge ' + (stale ? '' : 'fresh'),
+              text: stale ? 'STALE' : 'FRESH'
+            });
+            badgeHost.appendChild(badge);
+          }
+        }
+      }
+      setInterval(tickFooters, 1000);
+
       // ----- Tab switching -----
       function switchTab(tab) {
         STATE.activeTab = tab;
@@ -2402,6 +2795,10 @@
         // Lazy-load this tab's data
         if (tab === 'profiles') {
           loadProfiles(false);
+          // A5 — load drift + rec history alongside the visitors table.
+          // Cheap; both endpoints walk the same profiles dir.
+          loadDrift(false);
+          loadRecHistory(false);
           stopLlmHealthPolling();
         } else if (tab === 'performance') {
           loadPerformance(false);
@@ -2485,10 +2882,20 @@
           STATE.chains = null;
           STATE.usage = null;
           STATE.llmHealth = null;
+          STATE.llmHealthLoadedAt = null;
           STATE.profiles = null;
           STATE.profilesLoaded = false;
+          STATE.profilesLoadedAt = null;
           STATE.performance = null;
           STATE.performanceLoaded = false;
+          STATE.performanceLoadedAt = null;
+          // A5 — clear drift + rec history state on lock
+          STATE.drift = null;
+          STATE.driftLoaded = false;
+          STATE.driftLoadedAt = null;
+          STATE.recHistory = null;
+          STATE.recHistoryLoaded = false;
+          STATE.recHistoryLoadedAt = null;
           STATE.chainLoaded = false;
           stopLlmHealthPolling();
           try { localStorage.removeItem(STORAGE_KEY); } catch (_) {}
@@ -2512,6 +2919,37 @@
             .then(function () { btn.disabled = false; btn.textContent = 'Refresh'; });
         };
 
+        // A5 — Persona Drift refresh (stop bubbling so <summary> doesn't
+        // collapse the panel when the button is clicked).
+        var driftBtn = $('btn-refresh-drift');
+        if (driftBtn) {
+          driftBtn.onclick = function (e) {
+            e.stopPropagation();
+            e.preventDefault();
+            var btn = this;
+            btn.disabled = true;
+            btn.textContent = 'Refreshing…';
+            loadDrift(true).then(function () { toast('Persona drift refreshed', 'success'); })
+              .catch(handleFetchErr)
+              .then(function () { btn.disabled = false; btn.textContent = 'Refresh'; });
+          };
+        }
+
+        // A5 — Recommendation history refresh
+        var recBtn = $('btn-refresh-rec');
+        if (recBtn) {
+          recBtn.onclick = function (e) {
+            e.stopPropagation();
+            e.preventDefault();
+            var btn = this;
+            btn.disabled = true;
+            btn.textContent = 'Refreshing…';
+            loadRecHistory(true).then(function () { toast('Recommendation history refreshed', 'success'); })
+              .catch(handleFetchErr)
+              .then(function () { btn.disabled = false; btn.textContent = 'Refresh'; });
+          };
+        }
+
         // Performance refresh
         $('btn-refresh-performance').onclick = function () {
           var btn = this;

frontend/src/app/layout.tsx

@@ -1,4 +1,4 @@
-import type { Metadata } from "next";
+import type { Metadata, Viewport } from "next";
 import "./globals.css";
 
 export const metadata: Metadata = {
@@ -7,6 +7,16 @@ export const metadata: Metadata = {
     "Voice-first AI advisor for Indian health insurance. Built for Sarvam AI.",
 };
 
+// V4 #5 — iOS soft-keyboard handling. `viewport-fit=cover` lets the page
+// extend under safe-area insets (notch / home indicator) so the chat scroll
+// container can use `env(safe-area-inset-bottom)` and `100dvh` to avoid
+// being pushed behind the soft keyboard.
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  viewportFit: "cover",
+};
+
 export default function RootLayout({
   children,
 }: Readonly<{ children: React.ReactNode }>) {

frontend/src/app/page.tsx

@@ -206,6 +206,13 @@ export default function Page() {
   // re-rendering / re-subscribing.
   const isTextRequestPendingRef = useRef(false);
 
+  // KI-222 FIX 2 (2026-05-15) — AbortController for the in-flight /api/chat
+  // call inside send(). triggerBargeIn() (or any code path that wants to
+  // cancel a pending bot turn) can fire a `barge-in-abort` window event and
+  // the useEffect below will call .abort() on this controller. The signal
+  // is not yet plumbed through postChat()/api.ts — see TODO below in send().
+  const currentSendAbortRef = useRef<AbortController | null>(null);
+
   // Compatibility surface: the rest of the component (PTT path, UI pill, mic
   // blocked indicator) still references live.live / live.setLive /
   // live.recording / live.micPermissionDenied — preserve that shape so the
@@ -213,6 +220,31 @@ export default function Page() {
   const [voiceEnabled, setVoiceEnabled] = useState(false);
   const [voiceListening, setVoiceListening] = useState(false);
   const [voicePermDenied, setVoicePermDenied] = useState(false);
+
+  // V4 FIX 1 — Live PTT interim transcript. Mirrors the running browser-SR
+  // transcript so the user can see what's being captured BELOW the mic
+  // button in gray italic (rather than only inside the chat input).
+  // Throttled to ~200ms via pttInterimTimerRef so we don't thrash React on
+  // every SR partial. Cleared atomically by V4 FIX 3 when the final
+  // transcript arrives.
+  const [pttInterim, setPttInterim] = useState<string>("");
+  const pttInterimTimerRef = useRef<number | null>(null);
+  const pttInterimLatestRef = useRef<string>("");
+  // V4 FIX 2 — dedup window for final transcripts. Some browsers fire the
+  // final SpeechRecognition result twice (Safari quirk). Suppress
+  // identical strings arriving within 500ms.
+  const lastFinalTextRef = useRef<{ text: string; at: number }>({ text: "", at: 0 });
+  // V4 FIX 4 — when the input contains a freshly-committed transcript
+  // fragment (set programmatically by the voice path, not typed by the
+  // user), Backspace should erase the last WORD instead of one character.
+  // Tracks whether the current input contents originated from voice;
+  // cleared as soon as the user types or sends.
+  const inputFromTranscriptRef = useRef<boolean>(false);
+  const setInputFromTranscript = (text: string) => {
+    inputFromTranscriptRef.current = !!text;
+    setInput(text);
+  };
+
   // Submit handler — bound to the latest send() via a ref so the hook
   // doesn't need to re-subscribe on every closure change.
   const voiceSubmitRef = useRef<((text: string) => void) | null>(null);
@@ -222,7 +254,9 @@ export default function Page() {
     isTextRequestPendingRef,
     onInterimTranscript: (text) => {
       // Show the running transcript in the chat input area as the user speaks.
-      setInput(text);
+      // V4 FIX 4 — mark the input as transcript-sourced so Backspace
+      // erases the last word, not one character.
+      setInputFromTranscript(text);
     },
     onFinalTranscript: (text) => {
       // Browser detected end-of-speech — auto-submit through the regular
@@ -303,14 +337,106 @@ export default function Page() {
     localStorage.removeItem("insurance_live_pref");
   }, []);
   // Persist + sync to the live hook whenever the user toggles preference.
+  // V3 FIX 3 — if the user clicks the toggle while the bot is mid-sentence,
+  // run the interrupt cleanup so the audio stops, the blob is revoked, and
+  // the half-painted message gets the "⏸ paused" suffix. Only fires on
+  // OFF — toggling ON shouldn't pause anything (there's nothing to pause).
   useEffect(() => {
     if (typeof window !== "undefined") {
       localStorage.setItem("insurance_live_pref", userPrefersLive ? "on" : "off");
     }
+    if (!userPrefersLive) {
+      try { interruptBotAudio("user-toggle"); } catch { /* ignore */ }
+    }
     live.setLive(userPrefersLive);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [userPrefersLive]);
 
+  // V3 FIX 2 + FIX 3 — Hardened TTS interrupt cleanup. When the bot is
+  // mid-sentence and the user starts speaking / toggles voice off / clicks
+  // PTT, we need to:
+  //   (a) pause the currently-mounted <audio> elements,
+  //   (b) clear their `src` so the element releases the underlying decoder
+  //       and stops buffering further data (just .pause() leaves the blob
+  //       attached and Safari can resume autonomously after a tab refocus),
+  //   (c) URL.revokeObjectURL() the blob URL so the in-memory blob is GC'd
+  //       — without this, every interrupted reply leaks a multi-second WAV.
+  //   (d) tag the last assistant message with a gray italic "⏸ paused"
+  //       suffix so the user can see WHICH reply they cut off (V3 #3).
+  // Safe to call even when nothing is playing — every step is wrapped.
+  function interruptBotAudio(reason: "barge-in" | "user-toggle" | "ptt-start") {
+    let didPause = false;
+    if (typeof document !== "undefined") {
+      document.querySelectorAll("audio").forEach((el) => {
+        const audioEl = el as HTMLAudioElement;
+        const wasPlaying = !audioEl.paused && !audioEl.ended;
+        try {
+          audioEl.pause();
+        } catch { /* ignore */ }
+        const src = audioEl.src;
+        try {
+          if (src && src.startsWith("blob:")) URL.revokeObjectURL(src);
+        } catch { /* ignore */ }
+        try {
+          audioEl.removeAttribute("src");
+          // setting empty string makes some browsers attempt a refetch;
+          // load() after removing the attribute fully resets the element.
+          audioEl.load();
+        } catch { /* ignore */ }
+        if (wasPlaying) didPause = true;
+      });
+    }
+    // V3 FIX 3 — append "⏸ paused" suffix to the most recent assistant
+    // message ONLY if we actually paused mid-playback. We don't want to
+    // mark every reply as paused just because the user clicked the toggle
+    // before any audio existed. Guard with `didPause` and the existence of
+    // a trailing assistant bubble that still has its blob URL.
+    if (!didPause) return;
+    setMessages((prev) => {
+      if (prev.length === 0) return prev;
+      const lastIdx = prev.length - 1;
+      const last = prev[lastIdx];
+      if (last.role !== "assistant") return prev;
+      // Idempotent — don't double-append the suffix if the user fires
+      // multiple barge-ins back to back.
+      if (last.content.endsWith("⏸ paused")) return prev;
+      const updated = [...prev];
+      updated[lastIdx] = {
+        ...last,
+        content: `${last.content} ⏸ paused`,
+        // Drop the audioUrl so the inline player no longer offers replay
+        // of a blob URL we just revoked.
+        audioUrl: undefined,
+      };
+      void reason; // reserved for future telemetry
+      return updated;
+    });
+  }
+
+  // KI-222 FIX 2 (2026-05-15) — listen for the custom "barge-in-abort" DOM
+  // event so useStreamingVoice's triggerBargeIn (or any other code path)
+  // can cancel an in-flight send() turn. Hook dispatches via
+  //   window.dispatchEvent(new CustomEvent("barge-in-abort"))
+  // Idempotent: if no request is in-flight, the call is a no-op.
+  // V3 FIX 2 — also runs the audio cleanup helper so any in-flight TTS
+  // blob is released, not just paused.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onAbort = () => {
+      try {
+        currentSendAbortRef.current?.abort();
+      } catch { /* ignore — controller may already be released */ }
+      try {
+        interruptBotAudio("barge-in");
+      } catch { /* ignore */ }
+    };
+    window.addEventListener("barge-in-abort", onAbort);
+    return () => window.removeEventListener("barge-in-abort", onAbort);
+    // interruptBotAudio is referentially stable enough — closures over
+    // setMessages (stable) and DOM globals; safe to omit from deps.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   function pushUser(text: string) {
     setMessages((m) => [...m, { id: `u_${Date.now()}`, role: "user", content: text }]);
   }
@@ -373,22 +499,32 @@ export default function Page() {
   }
 
   async function send(text: string) {
+    // V4 FIX 6 — empty-message guard. The trim()-check below already
+    // covers Enter-on-empty + the disabled Send button; keeping the
+    // explicit early-return here so the guard survives any future change
+    // that bypasses the input-clear path.
     if (!text.trim() || busy) return;
     // KI-204 (2026-05-15) — silence any prior bot TTS BEFORE submitting.
     // User starting a new turn always takes precedence over the bot's
     // current reply audio. Covers typed sends, voice barge-in, manual Send
     // button, programmatic submits — every path through send() gets this.
-    if (typeof document !== "undefined") {
-      document.querySelectorAll("audio").forEach((el) => {
-        try {
-          (el as HTMLAudioElement).pause();
-          (el as HTMLAudioElement).currentTime = 0;
-        } catch {
-          // ignore — element may be in a state that disallows pause
-        }
-      });
-    }
+    // V3 FIX 2 — route through interruptBotAudio so the previous reply's
+    // blob URL is revoked (not just paused) and the half-painted message
+    // gets the "⏸ paused" suffix.
+    try { interruptBotAudio("barge-in"); } catch { /* ignore */ }
     setBusy(true);
+    // KI-222 FIX 2 (2026-05-15) — create an AbortController for this turn so
+    // a subsequent barge-in (or any external cancel) can interrupt the
+    // in-flight /api/chat call. The controller is exposed on
+    // currentSendAbortRef; a window-level "barge-in-abort" event listener
+    // (see useEffect below) calls .abort() on it.
+    // TODO: thread `signal: controller.signal` through postChat() →
+    // frontend/src/lib/api.ts so the abort actually reaches fetch. Until
+    // then, the controller is wired up but the abort() call has no effect
+    // on the in-flight request — the infrastructure is in place for the
+    // follow-up fix.
+    const controller = new AbortController();
+    currentSendAbortRef.current = controller;
     // KI-165 (2026-05-15) — flip the text-in-flight flag so the voice hook
     // (useLiveConversation) discards any captures that close during this
     // request. Prevents background notification dings from opening the mic,
@@ -424,12 +560,26 @@ export default function Page() {
         showProfile ? "profile" :
         showPremium ? "premium" :
         "chat";
+      // V3 FIX 4 — Safari has no webm/opus playback. Detect MediaSource
+      // codec support up front and ask the backend for audio/mp4 when the
+      // default opus would fail. Falls back to audio/wav (the historical
+      // default) when MediaSource isn't available at all (very old
+      // browsers / test environments).
+      const preferredCodec = (() => {
+        if (typeof window === "undefined") return undefined;
+        const MS = (window as unknown as { MediaSource?: { isTypeSupported: (t: string) => boolean } }).MediaSource;
+        if (!MS || typeof MS.isTypeSupported !== "function") return "audio/wav";
+        if (MS.isTypeSupported("audio/webm; codecs=opus")) return "audio/webm; codecs=opus";
+        if (MS.isTypeSupported("audio/mp4")) return "audio/mp4";
+        return "audio/wav";
+      })();
       const res = await postChat({
         user_text: actualText,
         session_id: sessionId,
         chat_history: history,
         return_audio: returnAudio,
         tts_language_code: ttsLang,
+        preferred_codec: preferredCodec,
         view_context: {
           active_view,
           active_policy_id: openPolicy?.policy_id,
@@ -455,7 +605,12 @@ export default function Page() {
       getProfileCompleteness(res.session_id)
         .then(setProfileCompleteness)
         .catch(() => { /* keep prior on transient error */ });
-      const audioUrl = res.audio_base64 ? audioBlobURLFromBase64(res.audio_base64) : undefined;
+      // V3 FIX 4 — honour the actual mime the backend produced when present
+      // (Safari refuses to play mp4 bytes wrapped in a wav-typed Blob).
+      // Falls back to wav for legacy backends that don't echo audio_mime.
+      const audioUrl = res.audio_base64
+        ? audioBlobURLFromBase64(res.audio_base64, res.audio_mime || "audio/wav")
+        : undefined;
       pushAssistant(res.reply_text, {
         citations: res.citations,
         audioUrl,
@@ -494,6 +649,12 @@ export default function Page() {
       // KI-165 (2026-05-15) — clear the text-in-flight flag so subsequent
       // genuine voice captures can be submitted again.
       isTextRequestPendingRef.current = false;
+      // KI-222 FIX 2 — release the abort controller now that the request
+      // has resolved (or thrown). If a later barge-in event fires after
+      // this point there's no in-flight turn to cancel.
+      if (currentSendAbortRef.current === controller) {
+        currentSendAbortRef.current = null;
+      }
     }
   }
 
@@ -506,10 +667,16 @@ export default function Page() {
     voiceSubmitRef.current = (text: string) => {
       const t = text.trim();
       if (t.length < 2) return;
+      // V4 FIX 2 — dedup repeated finals within 500ms.
+      const { text: prevText, at: prevAt } = lastFinalTextRef.current;
+      const now = Date.now();
+      if (t === prevText && now - prevAt < 500) return;
+      lastFinalTextRef.current = { text: t, at: now };
       // Mirror the typed-input flow: drop transcript into the input
       // (so the user sees their final words land in the box for a frame
       // before send() clears it) then submit.
-      setInput(t);
+      // V4 FIX 4 — flag the input as transcript-sourced.
+      setInputFromTranscript(t);
       void send(t);
     };
     // send() reads `messages` / `sessionId` / `ttsLang` / view flags via
@@ -518,6 +685,15 @@ export default function Page() {
   }, [messages, sessionId, ttsLang, openPolicy, showMarketplace, showProfile, showPremium]);
 
   async function startRecording() {
+    // KI-222 FIX 1 — silence any prior bot TTS BEFORE PTT recording starts.
+    // Mirrors the same pause-all-audio block from send() (KI-204). Without
+    // this, the previous reply's <audio> element keeps playing after the
+    // user clicks Push-to-talk, and Sarvam transcribes the bot's own voice
+    // as user input.
+    // V3 FIX 2 — use the unified interrupt helper so the blob URL is
+    // revoked and the half-painted message picks up the "⏸ paused" suffix
+    // when PTT cuts the bot off mid-sentence.
+    try { interruptBotAudio("ptt-start"); } catch { /* ignore */ }
     // KI-027 — Push-to-talk briefly SUSPENDS Live mode (which is otherwise
     // always on). This avoids the duplicate-mic / duplicate-/api/chat bug
     // from the 2026-05-14 screenshot: only one path captures + dispatches
@@ -556,6 +732,15 @@ export default function Page() {
       // the user speaks). Best-effort: if SR is unsupported or start() throws
       // we silently continue with the existing Sarvam-only flow.
       pttFinalTranscriptRef.current = "";
+      // V4 FIX 1 / FIX 3 — reset both the visible interim strip AND the
+      // throttle ref each new PTT cycle so a stale gray-italic transcript
+      // from the previous turn doesn't leak through.
+      pttInterimLatestRef.current = "";
+      setPttInterim("");
+      if (pttInterimTimerRef.current !== null) {
+        clearTimeout(pttInterimTimerRef.current);
+        pttInterimTimerRef.current = null;
+      }
       try {
         const w = window as unknown as {
           SpeechRecognition?: PTTSpeechRecognitionCtor;
@@ -582,9 +767,30 @@ export default function Page() {
               if (r.isFinal) final += alt.transcript;
               else interim += alt.transcript;
             }
-            if (final) pttFinalTranscriptRef.current = final;
+            // V4 FIX 2 — dedup repeated finals within 500ms.
+            if (final) {
+              const trimmedFinal = final.trim();
+              const { text: prevText, at: prevAt } = lastFinalTextRef.current;
+              const now = Date.now();
+              if (trimmedFinal && (trimmedFinal !== prevText || now - prevAt > 500)) {
+                pttFinalTranscriptRef.current = final;
+                lastFinalTextRef.current = { text: trimmedFinal, at: now };
+              }
+            }
             const display = (final + interim).trim();
-            if (display) setInput(display);
+            // V4 FIX 4 — interim transcript flows into the input as a
+            // transcript-sourced fragment so Backspace can word-erase.
+            if (display) setInputFromTranscript(display);
+            // V4 FIX 1 — feed the below-mic ghost-italic display. Throttle
+            // to 200ms so very chatty SR engines (Chrome fires ~20 partials/s
+            // on fast speakers) don't thrash React.
+            pttInterimLatestRef.current = display;
+            if (pttInterimTimerRef.current === null) {
+              pttInterimTimerRef.current = window.setTimeout(() => {
+                setPttInterim(pttInterimLatestRef.current);
+                pttInterimTimerRef.current = null;
+              }, 200);
+            }
           };
           rec.onerror = () => { /* best-effort — Sarvam is the source of truth */ };
           rec.onend = () => { /* nothing — recorder.onstop drives the submit */ };
@@ -608,6 +814,16 @@ export default function Page() {
         if (sr) {
           try { sr.abort(); } catch { /* already stopped */ }
         }
+        // V4 FIX 3 — atomically clear the interim ghost text (both the
+        // pending throttled update AND any visible state). Without this,
+        // the gray-italic strip below the mic can keep showing the last
+        // partial transcript after the final has already been committed.
+        if (pttInterimTimerRef.current !== null) {
+          clearTimeout(pttInterimTimerRef.current);
+          pttInterimTimerRef.current = null;
+        }
+        pttInterimLatestRef.current = "";
+        setPttInterim("");
         const srFallback = pttFinalTranscriptRef.current.trim();
         const blob = new Blob(audioChunksRef.current, { type: recorder.mimeType || "audio/webm" });
         setRecording(false);
@@ -638,14 +854,15 @@ export default function Page() {
             // KI-213 — replace the interim SR transcript with Sarvam's
             // authoritative version, then submit. send() clears the input
             // itself so the brief flash here is intentional UX feedback.
-            setInput(text);
+            // V4 FIX 4 — transcript-sourced.
+            setInputFromTranscript(text);
             // send() flips voicePhase to "thinking" itself; no need to set here
             await send(text);
           } else if (srFallback) {
             // KI-213 — Sarvam returned empty but the browser caught
             // something. Better than telling the user "couldn't hear that
             // clearly" when we actually have a usable transcript.
-            setInput(srFallback);
+            setInputFromTranscript(srFallback);
             await send(srFallback);
           } else {
             setInput("");
@@ -655,7 +872,7 @@ export default function Page() {
           // KI-213 — Sarvam failed (network / 5xx / rate limit). Fall back to
           // the SR transcript if we have one rather than dropping the turn.
           if (srFallback) {
-            setInput(srFallback);
+            setInputFromTranscript(srFallback);
             try { await send(srFallback); } catch { /* send handles its own errors */ }
           } else {
             setInput("");
@@ -758,8 +975,13 @@ export default function Page() {
     }
   }
 
+  // V4 FIX 5 — `min-h-[100dvh]` uses the dynamic viewport unit so the
+  // layout shrinks correctly when the iOS soft keyboard opens (vs the
+  // legacy `100vh` which stays fixed and pushes the composer behind the
+  // keyboard). `min-h-screen` is kept as a fallback for browsers that
+  // don't understand `dvh`.
   return (
-    <div className="min-h-screen flex flex-col bg-[var(--background)] text-[var(--foreground)]">
+    <div className="min-h-screen min-h-[100dvh] flex flex-col bg-[var(--background)] text-[var(--foreground)]">
       <header className="border-b border-[var(--border)] bg-[var(--card)]">
         <div className="max-w-6xl mx-auto px-4 sm:px-6 py-4 flex items-center justify-between">
           <div className="flex items-center gap-3">
@@ -930,12 +1152,62 @@ export default function Page() {
           </div>
         )}
 
-        <div className="border border-[var(--border)] rounded-2xl bg-[var(--card)] p-3 shadow-sm">
+        {/* V4 FIX 5 — pb-[env(safe-area-inset-bottom)] keeps the composer
+            above the iOS home-indicator strip even when the soft keyboard
+            is open. Combined with viewport-fit=cover on the meta + the
+            min-h-0 wrapper above, the chat scroll container hands the
+            keyboard its space instead of getting hidden behind it. */}
+        <div
+          className="border border-[var(--border)] rounded-2xl bg-[var(--card)] p-3 shadow-sm"
+          style={{ paddingBottom: "max(0.75rem, env(safe-area-inset-bottom))" }}
+        >
           <div className="flex items-end gap-2">
             <textarea
               value={input}
-              onChange={(e) => setInput(e.target.value)}
-              onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); send(input); } }}
+              onChange={(e) => {
+                // V4 FIX 4 — once the user starts typing, the input is no
+                // longer "transcript-sourced", so the next Backspace should
+                // behave normally (single-character erase).
+                inputFromTranscriptRef.current = false;
+                setInput(e.target.value);
+              }}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && !e.shiftKey) {
+                  e.preventDefault();
+                  // V4 FIX 6 — guard against empty Enter.
+                  if (!input.trim()) return;
+                  send(input);
+                  return;
+                }
+                // V4 FIX 4 — if the current input is a freshly-committed
+                // transcript fragment AND the caret is at the end of the
+                // text, Backspace erases the last word. Once the user has
+                // typed anything (or moved the caret mid-string), the
+                // transcript flag was cleared by onChange — so this branch
+                // no longer fires and Backspace behaves normally.
+                if (
+                  e.key === "Backspace"
+                  && inputFromTranscriptRef.current
+                  && !e.metaKey
+                  && !e.ctrlKey
+                  && !e.altKey
+                ) {
+                  const ta = e.currentTarget;
+                  const atEnd = ta.selectionStart === input.length && ta.selectionEnd === input.length;
+                  if (atEnd && input.length > 0) {
+                    e.preventDefault();
+                    // Strip trailing whitespace, then drop the last word.
+                    const stripped = input.replace(/\s+$/, "");
+                    const lastSpace = stripped.lastIndexOf(" ");
+                    const erased = lastSpace >= 0 ? stripped.slice(0, lastSpace) : "";
+                    setInput(erased);
+                    // Keep the transcript-sourced flag set so subsequent
+                    // Backspaces continue to erase by word until the box is
+                    // empty.
+                    inputFromTranscriptRef.current = erased.length > 0;
+                  }
+                }
+              }}
               placeholder="Ask about coverage, waiting periods, exclusions, or compare policies…"
               rows={1}
               className="flex-1 resize-none bg-transparent outline-none text-sm sm:text-base px-2 py-2 min-h-[40px] max-h-32"
@@ -993,6 +1265,20 @@ export default function Page() {
               Send
             </button>
           </div>
+          {/* V4 FIX 1 — live PTT interim transcript directly under the mic
+              row, shown in gray italic. Updates ~5/sec via the throttled
+              pttInterim state. Hidden when not recording or when there's
+              no partial yet, so we don't render an empty 1-line strip. */}
+          {recording && pttInterim && (
+            <div
+              className="mt-1 px-2 text-xs italic text-[var(--muted-foreground)] leading-snug truncate"
+              aria-live="polite"
+              aria-atomic="true"
+              title={pttInterim}
+            >
+              {pttInterim}
+            </div>
+          )}
           <div className="flex items-center justify-between gap-3 mt-2 pt-2 px-2 text-xs text-[var(--muted-foreground)]">
             <div className="flex items-center gap-3">
               {/* KI-028 — Clickable Live toggle. Green = always-on listening,
@@ -1634,7 +1920,16 @@ function stripInlineCitations(text: string): string {
 
 function Message({ m }: { m: DisplayMessage }) {
   const isUser = m.role === "user";
-  const displayContent = isUser ? m.content : stripInlineCitations(m.content);
+  // V3 FIX 3 — split off the trailing "⏸ paused" marker (appended by
+  // interruptBotAudio) so we can render it as gray italic instead of plain
+  // body text. Only matches an exact-suffix; embedded "paused" in normal
+  // prose is untouched.
+  const rawContent = isUser ? m.content : stripInlineCitations(m.content);
+  const PAUSED_SUFFIX = " ⏸ paused";
+  const isPaused = !isUser && rawContent.endsWith(PAUSED_SUFFIX);
+  const displayContent = isPaused
+    ? rawContent.slice(0, -PAUSED_SUFFIX.length)
+    : rawContent;
   const audioRef = useRef<HTMLAudioElement | null>(null);
 
   // KI-030 — Auto-play the bot's TTS reply when the message first mounts.
@@ -1648,12 +1943,27 @@ function Message({ m }: { m: DisplayMessage }) {
   // Played only on mount (one-shot) so chat-history rehydration doesn't
   // replay every old reply. (audioUrl is also stripped from localStorage on
   // persist, so old messages don't have URLs to replay anyway.)
+  //
+  // V3 FIX 1 — autoplay/observer race. An IntersectionObserver (or any
+  // mount-time effect) may try to play() the element before its metadata is
+  // ready, resulting in a NotSupportedError or a silent no-op. Wait for
+  // `loadedmetadata` before calling play(); if the metadata has already
+  // arrived by the time the effect runs, play() immediately. readyState ≥ 1
+  // means HAVE_METADATA per the HTMLMediaElement spec.
   useEffect(() => {
-    if (m.audioUrl && audioRef.current) {
-      audioRef.current.play().catch(() => {
+    const el = audioRef.current;
+    if (!m.audioUrl || !el) return;
+    const tryPlay = () => {
+      el.play().catch(() => {
         /* autoplay blocked — user can click the inline control to listen */
       });
+    };
+    if (el.readyState >= 1 /* HAVE_METADATA */) {
+      tryPlay();
+      return;
     }
+    el.addEventListener("loadedmetadata", tryPlay, { once: true });
+    return () => el.removeEventListener("loadedmetadata", tryPlay);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
@@ -1662,7 +1972,14 @@ function Message({ m }: { m: DisplayMessage }) {
       <div className={`max-w-[85%] sm:max-w-[75%] rounded-2xl px-4 py-3 ${
         isUser ? "bg-[var(--primary)] text-[var(--primary-foreground)]" : "bg-[var(--card)] border border-[var(--border)]"
       }`}>
-        <div className="text-sm sm:text-base whitespace-pre-wrap leading-relaxed">{displayContent}</div>
+        <div className="text-sm sm:text-base whitespace-pre-wrap leading-relaxed">
+          {displayContent}
+          {isPaused && (
+            <span className="ml-1 italic text-[var(--muted-foreground)] opacity-80">
+              ⏸ paused
+            </span>
+          )}
+        </div>
         {m.audioUrl && (
           <audio
             ref={audioRef}

frontend/src/lib/api.ts

@@ -26,6 +26,11 @@ export type ChatResponse = {
   latency_ms: number;
   session_id: string;
   audio_base64?: string | null;
+  // V3 #4 — backend MAY echo the actual mime it produced (e.g. "audio/mp4")
+  // when the client requested a codec other than the wav default. The
+  // frontend uses this when constructing the playback Blob URL so Safari
+  // doesn't refuse to play an mp4 payload labelled as wav.
+  audio_mime?: string | null;
   faithfulness_passed?: boolean;
   faithfulness_reasons?: string[];
   blocked?: boolean;
@@ -94,14 +99,21 @@ export async function postChat(args: {
   return_audio?: boolean;
   tts_language_code?: string;
   view_context?: ViewContext;
+  // V3 #4 — Safari has no webm/opus support. Caller passes its preferred
+  // codec ("audio/webm; codecs=opus" or "audio/mp4") and the backend SHOULD
+  // honour it on the TTS payload. Sent as a header (`X-Preferred-Codec`)
+  // AND included in the body for backends that ignore custom headers.
+  preferred_codec?: string;
   signal?: AbortSignal;
   onRetry?: (attempt: number) => void;
 }): Promise<ChatResponse> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (args.preferred_codec) headers["X-Preferred-Codec"] = args.preferred_codec;
   const resp = await _fetchWithRetry(
     `${BACKEND_URL}/api/chat`,
     {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers,
       body: JSON.stringify({
         user_text: args.user_text,
         session_id: args.session_id,
@@ -111,6 +123,7 @@ export async function postChat(args: {
         return_audio: args.return_audio ?? false,
         tts_language_code: args.tts_language_code ?? "en-IN",
         view_context: args.view_context,
+        preferred_codec: args.preferred_codec,
       }),
     },
     args.signal,

frontend/src/lib/useStreamingVoice.ts

@@ -39,6 +39,15 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import { postTranscribe } from "./api";
+// KI-223..228 (2026-05-15) — additive resilience layer (V1.1/V1.3/V5.4/V6.8).
+// Lives in a sibling module so the hook body stays under control and the
+// retry / noise-floor / sample-rate helpers can be unit-tested in isolation.
+import {
+  retryPostTranscribe,
+  scaleSpeechZcrBand,
+  AdaptiveNoiseFloor,
+  type VoiceError,
+} from "./voice_resilience";
 
 // KI-189 (2026-05-15) — live-speak barge-in tuning constants.
 // The MediaRecorder mic stream IS echo-cancelled by the browser (KI-185
@@ -85,6 +94,15 @@ const VOICE_MODE_TTS_VOLUME = 0.3;
 // never crosses the recognition threshold.
 const USER_SPEECH_RMS_INITIAL = 0.05;          // typical quiet speech, used until calibrated
 const USER_SPEECH_DETECTION_THRESHOLD = 0.02;  // mic RMS above this counts as "user speaking"
+// FIX 5 (HIGH) — hard ceiling on the rolling-peak userSpeechRms. Without
+// this, a single shout pins userSpeechRms at 0.4+ for the entire session
+// → adaptive barge-in threshold rises → normal-volume speech can't break
+// through → user has to shout to barge in again. The userRmsTick is also
+// gated on !isTtsPlaying, so during TTS playback there's NO decay path —
+// the wall-clock decay interval below provides decay regardless of gating.
+const USER_SPEECH_RMS_CEILING = 0.15;
+const USER_SPEECH_RMS_WALL_CLOCK_DECAY_MS = 1000;
+const USER_SPEECH_RMS_WALL_CLOCK_DECAY_FACTOR = 0.9;
 const VOLUME_CALIB_TARGET_RATIO = 0.35;        // bot_rms_at_mic should be ≤ user_rms × this
 const VOLUME_CALIB_TICK_MS = 300;              // calibration sample period during TTS
 const VOLUME_CALIB_DUCK_FACTOR = 0.8;          // multiply el.volume by this per tick if too loud
@@ -149,12 +167,34 @@ export interface UseStreamingVoiceOptions {
   onListening: (listening: boolean) => void;
   isTextRequestPendingRef: React.MutableRefObject<boolean>;
   language?: string;
+  // KI-223 (2026-05-15) — V1.1 / V1.2 / V5.4. Optional structured error
+  // callback so page.tsx can react specifically to recoverable failures
+  // (e.g. show "tap to enable audio" when audio_context_suspended fires).
+  // Optional: existing consumers that don't pass this still work.
+  onVoiceError?: (err: VoiceError) => void;
 }
 
 export interface UseStreamingVoiceReturn {
   start: () => void;
   stop: () => void;
   isSupported: boolean;
+  /**
+   * FIX 3 (HIGH) — Barge-in signal. The hook flips an internal flag when
+   * `triggerBargeIn` fires (user spoke over bot TTS). The caller (page.tsx)
+   * should poll this method before/after every fetch tick during a /api/chat
+   * stream — if it returns true, abort the in-flight request and any pending
+   * audio assembly so the bot doesn't keep talking after the user
+   * interrupted. Reading clears the flag (one-shot semantics).
+   *
+   * Wire-up (caller side, OUT OF THIS HOOK'S SCOPE):
+   *   - Before fetch, store an AbortController locally.
+   *   - In the stream-reading loop, periodically check
+   *     `streamingVoice.consumeBargeInSignal()` and call `controller.abort()`
+   *     when it returns true.
+   *   - Alternatively register a side-effect that polls every 100ms while a
+   *     send() is in flight.
+   */
+  consumeBargeInSignal: () => boolean;
 }
 
 function resolveCtor(): SpeechRecognitionCtor | null {
@@ -177,6 +217,7 @@ export function useStreamingVoice(
     onListening,
     isTextRequestPendingRef,
     language = "en-IN",
+    onVoiceError,
   } = opts;
 
   // Keep latest callback refs so the recognition handlers always call the
@@ -186,10 +227,16 @@ export function useStreamingVoice(
   const onFinalRef = useRef(onFinalTranscript);
   const onErrorRef = useRef(onError);
   const onListeningRef = useRef(onListening);
+  // KI-223 — optional structured-error callback ref. Defaults to no-op so
+  // the rest of the hook can call it unconditionally without null checks.
+  const onVoiceErrorRef = useRef<(err: VoiceError) => void>(
+    onVoiceError ?? (() => { /* no-op */ }),
+  );
   useEffect(() => { onInterimRef.current = onInterimTranscript; }, [onInterimTranscript]);
   useEffect(() => { onFinalRef.current = onFinalTranscript; }, [onFinalTranscript]);
   useEffect(() => { onErrorRef.current = onError; }, [onError]);
   useEffect(() => { onListeningRef.current = onListening; }, [onListening]);
+  useEffect(() => { onVoiceErrorRef.current = onVoiceError ?? (() => { /* no-op */ }); }, [onVoiceError]);
 
   const recognitionRef = useRef<SpeechRecognitionInstance | null>(null);
   const finalsRef = useRef<string[]>([]);
@@ -231,6 +278,20 @@ export function useStreamingVoice(
   const pendingUtteranceRef = useRef<string>("");
   const pendingChunksRef = useRef<Blob[]>([]);
   const pendingSubmitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // FIX 3 (HIGH) — one-shot barge-in signal. Flipped true by triggerBargeIn
+  // when the VAD detects sustained user speech over bot TTS. Read+cleared
+  // via consumeBargeInSignal() so the caller (page.tsx) can abort any
+  // in-flight /api/chat request that's still assembling more TTS audio.
+  const bargeInRequestedRef = useRef<boolean>(false);
+  // KI-228 (2026-05-15) — V6.8 adaptive noise floor. Persistent across the
+  // entire hook lifetime so a user's noise environment learned across the
+  // first 5 seconds carries through later TTS plays even if the audio
+  // effect tears down + rebuilds the analyser between turns.
+  const noiseFloorRef = useRef<AdaptiveNoiseFloor>(new AdaptiveNoiseFloor());
+  // KI-225 (2026-05-15) — V1.3 sample-rate-aware ZCR band, cached from the
+  // AudioContext at analyser-build time. Falls back to the 48 kHz reference
+  // band when the context isn't up yet.
+  const zcrBandRef = useRef<{ min: number; max: number }>({ min: 20, max: 250 });
 
   // ----------------------------------------------------------------------
   // KI-168 PHASE 2 — Sarvam authoritative-transcript layer.
@@ -452,6 +513,11 @@ export function useStreamingVoice(
       if (code === "no-speech" || code === "aborted") return;
       if (code === "not-allowed" || code === "service-not-allowed") {
         wantRunningRef.current = false;
+        // FIX 2 (HIGH) — Terminal-error mic leak. Without teardownAudio()
+        // here the MediaRecorder + MediaStream stay open even though
+        // recognition has shut down, so the browser's red-dot mic
+        // indicator stays lit and the OS thinks we're still recording.
+        teardownAudio();
         onErrorRef.current(
           "Mic permission denied. Click the lock icon in your browser's URL bar to enable the microphone.",
         );
@@ -459,6 +525,8 @@ export function useStreamingVoice(
       }
       if (code === "audio-capture") {
         wantRunningRef.current = false;
+        // FIX 2 (HIGH) — see above.
+        teardownAudio();
         onErrorRef.current("No microphone detected. Check your audio device and try again.");
         return;
       }
@@ -486,6 +554,39 @@ export function useStreamingVoice(
       // Sarvam fetch we'd be throwing away.
       const textRacing = isTextRequestPendingRef.current;
 
+      // FIX 7 (HIGH) — Silent onend early-return. Chrome's "no-speech"
+      // restart loop fires onend every ~5s with no content. Without this
+      // guard, every silent onend re-arms the 1500ms grace timer and the
+      // grace window extends forever — even when there's nothing pending
+      // to submit. Skip the grace-timer reset when:
+      //   - no new Web Speech text in this cycle, AND
+      //   - no audio chunks captured this cycle (chunksRef holds the
+      //     undrained chunks that will become drainedThisEnd below), AND
+      //   - no previously pending utterance text.
+      // We still call scheduleRestart() so the mic comes back online.
+      const hasNewChunksThisEnd = recorderActiveRef.current && chunksRef.current.length > 0;
+      if (!webSpeechText && !hasNewChunksThisEnd && pendingUtteranceRef.current === "") {
+        console.debug("[useStreamingVoice] KI-222 silent onend — skipping grace reset");
+        // Inline the restart-only path here so we don't need to refactor
+        // the scheduleRestart closure below it.
+        if (wantRunningRef.current && !isTextRequestPendingRef.current) {
+          const backoff = errorBackoffRef.current;
+          errorBackoffRef.current = 0;
+          clearRestartTimer();
+          restartTimerRef.current = setTimeout(() => {
+            restartTimerRef.current = null;
+            if (wantRunningRef.current) safeStart();
+          }, Math.max(50, backoff));
+        } else if (wantRunningRef.current && isTextRequestPendingRef.current) {
+          clearRestartTimer();
+          restartTimerRef.current = setTimeout(() => {
+            restartTimerRef.current = null;
+            if (wantRunningRef.current && !isTextRequestPendingRef.current) safeStart();
+          }, 250);
+        }
+        return;
+      }
+
       const scheduleRestart = () => {
         if (wantRunningRef.current && !isTextRequestPendingRef.current) {
           const backoff = errorBackoffRef.current;
@@ -657,11 +758,30 @@ export function useStreamingVoice(
           let authoritativeText = accumulatedText;
           if (allChunks.length > 0 && totalSize >= MIN_BLOB_BYTES) {
             const blob = new Blob(allChunks, { type: recorderMimeRef.current || "audio/webm" });
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), 8000);
-            try {
-              console.debug("[useStreamingVoice] POST /api/transcribe", { bytes: blob.size, mime: blob.type, lang: language });
-              const sarvam = await postTranscribe(blob, language, controller.signal);
+            // KI-226 (2026-05-15) — V5.4. Wrap the Sarvam POST in an
+            // exponential-backoff retry (1s/2s/4s, max 3 attempts). The
+            // accumulatedText (Web Speech fallback) and accumulated chunks
+            // are already captured locally, so retries don't lose the
+            // partial transcript. Each attempt enforces its own 8s timeout
+            // via the controller signal passed in by retryPostTranscribe.
+            console.debug("[useStreamingVoice] POST /api/transcribe", { bytes: blob.size, mime: blob.type, lang: language });
+            const sarvam = await retryPostTranscribe(async (signal) => {
+              // Race per-attempt 8s timeout against the retry signal so a
+              // hung connection still surfaces as an attempt failure (and
+              // triggers the next backoff step) rather than blocking
+              // forever. signal aborts when the OUTER retry loop is killed.
+              const timeoutCtl = new AbortController();
+              const timer = setTimeout(() => timeoutCtl.abort(), 8000);
+              const onOuterAbort = () => timeoutCtl.abort();
+              signal.addEventListener("abort", onOuterAbort);
+              try {
+                return await postTranscribe(blob, language, timeoutCtl.signal);
+              } finally {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", onOuterAbort);
+              }
+            });
+            if (sarvam) {
               const sarvamText = (sarvam.text || "").trim();
               if (sarvamText) {
                 authoritativeText = sarvamText;
@@ -673,10 +793,9 @@ export function useStreamingVoice(
               } else {
                 console.debug("[useStreamingVoice] Sarvam returned empty; using Web Speech fallback");
               }
-            } catch (err) {
-              console.debug("[useStreamingVoice] Sarvam failed; using Web Speech fallback", err);
-            } finally {
-              clearTimeout(timeoutId);
+            } else {
+              console.debug("[useStreamingVoice] Sarvam failed after retries; using Web Speech fallback");
+              try { onVoiceErrorRef.current("transcribe_failed"); } catch { /* ignore */ }
             }
           }
 
@@ -734,10 +853,38 @@ export function useStreamingVoice(
       } catch {
         // ignore
       }
+      // FIX 1 (HIGH) — Unbind handlers and null the ref so any late
+      // onresult/onend events delivered by Chrome AFTER abort() can't
+      // mutate finalsRef / pendingUtteranceRef / pendingChunksRef. Without
+      // this, a stale recognition instance fires onend ~50-300ms after
+      // abort() and re-arms the grace timer on a torn-down session.
+      try {
+        rec.onresult = null;
+        rec.onerror = null;
+        rec.onend = null;
+        rec.onstart = null;
+      } catch {
+        // ignore — some browsers reject null assignment on EventTarget props
+      }
     }
+    recognitionRef.current = null;
     teardownAudio();
     finalsRef.current = [];
     finalsConsumedRef.current = 0;
+    // FIX 6 (HIGH) — Mid-utterance toggle-off flush. If the user finishes
+    // a complete sentence and toggles voice off within the 1.5s grace
+    // window, submit the pending utterance instead of silently dropping
+    // it. Only flush when no text request is racing; otherwise dropping
+    // is safer than colliding with an in-flight turn.
+    const finalPending = pendingUtteranceRef.current.trim();
+    if (finalPending && !isTextRequestPendingRef.current) {
+      console.debug("[useStreamingVoice] KI-222 flushing pending on stop", { len: finalPending.length });
+      try {
+        onFinalRef.current(finalPending);
+      } catch {
+        // never let a callback throw break stop()
+      }
+    }
     // KI-202 — drop any pending utterance so toggling voice off mid-grace
     // doesn't auto-submit a stale half-sentence next time voice comes on.
     if (pendingSubmitTimerRef.current !== null) {
@@ -747,7 +894,7 @@ export function useStreamingVoice(
     pendingUtteranceRef.current = "";
     pendingChunksRef.current = [];
     onListeningRef.current(false);
-  }, [clearRestartTimer, teardownAudio]);
+  }, [clearRestartTimer, teardownAudio, isTextRequestPendingRef]);
 
   // Drive start/stop from the `enabled` prop so the hook is fire-and-forget
   // for the caller (mirrors useLiveConversation's `live` state semantics).
@@ -835,6 +982,14 @@ export function useStreamingVoice(
     const calibratedVolumes = new Map<HTMLAudioElement, number>();
     let userRmsRafId: number | null = null;
     let volumeCalibIntervalId: ReturnType<typeof setInterval> | null = null;
+    // FIX 5 (HIGH) — wall-clock decay interval. The rAF-driven userRmsTick
+    // is gated on `!isTtsPlaying`, so during bot TTS playback there is NO
+    // decay of userSpeechRms — a shout right before the bot starts speaking
+    // would pin userSpeechRms at 0.4 for the entire bot turn. This setInterval
+    // runs unconditionally while `enabled` is true, so the rolling peak
+    // decays toward USER_SPEECH_RMS_INITIAL on a wall-clock schedule that's
+    // independent of the rAF gate.
+    let userRmsWallClockIntervalId: ReturnType<typeof setInterval> | null = null;
 
     const sampleUserRms = (): number => {
       if (!analyser || !rmsBuf) return 0;
@@ -870,6 +1025,9 @@ export function useStreamingVoice(
       // doesn't permanently raise the baseline.
       if (rms > USER_SPEECH_DETECTION_THRESHOLD) {
         userSpeechRms = Math.max(userSpeechRms * 0.95, rms);
+        // FIX 5 (HIGH) — clamp to ceiling so a single shout cannot pin
+        // userSpeechRms permanently high and break subsequent barge-in.
+        userSpeechRms = Math.min(userSpeechRms, USER_SPEECH_RMS_CEILING);
       }
       userRmsRafId = requestAnimationFrame(userRmsTick);
     };
@@ -889,6 +1047,27 @@ export function useStreamingVoice(
       }
     };
 
+    // FIX 5 (HIGH) — wall-clock decay. Runs every USER_SPEECH_RMS_WALL_CLOCK_DECAY_MS
+    // regardless of TTS state so the rolling peak can't get permanently
+    // pinned high during long TTS turns. Floors at USER_SPEECH_RMS_INITIAL
+    // so we don't decay below the calibrated baseline.
+    const startUserRmsWallClockDecay = () => {
+      if (userRmsWallClockIntervalId !== null) return;
+      userRmsWallClockIntervalId = setInterval(() => {
+        userSpeechRms = Math.max(
+          USER_SPEECH_RMS_INITIAL,
+          userSpeechRms * USER_SPEECH_RMS_WALL_CLOCK_DECAY_FACTOR,
+        );
+      }, USER_SPEECH_RMS_WALL_CLOCK_DECAY_MS);
+    };
+
+    const stopUserRmsWallClockDecay = () => {
+      if (userRmsWallClockIntervalId !== null) {
+        clearInterval(userRmsWallClockIntervalId);
+        userRmsWallClockIntervalId = null;
+      }
+    };
+
     // KI-195 — volume calibration tick. Runs during TTS. Samples bot RMS
     // at the mic via botAnalysers. If bot is louder than target relative
     // to userSpeechRms, duck el.volume by 20% per tick down to the floor.
@@ -1025,6 +1204,41 @@ export function useStreamingVoice(
         frames: sustainedFrames,
         threshold: BARGE_IN_RMS_THRESHOLD,
       });
+      // KI-227 (2026-05-15) — V6.7. Flush any pending utterance that
+      // accumulated during the bot's TTS window BEFORE the barge-in fires.
+      // The grace-window timer (UTTERANCE_GRACE_MS) holds the user's
+      // utterance for up to 1.5s waiting for more bursts — if the user
+      // barges in over the bot before that timer fires, the pending text
+      // would otherwise sit silently until the timer expires. Deliver it
+      // now so page.tsx submits the user's actual question instead of
+      // letting it die on the floor while a fresh recognition starts.
+      try {
+        const flushText = pendingUtteranceRef.current.trim();
+        if (flushText && !isTextRequestPendingRef.current) {
+          console.debug("[useStreamingVoice] V6.7 flushing pending utterance on barge-in", {
+            len: flushText.length,
+          });
+          pendingUtteranceRef.current = "";
+          pendingChunksRef.current = [];
+          finalsRef.current = [];
+          finalsConsumedRef.current = 0;
+          if (pendingSubmitTimerRef.current !== null) {
+            clearTimeout(pendingSubmitTimerRef.current);
+            pendingSubmitTimerRef.current = null;
+          }
+          onFinalRef.current(flushText);
+        }
+      } catch (err) {
+        // Never let the flush throw break the barge-in pipeline.
+        console.debug("[useStreamingVoice] V6.7 pending flush threw", err);
+      }
+      // FIX 3 (HIGH) — flip the barge-in signal so the caller (page.tsx)
+      // can abort the in-flight /api/chat request that's still assembling
+      // more TTS audio. Without this, pausing the currently-mounted
+      // <audio> elements only stops THIS chunk; the next TTS chunk that
+      // arrives mounts a new <audio>, fires play, and the bot resumes
+      // talking after the user has already interrupted.
+      bargeInRequestedRef.current = true;
       // Pause + reset every TTS <audio>; the MutationObserver's pause
       // listener will set isTtsPlayingRef = false and call safeStart().
       ttsAudioElementsRef.current.forEach((el) => {
@@ -1054,19 +1268,46 @@ export function useStreamingVoice(
       }
       analyser.getFloatTimeDomainData(rmsBuf);
       let sumSq = 0;
+      // FIX 4 (HIGH) — compute zero-crossing rate alongside RMS. Speech
+      // ZCR sits in a specific band; keyboard typing has very high ZCR
+      // (transients), HVAC / room rumble has very low ZCR (DC-like).
+      // Rejecting frames outside the speech band cuts false-positive
+      // barge-ins from typing and ambient noise.
+      let zeroCrossings = 0;
+      let prevSign = rmsBuf[0] >= 0 ? 1 : -1;
       for (let i = 0; i < rmsBuf.length; i++) {
         const v = rmsBuf[i];
         sumSq += v * v;
+        if (i > 0) {
+          const sign = v >= 0 ? 1 : -1;
+          if (sign !== prevSign) zeroCrossings += 1;
+          prevSign = sign;
+        }
       }
       const rms = Math.sqrt(sumSq / rmsBuf.length);
+      // KI-228 (2026-05-15) — V6.8. Feed every frame into the adaptive
+      // noise-floor estimator. It only updates the EMA when the frame is
+      // below the CURRENT threshold (i.e. the frame looks like silence),
+      // so speech bursts can't pollute the room baseline.
+      noiseFloorRef.current.feed(rms);
+      const noiseAdaptiveThreshold = noiseFloorRef.current.currentThreshold();
       // KI-190 — adaptive threshold: bot_rms * 2 + 0.005, floored at the
       // base BARGE_IN_RMS_THRESHOLD so we never set it absurdly low.
+      // KI-228 (2026-05-15) — V6.8. ALSO floor at the noise-floor adaptive
+      // threshold so a noisy room (HVAC, café) doesn't cause false-positive
+      // barge-ins on the original static 0.008 threshold.
       const botRms = computeBotRms();
       const adaptiveThreshold = Math.max(
         BARGE_IN_RMS_THRESHOLD,
+        noiseAdaptiveThreshold,
         botRms * BARGE_IN_BOT_RMS_MULTIPLIER + BARGE_IN_BASE_THRESHOLD,
       );
-      if (rms >= adaptiveThreshold) {
+      // FIX 4 / KI-225 (V1.3) — speech ZCR band scaled to the actual
+      // AudioContext sampleRate. At 48 kHz that's the original 20..250;
+      // at 16 kHz it's ~7..83.
+      const band = zcrBandRef.current;
+      const isSpeechBand = zeroCrossings >= band.min && zeroCrossings <= band.max;
+      if (rms >= adaptiveThreshold && isSpeechBand) {
         sustainedFrames += 1;
         if (sustainedFrames >= BARGE_IN_SUSTAINED_FRAMES) {
           triggerBargeIn(rms);
@@ -1097,9 +1338,15 @@ export function useStreamingVoice(
           audioCtx = new Ctor();
         }
         if (audioCtx.state === "suspended") {
-          // Best-effort resume; ignore failures (autoplay policy may block
-          // until next user gesture — VAD simply won't fire).
-          void audioCtx.resume().catch(() => { /* ignore */ });
+          // KI-223 (2026-05-15) — V1.1. Best-effort resume; if it rejects
+          // (Chrome's autoplay policy requires a user gesture), surface a
+          // structured error so the UI can prompt the user to tap. Without
+          // this, the VAD silently never fires and barge-in appears broken
+          // for the entire session.
+          void audioCtx.resume().catch((err) => {
+            console.debug("[useStreamingVoice] V1.1 AudioContext.resume failed", err);
+            try { onVoiceErrorRef.current("audio_context_suspended"); } catch { /* ignore */ }
+          });
         }
         if (!analyser || attachedStream !== stream) {
           try { sourceNode?.disconnect(); } catch { /* ignore */ }
@@ -1111,6 +1358,26 @@ export function useStreamingVoice(
           sourceNode.connect(analyser);
           attachedStream = stream;
           rmsBuf = new Float32Array(new ArrayBuffer(analyser.fftSize * 4));
+          // KI-225 (2026-05-15) — V1.3. Compare the AudioContext's actual
+          // sampleRate against the track's reported rate. If they disagree,
+          // log a warning AND rescale the speech ZCR band so the VAD math
+          // keeps meaning at 16 kHz / 24 kHz consumer mics (the static
+          // 20..250 band from KI-189 was calibrated for 48 kHz).
+          try {
+            const trackRate = stream.getAudioTracks()[0]?.getSettings?.().sampleRate;
+            const ctxRate = audioCtx.sampleRate;
+            if (trackRate && Math.abs(trackRate - ctxRate) > 100) {
+              console.debug(
+                "[useStreamingVoice] V1.3 sample-rate mismatch",
+                { trackRate, ctxRate },
+              );
+            }
+            zcrBandRef.current = scaleSpeechZcrBand(ctxRate);
+          } catch {
+            // Older browsers without MediaTrackSettings.sampleRate — keep
+            // the reference band.
+            zcrBandRef.current = scaleSpeechZcrBand(audioCtx.sampleRate);
+          }
         }
         sustainedFrames = 0;
         if (rafId !== null) cancelAnimationFrame(rafId);
@@ -1264,11 +1531,17 @@ export function useStreamingVoice(
     // when conditions aren't met (no analyser / no stream / in TTS), so
     // firing it unconditionally here is safe.
     startUserRmsLoop();
+    // FIX 5 (HIGH) — start the wall-clock decay so userSpeechRms never
+    // gets permanently pinned high (even during TTS playback when the
+    // rAF loop is gated off).
+    startUserRmsWallClockDecay();
 
     return () => {
       // KI-195 — tear down adaptive volume calibration before clearing
       // ducked-audio state so the calibration tick can't race a clear().
       stopUserRmsLoop();
+      // FIX 5 (HIGH) — clean up the wall-clock decay interval.
+      stopUserRmsWallClockDecay();
       stopVolumeCalibration();
       calibratedVolumes.clear();
       observer.disconnect();
@@ -1360,5 +1633,16 @@ export function useStreamingVoice(
     };
   }, [clearRestartTimer, teardownAudio]);
 
-  return { start, stop, isSupported };
+  // FIX 3 (HIGH) — one-shot read-and-clear of the barge-in flag. Returns
+  // true exactly once after triggerBargeIn fires; subsequent calls return
+  // false until the next barge-in event.
+  const consumeBargeInSignal = useCallback((): boolean => {
+    if (bargeInRequestedRef.current) {
+      bargeInRequestedRef.current = false;
+      return true;
+    }
+    return false;
+  }, []);
+
+  return { start, stop, isSupported, consumeBargeInSignal };
 }

frontend/src/lib/voice_resilience.ts

@@ -0,0 +1,205 @@
+/**
+ * voice_resilience — KI-223..228 (2026-05-15).
+ *
+ * Companion module to useStreamingVoice. Holds pure helpers + small classes
+ * that don't need to live inside the hook's body. Keeping them out of the
+ * hook keeps the giant useStreamingVoice file readable, and makes the
+ * resilience logic independently unit-testable.
+ *
+ * Contents
+ * -------------------------------------------------------------------------
+ *  - retryPostTranscribe        — exponential-backoff wrapper around the
+ *                                  Sarvam STT POST so a transient network
+ *                                  blip / cold start / 502 doesn't drop the
+ *                                  user's utterance (V5.4).
+ *  - scaleSpeechZcrBand          — derives the speech-band ZCR window for a
+ *                                  given AudioContext sampleRate so the
+ *                                  fftSize=2048 VAD math from KI-189 keeps
+ *                                  meaning when the device delivers 16/24
+ *                                  kHz instead of 48 kHz (V1.3).
+ *  - AdaptiveNoiseFloor          — rolling EMA of "silent" RMS frames. Used
+ *                                  by the barge-in VAD to set a speech
+ *                                  threshold that adapts to the actual room
+ *                                  (quiet office vs. coffee shop). Replaces
+ *                                  the static BARGE_IN_RMS_THRESHOLD on the
+ *                                  noise-side; the bot-RMS adaptive piece
+ *                                  from KI-190 still rides on top (V6.8).
+ *  - VoiceError                  — string-union of new error states the hook
+ *                                  can surface to page.tsx so the UI can
+ *                                  prompt the user to interact (resume
+ *                                  suspended AudioContext) etc. (V1.1).
+ */
+
+// ---------------------------------------------------------------------------
+// V1.1 — AudioContext suspended / V1.2 — worklet failure error states.
+// We don't use AudioWorklet in this hook (the Web Speech API replaced the
+// custom PCM worklet path), but the type stays here so a future re-add
+// has a slot.
+// ---------------------------------------------------------------------------
+export type VoiceError =
+  | "audio_context_suspended"
+  | "worklet_failed"
+  | "stream_stale"
+  | "transcribe_failed";
+
+// ---------------------------------------------------------------------------
+// V5.4 — exponential-backoff transcribe retry.
+// ---------------------------------------------------------------------------
+export interface RetryOptions {
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * Wraps an async transcribe call with up to `maxAttempts` retries on
+ * network errors. Backs off 1s → 2s → 4s. Aborts propagate immediately
+ * (we don't retry a user-initiated abort).
+ *
+ * The caller passes a thunk that performs the actual POST. The thunk MUST
+ * accept its own AbortSignal so each attempt can be individually timed
+ * out — we wire one in via the per-attempt controller, while still
+ * honouring the outer `opts.signal` so a global cancel kills everything.
+ *
+ * Returns null when all attempts are exhausted (so the hook can fall back
+ * to the Web Speech transcript instead of crashing the utterance).
+ */
+export async function retryPostTranscribe<T>(
+  thunk: (signal: AbortSignal) => Promise<T>,
+  opts: RetryOptions = {},
+): Promise<T | null> {
+  const maxAttempts = opts.maxAttempts ?? 3;
+  const baseDelayMs = opts.baseDelayMs ?? 1000;
+  const outerSignal = opts.signal;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (outerSignal?.aborted) return null;
+    const perAttempt = new AbortController();
+    const onOuterAbort = () => perAttempt.abort();
+    if (outerSignal) outerSignal.addEventListener("abort", onOuterAbort);
+    try {
+      const result = await thunk(perAttempt.signal);
+      if (outerSignal) outerSignal.removeEventListener("abort", onOuterAbort);
+      return result;
+    } catch (err) {
+      if (outerSignal) outerSignal.removeEventListener("abort", onOuterAbort);
+      // User-initiated abort — don't retry.
+      if (outerSignal?.aborted) return null;
+      // Last attempt — surface null so caller can fall back.
+      if (attempt === maxAttempts) {
+        console.debug("[voice_resilience] retryPostTranscribe exhausted", {
+          attempt,
+          err: (err as Error)?.message,
+        });
+        return null;
+      }
+      const delay = baseDelayMs * Math.pow(2, attempt - 1);
+      console.debug("[voice_resilience] retryPostTranscribe attempt failed, backing off", {
+        attempt,
+        nextDelayMs: delay,
+        err: (err as Error)?.message,
+      });
+      await new Promise<void>((resolve, reject) => {
+        const t = setTimeout(resolve, delay);
+        if (outerSignal) {
+          outerSignal.addEventListener("abort", () => {
+            clearTimeout(t);
+            reject(new Error("aborted"));
+          }, { once: true });
+        }
+      }).catch(() => { /* outer abort — fall out of loop */ });
+      if (outerSignal?.aborted) return null;
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// V1.3 — sample-rate-aware ZCR band.
+// The original VAD assumes fftSize=2048 @ 48 kHz, where speech ZCR sits in
+// ~20..250 zero crossings per buffer. At 16 kHz the same 2048-sample window
+// covers 3x as long in time → ZCR counts scale by sampleRate/48000.
+//
+// We expose a helper so the hook can compute the band at AudioContext init.
+// ---------------------------------------------------------------------------
+const REFERENCE_SAMPLE_RATE = 48000;
+const REFERENCE_ZCR_MIN = 20;
+const REFERENCE_ZCR_MAX = 250;
+
+export function scaleSpeechZcrBand(actualSampleRate: number): { min: number; max: number } {
+  if (!actualSampleRate || actualSampleRate <= 0) {
+    return { min: REFERENCE_ZCR_MIN, max: REFERENCE_ZCR_MAX };
+  }
+  // ZCR scales linearly with the time-window length per buffer at fixed
+  // fftSize, which scales inversely with sampleRate. So a SHORTER window
+  // (higher rate) sees PROPORTIONALLY fewer crossings — but the per-second
+  // speech crossing rate is roughly constant. Net: the per-buffer count
+  // scales linearly with sampleRate.
+  const ratio = actualSampleRate / REFERENCE_SAMPLE_RATE;
+  return {
+    min: Math.max(1, Math.round(REFERENCE_ZCR_MIN * ratio)),
+    max: Math.max(REFERENCE_ZCR_MIN + 1, Math.round(REFERENCE_ZCR_MAX * ratio)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// V6.8 — adaptive noise-floor estimator.
+// Maintains a 5-second EMA of "silent" RMS values. The hook samples this
+// every VAD frame; when RMS is below the current speech threshold we treat
+// the frame as silent and feed it into the EMA. The current speech
+// threshold is `noiseFloor * 4 + 0.005`, clamped to [0.02, 0.15].
+//
+// Recompute cadence: caller decides. We expose a `currentThreshold()` getter
+// + a `feed(rms)` setter. The hook will call feed() every frame and read
+// the threshold whenever it needs to compare. Both are O(1).
+// ---------------------------------------------------------------------------
+const NOISE_EMA_WINDOW_SECONDS = 5;
+const NOISE_EMA_ASSUMED_FPS = 60; // rAF default
+const NOISE_EMA_ALPHA = 1 / (NOISE_EMA_WINDOW_SECONDS * NOISE_EMA_ASSUMED_FPS);
+const NOISE_THRESHOLD_MULTIPLIER = 4;
+const NOISE_THRESHOLD_BASE = 0.005;
+const NOISE_THRESHOLD_MIN = 0.02;
+const NOISE_THRESHOLD_MAX = 0.15;
+
+export class AdaptiveNoiseFloor {
+  private ema: number;
+  // Track the "current threshold" inline so currentThreshold() stays O(1)
+  // without re-running the clamp each call.
+  private threshold: number;
+
+  constructor(initialEma: number = 0.005) {
+    this.ema = initialEma;
+    this.threshold = this.computeThreshold(this.ema);
+  }
+
+  /** Feed every VAD-frame RMS. We update the EMA only when the frame is
+   *  below the CURRENT threshold (i.e. it looks like silence). This keeps
+   *  speech bursts from polluting the noise floor. */
+  feed(rms: number): void {
+    if (rms < this.threshold) {
+      this.ema = (1 - NOISE_EMA_ALPHA) * this.ema + NOISE_EMA_ALPHA * rms;
+      this.threshold = this.computeThreshold(this.ema);
+    }
+  }
+
+  /** Force-reseed (used on session start). */
+  reset(initialEma: number = 0.005): void {
+    this.ema = initialEma;
+    this.threshold = this.computeThreshold(this.ema);
+  }
+
+  currentThreshold(): number {
+    return this.threshold;
+  }
+
+  currentNoiseFloor(): number {
+    return this.ema;
+  }
+
+  private computeThreshold(ema: number): number {
+    const raw = ema * NOISE_THRESHOLD_MULTIPLIER + NOISE_THRESHOLD_BASE;
+    if (raw < NOISE_THRESHOLD_MIN) return NOISE_THRESHOLD_MIN;
+    if (raw > NOISE_THRESHOLD_MAX) return NOISE_THRESHOLD_MAX;
+    return raw;
+  }
+}