feat(web): a start that waits for the display answers 202 and is delivered in the background

The start route held a request open for up to 45 s while a cold-started
display loaded its plugins; the MQTT bridge (15 s timeout) and browsers
reported a failure for a request that was then delivered.

Now, when no display is listening, the route starts the service if asked
and answers 202 with status "starting" at once. A single worker in the web
process (web_interface/on_demand_dispatch.py) sends the request until the
display acknowledges it or the wait runs out (45 s cold start, 10 s for a
running service without a socket yet). A newer start supersedes the
pending one; a stop cancels it (and succeeds, with cancelled_request_id,
even with no display listening). The outcome is reported by
/display/on-demand/status (source "web": starting, or error with
start-timeout or the socket's reason, until the display publishes
something newer) and by /display/current-status as on_demand_pending.

Callers: the web UI's on-demand modal and "Preview on display" treat
"starting" as taken (an info toast); the MQTT bridge already treats any
non-error 2xx as success (now pinned by a test).

Tests: the dispatcher (ack, retry then ack, start-timeout, other failures,
superseded, an in-flight ack for a superseded start, stop while pending,
a per-start wait, outcome lifetime); the routes (202, status routes while
pending and after a timeout, a later display state replacing the failure,
stop while pending, a new start superseding); a JS suite for app.js.
Mutation check: 20 mutants on the worker, the routes and app.js, 20 killed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/ARCHITECTURE.md

@@ -62,8 +62,10 @@ send the command over the display's control socket and get an ack. That is
 the only way in: the cache-key mailboxes (`display_on_demand_request`,
 `plugin_error_clear_request`) are gone, and a write to either is dropped
 with a warning. When no display is listening yet, the start route starts the
-service (if asked) and sends the request again once the socket is up; any
-other failure is answered as an error. Socket commands and plugins'
+service (if asked) and answers `202`; the web process's dispatcher
+([`on_demand_dispatch.py`](../web_interface/on_demand_dispatch.py)) sends the
+request once the socket is up, and the status routes report the outcome.
+Any other failure is answered as an error. Socket commands and plugins'
 in-process requests end in the same handler, `_handle_on_demand_request()`.
 The socket's handlers only queue; see [IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)
 for the protocol and the permission model.

docs/IPC_CONTROL_SOCKET.md

@@ -472,19 +472,35 @@ request was never sent.
 
 | What happened | Example reasons | On-demand start | On-demand stop | `errors.clear` |
 |---|---|---|---|---|
