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`.

README.md

@@ -114,6 +114,24 @@ long — trim it and re-ask" (or a mistyped question) is fixed by
 trimming it in the editor instead of retyping it. Earlier bubbles
 never carry the button (last-question-only scope, owner-locked).
 
+**When a long answer spends its research budget** (phase 160): the
+answer's meta row carries a **Continue researching** button (row order
+Tune → Retry → Continue → Save-as-doc; not admin-gated — chat is
+public, so any visitor can keep a long research session going). Each
+tool result tells the model how many tool calls remain; calls
+attempted after the budget is spent are **rejected** (not executed,
+not shown) instead of being dumped into the chat, and the turn ends
+with a final no-tools reply — the model is coached to answer from the
+results it already has and to tell you it can keep going, and a
+deterministic "budget spent" fallback line stands in if that reply
+carries no visible content. Clicking the button sends one plain
+`continue` turn — the budget is per-turn, so the new turn has a whole
+new round budget, and nothing server-side knows or cares that this is
+a continuation (A10, stateless). The button is inert while a turn is
+streaming and single-shot (a stale button is removed when the new
+turn starts); the flag is persisted on the saved record, so the button
+restores on a refresh — but a shared chat never shows it.
+
 ### RAG / Knowledge base (`/sources.html`)
 
 The indexed document list. The *Path* column opens each document in the same
@@ -497,7 +515,18 @@ The model may call tools as many times as needed, bounded by a round cap:
 
 | Env | Default | Meaning |
 |-----|---------|---------|
-| `BOR_AGENT_MAX_ROUNDS` | `10` | hard cap on agent tool rounds per grounded turn (0 = no tools, the kill switch) |
+| `BOR_AGENT_MAX_ROUNDS` | `10` | hard cap on agent tool rounds per grounded turn (0 = no tools, the kill switch); every tool result carries the model's remaining count (phase 160) |
+
+At the cap, further tool calls are **rejected** (never executed, never
+shown) and the turn ends with a final no-tools reply: the model is
+coached to answer from the results it already has and to tell the user
+they can say "continue" to keep researching; a reply with no visible
+content answers with a deterministic "budget spent" fallback line
+instead of an error frame (phase 160, the recorded revision of the
+phase-71 cap-path terminal). The `done` frame carries an additive
+`budget_exhausted` key (ABSENT on every non-cap turn) that drives the
+**Continue researching** button on the answer's meta row — see the
+[Chat (`/`)](#chat--) section.
 
 ---
 
@@ -898,7 +927,7 @@ to `.env` and adjust.
 
 | Env | Default | Meaning |
 |-----|---------|---------|
-| `BOR_AGENT_MAX_ROUNDS` | `10` | Hard cap on agent tool rounds per grounded turn (0 = no tools) |
+| `BOR_AGENT_MAX_ROUNDS` | `10` | Hard cap on agent tool rounds per grounded turn (0 = no tools); every tool result carries the model's remaining count (phase 160) |
 | `BOR_READ_MAX_CHARS` | `128000` | Cap on a `read` tool result (chars); over-cap reads truncate + a notice that teaches the grep → `read(offset, limit)` workflow (phase 95, rewritten phase 131) |
 
 ### Import & sources