chore(hf): sync HomePilot to HF Space

.gitattributes

@@ -1,9 +1,9 @@
-*.jpeg filter=lfs diff=lfs merge=lfs -text
-*.woff filter=lfs diff=lfs merge=lfs -text
-*.ico filter=lfs diff=lfs merge=lfs -text
 *.hpersona filter=lfs diff=lfs merge=lfs -text
-*.png filter=lfs diff=lfs merge=lfs -text
 *.jpg filter=lfs diff=lfs merge=lfs -text
-*.webp filter=lfs diff=lfs merge=lfs -text
 *.svg filter=lfs diff=lfs merge=lfs -text
 *.woff2 filter=lfs diff=lfs merge=lfs -text
+*.ico filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.woff filter=lfs diff=lfs merge=lfs -text

backend/app/main.py

@@ -159,6 +159,44 @@ app.include_router(teams_router)
 from .teams.bridge_routes import router as teams_bridge_router
 app.include_router(teams_bridge_router)
 
+# --- Voice call (/v1/voice-call/*) — ADDITIVE, FEATURE-FLAGGED ---------------
+# Fully off by default. Enable with ``VOICE_CALL_ENABLED=true``. If anything
+# in the voice_call module raises on import (bad migration, missing dep, …)
+# we swallow it so the rest of the app stays up — this feature is optional
+# and must never take production down.
+try:
+    from .voice_call.config import load as _voice_call_load_config
+    _voice_call_cfg = _voice_call_load_config()
+    if _voice_call_cfg.enabled:
+        from .voice_call.router import build_router as _build_vc_router
+        from .voice_call.router import build_ws_router as _build_vc_ws_router
+        app.include_router(_build_vc_router(_voice_call_cfg))
+        app.include_router(_build_vc_ws_router(_voice_call_cfg))
+        print("[voice_call] enabled — routes mounted under /v1/voice-call")
+except Exception as _vc_err:  # noqa: BLE001
+    # Deliberate broad catch: this entire feature is optional. Log and move on.
+    print(f"[voice_call] DISABLED due to import error: {_vc_err}")
+
+# --- Persona call (/v1/persona-call/*) — ADDITIVE, FEATURE-FLAGGED -----------
+# Phone-call conversational dynamics + per-turn system suffix composer.
+# Off by default. Enable with ``PERSONA_CALL_ENABLED=true``. The module
+# operates behind voice_call/ws.py — the HTTP router is minor (facets
+# lookup, state inspection, shadow-directive audit). Independent flag so
+# it can ship in shadow-compose mode (``PERSONA_CALL_APPLY=false``)
+# before any prompt surface actually changes.
+try:
+    from .persona_call.config import load as _persona_call_load_config
+    _persona_call_cfg = _persona_call_load_config()
+    if _persona_call_cfg.enabled:
+        from .persona_call.router import build_router as _build_pc_router
+        app.include_router(_build_pc_router(_persona_call_cfg))
+        print(
+            f"[persona_call] enabled (apply={_persona_call_cfg.apply}) — "
+            "routes mounted under /v1/persona-call"
+        )
+except Exception as _pc_err:  # noqa: BLE001
+    print(f"[persona_call] DISABLED due to import error: {_pc_err}")
+
 # Include Marketplace routes (/v1/marketplace/*)
 app.include_router(marketplace_router)
 

backend/app/persona_call/__init__.py

@@ -0,0 +1,33 @@
+"""
+persona_call — phone-call conversational dynamics on top of voice_call.
+
+Adds nothing to a persona's BASE system prompt. Instead, when a persona
+is on a live phone call, this module composes a small per-turn system
+*suffix* that:
+
+  * tells the persona it is currently on a phone call (not chat),
+  * applies one research-grounded rule from the design doc (e.g.
+    "skip 'how are you' after 9 pm local"),
+  * enforces the two-phase closing handshake at the state machine level
+    (the only place the model is overridden rather than advised),
+  * emits server-originated *backchannels* and *fillers* on a separate
+    low-volume stream so the user hears continuers + thinking sounds
+    without waiting for a full LLM turn.
+
+Fully additive + feature-flagged. With ``PERSONA_CALL_ENABLED=false``
+(the default) this module is never imported and no row is ever written
+to the ``persona_call_state`` table.
+
+Published research baked in:
+  Schegloff 1968, Schegloff & Sacks 1973, Sacks/Schegloff/Jefferson 1974,
+  Jefferson 1984, Stivers et al. 2009, Clark & French 1981,
+  Local & Walker 2012, OpenAI Realtime Prompting Guide, Sesame 2025.
+
+Call-centre software-engineering practice applied:
+  single-source-of-truth state machine; every behavior has a named
+  module and a test anchor; deterministic telemetry counters for
+  naturalness SLOs; zero coupling to persona storage.
+"""
+from __future__ import annotations
+
+__all__ = ["config", "directive", "router"]

backend/app/persona_call/backchannel.py

@@ -0,0 +1,122 @@
+"""
+Server-originated backchannel emission — the separate low-volume
+stream (per the user's chosen default).
+
+A backchannel is NOT a turn. It's a "mm-hm" / "yeah" / "got it" the
+server emits *while the user is still speaking* so the caller hears
+recipiency instead of silence. Research (Jefferson 1984) shows humans
+emit one every 2–3 clauses on the phone — they compensate for the
+absence of visual nods.
+
+Design rules baked in:
+
+  * Token pulled from the persona's own pool (VoiceFacets.ack_tokens)
+    so Darkangel666 sounds like Darkangel666 even when backchanneling.
+  * Cadence: at most one per ``backchannel_min_gap_ms``, and only after
+    ``backchannel_clause_trigger`` clause boundaries in the CURRENT
+    user utterance.
+  * Anti-repetition: never the same token two backchannels in a row.
+  * Played at ``backchannel_volume_db`` below the main TTS stream so
+    it overlaps the user's voice without fighting it (the client
+    applies the gain — this module just names the dB).
+  * Skipped entirely when ``facets.backchannel_rate`` is 0.
+
+The emission itself is a WS event; this module picks the token and
+decides IF/WHEN. The actual ``ws.send`` call lives in ws.py.
+"""
+from __future__ import annotations
+
+import random
+import re
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from .config import PersonaCallConfig
+from .facets import VoiceFacets
+
+
+# Rough clause boundaries — commas, semicolons, sentence enders,
+# conjunctions that start a clause ("and then…", "but…", "so…").
+# Runs on the partial STT transcript, so it fires as the user speaks.
+_CLAUSE_BOUNDARY = re.compile(
+    r"("
+    r"[,;]|[.!?]\s+|"              # punctuation
+    r"\b(and|but|so|because|then|however|actually)\b\s"  # discourse markers
+    r")",
+    re.I,
+)
+
+
+def count_clause_boundaries(partial_text: str) -> int:
+    """How many clause boundaries have been uttered in the current
+    user turn so far."""
+    if not partial_text:
+        return 0
+    return len(_CLAUSE_BOUNDARY.findall(partial_text))
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def choose_token(
+    facets: VoiceFacets,
+    *,
+    recent_acks: List[str],
+    seed_utterance: str = "",
+) -> Optional[str]:
+    """Pick a backchannel token that is (a) in the persona's pool and
+    (b) not the most recent one. Returns None iff the pool is empty.
+
+    Mild stance-sensitivity: if the partial utterance ended with a
+    rising question mark, we bias toward stance tokens ('oh really?',
+    'yeah?'); falling-period endings bias toward acknowledgments.
+    """
+    pool = [t for t in facets.ack_tokens if t]
+    if not pool:
+        return None
+    last = (recent_acks[-1].lower() if recent_acks else "")
+    candidates = [t for t in pool if t.lower() != last] or pool
+    # Stance nudge — prefer single-syllable quick tokens on
+    # exclamations / questions, longer ones on plain pauses.
+    is_query = bool(seed_utterance.rstrip().endswith(("?", "!")))
+    if is_query:
+        candidates = sorted(candidates, key=lambda t: len(t))
+    return random.choice(candidates)
+
+
+def should_emit(
+    *,
+    partial_text: str,
+    last_backchannel_ms: int,
+    facets: VoiceFacets,
+    cfg: PersonaCallConfig,
+) -> bool:
+    """True iff we should send a backchannel right now. Pure decision;
+    no side effects."""
+    if facets.backchannel_rate <= 0:
+        return False
+    # Scale the clause threshold by the persona's own rate. Low-rate
+    # personas (e.g. reserved / clinical) need more clauses before a
+    # backchannel; chatty personas need fewer.
+    trigger = max(
+        1, int(round(cfg.backchannel_clause_trigger / max(0.25, facets.backchannel_rate)))
+    )
+    if count_clause_boundaries(partial_text) < trigger:
+        return False
+    min_gap = int(cfg.backchannel_min_gap_ms / max(0.25, facets.backchannel_rate))
+    if _now_ms() - int(last_backchannel_ms or 0) < min_gap:
+        return False
+    return True
+
+
+def build_event(token: str, volume_db: float) -> Dict[str, Any]:
+    """Shape the WS event payload ws.py will serialize."""
+    return {
+        "type": "assistant.backchannel",
+        "payload": {
+            "token": token,
+            "volume_db": float(volume_db),
+            "ts": _now_ms(),
+        },
+    }

backend/app/persona_call/closing.py

@@ -0,0 +1,102 @@
+"""
+Two-phase closing handshake — the one place we *enforce* instead of
+advise.
+
+Why enforced: LLMs reliably collapse Schegloff's 3–6-turn closing
+into "Goodbye!" the moment they hear an "ok". Humans don't. The
+handshake is a short, mandatory state transition that keeps the
+persona from hanging up before the caller does.
+
+Flow (per Schegloff & Sacks 1973, *Opening up Closings*):
+
+    user says "ok" / "alright" / "I should go" / "thanks, that's all"
+              │
+              ▼
+    state.phase := 'pre_closing'
+    pre_closing_trigger := <the user's token>
+              │
+              ▼
+    persona reply directive FORCES a pre-closing token reply:
+        - one short softener from facets.pre_closing_tokens
+        - no "bye", no "goodbye", no "take care" yet
+              │
+              ▼  (next user turn)
+    if user says "bye" / "talk later" / "see ya":
+        persona reply directive FORCES a mirrored two-part close:
+            <softener>, <terminal>
+        e.g. "take care, bye"
+    else:
+        state stays in 'pre_closing'; persona speaks a normal turn.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from .facets import VoiceFacets
+
+
+# User utterances that start a closing (pre-closing trigger).
+# Kept tight to avoid false positives mid-conversation.
+_PRE_CLOSE_PATTERNS = [
+    re.compile(p, re.I) for p in [
+        r"^\s*(ok|okay|alright|ok\s+then)\s*[.!?]?\s*$",
+        r"\b(i should (go|run|get back)|gotta (go|run)|need to go)\b",
+        r"\b(thanks[, ]+(that'?s|that is)\s+(all|it))\b",
+        r"\b(talk (to you )?(later|soon)|call (you )?(later|back))\b",
+    ]
+]
+
+# Pure terminal — "bye"-family tokens that complete the exchange.
+_TERMINAL_PATTERNS = [
+    re.compile(p, re.I) for p in [
+        r"^\s*(bye|good[\- ]?bye|later|see ya|see you|ciao)\s*[.!?]?\s*$",
+        r"\b(bye bye|byebye)\b",
+    ]
+]
+
+
+def is_pre_closing_trigger(user_text: str) -> bool:
+    """True iff the user just began a closing sequence."""
+    if not user_text:
+        return False
+    return any(p.search(user_text) for p in _PRE_CLOSE_PATTERNS)
+
+
+def is_terminal(user_text: str) -> bool:
+    """True iff the user said goodbye — the second half of the
+    two-phase close. Matched INDEPENDENTLY of the pre-close trigger
+    so the state machine can skip straight to terminal if the user
+    blurts out "bye!" without a prior "ok"."""
+    if not user_text:
+        return False
+    return any(p.search(user_text) for p in _TERMINAL_PATTERNS)
+
+
+# ── directive fragments for each phase ───────────────────────────────
+
+def pre_closing_directive(facets: VoiceFacets, trigger: Optional[str]) -> str:
+    """Directive the composer injects when we're in 'pre_closing'
+    but the user hasn't said 'bye' yet."""
+    pool = ", ".join(facets.pre_closing_tokens[:4])
+    trig = f'"{trigger}"' if trigger else "a closing cue"
+    return (
+        f"The caller offered a pre-closing ({trig}). "
+        "Reciprocate with ONE matching soft pre-closing token — "
+        f"something from: {pool}. Do NOT say 'goodbye' yet. "
+        "Keep the turn to ≤ 7 words and leave the actual goodbye to "
+        "the caller. Research: Schegloff & Sacks 1973 — the terminal "
+        "exchange is the caller's to initiate."
+    )
+
+
+def terminal_directive(facets: VoiceFacets) -> str:
+    """Directive for the actual bye-for-bye turn."""
+    softeners = ", ".join(facets.pre_closing_tokens[:3])
+    closings = ", ".join(facets.closing_tokens[:3])
+    return (
+        "The caller just said goodbye. Mirror them with a TWO-PART "
+        f"close: one softener (e.g. {softeners}) followed by one "
+        f"terminal (e.g. {closings}). Never a single bare 'goodbye'. "
+        "Keep it to ≤ 6 words. After this turn the call ends."
+    )

backend/app/persona_call/config.py

@@ -0,0 +1,102 @@
+"""
+Feature flags + runtime knobs for persona_call.
+
+Every knob is an env var with a safe default. The module ships off.
+
+Two flags, not one, so "shadow compose" (§ rollout P1 in the design)
+can run without changing any outgoing prompt:
+
+  PERSONA_CALL_ENABLED  — master. When false, this module is never
+                          loaded into the app.
+  PERSONA_CALL_APPLY    — when ENABLED=true but APPLY=false, the
+                          composer runs and its output is logged to
+                          ``persona_call_directives`` but NOT injected
+                          as a system message. Lets us collect
+                          production directives for a week before
+                          letting them shape turns.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _bool_env(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _int_env(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+def _float_env(name: str, default: float) -> float:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+@dataclass(frozen=True)
+class PersonaCallConfig:
+    """Resolved at every :func:`load` call — cheap, keep fresh for tests."""
+
+    # Master flag. False = this module is not imported into main.py.
+    enabled: bool
+    # When True, the composed directive is actually sent to the model.
+    # When False, it's logged only (shadow mode).
+    apply: bool
+
+    # Backchannel stream thresholds.
+    backchannel_clause_trigger: int     # emit after N clause boundaries
+    backchannel_min_gap_ms: int          # don't emit more often than this
+    backchannel_volume_db: float         # played at -6 dB by default
+
+    # Filler emission during tool/LLM wait (Stivers 700 ms trouble line).
+    filler_emit_after_ms: int            # default 600
+
+    # Phase machine thresholds.
+    how_are_you_late_hour: int           # skip "how are you" at or after
+    late_night_brevity_hour: int         # enter brevity bias at or after
+    late_night_brevity_hour_end: int     # exit brevity bias at or before
+
+    # Anti-repetition ledger sizes.
+    ack_ledger_window: int
+    opener_ledger_window: int
+
+    # Closing handshake — the one enforced override.
+    closing_trigger_tokens_extra: str    # comma-separated, user-supplied
+
+    # Reason-for-call fallback turn.
+    reason_fallback_turn: int            # at this turn, ask if nothing heard
+
+
+def load() -> PersonaCallConfig:
+    return PersonaCallConfig(
+        enabled=_bool_env("PERSONA_CALL_ENABLED", False),
+        apply=_bool_env("PERSONA_CALL_APPLY", True),
+        backchannel_clause_trigger=_int_env("PERSONA_CALL_BC_CLAUSES", 2),
+        backchannel_min_gap_ms=_int_env("PERSONA_CALL_BC_MIN_GAP_MS", 1800),
+        backchannel_volume_db=_float_env("PERSONA_CALL_BC_VOL_DB", -6.0),
+        filler_emit_after_ms=_int_env("PERSONA_CALL_FILLER_AFTER_MS", 600),
+        how_are_you_late_hour=_int_env("PERSONA_CALL_HAY_LATE_HOUR", 21),
+        late_night_brevity_hour=_int_env("PERSONA_CALL_LATE_HOUR", 22),
+        late_night_brevity_hour_end=_int_env("PERSONA_CALL_LATE_HOUR_END", 6),
+        ack_ledger_window=_int_env("PERSONA_CALL_ACK_WINDOW", 5),
+        opener_ledger_window=_int_env("PERSONA_CALL_OPENER_WINDOW", 3),
+        closing_trigger_tokens_extra=os.getenv(
+            "PERSONA_CALL_CLOSING_EXTRA_TOKENS", ""
+        ),
+        reason_fallback_turn=_int_env("PERSONA_CALL_REASON_FALLBACK_TURN", 3),
+    )

backend/app/persona_call/context.py

@@ -0,0 +1,191 @@
+"""
+Environmental + caller-context inputs for the per-turn composer.
+
+Three kinds of signal, all computed on demand (never stored):
+
+  (a) Local clock — hour, day-of-week, weekend bit. Resolved from the
+      caller's ``device_info.tz`` when present, else server tz, else UTC.
+      Late-night brevity and morning-energy rules key off this.
+
+  (b) Recency — weeks since this (user, persona) last spoke. Drives the
+      "hey, it's been a while" one-shot acknowledgment.
+
+  (c) Caller-state extraction from STT — a tiny regex/keyword classifier
+      that runs on every user utterance:
+        * mobility  (driving / walking / on transit)
+        * time pressure  (quick question, running late, stepping out)
+        * reason-for-call sentence  (turn ≤ 3)
+
+All inference is local + deterministic. No LLM calls in this module.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+# ── local clock ───────────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class CallEnv:
+    local_hour: int
+    day_of_week: int          # 0 Mon … 6 Sun
+    is_weekend: bool
+    weeks_since_last_call: int    # -1 when never
+    had_unfinished_topic: bool
+    resumed_from_topic: Optional[str] = None
+
+
+def _resolve_tz(tz_name: Optional[str]):
+    """Best-effort tz resolution. Returns a tzinfo or UTC."""
+    if not tz_name:
+        return _dt.timezone.utc
+    try:
+        # Python 3.9+ stdlib
+        from zoneinfo import ZoneInfo
+        return ZoneInfo(tz_name)
+    except Exception:
+        return _dt.timezone.utc
+
+
+def compute_env(
+    *,
+    tz: Optional[str] = None,
+    weeks_since_last_call: int = -1,
+    resumed_from_topic: Optional[str] = None,
+    now: Optional[_dt.datetime] = None,
+) -> CallEnv:
+    """Build a CallEnv from primitive inputs. No DB access here —
+    ws.py does the session lookups and calls this with the results so
+    this function stays cheap and unit-testable."""
+    tzinfo = _resolve_tz(tz)
+    current = (now or _dt.datetime.now(tz=_dt.timezone.utc)).astimezone(tzinfo)
+    return CallEnv(
+        local_hour=current.hour,
+        day_of_week=current.weekday(),
+        is_weekend=current.weekday() >= 5,
+        weeks_since_last_call=weeks_since_last_call,
+        had_unfinished_topic=bool(resumed_from_topic),
+        resumed_from_topic=resumed_from_topic,
+    )
+
+
+# ── caller-state extraction ───────────────────────────────────────────
+
+# Deliberately narrow regexes. False positives in this module produce
+# a directive like "the caller is driving — keep it to one sentence",
+# which is always a safe fallback; false negatives lose the rule, which
+# is also safe. So tight > comprehensive.
+
+_MOBILITY_DRIVING = re.compile(
+    r"\b(i[' ]?m|i am|currently|just)?\s*(driving|behind the wheel|on the road|in the car)\b",
+    re.I,
+)
+_MOBILITY_WALKING = re.compile(
+    r"\b(i[' ]?m|i am)?\s*(walking|out on a walk|going for a walk)\b",
+    re.I,
+)
+_MOBILITY_TRANSIT = re.compile(
+    r"\b(on (the )?(train|subway|tube|metro|bus)|at the (station|airport)|boarding)\b",
+    re.I,
+)
+_TIME_PRESSURE = re.compile(
+    r"\b("
+    r"quick question|only have a minute|short on time|running late|"
+    r"stepping out|have to run|in a rush|in a hurry|gotta be quick"
+    r")\b",
+    re.I,
+)
+
+# Very loose reason-for-call cues for turn ≤ 3. We don't need to
+# extract a perfect paraphrase — we just need a yes/no flag so the
+# directive composer can decide whether the phase machine can move
+# out of 'opening'.
+#
+# Intentionally does NOT match "quick question" — that is a
+# time-pressure signal, not an articulated reason. The composer reads
+# both signals and will still skip 'how are you' on time pressure
+# alone; we just don't want to prematurely promote phase → topic
+# before the skip rule fires.
+_REASON_CUE = re.compile(
+    r"\b("
+    r"i('?m| am)?\s+calling (about|to|because|for)|"
+    r"i wanted to (talk|ask|check|discuss|tell)|"
+    r"the reason i('?m| am) calling|"
+    r"i need (to know|help with|your help|a hand)"
+    r")\b",
+    re.I,
+)
+
+
+@dataclass
+class CallerSignal:
+    driving: bool = False
+    walking: bool = False
+    transit: bool = False
+    time_pressured: bool = False
+    reason_expressed: bool = False
+    reason_text: str = ""
+
+    def merge(self, other: "CallerSignal") -> "CallerSignal":
+        """Accumulate across multiple user utterances in one call.
+        Once a flag is set, it stays set until the phase machine
+        resets it."""
+        return CallerSignal(
+            driving=self.driving or other.driving,
+            walking=self.walking or other.walking,
+            transit=self.transit or other.transit,
+            time_pressured=self.time_pressured or other.time_pressured,
+            reason_expressed=self.reason_expressed or other.reason_expressed,
+            reason_text=self.reason_text or other.reason_text,
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "driving": self.driving,
+            "walking": self.walking,
+            "transit": self.transit,
+            "time_pressured": self.time_pressured,
+            "reason_expressed": self.reason_expressed,
+            "reason_text": self.reason_text,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Optional[Dict[str, Any]]) -> "CallerSignal":
+        d = d or {}
+        return cls(
+            driving=bool(d.get("driving")),
+            walking=bool(d.get("walking")),
+            transit=bool(d.get("transit")),
+            time_pressured=bool(d.get("time_pressured")),
+            reason_expressed=bool(d.get("reason_expressed")),
+            reason_text=str(d.get("reason_text") or ""),
+        )
+
+
+def classify_utterance(text: str) -> CallerSignal:
+    """Extract a CallerSignal from one user turn. O(len(text)) regex."""
+    if not text:
+        return CallerSignal()
+    sig = CallerSignal(
+        driving=bool(_MOBILITY_DRIVING.search(text)),
+        walking=bool(_MOBILITY_WALKING.search(text)),
+        transit=bool(_MOBILITY_TRANSIT.search(text)),
+        time_pressured=bool(_TIME_PRESSURE.search(text)),
+    )
+    m = _REASON_CUE.search(text)
+    if m:
+        sig.reason_expressed = True
+        # Take the remainder of the sentence as the reason paraphrase
+        # — a cheap heuristic good enough for the phase machine.
+        start = m.end()
+        remainder = text[start:].strip()
+        end = len(remainder)
+        for stop in (".", "?", "!", "\n"):
+            idx = remainder.find(stop)
+            if idx != -1 and idx < end:
+                end = idx
+        sig.reason_text = remainder[:end].strip()[:140]
+    return sig

backend/app/persona_call/directive.py

@@ -0,0 +1,365 @@
+"""
+Per-turn system-suffix composer.
+
+**Core invariant of this whole module** (the product promise):
+
+    The persona's own system prompt is NEVER touched. `compose()`
+    only produces a short suffix that is appended as a SEPARATE
+    system message in addition to whatever the /v1/chat/completions
+    endpoint already injects for the persona. When the call ends,
+    the suffix is gone; the persona's chat behavior is identical to
+    what it was before the call started.
+
+The suffix is assembled from five small paragraphs. Each paragraph
+is independently testable and individually gated by the current
+phase / time / caller-context, so on an uneventful turn the suffix
+is only ~4 lines long.
+
+The five stages, in assembly order:
+
+    1. _base_phone_frame       persona-neutral phone register
+    2. _phase_frame            opening / topic / pre_closing / closed
+    3. _context_frame          late-night / driving / resumed-topic
+    4. _repetition_frame       ledger-enforced variety
+    5. _latency_frame          filler rule for thinking pauses
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from . import closing, repeat, state as state_mod, store
+from .config import PersonaCallConfig
+from .context import CallEnv, CallerSignal
+from .facets import VoiceFacets
+
+
+# ── public result type ───────────────────────────────────────────────
+
+@dataclass
+class ComposedDirective:
+    """Return value of :func:`compose`. Two independently useful fields:
+
+    * ``system_suffix`` — the text we append as an additional system
+      message. If :class:`PersonaCallConfig`.apply is False (shadow
+      mode), this is logged but not actually sent to the model.
+    * ``post_directives`` — the list of individual rules we applied,
+      one string per rule, in the order composed. Dumped into
+      ``persona_call_directives.post_directives`` for observability.
+    """
+    session_id: str
+    phase: str
+    turn_index: int
+    system_suffix: str
+    post_directives: List[str] = field(default_factory=list)
+
+
+# ── paragraph builders ────────────────────────────────────────────────
+
+def _base_phone_frame(facets: VoiceFacets) -> str:
+    """Persona-neutral phone register. Same for every persona; the
+    persona's identity is NOT asserted here — that stays in the
+    persona's own system prompt which is already active."""
+    return (
+        "[PHONE CALL MODE — appended only for the duration of this call]\n"
+        "You are on a live phone call. Spoken, not typed. "
+        "No bullet points, no stage directions (never output '*smiles*' "
+        "or similar), no markdown headers. "
+        f"Keep replies in the {facets.typical_reply_sentences}-sentence range, "
+        f"≤ {facets.sentence_max_words} words per sentence. "
+        f"Tone: {facets.tone_line}."
+    )
+
+
+def _phase_frame(
+    *,
+    phase: str,
+    turn_index: int,
+    skipped_how_are_you: bool,
+    asked_reason_fallback: bool,
+    facets: VoiceFacets,
+    env: CallEnv,
+    caller: CallerSignal,
+    pre_closing_trigger: Optional[str],
+    cfg: PersonaCallConfig,
+) -> tuple[str, List[str]]:
+    """Return (paragraph, rule_names_applied) for the current phase."""
+    rules: List[str] = []
+
+    if phase == state_mod.OPENING:
+        # Turn 0 — Schegloff summons-answer.
+        if turn_index == 0:
+            rules.append("opening.summons_answer")
+            return (
+                "This is turn 0. Reply with ONE short line of recognition "
+                "— acknowledge you're there, use the caller's name if you "
+                "know it, ≤ 6 words. Do NOT launch into topic.",
+                rules,
+            )
+        # Turn ≥ 1 — decide on "how are you" exactly once.
+        if not skipped_how_are_you and turn_index <= 2:
+            # Skip "how are you" if: late hour, caller is pressed, or
+            # caller already expressed a reason.
+            should_skip = (
+                env.local_hour >= cfg.how_are_you_late_hour
+                or caller.time_pressured
+                or caller.reason_expressed
+            )
+            if should_skip:
+                rules.append("opening.skip_how_are_you")
+                return (
+                    "Skip the 'how are you?' exchange this time — the "
+                    "caller is either pressed, late, or already on-topic. "
+                    "Move directly to hearing them out.",
+                    rules,
+                )
+            rules.append("opening.how_are_you_once")
+            return (
+                "One brief round of 'how are you?' is appropriate now. "
+                "Ask once, let them answer, then pause for their reason "
+                "for calling. Do not stack this with another question.",
+                rules,
+            )
+        # Opening past turn 2 with no reason and no fallback asked.
+        if (
+            not caller.reason_expressed
+            and not asked_reason_fallback
+            and turn_index >= cfg.reason_fallback_turn
+        ):
+            rules.append("opening.reason_fallback_ask")
+            return (
+                "The caller has not said why they're calling yet. "
+                "Ask gently, in one sentence: something like "
+                "'what's on your mind today?' or 'what's up?'",
+                rules,
+            )
+        rules.append("opening.default")
+        return (
+            "Still in the opening. Keep replies short and oriented to "
+            "the caller's lead.",
+            rules,
+        )
+
+    if phase == state_mod.TOPIC:
+        rules.append("topic.default")
+        return (
+            "Mid-call. Be responsive: if the caller asked a question, "
+            "answer it before asking one back. Ask at most ONE follow-up "
+            "per turn — phone calls tolerate fewer questions per turn "
+            "than chat does.",
+            rules,
+        )
+
+    if phase == state_mod.PRE_CLOSING:
+        rules.append("closing.pre_closing_handshake")
+        return closing.pre_closing_directive(facets, pre_closing_trigger), rules
+
+    if phase == state_mod.CLOSED:
+        rules.append("closing.terminal")
+        return closing.terminal_directive(facets), rules
+
+    return "", rules
+
+
+def _context_frame(
+    env: CallEnv, caller: CallerSignal, cfg: PersonaCallConfig,
+) -> tuple[str, List[str]]:
+    """Situational rules. Paragraphs only emit when the predicate fires,
+    so uneventful turns get no context frame at all."""
+    lines: List[str] = []
+    rules: List[str] = []
+
+    # Late-night brevity (decision-fatigue bias).
+    late = (
+        env.local_hour >= cfg.late_night_brevity_hour
+        or env.local_hour <= cfg.late_night_brevity_hour_end
+    )
+    if late:
+        rules.append("context.late_night_brevity")
+        lines.append(
+            f"Local clock: {env.local_hour:02d}:00 for the caller. "
+            "It's late — keep replies to one sentence when you can, "
+            "offer to continue tomorrow for anything complex."
+        )
+
+    # Driving — safety/attention bias.
+    if caller.driving:
+        rules.append("context.driving")
+        lines.append(
+            "The caller is DRIVING. One-sentence answers, no multi-part "
+            "questions, never require a yes/no decision unless it's "
+            "genuinely urgent."
+        )
+    elif caller.walking or caller.transit:
+        rules.append("context.mobile")
+        lines.append(
+            "The caller is mobile. Keep it brief and well-paced — they "
+            "may lose signal or attention momentarily."
+        )
+
+    # Weeks-since-last-call resumption (fire at most once per call; the
+    # persona_call_state doesn't need a separate flag because this only
+    # fires when the topic hasn't been acknowledged yet — the composer
+    # sees the same state each turn until the persona says something).
+    if env.weeks_since_last_call >= 3:
+        rules.append("context.resumption")
+        lines.append(
+            f"It has been ≈{env.weeks_since_last_call} weeks since this "
+            "caller last spoke with you. One natural acknowledgment of "
+            "the gap is appropriate — do NOT make it the whole turn, "
+            "and say it only once this call."
+        )
+    if env.resumed_from_topic:
+        rules.append("context.resume_topic")
+        lines.append(
+            f"Unfinished topic from a prior call: {env.resumed_from_topic!r}. "
+            "Offer to pick it back up if natural, but don't force it."
+        )
+
+    return ("\n".join(lines) if lines else ""), rules
+
+
+def _repetition_frame(
+    state: Dict[str, Any], facets: VoiceFacets,
+) -> tuple[str, List[str]]:
+    text = repeat.forbid_clause(state, facets)
+    return (text, ["repeat.ledger"] if text else [])
+
+
+def _latency_frame(facets: VoiceFacets) -> tuple[str, List[str]]:
+    thinking = ", ".join(facets.thinking_tokens[:3])
+    return (
+        "If you need a beat to think, start your reply with a short "
+        f"filler from: {thinking}. Never produce a long silence — "
+        "callers read silence on the phone as trouble.",
+        ["latency.filler_rule"],
+    )
+
+
+# ── public compose() ──────────────────────────────────────────────────
+
+def compose(
+    *,
+    session_id: str,
+    persona_id: Optional[str],
+    user_text: str,
+    env: CallEnv,
+    cfg: PersonaCallConfig,
+    facets: Optional[VoiceFacets] = None,
+) -> ComposedDirective:
+    """Build the per-turn directive.
+
+    1. Advances the phase machine on the user utterance.
+    2. Composes the five paragraphs.
+    3. Persists the directive in shadow mode OR applies it.
+    """
+    from .facets import for_persona_id
+    _facets = facets if facets is not None else for_persona_id(persona_id)
+
+    # Step 1: phase machine.
+    new_state = state_mod.advance_on_user_utterance(
+        session_id=session_id,
+        user_text=user_text,
+        reason_fallback_turn=cfg.reason_fallback_turn,
+    )
+    phase = str(new_state.get("phase") or state_mod.OPENING)
+    turn_index = int(new_state.get("turn_index") or 0)
+
+    # The caller_context column is already updated by the phase machine,
+    # so re-derive the CallerSignal from it for the composer.
+    caller = CallerSignal.from_dict(
+        new_state.get("caller_context")
+        if isinstance(new_state.get("caller_context"), dict) else {}
+    )
+
+    # Step 2: five paragraphs.
+    rules_all: List[str] = []
+    parts: List[str] = [_base_phone_frame(_facets)]
+    rules_all.append("base.phone_frame")
+
+    phase_para, r = _phase_frame(
+        phase=phase,
+        turn_index=turn_index - 1,  # phase machine incremented already
+        skipped_how_are_you=bool(new_state.get("skipped_how_are_you")),
+        asked_reason_fallback=bool(new_state.get("asked_reason_fallback")),
+        facets=_facets,
+        env=env,
+        caller=caller,
+        pre_closing_trigger=(
+            str(new_state.get("pre_closing_trigger") or "")
+            if new_state.get("pre_closing_trigger") else None
+        ),
+        cfg=cfg,
+    )
+    if phase_para:
+        parts.append(phase_para)
+        rules_all.extend(r)
+
+    ctx_para, r = _context_frame(env, caller, cfg)
+    if ctx_para:
+        parts.append(ctx_para)
+        rules_all.extend(r)
+
+    rep_para, r = _repetition_frame(new_state, _facets)
+    if rep_para:
+        parts.append(rep_para)
+        rules_all.extend(r)
+
+    lat_para, r = _latency_frame(_facets)
+    parts.append(lat_para)
+    rules_all.extend(r)
+
+    system_suffix = "\n\n".join(parts).strip()
+
+    # Step 3: persist + (maybe) apply.
+    store.record_directive(
+        session_id=session_id,
+        turn_index=turn_index,
+        phase=phase,
+        applied=cfg.apply,
+        system_suffix=system_suffix,
+        post_directives=rules_all,
+    )
+
+    # If we asked 'how are you' or the reason-fallback, set the flags
+    # so we don't do it again.
+    if "opening.how_are_you_once" in rules_all:
+        state_mod.mark_how_are_you_decision(session_id, skipped=False)
+    if "opening.skip_how_are_you" in rules_all:
+        state_mod.mark_how_are_you_decision(session_id, skipped=True)
+    if "opening.reason_fallback_ask" in rules_all:
+        state_mod.mark_reason_fallback_asked(session_id)
+
+    return ComposedDirective(
+        session_id=session_id,
+        phase=phase,
+        turn_index=turn_index,
+        system_suffix=system_suffix if cfg.apply else "",
+        post_directives=rules_all,
+    )
+
+
+def record_persona_reply(
+    *,
+    session_id: str,
+    persona_id: Optional[str],
+    reply: str,
+    cfg: PersonaCallConfig,
+) -> None:
+    """Called after the LLM reply comes back. Rolls the anti-repetition
+    ledger forward so the next turn can forbid the just-used token."""
+    from .facets import for_persona_id
+    _facets = for_persona_id(persona_id)
+    state = store.ensure_state(session_id)
+    new_acks, new_openers = repeat.record_reply(
+        state,
+        reply,
+        _facets,
+        cfg_ack_window=cfg.ack_ledger_window,
+        cfg_opener_window=cfg.opener_ledger_window,
+    )
+    store.update_state(
+        session_id,
+        recent_acks=new_acks,
+        recent_openers=new_openers,
+    )

backend/app/persona_call/facets.py

@@ -0,0 +1,180 @@
+"""
+Per-persona ``voice_facets`` — non-destructive voice personalization.
+
+Facets live in an OPTIONAL field on the persona manifest
+(``persona.voice_facets``). Any existing persona with no facets gets
+the neutral-English default — its chat behavior is completely
+unchanged either way.
+
+The facets object drives four things at runtime:
+
+  * backchannel token pools (``mm``, ``yeah``, ``right`` etc.)
+  * pre-closing + closing token pools
+  * filler / thinking tokens for the latency hook
+  * scalar voice knobs (warmth, pace, formality) interpolated into
+    the per-turn system suffix as raw numbers — the model reads the
+    number, not an adjective. This avoids the same three adjectives
+    bleeding into every reply.
+
+The *base system prompt* of the persona is never touched. This file
+never rewrites a persona; it only reads the optional facets field.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# ── Default facets — applied when a persona ships no voice_facets ───
+#
+# Values chosen from the CA literature + common-sense phone norms.
+# Token pools kept short on purpose: fewer options → easier anti-
+# repetition tracking → cleaner entropy metric.
+
+_DEFAULT_ACKS     = ["mm", "mm-hm", "yeah", "right", "got it", "okay"]
+_DEFAULT_THINKING = ["hmm", "let me think", "one sec", "hold on"]
+_DEFAULT_PRE_CLOSE = ["okay", "alright", "so", "well"]
+_DEFAULT_CLOSING   = ["take care", "talk soon", "bye for now", "later"]
+
+
+@dataclass(frozen=True)
+class VoiceFacets:
+    """Immutable snapshot for one persona.
+
+    All scalar knobs are clamped on load so downstream code can trust
+    the range. Token pools are deduplicated + lowercased to keep the
+    anti-repetition ledger case-insensitive.
+    """
+
+    warmth: float           # 0 clinical … 1 affectionate
+    pace: float             # 0.25 … 2.0   speech-rate multiplier
+    formality: float        # 0 casual … 1 formal
+    humor: float            # 0 none … 1 playful
+    self_disclosure: float  # 0 reserved … 1 volunteers a lot
+    sentence_max_words: int
+    typical_reply_sentences: List[int]
+    language_register: str
+    ack_tokens: List[str]
+    thinking_tokens: List[str]
+    pre_closing_tokens: List[str]
+    closing_tokens: List[str]
+    backchannel_rate: float  # 0..2, multiplier on default cadence
+
+    @property
+    def tone_line(self) -> str:
+        """One-line summary of scalar knobs, ready to drop into the
+        per-turn system suffix. Numeric so the model interpolates
+        rather than falling back on the same adjective."""
+        return (
+            f"warmth {self.warmth:.1f} · pace {self.pace:.2f} · "
+            f"formality {self.formality:.1f} · humor {self.humor:.1f}"
+        )
+
+
+def _clamp(x: float, lo: float, hi: float) -> float:
+    try:
+        return max(lo, min(hi, float(x)))
+    except (TypeError, ValueError):
+        return lo
+
+
+def _tokens(raw: Any, default: List[str]) -> List[str]:
+    """Normalize a token-pool field: list[str], lowercase, de-dup,
+    keep stable order. Returns the default if input is empty / bad."""
+    if not isinstance(raw, list) or not raw:
+        return list(default)
+    seen, out = set(), []
+    for item in raw:
+        if not isinstance(item, str):
+            continue
+        t = item.strip().lower()
+        if t and t not in seen:
+            seen.add(t)
+            out.append(t)
+    return out if out else list(default)
+
+
+def default_facets() -> VoiceFacets:
+    """Neutral English phone-call default. What an unmodified persona
+    gets — indistinguishable from today's behavior except for the phone
+    context itself."""
+    return VoiceFacets(
+        warmth=0.5,
+        pace=1.0,
+        formality=0.4,
+        humor=0.3,
+        self_disclosure=0.3,
+        sentence_max_words=22,
+        typical_reply_sentences=[1, 2, 3],
+        language_register="en-US-casual",
+        ack_tokens=list(_DEFAULT_ACKS),
+        thinking_tokens=list(_DEFAULT_THINKING),
+        pre_closing_tokens=list(_DEFAULT_PRE_CLOSE),
+        closing_tokens=list(_DEFAULT_CLOSING),
+        backchannel_rate=1.0,
+    )
+
+
+def from_manifest(manifest: Optional[Dict[str, Any]]) -> VoiceFacets:
+    """Parse a persona manifest dict into a VoiceFacets.
+
+    Any missing / malformed field falls back to the default. Safe to
+    call with ``None`` or ``{}`` — returns :func:`default_facets` in
+    those cases. Never raises; a broken facets block must not break a
+    call.
+    """
+    d = default_facets()
+    if not isinstance(manifest, dict):
+        return d
+    raw = manifest.get("voice_facets")
+    if not isinstance(raw, dict):
+        return d
+
+    sig = raw.get("signature_tokens") or {}
+    if not isinstance(sig, dict):
+        sig = {}
+
+    reply_ns = raw.get("typical_reply_sentences")
+    if isinstance(reply_ns, list) and reply_ns:
+        reply_ns = [int(n) for n in reply_ns if isinstance(n, (int, float))]
+    else:
+        reply_ns = list(d.typical_reply_sentences)
+
+    return VoiceFacets(
+        warmth=_clamp(raw.get("warmth", d.warmth), 0.0, 1.0),
+        pace=_clamp(raw.get("pace", d.pace), 0.25, 2.0),
+        formality=_clamp(raw.get("formality", d.formality), 0.0, 1.0),
+        humor=_clamp(raw.get("humor", d.humor), 0.0, 1.0),
+        self_disclosure=_clamp(
+            raw.get("self_disclosure", d.self_disclosure), 0.0, 1.0
+        ),
+        sentence_max_words=int(raw.get("sentence_max_words", d.sentence_max_words)),
+        typical_reply_sentences=reply_ns,
+        language_register=str(raw.get("language_register", d.language_register)),
+        ack_tokens=_tokens(sig.get("acknowledgments"), d.ack_tokens),
+        thinking_tokens=_tokens(sig.get("thinking"), d.thinking_tokens),
+        pre_closing_tokens=_tokens(sig.get("pre_closing"), d.pre_closing_tokens),
+        closing_tokens=_tokens(sig.get("closings"), d.closing_tokens),
+        backchannel_rate=_clamp(raw.get("backchannel_rate", 1.0), 0.0, 2.0),
+    )
+
+
+# ── Runtime lookup — never mutates persona storage ───────────────────
+
+def for_persona_id(persona_id: Optional[str]) -> VoiceFacets:
+    """Load facets for a persona without touching persona storage.
+
+    Looks up the persona's manifest (if any) via the existing personas
+    module. Any error returns the neutral default — persona_call must
+    degrade silently when persona storage has not yet been initialized
+    (e.g. early tests).
+    """
+    if not persona_id:
+        return default_facets()
+    try:
+        # Lazy import to avoid any import-time coupling to personas.
+        from ..personas.repo import get_persona  # type: ignore
+        manifest = get_persona(persona_id)
+    except Exception:
+        return default_facets()
+    return from_manifest(manifest)

backend/app/persona_call/latency.py

@@ -0,0 +1,107 @@
+"""
+Pre-emptive filler scheduler — "hmm, one sec…" within the 700 ms
+Stivers trouble threshold.
+
+Because the MVP chat path is *non-streaming* (the compat endpoint
+returns 501 on stream=true), the only way to cover long LLM latency
+is to emit a server-originated filler BEFORE the real reply arrives.
+
+Usage (from ws.py inside a turn)::
+
+    async with FillerScheduler(ws=..., facets=facets, cfg=cfg,
+                               session_id=sid) as sched:
+        reply = await turn.run_turn(...)
+    # If the turn took longer than cfg.filler_emit_after_ms, the
+    # scheduler already emitted one 'assistant.filler' event to the
+    # client. Either way, the real reply follows.
+
+Per the design doc: filler tokens are persona-specific with a
+sensible universal fallback (covered by ``VoiceFacets.thinking_tokens``,
+whose default pool is ["hmm", "let me think", "one sec", "hold on"]).
+"""
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+from .config import PersonaCallConfig
+from .facets import VoiceFacets
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+class FillerScheduler:
+    """Async context-manager that emits at most ONE filler event per
+    turn, ``filler_emit_after_ms`` after entering the context. Cancel
+    on exit — if the LLM returned faster, no event is sent.
+
+    The event is emitted via the ``send`` callable injected at
+    construction, not by calling ``ws.send_text`` directly, so this
+    module stays free of fastapi imports and is trivially unit-testable.
+    """
+
+    def __init__(
+        self,
+        *,
+        send: Callable[[Dict[str, Any]], "asyncio.Future"],
+        facets: VoiceFacets,
+        cfg: PersonaCallConfig,
+        session_id: str,
+        recent_thinking: Optional[List[str]] = None,
+    ) -> None:
+        self._send = send
+        self._facets = facets
+        self._cfg = cfg
+        self._sid = session_id
+        self._recent = list(recent_thinking or [])
+        self._task: Optional[asyncio.Task] = None
+        self.emitted: bool = False
+        self.emitted_token: Optional[str] = None
+
+    def _pick_token(self) -> Optional[str]:
+        pool = [t for t in self._facets.thinking_tokens if t]
+        if not pool:
+            return None
+        last = (self._recent[-1].lower() if self._recent else "")
+        candidates = [t for t in pool if t.lower() != last] or pool
+        return random.choice(candidates)
+
+    async def _fire(self) -> None:
+        delay_ms = max(0, int(self._cfg.filler_emit_after_ms))
+        try:
+            await asyncio.sleep(delay_ms / 1000.0)
+        except asyncio.CancelledError:
+            return
+        token = self._pick_token()
+        if not token:
+            return
+        try:
+            await self._send({
+                "type": "assistant.filler",
+                "payload": {
+                    "token": token,
+                    "ts": _now_ms(),
+                    "session_id": self._sid,
+                },
+            })
+            self.emitted = True
+            self.emitted_token = token
+        except Exception:
+            # Best-effort — never let a filler failure break the turn.
+            pass
+
+    async def __aenter__(self) -> "FillerScheduler":
+        self._task = asyncio.create_task(self._fire())
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except Exception:
+                pass

backend/app/persona_call/openings.py

@@ -0,0 +1,334 @@
+"""
+persona_call.openings — "theory of answering" template bank.
+
+Adds the deterministic first-turn answer the persona uses when a call
+connects. Backed by conversation-analysis research on phone openings
+(Schegloff 1968, Hopper 1992) and cross-cultural data (Liddicoat
+2021, ch. 9); augmented with call-center industry practice for the
+formal-register templates.
+
+Why a template bank instead of "let the LLM improvise"
+------------------------------------------------------
+Phone openings are the single most ritualized slot in human
+conversation — every culture has a narrow, low-entropy answer
+inventory. A free-form LLM greeting is both slower (latency hurts
+most on turn 1) and less natural (LLMs over-generate: "Hello there!
+What a wonderful day to connect with you…"). A curated bank of
+short templates fires in <5 ms, is persona-aware, is rotated so the
+same caller never hears the same greeting twice in a row, and is
+trivially auditable.
+
+Design constraints
+------------------
+1. **Additive.** This module is new; nothing else changes. The
+   existing ``directive.compose()`` uses it opportunistically in
+   the opening phase only.
+2. **Persona-preserving.** A template is a *seed*, not a mandate:
+   the chosen text flows through the persona's own TTS voice and
+   the LLM never sees it as an instruction to copy. If a persona
+   ships ``voice_facets.signature_tokens.openings``, that override
+   wins; templates from this module are used only when the persona
+   declines to ship its own.
+3. **Deterministic under tests.** Selection is seeded by
+   (session_id, turn_index) so the same call always picks the same
+   template — regression tests don't flake.
+4. **Rotated.** A separate persisted ledger
+   (``persona_call_state.recent_openings``) already tracks the
+   last few opener tokens the persona used; we extend it to cover
+   full template IDs so cross-call repetition is avoided too.
+
+Template families (drawn from Hopper 1992 + call-center practice)
+-----------------------------------------------------------------
+- **summons_answer** — the minimalist acknowledge-you've-been-summoned
+  move: "Hello?", "Yes?", "Mm?" (Schegloff 1968, turn 1).
+- **identification** — name-forward answer, the default for most
+  non-intimate contexts: "Atlas speaking.", "This is Atlas."
+- **greeting_plus_name** — warmer, the default personal-call opener
+  in English: "Hi, Atlas here.", "Hey — Atlas."
+- **time_of_day** — morning/evening variants: "Good evening, Atlas.",
+  "Morning — Atlas.".
+- **intimate_reopen** — for repeat callers (weeks_since_last_call
+  < 2): "Hey you.", "Oh hi!", "Good to hear from you.".
+- **call_center_formal** — for personas with formality ≥ 0.75:
+  "Thank you for calling. This is Atlas, how can I help?" and
+  variants. The *only* family that includes a how-may-I-help tail.
+- **late_night_brief** — after 22:00 local: "Hey…", "Mm, yeah?",
+  "Yeah — hi.". Short on purpose.
+
+Each template carries a ``precond`` callable that decides whether it
+fits the current ``(facets, env, state)``. Selection is a two-pass
+filter+weight: first drop ineligible templates, then weight the
+survivors by persona fit.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import random
+from dataclasses import dataclass, field
+from typing import Callable, Iterable, List, Optional
+
+from .context import CallEnv
+from .facets import VoiceFacets
+
+
+# ── Template record ──────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class OpeningTemplate:
+    """One row in the template bank.
+
+    Attributes
+    ----------
+    id
+        Stable identifier persisted in the anti-repetition ledger.
+        Short snake_case.
+    family
+        One of the seven families in the module docstring. Used by
+        selection weighting + tests.
+    text
+        The template string. ``{name}`` is interpolated with the
+        persona's display name (or swallowed if empty). No other
+        interpolation — keeping templates 100% literal means a
+        reviewer can read the bank and know exactly what can ship.
+    formality_range
+        Inclusive ``(lo, hi)`` on the persona's formality facet.
+        Templates outside the persona's range are filtered out.
+    precond
+        Final predicate run against ``(facets, env)``. Returns True
+        iff the template is eligible *right now*. Typical uses:
+        late-night variants only after 22:00, intimate variants only
+        for recurring callers.
+    """
+    id: str
+    family: str
+    text: str
+    formality_range: tuple = (0.0, 1.0)
+    precond: Callable[[VoiceFacets, CallEnv], bool] = field(
+        default=lambda _f, _e: True,
+    )
+
+
+# ── Precondition helpers — readable and reusable. ────────────────────
+
+def _any_time(_f: VoiceFacets, _e: CallEnv) -> bool:
+    return True
+
+def _recurring(_f: VoiceFacets, env: CallEnv) -> bool:
+    """Fire only when this caller has spoken to this persona recently.
+    Guards against a cold-call receiving the intimate family."""
+    return 0 <= env.weeks_since_last_call < 2
+
+def _late_night(_f: VoiceFacets, env: CallEnv) -> bool:
+    return env.local_hour >= 22 or env.local_hour < 6
+
+def _morning(_f: VoiceFacets, env: CallEnv) -> bool:
+    return 5 <= env.local_hour < 11
+
+def _afternoon(_f: VoiceFacets, env: CallEnv) -> bool:
+    return 11 <= env.local_hour < 17
+
+def _evening(_f: VoiceFacets, env: CallEnv) -> bool:
+    return 17 <= env.local_hour < 22
+
+
+# ── The bank ─────────────────────────────────────────────────────────
+# Deliberately small — 23 templates across 7 families. Adding more is
+# cheap but every addition increases the risk of one slipping through
+# review in a voice that doesn't fit the persona. Keep the bar high.
+
+OPENING_BANK: tuple = (
+    # 1. summons_answer — the Schegloff minimum. Any formality.
+    OpeningTemplate("sa_hello",        "summons_answer",     "Hello?"),
+    OpeningTemplate("sa_hello_open",   "summons_answer",     "Hello — who's this?"),
+    OpeningTemplate("sa_yes",          "summons_answer",     "Yes?",
+                    formality_range=(0.0, 0.6)),
+    OpeningTemplate("sa_yeah",         "summons_answer",     "Yeah?",
+                    formality_range=(0.0, 0.45)),
+
+    # 2. identification — name-forward. Default for 0.3 ≤ formality ≤ 0.8.
+    OpeningTemplate("id_name_speaking", "identification",
+                    "{name} speaking.",
+                    formality_range=(0.4, 1.0)),
+    OpeningTemplate("id_this_is",       "identification",
+                    "This is {name}.",
+                    formality_range=(0.35, 1.0)),
+    OpeningTemplate("id_hello_name",    "identification",
+                    "Hello, this is {name}.",
+                    formality_range=(0.4, 1.0)),
+
+    # 3. greeting_plus_name — warmer, casual. Default personal-call.
+    OpeningTemplate("gn_hi_here",       "greeting_plus_name",
+                    "Hi, {name} here.",
+                    formality_range=(0.2, 0.75)),
+    OpeningTemplate("gn_hey_name",      "greeting_plus_name",
+                    "Hey — {name}.",
+                    formality_range=(0.0, 0.6)),
+    OpeningTemplate("gn_hi_hi",         "greeting_plus_name",
+                    "Hi hi.",
+                    formality_range=(0.0, 0.55)),
+
+    # 4. time_of_day — used only at matching hour, amortised across
+    #    the bank so it never dominates.
+    OpeningTemplate("td_morning",       "time_of_day",
+                    "Morning — {name}.",
+                    precond=_morning),
+    OpeningTemplate("td_good_morning",  "time_of_day",
+                    "Good morning, {name} speaking.",
+                    formality_range=(0.5, 1.0), precond=_morning),
+    OpeningTemplate("td_afternoon",     "time_of_day",
+                    "Good afternoon — {name}.",
+                    formality_range=(0.4, 1.0), precond=_afternoon),
+    OpeningTemplate("td_evening",       "time_of_day",
+                    "Good evening.",
+                    formality_range=(0.4, 1.0), precond=_evening),
+
+    # 5. intimate_reopen — recurring callers only.
+    OpeningTemplate("int_hey_you",      "intimate_reopen",
+                    "Hey you.",
+                    formality_range=(0.0, 0.5), precond=_recurring),
+    OpeningTemplate("int_oh_hi",        "intimate_reopen",
+                    "Oh, hi!",
+                    formality_range=(0.0, 0.6), precond=_recurring),
+    OpeningTemplate("int_good_to_hear", "intimate_reopen",
+                    "Hey — good to hear from you.",
+                    formality_range=(0.15, 0.7), precond=_recurring),
+
+    # 6. call_center_formal — high-formality only; the only family
+    #    that volunteers help.
+    OpeningTemplate("cc_thank_you_calling", "call_center_formal",
+                    "Thank you for calling. This is {name}, how can I help?",
+                    formality_range=(0.75, 1.0)),
+    OpeningTemplate("cc_name_how_help",     "call_center_formal",
+                    "{name} speaking — how can I help?",
+                    formality_range=(0.7, 1.0)),
+    OpeningTemplate("cc_standing_by",       "call_center_formal",
+                    "Hello, {name} here — what can I do for you?",
+                    formality_range=(0.65, 1.0)),
+
+    # 7. late_night_brief — just picked up the phone, mid-yawn.
+    OpeningTemplate("ln_hey",          "late_night_brief",
+                    "Hey…",
+                    formality_range=(0.0, 0.55), precond=_late_night),
+    OpeningTemplate("ln_yeah_hi",      "late_night_brief",
+                    "Yeah — hi.",
+                    formality_range=(0.0, 0.5), precond=_late_night),
+    OpeningTemplate("ln_mm_yeah",      "late_night_brief",
+                    "Mm, yeah?",
+                    formality_range=(0.0, 0.45), precond=_late_night),
+)
+
+
+# ── Public API ───────────────────────────────────────────────────────
+
+def _interpolate(tpl: str, name: str) -> str:
+    """Render ``{name}`` in the template. If the caller has no usable
+    display name, swallow the placeholder cleanly so we never ship
+    literal ``{name}``."""
+    safe = (name or "").strip()
+    if not safe:
+        # Drop the placeholder + surrounding whitespace around it so
+        # "This is {name}." → "This is." wouldn't be ugly. We replace
+        # with a near-natural collapse.
+        return (
+            tpl.replace(", this is {name}.", ".")
+               .replace(" this is {name}.", ".")
+               .replace(" — {name}.", ".")
+               .replace("{name} speaking.", "Speaking.")
+               .replace("{name} here.", "Here.")
+               .replace("{name}", "")
+               .strip()
+        )
+    return tpl.replace("{name}", safe)
+
+
+def eligible_templates(
+    facets: VoiceFacets,
+    env: CallEnv,
+    *,
+    bank: Iterable[OpeningTemplate] = OPENING_BANK,
+    forbidden_ids: Iterable[str] = (),
+) -> List[OpeningTemplate]:
+    """Filter the bank to what fits the persona + environment + ledger.
+
+    Two-pass filter:
+      1. Formality range contains ``facets.formality``.
+      2. ``precond(facets, env)`` returns True.
+      3. ``id`` not in ``forbidden_ids`` (the anti-repetition ledger).
+    """
+    banned = set(forbidden_ids or ())
+    out: List[OpeningTemplate] = []
+    for t in bank:
+        lo, hi = t.formality_range
+        if not (lo <= facets.formality <= hi):
+            continue
+        if not t.precond(facets, env):
+            continue
+        if t.id in banned:
+            continue
+        out.append(t)
+    return out
+
+
+def _seed(session_id: str, turn_index: int) -> int:
+    """Stable seed so tests don't flake.
+
+    Uses blake2b rather than hash() because CPython randomizes
+    ``hash()`` between processes (PYTHONHASHSEED), which makes the
+    selected template drift under test isolation and is a subtle
+    source of flakes.
+    """
+    h = hashlib.blake2b(
+        f"{session_id}:{turn_index}".encode("utf-8"), digest_size=8,
+    )
+    return int.from_bytes(h.digest(), "big")
+
+
+def choose(
+    facets: VoiceFacets,
+    env: CallEnv,
+    *,
+    session_id: str,
+    turn_index: int = 1,
+    forbidden_ids: Iterable[str] = (),
+    bank: Iterable[OpeningTemplate] = OPENING_BANK,
+) -> Optional[OpeningTemplate]:
+    """Pick one eligible template.
+
+    Returns the persona's own signature opener when ``facets`` ships a
+    custom pool — otherwise picks from the filtered bank. Never
+    returns an ``OpeningTemplate`` that matches a forbidden id.
+
+    If no eligible template survives the filter (rare — would require
+    an unusual formality + time-of-day combination and a ledger full
+    of every normally-eligible id), this returns ``None`` and the
+    caller should fall back to ``"Hello?"``, which is why the
+    summons_answer family has no preconditions.
+    """
+    pool = eligible_templates(facets, env, bank=bank, forbidden_ids=forbidden_ids)
+    if not pool:
+        return None
+    rnd = random.Random(_seed(session_id, turn_index))
+    return rnd.choice(pool)
+
+
+def render(
+    facets: VoiceFacets,
+    env: CallEnv,
+    *,
+    persona_display_name: str = "",
+    session_id: str,
+    turn_index: int = 1,
+    forbidden_ids: Iterable[str] = (),
+) -> Optional[str]:
+    """End-to-end helper: pick + interpolate. Returns None on empty
+    pool so the caller can fall back safely."""
+    tpl = choose(
+        facets, env,
+        session_id=session_id,
+        turn_index=turn_index,
+        forbidden_ids=forbidden_ids,
+    )
+    if tpl is None:
+        return None
+    return _interpolate(tpl.text, persona_display_name)

backend/app/persona_call/repeat.py

@@ -0,0 +1,128 @@
+"""
+Anti-repetition ledger.
+
+Three windowed deques per session, all backed by the JSON columns on
+``persona_call_state``:
+
+  recent_acks      last N acknowledgment tokens the persona used
+  recent_openers   last N first-words of the persona's turns
+  recent_closings  last N pre-closing tokens
+
+Read API returns the set to FORBID in the next turn's directive; write
+API is called after the reply comes back and extracts the new token via
+a regex-first / LLM-never extractor so it stays cheap.
+
+No LLM calls anywhere here — the extraction is regex + token-pool
+membership. If the persona's reply starts with a token that isn't in
+its own voice_facets pool, we store the first lowercased word anyway;
+it still anchors the entropy metric.
+"""
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional, Set, Tuple
+
+from .facets import VoiceFacets
+
+
+_WORD_BOUNDARY = re.compile(r"^[\s\W]*([a-z][a-z\-']*)", re.I)
+
+
+def _first_word(reply: str) -> Optional[str]:
+    if not reply:
+        return None
+    m = _WORD_BOUNDARY.match(reply.strip())
+    if not m:
+        return None
+    return m.group(1).lower()
+
+
+def _roll(deque: List[str], token: str, size: int) -> List[str]:
+    out = list(deque or [])
+    if token:
+        out.append(token)
+    if len(out) > size:
+        out = out[-size:]
+    return out
+
+
+# ── READ: directive paragraph that forbids recent tokens ─────────────
+
+def forbid_clause(
+    state: Dict[str, object],
+    facets: VoiceFacets,
+    *,
+    max_len: int = 80,
+) -> str:
+    """Return the one-line directive paragraph about recent tokens.
+
+    Empty string when there's nothing to forbid yet — keeps the
+    per-turn suffix short on early turns."""
+    acks = state.get("recent_acks") or []
+    openers = state.get("recent_openers") or []
+    if not acks and not openers:
+        return ""
+
+    dropped: Set[str] = set()
+    for t in acks:
+        if isinstance(t, str) and t:
+            dropped.add(t.lower())
+    for t in openers:
+        if isinstance(t, str) and t:
+            dropped.add(t.lower())
+
+    if not dropped:
+        return ""
+
+    pool = [t for t in facets.ack_tokens if t.lower() not in dropped]
+    fresh_hint = ""
+    if pool:
+        fresh_hint = f" Prefer a fresh one from: {', '.join(pool[:4])}."
+
+    forbidden = sorted(dropped)[: max_len // 5]  # rough clamp
+    return (
+        "Avoid repeating your recent openers / acknowledgments: "
+        f"{', '.join(forbidden)}." + fresh_hint
+    )
+
+
+# ── WRITE: record the persona's reply into the ledger ────────────────
+
+def record_reply(
+    state: Dict[str, object],
+    reply: str,
+    facets: VoiceFacets,
+    cfg_ack_window: int,
+    cfg_opener_window: int,
+) -> Tuple[List[str], List[str]]:
+    """Roll the ledger forward. Returns the new (recent_acks,
+    recent_openers) lists for ``store.update_state``."""
+    token = _first_word(reply) or ""
+    acks = state.get("recent_acks") or []
+    openers = state.get("recent_openers") or []
+
+    # An ack is anything that appears in the persona's ack pool AND
+    # appears in the first three words. That matches how human phone
+    # acks actually work ("mm yeah I hear you"): the ack is the front
+    # of the turn, not a whole separate utterance.
+    front = " ".join((reply or "").lower().strip().split()[:3])
+    matched_ack = None
+    for pool_token in facets.ack_tokens:
+        if pool_token in front:
+            matched_ack = pool_token
+            break
+
+    new_acks = _roll(list(acks), matched_ack or "", cfg_ack_window)
+    new_openers = _roll(list(openers), token, cfg_opener_window)
+    return new_acks, new_openers
+
+
+def record_closing(
+    state: Dict[str, object],
+    token: str,
+    window: int = 3,
+) -> List[str]:
+    """Roll the closings deque. Called when the closing state machine
+    chooses a pre-closing token."""
+    prev = state.get("recent_closings") or []
+    return _roll(list(prev), token.lower() if token else "", window)

backend/app/persona_call/router.py

@@ -0,0 +1,224 @@
+"""
+Public HTTP surface for persona_call.
+
+Five endpoints, all minor — this module is primarily called from
+``voice_call/ws.py`` at runtime. These REST routes are for
+observability + admin tuning + client facets lookup.
+
+Mount point in main.py is ONE feature-flagged try/except block.
+With ``PERSONA_CALL_ENABLED=false`` :func:`build_router` returns
+an empty router — every path 404s, zero schema is created.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from fastapi import (
+    APIRouter, Cookie, Depends, Header, HTTPException, Query,
+)
+from pydantic import BaseModel
+
+from . import facets as facets_mod
+from . import store
+from .config import PersonaCallConfig
+
+
+# ── auth passthrough (matches main._scoped_user_or_none) ─────────────
+
+def _resolve_user(
+    authorization: str,
+    homepilot_session: Optional[str],
+) -> dict:
+    from ..users import (
+        ensure_users_tables, _validate_token,
+        get_or_create_default_user, count_users,
+    )
+    ensure_users_tables()
+    token = ""
+    if authorization and authorization.lower().startswith("bearer "):
+        token = authorization.split(" ", 1)[1].strip()
+    if not token and homepilot_session:
+        token = homepilot_session.strip()
+    user = _validate_token(token) if token else None
+    if user:
+        return user
+    if count_users() > 1:
+        raise HTTPException(status_code=401, detail="Authentication required")
+    return get_or_create_default_user()
+
+
+# ── response models ──────────────────────────────────────────────────
+
+class FacetsResp(BaseModel):
+    persona_id: Optional[str]
+    warmth: float
+    pace: float
+    formality: float
+    humor: float
+    self_disclosure: float
+    sentence_max_words: int
+    typical_reply_sentences: List[int]
+    language_register: str
+    signature_tokens: Dict[str, List[str]]
+    backchannel_rate: float
+
+
+class StateResp(BaseModel):
+    session_id: str
+    phase: str
+    turn_index: int
+    skipped_how_are_you: bool
+    asked_reason_fallback: bool
+    reason_for_call: str
+    pre_closing_trigger: Optional[str]
+    recent_acks: List[str]
+    recent_openers: List[str]
+    recent_closings: List[str]
+    caller_context: Dict[str, Any]
+
+
+class DirectiveResp(BaseModel):
+    session_id: str
+    turn_index: int
+    phase: str
+    applied: bool
+    system_suffix: str
+    post_directives: List[str]
+
+
+# ── router builder ───────────────────────────────────────────────────
+
+def build_router(cfg: PersonaCallConfig) -> APIRouter:
+    """Construct the FastAPI router. Empty if ``cfg.enabled`` is
+    False so main.py's mount is always a safe no-op."""
+    r = APIRouter(prefix="/v1/persona-call", tags=["persona-call"])
+    if not cfg.enabled:
+        return r
+
+    @r.get("/facets/{persona_id}", response_model=FacetsResp)
+    def get_facets(persona_id: str):
+        f = facets_mod.for_persona_id(persona_id)
+        return FacetsResp(
+            persona_id=persona_id,
+            warmth=f.warmth,
+            pace=f.pace,
+            formality=f.formality,
+            humor=f.humor,
+            self_disclosure=f.self_disclosure,
+            sentence_max_words=f.sentence_max_words,
+            typical_reply_sentences=f.typical_reply_sentences,
+            language_register=f.language_register,
+            signature_tokens={
+                "acknowledgments": list(f.ack_tokens),
+                "thinking": list(f.thinking_tokens),
+                "pre_closing": list(f.pre_closing_tokens),
+                "closings": list(f.closing_tokens),
+            },
+            backchannel_rate=f.backchannel_rate,
+        )
+
+    @r.get("/state/{session_id}", response_model=StateResp)
+    def get_state(
+        session_id: str,
+        authorization: str = Header(default=""),
+        homepilot_session: Optional[str] = Cookie(default=None),
+    ):
+        """Runtime state for the session. Owner-bound via the
+        underlying voice_call_sessions row — if the session doesn't
+        belong to the caller, return 404 (probe-safe)."""
+        user = _resolve_user(authorization, homepilot_session)
+        # Ownership is enforced by looking up the voice_call_sessions
+        # row first. If that is missing or foreign, we 404 before
+        # touching persona_call_state at all.
+        try:
+            from ..voice_call.store import get_session_for_owner
+            vc_row = get_session_for_owner(session_id, user["id"])
+        except Exception:
+            vc_row = None
+        if vc_row is None:
+            raise HTTPException(status_code=404, detail="Session not found")
+        s = store.get_state(session_id)
+        if s is None:
+            # Session exists but no persona_call state yet — return a
+            # zero-ed row rather than 404 so clients can poll safely
+            # before the first turn.
+            return StateResp(
+                session_id=session_id,
+                phase="opening",
+                turn_index=0,
+                skipped_how_are_you=False,
+                asked_reason_fallback=False,
+                reason_for_call="",
+                pre_closing_trigger=None,
+                recent_acks=[],
+                recent_openers=[],
+                recent_closings=[],
+                caller_context={},
+            )
+        return StateResp(
+            session_id=s["session_id"],
+            phase=str(s.get("phase") or "opening"),
+            turn_index=int(s.get("turn_index") or 0),
+            skipped_how_are_you=bool(s.get("skipped_how_are_you")),
+            asked_reason_fallback=bool(s.get("asked_reason_fallback")),
+            reason_for_call=str(s.get("reason_for_call") or ""),
+            pre_closing_trigger=s.get("pre_closing_trigger"),
+            recent_acks=list(s.get("recent_acks") or []),
+            recent_openers=list(s.get("recent_openers") or []),
+            recent_closings=list(s.get("recent_closings") or []),
+            caller_context=dict(s.get("caller_context") or {}),
+        )
+
+    @r.get("/last-directive/{session_id}", response_model=DirectiveResp)
+    def get_last_directive(
+        session_id: str,
+        authorization: str = Header(default=""),
+        homepilot_session: Optional[str] = Cookie(default=None),
+    ):
+        user = _resolve_user(authorization, homepilot_session)
+        try:
+            from ..voice_call.store import get_session_for_owner
+            vc_row = get_session_for_owner(session_id, user["id"])
+        except Exception:
+            vc_row = None
+        if vc_row is None:
+            raise HTTPException(status_code=404, detail="Session not found")
+        d = store.last_directive(session_id)
+        if d is None:
+            raise HTTPException(status_code=404, detail="No directive yet")
+        return DirectiveResp(
+            session_id=d["session_id"],
+            turn_index=int(d["turn_index"]),
+            phase=str(d["phase"]),
+            applied=bool(d["applied"]),
+            system_suffix=str(d["system_suffix"] or ""),
+            post_directives=list(d["post_directives"] or []),
+        )
+
+    @r.post("/reset/{session_id}")
+    def reset_session(
+        session_id: str,
+        authorization: str = Header(default=""),
+        homepilot_session: Optional[str] = Cookie(default=None),
+    ):
+        """Wipe the anti-repetition ledgers for a session. Owner-bound.
+        Used by QA + tests; harmless in production because the phase
+        machine just starts fresh from 'opening'."""
+        user = _resolve_user(authorization, homepilot_session)
+        try:
+            from ..voice_call.store import get_session_for_owner
+            vc_row = get_session_for_owner(session_id, user["id"])
+        except Exception:
+            vc_row = None
+        if vc_row is None:
+            raise HTTPException(status_code=404, detail="Session not found")
+        store.update_state(
+            session_id,
+            recent_acks=[],
+            recent_openers=[],
+            recent_closings=[],
+        )
+        return {"ok": True, "session_id": session_id}
+
+    return r

backend/app/persona_call/state.py

@@ -0,0 +1,99 @@
+"""
+Phase state machine.
+
+Five phases, deterministic transitions:
+
+     opening  ─(reason expressed OR 'how are you' cycle done)─▶  topic
+     topic    ─(closing trigger)─────────────────────────────▶  pre_closing
+     pre_closing ─(user terminal)──────────────────────────────▶  closed
+     pre_closing ─(user recants / new topic)──────────────────▶  topic
+     closed   (terminal)
+
+Phase is the single source of truth for which paragraph
+:mod:`directive` injects into the per-turn system suffix.
+"""
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from . import closing, context, store
+
+
+OPENING = "opening"
+TOPIC = "topic"
+PRE_CLOSING = "pre_closing"
+CLOSED = "closed"
+
+
+def advance_on_user_utterance(
+    *,
+    session_id: str,
+    user_text: str,
+    reason_fallback_turn: int,
+) -> Dict[str, object]:
+    """Called by the WS orchestrator BEFORE composing the directive.
+
+    Updates the phase, turn_index, caller_context, and reason flags
+    based on the just-received user utterance. Returns the refreshed
+    state row so the composer has the latest view.
+    """
+    state = store.ensure_state(session_id)
+    turn_index = int(state.get("turn_index") or 0)
+    phase = state.get("phase") or OPENING
+
+    # Caller signal extraction — accumulate into caller_context.
+    prev_signal = context.CallerSignal.from_dict(
+        state.get("caller_context") if isinstance(
+            state.get("caller_context"), dict) else {}
+    )
+    fresh = context.classify_utterance(user_text)
+    merged = prev_signal.merge(fresh)
+
+    # Phase transition rules.
+    pre_closing_trigger = state.get("pre_closing_trigger")
+
+    if phase in (OPENING, TOPIC) and closing.is_pre_closing_trigger(user_text):
+        phase = PRE_CLOSING
+        pre_closing_trigger = user_text.strip()
+    elif phase == PRE_CLOSING and closing.is_terminal(user_text):
+        phase = CLOSED
+    elif phase == OPENING:
+        # Move to 'topic' if the user stated a reason, OR if we've
+        # already done one "how are you" cycle (2 user turns in
+        # opening without a reason).
+        if merged.reason_expressed:
+            phase = TOPIC
+        elif turn_index >= 2:
+            # After two turns in 'opening' without a stated reason,
+            # the phase-machine forces 'topic' — the persona will
+            # ask the reason-fallback question via the composer.
+            phase = TOPIC
+
+    # Persist.
+    updated = store.update_state(
+        session_id,
+        phase=phase,
+        turn_index=turn_index + 1,
+        caller_context=merged.to_dict(),
+        pre_closing_trigger=pre_closing_trigger,
+    )
+    return updated
+
+
+def mark_how_are_you_decision(session_id: str, *, skipped: bool) -> None:
+    """Record that the composer made a 'how are you' decision for this
+    session — idempotent; the deciding composer path may run multiple
+    turns but should only fire once."""
+    store.update_state(session_id, skipped_how_are_you=skipped)
+
+
+def mark_reason_fallback_asked(session_id: str) -> None:
+    """Record that the composer already asked the reason-fallback
+    question, so it never asks twice."""
+    store.update_state(session_id, asked_reason_fallback=True)
+
+
+def get(session_id: str) -> Optional[Dict[str, object]]:
+    """Thin pass-through to the store — avoids callers importing
+    store directly."""
+    return store.get_state(session_id)

backend/app/persona_call/store.py

@@ -0,0 +1,241 @@
+"""
+SQLite persistence for persona_call.
+
+Two tables, both additive and empty when the feature flag is off:
+
+  persona_call_state       per-session runtime state (phase, turn_index,
+                           ledgers, caller_context).
+
+  persona_call_directives  shadow-mode audit: every composed directive
+                           is appended here so P1 (compose but don't
+                           apply) produces a reviewable trail.
+
+Follows the same pattern as backend/app/voice_call/store.py and the
+rest of HomePilot: direct sqlite3, per-call connections, lazy
+``ensure_schema`` with a process-scoped guard so it's cheap after
+first use.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from typing import Any, Dict, List, Optional
+
+
+def _db_path() -> str:
+    from ..storage import _get_db_path
+    return _get_db_path()
+
+
+def _conn() -> sqlite3.Connection:
+    con = sqlite3.connect(_db_path())
+    con.row_factory = sqlite3.Row
+    return con
+
+
+_SCHEMA_READY = False
+
+
+def ensure_schema() -> None:
+    """Create persona_call tables if missing. Safe to call any number
+    of times. No-op on subsequent calls within the same process."""
+    global _SCHEMA_READY
+    if _SCHEMA_READY:
+        return
+    con = _conn()
+    cur = con.cursor()
+    cur.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS persona_call_state (
+            session_id              TEXT PRIMARY KEY,
+            phase                   TEXT NOT NULL DEFAULT 'opening',
+            turn_index              INTEGER NOT NULL DEFAULT 0,
+            skipped_how_are_you     INTEGER NOT NULL DEFAULT 0,
+            asked_reason_fallback   INTEGER NOT NULL DEFAULT 0,
+            reason_for_call         TEXT NOT NULL DEFAULT '',
+            last_backchannel_ms     INTEGER NOT NULL DEFAULT 0,
+            recent_acks             TEXT NOT NULL DEFAULT '[]',
+            recent_openers          TEXT NOT NULL DEFAULT '[]',
+            recent_closings         TEXT NOT NULL DEFAULT '[]',
+            caller_context          TEXT NOT NULL DEFAULT '{}',
+            pre_closing_trigger     TEXT,
+            created_at              INTEGER NOT NULL,
+            updated_at              INTEGER NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS persona_call_directives (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            session_id      TEXT NOT NULL,
+            turn_index      INTEGER NOT NULL,
+            phase           TEXT NOT NULL,
+            applied         INTEGER NOT NULL DEFAULT 1,
+            system_suffix   TEXT NOT NULL,
+            post_directives TEXT NOT NULL DEFAULT '[]',
+            created_at      INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS ix_pcd_session
+            ON persona_call_directives (session_id, turn_index);
+        """
+    )
+    con.commit()
+    con.close()
+    _SCHEMA_READY = True
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+# ── persona_call_state CRUD ───────────────────────────────────────────
+
+def get_state(session_id: str) -> Optional[Dict[str, Any]]:
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        "SELECT * FROM persona_call_state WHERE session_id = ?",
+        (session_id,),
+    )
+    row = cur.fetchone()
+    con.close()
+    if row is None:
+        return None
+    d = {k: row[k] for k in row.keys()}
+    # Deserialize JSON columns.
+    for col in ("recent_acks", "recent_openers", "recent_closings",
+                "caller_context"):
+        try:
+            d[col] = json.loads(d.get(col) or "[]")
+        except Exception:
+            d[col] = [] if col != "caller_context" else {}
+    return d
+
+
+def ensure_state(session_id: str) -> Dict[str, Any]:
+    """Upsert-shaped: returns the existing row, or creates a fresh one
+    in the 'opening' phase if this is the first turn."""
+    existing = get_state(session_id)
+    if existing is not None:
+        return existing
+    now = _now_ms()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        """
+        INSERT OR IGNORE INTO persona_call_state
+            (session_id, created_at, updated_at)
+        VALUES (?, ?, ?)
+        """,
+        (session_id, now, now),
+    )
+    con.commit()
+    con.close()
+    return get_state(session_id)  # type: ignore[return-value]
+
+
+def update_state(session_id: str, **changes: Any) -> Dict[str, Any]:
+    """Apply a partial update. JSON-typed columns accept Python lists /
+    dicts; everything else is a scalar."""
+    if not changes:
+        return ensure_state(session_id)
+
+    json_cols = {"recent_acks", "recent_openers", "recent_closings",
+                 "caller_context"}
+    sets, params = [], []
+    for col, val in changes.items():
+        if col in json_cols:
+            val = json.dumps(val, separators=(",", ":"))
+        if col in ("skipped_how_are_you", "asked_reason_fallback"):
+            val = 1 if val else 0
+        sets.append(f"{col} = ?")
+        params.append(val)
+    sets.append("updated_at = ?")
+    params.append(_now_ms())
+    params.append(session_id)
+
+    ensure_state(session_id)
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        f"UPDATE persona_call_state SET {', '.join(sets)} WHERE session_id = ?",
+        params,
+    )
+    con.commit()
+    con.close()
+    return get_state(session_id)  # type: ignore[return-value]
+
+
+# ── persona_call_directives (shadow-mode audit) ───────────────────────
+
+def record_directive(
+    *,
+    session_id: str,
+    turn_index: int,
+    phase: str,
+    applied: bool,
+    system_suffix: str,
+    post_directives: List[str],
+) -> None:
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        """
+        INSERT INTO persona_call_directives
+            (session_id, turn_index, phase, applied,
+             system_suffix, post_directives, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            session_id,
+            int(turn_index),
+            phase,
+            1 if applied else 0,
+            system_suffix,
+            json.dumps(post_directives, separators=(",", ":")),
+            _now_ms(),
+        ),
+    )
+    con.commit()
+    con.close()
+
+
+def last_directive(session_id: str) -> Optional[Dict[str, Any]]:
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        """
+        SELECT session_id, turn_index, phase, applied,
+               system_suffix, post_directives, created_at
+          FROM persona_call_directives
+         WHERE session_id = ?
+         ORDER BY id DESC
+         LIMIT 1
+        """,
+        (session_id,),
+    )
+    row = cur.fetchone()
+    con.close()
+    if row is None:
+        return None
+    d = {k: row[k] for k in row.keys()}
+    try:
+        d["post_directives"] = json.loads(d.get("post_directives") or "[]")
+    except Exception:
+        d["post_directives"] = []
+    d["applied"] = bool(d.get("applied"))
+    return d
+
+
+# ── test helper ───────────────────────────────────────────────────────
+
+def _reset_for_tests() -> None:
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute("DELETE FROM persona_call_directives")
+    cur.execute("DELETE FROM persona_call_state")
+    con.commit()
+    con.close()

backend/app/studio/render_jobs.py

@@ -53,6 +53,11 @@ class RenderJob:
     duration_sec: float = 0.0
     width: int = 0
     height: int = 0
+    # Render-time audio / subtitle options, captured so /jobs/{id}
+    # responses can describe exactly how the file was produced.
+    audio_rate: float = 1.0
+    audio_pitch: float = 1.0
+    subtitles: str = "none"
 
     def to_dict(self) -> Dict[str, Any]:
         d = asdict(self)
@@ -115,6 +120,9 @@ def submit_render(
     kind: RenderKind,
     preset: PlatformPreset,
     scenes: List[SceneInput],
+    audio_rate: float = 1.0,
+    audio_pitch: float = 1.0,
+    subtitles: str = "none",
 ) -> RenderJob:
     """Queue a render and return its job record. Worker thread starts immediately."""
     job_id = _new_job_id()
@@ -128,6 +136,9 @@ def submit_render(
         preset=preset,
         status="queued",
         output_path=output_path,
+        audio_rate=audio_rate,
+        audio_pitch=audio_pitch,
+        subtitles=subtitles,
     )
     _store(job)
 
@@ -169,6 +180,9 @@ def _run_job(job_id: str, scenes: List[SceneInput]) -> None:
             kind=job.kind,
             output_path=job.output_path or "",
             on_progress=_on_progress,
+            audio_rate=job.audio_rate,
+            audio_pitch=job.audio_pitch,
+            subtitles=job.subtitles,
         )
         _update(
             job_id,

backend/app/studio/render_mp4.py

@@ -54,12 +54,17 @@ class SceneInput:
     Either ``image_path`` or ``video_path`` should be provided. If both are
     set, ``video_path`` wins (it is the higher-fidelity asset). If neither
     is set, the scene is rendered as a black frame of ``duration_sec``.
+
+    ``narration`` is the source text used to synthesize subtitles when
+    the caller passes ``subtitles="burn_in"`` to :func:`render_scenes`.
+    It does not affect rendering when subtitles are off.
     """
     idx: int
     duration_sec: float = 5.0
     image_path: Optional[str] = None
     video_path: Optional[str] = None
     audio_path: Optional[str] = None
+    narration: str = ""
 
 
 @dataclass
@@ -243,6 +248,119 @@ def _per_scene_args(
     return inputs, filters, f"v{scene.idx}"
 
 
+def _audio_transform_chain(rate: float, pitch: float) -> Optional[str]:
+    """Build the ffmpeg audio-filter chain for the chosen rate + pitch.
+
+    Returns None when both are 1.0 (caller skips the transform stage).
+
+    Rate is applied with ``atempo``. Pitch uses the industry-standard
+    ``asetrate=48000*pitch, atempo=1/pitch`` compound so the tempo is
+    preserved while the pitch shifts. When both are non-unit we stack the
+    pitch compound first, then an outer atempo for rate.
+
+    ``atempo`` only accepts 0.5–2.0 per stage; we clamp inputs upstream
+    to stay within that range so we never need to chain multiple stages.
+    """
+    rate = max(0.5, min(2.0, float(rate or 1.0)))
+    pitch = max(0.5, min(2.0, float(pitch or 1.0)))
+    if rate == 1.0 and pitch == 1.0:
+        return None
+    parts: list[str] = []
+    if pitch != 1.0:
+        parts.append(f"asetrate=48000*{pitch:.6f}")
+        parts.append(f"atempo={1.0 / pitch:.6f}")
+    if rate != 1.0:
+        parts.append(f"atempo={rate:.6f}")
+    return ",".join(parts)
+
+
+def _ass_escape(text: str) -> str:
+    """Escape a string for embedding inside a libass SRT/ASS cue."""
+    return (text or "").replace("\\", "\\\\").replace("{", "\\{").replace("}", "\\}")
+
+
+def _srt_timestamp(seconds: float) -> str:
+    """Convert seconds to an SRT timestamp (HH:MM:SS,mmm)."""
+    if seconds < 0:
+        seconds = 0.0
+    ms = int(round(seconds * 1000))
+    hours, ms = divmod(ms, 3_600_000)
+    minutes, ms = divmod(ms, 60_000)
+    secs, ms = divmod(ms, 1000)
+    return f"{hours:02d}:{minutes:02d}:{secs:02d},{ms:03d}"
+
+
+def _split_narration_for_subtitles(text: str, max_chars: int = 42) -> list[str]:
+    """Chunk narration into subtitle-sized lines.
+
+    Subtitles read best at ~42 chars/line (YouTube's auto-caption default).
+    We split on sentence boundaries first, then on commas when a chunk is
+    still too long, falling back to hard-wrap at word boundaries.
+    """
+    import re
+    if not text:
+        return []
+    # Sentence split on ., !, ?, or newline.
+    sentences = [s.strip() for s in re.split(r"(?<=[.!?])\s+|\n+", text) if s.strip()]
+    chunks: list[str] = []
+    for s in sentences:
+        if len(s) <= max_chars:
+            chunks.append(s)
+            continue
+        # Try splitting on commas first.
+        sub = [p.strip() for p in s.split(",") if p.strip()]
+        if all(len(p) <= max_chars for p in sub):
+            chunks.extend(sub)
+            continue
+        # Fallback: greedy word-wrap.
+        cur = ""
+        for word in s.split():
+            if not cur:
+                cur = word
+            elif len(cur) + 1 + len(word) <= max_chars:
+                cur = f"{cur} {word}"
+            else:
+                chunks.append(cur)
+                cur = word
+        if cur:
+            chunks.append(cur)
+    return chunks
+
+
+def _write_srt_for_scene(
+    narration: str,
+    duration_sec: float,
+    srt_path: Path,
+    *,
+    start_offset: float = 0.0,
+) -> bool:
+    """Write an SRT file whose cues span [0, duration_sec] for a single scene.
+
+    Returns True on success, False when the narration is empty (no SRT
+    should be emitted — and the caller should not try to burn an empty
+    subtitle file, which would fail).
+    """
+    chunks = _split_narration_for_subtitles(narration)
+    if not chunks:
+        return False
+    dur = max(0.5, float(duration_sec or 5.0))
+    # Distribute the duration evenly across chunks. Cap per-cue at 5s so
+    # slow voices don't hold a single cue on screen forever.
+    per = min(dur / len(chunks), 5.0)
+    lines: list[str] = []
+    for i, chunk in enumerate(chunks):
+        start = start_offset + i * per
+        end = min(start_offset + dur, start + per)
+        if end <= start:
+            end = start + 0.1
+        lines.append(str(i + 1))
+        lines.append(f"{_srt_timestamp(start)} --> {_srt_timestamp(end)}")
+        lines.append(_ass_escape(chunk))
+        lines.append("")
+    srt_path.write_text("\n".join(lines), encoding="utf-8")
+    return True
+
+
 def _has_audio(path: str) -> bool:
     """Probe a media file and return True iff it has at least one audio stream."""
     try:
@@ -277,6 +395,9 @@ def render_scenes(
     kind: RenderKind,
     output_path: str,
     on_progress: Optional[Callable[[float], None]] = None,
+    audio_rate: float = 1.0,
+    audio_pitch: float = 1.0,
+    subtitles: str = "none",
 ) -> RenderResult:
     """Render a list of scenes into a single MP4 at ``output_path``.
 
@@ -284,6 +405,18 @@ def render_scenes(
     then concatenates the intermediates with ffmpeg's concat demuxer. This
     is slower than a single filter graph but far more robust against scenes
     with very different codecs / resolutions / sample rates / pixel formats.
+
+    Extra knobs:
+
+    - ``audio_rate`` (0.5–2.0, default 1.0): tempo multiplier for the
+      narration/audio track. Applied as ffmpeg ``atempo``.
+    - ``audio_pitch`` (0.5–2.0, default 1.0): pitch-shift multiplier.
+      Implemented via ``asetrate=48000*pitch, atempo=1/pitch`` so the
+      output duration is unchanged (tempo is preserved, pitch shifts).
+    - ``subtitles`` (``"burn_in"`` | ``"none"``, default ``"none"``):
+      when ``burn_in``, each scene's ``narration`` is chunked into an
+      SRT file and burned into the video via libass. A sidecar .srt
+      is also written next to the MP4 so editors can re-style.
     """
     if not ffmpeg_available():
         raise RuntimeError(
@@ -294,6 +427,8 @@ def render_scenes(
 
     width, height, fps = _resolution_for_preset(preset)
     encode_args = _encode_args_for_kind(kind, preset)
+    audio_transform = _audio_transform_chain(audio_rate, audio_pitch)
+    burn_subtitles = (subtitles or "none").lower() == "burn_in"
 
     out = Path(output_path)
     out.parent.mkdir(parents=True, exist_ok=True)
@@ -325,24 +460,61 @@ def render_scenes(
                 image_path=image_local,
                 video_path=video_local,
                 audio_path=audio_local,
+                narration=scene.narration,
             )
 
-            inputs, filters, _vlabel = _per_scene_args(
+            inputs, filters, vlabel = _per_scene_args(
                 normalized, width, height, fps, scratch
             )
 
+            # If subtitles are burning in, write a per-scene SRT into
+            # scratch and append a ``subtitles`` filter to the video chain.
+            # ffmpeg's subtitles filter uses libass under the hood. A
+            # sidecar .srt is also written next to the final MP4 below.
+            if burn_subtitles and scene.narration:
+                srt_path = scratch / f"scene_{i:04d}.srt"
+                wrote = _write_srt_for_scene(
+                    scene.narration,
+                    normalized.duration_sec,
+                    srt_path,
+                )
+                if wrote:
+                    # Escape the path for ffmpeg's filter-arg parser.
+                    esc = str(srt_path).replace("\\", "/").replace(":", r"\:")
+                    force_style = (
+                        "Fontname=DejaVu Sans,Fontsize=28,"
+                        "PrimaryColour=&H00FFFFFF&,"
+                        "OutlineColour=&H80000000&,"
+                        "BorderStyle=3,Outline=2,Shadow=0,MarginV=48"
+                    )
+                    # Replace the last video-chain step's output label so
+                    # the subtitle filter sits at the end of the pipeline.
+                    new_last = (
+                        f"[{vlabel}]subtitles='{esc}':"
+                        f"force_style='{force_style}'[{vlabel}_sub]"
+                    )
+                    filters.append(new_last)
+                    vlabel = f"{vlabel}_sub"
+
             # Audio handling: prefer explicit audio_path; otherwise reuse the
             # video's audio track if present; otherwise generate silence so
             # every clip has the same stream layout for the concat demuxer.
             audio_inputs: list[str] = []
             audio_filter: list[str] = []
             audio_label = "a0"
+            # Common tail applied to every audio path: resample to 48 kHz
+            # stereo + apply the optional rate/pitch transform the caller
+            # requested. Consolidating the tail here keeps the three
+            # branches below in sync.
+            tail = "aresample=48000,aformat=channel_layouts=stereo"
+            if audio_transform:
+                tail = f"{tail},{audio_transform}"
             if audio_local:
                 audio_inputs += ["-i", audio_local]
                 # Index 1 is the audio file (after the single video input).
-                audio_filter.append(f"[1:a]aresample=48000,aformat=channel_layouts=stereo[{audio_label}]")
+                audio_filter.append(f"[1:a]{tail}[{audio_label}]")
             elif video_local and _has_audio(video_local):
-                audio_filter.append(f"[0:a]aresample=48000,aformat=channel_layouts=stereo[{audio_label}]")
+                audio_filter.append(f"[0:a]{tail}[{audio_label}]")
             else:
                 audio_inputs += [
                     "-f", "lavfi",
@@ -362,7 +534,7 @@ def render_scenes(
                 *inputs,
                 *audio_inputs,
                 "-filter_complex", filter_complex,
-                "-map", "[v0]",
+                "-map", f"[{vlabel}]",
                 "-map", f"[{audio_label}]",
                 "-r", str(fps),
                 "-shortest",
@@ -396,6 +568,36 @@ def render_scenes(
         ]
         _run(concat_cmd)
 
+        # Sidecar SRT: full-video timeline, cue timings chained across
+        # scenes. Written whenever burn_subtitles=True, so editors get the
+        # same timing they saw burned in. Named <output>.srt.
+        if burn_subtitles:
+            sidecar = out.with_suffix(".srt")
+            running_offset = 0.0
+            cue_idx = 1
+            lines: list[str] = []
+            for s in scenes:
+                dur = max(0.5, float(s.duration_sec or 5.0))
+                chunks = _split_narration_for_subtitles(s.narration or "")
+                if chunks:
+                    per = min(dur / len(chunks), 5.0)
+                    for j, chunk in enumerate(chunks):
+                        start = running_offset + j * per
+                        end = min(running_offset + dur, start + per)
+                        if end <= start:
+                            end = start + 0.1
+                        lines.append(str(cue_idx))
+                        lines.append(f"{_srt_timestamp(start)} --> {_srt_timestamp(end)}")
+                        lines.append(_ass_escape(chunk))
+                        lines.append("")
+                        cue_idx += 1
+                running_offset += dur
+            try:
+                sidecar.write_text("\n".join(lines), encoding="utf-8")
+            except OSError:
+                # Non-fatal — the burned-in subs are still present.
+                pass
+
         if on_progress:
             on_progress(100.0)
 

backend/app/studio/routes.py

@@ -2360,8 +2360,24 @@ class VideoMp4ExportRequest(BaseModel):
     ``kind`` selects the encode profile; the platform preset (canvas
     aspect, fps) is read from the StudioVideo record so the same project
     always renders to the same canvas regardless of the chosen profile.
+
+    Audio / subtitle options are additive: the defaults reproduce the
+    original concat-only behavior so the endpoint stays backward
+    compatible for clients that don't send them.
     """
     kind: Literal["mp4_plain", "mp4_youtube"] = "mp4_plain"
+    # Audio rate (tempo) multiplier applied during render, 0.5–2.0. 1.0 is
+    # untouched; <1 slows narration, >1 speeds it up. Duration of the
+    # output clip stretches / shrinks accordingly.
+    audio_rate: float = 1.0
+    # Audio pitch shift, 0.5–2.0. 1.0 is untouched. Implemented with the
+    # industry-standard asetrate + atempo compound so tempo is preserved
+    # while only pitch shifts.
+    audio_pitch: float = 1.0
+    # When "burn_in", scene narration is wrapped into timed SRT cues and
+    # burned into the video via ffmpeg's libass subtitle filter. A sidecar
+    # .srt is always written alongside the MP4 when subtitles != "none".
+    subtitles: Literal["burn_in", "none"] = "none"
 
 
 @router.post("/videos/{video_id}/export/mp4", status_code=202)
@@ -2394,6 +2410,8 @@ def video_export_mp4(
         raise HTTPException(status_code=400, detail="Video has no scenes to render")
 
     # Translate StudioScene records into the renderer's SceneInput shape.
+    # ``narration`` is the source text for subtitles; it is the same field
+    # the Piper WASM wizard used to synthesize the uploaded audioUrl.
     inputs = [
         SceneInput(
             idx=i,
@@ -2401,20 +2419,100 @@ def video_export_mp4(
             image_path=s.imageUrl,
             video_path=s.videoUrl,
             audio_path=s.audioUrl,
+            narration=s.narration or "",
         )
         for i, s in enumerate(scenes)
     ]
 
+    # Clamp audio-transform inputs. The renderer itself has additional
+    # defensive clamps, but rejecting absurd values at the API boundary
+    # makes error messages clearer.
+    audio_rate = max(0.5, min(2.0, float(req.audio_rate or 1.0)))
+    audio_pitch = max(0.5, min(2.0, float(req.audio_pitch or 1.0)))
+
     job = render_jobs.submit_render(
         user_id=user["id"],
         video_id=video_id,
         kind=req.kind,
         preset=video.platformPreset,
         scenes=inputs,
+        audio_rate=audio_rate,
+        audio_pitch=audio_pitch,
+        subtitles=req.subtitles,
     )
     return job.to_dict()
 
 
+# ----------------------------------------------------------------------------
+# Narration upload
+# ----------------------------------------------------------------------------
+# The Creator Studio export wizard synthesizes per-scene narration with the
+# Piper WASM engine (in-browser), then uploads each WAV here. The server
+# persists the file under UPLOAD_DIR/studio/narration/<scene_id>.wav and
+# writes scene.audioUrl. During render the concat pipeline mixes this audio
+# into the final MP4.
+
+from fastapi import UploadFile, File
+
+
+@router.post("/videos/{video_id}/scenes/{scene_id}/narration")
+async def upload_scene_narration(
+    video_id: str,
+    scene_id: str,
+    file: UploadFile = File(..., description="Audio file (Piper-synthesized WAV)"),
+    authorization: str = Header(default=""),
+    homepilot_session: Optional[str] = Cookie(default=None),
+):
+    """Accept a narration audio upload for a scene. Writes ``scene.audioUrl``."""
+    _user = _resolve_user_or_401(authorization, homepilot_session)
+
+    video = get_video(video_id)
+    if not video:
+        raise HTTPException(status_code=404, detail="Video not found")
+    scene = get_scene(scene_id)
+    if not scene or scene.videoId != video_id:
+        raise HTTPException(status_code=404, detail="Scene not found")
+
+    # Piper produces 16-bit PCM WAV. Accept common audio types; the
+    # renderer normalizes anyway.
+    allowed_prefixes = ("audio/", "application/octet-stream")
+    ctype = (file.content_type or "").lower()
+    if ctype and not any(ctype.startswith(p) for p in allowed_prefixes):
+        raise HTTPException(
+            status_code=415,
+            detail=f"Unsupported narration content-type: {file.content_type}",
+        )
+
+    # Cap the upload at 50 MB — a minute of 48 kHz 16-bit stereo WAV is
+    # ~11 MB, so this is generous even for long scenes.
+    MAX_BYTES = 50 * 1024 * 1024
+    payload = await file.read(MAX_BYTES + 1)
+    if len(payload) > MAX_BYTES:
+        raise HTTPException(status_code=413, detail="Narration file too large (>50 MB)")
+    if not payload:
+        raise HTTPException(status_code=400, detail="Empty narration file")
+
+    from ..config import UPLOAD_DIR
+    narration_dir = os.path.join(UPLOAD_DIR, "studio", "narration")
+    os.makedirs(narration_dir, exist_ok=True)
+    # Use the scene_id as the filename so re-uploads replace the previous
+    # take cleanly and there is no growing pile of orphan wav files.
+    dest_path = os.path.join(narration_dir, f"{scene_id}.wav")
+    with open(dest_path, "wb") as fh:
+        fh.write(payload)
+
+    # Write back via the existing scene update path so everything
+    # downstream (frontend list, exporter) reads a consistent record.
+    update_scene(scene_id, StudioSceneUpdate(audioUrl=dest_path))
+
+    return {
+        "ok": True,
+        "scene_id": scene_id,
+        "audioUrl": dest_path,
+        "bytes": len(payload),
+    }
+
+
 @router.get("/videos/{video_id}/export/jobs/{job_id}")
 def video_export_job_status(
     video_id: str,

backend/app/voice_call/__init__.py

@@ -0,0 +1,16 @@
+"""
+HomePilot voice-call — additive backend module.
+
+Scope (MVP M1)
+--------------
+Purely additive feature. With ``VOICE_CALL_ENABLED=false`` (the default)
+this package is never imported into the running app and the DB tables it
+needs are never created — dropping the module directory is sufficient to
+remove the feature entirely.
+
+Public entry point is :func:`voice_call.router.build_router`; everything
+else is internal. No existing backend module imports from this package.
+"""
+from __future__ import annotations
+
+__all__ = ["config", "router"]

backend/app/voice_call/barge_in.py

@@ -0,0 +1,123 @@
+"""
+Per-session barge-in token registry.
+
+One process-local ``dict`` keyed by ``session_id``; each entry carries
+a single :class:`BargeInToken` representing the currently-active
+assistant turn. The token exposes an ``asyncio.Event`` the streaming
+turn runner polls between chunks — when the client sends
+``user.barge_in`` the WS handler calls :func:`cancel_active` which
+flips the event and the generator exits cleanly on its next poll.
+
+The module is deliberately small and state-machine-only:
+
+  * no HTTP, no DB, no asyncio transport — unit-testable in
+    milliseconds,
+  * ``cancel_active`` refuses cancels for stale ``turn_id`` values so
+    a barge-in racing a new turn is a silent no-op,
+  * ``cancel`` is idempotent (``asyncio.Event.set()`` is idempotent),
+  * ``clear`` wipes a session on WS close so a resume starts fresh.
+
+Contract is documented in
+``docs/analysis/voice-call-streaming-design.md`` § 4.3.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+@dataclass
+class BargeInToken:
+    """Per-turn cancellation handle.
+
+    Created by :func:`new_token` when the WS handler starts streaming
+    an assistant turn; polled by the streaming runner; flipped by
+    :func:`cancel_active` when the user barges in.
+    """
+
+    turn_id: str
+    _ev: asyncio.Event = field(default_factory=asyncio.Event)
+
+    def cancel(self) -> None:
+        """Flip the event. Idempotent."""
+        self._ev.set()
+
+    def is_cancelled(self) -> bool:
+        """Cheap read the streaming runner calls between chunks."""
+        return self._ev.is_set()
+
+    async def wait(self) -> None:
+        """Optional helper for callers that want to ``asyncio.wait``
+        on cancel rather than poll."""
+        await self._ev.wait()
+
+
+# ── process-local registry ────────────────────────────────────────────
+# One active token per session. A single lock because the hot path
+# (``cancel_active``) is O(1) — no contention worth sharding for.
+
+_lock = threading.Lock()
+_active: Dict[str, BargeInToken] = {}
+
+
+def new_token(session_id: str, turn_id: str) -> BargeInToken:
+    """Register ``turn_id`` as the active turn for ``session_id``.
+
+    Any previous active token for this session is replaced — if a
+    turn started without the previous one clearing (which would be
+    a bug upstream) we fail gracefully rather than leak.
+    """
+    token = BargeInToken(turn_id=turn_id)
+    with _lock:
+        _active[session_id] = token
+    return token
+
+
+def cancel_active(session_id: str, turn_id: str) -> bool:
+    """Cancel the active turn for ``session_id`` IFF its ``turn_id``
+    matches the argument.
+
+    Returns True on a successful cancel, False if the active turn has
+    a different id (stale barge-in) or no turn is active.
+    """
+    with _lock:
+        token = _active.get(session_id)
+        if token is None or token.turn_id != turn_id:
+            return False
+    # Release the lock before setting — the event set is itself
+    # thread-safe, and keeping the lock narrow keeps the hot path
+    # fast under contention.
+    token.cancel()
+    return True
+
+
+def get_active(session_id: str) -> Optional[BargeInToken]:
+    """Read the currently-active token without mutating.
+
+    Used by the WS handler to find the active ``turn_id`` when the
+    client sends a ``transcript.partial`` (secondary barge-in signal)
+    without an explicit ``turn_id``.
+    """
+    with _lock:
+        return _active.get(session_id)
+
+
+def clear_session(session_id: str) -> None:
+    """Drop all tokens for ``session_id`` — called on WS close.
+
+    If a turn was mid-stream we cancel it first so the streaming
+    runner exits promptly; the handler is responsible for emitting
+    the final envelope.
+    """
+    with _lock:
+        token = _active.pop(session_id, None)
+    if token is not None and not token.is_cancelled():
+        token.cancel()
+
+
+def _reset_for_tests() -> None:
+    """Test hook — wipe the whole registry between cases."""
+    with _lock:
+        _active.clear()

backend/app/voice_call/config.py

@@ -0,0 +1,92 @@
+"""
+voice_call runtime configuration.
+
+Every knob is an environment variable with a safe default. The feature
+ships **off by default** — set ``VOICE_CALL_ENABLED=true`` to opt in.
+
+Privacy defaults are deliberately conservative per the review note
+("treat storage/privacy as first-class from day 1"):
+- ``VOICE_CALL_STORE_TRANSCRIPTS`` defaults to ``false``.
+- Metadata persistence (sessions + events) is enabled by default, but
+  events only record event *types*, not full audio or raw user text.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _bool_env(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _int_env(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return default
+
+
+@dataclass(frozen=True)
+class VoiceCallConfig:
+    """Resolved runtime knobs. Immutable; re-import to refresh in tests."""
+
+    # Master flag. When false, ``router.build_router()`` returns an empty
+    # router and ``store.migrate()`` is a no-op — the feature is entirely
+    # latent.
+    enabled: bool
+
+    # WebSocket transport for the turn bridge. Off => HTTP-only polling
+    # fallback (not yet implemented, so if disabled the feature is
+    # effectively off even if ``enabled`` is true).
+    websocket_enabled: bool
+
+    # Provider strategy. Only "internal" is wired at MVP; the string is
+    # reserved for future external-realtime adapters.
+    provider: str
+
+    # Policy caps (server-enforced — never trust the client).
+    max_duration_sec: int
+    idle_timeout_sec: int
+    resume_window_sec: int
+    max_concurrent_per_user: int
+    session_create_rate_per_min: int
+
+    # Privacy. Turn transcripts are NOT persisted by default.
+    store_transcripts: bool
+    artifact_retention_days: int
+
+    # Phase 2 + 3 streaming (token-level LLM streaming + barge-in).
+    # Defaults off — when false, every byte on the wire and every
+    # code path taken is identical to today. Independent of
+    # ``enabled`` / ``websocket_enabled`` so the streaming path
+    # can be dark-shipped alongside unary turns for measurement.
+    streaming_enabled: bool
+    # Barge-in is an optional sub-feature of streaming; can be
+    # disabled independently if the VAD tap is misbehaving on a
+    # given deployment.
+    barge_in_enabled: bool
+
+
+def load() -> VoiceCallConfig:
+    """Resolve config from env vars every call. Cheap; keep fresh for tests."""
+    return VoiceCallConfig(
+        enabled=_bool_env("VOICE_CALL_ENABLED", False),
+        websocket_enabled=_bool_env("VOICE_CALL_WEBSOCKET_ENABLED", True),
+        provider=os.getenv("VOICE_CALL_PROVIDER", "internal").strip() or "internal",
+        max_duration_sec=_int_env("VOICE_CALL_MAX_DURATION_SEC", 45 * 60),
+        idle_timeout_sec=_int_env("VOICE_CALL_IDLE_TIMEOUT_SEC", 30),
+        resume_window_sec=_int_env("VOICE_CALL_RESUME_WINDOW_SEC", 20),
+        max_concurrent_per_user=_int_env("VOICE_CALL_MAX_CONCURRENT", 2),
+        session_create_rate_per_min=_int_env("VOICE_CALL_CREATE_RATE", 10),
+        store_transcripts=_bool_env("VOICE_CALL_STORE_TRANSCRIPTS", False),
+        artifact_retention_days=_int_env("VOICE_CALL_ARTIFACT_TTL_DAYS", 30),
+        streaming_enabled=_bool_env("VOICE_CALL_STREAMING_ENABLED", False),
+        barge_in_enabled=_bool_env("VOICE_CALL_BARGE_IN_ENABLED", True),
+    )

backend/app/voice_call/models.py

@@ -0,0 +1,112 @@
+"""
+voice_call request / response / event schemas.
+
+Kept small on purpose: the public surface is half a dozen shapes. If a
+new field is needed, add it optional so the client stays forward-
+compatible with older backends (same rule the rest of HomePilot follows).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+from pydantic import BaseModel, Field
+
+
+EntryMode = Literal["header_button", "long_press", "hint_tap", "resume"]
+
+SessionStatus = Literal[
+    "connecting",
+    "live",
+    "interrupted",  # WS dropped, within resume window
+    "ending",
+    "ended",
+]
+
+
+class DeviceInfo(BaseModel):
+    platform: Optional[str] = None      # "web" / "ios" / "android" / "desktop"
+    app_version: Optional[str] = None
+
+
+class CreateSessionReq(BaseModel):
+    conversation_id: Optional[str] = None
+    persona_id: Optional[str] = None
+    entry_mode: EntryMode = "header_button"
+    device_info: DeviceInfo = Field(default_factory=DeviceInfo)
+
+
+class Capabilities(BaseModel):
+    """What the server promises this session can do. Keep truthful — any
+    false promise here turns into a UX bug users feel immediately."""
+    # At MVP turn-based only. Full duplex (true barge-in) reads as false
+    # until we add server-side audio, per the review note.
+    interruptions: bool = False
+    barge_in: bool = False
+    # Assistant replies come as ``transcript.final`` only — no partials.
+    # This matches the current ``/v1/chat/completions`` behavior which
+    # rejects streaming with a 501 (openai_compat_endpoint.py:477).
+    transcript_live: bool = False
+    # Phase 2/3 opt-in — set True on the response when
+    # ``VOICE_CALL_STREAMING_ENABLED`` is on. Unaware clients ignore
+    # the field and stay on the unary path.
+    streaming: bool = False
+
+
+class CreateSessionResp(BaseModel):
+    session_id: str
+    ws_url: str
+    resume_token: str        # short-lived; only accepted by ws handshake
+    expires_at: int          # epoch ms; WS must open before this
+    max_duration_sec: int
+    capabilities: Capabilities
+
+
+class Session(BaseModel):
+    """Public session record. Mirrors the DB row without resume_token or
+    raw payloads, so an accidental log of this shape never leaks
+    credentials."""
+    id: str
+    user_id: str
+    conversation_id: Optional[str] = None
+    persona_id: Optional[str] = None
+    entry_mode: EntryMode
+    status: SessionStatus
+    started_at: int
+    ended_at: Optional[int] = None
+    ended_reason: Optional[str] = None
+    duration_sec: Optional[int] = None
+
+
+class EndSessionResp(BaseModel):
+    session_id: str
+    status: SessionStatus
+    ended_at: int
+    ended_reason: str
+    duration_sec: int
+
+
+class HintsResp(BaseModel):
+    """Discoverability copy + timings. Server is the source of truth so
+    the product team can tune thresholds without a frontend ship."""
+    hint_enabled: bool = True
+    show_on_mic_tap: bool = True
+    auto_hide_ms: int = 1400
+    hold_threshold_ms: int = 220
+    # Which entry modes this build accepts. Lets us A/B or disable a
+    # mode without a client change.
+    accepted_entry_modes: List[EntryMode] = Field(
+        default_factory=lambda: ["header_button", "long_press", "hint_tap"]
+    )
+
+
+# ── WebSocket event envelope ──────────────────────────────────────────
+
+class WsEvent(BaseModel):
+    """Every message over the WS — both directions — wraps into this.
+
+    ``seq`` is monotonic per session for events the server originates;
+    client-originated events don't need it (server ignores it if set).
+    """
+    type: str
+    seq: Optional[int] = None
+    ts: Optional[int] = None
+    payload: Dict[str, Any] = Field(default_factory=dict)

backend/app/voice_call/policy.py

@@ -0,0 +1,73 @@
+"""
+Server-enforced policy for voice-call sessions.
+
+Never trust the client; every cap here is enforced before a session row
+is inserted or a WebSocket is accepted. Counters live in the DB via
+``store`` so they survive process restarts and apply across workers.
+"""
+from __future__ import annotations
+
+from . import store
+from .config import VoiceCallConfig
+
+
+class PolicyError(Exception):
+    """Raised when a caller violates a policy cap. Carries an HTTP status
+    and a short machine-readable code so the router can return a clean
+    JSON error without leaking internals."""
+
+    def __init__(self, http_status: int, code: str, detail: str) -> None:
+        super().__init__(detail)
+        self.http_status = http_status
+        self.code = code
+        self.detail = detail
+
+
+def check_session_create(*, user_id: str, cfg: VoiceCallConfig) -> None:
+    """Called before :func:`store.create_session`. Raises ``PolicyError``
+    on any violation.
+
+    Checks applied, in order of cheapness:
+      1. ``VOICE_CALL_ENABLED`` — feature gate.
+      2. Concurrent session cap (default 2). Stops the "infinite parallel
+         calls" abuse vector.
+      3. Rate limit on session creates (default 10 / 60 s). Stops script
+         kiddies from hammering ``/sessions``.
+    """
+    if not cfg.enabled:
+        raise PolicyError(
+            http_status=404, code="voice_call_disabled",
+            detail="Voice call feature is not enabled on this server.",
+        )
+
+    active = store.count_active_sessions_for_user(user_id)
+    if active >= cfg.max_concurrent_per_user:
+        raise PolicyError(
+            http_status=409, code="too_many_active_sessions",
+            detail=(
+                f"You already have {active} active voice call(s). "
+                f"End one before starting a new one."
+            ),
+        )
+
+    recent = store.recent_session_creates_for_user(
+        user_id, window_sec=60,
+    )
+    if recent >= cfg.session_create_rate_per_min:
+        raise PolicyError(
+            http_status=429, code="rate_limited",
+            detail=(
+                f"Too many voice call starts in the last minute "
+                f"(limit {cfg.session_create_rate_per_min})."
+            ),
+        )
+
+
+def session_hard_cap_exceeded(session_row: dict, cfg: VoiceCallConfig) -> bool:
+    """True if the session has exceeded its hard duration cap.
+    The WS orchestrator checks this every heartbeat to force ``ending``."""
+    started = int(session_row.get("started_at") or 0)
+    if started <= 0:
+        return False
+    now_ms = int(__import__("time").time() * 1000)
+    return (now_ms - started) >= cfg.max_duration_sec * 1000

backend/app/voice_call/router.py

@@ -0,0 +1,223 @@
+"""
+Public HTTP + WebSocket surface.
+
+All endpoints live under ``/v1/voice-call/*``. The router is built
+dynamically so that with ``VOICE_CALL_ENABLED=false`` it returns an
+empty router — no endpoints, no 500s, no accidental exposure.
+
+Mount from main.py ONCE, always behind the feature flag::
+
+    from .voice_call.router import build_router, build_ws_router
+    from .voice_call.config import load as _vc_load
+    _vc_cfg = _vc_load()
+    if _vc_cfg.enabled:
+        app.include_router(build_router(_vc_cfg))
+        app.include_router(build_ws_router(_vc_cfg))
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+from fastapi import (
+    APIRouter, Cookie, Depends, Header, HTTPException,
+    Query, WebSocket,
+)
+from fastapi.responses import JSONResponse
+
+from . import service, store, ws as ws_mod
+from .config import VoiceCallConfig
+from .models import (
+    Capabilities, CreateSessionReq, CreateSessionResp,
+    EndSessionResp, HintsResp, Session,
+)
+from .policy import PolicyError
+
+
+logger = logging.getLogger("voice_call.http")
+
+
+# ── shared auth resolver (matches main._scoped_user_or_none) ──────────
+# Kept inline to avoid a circular import. Same semantics: single-user
+# installs auto-resolve to the default user; multi-user installs require
+# a bearer token.
+
+def _resolve_user(
+    authorization: str,
+    homepilot_session: Optional[str],
+) -> dict:
+    from ..users import (
+        ensure_users_tables, _validate_token,
+        get_or_create_default_user, count_users,
+    )
+    ensure_users_tables()
+    token = ""
+    if authorization and authorization.lower().startswith("bearer "):
+        token = authorization.split(" ", 1)[1].strip()
+    if not token and homepilot_session:
+        token = homepilot_session.strip()
+    user = _validate_token(token) if token else None
+    if user:
+        return user
+    if count_users() > 1:
+        raise HTTPException(status_code=401, detail="Authentication required")
+    return get_or_create_default_user()
+
+
+# ── helpers ────────────────────────────────────────────────────────────
+
+def _public_session(row: dict) -> Session:
+    """Strip the resume_token out before the dict leaves the server."""
+    duration = None
+    if row.get("ended_at") and row.get("started_at"):
+        duration = int((int(row["ended_at"]) - int(row["started_at"])) / 1000)
+    return Session(
+        id=row["id"],
+        user_id=row["user_id"],
+        conversation_id=row.get("conversation_id"),
+        persona_id=row.get("persona_id"),
+        entry_mode=row["entry_mode"],
+        status=row["status"],
+        started_at=int(row["started_at"]),
+        ended_at=int(row["ended_at"]) if row.get("ended_at") else None,
+        ended_reason=row.get("ended_reason"),
+        duration_sec=duration,
+    )
+
+
+def _ws_url_for(session_id: str) -> str:
+    """The WS URL the client should open. Override via env for
+    containerized deployments where 127.0.0.1 is wrong."""
+    base = (
+        os.getenv("VOICE_CALL_PUBLIC_WS_BASE")
+        or "ws://127.0.0.1:8000"
+    ).rstrip("/")
+    return f"{base}/v1/voice-call/ws/{session_id}"
+
+
+# ── HTTP router ────────────────────────────────────────────────────────
+
+def build_router(cfg: VoiceCallConfig) -> APIRouter:
+    """Return the REST sub-router. Empty router if feature off."""
+    r = APIRouter(prefix="/v1/voice-call", tags=["voice-call"])
+    if not cfg.enabled:
+        return r  # feature off → empty surface
+
+    @r.post("/sessions", response_model=CreateSessionResp, status_code=201)
+    def create_session(
+        body: CreateSessionReq,
+        authorization: str = Header(default=""),
+        homepilot_session: Optional[str] = Cookie(default=None),
+    ):
+        user = _resolve_user(authorization, homepilot_session)
+        try:
+            row = service.create_session(
+                user_id=user["id"],
+                conversation_id=body.conversation_id,
+                persona_id=body.persona_id,
+                entry_mode=body.entry_mode,
+                client_platform=body.device_info.platform,
+                app_version=body.device_info.app_version,
+                cfg=cfg,
+            )
+        except PolicyError as exc:
+            logger.warning(
+                "[call] create_session policy_error user=%s code=%s status=%s",
+                user["id"], exc.code, exc.http_status,
+            )
+            return JSONResponse(
+                status_code=exc.http_status,
+                content={"ok": False, "code": exc.code, "detail": exc.detail},
+            )
+        logger.info(
+            "[call] create_session ok user=%s sid=%s persona=%s conv=%s",
+            user["id"], row["id"], body.persona_id, body.conversation_id,
+        )
+        # Token is only returned in the create response — never again.
+        expires_at = int(row["created_at"]) + 15 * 60 * 1000
+        return CreateSessionResp(
+            session_id=row["id"],
+            ws_url=_ws_url_for(row["id"]),
+            resume_token=row["resume_token"],
+            expires_at=expires_at,
+            max_duration_sec=cfg.max_duration_sec,
+            capabilities=Capabilities(
+                interruptions=False,
+                # barge_in reflects the combined streaming + barge-in
+                # flag pair — it only works when the session actually
+                # streams, since there's nothing to cancel in unary.
+                barge_in=cfg.streaming_enabled and cfg.barge_in_enabled,
+                # transcript_live = streaming assistant partials.
+                transcript_live=cfg.streaming_enabled,
+                streaming=cfg.streaming_enabled,
+            ),
+        )
+
+    @r.get("/sessions/{sid}", response_model=Session)
+    def get_session(
+        sid: str,
+        authorization: str = Header(default=""),
+        homepilot_session: Optional[str] = Cookie(default=None),
+    ):
+        user = _resolve_user(authorization, homepilot_session)
+        row = service.get(sid, user["id"])
+        if row is None:
+            # 404, never 403 — probe-safe.
+            logger.info("[call] get_session miss user=%s sid=%s", user["id"], sid)
+            raise HTTPException(status_code=404, detail="Session not found")
+        return _public_session(row)
+
+    @r.post("/sessions/{sid}/end", response_model=EndSessionResp)
+    def end_session_ep(
+        sid: str,
+        authorization: str = Header(default=""),
+        homepilot_session: Optional[str] = Cookie(default=None),
+    ):
+        user = _resolve_user(authorization, homepilot_session)
+        row = service.end_session(sid=sid, user_id=user["id"])
+        if row is None:
+            logger.info("[call] end_session miss user=%s sid=%s", user["id"], sid)
+            raise HTTPException(status_code=404, detail="Session not found")
+        logger.info(
+            "[call] end_session ok user=%s sid=%s reason=%s",
+            user["id"], sid, row.get("ended_reason"),
+        )
+        public = _public_session(row)
+        return EndSessionResp(
+            session_id=public.id,
+            status=public.status,
+            ended_at=public.ended_at or int(row["updated_at"]),
+            ended_reason=public.ended_reason or "user_ended",
+            duration_sec=public.duration_sec or 0,
+        )
+
+    @r.get("/hints", response_model=HintsResp)
+    def hints():
+        # Public on purpose — the client needs this BEFORE it has a
+        # session. Still costs nothing to allow without auth.
+        return HintsResp()
+
+    return r
+
+
+# ── WS router ──────────────────────────────────────────────────────────
+
+def build_ws_router(cfg: VoiceCallConfig) -> APIRouter:
+    r = APIRouter(prefix="/v1/voice-call", tags=["voice-call"])
+    if not cfg.enabled or not cfg.websocket_enabled:
+        return r
+
+    @r.websocket("/ws/{session_id}")
+    async def voice_call_ws(
+        websocket: WebSocket,
+        session_id: str,
+        resume_token: Optional[str] = Query(default=None),
+    ):
+        # Accept first so we can close with a clean error code if needed.
+        await websocket.accept()
+        await ws_mod.run_session_ws(
+            websocket, session_id, resume_token, cfg,
+        )
+
+    return r

backend/app/voice_call/service.py

@@ -0,0 +1,145 @@
+"""
+Pure-Python state machine for a voice-call session.
+
+No HTTP or WebSocket imports here — the router/WS layers consume this
+module. That separation lets the unit tests drive the state machine
+end-to-end without spinning up FastAPI.
+
+State flow (from the design doc, collapsed for MVP):
+
+    connecting  →  live  →  ending  →  ended
+         │             │
+         │             ├─ interrupted  (WS dropped, within resume window)
+         │             │       │
+         │             │       └─→ live again (on resume)
+         │             │       └─→ ended (resume window expired)
+         │
+         └─ ended (ws never opens)
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+from . import store
+from .config import VoiceCallConfig
+from .policy import PolicyError, check_session_create
+
+
+_TERMINAL_STATES = {"ended"}
+_LIVE_STATES = {"connecting", "live", "interrupted"}
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+# ── create / end ─────────────────────────────────────────────────────
+
+def create_session(
+    *,
+    user_id: str,
+    conversation_id: Optional[str],
+    persona_id: Optional[str],
+    entry_mode: str,
+    client_platform: Optional[str],
+    app_version: Optional[str],
+    cfg: VoiceCallConfig,
+) -> Dict[str, Any]:
+    """Gate through policy, then insert a new session row.
+
+    The returned dict includes the ``resume_token`` which the router
+    will forward to the client. Callers MUST strip this from any
+    response that ends up in an observability log.
+    """
+    check_session_create(user_id=user_id, cfg=cfg)
+    row = store.create_session(
+        user_id=user_id,
+        conversation_id=conversation_id,
+        persona_id=persona_id,
+        entry_mode=entry_mode,
+        client_platform=client_platform,
+        app_version=app_version,
+    )
+    store.append_event(
+        session_id=row["id"],
+        seq=0,
+        event_type="session.created",
+        payload={"entry_mode": entry_mode},
+    )
+    return row
+
+
+def end_session(
+    *,
+    sid: str,
+    user_id: str,
+    reason: str = "user_ended",
+) -> Optional[Dict[str, Any]]:
+    """Mark a session ``ended``. Idempotent: calling twice returns the
+    same row on the second call. Returns ``None`` if the session doesn't
+    exist OR doesn't belong to ``user_id`` (probe-safe)."""
+    row = store.get_session_for_owner(sid, user_id)
+    if row is None:
+        return None
+    if row["status"] in _TERMINAL_STATES:
+        return row  # already ended; idempotent
+    updated = store.update_session_status(sid, "ended", ended_reason=reason)
+    if updated is not None:
+        store.append_event(
+            session_id=sid,
+            seq=_next_event_seq(sid),
+            event_type="session.ended",
+            payload={"reason": reason},
+        )
+    return updated
+
+
+def get(sid: str, user_id: str) -> Optional[Dict[str, Any]]:
+    """Owner-bound getter. Mirrors :func:`store.get_session_for_owner`
+    so callers don't import store directly."""
+    return store.get_session_for_owner(sid, user_id)
+
+
+# ── internal state transitions (called from ws.py) ───────────────────
+
+def mark_live(sid: str) -> Optional[Dict[str, Any]]:
+    """Transition from ``connecting`` → ``live``. Called when the WS
+    opens with a valid resume token."""
+    return store.update_session_status(sid, "live")
+
+
+def mark_interrupted(sid: str) -> Optional[Dict[str, Any]]:
+    return store.update_session_status(sid, "interrupted")
+
+
+def mark_ended_by_timeout(sid: str, reason: str) -> Optional[Dict[str, Any]]:
+    return store.update_session_status(sid, "ended", ended_reason=reason)
+
+
+# ── sequence bookkeeping ─────────────────────────────────────────────
+
+# The server emits events with a monotonically-increasing ``seq``. We
+# keep a tiny per-process cache to avoid a SELECT MAX() on every write.
+# The cache is seeded on first use by reading the current max seq for
+# the session — so it recovers cleanly across process restarts.
+
+from threading import Lock
+_seq_cache: Dict[str, int] = {}
+_seq_lock = Lock()
+
+
+def _next_event_seq(session_id: str) -> int:
+    with _seq_lock:
+        if session_id in _seq_cache:
+            _seq_cache[session_id] += 1
+            return _seq_cache[session_id]
+        events = store.list_events(session_id, limit=1000)
+        current_max = max((e["seq"] for e in events), default=-1)
+        _seq_cache[session_id] = current_max + 1
+        return _seq_cache[session_id]
+
+
+def _reset_for_tests() -> None:
+    with _seq_lock:
+        _seq_cache.clear()

backend/app/voice_call/store.py

@@ -0,0 +1,293 @@
+"""
+SQLite access for voice_call.
+
+Follows the same pattern as backend/app/storage.py and users.py:
+direct sqlite3 calls, no ORM, per-call connections. Tables are created
+lazily by :func:`ensure_schema` — no separate migration file, no side
+effects on import. If the feature is disabled, this module is never
+loaded and no tables are created.
+"""
+from __future__ import annotations
+
+import json
+import secrets
+import sqlite3
+import time
+from typing import Any, Dict, List, Optional
+
+
+# Re-use the same DB path the rest of HomePilot uses.
+def _db_path() -> str:
+    from ..storage import _get_db_path  # lazy import, avoids cycles
+    return _get_db_path()
+
+
+def _conn() -> sqlite3.Connection:
+    con = sqlite3.connect(_db_path())
+    con.row_factory = sqlite3.Row
+    return con
+
+
+_SCHEMA_READY = False
+
+
+def ensure_schema() -> None:
+    """Create voice_call tables if they don't exist. Safe to call repeatedly."""
+    global _SCHEMA_READY
+    if _SCHEMA_READY:
+        return
+    con = _conn()
+    cur = con.cursor()
+    cur.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS voice_call_sessions (
+            id              TEXT PRIMARY KEY,
+            user_id         TEXT NOT NULL,
+            conversation_id TEXT,
+            persona_id      TEXT,
+            entry_mode      TEXT NOT NULL,
+            status          TEXT NOT NULL,
+            resume_token    TEXT NOT NULL,
+            started_at      INTEGER NOT NULL,
+            ended_at        INTEGER,
+            ended_reason    TEXT,
+            client_platform TEXT,
+            app_version     TEXT,
+            created_at      INTEGER NOT NULL,
+            updated_at      INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS ix_vcs_user_started
+            ON voice_call_sessions (user_id, started_at DESC);
+        CREATE INDEX IF NOT EXISTS ix_vcs_user_status
+            ON voice_call_sessions (user_id, status);
+
+        CREATE TABLE IF NOT EXISTS voice_call_events (
+            id          INTEGER PRIMARY KEY AUTOINCREMENT,
+            session_id  TEXT NOT NULL,
+            seq         INTEGER NOT NULL,
+            event_type  TEXT NOT NULL,
+            event_ts    INTEGER NOT NULL,
+            payload     TEXT NOT NULL DEFAULT '{}'
+        );
+        CREATE INDEX IF NOT EXISTS ix_vce_session_seq
+            ON voice_call_events (session_id, seq);
+        """
+    )
+    con.commit()
+    con.close()
+    _SCHEMA_READY = True
+
+
+# ── session CRUD ──────────────────────────────────────────────────────
+
+def new_session_id() -> str:
+    return "vcs_" + secrets.token_urlsafe(16)
+
+
+def new_resume_token() -> str:
+    return secrets.token_urlsafe(24)
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def create_session(
+    *,
+    user_id: str,
+    conversation_id: Optional[str],
+    persona_id: Optional[str],
+    entry_mode: str,
+    client_platform: Optional[str],
+    app_version: Optional[str],
+) -> Dict[str, Any]:
+    """Insert a session row in the ``connecting`` state and return it."""
+    ensure_schema()
+    sid = new_session_id()
+    token = new_resume_token()
+    now = _now_ms()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        """
+        INSERT INTO voice_call_sessions
+            (id, user_id, conversation_id, persona_id, entry_mode, status,
+             resume_token, started_at, ended_at, ended_reason,
+             client_platform, app_version, created_at, updated_at)
+        VALUES
+            (?, ?, ?, ?, ?, 'connecting', ?, ?, NULL, NULL, ?, ?, ?, ?)
+        """,
+        (sid, user_id, conversation_id, persona_id, entry_mode, token,
+         now, client_platform, app_version, now, now),
+    )
+    con.commit()
+    con.close()
+    return _select_session(sid)  # type: ignore[return-value]
+
+
+def _row_to_dict(row: sqlite3.Row) -> Dict[str, Any]:
+    d = {k: row[k] for k in row.keys()}
+    return d
+
+
+def _select_session(sid: str) -> Optional[Dict[str, Any]]:
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute("SELECT * FROM voice_call_sessions WHERE id = ?", (sid,))
+    row = cur.fetchone()
+    con.close()
+    return _row_to_dict(row) if row else None
+
+
+def get_session_for_owner(sid: str, user_id: str) -> Optional[Dict[str, Any]]:
+    """Fetch a session ONLY if it belongs to ``user_id``.
+
+    Returns ``None`` for both "not found" and "wrong owner" so callers
+    cannot probe session ids they don't own. Matches the pattern used
+    by studio render jobs.
+    """
+    row = _select_session(sid)
+    if row and row["user_id"] == user_id:
+        return row
+    return None
+
+
+def count_active_sessions_for_user(user_id: str) -> int:
+    """Count sessions that are still 'live' or 'connecting' or 'interrupted'."""
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        """
+        SELECT COUNT(*) AS n FROM voice_call_sessions
+         WHERE user_id = ?
+           AND status IN ('connecting', 'live', 'interrupted')
+        """,
+        (user_id,),
+    )
+    n = int(cur.fetchone()["n"])
+    con.close()
+    return n
+
+
+def recent_session_creates_for_user(user_id: str, window_sec: int) -> int:
+    """Session creates by ``user_id`` in the last ``window_sec`` seconds."""
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    since = _now_ms() - int(window_sec * 1000)
+    cur.execute(
+        """
+        SELECT COUNT(*) AS n FROM voice_call_sessions
+         WHERE user_id = ? AND created_at >= ?
+        """,
+        (user_id, since),
+    )
+    n = int(cur.fetchone()["n"])
+    con.close()
+    return n
+
+
+def update_session_status(
+    sid: str,
+    status: str,
+    *,
+    ended_reason: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    ensure_schema()
+    now = _now_ms()
+    con = _conn()
+    cur = con.cursor()
+    if status == "ended":
+        cur.execute(
+            """
+            UPDATE voice_call_sessions
+               SET status = 'ended', ended_at = ?, ended_reason = ?, updated_at = ?
+             WHERE id = ?
+            """,
+            (now, ended_reason or "user_ended", now, sid),
+        )
+    else:
+        cur.execute(
+            """
+            UPDATE voice_call_sessions
+               SET status = ?, updated_at = ?
+             WHERE id = ?
+            """,
+            (status, now, sid),
+        )
+    con.commit()
+    con.close()
+    return _select_session(sid)
+
+
+# ── events ────────────────────────────────────────────────────────────
+
+def append_event(
+    *,
+    session_id: str,
+    seq: int,
+    event_type: str,
+    payload: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Append a structured event row. Payload defaults to {} — DO NOT
+    pass raw audio or full user text here unless privacy flag allows it."""
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        """
+        INSERT INTO voice_call_events (session_id, seq, event_type, event_ts, payload)
+        VALUES (?, ?, ?, ?, ?)
+        """,
+        (
+            session_id,
+            int(seq),
+            event_type,
+            _now_ms(),
+            json.dumps(payload or {}, separators=(",", ":")),
+        ),
+    )
+    con.commit()
+    con.close()
+
+
+def list_events(session_id: str, limit: int = 500) -> List[Dict[str, Any]]:
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute(
+        """
+        SELECT session_id, seq, event_type, event_ts, payload
+          FROM voice_call_events
+         WHERE session_id = ?
+         ORDER BY seq ASC
+         LIMIT ?
+        """,
+        (session_id, int(limit)),
+    )
+    rows = cur.fetchall()
+    con.close()
+    out = []
+    for r in rows:
+        d = _row_to_dict(r)
+        try:
+            d["payload"] = json.loads(d.get("payload") or "{}")
+        except Exception:
+            d["payload"] = {}
+        out.append(d)
+    return out
+
+
+# ── test helper ───────────────────────────────────────────────────────
+
+def _reset_for_tests() -> None:
+    """DELETE every voice_call row. Only used by pytest fixtures."""
+    ensure_schema()
+    con = _conn()
+    cur = con.cursor()
+    cur.execute("DELETE FROM voice_call_events")
+    cur.execute("DELETE FROM voice_call_sessions")
+    con.commit()
+    con.close()

backend/app/voice_call/turn.py

@@ -0,0 +1,125 @@
+"""
+Turn bridge — send a ``transcript.final`` from the client to the
+existing ``/v1/chat/completions`` endpoint and get back an assistant
+reply (also final, no deltas).
+
+Implementation note
+-------------------
+The review confirmed the compat endpoint currently returns 501 on
+``stream=true`` (openai_compat_endpoint.py:477), so MVP M1 is final-
+only. We invoke the endpoint via an internal loopback HTTP call; that
+buys:
+
+  * zero import-time coupling to the chat module,
+  * the same auth / memory / persona context the normal chat path uses,
+  * a natural seam for the V2 realtime-provider adapter (swap this
+    function, everything else stays).
+
+When the feature flag is off this module is never imported.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+
+def _local_backend_url() -> str:
+    """Where to reach our own FastAPI server over loopback. Honors an
+    override for containerized / split-process deployments."""
+    return (
+        os.getenv("VOICE_CALL_INTERNAL_BACKEND_URL")
+        or os.getenv("HOMEPILOT_INTERNAL_BACKEND_URL")
+        or "http://127.0.0.1:8000"
+    ).rstrip("/")
+
+
+DEFAULT_TIMEOUT_SEC = float(os.getenv("VOICE_CALL_TURN_TIMEOUT_SEC", "30"))
+
+
+async def run_turn(
+    *,
+    user_text: str,
+    model: str,
+    auth_bearer: Optional[str] = None,
+    system_prompt: Optional[str] = None,
+    additional_system: Optional[str] = None,
+    history: Optional[List[Dict[str, str]]] = None,
+    extra_headers: Optional[Dict[str, str]] = None,
+) -> str:
+    """Run a single assistant turn via the existing chat endpoint.
+
+    Parameters
+    ----------
+    user_text:
+        The final STT transcript from the client.
+    model:
+        The model id. ``persona:<project_id>`` / ``personality:<id>`` /
+        plain ollama model name — whatever the existing chat endpoint
+        accepts.
+    auth_bearer:
+        The caller's bearer token, forwarded verbatim so the chat
+        endpoint sees the same user identity as the WS session owner.
+    system_prompt / history:
+        Optional pre-built context. Left empty the endpoint will attach
+        its own persona / memory context based on the model.
+    additional_system:
+        Optional extra system message appended AFTER ``system_prompt``
+        (or on its own if no ``system_prompt`` is provided). Additive
+        only — used by ``persona_call`` to inject a per-turn phone-call
+        suffix WITHOUT touching the persona's own system prompt that
+        the compat endpoint already injects for ``persona:*`` models.
+
+    Returns
+    -------
+    The assistant's reply text (the ``choices[0].message.content`` from
+    the chat completion response). Raises on non-2xx responses so the
+    caller can surface an ``error`` event over the WS.
+    """
+    messages: List[Dict[str, str]] = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    if additional_system:
+        messages.append({"role": "system", "content": additional_system})
+    if history:
+        messages.extend(history)
+    messages.append({"role": "user", "content": user_text})
+
+    headers: Dict[str, str] = {"Content-Type": "application/json"}
+    if auth_bearer:
+        headers["Authorization"] = f"Bearer {auth_bearer}"
+    if extra_headers:
+        headers.update(extra_headers)
+
+    payload = {
+        "model": model,
+        "messages": messages,
+        # Final-only — must stay False at MVP. The compat endpoint
+        # returns 501 on streaming requests.
+        "stream": False,
+        # Keep response tight for voice. Long prose makes for bad audio.
+        "max_tokens": int(os.getenv("VOICE_CALL_TURN_MAX_TOKENS", "300")),
+        "temperature": float(os.getenv("VOICE_CALL_TURN_TEMPERATURE", "0.7")),
+    }
+
+    url = f"{_local_backend_url()}/v1/chat/completions"
+    async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT_SEC) as client:
+        r = await client.post(url, json=payload, headers=headers)
+    # Let the caller see the HTTP body on error — useful for debugging.
+    if r.status_code >= 400:
+        raise RuntimeError(
+            f"chat endpoint {url} returned {r.status_code}: {r.text[:400]}"
+        )
+    data = r.json()
+    try:
+        return (
+            data["choices"][0]["message"]["content"]
+            if data.get("choices")
+            else ""
+        )
+    except (KeyError, IndexError, TypeError):
+        raise RuntimeError(
+            "chat endpoint returned an unexpected body shape: "
+            + str(data)[:400]
+        )

backend/app/voice_call/turn_stream.py

@@ -0,0 +1,259 @@
+"""
+Streaming turn runner — async-generator peer of :func:`turn.run_turn`.
+
+Yields assistant text chunks from the chat provider as they arrive so
+the WebSocket handler can emit ``assistant.partial`` envelopes without
+waiting for the full reply. Drops cleanly on barge-in cancel.
+
+Contract is documented in
+``docs/analysis/voice-call-streaming-design.md`` § 4.1 and § 4.2.
+
+Two execution paths, selected at runtime:
+
+  1. **Native streaming** — POST to the compat chat endpoint with
+     ``stream: true`` and consume the SSE / NDJSON response. This is
+     the real Phase 2 path and delivers sub-500 ms first-audio when
+     the provider supports it.
+
+  2. **Chunked-unary fallback** — if the compat endpoint returns 501
+     (current default, see ``turn.py`` comment) OR the provider
+     doesn't support streaming, we call the unary endpoint, receive
+     the full reply, and emit it in clause-sized chunks with a tiny
+     delay so the downstream plumbing (``assistant.partial`` →
+     ``streamTts.appendDelta``) still exercises correctly.
+
+The fallback yields no latency improvement — its value is keeping
+the envelope contract and the client-side streaming TTS alive even
+while the compat endpoint hasn't flipped on streaming. When it does,
+this module starts getting real deltas automatically.
+
+The persona_call suffix, persona resolution, and auth are all handled
+by ``ws.py`` / the compat endpoint exactly as today. This module
+receives the already-resolved ``user_text`` + ``model`` + headers
+and does nothing with the persona layer directly.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+from typing import AsyncIterator, Dict, List, Optional
+
+import httpx
+
+from .barge_in import BargeInToken
+
+
+def _local_backend_url() -> str:
+    return (
+        os.getenv("VOICE_CALL_INTERNAL_BACKEND_URL")
+        or os.getenv("HOMEPILOT_INTERNAL_BACKEND_URL")
+        or "http://127.0.0.1:8000"
+    ).rstrip("/")
+
+
+DEFAULT_TIMEOUT_SEC = float(os.getenv("VOICE_CALL_TURN_TIMEOUT_SEC", "60"))
+# Chunk pacing for the fallback path. Kept deliberately small so the
+# fallback "feels like" streaming without flooding the client.
+_FALLBACK_INTER_CHUNK_MS = int(os.getenv("VOICE_CALL_FALLBACK_CHUNK_MS", "35"))
+
+# Simple clause splitter used only by the fallback path. Deliberately
+# naive: split on sentence-enders first, then on commas if a sentence
+# is too long for one chunk.
+_SENTENCE_SPLIT = re.compile(r"(?<=[.!?])\s+")
+_CHUNK_MAX_CHARS = 90
+
+
+def _split_for_chunking(text: str) -> List[str]:
+    if not text:
+        return []
+    parts = [p for p in _SENTENCE_SPLIT.split(text) if p]
+    out: List[str] = []
+    for part in parts:
+        if len(part) <= _CHUNK_MAX_CHARS:
+            out.append(part)
+            continue
+        # Long sentence — split on commas, rejoining short pieces so
+        # we don't over-chunk.
+        comma_bits = [b.strip() for b in part.split(",") if b.strip()]
+        buf = ""
+        for bit in comma_bits:
+            if len(buf) + len(bit) + 2 <= _CHUNK_MAX_CHARS:
+                buf = f"{buf}, {bit}" if buf else bit
+            else:
+                if buf:
+                    out.append(buf)
+                buf = bit
+        if buf:
+            out.append(buf)
+    # Re-attach trailing whitespace so concatenation preserves spacing.
+    return [f"{p} " if not p.endswith(" ") else p for p in out]
+
+
+def _extract_delta_from_sse_line(line: str) -> Optional[str]:
+    """Parse one SSE / NDJSON frame from a streaming chat endpoint.
+
+    Supports both the OpenAI-style ``data: {...}`` SSE format and
+    Ollama's raw NDJSON (``{"message": {...}}`` per line).
+    """
+    line = line.strip()
+    if not line:
+        return None
+    if line.startswith("data:"):
+        line = line[5:].strip()
+    if line == "[DONE]":
+        return None
+    try:
+        obj = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    # OpenAI streaming: choices[0].delta.content
+    try:
+        choices = obj.get("choices") or []
+        if choices:
+            delta = (choices[0] or {}).get("delta") or {}
+            content = delta.get("content")
+            if isinstance(content, str) and content:
+                return content
+    except (AttributeError, TypeError):
+        pass
+    # Ollama streaming: message.content
+    try:
+        msg = obj.get("message") or {}
+        content = msg.get("content")
+        if isinstance(content, str) and content:
+            return content
+    except (AttributeError, TypeError):
+        pass
+    return None
+
+
+async def _yield_native_stream(
+    client: httpx.AsyncClient,
+    url: str,
+    payload: Dict,
+    headers: Dict[str, str],
+    cancel_token: BargeInToken,
+) -> AsyncIterator[str]:
+    """Native provider streaming path — returns an async iterator of
+    deltas. Caller handles 501 / 4xx / 5xx by catching the upstream
+    status before entering this coroutine."""
+    async with client.stream("POST", url, json=payload, headers=headers) as r:
+        if r.status_code == 501:
+            # Sentinel for "provider doesn't support streaming yet".
+            # Caller will fall back to chunked-unary.
+            await r.aread()
+            raise _StreamingUnsupported()
+        if r.status_code >= 400:
+            body = (await r.aread()).decode("utf-8", errors="replace")
+            raise RuntimeError(
+                f"chat stream {url} returned {r.status_code}: {body[:400]}"
+            )
+        async for line in r.aiter_lines():
+            if cancel_token.is_cancelled():
+                return
+            delta = _extract_delta_from_sse_line(line)
+            if delta:
+                yield delta
+
+
+class _StreamingUnsupported(Exception):
+    """Raised when the provider returns 501 on ``stream: true`` so the
+    caller can route to the chunked-unary fallback without conflating
+    it with an ordinary upstream error."""
+
+
+async def _yield_chunked_unary(
+    client: httpx.AsyncClient,
+    url: str,
+    payload: Dict,
+    headers: Dict[str, str],
+    cancel_token: BargeInToken,
+) -> AsyncIterator[str]:
+    """Fallback path — full unary call, then chunk the reply."""
+    unary_payload = dict(payload, stream=False)
+    r = await client.post(url, json=unary_payload, headers=headers)
+    if r.status_code >= 400:
+        raise RuntimeError(
+            f"chat endpoint {url} returned {r.status_code}: {r.text[:400]}"
+        )
+    data = r.json()
+    try:
+        reply = (
+            data["choices"][0]["message"]["content"]
+            if data.get("choices")
+            else ""
+        )
+    except (KeyError, IndexError, TypeError):
+        raise RuntimeError(
+            f"chat endpoint returned an unexpected body shape: {str(data)[:400]}"
+        )
+    for chunk in _split_for_chunking(reply):
+        if cancel_token.is_cancelled():
+            return
+        yield chunk
+        # Small delay so the client's streaming TTS has a beat to
+        # synth + play before the next chunk arrives. Keeps the
+        # fallback from flooding the WS.
+        await asyncio.sleep(_FALLBACK_INTER_CHUNK_MS / 1000.0)
+
+
+async def run_turn_streaming(
+    *,
+    user_text: str,
+    model: str,
+    auth_bearer: Optional[str] = None,
+    system_prompt: Optional[str] = None,
+    additional_system: Optional[str] = None,
+    history: Optional[List[Dict[str, str]]] = None,
+    extra_headers: Optional[Dict[str, str]] = None,
+    cancel_token: BargeInToken,
+) -> AsyncIterator[str]:
+    """Yield assistant text chunks for the given user turn.
+
+    Exits cleanly (no exception) when ``cancel_token`` is tripped by
+    a barge-in. The caller is responsible for emitting the final
+    ``assistant.turn_end`` envelope regardless of exit reason.
+    """
+    messages: List[Dict[str, str]] = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    if additional_system:
+        messages.append({"role": "system", "content": additional_system})
+    if history:
+        messages.extend(history)
+    messages.append({"role": "user", "content": user_text})
+
+    headers: Dict[str, str] = {"Content-Type": "application/json"}
+    if auth_bearer:
+        headers["Authorization"] = f"Bearer {auth_bearer}"
+    if extra_headers:
+        headers.update(extra_headers)
+
+    payload = {
+        "model": model,
+        "messages": messages,
+        "stream": True,
+        "max_tokens": int(os.getenv("VOICE_CALL_TURN_MAX_TOKENS", "300")),
+        "temperature": float(os.getenv("VOICE_CALL_TURN_TEMPERATURE", "0.7")),
+    }
+
+    url = f"{_local_backend_url()}/v1/chat/completions"
+
+    async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT_SEC) as client:
+        # Try native streaming first.
+        try:
+            async for delta in _yield_native_stream(
+                client, url, payload, headers, cancel_token,
+            ):
+                yield delta
+            return
+        except _StreamingUnsupported:
+            # Compat endpoint currently returns 501 on stream=true;
+            # fall back to unary + chunker. Covered by test.
+            pass
+        async for delta in _yield_chunked_unary(
+            client, url, payload, headers, cancel_token,
+        ):
+            yield delta

backend/app/voice_call/ws.py

@@ -0,0 +1,605 @@
+"""
+WebSocket orchestrator for voice-call sessions.
+
+Transport
+---------
+Path:            ``/v1/voice-call/ws/{session_id}``
+Query param:     ``resume_token=<token issued at POST /sessions>``
+                 (headers don't round-trip cleanly from browsers; a
+                 short-lived query token is the standard WS-auth trick)
+
+Protocol
+--------
+Server and client exchange JSON envelopes::
+
+    { "type": "<event>", "seq": <int?>, "ts": <ms>, "payload": { ... } }
+
+Client → server (each is harmless if the server can't handle it —
+forward-compatible by design):
+    ui.state            { muted, speaker_on, backgrounded }
+    transcript.final    { text, lang? }
+    call.control        { action: "end" | "ping" }
+
+Server → client:
+    call.state          { status, since }
+    transcript.final    { role: "assistant", text }
+    error               { code, message }
+    pong                { ts }
+    safety.notice       (forwarded from upstream providers, reserved)
+
+Out of scope for MVP (per review): transcript.partial (requires chat
+endpoint streaming, which returns 501 today), raw audio frames, server-
+side barge-in.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+import uuid
+from typing import Any, Dict, Optional
+
+from fastapi import WebSocket, WebSocketDisconnect, status
+
+from . import barge_in as _barge_in
+from . import service, store, turn, turn_stream
+from .config import VoiceCallConfig
+
+
+logger = logging.getLogger("voice_call.ws")
+
+
+def _clog(event: str, **kwargs: Any) -> None:
+    """Structured ``[call]`` log line — mirrors the frontend's clog()
+    format so a single grep surfaces the whole round-trip. One
+    ``logger.info`` per inflection point; fields stay flat so
+    downstream log-shippers don't have to deserialize.
+
+    Used at: session accept (open), call.state live (ready), opener
+    greeting (greet), user transcript in (turn_user_in), assistant
+    reply out (turn_assistant_out), cooperative cancel (barge_in),
+    user-ended (hangup), WS teardown (close)."""
+    logger.info("[call] %s %s", event, json.dumps(kwargs, separators=(",", ":"), default=str))
+
+HEARTBEAT_INTERVAL_SEC = 10.0
+
+# Protocol sentinels — reserved strings the frontend may send as a
+# ``transcript.final`` payload to nudge backend state without asking
+# the LLM to react. We drop these on the floor before the turn runner
+# sees them; otherwise the model treats them as literal user speech
+# and produces a confused reply (the classic "I'm not sure what
+# [phone-call-open] means" double-greet). Add new sentinels here only
+# when both sides have landed.
+_PROTOCOL_SENTINELS = frozenset({
+    "[phone-call-open]",
+    "[phone-call-close]",
+})
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+async def _send(ws: WebSocket, type_: str, payload: Dict[str, Any], *,
+                session_id: str) -> None:
+    """Send a server→client event with a monotonic seq number."""
+    seq = service._next_event_seq(session_id)
+    env = {"type": type_, "seq": seq, "ts": _now_ms(), "payload": payload}
+    try:
+        await ws.send_text(json.dumps(env, separators=(",", ":")))
+    except Exception:
+        # WebSocket already closed; caller will clean up.
+        raise
+    # Only persist the *type* for privacy unless the user has explicitly
+    # opted into transcript storage.
+    store.append_event(
+        session_id=session_id, seq=seq, event_type=type_,
+        payload={},  # intentionally empty
+    )
+
+
+async def _send_error(ws: WebSocket, session_id: str, code: str, msg: str) -> None:
+    try:
+        await _send(ws, "error",
+                    {"code": code, "message": msg},
+                    session_id=session_id)
+    except Exception:
+        pass  # best-effort
+
+
+async def _resolve_session_for_ws(
+    ws: WebSocket, session_id: str, resume_token: Optional[str],
+    cfg: VoiceCallConfig,
+) -> Optional[Dict[str, Any]]:
+    """Validate the handshake. Closes the socket with a clean code if
+    anything is off."""
+    if not cfg.websocket_enabled:
+        await ws.close(code=status.WS_1008_POLICY_VIOLATION,
+                       reason="websocket-disabled")
+        return None
+    row = store._select_session(session_id)
+    if row is None:
+        await ws.close(code=status.WS_1008_POLICY_VIOLATION,
+                       reason="session-not-found")
+        return None
+    if not resume_token or row.get("resume_token") != resume_token:
+        await ws.close(code=status.WS_1008_POLICY_VIOLATION,
+                       reason="bad-resume-token")
+        return None
+    if row.get("status") == "ended":
+        await ws.close(code=status.WS_1008_POLICY_VIOLATION,
+                       reason="session-ended")
+        return None
+    # Resume window: an "interrupted" session is only acceptable if the
+    # drop happened within the configured window.
+    if row.get("status") == "interrupted":
+        last_update = int(row.get("updated_at") or 0)
+        if _now_ms() - last_update > cfg.resume_window_sec * 1000:
+            service.mark_ended_by_timeout(session_id, "resume_expired")
+            await ws.close(code=status.WS_1008_POLICY_VIOLATION,
+                           reason="resume-expired")
+            return None
+    return row
+
+
+async def run_session_ws(
+    ws: WebSocket,
+    session_id: str,
+    resume_token: Optional[str],
+    cfg: VoiceCallConfig,
+) -> None:
+    """Main WS loop for one session. Called from router after
+    ``await ws.accept()``.
+
+    Ownership is established by the resume token alone (token is only
+    ever handed to the user who created the session). The per-turn
+    chat request also carries the caller's bearer — so the chat
+    endpoint does its own auth and refuses foreign personas even if
+    the token somehow leaks."""
+    session = await _resolve_session_for_ws(ws, session_id, resume_token, cfg)
+    if session is None:
+        return  # close already issued
+
+    # Extract the bearer from the WS query so turn.py can re-use it.
+    # Browsers can't attach custom headers to WS; the client passes
+    # ?token=<jwt> alongside ?resume_token=.
+    query_bearer = ws.query_params.get("token") or None
+
+    sid = session["id"]
+    _clog("lifecycle_open", sid=sid, persona_id=session.get("persona_id"))
+    service.mark_live(sid)
+    await _send(ws, "call.state", {"status": "live"}, session_id=sid)
+    _clog("lifecycle_ready", sid=sid)
+
+    # ── "Theory of answering" hook ────────────────────────────────
+    # When persona_call is on, the persona answers first — the way a
+    # real callee picks up the phone — instead of sitting silent
+    # until the caller speaks. The opening text comes from the
+    # curated bank in persona_call/openings.py; selection is
+    # deterministic (seeded by session_id) + persona-aware + rotated
+    # against the anti-repetition ledger, so the same caller never
+    # hears the same greeting twice in a row.
+    try:
+        from ..persona_call import (
+            config as _pc_cfg_mod,
+            context as _pc_context,
+            facets as _pc_facets,
+            openings as _pc_openings,
+            store as _pc_store,
+        )
+        _pc_cfg = _pc_cfg_mod.load()
+        if _pc_cfg.enabled:
+            _pc_store.ensure_schema()
+            _pc_store.ensure_state(sid)
+            _state = _pc_store.get_state(sid) or {}
+            forbidden = list(_state.get("recent_openers") or [])
+            _pc_env = _pc_context.compute_env(tz=None, weeks_since_last_call=-1)
+            _pc_facets_obj = _pc_facets.for_persona_id(session.get("persona_id"))
+            # We need the template *id* too so we can push it into
+            # the ledger, so call choose() (not render() directly).
+            tpl = _pc_openings.choose(
+                _pc_facets_obj, _pc_env,
+                session_id=sid,
+                turn_index=1,
+                forbidden_ids=forbidden,
+            )
+            greeting_text = None
+            if tpl is not None:
+                greeting_text = _pc_openings._interpolate(
+                    tpl.text,
+                    # Fall back to "Assistant" only if the session row
+                    # has no persona_id — matches the frontend label.
+                    (session.get("persona_id") or "Assistant").replace("persona:", "").strip(),
+                )
+                # Append the chosen id to the opener ledger, keeping
+                # only the last N so the ledger doesn't grow
+                # unbounded across long-lived sessions.
+                window = max(1, _pc_cfg.opener_ledger_window)
+                new_openers = (list(forbidden) + [tpl.id])[-window:]
+                _pc_store.update_state(sid, recent_openers=new_openers)
+            if greeting_text:
+                await _send(ws, "transcript.final",
+                            {"role": "assistant", "text": greeting_text},
+                            session_id=sid)
+                _clog("lifecycle_greet", sid=sid, text_len=len(greeting_text))
+    except Exception as _pc_err:
+        # Shadow-fail — the call still works without a greeting.
+        logger.warning("[persona_call] opening greeting skipped: %s", _pc_err)
+
+    # Heartbeat keeps idle TCP paths alive on mobile networks.
+    hb_task = asyncio.create_task(_heartbeat_loop(ws, sid, cfg))
+
+    try:
+        while True:
+            try:
+                text = await asyncio.wait_for(
+                    ws.receive_text(),
+                    timeout=cfg.idle_timeout_sec,
+                )
+            except asyncio.TimeoutError:
+                await _send_error(ws, sid, "idle_timeout",
+                                  "No activity for a while — ending call.")
+                service.end_session(sid=sid, user_id=session["user_id"],
+                                    reason="idle")
+                await _send(ws, "call.state", {"status": "ended",
+                                               "reason": "idle"},
+                            session_id=sid)
+                break
+
+            try:
+                env = json.loads(text)
+            except json.JSONDecodeError:
+                await _send_error(ws, sid, "bad_json", "Invalid JSON envelope.")
+                continue
+
+            evt_type = env.get("type")
+            payload = env.get("payload") or {}
+
+            if evt_type == "call.control":
+                action = (payload.get("action") or "").strip()
+                if action == "end":
+                    service.end_session(sid=sid, user_id=session["user_id"],
+                                        reason="user_ended")
+                    await _send(ws, "call.state", {"status": "ended",
+                                                   "reason": "user_ended"},
+                                session_id=sid)
+                    _clog("lifecycle_hangup", sid=sid, reason="user_ended")
+                    break
+                if action == "ping":
+                    await _send(ws, "pong", {}, session_id=sid)
+
+            elif evt_type == "ui.state":
+                # Pure bookkeeping. Client tells us muted / speaker_on /
+                # backgrounded; we persist only the type (privacy).
+                pass
+
+            elif evt_type == "transcript.final":
+                text_in = (payload.get("text") or "").strip()
+                if not text_in:
+                    continue
+                # Protocol sentinels are NOT user utterances — they
+                # exist solely so the frontend can signal state
+                # transitions (phase machine nudges, etc.) without
+                # the LLM reacting to the literal string. Drop and
+                # continue; the phase machine already advances on the
+                # first real user utterance, so no special handling
+                # is required here beyond not running the turn.
+                if text_in in _PROTOCOL_SENTINELS:
+                    continue
+                _clog("turn_user_in", sid=sid, text_len=len(text_in))
+                model = (
+                    payload.get("model")
+                    or session.get("persona_id")
+                    and f"persona:{session['persona_id']}"
+                    or "llama3:8b"
+                )
+
+                # ── persona_call hook ───────────────────────────────
+                # Additive, behind its own feature flag. Composes a
+                # per-turn system SUFFIX (never touches the persona's
+                # base system prompt) and — if cfg.apply is True —
+                # appends it as an extra system message on the chat
+                # call. Wraps the turn in a filler scheduler so a long
+                # LLM wait produces a "hmm…" event within 600 ms.
+                pc_additional_system: Optional[str] = None
+                pc_persona_id: Optional[str] = session.get("persona_id")
+                try:
+                    from ..persona_call import (
+                        config as _pc_cfg_mod,
+                        context as _pc_context,
+                        directive as _pc_directive,
+                        facets as _pc_facets,
+                        latency as _pc_latency,
+                    )
+                    _pc_cfg = _pc_cfg_mod.load()
+                except Exception:
+                    _pc_cfg = None  # persona_call not importable; skip
+
+                _pc_facets_obj = None
+                if _pc_cfg is not None and _pc_cfg.enabled:
+                    try:
+                        _pc_env = _pc_context.compute_env(
+                            tz=(session.get("client_platform") and None),
+                            weeks_since_last_call=-1,
+                        )
+                        _pc_facets_obj = _pc_facets.for_persona_id(pc_persona_id)
+                        composed = _pc_directive.compose(
+                            session_id=sid,
+                            persona_id=pc_persona_id,
+                            user_text=text_in,
+                            env=_pc_env,
+                            cfg=_pc_cfg,
+                            facets=_pc_facets_obj,
+                        )
+                        if _pc_cfg.apply and composed.system_suffix:
+                            pc_additional_system = composed.system_suffix
+                    except Exception as _pc_err:
+                        # Shadow fail — turn still runs without the
+                        # phone-call suffix. persona_call must never
+                        # break an otherwise-working call.
+                        logger.warning(
+                            "[persona_call] compose skipped: %s", _pc_err
+                        )
+
+                async def _pc_send(env_: dict) -> None:
+                    try:
+                        await ws.send_text(
+                            json.dumps(env_, separators=(",", ":"))
+                        )
+                    except Exception:
+                        pass
+
+                # ── Streaming vs unary turn — additive branch ──────
+                # When VOICE_CALL_STREAMING_ENABLED=true the turn runs
+                # through turn_stream.run_turn_streaming and emits
+                # ``assistant.partial`` + ``assistant.turn_end`` envelopes
+                # so the client's streaming TTS can begin speaking long
+                # before the full reply has arrived. When the flag is
+                # off we take the original path byte-for-byte.
+                if cfg.streaming_enabled:
+                    turn_id = f"t_{uuid.uuid4().hex[:12]}"
+                    token = _barge_in.new_token(sid, turn_id)
+                    assistant_text_parts: list[str] = []
+                    end_reason = "complete"
+                    try:
+                        if (
+                            _pc_cfg is not None
+                            and _pc_cfg.enabled
+                            and _pc_facets_obj is not None
+                        ):
+                            # Filler scheduler still wraps streaming —
+                            # if the FIRST delta takes > N ms the
+                            # client still gets a ``hmm…`` event.
+                            async with _pc_latency.FillerScheduler(
+                                send=_pc_send,
+                                facets=_pc_facets_obj,
+                                cfg=_pc_cfg,
+                                session_id=sid,
+                            ):
+                                index = 0
+                                async for delta in turn_stream.run_turn_streaming(
+                                    user_text=text_in,
+                                    model=model,
+                                    auth_bearer=query_bearer,
+                                    additional_system=pc_additional_system,
+                                    cancel_token=token,
+                                ):
+                                    if token.is_cancelled():
+                                        break
+                                    assistant_text_parts.append(delta)
+                                    await _send(
+                                        ws, "assistant.partial",
+                                        {
+                                            "turn_id": turn_id,
+                                            "delta": delta,
+                                            "index": index,
+                                        },
+                                        session_id=sid,
+                                    )
+                                    index += 1
+                        else:
+                            index = 0
+                            async for delta in turn_stream.run_turn_streaming(
+                                user_text=text_in,
+                                model=model,
+                                auth_bearer=query_bearer,
+                                additional_system=pc_additional_system,
+                                cancel_token=token,
+                            ):
+                                if token.is_cancelled():
+                                    break
+                                assistant_text_parts.append(delta)
+                                await _send(
+                                    ws, "assistant.partial",
+                                    {
+                                        "turn_id": turn_id,
+                                        "delta": delta,
+                                        "index": index,
+                                    },
+                                    session_id=sid,
+                                )
+                                index += 1
+                        if token.is_cancelled():
+                            end_reason = "cancelled"
+                    except Exception as exc:
+                        logger.warning("[voice_call] stream turn failed: %s", exc)
+                        end_reason = "error"
+                    finally:
+                        # Always emit turn_end so the client can close
+                        # the turn bookkeeping cleanly.
+                        _barge_in.clear_session(sid)
+                        assistant_text = "".join(assistant_text_parts)
+                        await _send(
+                            ws, "assistant.turn_end",
+                            {
+                                "turn_id": turn_id,
+                                "reason": end_reason,
+                                "full_text": assistant_text,
+                            },
+                            session_id=sid,
+                        )
+                        _clog(
+                            "turn_assistant_out",
+                            sid=sid,
+                            turn_id=turn_id,
+                            reason=end_reason,
+                            text_len=len(assistant_text),
+                            route="stream",
+                        )
+                else:
+                    try:
+                        if (
+                            _pc_cfg is not None
+                            and _pc_cfg.enabled
+                            and _pc_facets_obj is not None
+                        ):
+                            async with _pc_latency.FillerScheduler(
+                                send=_pc_send,
+                                facets=_pc_facets_obj,
+                                cfg=_pc_cfg,
+                                session_id=sid,
+                            ):
+                                assistant_text = await turn.run_turn(
+                                    user_text=text_in,
+                                    model=model,
+                                    auth_bearer=query_bearer,
+                                    additional_system=pc_additional_system,
+                                )
+                        else:
+                            assistant_text = await turn.run_turn(
+                                user_text=text_in,
+                                model=model,
+                                auth_bearer=query_bearer,
+                                additional_system=pc_additional_system,
+                            )
+                    except Exception as exc:
+                        logger.warning("[voice_call] turn failed: %s", exc)
+                        await _send_error(ws, sid, "turn_failed", str(exc)[:400])
+                        continue
+
+                    await _send(ws, "transcript.final",
+                                {"role": "assistant", "text": assistant_text},
+                                session_id=sid)
+                    _clog(
+                        "turn_assistant_out",
+                        sid=sid,
+                        text_len=len(assistant_text),
+                        route="unary",
+                    )
+
+                # Record the reply into the anti-repetition ledger so
+                # the NEXT turn can forbid the just-used opener/ack.
+                if _pc_cfg is not None and _pc_cfg.enabled:
+                    try:
+                        _pc_directive.record_persona_reply(
+                            session_id=sid,
+                            persona_id=pc_persona_id,
+                            reply=assistant_text,
+                            cfg=_pc_cfg,
+                        )
+                    except Exception as _pc_err:
+                        logger.warning(
+                            "[persona_call] record_reply skipped: %s",
+                            _pc_err,
+                        )
+
+            elif evt_type == "user.barge_in":
+                # Phase 3 — cooperative cancel. Client's VAD detected
+                # user speech-start while the persona was mid-reply.
+                # § 4.4 of the streaming design doc.
+                if not (cfg.streaming_enabled and cfg.barge_in_enabled):
+                    continue
+                turn_id = (payload.get("turn_id") or "").strip()
+                if not turn_id:
+                    continue
+                cancelled = _barge_in.cancel_active(sid, turn_id)
+                if cancelled:
+                    # Emit the ack IMMEDIATELY — client stops TTS on
+                    # receipt, shaving ~50-100 ms off the perceived
+                    # barge-in latency vs waiting for the generator
+                    # to notice the event on its next poll.
+                    await _send(
+                        ws, "assistant.cancel",
+                        {"turn_id": turn_id, "cause": "user_barge_in"},
+                        session_id=sid,
+                    )
+                    _clog("barge_in", sid=sid, turn_id=turn_id, cause="user_barge_in")
+                # Else: stale turn_id (turn already ended). Silent drop.
+
+            elif evt_type == "transcript.partial":
+                # Secondary barge-in signal — if the client's explicit
+                # user.barge_in didn't arrive but the STT started
+                # decoding words, that also means the user spoke.
+                # Only fires while a turn is active.
+                if not (cfg.streaming_enabled and cfg.barge_in_enabled):
+                    continue
+                active = _barge_in.get_active(sid)
+                if active is not None and not active.is_cancelled():
+                    cancelled = _barge_in.cancel_active(sid, active.turn_id)
+                    if cancelled:
+                        await _send(
+                            ws, "assistant.cancel",
+                            {
+                                "turn_id": active.turn_id,
+                                "cause": "user_partial",
+                            },
+                            session_id=sid,
+                        )
+
+            else:
+                # Forward-compat: unknown event type is a no-op, not an
+                # error. Older servers + newer clients stay friendly.
+                pass
+    except WebSocketDisconnect:
+        # Client dropped — park the session as 'interrupted' so a resume
+        # request within the window can pick it back up.
+        _barge_in.clear_session(sid)
+        service.mark_interrupted(sid)
+    except Exception as exc:
+        logger.exception("[voice_call] ws error for %s: %s", sid, exc)
+        try:
+            await _send_error(ws, sid, "internal", "Internal error")
+        except Exception:
+            pass
+        _barge_in.clear_session(sid)
+        service.mark_interrupted(sid)
+    finally:
+        _clog("lifecycle_close", sid=sid)
+        _barge_in.clear_session(sid)
+        hb_task.cancel()
+        try:
+            await hb_task
+        except Exception:
+            pass
+
+
+async def _heartbeat_loop(ws: WebSocket, session_id: str, cfg: VoiceCallConfig) -> None:
+    """Send a server-initiated ping every N seconds. Doubles as a
+    liveness check + hard-duration-cap enforcement."""
+    while True:
+        await asyncio.sleep(HEARTBEAT_INTERVAL_SEC)
+        row = store._select_session(session_id)
+        if row is None or row["status"] == "ended":
+            return
+        # Enforce hard cap.
+        started = int(row.get("started_at") or 0)
+        if started and (_now_ms() - started) >= cfg.max_duration_sec * 1000:
+            try:
+                await _send(ws, "call.state",
+                            {"status": "ending", "reason": "max_duration"},
+                            session_id=session_id)
+            except Exception:
+                return
+            service.end_session(sid=session_id, user_id=row["user_id"],
+                                reason="max_duration")
+            try:
+                await ws.close(code=status.WS_1000_NORMAL_CLOSURE,
+                               reason="max-duration")
+            except Exception:
+                pass
+            return
+        try:
+            await _send(ws, "ping", {}, session_id=session_id)
+        except Exception:
+            return

frontend/.cache-bust

@@ -1 +1 @@
-1776444513
+1776516992

frontend/src/ui/App.tsx

@@ -21,6 +21,7 @@ import {
   Copy,
   RotateCw,
   PenLine,
+  Phone,
   Users,
   EyeOff,
   BookOpen,
@@ -34,6 +35,9 @@ import UserAvatar from './components/UserAvatar'
 import AccountMenu, { type AccountMenuUser } from './components/AccountMenu'
 import { useAuth } from './components/AuthGate'
 import VoiceMode, { stripMarkdownForSpeech } from './VoiceModeGrok'
+import CallOverlay from './CallOverlay'
+import { clog, speakOwned, isCallFullDuplexEnabled } from './call/log'
+import PostCallCard from './phone/PostCallCard'
 // Legacy voice mode available as: import VoiceModeLegacy from './VoiceModeLegacy'
 import ProjectsView from './ProjectsView'
 import ImagineView from './Imagine'
@@ -113,6 +117,22 @@ export type Msg = {
     intent: 'generate_images' | 'generate_videos'
     prompt: string
   }
+  // "Call memory card" — when present the message renders as an
+  // inline record of a just-ended voice call instead of a regular
+  // bubble. Additive: untouched by every existing code path.
+  callMemory?: {
+    durationSec: number
+    /** Epoch-ms timestamp of when the call ended. Rendered as an
+     *  auditable stamp (e.g. "7:36 PM") in the card header. */
+    endedAt?: number
+    /** Persona the user was speaking with during this call — feeds
+     *  PostCallCard's "Call with X" / "X remembers" headers. */
+    personaName?: string
+    /** Optional transcript the user can expand inline from the card.
+     *  Populated by App.tsx at call-end by slicing chatMessages
+     *  between the call's open + close timestamps. */
+    transcript?: Array<{ who: 'user' | 'assistant'; text: string }>
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1574,12 +1594,92 @@ function useCopyMessage(timeoutMs = 900) {
   return { copied, copy }
 }
 
+/**
+ * CallMemoryCard — enterprise-style inline record of a just-ended
+ * call. Rendered inside the chat stream as a neutral system event
+ * rather than a floating toast or an emotional "moment" card. The
+ * tone is auditable, not expressive: the card states what happened,
+ * when, and offers one standard system action to resume.
+ */
+function CallMemoryCard({
+  durationSec,
+  endedAt,
+  onSpeakAgain,
+}: {
+  durationSec: number
+  endedAt?: number
+  onSpeakAgain?: () => void
+}) {
+  const fmt = (s: number) => {
+    if (s < 60) return `${s}s`
+    const m = Math.floor(s / 60)
+    const r = s % 60
+    return r === 0 ? `${m}m` : `${m}m ${r}s`
+  }
+  const stamp = endedAt
+    ? new Date(endedAt).toLocaleTimeString(undefined, {
+        hour: 'numeric', minute: '2-digit',
+      })
+    : ''
+  return (
+    <div
+      className="flex items-start gap-5 w-full hp-fade-in"
+      role="note"
+      aria-label="Call record"
+    >
+      <div className="w-8 h-8 rounded-full bg-white/5 border border-white/10 text-white/50 flex items-center justify-center flex-shrink-0 mt-1">
+        <Phone size={12} />
+      </div>
+      <div
+        className="max-w-[85%] rounded-[12px] px-4 py-3 bg-white/[0.03] border border-white/10"
+      >
+        {/* Meta row — factual header, low emphasis */}
+        <div className="flex items-center gap-2 text-[11px] text-white/50">
+          <span>Call</span>
+          <span className="text-white/25">·</span>
+          <span
+            className="font-mono tabular-nums text-white/70"
+            style={{ fontFeatureSettings: '"tnum"' }}
+          >
+            {fmt(durationSec)}
+          </span>
+          {stamp ? (
+            <>
+              <span className="text-white/25">·</span>
+              <span className="font-mono tabular-nums text-white/50">{stamp}</span>
+            </>
+          ) : null}
+        </div>
+        {/* Body — neutral factual line, no emotional copy */}
+        <div className="mt-1.5 text-[13.5px] leading-snug text-white/75">
+          Voice session completed
+        </div>
+        {/* CTA — system-style outline button, same weight as header icons */}
+        <div className="mt-3">
+          <button
+            type="button"
+            onClick={onSpeakAgain}
+            disabled={!onSpeakAgain}
+            className="inline-flex items-center gap-1.5 rounded-md bg-transparent hover:bg-white/5 border border-white/15 hover:border-white/25 text-white/80 hover:text-white px-3 py-1 text-[12px] font-medium transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
+            aria-label="Resume call"
+          >
+            <Phone size={12} />
+            Resume call
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+
 function ChatState({
   messages,
   setLightbox,
   endRef,
   mode,
   onNewConversation,
+  onStartCall,
   onRetryMessage,
   chatSettings,
   onUpdateChatSettings,
@@ -1598,6 +1698,9 @@ function ChatState({
   endRef: React.RefObject<HTMLDivElement>
   mode: Mode
   onNewConversation: () => void
+  /** Primary call action — opens the live-voice mode. Optional so
+   *  callers that don't want the button can omit it. */
+  onStartCall?: () => void
   onRetryMessage: (id: string) => void
   chatSettings: ChatScopedSettings
   onUpdateChatSettings: (next: ChatScopedSettings) => void
@@ -1613,6 +1716,9 @@ function ChatState({
 }) {
   const { copied, copy } = useCopyMessage()
   const [chatSettingsOpen, setChatSettingsOpen] = useState(false)
+  const handleStartCall = useCallback(() => {
+    onStartCall?.()
+  }, [onStartCall])
   // Local overrides for view-pack angle switching (keyed by message id)
   const [angleOverrides, setAngleOverrides] = useState<Record<string, { angle: string; url: string }>>({})
 
@@ -1650,9 +1756,24 @@ function ChatState({
 
   return (
     <div className="flex flex-col h-full w-full max-w-[52rem] mx-auto">
-      {/* Top-right fixed: Chat settings gear + New Chat icon (Phase 2, additive) */}
+      {/* Top-right fixed: a single flat group of neutral header icons.
+          The call button is intentionally *not* a CTA — it sits inline
+          with the other utility icons and only opens a dedicated call
+          overlay (see CallOverlay). Call mode is a distinct session,
+          not a styling of the header. */}
       <div className="fixed top-3 right-5 z-50">
-        <div className="relative flex items-center gap-3">
+        <div className="relative flex items-center gap-2">
+          {onStartCall && (
+            <button
+              type="button"
+              onClick={handleStartCall}
+              className="w-9 h-9 flex items-center justify-center rounded-full bg-white/5 border border-white/10 text-white/60 hover:bg-white/10 hover:text-white transition-colors"
+              title="Start call"
+              aria-label="Start call"
+            >
+              <Phone size={16} />
+            </button>
+          )}
           <button
             type="button"
             onClick={() => setChatSettingsOpen((v) => !v)}
@@ -1701,6 +1822,20 @@ function ChatState({
             key={m.id}
             className={`flex gap-5 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
           >
+            {/* Inline "call memory card" — renders instead of a bubble
+                when this message represents a just-ended voice call.
+                Treated as assistant-aligned (left) so it reads as "a
+                moment we shared" rather than a system toast. */}
+            {m.callMemory ? (
+              <PostCallCard
+                durationSec={m.callMemory.durationSec}
+                endedAt={m.callMemory.endedAt}
+                personaName={m.callMemory.personaName || 'Assistant'}
+                variant="expand"
+                transcript={m.callMemory.transcript}
+                onResume={onStartCall}
+              />
+            ) : (<>
             {m.role === 'assistant' ? (
               <div className="w-8 h-8 rounded-full bg-white text-black flex items-center justify-center flex-shrink-0 font-bold text-sm mt-1">
                 /
@@ -1858,6 +1993,7 @@ function ChatState({
                 ) : null}
               </div>
             )}
+            </>)}
           </div>
         ))}
         <div ref={endRef} className="h-6" />
@@ -2040,6 +2176,22 @@ export default function App() {
   })
   const [voiceConversationId, setVoiceConversationId] = useState<string>(() => uuid())
   const [lightbox, setLightbox] = useState<string | null>(null)
+  // Call mode — a dedicated session distinct from Voice mode. The
+  // header 📞 opens a centered CallOverlay; it does not swap modes.
+  const [callOpen, setCallOpen] = useState(false)
+  // `skipDialing` is flipped on for the "Speak again" re-entry so the
+  // user doesn't have to sit through "calling…" twice in a row.
+  const [callSkipDialing, setCallSkipDialing] = useState(false)
+  // Snapshot of chatMessages.length at the moment a call opens —
+  // used at call-end to slice the transcript of turns that happened
+  // during the call, for PostCallCard's expandable transcript.
+  const callOpenMsgIndexRef = useRef<number>(-1)
+  useEffect(() => {
+    if (callOpen) {
+      callOpenMsgIndexRef.current = chatMessages.length
+    }
+  }, [callOpen]) // intentionally miss chatMessages — we want the
+                 // snapshot at OPEN time, not every keystroke after
 
   // Persona Integration — "Save as Persona Avatar" from AvatarStudio (additive)
   const [saveAsPersonaData, setSaveAsPersonaData] = useState<{ item: GalleryItem; outfits: GalleryItem[]; batchSiblings?: GalleryItem[] } | null>(null)
@@ -2311,6 +2463,26 @@ export default function App() {
   // Track last spoken message to avoid re-speaking
   const lastSpokenMessageIdRef = useRef<string | null>(null)
 
+  // Call-open history guard — when the overlay opens, seed the
+  // last-spoken pointer to the CURRENT tail of ``messages``. Without
+  // this the TTS-on-assistant-reply effect treats the previous
+  // chat-history tail as a fresh reply the moment ``callOpen`` flips
+  // true, producing a pre-existing message read-aloud that collides
+  // with CallOverlay's own fallback opener (the "two openings
+  // overlapping" symptom). Only NEW assistant messages that land
+  // DURING the call will be spoken by App.tsx from here on; the
+  // call-itself-opener is owned by CallOverlay via speakOwned().
+  useEffect(() => {
+    if (!callOpen) return
+    const tail = messages[messages.length - 1]
+    lastSpokenMessageIdRef.current = tail ? tail.id : null
+    // Intentionally single-shot on callOpen flip — we don't want this
+    // to re-run on every message mutation during the call, otherwise
+    // the guard would swallow the very replies it's supposed to let
+    // through.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [callOpen])
+
   // When a voice session is explicitly chosen from Session Hub, skip the auto-link resolve
   // to prevent the useEffect from overwriting the chosen session with the active one.
   const voiceSessionExplicitRef = useRef(false)
@@ -3985,10 +4157,21 @@ ${personalityPrompt || 'You are a friendly voice assistant. Be helpful and warm.
     [authHeaders, conversationId, messages, settings.backendUrl, settings.funMode, settingsDraft]
   )
 
-  // TTS for assistant responses (speak-once pattern) - ONLY IN VOICE MODE
+  // TTS for assistant responses (speak-once pattern). Fires when
+  // the user is in Voice mode OR the CallOverlay is open. The
+  // second branch matters in the chat-REST fallback path: when
+  // VOICE_CALL_ENABLED is false server-side, the call runs through
+  // the regular chat pipeline, assistant replies land in the
+  // current ``messages`` array, and without this nothing speaks
+  // them — the user hears silence during the call.
+  //
+  // SpeechService.speak + stripMarkdownForSpeech are the canonical
+  // app-level TTS primitives; reusing them here keeps call-mode
+  // TTS consistent with voice-mode TTS (same voice pick, same
+  // markdown sanitation, same single-utterance dedupe via
+  // lastSpokenMessageIdRef).
   useEffect(() => {
-    // Only enable TTS when in Voice mode
-    if (mode !== 'voice') return
+    if (mode !== 'voice' && !callOpen) return
 
     const ttsEnabled = settingsDraft.ttsEnabled ?? true
     if (!ttsEnabled || !window.SpeechService) return
@@ -4001,6 +4184,7 @@ ${personalityPrompt || 'You are a friendly voice assistant. Be helpful and warm.
       lastMessage.role === 'assistant' &&
       !lastMessage.pending &&
       lastMessage.text &&
+      !lastMessage.callMemory &&
       lastMessage.id !== lastSpokenMessageIdRef.current
     ) {
       // Mark this message as spoken
@@ -4009,9 +4193,21 @@ ${personalityPrompt || 'You are a friendly voice assistant. Be helpful and warm.
       // Speak the assistant's response — strip markdown images/links so TTS
       // doesn't read raw URLs aloud. Images are shown visually instead.
       const speechText = stripMarkdownForSpeech(lastMessage.text)
-      if (speechText) window.SpeechService.speak(speechText)
+      if (!speechText) return
+      // During a call, route through the shared speakOwned lock so
+      // this app-level path can't double-speak alongside the overlay's
+      // fallback opener (both targeting the same assistant message).
+      // Outside a call, keep the legacy SpeechService.speak path —
+      // voice-mode has no peer TTS source so the lock would add noise
+      // without benefit.
+      if (callOpen && isCallFullDuplexEnabled()) {
+        clog({ e: 'turn', action: 'assistant_in', route: 'chat_rest' })
+        speakOwned('app-level', speechText)
+      } else {
+        window.SpeechService.speak(speechText)
+      }
     }
-  }, [messages, settingsDraft.ttsEnabled, mode])
+  }, [messages, settingsDraft.ttsEnabled, mode, callOpen])
 
   const uploadAndSend = useCallback(
     async (file: File) => {
@@ -4489,7 +4685,7 @@ ${personalityPrompt || 'You are a friendly voice assistant. Be helpful and warm.
 
         {/* Top-right Project Indicator - Only shown in chat mode when a project is active */}
         {mode === 'chat' && (
-        <header className="absolute top-0 left-0 right-0 pr-[7rem] pl-5 py-3 z-20 flex items-center justify-end gap-3 pointer-events-none">
+        <header className="absolute top-0 left-0 right-0 pr-[9rem] pl-5 py-3 z-20 flex items-center justify-end gap-3 pointer-events-none">
           {/* Project Indicator */}
           {(() => {
             const currentProjectId = localStorage.getItem('homepilot_current_project')
@@ -5049,6 +5245,7 @@ ${personalityPrompt || 'You are a friendly voice assistant. Be helpful and warm.
               endRef={endRef}
               mode={mode}
               onNewConversation={onNewConversation}
+              onStartCall={() => setCallOpen(true)}
               onRetryMessage={retryFailedMessage}
               chatSettings={chatSettings}
               onUpdateChatSettings={updateChatSettings}
@@ -5124,6 +5321,7 @@ ${personalityPrompt || 'You are a friendly voice assistant. Be helpful and warm.
             endRef={endRef}
             mode={mode}
             onNewConversation={onNewConversation}
+            onStartCall={() => setCallOpen(true)}
             onRetryMessage={retryFailedMessage}
             chatSettings={chatSettings}
             onUpdateChatSettings={updateChatSettings}
@@ -5149,6 +5347,91 @@ ${personalityPrompt || 'You are a friendly voice assistant. Be helpful and warm.
         />
       ) : null}
 
+      {/* Call overlay — a distinct session layered over the chat.
+          Open it with the 📞 header icon; end it with the red button
+          inside the overlay. Not the same as Voice mode. */}
+      <CallOverlay
+        open={callOpen}
+        onClose={() => {
+          setCallOpen(false)
+          // Reset the skip flag once the overlay has closed so the
+          // next fresh tap on 📞 starts with the full dial phase.
+          setCallSkipDialing(false)
+        }}
+        skipDialing={callSkipDialing}
+        onEnded={(durationSec) => {
+          // Append an inline PostCallCard to the chat stream. Captures
+          // the slice of turns exchanged during the call — which the
+          // user can expand inline from the card (no modal) — plus
+          // the persona name + end-of-call timestamp.
+          const endedAt = Date.now()
+          const personaName = currentProject?.name || 'Assistant'
+          const startIdx = callOpenMsgIndexRef.current
+          // Build a transcript only when we have a valid open-time
+          // snapshot AND new messages landed during the call.
+          let transcript:
+            | Array<{ who: 'user' | 'assistant'; text: string }>
+            | undefined
+          if (startIdx >= 0 && startIdx <= chatMessages.length) {
+            const slice = chatMessages.slice(startIdx)
+            const lines = slice
+              .filter((m) => !m.callMemory && (m.text || '').trim())
+              .map((m) => ({
+                who: (m.role === 'user' ? 'user' : 'assistant') as
+                  | 'user' | 'assistant',
+                text: m.text.trim(),
+              }))
+            if (lines.length > 0) transcript = lines
+          }
+          setChatMessages((prev) => [
+            ...prev,
+            {
+              id: `call-memory-${endedAt}`,
+              role: 'assistant',
+              text: '',
+              callMemory: {
+                durationSec,
+                endedAt,
+                personaName,
+                transcript,
+              },
+            },
+          ])
+        }}
+        personaName={currentProject?.name || 'Assistant'}
+        messages={chatMessages}
+        avatarUrl={(() => {
+          // Resolve the persona's thumbnail the same way
+          // PersonaSettingsPanel does: prefer
+          // persona_appearance.selected_thumb_filename, then
+          // .selected_filename, wrapped in the /files/ auth URL.
+          const pap = (currentProject?.persona_appearance as Record<string, unknown> | undefined) || {}
+          const rel =
+            (pap.selected_thumb_filename as string | undefined) ||
+            (pap.selected_filename as string | undefined)
+          if (!rel) return null
+          const base = settings.backendUrl.replace(/\/+$/, '')
+          const tok = localStorage.getItem('homepilot_auth_token') || ''
+          const clean = rel.replace(/^\/+/, '')
+          return `${base}/files/${clean}${tok ? `?token=${encodeURIComponent(tok)}` : ''}`
+        })()}
+        onSendText={(text) => sendTextOrIntent(text)}
+        backend={{
+          backendUrl: settings.backendUrl,
+          authToken: localStorage.getItem('homepilot_auth_token'),
+          conversationId: chatConversationId,
+          personaId: currentProject?.persona_agent
+            ? (currentProject.persona_agent.id as string | undefined) || null
+            : null,
+        }}
+      />
+
+      {/* Previous floating "call ended" toast has been replaced by an
+          inline CallMemoryCard rendered directly in the chat stream
+          (see the messages.map branch on m.callMemory). Keeping this
+          comment as a breadcrumb for reviewers. */}
+
+
       {/* Save as Persona Avatar modal (from AvatarStudio gallery) */}
       {saveAsPersonaData && (
         <SaveAsPersonaModal

frontend/src/ui/CallOverlay.tsx

@@ -0,0 +1,1389 @@
+/**
+ * CallOverlay.tsx — TSX port of the frontend/src/ui/phone/ design set.
+ *
+ * Maps 1:1 onto the design-only mockups in `phone/`:
+ *   tokens.jsx       → HP_CALL + hpCallStateColor/Label (inlined below)
+ *   icons.jsx        → <Icon* /> components
+ *   controls.jsx     → <ControlBtn />
+ *   avatar.jsx       → <CallAvatar />
+ *   waveform.jsx     → <CallWaveform />
+ *   call-modal.jsx   → <CallModal /> + the ModalPresentation wrapper
+ *
+ * Layered as a distinct "call mode" on top of the chat — it is NOT
+ * the same thing as Voice mode:
+ *   🎤 Voice  = input method inside the chat
+ *   📞 Call   = a separate immersive session (this component)
+ *
+ * States (mirrors the designer's set):
+ *   connecting · listening · thinking · speaking · muted
+ *   (ended is intentionally short-lived — the overlay fades out.)
+ *
+ * This pass wires the visual shell. Real STT/TTS plumbing from
+ * useVoiceController maps `listening/thinking/speaking` later.
+ */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useVoiceController, type VoiceState } from './voice/useVoiceController'
+import { useCallSession } from './call/useCallSession'
+import Waveform, { type WaveformMode } from './phone/primitives/Waveform'
+import Aura from './phone/primitives/Aura'
+import { createStreamingTts, type StreamingTts } from './call/streamTts'
+import { clog, speakOwned, isCallFullDuplexEnabled } from './call/log'
+import { useBargeInDetector } from './call/bargeIn'
+
+export type CallState =
+  | 'dialing'
+  | 'connecting'
+  | 'listening'
+  | 'thinking'
+  | 'speaking'
+  | 'muted'
+  | 'ended'
+
+// ── Staged lifecycle timings. Numbers chosen so the user *feels* the
+//    handshake instead of getting a hard screen flip: dial (ringing) →
+//    connecting → listening (live). Dial is long enough for ~one full
+//    PSTN ringback cadence (2 s on / 4 s off in the US) so the user
+//    actually hears the phone "ring" before pickup.
+const DIAL_MS = 2200     // 📞  "calling…"  — pulse-ring phase + one PSTN ring
+const CONNECT_MS = 500   // 🔵  "connecting…" — dots-pulse phase
+const END_FADE_MS = 220  // 🔴  end button → modal fade-out → onClose
+
+// ── Design tokens (ported from phone/tokens.jsx) ──────────────────
+
+const HP_CALL = {
+  font: 'Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif',
+  fontTabular: 'ui-monospace, SFMono-Regular, "Roboto Mono", Menlo, monospace',
+  backdrop: 'rgba(5, 5, 6, 0.72)',
+  surface: '#0b0b0c',
+  surface2: '#121214',
+  border: 'rgba(255, 255, 255, 0.08)',
+  text: 'rgba(255, 255, 255, 0.92)',
+  text2: 'rgba(255, 255, 255, 0.55)',
+  text3: 'rgba(255, 255, 255, 0.35)',
+  accent: '#22d3ee',
+  stateListening: '#22d3ee',
+  stateThinking: '#a78bfa',
+  stateSpeaking: '#10b981',
+  stateError: '#f87171',
+  end: '#ef4444',
+} as const
+
+function hpCallStateColor(state: CallState): string {
+  switch (state) {
+    case 'listening': return HP_CALL.stateListening
+    case 'thinking':  return HP_CALL.stateThinking
+    case 'speaking':  return HP_CALL.stateSpeaking
+    case 'dialing':
+    case 'connecting': return HP_CALL.accent
+    case 'muted':
+    case 'ended':     return HP_CALL.text3
+    default:          return HP_CALL.text2
+  }
+}
+
+// Map the voice-controller's internal machine onto our UI machine.
+// Returns null for states we don't want to reflect (OFF — overlay is
+// open so "off" is not a meaningful UI frame; render last mapped).
+function mapVoiceState(s: VoiceState): CallState | null {
+  switch (s) {
+    case 'LISTENING': return 'listening'
+    case 'THINKING':  return 'thinking'
+    case 'SPEAKING':  return 'speaking'
+    case 'IDLE':      return 'listening'
+    case 'OFF':       return null
+    default:          return null
+  }
+}
+
+// Map the overlay's richer CallState onto the primitive Waveform's
+// four-valued mode enum. The primitive doesn't know about dialing /
+// connecting / thinking — those all fold to 'idle' (low ambient
+// amplitude, faint colour); only the three audible states drive
+// distinct waveform modes.
+function waveformModeFromCallState(state: CallState): WaveformMode {
+  if (state === 'listening' || state === 'thinking') return 'listening'
+  if (state === 'speaking') return 'speaking'
+  if (state === 'muted') return 'muted'
+  return 'idle'
+}
+
+function hpCallStateLabel(state: CallState, personaName: string): string {
+  switch (state) {
+    case 'dialing':    return `calling ${personaName.toLowerCase()}…`
+    case 'connecting': return 'connecting…'
+    case 'listening':  return 'listening'
+    case 'thinking':   return 'thinking'
+    case 'speaking':   return 'speaking'
+    case 'muted':      return 'microphone off'
+    case 'ended':      return 'call ended'
+    default:           return ''
+  }
+}
+
+// ── Icons (ported from phone/icons.jsx) ───────────────────────────
+
+type IconProps = { size?: number; color?: string }
+const IconBase: React.FC<IconProps & { strokeWidth?: number; children: React.ReactNode }> = ({
+  size = 20, color = 'currentColor', strokeWidth = 1.75, children,
+}) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+    stroke={color} strokeWidth={strokeWidth}
+    strokeLinecap="round" strokeLinejoin="round">
+    {children}
+  </svg>
+)
+const IconPhoneEnd: React.FC<IconProps> = (p) => (
+  <IconBase {...p} strokeWidth={1.9}>
+    <path d="M4 14c5-5 11-5 16 0l-2 2-3-1v-2a9 9 0 0 0-6 0v2l-3 1-2-2z" transform="rotate(135 12 12)" />
+  </IconBase>
+)
+const IconMic: React.FC<IconProps> = (p) => (
+  <IconBase {...p}>
+    <rect x="9" y="3" width="6" height="12" rx="3" />
+    <path d="M5 11a7 7 0 0 0 14 0M12 18v3" />
+  </IconBase>
+)
+const IconMicOff: React.FC<IconProps> = (p) => (
+  <IconBase {...p}>
+    <path d="M9 9V6a3 3 0 0 1 6 0v5m0 4a3 3 0 0 1-6 0" />
+    <path d="M5 11a7 7 0 0 0 11.5 5.3M19 11a7 7 0 0 1-.4 2.3M12 18v3" />
+    <path d="M3 3l18 18" />
+  </IconBase>
+)
+const IconChat: React.FC<IconProps> = (p) => (
+  <IconBase {...p}>
+    <path d="M4 5h16v11H9l-5 4z" />
+  </IconBase>
+)
+const IconBack: React.FC<IconProps> = (p) => (
+  <IconBase {...p} strokeWidth={1.9}>
+    <path d="M15 5l-7 7 7 7" />
+  </IconBase>
+)
+
+// ── ControlBtn (ported from phone/controls.jsx) ───────────────────
+
+type Tone = 'neutral' | 'danger' | 'start' | 'accent'
+const ControlBtn: React.FC<{
+  size?: number
+  tone?: Tone
+  active?: boolean
+  disabled?: boolean
+  label?: string
+  ariaLabel?: string
+  onClick?: () => void
+  children: React.ReactNode
+}> = ({
+  size = 48, tone = 'neutral', active = false, disabled, label, ariaLabel, onClick, children,
+}) => {
+  const bg =
+    tone === 'danger' ? HP_CALL.end :
+    tone === 'start'  ? HP_CALL.stateSpeaking :
+    tone === 'accent' ? HP_CALL.accent :
+    active ? 'rgba(255,255,255,0.92)' : HP_CALL.surface2
+  const fg =
+    tone === 'danger' || tone === 'start' ? '#ffffff' :
+    tone === 'accent' ? '#052c33' :
+    active ? '#0b0b0c' : HP_CALL.text
+  const glow =
+    tone === 'danger' ? 'rgba(239, 68, 68, 0.45)' :
+    tone === 'start'  ? 'rgba(16, 185, 129, 0.45)' :
+    tone === 'accent' ? 'rgba(34, 211, 238, 0.4)' :
+    'rgba(0, 0, 0, 0.3)'
+  const border = tone === 'neutral' && !active ? `1px solid ${HP_CALL.border}` : 'none'
+
+  return (
+    <div style={{
+      display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 6,
+      opacity: disabled ? 0.45 : 1,
+    }}>
+      <button
+        type="button"
+        onClick={onClick}
+        disabled={disabled}
+        aria-label={ariaLabel || label || ''}
+        style={{
+          width: size, height: size, borderRadius: '50%',
+          background: bg, border, color: fg, padding: 0,
+          display: 'flex', alignItems: 'center', justifyContent: 'center',
+          cursor: disabled ? 'not-allowed' : 'pointer',
+          boxShadow:
+            tone === 'neutral' && !active
+              ? 'inset 0 1px 0 rgba(255,255,255,0.04)'
+              : `0 8px 22px ${glow}, inset 0 1px 0 rgba(255,255,255,0.12)`,
+          transition: 'transform 80ms ease, background 120ms ease, box-shadow 120ms ease',
+        }}
+      >
+        {children}
+      </button>
+      {label ? (
+        <span style={{
+          fontFamily: HP_CALL.font, fontSize: 11, fontWeight: 500, letterSpacing: 0.2,
+          color: HP_CALL.text3, textTransform: 'lowercase',
+        }}>{label}</span>
+      ) : null}
+    </div>
+  )
+}
+
+// ── CallAvatar (ported from phone/avatar.jsx) ─────────────────────
+
+const CallAvatar: React.FC<{
+  size?: number
+  state: CallState
+  imageUrl?: string | null
+  accentColor?: string | null
+}> = ({ size = 156, state, imageUrl = null, accentColor = null }) => {
+  const stateColor = hpCallStateColor(state)
+  const breathes =
+    state === 'listening' ||
+    state === 'connecting' ||
+    state === 'speaking' ||
+    state === 'dialing'
+  const showPulseRings = state === 'dialing'
+  const haloOuter = size + 28
+  // seed + hue derivation now live inside the Aura primitive
+  // (hashHue + moodOffset). This component only owns the halo +
+  // ring decorations that depend on CallState.
+
+  return (
+    <div style={{
+      position: 'relative', width: haloOuter, height: haloOuter,
+      display: 'flex', alignItems: 'center', justifyContent: 'center',
+    }}>
+      {/* Expanding pulse rings — only while dialing. Three rings on
+          staggered delays so the modal reads as "ringing", not just
+          "spinning up". */}
+      {showPulseRings && [0, 1, 2].map(i => (
+        <div key={i} aria-hidden="true" style={{
+          position: 'absolute', inset: 0, borderRadius: '50%',
+          border: `1.5px solid ${stateColor}`,
+          // Split to longhand so per-ring animationDelay doesn't race
+          // the shorthand reset — React warns when both are set
+          // (mixing shorthand + longhand produces inconsistent results
+          // across browsers).
+          animationName: 'hp-call-pulse-ring',
+          animationDuration: '1600ms',
+          animationTimingFunction: 'ease-out',
+          animationIterationCount: 'infinite',
+          animationDelay: `${i * 420}ms`,
+          opacity: 0,
+        }} />
+      ))}
+      <div style={{
+        position: 'absolute', inset: 0, borderRadius: '50%',
+        background: `radial-gradient(circle, ${stateColor}55 0%, transparent 68%)`,
+        filter: 'blur(14px)',
+        opacity: breathes ? 0.8 : 0.35,
+        animation: breathes ? 'hp-halo-breathe 2s ease-in-out infinite' : 'none',
+      }} />
+      <div style={{
+        position: 'absolute', width: size + 10, height: size + 10,
+        borderRadius: '50%',
+        border: `2px solid ${stateColor}`,
+        opacity: state === 'ended' || state === 'muted' ? 0.25 : 0.92,
+      }} />
+      <div
+        style={{
+          // ``state === 'ended'`` filter stays on this wrapper so
+          // the Aura primitive stays state-agnostic while the
+          // overlay still gets a visible "call's over" cue.
+          filter: state === 'ended'
+            ? 'grayscale(0.6) brightness(0.7)'
+            : 'none',
+          borderRadius: '50%',
+        }}
+      >
+        <Aura
+          seed={imageUrl || accentColor || 'homepilot'}
+          size={size}
+          photoUrl={imageUrl}
+          // Hue-drift polish is the only thing the Aura primitive
+          // animates internally. We disable it here — the overlay
+          // already owns the halo breath + dialing rings, and the
+          // combined motion was too busy on the call surface.
+          animated={false}
+        />
+      </div>
+    </div>
+  )
+}
+
+// CallWaveform used to live here — extracted to
+// frontend/src/ui/phone/primitives/Waveform.tsx. Consumed via the
+// imported <Waveform /> component + waveformModeFromCallState
+// mapper above.
+
+// ── CallModal (ported from phone/call-modal.jsx) ──────────────────
+
+interface CallModalProps {
+  state: CallState
+  personaName: string
+  imageUrl?: string | null
+  accentColor?: string | null
+  durationSec: number
+  onEnd: () => void
+  onToggleMute: () => void
+  onMinimize: () => void
+  onSwitchToChat?: () => void
+  /** Live 0..1 intensity. Drives the waveform bars per frame. */
+  intensityRef?: React.MutableRefObject<number>
+}
+
+const CallModal: React.FC<CallModalProps> = ({
+  state, personaName, imageUrl = null, accentColor = null,
+  durationSec, onEnd, onToggleMute, onMinimize, onSwitchToChat,
+  intensityRef,
+}) => {
+  const stateColor = hpCallStateColor(state)
+  const stateLabel = hpCallStateLabel(state, personaName)
+  const mm = Math.floor(durationSec / 60).toString().padStart(2, '0')
+  const ss = (durationSec % 60).toString().padStart(2, '0')
+  const preConnect = state === 'dialing' || state === 'connecting'
+  const timer = preConnect ? '—:—' : `${mm}:${ss}`
+
+  return (
+    <div style={{
+      width: 'min(420px, 92vw)',
+      padding: '18px 22px 26px',
+      borderRadius: 24,
+      background: HP_CALL.surface,
+      border: `1px solid ${HP_CALL.border}`,
+      boxShadow:
+        '0 30px 80px rgba(0,0,0,0.55), 0 0 0 1px rgba(0,0,0,0.4), inset 0 1px 0 rgba(255,255,255,0.04)',
+      position: 'relative', overflow: 'hidden',
+      fontFamily: HP_CALL.font, color: HP_CALL.text,
+      animation: 'hp-call-in 180ms ease-out',
+    }}>
+      <div style={{
+        position: 'absolute', inset: '-40% -10% auto -10%', height: '60%',
+        background: `radial-gradient(ellipse at 50% 100%, ${stateColor}26 0%, transparent 65%)`,
+        pointerEvents: 'none', opacity: state === 'muted' ? 0.1 : 0.35,
+      }} />
+
+      {/* Header row */}
+      <div style={{
+        position: 'relative', zIndex: 2,
+        display: 'flex', alignItems: 'center',
+        height: 32, marginBottom: 10,
+      }}>
+        <button
+          type="button"
+          onClick={onMinimize}
+          aria-label="Minimize call"
+          style={{
+            width: 32, height: 32, borderRadius: 10, padding: 0,
+            background: 'transparent', border: 'none', cursor: 'pointer',
+            color: HP_CALL.text2,
+            display: 'flex', alignItems: 'center', justifyContent: 'center',
+          }}
+        >
+          <IconBack size={18} color={HP_CALL.text2} />
+        </button>
+        <div style={{
+          position: 'absolute', left: 40, right: 40, textAlign: 'center',
+          fontSize: 16, fontWeight: 600, letterSpacing: -0.1,
+          color: HP_CALL.text,
+          whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis',
+          pointerEvents: 'none',
+        }}>{personaName}</div>
+      </div>
+
+      {/* Timer */}
+      <div style={{
+        position: 'relative', zIndex: 2, textAlign: 'center',
+        fontSize: 13, color: HP_CALL.text2,
+        fontFamily: HP_CALL.fontTabular,
+        fontVariantNumeric: 'tabular-nums',
+        marginBottom: 18,
+      }}>{timer}</div>
+
+      {/* Avatar + halo */}
+      <div style={{
+        position: 'relative', zIndex: 2,
+        display: 'flex', justifyContent: 'center', marginBottom: 18,
+      }}>
+        <CallAvatar size={156} state={state} imageUrl={imageUrl} accentColor={accentColor} />
+      </div>
+
+      {/* State label + waveform/dots */}
+      <div style={{
+        position: 'relative', zIndex: 2,
+        display: 'flex', flexDirection: 'column', alignItems: 'center',
+        gap: 10, marginBottom: 22, minHeight: 52,
+      }}>
+        {preConnect ? (
+          <div style={{ display: 'flex', gap: 5 }}>
+            {[0, 1, 2].map(i => (
+              <div key={i} style={{
+                width: 5, height: 5, borderRadius: '50%',
+                background: HP_CALL.text,
+                opacity: 0.35 + i * 0.2,
+                // Longhand — keeps per-dot animationDelay from being
+                // reset by the shorthand during React rerenders.
+                animationName: 'hp-dot-pulse',
+                animationDuration: state === 'dialing' ? '1.2s' : '0.8s',
+                animationTimingFunction: 'ease-in-out',
+                animationIterationCount: 'infinite',
+                animationDelay: `${i * 0.12}s`,
+              }} />
+            ))}
+          </div>
+        ) : (
+          <Waveform
+            bars={26}
+            height={24}
+            mode={waveformModeFromCallState(state)}
+            seed={personaName}
+            intensityRef={intensityRef}
+          />
+        )}
+        <div style={{
+          fontSize: 14, fontWeight: 500, letterSpacing: 0.3,
+          color: stateColor, textTransform: 'lowercase',
+        }}>{stateLabel}</div>
+      </div>
+
+      {/* Three-button dock */}
+      <div style={{
+        position: 'relative', zIndex: 2,
+        display: 'flex', justifyContent: 'center', alignItems: 'center',
+        gap: 28,
+      }}>
+        <ControlBtn
+          size={56}
+          active={state === 'muted'}
+          ariaLabel={state === 'muted' ? 'Unmute microphone' : 'Mute microphone'}
+          onClick={onToggleMute}
+          disabled={state === 'dialing' || state === 'connecting' || state === 'ended'}
+        >
+          {state === 'muted'
+            ? <IconMicOff size={22} color="#0b0b0c" />
+            : <IconMic size={22} />}
+        </ControlBtn>
+
+        <ControlBtn
+          size={72} tone="danger" ariaLabel="End call"
+          onClick={onEnd}
+        >
+          <IconPhoneEnd size={26} color="#ffffff" />
+        </ControlBtn>
+
+        <ControlBtn
+          size={56} ariaLabel="Switch to text chat"
+          onClick={onSwitchToChat}
+          disabled={!onSwitchToChat || state === 'dialing' || state === 'connecting' || state === 'ended'}
+        >
+          <IconChat size={22} />
+        </ControlBtn>
+      </div>
+    </div>
+  )
+}
+
+// ── Public overlay component ─────────────────────────────────────
+
+export interface CallOverlayProps {
+  open: boolean
+  onClose: () => void
+  /** Optional: the persona the user is calling (display only). */
+  personaName?: string
+  /** Optional: avatar URL for the orb. */
+  avatarUrl?: string | null
+  /** Optional: per-persona accent for the fallback aura. */
+  accentColor?: string | null
+  /** Optional: minimize handler — reserved for the future PIP. */
+  onMinimize?: () => void
+  /** Optional: "Switch to text chat" handler. */
+  onSwitchToChat?: () => void
+  /** Skip the dial-ring phase. Used by "Speak again" re-entry so the
+   *  user doesn't have to sit through "calling…" twice in a row. */
+  skipDialing?: boolean
+  /** Fired when the call ends; receives the live-phase duration in
+   *  seconds. Used by App.tsx to show the "call ended · Ns" toast. */
+  onEnded?: (durationSec: number) => void
+  /** Route a captured user utterance into the chat pipeline. When
+   *  omitted the call runs in visual-only mode (no STT hook mounts).
+   *  Only used as a fallback when the backend voice_call WS is
+   *  unavailable (VOICE_CALL_ENABLED=false). */
+  onSendText?: (text: string) => void
+  /** When true the assistant is currently producing its reply (LLM
+   *  is thinking). Maps CallState → 'thinking'. Reserved — the
+   *  voice controller surfaces this itself once TTS events land. */
+  isAssistantThinking?: boolean
+  /** Backend config for the dedicated voice_call session. When
+   *  supplied, the overlay will POST /v1/voice-call/sessions and
+   *  open the WebSocket; if the backend responds with 404/501 we
+   *  cleanly fall back to onSendText (chat REST). */
+  backend?: {
+    backendUrl: string
+    authToken: string | null
+    conversationId?: string | null
+    personaId?: string | null
+  }
+  /** Optional chat thread. When present AND the call runs in
+   *  fallback mode (VOICE_CALL_ENABLED=false or unreachable),
+   *  CallOverlay watches this array for new assistant replies
+   *  that arrive DURING the call and speaks them via TTS — so
+   *  the user hears the persona even without the voice_call WS.
+   *
+   *  We also synthesize a short opener the moment the call
+   *  connects in fallback mode, so the AI still "answers first"
+   *  the way a real callee would. The baseline is captured at
+   *  call-open so pre-existing chat history isn't re-spoken. */
+  messages?: ReadonlyArray<{
+    id: string
+    role: 'user' | 'assistant' | string
+    text: string
+    callMemory?: unknown
+  }>
+}
+
+// Outer shell — renders nothing when closed so the voice hook inside
+// CallOverlayInner only mounts during an active call. This matters: the
+// voice controller requests mic permission + starts the VAD as soon as
+// it mounts. Keeping it gated behind `open` means the mic is only
+// touched while the user is in a call.
+export default function CallOverlay(props: CallOverlayProps) {
+  if (!props.open) return null
+  return <CallOverlayInner {...props} />
+}
+
+function CallOverlayInner({
+  onClose,
+  personaName = 'Assistant',
+  avatarUrl = null,
+  accentColor = null,
+  onMinimize,
+  onSwitchToChat,
+  skipDialing = false,
+  onEnded,
+  onSendText,
+  backend,
+  messages,
+}: CallOverlayProps) {
+  const initial: CallState = skipDialing ? 'connecting' : 'dialing'
+  const [state, setState] = useState<CallState>(initial)
+  const [muted, setMuted] = useState(false)
+  const [durationSec, setDurationSec] = useState(0)
+
+  // Staged lifecycle on mount:
+  //   dialing (DIAL_MS) → connecting (CONNECT_MS) → listening
+  //   (or: connecting → listening when skipDialing).
+  useEffect(() => {
+    const timers: number[] = []
+    if (!skipDialing) {
+      timers.push(window.setTimeout(() => {
+        setState(s => (s === 'dialing' ? 'connecting' : s))
+      }, DIAL_MS))
+    }
+    timers.push(window.setTimeout(() => {
+      setState(s =>
+        (s === 'connecting' || s === 'dialing') ? 'listening' : s
+      )
+    }, (skipDialing ? 0 : DIAL_MS) + CONNECT_MS))
+
+    return () => { timers.forEach(t => window.clearTimeout(t)) }
+  }, [skipDialing])
+
+  // Live timer during active call (dialing + connecting don't count).
+  useEffect(() => {
+    if (state === 'dialing' || state === 'connecting' || state === 'ended') return
+    const iv = window.setInterval(() => setDurationSec((n) => n + 1), 1000)
+    return () => window.clearInterval(iv)
+  }, [state])
+
+  // Ringback tone — PSTN-standard two-frequency synthesis via
+  // WebAudio. US telephony uses 440 Hz + 480 Hz played together, 2 s
+  // on / 4 s off. We play one full on-phase (2 s) during dialing so
+  // the user hears a real phone-style ring before pickup. Nothing
+  // plays during connecting or live — a phone that keeps ringing
+  // after pickup is a broken phone.
+  useEffect(() => {
+    if (state !== 'dialing') return
+    const AC =
+      (window as unknown as { AudioContext?: typeof AudioContext }).AudioContext ||
+      (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext
+    if (!AC) return
+    let ctx: AudioContext | null = null
+    try { ctx = new AC() } catch { return }
+
+    const start = ctx.currentTime + 0.03
+    const durationSec = 2.0     // "on" portion of the 2-on-4-off cadence
+    const peakGain = 0.07       // loud enough to be heard, soft enough to sit
+                                // under the persona's TTS once it lands
+
+    // 440 Hz + 480 Hz fundamentals — the exact CCITT-spec recipe for
+    // "ringing signal, North American" (Precise Tone Plan).
+    const freqs = [440, 480] as const
+    const oscs: OscillatorNode[] = []
+    const gain = ctx.createGain()
+    gain.gain.setValueAtTime(0, start)
+    gain.gain.linearRampToValueAtTime(peakGain, start + 0.08)
+    gain.gain.setValueAtTime(peakGain, start + durationSec - 0.2)
+    gain.gain.linearRampToValueAtTime(0, start + durationSec)
+    gain.connect(ctx.destination)
+
+    for (const f of freqs) {
+      const o = ctx.createOscillator()
+      o.type = 'sine'
+      o.frequency.setValueAtTime(f, start)
+      o.connect(gain)
+      o.start(start)
+      o.stop(start + durationSec + 0.05)
+      oscs.push(o)
+    }
+
+    return () => {
+      for (const o of oscs) { try { o.stop() } catch { /* ignore */ } }
+      try { ctx?.close() } catch { /* ignore */ }
+    }
+  }, [state])
+
+  const handleEnd = useCallback(() => {
+    setState('ended')
+    // If the backend session is live, send a graceful call.control
+    // 'end' envelope so the server-side ledger closes cleanly.
+    if (useBackendRef.current) {
+      try { sessionRef.current.end() } catch { /* ignore */ }
+    }
+    // Capture the live-phase duration NOW — durationSec is frozen at
+    // the last tick because the interval effect tears down on
+    // state==='ended'. Close after a short fade so the backdrop +
+    // modal get a chance to animate out.
+    const endedWith = durationSec
+    window.setTimeout(() => {
+      if (onEnded) onEnded(endedWith)
+      onClose()
+    }, END_FADE_MS)
+  }, [onClose, onEnded, durationSec])
+
+  // Esc ends.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') handleEnd() }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [handleEnd])
+
+  // ── Backend voice_call session (preferred transport) ───────────
+  // When a `backend` prop is supplied we attempt the dedicated
+  // voice_call WebSocket. If the backend responds 404/501 we stay
+  // in 'unavailable' and the chat-REST fallback takes over below.
+  const session = useCallSession({
+    enabled: !!backend,
+    backendUrl: backend?.backendUrl ?? '',
+    authToken: backend?.authToken ?? null,
+    request: useMemo(() => ({
+      conversation_id: backend?.conversationId ?? null,
+      persona_id: backend?.personaId ?? null,
+      entry_mode: 'call' as const,
+      // Declare Phase 2/3 client capability. Server replies with
+      // its own capability advertisement; effective mode is the
+      // intersection (useCallSession reads capabilities from the
+      // session-create response).
+      device_info: {
+        tz: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        platform: navigator.platform,
+        streaming: true,
+        barge_in: true,
+      },
+    }), [backend?.conversationId, backend?.personaId]),
+  })
+
+  const useBackend =
+    !!backend &&
+    session.status !== 'unavailable' &&
+    session.status !== 'error'
+
+  // ── "Listen first" gate — opener-TTS is playing ───────────────
+  // When the backend emits the curated opening greeting as a
+  // transcript.final right after call.state live, the client's
+  // microphone must stay CLOSED until the greeting has finished
+  // speaking. Otherwise the user's natural "hello?" mid-greeting
+  // triggers a barge-in and cuts the persona off — the opposite
+  // of the "AI answers first, user listens" product spec.
+  //
+  // openerDoneRef is a one-shot — once the first assistant
+  // utterance has finished, subsequent utterances (responses to
+  // user turns) do NOT relock the mic; the user can barge-in on
+  // those freely, which is the correct UX.
+  const [openerPlaying, setOpenerPlaying] = useState(false)
+  // ``connected`` is a pure derivation from ``state``; declared early
+  // so effects that fire before the setHandsFree gate (fallback opener
+  // below) can reference it without a forward-ref.
+  const connected =
+    state !== 'dialing' && state !== 'connecting' && state !== 'ended'
+  const openerDoneRef = useRef(false)
+  useEffect(() => {
+    if (session.status === 'creating') {
+      openerDoneRef.current = false
+      setOpenerPlaying(false)
+    }
+  }, [session.status])
+
+  // ── Real voice pipeline ────────────────────────────────────────
+  // STT capture → preferred transport. If the backend session is
+  // live we route transcripts through the voice_call WS; otherwise
+  // we fall back to onSendText (regular chat REST) so the overlay
+  // still works when VOICE_CALL_ENABLED is off server-side.
+  const onSendTextRef = useRef(onSendText)
+  useEffect(() => { onSendTextRef.current = onSendText }, [onSendText])
+  const sessionRef = useRef(session)
+  useEffect(() => { sessionRef.current = session }, [session])
+  const useBackendRef = useRef(useBackend)
+  useEffect(() => { useBackendRef.current = useBackend }, [useBackend])
+
+  const voice = useVoiceController((text: string) => {
+    clog({
+      e: 'turn',
+      action: 'user_out',
+      route: useBackendRef.current ? 'ws' : 'chat_rest',
+    })
+    if (useBackendRef.current) {
+      sessionRef.current.sendTranscript(text)
+    } else {
+      onSendTextRef.current?.(text)
+    }
+  })
+
+  // Speak assistant replies that land over the WS. (In the chat-REST
+  // fallback path, the existing assistant-message pipeline already
+  // triggers TTS — so this effect is a no-op there.)
+  //
+  // In STREAMING mode this stays a no-op for the assistant turn
+  // (partials feed streamTts below). It still fires for any
+  // transcript.final the server emits OUTSIDE a streamed turn —
+  // e.g. the opening greeting, which the current ws.py path sends
+  // as transcript.final regardless of streaming mode.
+  // Shared TTS helper — called by both the WS path AND the
+  // fallback-mode openers/replies below. The FIRST utterance on a
+  // mounted session is treated as the opener (locks the mic gate
+  // via openerPlaying / openerDoneRef); subsequent utterances play
+  // freely so the user can barge in.
+
+  // ── Turn-lock state machine (full-duplex fix) ─────────────────
+  // The overlay owns a simple 3-state machine:
+  //   'ai'   — AI is speaking; VAD events from the mic must be
+  //            suppressed (the AI's own voice bleeding through the
+  //            laptop speaker would otherwise trigger a false user
+  //            turn — this is the "AI says yes, hears itself, then
+  //            stops" bug reported in the log).
+  //   'user' — user is actively speaking (voice.state === LISTENING)
+  //   'idle' — nobody has the floor; VAD drives transitions normally
+  //
+  // Transitions fire setListeningSuppressed on the voice controller
+  // so suppression is a single source of truth. 300 ms release
+  // margin on 'ai → idle' lets echo tail die before we trust the
+  // mic again. Gated behind isCallFullDuplexEnabled() so the old
+  // behaviour is restorable via localStorage override.
+  type TurnLock = 'ai' | 'user' | 'idle'
+  const turnLockRef = useRef<TurnLock>('idle')
+  const turnUnlockTimerRef = useRef<number | null>(null)
+  const fullDuplexEnabledRef = useRef<boolean>(isCallFullDuplexEnabled())
+
+  const setTurnLock = useCallback((next: TurnLock, trigger: string) => {
+    if (!fullDuplexEnabledRef.current) return
+    const prev = turnLockRef.current
+    if (prev === next) return
+    turnLockRef.current = next
+    voice.setListeningSuppressed(next === 'ai', `turn_lock:${trigger}`)
+    clog({ e: 'state', from: prev, to: next, trigger })
+  }, [voice])
+
+  const releaseAiTurnWithMargin = useCallback((trigger: string) => {
+    if (turnUnlockTimerRef.current) {
+      window.clearTimeout(turnUnlockTimerRef.current)
+      turnUnlockTimerRef.current = null
+    }
+    turnUnlockTimerRef.current = window.setTimeout(() => {
+      setTurnLock('idle', `${trigger}:margin_release`)
+      turnUnlockTimerRef.current = null
+    }, 300)
+  }, [setTurnLock])
+
+  useEffect(() => {
+    return () => {
+      if (turnUnlockTimerRef.current) {
+        window.clearTimeout(turnUnlockTimerRef.current)
+        turnUnlockTimerRef.current = null
+      }
+    }
+  }, [])
+
+  const speakText = useCallback((text: string) => {
+    if (!text || !text.trim()) return
+    setTurnLock('ai', 'speak:start')
+    const isOpener = !openerDoneRef.current
+    if (isOpener) setOpenerPlaying(true)
+    const markDone = () => {
+      openerDoneRef.current = true
+      setOpenerPlaying(false)
+      // 300 ms margin before we flip the lock back to 'idle'. Echo
+      // tail can linger after TTS says "ended"; releasing immediately
+      // would let the mic re-open while our own voice is still in
+      // the air.
+      releaseAiTurnWithMargin('speak:end')
+    }
+    // Length-based estimate for the SpeechService path (the shim
+    // doesn't expose onend). ~12 chars/sec; floor 1.5 s so "Yes?"
+    // still gives the user a beat; ceiling 8 s so a runaway
+    // greeting can't lock the mic indefinitely.
+    const estimateSpeechMs = (t: string) =>
+      Math.max(1500, Math.min(8000, t.length * 80))
+    try {
+      // Prefer the owned TTS path when full-duplex is on. speakOwned
+      // handles both the window.SpeechService route AND the
+      // cross-source dedupe (see call/log.ts). Returns true iff this
+      // caller owns the utterance; false means another source
+      // (App-level TTS) was mid-speak — we fall through to the legacy
+      // speechSynthesis path unchanged so the overlay isn't silent.
+      if (fullDuplexEnabledRef.current) {
+        const spoke = speakOwned('overlay', text, {
+          onEnd: markDone,
+          onError: () => markDone(),
+        })
+        if (spoke) {
+          if (isOpener) window.setTimeout(markDone, estimateSpeechMs(text))
+          return
+        }
+      } else {
+        const w = window as unknown as {
+          SpeechService?: { speak?: (t: string) => void }
+        }
+        if (w.SpeechService?.speak) {
+          w.SpeechService.speak(text)
+          if (isOpener) window.setTimeout(markDone, estimateSpeechMs(text))
+          return
+        }
+      }
+      if ('speechSynthesis' in window) {
+        const utt = new SpeechSynthesisUtterance(text)
+        if (isOpener) {
+          utt.onend = markDone
+          utt.onerror = markDone
+          window.setTimeout(markDone, estimateSpeechMs(text))
+        }
+        window.speechSynthesis.speak(utt)
+        return
+      }
+      if (isOpener) markDone()
+    } catch {
+      if (isOpener) markDone()
+    }
+  }, [setTurnLock, releaseAiTurnWithMargin])
+
+  // WS path — speak every assistant transcript.final (the opening
+  // greeting from ws.py, and in unary mode every reply). In
+  // streaming mode, per-token partials go through streamTts below
+  // and THIS path fires only for transcript.final emitted outside
+  // a streamed turn — e.g. the opener itself.
+  useEffect(() => {
+    if (!useBackend) return
+    const unsub = session.onAssistantTranscript((p) => {
+      clog({ e: 'turn', action: 'assistant_in', route: 'ws' })
+      speakText(p.text)
+    })
+    return unsub
+  }, [useBackend, session, speakText])
+
+  // ── Fallback mode (VOICE_CALL_ENABLED=false on backend) ───────
+  // When the backend voice_call route isn't mounted, the session
+  // POST 404s, useBackend stays false, and the STT pipeline routes
+  // through the regular chat-REST path (onSendText above). That
+  // works for text round-tripping — but without the hooks below,
+  // the assistant's replies land in chatMessages and are never
+  // spoken, so the user hears nothing.
+  //
+  // These two effects close that gap so the overlay is functional
+  // even with the WS disabled:
+  //   (a) a synthetic opener fires when the call connects, so the
+  //       AI still "answers first"
+  //   (b) every new assistant message arriving in ``messages``
+  //       during the call is spoken via the same TTS path the WS
+  //       reply path uses
+
+  // (a) Fallback opener — once per session, when the line connects
+  // and we're running fallback mode, pick a short greeting and
+  // speak it. The greeting is marked as opener via speakText's
+  // first-utterance heuristic, so the mic gate stays closed
+  // exactly like the WS path.
+  const fallbackOpeners = useMemo(
+    () => [
+      'Hello?',
+      'Yes?',
+      `Hi, this is ${personaName}.`,
+      `${personaName} speaking.`,
+      `Hey — ${personaName}.`,
+      `Hi, ${personaName} here.`,
+    ],
+    [personaName],
+  )
+  const fallbackOpenerFiredRef = useRef(false)
+  useEffect(() => {
+    if (useBackend) return
+    if (!connected) return
+    if (fallbackOpenerFiredRef.current) return
+    fallbackOpenerFiredRef.current = true
+    const g = fallbackOpeners[
+      Math.floor(Math.random() * fallbackOpeners.length)
+    ]
+    speakText(g)
+  }, [useBackend, connected, fallbackOpeners, speakText])
+
+  // (b) Ongoing assistant replies in fallback mode are now spoken
+  // by the App-level TTS effect (App.tsx — gated on callOpen). That
+  // pipeline already handles stripMarkdownForSpeech + per-message
+  // dedupe via lastSpokenMessageIdRef, so we don't duplicate it
+  // here. The fallback OPENER above stays — it's synthesized in
+  // the overlay and never enters chatMessages, so the App-level
+  // effect can't produce it.
+  //
+  // ``messages`` prop is still accepted for future use (mid-call
+  // transcript viewer, etc.) but intentionally unused here — no
+  // TTS side-effect reads it.
+
+  // ── Phase 2: streaming TTS pipeline ───────────────────────────
+  // Holds one streamTts instance per mounted overlay. Stopped on
+  // unmount so a re-entry creates a fresh engine.
+  const ttsRef = useRef<StreamingTts | null>(null)
+  useEffect(() => {
+    if (!useBackend || !session.streamingNegotiated) {
+      ttsRef.current = null
+      return
+    }
+    const tts = createStreamingTts()
+    ttsRef.current = tts
+    return () => {
+      try { tts.stop() } catch { /* ignore */ }
+      ttsRef.current = null
+    }
+  }, [useBackend, session.streamingNegotiated])
+
+  // Track the currently-streaming turn_id so the barge-in path can
+  // address the right turn without racing a new one.
+  const currentTurnIdRef = useRef<string | null>(null)
+
+  // Partial deltas → streamTts.appendDelta. Each delta triggers
+  // sentence-boundary flushing inside the TTS engine; callers don't
+  // see the buffering.
+  useEffect(() => {
+    if (!useBackend || !session.streamingNegotiated) return
+    return session.onAssistantPartial((p) => {
+      currentTurnIdRef.current = p.turn_id
+      ttsRef.current?.appendDelta(p.delta)
+    })
+  }, [useBackend, session])
+
+  // Turn end → flush residual buffer + clear the active turn id.
+  useEffect(() => {
+    if (!useBackend || !session.streamingNegotiated) return
+    return session.onAssistantTurnEnd((p) => {
+      if (p.reason === 'cancelled' || p.reason === 'error') {
+        ttsRef.current?.stop()
+      } else {
+        ttsRef.current?.flush()
+      }
+      if (currentTurnIdRef.current === p.turn_id) {
+        currentTurnIdRef.current = null
+      }
+    })
+  }, [useBackend, session])
+
+  // Server-initiated cancel (barge-in ack) → stop TTS immediately.
+  // Must land inside ~50 ms of receipt (§ 5.3 contract).
+  useEffect(() => {
+    if (!useBackend || !session.streamingNegotiated) return
+    return session.onAssistantCancel((_p) => {
+      ttsRef.current?.stop()
+    })
+  }, [useBackend, session])
+
+  // ── Phase 3: barge-in VAD tap ─────────────────────────────────
+  // Audio level mirror — useVoiceController returns fresh values
+  // every render; we stash the latest into a ref so the rAF loop
+  // inside useBargeInDetector always sees the current value.
+  const voiceLevelRef = useRef(0)
+  useEffect(() => {
+    voiceLevelRef.current = voice.audioLevel
+  }, [voice.audioLevel])
+
+  // Re-evaluated each render; the detector's rAF loop reads its own
+  // refs so identity changes don't thrash.
+  const bargeInEnabled =
+    useBackend &&
+    session.bargeInNegotiated &&
+    (ttsRef.current?.isSpeaking ?? false)
+
+  useBargeInDetector({
+    audioLevelRef: voiceLevelRef,
+    enabled: bargeInEnabled,
+    onBargeIn: () => {
+      const tid = currentTurnIdRef.current
+      clog({ e: 'turn', action: 'barge_in', route: 'ws' })
+      ttsRef.current?.stop()
+      if (tid) session.sendBargeIn(tid)
+    },
+  })
+
+  // Call-center-style auto-greeting — the moment the backend session
+  // goes live, prompt the persona to answer first (the way a real
+  // person picks up the phone). We send a short synthetic transcript
+  // the backend's persona_call phase machine will treat as turn 0 of
+  // the opening sequence — it responds with a contextual "hello?" /
+  // "hey, what's up?" in the persona's own voice.
+  //
+  // This is a one-shot per call session. `greetedRef` guards against
+  // reconnect storms triggering a second "hello".
+  const greetedRef = useRef(false)
+  useEffect(() => {
+    if (!useBackend) return
+    if (session.callState !== 'live') return
+    if (greetedRef.current) return
+    greetedRef.current = true
+    // One very short open-channel ping. persona_call reads this as the
+    // caller-initiated summons in the Schegloff opening structure and
+    // the persona answers.
+    session.sendTranscript('[phone-call-open]')
+  }, [useBackend, session])
+
+  // Reset the greet guard when a fresh session is (re)created.
+  useEffect(() => {
+    if (session.status === 'creating') greetedRef.current = false
+  }, [session.status])
+
+  // Backchannel + filler events are short, low-volume TTS clips.
+  // We route them through the same speak path; they're short enough
+  // (one token) that interrupting a reply mid-stream is fine.
+  useEffect(() => {
+    if (!useBackend) return
+    const unsub1 = session.onAssistantBackchannel((p) => {
+      try { window.speechSynthesis?.speak?.(new SpeechSynthesisUtterance(p.token)) }
+      catch { /* ignore */ }
+    })
+    const unsub2 = session.onAssistantFiller((p) => {
+      try { window.speechSynthesis?.speak?.(new SpeechSynthesisUtterance(p.token)) }
+      catch { /* ignore */ }
+    })
+    return () => { unsub1(); unsub2() }
+  }, [useBackend, session])
+
+  // Enter hands-free once the line is "connected" AND the opener
+  // has finished speaking. The second gate is the "listen first"
+  // rule — the AI speaks its greeting and the user hears it out
+  // before the mic opens; otherwise a natural early "hello?" trips
+  // the barge-in detector and cuts the persona off mid-greeting.
+  // ``connected`` is declared earlier (near state).
+  //
+  // This effect intentionally has NO cleanup that toggles handsFree —
+  // the original cleanup raced against `openerPlaying` transitions
+  // and re-render-driven re-runs (voice + setTurnLock change identity
+  // on every render), which flipped handsFree OFF mid-call and left
+  // state on OFF right when the user started speaking. The STT path
+  // then dropped the VAD speech_start because state !== IDLE. Tear-
+  // down lives in the dedicated unmount effect below.
+  const voiceHandleRef = useRef(voice)
+  useEffect(() => { voiceHandleRef.current = voice }, [voice])
+  const setTurnLockRef = useRef(setTurnLock)
+  useEffect(() => { setTurnLockRef.current = setTurnLock }, [setTurnLock])
+
+  useEffect(() => {
+    if (!connected) return
+    if (openerPlaying) return
+    setTurnLockRef.current('idle', 'connected_open_mic')
+    voiceHandleRef.current.setHandsFree(true)
+  }, [connected, openerPlaying])
+
+  // Unmount-only cleanup. Guarantees the mic is released and the
+  // turn-lock is reset when the overlay actually tears down (call
+  // ended, user navigated away), without coupling that teardown to
+  // the normal-effect re-run cycle above.
+  useEffect(() => {
+    return () => {
+      try { voiceHandleRef.current.setHandsFree(false) } catch { /* ignore */ }
+      try { setTurnLockRef.current('idle', 'cleanup') } catch { /* ignore */ }
+    }
+  }, [])
+
+  // Mirror the voice-controller's machine onto our UI state so the
+  // halo + waveform + label actually reflect what's happening:
+  //   LISTENING     → 'listening'
+  //   THINKING      → 'thinking'
+  //   SPEAKING      → 'speaking'
+  //   IDLE          → 'listening' (ready, nothing to say yet)
+  //   OFF / muted   → preserved
+  useEffect(() => {
+    if (!connected) return
+    if (muted) return
+    const mapped = mapVoiceState(voice.state)
+    if (!mapped) return
+    setState(prev => {
+      if (prev === 'ended' || prev === 'muted') return prev
+      return mapped
+    })
+  }, [voice.state, connected, muted])
+
+  // Mirror the voice-controller's LISTENING / THINKING onto the
+  // turn-lock 'user' slot. The AI owns 'ai' (see speakText); VAD
+  // drives 'user' only when the AI isn't already speaking. This is
+  // the industry-standard "who has the floor" gate — with it, the
+  // AI's TTS bleed through the speaker can't trip a false user turn
+  // (the root cause of the "AI says yes, hears itself, stops" bug).
+  useEffect(() => {
+    if (!fullDuplexEnabledRef.current) return
+    if (!connected) return
+    if (muted) return
+    if (voice.state === 'LISTENING' && turnLockRef.current === 'idle') {
+      clog({ e: 'vad', action: 'speech_start', state: voice.state })
+      setTurnLock('user', 'voice_listening')
+    } else if (voice.state === 'THINKING' && turnLockRef.current === 'user') {
+      clog({ e: 'vad', action: 'speech_end', state: voice.state })
+      setTurnLock('idle', 'voice_thinking')
+    }
+  }, [voice.state, connected, muted, setTurnLock])
+
+  // While the opener TTS is playing, the UI label must read
+  // 'speaking' — the persona is literally talking. Default state
+  // transitions would land on 'listening' (post-connect default)
+  // which is a lie: audio is going OUT of the speaker, not coming
+  // IN to the mic. The mic is still closed (see the openerPlaying
+  // gate on setHandsFree above), so voice.state stays OFF during
+  // this window and the mirror effect above doesn't override us.
+  useEffect(() => {
+    if (!openerPlaying) return
+    setState(prev =>
+      (prev === 'ended' || prev === 'muted') ? prev : 'speaking',
+    )
+  }, [openerPlaying])
+
+  // ── Live waveform intensity (0..1) ─────────────────────────────
+  // One rAF loop per state-group writes to a ref that CallWaveform
+  // reads directly (no React re-renders). React only sees the state
+  // label; the bars themselves are driven straight from the DOM.
+  //
+  //   listening / muted → voice.audioLevel (real mic RMS)
+  //   speaking          → synthesised speech envelope — browser TTS
+  //                       audio isn't routable through an AnalyserNode,
+  //                       so we generate a natural-sounding envelope
+  //                       (sum of 3 sines + a small noise floor). The
+  //                       visual cadence matches syllable rate + the
+  //                       amplitude range matches what mic analysers
+  //                       produce on voiced speech, so the persona's
+  //                       bars and the user's bars "look like the
+  //                       same kind of thing."
+  //   thinking          → slow 0.15..0.25 drift — "processing"
+  //   dialing/connecting/ended → 0.05 floor — visible but quiet
+  const intensityRef = useRef(0.05)
+  const voiceRef = useRef(voice)
+  useEffect(() => { voiceRef.current = voice }, [voice])
+
+  useEffect(() => {
+    let raf = 0
+    const start = performance.now()
+
+    if (state === 'listening' || state === 'muted') {
+      const tick = () => {
+        // Real mic level. useVoiceController already smooths with
+        // an EMA internally; we pass it through unmodified.
+        intensityRef.current = muted ? 0 : voiceRef.current.audioLevel
+        raf = requestAnimationFrame(tick)
+      }
+      raf = requestAnimationFrame(tick)
+      return () => cancelAnimationFrame(raf)
+    }
+
+    if (state === 'speaking') {
+      const tick = () => {
+        const t = (performance.now() - start) / 1000
+        // Three sines at the frequencies you'd see in actual
+        // voiced speech analysis: ~2 Hz syllable rate, ~5 Hz
+        // mid-band, ~10 Hz high-band flutter. A small noise floor
+        // breaks the periodicity so bars don't pulse in lockstep.
+        const v =
+          0.45 +
+          Math.sin(t * 2.3) * 0.22 +
+          Math.sin(t * 5.7 + 1.3) * 0.16 +
+          Math.sin(t * 11.1 + 2.7) * 0.09 +
+          (Math.random() - 0.5) * 0.07
+        intensityRef.current = Math.max(0, Math.min(1, v))
+        raf = requestAnimationFrame(tick)
+      }
+      raf = requestAnimationFrame(tick)
+      return () => cancelAnimationFrame(raf)
+    }
+
+    if (state === 'thinking') {
+      const tick = () => {
+        const t = (performance.now() - start) / 1000
+        intensityRef.current = 0.18 + Math.sin(t * 1.1) * 0.06
+        raf = requestAnimationFrame(tick)
+      }
+      raf = requestAnimationFrame(tick)
+      return () => cancelAnimationFrame(raf)
+    }
+
+    // dialing / connecting / ended → static low floor.
+    intensityRef.current = 0.05
+  }, [state, muted])
+
+  const toggleMute = useCallback(() => {
+    setMuted((m) => {
+      const next = !m
+      if (next) {
+        voice.setHandsFree(false)
+        setState('muted')
+      } else {
+        voice.setHandsFree(true)
+        setState('listening')
+      }
+      if (useBackendRef.current) {
+        try { sessionRef.current.sendUiState({ muted: next }) } catch { /* ignore */ }
+      }
+      return next
+    })
+  }, [voice])
+
+  const handleMinimize = useCallback(() => {
+    if (onMinimize) onMinimize()
+    else onClose()
+  }, [onMinimize, onClose])
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={`Call with ${personaName}`}
+      className="fixed inset-0 z-[100] flex items-center justify-center"
+    >
+      <div
+        className="absolute inset-0"
+        style={{
+          background: HP_CALL.backdrop,
+          backdropFilter: 'blur(20px)',
+          WebkitBackdropFilter: 'blur(20px)',
+          transition: 'opacity 200ms ease',
+          opacity: state === 'ended' ? 0 : 1,
+        }}
+      />
+      <div className="relative z-10">
+        <CallModal
+          state={state}
+          personaName={personaName}
+          imageUrl={avatarUrl}
+          accentColor={accentColor}
+          durationSec={durationSec}
+          onEnd={handleEnd}
+          onToggleMute={toggleMute}
+          onMinimize={handleMinimize}
+          onSwitchToChat={onSwitchToChat}
+          intensityRef={intensityRef}
+        />
+      </div>
+
+      <style>{`
+        @keyframes hp-call-in {
+          from { opacity: 0; transform: scale(0.95); }
+          to   { opacity: 1; transform: scale(1); }
+        }
+        @keyframes hp-halo-breathe {
+          0%, 100% { opacity: 0.30; transform: scale(1); }
+          50%      { opacity: 0.85; transform: scale(1.06); }
+        }
+        @keyframes hp-dot-pulse {
+          0%, 100% { transform: translateY(0);   opacity: 0.35; }
+          50%      { transform: translateY(-3px); opacity: 1; }
+        }
+        @keyframes hp-call-pulse-ring {
+          0%   { transform: scale(1);    opacity: 0.65; }
+          80%  { opacity: 0; }
+          100% { transform: scale(1.55); opacity: 0; }
+        }
+        @keyframes hp-call-toast-in {
+          from { opacity: 0; transform: translateY(8px); }
+          to   { opacity: 1; transform: translateY(0); }
+        }
+      `}</style>
+    </div>
+  )
+}
+
+
+// ── Call-ended toast — the "you just hung up, want to call back?" chip
+
+export interface CallEndedToastProps {
+  /** Duration of the live phase (seconds). Rendered as "42s" / "3m 12s". */
+  durationSec: number
+  onSpeakAgain: () => void
+  onDismiss: () => void
+}
+
+function formatEndedDuration(s: number): string {
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  const rest = s % 60
+  return rest === 0 ? `${m}m` : `${m}m ${rest}s`
+}
+
+export const CallEndedToast: React.FC<CallEndedToastProps> = ({
+  durationSec, onSpeakAgain, onDismiss,
+}) => {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="fixed bottom-6 left-1/2 z-[95] -translate-x-1/2"
+      style={{
+        animation: 'hp-call-toast-in 220ms ease-out',
+        fontFamily: HP_CALL.font,
+      }}
+    >
+      <div style={{
+        display: 'flex', alignItems: 'center', gap: 12,
+        padding: '8px 10px 8px 14px',
+        borderRadius: 9999,
+        background: HP_CALL.surface,
+        border: `1px solid ${HP_CALL.border}`,
+        boxShadow: '0 12px 32px rgba(0,0,0,0.45), inset 0 1px 0 rgba(255,255,255,0.04)',
+        color: HP_CALL.text,
+      }}>
+        <span style={{
+          display: 'inline-flex', alignItems: 'center', gap: 8,
+          fontSize: 13, fontWeight: 500, color: HP_CALL.text2,
+        }}>
+          <span style={{
+            width: 6, height: 6, borderRadius: '50%',
+            background: HP_CALL.text3,
+          }} />
+          Call ended · <span style={{
+            color: HP_CALL.text,
+            fontFamily: HP_CALL.fontTabular,
+            fontVariantNumeric: 'tabular-nums',
+          }}>{formatEndedDuration(durationSec)}</span>
+        </span>
+        <button
+          type="button"
+          onClick={onSpeakAgain}
+          style={{
+            height: 30, padding: '0 14px', borderRadius: 9999,
+            background: HP_CALL.accent,
+            color: '#052c33', border: 'none', cursor: 'pointer',
+            fontSize: 12, fontWeight: 600, letterSpacing: 0.2,
+          }}
+        >
+          Speak again
+        </button>
+        <button
+          type="button"
+          onClick={onDismiss}
+          aria-label="Dismiss"
+          style={{
+            width: 28, height: 28, borderRadius: 9999,
+            background: 'transparent', border: 'none', cursor: 'pointer',
+            color: HP_CALL.text3, fontSize: 18, lineHeight: 1, padding: 0,
+          }}
+        >
+          ×
+        </button>
+      </div>
+    </div>
+  )
+}

frontend/src/ui/CreatorStudioEditor.tsx

@@ -1847,6 +1847,12 @@ export function CreatorStudioEditor({
           backendUrl={backendUrl}
           videoId={projectId}
           videoTitle={project?.title}
+          scenes={scenes.map((s) => ({
+            id: s.id,
+            idx: s.idx,
+            narration: s.narration || "",
+            audioUrl: s.audioUrl || null,
+          }))}
           disabledReason={
             scenes.length === 0
               ? "Add at least one scene before exporting."

frontend/src/ui/SettingsPanel.tsx

@@ -1,6 +1,15 @@
 import React, { useEffect, useMemo, useState } from "react";
 import OllamaHealthBanner from "./OllamaHealthBanner";
 import ProfileSettingsModal from "./ProfileSettingsModal";
+import TtsEngineSection from "./components/TtsEngineSection";
+// Side-effect import: registers the bundled TTS providers (web-speech-api,
+// piper-wasm). Importing here guarantees the registry is populated the
+// first time the Settings panel mounts, before TtsEngineSection reads it.
+import "./tts";
+import {
+  getActiveTtsEngineId,
+  onActiveTtsEngineChange,
+} from "./tts";
 import { resolveBackendUrl } from "./lib/backendUrl";
 import {
   getModelSettings,
@@ -208,6 +217,12 @@ export default function SettingsPanel({
 
   // Voice state
   const [availableVoices, setAvailableVoices] = useState<SpeechSynthesisVoice[]>([]);
+  // Track the active TTS engine so we can hide the legacy "Assistant
+  // Voice" select when the user picks a non-default engine (Piper etc.).
+  // Purely cosmetic: the underlying value.selectedVoice state is not
+  // touched — only the control rendering it.
+  const [ttsEngineId, setTtsEngineId] = useState<string>(() => getActiveTtsEngineId());
+  useEffect(() => onActiveTtsEngineChange(setTtsEngineId), []);
   const [voicesInitialized, setVoicesInitialized] = useState(false);
 
   // Video presets state (fetched from backend based on selected model)
@@ -1084,27 +1099,40 @@ export default function SettingsPanel({
               <span className="text-xs text-white">Enable Text-to-Speech (TTS)</span>
             </label>
 
-            {/* Voice Selection */}
-            <div>
-              <label className="block text-[10px] text-white/50 mb-2">Assistant Voice</label>
-              <select
-                className="w-full bg-black border border-white/10 rounded-lg px-3 py-2 text-xs text-white"
-                value={value.selectedVoice ?? ''}
-                onChange={(e) => onChangeDraft({ ...value, selectedVoice: e.target.value })}
-              >
-                <option value="">System Default</option>
-                {availableVoices.map((voice) => (
-                  <option key={voice.voiceURI} value={voice.name}>
-                    {voice.name} ({voice.lang})
-                  </option>
-                ))}
-              </select>
-              <div className="mt-1 text-[10px] text-white/40">
-                {availableVoices.length > 0
-                  ? `Choose from ${availableVoices.length} available voices`
-                  : 'Loading voices...'}
+            {/* Voice Selection — only shown for the default engine. When
+                the user picks a non-default engine (Piper etc.) the engine
+                owns its own voice picker below, and showing two would be
+                confusing duplication. */}
+            {ttsEngineId === 'web-speech-api' && (
+              <div>
+                <label className="block text-[10px] text-white/50 mb-2">Assistant Voice</label>
+                <select
+                  className="w-full bg-black border border-white/10 rounded-lg px-3 py-2 text-xs text-white"
+                  value={value.selectedVoice ?? ''}
+                  onChange={(e) => onChangeDraft({ ...value, selectedVoice: e.target.value })}
+                >
+                  <option value="">System Default</option>
+                  {availableVoices.map((voice) => (
+                    <option key={voice.voiceURI} value={voice.name}>
+                      {voice.name} ({voice.lang})
+                    </option>
+                  ))}
+                </select>
+                <div className="mt-1 text-[10px] text-white/40">
+                  {availableVoices.length > 0
+                    ? `Choose from ${availableVoices.length} available voices`
+                    : 'Loading voices...'}
+                </div>
               </div>
-            </div>
+            )}
+
+            {/* TTS Engine picker — additive plugin system. The existing
+                System Voice selector above stays as the default path; this
+                section lets the user opt into alternative engines (Piper
+                WASM today; more can register themselves without touching
+                this file). Schema-driven controls so future engines
+                require zero Settings edits. */}
+            <TtsEngineSection systemVoices={availableVoices} />
           </div>
         </div>
 

frontend/src/ui/call/bargeIn.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Unit tests for the pure detector in bargeIn.ts. Covers the exact
+ * § 6 invariants (single-spike rejection, sustain gate, refractory).
+ * The hook form is intentionally not tested here — it's a thin
+ * wrapper around the detector + rAF; coverage lives in the overlay
+ * integration path.
+ */
+import { describe, it, expect } from 'vitest'
+import { detectBargeIn } from './bargeIn'
+
+const OPTS = {
+  threshold: 0.08,
+  minSustainMs: 80,
+  minRefractoryMs: 400,
+} as const
+
+function genConstant(level: number, durMs: number, stepMs = 16) {
+  const out: Array<{ tMs: number; level: number }> = []
+  for (let t = 0; t <= durMs; t += stepMs) {
+    out.push({ tMs: t, level })
+  }
+  return out
+}
+
+describe('detectBargeIn', () => {
+  it('fires once after sustained speech above threshold', () => {
+    // Steady high level for 200 ms — comfortably over the 80 ms sustain.
+    const events = detectBargeIn(genConstant(0.2, 200), OPTS)
+    expect(events.length).toBe(1)
+    expect(events[0]).toBeGreaterThanOrEqual(OPTS.minSustainMs)
+  })
+
+  it('does NOT fire on a single spike below sustain', () => {
+    // One 16 ms spike followed by silence. Below 80 ms sustain → drops.
+    const samples = [
+      { tMs: 0, level: 0.0 },
+      { tMs: 16, level: 0.2 },
+      { tMs: 32, level: 0.0 },
+      { tMs: 48, level: 0.0 },
+      { tMs: 64, level: 0.0 },
+    ]
+    expect(detectBargeIn(samples, OPTS)).toEqual([])
+  })
+
+  it('does NOT fire when level never exceeds threshold', () => {
+    const events = detectBargeIn(genConstant(0.04, 400), OPTS)
+    expect(events).toEqual([])
+  })
+
+  it('honours the refractory window (no double-fire during sustained speech)', () => {
+    // 1500 ms of steady speech. Without refractory we'd fire every
+    // tick after 80 ms. With refractory we fire at most once per
+    // minRefractoryMs (~400 ms).
+    const events = detectBargeIn(genConstant(0.2, 1500), OPTS)
+    expect(events.length).toBeGreaterThan(0)
+    // At 16 ms steps and 400 ms refractory: expect ~3 events.
+    expect(events.length).toBeLessThanOrEqual(4)
+    // Consecutive events must be at least refractory-ms apart.
+    for (let i = 1; i < events.length; i++) {
+      expect(events[i] - events[i - 1]).toBeGreaterThanOrEqual(
+        OPTS.minRefractoryMs,
+      )
+    }
+  })
+
+  it('resets the sustain counter after a dip below threshold', () => {
+    // 50 ms above, 30 ms below, 100 ms above. First run is too short;
+    // second run also too short on its own because counter reset.
+    const samples = [
+      ...Array.from({ length: 4 }, (_, i) => ({
+        tMs: i * 16, level: 0.2,
+      })),
+      { tMs: 64, level: 0.0 },
+      { tMs: 80, level: 0.0 },
+      ...Array.from({ length: 4 }, (_, i) => ({
+        tMs: 96 + i * 16, level: 0.2,
+      })),
+    ]
+    expect(detectBargeIn(samples, OPTS)).toEqual([])
+  })
+})

frontend/src/ui/call/bargeIn.ts

@@ -0,0 +1,132 @@
+/**
+ * bargeIn.ts — VAD-tap hook that detects user speech-start while
+ * the assistant's TTS is playing, so the client can interrupt the
+ * persona the way a person would.
+ *
+ * Design (§ 5.4 of docs/analysis/voice-call-streaming-design.md):
+ *
+ *   - Reads the EMA-smoothed mic level that useVoiceController
+ *     already exposes (audioLevelRef), sampled at rAF cadence.
+ *   - Fires onBargeIn when the level stays above ``threshold`` for
+ *     at least ``minSustainMs``. Sustain protects against a
+ *     single spike (keyboard click, cough) cutting the persona off.
+ *   - Only enabled when the overlay says it should be — i.e. the
+ *     TTS is actually speaking AND the session negotiated streaming.
+ *     Outside that window it's a pure no-op.
+ *
+ * The threshold here (default 0.08) is deliberately HIGHER than the
+ * baseline VAD threshold (~0.035) that useVoiceController uses for
+ * end-of-user-turn silence detection. Reason: during TTS playback a
+ * fraction of the persona's own audio returns into the mic on most
+ * laptops; a low threshold trips on that bleed and generates
+ * phantom barge-ins. 0.08 is above typical TTS bleed but well below
+ * normal voiced-speech peaks.
+ */
+
+import { useEffect, useRef } from 'react'
+
+export interface UseBargeInDetectorArgs {
+  /** Shared ref mutated at rAF cadence by the parent — typically
+   *  ``voice.audioLevel`` mirrored into a ref so we avoid stale
+   *  reads without thrashing React.  0..1 range. */
+  audioLevelRef: React.MutableRefObject<number>
+  /** Only fire barge-ins when this is true. Wire this to
+   *  ``tts.isSpeaking && session.streamingNegotiated``. */
+  enabled: boolean
+  /** Callback fired once per speech-start episode. Debounced via
+   *  ``minRefractoryMs`` to avoid double-firing on sustained speech. */
+  onBargeIn: () => void
+  /** Audio level (0..1) above which the tap considers the user to
+   *  be speaking. Default 0.08 — see header comment on TTS bleed. */
+  threshold?: number
+  /** How long the level must stay above ``threshold`` before we
+   *  declare speech-start. 80 ms matches the minimum voiced-phoneme
+   *  duration, so a single keyboard clack doesn't trigger. */
+  minSustainMs?: number
+  /** After firing, ignore further triggers for this long. Prevents
+   *  a single barge-in from firing twice while speech continues. */
+  minRefractoryMs?: number
+}
+
+/**
+ * Mount a VAD tap that fires ``onBargeIn`` when sustained speech is
+ * detected during an active TTS phase. Cleanup on unmount.
+ */
+export function useBargeInDetector({
+  audioLevelRef,
+  enabled,
+  onBargeIn,
+  threshold = 0.08,
+  minSustainMs = 80,
+  minRefractoryMs = 400,
+}: UseBargeInDetectorArgs): void {
+  // Latest callback in a ref so a change in ``onBargeIn`` identity
+  // doesn't tear down the whole rAF loop.
+  const onBargeInRef = useRef(onBargeIn)
+  useEffect(() => {
+    onBargeInRef.current = onBargeIn
+  }, [onBargeIn])
+
+  useEffect(() => {
+    if (!enabled) return
+    let raf = 0
+    let aboveSince: number | null = null
+    let refractoryUntil = 0
+    const tick = () => {
+      const now = performance.now()
+      const level = audioLevelRef.current ?? 0
+      if (level >= threshold) {
+        if (aboveSince === null) aboveSince = now
+        else if (
+          now >= refractoryUntil &&
+          now - aboveSince >= minSustainMs
+        ) {
+          refractoryUntil = now + minRefractoryMs
+          aboveSince = null
+          try {
+            onBargeInRef.current()
+          } catch {
+            /* listener errors must not crash the rAF loop */
+          }
+        }
+      } else {
+        aboveSince = null
+      }
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => {
+      cancelAnimationFrame(raf)
+    }
+  }, [enabled, audioLevelRef, threshold, minSustainMs, minRefractoryMs])
+}
+
+// Exported for tests — pure detector without the React hook.
+export function detectBargeIn(
+  samples: Array<{ tMs: number; level: number }>,
+  opts: {
+    threshold: number
+    minSustainMs: number
+    minRefractoryMs: number
+  },
+): number[] {
+  const events: number[] = []
+  let aboveSince: number | null = null
+  let refractoryUntil = 0
+  for (const { tMs, level } of samples) {
+    if (level >= opts.threshold) {
+      if (aboveSince === null) aboveSince = tMs
+      else if (
+        tMs >= refractoryUntil &&
+        tMs - aboveSince >= opts.minSustainMs
+      ) {
+        refractoryUntil = tMs + opts.minRefractoryMs
+        aboveSince = null
+        events.push(tMs)
+      }
+    } else {
+      aboveSince = null
+    }
+  }
+  return events
+}

frontend/src/ui/call/callApi.ts

@@ -0,0 +1,190 @@
+/**
+ * callApi.ts — REST wrapper for the voice_call session endpoint.
+ *
+ * Thin on purpose. Two responsibilities:
+ *   1. POST /v1/voice-call/sessions with the right shape
+ *   2. Normalize "feature unavailable" (404/501) vs hard errors
+ *      so the hook can gracefully fall back to the chat-REST path
+ *      when the backend has VOICE_CALL_ENABLED=false.
+ *
+ * Anything richer (envelope codec, seq bookkeeping, heartbeat,
+ * reconnect) lives in callSocket.ts — keeping those concerns out of
+ * this file is deliberate; the REST handshake runs once per call,
+ * the socket lifecycle runs for every envelope.
+ */
+
+import { resolveBackendUrl } from '../lib/backendUrl'
+
+export interface CreateCallSessionRequest {
+  /** Existing chat conversation id to link this call to. Optional.
+   *  The backend will create an ephemeral conversation if omitted. */
+  conversation_id?: string | null
+  /** Persona to carry into the turn. Null = assistant default. */
+  persona_id?: string | null
+  /** How the call was initiated. Matches backend CreateSessionReq. */
+  entry_mode?: 'voice' | 'call' | 'handoff'
+  /** Free-form client fingerprint (tz, platform, ua family).
+   *  Also carries Phase 2/3 capability declarations:
+   *    - ``streaming``  client can consume assistant.partial
+   *    - ``barge_in``   client can detect user speech-start during
+   *                     TTS playback and send ``user.barge_in``
+   *  The effective streaming mode for the session is
+   *  ``min(client_declared, server_advertised)`` — both ends must
+   *  agree or the turn runs in unary mode. Mismatches degrade
+   *  gracefully without a hard error. */
+  device_info?: Record<string, unknown>
+}
+
+/** Server-advertised capabilities. Fields are optional so older
+ *  servers (which don't emit them) are parsed safely and treated
+ *  as "no". Used by useCallSession to decide whether to subscribe
+ *  to the Phase 2 streaming events. */
+export interface CallCapabilities {
+  /** Server supports assistant.partial / assistant.turn_end /
+   *  assistant.cancel envelopes. */
+  streaming?: boolean
+  /** Server honours user.barge_in / transcript.partial as cancel
+   *  signals. Only meaningful when ``streaming`` is also true. */
+  barge_in?: boolean
+  /** Legacy fields (pre-streaming). Kept in the interface so
+   *  existing consumers don't need to widen the type. */
+  interruptions?: boolean
+  transcript_live?: boolean
+  [k: string]: unknown
+}
+
+export interface CreateCallSessionResponse {
+  session_id: string
+  /** Absolute or root-relative WebSocket URL to connect to. */
+  ws_url: string
+  /** Short-lived token the WS handshake must echo in its query. */
+  resume_token: string
+  /** When the session expires if never connected (ISO or epoch ms). */
+  expires_at: string | number
+  /** Hard cap enforced by the server. */
+  max_duration_sec: number
+  /** Backend capability advertisement (§ 3.1 of the streaming design). */
+  capabilities?: CallCapabilities
+}
+
+/** Error raised for any non-2xx from /v1/voice-call/sessions. The
+ *  `isUnavailable` flag distinguishes "backend hasn't enabled this
+ *  feature yet" from real failures the UI should surface. */
+export class CallApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly bodyText: string,
+  ) {
+    super(`voice-call session api ${status}${bodyText ? `: ${bodyText}` : ''}`)
+    this.name = 'CallApiError'
+  }
+  /** 404 = route not mounted (VOICE_CALL_ENABLED=false).
+   *  501 = feature recognized but disabled at runtime.
+   *  The hook treats both as "fall back to chat REST". */
+  get isUnavailable(): boolean {
+    return this.status === 404 || this.status === 501
+  }
+}
+
+export async function createCallSession(
+  backendUrl: string,
+  req: CreateCallSessionRequest,
+  authToken?: string | null,
+): Promise<CreateCallSessionResponse> {
+  // Defensive resolution: when the caller passes an empty or
+  // whitespace-only backend URL (e.g. a stale settings load), a
+  // naive ``replace(/\/+$/, '')`` leaves us with ``''`` and fetch
+  // falls back to the current page origin. On the Vite dev server
+  // (:3000) that silently routes to the SPA, which returns
+  // index.html and the subsequent JSON parse fails; in prod it can
+  // hit the wrong origin entirely. ``resolveBackendUrl`` ignores
+  // empty overrides and falls through to the app-wide resolver
+  // (localStorage → VITE_API_URL → origin → ``http://localhost:8000``),
+  // so we never accidentally issue a relative request.
+  const base = resolveBackendUrl(backendUrl)
+  const res = await fetch(`${base}/v1/voice-call/sessions`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(authToken ? { authorization: `Bearer ${authToken}` } : {}),
+    },
+    body: JSON.stringify({
+      conversation_id: req.conversation_id ?? null,
+      persona_id: req.persona_id ?? null,
+      entry_mode: req.entry_mode ?? 'call',
+      device_info: req.device_info ?? {},
+    }),
+    credentials: 'include',
+  })
+
+  if (!res.ok) {
+    const bodyText = await res.text().catch(() => '')
+    throw new CallApiError(res.status, bodyText)
+  }
+
+  const json = (await res.json()) as CreateCallSessionResponse
+  if (!json?.session_id || !json?.resume_token || !json?.ws_url) {
+    throw new CallApiError(res.status, 'malformed session payload')
+  }
+  return json
+}
+
+/** Declare the client's Phase 2/3 capabilities into the
+ *  ``device_info`` blob. Set both to true in build configurations
+ *  that include streamTts + bargeIn modules; set to false to run
+ *  the session in forced-unary mode even against a streaming server
+ *  (useful for bisecting regressions). */
+export function clientStreamingCapabilities(
+  base: Record<string, unknown>,
+  enabled: boolean,
+): Record<string, unknown> {
+  if (!enabled) return base
+  return { ...base, streaming: true, barge_in: true }
+}
+
+/** Compute the effective streaming mode from the server's capability
+ *  response and the client's declared support. Truth table in § 3.1
+ *  of docs/analysis/voice-call-streaming-design.md. */
+export function effectiveStreamingMode(
+  serverCaps: CallCapabilities | undefined,
+  clientStreaming: boolean,
+): { streaming: boolean; barge_in: boolean } {
+  const streaming = !!(serverCaps?.streaming && clientStreaming)
+  const barge_in = streaming && !!serverCaps?.barge_in
+  return { streaming, barge_in }
+}
+
+/** Resolve a potentially-relative ws_url against the current page
+ *  and the backend URL. Backends sometimes return `/v1/voice-call/ws`
+ *  (path only) so the client can pick the right scheme + host. */
+export function resolveWsUrl(
+  wsUrl: string,
+  sessionId: string,
+  resumeToken: string,
+  authToken: string | null,
+  backendUrl: string,
+): string {
+  let url: URL
+  if (/^wss?:\/\//i.test(wsUrl)) {
+    url = new URL(wsUrl)
+  } else if (wsUrl.startsWith('//')) {
+    url = new URL(`${location.protocol === 'https:' ? 'wss:' : 'ws:'}${wsUrl}`)
+  } else if (wsUrl.startsWith('/')) {
+    // Root-relative — derive scheme + host from backendUrl.
+    const backend = new URL(backendUrl)
+    const scheme = backend.protocol === 'https:' ? 'wss:' : 'ws:'
+    url = new URL(`${scheme}//${backend.host}${wsUrl}`)
+  } else {
+    url = new URL(wsUrl, backendUrl)
+  }
+
+  // Inject session_id if the server gave us a template (rare) or
+  // appended nothing; the standard shape is
+  // /v1/voice-call/ws/{session_id}.
+  if (!url.pathname.endsWith(sessionId)) {
+    url.pathname = url.pathname.replace(/\/+$/, '') + `/${sessionId}`
+  }
+  url.searchParams.set('resume_token', resumeToken)
+  if (authToken) url.searchParams.set('token', authToken)
+  return url.toString()
+}

frontend/src/ui/call/callSocket.ts

@@ -0,0 +1,579 @@
+/**
+ * callSocket.ts — typed transport for the voice_call WebSocket.
+ *
+ * Owns the connection, the envelope codec, monotonic sequence
+ * tracking, the heartbeat, graceful shutdown, and reconnect-with-
+ * backoff semantics. Exposes a narrow event surface that the React
+ * hook (useCallSession) binds to; callers never touch the raw socket.
+ *
+ * Explicit state machine — the only transitions allowed are:
+ *
+ *     idle ──connect()──▶ connecting ──open───────▶ live
+ *                             │                        │
+ *                             │ (handshake failure)    │ (transient drop w/ resume window)
+ *                             ▼                        ▼
+ *                          closed                  reconnecting ──(give up / expired)──▶ closed
+ *                                                      │
+ *                                                      └─────(socket open)───────▶ live
+ *
+ *     live ──close('user_ended' | 'max_duration' | 'idle')───▶ closed
+ *
+ * Industry choices baked in:
+ *   • Exponential backoff with full jitter (AWS / Cloudflare canonical
+ *     implementation) — stops thundering herds on a shared-backend
+ *     brown-out.
+ *   • Heartbeat treats silence as liveness failure — we send a
+ *     client-originated `call.control ping` every N seconds AND
+ *     watch for server-side `ping` events; if BOTH are silent for
+ *     2× the interval, the connection is considered dead and the
+ *     backoff loop fires.
+ *   • Outbound envelopes are queued while reconnecting. When the
+ *     socket reopens within the resume window the queue is flushed
+ *     in-order; otherwise it's dropped on shutdown.
+ *   • Resume semantics honoured: one reconnect attempt carries the
+ *     same session_id + resume_token; if the server returns
+ *     1008 resume-expired we give up and surface 'resume_expired'.
+ *   • Every event emitted by this module is typed; no `any`, no
+ *     ad-hoc payload parsing inside listeners.
+ */
+
+// ── Typed envelope contracts ───────────────────────────────────────
+// Mirror the backend ws.py contract. Keep in sync with
+// docs/analysis/voice-call-human-simulation-design.md § 6.
+
+export type CallLifecycleStatus =
+  | 'idle'
+  | 'connecting'
+  | 'live'
+  | 'reconnecting'
+  | 'draining'
+  | 'closed'
+
+export type CallCloseReason =
+  | 'user_ended'
+  | 'max_duration'
+  | 'idle_timeout'
+  | 'resume_expired'
+  | 'bad_resume_token'
+  | 'session_not_found'
+  | 'session_ended'
+  | 'websocket_disabled'
+  | 'network_error'
+  | 'unmounted'
+  | 'unknown'
+
+export interface ServerEnvelope<
+  T extends string = string,
+  P extends Record<string, unknown> = Record<string, unknown>,
+> {
+  type: T
+  seq: number
+  ts: number
+  payload: P
+}
+
+// Server → client event payloads. One type per server `type`; if
+// the backend ever adds a new event, it lands in `unknown` and is
+// dropped — not a runtime crash.
+
+export interface CallStatePayload {
+  status: 'live' | 'ending' | 'ended'
+  reason?: 'user_ended' | 'idle' | 'max_duration'
+  since?: number
+}
+export interface AssistantTranscriptPayload {
+  role: 'assistant'
+  text: string
+}
+export interface AssistantFillerPayload {
+  token: string
+  ts?: number
+  session_id?: string
+}
+export interface AssistantBackchannelPayload {
+  token: string
+  volume_db?: number
+  ts?: number
+}
+export interface ServerErrorPayload {
+  code: string
+  message: string
+}
+
+// Phase 2/3 payloads (§ 3.2 of the streaming design doc).
+
+export interface AssistantPartialPayload {
+  turn_id: string
+  /** The NEW text only. Callers concatenate deltas per turn_id. */
+  delta: string
+  /** Monotonic per-turn index starting at 0. Advisory (the WS
+   *  already enforces monotonic seq); useful for replay logs. */
+  index: number
+}
+export interface AssistantTurnEndPayload {
+  turn_id: string
+  reason: 'complete' | 'cancelled' | 'error'
+  /** Authoritative concatenation of this turn's deltas (server-side).
+   *  Clients can use this directly instead of maintaining their own
+   *  buffer. Optional in principle — but our server always emits it. */
+  full_text?: string
+}
+export interface AssistantCancelPayload {
+  turn_id: string
+  cause?: 'user_barge_in' | 'user_partial' | string
+}
+
+// Client → server. Keep the types literal so the compiler catches
+// typos at the send() call site.
+
+export interface UiStatePayload {
+  muted?: boolean
+  speaker_on?: boolean
+  backgrounded?: boolean
+}
+export interface TranscriptFinalPayload {
+  text: string
+  model?: string
+  lang?: string
+}
+export type CallControlAction = 'end' | 'ping'
+
+// ── Typed event bus for callers ────────────────────────────────────
+
+export interface CallSocketEventMap {
+  statusChange: CallLifecycleStatus
+  callState: CallStatePayload
+  /** Still fires for turns that ran in unary mode (flag off OR
+   *  capability mismatch). Streaming turns use the three events
+   *  below instead. */
+  assistantTranscript: AssistantTranscriptPayload
+  /** Phase 2: one delta per server emission. */
+  assistantPartial: AssistantPartialPayload
+  /** Phase 2: exactly once per streamed turn, with a final reason. */
+  assistantTurnEnd: AssistantTurnEndPayload
+  /** Phase 3: server acks a barge-in; client stops TTS on receipt. */
+  assistantCancel: AssistantCancelPayload
+  assistantFiller: AssistantFillerPayload
+  assistantBackchannel: AssistantBackchannelPayload
+  serverError: ServerErrorPayload
+  safetyNotice: Record<string, unknown>
+  pong: void
+  closed: { reason: CallCloseReason; code?: number; detail?: string }
+}
+
+type Listener<E extends keyof CallSocketEventMap> = (
+  payload: CallSocketEventMap[E],
+) => void
+
+// ── Backoff helper (AWS-style full jitter) ─────────────────────────
+
+function backoffMs(attempt: number, baseMs = 500, capMs = 10_000): number {
+  const exp = Math.min(capMs, baseMs * 2 ** attempt)
+  return Math.floor(Math.random() * exp)
+}
+
+// ── Close-code → reason mapping ────────────────────────────────────
+
+const POLICY_VIOLATION = 1008
+const NORMAL_CLOSURE = 1000
+
+function closeReasonFrom(code: number | undefined, text: string): CallCloseReason {
+  const reason = (text || '').toLowerCase()
+  if (code === POLICY_VIOLATION) {
+    if (reason.includes('resume-expired')) return 'resume_expired'
+    if (reason.includes('bad-resume-token')) return 'bad_resume_token'
+    if (reason.includes('session-not-found')) return 'session_not_found'
+    if (reason.includes('session-ended')) return 'session_ended'
+    if (reason.includes('websocket-disabled')) return 'websocket_disabled'
+  }
+  if (code === NORMAL_CLOSURE && reason.includes('max-duration')) return 'max_duration'
+  if (reason.includes('idle')) return 'idle_timeout'
+  return 'unknown'
+}
+
+// ── Construction options ───────────────────────────────────────────
+
+export interface CallSocketOptions {
+  /** Fully-resolved WS URL including ?resume_token=… and ?token=…. */
+  url: string
+  /** How long the backend will honour a resume. Used to decide when to
+   *  give up reconnecting. Default 20 s (matches VOICE_CALL_RESUME_WINDOW_SEC). */
+  resumeWindowSec?: number
+  /** How often we send a client-originated ping. Default 15 s. */
+  heartbeatIntervalMs?: number
+  /** Dependency injection for tests — defaults to global WebSocket. */
+  webSocketImpl?: typeof WebSocket
+  /** Structured log sink. Defaults to console.{info,warn,error} with
+   *  any `resume_token`, `token`, or `jwt` fields redacted by the
+   *  caller. Keep string-typed; don't pass raw envelopes in. */
+  log?: {
+    info: (msg: string, extra?: Record<string, unknown>) => void
+    warn: (msg: string, extra?: Record<string, unknown>) => void
+    error: (msg: string, extra?: Record<string, unknown>) => void
+  }
+}
+
+// ── CallSocket class ───────────────────────────────────────────────
+
+export class CallSocket {
+  private ws: WebSocket | null = null
+  private status: CallLifecycleStatus = 'idle'
+  private lastServerSeq = 0
+  private outboundQueue: string[] = []
+  private heartbeatTimer: number | null = null
+  private lastServerActivityMs = 0
+  private deadPeerTimer: number | null = null
+  private reconnectAttempt = 0
+  private reconnectTimer: number | null = null
+  private connectedAtMs = 0
+  private shuttingDown = false
+
+  private readonly listeners: {
+    [K in keyof CallSocketEventMap]?: Set<Listener<K>>
+  } = {}
+
+  private readonly url: string
+  private readonly resumeWindowMs: number
+  private readonly heartbeatIntervalMs: number
+  private readonly WebSocketImpl: typeof WebSocket
+  private readonly log: NonNullable<CallSocketOptions['log']>
+
+  constructor(opts: CallSocketOptions) {
+    this.url = opts.url
+    this.resumeWindowMs = (opts.resumeWindowSec ?? 20) * 1000
+    this.heartbeatIntervalMs = opts.heartbeatIntervalMs ?? 15_000
+    this.WebSocketImpl = opts.webSocketImpl ?? WebSocket
+    this.log = opts.log ?? {
+      info: (m, e) => console.info(`[callSocket] ${m}`, e ?? ''),
+      warn: (m, e) => console.warn(`[callSocket] ${m}`, e ?? ''),
+      error: (m, e) => console.error(`[callSocket] ${m}`, e ?? ''),
+    }
+  }
+
+  // Public API ----------------------------------------------------
+
+  getStatus(): CallLifecycleStatus { return this.status }
+
+  on<E extends keyof CallSocketEventMap>(evt: E, fn: Listener<E>): () => void {
+    let set = this.listeners[evt] as Set<Listener<E>> | undefined
+    if (!set) {
+      set = new Set<Listener<E>>()
+      // Narrow through `as unknown` — TS can't track the generic
+      // discriminant through the indexed property set.
+      ;(this.listeners as Record<string, unknown>)[evt] = set
+    }
+    set.add(fn)
+    return () => set!.delete(fn)
+  }
+
+  /** Open the socket. Safe to call exactly once per instance. */
+  connect(): void {
+    if (this.status !== 'idle') {
+      this.log.warn('connect() called in non-idle state', { status: this.status })
+      return
+    }
+    this.openSocket()
+  }
+
+  /** Send the captured user transcript as a chat turn. Queued if the
+   *  socket is currently mid-reconnect. */
+  sendTranscript(p: TranscriptFinalPayload): void {
+    this.enqueueLine({ type: 'transcript.final', ts: Date.now(), payload: p })
+  }
+
+  /** Bookkeeping — muted, speaker on/off, app backgrounded. */
+  sendUiState(p: UiStatePayload): void {
+    this.enqueueLine({ type: 'ui.state', ts: Date.now(), payload: p })
+  }
+
+  /** Control channel — 'ping' requests a pong; 'end' terminates. */
+  sendControl(action: CallControlAction): void {
+    this.enqueueLine({ type: 'call.control', ts: Date.now(), payload: { action } })
+  }
+
+  /** Phase 2 — interim STT output while the user is still speaking.
+   *  Server uses it as a secondary barge-in trigger and, in a
+   *  future phase, for semantic endpointing. Safe no-op against a
+   *  non-streaming server (unknown type is dropped). */
+  sendTranscriptPartial(p: { text: string; stable_prefix_len?: number }): void {
+    this.enqueueLine({
+      type: 'transcript.partial',
+      ts: Date.now(),
+      payload: p,
+    })
+  }
+
+  /** Phase 3 — explicit interrupt. Fired the instant the client's
+   *  VAD trips above threshold while an assistant turn is in-flight.
+   *  ``turn_id`` disambiguates against a stale signal racing a new
+   *  turn; the server compares ids and silently drops mismatches. */
+  sendBargeIn(turn_id: string): void {
+    this.enqueueLine({
+      type: 'user.barge_in',
+      ts: Date.now(),
+      payload: { turn_id },
+    })
+  }
+
+  /** Graceful user-initiated end. Sends control 'end', then closes. */
+  end(): void {
+    if (this.shuttingDown) return
+    this.shuttingDown = true
+    this.transition('draining')
+    this.sendControl('end')
+    // Give the server ~400 ms to echo call.state {status:'ended'}
+    // before we force-close; prevents the socket from looking
+    // orphaned in backend logs.
+    window.setTimeout(() => this.dispose('user_ended'), 400)
+  }
+
+  /** Teardown without a control 'end' — used when the component
+   *  unmounts, the user navigates away, or a terminal error occurs. */
+  dispose(reason: CallCloseReason = 'unmounted', code = NORMAL_CLOSURE): void {
+    if (this.status === 'closed') return
+    this.shuttingDown = true
+    this.clearTimers()
+    try { this.ws?.close(code, reason) } catch { /* already closed */ }
+    this.ws = null
+    this.outboundQueue = []
+    this.transition('closed')
+    this.emit('closed', { reason, code })
+  }
+
+  // Socket lifecycle ----------------------------------------------
+
+  private openSocket(): void {
+    this.transition(this.reconnectAttempt === 0 ? 'connecting' : 'reconnecting')
+    let ws: WebSocket
+    try {
+      ws = new this.WebSocketImpl(this.url)
+    } catch (err) {
+      this.log.error('WebSocket constructor threw', { err: String(err) })
+      this.scheduleReconnect()
+      return
+    }
+    this.ws = ws
+    this.lastServerActivityMs = Date.now()
+
+    ws.addEventListener('open', () => {
+      this.reconnectAttempt = 0
+      this.connectedAtMs = Date.now()
+      this.transition('live')
+      this.startHeartbeat()
+      this.flushQueue()
+    })
+
+    ws.addEventListener('message', (ev) => this.onMessage(ev))
+
+    ws.addEventListener('close', (ev) => this.onClose(ev))
+
+    ws.addEventListener('error', () => {
+      // The browser fires `error` right before `close` on network
+      // failures. We don't transition here — onClose() decides
+      // reconnect vs terminal based on the code.
+      this.log.warn('socket error event')
+    })
+  }
+
+  private onMessage(ev: MessageEvent): void {
+    this.lastServerActivityMs = Date.now()
+    if (typeof ev.data !== 'string') return
+
+    let env: ServerEnvelope | null = null
+    try {
+      env = JSON.parse(ev.data) as ServerEnvelope
+    } catch {
+      this.log.warn('non-JSON frame dropped')
+      return
+    }
+    if (!env || typeof env.type !== 'string') return
+
+    // Monotonic seq validation. If the server ever ships out-of-order
+    // frames we log once and keep going — correctness trumps strictness.
+    if (typeof env.seq === 'number' && env.seq <= this.lastServerSeq) {
+      this.log.warn('non-monotonic seq', {
+        got: env.seq, last: this.lastServerSeq, type: env.type,
+      })
+    } else if (typeof env.seq === 'number') {
+      this.lastServerSeq = env.seq
+    }
+
+    this.dispatch(env)
+  }
+
+  private dispatch(env: ServerEnvelope): void {
+    const raw = env.payload as unknown
+    switch (env.type) {
+      case 'call.state': {
+        const p = raw as CallStatePayload
+        this.emit('callState', p)
+        if (p.status === 'ended') this.dispose('user_ended')
+        return
+      }
+      case 'transcript.final':
+        this.emit('assistantTranscript', raw as AssistantTranscriptPayload)
+        return
+      case 'assistant.partial':
+        this.emit('assistantPartial', raw as AssistantPartialPayload)
+        return
+      case 'assistant.turn_end':
+        this.emit('assistantTurnEnd', raw as AssistantTurnEndPayload)
+        return
+      case 'assistant.cancel':
+        this.emit('assistantCancel', raw as AssistantCancelPayload)
+        return
+      case 'assistant.filler':
+        this.emit('assistantFiller', raw as AssistantFillerPayload)
+        return
+      case 'assistant.backchannel':
+        this.emit('assistantBackchannel', raw as AssistantBackchannelPayload)
+        return
+      case 'safety.notice':
+        this.emit('safetyNotice', env.payload)
+        return
+      case 'error':
+        this.emit('serverError', raw as ServerErrorPayload)
+        return
+      case 'pong':
+        this.emit('pong', undefined as void)
+        return
+      case 'ping':
+        // Server heartbeat — immediately echo to keep the liveness
+        // counters tight on both ends.
+        this.sendControl('ping')
+        return
+      default:
+        // Forward-compat: unknown event types are no-ops.
+        this.log.info(`unknown server event: ${env.type}`)
+    }
+  }
+
+  private onClose(ev: CloseEvent): void {
+    const reason = closeReasonFrom(ev.code, ev.reason)
+    this.clearTimers()
+
+    // Terminal close codes: don't reconnect.
+    const terminal: ReadonlySet<CallCloseReason> = new Set([
+      'user_ended',
+      'max_duration',
+      'resume_expired',
+      'bad_resume_token',
+      'session_not_found',
+      'session_ended',
+      'websocket_disabled',
+    ])
+    if (this.shuttingDown || terminal.has(reason)) {
+      this.ws = null
+      this.transition('closed')
+      this.emit('closed', { reason, code: ev.code, detail: ev.reason })
+      return
+    }
+
+    // Transient — try to reconnect within the resume window.
+    this.log.warn('socket dropped; scheduling reconnect', {
+      code: ev.code, reason: ev.reason,
+    })
+    this.ws = null
+    this.scheduleReconnect()
+  }
+
+  private scheduleReconnect(): void {
+    if (this.shuttingDown) return
+    const sinceLiveMs = this.connectedAtMs > 0 ? Date.now() - this.connectedAtMs : 0
+    if (sinceLiveMs > this.resumeWindowMs) {
+      this.log.warn('resume window elapsed; giving up')
+      this.dispose('resume_expired', POLICY_VIOLATION)
+      return
+    }
+    const delay = backoffMs(this.reconnectAttempt)
+    this.reconnectAttempt += 1
+    this.transition('reconnecting')
+    this.reconnectTimer = window.setTimeout(() => {
+      this.reconnectTimer = null
+      this.openSocket()
+    }, delay)
+  }
+
+  // Queue + heartbeat ---------------------------------------------
+
+  private enqueueLine(env: { type: string; ts: number; payload: unknown }): void {
+    const line = JSON.stringify(env)
+    if (this.status === 'live' && this.ws?.readyState === this.WebSocketImpl.OPEN) {
+      try { this.ws.send(line) } catch (err) {
+        this.log.warn('send failed; queueing', { err: String(err) })
+        this.outboundQueue.push(line)
+      }
+    } else {
+      this.outboundQueue.push(line)
+    }
+  }
+
+  private flushQueue(): void {
+    if (!this.ws || this.ws.readyState !== this.WebSocketImpl.OPEN) return
+    const q = this.outboundQueue
+    this.outboundQueue = []
+    for (const line of q) {
+      try { this.ws.send(line) } catch (err) {
+        this.log.error('flush failed; re-queueing remaining', { err: String(err) })
+        this.outboundQueue.push(line)
+        return
+      }
+    }
+  }
+
+  private startHeartbeat(): void {
+    this.clearHeartbeat()
+    this.heartbeatTimer = window.setInterval(() => {
+      this.sendControl('ping')
+    }, this.heartbeatIntervalMs)
+
+    // Dead-peer watchdog — if we haven't heard from the server in
+    // 2× the heartbeat interval, force a reconnect. Avoids hanging
+    // forever on half-open TCP sockets (mobile NAT rebinds).
+    this.deadPeerTimer = window.setInterval(() => {
+      if (Date.now() - this.lastServerActivityMs > this.heartbeatIntervalMs * 2) {
+        this.log.warn('peer silent; forcing reconnect')
+        try { this.ws?.close() } catch { /* ignore */ }
+      }
+    }, this.heartbeatIntervalMs)
+  }
+
+  private clearHeartbeat(): void {
+    if (this.heartbeatTimer !== null) {
+      window.clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = null
+    }
+    if (this.deadPeerTimer !== null) {
+      window.clearInterval(this.deadPeerTimer)
+      this.deadPeerTimer = null
+    }
+  }
+
+  private clearTimers(): void {
+    this.clearHeartbeat()
+    if (this.reconnectTimer !== null) {
+      window.clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+  }
+
+  // Emit + state transition ---------------------------------------
+
+  private emit<E extends keyof CallSocketEventMap>(
+    evt: E, payload: CallSocketEventMap[E],
+  ): void {
+    const set = this.listeners[evt] as Set<Listener<E>> | undefined
+    if (!set) return
+    for (const fn of set) {
+      try { fn(payload) } catch (err) {
+        this.log.error('listener threw', { evt, err: String(err) })
+      }
+    }
+  }
+
+  private transition(next: CallLifecycleStatus): void {
+    if (this.status === next) return
+    this.status = next
+    this.emit('statusChange', next)
+  }
+}

frontend/src/ui/call/log.ts

@@ -0,0 +1,140 @@
+/**
+ * Structured call-lifecycle logger + shared TTS ownership.
+ *
+ * Three pieces, shipped together because they're tightly coupled:
+ *
+ *   clog(evt)                Namespaced, grep-friendly console log
+ *                             for every call-related event. Format
+ *                             ``[Call+<ms>] {e:…, …}`` so
+ *                             ``grep "\\[Call\\]"`` surfaces a
+ *                             chronological trace of any session.
+ *
+ *   speakOwned(source, text)  Single-owner TTS dispatch. Both the
+ *                             overlay's fallback opener and the
+ *                             App-level assistant-reply effect route
+ *                             through this function, which guards
+ *                             on ``window.__hp_tts_owner__`` so
+ *                             duplicate sources don't double-speak
+ *                             the same turn. First to call wins;
+ *                             the second sees ``owner !== source``
+ *                             and drops cleanly (emits an
+ *                             ``tts: dedupe`` log so the drop is
+ *                             auditable).
+ *
+ *   isCallFullDuplexEnabled() Feature flag gate. Defaults to ON; a
+ *                             user can force-off via
+ *                             ``localStorage.homepilot_call_full_duplex``
+ *                             or a build-time ``VITE_CALL_FULL_DUPLEX_ENABLED``.
+ *                             With the flag off every consumer keeps
+ *                             its pre-flag behaviour — lets us flip
+ *                             the full-duplex fix on/off during
+ *                             dogfood without editing code.
+ *
+ * No runtime DOM setup; safe to import from SSR contexts — the
+ * speakOwned path guards on ``typeof window``.
+ */
+
+export type CallLogEvent =
+  | { e: 'lifecycle'; phase: 'open' | 'ready' | 'greet' | 'hangup' | 'close'; sid?: string }
+  | { e: 'tts'; action: 'start' | 'end' | 'dedupe'; source: 'overlay' | 'app-level'; textLen: number }
+  | { e: 'vad'; action: 'speech_start' | 'speech_end' | 'suppressed'; level?: number; state: string }
+  | { e: 'turn'; action: 'user_out' | 'assistant_in' | 'barge_in'; route: 'ws' | 'chat_rest'; latencyMs?: number }
+  | { e: 'state'; from: string; to: string; trigger: string }
+  | { e: 'error'; where: string; message: string }
+
+declare global {
+  interface Window {
+    __hp_tts_owner__?: 'overlay' | 'app-level' | null
+  }
+}
+
+export function clog(evt: CallLogEvent): void {
+  if (typeof performance === 'undefined') return
+  const ts = Math.floor(performance.now())
+  // console.info so DevTools 'Info' filter can hide it in prod if
+  // needed; keeps the log present for debug without noise.
+  // eslint-disable-next-line no-console
+  console.info(`[Call+${ts}]`, evt)
+}
+
+/** Resolve the feature-flag state. Priority:
+ *    1. ``localStorage.homepilot_call_full_duplex`` override
+ *    2. build-time ``VITE_CALL_FULL_DUPLEX_ENABLED`` (default 'true')
+ *  Falls through to ``true`` on any read error. */
+export function isCallFullDuplexEnabled(): boolean {
+  if (typeof window === 'undefined') return true
+  try {
+    const override = window.localStorage.getItem('homepilot_call_full_duplex')
+    if (override === 'true') return true
+    if (override === 'false') return false
+  } catch {
+    /* ignore storage errors */
+  }
+  const envVal = (import.meta as unknown as {
+    env?: Record<string, string | undefined>
+  }).env?.VITE_CALL_FULL_DUPLEX_ENABLED
+  return String(envVal ?? 'true') !== 'false'
+}
+
+export interface SpeakOwnedHooks {
+  onStart?: () => void
+  onEnd?: () => void
+  onError?: (message: string) => void
+}
+
+/**
+ * Speak ``text`` via ``window.SpeechService`` with a shared owner
+ * lock. Returns ``true`` if this call owns the utterance, ``false``
+ * if another owner was already speaking (dedupe). Hooks fire on
+ * the owning path only.
+ *
+ * Fallback when the shim isn't available: emits the ``tts.start``
+ * log + an estimated ``tts.end`` timer anyway, so callers still
+ * get their ``onEnd`` hook (used by the mic-gate release in
+ * ``CallOverlay``) even with no TTS engine present.
+ */
+export function speakOwned(
+  source: 'overlay' | 'app-level',
+  text: string,
+  hooks?: SpeakOwnedHooks,
+): boolean {
+  if (typeof window === 'undefined') return false
+  const t = (text ?? '').trim()
+  if (!t) return false
+  const owner = window.__hp_tts_owner__
+  if (owner && owner !== source) {
+    clog({ e: 'tts', action: 'dedupe', source, textLen: t.length })
+    return false
+  }
+  window.__hp_tts_owner__ = source
+  try {
+    hooks?.onStart?.()
+    clog({ e: 'tts', action: 'start', source, textLen: t.length })
+    const svc = (window as unknown as {
+      SpeechService?: { speak?: (text: string) => void }
+    }).SpeechService
+    svc?.speak?.(t)
+    // Length-estimate for the onEnd release — the SpeechService shim
+    // in this repo doesn't expose an explicit onend hook, so we
+    // guesstimate from text length + cap it so a runaway payload
+    // can't permanently hold the owner lock. ~12 chars/s typical;
+    // [800 ms, 10 s] clamp.
+    const estimateMs = Math.max(800, Math.min(10_000, t.length * 80))
+    window.setTimeout(() => {
+      if (window.__hp_tts_owner__ === source) {
+        window.__hp_tts_owner__ = null
+      }
+      hooks?.onEnd?.()
+      clog({ e: 'tts', action: 'end', source, textLen: t.length })
+    }, estimateMs)
+    return true
+  } catch (err) {
+    if (window.__hp_tts_owner__ === source) {
+      window.__hp_tts_owner__ = null
+    }
+    const message = err instanceof Error ? err.message : String(err)
+    hooks?.onError?.(message)
+    clog({ e: 'error', where: 'speakOwned', message })
+    return false
+  }
+}

frontend/src/ui/call/streamTts.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Unit tests for streamTts — the pluggable streaming TTS surface.
+ * Anchored to § 5.3 of docs/analysis/voice-call-streaming-design.md.
+ */
+import { describe, it, expect } from 'vitest'
+import { createStreamingTts, streamTtsInternals } from './streamTts'
+
+const { splitIntoSentences, NullStreamTts } = streamTtsInternals
+
+describe('splitIntoSentences', () => {
+  it('splits on sentence enders followed by whitespace', () => {
+    const { sentences, remainder } = splitIntoSentences(
+      'hello there. how are you? fine! and you',
+    )
+    expect(sentences).toEqual([
+      'hello there.',
+      'how are you?',
+      'fine!',
+    ])
+    expect(remainder).toBe('and you')
+  })
+
+  it('keeps partial trailing text as remainder', () => {
+    const { sentences, remainder } = splitIntoSentences('partial sentence')
+    expect(sentences).toEqual([])
+    expect(remainder).toBe('partial sentence')
+  })
+
+  it('is safe on empty input', () => {
+    const { sentences, remainder } = splitIntoSentences('')
+    expect(sentences).toEqual([])
+    expect(remainder).toBe('')
+  })
+
+  it('splits on newlines + semicolons', () => {
+    const { sentences, remainder } = splitIntoSentences(
+      'one thing;\n another thing.\n tail',
+    )
+    // Exact count + order matters so regressions are obvious.
+    expect(sentences.length).toBeGreaterThanOrEqual(2)
+    expect(sentences[0]).toContain('one thing')
+    expect(remainder.trim()).toBe('tail')
+  })
+})
+
+describe('NullStreamTts fallback', () => {
+  it('is safe to call every method; never claims to be speaking', () => {
+    const tts = new NullStreamTts()
+    expect(tts.isSpeaking).toBe(false)
+    tts.appendDelta('hello')
+    tts.flush()
+    tts.stop()
+    expect(tts.isSpeaking).toBe(false)
+  })
+})
+
+describe('createStreamingTts factory', () => {
+  it('returns an object implementing the StreamingTts contract', () => {
+    const tts = createStreamingTts()
+    expect(typeof tts.appendDelta).toBe('function')
+    expect(typeof tts.flush).toBe('function')
+    expect(typeof tts.stop).toBe('function')
+    expect(typeof tts.isSpeaking).toBe('boolean')
+  })
+})

frontend/src/ui/call/streamTts.ts

@@ -0,0 +1,173 @@
+/**
+ * streamTts.ts — pluggable streaming text-to-speech surface.
+ *
+ * One interface, three planned implementations. This file ships the
+ * first (browser Web Speech); Piper-WASM and remote vendor streamers
+ * are follow-ups that just swap the concrete constructor in
+ * :func:`createStreamingTts`.
+ *
+ * Contract (§ 5.3 of docs/analysis/voice-call-streaming-design.md):
+ *
+ *   appendDelta(delta)   push a new text chunk. Implementations
+ *                         flush to the audio engine at sentence
+ *                         boundaries; callers hand over raw deltas
+ *                         without worrying about clause shaping.
+ *   flush()              signal end-of-turn. Any residual buffer
+ *                         is spoken; the engine transitions back
+ *                         to idle once the audio drains.
+ *   stop()               barge-in. MUST silence any audio playing
+ *                         or scheduled to play within ≤ 50 ms on
+ *                         Chromium. Cheap to call redundantly.
+ *   isSpeaking           read-only; true while audio is playing or
+ *                         scheduled. Drives the VAD-tap enable gate.
+ */
+
+export interface StreamingTts {
+  appendDelta(delta: string): void
+  flush(): void
+  stop(): void
+  readonly isSpeaking: boolean
+}
+
+// ── Sentence-boundary helper ──────────────────────────────────────────
+//
+// Flush on: .  !  ?  ; or a newline — but only when they're followed
+// by whitespace or end-of-buffer (so "e.g." / "Dr." don't mis-split).
+// A tiny regex, kept readable rather than clever; the failure mode on
+// a miss is "one extra utterance per turn," not a correctness bug.
+
+const SENTENCE_END = /([.!?;\n])\s+/g
+
+function splitIntoSentences(buffer: string): {
+  sentences: string[]
+  remainder: string
+} {
+  const sentences: string[] = []
+  let lastIndex = 0
+  let m: RegExpExecArray | null
+  SENTENCE_END.lastIndex = 0
+  while ((m = SENTENCE_END.exec(buffer)) !== null) {
+    const end = m.index + m[0].length
+    const piece = buffer.slice(lastIndex, end).trim()
+    if (piece) sentences.push(piece)
+    lastIndex = end
+  }
+  const remainder = buffer.slice(lastIndex)
+  return { sentences, remainder }
+}
+
+// ── Web Speech implementation (ships first) ──────────────────────────
+//
+// Uses ``window.speechSynthesis`` directly. Each sentence becomes
+// exactly one SpeechSynthesisUtterance so barge-in (via ``cancel()``)
+// drops the current sentence + the queue atomically.
+//
+// Why one utterance per sentence instead of one per delta:
+//
+//  1. SpeechSynthesis queues utterances, not characters. Passing every
+//     delta through would create 40+ queued utterances per turn on
+//     Chromium, each with its own intonation reset — sounds robotic.
+//  2. Cancel semantics are per-utterance, so sentence-granularity
+//     means barge-in can interrupt mid-sentence without stranding
+//     half-spoken buffers.
+
+class WebSpeechStreamTts implements StreamingTts {
+  private buffer = ''
+  private speakingCount = 0
+  private stopped = false
+  private readonly syn: SpeechSynthesis | null
+
+  constructor() {
+    this.syn =
+      typeof window !== 'undefined' && 'speechSynthesis' in window
+        ? window.speechSynthesis
+        : null
+  }
+
+  get isSpeaking(): boolean {
+    return this.speakingCount > 0
+  }
+
+  appendDelta(delta: string): void {
+    if (this.stopped || !delta) return
+    this.buffer += delta
+    const { sentences, remainder } = splitIntoSentences(this.buffer)
+    this.buffer = remainder
+    for (const s of sentences) this._speak(s)
+  }
+
+  flush(): void {
+    if (this.stopped) return
+    if (this.buffer.trim()) {
+      this._speak(this.buffer.trim())
+      this.buffer = ''
+    }
+  }
+
+  stop(): void {
+    // Idempotent — safe to call repeatedly from the barge-in path.
+    this.stopped = true
+    this.buffer = ''
+    this.speakingCount = 0
+    try {
+      this.syn?.cancel()
+    } catch {
+      /* cancel is best-effort */
+    }
+  }
+
+  private _speak(text: string): void {
+    if (!this.syn) return
+    let utter: SpeechSynthesisUtterance
+    try {
+      utter = new SpeechSynthesisUtterance(text)
+    } catch {
+      return
+    }
+    // Track speaking state so the VAD-tap enable gate stays tight
+    // even when the queue reorders utterances (Safari / old Chromium).
+    this.speakingCount += 1
+    const done = () => {
+      this.speakingCount = Math.max(0, this.speakingCount - 1)
+    }
+    utter.onend = done
+    utter.onerror = done
+    try {
+      this.syn.speak(utter)
+    } catch {
+      done()
+    }
+  }
+}
+
+// ── Null implementation — used in tests + as a safety fallback ───────
+
+class NullStreamTts implements StreamingTts {
+  isSpeaking = false
+  appendDelta(_delta: string): void { /* no-op */ }
+  flush(): void { /* no-op */ }
+  stop(): void { /* no-op */ }
+}
+
+// ── Factory ───────────────────────────────────────────────────────────
+//
+// Returns the best implementation available at runtime. Swapping
+// in Piper-WASM or a remote vendor streamer is a one-line change
+// in this function — call sites don't need to know.
+
+export function createStreamingTts(): StreamingTts {
+  if (typeof window === 'undefined') return new NullStreamTts()
+  if (!('speechSynthesis' in window)) return new NullStreamTts()
+  // Probe for the existence of an app-level SpeechService shim; if
+  // present we could route through it, but for now the direct Web
+  // Speech path is both simpler and lower-latency.
+  return new WebSpeechStreamTts()
+}
+
+// Exported for tests + rare callers that want an explicit unplugged
+// implementation (e.g. when a user opts out of TTS entirely).
+export const streamTtsInternals = {
+  splitIntoSentences,
+  WebSpeechStreamTts,
+  NullStreamTts,
+}

frontend/src/ui/call/useCallSession.ts

@@ -0,0 +1,381 @@
+/**
+ * useCallSession — React hook that owns the voice_call lifecycle.
+ *
+ * One instance per mounted `CallOverlayInner`. Composes callApi +
+ * callSocket into a single, cleanup-safe React surface:
+ *
+ *   const session = useCallSession({ enabled, backendUrl, authToken,
+ *                                    conversationId, personaId,
+ *                                    deviceInfo })
+ *
+ *   session.status                → 'idle' | 'creating' | 'connecting'
+ *                                  | 'live' | 'reconnecting'
+ *                                  | 'unavailable' | 'error' | 'closed'
+ *   session.sendTranscript(text)  → route STT capture to the backend
+ *   session.end()                 → graceful user-initiated close
+ *   session.onAssistantTranscript → subscribe to assistant replies
+ *   session.onAssistantFiller     → subscribe to "hmm…" events
+ *   session.onAssistantBackchannel → subscribe to "mm-hm" events
+ *   session.lastError             → surface for the UI
+ *
+ * When `enabled` flips to true we:
+ *   1. POST /v1/voice-call/sessions  (via callApi)
+ *   2. Open the WebSocket             (via callSocket)
+ *   3. Wire status + event forwarding into React state
+ *
+ * Critically, if the POST returns 404/501 (backend has
+ * VOICE_CALL_ENABLED=false) we surface `status='unavailable'` and
+ * stop — the caller then falls back to the chat-REST path. That
+ * graceful-degradation path is what lets us ship this module
+ * independent of the backend flag rollout.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import {
+  createCallSession,
+  resolveWsUrl,
+  CallApiError,
+  type CreateCallSessionRequest,
+  type CreateCallSessionResponse,
+} from './callApi'
+import {
+  CallSocket,
+  type AssistantBackchannelPayload,
+  type AssistantCancelPayload,
+  type AssistantFillerPayload,
+  type AssistantPartialPayload,
+  type AssistantTranscriptPayload,
+  type AssistantTurnEndPayload,
+  type CallCloseReason,
+  type CallLifecycleStatus,
+} from './callSocket'
+
+export type CallSessionStatus =
+  | 'idle'
+  | 'creating'
+  | 'connecting'
+  | 'live'
+  | 'reconnecting'
+  | 'draining'
+  | 'closed'
+  | 'unavailable'
+  | 'error'
+
+export interface UseCallSessionArgs {
+  /** The hook is inert until this flips to true. Flipping back to
+   *  false triggers a graceful dispose. */
+  enabled: boolean
+  /** Resolved HomePilot backend URL (scheme + host). */
+  backendUrl: string
+  /** Bearer JWT for the REST handshake + WS query param. */
+  authToken: string | null
+  /** Session-creation request fields. */
+  request: CreateCallSessionRequest
+}
+
+export interface CallSessionHandle {
+  status: CallSessionStatus
+  /** Server-side canonical status last seen (live / ending / ended). */
+  callState: 'live' | 'ending' | 'ended' | null
+  /** Raw close reason once the session terminates. Useful for
+   *  differentiating user-end vs timeout vs backend-disabled. */
+  closeReason: CallCloseReason | null
+  /** Any terminal error. 'unavailable' is NOT an error — it's a
+   *  legitimate graceful-degradation signal. */
+  lastError: string | null
+  /** Route a final STT transcript into the call turn. No-op outside
+   *  the 'live' | 'reconnecting' states. */
+  sendTranscript: (text: string) => void
+  /** Graceful end — sends call.control end, closes the socket. */
+  end: () => void
+  /** Bookkeeping. Server persists the *type* of the event only. */
+  sendUiState: (p: { muted?: boolean; speaker_on?: boolean; backgrounded?: boolean }) => void
+  /** Phase 2 — interim user STT (secondary barge-in signal). */
+  sendTranscriptPartial: (p: { text: string; stable_prefix_len?: number }) => void
+  /** Phase 3 — explicit user interrupt carrying the active turn_id. */
+  sendBargeIn: (turn_id: string) => void
+  /** Whether this session negotiated streaming. Pulled from the
+   *  session-create capabilities response. False = unary mode. */
+  streamingNegotiated: boolean
+  /** Whether this session negotiated barge-in (implies streaming). */
+  bargeInNegotiated: boolean
+  /** Subscribe helpers — each returns an unsubscribe fn. Stable
+   *  identities via useRef-backed implementation so the caller can
+   *  pass them to useEffect deps without re-subscription storms. */
+  onAssistantTranscript: (fn: (p: AssistantTranscriptPayload) => void) => () => void
+  onAssistantFiller: (fn: (p: AssistantFillerPayload) => void) => () => void
+  onAssistantBackchannel: (fn: (p: AssistantBackchannelPayload) => void) => () => void
+  /** Phase 2 subscribes. */
+  onAssistantPartial: (fn: (p: AssistantPartialPayload) => void) => () => void
+  onAssistantTurnEnd: (fn: (p: AssistantTurnEndPayload) => void) => () => void
+  onAssistantCancel: (fn: (p: AssistantCancelPayload) => void) => () => void
+}
+
+// When the backend returns 404/501 for voice_call (VOICE_CALL_ENABLED=false)
+// we remember the miss per-backend and short-circuit future session creates
+// for UNAVAILABLE_BACKOFF_MS. Without this, every CallOverlay mount posts a
+// fresh 404 against the same flag, spamming the console and delaying the
+// fallback path by a full network round-trip.
+const UNAVAILABLE_BACKOFF_MS = 30_000
+const unavailableUntilByBackend = new Map<string, number>()
+
+export function useCallSession(args: UseCallSessionArgs): CallSessionHandle {
+  const { enabled, backendUrl, authToken, request } = args
+
+  const [status, setStatus] = useState<CallSessionStatus>('idle')
+  const [callState, setCallState] = useState<'live' | 'ending' | 'ended' | null>(null)
+  const [closeReason, setCloseReason] = useState<CallCloseReason | null>(null)
+  const [lastError, setLastError] = useState<string | null>(null)
+
+  const socketRef = useRef<CallSocket | null>(null)
+  const sessionRef = useRef<CreateCallSessionResponse | null>(null)
+
+  // Stable subscribe surface. Keep listener sets here so they survive
+  // socket reconnects — the old socket's listeners are torn down with
+  // it, but user subscriptions persist across reconnects and are
+  // re-attached when a new socket comes up.
+  const txListeners = useRef(new Set<(p: AssistantTranscriptPayload) => void>())
+  const fillerListeners = useRef(new Set<(p: AssistantFillerPayload) => void>())
+  const bcListeners = useRef(new Set<(p: AssistantBackchannelPayload) => void>())
+  // Phase 2/3 listener sets. Kept separate so an old subscribe set
+  // doesn't churn when a new one mounts (stream wire-up rebinds often
+  // during CallOverlay renders).
+  const partialListeners = useRef(new Set<(p: AssistantPartialPayload) => void>())
+  const turnEndListeners = useRef(new Set<(p: AssistantTurnEndPayload) => void>())
+  const cancelListeners = useRef(new Set<(p: AssistantCancelPayload) => void>())
+  // Negotiated modes — re-derived on session create, stashed here so
+  // every render reads the same value without re-running the effect.
+  const [streamingNegotiated, setStreamingNegotiated] = useState(false)
+  const [bargeInNegotiated, setBargeInNegotiated] = useState(false)
+
+  // Ref'd primitive so the session-create effect doesn't re-trigger
+  // when the request object identity changes every render.
+  const requestRef = useRef(request)
+  useEffect(() => { requestRef.current = request }, [request])
+
+  // Main lifecycle. Runs once per (enabled, backendUrl, authToken)
+  // triple — which is what we want: flipping enabled true/false
+  // drives open/close; swapping backendUrl or re-auth reconnects.
+  useEffect(() => {
+    if (!enabled) return
+
+    let disposed = false
+    const teardown = () => {
+      disposed = true
+      socketRef.current?.dispose('unmounted')
+      socketRef.current = null
+      sessionRef.current = null
+    }
+
+    const run = async () => {
+      setStatus('creating')
+      setLastError(null)
+      setCloseReason(null)
+      setCallState(null)
+
+      // Skip the POST entirely if this backend has been 404/501-ing
+      // recently. Saves a round-trip per call re-entry while the flag
+      // is off server-side; the backoff window expires automatically
+      // when we clear the map entry below on a success.
+      const skipUntil = unavailableUntilByBackend.get(backendUrl)
+      if (skipUntil && Date.now() < skipUntil) {
+        // eslint-disable-next-line no-console
+        console.info(
+          '[useCallSession] skipping createCallSession — backend flagged unavailable',
+          { backendUrl, resumesAt: new Date(skipUntil).toISOString() },
+        )
+        setStatus('unavailable')
+        return
+      }
+
+      let handshake: CreateCallSessionResponse
+      try {
+        handshake = await createCallSession(backendUrl, requestRef.current, authToken)
+      } catch (err) {
+        if (disposed) return
+        if (err instanceof CallApiError && err.isUnavailable) {
+          unavailableUntilByBackend.set(
+            backendUrl,
+            Date.now() + UNAVAILABLE_BACKOFF_MS,
+          )
+          // eslint-disable-next-line no-console
+          console.warn(
+            '[useCallSession] voice_call unavailable — falling back to chat REST for',
+            `${UNAVAILABLE_BACKOFF_MS}ms`,
+          )
+          setStatus('unavailable')
+          return
+        }
+        // eslint-disable-next-line no-console
+        console.error('[useCallSession] createCallSession failed', err)
+        setStatus('error')
+        setLastError(err instanceof Error ? err.message : String(err))
+        return
+      }
+      if (disposed) return
+
+      // Handshake worked — clear any prior backoff so new flag flips
+      // take effect immediately instead of waiting out the window.
+      unavailableUntilByBackend.delete(backendUrl)
+
+      sessionRef.current = handshake
+      const url = resolveWsUrl(
+        handshake.ws_url,
+        handshake.session_id,
+        handshake.resume_token,
+        authToken,
+        backendUrl,
+      )
+
+      const sock = new CallSocket({ url })
+      socketRef.current = sock
+
+      // Translate socket lifecycle → hook status.
+      sock.on('statusChange', (s: CallLifecycleStatus) => {
+        if (disposed) return
+        setStatus(s === 'idle' ? 'idle' : s)
+      })
+      sock.on('callState', (p) => {
+        if (disposed) return
+        setCallState(p.status)
+      })
+      sock.on('closed', ({ reason }) => {
+        if (disposed) return
+        setStatus('closed')
+        setCloseReason(reason)
+      })
+      sock.on('serverError', (p) => {
+        // Non-terminal by contract; surface for the UI but keep the
+        // socket open. The server will close explicitly if fatal.
+        if (disposed) return
+        setLastError(`${p.code}: ${p.message}`)
+      })
+      sock.on('assistantTranscript', (p) => {
+        for (const fn of txListeners.current) fn(p)
+      })
+      sock.on('assistantFiller', (p) => {
+        for (const fn of fillerListeners.current) fn(p)
+      })
+      sock.on('assistantBackchannel', (p) => {
+        for (const fn of bcListeners.current) fn(p)
+      })
+      // Phase 2/3 event fan-outs.
+      sock.on('assistantPartial', (p) => {
+        for (const fn of partialListeners.current) fn(p)
+      })
+      sock.on('assistantTurnEnd', (p) => {
+        for (const fn of turnEndListeners.current) fn(p)
+      })
+      sock.on('assistantCancel', (p) => {
+        for (const fn of cancelListeners.current) fn(p)
+      })
+
+      // Reflect negotiated modes from the session-create response.
+      const caps = handshake.capabilities as
+        | { streaming?: boolean; barge_in?: boolean } | undefined
+      setStreamingNegotiated(!!caps?.streaming)
+      setBargeInNegotiated(!!caps?.streaming && !!caps?.barge_in)
+
+      sock.connect()
+    }
+
+    void run()
+    return teardown
+  }, [enabled, backendUrl, authToken])
+
+  // Public actions. Guarded against stale-socket calls. --------------
+
+  const sendTranscript = useCallback((text: string) => {
+    const sock = socketRef.current
+    if (!sock) return
+    const trimmed = text.trim()
+    if (!trimmed) return
+    sock.sendTranscript({ text: trimmed })
+  }, [])
+
+  const end = useCallback(() => {
+    socketRef.current?.end()
+  }, [])
+
+  const sendUiState = useCallback(
+    (p: { muted?: boolean; speaker_on?: boolean; backgrounded?: boolean }) => {
+      socketRef.current?.sendUiState(p)
+    },
+    [],
+  )
+
+  const sendTranscriptPartial = useCallback(
+    (p: { text: string; stable_prefix_len?: number }) => {
+      socketRef.current?.sendTranscriptPartial(p)
+    },
+    [],
+  )
+
+  const sendBargeIn = useCallback((turn_id: string) => {
+    socketRef.current?.sendBargeIn(turn_id)
+  }, [])
+
+  const onAssistantTranscript = useCallback(
+    (fn: (p: AssistantTranscriptPayload) => void) => {
+      txListeners.current.add(fn)
+      return () => { txListeners.current.delete(fn) }
+    }, [],
+  )
+  const onAssistantFiller = useCallback(
+    (fn: (p: AssistantFillerPayload) => void) => {
+      fillerListeners.current.add(fn)
+      return () => { fillerListeners.current.delete(fn) }
+    }, [],
+  )
+  const onAssistantBackchannel = useCallback(
+    (fn: (p: AssistantBackchannelPayload) => void) => {
+      bcListeners.current.add(fn)
+      return () => { bcListeners.current.delete(fn) }
+    }, [],
+  )
+  const onAssistantPartial = useCallback(
+    (fn: (p: AssistantPartialPayload) => void) => {
+      partialListeners.current.add(fn)
+      return () => { partialListeners.current.delete(fn) }
+    }, [],
+  )
+  const onAssistantTurnEnd = useCallback(
+    (fn: (p: AssistantTurnEndPayload) => void) => {
+      turnEndListeners.current.add(fn)
+      return () => { turnEndListeners.current.delete(fn) }
+    }, [],
+  )
+  const onAssistantCancel = useCallback(
+    (fn: (p: AssistantCancelPayload) => void) => {
+      cancelListeners.current.add(fn)
+      return () => { cancelListeners.current.delete(fn) }
+    }, [],
+  )
+
+  return useMemo<CallSessionHandle>(() => ({
+    status,
+    callState,
+    closeReason,
+    lastError,
+    sendTranscript,
+    end,
+    sendUiState,
+    sendTranscriptPartial,
+    sendBargeIn,
+    streamingNegotiated,
+    bargeInNegotiated,
+    onAssistantTranscript,
+    onAssistantFiller,
+    onAssistantBackchannel,
+    onAssistantPartial,
+    onAssistantTurnEnd,
+    onAssistantCancel,
+  }), [
+    status, callState, closeReason, lastError,
+    sendTranscript, end, sendUiState,
+    sendTranscriptPartial, sendBargeIn,
+    streamingNegotiated, bargeInNegotiated,
+    onAssistantTranscript, onAssistantFiller, onAssistantBackchannel,
+    onAssistantPartial, onAssistantTurnEnd, onAssistantCancel,
+  ])
+}

frontend/src/ui/components/CreatorExportWizard.tsx

@@ -1,28 +1,65 @@
 /**
- * CreatorExportWizard — 2-step modal for exporting a Creator Studio video.
+ * CreatorExportWizard — 4-step modal for exporting a Creator Studio video
+ * with in-browser Piper TTS narration.
  *
  * Flow:
- *   1. Choose target — "MP4 (edit/share)" or "MP4 for YouTube".
- *   2. Render + download — POST /studio/videos/{id}/export/mp4, poll the
- *      job, then trigger a same-tab download via <a href download>.
+ *   1. Target    — MP4 (edit/share) vs MP4 for YouTube.
+ *   2. Voiceover — Piper voice + rate + pitch + subtitle burn-in toggle,
+ *                  with a Preview button.
+ *   3. Generate  — synthesize narration for every scene that has text
+ *                  (or re-synthesize all if the user checks "regenerate")
+ *                  and upload each WAV to the backend.
+ *   4. Render    — POST /studio/videos/{id}/export/mp4, poll, download.
  *
  * Race protection:
- *   The poller captures the wizard's mount-instance id at submit time and
- *   discards any response that returns after the wizard has been closed
- *   or after the user submitted a different render. This mirrors the
- *   session-epoch pattern used in App.tsx for account-switch races.
+ *   Every async op captures a per-mount epoch; closing the modal or
+ *   starting a new render bumps the epoch and stale responses are
+ *   dropped. Same pattern as App.tsx's account-switch guard.
  */
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Download, Film, Youtube, X, CheckCircle2, AlertTriangle, Loader2 } from 'lucide-react'
+import {
+  AlertTriangle,
+  CheckCircle2,
+  Download,
+  Film,
+  Loader2,
+  Mic,
+  Play,
+  Square,
+  X,
+  Youtube,
+} from 'lucide-react'
+
+import {
+  listVoices,
+  synthesizeToBlob,
+  speak as piperSpeak,
+  stop as piperStop,
+  isSupported as piperSupported,
+  getSelectedVoiceId,
+  setSelectedVoiceId,
+} from '../tts/piperTts'
+import { DEFAULT_PIPER_VOICE_ID } from '../tts/piperVoices'
 
 export type ExportKind = 'mp4_plain' | 'mp4_youtube'
 
+/** Minimum scene info the wizard needs. Matches the flat shape used
+ *  inside CreatorStudioEditor. */
+export interface WizardScene {
+  id: string
+  idx: number
+  narration: string
+  audioUrl: string | null
+}
+
 interface Props {
   open: boolean
   onClose: () => void
   backendUrl: string
   videoId: string
-  /** Display name shown in the modal header (project / video title). */
+  /** Ordered scenes the render will concatenate. */
+  scenes: WizardScene[]
+  /** Display name shown in the modal header. */
   videoTitle?: string
   /** Disable submit when there are no scenes or scenes are still generating. */
   disabledReason?: string | null
@@ -40,6 +77,7 @@ interface JobView {
 
 const POLL_INTERVAL_MS = 1000
 const POLL_TIMEOUT_MS = 10 * 60 * 1000 // 10 minutes
+const PREVIEW_TEXT = 'Hello, this is a preview of your selected voice.'
 
 function authHeaders(): Record<string, string> {
   const token = localStorage.getItem('homepilot_auth_token') || ''
@@ -50,35 +88,74 @@ function trimBackend(u: string): string {
   return u.replace(/\/+$/, '')
 }
 
+type Step = 1 | 2 | 3 | 4
+
 export default function CreatorExportWizard({
   open,
   onClose,
   backendUrl,
   videoId,
+  scenes,
   videoTitle,
   disabledReason,
 }: Props) {
-  const [step, setStep] = useState<1 | 2>(1)
+  // ── Step ─────────────────────────────────────────────────────────────────
+  const [step, setStep] = useState<Step>(1)
+
+  // ── Step 1 state ─────────────────────────────────────────────────────────
   const [kind, setKind] = useState<ExportKind>('mp4_youtube')
+
+  // ── Step 2 state ─────────────────────────────────────────────────────────
+  const voices = useMemo(() => listVoices(), [])
+  const [voiceId, setVoiceId] = useState<string>(() =>
+    piperSupported() ? getSelectedVoiceId() : DEFAULT_PIPER_VOICE_ID,
+  )
+  const [rate, setRate] = useState<number>(0.9)
+  const [pitch, setPitch] = useState<number>(1.0)
+  const [subtitlesBurnIn, setSubtitlesBurnIn] = useState<boolean>(true)
+  // Default: synthesize every scene that has narration text, even if an
+  // audioUrl already exists. The user's invariant is "audio from all
+  // scenes" at export time, so freshness beats speed by default.
+  // "Keep existing audio" below is the opt-in for re-exports of an
+  // unchanged project, where regenerating every take is wasted work.
+  const [keepExisting, setKeepExisting] = useState<boolean>(false)
+  const [previewing, setPreviewing] = useState<boolean>(false)
+  const [previewError, setPreviewError] = useState<string | null>(null)
+
+  // ── Step 3 state ─────────────────────────────────────────────────────────
+  const [genIdx, setGenIdx] = useState<number>(0)
+  const [genTotal, setGenTotal] = useState<number>(0)
+  const [genError, setGenError] = useState<string | null>(null)
+
+  // ── Step 4 state ─────────────────────────────────────────────────────────
   const [job, setJob] = useState<JobView | null>(null)
   const [submitError, setSubmitError] = useState<string | null>(null)
 
-  // Race protection: a monotonically-increasing token; every submit captures
-  // the current value, and the poller drops responses whose epoch < current.
+  // Race protection.
   const epochRef = useRef(0)
 
-  // Reset modal whenever it opens.
+  // Reset when modal opens or closes.
   useEffect(() => {
     if (open) {
       setStep(1)
       setJob(null)
       setSubmitError(null)
+      setGenIdx(0)
+      setGenTotal(0)
+      setGenError(null)
+      setPreviewing(false)
+      setPreviewError(null)
     } else {
-      // Closing the modal invalidates any in-flight poll.
       epochRef.current += 1
+      try { piperStop() } catch { /* ignore */ }
     }
   }, [open])
 
+  // Persist voice selection so subsequent renders remember the pick.
+  useEffect(() => {
+    if (voiceId) setSelectedVoiceId(voiceId)
+  }, [voiceId])
+
   const downloadUrl = useMemo(() => {
     if (!job || job.status !== 'done') return ''
     const tok = localStorage.getItem('homepilot_auth_token') || ''
@@ -86,12 +163,115 @@ export default function CreatorExportWizard({
     return `${trimBackend(backendUrl)}/studio/videos/${videoId}/export/jobs/${job.id}/download${qp}`
   }, [job, backendUrl, videoId])
 
+  // ── Step 2 — Preview ─────────────────────────────────────────────────────
+
+  const handlePreview = useCallback(async () => {
+    setPreviewError(null)
+    if (previewing) {
+      try { piperStop() } catch { /* ignore */ }
+      setPreviewing(false)
+      return
+    }
+    if (!piperSupported()) {
+      setPreviewError('Piper requires a secure context (https) with Web Audio + OPFS support.')
+      return
+    }
+    setPreviewing(true)
+    try {
+      await piperSpeak(PREVIEW_TEXT, {
+        voiceId,
+        rate,
+        onEnd: () => setPreviewing(false),
+        onError: (err) => {
+          setPreviewError(String(err?.message || err))
+          setPreviewing(false)
+        },
+      })
+    } catch (err: any) {
+      setPreviewError(String(err?.message || err))
+      setPreviewing(false)
+    }
+  }, [previewing, voiceId, rate])
+
+  // ── Step 3 — Generate all scene narrations ───────────────────────────────
+
+  /** Scenes that need synthesis under the current toggle state.
+   *  Default ("keep existing" off): every scene with narration text.
+   *  Opt-in ("keep existing" on):   only scenes that do NOT already
+   *                                 have an uploaded audioUrl. */
+  const scenesToSynthesize = useMemo(
+    () =>
+      scenes.filter((s) => {
+        const hasText = (s.narration || '').trim().length > 0
+        if (!hasText) return false
+        if (keepExisting && s.audioUrl) return false
+        return true
+      }),
+    [scenes, keepExisting],
+  )
+
+  const handleGenerate = useCallback(async () => {
+    if (!piperSupported()) {
+      setGenError('Piper is not supported in this browser. Use a Chromium-based browser on https.')
+      return
+    }
+    epochRef.current += 1
+    const myEpoch = epochRef.current
+    setStep(3)
+    setGenError(null)
+    setGenIdx(0)
+    setGenTotal(scenesToSynthesize.length)
+
+    if (scenesToSynthesize.length === 0) {
+      // Nothing to synthesize — jump straight to render.
+      setStep(4)
+      void startRender(myEpoch)
+      return
+    }
+
+    for (let i = 0; i < scenesToSynthesize.length; i++) {
+      if (epochRef.current !== myEpoch) return
+      const scene = scenesToSynthesize[i]
+      try {
+        const blob = await synthesizeToBlob(scene.narration, { voiceId })
+        if (epochRef.current !== myEpoch) return
+
+        // Upload to the backend so render_mp4 can mix it in.
+        const fd = new FormData()
+        fd.append('file', blob, `${scene.id}.wav`)
+        const url = `${trimBackend(backendUrl)}/studio/videos/${videoId}/scenes/${scene.id}/narration`
+        const r = await fetch(url, {
+          method: 'POST',
+          headers: { ...authHeaders() },
+          body: fd,
+        })
+        if (epochRef.current !== myEpoch) return
+        if (!r.ok) {
+          const text = await r.text().catch(() => '')
+          throw new Error(text || `Upload failed (HTTP ${r.status})`)
+        }
+      } catch (err: any) {
+        if (epochRef.current !== myEpoch) return
+        setGenError(
+          `Scene ${scene.idx + 1}: ${String(err?.message || err)}`,
+        )
+        return
+      }
+      setGenIdx(i + 1)
+    }
+
+    if (epochRef.current !== myEpoch) return
+    // All done — kick off the render.
+    setStep(4)
+    void startRender(myEpoch)
+  }, [scenesToSynthesize, voiceId, backendUrl, videoId])
+
+  // ── Step 4 — Render + poll ───────────────────────────────────────────────
+
   const pollJob = useCallback(
     async (jobId: string, myEpoch: number) => {
       const url = `${trimBackend(backendUrl)}/studio/videos/${videoId}/export/jobs/${jobId}`
       const start = Date.now()
-      // Polling loop with a hard upper bound.
-      // We bail on epoch mismatch so closing the modal cancels the loop.
       while (Date.now() - start < POLL_TIMEOUT_MS) {
         if (epochRef.current !== myEpoch) return
         try {
@@ -124,8 +304,6 @@ export default function CreatorExportWizard({
         }
         await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS))
       }
-      // Timed out: surface to the user, leave the job alone so they can
-      // re-open the wizard later if it does eventually finish.
       if (epochRef.current === myEpoch) {
         setJob((prev) =>
           prev ? { ...prev, status: 'error', error: 'Render timed out' } : prev,
@@ -135,50 +313,57 @@ export default function CreatorExportWizard({
     [backendUrl, videoId],
   )
 
-  const handleStart = useCallback(async () => {
-    setSubmitError(null)
-    epochRef.current += 1
-    const myEpoch = epochRef.current
-    setStep(2)
-    setJob({ id: '', status: 'queued', progress: 0, kind })
-    try {
-      const r = await fetch(
-        `${trimBackend(backendUrl)}/studio/videos/${videoId}/export/mp4`,
-        {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json', ...authHeaders() },
-          body: JSON.stringify({ kind }),
-        },
-      )
-      if (epochRef.current !== myEpoch) return
-      if (!r.ok) {
-        const text = await r.text().catch(() => '')
-        const detail = text || `HTTP ${r.status}`
-        setSubmitError(detail)
-        setJob({ id: '', status: 'error', progress: 0, error: detail, kind })
-        return
+  const startRender = useCallback(
+    async (myEpoch: number) => {
+      setSubmitError(null)
+      setJob({ id: '', status: 'queued', progress: 0, kind })
+      try {
+        const r = await fetch(
+          `${trimBackend(backendUrl)}/studio/videos/${videoId}/export/mp4`,
+          {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...authHeaders() },
+            body: JSON.stringify({
+              kind,
+              audio_rate: rate,
+              audio_pitch: pitch,
+              subtitles: subtitlesBurnIn ? 'burn_in' : 'none',
+            }),
+          },
+        )
+        if (epochRef.current !== myEpoch) return
+        if (!r.ok) {
+          const text = await r.text().catch(() => '')
+          const detail = text || `HTTP ${r.status}`
+          setSubmitError(detail)
+          setJob({ id: '', status: 'error', progress: 0, error: detail, kind })
+          return
+        }
+        const j = await r.json()
+        if (epochRef.current !== myEpoch) return
+        setJob({
+          id: j.id,
+          status: j.status,
+          progress: typeof j.progress === 'number' ? j.progress : 0,
+          kind: j.kind,
+        })
+        void pollJob(j.id, myEpoch)
+      } catch (err: any) {
+        if (epochRef.current !== myEpoch) return
+        const msg = String(err?.message || err)
+        setSubmitError(msg)
+        setJob({ id: '', status: 'error', progress: 0, error: msg, kind })
       }
-      const j = await r.json()
-      if (epochRef.current !== myEpoch) return
-      setJob({
-        id: j.id,
-        status: j.status,
-        progress: typeof j.progress === 'number' ? j.progress : 0,
-        kind: j.kind,
-      })
-      void pollJob(j.id, myEpoch)
-    } catch (err: any) {
-      if (epochRef.current !== myEpoch) return
-      const msg = String(err?.message || err)
-      setSubmitError(msg)
-      setJob({ id: '', status: 'error', progress: 0, error: msg, kind })
-    }
-  }, [backendUrl, videoId, kind, pollJob])
+    },
+    [backendUrl, videoId, kind, rate, pitch, subtitlesBurnIn, pollJob],
+  )
 
   if (!open) return null
 
   const submitDisabled = Boolean(disabledReason)
 
+  // ── UI ───────────────────────────────────────────────────────────────────
+
   return (
     <div
       className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm p-4"
@@ -188,16 +373,26 @@ export default function CreatorExportWizard({
       aria-label="Export video"
     >
       <div
-        className="w-full max-w-lg rounded-2xl border border-white/10 bg-[#0b0b0c] text-white shadow-2xl"
+        className="w-full max-w-xl rounded-2xl border border-white/10 bg-[#0b0b0c] text-white shadow-2xl max-h-[90vh] overflow-hidden flex flex-col"
         onClick={(e) => e.stopPropagation()}
       >
-        <div className="flex items-center justify-between border-b border-white/10 px-5 py-3">
+        {/* Header */}
+        <div className="flex items-center justify-between border-b border-white/10 px-5 py-3 flex-shrink-0">
           <div>
             <div className="text-sm font-semibold">Export video</div>
             {videoTitle ? (
               <div className="text-xs text-white/50 truncate max-w-[28rem]">{videoTitle}</div>
             ) : null}
           </div>
+          <div className="flex items-center gap-3 text-[11px] text-white/40">
+            <span className={step >= 1 ? 'text-white/80' : ''}>1 · Target</span>
+            <span>›</span>
+            <span className={step >= 2 ? 'text-white/80' : ''}>2 · Voiceover</span>
+            <span>›</span>
+            <span className={step >= 3 ? 'text-white/80' : ''}>3 · Narration</span>
+            <span>›</span>
+            <span className={step >= 4 ? 'text-white/80' : ''}>4 · Render</span>
+          </div>
           <button
             type="button"
             onClick={onClose}
@@ -208,7 +403,8 @@ export default function CreatorExportWizard({
           </button>
         </div>
 
-        <div className="px-5 py-5 space-y-4">
+        {/* Body */}
+        <div className="px-5 py-5 space-y-4 overflow-y-auto">
           {step === 1 && (
             <>
               <div className="text-xs text-white/60">
@@ -282,7 +478,7 @@ export default function CreatorExportWizard({
                 </button>
                 <button
                   type="button"
-                  onClick={handleStart}
+                  onClick={() => setStep(2)}
                   disabled={submitDisabled}
                   className={[
                     'px-3 py-1.5 rounded-lg text-sm font-medium',
@@ -291,13 +487,172 @@ export default function CreatorExportWizard({
                       : 'bg-white text-black hover:bg-white/90',
                   ].join(' ')}
                 >
-                  Render
+                  Next: Voiceover
                 </button>
               </div>
             </>
           )}
 
           {step === 2 && (
+            <>
+              <div className="flex items-center gap-2 text-xs text-white/60">
+                <Mic size={14} className="text-cyan-300" />
+                Piper runs fully in-browser via WebAssembly. First use
+                downloads a voice model (~20 MB, cached).
+              </div>
+
+              <div className="space-y-3">
+                <label className="block text-[11px] uppercase tracking-wide text-white/50">
+                  Piper voice
+                </label>
+                <select
+                  value={voiceId}
+                  onChange={(e) => setVoiceId(e.target.value)}
+                  className="w-full px-3 py-2 rounded-lg bg-white/5 border border-white/10 text-sm text-white/90 focus:outline-none focus:border-white/30"
+                >
+                  {voices.map((v) => (
+                    <option key={v.id} value={v.id}>
+                      {v.name} — {v.lang} · {v.gender} · {v.quality}
+                    </option>
+                  ))}
+                </select>
+              </div>
+
+              <div className="grid grid-cols-2 gap-4">
+                <div>
+                  <div className="flex items-center justify-between text-[11px] uppercase tracking-wide text-white/50">
+                    <span>Rate</span>
+                    <span className="font-mono text-white/70">{rate.toFixed(2)}</span>
+                  </div>
+                  <input
+                    type="range"
+                    min={0.5}
+                    max={2.0}
+                    step={0.05}
+                    value={rate}
+                    onChange={(e) => setRate(Number(e.target.value))}
+                    className="w-full accent-cyan-400"
+                  />
+                </div>
+                <div>
+                  <div className="flex items-center justify-between text-[11px] uppercase tracking-wide text-white/50">
+                    <span>Pitch</span>
+                    <span className="font-mono text-white/70">{pitch.toFixed(2)}</span>
+                  </div>
+                  <input
+                    type="range"
+                    min={0.5}
+                    max={2.0}
+                    step={0.05}
+                    value={pitch}
+                    onChange={(e) => setPitch(Number(e.target.value))}
+                    className="w-full accent-cyan-400"
+                  />
+                </div>
+              </div>
+
+              <div className="flex items-center gap-2">
+                <button
+                  type="button"
+                  onClick={handlePreview}
+                  className="inline-flex items-center gap-2 px-3 py-1.5 rounded-lg text-sm bg-white/10 hover:bg-white/15 border border-white/10"
+                >
+                  {previewing ? <Square size={14} /> : <Play size={14} />}
+                  {previewing ? 'Stop preview' : 'Preview voice'}
+                </button>
+                <span className="text-[11px] text-white/40 truncate">{PREVIEW_TEXT}</span>
+              </div>
+
+              {previewError ? (
+                <div className="text-[11px] text-red-300/80">{previewError}</div>
+              ) : null}
+
+              <label className="flex items-center gap-2 text-sm text-white/80 cursor-pointer">
+                <input
+                  type="checkbox"
+                  checked={subtitlesBurnIn}
+                  onChange={(e) => setSubtitlesBurnIn(e.target.checked)}
+                  className="accent-cyan-400"
+                />
+                Burn subtitles into the video (from scene narration text)
+              </label>
+
+              <label className="flex items-center gap-2 text-sm text-white/80 cursor-pointer">
+                <input
+                  type="checkbox"
+                  checked={keepExisting}
+                  onChange={(e) => setKeepExisting(e.target.checked)}
+                  className="accent-cyan-400"
+                />
+                Keep existing narration audio where present
+                <span className="text-[11px] text-white/40">(skip scenes that already have a take)</span>
+              </label>
+
+              <div className="text-[11px] text-white/40">
+                {scenesToSynthesize.length === 0
+                  ? 'No scenes have narration text — the export will have silent audio.'
+                  : `${scenesToSynthesize.length} of ${scenes.length} scene${scenes.length === 1 ? '' : 's'} will be synthesized with the selected voice.`}
+              </div>
+
+              <div className="flex justify-between gap-2 pt-2">
+                <button
+                  type="button"
+                  onClick={() => setStep(1)}
+                  className="px-3 py-1.5 rounded-lg text-sm text-white/70 hover:bg-white/10"
+                >
+                  Back
+                </button>
+                <button
+                  type="button"
+                  onClick={handleGenerate}
+                  className="px-3 py-1.5 rounded-lg text-sm font-medium bg-white text-black hover:bg-white/90"
+                >
+                  {scenesToSynthesize.length === 0 ? 'Skip & render' : 'Generate narration'}
+                </button>
+              </div>
+            </>
+          )}
+
+          {step === 3 && (
+            <>
+              <div className="flex items-center gap-2 text-white/80">
+                <Loader2 size={16} className="animate-spin" />
+                <span className="text-sm">Synthesizing narration…</span>
+              </div>
+              <div className="h-2 rounded-full bg-white/10 overflow-hidden">
+                <div
+                  className="h-full bg-cyan-400 transition-all"
+                  style={{
+                    width: `${genTotal === 0 ? 0 : Math.round((genIdx / genTotal) * 100)}%`,
+                  }}
+                />
+              </div>
+              <div className="text-[11px] text-white/40 text-center">
+                {genIdx} of {genTotal} scenes
+              </div>
+
+              {genError ? (
+                <div className="space-y-3">
+                  <div className="flex items-start gap-2 rounded-lg border border-red-400/30 bg-red-400/10 p-3 text-[12px] text-red-200">
+                    <AlertTriangle size={14} className="mt-0.5 flex-shrink-0" />
+                    <div>
+                      <div className="font-medium mb-0.5">Narration synthesis failed</div>
+                      <div className="text-red-300/80 break-words">{genError}</div>
+                    </div>
+                  </div>
+                  <button
+                    type="button"
+                    onClick={() => setStep(2)}
+                    className="w-full px-3 py-1.5 rounded-lg text-sm bg-white/10 hover:bg-white/15"
+                  >
+                    Back to voiceover
+                  </button>
+                </div>
+              ) : null}
+            </>
+          )}
+
+          {step === 4 && (
             <>
               {job?.status === 'done' ? (
                 <div className="space-y-4">
@@ -315,6 +670,7 @@ export default function CreatorExportWizard({
                   </a>
                   <div className="text-[11px] text-white/40 text-center">
                     {job.kind === 'mp4_youtube' ? 'YouTube-optimized' : 'Plain MP4'}
+                    {subtitlesBurnIn ? ' · subtitles burned in' : ''}
                   </div>
                 </div>
               ) : job?.status === 'error' ? (
@@ -330,10 +686,10 @@ export default function CreatorExportWizard({
                   </div>
                   <button
                     type="button"
-                    onClick={() => setStep(1)}
+                    onClick={() => setStep(2)}
                     className="w-full px-3 py-1.5 rounded-lg text-sm bg-white/10 hover:bg-white/15"
                   >
-                    Try again
+                    Back to voiceover
                   </button>
                 </div>
               ) : (
@@ -347,7 +703,9 @@ export default function CreatorExportWizard({
                   <div className="h-2 rounded-full bg-white/10 overflow-hidden">
                     <div
                       className="h-full bg-cyan-400 transition-all"
-                      style={{ width: `${Math.max(2, Math.min(100, job?.progress || 0))}%` }}
+                      style={{
+                        width: `${Math.max(2, Math.min(100, job?.progress || 0))}%`,
+                      }}
                     />
                   </div>
                   <div className="text-[11px] text-white/40 text-center">

frontend/src/ui/components/TtsEngineSection.tsx

@@ -0,0 +1,279 @@
+/**
+ * Schema-driven Settings section for the active TTS engine.
+ *
+ * This component is deliberately self-contained so SettingsPanel can mount
+ * it with one line and stay agnostic of which engines are installed.
+ *
+ * Behavior:
+ *   - Dropdown to pick the active engine (only ``isAvailable()`` ones).
+ *   - Below: controls rendered from the active provider's
+ *     ``getSettingsSchema()`` — ``select`` / ``range`` / ``toggle``.
+ *   - The Web Speech provider's ``voiceId`` schema has a placeholder
+ *     options list; we merge in the browser's live voices at render
+ *     time so the user sees their actual installed voices.
+ *   - Every edit persists to the registry's per-user scoped settings
+ *     bucket AND to ``value`` via ``onChangeDraft`` so the existing
+ *     Voice Assistant code continues to read ``value.selectedVoice``.
+ *
+ * Purely additive: the existing System Voice select stays untouched
+ * above this component, and this section only appears when the user
+ * opts into it by picking a non-default engine (or leaves it on
+ * ``web-speech-api`` where we render the same controls the old UI did).
+ */
+
+import React, { useEffect, useMemo, useState } from 'react'
+import {
+  getActiveTtsEngineId,
+  listTtsProviders,
+  onActiveTtsEngineChange,
+  readTtsProviderSettings,
+  setActiveTtsEngine,
+  writeTtsProviderSettings,
+} from '../tts'
+import type { SettingsField, TtsProvider } from '../tts'
+
+interface Props {
+  /** Optional: used by the Web Speech engine to populate its voice
+   *  dropdown with the browser's live voices. Passing undefined is
+   *  safe — we fall back to ``getVoices()``. */
+  systemVoices?: readonly SpeechSynthesisVoice[]
+}
+
+function _fieldValue(schema: SettingsField, saved: Record<string, unknown>): string | number | boolean {
+  const v = saved[schema.key]
+  if (schema.kind === 'range') {
+    return typeof v === 'number' ? v : schema.defaultValue
+  }
+  if (schema.kind === 'toggle') {
+    return typeof v === 'boolean' ? v : schema.defaultValue
+  }
+  return typeof v === 'string' ? v : schema.defaultValue
+}
+
+function _mergeWebSpeechOptions(
+  field: SettingsField,
+  voices: readonly SpeechSynthesisVoice[],
+): SettingsField {
+  if (field.kind !== 'select' || field.key !== 'voiceId' || voices.length === 0) {
+    return field
+  }
+  const live = voices.map((v) => ({
+    value: v.voiceURI || v.name,
+    label: `${v.name} (${v.lang})`,
+  }))
+  return { ...field, options: [...field.options, ...live] }
+}
+
+export default function TtsEngineSection({ systemVoices }: Props): JSX.Element {
+  const [activeId, setActiveIdState] = useState<string>(() => getActiveTtsEngineId())
+  // Re-render when another component swaps the active engine.
+  useEffect(() => onActiveTtsEngineChange((id) => setActiveIdState(id)), [])
+
+  const providers = useMemo<readonly TtsProvider[]>(
+    () => listTtsProviders().filter((p) => p.isAvailable()),
+    [activeId],
+  )
+
+  const active = useMemo<TtsProvider | undefined>(
+    () => providers.find((p) => p.id === activeId),
+    [providers, activeId],
+  )
+
+  // Saved settings blob for the active provider.
+  const [settings, setSettings] = useState<Record<string, unknown>>(
+    () => readTtsProviderSettings(activeId),
+  )
+  useEffect(() => {
+    setSettings(readTtsProviderSettings(activeId))
+  }, [activeId])
+
+  // When the default engine is selected the host panel already renders
+  // a dedicated "Assistant Voice" / "System Voice" dropdown above us
+  // that covers voice + rate + pitch for Web Speech. Rendering our
+  // schema-driven twin on top of it is pure duplication — skip it
+  // unless the user has opted into a non-default engine (Piper etc.).
+  const isDefaultEngine = activeId === 'web-speech-api'
+  const schema = active && !isDefaultEngine ? active.getSettingsSchema() : []
+
+  // Test-voice state: the button speaks through whichever engine is
+  // active right now so the user can hear their pick without leaving
+  // Settings. Mirrors the Preview button in the Creator Studio wizard.
+  const [testing, setTesting] = useState(false)
+  const [testError, setTestError] = useState<string | null>(null)
+  const onTest = () => {
+    setTestError(null)
+    if (!active) return
+    if (testing) {
+      try { active.stop() } catch { /* ignore */ }
+      setTesting(false)
+      return
+    }
+    setTesting(true)
+    const voiceId = typeof settings.voiceId === 'string' ? settings.voiceId : undefined
+    const rate = typeof settings.rate === 'number' ? settings.rate : undefined
+    const pitch = typeof settings.pitch === 'number' ? settings.pitch : undefined
+    active
+      .speak('Hello, this is a preview of your selected voice.', {
+        voiceId,
+        rate,
+        pitch,
+        onEnd: () => setTesting(false),
+        onError: (err) => {
+          setTestError(String(err?.message || err))
+          setTesting(false)
+        },
+      })
+      .catch((err) => {
+        setTestError(String(err?.message || err))
+        setTesting(false)
+      })
+  }
+
+  const onChangeField = (key: string, value: string | number | boolean) => {
+    const next = { ...settings, [key]: value }
+    setSettings(next)
+    writeTtsProviderSettings(activeId, { [key]: value })
+  }
+
+  return (
+    <div className="border-t border-white/5 pt-3">
+      <div className="text-[11px] uppercase tracking-wider text-white/40 mb-2 font-semibold">
+        TTS Engine
+      </div>
+
+      <div className="space-y-3">
+        <div>
+          <label className="block text-[10px] text-white/50 mb-2">Engine</label>
+          <select
+            className="w-full bg-black border border-white/10 rounded-lg px-3 py-2 text-xs text-white"
+            value={activeId}
+            onChange={(e) => setActiveTtsEngine(e.target.value)}
+          >
+            {providers.map((p) => (
+              <option key={p.id} value={p.id}>
+                {p.displayName}
+              </option>
+            ))}
+          </select>
+          {active?.id === 'piper-wasm' && (
+            <div className="mt-1 text-[10px] text-white/40 leading-relaxed">
+              Piper runs fully in-browser via WebAssembly. First use
+              downloads a voice model (~20 MB, cached). Falls back to the
+              HomePilot mirror when the upstream CDN is unreachable.
+            </div>
+          )}
+        </div>
+
+        {active && !isDefaultEngine ? (
+          schema.map((field) => {
+            const resolved =
+              active.id === 'web-speech-api' && field.kind === 'select' && field.key === 'voiceId'
+                ? _mergeWebSpeechOptions(
+                    field,
+                    systemVoices ??
+                      (typeof window !== 'undefined' && 'speechSynthesis' in window
+                        ? window.speechSynthesis.getVoices()
+                        : []),
+                  )
+                : field
+            const value = _fieldValue(resolved, settings)
+
+            if (resolved.kind === 'select') {
+              return (
+                <div key={resolved.key}>
+                  <label className="block text-[10px] text-white/50 mb-2">
+                    {resolved.label}
+                  </label>
+                  <select
+                    className="w-full bg-black border border-white/10 rounded-lg px-3 py-2 text-xs text-white"
+                    value={String(value)}
+                    onChange={(e) => onChangeField(resolved.key, e.target.value)}
+                  >
+                    {resolved.options.map((o) => (
+                      <option key={o.value} value={o.value}>
+                        {o.label}
+                      </option>
+                    ))}
+                  </select>
+                  {resolved.description ? (
+                    <div className="mt-1 text-[10px] text-white/40">{resolved.description}</div>
+                  ) : null}
+                </div>
+              )
+            }
+
+            if (resolved.kind === 'range') {
+              return (
+                <div key={resolved.key}>
+                  <div className="flex items-center justify-between">
+                    <label className="text-[10px] text-white/50">{resolved.label}</label>
+                    <span className="text-[10px] text-white/60 font-mono">
+                      {typeof value === 'number' ? value.toFixed(2) : value}
+                    </span>
+                  </div>
+                  <input
+                    type="range"
+                    min={resolved.min}
+                    max={resolved.max}
+                    step={resolved.step}
+                    value={typeof value === 'number' ? value : resolved.defaultValue}
+                    onChange={(e) => onChangeField(resolved.key, Number(e.target.value))}
+                    className="w-full accent-cyan-400"
+                  />
+                </div>
+              )
+            }
+
+            // toggle
+            return (
+              <label key={resolved.key} className="flex items-center gap-2 cursor-pointer">
+                <input
+                  type="checkbox"
+                  checked={Boolean(value)}
+                  onChange={(e) => onChangeField(resolved.key, e.target.checked)}
+                  className="w-4 h-4 rounded"
+                />
+                <span className="text-xs text-white">{resolved.label}</span>
+              </label>
+            )
+          })
+        ) : !active ? (
+          <div className="text-[10px] text-white/40">
+            No TTS engine available in this environment.
+          </div>
+        ) : null}
+
+        {active && !isDefaultEngine && !active.capabilities.pitch && (
+          <div className="text-[10px] text-white/40 italic">
+            The {active.displayName.split(' (')[0]} engine does not support a pitch control in
+            playback. The Creator Studio export applies pitch post-synthesis via ffmpeg.
+          </div>
+        )}
+
+        {/* Test voice button — positioned AFTER the voice + rate + pitch
+            controls so users pick their voice first, then preview it
+            (best-practice: action sits at the end of the configuration
+            flow). Always visible; mirrors the "Preview voice" affordance
+            in the Creator Studio export wizard. */}
+        {active && (
+          <div className="flex items-center gap-2 pt-1">
+            <button
+              type="button"
+              onClick={onTest}
+              className="text-[11px] px-3 py-1.5 rounded-lg bg-white/10 hover:bg-white/15 border border-white/10 text-white/80"
+              aria-pressed={testing}
+            >
+              {testing ? 'Stop' : 'Test voice'}
+            </button>
+            <span className="text-[10px] text-white/40">
+              Hello, this is a preview of your selected voice.
+            </span>
+          </div>
+        )}
+        {testError ? (
+          <div className="text-[10px] text-red-300/80">{testError}</div>
+        ) : null}
+      </div>
+    </div>
+  )
+}

frontend/src/ui/lib/backendUrl.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { resolveBackendUrl } from './backendUrl'
+
+afterEach(() => {
+  window.localStorage.clear()
+  vi.unstubAllGlobals()
+})
+
+describe('resolveBackendUrl', () => {
+  it('falls back to localhost:8000 when stored backend points to local vite dev port', () => {
+    vi.stubGlobal('location', {
+      hostname: 'localhost',
+      origin: 'http://localhost:3000',
+      port: '3000',
+      protocol: 'http:',
+    })
+
+    window.localStorage.setItem('homepilot_backend_url', 'http://localhost:3000')
+
+    expect(resolveBackendUrl()).toBe('http://localhost:8000')
+  })
+
+  it('keeps stored localhost backend when it targets a non-vite port', () => {
+    vi.stubGlobal('location', {
+      hostname: 'localhost',
+      origin: 'http://localhost:3000',
+      port: '3000',
+      protocol: 'http:',
+    })
+
+    window.localStorage.setItem('homepilot_backend_url', 'http://localhost:8010')
+
+    expect(resolveBackendUrl()).toBe('http://localhost:8010')
+  })
+})

frontend/src/ui/lib/backendUrl.ts

@@ -19,7 +19,12 @@
  */
 
 const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1"]);
-const DEV_VITE_PORTS = new Set(["5173", "5174"]);
+// Vite dev ports used across the repo. The Makefile's `make start` target
+// launches vite with --port 3000; earlier tooling used Vite's defaults
+// 5173/5174. All of them must route API traffic to the backend at :8000
+// rather than to the Vite origin (which would SPA-fallback every request
+// to index.html and break JSON.parse).
+const DEV_VITE_PORTS = new Set(["3000", "5173", "5174"]);
 
 function isLocalHost(hostname: string): boolean {
   return LOCAL_HOSTS.has(hostname);
@@ -70,13 +75,25 @@ export function resolveBackendUrl(override?: string | null): string {
       if (stored && stored.trim()) {
         const clean = stripTrailingSlash(stored.trim());
         const pageIsRemote = !isLocalHost(window.location.hostname);
-        const storedHost = parsedHostname(clean);
+        const storedUrl = (() => { try { return new URL(clean); } catch { return null; } })();
+        const storedHost = storedUrl?.hostname ?? null;
+        const storedPort = storedUrl?.port ?? "";
         const storedIsLocal = storedHost !== null && isLocalHost(storedHost);
         if (pageIsRemote && storedIsLocal) {
           // Stale setting from a previous local dev session. Ignore it and
           // let getDefaultBackendUrl() take over (same origin).
           return getDefaultBackendUrl();
         }
+        // Stale setting pointing at a Vite DEV port on localhost (3000 / 5173
+        // / 5174). The frontend origin serves the SPA — POSTing JSON there
+        // SPA-falls-back to index.html and the caller sees a 404, which the
+        // voice-call path reads as "feature unavailable" and flips to the
+        // chat-REST fallback. Redirect to :8000 (the default backend port)
+        // so the stored preference doesn't silently break voice-call
+        // session creation.
+        if (storedIsLocal && DEV_VITE_PORTS.has(storedPort)) {
+          return "http://localhost:8000";
+        }
         return clean;
       }
     } catch {

frontend/src/ui/phone/PostCallCard.test.tsx

@@ -0,0 +1,156 @@
+/**
+ * Unit tests for PostCallCard.
+ *
+ * Anchored to the variant × missed matrix in § 3 of the handoff.
+ * Each test names the invariant it protects.
+ */
+import React from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+
+import PostCallCard, { postCallCardInternals } from './PostCallCard'
+
+const { formatDuration } = postCallCardInternals
+
+describe('formatDuration', () => {
+  it('renders seconds under a minute', () => {
+    expect(formatDuration(5)).toBe('5s')
+    expect(formatDuration(59)).toBe('59s')
+  })
+  it('rounds to whole minutes when exact', () => {
+    expect(formatDuration(60)).toBe('1 min')
+    expect(formatDuration(720)).toBe('12 min')
+  })
+  it('renders minutes + residual seconds', () => {
+    expect(formatDuration(64)).toBe('1 min 4s')
+  })
+})
+
+describe('PostCallCard — expand variant (default)', () => {
+  it('renders duration + persona name', () => {
+    render(<PostCallCard durationSec={42} personaName="Vesper" />)
+    expect(screen.getByText(/Call with Vesper/i)).toBeInTheDocument()
+    expect(screen.getByText(/42s/)).toBeInTheDocument()
+  })
+
+  it('hides the transcript button when no transcript is supplied', () => {
+    render(<PostCallCard durationSec={42} personaName="Vesper" />)
+    expect(screen.queryByRole('button', { name: /view transcript/i })).not.toBeInTheDocument()
+  })
+
+  it('shows the transcript button when a transcript is supplied', () => {
+    render(
+      <PostCallCard
+        durationSec={42}
+        personaName="Vesper"
+        transcript={[{ who: 'user', text: 'hello' }]}
+      />,
+    )
+    expect(screen.getByRole('button', { name: /view transcript/i })).toBeInTheDocument()
+  })
+
+  it('expands the transcript inline (NOT a modal) when clicked', () => {
+    render(
+      <PostCallCard
+        durationSec={42}
+        personaName="Vesper"
+        transcript={[
+          { who: 'user', text: 'hello' },
+          { who: 'assistant', text: 'hey there' },
+        ]}
+      />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: /view transcript/i }))
+    expect(screen.getByText('hey there')).toBeInTheDocument()
+    // The only role=dialog in the tree would be a modal; assert none.
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('collapses the transcript on a second click', () => {
+    render(
+      <PostCallCard
+        durationSec={42}
+        personaName="Vesper"
+        transcript={[{ who: 'assistant', text: 'hey there' }]}
+      />,
+    )
+    const btn = screen.getByRole('button', { name: /view transcript/i })
+    fireEvent.click(btn)
+    expect(screen.getByText('hey there')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /collapse transcript/i }))
+    expect(screen.queryByText('hey there')).not.toBeInTheDocument()
+  })
+
+  it('fires onResume when Resume call is clicked', () => {
+    const onResume = vi.fn()
+    render(
+      <PostCallCard durationSec={42} personaName="Vesper" onResume={onResume} />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: /resume call/i }))
+    expect(onResume).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('PostCallCard — highlights variant', () => {
+  it('shows the summary line and a "Full transcript" button when handler supplied', () => {
+    const onOpen = vi.fn()
+    render(
+      <PostCallCard
+        durationSec={600}
+        personaName="Vesper"
+        variant="highlights"
+        summary="You talked about Lisbon and made plans for Friday."
+        onOpenFullTranscript={onOpen}
+      />,
+    )
+    expect(screen.getByText(/Vesper remembers/i)).toBeInTheDocument()
+    expect(
+      screen.getByText(/You talked about Lisbon and made plans for Friday/i),
+    ).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /open full transcript/i }))
+    expect(onOpen).toHaveBeenCalledTimes(1)
+  })
+
+  it('omits the "Full transcript" button when no handler is supplied', () => {
+    render(
+      <PostCallCard
+        durationSec={600}
+        personaName="Vesper"
+        variant="highlights"
+        summary="…"
+      />,
+    )
+    expect(
+      screen.queryByRole('button', { name: /open full transcript/i }),
+    ).not.toBeInTheDocument()
+  })
+})
+
+describe('PostCallCard — missed variant', () => {
+  it('swaps Resume → Call back and omits secondary CTA', () => {
+    const onCallBack = vi.fn()
+    render(
+      <PostCallCard
+        durationSec={0}
+        personaName="Vesper"
+        missed
+        onCallBack={onCallBack}
+      />,
+    )
+    expect(screen.getByText(/Missed call/i)).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /call back/i }))
+    expect(onCallBack).toHaveBeenCalledTimes(1)
+    // No secondary button at all in the missed variant.
+    expect(screen.queryByRole('button', { name: /view transcript/i })).not.toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: /full transcript/i })).not.toBeInTheDocument()
+  })
+
+  it('falls back to onResume when onCallBack is omitted', () => {
+    const onResume = vi.fn()
+    render(
+      <PostCallCard durationSec={0} personaName="Vesper" missed onResume={onResume} />,
+    )
+    fireEvent.click(screen.getByRole('button', { name: /call back/i }))
+    expect(onResume).toHaveBeenCalledTimes(1)
+  })
+})

frontend/src/ui/phone/PostCallCard.tsx

@@ -0,0 +1,384 @@
+/**
+ * PostCallCard — inline "we just talked" record rendered directly
+ * in the chat thread, NOT as a modal. Product direction from the
+ * engineering handoff:
+ *
+ *   "You are building a conversational / companion experience,
+ *    not a compliance tool. → Use inline card + expandable
+ *    transcript."
+ *
+ * Three variants covering the full (variant × missed) matrix from
+ * the handoff's § 3:
+ *
+ *   expand      — default. Duration + time + [Resume call] +
+ *                  [View transcript ▾]. Tapping the latter expands
+ *                  the transcript INLINE inside the same card (no
+ *                  modal). Keeps the call record as an event in
+ *                  the conversation the user can glance at later.
+ *   highlights  — same shell, but the body is a short italic
+ *                  "Vesper remembers…" summary + a [Full transcript]
+ *                  link. For sessions where the call was long and
+ *                  the full transcript is too long to inline.
+ *   missed      — red tint, phone-slash icon, single [Call back]
+ *                  CTA. Set via ``missed`` prop (orthogonal to
+ *                  variant; a missed call is always rendered as the
+ *                  missed variant, others ignored).
+ *
+ * This component replaces the prior enterprise-neutral
+ * CallMemoryCard. The enterprise form (flat surface, \"Voice session
+ * completed\" copy) is preserved as a setting-free default by
+ * passing only durationSec + endedAt; richer props turn on the
+ * conversational surface.
+ */
+
+import React, { useState } from 'react'
+import {
+  IconPhone,
+  IconPhoneMissed,
+  IconSparkle,
+} from './icons'
+import { CALL, POST_CALL } from './tokens'
+
+// ── Props ────────────────────────────────────────────────────────
+
+export type PostCallVariant = 'expand' | 'highlights'
+
+export interface TranscriptLine {
+  who: 'user' | 'assistant'
+  text: string
+}
+
+export interface PostCallCardProps {
+  /** Live-phase duration in seconds. Rendered as "12s" / "1m 4s" /
+   *  "12 min" depending on magnitude. */
+  durationSec: number
+  /** Epoch-ms timestamp of when the call ended. Rendered as
+   *  "8:14 PM" via toLocaleTimeString. */
+  endedAt?: number
+  /** The persona the user was talking to. Drives the body text
+   *  ("Call with Vesper"). Default "Assistant". */
+  personaName?: string
+  /** Variant — see module docstring. */
+  variant?: PostCallVariant
+  /** Missed-call variant — tints red, shows phone-slash icon,
+   *  swaps the CTAs. */
+  missed?: boolean
+  /** Optional transcript. When present AND variant='expand',
+   *  enables the inline expand button. */
+  transcript?: TranscriptLine[]
+  /** Optional short summary for variant='highlights'
+   *  (e.g. "You talked about Lisbon and made plans for Friday"). */
+  summary?: string
+  /** "Resume call" click — re-open the call overlay with
+   *  skipDialing=true. */
+  onResume?: () => void
+  /** "Call back" click on the missed variant. Defaults to the same
+   *  as onResume when omitted. */
+  onCallBack?: () => void
+  /** "Full transcript" click on the highlights variant — typically
+   *  opens a separate route or sheet. Optional; button hides when
+   *  handler isn't provided. */
+  onOpenFullTranscript?: () => void
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function formatDuration(s: number): string {
+  if (s < 60) return `${s}s`
+  const m = Math.floor(s / 60)
+  const r = s % 60
+  if (r === 0) return m < 60 ? `${m} min` : `${Math.floor(m / 60)}h ${m % 60}m`
+  return `${m} min ${r}s`
+}
+
+function formatClock(endedAt: number): string {
+  return new Date(endedAt).toLocaleTimeString(undefined, {
+    hour: 'numeric',
+    minute: '2-digit',
+  })
+}
+
+// ── Component ────────────────────────────────────────────────────
+
+const PostCallCard: React.FC<PostCallCardProps> = ({
+  durationSec,
+  endedAt,
+  personaName = 'Assistant',
+  variant = 'expand',
+  missed = false,
+  transcript,
+  summary,
+  onResume,
+  onCallBack,
+  onOpenFullTranscript,
+}) => {
+  const [expanded, setExpanded] = useState(false)
+  const clock = endedAt ? formatClock(endedAt) : ''
+  const dur = formatDuration(durationSec)
+  const accent = missed ? CALL.danger : CALL.rose
+  const hasTranscript = !!(transcript && transcript.length > 0)
+
+  // Top row — icon, title, sub.
+  const subtitle = missed
+    ? clock
+      ? `${clock} · tap to call back`
+      : 'tap to call back'
+    : clock
+      ? `${dur} · ${clock}`
+      : dur
+
+  const titleText = missed
+    ? `Missed call · ${personaName}`
+    : `Call with ${personaName}`
+
+  return (
+    <div
+      role="note"
+      aria-label={missed ? `Missed call from ${personaName}` : `Call with ${personaName}`}
+      className="hp-fade-in"
+      style={{
+        width: POST_CALL.cardWidth,
+        maxWidth: '100%',
+        borderRadius: POST_CALL.cardRadius,
+        overflow: 'hidden',
+        background: missed
+          ? `linear-gradient(180deg, color-mix(in oklch, ${accent} 12%, transparent) 0%, rgba(245,236,255,0.03) 100%)`
+          : 'linear-gradient(180deg, rgba(245,236,255,0.06) 0%, rgba(245,236,255,0.03) 100%)',
+        border: missed
+          ? `0.5px solid color-mix(in oklch, ${accent} 35%, transparent)`
+          : `0.5px solid ${CALL.line}`,
+        fontFamily: CALL.font,
+        color: CALL.ink,
+      }}
+    >
+      {/* Header row — icon + title + time */}
+      <div
+        style={{
+          padding: POST_CALL.rowPadding,
+          display: 'flex',
+          alignItems: 'center',
+          gap: 10,
+        }}
+      >
+        <div
+          aria-hidden="true"
+          style={{
+            width: POST_CALL.avatarSize,
+            height: POST_CALL.avatarSize,
+            borderRadius: '50%',
+            background: `color-mix(in oklch, ${accent} 20%, transparent)`,
+            border: `0.5px solid color-mix(in oklch, ${accent} 40%, transparent)`,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            color: accent,
+            flexShrink: 0,
+          }}
+        >
+          {missed ? (
+            <IconPhoneMissed size={14} color={accent} />
+          ) : (
+            <IconPhone size={14} color={accent} />
+          )}
+        </div>
+        <div style={{ flex: 1, minWidth: 0 }}>
+          <div
+            style={{
+              fontSize: 13,
+              fontWeight: 600,
+              letterSpacing: -0.1,
+              color: missed ? accent : CALL.ink,
+              whiteSpace: 'nowrap',
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+            }}
+          >
+            {titleText}
+          </div>
+          <div
+            style={{
+              fontSize: 11,
+              color: CALL.dim,
+              fontVariantNumeric: 'tabular-nums',
+            }}
+          >
+            {subtitle}
+          </div>
+        </div>
+      </div>
+
+      {/* Highlights body — italic summary line (only when variant is
+          'highlights' and we're not in the missed state). */}
+      {variant === 'highlights' && !missed && summary ? (
+        <div
+          style={{
+            padding: '4px 14px 12px',
+            fontFamily: CALL.display,
+            fontSize: 15,
+            lineHeight: 1.4,
+            color: 'rgba(245,236,255,0.82)',
+            fontStyle: 'italic',
+          }}
+        >
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: 5,
+              marginBottom: 4,
+              fontFamily: CALL.font,
+              fontStyle: 'normal',
+              fontSize: 9,
+              color: 'oklch(0.80 0.15 340)',
+              letterSpacing: 1.4,
+              textTransform: 'uppercase',
+            }}
+          >
+            <IconSparkle size={9} color="oklch(0.80 0.15 340)" />
+            {personaName} remembers
+          </div>
+          <span>&ldquo;{summary}&rdquo;</span>
+        </div>
+      ) : null}
+
+      {/* Expanded transcript — inline, NOT a modal. Renders only for
+          variant='expand' when the user has clicked the expand button
+          and a transcript was provided. */}
+      {variant === 'expand' && expanded && !missed && hasTranscript ? (
+        <div
+          style={{
+            padding: '2px 14px 12px',
+            borderTop: `0.5px solid ${CALL.line}`,
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 8,
+          }}
+        >
+          <div
+            style={{
+              fontSize: 9,
+              letterSpacing: 1.4,
+              textTransform: 'uppercase',
+              color: 'rgba(245,236,255,0.4)',
+              paddingTop: 10,
+            }}
+          >
+            Transcript
+          </div>
+          {(transcript as TranscriptLine[]).map((line, i) => (
+            <div key={i} style={{ fontSize: 12, lineHeight: 1.45 }}>
+              <span
+                style={{
+                  color:
+                    line.who === 'user'
+                      ? 'oklch(0.80 0.15 50)'
+                      : 'oklch(0.80 0.15 340)',
+                  fontWeight: 600,
+                  marginRight: 6,
+                }}
+              >
+                {line.who === 'user' ? 'You' : personaName}
+              </span>
+              <span style={{ color: 'rgba(245,236,255,0.85)' }}>
+                {line.text}
+              </span>
+            </div>
+          ))}
+        </div>
+      ) : null}
+
+      {/* CTA row */}
+      <div
+        style={{
+          display: 'flex',
+          gap: 6,
+          padding: '8px 10px 10px',
+          borderTop:
+            variant === 'expand' && expanded && !missed && hasTranscript
+              ? 'none'
+              : `0.5px solid ${CALL.line}`,
+        }}
+      >
+        <button
+          type="button"
+          onClick={missed ? (onCallBack ?? onResume) : onResume}
+          disabled={!(missed ? (onCallBack ?? onResume) : onResume)}
+          aria-label={missed ? 'Call back' : 'Resume call'}
+          style={{
+            flex: 1,
+            height: POST_CALL.ctaHeight,
+            borderRadius: POST_CALL.ctaRadius,
+            cursor: 'pointer',
+            background: accent,
+            color: '#0c0810',
+            border: 'none',
+            fontFamily: CALL.font,
+            fontSize: 12,
+            fontWeight: 600,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 6,
+          }}
+        >
+          <IconPhone size={12} color="#0c0810" />
+          {missed ? 'Call back' : 'Resume call'}
+        </button>
+
+        {/* Secondary CTA — only the non-missed variants have one */}
+        {!missed && variant === 'highlights' && onOpenFullTranscript ? (
+          <button
+            type="button"
+            onClick={onOpenFullTranscript}
+            aria-label="Open full transcript"
+            style={{
+              flex: 1,
+              height: POST_CALL.ctaHeight,
+              borderRadius: POST_CALL.ctaRadius,
+              cursor: 'pointer',
+              background: 'rgba(245,236,255,0.06)',
+              color: CALL.ink,
+              border: `0.5px solid ${CALL.line}`,
+              fontFamily: CALL.font,
+              fontSize: 12,
+              fontWeight: 500,
+            }}
+          >
+            Full transcript
+          </button>
+        ) : null}
+
+        {!missed && variant === 'expand' && hasTranscript ? (
+          <button
+            type="button"
+            onClick={() => setExpanded((v) => !v)}
+            aria-expanded={expanded}
+            aria-label={expanded ? 'Collapse transcript' : 'View transcript'}
+            style={{
+              flex: 1,
+              height: POST_CALL.ctaHeight,
+              borderRadius: POST_CALL.ctaRadius,
+              cursor: 'pointer',
+              background: 'rgba(245,236,255,0.06)',
+              color: CALL.ink,
+              border: `0.5px solid ${CALL.line}`,
+              fontFamily: CALL.font,
+              fontSize: 12,
+              fontWeight: 500,
+            }}
+          >
+            {expanded ? 'Collapse ▴' : 'View transcript ▾'}
+          </button>
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+export default PostCallCard
+
+// Test hooks — exposed for unit tests without widening the public API.
+export const postCallCardInternals = {
+  formatDuration,
+  formatClock,
+}

frontend/src/ui/phone/README.md

@@ -0,0 +1,103 @@
+# `ui/phone/` — call surface component library
+
+Status: **partial port** of the design system from the engineering
+handoff (`Phone Call UI.html`). This README tracks what ships today
+and what's queued for follow-up sessions.
+
+## What's here now
+
+```
+phone/
+├── README.md                        this file
+├── tokens.ts                        CALL palette + POST_CALL layout constants
+├── icons.tsx                        shared SVG icon set (mic, phone*, chat, …)
+├── PostCallCard.tsx                 inline chat card, expandable transcript,
+│                                     3 variants (expand / highlights / missed)
+├── PostCallCard.test.tsx            13 tests — variant matrix + keyboard/click
+└── primitives/
+    ├── index.ts                     barrel — single import path
+    ├── useReducedMotion.ts          OS motion-preference subscription
+    ├── useReducedMotion.test.ts     4 tests
+    ├── useFocusTrap.ts              keyboard-focus containment for dialogs
+    ├── useFocusTrap.test.tsx        6 tests
+    ├── ControlBtn.tsx               circular action button
+    ├── ControlBtn.test.tsx          8 tests
+    ├── Waveform.tsx                 rAF-driven audio-level bars
+    ├── Waveform.test.tsx            9 tests
+    ├── Aura.tsx                     seeded-hue persona identity chip
+    ├── Aura.test.tsx                8 tests
+    ├── AmbientAura.tsx              page-scale coloured backdrop glow
+    └── AmbientAura.test.tsx         7 tests
+```
+
+Consumed by:
+
+- `frontend/src/ui/App.tsx` — renders `PostCallCard` inline in the
+  chat stream for every `Msg` that carries a `callMemory` payload.
+  The card is **not** a modal — it sits in the conversation so the
+  user can expand the transcript without a context switch.
+- `primitives/` are additive foundation for the next batch
+  (Waveform, Aura, AmbientAura, CallScreen). No consumers yet;
+  `CallOverlay` still has its own inlined versions of waveform +
+  avatar + control buttons, which the next session extracts.
+
+## What's queued for follow-up sessions
+
+The handoff defines a much larger set of components. They are
+additive, so shipping them one at a time doesn't block the current
+call feature — it's already functional end-to-end with the
+`CallOverlay` + the inline `PostCallCard`.
+
+| File | Status | Notes |
+|---|---|---|
+| `primitives/ControlBtn.tsx` | **Shipped** | 8 tests. CallOverlay still inlines its own; extraction queued behind CallScreen. |
+| `primitives/useReducedMotion.ts` | **Shipped** | 4 tests. Drives the motion gate on Waveform + Aura + AmbientAura. |
+| `primitives/useFocusTrap.ts` | **Shipped** | 6 tests. Consumed by CallScreen + LockScreenIncoming when they land. |
+| `primitives/Waveform.tsx` | **Shipped + extracted** | 9 tests. CallOverlay's inline CallWaveform is gone — `<Waveform mode={waveformModeFromCallState(state)} intensityRef={…} />` takes its place. |
+| `primitives/Aura.tsx` | **Shipped + extracted** | 8 tests. FNV-1a hashed seeded hue + optional photoUrl path. Inner disc of CallOverlay's CallAvatar now delegates to `<Aura />`; the halo + pulse rings stay outside (state-dependent). |
+| `primitives/AmbientAura.tsx` | **Shipped** | 7 tests. Additive — CallOverlay today uses a flat dim+blur backdrop; this primitive is slated for CallScreen's fullscreen composition. |
+| `CallScreen.tsx` | Pending | Fullscreen mobile composition. Desktop uses the existing `CallOverlay` modal. |
+| `CallOverlay.tsx` (refactor) | Pending | Route between fullscreen / modal / PiP based on viewport. Today's `CallOverlay.tsx` is desktop-modal-only. |
+| `TextInCall.tsx` | Pending | Mid-call composer sheet — minimize call to a thin bar, slide composer up, send text over the existing chat REST. |
+| `HangUpTransition.tsx` | Pending | ~1 s "call ended" fade beat before the overlay dismisses. Today the overlay fades inline. |
+| `MutedToast.tsx` | Pending | Brief "you're muted" confirmation pill. Today the muted state is indicated only by the waveform colour. |
+| `LockScreenIncoming.tsx` | Pending | iOS-style full-bleed incoming with slide-to-answer. PWA only. |
+| `PoorConnection.tsx` | Pending | Reconnecting banner when WS has been silent >3 s. Today the socket reconnects silently. |
+
+## Suggested sequencing for the next session
+
+Small commits, one per component file, matching the pattern from
+this session:
+
+1. `primitives/Waveform.tsx` — extract the `rAF`-driven version
+   from `CallOverlay.tsx`, swap `CallOverlay`'s inline copy for
+   the import.
+2. `primitives/Aura.tsx` — extract `CallAvatar`, thread through
+   `CallOverlay` + `PostCallCard` so the avatar identity is
+   consistent across surfaces.
+3. `primitives/ControlBtn.tsx` — same.
+4. `CallScreen.tsx` — fullscreen mobile composition on top of the
+   primitives.
+5. `HangUpTransition.tsx` + `MutedToast.tsx` — small polish
+   additions; each a single new render branch in `CallOverlay`.
+6. `TextInCall.tsx` — biggest piece, needs its own focus session.
+7. `LockScreenIncoming.tsx` — PWA-only, coordinates with service-
+   worker push; scope-separate.
+8. `PoorConnection.tsx` — layer on `callSocket`'s existing silence
+   watchdog.
+
+Keep each batch under ~300 LOC and write a vitest for every
+component (the 13-test PostCallCard file is the template).
+
+## Design reference
+
+The pixel-level source of truth is `Phone Call UI.html` in the
+design project — matches every state and surface. Each TSX file in
+this folder maps 1:1 to a named component in the design canvas.
+
+## Not in scope (anywhere in this folder)
+
+- New backend endpoints
+- Replacing the `voice_call` module
+- Replacing `CallOverlay`'s streaming / barge-in plumbing
+- Group calls / add participant

frontend/src/ui/phone/icons.tsx

@@ -0,0 +1,144 @@
+/**
+ * phone/icons.tsx — shared SVG icon set for the call surface.
+ *
+ * Direct-return functions (no shared base helper) so each export is
+ * trivially tree-shakable and the module's export table stays
+ * predictable under the vitest transform (a helper-based variant
+ * earlier in this branch caused every export to vanish from the
+ * module namespace — the root cause wasn't isolated, but the
+ * direct-return form sidesteps it entirely).
+ *
+ * Stroke weight is 1.6 for mic/chat/speaker/video (secondary
+ * actions) and 1.8 for phone icons + back (primary + nav) to match
+ * the design spec in ``Phone Call UI.html``. Icons inherit
+ * currentColor by default so a parent text colour change cascades
+ * cleanly.
+ */
+
+import React from 'react'
+
+interface IconProps {
+  size?: number
+  color?: string
+  title?: string
+}
+
+type SvgExtras = {
+  role: 'img' | 'presentation'
+  'aria-hidden'?: 'true'
+  'aria-label'?: string
+}
+
+function a11y(title?: string): SvgExtras {
+  return title
+    ? { role: 'img', 'aria-label': title }
+    : { role: 'presentation', 'aria-hidden': 'true' }
+}
+
+// ── Icons ─────────────────────────────────────────────────────────
+
+export const IconMic: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <rect x="9" y="3" width="6" height="12" rx="3" />
+    <path d="M5 11a7 7 0 0 0 14 0M12 18v3" />
+  </svg>
+)
+
+export const IconMicOff: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <path d="M9 9V6a3 3 0 0 1 6 0v5m0 4a3 3 0 0 1-6 0" />
+    <path d="M5 11a7 7 0 0 0 11.5 5.3M19 11a7 7 0 0 1-.4 2.3M12 18v3" />
+    <path d="M3 3l18 18" />
+  </svg>
+)
+
+export const IconPhone: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <path d="M5 4h3l2 5-2.5 1.5a11 11 0 0 0 6 6L15 14l5 2v3a2 2 0 0 1-2 2A16 16 0 0 1 3 6a2 2 0 0 1 2-2z" />
+  </svg>
+)
+
+export const IconPhoneEnd: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <path d="M4 14c5-5 11-5 16 0l-2 2-3-1v-2a9 9 0 0 0-6 0v2l-3 1-2-2z"
+          transform="rotate(135 12 12)" />
+  </svg>
+)
+
+/** Phone with superimposed slash — used by PostCallCard's missed
+ *  variant so the missed state reads differently from a normal
+ *  call event even at thumbnail sizes. */
+export const IconPhoneMissed: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <path d="M22 16.92v3a2 2 0 01-2.18 2 19.79 19.79 0 01-8.63-3.07 19.5 19.5 0 01-6-6 19.79 19.79 0 01-3.07-8.67A2 2 0 014.11 2h3a2 2 0 012 1.72 12.84 12.84 0 00.7 2.81 2 2 0 01-.45 2.11L8.09 9.91a16 16 0 006 6l1.27-1.27a2 2 0 012.11-.45 12.84 12.84 0 002.81.7 2 2 0 011.72 2.03z" />
+    <line x1="23" y1="1" x2="17" y2="7" />
+    <line x1="17" y1="1" x2="23" y2="7" />
+  </svg>
+)
+
+export const IconChat: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <path d="M4 5h16v11H9l-5 4z" />
+    <circle cx="9" cy="10.5" r="0.9" fill={color} stroke="none" />
+    <circle cx="12" cy="10.5" r="0.9" fill={color} stroke="none" />
+    <circle cx="15" cy="10.5" r="0.9" fill={color} stroke="none" />
+  </svg>
+)
+
+export const IconSpeaker: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <path d="M4 9v6h4l5 4V5L8 9H4z" />
+    <path d="M17 8a5 5 0 0 1 0 8M19.5 5.5a8.5 8.5 0 0 1 0 13" />
+  </svg>
+)
+
+export const IconVideo: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <rect x="3" y="6" width="13" height="12" rx="2" />
+    <path d="M16 10l5-3v10l-5-3z" />
+  </svg>
+)
+
+export const IconBack: React.FC<IconProps> = ({ size = 22, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+       stroke={color} strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round"
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <path d="M15 5l-7 7 7 7" />
+  </svg>
+)
+
+/** Small star glyph used by the "persona remembers" label on the
+ *  highlights variant of PostCallCard. Fill-mode render (not stroke)
+ *  reads better at 9–11 px. */
+export const IconSparkle: React.FC<IconProps> = ({ size = 12, color = 'currentColor', title }) => (
+  <svg width={size} height={size} viewBox="0 0 24 24" fill={color}
+       {...a11y(title)}>
+    {title ? <title>{title}</title> : null}
+    <path d="M12 2l1.8 6.2L20 10l-6.2 1.8L12 18l-1.8-6.2L4 10l6.2-1.8z" />
+  </svg>
+)