Add Transport-Neutral Serial Session Broker

README.md

@@ -12,7 +12,7 @@ Universal wireless serial adaptor firmware for the ESP32-S3.
 - 8 MB octal PSRAM
 - Adafruit MAX3243 full-pinout RS-232 breakout, product 5988
 
-The firmware has completed **Phase 0 hardware characterization** and now includes the **Phase 1 serial-core foundation**. The MAX3243 diagnostics remain available, alongside a versioned NVS-backed serial configuration and a buffered UART1 service with modem-state monitoring and error counters. Neither the UART service nor an electrical test starts automatically at boot.
+The firmware has completed **Phase 0 hardware characterization** and the **Phase 1 serial-core foundation**. **Phase 2** adds a transport-neutral serial-session broker with one active writer, multiple observers, bounded per-client queues, event delivery, and slow-client isolation. The MAX3243 diagnostics and persistent serial configuration remain available. Neither the UART service nor an electrical test starts automatically at boot.
 
 ## Hardware wiring
 
@@ -50,8 +50,6 @@ serial defaults
 serial reset
 serial counters
 serial clear-counters
-serial send-hex <hex-bytes>
-serial read [maximum-bytes]
 ```
 
 Safe defaults are 115200 baud, 8 data bits, no parity, one stop bit, no flow control, and inactive DTR. Supported configuration values are:
@@ -68,10 +66,37 @@ Safe defaults are 115200 baud, 8 data bits, no parity, one stop bit, no flow con
 
 `serial set` changes the working configuration and safely restarts UART1 if the service is running. It does not write flash; use `serial save` to commit the current configuration to NVS. `serial defaults` changes RAM only, while `serial reset` applies and persists defaults. The firmware never erases the shared NVS partition automatically when storage is incompatible or unavailable.
 
-The service uses independent software RX and TX streams. Calls into those streams are nonblocking, and a deasserted CTS cannot block service shutdown. `serial send-hex` and `serial read` are temporary binary-safe console clients for validation before the session broker and USB/network clients are added.
+The service uses independent software RX and TX streams. Calls into those streams are nonblocking, and a deasserted CTS cannot block service shutdown. UART data access is intentionally reserved for the session broker; the `serial` command controls configuration and lifecycle only.
 
 UART1 has exclusive ownership while the service runs. Phase 0 commands will refuse to touch the port until `serial stop` releases it.
 
+### Phase 2 session broker
+
+The broker is initialized at boot and continuously drains the serial service whenever UART1 is running. It is transport-neutral: current console clients use the same API that native USB CDC, WebSocket, and SSH transports will use later.
+
+```text
+broker status
+broker clients
+broker counters
+broker clear-counters
+broker connect <name>
+broker disconnect <client-id>
+broker request-writer <client-id>
+broker release-writer <client-id>
+broker force-writer <client-id|none>
+broker send-hex <client-id> <hex-bytes>
+broker read <client-id> [maximum-bytes]
+broker events <client-id>
+```
+
+Each connection receives a generation-safe numeric ID. Stale IDs from disconnected clients cannot address a newly reused slot. Up to eight clients may connect, each with a bounded 4096-byte output queue and a 16-entry event queue.
+
+UART RX is copied to every connected client. A full observer queue drops bytes only for that observer and records the loss; it never blocks UART reception or another client. With no clients, the broker still drains UART data and records it as unobserved.
+
+Exactly one client may hold the writer lease. Competing requests are denied and generate events. Administrative forced reassignment atomically revokes the old writer and grants the new one. Bytes already accepted before revocation remain queued for transmission; revocation prevents future admission rather than purging the UART TX stream.
+
+Connect, disconnect, writer grant, release, revoke, and denial events have a broker-global sequence number. Event queues are intentionally bounded, so future transports should reconcile sequence gaps against broker snapshots. The first and last broker connection also drive the Phase 1 `DTR=on-connect` policy.
+
 ### Phase 0 diagnostics
 
 The retained hardware-characterization commands are: