[T017-T029] Phase 1 — agent loop + interview core

- agent/loop.py: full turn cycle (already streamed); separate system prompt
from persisted history (no accumulation); create_loop() session factory (T019)
- app/prompts/interview.md: 4 sub-phase question bank + @@RESPONDER directive (T020)
- app/prompt_loader.py: compose system + interview prompts (T021)
- app/responder.py: parse @@RESPONDER -> ResponderSpec, lenient fallback
- app/phases/interview.py: mockup-faithful progress rail, chat bubbles,
thinking indicator, structured responder (choice/country/text), ghost
"Save and continue later"; real per-delta streaming; turn_end sets responder
mode; agent_end advances state (T022-T025)
- app/countries.py: country selector choices from countries.json
- app/design_tokens.py: align CSS var names to mockup (--primary/--bg/--r-md/
--s-md) + shadows/maxw from DESIGN §4/§5; app.py hero updated
- app/app.py: mount interview, auto-start first question via demo.load

Tests (33 pass): responder parse, event contracts (T028), loop isolation,
loop error->ErrorEvent (SC-015); real-model interview flow + 3 distinct
questions (SC-008/014) and progressive streaming via the Gradio handler
(SC-009/010/011).

Co-authored-by: Codex <noreply@openai.com>

agent/loop.py

@@ -153,14 +153,16 @@ class AgentLoop:
         tool_map = self._tool_map(active_tools)
         tool_schemas = [t.to_ollama_schema() for t in active_tools] or None
 
-        # Build the message list: system prompt, prior history, new prompt.
-        messages: list[dict] = []
-        if system_prompt:
-            messages.append({"role": "system", "content": system_prompt})
-        prior = list(getattr(session, "messages", None) or [])
-        messages.extend(prior)
+        # Conversation history excludes the system prompt: the system message is
+        # supplied fresh on every API call, so it must not be persisted into the
+        # history we return (otherwise it would accumulate across turns).
+        history: list[dict] = list(getattr(session, "messages", None) or [])
         if prompt:
-            messages.append({"role": "user", "content": prompt})
+            history.append({"role": "user", "content": prompt})
+
+        def api_messages() -> list[dict]:
+            sys = [{"role": "system", "content": system_prompt}] if system_prompt else []
+            return sys + history
 
         try:
             client = self._client_lazy()
@@ -176,7 +178,7 @@ class AgentLoop:
 
                 think_arg = thinking_level if thinking_level in ("low", "medium", "high") else None
 
-                async for chunk in self._iter_chat(client, messages, tool_schemas, think_arg):
+                async for chunk in self._iter_chat(client, api_messages(), tool_schemas, think_arg):
                     if self.abort_event.is_set():
                         break
                     msg = getattr(chunk, "message", None)
@@ -203,7 +205,7 @@ class AgentLoop:
                                 args = {}
                         serialised_calls.append({"function": {"name": fn.name, "arguments": args}})
                     assistant_message["tool_calls"] = serialised_calls
-                    messages.append(assistant_message)
+                    history.append(assistant_message)
 
                     # Run each requested tool and feed results back to the model.
                     for call in serialised_calls:
@@ -212,7 +214,7 @@ class AgentLoop:
                         yield ToolStartEvent(name=name, args=args)
                         result = await self._execute_tool(name, args, tool_map)
                         yield ToolEndEvent(name=name, result=result)
