phase: 124_image_chips_and_answers

All green. Final report:

**Phase 124 final verification pass — all criteria verified, no defects found (nothing to fix)**
- Verified the implemented phase (all 7 tasks done, changes in working tree): `BOR_ANSWER_IMAGES` toggle, `show_image` tool + refusals + `holder.shown_images`, toggle-gated prompt clause, `answer_image` frame field (None-omitting serializer) + `ChatMessage` persistence, `merge_cited_docs` auto-cite bug fix, answer-figure UI (live/restore/shared/CSS), mock triggers + E2E suite. Also confirmed the bytes route → public change matches the phase-123 shared-chat precedent (task 06 design).
- `uv run pytest --cov=app --cov-report=term-missing` → **2848 passed**, TOTAL **99%** (>90% gate)
- `bash .agents/validate.sh` → **validation OK** (tests + coverage + ruff + pyright)
- `uv run ruff check . && uv run pyright` → clean, 0 errors
- `uv run pytest tests/e2e/test_answer_images.py -v --no-cov` (isolated) → **5/5 passed**
- Mock-inert spot checks: `tests/e2e/test_image_documents.py` 4/4, `tests/e2e/test_agent_document_tools.py` 4/4

**Completion criteria:** ① zero-read suggested-tier image doc chips with figure — verified (unit matrix, integration `test_zero_read_grounded_turn_auto_cites_suggested_image_doc`, E2E bug-fix flows); ② show_image → answer figure below text/above chips, second call refused, persists + restore + shared — verified (unit handler matrix, integration round-trip, E2E feature flow); ③ default-off byte-identical (3 tools, no clause, no key) — verified (unit + integration + E2E toggle-off); ④ full suite green / >90% / lint clean — verified above; ⑤ commit + phase move — harness responsibility (changes left uncommitted in working tree, no live-infrastructure changes made).

**Next pending phase:** none — `todo/` holds only this phase; the pipeline is clear once the harness moves it.

app/api/chat.py

@@ -462,7 +462,14 @@ def plan_turn(
             fts_hits,
             False,
             build_high_prompt(
-                suggested, notes=steering, kb_overview=kb_text, folder_lines=folder_lines
+                suggested,
+                notes=steering,
+                kb_overview=kb_text,
+                folder_lines=folder_lines,
+                # Phase 124 (task 03, LOCKED A5): the grounded HIGH prompt
+                # carries the show_image clause exactly when the
+                # BOR_ANSWER_IMAGES toggle is on (off = byte-identical).
+                show_image=settings.answer_images,
             ),
             suggested,
             related_docs,
@@ -486,6 +493,51 @@ def plan_turn(
     )
 
 
+def merge_cited_docs(
+    read_docs: list[Document],
+    suggested_docs: list[Document],
+    deflected: bool,
+) -> list[Document]:
+    """Compose the citation tier (the done frame's ``sources``, PLAN §9).
+
+    Phase 119 (LOCKED A1): on grounded turns the agent's READ DOCS —
+    deduped by ``(source, path)``, read order; on deflected turns
+    nothing (a weak-hit answer is not a citation). Phase 124 (TODO L3)
+    adds the rule's single documented exception: a suggested-tier
+    IMAGE doc's seed block IS its entire content (content == summary
+    == the vision description, phase 122 task 03) — a ``read`` would
+    add only the marker line, so a real model never performs one and
+    the doc's chip never appeared. "Suggested" is therefore equivalent
+    to "read" for it, and it is auto-cited — in SUGGESTION order AFTER
+    the read docs, deduped against them (an image doc the agent also
+    explicitly read appears once, at its read position). Non-image
+    suggested docs are never auto-cited: the phase-119 read-docs-only
+    rule stays intact for text docs (a zero-read text turn still chips
+    nothing).
+    """
+    if deflected:
+        return []
+    cited: list[Document] = []
+    seen: set[tuple[str, str]] = set()
+    for doc in read_docs:
+        key = (doc.source, doc.path)
+        if key not in seen:
+            seen.add(key)
+            cited.append(doc)
+    # Phase 124 (TODO L3): the suggested-tier IMAGE docs join the
+    # citation tier — "suggested" is equivalent to "read" for them
+    # (their seed block is their entire content), so a zero-read
+    # grounded turn chips them too. Suggestion order, deduped.
+    for doc in suggested_docs:
+        if not doc.is_image:
+            continue
+        key = (doc.source, doc.path)
+        if key not in seen:
+            seen.add(key)
+            cited.append(doc)
+    return cited
+
+
 @router.post("/chat")
 async def chat(
     request: ChatRequest,
@@ -1035,15 +1087,21 @@ async def chat(
                 #    phase-119 cite discipline, A5) — and [] on
                 #    deflected ones (a deflected answer cites nothing;
                 #    the weak hits stay in the durable record).
+                #    Phase 124 (TODO L3) gives that rule its single
+                #    documented exception — the suggested-tier IMAGE
+                #    docs (``merge_cited_docs``, below): a seed block
+                #    IS an image doc's entire content, so "suggested"
+                #    is equivalent to "read" for it and it is
+                #    auto-cited in suggestion order AFTER the read
+                #    docs, deduped (a read image doc stays at its read
+                #    position, once). Text docs keep the read-docs-only
+                #    rule — a zero-read text turn still chips nothing.
                 #    A cancelled turn (the generator closed by the
                 #    consumer) never reaches this step — no query_log row.
-                cited_docs: list[Document] = []
-                cited_seen: set[tuple[str, str]] = set()
-                for doc in holder.read_docs:
-                    key = (doc.source, doc.path)
-                    if key not in cited_seen:
-                        cited_seen.add(key)
-                        cited_docs.append(doc)
+                cited_docs = merge_cited_docs(
+                    holder.read_docs, plan.suggested_docs, plan.deflected
+                )
+                cited_seen = {(d.source, d.path) for d in cited_docs}
                 record_docs: list[Document] = []
                 seen: set[tuple[str, str]] = set()
                 for doc in [*plan.suggested_docs, *plan.related_docs, *holder.read_docs]:
@@ -1124,12 +1182,28 @@ async def chat(
                     for d in plan.related_docs
                     if (d.source, d.path) not in cited_seen
                 ]
+                # Phase 124 (task 04): the answer's first-class image —
+                # the shown document's ref (the LLM's ``show_image``
+                # pick, task 02's ``holder.shown_images``), built by the
+                # SAME shared ref builder (source/path/title +
+                # ``image_url``). ``None`` on every other turn — a
+                # deflected turn runs no agent (``shown_images`` is
+                # always empty) and an image-less grounded turn never
+                # called the tool — and ``None`` is DROPPED on
+                # serialization, so those frames stay byte-identical to
+                # pre-phase (no key, no null).
+                answer_ref = (
+                    source_ref_with_image(holder.shown_images[0])
+                    if holder.shown_images
+                    else None
+                )
                 yield sse_event(
                     ChatDoneEvent(
                         deflected=plan.deflected,
                         sources=cited_refs,
                         related=related_refs,
                         suggestions=plan.suggestions,
+                        answer_image=answer_ref,
                     ).model_dump()
                 )
             finally: