phase: 114_embed_question_length

All verification passes complete — the phase was already fully implemented in the working tree, and every gate is green. No defects found; no code changes were needed.

**Final verification pass — Phase 114 (embed question length):**
- Verified truncation: `chat.py:459` embeds `request.message[:settings.embed_question_max_chars]` (default 1200, `BOR_EMBED_QUESTION_MAX_CHARS`, `>0` validator); full question still reaches the LLM prompt/log.
- Verified error mapping: `EmbeddingInputTooLargeError(EmbeddingError)` (byte-identical message) caught **before** `EmbeddingError` → no retry, terminal frame `detail="Question too long — trim it and re-ask."` + reachability-fine hint; `ChatErrorEvent.hint` additive.
- Verified frontend chain: frame `hint` → `err.hint` → `setUiState(error, …, {hint})` → `showErrorBanner(…, {retryable: true})` — hint replaces default `ERROR_HINT`, phase-111 `#banner-retry` button revealed. 4,000-char clamp untouched (A2).
- `uv run pytest tests/unit/test_embed_question_length.py -v --no-cov` → 21 passed
- `uv run pytest tests/e2e/test_embed_question_length.py -v --no-cov` (isolation, DB up) → 1 passed (4,000-char question → done, no banner)
- Regression: `test_llm_retry.py` 4 passed · `test_oneshot_llm_retry.py` 2 passed · `test_chip_sizing_question_cap.py` 6 passed
- `uv run pytest --cov=app --cov-report=term-missing` → 2444 passed, TOTAL **99%** (>90% gate)
- `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors, 0 warnings

**Completion criteria:** (1) 4,000-char question embeds prefix + full prompt ✅ · (2) too-large → accurate frame + hint + Retry button ✅ · (3) reachability failure byte-identical (retries + old copy) ✅ · (4) all gates green ✅ · (5) commit/phase-move → left to the harness per instructions (no `git add`/`commit` run).
**Deviations:** none. **Next pending phase:** `115_doc_draft_discard`.

tests/unit/test_sse_events.py

@@ -56,16 +56,35 @@ def test_multi_line_text_stays_one_frame() -> None:
 
 def test_error_event_model_serializes_exact_frame() -> None:
     """The ``ChatErrorEvent`` model is the wire shape of every server-side
-    failure the UI's state machine (phase 06) must recover from."""
+    failure the UI's state machine (phase 06) must recover from.
+
+    Phase 114: the additive ``hint`` field serializes ``null`` when
+    absent (old clients ignore the field — PLAN §4; the
+    ``ChatDoneEvent.related`` pattern)."""
     frame = sse_event(ChatErrorEvent(detail="boom").model_dump())
-    assert frame == 'data: {"type": "error", "detail": "boom"}\n\n'
-    assert _payload(frame) == {"type": "error", "detail": "boom"}
+    assert frame == 'data: {"type": "error", "detail": "boom", "hint": null}\n\n'
+    assert _payload(frame) == {"type": "error", "detail": "boom", "hint": None}
 
 
-def test_error_event_shape_is_type_and_detail_only() -> None:
+def test_error_event_shape_is_type_detail_and_optional_hint() -> None:
     dumped = ChatErrorEvent(detail="The chat model dropped the connection").model_dump()
-    assert set(dumped.keys()) == {"type", "detail"}
+    assert set(dumped.keys()) == {"type", "detail", "hint"}
     assert dumped["type"] == "error"  # default — call sites never spell it out
+    assert dumped["hint"] is None  # absent hint serializes null, not dropped
+
+
+def test_error_event_hint_serializes_verbatim_when_set() -> None:
+    """Phase 114 (TODO L6): the too-long frame carries the reachability-
+    fine hint — it survives the roundtrip byte-identically (em-dash and
+    all) for the banner to show in place of the default hint."""
+    hint = "The app reached the embedding model fine — only the question length is the problem."
+    dumped = ChatErrorEvent(
+        detail="Question too long — trim it and re-ask.", hint=hint
+    ).model_dump()
+    assert dumped["hint"] == hint
+    payload = _payload(sse_event(dumped))
+    assert payload["hint"] == hint
+    assert payload["detail"] == "Question too long — trim it and re-ask."
 
 
 def test_thinking_frame_serializes_exactly() -> None: