ChuckBuilds · ChuckBuilds · Oct 5, 2026 · Oct 5, 2026 · Oct 5, 2026 · Oct 5, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -19,6 +19,63 @@ accepts both, but the store flags the old spelling as deprecated
 
 ## Unreleased
 
+### Removed: the cache-key mailboxes (control socket stage 5) -- breaking
+
+The control socket (`docs/IPC_CONTROL_SOCKET.md`) is now the only way the
+web interface sends the display a command. The file mailboxes it fell back
+to for one release are gone.
+
+- **`display_on_demand_request` and `plugin_error_clear_request` are no
+  longer written or read.** The display stops polling the on-demand mailbox
+  (`MailboxWatch`, `MAILBOX_POLL_INTERVAL_WITH_SOCKET`,
+  `_consume_on_demand_request` and the persisted
+  `display_on_demand_processed_id` guard are removed), and the error
+  publisher stops reading the clear request. `CacheManager.file_signature`,
+  `src.cache_manager.MailboxWatch`, `src.ipc.client.should_fall_back` and
+  `src.error_aggregator.ERROR_CLEAR_REQUEST_KEY` are removed.
+- **A write to either key is dropped, with one warning per writer.**
+  `CacheManager.save_cache` (and so `set`) refuses `RETIRED_MAILBOX_KEYS`
+  and logs `Ignored a write to the retired '<key>' cache key by plugin
+  '<id>'`, naming the plugin from the call stack or the request. Plugins
+  must use `BasePlugin.request_on_demand()` / `end_on_demand()` (3.8.1).
+  In the official monorepo, birdnet-go, mqtt-notifications, on-air and
+  pomodoro-timer still write the mailbox, but only as their fallback when
+  those methods are missing or answer `None`.
+- **On-demand routes without a listening display.** `POST
+  /api/v3/display/on-demand/start` with no display listening starts the
+  service (when `start_service`, the default) and answers **`202`** with
+  `status: "starting"` at once; a single background worker in the web
+  process (`web_interface/on_demand_dispatch.py`) sends the request until
+  the display acknowledges it, for up to 45 s (10 s for a service that is
+  running but has no socket yet). `GET /display/on-demand/status` reports it
+  (`starting`; still `starting` with `delivered: true` after the display
+  acknowledges it, until the display publishes the state for that
+  `request_id`, now part of its on-demand state, for at most 30 s; then the
+  display's state, or `error` / `start-timeout`), and
+  `/display/current-status` adds `on_demand_pending`. A newer start replaces
+  a pending one and a stop cancels it (`cancelled_request_id`). The web UI
+  and the MQTT bridge treat `202` as taken. With the service stopped and
+  `start_service` false it answers `400`. Every other socket failure (`unknown_command`
+  from an older display, `disabled`/`unsupported`, `busy`, a timeout) is a
+  `503`. `/stop` answers `503` when no display is listening, unless
+  `stop_service` stops the service. `transport` is always `"socket"`; the
+  `"mailbox"` value is gone.
+- **`POST /api/v3/errors/clear` without the socket answers `503`** (with
+  `context.socket_error` and a message saying why) instead of recording a
+  request. `clear_pending` in the error routes is now always `false`;
+  `src.error_aggregator.read_error_report()` returns only the snapshot, and
+  `error_summary_from_report()` / `plugin_health_from_report()` /
+  `request_error_clear()` lose their clear-request arguments.
+- **Kept:** the display still writes `display_current_state`,
+  `display_on_demand_state`, `plugin_runtime_snapshot` and the heartbeat
+  file, because the web interface reads them whenever the socket cannot
+  answer (a stopped or starting display, a web user not yet in the socket's
+  group, Windows), and `display_on_demand_config`, its own record for
+  resuming a session after a restart.
+- **Windows and `LEDMATRIX_CONTROL_SOCKET=off`:** with no socket, the web
+  interface can no longer start or stop on-demand sessions or clear errors
+  on a running display (the mailbox used to carry them).
+
 ## 3.8.2
 
 The display hands freed memory back to the OS (#774), and sports consolidation

diff --git a/docs/ADVANCED_FEATURES.md b/docs/ADVANCED_FEATURES.md
@@ -650,11 +650,10 @@ When nothing is running on demand, `data.state` is
 > above (or the web UI buttons). The API handlers
 > (`start_on_demand_display()` / `stop_on_demand_display()` in
 > `web_interface/blueprints/api_v3/display.py`) send the request over the
-> display's control socket ([IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)).
-> Only when the socket cannot carry it do they write it into the cache
-> manager under the `display_on_demand_request` key, which
-> `DisplayController._poll_on_demand_requests()`
-> (`src/display_controller.py`) picks up. A separate
+> display's control socket ([IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)),
+> the only way in (the `display_on_demand_request` cache-key mailbox is
+> gone). A plugin asks for the screen with `BasePlugin.request_on_demand()`
+> (see [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md)). A separate
 > `display_on_demand_config` key is used by the controller itself
 > during activation (`_activate_on_demand()`) to track what's
 > currently running, and is cleared by `_clear_on_demand()`.
@@ -737,29 +736,12 @@ keys helps troubleshoot stuck states.
 
 ### Cache Keys
 
-**1. display_on_demand_request** (TTL: 1 hour)
-```json
-{
-  "request_id": "uuid-string",
-  "action": "start|stop",
-  "plugin_id": "plugin-name",
-  "mode": "mode-name",
-  "duration": 30.0,
-  "pinned": true,
-  "timestamp": 1234567890.123
-}
-```
-**Purpose:** Communication from web interface to display controller, as the
-fallback when the control socket cannot carry the request (deprecated; it
-will be removed in a later release)
-**When Set:** API endpoint receives a request and the display's control
-socket is unavailable (display stopped, or older than the socket or the
-command); some plugins also write it directly
-**Read:** once a second while the display serves the control socket (0.25 s
-without it), and only when the file changed since the last look
-**Auto-Cleared:** After processing or 1 hour TTL
-
-**2. display_on_demand_config** (No TTL)
+Requests are not cache keys: they go over the control socket. The
+`display_on_demand_request` and `display_on_demand_processed_id` keys of
+earlier releases are no longer written or read; a leftover file is
+harmless and can be deleted.
+
+**1. display_on_demand_config** (No TTL)
 ```json
 {
   "mode": "mode-name",
@@ -771,7 +753,7 @@ without it), and only when the file changed since the last look
 **When Set:** Controller processes start request
 **Auto-Cleared:** When on-demand stops
 
-**3. display_on_demand_state** (Continuously updated)
+**2. display_on_demand_state** (Continuously updated)
 ```json
 {
   "active": true,
@@ -785,31 +767,24 @@ without it), and only when the file changed since the last look
 **When Set:** Every display loop iteration
 **Auto-Cleared:** Never (continuously updated)
 
-**4. display_on_demand_processed_id** (TTL: 1 hour)
-```text
-"uuid-string-of-last-processed-request"
-```
-**Purpose:** Prevents duplicate request processing
-**When Set:** After processing request
-**Auto-Cleared:** After 1 hour TTL
-
 ### When Manual Clearing is Needed
 
 **Scenario 1: Stuck in On-Demand State**
 - Symptom: Display stays on one plugin, won't return to rotation
-- Clear: `config`, `state`, `request`
+- Clear: `config`, `state`
 
 **Scenario 2: Mode Switching Issues**
 - Symptom: Can't change to different plugin
-- Clear: `request`, `processed_id`, `state`
+- Clear: `state`, then restart the display
 
 **Scenario 3: On-Demand Not Activating**
-- Symptom: Button click does nothing
-- Clear: `processed_id`, `request`
+- Symptom: Button click does nothing, or answers an error
+- Check the error's `socket_error` (see [IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md),
+  "Checking it on a device"); no cache key is involved
 
 **Scenario 4: After Service Crash**
 - Symptom: Strange behavior after crash/restart
-- Clear: All four keys
+- Clear: both keys
 
 ### Manual Recovery Procedures
 
@@ -846,8 +821,6 @@ from src.cache_manager import CacheManager
 cache = CacheManager()
 cache.clear_cache('display_on_demand_config')
 cache.clear_cache('display_on_demand_state')
-cache.clear_cache('display_on_demand_request')
-cache.clear_cache('display_on_demand_processed_id')
 ```
 
 > `CacheManager` also has a `delete(key)` method — a thin wrapper over

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -42,11 +42,11 @@ each other. They share three things:
 | State | Where | Written by | Read by |
 |---|---|---|---|
 | On-demand command | control socket `/run/ledmatrix/control.sock` ([IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)) | web: `start_on_demand_display()` / `stop_on_demand_display()` in [`api_v3/display.py`](../web_interface/blueprints/api_v3/display.py), via [`src/ipc/client.py`](../src/ipc/client.py) | display: [`src/ipc/server.py`](../src/ipc/server.py) acks; the render thread applies it in `_poll_on_demand_requests()` |
-| On-demand request (fallback) | cache `display_on_demand_request` | web, only when the socket could not carry the request (`should_fall_back`); four plugins write it directly | display: `_poll_on_demand_requests()`, a `stat()` every 1 s while the socket is up (0.25 s without), read only when the file changed |
+| On-demand request from a plugin | in memory: `BasePlugin.request_on_demand()` / `end_on_demand()` | a plugin in the display process | display: `submit_plugin_on_demand()` queues it; the render thread applies it in `_poll_on_demand_requests()` |
 | On-demand state | cache `display_on_demand_state` | display: `_publish_on_demand_state()` | web: `/api/v3/display/on-demand/status` |
 | Current screen | cache `display_current_state` | display | web: `/api/v3/display/current-status` |
 | Plugin errors | cache `plugin_error_snapshot` | display: `ErrorSnapshotPublisher` ([`src/error_aggregator.py`](../src/error_aggregator.py)) | web: `read_error_report()` for `/api/v3/errors/*` |
-| Error clear | control socket `errors.clear`; cache `plugin_error_clear_request` as the fallback | web: `POST /api/v3/errors/clear` | display: applied before the socket answers; the mailbox on the error publisher's 5 s tick, read only when the file changed |
+| Error clear | control socket `errors.clear` | web: `POST /api/v3/errors/clear` | display: applied before the socket answers |
 | Font usage | cache `font_usage_snapshot` | display: `FontUsagePublisher` ([`src/font_usage.py`](../src/font_usage.py)) | web: Fonts tab |
 | Fetch statistics (requests per plugin and host) | cache `fetch_stats_snapshot` | display: `FetchStatsPublisher` ([`src/common/fetch_service.py`](../src/common/fetch_service.py)), at most once a minute on change | web: `read_fetch_stats()` for `/api/v3/plugins/fetch-stats` |
 | Plugin health | cache `plugin_health:<id>` | display (web writes on reset) | web: `/api/v3/plugins/health` |
@@ -58,18 +58,17 @@ each other. They share three things:
 
 The on-demand start route starts `ledmatrix.service` when it is not running
 (`start_service`, on by default) but never restarts a running one. The routes
-send the command over the display's control socket and get an ack; only when
-the socket could not carry it (a stopped display, one older than the socket
-or the command) do they write the mailbox instead. A display that had the
-request and refused it is answered with the error, not posted a mailbox
-copy. The display looks at the mailbox every
-`MAILBOX_POLL_INTERVAL_WITH_SOCKET` (1 s) while it serves the socket, and
-every `ON_DEMAND_POLL_INTERVAL` (0.25 s) without one, from its dwell sleep,
-its render loops and Vegas's interrupt check as well as the main loop; a
-look is one `stat()` unless the file changed. Both ways end in the same
-handler, `_handle_on_demand_request()`.
+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 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, the permission model and the plan to retire the mailboxes.
+for the protocol and the permission model.
 
 ### Web and display processes: who runs plugins
 
@@ -118,8 +117,8 @@ other web-UI action runs its script as a subprocess. A later, explicit
 
 The **control socket** from the web process to the display
 ([IPC_CONTROL_SOCKET.md](IPC_CONTROL_SOCKET.md)) carries on-demand
-commands and reloads an updated plugin; its next stages stream the
-display's state and retire the cache-key mailboxes. The plugin web-entry
+commands, reloads an updated plugin and streams the display's state; it
+replaced the cache-key mailboxes. The plugin web-entry
 contract above is still to come.
 
 ### Plugin state: desired, observed, and who owns it