phase: 95_read_truncation_cap

All gates are green. Final verification is complete — no fixes were needed; the phase is fully implemented and passing.

**Phase 95 final verification report**

- Verified all 3 tasks already implemented (task files in `complete/`): read cap + notice + `ToolResultPiece` (task 01), `tool_result` SSE + live/saved/shared marker (task 02), E2E suite (task 03).
- Code checks passed: `BOR_READ_MAX_CHARS` (default 128 000, validator), pinned `READ_TRUNCATION_NOTICE` + `TRUNCATION_MARKER`, byte-identical at/under-cap read, holder `read_truncations` (no `tool_calls` impact), piece order (after `tool`, before next round), `ChatToolResultEvent`, `ToolCall` back-compat fields, `app.js` live/restore handlers, `shared.js`, `.truncated-note` CSS, `.env.example` entry, mock-LLM echo script.
- **Tests:** `uv run pytest` → 1966 passed; `uv run pytest --cov=app --cov-report=term-missing` → all green, TOTAL **99%** (>90% gate).
- **E2E:** `uv run pytest tests/e2e/test_read_truncation_cap.py -v --no-cov` → **3 passed** (frame order + live marker + LLM notice via echo; save→shared fidelity; short-read control).
- **Regression (isolated):** `test_agent_document_tools` 4 ✓, `test_chat_history` 5 ✓, `test_share_chat` 4 ✓, `test_big_read_progress` 4 ✓, `test_stop_generation` 3 ✓.
- **Lint/types:** `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors, 0 warnings.

**Completion criteria:** ① over-cap read → first-cap-chars + marker + pinned notice — ✓ (unit-pinned: at-cap/cap+1/notice tests); ② user marker live/saved/shared — ✓ (E2E + frontend tests); ③ at/under cap byte-identical, no frame — ✓ (unit + control E2E); ④ top-2 `<documents>` retrieval untouched — ✓ (`app/rag/retriever.py` unmodified vs HEAD); ⑤ suite green, >90% coverage, ruff+pyright clean — ✓; ⑥ no completed-phase behavior change — ✓ (all gates green; commit left to harness per pass rules).

- No defects found; no changes made this pass. Next pending phase: none in `todo/` (96 is the next free number).

tests/integration/test_chats_api.py

@@ -54,6 +54,9 @@ SHARED_OUT_KEYS = {"title", "messages"}
 
 #: A full ``bor.chat.v1`` brain record (phase 14 shape) — every optional
 #: key present; the round-trip test asserts it survives byte-identical.
+#: Phase 95 (task 02): the CURRENT full tool-entry shape — the additive
+#: truncation fields ride each record (a pre-phase-95 entry WITHOUT them
+#: still validates — the backward-compat pin in test_schemas.py).
 FULL_BRAIN: dict[str, Any] = {
     "who": "brain",
     "text": "Your k3s cluster runs on three nodes — you've got this.",
@@ -64,12 +67,30 @@ FULL_BRAIN: dict[str, Any] = {
     "suggestions": ["What ports does Traefik expose?"],
     "thinking": "The kubernetes doc covers the cluster layout…",
     "tools": [
-        {"name": "read", "argument": "Homelab/kubernetes.md"},
-        {"name": "ls", "argument": None},
+        {
+            "name": "read",
+            "argument": "Homelab/kubernetes.md",
+            "truncated": True,
+            "chars_shown": 128_000,
+            "chars_total": 204_000,
+        },
+        {
+            "name": "ls",
+            "argument": None,
+            "truncated": False,
+            "chars_shown": None,
+            "chars_total": None,
+        },
         # Saved chats persisting the pre-phase-70 tool names still
         # validate — ``name`` is opaque to the API (no migration,
         # locked: old chats render fine).
-        {"name": "read_document", "argument": "Homelab/legacy-notes.md"},
+        {
+            "name": "read_document",
+            "argument": "Homelab/legacy-notes.md",
+            "truncated": False,
+            "chars_shown": None,
+            "chars_total": None,
+        },
     ],
     "stopped": False,
 }