phase: 160_tool_budget_telemetry

All green. Final report:

**Phase 160 completion pass — verified (final verification; all 5 tasks already in `complete/`)**

- **Verified, no code defects found:** budget trailers (`TOOL_BUDGET_REMAINING/LAST/SPENT`), cap-path rejection + `ROUND_CAP_FALLBACK_ANSWER` + `ROUND_CAP_WRAPUP_INSTRUCTION`, `done.budget_exhausted` (ABSENT-when-false), `rounds=/cap_hit=` log fields, `agent_max_rounds=10` default, frontend Continue button + restore + shared-page exclusion, mock markers.
- **Tests/lint:** `uv run pytest` 153/153 green (EXIT 0); `uv run pytest --cov=app --cov-report=term-missing` TOTAL **99%** (>90%); `uv run ruff check .` clean; `uv run pyright` 0 errors/0 warnings.
- **Criteria:** ① decreasing trailer pinned by unit tests (9→…→spent) ✅ ② cap path ends readable, no tool lines after cap (E2E) ✅ ③ `budget_exhausted` true-only-on-cap, absent otherwise (integration) ✅ ④ Continue button → one fresh `continue` turn, fresh budget, record intact (E2E) ✅ ⑤ flag survives refresh; shared chat never renders it (`shared.js` has no `budget_exhausted` path) ✅ ⑥ `max_rounds=0` byte-identical single `tools=None` request; default still 10 ✅ ⑦ full suite/coverage/lint green ✅ ⑧ `test_tool_budget_telemetry.py` **7/7** in isolation; all 6 regression E2E suites green in isolation ✅ ⑨ commit + phase move = harness (I make no git history/index changes).
- **Docs:** README.md — fixed: the "Continue researching" button and cap behavior were undocumented (added a Chat-section paragraph + an Agent-tools-section paragraph, incl. the phase-71 recorded-revision note); env-var table, commands, and architecture all verified consistent otherwise. AGENTS.md — verified consistent, no changes needed.
- **Decisions:** no code changes required — phase was fully implemented; only README docs added. No live-infrastructure touched.
- **Next pending phase:** `161_reasoning_bubble`.

tests/integration/test_agent_tools_dates.py

@@ -28,7 +28,7 @@ from sqlalchemy.orm import Session
 from app.config import Settings
 from app.db import SessionLocal
 from app.models import Document, GitSource
-from app.rag.agent import AgentHolder, run_agent
+from app.rag.agent import AgentHolder, _budget_note, run_agent
 from app.rag.llm import LLMClient, RetryPiece, StreamPiece, ToolCallPiece, ToolResultPiece
 
 if TYPE_CHECKING:
@@ -160,7 +160,9 @@ def test_read_result_second_line_is_stored_date(kb, db) -> None:
 
     holder, llm = _run_call(db, "read", {"path": "Alpha/deep/nested/doc.md"})
 
-    content = llm.requests[1][0][3]["content"]
+    # Phase 160 (task 01): the trailer rides the read result — the raw
+    # result is the RAW part (the trailer stripped).
+    content = llm.requests[1][0][3]["content"].removesuffix(_budget_note(9))
     lines = content.splitlines()
     assert lines[0] == "Document Alpha/deep/nested/doc.md:"  # byte-identical header
     assert lines[1] == f"date: {D2_STR}"  # the STORED date (row's UTC date part)
@@ -178,13 +180,13 @@ def test_read_result_date_is_the_row_date_not_a_constant(kb, db) -> None:
     db.commit()
 
     holder_a, llm_a = _run_call(db, "read", {"path": "Alpha/a.md"})
-    assert llm_a.requests[1][0][3]["content"] == (
+    assert llm_a.requests[1][0][3]["content"].startswith(
         f"Document Alpha/a.md:\ndate: {D1_STR}\nA-TEXT"
-    )
+        )
     holder_b, llm_b = _run_call(db, "read", {"path": "Alpha/b.md"})
-    assert llm_b.requests[1][0][3]["content"] == (
+    assert llm_b.requests[1][0][3]["content"].startswith(
         f"Document Alpha/b.md:\ndate: {D3_STR}\nB-TEXT"
-    )
+        )
     # SEC-14-04: short-lived sessions
     assert [d.id for d in holder_a.read_docs] == [a.id]
     assert [d.id for d in holder_b.read_docs] == [b.id]
@@ -207,7 +209,9 @@ def test_ls_drill_file_lines_carry_their_dates(kb, src, db) -> None:
 
     holder, llm = _run_call(db, "ls", {"path": "Homelab"})
 
-    content = llm.requests[1][0][3]["content"]
+    # Phase 160 (task 01): the trailer rides the listing — stripped for
+    # the raw-part pins below.
+    content = llm.requests[1][0][3]["content"].removesuffix(_budget_note(9))
     lines = content.splitlines()
     # The root level: one direct file (readme.md — D1) + the two
     # subfolder lines (date-free) + the date-free header.
@@ -221,7 +225,7 @@ def test_ls_drill_file_lines_carry_their_dates(kb, src, db) -> None:
 
     # Drill into backups: BOTH files list, each with its OWN date.
     holder2, llm2 = _run_call(db, "ls", {"path": "Homelab/backups"})
-    lines2 = llm2.requests[1][0][3]["content"].splitlines()
+    lines2 = llm2.requests[1][0][3]["content"].removesuffix(_budget_note(9)).splitlines()
     assert lines2[0] == "Homelab/backups — 2 documents, 0 folders:"
     assert lines2[2] == (
         f"source: Homelab | path: backups/cron.md | title: Cron | date: {D1_STR}"
@@ -247,7 +251,7 @@ def test_ls_top_level_source_lines_carry_no_date(kb, db) -> None:
 
         holder, llm = _run_call(db, "ls", {})
 
-        content = llm.requests[1][0][3]["content"]
+        content = llm.requests[1][0][3]["content"].removesuffix(_budget_note(9))
         assert content == "1 sources:\n\nHomelab — 1 documents"
         assert "date" not in content
         assert holder.tool_calls == 1