Add PRESENT_STATE intent + head-shake turnaround

Right-now questions ("how are you feeling?") were fabricating answers
from autobiographical memory. PRESENT_STATE is a new intent class that
skips retrieval and uses an affect-grounded prompt branch, falling back
to "I'm not sure" when the read is ambiguous.

Head-shake or sharp head-nod (or the manual "Not quite right" button)
hits a /chat/turnaround endpoint that re-plans the last turn:
- PERSONAL turns re-retrieve excluding the rejected bucket and exact
chunk texts, with a score floor so the rephrase doesn't degrade into
off-topic memories
- PRESENT_STATE turns flip the emotional read or admit uncertainty

Head-pose detection is client-side (MediaPipe nose-tip), with a
calibrate button and live Δx/Δy debug readout. Both bubbles stay
visible after turnaround — rejected gets strikethrough + "rephrased"
badge, new one gets "↻ turnaround".

README.md

@@ -353,9 +353,12 @@ Heads up: all camera/sensing stuff is in the frontend (MediaPipe JS). Backend ju
 
 ### Sensing (frontend)
 
-- [ ] **[Core]** Head-nod / sharp tilt = "I don't like that". Different from frustrated affect.
-  - [ ] send a `dissatisfaction_signal` flag with the chat request
-  - [ ] when set, planner returns a "did you mean X or Y?" instead of an answer (the spec's "Turnaround Option")
+- [x] **[Core]** Head-nod / sharp tilt / head-shake = "I don't like that". Different from frustrated affect.
+  - [x] frontend `HeadPoseTracker` (deadband-filtered shake + sharp-nod-with-recovery), explicit calibrate button, live Δx/Δy debug readout in sidebar
+  - [x] dedicated `POST /chat/turnaround` endpoint reuses cached last-state — one extra LLM call, no full pipeline re-run
+  - [x] intent-aware turnaround: PERSONAL re-retrieves excluding the rejected bucket *and* exact rejected chunk texts (with `turnaround_min_score` floor — falls back to original chunks rather than degrading); PRESENT_STATE flips emotional read or admits uncertainty
+  - [x] UI: rejected bubble gets strikethrough + "rephrased" badge, new bubble appended with "↻ turnaround" badge — both visible (you can't unsay something to a partner). Manual "↻ Not quite right" button as fallback
+  - [x] guards: `turnaroundConsumedTurnRef` prevents self-retrigger loops; backend `turn_id` returned in `ChatResponse` so frontend doesn't desync on persona switch; stale-turn 409
 - [ ] **[Core]** Smile / positive affect should actually change the wording (more positive lexicon), not just be metadata. Right now it's annotated in the prompt but we never checked if the LLM is doing anything with it — probably need a stronger constraint or example in the prompt
 - [ ] **[Core]** Air-writing is treated as raw text appended to the query. Spec wants it as a stylistic constraint too — should it bias tone, or stay query-only? Decide and document
 - [ ] **[Bonus]** Voice + air-writing conflict resolution. Capture short voice (Web Speech API), compare to air-written intent, send a `resolved_intent`
@@ -363,10 +366,11 @@ Heads up: all camera/sensing stuff is in the frontend (MediaPipe JS). Backend ju
 
 ### Intent decomposition
 
-> Current state: regex-splits the partner query on conjunctions/punctuation into fragments, then runs each fragment through a BGE zero-shot classifier (cosine vs. 5 seed exemplars per class). No LLM call, no retries. Runs in ~10–30ms per turn. Bucket hints for `PERSONAL` fragments come from a shared keyword helper in [backend/sensing/bucket_keywords.py](backend/sensing/bucket_keywords.py). Earlier versions used an LLM with Pydantic validation + 3 retries, which cost ~100s per turn on Ollama Cloud when the model emitted bad JSON.
+> Current state: regex-splits the partner query on conjunctions/punctuation into fragments, then runs each fragment through a BGE zero-shot classifier (cosine vs. seed exemplars per class). No LLM call, no retries. Runs in ~10–30ms per turn. Bucket hints for `PERSONAL` fragments come from a shared keyword helper in [backend/sensing/bucket_keywords.py](backend/sensing/bucket_keywords.py). Earlier versions used an LLM with Pydantic validation + 3 retries, which cost ~100s per turn on Ollama Cloud when the model emitted bad JSON.
 
 - [x] **[Core]** Personal / Contextual / Open-domain dispatch to distinct pools (personal → BGE vector store; contextual → persona memory + relevant in-session turns layered on top; open-domain → stub chunk, LLM answers from its own general knowledge — web search is intentionally out of scope).
 - [x] intent node latency — split + BGE zero-shot classifier replaces the LLM router. Parallelising sub-query retrieval is still open.
+- [x] **[Core]** `PRESENT_STATE` intent class — questions about right-now state ("how are you feeling?", "are you tired?") used to fabricate confident answers from autobiographical memory (wrong by category, not just by wording). Now they skip retrieval entirely and the planner uses an affect-grounded prompt branch with explicit fallback to "I'm not sure" when the read is ambiguous. Margin guard demotes narrow PRESENT_STATE wins to PERSONAL (better to over-retrieve than to silently drop persona memories). Air-written supplements are classified the same way as a normal fragment — a present-tense supplement on a PRESENT_STATE query no longer flips the route to PERSONAL.
 
 ### Retrieval
 

backend/api/main.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import logging
 
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
@@ -15,9 +16,12 @@ from backend.generation.llm_client import (  # active_model used by /debug/confi
 )
 from backend.guardrails.checks import check_input
 from backend.pipeline.graph import run_pipeline
+from backend.pipeline.intent_kind import classify_intent_kind
+from backend.pipeline.nodes import feedback as feedback_node
+from backend.pipeline.nodes import planner as planner_node
 from backend.pipeline.state import PipelineState
 from backend.retrieval.bucket_priors import uniform_priors
-from backend.retrieval.vector_store import _get_embedder
+from backend.retrieval.vector_store import _get_embedder, retrieve
 
 app = FastAPI(
     title="Multimodal AAC Chatbot API",
@@ -32,6 +36,7 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+_log = logging.getLogger(__name__)
 _models_ready = False
 
 
@@ -64,6 +69,13 @@ class ChatRequest(BaseModel):
     gesture_tag: str | None = None
     gaze_bucket: str | None = None
     air_written_text: str | None = None
+    head_signal: str | None = None  # "HEAD_SHAKE"|"HEAD_NOD_DISSATISFIED"
+
+
+class TurnaroundRequest(BaseModel):
+    user_id: str
+    turn_id: int | None = None  # optional guard against stale turnaround calls
+    head_signal: str | None = None
 
 
 class EvalScoresResponse(BaseModel):
@@ -91,6 +103,7 @@ class ChatResponse(BaseModel):
     latency: dict
     guardrail_passed: bool
     eval_scores: EvalScoresResponse | None = None
+    turn_id: int
 
 
 # ── Helpers ────────────────────────────────────────────────────────────────────
@@ -145,6 +158,8 @@ def _build_initial_state(req: ChatRequest, session: dict) -> PipelineState:
         gesture_tag=req.gesture_tag,
         gaze_bucket=req.gaze_bucket,
         air_written_text=req.air_written_text,
+        head_signal=req.head_signal,
+        turnaround_triggered=False,
         raw_query=req.query,
         intent_route=None,
         generation_config=None,
@@ -168,6 +183,58 @@ def _build_initial_state(req: ChatRequest, session: dict) -> PipelineState:
     )
 
 
+def _re_retrieve_excluding(
+    query: str,
+    user_id: str,
+    rejected_chunks: list[dict],
+) -> list[dict] | None:
+    """Pull fresh chunks for a turnaround, excluding the bucket and exact texts
+    of the rejected chunks.
+
+    Returns:
+        - list of chunks (passing min-score floor) when re-retrieval improved
+          on the rejected set
+        - None when re-retrieval should not be used (no signal, all dropped by
+          dedupe, or all below score floor) — caller should keep original chunks
+    """
+    if not rejected_chunks:
+        return None
+    rejected_bucket = rejected_chunks[0].get("bucket")
+    rejected_texts = {c.get("text") for c in rejected_chunks if c.get("text")}
+    if not rejected_bucket:
+        return None
+
+    try:
+        # Pull a wider net (top_k * 2) so dedupe + bucket-exclusion still leaves
+        # enough candidates to fill rerank_k.
+        fresh = retrieve(
+            query=query,
+            user_id=user_id,
+            top_k=settings.retrieval_top_k * 2,
+            rerank_k=settings.retrieval_top_k * 2,
+            bucket_filter=None,
+        )
+    except Exception as exc:
+        _log.warning("turnaround re-retrieval failed: %r", exc)
+        return None
+
+    filtered = [
+        c
+        for c in fresh
+        if c.get("bucket") != rejected_bucket
+        and c.get("text") not in rejected_texts
+        and float(c.get("score", 0.0)) >= settings.turnaround_min_score
+    ]
+    if not filtered:
+        _log.info(
+            "turnaround re-retrieval found no chunks above score floor %.2f — "
+            "keeping original chunks",
+            settings.turnaround_min_score,
+        )
+        return None
+    return filtered[: settings.retrieval_rerank_k]
+
+
 # ── Routes ─────────────────────────────────────────────────────────────────────
 
 
@@ -222,6 +289,7 @@ def chat(req: ChatRequest):
             retrieval_mode="none",
             latency={},
             guardrail_passed=False,
+            turn_id=0,
         )
 
     session = _get_or_init_session(req.user_id)
@@ -232,6 +300,7 @@ def chat(req: ChatRequest):
     # Persist updated session state
     session["session_history"] = result["session_history"]
     session["bucket_priors"] = result["bucket_priors"]
+    session["last_state"] = result
 
     # Compute evaluation metrics
     affect_emotion = (result.get("affect") or {}).get("emotion", "NEUTRAL")
@@ -256,4 +325,101 @@ def chat(req: ChatRequest):
         latency=result.get("latency_log") or {},
         guardrail_passed=result.get("guardrail_passed", True),
         eval_scores=eval_scores,
+        turn_id=result["turn_id"],
+    )
+
+
+@app.post("/chat/turnaround", response_model=ChatResponse)
+def chat_turnaround(req: TurnaroundRequest):
+    if req.user_id not in _sessions:
+        raise HTTPException(status_code=404, detail="no active session")
+
+    session = _sessions[req.user_id]
+    last: PipelineState | None = session.get("last_state")
+    if last is None:
+        raise HTTPException(status_code=409, detail="no prior turn to rephrase")
+
+    if req.turn_id is not None and req.turn_id != last["turn_id"]:
+        raise HTTPException(status_code=409, detail="stale turn_id")
+
+    # feedback.run will re-append (partner, aac_user) for this turn, so strip
+    # both of those tail entries to avoid duplicating the partner line. The
+    # rejected aac_user text is also excluded from the re-plan context this way.
+    trimmed_history = list(last.get("session_history") or [])
+    if trimmed_history and trimmed_history[-1].get("role") == "aac_user":
+        trimmed_history.pop()
+    if trimmed_history and trimmed_history[-1].get("role") == "partner":
+        trimmed_history.pop()
+
+    intent_kind = classify_intent_kind(last.get("intent_route"))
+
+    gen_cfg = dict(last.get("generation_config") or {})
+    if intent_kind == "present_state":
+        gen_cfg["persona_mod"] = "present_state_retry"
+        gen_cfg["tone_tag"] = "[TONE:HONEST_UNCERTAIN]"
+    else:
+        gen_cfg["persona_mod"] = "reverse_stance"
+        gen_cfg.setdefault("tone_tag", "[TONE:CLARIFYING_REPHRASE]")
+
+    replan_state: PipelineState = dict(last)  # type: ignore[assignment]
+    replan_state["session_history"] = trimmed_history
+    replan_state["generation_config"] = gen_cfg
+    replan_state["head_signal"] = req.head_signal or last.get("head_signal")
+    replan_state["turnaround_triggered"] = True
+    replan_state["latency_log"] = {
+        "t_sensing": 0.0,
+        "t_intent": 0.0,
+        "t_retrieval": 0.0,
+        "t_generation": 0.0,
+        "t_total": 0.0,
+    }
+
+    # For PERSONAL turnarounds, pull fresh chunks excluding the bucket and
+    # exact texts of the rejected response — same chunks would just produce
+    # the same wrong answer. _re_retrieve_excluding returns None when the
+    # fresh batch is no better than what we already had, in which case we
+    # keep the original chunks rather than degrade to lower-relevance ones.
+    if intent_kind == "memory":
+        fresh_chunks = _re_retrieve_excluding(
+            query=last["raw_query"],
+            user_id=last["user_id"],
+            rejected_chunks=last.get("retrieved_chunks") or [],
+        )
+        if fresh_chunks is not None:
+            replan_state["retrieved_chunks"] = fresh_chunks
+            replan_state["retrieval_mode_used"] = "turnaround_rebucket"
+
+    planner_update = planner_node.run_primary(replan_state)
+    replan_state.update(planner_update)  # type: ignore[typeddict-item]
+
+    feedback_update = feedback_node.run(replan_state)
+    replan_state.update(feedback_update)  # type: ignore[typeddict-item]
+
+    session["session_history"] = replan_state["session_history"]
+    session["bucket_priors"] = replan_state["bucket_priors"]
+    session["last_state"] = replan_state
+
+    affect_emotion = (replan_state.get("affect") or {}).get("emotion", "NEUTRAL")
+    eval_scores = compute_evals(
+        response=replan_state["selected_response"] or "",
+        chunks=replan_state.get("retrieved_chunks") or [],
+        latency_log=replan_state.get("latency_log") or {},
+        affect=affect_emotion,
+        gesture_tag=replan_state.get("gesture_tag"),
+        gaze_bucket=replan_state.get("gaze_bucket"),
+        slo_target=settings.slo_target_s,
+    )
+
+    return ChatResponse(
+        user_id=req.user_id,
+        query=replan_state["raw_query"],
+        response=replan_state["selected_response"] or "",
+        affect=affect_emotion,
+        llm_tier=replan_state.get("llm_tier_used", "unknown"),
+        llm_model=replan_state.get("llm_model_used", "unknown"),
+        retrieval_mode=replan_state.get("retrieval_mode_used", "unknown"),
+        latency=replan_state.get("latency_log") or {},
+        guardrail_passed=replan_state.get("guardrail_passed", True),
+        eval_scores=eval_scores,
+        turn_id=replan_state["turn_id"],
     )

