review classifier: queued review requests survive a restart and are never refused

docs/swarm/review-classifier.md

@@ -118,14 +118,24 @@ the earlier one. A repo whose branch protection also dismisses stale approvals (
 on an older commit even without a re-request.
 
 How many requested reviews run at once is a swarm-wide setting, two by
-default (see [Swarm-level settings](#swarm-level-settings)). Up to eight more
-wait in the controller's memory, a bound that isn't configurable, so a
-controller restart drops them, and nothing gets posted for them. Waiting
-reviews start in no guaranteed order. A request for a PR and head that's
-already running, waiting or re-posting starts nothing, and the head stays
-taken until the controller writes its record. A request with every running place
-and all eight waiting places taken starts no run: the account posts a
-`**No verdict:**` comment saying so.
+default (see [Swarm-level settings](#swarm-level-settings)). The controller
+turns no request away. It puts each one in the `review-requests` work-queue
+stream on the swarm queue, one subject per PR, and the stream keeps one
+message per subject: a newer request for a PR replaces one still waiting.
+The controller takes a request once a run place is free and acks it after
+writing the run's record. While a run goes, the controller tells the queue
+every 20 seconds that the request is still in hand. A request it took and
+never acked, because the controller stopped first, comes back within a
+minute, and the controller that's running then reviews it. A restart
+therefore repeats a run that was going. When it can't queue a request, the
+account posts a `**No verdict:**` comment saying so.
+
+When the controller takes a request, it reads the PR first. It drops a
+request whose head is no longer the PR's head, and posts and records nothing
+for it.
+A request for a PR whose review is still going waits in the queue until that
+review ends, so a PR never has two runs at once. A request that re-posts an
+earlier verdict waits for a run place too, and frees it before it posts.
 
 ## Components
 
@@ -206,7 +216,7 @@ replaces it.
   runtime's own default. On the ACP runtime it applies only where the agent
   offers it
 - `max_concurrent_reviews`: 1 to 8, how many requested reviews run at once.
-  Try-outs don't count toward it. Up to eight more reviews wait for a place
+  Try-outs don't count toward it. The rest wait in the queue for a place
 - `runtime`: `api-key` or `acp` (see [Runtimes](#runtimes))
 - `acp`: the provider the ACP runtime runs on, or `null`. It stays stored
   while the runtime is `api-key`, so switching back and forth needs no
@@ -574,13 +584,12 @@ The route answers **201** with `branch`, `path` (the file written) and
 
 `swarm-controller` records every run when it ends: a try-out when the
 classifier's reply arrives, a requested review once the controller has posted
-its review or the post has failed, and a request turned away because the
-queue was full once its comment is on the forge or the post has failed. The
-controller records a re-posted verdict the same way, with the outcome and answer of
-the run it repeats and that run's id in its `detail`. A review request for a
-head that's already running, waiting or re-posting starts nothing and isn't
-recorded. A run still going isn't
-in the list, and a controller restart drops a run in progress.
+its review or the post has failed, and a request the controller couldn't queue
+once its comment is on the forge or the post has failed. The controller records a
+re-posted verdict the same way, with the outcome and answer of the run it
+repeats and that run's id in its `detail`. A dropped request, whose head the
+PR has moved on from, isn't recorded. A run still going isn't in the list; a
+controller restart stops it, and the queue hands its request back.
 
 The newest 100 runs are one JSON array under the key `recent` in the
 `review-classifier-runs` KV bucket on the swarm queue, which only the
@@ -602,11 +611,12 @@ header. Each run has:
 - `repo` (`owner/name`), `pr`, and `requester`: the swarm UI user who started
   the try-out, or the forge user who requested the review
 - `head_sha`: the commit the run read, absent when the PR wasn't read, as for
-  an unreadable PR or a full queue
+  an unreadable PR or a request the controller couldn't queue
 - `started_unix` and `finished_unix`: a try-out starts at its POST, a review
-  once it has a run place
-- `outcome`: `approved`, `changes-requested`, `no-verdict`, `queue-full` or
-  `post-failed` for a review; `done` or `failed` for a try-out
+  once it has a run place and has read the PR
+- `outcome`: `approved`, `changes-requested`, `no-verdict` or `post-failed`
+  for a review, or `queue-full` on a record written before the request queue;
+  `done` or `failed` for a try-out
 - `detail`: the reason, for every outcome but `approved`,
   `changes-requested` and `done`. For `post-failed` it's the run's own reason,
   when it has one, then why the post failed.