-| No display listening | `no_socket`, `refused` | service stopped: `400` without `start_service`; with it, start the service and send again once the socket answers (up to 45 s), else `503`. Service running (still starting): send again for up to 10 s, else `503` | `503` ("not running" / "may still be starting"); with `stop_service` the service is stopped and the route succeeds | `503` ("not running"; its errors are the last run's, and the next run starts with none) |
+| No display listening | `no_socket`, `refused` | service stopped: `400` without `start_service`; with it, start the service and answer `202` (`status: "starting"`) at once; the dispatcher sends the request until the display takes it (up to 45 s), else `start-timeout`. Service running (still starting): the same `202`, sent for up to 10 s | `503` ("not running" / "may still be starting"); with `stop_service` the service is stopped and the route succeeds | `503` ("not running"; its errors are the last run's, and the next run starts with none) |
 | A display too old to know the command | `unknown_command`, `unsupported_version` | `503` | `503` | `503`, "restart it" |
 | No socket in this process | `disabled`, `unsupported` (Windows, `LEDMATRIX_CONTROL_SOCKET=off`) | `503` | `503` | `503` |
 | The display had it and failed, turned it away, or never answered | `busy`, `invalid_args`, `internal`, a timeout, a hang-up, `bad_response`, `forbidden` | `503` (`400` for `invalid_args`) | `503` (with `stop_service`: stopped anyway) | `503` |
 
 Every error answer carries `socket_error` (a reason code, or `other`).
-Nothing is written to the cache in any of these cases. The start route's
-waits are bounded (`ON_DEMAND_SOCKET_WAIT_SECONDS`,
-`ON_DEMAND_SOCKET_WAIT_RUNNING_SECONDS` in
-`web_interface/blueprints/api_v3/display.py`): the socket comes up when the
-display's run loop starts, after every plugin has loaded. A client with a
-shorter HTTP timeout (the MQTT bridge's is 15 s) can give up first while
-the route still delivers the request.
+Nothing is written to the cache in any of these cases.
+
+**Waiting for a display that is starting.** The socket comes up when the
+display's run loop starts, after every plugin has loaded, which can take
+longer than a client waits (the MQTT bridge gives up after 15 s). So the
+start route never waits: it answers `202` with `status: "starting"`, and
+hands the request to the web process's one dispatcher
+([`web_interface/on_demand_dispatch.py`](../web_interface/on_demand_dispatch.py)).
+Its worker thread sends the request every 0.5 s while nothing is listening,
+until the display acknowledges it or the wait runs out (45 s after a cold
+start, `START_WAIT_SECONDS`; 10 s for a service that was already running,
+`ON_DEMAND_SOCKET_WAIT_RUNNING_SECONDS`). Any other failure ends it at once.
+One start is pending at a time: a newer start replaces it, and a stop
+cancels it (the stop then succeeds even with no display listening, and
+reports `cancelled_request_id`).
+
+The outcome is reported where clients already look:
+`GET /display/on-demand/status` answers the pending start's state
+(`source: "web"`, `status: "starting"`, or `status: "error"` with `error:
+"start-timeout"` or the socket's reason) until the display publishes
+something newer, and `GET /display/current-status` adds it as
+`on_demand_pending`. Once the display has taken the request its own state
+is reported, as for any start.
 
 Brightness and plugin reload never had a mailbox: without the socket, the
 config watcher applies the saved brightness and a reload becomes the
@@ -676,8 +692,9 @@ device never touches the live display.
    interface no longer writes `display_on_demand_request` or
    `plugin_error_clear_request`, and the display no longer reads them (see
    "Without the socket"). When no display is listening, the start route
-   starts the service if asked and sends the request again once its socket
-   is up; every other failure is an error the route reports. A write to
+   starts the service if asked, answers `202`, and the web process's
+   dispatcher sends the request once the socket is up; every other failure
+   is an error the route reports. A write to
    either key is dropped with a one-time warning naming the writer. The
    display still writes `display_current_state`, `display_on_demand_state`
    and `plugin_runtime_snapshot`: the web interface reads them whenever the

docs/REST_API_REFERENCE.md

@@ -464,7 +464,7 @@ Request a specific plugin to display on-demand.
 - `mode` (string, optional): Display mode name (plugin_id inferred if not provided)
 - `duration` (number, optional): Duration in seconds (0 = until stopped)
 - `pinned` (boolean, optional): Pin display (pause rotation)
-- `start_service` (boolean, optional): Start the display service if it is not running (default: true). A running service is never restarted: it picks the request up within a frame over its control socket. A stopped one is started and sent the request once its socket is up, which can take as long as the display takes to load its plugins (the route waits up to 45 s). When false and the service is stopped, the route returns 400.
+- `start_service` (boolean, optional): Start the display service if it is not running (default: true). A running service is never restarted: it picks the request up within a frame over its control socket. A stopped one is started, and the route answers `202` at once (see below); the request is sent once the display's socket is up, which can take as long as the display takes to load its plugins. When false and the service is stopped, the route returns 400.
 
 **Response**:
 ```json
@@ -490,15 +490,35 @@ applies it within a frame; see [IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)).
 The `"mailbox"` value earlier releases could answer is gone with the
 mailbox: nothing is written to the cache.
 
-When the display did not take the request, the route answers an error with
-`status: "error"` and `data: {request_id, transport: "socket",
-socket_error}` (plus `service` when it started or checked the service):
+**No display listening yet** (`no_socket`, `refused`: the service is
+stopped, or still loading its plugins). With the service stopped and
+`start_service` false, `400`. Otherwise the route starts the service if
+needed and answers at once:
+
+```json
+{
+  "status": "starting",
+  "message": "The display service is starting; ...",
+  "data": {"request_id": "uuid-here", "plugin_id": "football-scoreboard", "mode": "nfl_live",
+           "duration": 45, "pinned": true, "service": {"active": true, "started": true},
+           "transport": "socket", "socket_error": "no_socket",
+           "pending": true, "wait_seconds": 45.0}
+}
+```
+
+with HTTP `202`. The web process sends the request until the display takes
+it, for up to `wait_seconds` (45 after a cold start, 10 when the service was
+already running). Follow it with `GET /api/v3/display/on-demand/status`:
+its `state` is `{status: "starting", source: "web", request_id, ...}` while
+it waits, the display's own state once delivered, or `{status: "error",
+error: "start-timeout"}` (or the socket's reason) if it never was;
+`GET /api/v3/display/current-status` carries the same as
+`on_demand_pending`. A newer start replaces a pending one; a stop cancels it.
+
+Otherwise, when the display did not take the request, the route answers an
+error with `status: "error"` and `data: {request_id, transport: "socket",
+socket_error}`:
 
-- no display listening (`no_socket`, `refused`): with the service stopped
-  and `start_service` false, `400`; otherwise the route waits for the
-  display's socket (45 s after starting the service, 10 s when it was
-  already running and may still be starting) and answers `503` if it never
-  answers;
 - a full queue (`busy`), no answer after the request was sent (`timeout`,
   `closed`), a display older than the command (`unknown_command`), no
   socket in the web process (`disabled`, `unsupported`): `503` at once;
@@ -507,7 +527,9 @@ socket_error}` (plus `service` when it started or checked the service):
 The stop route answers the same errors (`503` when no display is
 listening, with a message saying whether the service is stopped), except
 that with `stop_service: true` it still stops the service and answers
-success, with `socket_error` set.
+success, with `socket_error` set, and that a stop which cancelled a pending
+start succeeds with `cancelled_request_id` even when no display is
+listening.
 
 ### Stop On-Demand Display