Improve toolbar review layout.

README.md

@@ -811,6 +811,7 @@ The endpoints, all under `/t/<tabId>/api`:
 | `GET repo` | the repository, its refs, the comment counts, and the diff selection on screen |
 | `POST repo/context` | what the page publishes when you change the base ref |
 | `GET diff` | `base`, `uncommitted`, `commit`, `force`, `ignoreWhitespace` |
+| `GET diff/revision` | a digest of what that same selection resolves to now — one hash, so the page can poll it |
 | `GET file` | a file's contents at a ref, for expanding collapsed context |
 | `GET/POST comments` | list, or open a thread |
 | `PATCH/DELETE comments/{id}` | edit or delete one |
@@ -828,6 +829,25 @@ author starts as a draft. An agent has no drafting step — it posts a review it
 has already decided on — so `"author":"claude"` is born submitted: an open thread,
 with no **Submit review** click standing between it and being read.
 
+### The diff never moves under you
+
+An agent editing files while you read is the normal case here, so the pane has to
+have an answer for "the diff you are looking at is no longer the diff". Reloading
+itself is not that answer: it would lose your scroll position, your place in a
+hunk, and whatever you had half-typed into a composer.
+
+So the page asks `GET diff/revision` every few seconds — a hash of the patch plus
+`HEAD`, which is cheap enough to ask for on a timer and catches both an
+uncommitted edit and work being committed out from under the range. When it stops
+matching the revision the diff came with, a banner says so and offers the refresh.
+Dismissing it keeps the diff you are reading and re-arms against what is there
+now, so the *next* change tells you too. Polling stops while the pane is hidden,
+and starts again the moment it comes back.
+
+Comments are the other half, and they work the other way round: those arrive over
+`GET events` and are applied live, because a thread appearing in the rail doesn't
+move anything you were reading.
+
 ### Comments are markdown
 
 A comment body is markdown, rendered where it is read: fenced code (highlighted