backend/config/settings.py

@@ -20,6 +20,10 @@ class Settings(BaseSettings):
     retrieval_top_k: int = 5
     retrieval_rerank_k: int = 3
     retrieval_fast_k: int = 2  # used when affect == FRUSTRATED
+    # Minimum cosine score for a chunk to be used in turnaround re-retrieval.
+    # Below this, we'd rather fall back to original chunks than serve clearly
+    # off-topic memories just to "look different."
+    turnaround_min_score: float = 0.45
 
     # LLM tiers — both hit Ollama Cloud via OpenAI-compatible endpoint.
     # Same model on both tiers for now; swap one when a larger cloud model

backend/pipeline/intent_kind.py

@@ -0,0 +1,28 @@
+"""Shared intent-kind classification — used by retrieval, planner, and the
+turnaround endpoint to decide whether a turn is memory-grounded or about
+the user's present state.
+
+Centralized here so all three callers stay in lock-step. If you add a new
+intent type that should bypass retrieval, this is the only file to update.
+"""
+
+
+def classify_intent_kind(route: dict | None) -> str:
+    """Return "present_state" if every sub-intent is PRESENT_STATE; "memory" otherwise.
+
+    Mixed routes fall through to "memory" — the memory path is the safer default
+    because it still allows the model to use chunks if any are present.
+    """
+    if not route:
+        return "memory"
+    sub_intents = route.get("sub_intents") or []
+    if not sub_intents:
+        return "memory"
+    if all(si.get("type") == "PRESENT_STATE" for si in sub_intents):
+        return "present_state"
+    return "memory"
+
+
+def is_present_state_only(route: dict | None) -> bool:
+    """Convenience wrapper for retrieval node — returns True iff route is purely PRESENT_STATE."""
+    return classify_intent_kind(route) == "present_state"