-                        messages.append(
+                        history.append(
                             {
                                 "role": "tool",
                                 "name": name,
@@ -223,21 +225,35 @@ class AgentLoop:
                     continue
 
                 # No tool calls: this turn produced the final answer.
-                messages.append(assistant_message)
+                history.append(assistant_message)
                 yield TurnEndEvent(message=assistant_message)
 
                 # Honour any steering message queued during the turn.
                 if not self.steering_queue.empty():
                     steer_msg = await self.steering_queue.get()
-                    messages.append({"role": "user", "content": steer_msg})
+                    history.append({"role": "user", "content": steer_msg})
                     continue
 
                 break
 
-            yield AgentEndEvent(messages=messages)
+            yield AgentEndEvent(messages=history)
 
         except Exception as exc:  # noqa: BLE001 — surfaced to UI, never raised through
             yield ErrorEvent(message=f"{type(exc).__name__}: {exc}")
 
 
-__all__ = ["AgentLoop", "AgentTool", "DEFAULT_MODEL_ID"]
+def create_loop(
+    tools: Optional[Iterable[AgentTool]] = None,
+    model_id: Optional[str] = None,
+    host: Optional[str] = None,
+) -> AgentLoop:
+    """Factory: a fresh, isolated AgentLoop for one Gradio session (T019).
+
+    Each session must call this to get its own loop instance — the steering
+    queue and abort flag are per-instance, so concurrent sessions never share
+    mutable state.
+    """
+    return AgentLoop(tools=tools, model_id=model_id, host=host)
+
+
+__all__ = ["AgentLoop", "AgentTool", "DEFAULT_MODEL_ID", "create_loop"]

app/app.py

@@ -24,6 +24,7 @@ import gradio as gr  # noqa: E402
 
 from app.config import load_env  # noqa: E402
 from app.design_tokens import root_css  # noqa: E402
+from app.phases import interview as interview_phase  # noqa: E402
 
 # Load .env (OLLAMA_HOST, MODEL_ID, …) before anything reads the environment.
 load_env()
@@ -39,15 +40,15 @@ FONT_IMPORT = (
 # literal hex/px design values live here.
 COMPONENT_CSS = """
 body, .gradio-container {
-  background: var(--color-background) !important;
-  color: var(--color-text-primary);
+  background: var(--bg) !important;
+  color: var(--text);
   font-family: var(--font-ui);
 }
-.gradio-container { max-width: 780px !important; margin: 0 auto !important; }
+.gradio-container { max-width: var(--maxw) !important; margin: 0 auto !important; }
 
 #refuge-hero {
   text-align: center;
-  padding: var(--space-xxl) var(--space-lg);
+  padding: var(--s-xxl) var(--s-lg);
 }
 #refuge-wordmark {
   font-family: var(--font-display);
@@ -55,40 +56,44 @@ body, .gradio-container {
   font-size: clamp(38px, 6vw, 58px);
   line-height: 1.15;
   letter-spacing: -0.02em;
-  color: var(--color-primary);
-  margin: 0 0 var(--space-md) 0;
+  color: var(--primary);
+  margin: 0 0 var(--s-md) 0;
   text-wrap: balance;
 }
 #refuge-tagline {
   font-family: var(--font-ui);
   font-size: 18px;
   line-height: 1.6;
-  color: var(--color-text-secondary);
-  margin: 0 0 var(--space-xl) 0;
+  color: var(--text-secondary);
+  margin: 0 0 var(--s-xl) 0;
 }
 #refuge-trust {
   display: inline-flex;
   align-items: center;
-  gap: var(--space-sm);
-  padding: var(--space-sm) var(--space-md);
-  border-radius: var(--radius-full);
-  background: var(--color-surface);
-  border: 1px solid var(--color-line);
-  color: var(--color-text-muted);
+  gap: var(--s-sm);
+  padding: var(--s-sm) var(--s-md);
+  border-radius: var(--r-full);
+  background: var(--surface);
+  border: 1px solid var(--line);
+  color: var(--text-muted);
   font-size: 13.5px;
+  box-shadow: var(--shadow-sm);
 }
-#refuge-trust .lock { color: var(--color-primary); }
+#refuge-trust .lock { color: var(--primary); }
 #refuge-footer {
-  margin-top: var(--space-xxl);
-  padding-top: var(--space-lg);
-  border-top: 1px solid var(--color-line);
-  color: var(--color-text-muted);
+  margin-top: var(--s-xxl);
+  padding-top: var(--s-lg);
+  border-top: 1px solid var(--line);
+  color: var(--text-muted);
   font-size: 12px;
   text-align: center;
 }
 """
 
-APP_CSS = FONT_IMPORT + "\n" + root_css() + "\n" + COMPONENT_CSS
+APP_CSS = (
+    FONT_IMPORT + "\n" + root_css() + "\n" + COMPONENT_CSS
+    + "\n" + interview_phase.INTERVIEW_CSS
+)
 
 HERO_HTML = """
 <main id="refuge-hero">
@@ -96,7 +101,6 @@ HERO_HTML = """
   <p id="refuge-tagline">Safe guidance for people on the move</p>
   <span id="refuge-trust"><span class="lock">&#128274;</span>
     This conversation is private. Nothing is stored without your consent.</span>
-  <div id="refuge-footer">Built for the Hugging Face Build Small Hackathon &middot; runs on a small, local model</div>
 </main>
 """
 
@@ -105,6 +109,9 @@ def build_app() -> gr.Blocks:
     # Gradio 6: `css` is passed to launch(), not the Blocks constructor.
     with gr.Blocks(title="Refuge", analytics_enabled=False) as demo:
         gr.HTML(HERO_HTML)
+        iv = interview_phase.build()
+        # Auto-start the interview: stream the agent's first question on load.
+        demo.load(iv.start_fn, inputs=iv.start_inputs, outputs=iv.stream_outputs)
     return demo
 
 

app/countries.py

@@ -0,0 +1,44 @@
+"""app/countries.py — lightweight country list for UI selectors.
+
+Reads names + flags from specs/data/countries.json (the committed fallback) for
+the interview's country selector. The richer per-country asylum data is loaded by
+the country_lookup tool in Phase 3; this is only for the dropdown labels.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+COUNTRIES_JSON = REPO_ROOT / "specs" / "data" / "countries.json"
+
+
+@lru_cache(maxsize=1)
+def country_choices() -> list[str]:
+    """Sorted ``"<flag> <name>"`` labels for every documented country."""
+    data = json.loads(COUNTRIES_JSON.read_text(encoding="utf-8"))
+    labels: list[str] = []
+    for group in ("signatories", "non_signatories"):
+        for entry in data.get(group, {}).values():
+            name = entry.get("name")
+            if not name:
+                continue
+            flag = entry.get("flag", "").strip()
+            labels.append(f"{flag} {name}".strip())
+    return sorted(set(labels), key=lambda s: s.split(" ", 1)[-1])
+
+
+def country_name(label: str) -> str:
+    """Strip the leading flag emoji from a selector label."""
+    if not label:
+        return ""
+    parts = label.split(" ", 1)
+    # If the first token is non-ASCII (a flag), drop it.
+    if len(parts) == 2 and not parts[0].isascii():
+        return parts[1].strip()
+    return label.strip()
+
+
+__all__ = ["country_choices", "country_name", "COUNTRIES_JSON"]

app/design_tokens.py

@@ -1,13 +1,17 @@
 """app/design_tokens.py — single source for DESIGN.md tokens in Python.
 
-DESIGN.md is the canonical design system (CLAUDE.md Design Rule 7). To guarantee
-the Gradio app can never drift from it, both the app's injected ``:root`` CSS
-block and the T010 token validator are derived from this one parser. No hardcoded
-hex values live in the Python UI code (ARCHITECTURE.md §4 theming contract).
-
-The parser reads the YAML frontmatter of DESIGN.md without a YAML dependency —
-it only needs the flat ``colors``, ``typography`` (font families), ``rounded``,
-and ``spacing`` maps, all of which are simple ``key: "value"`` lines.
+DESIGN.md is the canonical design system (CLAUDE.md Design Rule 7) and
+``mockup.html`` is the visual reference. To guarantee the Gradio app matches
+both, this module parses DESIGN.md's YAML frontmatter and emits CSS custom
+properties using the **same variable names as mockup.html** (``--primary``,
+``--bg``, ``--text``, ``--r-md``, ``--s-md`` …). That way the phase CSS can be
+lifted from the mockup verbatim and stay token-faithful.
+
+A few tokens that mockup.html uses live in DESIGN.md prose (§4 Layout, §5
+Elevation) rather than the frontmatter — the shadows and the max reading width.
+Those are declared here as ``PROSE_TOKENS`` with their DESIGN.md source noted.
+
+No hardcoded hex values live in the Python UI code (ARCHITECTURE.md §4).
 """
 
 from __future__ import annotations
@@ -15,35 +19,42 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-# Repo root = two levels up from this file (app/ -> repo).
 REPO_ROOT = Path(__file__).resolve().parent.parent
 DESIGN_MD = REPO_ROOT / "DESIGN.md"
 
-# Sections of the frontmatter we map to CSS custom properties, and the prefix
-# each becomes under :root.
-_SECTION_PREFIX = {
-    "colors": "color",
-    "rounded": "radius",
-    "spacing": "space",
-}
+# DESIGN.md frontmatter sections we lift, and how each key becomes a CSS var.
+# Most keys map to "<prefix><key>"; a few colours are renamed to match the
+# mockup's shorter names (background -> bg, text-primary -> text).
+_COLOR_RENAME = {"background": "bg", "text-primary": "text"}
+_PREFIX = {"rounded": "r-", "spacing": "s-"}
 
-# Within typography we only lift the two font-family declarations to vars.
+# Typography keys lifted as font-family vars.
 _FONT_KEYS = {"font-display", "font-ui"}
 
+# Tokens defined in DESIGN.md prose (not frontmatter) but used by mockup.html.
+#   shadows  -> DESIGN.md §5 Elevation & Depth
+#   maxw     -> DESIGN.md §4 Layout (max content width 780px)
+PROSE_TOKENS: dict[str, str] = {
+    "shadow-sm": "0 1px 2px rgba(13,46,38,.06), 0 1px 1px rgba(13,46,38,.04)",
+    "shadow-md": "0 6px 20px rgba(13,46,38,.08)",
+    "shadow-lg": "0 18px 48px rgba(13,46,38,.12)",
+    "maxw": "780px",
+}
+
 _SECTION_RE = re.compile(r"^([a-z0-9-]+):\s*$")
 _KV_RE = re.compile(r'^\s+([a-z0-9-]+):\s*"(.*?)"')
 
 
 def load_tokens(design_md: Path | None = None) -> dict[str, str]:
-    """Parse DESIGN.md frontmatter into a flat {css-var-name: value} map.
+    """Parse DESIGN.md into a flat {css-var-name: value} map (mockup naming).
 
-    Keys are the full CSS custom property names without the leading ``--``,
-    e.g. ``color-primary``, ``font-display``, ``radius-md``, ``space-lg``.
+    Keys are CSS custom-property names without the leading ``--`` — e.g.
+    ``primary``, ``bg``, ``text``, ``r-md``, ``s-lg``, ``font-display`` — plus
+    the prose-sourced ``shadow-*`` and ``maxw`` tokens.
     """
     path = design_md or DESIGN_MD
     text = path.read_text(encoding="utf-8")
 
-    # Frontmatter is the first block fenced by --- ... ---.
     if text.startswith("---"):
         end = text.find("\n---", 3)
         frontmatter = text[3:end] if end != -1 else text
@@ -66,11 +77,14 @@ def load_tokens(design_md: Path | None = None) -> dict[str, str]:
             continue
         key, value = kv.group(1), kv.group(2)
 
-        if section in _SECTION_PREFIX:
-            tokens[f"{_SECTION_PREFIX[section]}-{key}"] = value
+        if section == "colors":
+            tokens[_COLOR_RENAME.get(key, key)] = value
+        elif section in _PREFIX:
+            tokens[f"{_PREFIX[section]}{key}"] = value
         elif section == "typography" and key in _FONT_KEYS:
             tokens[key] = value
 
+    tokens.update(PROSE_TOKENS)
     return tokens
 
 
@@ -81,4 +95,4 @@ def root_css(design_md: Path | None = None) -> str:
     return ":root {\n" + "\n".join(lines) + "\n}"
 
 
-__all__ = ["load_tokens", "root_css", "DESIGN_MD", "REPO_ROOT"]
+__all__ = ["load_tokens", "root_css", "PROSE_TOKENS", "DESIGN_MD", "REPO_ROOT"]

app/phases/interview.py

@@ -1 +1,359 @@
-# interview.py — see PLAN.md and ARCHITECTURE.md for implementation spec
+"""app/phases/interview.py — Phase 2 structured interview screen (T022-T025).
+
+Renders the interview as in mockup.html #phase-2: a progress rail, agent/user
+chat bubbles, a "Refuge is listening" thinking indicator, and a structured
+responder that switches between Choice pills / Country selector / Free text based
+on the agent's ``@@RESPONDER`` directive. Agent replies stream token-by-token via
+``AgentLoop.run`` (no buffering).
+
+State lives in per-session ``gr.State`` (session, loop, current responder spec),
+so concurrent sessions stay isolated (T019).
+"""
+
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+
+import gradio as gr
+
+from agent.events import AgentEndEvent, ErrorEvent, TextDeltaEvent
+from agent.loop import create_loop
+from app.countries import country_choices, country_name
+from app.prompt_loader import interview_system_prompt
+from app.responder import ResponderSpec, parse, strip_directive
+from app.state.session import SessionState, State
+
+# Order of the progress rail (Intake is "done" once the interview starts).
+RAIL = [
+    ("Intake", State.INTAKE),
+    ("Situation", State.SITUATION),
+    ("History", State.HISTORY),
+    ("Goals", State.GOALS),
+    ("Review", State.REVIEW),
+]
+
+# Internal first-turn instruction — never shown to the person or resent.
+BOOTSTRAP = "Please begin the interview now with your first question."
+
+AGENT_AVATAR = (
+    '<svg width="18" height="18" viewBox="0 0 32 32" aria-hidden="true">'
+    '<path d="M16 7l7 6.5V25h-4.6v-6.2h-4.8V25H9V13.5L16 7z" fill="#fff"/></svg>'
+)
+
+# CSS lifted from mockup.html #phase-2 — variable names already match the
+# injected :root block (app/design_tokens.py).
+INTERVIEW_CSS = """
+#iv-screen { background: var(--surface); border: 1px solid var(--line);
+  border-radius: var(--r-lg); box-shadow: var(--shadow-md); overflow: hidden;
+  max-width: var(--maxw); margin: 0 auto; }
+
+.iv-rail { display:flex; align-items:center; gap:6px; padding:18px clamp(18px,4vw,28px);
+  background:var(--surface-2); border-bottom:1px solid var(--line); flex-wrap:wrap; }
+.iv-pill { display:flex; align-items:center; gap:8px; font-size:13px; color:var(--text-muted); font-weight:500; }
+.iv-pill .dot { width:22px; height:22px; border-radius:var(--r-full); border:1.5px solid var(--line-strong);
+  display:flex; align-items:center; justify-content:center; font-size:11px; font-weight:700;
+  color:var(--text-muted); background:var(--surface); }
+.iv-pill.done .dot { background:var(--primary); border-color:var(--primary); color:#fff; }
+.iv-pill.done { color:var(--text-secondary); }
+.iv-pill.active .dot { background:var(--accent); border-color:var(--accent); color:#fff; box-shadow:0 0 0 4px var(--accent-tint); }
+.iv-pill.active { color:var(--text); font-weight:600; }
+.iv-sep { width:18px; height:1.5px; background:var(--line-strong); flex:0 0 auto; }
+@media(max-width:620px){ .iv-pill span.t{display:none;} .iv-sep{width:10px;} }
+
+.iv-chat { padding:clamp(18px,4vw,30px); display:flex; flex-direction:column; gap:18px; background:var(--surface); }
+.iv-msg { display:flex; gap:12px; max-width:88%; }
+.iv-msg__av { flex:0 0 auto; width:34px; height:34px; border-radius:var(--r-full); background:var(--primary);
+  display:flex; align-items:center; justify-content:center; box-shadow:var(--shadow-sm); }
+.iv-msg__bubble { padding:13px 16px; border-radius:14px; font-size:15px; line-height:1.55; }
+.iv-msg--agent .iv-msg__bubble { background:var(--primary-tint); color:#15302a; border-bottom-left-radius:5px; }
+.iv-msg--user { margin-left:auto; flex-direction:row-reverse; }
+.iv-msg--user .iv-msg__bubble { background:var(--accent-tint); color:#5c3415; border-bottom-right-radius:5px; }
+.iv-msg--user .iv-msg__av { background:var(--accent); }
+.iv-msg--user .iv-msg__av span { color:#fff; font-size:13px; font-weight:600; }
+.iv-msg--current .iv-msg__bubble { background:var(--surface); border:1.5px solid var(--primary-tint-2);
+  box-shadow:var(--shadow-sm); font-weight:500; color:var(--text); }
+
+.iv-thinking { display:inline-flex; align-items:center; gap:9px; font-size:13px; color:var(--text-muted); padding:2px 0 0 46px; }
+.iv-thinking .dots { display:inline-flex; gap:4px; }
+.iv-thinking .dots i { width:6px; height:6px; border-radius:50%; background:var(--primary); opacity:.4; animation:ivblink 1.2s infinite; display:inline-block; }
+.iv-thinking .dots i:nth-child(2){ animation-delay:.2s; }
+.iv-thinking .dots i:nth-child(3){ animation-delay:.4s; }
+@keyframes ivblink { 0%,60%,100%{opacity:.25;transform:translateY(0);} 30%{opacity:1;transform:translateY(-2px);} }
+
+#iv-responder { border-top:1px solid var(--line); background:var(--surface-2); padding:clamp(16px,4vw,24px); }
+#iv-responder .label-row { font-size:12px; letter-spacing:.04em; text-transform:uppercase;
+  color:var(--text-muted); font-weight:600; }
+
+/* Native Gradio controls themed to match the responder */
+#iv-choice .wrap label, #iv-multi .wrap label { border-radius:var(--r-full) !important; }
+#iv-continue button { background:var(--primary) !important; color:var(--on-primary) !important;
+  box-shadow:0 2px 0 var(--primary-deep) !important; border:0 !important; font-weight:600 !important; }
+#iv-continue button:hover { background:var(--primary-deep) !important; }
+#iv-save button { background:transparent !important; color:var(--primary-deep) !important;
+  border:0 !important; box-shadow:none !important; font-weight:600 !important; }
+#iv-save button:hover { background:var(--primary-tint) !important; }
+"""
+
+
+# --------------------------------------------------------------------------
+# Rendering helpers (pure functions → HTML)
+# --------------------------------------------------------------------------
+
+def render_rail(state: State) -> str:
+    pills = []
+    for i, (label, st) in enumerate(RAIL):
+        if i:
+            pills.append('<span class="iv-sep"></span>')
+        if state > st:
+            cls, dot = "iv-pill done", "✓"
+        elif state == st:
+            cls, dot = "iv-pill active", str(i + 1) if i else "✓"
+        else:
+            cls, dot = "iv-pill", str(i + 1)
+        pills.append(
+            f'<div class="{cls}"><span class="dot">{dot}</span>'
+            f'<span class="t">{html.escape(label)}</span></div>'
+        )
+    return f'<div class="iv-rail" aria-label="Interview progress">{"".join(pills)}</div>'
+
+
+def _bubble(role: str, text: str, current: bool = False) -> str:
+    safe = html.escape(text).replace("\n", "<br>")
+    if role == "user":
+        return (
+            '<div class="iv-msg iv-msg--user"><div class="iv-msg__av"><span>You</span></div>'
+            f'<div class="iv-msg__bubble">{safe}</div></div>'
+        )
+    cur = " iv-msg--current" if current else ""
+    return (
+        f'<div class="iv-msg iv-msg--agent{cur}"><div class="iv-msg__av">{AGENT_AVATAR}</div>'
+        f'<div class="iv-msg__bubble">{safe}</div></div>'
+    )
+
+
+def render_chat(messages: list[dict], streaming_text: str | None = None, thinking: bool = False) -> str:
+    """Render the visible conversation. Agent directives are stripped."""
+    rows: list[str] = []
+    visible_msgs = [m for m in messages if m.get("role") in ("user", "assistant")]
+    last_idx = len(visible_msgs) - 1
+    for i, m in enumerate(visible_msgs):
+        role = m["role"]
+        content = m.get("content", "")
+        if role == "assistant":
+            content = strip_directive(content)
+            if not content.strip():
+                continue
+            rows.append(_bubble("agent", content, current=(streaming_text is None and i == last_idx)))
+        else:
+            rows.append(_bubble("user", content))
+    if streaming_text is not None:
+        rows.append(_bubble("agent", strip_directive(streaming_text) or "…", current=True))
+    if thinking:
+        rows.append(
+            '<div class="iv-thinking" aria-live="polite"><span class="dots">'
+            "<i></i><i></i><i></i></span> Refuge is listening</div>"
+        )
+    return f'<div class="iv-chat">{"".join(rows)}</div>'
+
+
+# --------------------------------------------------------------------------
+# State helpers
+# --------------------------------------------------------------------------
+
+def advance_to(session: SessionState, target: "State | str | None") -> None:
+    """Step the state machine forward to ``target`` (never backward).
+
+    ``target`` may be a State or a phase name string (e.g. "SITUATION") as
+    produced by the responder directive.
+    """
+    if target is None:
+        return
+    if isinstance(target, str):
+        try:
+            target = State[target]
+        except KeyError:
+            return
+    while session.state < target:
+        session.advance()
+
+
+def derive_answer(spec: ResponderSpec, radio_v, multi_v, country_v, text_v) -> str:
+    if spec.mode == "choice" and spec.multi:
+        return ", ".join(multi_v) if multi_v else ""
+    if spec.mode == "choice":
+        return radio_v or ""
+    if spec.mode == "country":
+        return country_name(country_v) if country_v else ""
+    return (text_v or "").strip()
+
+
+def responder_updates(spec: ResponderSpec):
+    """gr.update() tuple for (radio, multi, country, text) given the spec."""
+    is_choice_single = spec.mode == "choice" and not spec.multi
+    is_choice_multi = spec.mode == "choice" and spec.multi
+    is_country = spec.mode == "country"
+    is_text = spec.mode == "text"
+    return (
+        gr.update(visible=is_choice_single, choices=spec.options if is_choice_single else [], value=None),
+        gr.update(visible=is_choice_multi, choices=spec.options if is_choice_multi else [], value=[]),
+        gr.update(visible=is_country, value=None),
+        gr.update(
+            visible=is_text,
+            value="",
+            placeholder=spec.placeholder or "Take your time. You can write in any language.",
+        ),
+    )
+
+
+# --------------------------------------------------------------------------
+# UI assembly
+# --------------------------------------------------------------------------
+
+@dataclass
+class InterviewUI:
+    column: gr.Column
+    session: gr.State
+    loop: gr.State
+    spec: gr.State
+    start_fn: callable
+    start_inputs: list
+    stream_outputs: list
+
+
+def build() -> InterviewUI:
+    """Build the interview screen inside the current gr.Blocks context."""
+    session_st = gr.State(None)
+    loop_st = gr.State(None)
+    spec_st = gr.State(ResponderSpec())
+
+    with gr.Column(elem_id="iv-screen") as column:
+        rail = gr.HTML(render_rail(State.SITUATION))
+        chat = gr.HTML(render_chat([], thinking=True))
+
+        with gr.Column(elem_id="iv-responder"):
+            gr.HTML('<div class="label-row">Your answer</div>')
+            radio = gr.Radio(choices=[], label="", visible=False, elem_id="iv-choice")
+            multi = gr.CheckboxGroup(choices=[], label="", visible=False, elem_id="iv-multi")
+            country = gr.Dropdown(
+                choices=country_choices(), label="", visible=False,
+                allow_custom_value=True, filterable=True, elem_id="iv-country",
+            )
+            text = gr.Textbox(
+                label="", lines=3, visible=False, elem_id="iv-text",
+                placeholder="Take your time. You can write in any language.",
+            )
+            with gr.Row():
+                save = gr.Button("⤓ Save and continue later", elem_id="iv-save", scale=1)
+                cont = gr.Button("Continue →", elem_id="iv-continue", scale=1)
+
+    stream_outputs = [chat, rail, radio, multi, country, text, session_st, loop_st, spec_st]
+
+    # -- handlers -------------------------------------------------------
+
+    async def _run_turn(prompt, session, loop):
+        """Shared streaming routine. ``prompt`` is the new user turn, or ""
+        when the user message is already appended to ``session.messages``."""
+        system_prompt = interview_system_prompt()
+        acc = ""
+        final_messages = list(session.messages)
+        async for ev in loop.run(prompt, session, system_prompt=system_prompt):
+            if isinstance(ev, TextDeltaEvent):
+                acc += ev.delta
+                yield render_chat(session.messages, streaming_text=acc), None
+            elif isinstance(ev, AgentEndEvent):
+                final_messages = ev.messages
+            elif isinstance(ev, ErrorEvent):
+                acc += f"\n\n_(Something went wrong: {ev.message})_"
+                yield render_chat(session.messages, streaming_text=acc), None
+
+        session.messages = final_messages
+        _, spec = parse(acc)
+        advance_to(session, spec.phase)
+        yield render_chat(session.messages), spec
+
+    async def start(session, loop):
+        if session is None:
+            session = SessionState()
+            session.transition_to(State.INTAKE)
+            loop = create_loop()
+        # entering the interview shows the thinking indicator immediately
+        yield (
+            render_chat(session.messages, thinking=True), render_rail(session.state),
+            gr.update(visible=False), gr.update(visible=False), gr.update(visible=False),
+            gr.update(visible=False), session, loop, ResponderSpec(),
+        )
+        spec = ResponderSpec()
+        async for chat_html, maybe_spec in _run_turn(BOOTSTRAP, session, loop):
+            if maybe_spec is None:
+                yield (chat_html, render_rail(session.state), *(_NO_CHANGE * 4),
+                       session, loop, gr.update())
+            else:
+                spec = maybe_spec
+        # The bootstrap instruction is internal — never show or resend it.
+        session.messages = [
+            m for m in session.messages
+            if not (m.get("role") == "user" and m.get("content") == BOOTSTRAP)
+        ]
+        r_up = responder_updates(spec)
+        yield (render_chat(session.messages), render_rail(session.state), *r_up,
+               session, loop, spec)
+
+    async def on_continue(radio_v, multi_v, country_v, text_v, session, loop, spec):
+        if session is None:
+            session = SessionState(); session.transition_to(State.INTAKE)
+            loop = create_loop()
+        answer = derive_answer(spec, radio_v, multi_v, country_v, text_v)
+        if not answer:
+            # nothing chosen — leave everything as-is
+            yield (gr.update(), gr.update(), *(_NO_CHANGE * 4), session, loop, spec)
+            return
+        # Append the answer now so it shows during streaming; pass "" to the
+        # loop so it isn't added a second time.
+        session.messages = list(session.messages) + [{"role": "user", "content": answer}]
+        yield (
+            render_chat(session.messages, thinking=True), render_rail(session.state),
+            gr.update(visible=False), gr.update(visible=False), gr.update(visible=False),
+            gr.update(visible=False), session, loop, spec,
+        )
+        new_spec = spec
+        async for chat_html, maybe_spec in _run_turn("", session, loop):
+            if maybe_spec is None:
+                yield (chat_html, render_rail(session.state), *(_NO_CHANGE * 4),
+                       session, loop, gr.update())
+            else:
+                new_spec = maybe_spec
+        r_up = responder_updates(new_spec)
+        yield (render_chat(session.messages), render_rail(session.state), *r_up,
+               session, loop, new_spec)
+
+    cont.click(
+        on_continue,
+        inputs=[radio, multi, country, text, session_st, loop_st, spec_st],
+        outputs=stream_outputs,
+    )
+
+    return InterviewUI(
+        column=column,
+        session=session_st,
+        loop=loop_st,
+        spec=spec_st,
+        start_fn=start,
+        start_inputs=[session_st, loop_st],
+        stream_outputs=stream_outputs,
+    )
+
+
+# A no-op gr.update placeholder used when a yield doesn't touch a control.
+_NO_CHANGE = (gr.update(),)
+
+
+__all__ = [
+    "build",
+    "InterviewUI",
+    "INTERVIEW_CSS",
+    "render_chat",
+    "render_rail",
+    "advance_to",
+    "derive_answer",
+]

app/prompt_loader.py

@@ -0,0 +1,33 @@
+"""app/prompt_loader.py — load and compose the agent's markdown prompts.
+
+Prompts live in app/prompts/*.md. ``system.md`` is always the base persona;
+phase prompts (``interview.md``, ``assessment.md``) are appended for the phase
+the agent is currently driving (T021).
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+PROMPTS_DIR = Path(__file__).resolve().parent / "prompts"
+
+
+@lru_cache(maxsize=None)
+def load_prompt(name: str) -> str:
+    """Read a prompt markdown file by stem (e.g. ``"system"``)."""
+    path = PROMPTS_DIR / f"{name}.md"
+    return path.read_text(encoding="utf-8").strip()
+
+
+def compose(*names: str) -> str:
+    """Join several prompts with blank-line separators, in order."""
+    return "\n\n".join(load_prompt(n) for n in names)
+
+
+def interview_system_prompt() -> str:
+    """Base persona + interview protocol + responder directive spec (T021)."""
+    return compose("system", "interview")
+
+
+__all__ = ["load_prompt", "compose", "interview_system_prompt", "PROMPTS_DIR"]

app/prompts/interview.md

@@ -1 +1,79 @@
-# interview.md — to be written by Codex per PLAN.md
+# Interview protocol
+
+You are now conducting the **structured interview**. Gather what you need to
+assess this person's situation, one question at a time, in their chosen language.
+Be warm and unhurried. Acknowledge what they just said before asking the next
+thing. Never stack two questions in one message.
+
+The interview has four sub-phases, in order. Move forward through them; never go
+back to a sub-phase you have left.
+
+## SITUATION
+- What country are you currently in, and what country are you originally from?
+- What is the primary reason you had to leave your home?
+  (political / ethnic / religious / gender-based / sexual orientation /
+   climate displacement / other)
+- Are you in immediate danger where you are now?
+
+## HISTORY
+- How long ago did you have to leave?
+- Have you applied for asylum or refugee status anywhere before?
+- What identity or travel documents do you still have?
+
+## GOALS
+- Is there a country where you already have family or a community?
+- Do you have a preference for where you would like to seek safety?
+- What languages do you speak?
+
+## REVIEW
+- Briefly summarise back what you have understood, and ask the person to
+  confirm it is correct before you begin your assessment.
+
+---
+
+# Answer controls — REQUIRED machine directive
+
+The interface shows the person a tailored answer control for each question.
+You choose it by ending **every** message with **exactly one** directive line,
+on its own line, in this format:
+
+    @@RESPONDER mode=<choice|country|text>; phase=<SITUATION|HISTORY|GOALS|REVIEW>; multi=<true|false>; options=<A | B | C>; placeholder=<short hint>
+
+Rules:
+- The directive line is the **last line** of your message. Write nothing after it.
+- It is metadata for the interface — the person never sees it. Keep it out of the
+  natural-language part of your message.
+- `mode=choice` → also give `options=` (a `|`-separated list) and `multi=` (true
+  if several can apply, e.g. reasons for leaving; false for yes/no).
+- `mode=country` → for any "which country" question. No options needed.
+- `mode=text` → for open questions; give a short `placeholder=`.
+- `phase=` is the sub-phase this question belongs to. Set it correctly so the
+  progress rail advances. Move it forward only (SITUATION → HISTORY → GOALS →
+  REVIEW).
+
+## Examples
+
+A yes/no question:
+
+    Are you in immediate danger where you are right now?
+    @@RESPONDER mode=choice; phase=SITUATION; multi=false; options=Yes | No
+
+The reason-for-leaving question:
+
+    What is the primary reason you had to leave your home? Take your time.
+    @@RESPONDER mode=choice; phase=SITUATION; multi=true; options=Political | Ethnic | Religious | Gender-based | Sexual orientation | Climate displacement | Other
+
+A country question:
+
+    Which country are you originally from?
+    @@RESPONDER mode=country; phase=SITUATION
+
+An open question:
+
+    What languages do you speak?
+    @@RESPONDER mode=text; phase=GOALS; placeholder=e.g. Amharic, Arabic (basic)
+
+The review step:
+
+    Here is what I've understood so far: … Is this correct?
+    @@RESPONDER mode=choice; phase=REVIEW; multi=false; options=Yes, that's correct | Something needs changing

app/responder.py

@@ -0,0 +1,93 @@
+"""app/responder.py — parse the agent's ``@@RESPONDER`` answer-control directive.
+
+The interview agent ends each message with one machine directive line telling the
+UI which answer control to show (see app/prompts/interview.md). This module
+splits that directive off the visible message and parses it into a
+:class:`ResponderSpec`, so the chat bubble shows only natural language and the
+structured responder switches mode deterministically (SC-011).
+
+Parsing is lenient: a missing or malformed directive falls back to free text,
+so a small model that forgets the directive never breaks the UI.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+DIRECTIVE_RE = re.compile(r"^[ \t]*@@RESPONDER\b(.*)$", re.IGNORECASE | re.MULTILINE)
+
+VALID_MODES = {"choice", "country", "text"}
+VALID_PHASES = {"SITUATION", "HISTORY", "GOALS", "REVIEW"}
+
+
+@dataclass
+class ResponderSpec:
+    mode: str = "text"
+    options: list[str] = field(default_factory=list)
+    multi: bool = False
+    placeholder: str = ""
+    phase: Optional[str] = None
+
+
+def _parse_fields(body: str) -> dict[str, str]:
+    """Parse ``key=value; key=value`` pairs from a directive body."""
+    fields: dict[str, str] = {}
+    for part in body.split(";"):
+        if "=" not in part:
+            continue
+        key, _, value = part.partition("=")
+        key = key.strip().lower()
+        value = value.strip()
+        if key:
+            fields[key] = value
+    return fields
+
+
+def parse(text: str) -> tuple[str, ResponderSpec]:
+    """Split ``text`` into (visible_message, ResponderSpec).
+
+    The visible message is everything before the directive line, trimmed. If no
+    directive is present, the whole text is returned with a free-text spec.
+    """
+    if not text:
+        return "", ResponderSpec(mode="text")
+
+    match = DIRECTIVE_RE.search(text)
+    if not match:
+        return text.strip(), ResponderSpec(mode="text")
+
+    visible = text[: match.start()].rstrip()
+    fields = _parse_fields(match.group(1))
+
+    mode = fields.get("mode", "text").lower()
+    if mode not in VALID_MODES:
+        mode = "text"
+
+    options = [o.strip() for o in fields.get("options", "").split("|") if o.strip()]
+    multi = fields.get("multi", "false").lower() == "true"
+
+    phase = fields.get("phase", "").upper() or None
+    if phase not in VALID_PHASES:
+        phase = None
+
+    # A choice with no options is meaningless — degrade to free text.
+    if mode == "choice" and not options:
+        mode = "text"
+
+    return visible, ResponderSpec(
+        mode=mode,
+        options=options,
+        multi=multi,
+        placeholder=fields.get("placeholder", ""),
+        phase=phase,
+    )
+
+
+def strip_directive(text: str) -> str:
+    """Return just the visible message (drops the directive)."""
+    return parse(text)[0]
+
+
+__all__ = ["ResponderSpec", "parse", "strip_directive", "VALID_PHASES", "VALID_MODES"]

tests/integration/test_interview_flow.py

@@ -1 +1,118 @@
-# test_interview_flow.py — see PLAN.md and ARCHITECTURE.md for implementation spec
+"""tests/integration/test_interview_flow.py — real multi-turn interview (T026).
+
+Uses the real AgentLoop and a real model (whatever MODEL_ID/.env points at —
+gemma4:12b by default) against the configured Ollama host. No mocks, no
+fabricated tool results. Skips cleanly if the model host is unreachable so the
+unit suite can still run offline.
+
+Covers: SC-008 (3 distinct agent questions), SC-014 (state advances within
+SITUATION..REVIEW), and the streaming event ordering contract.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from agent.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    ErrorEvent,
+    TextDeltaEvent,
+    TurnStartEvent,
+)
+from agent.loop import create_loop
+from app.phases.interview import BOOTSTRAP, advance_to
+from app.prompt_loader import interview_system_prompt
+from app.responder import parse
+from app.state.session import SessionState, State
+
+
+def _host_reachable() -> bool:
+    import os
+    import urllib.request
+
+    host = os.getenv("OLLAMA_HOST", "http://127.0.0.1:11434").rstrip("/")
+    try:
+        urllib.request.urlopen(host + "/api/tags", timeout=3)
+        return True
+    except Exception:
+        return False
+
+
+pytestmark = pytest.mark.skipif(
+    not _host_reachable(), reason="Ollama host not reachable; integration test needs a real model"
+)
+
+
+async def _run_turn(loop, session, prompt):
+    """Drive one real turn; return (event_types, agent_text, spec)."""
+    types: list[str] = []
+    acc = ""
+    final = list(session.messages)
+    async for ev in loop.run(prompt, session, system_prompt=interview_system_prompt()):
+        types.append(ev.type)
+        if isinstance(ev, TextDeltaEvent):
+            acc += ev.delta
+        elif isinstance(ev, AgentEndEvent):
+            final = ev.messages
+        elif isinstance(ev, ErrorEvent):
+            raise AssertionError(f"loop raised ErrorEvent: {ev.message}")
+    session.messages = final
+    _, spec = parse(acc)
+    advance_to(session, spec.phase)
+    return types, acc.strip(), spec
+
+
+def _assert_stream_order(types: list[str]):
+    assert types, "no events were produced"
+    assert types[0] == "agent_start", f"first event must be agent_start, got {types[0]}"
+    assert types[-1] == "agent_end", f"last event must be agent_end, got {types[-1]}"
+    assert "turn_start" in types
+    assert types.index("agent_start") < types.index("turn_start")
+    assert "text_delta" in types, "expected streamed text deltas"
+
+
+@pytest.mark.asyncio
+async def test_real_interview_multiturn():
+    session = SessionState()
+    session.transition_to(State.INTAKE)
+    loop = create_loop()
+
+    # Turn 1 — the agent's opening question.
+    t1_types, t1_text, _ = await _run_turn(loop, session, BOOTSTRAP)
+    _assert_stream_order(t1_types)
+    assert len(t1_text) > 0
+    # The bootstrap drove us into the interview proper.
+    assert State.SITUATION <= session.state <= State.REVIEW
+
+    # Turn 2 — the seeded real scenario.
+    t2_types, t2_text, _ = await _run_turn(
+        loop, session, "I am from Ethiopia, and I am currently in Sudan."
+    )
+    _assert_stream_order(t2_types)
+    assert len(t2_text) > 0, "agent must ask a follow-up, not go silent"
+    assert State.SITUATION <= session.state <= State.REVIEW
+
+    # Turn 3 — another answer; agent should keep the interview moving.
+    t3_types, t3_text, _ = await _run_turn(loop, session, "I left for political reasons.")
+    _assert_stream_order(t3_types)
+    assert len(t3_text) > 0
+    assert State.SITUATION <= session.state <= State.REVIEW
+
+    # SC-008: three distinct agent questions.
+    assert t1_text != t2_text != t3_text
+    assert t1_text != t3_text
+
+
+@pytest.mark.asyncio
+async def test_first_event_is_agent_start_quickly():
+    """The loop yields AgentStartEvent before any network call (SC-004 echo)."""
+    loop = create_loop()
+    gen = loop.run(BOOTSTRAP, SessionState(), system_prompt=interview_system_prompt())
+    try:
+        first = await asyncio.wait_for(gen.__anext__(), timeout=3.0)
+    finally:
+        await gen.aclose()
+    assert isinstance(first, AgentStartEvent)

tests/integration/test_interview_handler.py

@@ -0,0 +1,66 @@
+"""tests/integration/test_interview_handler.py — the real Gradio handler streams.
+
+Exercises the exact ``start_fn`` closure the app wires to ``demo.load`` (built
+inside a gr.Blocks context) against the real model. Proves the UI handler emits
+progressive chat updates (SC-009/SC-010: not buffered) and ends by switching the
+structured responder to a concrete mode (SC-011) while advancing state (SC-014).
+"""
+
+from __future__ import annotations
+
+import os
+import urllib.request
+
+import gradio as gr
+import pytest
+
+from app.phases.interview import build
+from app.responder import ResponderSpec
+from app.state.session import State
+
+
+def _host_reachable() -> bool:
+    host = os.getenv("OLLAMA_HOST", "http://127.0.0.1:11434").rstrip("/")
+    try:
+        urllib.request.urlopen(host + "/api/tags", timeout=3)
+        return True
+    except Exception:
+        return False
+
+
+pytestmark = pytest.mark.skipif(
+    not _host_reachable(), reason="Ollama host not reachable; needs a real model"
+)
+
+
+@pytest.mark.asyncio
+async def test_start_handler_streams_progressively():
+    with gr.Blocks():
+        iv = build()
+
+    chat_lengths: list[int] = []
+    last_tuple = None
+    session = None
+    async for out in iv.start_fn(None, None):
+        last_tuple = out
+        chat_html = out[0]
+        # The chat HTML is the first output; track its visible size growth.
+        if isinstance(chat_html, str):
+            chat_lengths.append(len(chat_html))
+        # session is the 7th output (index 6)
+        session = out[6]
+
+    # Progressive streaming: the chat HTML grew across multiple yields rather
+    # than appearing in a single buffered update.
+    growth_steps = sum(1 for a, b in zip(chat_lengths, chat_lengths[1:]) if b > a)
+    assert len(chat_lengths) >= 3, f"expected multiple streamed updates, got {len(chat_lengths)}"
+    assert growth_steps >= 2, "chat did not grow progressively (looks buffered)"
+
+    # State advanced into the interview proper.
+    assert session is not None
+    assert State.SITUATION <= session.state <= State.REVIEW
+
+    # Final responder spec is a concrete, valid mode (mode switching works).
+    spec = last_tuple[8]
+    assert isinstance(spec, ResponderSpec)
+    assert spec.mode in {"choice", "country", "text"}

tests/unit/test_event_parser.py

@@ -1 +1,67 @@
-# test_event_parser.py — see PLAN.md and ARCHITECTURE.md for implementation spec
+"""tests/unit/test_event_parser.py — agent event contracts (T028).
+
+Every AgentEvent dataclass instantiates with the correct ``type`` string and
+carries its payload fields. These are the typed contracts the Gradio phases
+dispatch on, so a drift here breaks streaming.
+"""
+
+from agent.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    ErrorEvent,
+    TextDeltaEvent,
+    ToolEndEvent,
+    ToolStartEvent,
+    TurnEndEvent,
+    TurnStartEvent,
+)
+
+
+def test_marker_events_have_correct_type():
+    assert AgentStartEvent().type == "agent_start"
+    assert TurnStartEvent().type == "turn_start"
+
+
+def test_text_delta_carries_delta():
+    ev = TextDeltaEvent(delta="hello")
+    assert ev.type == "text_delta"
+    assert ev.delta == "hello"
+
+
+def test_tool_start_carries_name_and_args():
+    ev = ToolStartEvent(name="country_lookup", args={"country": "Kenya"})
+    assert ev.type == "tool_start"
+    assert ev.name == "country_lookup"
+    assert ev.args == {"country": "Kenya"}
+
+
+def test_tool_end_carries_result():
+    ev = ToolEndEvent(name="country_lookup", result={"unhcrPresence": True})
+    assert ev.type == "tool_end"
+    assert ev.result["unhcrPresence"] is True
+
+
+def test_turn_end_carries_message():
+    ev = TurnEndEvent(message={"role": "assistant", "content": "hi"})
+    assert ev.type == "turn_end"
+    assert ev.message["role"] == "assistant"
+
+
+def test_agent_end_carries_messages():
+    msgs = [{"role": "user", "content": "x"}]
+    ev = AgentEndEvent(messages=msgs)
+    assert ev.type == "agent_end"
+    assert ev.messages == msgs
+
+
+def test_error_carries_message():
+    ev = ErrorEvent(message="boom")
+    assert ev.type == "error"
+    assert ev.message == "boom"
+
+
+def test_default_factories_are_independent():
+    # Mutable defaults must not be shared between instances.
+    a, b = ToolStartEvent(), ToolStartEvent()
+    a.args["k"] = 1
+    assert b.args == {}

tests/unit/test_loop_errors.py

@@ -0,0 +1,45 @@
+"""tests/unit/test_loop_errors.py — loop error handling (SC-015).
+
+If the LLM client fails, the loop must yield an ``ErrorEvent`` and finish
+gracefully — never raise through the async generator (which in the UI would be a
+silent hang). No real network is used: the client is replaced with a fake.
+"""
+
+import pytest
+
+from agent.events import AgentStartEvent, ErrorEvent
+from agent.loop import AgentLoop
+
+
+class _RaisingClient:
+    async def chat(self, *args, **kwargs):
+        raise RuntimeError("connection refused")
+
+
+class _RaisingMidStreamClient:
+    async def chat(self, *args, **kwargs):
+        async def _gen():
+            raise RuntimeError("stream died")
+            yield  # pragma: no cover - makes this an async generator
+        return _gen()
+
+
+@pytest.mark.asyncio
+async def test_error_before_stream_becomes_error_event():
+    loop = AgentLoop()
+    loop._client = _RaisingClient()  # bypass lazy real client
+    events = [ev async for ev in loop.run("hi", session=None, system_prompt="x")]
+    assert isinstance(events[0], AgentStartEvent)
+    assert isinstance(events[-1], ErrorEvent)
+    assert "connection refused" in events[-1].message
+
+
+@pytest.mark.asyncio
+async def test_error_mid_stream_becomes_error_event():
+    loop = AgentLoop()
+    loop._client = _RaisingMidStreamClient()
+    events = [ev async for ev in loop.run("hi", session=None, system_prompt="x")]
+    types = [e.type for e in events]
+    assert types[0] == "agent_start"
+    assert types[-1] == "error"
+    assert "stream died" in events[-1].message

tests/unit/test_loop_isolation.py

@@ -0,0 +1,39 @@
+"""tests/unit/test_loop_isolation.py — per-session loop isolation (T019).
+
+Each Gradio session gets its own AgentLoop via the factory; their steering
+queues and abort flags must be independent (no shared mutable state).
+"""
+
+from agent.loop import AgentLoop, create_loop
+
+
+def test_factory_returns_distinct_instances():
+    a = create_loop()
+    b = create_loop()
+    assert isinstance(a, AgentLoop) and isinstance(b, AgentLoop)
+    assert a is not b
+
+
+def test_steering_queue_is_per_instance():
+    a = create_loop()
+    b = create_loop()
+    a.steer("a-message")
+    assert a.steering_queue.qsize() == 1
+    assert b.steering_queue.qsize() == 0
+
+
+def test_abort_flag_is_per_instance():
+    a = create_loop()
+    b = create_loop()
+    a.abort()
+    assert a.abort_event.is_set()
+    assert not b.abort_event.is_set()
+
+
+def test_reset_clears_abort_and_steering():
+    a = create_loop()
+    a.steer("x")
+    a.abort()
+    a.reset()
+    assert not a.abort_event.is_set()
+    assert a.steering_queue.empty()

tests/unit/test_responder.py

@@ -0,0 +1,70 @@
+"""tests/unit/test_responder.py — @@RESPONDER directive parsing.
+
+The directive must be split cleanly off the visible message, parsed correctly,
+and degrade safely to free text when missing or malformed.
+"""
+
+from app.responder import ResponderSpec, parse, strip_directive
+
+
+def test_choice_multi_with_options():
+    text = (
+        "What is the primary reason you had to leave?\n"
+        "@@RESPONDER mode=choice; phase=SITUATION; multi=true; "
+        "options=Political | Ethnic | Religious | Other"
+    )
+    visible, spec = parse(text)
+    assert visible == "What is the primary reason you had to leave?"
+    assert "@@RESPONDER" not in visible
+    assert spec.mode == "choice"
+    assert spec.multi is True
+    assert spec.phase == "SITUATION"
+    assert spec.options == ["Political", "Ethnic", "Religious", "Other"]
+
+
+def test_yes_no_choice_single():
+    visible, spec = parse(
+        "Are you in immediate danger?\n@@RESPONDER mode=choice; phase=SITUATION; "
+        "multi=false; options=Yes | No"
+    )
+    assert spec.mode == "choice"
+    assert spec.multi is False
+    assert spec.options == ["Yes", "No"]
+
+
+def test_country_mode():
+    visible, spec = parse("Which country are you from?\n@@RESPONDER mode=country; phase=SITUATION")
+    assert spec.mode == "country"
+    assert spec.phase == "SITUATION"
+    assert spec.options == []
+
+
+def test_text_mode_with_placeholder():
+    _, spec = parse(
+        "What languages do you speak?\n@@RESPONDER mode=text; phase=GOALS; "
+        "placeholder=e.g. Amharic"
+    )
+    assert spec.mode == "text"
+    assert spec.placeholder == "e.g. Amharic"
+    assert spec.phase == "GOALS"
+
+
+def test_missing_directive_defaults_to_text():
+    visible, spec = parse("Just a plain question with no directive.")
+    assert visible == "Just a plain question with no directive."
+    assert spec.mode == "text"
+    assert spec.phase is None
+
+
+def test_choice_without_options_degrades_to_text():
+    _, spec = parse("Hmm?\n@@RESPONDER mode=choice; phase=SITUATION")
+    assert spec.mode == "text"
+
+
+def test_invalid_phase_becomes_none():
+    _, spec = parse("Q?\n@@RESPONDER mode=country; phase=NONSENSE")
+    assert spec.phase is None
+
+
+def test_strip_directive_helper():
+    assert strip_directive("Hello\n@@RESPONDER mode=text; phase=GOALS") == "Hello"