backend/pipeline/nodes/feedback.py

@@ -43,6 +43,8 @@ def _log_to_jsonl(state: PipelineState, run_id: str) -> None:
         "llm_tier": state.get("llm_tier_used", "unknown"),
         "retrieval_mode": state.get("retrieval_mode_used", "unknown"),
         "affect": affect,
+        "head_signal": state.get("head_signal"),
+        "turnaround_triggered": state.get("turnaround_triggered", False),
         "guardrail_passed": state.get("guardrail_passed", True),
         "num_chunks": len(chunks),
         "num_personal": sum(

backend/pipeline/nodes/intent.py

@@ -19,11 +19,20 @@ from backend.sensing.bucket_keywords import infer_bucket
 
 _CLASS_EXEMPLARS: dict[str, list[str]] = {
     "PERSONAL": [
-        "how are you today",
         "what is your favourite food",
         "tell me about your family",
-        "what do you do in the mornings",
-        "did you enjoy the weekend",
+        "what do you do for work",
+        "did you grow up around here",
+        "what was your childhood like",
+    ],
+    "PRESENT_STATE": [
+        "how are you feeling today",
+        "are you tired right now",
+        "what are you doing at the moment",
+        "did you sleep well last night",
+        "are you in pain today",
+        "how is your day going",
+        "are you having a good day",
     ],
     "CONTEXTUAL": [
         "what did you just say",
@@ -47,6 +56,10 @@ _CLASSIFIER_THRESHOLD = (
 _CONTEXTUAL_MARGIN_MIN = (
     0.08  # CONTEXTUAL must beat runner-up by at least this — it over-matches without it
 )
+_PRESENT_STATE_MARGIN_MIN = (
+    0.05  # PRESENT_STATE skips retrieval, so a narrow win against PERSONAL would silently
+    # drop persona memories. Require a clear margin before going down that path.
+)
 _MIN_FRAGMENT_WORDS = 3
 _MAX_FRAGMENTS = 4
 
@@ -150,6 +163,15 @@ def _classify(fragment: str) -> str:
         if margin < _CONTEXTUAL_MARGIN_MIN or not has_discourse_marker:
             return "PERSONAL"
 
+    # PRESENT_STATE skips retrieval entirely, so a narrow win over PERSONAL
+    # would silently drop persona memories with no recovery path. Demote to
+    # PERSONAL if the win isn't decisive — better to over-retrieve than to
+    # answer a personal question with no chunks.
+    if best_cls == "PRESENT_STATE":
+        margin = best_score - runner_up_score
+        if margin < _PRESENT_STATE_MARGIN_MIN:
+            return "PERSONAL"
+
     return best_cls
 
 
@@ -193,11 +215,17 @@ def run(state: PipelineState) -> dict:
 
     air_written = state.get("air_written_text")
     if air_written:
+        # Classify the air-written supplement the same way as a normal fragment
+        # so a present-tense supplement ("tired") on a present-state question
+        # doesn't silently flip the route to PERSONAL and re-enable retrieval.
+        air_cls = _classify(air_written)
         sub_intents.append(
             {
-                "type": "PERSONAL",
+                "type": air_cls,
                 "query": air_written,
-                "bucket_hint": infer_bucket(air_written),
+                "bucket_hint": infer_bucket(air_written)
+                if air_cls == "PERSONAL"
+                else None,
                 "priority": priority,
             }
         )

backend/pipeline/nodes/planner.py

@@ -6,6 +6,7 @@ import time
 from backend.config.settings import settings
 from backend.generation.llm_client import active_model, chat_complete
 from backend.guardrails.checks import check_output
+from backend.pipeline.intent_kind import classify_intent_kind
 from backend.pipeline.state import PipelineState
 from backend.sensing.labels import GESTURE_TO_TAG
 
@@ -53,6 +54,11 @@ def _run(state: PipelineState, tier: str) -> dict:
     )
     gesture_tag = state.get("gesture_tag")
     air_written_text = state.get("air_written_text")
+    turnaround_triggered = state.get("turnaround_triggered", False)
+    rejected_response: str | None = None
+    if turnaround_triggered:
+        rejected_response = state.get("selected_response")
+    intent_kind = classify_intent_kind(state.get("intent_route"))
     messages = _build_messages(
         profile,
         chunks,
@@ -62,6 +68,9 @@ def _run(state: PipelineState, tier: str) -> dict:
         gen_cfg,
         gesture_tag=gesture_tag,
         air_written_text=air_written_text,
+        rejected_response=rejected_response,
+        intent_kind=intent_kind,
+        affect=affect,
     )
 
     selected = chat_complete(
@@ -102,6 +111,14 @@ def _resolve_tone_tag(user_id: str, affect: str, default_tag: str) -> str:
     return _PERSONA_TONE_OVERRIDES.get(user_id, {}).get(affect, default_tag)
 
 
+_AFFECT_HINTS = {
+    "HAPPY": "You currently feel positive — light, content, energetic.",
+    "FRUSTRATED": "You currently feel frustrated — tired, irritable, or off.",
+    "SURPRISED": "You currently feel surprised or caught off-guard.",
+    "NEUTRAL": "Your current state is unclear from the affect signal.",
+}
+
+
 def _build_messages(
     profile: dict,
     chunks: list[dict],
@@ -111,6 +128,9 @@ def _build_messages(
     gen_cfg: dict,
     gesture_tag: str | None = None,
     air_written_text: str | None = None,
+    rejected_response: str | None = None,
+    intent_kind: str = "memory",
+    affect: str = "NEUTRAL",
 ) -> list[dict]:
     # Split into a stable system message (same per persona — gets cached by the
     # provider) and a turn-specific user message. Anything that changes per
@@ -126,6 +146,9 @@ def _build_messages(
         gesture_tag,
         air_written_text,
         profile["name"],
+        rejected_response=rejected_response,
+        intent_kind=intent_kind,
+        affect=affect,
     )
     return [
         {"role": "system", "content": system_content},
@@ -178,6 +201,24 @@ _PERSONA_MOD_INSTRUCTIONS = {
     "suppress_humor": "Be direct and supportive. Suppress humor.",
     "baseline": "Use your natural communication style.",
     "add_confirmation": "Add a clarifying question or confirmation at the end.",
+    "turnaround": (
+        "Your previous reply missed what you actually meant. Rephrase "
+        "more directly — change the wording meaningfully, not just "
+        "surface tweaks — and end with a one-sentence clarifying "
+        "question to confirm you're on the right track."
+    ),
+    "reverse_stance": (
+        "Your previous reply was substantively wrong — not poorly worded, "
+        "but the wrong content. Take a meaningfully different stance using "
+        "the available memories or, if none fit, honestly say you don't "
+        "know. Do NOT just reword the previous reply."
+    ),
+    "present_state_retry": (
+        "Your previous reply was wrong about your current state. The "
+        "affect signal probably misled you. Either flip the emotional "
+        "read (if you said 'good', try 'not great') or honestly admit "
+        "you're not sure how you feel right now. Do NOT invent details."
+    ),
 }
 
 
@@ -190,6 +231,10 @@ def _build_user(
     gesture_tag: str | None,
     air_written_text: str | None,
     persona_name: str,
+    *,
+    rejected_response: str | None = None,
+    intent_kind: str = "memory",
+    affect: str = "NEUTRAL",
 ) -> str:
     personal_chunks = [c for c in chunks if c.get("source", "personal") == "personal"]
     contextual_chunks = [c for c in chunks if c.get("source") == "contextual"]
@@ -231,8 +276,38 @@ def _build_user(
         _PERSONA_MOD_INSTRUCTIONS["baseline"],
     )
 
+    turnaround_line = ""
+    if rejected_response:
+        safe_rejected = rejected_response.replace('"', "'").replace("\n", " ")[:300]
+        turnaround_line = (
+            f"\nYour previous reply (which you need to replace, not repeat): "
+            f'"{safe_rejected}"'
+        )
+
+    if intent_kind == "present_state":
+        affect_hint = _AFFECT_HINTS.get(affect, _AFFECT_HINTS["NEUTRAL"])
+        return f"""\
+{tone_tag}{gesture_line}{air_writing_line}{turnaround_line}
+{persona_instruction}
+
+The partner is asking about your present state (right now, today).
+Your autobiographical memories do NOT contain this — do not fabricate details from them.
+
+Current affect read: {affect}
+  {affect_hint}
+
+Recent conversation:
+{history_block}
+
+Partner just said: {query}
+
+Reply as {persona_name} in 1–2 sentences, first person.
+- Ground the answer in the affect read above and recent conversation only.
+- If the affect read is NEUTRAL or doesn't match what you'd say, it's better to say "I'm not sure" or "honestly, I don't really know right now" than to invent.
+- Do NOT use autobiographical facts (job, family, hobbies) unless the partner asked."""
+
     return f"""\
-{tone_tag}{gesture_line}{air_writing_line}
+{tone_tag}{gesture_line}{air_writing_line}{turnaround_line}
 {persona_instruction}
 
 Personal memories:

backend/pipeline/nodes/retrieval.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import time
 
 from backend.config.settings import settings
+from backend.pipeline.intent_kind import is_present_state_only
 from backend.pipeline.state import PipelineState, RetrievedChunk, SubIntent
 from backend.retrieval.contextual import retrieve_from_history
 from backend.retrieval.vector_store import retrieve
@@ -16,6 +17,8 @@ _OPEN_DOMAIN_STUB_TEXT = (
 def run_fast(state: PipelineState) -> dict:
     """Fast retrieval path for FRUSTRATED affect (k=2, no reranker)."""
     t0 = time.perf_counter()
+    if is_present_state_only(state.get("intent_route")):
+        return _build_return(state, [], "skipped_present_state", t0)
     chunks = _dispatch_all(state, per_intent_k=settings.retrieval_fast_k)
     return _build_return(state, chunks, "fast", t0)
 
@@ -23,6 +26,8 @@ def run_fast(state: PipelineState) -> dict:
 def run_full(state: PipelineState) -> dict:
     """Full retrieval path: top_k cosine matches narrowed to rerank_k."""
     t0 = time.perf_counter()
+    if is_present_state_only(state.get("intent_route")):
+        return _build_return(state, [], "skipped_present_state", t0)
     chunks = _dispatch_all(state, per_intent_k=settings.retrieval_rerank_k)
     return _build_return(state, chunks, "full", t0)
 
@@ -50,6 +55,12 @@ def _dispatch_all(state: PipelineState, per_intent_k: int) -> list[RetrievedChun
             merged.extend(_retrieve_contextual(sub, state, per_intent_k))
         elif kind == "OPEN_DOMAIN":
             merged.extend(_retrieve_open_domain(sub))
+        elif kind == "PRESENT_STATE":
+            # PRESENT_STATE is grounded in the affect signal, not memory.
+            # In a pure-present-state route the run_fast/run_full early skip
+            # already short-circuits us; in a mixed route we just contribute
+            # nothing here so the planner doesn't see misleading chunks.
+            continue
         else:
             merged.extend(_retrieve_personal(sub, state, per_intent_k))
 

backend/pipeline/state.py

@@ -31,7 +31,7 @@ class RetrievedChunk(TypedDict):
 
 
 class SubIntent(TypedDict):
-    type: str  # "PERSONAL" | "CONTEXTUAL" | "OPEN_DOMAIN"
+    type: str  # "PERSONAL" | "CONTEXTUAL" | "PRESENT_STATE" | "OPEN_DOMAIN"
     query: str
     bucket_hint: str | None
     priority: str  # "fast" | "normal"
@@ -47,9 +47,10 @@ class GenerationConfig(TypedDict):
     max_tokens: int
     tone_tag: str  # e.g. "[TONE:WITTY_SARCASTIC]"
     retrieval_mode: str  # "fast" | "full"
-    persona_mod: (
-        str  # "amplify_quirks" | "suppress_humor" | "baseline" | "add_confirmation"
-    )
+    persona_mod: str
+    # persona_mod values:
+    #   "amplify_quirks" | "suppress_humor" | "baseline"
+    #   | "add_confirmation" | "turnaround"
 
 
 class LatencyLog(TypedDict):
@@ -75,6 +76,8 @@ class PipelineState(TypedDict):
     gesture_tag: str | None  # e.g. "THUMBS_UP"
     gaze_bucket: str | None  # bucket hinted by gaze fixation
     air_written_text: str | None  # concatenated air-written chars
+    head_signal: str | None  # "HEAD_SHAKE" | "HEAD_NOD_DISSATISFIED"
+    turnaround_triggered: bool  # true when re-planned from dissatisfaction signal
 
     # ── L2: Intent decomposition outputs ─────────────────────────────────────
     raw_query: str  # partner's typed/spoken query

frontend/src/App.css

@@ -343,6 +343,75 @@ input[type="text"]:hover {
   font-size: 13px;
 }
 
+.sensing-debug {
+  font-family: var(--mono, monospace);
+  font-size: 11px;
+  opacity: 0.7;
+}
+
+.calibrate-btn {
+  margin-top: 8px;
+  width: 100%;
+  padding: 8px 12px;
+  font-size: 13px;
+  font-family: var(--sans);
+  background: transparent;
+  color: var(--accent);
+  border: 1px solid var(--accent);
+  border-radius: 8px;
+  cursor: pointer;
+}
+
+.calibrate-btn:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.calibrate-btn:hover:not(:disabled) {
+  background: var(--accent);
+  color: #ffffff;
+}
+
+.chat-bubble.rephrased p {
+  opacity: 0.6;
+  text-decoration: line-through;
+}
+
+.chat-bubble.turnaround {
+  border-left: 3px solid var(--accent);
+}
+
+.badge {
+  display: inline-block;
+  margin-left: 6px;
+  padding: 1px 6px;
+  font-size: 11px;
+  font-weight: 500;
+  border-radius: 10px;
+  vertical-align: middle;
+}
+
+.badge-rephrased {
+  background: rgba(0, 0, 0, 0.08);
+  color: var(--fail);
+}
+
+.badge-turnaround {
+  background: var(--accent);
+  color: #ffffff;
+}
+
+.turnaround-btn {
+  background: transparent !important;
+  color: var(--accent) !important;
+  border: 1px solid var(--accent) !important;
+}
+
+.turnaround-btn:hover:not(:disabled) {
+  background: var(--accent) !important;
+  color: #ffffff !important;
+}
+
 .eval-panel {
   margin-top: 10px;
   border-top: 1px solid var(--border);

frontend/src/App.tsx

@@ -32,8 +32,17 @@ function App() {
     return () => clearInterval(healthPoll.current);
   }, []);
 
-  const { sensing, ready, initError, init, processFrame, clearAirWrittenText, resetCalibration } =
-    useSensing();
+  const {
+    sensing,
+    ready,
+    initError,
+    init,
+    processFrame,
+    clearAirWrittenText,
+    clearHeadSignal,
+    calibrateHeadPose,
+    resetCalibration,
+  } = useSensing();
 
   const onFrame = useCallback(
     (video: HTMLVideoElement, timestamp: number) => {
@@ -89,6 +98,16 @@ function App() {
           </label>
           <WebcamSensing videoRef={videoRef} active={active} error={error || initError} />
           <SensingStatus sensing={sensing} webcamActive={active} />
+          <button
+            type="button"
+            className="calibrate-btn"
+            disabled={!active}
+            onClick={() => calibrateHeadPose()}
+          >
+            {sensing.headCalibrated
+              ? "Re-calibrate head pose"
+              : "Calibrate head pose"}
+          </button>
         </div>
 
         <div className="sidebar-section">
@@ -120,6 +139,7 @@ function App() {
           sensing={sensing}
           affectOverride={affectOverride}
           onAirTextConsumed={clearAirWrittenText}
+          onHeadSignalConsumed={clearHeadSignal}
           messages={messages}
           setMessages={setMessages}
           onLatency={setLatency}

frontend/src/components/ChatPanel.tsx

@@ -1,6 +1,6 @@
-import { useState, useRef, useEffect } from "react";
+import { useState, useRef, useEffect, useCallback } from "react";
 import type { ChatMessage, SensingState, Affect, LatencyLog } from "../types";
-import { sendChat } from "../lib/api";
+import { sendChat, sendTurnaround } from "../lib/api";
 import { EvalPanel } from "./EvalPanel";
 
 interface Props {
@@ -9,18 +9,22 @@ interface Props {
   sensing: SensingState;
   affectOverride: Affect | null;
   onAirTextConsumed: () => void;
+  onHeadSignalConsumed: () => void;
   messages: ChatMessage[];
   setMessages: React.Dispatch<React.SetStateAction<ChatMessage[]>>;
   onLatency: (latency: LatencyLog) => void;
   backendReady: boolean;
 }
 
+const TURNAROUND_WINDOW_MS = 5000;
+
 export function ChatPanel({
   userId,
   personaName,
   sensing,
   affectOverride,
   onAirTextConsumed,
+  onHeadSignalConsumed,
   messages,
   setMessages,
   onLatency,
@@ -28,12 +32,120 @@ export function ChatPanel({
 }: Props) {
   const [input, setInput] = useState("");
   const [loading, setLoading] = useState(false);
+  const [turnaroundLoading, setTurnaroundLoading] = useState(false);
   const bottomRef = useRef<HTMLDivElement>(null);
+  const lastResponseTsRef = useRef<number>(0);
+  const lastTurnIdRef = useRef<number | null>(null);
+  // turn_id of the most recent turn that was already turned around — guards
+  // against the new turnaround bubble's own head-signal re-firing turnaround
+  // on itself.
+  const turnaroundConsumedTurnRef = useRef<number | null>(null);
 
   useEffect(() => {
     bottomRef.current?.scrollIntoView({ behavior: "smooth" });
   }, [messages]);
 
+  // Reset per-turn state when the persona changes (parent clears `messages`
+  // and resets the backend session — the frontend turn counter must follow).
+  useEffect(() => {
+    lastTurnIdRef.current = null;
+    turnaroundConsumedTurnRef.current = null;
+    lastResponseTsRef.current = 0;
+  }, [userId]);
+
+  const handleTurnaround = useCallback(
+    async (reason: "head" | "manual") => {
+      if (!userId || !backendReady || turnaroundLoading || loading) return;
+      const targetTurnId = lastTurnIdRef.current;
+      if (targetTurnId === null) return;
+      if (turnaroundConsumedTurnRef.current === targetTurnId) return;
+
+      turnaroundConsumedTurnRef.current = targetTurnId;
+      setTurnaroundLoading(true);
+      try {
+        const res = await sendTurnaround({
+          user_id: userId,
+          turn_id: targetTurnId,
+          head_signal: reason === "head" ? sensing.headSignal : null,
+        });
+
+        lastTurnIdRef.current = res.turn_id;
+        turnaroundConsumedTurnRef.current = res.turn_id;
+
+        setMessages((prev) => {
+          const next = [...prev];
+          for (let i = next.length - 1; i >= 0; i--) {
+            if (next[i].role === "aac_user" && !next[i].isTurnaround) {
+              next[i] = { ...next[i], rephrased: true };
+              break;
+            }
+          }
+          next.push({
+            role: "aac_user",
+            content: res.response,
+            latency: res.latency,
+            affect: res.affect,
+            evalScores: res.eval_scores,
+            turnId: res.turn_id,
+            isTurnaround: true,
+          });
+          return next;
+        });
+        onLatency(res.latency);
+        // Do NOT advance lastResponseTsRef — keep the original turn's window so
+        // the user can't head-shake the turnaround itself into another loop.
+      } catch (e) {
+        setMessages((prev) => [
+          ...prev,
+          {
+            role: "aac_user",
+            content: `Error rephrasing: ${
+              e instanceof Error ? e.message : "request failed"
+            }`,
+            isTurnaround: true,
+          },
+        ]);
+      } finally {
+        if (reason === "head") onHeadSignalConsumed();
+        setTurnaroundLoading(false);
+      }
+    },
+    [
+      userId,
+      backendReady,
+      turnaroundLoading,
+      loading,
+      sensing.headSignal,
+      setMessages,
+      onLatency,
+      onHeadSignalConsumed,
+    ]
+  );
+
+  useEffect(() => {
+    if (
+      sensing.headSignal !== "HEAD_NOD_DISSATISFIED" &&
+      sensing.headSignal !== "HEAD_SHAKE"
+    ) {
+      return;
+    }
+    const targetTurnId = lastTurnIdRef.current;
+    const eligible =
+      targetTurnId !== null &&
+      turnaroundConsumedTurnRef.current !== targetTurnId &&
+      lastResponseTsRef.current > 0 &&
+      performance.now() - lastResponseTsRef.current <= TURNAROUND_WINDOW_MS;
+
+    if (eligible) {
+      handleTurnaround("head");
+      return;
+    }
+    // Not eligible — keep the chip visible briefly so the user can see that
+    // detection fired, then clear it. (Instant clear made detection invisible.)
+    const id = window.setTimeout(() => onHeadSignalConsumed(), 1500);
+    return () => window.clearTimeout(id);
+  }, [sensing.headSignal, handleTurnaround, onHeadSignalConsumed]);
+
   async function handleSend() {
     if (!input.trim() || !userId || !backendReady || loading) return;
 
@@ -51,8 +163,10 @@ export function ChatPanel({
         gesture_tag: sensing.gestureTag,
         gaze_bucket: sensing.gazeBucket,
         air_written_text: airText,
+        head_signal: sensing.headSignal,
       });
 
+      lastTurnIdRef.current = res.turn_id;
       setMessages((prev) => [
         ...prev,
         {
@@ -61,9 +175,11 @@ export function ChatPanel({
           latency: res.latency,
           affect: res.affect,
           evalScores: res.eval_scores,
+          turnId: res.turn_id,
         },
       ]);
       onLatency(res.latency);
+      lastResponseTsRef.current = performance.now();
     } catch (e) {
       setMessages((prev) => [
         ...prev,
@@ -78,6 +194,13 @@ export function ChatPanel({
     }
   }
 
+  const canTurnaround =
+    !!userId &&
+    backendReady &&
+    !loading &&
+    !turnaroundLoading &&
+    lastTurnIdRef.current !== null;
+
   return (
     <div className="chat-panel">
       <div className="chat-header">
@@ -85,9 +208,20 @@ export function ChatPanel({
       </div>
       <div className="chat-messages">
         {messages.map((msg, i) => (
-          <div key={i} className={`chat-bubble ${msg.role}`}>
+          <div
+            key={i}
+            className={`chat-bubble ${msg.role}${
+              msg.rephrased ? " rephrased" : ""
+            }${msg.isTurnaround ? " turnaround" : ""}`}
+          >
             <span className="chat-role">
               {msg.role === "partner" ? "Partner" : "AAC User"}
+              {msg.rephrased && (
+                <span className="badge badge-rephrased"> rephrased</span>
+              )}
+              {msg.isTurnaround && (
+                <span className="badge badge-turnaround"> ↻ turnaround</span>
+              )}
             </span>
             <p>{msg.content}</p>
             {msg.role === "aac_user" && msg.evalScores && (
@@ -101,6 +235,12 @@ export function ChatPanel({
             <p>Generating...</p>
           </div>
         )}
+        {turnaroundLoading && (
+          <div className="chat-bubble aac_user loading">
+            <span className="chat-role">AAC User</span>
+            <p>↻ Rephrasing...</p>
+          </div>
+        )}
         <div ref={bottomRef} />
       </div>
       <div className="chat-input-row">
@@ -115,6 +255,15 @@ export function ChatPanel({
         <button onClick={handleSend} disabled={!userId || loading || !backendReady || !input.trim()}>
           Send
         </button>
+        <button
+          type="button"
+          className="turnaround-btn"
+          onClick={() => handleTurnaround("manual")}
+          disabled={!canTurnaround}
+          title="Re-plan the last response (also triggered by a head shake / sharp nod)"
+        >
+          ↻ Not quite right
+        </button>
       </div>
     </div>
   );

frontend/src/components/SensingStatus.tsx

@@ -38,6 +38,26 @@ export function SensingStatus({ sensing, webcamActive }: Props) {
           {sensing.gazeBucket ?? "none"}
         </span>
       </div>
+      <div className="sensing-row">
+        <span className="sensing-label">Head</span>
+        <span className="sensing-value">
+          {sensing.headCalibrated
+            ? sensing.headSignal ?? "steady"
+            : "not calibrated"}
+        </span>
+      </div>
+      {sensing.headCalibrated && (
+        <div className="sensing-row sensing-debug">
+          <span className="sensing-label">  ↳ Δx/Δy</span>
+          <span className="sensing-value">
+            {sensing.headDebug.dx.toFixed(3)} / {sensing.headDebug.dy.toFixed(3)}
+            {"  "}
+            (peak {sensing.headDebug.maxAbsDx.toFixed(3)}/
+            {sensing.headDebug.maxAbsDy.toFixed(3)},{" "}
+            x{sensing.headDebug.crossings})
+          </span>
+        </div>
+      )}
       {sensing.airWrittenText && (
         <div className="sensing-row">
           <span className="sensing-label">Air-written</span>

frontend/src/hooks/useSensing.ts

@@ -11,6 +11,7 @@ import {
   classifyGesture,
   GazeTracker,
   AirWriter,
+  HeadPoseTracker,
 } from "../lib/sensing";
 
 const EMA_ALPHA = 0.3;
@@ -20,6 +21,9 @@ export function useSensing() {
   const handLandmarkerRef = useRef<HandLandmarker | null>(null);
   const gazeTrackerRef = useRef(new GazeTracker());
   const airWriterRef = useRef(new AirWriter());
+  const headTrackerRef = useRef(new HeadPoseTracker());
+  const calibratePendingRef = useRef(false);
+  const headDebugRef = useRef({ dx: 0, dy: 0, maxAbsDx: 0, maxAbsDy: 0, crossings: 0 });
   const neutralLCPRef = useRef<number | null>(null);
   const smoothedRef = useRef({ MAR: 0, EAR: 0.3, BRI: -0.3, LCP: 0 });
   const initingRef = useRef(false);
@@ -30,6 +34,9 @@ export function useSensing() {
     gestureTag: null,
     gazeBucket: null,
     airWrittenText: "",
+    headSignal: null,
+    headCalibrated: false,
+    headDebug: { dx: 0, dy: 0, maxAbsDx: 0, maxAbsDy: 0, crossings: 0 },
   });
 
   // Cleanup MediaPipe resources on unmount
@@ -95,6 +102,7 @@ export function useSensing() {
 
       let affect: SensingState["affect"] = null;
       let gazeBucket: SensingState["gazeBucket"] = null;
+      let headSignal: SensingState["headSignal"] = null;
 
       const faceResult = faceLandmarker.detectForVideo(video, timestamp);
       if (faceResult.faceLandmarks && faceResult.faceLandmarks.length > 0) {
@@ -105,6 +113,11 @@ export function useSensing() {
             (landmarks[61].x + landmarks[291].x) / 2;
         }
 
+        if (calibratePendingRef.current) {
+          headTrackerRef.current.calibrate(landmarks);
+          calibratePendingRef.current = false;
+        }
+
         const raw = computeAffectVector(landmarks, neutralLCPRef.current);
 
         const prev = smoothedRef.current;
@@ -118,6 +131,8 @@ export function useSensing() {
 
         affect = classifyAffect(smoothed);
         gazeBucket = gazeTrackerRef.current.process(landmarks);
+        headSignal = headTrackerRef.current.process(landmarks);
+        headDebugRef.current = headTrackerRef.current.debug;
       }
 
       let gestureTag: SensingState["gestureTag"] = null;
@@ -144,6 +159,9 @@ export function useSensing() {
         airWrittenText: newAirText
           ? prev.airWrittenText + newAirText
           : prev.airWrittenText,
+        headSignal: headSignal ?? prev.headSignal,
+        headCalibrated: headTrackerRef.current.calibrated,
+        headDebug: headDebugRef.current,
       }));
     },
     []
@@ -153,12 +171,40 @@ export function useSensing() {
     setSensing((prev) => ({ ...prev, airWrittenText: "" }));
   }, []);
 
+  const clearHeadSignal = useCallback(() => {
+    setSensing((prev) => ({ ...prev, headSignal: null }));
+  }, []);
+
+  const calibrateHeadPose = useCallback(() => {
+    calibratePendingRef.current = true;
+    setSensing((prev) => ({ ...prev, headSignal: null }));
+  }, []);
+
   const resetCalibration = useCallback(() => {
     neutralLCPRef.current = null;
     smoothedRef.current = { MAR: 0, EAR: 0.3, BRI: -0.3, LCP: 0 };
     gazeTrackerRef.current.reset();
-    setSensing({ affect: null, gestureTag: null, gazeBucket: null, airWrittenText: "" });
+    headTrackerRef.current.reset();
+    setSensing({
+      affect: null,
+      gestureTag: null,
+      gazeBucket: null,
+      airWrittenText: "",
+      headSignal: null,
+      headCalibrated: false,
+      headDebug: { dx: 0, dy: 0, maxAbsDx: 0, maxAbsDy: 0, crossings: 0 },
+    });
   }, []);
 
-  return { sensing, ready, initError, init, processFrame, clearAirWrittenText, resetCalibration };
+  return {
+    sensing,
+    ready,
+    initError,
+    init,
+    processFrame,
+    clearAirWrittenText,
+    clearHeadSignal,
+    calibrateHeadPose,
+    resetCalibration,
+  };
 }

frontend/src/lib/api.ts

@@ -1,4 +1,9 @@
-import type { ChatRequest, ChatResponse, Persona } from "../types";
+import type {
+  ChatRequest,
+  ChatResponse,
+  Persona,
+  TurnaroundRequest,
+} from "../types";
 
 const API_BASE = "";
 
@@ -19,6 +24,18 @@ export async function sendChat(req: ChatRequest): Promise<ChatResponse> {
   return res.json();
 }
 
+export async function sendTurnaround(
+  req: TurnaroundRequest
+): Promise<ChatResponse> {
+  const res = await fetch(`${API_BASE}/chat/turnaround`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(req),
+  });
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.json();
+}
+
 export async function resetSession(userId: string): Promise<void> {
   const res = await fetch(
     `${API_BASE}/session/reset?user_id=${encodeURIComponent(userId)}`,

frontend/src/lib/sensing.ts

@@ -189,6 +189,227 @@ export class GazeTracker {
   }
 }
 
+// ── Head-pose tracker (shake / sharp-nod-dissatisfied) ──────────────────────
+
+export type HeadSignal = "HEAD_SHAKE" | "HEAD_NOD_DISSATISFIED";
+
+const NOSE_TIP = 1;
+
+interface NosePoint {
+  x: number;
+  y: number;
+  t: number;
+}
+
+export interface HeadDebug {
+  dx: number;        // current x displacement from neutral
+  dy: number;        // current y displacement from neutral
+  maxAbsDx: number;  // peak |dx| within the window
+  maxAbsDy: number;  // peak |dy| within the window
+  crossings: number; // side crossings within the window (deadband-filtered)
+}
+
+export class HeadPoseTracker {
+  private neutralX: number | null = null;
+  private neutralY: number | null = null;
+  private history: NosePoint[] = [];
+  private lastEmitTs = 0;
+  private lastDebug: HeadDebug = {
+    dx: 0,
+    dy: 0,
+    maxAbsDx: 0,
+    maxAbsDy: 0,
+    crossings: 0,
+  };
+
+  private static WINDOW_MS = 1000;
+  private static REFRACTORY_MS = 2000;
+  private static SHAKE_AMPLITUDE = 0.015;
+  private static SHAKE_MIN_CROSSINGS = 3;
+  // Per-frame jitter below this magnitude is ignored when counting side
+  // crossings, so micro-fidgets near neutral can't rack up false crossings.
+  private static SHAKE_DEADBAND = 0.005;
+  private static NOD_DROP = 0.06;
+  private static NOD_WINDOW_MS = 600;
+  // Reject "nod" when horizontal motion exceeds this — it's a shake/sway.
+  private static NOD_MAX_HORIZONTAL = 0.015;
+  // Recovery: head must come back to within this of neutral.
+  private static NOD_RECOVERY = 0.015;
+  // The drop must start from near-neutral (not from a tilted resting pose).
+  private static NOD_START_THRESHOLD = 0.015;
+  // Minimum frames between drop start and peak — guards against single-frame
+  // landmark glitches that look like an instantaneous jerk.
+  private static NOD_MIN_DROP_FRAMES = 3;
+  // Minimum frames between peak and recovery — same reason, going up.
+  private static NOD_MIN_RECOVERY_FRAMES = 2;
+
+  calibrate(landmarks: { x: number; y: number }[]): void {
+    if (!landmarks[NOSE_TIP]) return;
+    this.neutralX = landmarks[NOSE_TIP].x;
+    this.neutralY = landmarks[NOSE_TIP].y;
+    this.history = [];
+    this.lastEmitTs = 0;
+  }
+
+  process(landmarks: { x: number; y: number }[]): HeadSignal | null {
+    if (!landmarks[NOSE_TIP]) return null;
+    if (this.neutralX === null || this.neutralY === null) return null;
+
+    const now = performance.now();
+    const nose = landmarks[NOSE_TIP];
+    this.history.push({ x: nose.x, y: nose.y, t: now });
+    const cutoff = now - HeadPoseTracker.WINDOW_MS;
+    this.history = this.history.filter((p) => p.t >= cutoff);
+
+    this.updateDebug(nose);
+
+    if (now - this.lastEmitTs < HeadPoseTracker.REFRACTORY_MS) return null;
+    if (this.history.length < 6) return null;
+
+    const shake = this.detectShake();
+    if (shake) {
+      this.lastEmitTs = now;
+      return shake;
+    }
+
+    const nod = this.detectNod(now);
+    if (nod) {
+      this.lastEmitTs = now;
+      return nod;
+    }
+
+    return null;
+  }
+
+  private updateDebug(nose: { x: number; y: number }): void {
+    if (this.neutralX === null || this.neutralY === null) return;
+    let maxAbsDx = 0;
+    let maxAbsDy = 0;
+    let crossings = 0;
+    let prevSide = 0;
+    for (const p of this.history) {
+      const dx = p.x - this.neutralX;
+      const dy = p.y - this.neutralY;
+      const absDx = Math.abs(dx);
+      maxAbsDx = Math.max(maxAbsDx, absDx);
+      maxAbsDy = Math.max(maxAbsDy, Math.abs(dy));
+      if (absDx < HeadPoseTracker.SHAKE_DEADBAND) continue;
+      const side = dx > 0 ? 1 : -1;
+      if (prevSide !== 0 && side !== prevSide) crossings += 1;
+      prevSide = side;
+    }
+    this.lastDebug = {
+      dx: nose.x - this.neutralX,
+      dy: nose.y - this.neutralY,
+      maxAbsDx,
+      maxAbsDy,
+      crossings,
+    };
+  }
+
+  get debug(): HeadDebug {
+    return this.lastDebug;
+  }
+
+  private detectShake(): HeadSignal | null {
+    if (this.neutralX === null) return null;
+    let crossings = 0;
+    let prevSide = 0;
+    let maxAbs = 0;
+    for (const p of this.history) {
+      const dx = p.x - this.neutralX;
+      const absDx = Math.abs(dx);
+      maxAbs = Math.max(maxAbs, absDx);
+      // Only commit to a side once the displacement clears the deadband —
+      // otherwise sub-millimeter jitter near neutral fakes crossings.
+      if (absDx < HeadPoseTracker.SHAKE_DEADBAND) continue;
+      const side = dx > 0 ? 1 : -1;
+      if (prevSide !== 0 && side !== prevSide) crossings += 1;
+      prevSide = side;
+    }
+    if (
+      crossings >= HeadPoseTracker.SHAKE_MIN_CROSSINGS &&
+      maxAbs >= HeadPoseTracker.SHAKE_AMPLITUDE
+    ) {
+      return "HEAD_SHAKE";
+    }
+    return null;
+  }
+
+  private detectNod(now: number): HeadSignal | null {
+    if (this.neutralX === null || this.neutralY === null) return null;
+    const windowStart = now - HeadPoseTracker.NOD_WINDOW_MS;
+    const recent = this.history.filter((p) => p.t >= windowStart);
+    if (recent.length < 6) return null;
+
+    // Reject if there's significant horizontal motion — that's a shake/sway.
+    let maxAbsDx = 0;
+    for (const p of recent) {
+      maxAbsDx = Math.max(maxAbsDx, Math.abs(p.x - this.neutralX));
+    }
+    if (maxAbsDx > HeadPoseTracker.NOD_MAX_HORIZONTAL) return null;
+
+    // Find the peak (lowest head position) within the window.
+    let maxDrop = 0;
+    let peakIdx = -1;
+    for (let i = 0; i < recent.length; i++) {
+      const drop = recent[i].y - this.neutralY;
+      if (drop > maxDrop) {
+        maxDrop = drop;
+        peakIdx = i;
+      }
+    }
+    if (maxDrop < HeadPoseTracker.NOD_DROP || peakIdx < 0) return null;
+
+    // Find a near-neutral start before the peak — a nod is a deliberate
+    // motion *from* neutral, not a recovery from an already-tilted pose.
+    let startIdx = -1;
+    for (let i = peakIdx - 1; i >= 0; i--) {
+      if (
+        recent[i].y - this.neutralY <=
+        HeadPoseTracker.NOD_START_THRESHOLD
+      ) {
+        startIdx = i;
+        break;
+      }
+    }
+    if (
+      startIdx < 0 ||
+      peakIdx - startIdx < HeadPoseTracker.NOD_MIN_DROP_FRAMES
+    ) {
+      return null;
+    }
+
+    // Recovery: head must return near neutral after the peak.
+    let recoveryIdx = -1;
+    for (let i = peakIdx + 1; i < recent.length; i++) {
+      if (recent[i].y - this.neutralY < HeadPoseTracker.NOD_RECOVERY) {
+        recoveryIdx = i;
+        break;
+      }
+    }
+    if (
+      recoveryIdx < 0 ||
+      recoveryIdx - peakIdx < HeadPoseTracker.NOD_MIN_RECOVERY_FRAMES
+    ) {
+      return null;
+    }
+
+    return "HEAD_NOD_DISSATISFIED";
+  }
+
+  reset(): void {
+    this.neutralX = null;
+    this.neutralY = null;
+    this.history = [];
+    this.lastEmitTs = 0;
+  }
+
+  get calibrated(): boolean {
+    return this.neutralX !== null && this.neutralY !== null;
+  }
+}
+
 // ── Air-writing DTW (ported from backend/sensing/air_writing.py) ─────────────
 
 const INDEX_TIP = 8;

frontend/src/types.ts

@@ -1,12 +1,24 @@
 export type Affect = "HAPPY" | "FRUSTRATED" | "NEUTRAL" | "SURPRISED";
 export type GestureName = "THUMBS_UP" | "THUMBS_DOWN" | "POINTING" | "WAVING";
 export type MemoryBucket = "family" | "medical" | "hobbies" | "daily_routine" | "social";
+export type HeadSignal = "HEAD_SHAKE" | "HEAD_NOD_DISSATISFIED";
+
+export interface HeadDebug {
+  dx: number;
+  dy: number;
+  maxAbsDx: number;
+  maxAbsDy: number;
+  crossings: number;
+}
 
 export interface SensingState {
   affect: Affect | null;
   gestureTag: GestureName | null;
   gazeBucket: MemoryBucket | null;
   airWrittenText: string;
+  headSignal: HeadSignal | null;
+  headCalibrated: boolean;
+  headDebug: HeadDebug;
 }
 
 export interface Persona {
@@ -23,6 +35,13 @@ export interface ChatRequest {
   gesture_tag: GestureName | null;
   gaze_bucket: MemoryBucket | null;
   air_written_text: string | null;
+  head_signal?: HeadSignal | null;
+}
+
+export interface TurnaroundRequest {
+  user_id: string;
+  turn_id?: number;
+  head_signal?: HeadSignal | null;
 }
 
 export interface LatencyLog {
@@ -57,6 +76,7 @@ export interface ChatResponse {
   latency: LatencyLog;
   guardrail_passed: boolean;
   eval_scores: EvalScores | null;
+  turn_id: number;
 }
 
 export interface ChatMessage {
@@ -65,4 +85,7 @@ export interface ChatMessage {
   latency?: LatencyLog;
   affect?: string;
   evalScores?: EvalScores | null;
+  turnId?: number;
+  rephrased?: boolean;
+  isTurnaround?: boolean;
 }