forgot to build roverd binary lol lol

feat(commands): add a fun command category with 18 public `rs` commands

.gitignore

@@ -26,10 +26,14 @@ webui/package-lock.json
 !server/data/barcode-registry.json
 webui/src/config/analytics.jsx
 webui/src/config/driverAnalytics.json
-webui/src/config/analytics.html
+server/data/analytics.html
 plans/barcodegames.txt
 .gitignore
 server/data/identity.sqlite
 server/data/barcode-games.json
 server/data/identity.sqlite-shm
 server/data/identity.sqlite-wal
+server/src/services/balanceBoardService/native/balance_board_worker
+server/data/fleet-reports.sqlite
+server/data/fleet-reports.sqlite-shm
+server/data/fleet-reports.sqlite-wal

docs/spectator-bot.md

@@ -0,0 +1,117 @@
+# Simple spectator bot
+
+A spectator bot connects to the rover server with Socket.IO. It can receive the current session, read chat, and send messages that are visually tagged as bot messages.
+
+## Install
+
+Create a small Node.js project and install the Socket.IO client:
+
+```bash
+npm install socket.io-client
+```
+
+## Example bot
+
+Create `bot.js`:
+
+```js
+import { io } from 'socket.io-client';
+
+// Replace this with the public URL of the MultiRoombaRover server.
+const socket = io('https://your-rover-server.example', {
+  // Match the transports supported by the server while retaining polling as a
+  // fallback for networks or proxies that do not allow WebSocket connections.
+  transports: ['websocket', 'polling'],
+});
+
+// Socket.IO acknowledgements use callbacks. This small wrapper turns them into
+// promises so setup failures and rejected chat messages are easy to handle.
+function emitWithAck(event, payload) {
+  return new Promise((resolve, reject) => {
+    socket.emit(event, payload, (response = {}) => {
+      if (response.error) {
+        reject(new Error(response.error));
+        return;
+      }
+
+      resolve(response);
+    });
+  });
+}
+
+socket.on('connect', async () => {
+  console.log('Connected:', socket.id);
+
+  try {
+    // Set the name that will appear beside this connection and its messages.
+    await emitWithAck('nickname:set', {
+      nickname: 'My spectator bot',
+    });
+
+    // Ask the server to make this passive connection a spectator. Performing
+    // this after every connection also restores the role after a reconnect.
+    await emitWithAck('session:setRole', {
+      role: 'spectator',
+    });
+
+    console.log('Connected as a spectator');
+  } catch (error) {
+    console.error('Spectator setup failed:', error.message);
+  }
+});
+
+// Each session:sync event is a complete current session snapshot. Replace any
+// previously stored session with this object instead of merging snapshots.
+socket.on('session:sync', (session) => {
+  console.log('Session:', session);
+});
+
+// chat:init contains the recent chat history available when the bot connects.
+socket.on('chat:init', (messages) => {
+  console.log('Recent chat:', messages);
+});
+
+// chat:message fires whenever a new message is broadcast, including messages
+// sent by this bot itself.
+socket.on('chat:message', (message) => {
+  console.log(`${message.nickname || 'Unknown'}: ${message.text}`);
+});
+
+socket.on('disconnect', (reason) => {
+  console.log('Disconnected:', reason);
+});
+
+// Setting bot to true adds the normal bot tag to the displayed chat message.
+// It does not grant the connection any additional permissions.
+function sendBotMessage(text) {
+  return emitWithAck('chat:send', {
+    text,
+    bot: true,
+  });
+}
+
+// Send one example message after the connection has had time to finish setup.
+// A real bot would call sendBotMessage from its own message-handling logic.
+setTimeout(() => {
+  sendBotMessage('Hello from my spectator bot!').catch((error) => {
+    console.error('Message failed:', error.message);
+  });
+}, 5000);
+```
+
+Run it with:
+
+```bash
+node bot.js
+```
+
+## Events used
+
+- `nickname:set` sets the bot's visible nickname.
+- `session:setRole` changes the connection to a spectator.
+- `session:sync` provides the latest complete session state.
+- `chat:init` provides recent chat history after connecting.
+- `chat:message` provides new chat messages.
+- `chat:send` sends a chat message. Include `bot: true` to give it the bot tag.
+
+The server can reject spectator access or a chat message. Always check the acknowledgement callback, as the example does, so those errors are not silently ignored.

pi/bin/audio-forward-listener.sh

@@ -9,9 +9,8 @@ if [[ ! -f "$ENV_FILE" ]]; then
   exit 1
 fi
 
-# Load KEY=VALUE pairs from media.env without evaluating shell syntax. The
+# Load KEY=VALUE pairs from media.env without evaluating shell syntax. The forward URL is
-# forward URL is data produced by roverd, and treating it as shell code would
+# data produced by roverd and must never be interpreted as executable shell code.
-# break on normal SRT query-string characters such as '&'.
 load_env_file() {
   local content=""
 
@@ -95,6 +94,9 @@ run_pipeline() {
     -flags low_delay
     -analyzeduration 200k
     -probesize 32k
+    # The forwarded-audio URL is RTSP. Pinning TCP avoids ffmpeg negotiating the
+    # separate unreliable RTP/UDP transport that the server intentionally disables.
+    -rtsp_transport tcp
     -i "${ROVERD_AUDIO_PLAYBACK_FORWARD_URL}"
     -vn
   )

pi/bin/audio-only-publisher.sh

@@ -9,9 +9,8 @@ if [[ ! -f "$ENV_FILE" ]]; then
 	exit 1
 fi
 
-# Load KEY=VALUE pairs from media.env without evaluating shell syntax. SRT URLs
+# Load KEY=VALUE pairs from media.env without evaluating shell syntax. URLs are data;
-# contain characters such as '&' and '#!', so sourcing this file would treat a
+# sourcing this file would unnecessarily treat server-provided values as shell code.
-# data file as code and can split a valid URL into shell control operators.
 load_env_file() {
 	local content=""
 
@@ -88,6 +87,7 @@ else
 fi
 
 run_pipeline() {
+	local -a pipeline_statuses=()
 	local ffmpeg_args=(
 		-hide_banner
 		-loglevel warning
@@ -123,13 +123,14 @@ run_pipeline() {
 		-frame_duration 20
 		-compression_level 0
 
-		# Mirror the video publisher's MPEG-TS low-latency settings. Without
+		# RTSP carries the existing Opus stream directly, avoiding MediaMTX's costly
-		# these, ffmpeg is allowed to hold packets for mux timing, which is
+		# MPEG-TS demux without changing microphone capture or encoding quality. TCP is
-		# exactly the wrong tradeoff for live rover feedback.
+		# required for the same reliable local-network behavior as the video publisher.
 		-flush_packets 1
 		-muxdelay 0
 		-muxpreload 0
-		-f mpegts
+		-f rtsp
+		-rtsp_transport tcp
 		"${ROVERD_AUDIO_CAPTURE_PUBLISH_URL}"
 	)
 
@@ -146,6 +147,17 @@ run_pipeline() {
 	# latency compared with the old 65,536-byte buffer.
 	arecord -D "${CAPTURE_DEVICE}" -f S32_LE -c "${ROVERD_AUDIO_CAPTURE_CHANNELS}" -r "${ROVERD_AUDIO_CAPTURE_SAMPLE_RATE}" -B "${AUDIO_ALSA_BUFFER_BYTES}" -F "${AUDIO_ALSA_PERIOD_BYTES}" -q -t raw \
 		| "${FFMPEG_BIN_PATH}" "${ffmpeg_args[@]}"
+	pipeline_statuses=("${PIPESTATUS[@]}")
+
+	# PIPESTATUS belongs to the pipeline that just finished and is replaced by the next shell
+	# command. Capture it immediately, then return the publisher failure first because that is
+	# normally the reason arecord receives a secondary broken pipe.
+	LAST_ARECORD_STATUS="${pipeline_statuses[0]:-unknown}"
+	LAST_FFMPEG_STATUS="${pipeline_statuses[1]:-unknown}"
+	if [[ "${LAST_FFMPEG_STATUS}" != "0" ]]; then
+		return "${LAST_FFMPEG_STATUS}"
+	fi
+	return "${LAST_ARECORD_STATUS}"
 }
 
 trap 'kill 0 2>/dev/null' EXIT INT TERM
@@ -154,6 +166,6 @@ while true; do
 	if run_pipeline; then
 		exit 0
 	fi
-	echo "Audio-only publisher exited arecord=${PIPESTATUS[0]} ffmpeg=${PIPESTATUS[1]}, restarting in 2s..." >&2
+	echo "Audio-only publisher exited arecord=${LAST_ARECORD_STATUS:-unknown} ffmpeg=${LAST_FFMPEG_STATUS:-unknown}, restarting in 2s..." >&2
 	sleep 2
 done

pi/bin/debian-laptop-video-publisher.sh

@@ -9,9 +9,8 @@ if [[ ! -f "$ENV_FILE" ]]; then
 	exit 1
 fi
 
-# Load roverd's generated media.env as data instead of sourcing it as shell.
+# Load roverd's generated media.env as data instead of sourcing it as shell. URLs are
-# The SRT publish URL contains normal query-string characters like '&' and '#!',
+# configuration data, so evaluating the file would be both fragile and unnecessary.
-# so evaluating the file would be both fragile and unnecessary.
 load_env_file() {
 	local content=""
 
@@ -103,6 +102,8 @@ if [[ "${ROVERD_VIDEO_INVERT}" -ne 0 ]]; then
 fi
 
 run_pipeline() {
+	# Keep laptop rovers on the same transport contract as Pi camera rovers. This changes
+	# only the encoded stream's carrier; V4L2 capture and H264 encoding remain untouched.
 	"${FFMPEG_BIN_PATH}" \
 		-hide_banner \
 		-loglevel warning \
@@ -130,7 +131,8 @@ run_pipeline() {
 		-flush_packets 1 \
 		-muxdelay 0 \
 		-muxpreload 0 \
-		-f mpegts \
+		-f rtsp \
+		-rtsp_transport tcp \
 		"${ROVERD_VIDEO_PUBLISH_URL}"
 }
 

pi/bin/media-transport.test.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# These publishers contain hardware-facing infinite retry loops, so executing them in a unit
+# test would require unsafe process-group traps and fake camera/ALSA devices. Pin the small
+# transport boundary directly instead: every publisher must request RTSP/TCP and none may
+# reintroduce the high-latency MPEG-TS muxer.
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+
+assert_rtsp_tcp() {
+	local file="$1"
+	if ! grep -q -- '-f rtsp' "$file"; then
+		echo "Missing RTSP muxer in $file" >&2
+		exit 1
+	fi
+	if ! grep -q -- '-rtsp_transport tcp' "$file"; then
+		echo "Missing RTSP/TCP pin in $file" >&2
+		exit 1
+	fi
+	if grep -q -- '-f mpegts' "$file"; then
+		echo "Unexpected MPEG-TS muxer in $file" >&2
+		exit 1
+	fi
+}
+
+assert_rtsp_tcp "$SCRIPT_DIR/video-publisher.sh"
+assert_rtsp_tcp "$SCRIPT_DIR/debian-laptop-video-publisher.sh"
+assert_rtsp_tcp "$SCRIPT_DIR/audio-only-publisher.sh"
+
+# The speaker path reads rather than publishes, so it has no output muxer. It must still pin
+# RTSP/TCP before its input URL to match the server's TCP-only listener.
+if ! grep -q -- '-rtsp_transport tcp' "$SCRIPT_DIR/audio-forward-listener.sh"; then
+	echo "Missing RTSP/TCP input pin in audio-forward-listener.sh" >&2
+	exit 1
+fi
+
+echo "Media publisher transport checks passed"

pi/bin/video-publisher.sh

@@ -110,6 +110,10 @@ else
 fi
 
 run_pipeline() {
+  # MPEG-TS added most of the former rover-to-browser latency inside MediaMTX's
+  # demuxer. RTSP carries the same encoded H264 without changing the camera or codec.
+  # TCP is explicit because plain RTSP/RTP over UDP has no retransmission and proved
+  # unreliable even though MediaMTX still reported the incomplete stream as ready.
   "${LIBCAMERA_BIN_PATH}" \
     --inline \
     --timeout 0 \
@@ -142,7 +146,8 @@ run_pipeline() {
       -flush_packets 1 \
       -muxdelay 0 \
       -muxpreload 0 \
-      -f mpegts \
+      -f rtsp \
+      -rtsp_transport tcp \
       "${ROVERD_VIDEO_PUBLISH_URL}"
 }
 

pi/install/media_env.sh

@@ -13,7 +13,7 @@ write_media_env_placeholder() {
 # Managed by roverd; placeholder values will be overwritten at runtime.
 ROVERD_VIDEO_ENABLE=1
 ROVERD_VIDEO_PUBLISHER=pi-libcamera
-ROVERD_VIDEO_PUBLISH_URL=srt://192.168.0.86:9000?streamid=#!::r=CHANGE_ME,m=publish&latency=10&mode=caller&transtype=live&pkt_size=1316
+ROVERD_VIDEO_PUBLISH_URL=rtsp://control-server.local:8554/CHANGE_ME
 ROVERD_VIDEO_DEVICE=
 ROVERD_VIDEO_INPUT_FORMAT=
 ROVERD_VIDEO_WIDTH=640
@@ -23,13 +23,13 @@ ROVERD_VIDEO_BITRATE=2000000
 ROVERD_VIDEO_INVERT=1
 ROVERD_VIDEO_SENSOR_MODE=1296:972
 ROVERD_AUDIO_CAPTURE_ENABLE=0
-ROVERD_AUDIO_CAPTURE_PUBLISH_URL=srt://192.168.0.86:9000?streamid=#!::r=CHANGE_ME-audio,m=publish&latency=10&mode=caller&transtype=live&pkt_size=1316
+ROVERD_AUDIO_CAPTURE_PUBLISH_URL=rtsp://control-server.local:8554/CHANGE_ME-audio
 ROVERD_AUDIO_CAPTURE_DEVICE=hw:0,0
 ROVERD_AUDIO_CAPTURE_SAMPLE_RATE=48000
 ROVERD_AUDIO_CAPTURE_CHANNELS=2
 ROVERD_AUDIO_CAPTURE_BITRATE=510000
 ROVERD_AUDIO_PLAYBACK_ENABLE=1
-ROVERD_AUDIO_PLAYBACK_FORWARD_URL=srt://192.168.0.86:9000?streamid=#!::r=CHANGE_ME-fwd,m=request&latency=10&mode=caller&transtype=live&pkt_size=1316
+ROVERD_AUDIO_PLAYBACK_FORWARD_URL=rtsp://control-server.local:8554/CHANGE_ME-fwd
 ROVERD_AUDIO_PLAYBACK_DEVICE=forward
 ROVERD_AUDIO_PLAYBACK_NORMALIZE=1
 ROVERD_AUDIO_PLAYBACK_NORMALIZE_FILTER=dynaudnorm=f=75:g=15:m=10:p=0.9,alimiter=limit=0.85:level=disabled
@@ -43,7 +43,7 @@ ENV
 # Managed by roverd; placeholder values will be overwritten at runtime.
 ROVERD_VIDEO_ENABLE=1
 ROVERD_VIDEO_PUBLISHER=debian-laptop-v4l2
-ROVERD_VIDEO_PUBLISH_URL=srt://192.168.0.86:9000?streamid=#!::r=CHANGE_ME,m=publish&latency=10&mode=caller&transtype=live&pkt_size=1316
+ROVERD_VIDEO_PUBLISH_URL=rtsp://control-server.local:8554/CHANGE_ME
 ROVERD_VIDEO_DEVICE=/dev/video0
 ROVERD_VIDEO_INPUT_FORMAT=mjpeg
 ROVERD_VIDEO_WIDTH=640
@@ -53,13 +53,13 @@ ROVERD_VIDEO_BITRATE=2000000
 ROVERD_VIDEO_INVERT=0
 ROVERD_VIDEO_SENSOR_MODE=
 ROVERD_AUDIO_CAPTURE_ENABLE=1
-ROVERD_AUDIO_CAPTURE_PUBLISH_URL=srt://192.168.0.86:9000?streamid=#!::r=CHANGE_ME-audio,m=publish&latency=10&mode=caller&transtype=live&pkt_size=1316
+ROVERD_AUDIO_CAPTURE_PUBLISH_URL=rtsp://control-server.local:8554/CHANGE_ME-audio
 ROVERD_AUDIO_CAPTURE_DEVICE=default
 ROVERD_AUDIO_CAPTURE_SAMPLE_RATE=48000
 ROVERD_AUDIO_CAPTURE_CHANNELS=2
 ROVERD_AUDIO_CAPTURE_BITRATE=510000
 ROVERD_AUDIO_PLAYBACK_ENABLE=1
-ROVERD_AUDIO_PLAYBACK_FORWARD_URL=srt://192.168.0.86:9000?streamid=#!::r=CHANGE_ME-fwd,m=request&latency=10&mode=caller&transtype=live&pkt_size=1316
+ROVERD_AUDIO_PLAYBACK_FORWARD_URL=rtsp://control-server.local:8554/CHANGE_ME-fwd
 ROVERD_AUDIO_PLAYBACK_DEVICE=forward
 ROVERD_AUDIO_PLAYBACK_NORMALIZE=1
 ROVERD_AUDIO_PLAYBACK_NORMALIZE_FILTER=dynaudnorm=f=75:g=15:m=10:p=0.9,alimiter=limit=0.85:level=disabled

pi/roverd/config.go

@@ -3,9 +3,11 @@ package roverd
 import (
 	"errors"
 	"fmt"
+	"net"
 	"net/url"
 	"os"
 	"regexp"
+	"strconv"
 	"strings"
 	"time"
 
@@ -77,10 +79,10 @@ type HornConfig struct {
 }
 
 type MediaConfig struct {
-	// PublishPort is shared by the derived video, microphone, and forwarded-audio
+	// RTSPPort is shared by the derived video, microphone, and forwarded-audio
-	// SRT URLs. Keeping it at this level prevents each nested block from needing
+	// RTSP URLs. Keeping it at this level prevents each nested block from needing
 	// to repeat the same server port when the common MediaMTX listener is used.
-	PublishPort    int                 `yaml:"publishPort" json:"-"`
+	RTSPPort       int                 `yaml:"rtspPort" json:"-"`
 	Manage         bool                `yaml:"manage" json:"manage"`
 	HealthURL      string              `yaml:"healthUrl" json:"healthUrl,omitempty"`
 	HealthInterval Duration            `yaml:"healthInterval" json:"-"`
@@ -96,7 +98,9 @@ type VideoMediaConfig struct {
 	Enabled   bool   `yaml:"enabled" json:"enabled"`
 	Service   string `yaml:"service" json:"service,omitempty"`
 	Publisher string `yaml:"publisher" json:"publisher,omitempty"`
-	PublishURL  string `yaml:"publishUrl" json:"publishUrl,omitempty"`
+	// PublishURL is derived during validation. It remains in rover metadata for server-side
+	// consumers, but is not a second hand-written endpoint in /etc/roverd.yaml.
+	PublishURL  string `yaml:"-" json:"publishUrl,omitempty"`
 	Device      string `yaml:"device" json:"device,omitempty"`
 	InputFormat string `yaml:"inputFormat" json:"-"`
 	Width       int    `yaml:"width" json:"-"`
@@ -113,7 +117,8 @@ type AudioCaptureConfig struct {
 	// normalized defaults so enabling it only requires flipping enabled: true.
 	Enabled bool   `yaml:"enabled" json:"enabled"`
 	Service string `yaml:"service" json:"service,omitempty"`
-	PublishURL string `yaml:"publishUrl" json:"publishUrl,omitempty"`
+	// PublishURL follows the same derived-only contract as the video path.
+	PublishURL string `yaml:"-" json:"publishUrl,omitempty"`
 	Device     string `yaml:"device" json:"device,omitempty"`
 	SampleRate int    `yaml:"sampleRate" json:"-"`
 	Channels   int    `yaml:"channels" json:"-"`
@@ -127,7 +132,8 @@ type AudioPlaybackConfig struct {
 	// it needs to inject audio.
 	Enabled bool   `yaml:"enabled" json:"enabled"`
 	Service string `yaml:"service" json:"service,omitempty"`
-	ForwardURL      string `yaml:"forwardUrl" json:"forwardUrl,omitempty"`
+	// ForwardURL is derived because the server and rover must agree on the exact -fwd path.
+	ForwardURL      string `yaml:"-" json:"forwardUrl,omitempty"`
 	Device          string `yaml:"device" json:"device,omitempty"`
 	Normalize       bool   `yaml:"normalize" json:"-"`
 	NormalizeFilter string `yaml:"normalizeFilter" json:"-"`
@@ -230,7 +236,7 @@ func LoadConfig(path string) (*Config, error) {
 			},
 		},
 		Media: MediaConfig{
-			PublishPort:    9000,
+			RTSPPort:       8554,
 			HealthInterval: Duration{Duration: 30 * time.Second},
 			Video: VideoMediaConfig{
 				Enabled:    true,
@@ -349,8 +355,8 @@ func LoadConfig(path string) (*Config, error) {
 	if cfg.BRC.GPIOChip == "" {
 		cfg.BRC.GPIOChip = "gpiochip0"
 	}
-	if cfg.Media.PublishPort <= 0 {
+	if cfg.Media.RTSPPort <= 0 {
-		cfg.Media.PublishPort = 9000
+		cfg.Media.RTSPPort = 8554
 	}
 	if err := validateMediaConfig(&cfg.Media, cfg.ServerURL, cfg.Name); err != nil {
 		return nil, fmt.Errorf("media: %w", err)
@@ -432,25 +438,25 @@ func validateMediaConfig(cfg *MediaConfig, serverURL string, roverName string) e
 		file is written. This keeps the Pi behavior stable while making laptop
 		and future publisher variants explicit configuration choices.
 	*/
-	if cfg.PublishPort <= 0 {
+	if cfg.RTSPPort <= 0 {
-		cfg.PublishPort = 9000
+		cfg.RTSPPort = 8554
 	}
 	if cfg.HealthInterval.Duration <= 0 {
 		cfg.HealthInterval = Duration{Duration: 30 * time.Second}
 	}
-	if err := validateVideoMediaConfig(&cfg.Video, serverURL, roverName, cfg.PublishPort); err != nil {
+	if err := validateVideoMediaConfig(&cfg.Video, serverURL, roverName, cfg.RTSPPort); err != nil {
 		return fmt.Errorf("video: %w", err)
 	}
-	if err := validateAudioCaptureConfig(&cfg.AudioCapture, serverURL, roverName, cfg.PublishPort); err != nil {
+	if err := validateAudioCaptureConfig(&cfg.AudioCapture, serverURL, roverName, cfg.RTSPPort); err != nil {
 		return fmt.Errorf("audioCapture: %w", err)
 	}
-	if err := validateAudioPlaybackConfig(&cfg.AudioPlayback, serverURL, roverName, cfg.PublishPort); err != nil {
+	if err := validateAudioPlaybackConfig(&cfg.AudioPlayback, serverURL, roverName, cfg.RTSPPort); err != nil {
 		return fmt.Errorf("audioPlayback: %w", err)
 	}
 	return nil
 }
 
-func validateVideoMediaConfig(cfg *VideoMediaConfig, serverURL string, roverName string, publishPort int) error {
+func validateVideoMediaConfig(cfg *VideoMediaConfig, serverURL string, roverName string, rtspPort int) error {
 	if cfg.Service == "" {
 		cfg.Service = "video-publisher.service"
 	}
@@ -476,17 +482,19 @@ func validateVideoMediaConfig(cfg *VideoMediaConfig, serverURL string, roverName
 	if cfg.SensorMode == "" && cfg.Publisher == "pi-libcamera" {
 		cfg.SensorMode = "1296:972"
 	}
-	if cfg.PublishURL == "" {
+	/*
-		derived, err := derivePublishURL(serverURL, roverName, publishPort)
+		Always derive this endpoint. Older rover configs can contain an explicit SRT publishUrl;
+		honoring it after a binary update would silently leave that rover on the old transport.
+	*/
+	derived, err := derivePublishURL(serverURL, roverName, rtspPort)
 	if err != nil {
 		return fmt.Errorf("derive publishUrl: %w", err)
 	}
 	cfg.PublishURL = derived
-	}
 	return nil
 }
 
-func validateAudioCaptureConfig(cfg *AudioCaptureConfig, serverURL string, roverName string, publishPort int) error {
+func validateAudioCaptureConfig(cfg *AudioCaptureConfig, serverURL string, roverName string, rtspPort int) error {
 	if cfg.Service == "" {
 		cfg.Service = "audio-only-publisher.service"
 	}
@@ -502,17 +510,15 @@ func validateAudioCaptureConfig(cfg *AudioCaptureConfig, serverURL string, rover
 	if cfg.Bitrate <= 0 {
 		cfg.Bitrate = 510000
 	}
-	if cfg.PublishURL == "" {
+	derived, err := derivePublishURL(serverURL, roverName+"-audio", rtspPort)
-		derived, err := derivePublishURL(serverURL, roverName+"-audio", publishPort)
 	if err != nil {
 		return fmt.Errorf("derive publishUrl: %w", err)
 	}
 	cfg.PublishURL = derived
-	}
 	return nil
 }
 
-func validateAudioPlaybackConfig(cfg *AudioPlaybackConfig, serverURL string, roverName string, publishPort int) error {
+func validateAudioPlaybackConfig(cfg *AudioPlaybackConfig, serverURL string, roverName string, rtspPort int) error {
 	if cfg.Service == "" {
 		cfg.Service = "audio-forward-listener.service"
 	}
@@ -522,13 +528,11 @@ func validateAudioPlaybackConfig(cfg *AudioPlaybackConfig, serverURL string, rov
 	if cfg.NormalizeFilter == "" {
 		cfg.NormalizeFilter = "dynaudnorm=f=75:g=15:m=10:p=0.9,alimiter=limit=0.85:level=disabled"
 	}
-	if cfg.ForwardURL == "" {
+	derived, err := deriveReadURL(serverURL, roverName+"-fwd", rtspPort)
-		derived, err := deriveReadURL(serverURL, roverName+"-fwd", publishPort)
 	if err != nil {
 		return fmt.Errorf("derive forwardUrl: %w", err)
 	}
 	cfg.ForwardURL = derived
-	}
 	return nil
 }
 
@@ -577,20 +581,17 @@ func validateAutoSideBrushConfig(cfg *AutoSideBrushConfig) {
 }
 
 func derivePublishURL(serverURL, streamName string, port int) (string, error) {
-	return deriveSRTURL(serverURL, streamName, port, "publish")
+	return deriveRTSPURL(serverURL, streamName, port)
 }
 
 func deriveReadURL(serverURL, streamName string, port int) (string, error) {
-	return deriveSRTURL(serverURL, streamName, port, "request")
+	return deriveRTSPURL(serverURL, streamName, port)
 }
 
-func deriveSRTURL(serverURL, streamName string, port int, mode string) (string, error) {
+func deriveRTSPURL(serverURL, streamName string, port int) (string, error) {
 	if streamName == "" {
 		return "", errors.New("missing stream name for publishUrl")
 	}
-	if mode == "" {
-		mode = "publish"
-	}
 	parsed, err := url.Parse(serverURL)
 	if err != nil {
 		return "", err
@@ -600,10 +601,16 @@ func deriveSRTURL(serverURL, streamName string, port int, mode string) (string,
 		return "", errors.New("serverUrl missing host")
 	}
 	if port <= 0 {
-		port = 9000
+		port = 8554
 	}
+	/*
+		JoinHostPort handles both ordinary hostnames and bracketed IPv6 addresses. The rover name
+		is a MediaMTX path, so it is escaped independently instead of interpolated into the host.
+		RTSP distinguishes publishing from reading through protocol methods, which is why both
+		directions intentionally use the same URL shape.
+	*/
 	escaped := url.PathEscape(streamName)
-	return fmt.Sprintf("srt://%s:%d?streamid=#!::r=%s,m=%s&latency=10&mode=caller&transtype=live&pkt_size=1316", host, port, escaped, mode), nil
+	return fmt.Sprintf("rtsp://%s/%s", net.JoinHostPort(host, strconv.Itoa(port)), escaped), nil
 }
 
 var hexColorRe = regexp.MustCompile(`^#[0-9A-Fa-f]{6}$`)

pi/roverd/host_stats.go

@@ -3,6 +3,7 @@ package roverd
 import (
 	"bufio"
 	"context"
+	"errors"
 	"fmt"
 	"math"
 	"os"
@@ -14,7 +15,7 @@ import (
 )
 
 const (
-	hostStatsInterval = 5 * time.Second
+	hostStatsInterval = 1 * time.Second
 	rootFilesystem    = "/"
 )
 
@@ -63,7 +64,24 @@ type WiFiStats struct {
 	TXBytes       *uint64  `json:"txBytes,omitempty"`
 	RXPackets     *uint64  `json:"rxPackets,omitempty"`
 	TXPackets     *uint64  `json:"txPackets,omitempty"`
+	DownloadMbps  *float64 `json:"downloadMbps,omitempty"`
+	UploadMbps    *float64 `json:"uploadMbps,omitempty"`
 	InactiveMs    *int     `json:"inactiveMs,omitempty"`
+
+	// networkSampledAt records the instant associated with the kernel byte
+	// counters. Keeping it out of JSON lets the websocket loop calculate rates
+	// with monotonic Go timestamps without expanding the browser contract with
+	// an implementation-only value.
+	networkSampledAt time.Time
+}
+
+// networkRateSample is scoped to one rover websocket connection. A new
+// connection intentionally starts a new baseline so counters from an old boot
+// or network interface lifetime can never create an artificial traffic spike.
+type networkRateSample struct {
+	rxBytes   uint64
+	txBytes   uint64
+	sampledAt time.Time
 }
 
 // CollectHostStats gathers every source independently so one missing kernel
@@ -370,12 +388,81 @@ func collectWiFiStats(ctx context.Context) (*WiFiStats, error) {
 		return nil, err
 	}
 
-	// The interface is used only to ask iw about the active connection. It is
+	// The interface is used only for local collection. It is not copied into
-	// not copied into WiFiStats because the UI does not need to expose it.
+	// WiFiStats because the UI does not need to expose Linux device names.
-	if err := enrichWiFiWithIW(ctx, iface, stats); err != nil {
+	iwErr := enrichWiFiWithIW(ctx, iface, stats)
-		return stats, err
+
+	// Read the kernel counters after iw because iw also provides cumulative
+	// station counters. The kernel interface values deliberately win: they are
+	// the host-traffic source used for both the cumulative display and Mbps math.
+	// Link capacity still comes independently from iw's bitrate fields.
+	counterErr := enrichWiFiWithNetworkCounters(iface, stats)
+	return stats, errors.Join(counterErr, iwErr)
+}
+
+func enrichWiFiWithNetworkCounters(iface string, stats *WiFiStats) error {
+	basePath := "/sys/class/net/" + iface + "/statistics/"
+	rxBytes, err := readUintFile(basePath + "rx_bytes")
+	if err != nil {
+		return fmt.Errorf("read %s receive bytes: %w", iface, err)
 	}
-	return stats, nil
+	txBytes, err := readUintFile(basePath + "tx_bytes")
+	if err != nil {
+		return fmt.Errorf("read %s transmit bytes: %w", iface, err)
+	}
+
+	stats.RXBytes = &rxBytes
+	stats.TXBytes = &txBytes
+	// Capture the timestamp immediately beside the counter reads so unrelated
+	// host-stat collection latency cannot distort the elapsed-time divisor.
+	stats.networkSampledAt = time.Now()
+	return nil
+}
+
+func readUintFile(path string) (uint64, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return 0, err
+	}
+	return strconv.ParseUint(strings.TrimSpace(string(raw)), 10, 64)
+}
+
+func applyNetworkThroughput(stats *WiFiStats, previous *networkRateSample) *networkRateSample {
+	if stats == nil || stats.RXBytes == nil || stats.TXBytes == nil || stats.networkSampledAt.IsZero() {
+		// Do not discard the last valid baseline during a temporary read failure.
+		// The next successful calculation then covers the full elapsed interval and
+		// remains an accurate average for all traffic transferred during the gap.
+		return previous
+	}
+
+	current := &networkRateSample{
+		rxBytes:   *stats.RXBytes,
+		txBytes:   *stats.TXBytes,
+		sampledAt: stats.networkSampledAt,
+	}
+	if previous == nil {
+		return current
+	}
+
+	elapsed := current.sampledAt.Sub(previous.sampledAt).Seconds()
+	// Linux counters can return to zero after an interface reset. Re-baselining
+	// on any decrease prevents unsigned underflow from becoming a huge false
+	// throughput spike in the host-stat card.
+	if elapsed <= 0 || current.rxBytes < previous.rxBytes || current.txBytes < previous.txBytes {
+		return current
+	}
+
+	downloadMbps := bytesToMbps(current.rxBytes-previous.rxBytes, elapsed)
+	uploadMbps := bytesToMbps(current.txBytes-previous.txBytes, elapsed)
+	stats.DownloadMbps = &downloadMbps
+	stats.UploadMbps = &uploadMbps
+	return current
+}
+
+func bytesToMbps(byteDelta uint64, elapsedSeconds float64) float64 {
+	// Mbps uses decimal megabits, matching network equipment and link-rate
+	// conventions: eight bits per byte and 1,000,000 bits per megabit.
+	return roundOneDecimal((float64(byteDelta) * 8) / elapsedSeconds / 1_000_000)
 }
 
 func readWirelessStats() (string, *WiFiStats, error) {

pi/roverd/host_stats_test.go

@@ -0,0 +1,79 @@
+package roverd
+
+import (
+	"testing"
+	"time"
+)
+
+func TestApplyNetworkThroughputCalculatesMbpsFromActualElapsedTime(t *testing.T) {
+	startedAt := time.Unix(100, 0)
+	previous := &networkRateSample{rxBytes: 1_000, txBytes: 2_000, sampledAt: startedAt}
+	rxBytes := uint64(2_001_000)
+	txBytes := uint64(1_002_000)
+	stats := &WiFiStats{
+		RXBytes:          &rxBytes,
+		TXBytes:          &txBytes,
+		networkSampledAt: startedAt.Add(2 * time.Second),
+	}
+
+	next := applyNetworkThroughput(stats, previous)
+
+	if stats.DownloadMbps == nil || *stats.DownloadMbps != 8.0 {
+		t.Fatalf("expected 8.0 Mbps download, got %v", stats.DownloadMbps)
+	}
+	if stats.UploadMbps == nil || *stats.UploadMbps != 4.0 {
+		t.Fatalf("expected 4.0 Mbps upload, got %v", stats.UploadMbps)
+	}
+	if next == nil || next.rxBytes != rxBytes || next.txBytes != txBytes {
+		t.Fatalf("expected current counters to become the next baseline, got %#v", next)
+	}
+}
+
+func TestApplyNetworkThroughputFirstSampleOnlyEstablishesBaseline(t *testing.T) {
+	rxBytes := uint64(100)
+	txBytes := uint64(200)
+	stats := &WiFiStats{RXBytes: &rxBytes, TXBytes: &txBytes, networkSampledAt: time.Unix(100, 0)}
+
+	next := applyNetworkThroughput(stats, nil)
+
+	if stats.DownloadMbps != nil || stats.UploadMbps != nil {
+		t.Fatalf("expected no rates for the first sample, got download=%v upload=%v", stats.DownloadMbps, stats.UploadMbps)
+	}
+	if next == nil {
+		t.Fatal("expected the first valid sample to establish a baseline")
+	}
+}
+
+func TestApplyNetworkThroughputCounterResetEstablishesNewBaseline(t *testing.T) {
+	startedAt := time.Unix(100, 0)
+	previous := &networkRateSample{rxBytes: 10_000, txBytes: 20_000, sampledAt: startedAt}
+	rxBytes := uint64(10)
+	txBytes := uint64(20)
+	stats := &WiFiStats{RXBytes: &rxBytes, TXBytes: &txBytes, networkSampledAt: startedAt.Add(time.Second)}
+
+	next := applyNetworkThroughput(stats, previous)
+
+	if stats.DownloadMbps != nil || stats.UploadMbps != nil {
+		t.Fatalf("expected no rates after a counter reset, got download=%v upload=%v", stats.DownloadMbps, stats.UploadMbps)
+	}
+	if next == nil || next.rxBytes != rxBytes || next.txBytes != txBytes {
+		t.Fatalf("expected reset counters to become the new baseline, got %#v", next)
+	}
+}
+
+func TestApplyNetworkThroughputInvalidElapsedTimeEstablishesNewBaseline(t *testing.T) {
+	sampledAt := time.Unix(100, 0)
+	previous := &networkRateSample{rxBytes: 100, txBytes: 200, sampledAt: sampledAt}
+	rxBytes := uint64(200)
+	txBytes := uint64(300)
+	stats := &WiFiStats{RXBytes: &rxBytes, TXBytes: &txBytes, networkSampledAt: sampledAt}
+
+	next := applyNetworkThroughput(stats, previous)
+
+	if stats.DownloadMbps != nil || stats.UploadMbps != nil {
+		t.Fatalf("expected no rates with zero elapsed time, got download=%v upload=%v", stats.DownloadMbps, stats.UploadMbps)
+	}
+	if next == nil || next.sampledAt != sampledAt {
+		t.Fatalf("expected invalid timing sample to become the new baseline, got %#v", next)
+	}
+}

pi/roverd/media_url_test.go

@@ -0,0 +1,80 @@
+package roverd
+
+// These tests pin the network-agnostic RTSP contract. A rover provides its server URL and name
+// once; all three media paths must then resolve to distinct, safely escaped MediaMTX paths.
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestMediaURLsDeriveFromServerURLAndRoverName(t *testing.T) {
+	cfg := MediaConfig{
+		Video:         VideoMediaConfig{Enabled: true},
+		AudioCapture:  AudioCaptureConfig{Enabled: true},
+		AudioPlayback: AudioPlaybackConfig{Enabled: true},
+	}
+	if err := validateMediaConfig(&cfg, "ws://control-server.local:8080/rover", "rover one"); err != nil {
+		t.Fatalf("validate media config: %v", err)
+	}
+
+	wants := map[string]string{
+		"video":   "rtsp://control-server.local:8554/rover%20one",
+		"mic":     "rtsp://control-server.local:8554/rover%20one-audio",
+		"speaker": "rtsp://control-server.local:8554/rover%20one-fwd",
+	}
+	got := map[string]string{
+		"video":   cfg.Video.PublishURL,
+		"mic":     cfg.AudioCapture.PublishURL,
+		"speaker": cfg.AudioPlayback.ForwardURL,
+	}
+	for name, want := range wants {
+		if got[name] != want {
+			t.Errorf("%s URL: got %q, want %q", name, got[name], want)
+		}
+	}
+	if cfg.RTSPPort != 8554 {
+		t.Fatalf("RTSP port: got %d, want 8554", cfg.RTSPPort)
+	}
+}
+
+func TestExplicitMediaPortAppliesToEveryRTSPPath(t *testing.T) {
+	cfg := MediaConfig{
+		RTSPPort:      10554,
+		Video:         VideoMediaConfig{Enabled: true},
+		AudioCapture:  AudioCaptureConfig{Enabled: true},
+		AudioPlayback: AudioPlaybackConfig{Enabled: true},
+	}
+	if err := validateMediaConfig(&cfg, "ws://media.example/rover", "r1"); err != nil {
+		t.Fatalf("validate media config: %v", err)
+	}
+	for name, value := range map[string]string{
+		"video": cfg.Video.PublishURL, "mic": cfg.AudioCapture.PublishURL, "speaker": cfg.AudioPlayback.ForwardURL,
+	} {
+		if !strings.Contains(value, ":10554/") {
+			t.Errorf("%s URL did not use configured port: %q", name, value)
+		}
+	}
+}
+
+func TestLegacyExplicitSRTURLsCannotKeepAnUpdatedRoverOnTheOldTransport(t *testing.T) {
+	/*
+		Deployed rover configs can still contain these former fields. Validation must replace
+		them unconditionally so updating roverd is sufficient to move the whole media path.
+	*/
+	cfg := MediaConfig{
+		Video:         VideoMediaConfig{Enabled: true, PublishURL: "srt://old/video"},
+		AudioCapture:  AudioCaptureConfig{Enabled: true, PublishURL: "srt://old/audio"},
+		AudioPlayback: AudioPlaybackConfig{Enabled: true, ForwardURL: "srt://old/forward"},
+	}
+	if err := validateMediaConfig(&cfg, "ws://new-server.local:8080/rover", "r1"); err != nil {
+		t.Fatalf("validate media config: %v", err)
+	}
+	for name, value := range map[string]string{
+		"video": cfg.Video.PublishURL, "mic": cfg.AudioCapture.PublishURL, "speaker": cfg.AudioPlayback.ForwardURL,
+	} {
+		if !strings.HasPrefix(value, "rtsp://new-server.local:8554/") {
+			t.Errorf("%s retained an old transport URL: %q", name, value)
+		}
+	}
+}

pi/roverd/roverd.debian-laptop.sample.yaml

@@ -22,7 +22,8 @@ battery:
 maxWheelSpeed: 350
 
 media:
-  publishPort: 9000
+  # Media URLs are derived from serverUrl's hostname, this port, and the rover name.
+  rtspPort: 8554
   manage: true
   healthUrl: ""
   healthInterval: 30s

pi/roverd/roverd.sample.yaml

@@ -17,7 +17,8 @@ battery:
   urgent: 1650
 maxWheelSpeed: 350
 media:
-  publishPort: 9000
+  # Media URLs are derived from serverUrl's hostname, this port, and the rover name.
+  rtspPort: 8554
   manage: true
   healthUrl: ""
   healthInterval: 30s
@@ -25,7 +26,6 @@ media:
     enabled: true
     service: video-publisher.service
     publisher: pi-libcamera
-    publishUrl: srt://192.168.0.86:9000?streamid=#!::r=roomba-alpha,m=publish&latency=10&mode=caller&transtype=live&pkt_size=1316
     width: 640
     height: 480
     fps: 30
@@ -36,7 +36,6 @@ media:
   audioCapture:
     enabled: false
     service: audio-only-publisher.service
-    publishUrl: srt://192.168.0.86:9000?streamid=#!::r=roomba-alpha-audio,m=publish&latency=10&mode=caller&transtype=live&pkt_size=1316
     device: hw:0,0
     sampleRate: 48000
     channels: 2
@@ -44,7 +43,6 @@ media:
   audioPlayback:
     enabled: true
     service: audio-forward-listener.service
-    forwardUrl: srt://192.168.0.86:9000?streamid=#!::r=roomba-alpha-fwd,m=request&latency=10&mode=caller&transtype=live&pkt_size=1316
     device: forward
     normalize: true
 cameraServo:

pi/roverd/wsclient.go

@@ -531,14 +531,21 @@ func (c *WSClient) forwardEvents(ctx context.Context, conn *websocket.Conn) {
 }
 
 func (c *WSClient) forwardHostStats(ctx context.Context, conn *websocket.Conn) {
+	var previousNetworkSample *networkRateSample
+
 	send := func() bool {
 		// Host stats are collected on demand so each outbound message describes
 		// the current Pi state. Collection failures are encoded into the stats
 		// payload, which keeps this telemetry path from closing the rover socket.
+		stats := CollectHostStats(ctx)
+		// Throughput is derived here because this loop owns the ordered, periodic
+		// samples for one connection. CollectHostStats stays independent, while a
+		// reconnect automatically receives a clean counter baseline.
+		previousNetworkSample = applyNetworkThroughput(stats.WiFi, previousNetworkSample)
 		msg := hostStatsMessage{
 			Type:      "hostStats",
 			Timestamp: time.Now().UnixMilli(),
-			Stats:     CollectHostStats(ctx),
+			Stats:     stats,
 		}
 		if err := writeJSON(ctx, conn, msg); err != nil {
 			c.log.Printf("host stats send failed: %v", err)

pi/systemd/audio-forward-listener.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=Rover Audio Forward Listener (SRT -> ALSA)
+Description=Rover Audio Forward Listener (RTSP/TCP -> ALSA)
 After=network-online.target roverd.service
 Wants=network-online.target
 

pi/systemd/audio-only-publisher.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=Rover Audio Publisher (ALSA -> SRT)
+Description=Rover Audio Publisher (ALSA -> RTSP/TCP)
 After=network-online.target roverd.service
 Wants=network-online.target
 

pi/systemd/debian-laptop-video-publisher.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=Rover Debian Laptop Video Publisher (V4L2 -> SRT)
+Description=Rover Debian Laptop Video Publisher (V4L2 -> RTSP/TCP)
 After=network-online.target roverd.service
 Wants=network-online.target
 

pi/systemd/roverd.service

@@ -1,6 +1,6 @@
 [Unit]
 Description=Multi-Roomba rover control agent
-After=network-online.target mediamtx.service
+After=network-online.target
 Wants=network-online.target
 
 [Service]

pi/systemd/video-publisher.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=Rover Video Publisher (libcamera -> SRT)
+Description=Rover Video Publisher (libcamera -> RTSP/TCP)
 After=network-online.target roverd.service
 Wants=network-online.target
 

plans/toggleable bandwidth savings.md

@@ -7,8 +7,9 @@
   - not allowed
 - snapshots
   - non-turn video
-    - snapshots (rover non-active turn holders and PTZ non-operators see snapshots)
+    - snapshots (rover non-active turn holders and PTZ non-operators see snapshots after the user threshold is exceeded)
     - live (rover non-active turn holders and PTZ non-operators can get full video)
+    - userThreshold (snapshots turn on when controllable users exceed this number)
   - external spectator video
     - snapshots (external spectators are only allowed snapshots)
     - live (external spectators can get full video)
@@ -23,7 +24,9 @@
 ```yaml
 bandwidthSavings:
   multiTabProtection: "verifiedOnly" # allowed | verifiedOnly | notAllowed
-  nonTurnVideo: "snapshots" # snapshots | live
+  nonTurnVideo:
+    mode: "snapshots" # snapshots | live
+    userThreshold: 0 # snapshots turn on when controllable users exceed this number
   externalSpectatorVideo: "snapshots" # snapshots | live
   externalSpectatorAccess: "on" # off | on | verifiedOnly | admin
 ```

server/config.example.yaml

@@ -51,8 +51,15 @@ barcodeGames:
 media:
   # Base address for mediaMTX (scheme + host + optional port/path). The UI will always request
   #   http://<base>/<roverId>/whep
-  # Example: http://192.168.0.86:8889/video
+  # Example: http://media-server.local:8889/video
-  whepBaseUrl: "http://192.168.0.86:8889/video"
+  whepBaseUrl: "http://media-server.local:8889/video"
+  # MediaMTX advertises these instance-specific DNS names or IP addresses as WebRTC ICE
+  # candidates. Include every public and LAN address browsers use to reach this server.
+  # The server generates MediaMTX's runtime configuration from this list; never edit a
+  # separate mediamtx.yml for a new installation.
+  additionalHosts:
+    - "rover.example.com"
+    - "media-server.local"
 
 bandwidthSavings:
   # Duplicate driver-tab handling for the same browser identity.
@@ -60,10 +67,21 @@ bandwidthSavings:
   #   verifiedOnly: verified/admin users may keep multiple driver tabs; unverified users may not
   #   notAllowed: every identity is limited to one driver tab
   multiTabProtection: "verifiedOnly"
-  # Live video for users who are attached to a source but do not currently own
+  # Disconnect rover video when its player is outside the viewport or the web
-  # its active turn. "snapshots" saves upload bandwidth; "live" allows full
+  # page is in a background browser tab. Rover audio is a separate stream and
-  # video whenever the normal mode/visibility rules allow it.
+  # remains connected. /mini intentionally keeps its existing always-warm video
-  nonTurnVideo: "snapshots"
+  # behavior regardless of this option.
+  pauseHiddenRoverVideo: false
+  # Video for users who are attached to a source but do not currently own its
+  # active turn. "snapshots" saves upload bandwidth; "live" allows full video
+  # whenever the normal mode/visibility rules allow it.
+  nonTurnVideo:
+    mode: "snapshots"
+    # Snapshot mode activates only when controllable users exceed this number.
+    # A controllable user is attached to a rover or PTZ as operator/queue, not a
+    # plain spectator. 0 preserves always-on non-turn snapshots once anyone is
+    # actually attached to a controllable source.
+    userThreshold: 0
   # Live video for spectators outside the local network. Local spectators are
   # not restricted by this switch because LAN traffic is not the upload limit.
   externalSpectatorVideo: "snapshots"
@@ -171,6 +189,11 @@ kinect:
   # camera cache; it only gates browser-requested broadcasts.
   captureCooldownMs: 10000
 
+balanceBoard:
+  # The server installer always prepares Bluetooth and the kernel driver. This
+  # switch only starts the service and shows its small live-weight panel.
+  enabled: false
+
 buttonBox:
   enabled: false
 
@@ -216,3 +239,35 @@ socials:
       url: "https://ko-fi.com/your-handle"
       icon: "FaCoffee"
       color: "#29ABE0"
+
+# Optional trusted HTML card shown at the bottom of the desktop driver page's
+# left column. Leave html empty (or omit this section) to hide the card. This
+# content is sent to driver browsers without sanitization, so only place markup
+# here that is controlled by the server operator.
+driverAd:
+  title: "Advertisement"
+  html: |
+    <a href="https://example.com" target="_blank" rel="noopener noreferrer">
+      <img src="https://example.com/ad.png" alt="Advertisement" style="display:block;width:100%;height:auto;">
+    </a>
+
+# Optional passive fleet telemetry, history, and daily reporting. The collector
+# observes existing server events and rover sensor frames but never participates
+# in command, assignment, docking, or safety decisions.
+fleetReports:
+  enabled: false
+  retention:
+    # Zero retains evidence indefinitely. Set explicit day counts on servers
+    # that prefer bounded storage over complete long-term history.
+    detailedDays: 0
+    minuteSamplesDays: 0
+  battery:
+    enabled: true
+    maximumIntegrationGapSeconds: 5
+    minimumCapacityTestDepthPercent: 60
+  discord:
+    enabled: true
+    sendAt: "08:00"
+    timezone: "America/New_York"
+  privacy:
+    retainChatBodies: true

server/data/analytics.umami.example.html

@@ -0,0 +1,21 @@
+<!--
+  Umami example for the optional provider-neutral rover analytics bridge.
+
+  Copy this file to analytics.html in the same data directory, replace the
+  example URLs and attributes, and restart the server. The server injects the
+  copied file into every web UI entry page; this example filename is not loaded
+  automatically.
+-->
+<script defer src="https://analytics.example.com/script.js" data-website-id="replace-with-website-id" data-domains="rover.example.com"></script>
+<script defer src="https://analytics.example.com/recorder.js" data-website-id="replace-with-website-id" data-domains="rover.example.com" data-sample-rate="0.15" data-mask-level="moderate" data-max-duration="300000"></script>
+
+<script>
+  window.roverAnalytics = {
+    track: function (name, data) {
+      window.umami?.track(name, data);
+    },
+    identify: function (data) {
+      window.umami?.identify(data);
+    },
+  };
+</script>

server/index.js

@@ -28,6 +28,7 @@ require('./src/services/serverControlService');
 require('./src/services/videoSessions');
 require('./src/services/ptzCameraService');
 require('./src/services/videoAuthService');
+require('./src/services/mediaMtxService');
 require('./src/services/videoSocketService');
 require('./src/services/roomCameraService');
 require('./src/services/roverSnapshotService');
@@ -46,8 +47,13 @@ require('./src/services/buttonBoxService');
 require('./src/services/barcodeScannerService');
 require('./src/services/barcodeGameService');
 require('./src/services/kinectService');
+require('./src/services/balanceBoardService');
 require('./src/services/sessionService');
 require('./src/services/batteryManager');
+// Fleet reporting starts after the rover and battery services so its passive
+// subscriptions see fully decoded state without becoming an initialization
+// dependency of either control path.
+require('./src/services/fleetReportService');
 require('./src/services/replayEngineV2');
 // Replay delivery is a core service. It must subscribe before the optional
 // Discord feature so web requests always have a local delivery path.

server/install_server.sh

@@ -8,14 +8,14 @@ NEOLINK_BASE_URL="https://github.com/QuantumEntangledAndy/neolink/releases/downl
 MEDIAMTX_BIN="/usr/local/bin/mediamtx"
 NEOLINK_BIN="/usr/local/bin/neolink"
 CHROMEGTTS_WAV_BIN="/usr/local/bin/chromegtts-wav"
-MEDIAMTX_CONF_DIR="/etc/mediamtx"
-MEDIAMTX_CONFIG="$MEDIAMTX_CONF_DIR/mediamtx.yml"
 ROVER_SNAPSHOT_WRITER_BIN="/usr/local/bin/rover-snapshot-writer.sh"
 MEDIAMTX_SERVICE="/etc/systemd/system/mediamtx.service"
 MULTIROVER_SERVICE="/etc/systemd/system/multirover.service"
 SNAPSHOT_DIR="/var/lib/rover-snapshots"
 REPLAY_SEGMENT_DIR="/var/lib/replay-segments"
 KINECT_UDEV_RULE="/etc/udev/rules.d/99-kinect-world.rules"
+BLUETOOTH_OVERRIDE_DIR="/etc/systemd/system/bluetooth.service.d"
+BLUETOOTH_OVERRIDE="$BLUETOOTH_OVERRIDE_DIR/20-multirover-balance-board.conf"
 
 if [[ $EUID -ne 0 ]]; then
   echo "This installer must be run with sudo/root." >&2
@@ -30,8 +30,9 @@ fi
 TARGET_USER="$SUDO_USER"
 SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
 SERVER_DIR="$SCRIPT_DIR"
+BALANCE_BOARD_NATIVE_DIR="$SCRIPT_DIR/src/services/balanceBoardService/native"
+BALANCE_BOARD_WORKER="$BALANCE_BOARD_NATIVE_DIR/balance_board_worker"
 CONFIG_PATH="$SERVER_DIR/config.yaml"
-MEDIAMTX_TEMPLATE="$SERVER_DIR/mediamtx/mediamtx.yml"
 ROVER_SNAPSHOT_WRITER_TEMPLATE="$SERVER_DIR/mediamtx/rover-snapshot-writer.sh"
 CHROMEGTTS_WAV_TEMPLATE="$SERVER_DIR/bin/chromegtts-wav.py"
 
@@ -134,7 +135,11 @@ dnf install -y \
   gstreamer1-rtsp-server \
   libfreenect \
   libfreenect-devel \
-  libusb1-devel >/dev/null
+  libusb1-devel \
+  bluez \
+  wiiuse \
+  wiiuse-devel \
+  libcap >/dev/null
 NODE_BIN="$(command -v node)"
 
 echo "      Installing Kinect udev rule -> $KINECT_UDEV_RULE"
@@ -166,12 +171,43 @@ if [[ -f "$SERVER_DIR/src/services/kinectService/native/Makefile" ]]; then
   runuser -u "$TARGET_USER" -- bash -c "cd '$SERVER_DIR/src/services/kinectService/native' && make"
 fi
 
+if [[ -f "$BALANCE_BOARD_NATIVE_DIR/Makefile" ]]; then
+  echo "      Building native Balance Board bridge..."
+  runuser -u "$TARGET_USER" -- bash -c "cd '$BALANCE_BOARD_NATIVE_DIR' && make"
+  if [[ ! -x "$BALANCE_BOARD_WORKER" ]]; then
+    echo "Balance Board worker build did not create $BALANCE_BOARD_WORKER" >&2
+    exit 1
+  fi
+  # Only this small audited bridge needs the management socket used for the
+  # board's raw six-byte pairing PIN and the two reserved HID PSMs used by
+  # front-button reconnects. Never grant either capability to node or the full
+  # multirover service executable.
+  setcap cap_net_admin,cap_net_bind_service+ep "$BALANCE_BOARD_WORKER"
+fi
+
 if [[ ! -f "$CONFIG_PATH" ]]; then
   cp "$SERVER_DIR/config.example.yaml" "$CONFIG_PATH"
   chown "$TARGET_USER":"$TARGET_USER" "$CONFIG_PATH"
   echo "Copied config.example.yaml to config.yaml; edit it before exposing the service."
 fi
 
+# Bluetoothd remains responsible for discovery and the one-time bond, but its
+# generic input plugin otherwise reserves control PSM 0x11 and interrupt PSM
+# 0x13 before the Balance Board worker can listen for the board's front-button
+# reconnect. This dedicated rover server gives those two HID listeners to the
+# worker; every other BlueZ profile is left enabled. Clearing ExecStart is
+# required by systemd before replacing the vendor unit's command in a drop-in.
+install -d -m 0755 "$BLUETOOTH_OVERRIDE_DIR"
+cat > "$BLUETOOTH_OVERRIDE" <<'EOF'
+[Service]
+ExecStart=
+ExecStart=/usr/libexec/bluetooth/bluetoothd --noplugin=input
+EOF
+chmod 0644 "$BLUETOOTH_OVERRIDE"
+systemctl daemon-reload
+systemctl enable bluetooth.service
+systemctl restart bluetooth.service
+
 tmpdir=$(mktemp -d)
 trap 'rm -rf "$tmpdir"' EXIT
 
@@ -220,54 +256,40 @@ if ! verify_google_tts_helper; then
   verify_google_tts_helper
 fi
 
-mkdir -p "$MEDIAMTX_CONF_DIR"
-if [[ ! -f "$MEDIAMTX_TEMPLATE" ]]; then
-  echo "mediaMTX template missing at $MEDIAMTX_TEMPLATE" >&2
-  exit 1
-fi
 if [[ ! -f "$ROVER_SNAPSHOT_WRITER_TEMPLATE" ]]; then
   echo "Snapshot writer template missing at $ROVER_SNAPSHOT_WRITER_TEMPLATE" >&2
   exit 1
 fi
-if [[ -f "$MEDIAMTX_CONFIG" ]]; then
-  echo "      Preserving existing mediaMTX config -> $MEDIAMTX_CONFIG"
-else
-  echo "      Installing mediaMTX config -> $MEDIAMTX_CONFIG"
-  install -m 0644 "$MEDIAMTX_TEMPLATE" "$MEDIAMTX_CONFIG"
-fi
 echo "      Installing rover snapshot writer -> $ROVER_SNAPSHOT_WRITER_BIN"
 install -m 0755 "$ROVER_SNAPSHOT_WRITER_TEMPLATE" "$ROVER_SNAPSHOT_WRITER_BIN"
-chown -R "$TARGET_USER":"$TARGET_USER" "$MEDIAMTX_CONF_DIR"
+
+# Validate the new source of truth before disabling a working legacy service. The validator
+# performs the same build and YAML serialization as server startup without opening listeners
+# or leaving a process behind.
+runuser -u "$TARGET_USER" -- env \
+  SERVER_CONFIG="$CONFIG_PATH" \
+  ROVER_SNAPSHOT_WRITER_BIN="$ROVER_SNAPSHOT_WRITER_BIN" \
+  "$NODE_BIN" "$SERVER_DIR/scripts/validateMediaMtxConfig.js"
+
+# MediaMTX used to run as its own systemd service with a hand-maintained config in
+# /etc/mediamtx. Stop it before multirover starts the new child process, otherwise the two
+# processes race for every media listener. Both commands are deliberately idempotent so an
+# already-migrated server and a first-time installation follow the same path.
+echo "      Disabling legacy mediamtx.service"
+systemctl disable --now mediamtx.service 2>/dev/null || true
+rm -f "$MEDIAMTX_SERVICE"
+rm -f /etc/mediamtx/mediamtx.yml
 
 echo "[4/6] Writing systemd units..."
 mkdir -p "$SNAPSHOT_DIR"
 chown "$TARGET_USER":"$TARGET_USER" "$SNAPSHOT_DIR"
 mkdir -p "$REPLAY_SEGMENT_DIR"
 chown "$TARGET_USER":"$TARGET_USER" "$REPLAY_SEGMENT_DIR"
-cat > "$MEDIAMTX_SERVICE" <<EOF
-[Unit]
-Description=mediaMTX WebRTC Server
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-User=$TARGET_USER
-Group=$TARGET_USER
-WorkingDirectory=$MEDIAMTX_CONF_DIR
-Environment=ROVER_SNAPSHOT_DIR=$SNAPSHOT_DIR
-ExecStart=$MEDIAMTX_BIN $MEDIAMTX_CONFIG
-Restart=on-failure
-RestartSec=2
-
-[Install]
-WantedBy=multi-user.target
-EOF
-
 cat > "$MULTIROVER_SERVICE" <<EOF
 [Unit]
 Description=Multi-Roomba Rover control server
-After=network-online.target mediamtx.service
+After=network-online.target bluetooth.service
-Wants=network-online.target
+Wants=network-online.target bluetooth.service
 
 [Service]
 User=$TARGET_USER
@@ -277,6 +299,9 @@ Environment=NODE_ENV=production
 Environment=SERVER_CONFIG=$CONFIG_PATH
 Environment=ROVER_SNAPSHOT_DIR=$SNAPSHOT_DIR
 Environment=REPLAY_SEGMENT_DIR=$REPLAY_SEGMENT_DIR
+Environment=ROVER_SNAPSHOT_WRITER_BIN=$ROVER_SNAPSHOT_WRITER_BIN
+RuntimeDirectory=multirover
+RuntimeDirectoryMode=0750
 ExecStart=$NODE_BIN $SERVER_DIR/index.js
 Restart=on-failure
 RestartSec=2
@@ -286,21 +311,20 @@ SuccessExitStatus=130 143
 WantedBy=multi-user.target
 EOF
 
-chmod 644 "$MEDIAMTX_SERVICE" "$MULTIROVER_SERVICE"
+chmod 644 "$MULTIROVER_SERVICE"
 
 echo "[5/6] Enabling services..."
 systemctl daemon-reload
-systemctl enable --now mediamtx.service
 systemctl enable --now multirover.service
-systemctl restart mediamtx.service
 systemctl restart multirover.service
 
 echo "[6/6] Done."
 echo
 echo "Services installed:"
-echo "  mediamtx.service (WebRTC fan-out)"
+echo "  multirover.service (Node.js control server with MediaMTX child)"
-echo "  multirover.service (Node.js control server)"
 echo
 echo "Update $CONFIG_PATH to set admins, lockdown settings, and media parameters."
 echo "Kinect/libfreenect packages and udev permissions were installed."
 echo "If a Kinect is already plugged in, unplug/replug its USB/power before testing so the new udev rule applies."
+echo "Wii Balance Board direct Bluetooth bridge and front-button listener were installed."
+echo "Enable balanceBoard in config.yaml, press red Sync once, then use the front button for later wakes."

server/mediamtx/mediamtx.yml

@@ -1,47 +0,0 @@
-# Managed by install_server.sh; edit server/mediamtx/mediamtx.yml and rerun the installer.
-logLevel: info
-
-api: yes
-apiAddress: 0.0.0.0:9997
-metrics: yes
-metricsAddress: 0.0.0.0:9998
-pprof: no
-pprofAddress: 127.0.0.1:9999
-
-rtsp: no
-rtmp: no
-hls: no
-
-webrtc: yes
-webrtcLocalUDPAddress: :8189
-webrtcLocalTCPAddress: :8189
-webrtcAdditionalHosts: ['rover.otter.land', '192.168.0.100']
-webrtcICEServers2:
-  # Google public STUN (world-wide, very commonly used)
-  - url: stun:stun.l.google.com:19302
-  - url: stun:stun1.l.google.com:19302
-  - url: stun:stun2.l.google.com:19302
-  - url: stun:stun3.l.google.com:19302
-  - url: stun:stun4.l.google.com:19302
-
-  # Cloudflare STUN (anycast, global PoPs)
-  - url: stun:stun.cloudflare.com:3478
-
-srt: yes
-srtAddress: :9000
-
-authMethod: http
-authHTTPAddress: http://127.0.0.1:8080/mediamtx/auth
-authHTTPExclude:
-  - action: api
-  - action: metrics
-  - action: pprof
-
-paths:
-  all:
-    source: publisher
-    sourceOnDemand: no
-    # Rover Snapshot Writer
-    # Keep rover snapshots continuously updated while a rover video path is live.
-    runOnReady: /usr/local/bin/rover-snapshot-writer.sh
-    runOnReadyRestart: yes

server/package.json

@@ -16,6 +16,7 @@
     "home-assistant-js-websocket": "^3.1.2",
     "js-yaml": "^4.1.1",
     "kokoro-js": "^1.2.1",
+    "luxon": "^3.7.2",
     "morgan": "^1.10.0",
     "obscenity": "^0.4.6",
     "ollama": "^0.6.3",

server/public/index.html

@@ -4,82 +4,16 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/png" href="/bitmap.png" />
     <link rel="apple-touch-icon" href="/bitmap.png" />
-    <link rel="manifest" href="/manifest.json" />
+    <!-- The server renders this manifest so installed shortcuts use the local instance's configured branding. -->
+    <link rel="manifest" href="/manifest.webmanifest" />
     <!-- Mobile driving uses dense press controls, so the viewport opts out of browser zoom gestures that can steal touches from the controls. -->
     <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
-    <meta name="theme-color" content="#020617" />
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
-    <meta name="apple-mobile-web-app-title" content="Roomba Rover" />
+    <!-- site-metadata:inject -->
-    <!-- place analytics tags here and they will be injected into <head> of index.html at build time of the web UI. -->
+    <!-- analytics:inject -->
-<!-- these tags are loaded PAGE-WIDE, this means /, /spectate, /mini, etc. -->
+    <script type="module" crossorigin src="/assets/index-C7V6I437.js"></script>
-
+    <link rel="stylesheet" crossorigin href="/assets/index-7PpZTwSc.css">
-<script>
-  /*
-    Build-time analytics adapter for the rover UI.
-
-    React only calls window.roverAnalytics.track/identify. Keeping the Umami
-    adapter here means analytics can still be removed, replaced, or configured
-    by changing this injected file instead of rebuilding app logic around a
-    specific analytics provider.
-  */
-  (function () {
-    var pendingCalls = [];
-    var flushTimer = null;
-
-    function callUmami(method, args) {
-      if (!window.umami || typeof window.umami[method] !== 'function') return false;
-      window.umami[method].apply(window.umami, args);
-      return true;
-    }
-
-    function flushPendingCalls() {
-      if (!pendingCalls.length) return;
-      if (!window.umami) return;
-
-      pendingCalls = pendingCalls.filter(function (call) {
-        return !callUmami(call.method, call.args);
-      });
-
-      if (!pendingCalls.length && flushTimer) {
-        window.clearInterval(flushTimer);
-        flushTimer = null;
-      }
-    }
-
-    function enqueue(method, args) {
-      if (callUmami(method, args)) return;
-      pendingCalls.push({ method: method, args: args });
-
-      /*
-        The React app may fire route/session events before Umami's deferred
-        script has executed. Queueing preserves those early events while still
-        letting the whole adapter no-op harmlessly if the script is blocked.
-      */
-      if (!flushTimer) {
-        flushTimer = window.setInterval(flushPendingCalls, 500);
-      }
-    }
-
-    window.roverAnalytics = {
-      track: function (name, data) {
-        enqueue('track', typeof data === 'undefined' ? [name] : [name, data]);
-      },
-      identify: function (data) {
-        enqueue('identify', [data || {}]);
-      },
-    };
-
-    window.addEventListener('load', flushPendingCalls);
-  })();
-</script>
-
-<!-- otterlytics testing for blocking local -->
-<script defer src="https://analytics.otter.land/script.js" data-website-id="82dd56a5-db44-4279-bd1e-a4d9fee39af7" data-domains="rover.otter.land"></script>
-<script defer src="https://analytics.otter.land/recorder.js" data-website-id="82dd56a5-db44-4279-bd1e-a4d9fee39af7" data-domains="rover.otter.land" data-sample-rate="0.15" data-mask-level="moderate" data-max-duration="300000"></script>
-    <title>Roomba Rover</title>
-    <script type="module" crossorigin src="/assets/index-B8ElczOE.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-ZpgWUPKf.css">
   </head>
   <body>
     <div id="root"></div>

server/public/manifest.json

@@ -1,18 +0,0 @@
-{
-  "name": "Multi Roomba Rover",
-  "short_name": "MRR",
-  "description": "Remote driving interface for the MultiRoomba Rover fleet.",
-  "start_url": "/",
-  "scope": "/",
-  "display": "standalone",
-  "background_color": "#000000",
-  "theme_color": "#020617",
-  "icons": [
-    {
-      "src": "/bitmap.png",
-      "sizes": "512x512",
-      "type": "image/png",
-      "purpose": "any"
-    }
-  ]
-}

server/scripts/validateMediaMtxConfig.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// MediaMTX Configuration Validator
+// Purpose: Lets the installer validate server-owned MediaMTX inputs before disabling the legacy service.
+// Scope: Builds and serializes the runtime YAML without starting MediaMTX or changing external state.
+const yaml = require('js-yaml');
+const { loadConfig } = require('../src/helpers/configLoader');
+const { buildMediaMtxConfig } = require('../src/services/mediaMtxService/config');
+
+const config = loadConfig();
+const generated = buildMediaMtxConfig({
+  config,
+  serverPort: process.env.PORT || 8080,
+  snapshotWriterPath: process.env.ROVER_SNAPSHOT_WRITER_BIN || '/usr/local/bin/rover-snapshot-writer.sh',
+});
+
+/*
+  Serializing is part of validation: it catches values that the builder accepted but js-yaml
+  cannot represent before the installer removes the previous service configuration.
+*/
+yaml.dump(generated, { noRefs: true, lineWidth: 120 });
+process.stdout.write('MediaMTX server configuration is valid\n');

server/src/helpers/bandwidthSavings.js

@@ -10,7 +10,11 @@ const EXTERNAL_SPECTATOR_ACCESS_MODES = new Set(['off', 'on', 'verifiedOnly', 'a
 
 const DEFAULT_BANDWIDTH_SAVINGS = Object.freeze({
   multiTabProtection: 'verifiedOnly',
-  nonTurnVideo: 'snapshots',
+  pauseHiddenRoverVideo: false,
+  nonTurnVideo: Object.freeze({
+    mode: 'snapshots',
+    userThreshold: 0,
+  }),
   externalSpectatorVideo: 'snapshots',
   externalSpectatorAccess: 'on',
 });
@@ -25,6 +29,32 @@ function normalizeEnum(value, allowed, fallback) {
   return allowed.has(normalized) ? normalized : fallback;
 }
 
+function normalizeBoolean(value, fallback) {
+  /*
+    YAML booleans must stay real booleans. Treating strings such as "false" as
+    truthy would silently enable a bandwidth policy that the operator intended
+    to disable, so invalid values fall back to the documented server default.
+  */
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function normalizeNonTurnVideo(value) {
+  const raw = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const threshold = Number(raw.userThreshold);
+  /*
+    userThreshold is intentionally "greater than", not "greater than or equal".
+    A value of 4 means the first four controllable users can keep live non-turn
+    video, and the fifth controllable user activates snapshot saving. Invalid
+    or negative values fall back to zero, which preserves always-on snapshots
+    for any real non-turn participant.
+  */
+  const userThreshold = Number.isFinite(threshold) ? Math.max(0, Math.floor(threshold)) : 0;
+  return {
+    mode: normalizeEnum(raw.mode, VIDEO_MODES, DEFAULT_BANDWIDTH_SAVINGS.nonTurnVideo.mode),
+    userThreshold,
+  };
+}
+
 function buildBandwidthSavingsPolicy(config = loadConfig()) {
   const raw = config.bandwidthSavings || {};
   return {
@@ -33,11 +63,11 @@ function buildBandwidthSavingsPolicy(config = loadConfig()) {
       MULTI_TAB_MODES,
       DEFAULT_BANDWIDTH_SAVINGS.multiTabProtection,
     ),
-    nonTurnVideo: normalizeEnum(
+    pauseHiddenRoverVideo: normalizeBoolean(
-      raw.nonTurnVideo,
+      raw.pauseHiddenRoverVideo,
-      VIDEO_MODES,
+      DEFAULT_BANDWIDTH_SAVINGS.pauseHiddenRoverVideo,
-      DEFAULT_BANDWIDTH_SAVINGS.nonTurnVideo,
     ),
+    nonTurnVideo: normalizeNonTurnVideo(raw.nonTurnVideo),
     externalSpectatorVideo: normalizeEnum(
       raw.externalSpectatorVideo,
       VIDEO_MODES,
@@ -72,8 +102,16 @@ function shouldEnforceSingleDriverTab({ isVerified = false, isAdmin = false } =
   return !isVerified && !isAdmin;
 }
 
-function shouldUseSnapshotsForNonTurnVideo() {
+function shouldUseSnapshotsForNonTurnVideo({ controllableUserCount = 0 } = {}) {
-  return getBandwidthSavingsPolicy().nonTurnVideo === 'snapshots';
+  const { nonTurnVideo } = getBandwidthSavingsPolicy();
+  if (nonTurnVideo.mode !== 'snapshots') return false;
+  /*
+    The threshold is evaluated centrally so MediaMTX auth, socket-issued video
+    tokens, PTZ authorization, and browser session state all agree. Using a
+    strict greater-than comparison makes the configured value read like the
+    maximum number of controllable users allowed before snapshots start.
+  */
+  return Math.max(0, Number(controllableUserCount) || 0) > nonTurnVideo.userThreshold;
 }
 
 function shouldUseSnapshotsForExternalSpectatorVideo() {

server/src/helpers/features.js

@@ -46,11 +46,13 @@ function buildFeatureFlags(config = loadConfig()) {
   const kinectConfig = config.kinect || {};
   const buttonBoxConfig = config.buttonBox || {};
   const barcodeScannerConfig = config.barcodeScanner || {};
+  const balanceBoardConfig = config.balanceBoard || {};
   const barcodeGamesConfig = config.barcodeGames || {};
   const socialsConfig = config.socials || {};
   const interInstanceConfig = config.interInstance || {};
   const ptzCameraConfig = config.ptzCamera || {};
   const discordConfig = config.discord || {};
+  const fleetReportsConfig = config.fleetReports || {};
   const homeAssistant = Boolean(
     asBoolean(homeAssistantConfig.enabled) &&
       asTrimmedString(homeAssistantConfig.url) &&
@@ -68,6 +70,10 @@ function buildFeatureFlags(config = loadConfig()) {
     kinect: asBoolean(kinectConfig.enabled),
     buttonBox: asBoolean(buttonBoxConfig.enabled),
     barcodeScanner,
+    // The worker performs its own runtime availability reporting. Advertising
+    // the feature from the explicit config switch lets the UI show useful
+    // commissioning and hardware-error states even before a board is paired.
+    balanceBoard: asBoolean(balanceBoardConfig.enabled),
     barcodeGames: Boolean(barcodeScanner && asBoolean(barcodeGamesConfig.enabled)),
     lift: Boolean(
       homeAssistant &&
@@ -95,6 +101,11 @@ function buildFeatureFlags(config = loadConfig()) {
       to run without the integration.
     */
     discord: Boolean(asBoolean(discordConfig.enabled) && asTrimmedString(discordConfig.token)),
+    // Fleet reports are deliberately controlled by one explicit server switch.
+    // Storage contents, Discord availability, or historical database files must
+    // never cause the reporting UI to appear on an installation that has not
+    // opted into the collector.
+    fleetReports: asBoolean(fleetReportsConfig.enabled),
   };
 }
 

server/src/helpers/siteMetadata.js

@@ -0,0 +1,120 @@
+// Site Metadata Helper
+// Purpose: Resolves the public name, description, and colors used before the web UI starts.
+// Scope: Keeps document/PWA branding server-rendered and independent of Socket.IO session state.
+const { loadConfig } = require('./configLoader');
+
+const DEFAULT_SITE_METADATA = Object.freeze({
+  name: 'Multi Roomba Rover',
+  shortName: 'Multi Roomba Rover',
+  description: 'Drive and watch remote rovers from your browser.',
+  accentColor: '#38bdf8',
+  backgroundColor: '#020617',
+  publicUrl: null,
+});
+
+const BACKGROUND_BLEND_AMOUNT = 0.15;
+
+function asTrimmedString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeHexColor(value) {
+  const color = asTrimmedString(value).toLowerCase();
+
+  /*
+    Supporting both common CSS hex forms keeps the operator-facing setting
+    forgiving while still preventing arbitrary CSS from being injected into
+    generated HTML and SVG attributes.
+  */
+  if (/^#[0-9a-f]{6}$/.test(color)) return color;
+  if (/^#[0-9a-f]{3}$/.test(color)) {
+    return `#${color.slice(1).split('').map((character) => character.repeat(2)).join('')}`;
+  }
+  return null;
+}
+
+function blendHexColors(baseColor, accentColor, accentAmount) {
+  const base = baseColor.slice(1).match(/.{2}/g).map((channel) => Number.parseInt(channel, 16));
+  const accent = accentColor.slice(1).match(/.{2}/g).map((channel) => Number.parseInt(channel, 16));
+
+  /*
+    The profile color is deliberately only a tint. A full-strength profile
+    color could produce a glaring PWA launch screen, while this blend preserves
+    the application's established dark appearance and still makes each server
+    visually recognizable.
+  */
+  const channels = base.map((channel, index) =>
+    Math.round(channel * (1 - accentAmount) + accent[index] * accentAmount),
+  );
+  return `#${channels.map((channel) => channel.toString(16).padStart(2, '0')).join('')}`;
+}
+
+function normalizePublicUrl(value) {
+  const candidate = asTrimmedString(value);
+  if (!candidate) return null;
+
+  /*
+    URL() helpfully repairs strings such as `http:192.168.0.1`, but preserving
+    that typo in public metadata would conceal a configuration mistake. Require
+    the conventional absolute URL form so the published address is explicit.
+  */
+  if (!/^https?:\/\//i.test(candidate)) return null;
+
+  try {
+    const url = new URL(candidate);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+
+    /*
+      Removing a trailing slash gives callers one stable base URL to combine
+      with paths. Invalid values are ignored instead of producing broken
+      canonical and social metadata on every page.
+    */
+    return url.toString().replace(/\/$/, '');
+  } catch {
+    return null;
+  }
+}
+
+function getReadableAccentText(accentColor) {
+  const channels = accentColor.slice(1).match(/.{2}/g).map((channel) => Number.parseInt(channel, 16));
+  const luminance = (channels[0] * 299 + channels[1] * 587 + channels[2] * 114) / 1000;
+
+  // A simple luminance split keeps the generated preview badge legible for both dark and light profile colors.
+  return luminance > 150 ? '#020617' : '#ffffff';
+}
+
+function resolveSiteMetadata(config = loadConfig()) {
+  const interInstance = config?.interInstance;
+  const profile = interInstance?.profile;
+  const profileName = asTrimmedString(profile?.name);
+
+  /*
+    A partially filled profile must not unexpectedly rename the site. The
+    inter-instance feature must be explicitly enabled and have a usable name
+    before any profile branding is applied; otherwise every value comes from
+    the coherent default set above.
+  */
+  if (interInstance?.enabled !== true || !profileName) {
+    return { ...DEFAULT_SITE_METADATA, accentTextColor: getReadableAccentText(DEFAULT_SITE_METADATA.accentColor) };
+  }
+
+  const accentColor = normalizeHexColor(profile.color) || DEFAULT_SITE_METADATA.accentColor;
+  return {
+    name: profileName,
+    shortName: profileName,
+    description: asTrimmedString(profile.description) || DEFAULT_SITE_METADATA.description,
+    accentColor,
+    backgroundColor: blendHexColors(
+      DEFAULT_SITE_METADATA.backgroundColor,
+      accentColor,
+      BACKGROUND_BLEND_AMOUNT,
+    ),
+    accentTextColor: getReadableAccentText(accentColor),
+    publicUrl: normalizePublicUrl(profile.publicUrl),
+  };
+}
+
+module.exports = {
+  DEFAULT_SITE_METADATA,
+  resolveSiteMetadata,
+};

server/src/services/audioForwardService/bonkSound.js

@@ -0,0 +1,55 @@
+// audio Forward Service bonk sound
+// Purpose: Plays the built-in bonk sound effect on the rover a bonked user is driving.
+// Scope: Keeps the fun commands and the audio pipeline decoupled by listening to the server event bus only.
+const path = require('path');
+const fs = require('fs');
+const { subscribe } = require('../eventBus');
+
+/*
+  Lives in server/assets rather than server/public because the webui build writes
+  to server/public with emptyOutDir enabled, which deletes anything else in there.
+  server/assets is a plain checked-in asset directory that no build step touches.
+*/
+const BONK_SOUND_PATH = path.resolve(__dirname, '..', '..', '..', 'assets', 'bonk.wav');
+
+function registerBonkSound(deps) {
+  const {
+    logger,
+    playServerAudioFile,
+    soundPath = BONK_SOUND_PATH,
+  } = deps;
+
+  subscribe('fun.bonked', (event = {}) => {
+    const roverId = String(event?.payload?.roverId || '').trim();
+    if (!roverId) return;
+
+    /*
+      The sound is optional. An operator who has not dropped a bonk.wav into
+      server/assets still gets a fully working `rs bonk` command, so a missing
+      file is reported once at debug volume rather than thrown at the caller.
+    */
+    if (!fs.existsSync(soundPath)) {
+      logger.info('Bonk sound file is not installed; skipping playback', { soundPath });
+      return;
+    }
+
+    try {
+      playServerAudioFile(roverId, soundPath, { source: 'bonk' });
+      logger.info('Played bonk sound', { roverId, soundPath });
+    } catch (err) {
+      // Playback interrupts mic forwarding and spawns ffmpeg, so an offline rover
+      // or a missing encoder must not turn into a failed chat command. The bonk
+      // itself already happened; the sound is layered on top of it.
+      logger.warn('Failed to play bonk sound', {
+        roverId,
+        soundPath,
+        error: err?.message || String(err),
+      });
+    }
+  });
+}
+
+module.exports = {
+  registerBonkSound,
+  BONK_SOUND_PATH,
+};

server/src/services/audioForwardService/bonkSound.test.js

@@ -0,0 +1,84 @@
+// audio Forward Service bonk sound tests
+// Purpose: Verifies the bonk cue plays for a real event and stays contained when the file or rover is missing.
+// Scope: Subscribes through the real event bus with a playback double; no ffmpeg runs.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { publishEvent } = require('../eventBus');
+const { registerBonkSound, BONK_SOUND_PATH } = require('./bonkSound');
+
+const soundDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bonk-sound-test-'));
+const presentSound = path.join(soundDir, 'bonk.wav');
+fs.writeFileSync(presentSound, 'not really audio, only the path is read here');
+const missingSound = path.join(soundDir, 'absent.wav');
+
+function harness({ soundPath = presentSound, playImpl = null } = {}) {
+  const played = [];
+  const warnings = [];
+  registerBonkSound({
+    logger: {
+      info: () => {},
+      warn: (message, meta) => warnings.push({ message, meta }),
+    },
+    playServerAudioFile: (roverId, filePath, options) => {
+      played.push({ roverId, filePath, options });
+      if (playImpl) playImpl();
+    },
+    soundPath,
+  });
+  return { played, warnings };
+}
+
+// Each registerBonkSound call adds another subscriber to the shared bus, so every
+// test publishes a distinct rover id and asserts only on its own rover.
+function bonk(roverId) {
+  publishEvent({ source: 'test', type: 'fun.bonked', payload: { roverId, targetLabel: 'bob' } });
+}
+
+test('a bonk event plays the sound on the named rover', () => {
+  const { played } = harness();
+  bonk('rover-play');
+
+  const mine = played.filter((entry) => entry.roverId === 'rover-play');
+  assert.equal(mine.length, 1);
+  assert.equal(mine[0].filePath, presentSound);
+  assert.equal(mine[0].options.source, 'bonk');
+});
+
+test('an event with no rover id is ignored', () => {
+  const { played } = harness();
+  publishEvent({ source: 'test', type: 'fun.bonked', payload: {} });
+  publishEvent({ source: 'test', type: 'fun.bonked', payload: { roverId: '   ' } });
+  assert.equal(played.length, 0);
+});
+
+test('a missing sound file skips playback instead of throwing', () => {
+  const { played, warnings } = harness({ soundPath: missingSound });
+  assert.doesNotThrow(() => bonk('rover-missing'));
+  assert.equal(played.filter((entry) => entry.roverId === 'rover-missing').length, 0);
+  assert.equal(warnings.length, 0, 'a not-installed sound is informational, not a warning');
+});
+
+test('a playback failure is contained and logged rather than thrown at the caller', () => {
+  const { warnings } = harness({
+    playImpl: () => {
+      throw new Error('Rover offline');
+    },
+  });
+  assert.doesNotThrow(() => bonk('rover-offline'));
+  assert.ok(warnings.some((entry) => entry.meta?.error === 'Rover offline'));
+});
+
+test('the default sound path lives in server/assets, which the webui build does not wipe', () => {
+  // webui/vite.config.js builds to ../server/public with emptyOutDir enabled, so a
+  // sound stored there would be deleted by the next build.
+  assert.match(BONK_SOUND_PATH, /server\/assets\/bonk\.wav$/);
+  assert.doesNotMatch(BONK_SOUND_PATH, /server\/public/);
+});
+
+test.after(() => {
+  fs.rmSync(soundDir, { recursive: true, force: true });
+});

server/src/services/audioForwardService/hooks.js

@@ -23,8 +23,34 @@ function registerAudioForwardHooks(deps) {
     buildWhipUrl,
     videoSessions,
     startSilenceWriter,
+    isMuted,
+    verificationEvents,
   } = deps;
 
+  verificationEvents.on('change', ({ socketId } = {}) => {
+    if (!socketId) return;
+    const socket = io.sockets.sockets.get(socketId);
+    if (!socket || !isMuted(socket)) return;
+
+    /*
+      Permission checks stop new muted audio, but an upload or microphone can
+      already be live when moderation changes. Stop only streams owned by this
+      socket so muting does not disturb another driver's audio or unrelated
+      server-generated sounds.
+    */
+    for (const [roverId, ownerSocketId] of whipOwners.entries()) {
+      if (ownerSocketId === socketId) {
+        stopWhipForRover(roverId, 'owner_muted');
+      }
+    }
+    workers.forEach((worker, roverId) => {
+      if (worker?.contentKind === 'upload' && worker.activeOwnerSocketId === socketId) {
+        logger.info('Stopping uploaded audio because its owner was muted', { roverId, socketId });
+        startSilenceWriter(roverId);
+      }
+    });
+  });
+
   roverManager.managerEvents.on('rover', ({ roverId, action } = {}) => {
     if (!roverId) return;
     if (action === 'removed') {

server/src/services/audioForwardService/index.js

@@ -8,12 +8,13 @@ const logger = require('../../globals/logger').child('audioForwardService');
 const { loadConfig } = require('../../helpers/configLoader');
 const roverManager = require('../roverManager');
 const turnService = require('../turnService');
-const { isVerified } = require('../verificationService');
+const { isMuted, isVerified, verificationEvents } = require('../verificationService');
 const videoSessions = require('../videoSessions');
 const { createAudioForwardPolicy } = require('./policy');
 const { createAudioForwardWorkerEngine } = require('./workerEngine');
 const { registerAudioForwardHooks } = require('./hooks');
 const { registerChargeCompleteSound } = require('./chargeCompleteSound');
+const { registerBonkSound } = require('./bonkSound');
 
 const audioForwardEvents = new EventEmitter();
 const config = loadConfig();
@@ -62,6 +63,7 @@ function getAudioForwardState() {
 
 const audioForwardPolicy = createAudioForwardPolicy({
   isVerified,
+  isMuted,
   roverManager,
   turnService,
   streamSuffix,
@@ -141,6 +143,8 @@ registerAudioForwardHooks({
   buildWhipUrl,
   videoSessions,
   startSilenceWriter,
+  isMuted,
+  verificationEvents,
 });
 
 registerChargeCompleteSound({
@@ -148,6 +152,11 @@ registerChargeCompleteSound({
   playServerAudioFile,
 });
 
+registerBonkSound({
+  logger,
+  playServerAudioFile,
+});
+
 module.exports = {
   getAudioForwardState,
   audioForwardEvents,

server/src/services/audioForwardService/policy.js

@@ -4,6 +4,7 @@
 function createAudioForwardPolicy(deps) {
   const {
     isVerified,
+    isMuted,
     roverManager,
     turnService,
     streamSuffix,
@@ -18,6 +19,9 @@ function createAudioForwardPolicy(deps) {
 
   function ensureAudioForwardPermission(socket, roverId) {
     ensureVipVerified(socket);
+    if (isMuted(socket)) {
+      throw new Error('Muted');
+    }
     if (!roverManager.isDriver(roverId, socket)) {
       throw new Error('Audio forwarding is only allowed on your own rover');
     }
@@ -26,25 +30,13 @@ function createAudioForwardPolicy(deps) {
     }
   }
 
-  function forcePublishStreamMode(rawUrl) {
-    const value = String(rawUrl || '').trim();
-    if (!value) return '';
-    if (!/[?&]streamid=#!::/.test(value)) return value;
-    if (/,m=publish\b/.test(value)) return value;
-    if (/,m=[a-zA-Z]+\b/.test(value)) return value.replace(/,m=[a-zA-Z]+\b/, ',m=publish');
-    return value.replace(/([?&]streamid=#!::[^&]*)/, '$1,m=publish');
-  }
-
   function resolveForwardUrl(roverId) {
-    const record = roverManager.rovers.get(roverId);
+    /*
-    // Rovers listen to the playback stream with a request/read URL. The VIP
+      The server publishes to its own MediaMTX child, so loopback is the stable and correct
-    // upload path needs to publish into that same stream, so the configured
+      route regardless of which hostname a rover uses to reach this machine. RTSP uses the
-    // nested playback URL is converted to publish mode below.
+      same path for publish and read; ANNOUNCE/RECORD and DESCRIBE/PLAY distinguish direction.
-    const configured = record?.meta?.media?.audioPlayback?.forwardUrl;
+    */
-    if (configured) return forcePublishStreamMode(configured);
+    return `rtsp://127.0.0.1:8554/${encodeURIComponent(roverId + streamSuffix)}`;
-    return `srt://127.0.0.1:9000?streamid=#!::r=${encodeURIComponent(
-      roverId + streamSuffix,
-    )},m=publish&latency=10&mode=caller&transtype=live&pkt_size=1316`;
   }
 
   function resolveForwardPathId(roverId) {

server/src/services/audioForwardService/policy.test.js

@@ -0,0 +1,32 @@
+// Audio Forward Policy Tests
+// Purpose: Verifies that mute blocks user-owned forwarding without changing ordinary driver authorization.
+// Scope: Exercises the pure permission policy with small injected role, rover, and turn doubles.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createAudioForwardPolicy } = require('./policy');
+
+function createPolicy({ verified = true, muted = false, driver = true, canDrive = true } = {}) {
+  return createAudioForwardPolicy({
+    isVerified: () => verified,
+    isMuted: () => muted,
+    roverManager: { isDriver: () => driver },
+    turnService: { canDrive: () => canDrive },
+    streamSuffix: '-fwd',
+    mediaConfig: {},
+  });
+}
+
+test('rejects audio forwarding for a muted verified driver', () => {
+  const policy = createPolicy({ muted: true });
+  assert.throws(() => policy.ensureAudioForwardPermission({}, 'rover'), /Muted/);
+});
+
+test('preserves normal audio forwarding for an unmuted verified driver', () => {
+  const policy = createPolicy();
+  assert.doesNotThrow(() => policy.ensureAudioForwardPermission({}, 'rover'));
+});
+
+test('publishes forwarded audio to the local MediaMTX RTSP path', () => {
+  const policy = createPolicy();
+  assert.equal(policy.resolveForwardUrl('rover one'), 'rtsp://127.0.0.1:8554/rover%20one-fwd');
+});

server/src/services/audioForwardService/workerEngine.js

@@ -86,7 +86,7 @@ function createAudioForwardWorkerEngine(deps) {
       exited = true;
     };
     // ChildProcess.killed only means Node successfully sent a signal, not that
-    // ffmpeg actually exited. Track the real exit event so FIFO/SRT hangs still
+    // ffmpeg actually exited. Track the real exit event so FIFO/publisher hangs still
     // get escalated to SIGKILL instead of making systemd wait for its timeout.
     proc.once('exit', markExited);
     try {
@@ -145,7 +145,13 @@ function createAudioForwardWorkerEngine(deps) {
       '-muxpreload',
       '0',
       '-f',
-      'mpegts',
+      'rtsp',
+      /*
+        The MediaMTX listener accepts RTSP over TCP only. Pinning it here makes the server's
+        own publisher follow the same reliable transport contract as every rover publisher.
+      */
+      '-rtsp_transport',
+      'tcp',
       outputUrl,
     ];
   }

server/src/services/audioLevelsService/gainMath.js

@@ -0,0 +1,79 @@
+// audio Levels Gain Math
+// Purpose: Holds the pure clamping and ceiling rules shared by every gain layer.
+// Scope: No IO, no state; keeps the volume policy independently reviewable and testable.
+
+/*
+  The three gain keys are the same on every layer of this feature: the global
+  admin gains, the admin-editable VIP boost caps, and each user's personal
+  preference. Iterating one list keeps those layers from drifting apart.
+*/
+const GAIN_KEYS = ['hornGain', 'ttsGain', 'forwardGain'];
+
+// Absolute gain limits accepted anywhere a multiplier is stored.
+const MIN_GAIN = 0;
+const MAX_GAIN = 4;
+
+function clampGain(value, fallback = 1) {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
+  return Math.max(MIN_GAIN, Math.min(MAX_GAIN, num));
+}
+
+function clampFraction(value, fallback = 1) {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
+  return Math.max(0, Math.min(1, num));
+}
+
+function normalizeUserGains(raw = {}) {
+  const out = {};
+  GAIN_KEYS.forEach((key) => {
+    out[key] = clampFraction(raw?.[key], 1);
+  });
+  return out;
+}
+
+function normalizeGainSet(raw = {}, fallback = {}) {
+  const out = {};
+  GAIN_KEYS.forEach((key) => {
+    out[key] = clampGain(raw?.[key], clampGain(fallback?.[key], 1));
+  });
+  return out;
+}
+
+/*
+  A user without the boost flag can never exceed the global admin gain. The flag
+  raises the ceiling to the admin-managed hard cap, and Math.max keeps the flag
+  from ever being a downgrade: if an admin runs the global gain higher than the
+  boost cap, a boosted user keeps the global ceiling instead of losing volume
+  for holding a permission.
+*/
+function resolveCeilings({ adminLimits = {}, boostCaps = {}, hasBoost = false } = {}) {
+  const out = {};
+  GAIN_KEYS.forEach((key) => {
+    const adminCeiling = clampGain(adminLimits?.[key], 0);
+    out[key] = hasBoost ? Math.max(adminCeiling, clampGain(boostCaps?.[key], 0)) : adminCeiling;
+  });
+  return out;
+}
+
+// Personal preferences are fractions of whichever ceiling applies to the user.
+function applyCeilings(fractions = {}, ceilings = {}) {
+  const out = {};
+  GAIN_KEYS.forEach((key) => {
+    out[key] = clampGain(clampFraction(fractions?.[key], 1) * clampGain(ceilings?.[key], 0), 0);
+  });
+  return out;
+}
+
+module.exports = {
+  GAIN_KEYS,
+  MIN_GAIN,
+  MAX_GAIN,
+  clampGain,
+  clampFraction,
+  normalizeUserGains,
+  normalizeGainSet,
+  resolveCeilings,
+  applyCeilings,
+};

server/src/services/audioLevelsService/gainMath.test.js

@@ -0,0 +1,85 @@
+// audio Levels Gain Math Tests
+// Purpose: Pins the ceiling rules that keep user volume inside admin limits.
+// Scope: Pure math only; no store, socket, or rover involvement.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  clampFraction,
+  clampGain,
+  normalizeUserGains,
+  normalizeGainSet,
+  resolveCeilings,
+  applyCeilings,
+} = require('./gainMath');
+
+const ADMIN_LIMITS = { hornGain: 0.3, ttsGain: 0.2, forwardGain: 0.1 };
+const BOOST_CAPS = { hornGain: 0.5, ttsGain: 0.8, forwardGain: 0.4 };
+
+test('an unboosted user is capped by the global admin gains', () => {
+  const ceilings = resolveCeilings({ adminLimits: ADMIN_LIMITS, boostCaps: BOOST_CAPS, hasBoost: false });
+  assert.deepEqual(ceilings, ADMIN_LIMITS);
+});
+
+test('the boost flag raises the ceiling to the hard caps', () => {
+  const ceilings = resolveCeilings({ adminLimits: ADMIN_LIMITS, boostCaps: BOOST_CAPS, hasBoost: true });
+  assert.deepEqual(ceilings, BOOST_CAPS);
+});
+
+test('the boost flag never lowers a ceiling when admin gains exceed the caps', () => {
+  const loud = { hornGain: 2, ttsGain: 1.5, forwardGain: 3 };
+  const ceilings = resolveCeilings({ adminLimits: loud, boostCaps: BOOST_CAPS, hasBoost: true });
+  assert.deepEqual(ceilings, loud);
+});
+
+test('a full personal slider resolves to exactly the ceiling', () => {
+  const effective = applyCeilings({ hornGain: 1, ttsGain: 1, forwardGain: 1 }, ADMIN_LIMITS);
+  assert.deepEqual(effective, ADMIN_LIMITS);
+});
+
+test('a personal slider scales the ceiling rather than replacing it', () => {
+  const effective = applyCeilings({ hornGain: 0.5, ttsGain: 0.5, forwardGain: 0.5 }, BOOST_CAPS);
+  assert.deepEqual(effective, { hornGain: 0.25, ttsGain: 0.4, forwardGain: 0.2 });
+});
+
+test('an out-of-range personal value cannot escape the ceiling', () => {
+  const effective = applyCeilings({ hornGain: 12, ttsGain: -4, forwardGain: 'loud' }, ADMIN_LIMITS);
+  assert.equal(effective.hornGain, ADMIN_LIMITS.hornGain);
+  assert.equal(effective.ttsGain, 0);
+  // A non-numeric value falls back to the full slider, still bounded by the ceiling.
+  assert.equal(effective.forwardGain, ADMIN_LIMITS.forwardGain);
+});
+
+test('a zero admin gain silences even a boosted user at full slider', () => {
+  const ceilings = resolveCeilings({
+    adminLimits: { hornGain: 0, ttsGain: 0, forwardGain: 0 },
+    boostCaps: { hornGain: 0, ttsGain: 0, forwardGain: 0 },
+    hasBoost: true,
+  });
+  assert.deepEqual(applyCeilings({ hornGain: 1, ttsGain: 1, forwardGain: 1 }, ceilings), {
+    hornGain: 0,
+    ttsGain: 0,
+    forwardGain: 0,
+  });
+});
+
+test('personal values normalize into the 0..1 range with a full-volume default', () => {
+  assert.deepEqual(normalizeUserGains({ hornGain: 0.25, ttsGain: 9 }), {
+    hornGain: 0.25,
+    ttsGain: 1,
+    forwardGain: 1,
+  });
+});
+
+test('gain sets normalize into the 0..4 range and fall back per key', () => {
+  assert.deepEqual(normalizeGainSet({ hornGain: 9, ttsGain: 'x' }, BOOST_CAPS), {
+    hornGain: 4,
+    ttsGain: BOOST_CAPS.ttsGain,
+    forwardGain: BOOST_CAPS.forwardGain,
+  });
+});
+
+test('clamps reject non-finite input by returning the supplied fallback', () => {
+  assert.equal(clampGain(Number.NaN, 0.7), 0.7);
+  assert.equal(clampGain(Infinity, 0.7), 0.7);
+  assert.equal(clampFraction(undefined, 0.4), 0.4);
+});

server/src/services/audioLevelsService/index.js

@@ -9,24 +9,53 @@ const { loadConfig } = require('../../helpers/configLoader');
 const { resolveDataDir, resolveDataPath } = require('../../helpers/dataPaths');
 const { isAdmin } = require('../roleService');
 const roverManager = require('../roverManager');
+const { getFeatureState, setFeatureState, getUserIdForSocket } = require('../identityService');
 const { issueCommand } = require('../commandService');
+const {
+  GAIN_KEYS,
+  clampGain,
+  clampFraction,
+  normalizeUserGains,
+  normalizeGainSet,
+  resolveCeilings,
+  applyCeilings,
+} = require('./gainMath');
 
 const audioLevelsEvents = new EventEmitter();
 const DATA_DIR = resolveDataDir();
 const STORE_PATH = resolveDataPath('audio-levels.json');
 const config = loadConfig();
 const configuredDefaults = config.audioLevels || {};
+const configuredUserCaps = configuredDefaults.userGainCaps || {};
+
+/*
+  Per-user preferences live in identity feature state so they follow the user
+  across browsers and cannot be raised by editing a client-side cookie. They are
+  stored as a 0..1 fraction of whatever ceiling currently applies rather than an
+  absolute gain, so lowering the global admin gain immediately quiets everyone
+  without having to rewrite every stored preference.
+*/
+const USER_GAINS_NAMESPACE = 'audioGains';
+
+/*
+  Absolute ceilings for users holding the audioGainBoost flag. These are the
+  hard caps the flag cannot exceed; admins can retune them from the driver page.
+*/
+const USER_GAIN_CAP_DEFAULTS = {
+  hornGain: 0.5,
+  ttsGain: 0.8,
+  forwardGain: 0.4,
+};
 
 const DEFAULTS = {
   hornGain: clampGain(configuredDefaults.hornGain, 1),
   ttsGain: clampGain(configuredDefaults.ttsGain, 1),
   forwardGain: clampGain(configuredDefaults.forwardGain, 1),
+  userGainCaps: normalizeGainSet(configuredUserCaps, USER_GAIN_CAP_DEFAULTS),
 };
 
-function clampGain(value, fallback = 1) {
+function normalizeUserGainCaps(raw = {}, fallback = DEFAULTS.userGainCaps) {
-  const num = Number(value);
+  return normalizeGainSet(raw, fallback);
-  if (!Number.isFinite(num)) return fallback;
-  return Math.max(0, Math.min(4, num));
 }
 
 function normalizeStore(raw = {}) {
@@ -34,8 +63,11 @@ function normalizeStore(raw = {}) {
     hornGain: clampGain(raw.hornGain, DEFAULTS.hornGain),
     ttsGain: clampGain(raw.ttsGain, DEFAULTS.ttsGain),
     forwardGain: clampGain(raw.forwardGain, DEFAULTS.forwardGain),
+    userGainCaps: normalizeUserGainCaps(raw.userGainCaps),
     updatedAt: Number.isFinite(raw.updatedAt) ? raw.updatedAt : null,
     updatedBy: typeof raw.updatedBy === 'string' ? raw.updatedBy : null,
+    capsUpdatedAt: Number.isFinite(raw.capsUpdatedAt) ? raw.capsUpdatedAt : null,
+    capsUpdatedBy: typeof raw.capsUpdatedBy === 'string' ? raw.capsUpdatedBy : null,
   };
 }
 
@@ -71,18 +103,94 @@ function getAudioLevels() {
     hornGain: current.hornGain,
     ttsGain: current.ttsGain,
     forwardGain: current.forwardGain,
+    userGainCaps: { ...current.userGainCaps },
     updatedAt: current.updatedAt,
     updatedBy: current.updatedBy,
+    capsUpdatedAt: current.capsUpdatedAt,
+    capsUpdatedBy: current.capsUpdatedBy,
   };
 }
 
-function emitChange(reason = 'update') {
+function getUserGainCaps() {
+  return { ...loadState().userGainCaps };
+}
+
+function emitChange(reason = 'update', extra = {}) {
   audioLevelsEvents.emit('change', {
     reason,
     levels: getAudioLevels(),
+    ...extra,
   });
 }
 
+function getAdminLimits() {
+  const current = loadState();
+  return {
+    hornGain: current.hornGain,
+    ttsGain: current.ttsGain,
+    forwardGain: current.forwardGain,
+  };
+}
+
+function getGainCeilings(hasBoost) {
+  const current = loadState();
+  return resolveCeilings({
+    adminLimits: getAdminLimits(),
+    boostCaps: current.userGainCaps,
+    hasBoost,
+  });
+}
+
+function getGainCeilingsForSocket(socket) {
+  return getGainCeilings(Boolean(socket?.data?.hasAudioGainBoost));
+}
+
+function getUserGains(userId) {
+  if (!userId) return normalizeUserGains({});
+  return normalizeUserGains(getFeatureState(userId, USER_GAINS_NAMESPACE, {}));
+}
+
+function getUserGainsForSocket(socket) {
+  return getUserGains(getUserIdForSocket(socket));
+}
+
+function getEffectiveLevelsForSocket(socket) {
+  return applyCeilings(getUserGainsForSocket(socket), getGainCeilingsForSocket(socket));
+}
+
+/*
+  The rover applies gain as three ALSA master controls, so only one set of gains
+  can be live per rover at a time. That is not a limitation in practice: horn,
+  TTS, and mic forwarding are all restricted to the socket currently holding
+  audio control, so pushing that socket's resolved gains gives genuinely
+  per-user volume. When nobody owns audio the global admin gains apply.
+*/
+function resolveAudioOwnerSocket(roverId) {
+  const record = roverManager.rovers.get(roverId);
+  if (!record) return null;
+  const driverIds = Array.from(record.drivers || []);
+  if (!driverIds.length) return null;
+
+  // Required lazily: turnService reaches back into roverManager during startup.
+  let activeSocketId = null;
+  try {
+    activeSocketId = require('../turnService').getActiveDrivers()[roverId] || null;
+  } catch (err) {
+    logger.warn('Failed to resolve active driver for audio levels', roverId, err.message);
+  }
+
+  const chosenId = activeSocketId && driverIds.includes(activeSocketId)
+    ? activeSocketId
+    : (driverIds.length === 1 ? driverIds[0] : null);
+  if (!chosenId) return null;
+  return io.sockets.sockets.get(chosenId) || null;
+}
+
+function resolveLevelsForRover(roverId) {
+  const owner = resolveAudioOwnerSocket(roverId);
+  return owner ? getEffectiveLevelsForSocket(owner) : getAdminLimits();
+}
+
 function pushLevelsToRover(roverId) {
   if (!roverId) return;
   const record = roverManager.rovers.get(roverId);
@@ -90,7 +198,7 @@ function pushLevelsToRover(roverId) {
   try {
     issueCommand(roverId, {
       type: 'audioLevels',
-      audioLevels: getAudioLevels(),
+      audioLevels: resolveLevelsForRover(roverId),
     });
   } catch (err) {
     logger.warn('Failed to push audio levels to rover', roverId, err.message);
@@ -105,6 +213,11 @@ function pushLevelsToAllRovers() {
   });
 }
 
+function pushLevelsForSocket(socket) {
+  if (!socket) return;
+  roverManager.getRoversForSocket(socket.id).forEach((roverId) => pushLevelsToRover(roverId));
+}
+
 function setAudioLevels(input = {}, actor = null) {
   const current = loadState();
   const next = {
@@ -121,12 +234,83 @@ function setAudioLevels(input = {}, actor = null) {
   return getAudioLevels();
 }
 
+function setUserGainCaps(input = {}, actor = null) {
+  const current = loadState();
+  const next = {
+    ...current,
+    userGainCaps: normalizeUserGainCaps(input, current.userGainCaps),
+    capsUpdatedAt: Date.now(),
+    capsUpdatedBy: actor,
+  };
+  persistState(next);
+  /*
+    Lowering a cap has to take effect immediately for anyone already driving,
+    otherwise a boosted user keeps the louder gain until their next turn.
+  */
+  pushLevelsToAllRovers();
+  emitChange('user_caps_set');
+  return getUserGainCaps();
+}
+
+function setUserGains(socket, input = {}) {
+  const userId = getUserIdForSocket(socket);
+  if (!userId) throw new Error('Identity required');
+  const current = getUserGains(userId);
+  const next = { ...current };
+  GAIN_KEYS.forEach((key) => {
+    if (input?.[key] === undefined) return;
+    next[key] = clampFraction(input[key], current[key]);
+  });
+  setFeatureState(userId, USER_GAINS_NAMESPACE, next);
+  pushLevelsForSocket(socket);
+  emitChange('user_gains_set', { scope: 'user', userId });
+  return getAudioGainStateForSocket(socket);
+}
+
+/*
+  The client needs all three layers to render an honest slider: its own stored
+  fraction, the ceiling that fraction is measured against, and the resolved gain
+  so the UI can show what the rover will actually play.
+*/
+function getAudioGainStateForSocket(socket) {
+  const hasBoost = Boolean(socket?.data?.hasAudioGainBoost);
+  const values = getUserGainsForSocket(socket);
+  const ceilings = getGainCeilings(hasBoost);
+  return {
+    values,
+    ceilings,
+    effective: applyCeilings(values, ceilings),
+    boostGranted: hasBoost,
+    adminLimits: getAdminLimits(),
+    boostCaps: getUserGainCaps(),
+  };
+}
+
 roverManager.managerEvents.on('rover', ({ roverId, action } = {}) => {
   if (action === 'upsert' && roverId) {
     pushLevelsToRover(roverId);
   }
 });
 
+/*
+  Whoever owns a rover's audio determines which gains are live, so the rover has
+  to be re-pushed whenever that ownership moves: joining or leaving a rover, and
+  every turn rotation.
+*/
+roverManager.managerEvents.on('driver', ({ roverId } = {}) => {
+  if (roverId) pushLevelsToRover(roverId);
+});
+
+setImmediate(() => {
+  try {
+    require('../turnService').turnEvents.on('queue', ({ roverId } = {}) => {
+      if (roverId) pushLevelsToRover(roverId);
+    });
+  } catch (err) {
+    logger.warn('Failed to subscribe to turn changes for audio levels', err.message);
+  }
+});
+
 io.on('connection', (socket) => {
   socket.on('audioLevels:get', (_, cb = () => {}) => {
     cb({ success: true, levels: getAudioLevels() });
@@ -144,13 +328,51 @@ io.on('connection', (socket) => {
       cb({ error: err.message });
     }
   });
+
+  socket.on('audioLevels:setUserCaps', (payload = {}, cb = () => {}) => {
+    try {
+      if (!isAdmin(socket)) {
+        throw new Error('Not authorized');
+      }
+      const actor = socket?.data?.user?.username || null;
+      const userGainCaps = setUserGainCaps(payload || {}, actor);
+      cb({ success: true, userGainCaps });
+    } catch (err) {
+      cb({ error: err.message });
+    }
+  });
+
+  socket.on('audioLevels:getUserGains', (_, cb = () => {}) => {
+    try {
+      cb({ success: true, audioGains: getAudioGainStateForSocket(socket) });
+    } catch (err) {
+      cb({ error: err.message });
+    }
+  });
+
+  socket.on('audioLevels:setUserGains', (payload = {}, cb = () => {}) => {
+    try {
+      cb({ success: true, audioGains: setUserGains(socket, payload || {}) });
+    } catch (err) {
+      cb({ error: err.message });
+    }
+  });
 });
 
 loadState();
 
 module.exports = {
+  GAIN_KEYS,
+  USER_GAIN_CAP_DEFAULTS,
   getAudioLevels,
   setAudioLevels,
+  getUserGainCaps,
+  setUserGainCaps,
+  getUserGains,
+  setUserGains,
+  getGainCeilingsForSocket,
+  getEffectiveLevelsForSocket,
+  getAudioGainStateForSocket,
   pushLevelsToRover,
   audioLevelsEvents,
 };

server/src/services/balanceBoardService/hardware.js

@@ -0,0 +1,179 @@
+// Balance Board Hardware Bridge
+// Purpose: Supervises the capability-limited native worker and converts its JSON-line protocol into service events.
+// Scope: Owns process lifecycle, restart recovery, shutdown, and protocol validation; scale policy remains in index.js.
+const { spawn } = require('child_process');
+const EventEmitter = require('events');
+const path = require('path');
+
+const WORKER_PATH =
+  process.env.BALANCE_BOARD_WORKER ||
+  path.join(__dirname, 'native', 'balance_board_worker');
+const RESTART_DELAY_MS = 2000;
+const STDERR_LOG_INTERVAL_MS = 5000;
+
+function createBalanceBoardHardware({ logger, address = '', simulate = false } = {}) {
+  const events = new EventEmitter();
+  let worker = null;
+  let stdoutBuffer = '';
+  let stopped = false;
+  let restarting = false;
+  let restartTimer = null;
+  let lastStderrLogAt = 0;
+  let suppressedStderrLines = 0;
+  let currentAddress = address;
+
+  function emitProtocolError(message) {
+    events.emit('message', {
+      type: 'status',
+      state: 'error',
+      error: message,
+    });
+  }
+
+  function processStdout(chunk) {
+    stdoutBuffer += chunk.toString('utf8');
+    let newline = stdoutBuffer.indexOf('\n');
+    while (newline !== -1) {
+      const line = stdoutBuffer.slice(0, newline).trim();
+      stdoutBuffer = stdoutBuffer.slice(newline + 1);
+      if (line) {
+        try {
+          const message = JSON.parse(line);
+          if (!message || typeof message !== 'object' || typeof message.type !== 'string') {
+            throw new Error('message needs a type');
+          }
+          events.emit('message', message);
+        } catch (err) {
+          // A corrupted stdout line means measurement framing can no longer be
+          // trusted. Surface the exact line rather than silently discarding a
+          // potential hardware failure that would otherwise look like zero kg.
+          emitProtocolError(`balance board worker returned invalid JSON: ${err.message}`);
+          logger?.warn?.('Balance Board worker protocol error', { line, error: err.message });
+        }
+      }
+      newline = stdoutBuffer.indexOf('\n');
+    }
+  }
+
+  function scheduleRestart() {
+    if (stopped || restartTimer) return;
+    restartTimer = setTimeout(() => {
+      restartTimer = null;
+      start();
+    }, RESTART_DELAY_MS);
+  }
+
+  function start() {
+    if (stopped || (worker && !worker.killed)) return;
+    stdoutBuffer = '';
+
+    const child = spawn(WORKER_PATH, [], {
+      env: {
+        ...process.env,
+        BALANCE_BOARD_ADDRESS: currentAddress || '',
+        BALANCE_BOARD_SIMULATE: simulate ? 'cycle' : '',
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    worker = child;
+
+    child.stdout.on('data', processStdout);
+    child.stderr.on('data', (chunk) => {
+      const text = chunk.toString('utf8').trim();
+      if (!text) return;
+      const now = Date.now();
+      if (now - lastStderrLogAt >= STDERR_LOG_INTERVAL_MS) {
+        const suffix = suppressedStderrLines
+          ? ` (${suppressedStderrLines} worker stderr lines suppressed)`
+          : '';
+        logger?.warn?.(`Balance Board worker: ${text}${suffix}`);
+        lastStderrLogAt = now;
+        suppressedStderrLines = 0;
+      } else {
+        suppressedStderrLines += 1;
+      }
+    });
+    child.on('error', (err) => {
+      if (worker === child) worker = null;
+      emitProtocolError(`balance board worker failed to start: ${err.message}`);
+      scheduleRestart();
+    });
+    child.on('close', (code, signal) => {
+      if (worker === child) worker = null;
+      if (!stopped) {
+        // Admin unpair deliberately replaces the worker with an empty address.
+        // Do not turn that expected exit into a red hardware-error state while
+        // still using the normal restart scheduler for the replacement.
+        if (!restarting) emitProtocolError(`balance board worker exited (${signal || code})`);
+        restarting = false;
+        scheduleRestart();
+      }
+    });
+  }
+
+  function stop() {
+    stopped = true;
+    restarting = false;
+    if (restartTimer) {
+      clearTimeout(restartTimer);
+      restartTimer = null;
+    }
+    if (!worker) return;
+    const child = worker;
+    worker = null;
+    try {
+      child.stdin.write(`${JSON.stringify({ command: 'stop' })}\n`);
+    } catch (_err) {
+      // The worker may have already closed stdin while its exit event is still
+      // queued. SIGTERM below remains the reliable cleanup path.
+    }
+    child.kill('SIGTERM');
+    setTimeout(() => {
+      // bluetoothctl may still be finishing a bounded pairing command inside a
+      // worker thread. Do not let that delay server shutdown indefinitely.
+      if (child.exitCode == null && child.signalCode == null) child.kill('SIGKILL');
+    }, 1500).unref();
+  }
+
+  function restart() {
+    if (stopped) return;
+    if (!worker) {
+      start();
+      return;
+    }
+
+    const child = worker;
+    restarting = true;
+    try {
+      // An admin forget changes the address used in the child environment. A
+      // controlled restart lets the replacement worker start with that new
+      // value, while the existing close handler remains the single owner of
+      // delayed respawn and avoids overlapping Bluetooth listeners.
+      child.stdin.write(`${JSON.stringify({ command: 'stop' })}\n`);
+    } catch (_err) {
+      // The child may have already closed stdin; SIGTERM below still guarantees
+      // that it cannot keep listening for the address that was just forgotten.
+    }
+    child.kill('SIGTERM');
+    setTimeout(() => {
+      if (child.exitCode == null && child.signalCode == null) child.kill('SIGKILL');
+    }, 1500).unref();
+  }
+
+  return {
+    events,
+    start,
+    stop,
+    restart,
+    setAddress(nextAddress) {
+      // The factory can be created before first commissioning. Preserve the
+      // newly paired address for later bridge restarts in the same Node process
+      // instead of reverting the replacement worker to discovery mode.
+      currentAddress = typeof nextAddress === 'string' ? nextAddress.trim().toUpperCase() : '';
+    },
+  };
+}
+
+module.exports = {
+  createBalanceBoardHardware,
+};

server/src/services/balanceBoardService/index.js

@@ -0,0 +1,575 @@
+// Balance Board Service
+// Purpose: Exposes one Wii Balance Board as a self-pairing Bluetooth scale.
+// Scope: Stores pairing and admin zero calibration, then publishes status plus live four-corner weight.
+const fs = require('fs');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const EventEmitter = require('events');
+const io = require('../../globals/io');
+const logger = require('../../globals/logger').child('balanceBoardService');
+const { loadConfig } = require('../../helpers/configLoader');
+const { resolveDataDir, resolveDataPath } = require('../../helpers/dataPaths');
+const { isFeatureEnabled } = require('../../helpers/features');
+const { isAdmin } = require('../roleService');
+const { sendAlert } = require('../alertService');
+const { createBalanceBoardHardware } = require('./hardware');
+
+const events = new EventEmitter();
+const enabled = isFeatureEnabled('balanceBoard');
+const rawConfig = loadConfig().balanceBoard || {};
+const DATA_DIR = resolveDataDir();
+const STORE_PATH = resolveDataPath('balance-board.json');
+const FRAME_ROOM = 'balance-board-viewers';
+const CORNER_KEYS = ['topRight', 'bottomRight', 'topLeft', 'bottomLeft'];
+const ZERO_SAMPLE_COUNT = 10;
+const ZERO_SAMPLE_INTERVAL_MS = 1000;
+const ZERO_MAX_SAMPLE_AGE_MS = 1500;
+const ZERO_MAX_COMBINED_RANGE_KG = 0.5;
+const RECORD_PERSIST_DELAY_MS = 1000;
+const execFileAsync = promisify(execFile);
+const ALERT_COLOR = '#38bdf8';
+
+function emptyZeroCorners() {
+  return Object.fromEntries(CORNER_KEYS.map((key) => [key, 0]));
+}
+
+function normalizeStoredCorners(value) {
+  if (!value || typeof value !== 'object') return emptyZeroCorners();
+  return Object.fromEntries(CORNER_KEYS.map((key) => {
+    const number = Number(value[key]);
+    return [key, Number.isFinite(number) ? Math.max(0, number) : 0];
+  }));
+}
+
+function emptyStore() {
+  return {
+    address: '',
+    zeroCorners: emptyZeroCorners(),
+    zeroedAt: null,
+    recordKg: 0,
+    recordedAt: null,
+  };
+}
+
+function loadStore() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(STORE_PATH, 'utf8'));
+    const address = typeof parsed?.address === 'string' ? parsed.address.trim().toUpperCase() : '';
+    const zeroedAt = Number.isFinite(Number(parsed?.zeroedAt)) ? Number(parsed.zeroedAt) : null;
+    const recordKg = Number.isFinite(Number(parsed?.recordKg))
+      ? roundedWeight(parsed.recordKg)
+      : 0;
+    const recordedAt = Number.isFinite(Number(parsed?.recordedAt))
+      ? Number(parsed.recordedAt)
+      : null;
+    return {
+      address,
+      zeroCorners: zeroedAt ? normalizeStoredCorners(parsed.zeroCorners) : emptyZeroCorners(),
+      zeroedAt,
+      recordKg,
+      recordedAt: recordKg > 0 ? recordedAt : null,
+    };
+  } catch (err) {
+    if (err.code !== 'ENOENT') logger.warn('Failed to load Balance Board address', err.message);
+    return emptyStore();
+  }
+}
+
+function persistStore() {
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  const temporary = `${STORE_PATH}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+  fs.renameSync(temporary, STORE_PATH);
+}
+
+function roundedWeight(value) {
+  return Math.round(Math.max(0, Number(value) || 0) * 100) / 100;
+}
+
+function cornerWeightsKg(corners = {}) {
+  // Preserve wiiuse's factory-calibrated load cells in kilograms. The separate
+  // admin zero calibration below is an installation baseline layered on top of
+  // this factory conversion; it must never replace the hardware calibration.
+  return {
+    topRight: roundedWeight((Number(corners.topRight) || 0) / 100),
+    bottomRight: roundedWeight((Number(corners.bottomRight) || 0) / 100),
+    topLeft: roundedWeight((Number(corners.topLeft) || 0) / 100),
+    bottomLeft: roundedWeight((Number(corners.bottomLeft) || 0) / 100),
+  };
+}
+
+function subtractZero(rawCorners) {
+  const baseline = store.zeroedAt ? store.zeroCorners : emptyZeroCorners();
+  return Object.fromEntries(CORNER_KEYS.map((key) => [
+    key,
+    roundedWeight(Math.max(0, rawCorners[key] - baseline[key])),
+  ]));
+}
+
+function totalCornerWeight(corners) {
+  return roundedWeight(CORNER_KEYS.reduce((total, key) => total + corners[key], 0));
+}
+
+let store = enabled ? loadStore() : emptyStore();
+let hardware = null;
+let status = enabled ? (store.address ? 'waiting' : 'starting') : 'disabled';
+let detail = enabled
+  ? (store.address ? 'Press the front power button.' : 'Starting Bluetooth discovery.')
+  : 'Balance Board support is disabled.';
+let connected = false;
+let batteryPercent = null;
+let latestFrame = null;
+let latestRawCorners = null;
+let latestRawFrameAt = 0;
+let zeroTimer = null;
+let recordPersistTimer = null;
+let zeroSamples = [];
+let zeroProgress = {
+  active: false,
+  samplesCollected: 0,
+  totalSamples: ZERO_SAMPLE_COUNT,
+  error: '',
+};
+let previousWorkerState = '';
+let lastAlertKey = '';
+let unpairing = false;
+
+function sendRawAlert(state, message = '') {
+  const rawMessage = message ? `${state}: ${message}` : state;
+  if (rawMessage === lastAlertKey) return;
+  lastAlertKey = rawMessage;
+  sendAlert({ color: ALERT_COLOR, title: 'Balance Board', message: rawMessage });
+}
+
+function sendStatusAlert(workerState, message = '') {
+  const shouldAlert =
+    workerState === 'connected' ||
+    workerState === 'sleeping' ||
+    workerState === 'connection-failed' ||
+    workerState === 'error' ||
+    (workerState === 'waiting' && previousWorkerState === 'connected');
+
+  previousWorkerState = workerState;
+  if (!shouldAlert) return;
+
+  // Keep the alert at the same system-level boundary as the worker protocol:
+  // state first, followed by its exact detail when one exists. The service does
+  // not reinterpret failures as friendlier product copy, but still collapses
+  // identical retries so a failing reconnect cannot flood the activity feed.
+  sendRawAlert(workerState, message);
+}
+
+function getState() {
+  return {
+    enabled,
+    paired: Boolean(store.address) || Boolean(rawConfig.simulate),
+    address: store.address || (rawConfig.simulate ? 'SIMULATED' : null),
+    connected,
+    status,
+    detail,
+    batteryPercent,
+    recordKg: store.recordKg,
+    recordedAt: store.recordedAt,
+    calibration: {
+      calibrated: Boolean(store.zeroedAt),
+      zeroedAt: store.zeroedAt,
+      ...zeroProgress,
+    },
+  };
+}
+
+function clearRecordPersistTimer() {
+  if (!recordPersistTimer) return;
+  clearTimeout(recordPersistTimer);
+  recordPersistTimer = null;
+}
+
+function scheduleRecordPersistence() {
+  clearRecordPersistTimer();
+
+  // A person driving onto the board produces many successively larger frames.
+  // Waiting until the maximum has stopped changing prevents a synchronous JSON
+  // rewrite for every 20 Hz sensor frame while still saving a settled record
+  // promptly enough to survive an ordinary service restart.
+  recordPersistTimer = setTimeout(() => {
+    recordPersistTimer = null;
+    persistStore();
+  }, RECORD_PERSIST_DELAY_MS);
+  recordPersistTimer.unref?.();
+}
+
+function publishLatestFrame() {
+  if (!latestFrame) return;
+  io.to(FRAME_ROOM).emit('balanceBoard:frame', latestFrame);
+}
+
+function resetWeightRecord() {
+  clearRecordPersistTimer();
+
+  // Reset means "start measuring the record from now." If the board currently
+  // has a load, that current measurement is the first candidate in the new
+  // period. Saving it immediately avoids briefly showing zero before the next
+  // live frame restores the same weight as the record.
+  const currentWeight = connected && latestFrame ? roundedWeight(latestFrame.totalKg) : 0;
+  store.recordKg = currentWeight;
+  store.recordedAt = currentWeight > 0 ? Date.now() : null;
+  persistStore();
+
+  if (latestFrame) {
+    latestFrame = {
+      ...latestFrame,
+      recordKg: store.recordKg,
+      recordedAt: store.recordedAt,
+    };
+    publishLatestFrame();
+  }
+  events.emit('change', { state: getState() });
+  sendRawAlert('record-reset');
+}
+
+function updateStatus(nextStatus, nextDetail) {
+  const normalizedStatus = String(nextStatus || 'unknown');
+  const normalizedDetail = String(nextDetail || '');
+  if (status === normalizedStatus && detail === normalizedDetail) return;
+  status = normalizedStatus;
+  detail = normalizedDetail;
+  events.emit('change', { state: getState() });
+}
+
+function publishCalibrationState() {
+  // Calibration progress belongs in the ordinary session payload because it
+  // changes only once per second for ten seconds. Live 20 Hz weights remain in
+  // their dedicated room and never trigger a full-session broadcast.
+  events.emit('change', { state: getState() });
+}
+
+function clearZeroTimer() {
+  if (!zeroTimer) return;
+  clearInterval(zeroTimer);
+  zeroTimer = null;
+}
+
+function failZeroCalibration(error, { alert = true } = {}) {
+  clearZeroTimer();
+  zeroSamples = [];
+  zeroProgress = {
+    active: false,
+    samplesCollected: 0,
+    totalSamples: ZERO_SAMPLE_COUNT,
+    error: String(error || 'Calibration failed'),
+  };
+  publishCalibrationState();
+  if (alert) sendRawAlert('zero-failed', zeroProgress.error);
+}
+
+function finishZeroCalibration() {
+  clearZeroTimer();
+
+  // A single average could hide movement that returns to its starting point.
+  // Sum every corner's complete ten-second range before accepting the result so
+  // distributed movement cannot hide below four independent thresholds. Retain
+  // three decimals so averaging ten centi-kilogram samples does not throw away
+  // useful sub-centi-kilogram precision in the persisted baseline.
+  const combinedRange = CORNER_KEYS.reduce((totalRange, key) => {
+    const values = zeroSamples.map((sample) => sample[key]);
+    return totalRange + Math.max(...values) - Math.min(...values);
+  }, 0);
+  if (combinedRange > ZERO_MAX_COMBINED_RANGE_KG) {
+    failZeroCalibration('Load moved during the ten-second calibration.');
+    return;
+  }
+
+  store.zeroCorners = Object.fromEntries(CORNER_KEYS.map((key) => {
+    const average = zeroSamples.reduce((sum, sample) => sum + sample[key], 0) /
+      zeroSamples.length;
+    return [key, Math.round(average * 1000) / 1000];
+  }));
+  store.zeroedAt = Date.now();
+  // A new zero changes the meaning of every adjusted weight, so an old record
+  // cannot be compared with measurements under the new baseline.
+  clearRecordPersistTimer();
+  store.recordKg = 0;
+  store.recordedAt = null;
+  persistStore();
+  zeroSamples = [];
+  zeroProgress = {
+    active: false,
+    samplesCollected: ZERO_SAMPLE_COUNT,
+    totalSamples: ZERO_SAMPLE_COUNT,
+    error: '',
+  };
+  publishCalibrationState();
+  sendRawAlert('zeroed');
+}
+
+function takeZeroSample() {
+  if (!connected || !latestRawCorners || Date.now() - latestRawFrameAt > ZERO_MAX_SAMPLE_AGE_MS) {
+    failZeroCalibration('Live Balance Board data stopped during calibration.');
+    return;
+  }
+
+  zeroSamples.push({ ...latestRawCorners });
+  zeroProgress = {
+    active: true,
+    samplesCollected: zeroSamples.length,
+    totalSamples: ZERO_SAMPLE_COUNT,
+    error: '',
+  };
+  publishCalibrationState();
+  if (zeroSamples.length >= ZERO_SAMPLE_COUNT) finishZeroCalibration();
+}
+
+function startZeroCalibration() {
+  if (zeroProgress.active) throw new Error('Balance Board zero calibration is already running');
+  if (!connected || !latestRawCorners || Date.now() - latestRawFrameAt > ZERO_MAX_SAMPLE_AGE_MS) {
+    throw new Error('The Balance Board must be connected and sending weight data');
+  }
+
+  zeroSamples = [];
+  zeroProgress = {
+    active: true,
+    samplesCollected: 0,
+    totalSamples: ZERO_SAMPLE_COUNT,
+    error: '',
+  };
+  publishCalibrationState();
+  sendRawAlert('zeroing');
+  // Delaying the first sample by one interval makes this a real ten-second
+  // calibration rather than ten rapid reads followed by nine seconds of UI.
+  zeroTimer = setInterval(takeZeroSample, ZERO_SAMPLE_INTERVAL_MS);
+}
+
+function processFrame(message = {}) {
+  const rawCorners = cornerWeightsKg(message.corners);
+  latestRawCorners = rawCorners;
+  latestRawFrameAt = Date.now();
+  if (Number.isFinite(Number(message.batteryPercent))) {
+    batteryPercent = Math.max(0, Math.min(100, Number(message.batteryPercent)));
+  }
+
+  connected = true;
+  updateStatus('connected', 'Live weight is updating.');
+  const adjustedCorners = subtractZero(rawCorners);
+  const totalKg = totalCornerWeight(adjustedCorners);
+  if (totalKg > store.recordKg) {
+    // Store only adjusted weight so the displayed record uses the same admin
+    // zero baseline as the live total and all four corner readings.
+    store.recordKg = totalKg;
+    store.recordedAt = Date.now();
+    scheduleRecordPersistence();
+  }
+  latestFrame = {
+    totalKg,
+    corners: adjustedCorners,
+    batteryPercent,
+    recordKg: store.recordKg,
+    recordedAt: store.recordedAt,
+  };
+  publishLatestFrame();
+}
+
+function handleWorkerMessage(message = {}) {
+  if (message.type === 'frame') {
+    processFrame(message);
+    return;
+  }
+
+  if (message.type === 'paired') {
+    const address = typeof message.address === 'string' ? message.address.trim().toUpperCase() : '';
+    if (address && address !== store.address) {
+      store.address = address;
+      // A zero baseline belongs to one physical board and whatever permanent
+      // platform/load was present when an admin calibrated it. Never carry that
+      // baseline across commissioning a different Bluetooth identity.
+      store.zeroCorners = emptyZeroCorners();
+      store.zeroedAt = null;
+      clearRecordPersistTimer();
+      store.recordKg = 0;
+      store.recordedAt = null;
+      persistStore();
+    }
+    hardware?.setAddress(address);
+    sendRawAlert('paired');
+    updateStatus('connecting', 'Paired. Connecting to the board now.');
+    return;
+  }
+
+  if (message.type !== 'status') return;
+  const workerState = String(message.state || 'unknown');
+  sendStatusAlert(workerState, message.error || '');
+  if (workerState === 'commissioning') {
+    updateStatus('starting', 'Starting Bluetooth discovery.');
+  } else if (workerState === 'discovering') {
+    updateStatus('waiting-for-sync', 'Press the red Sync button underneath the board.');
+  } else if (workerState === 'pairing') {
+    updateStatus('pairing', 'Board found. Pairing now.');
+  } else if (workerState === 'connected') {
+    connected = true;
+    updateStatus('connected', 'Connected. Waiting for live weight data.');
+  } else if (workerState === 'link-detected') {
+    connected = false;
+    // The native bridge can now distinguish which half of the board's HID
+    // connection reached the server. Preserve that diagnostic until both
+    // channels arrive; the generic text remains for the outbound Sync flow.
+    updateStatus('connecting', message.error || 'Board responded. Reading its sensor calibration.');
+  } else if (workerState === 'connection-failed') {
+    connected = false;
+    latestFrame = null;
+    latestRawCorners = null;
+    latestRawFrameAt = 0;
+    if (zeroProgress.active) failZeroCalibration('Board disconnected during calibration.');
+    updateStatus('connection-failed', message.error || 'The direct Balance Board connection failed.');
+  } else if (workerState === 'sleeping') {
+    connected = false;
+    latestFrame = null;
+    latestRawCorners = null;
+    latestRawFrameAt = 0;
+    if (zeroProgress.active) failZeroCalibration('Board slept during calibration.');
+    updateStatus('sleeping', message.error || 'Board is asleep. Press the front power button to wake it.');
+  } else if (workerState === 'waiting') {
+    connected = false;
+    latestFrame = null;
+    latestRawCorners = null;
+    latestRawFrameAt = 0;
+    if (zeroProgress.active) failZeroCalibration('Board disconnected during calibration.');
+    updateStatus('waiting', message.error || 'Press the front power button. The server will keep trying to connect.');
+  } else if (workerState === 'error') {
+    connected = false;
+    latestRawCorners = null;
+    latestRawFrameAt = 0;
+    if (zeroProgress.active) failZeroCalibration('Worker stopped during calibration.');
+    updateStatus('error', message.error || 'The Balance Board worker stopped.');
+  }
+}
+
+io.on('connection', (socket) => {
+  socket.on('balanceBoard:subscribe', (_payload = {}, cb = () => {}) => {
+    socket.join(FRAME_ROOM);
+    if (latestFrame) socket.emit('balanceBoard:frame', latestFrame);
+    cb({ success: true });
+  });
+  socket.on('balanceBoard:unsubscribe', () => socket.leave(FRAME_ROOM));
+  socket.on('balanceBoard:zero', (_payload = {}, cb = () => {}) => {
+    if (!isAdmin(socket)) {
+      cb({ error: 'Admin access required' });
+      return;
+    }
+    try {
+      startZeroCalibration();
+      cb({ success: true });
+    } catch (err) {
+      cb({ error: err.message || 'Failed to start Balance Board zero calibration' });
+    }
+  });
+  socket.on('balanceBoard:resetRecord', (_payload = {}, cb = () => {}) => {
+    if (!isAdmin(socket)) {
+      cb({ error: 'Admin access required' });
+      return;
+    }
+
+    try {
+      resetWeightRecord();
+      cb({ success: true });
+    } catch (err) {
+      logger.error('Failed to reset Balance Board weight record', err);
+      cb({ error: err.message || 'Failed to reset the Balance Board weight record' });
+    }
+  });
+  socket.on('balanceBoard:unpair', async (_payload = {}, cb = () => {}) => {
+    if (!isAdmin(socket)) {
+      cb({ error: 'Admin access required' });
+      return;
+    }
+    if (unpairing) {
+      cb({ error: 'The Balance Board is already being unpaired' });
+      return;
+    }
+
+    unpairing = true;
+    const address = store.address;
+    let bluetoothWarning = '';
+    try {
+      if (address) {
+        try {
+          // A complete forget removes both sources of remembered identity. If
+          // only the JSON address or only the BlueZ bond were removed, the next
+          // red-Sync attempt could inherit half of the previous relationship.
+          await execFileAsync('bluetoothctl', ['remove', address], { timeout: 10000 });
+        } catch (err) {
+          bluetoothWarning = String(
+            err?.stderr || err?.message || 'BlueZ did not remove the bond',
+          ).trim();
+          logger.warn('Balance Board BlueZ bond removal failed', bluetoothWarning);
+        }
+      }
+
+      store.address = '';
+      store.zeroCorners = emptyZeroCorners();
+      store.zeroedAt = null;
+      clearRecordPersistTimer();
+      store.recordKg = 0;
+      store.recordedAt = null;
+      persistStore();
+      clearZeroTimer();
+      zeroSamples = [];
+      zeroProgress = {
+        active: false,
+        samplesCollected: 0,
+        totalSamples: ZERO_SAMPLE_COUNT,
+        error: '',
+      };
+      connected = false;
+      batteryPercent = null;
+      latestFrame = null;
+      latestRawCorners = null;
+      latestRawFrameAt = 0;
+      previousWorkerState = '';
+      hardware?.setAddress('');
+      hardware?.restart();
+      updateStatus('starting', 'Starting Bluetooth discovery.');
+      sendRawAlert('unpaired');
+      cb({ success: true, warning: bluetoothWarning || null });
+    } catch (err) {
+      logger.error('Failed to unpair Balance Board', err);
+      cb({ error: err.message || 'Failed to unpair the Balance Board' });
+    } finally {
+      unpairing = false;
+    }
+  });
+});
+
+if (enabled) {
+  hardware = createBalanceBoardHardware({
+    logger,
+    address: store.address,
+    simulate: Boolean(rawConfig.simulate || process.env.BALANCE_BOARD_SIMULATE),
+  });
+  hardware.events.on('message', handleWorkerMessage);
+  hardware.start();
+} else {
+  logger.info('Balance Board disabled by config');
+}
+
+function installShutdownHooks() {
+  const shutdown = () => {
+    clearZeroTimer();
+    // A record may still be inside the short debounce window when the process
+    // receives a normal shutdown signal. Flush that newest maximum before the
+    // hardware worker stops so a clean restart cannot lose it.
+    if (recordPersistTimer) {
+      clearRecordPersistTimer();
+      persistStore();
+    }
+    hardware?.stop();
+  };
+  process.once('exit', shutdown);
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+}
+
+installShutdownHooks();
+
+module.exports = {
+  getState,
+  balanceBoardEvents: events,
+};

server/src/services/balanceBoardService/native/Makefile

@@ -0,0 +1,22 @@
+CXX ?= g++
+
+# Wiiuse owns the Balance Board's HID control/interrupt channels and applies the
+# calibration stored in the board. This deliberately avoids BlueZ's generic HID
+# profile: current BlueZ requests medium link security for a bonded board, and
+# the original Balance Board rejects that negotiation before an input device is
+# created.
+CXXFLAGS ?= -O2 -std=c++17 -Wall -Wextra -pedantic
+LDLIBS += -lwiiuse -lbluetooth -pthread
+
+TARGET := balance_board_worker
+SRC := balance_board_worker.cpp
+
+.PHONY: all clean
+
+all: $(TARGET)
+
+$(TARGET): $(SRC)
+	$(CXX) $(CXXFLAGS) -o $@ $< $(LDLIBS)
+
+clean:
+	rm -f $(TARGET)

server/src/services/chatService/handlers.js

@@ -3,12 +3,13 @@
 // Scope: Owns message validation pipeline and typed outbound message construction.
 const logger = require('../../globals/logger').child('chatService');
 const { getRole } = require('../roleService');
+const { isDeterred, isMuted } = require('../verificationService');
 const { withinRateLimit } = require('./state');
 const { hasProfanity, isKeymash, normalizeUserText } = require('./contentFilters');
 const { buildMessage, buildTypingPayload, resolveRoverId, isPrivateClosedRoverId, buildRoverCtxSnapshot } = require('./contextBuilders');
 const { broadcastMessage, broadcastTyping } = require('./broadcast');
 const { playTypingNote, normalizeTtsOptions, maybeSendAccessNotice, maybeSpeak, TYPING_SEND_NOTE } = require('./notifications');
-const { runChatTextCommand } = require('./textCommands');
+const { isTextCommand, runChatTextCommand } = require('./textCommands');
 
 function createHandlers({ sendSystemMessage }) {
   async function handleIncoming({ text, tts, bot = false, profileImage = null } = {}, socket, cb = () => {}) {
@@ -17,6 +18,12 @@ function createHandlers({ sendSystemMessage }) {
     const normalized = normalizeUserText(text);
     const clean = normalized.trim();
     if (!clean) return cb({ error: 'Message required' });
+    /*
+      Mute is narrower than deterrence: the socket may continue driving and
+      using ordinary features, but its message must stop before broadcast,
+      command parsing, TTS, or any other chat-derived side effect occurs.
+    */
+    if (isMuted(socket)) return cb({ error: 'Muted' });
     if (!withinRateLimit(socket.id)) return cb({ error: 'Slow down' });
     // This service no longer enforces a character-count ceiling for chat text.
     // The chat layer only rejects empty, rate-limited, or moderated content so
@@ -37,37 +44,59 @@ function createHandlers({ sendSystemMessage }) {
     });
 
     logger.info('Chat message', { socket: socket.id, roverId: message.roverId });
+    const deterred = isDeterred(socket);
+    /*
+      Deterred users retain text chat, but chat must not become an indirect
+      hardware-control path. Suppress the rover typing note and TTS while still
+      constructing and broadcasting the same visible message as everyone else.
+    */
+    if (!deterred) {
       playTypingNote(roverId, TYPING_SEND_NOTE, socket?.id);
+    }
 
     if (isPrivateClosedRoverId(message.roverId)) {
       // Private-closed chat does not broadcast the text, so TTS is the only
       // delivery path. Use the same Google speech default as normal chat when
       // the sender did not provide explicit TTS settings.
       const forcedTts = ttsOptions || { speak: true, engine: 'chromegtts' };
+      if (!deterred) {
         maybeSpeak(socket, message, forcedTts);
+      }
       cb({ success: true, privateOnly: true });
       return;
     }
 
     broadcastMessage(message);
     maybeSendAccessNotice(message, sendSystemMessage);
+    if (!deterred) {
       maybeSpeak(socket, message, ttsOptions);
-
-    try {
-      // Commands sent from site chat should still be visible as normal chat
-      // messages. Running the command after broadcast preserves the user-visible
-      // transcript while keeping permissions and command execution entirely on
-      // the server.
-      const ranCommand = await runChatTextCommand({ text: clean, socket, sendSystemMessage });
-      cb({ success: true, command: ranCommand });
-      return;
-    } catch (err) {
-      logger.warn('Chat command failed after broadcast', { socket: socket?.id, error: err.message });
-      cb({ success: true, command: true, commandError: err.message || 'Command failed' });
-      return;
     }
 
-    cb({ success: true });
+    /*
+      Command-shaped text from a deterred user remains ordinary visible chat.
+      Reporting command=false prevents the client from implying that the server
+      accepted an action, and the command router is never invoked.
+    */
+    const command = !deterred && isTextCommand(clean);
+    // Chat delivery is complete once validation, broadcast, and local side
+    // effects above have succeeded. A command may wait on Home Assistant,
+    // hardware, replay preparation, or an external transport, so tying the
+    // socket acknowledgement to command completion leaves the browser's send
+    // promise pending and makes its input state appear stuck. Acknowledge now;
+    // command replies continue through the normal Rover bot message stream.
+    cb({ success: true, command });
+
+    if (command) {
+      // Deliberately do not await this promise. runChatTextCommand already turns
+      // ordinary command failures into visible bot messages; this final catch
+      // protects the service from an unexpected setup/programming failure and
+      // cannot attempt a second acknowledgement after the UI has moved on.
+      void runChatTextCommand({ text: clean, socket, sendSystemMessage }).catch((err) => {
+        logger.warn('Chat command failed after acknowledgement', { socket: socket?.id, error: err.message });
+        sendSystemMessage(`Command failed: ${err.message || 'unknown error'}`, { nickname: 'Rover bot', bot: true });
+      });
+    }
+    return;
   }
 
   function sendExternalMessage({ text, nickname = 'Discord', role = 'admin', roverId = null, discordGuildId = null, discordGuildName = null, discordGuildIconUrl = null, discordChannelId = null, discordUserId = null, discordUserName = null, discordUserAvatarUrl = null, bot = false, profileImage = null }) {

server/src/services/chatService/socketHooks.js

@@ -3,6 +3,7 @@
 // Scope: Bridges socket events to chat handlers and publishes chat updates to connected clients.
 const io = require('../../globals/io');
 const { subscribe } = require('../eventBus');
+const { isDeterred, isMuted } = require('../verificationService');
 const { typingBySocket } = require('./state');
 const { buildTypingPayload, resolveRoverId, isPrivateClosedRoverId } = require('./contextBuilders');
 const { broadcastTyping } = require('./broadcast');
@@ -13,11 +14,29 @@ function registerChatSocketHooks({ history, handleIncoming }) {
     socket.emit('chat:init', history);
     socket.on('chat:send', (payload = {}, cb = () => {}) => handleIncoming(payload, socket, cb));
     socket.on('chat:typing', (payload = {}) => {
+      /*
+        A muted typing packet must not leak presence or produce rover notes.
+        Clearing any prior state also removes a typing indicator that began
+        immediately before an administrator applied the mute.
+      */
+      if (isMuted(socket)) {
+        const wasTyping = typingBySocket.delete(socket.id);
+        const roverId = resolveRoverId(socket?.id);
+        if (wasTyping && !isPrivateClosedRoverId(roverId)) {
+          broadcastTyping(buildTypingPayload(socket, { roverId, fromDiscord: false, isTyping: false }));
+        }
+        return;
+      }
       const isTyping = Boolean(payload?.isTyping);
       const wasTyping = typingBySocket.get(socket.id);
       if (isTyping) {
         typingBySocket.set(socket.id, true);
-        if (!wasTyping) {
+        /*
+          The typing indicator is part of chat and remains available to a
+          deterred user. The rover note is a physical side effect, however, so
+          text-only deterrence suppresses that note without changing presence.
+        */
+        if (!wasTyping && !isDeterred(socket)) {
           const roverId = resolveRoverId(socket?.id);
           playTypingNote(roverId, TYPING_START_NOTE, socket?.id);
         }

server/src/services/chatService/textCommands.js

@@ -17,13 +17,21 @@ const {
   listVerifiedUsers,
   removeVerifiedUser,
   listDeterredUsers,
+  listMutedUsers,
   deterUser,
   undeterUser,
+  muteUser,
+  unmuteUser,
+  listAudioGainBoostUsers,
+  grantAudioGainBoost,
+  revokeAudioGainBoost,
 } = require('../verificationService');
 const { publishEvent } = require('../eventBus');
 const assignmentService = require('../assignmentService');
+const funStatsService = require('../funStatsService');
 const { loadConfig } = require('../../helpers/configLoader');
 const { createCommandHandlers } = require('../operatorCommandService');
+const { createCooldownGate } = require('../operatorCommandService/cooldowns');
 const { parseCommandText } = require('../operatorCommandService/config');
 const { createWebTransportHandlers } = require('../operatorCommandService/webTransport');
 const { commandReplyToText } = require('./commandResultFormatter');
@@ -36,6 +44,14 @@ const {
 const config = loadConfig();
 const discordConfig = config.discord || {};
 
+/*
+  Site chat builds a fresh command router for every message so each router can
+  close over the sending socket. Fun command cooldowns therefore have to live out
+  here: a gate created inside the router would be thrown away after one message
+  and would never actually rate limit anything.
+*/
+const commandCooldowns = createCooldownGate();
+
 function isTextCommand(text) {
   return parseCommandText(text, config).matched;
 }
@@ -117,6 +133,12 @@ function createChatCommandRequest({ socket, text, sendSystemMessage }) {
     actor: {
       bot: false,
       id: socket.id,
+      /*
+        Fun command tallies are keyed by identity rather than connection, so the
+        canonical user id is passed alongside the socket id. Without it a user's
+        bonk count would reset on every reconnect and split across browser tabs.
+      */
+      userId: String(socket?.data?.userId || '').trim() || null,
       label: nickname,
       isAdmin: isAdmin(socket),
       isLockdownAdmin: isLockdownAdmin(socket),
@@ -176,9 +198,28 @@ async function runChatTextCommand({ text, socket, sendSystemMessage }) {
     listVerifiedUsers,
     removeVerifiedUser,
     listDeterredUsers,
+    listMutedUsers,
     deterUser,
     undeterUser,
+    muteUser,
+    unmuteUser,
+    listAudioGainBoostUsers,
+    grantAudioGainBoost,
+    revokeAudioGainBoost,
     sanitizeMentions,
+    funStatsService,
+    commandCooldowns,
+    // Lets `rs bonk` announce itself so audioForwardService can play the bonk
+    // sound on the rover the target is driving.
+    publishEvent,
+    /*
+      Fun commands that move hardware need the sending socket so they can prove
+      the caller holds control. issueCommand is required lazily for the same
+      reason replayEngineV2 is: commandService registers socket handlers on load,
+      and chatService should not pull that forward in the boot order.
+    */
+    getActorSocket: () => socket,
+    issueCommand: (roverId, payload) => require('../commandService').issueCommand(roverId, payload),
     sendToChannel: null,
     isAdminUser: (id) => String(id) === String(socket.id) && isAdmin(socket),
     isLockdownAdminUser: (id) => String(id) === String(socket.id) && isLockdownAdmin(socket),

server/src/services/commandService/index.js

@@ -2,13 +2,21 @@
 // Purpose: Defines the command Service module and the helpers/state used by this service unit.
 // Scope: Keeps runtime behavior unchanged while isolating responsibilities into a clear module boundary.
 const { v4: uuidv4 } = require('uuid');
+const EventEmitter = require('events');
 const io = require('../../globals/io');
 const roverManager = require('../roverManager');
 const { isAdmin, isLockdownAdmin } = require('../roleService');
-const { isDeterred } = require('../verificationService');
+const { isDeterred, isMuted } = require('../verificationService');
 const logger = require('../../globals/logger').child('commandService');
 const { isHeadlightBlocked } = require('../../rewards/definitions/darkness');
 const homeAssistantService = require('../homeAssistantService');
+const overcurrentProtectionService = require('../overcurrentProtectionService');
+
+// Command observations are intentionally separate from the global event bus.
+// Drive and motor commands can run at control-loop frequency, and publishing
+// every packet onto the logging event bus would manufacture noise. Optional
+// observers can aggregate this emitter without changing command delivery.
+const commandEvents = new EventEmitter();
 
 const pendingCommands = new Map(); // id -> { roverId }
 const lastDriveActivity = new Map(); // roverId -> { ts, socketId, direction, speed, isAdmin }
@@ -93,6 +101,31 @@ function issueCommand(roverId, payload) {
   return id;
 }
 
+/*
+  The protection service owns decisions about when a held command must be
+  resent at a lower output. Injecting this raw transport function keeps those
+  resends on the same rover websocket path as every other server command while
+  avoiding a circular dependency from the protection service back into this
+  socket-facing module.
+*/
+overcurrentProtectionService.configureCommandIssuer((roverId, payload) => {
+  const blockedUntil = driveCooldowns.get(roverId);
+  const safetyCooldownActive = blockedUntil && Date.now() < blockedUntil;
+  if (safetyCooldownActive && getCommandMotionMagnitude(payload?.type, payload) > 0) {
+    /*
+      Private-rover and dock safety own the existing command cooldown map. A
+      rate-limited protection resend must respect those independent systems;
+      otherwise this new service could restart drive or brushes immediately
+      after an unrelated safety feature deliberately stopped them. Returning
+      false tells the protection service to retry after the cooldown instead of
+      recording an output that never reached the rover.
+    */
+    return false;
+  }
+  issueCommand(roverId, payload);
+  return true;
+});
+
 function handleAck(msg) {
   const pending = pendingCommands.get(msg.id);
   if (!pending) return;
@@ -104,6 +137,16 @@ function handleAck(msg) {
     status: msg.status || 'ok',
     error: msg.error,
   });
+  commandEvents.emit('observation', {
+    ts: Date.now(),
+    roverId: pending.roverId,
+    type: pending.type,
+    commandId: msg.id,
+    outcome: msg.error ? 'failed' : 'acknowledged',
+    latencyMs: Date.now() - pending.ts,
+    status: msg.status || 'ok',
+    error: msg.error || null,
+  });
 }
 
 function issueUpdateToAllRovers() {
@@ -211,6 +254,7 @@ module.exports = {
   handleAck,
   getRecentDriveActivity,
   setDriveCooldown,
+  commandEvents,
 };
 
 io.on('connection', (socket) => {
@@ -226,7 +270,7 @@ io.on('connection', (socket) => {
       if (type === 'audioLevels') {
         throw new Error('audioLevels command is service-managed');
       }
-      const payload = data ? { ...data } : {};
+      let payload = data ? { ...data } : {};
       if (type === 'headlight' && isHeadlightBlocked()) {
         logger.info('Ignoring headlight command while darkness lock is active', { socketId: socket.id, roverId });
         reply({ ignored: true, reason: 'darknessActive' });
@@ -248,6 +292,14 @@ io.on('connection', (socket) => {
       if (!isAdminSocket && isDeterred(socket)) {
         throw new Error('Not authorized');
       }
+      /*
+        Both structured song commands and raw Open Interface song payloads
+        reach this shared flag. Enforcing mute here covers the VIP MIDI beeper
+        and any future browser beeper without affecting unrelated driving.
+      */
+      if (!isAdminSocket && isSongCommand && isMuted(socket)) {
+        throw new Error('Muted');
+      }
       // Rover updates run a privileged, root-owned helper on the Pi. Keep this
       // in the same explicit admin-only branch as reboot instead of relying on
       // drive ownership checks, because having a turn should not grant system
@@ -291,7 +343,31 @@ io.on('connection', (socket) => {
           });
         }
       }
+
+      if (type === 'drive' || type === 'motors') {
+        /*
+          Role is supplied at the command boundary because telemetry does not
+          identify the operator who produced the active motor intent. Admin and
+          lockdown commands therefore enter the service explicitly bypassed;
+          they are recorded for status visibility but are never scaled, blocked,
+          or countermanded by a later sensor frame.
+        */
+        payload = overcurrentProtectionService.protectCommand(roverId, type, payload, {
+          bypassed: isAdminSocket,
+        });
+      }
       const id = issueCommand(roverId, { type, ...payload });
+      commandEvents.emit('observation', {
+        ts: Date.now(),
+        roverId: String(roverId),
+        type,
+        commandId: id,
+        outcome: 'issued',
+        socketId: socket.id,
+        // Payloads are omitted deliberately: raw OI, TTS, and maintenance
+        // commands can carry arbitrary content. Their structured type/outcome
+        // supplies analytics without accidentally persisting secret material.
+      });
       logger.info('Queued command', socket.id, roverId, type);
       if (shouldRecordTurnActivity(type, payload)) {
         try {
@@ -304,6 +380,14 @@ io.on('connection', (socket) => {
       reply({ id });
     } catch (err) {
       logger.warn('Command rejected', socket.id, err.message);
+      commandEvents.emit('observation', {
+        ts: Date.now(),
+        roverId: roverId ? String(roverId) : null,
+        type: type || 'unknown',
+        outcome: 'rejected',
+        socketId: socket.id,
+        error: err.message,
+      });
       reply({ error: err.message });
     }
   }

server/src/services/discordBotService/commands/replay.js

@@ -12,7 +12,7 @@ const {
   createReplaySourceResolver,
   createReplayCaptionBuilder,
   startDiscordTypingLoop,
-  sanitizeReplayTitleForFilename,
+  buildReplayFilename,
   firstAttachmentFromMessage,
   buildDiscordReplayMediaPayload,
   buildAcceptedMessage,
@@ -103,7 +103,9 @@ function createReplayCommand({
         await progressMessage.edit({ content: sanitizeMentions(buildStatusMessage(job, 'uploading')), allowedMentions: DEFAULT_ALLOWED_MENTIONS });
       }
 
-      const attachment = new AttachmentBuilder(buffer, { name: `${sanitizeReplayTitleForFilename(job.title)}.mp4` });
+      // Keep direct Discord commands consistent with web-triggered uploads and
+      // with the local hosting fallback used when Discord delivery is unavailable.
+      const attachment = new AttachmentBuilder(buffer, { name: buildReplayFilename(job) });
       const body = replayCaption.build({ job, usedSources, missingSources });
       const uploadMessage = await progressMessage.reply({
         content: body,

server/src/services/discordBotService/fleetDailyReports.js

@@ -0,0 +1,149 @@
+// Discord Fleet Daily Reports
+// Purpose: Schedules and delivers completed-day fleet summaries to the existing admin alert channel.
+// Scope: Discord owns timing/formatting/delivery; the fleet service owns evidence, analysis, and durable delivery state.
+const { DateTime } = require('luxon');
+const { EmbedBuilder } = require('discord.js');
+
+function parseSendTime(value) {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(String(value || '').trim());
+  if (!match) return { hour: 8, minute: 0 };
+  return {
+    hour: Math.max(0, Math.min(23, Number(match[1]))),
+    minute: Math.max(0, Math.min(59, Number(match[2]))),
+  };
+}
+
+function nextRunAt({ zone, hour, minute }) {
+  const now = DateTime.now().setZone(zone);
+  let next = now.set({ hour, minute, second: 0, millisecond: 0 });
+  if (next <= now) next = next.plus({ days: 1 });
+  return next;
+}
+
+function formatNumber(value, digits = 1) {
+  return Number(value || 0).toLocaleString(undefined, { maximumFractionDigits: digits });
+}
+
+function createFleetDailyReports({ logger, discordConfig, fleetConfig, fleetReportService, roverManager, sendToChannel }) {
+  let timer = null;
+  const reportConfig = fleetConfig?.discord || {};
+  const enabled = fleetReportService?.enabled && reportConfig.enabled !== false;
+  const channelId = discordConfig?.channels?.adminAlerts;
+  const zone = String(reportConfig.timezone || 'America/New_York');
+  const { hour, minute } = parseSendTime(reportConfig.sendAt);
+
+  function publicRoverIds() {
+    // Discord's shared admin-alert channel does not provide a per-viewer socket
+    // against which private-rover grants can be checked. Excluding private
+    // rovers here preserves the existing privacy boundary instead of assuming
+    // every channel reader has every private grant.
+    return roverManager.getRoster()
+      .filter((rover) => !rover?.private?.enabled)
+      .map((rover) => String(rover.id));
+  }
+
+  function completedDayRange() {
+    const end = DateTime.now().setZone(zone).startOf('day');
+    const start = end.minus({ days: 1 });
+    return {
+      reportDate: start.toISODate(),
+      since: start.toMillis(),
+      until: end.toMillis(),
+    };
+  }
+
+  function buildEmbed(reportDate, report) {
+    const totals = report.totals;
+    const attention = report.attention
+      .filter((item) => item.severity !== 'notice')
+      .slice(0, 12)
+      .map((item) => `• ${item.roverId}: ${item.title}`)
+      .join('\n') || 'No material battery or efficiency changes need attention.';
+    const roverLines = report.rovers.map((rover) => {
+      const health = rover.batteryHealth || {};
+      const efficiency = rover.overallWhPerKm == null
+        ? `efficiency pending (${formatNumber(rover.distanceMm / 1000, 0)} m)`
+        : `${formatNumber(rover.overallWhPerKm)} Wh/km`;
+      const capacity = health.measuredUsableMah == null
+        ? `health collecting (${health.confidence || 'low'} confidence)`
+        : `${formatNumber(health.measuredUsableMah / 1000, 2)} Ah usable · ${formatNumber(health.capacityRetentionPercent)}% retained · ${health.confidence} confidence`;
+      return `• ${rover.name}: ${formatNumber(rover.distanceMm / 1e6, 2)} km · ${formatNumber(rover.dischargedWh, 2)} Wh · ${efficiency}\n  Battery: ${capacity}`;
+    }
+    ).join('\n') || 'No public rover telemetry.';
+    return new EmbedBuilder()
+      .setTitle(`Daily fleet report — ${reportDate}`)
+      .setColor(totals.attentionCount ? 0xf0b651 : 0x4caf50)
+      .addFields(
+        {
+          name: 'Fleet energy',
+          value: `${formatNumber(totals.distanceMm / 1e6, 2)} km · ${formatNumber(totals.dischargedWh, 2)} Wh · ${totals.overallWhPerKm == null ? 'efficiency pending' : `${formatNumber(totals.overallWhPerKm)} Wh/km`} · ${formatNumber(totals.stationaryDischargedWh, 2)} stationary Wh`,
+        },
+        { name: 'Needs attention', value: attention.slice(0, 1024) },
+        { name: 'Rovers', value: roverLines.slice(0, 1024) },
+      )
+      .setFooter({ text: 'The server reports page contains the complete all-rovers metric table.' });
+  }
+
+  async function deliverPreviousDay() {
+    if (!enabled || !channelId) return;
+    const range = completedDayRange();
+    const existing = fleetReportService.storage.getDailyReport(range.reportDate);
+    if (existing?.discordDeliveredAt) return;
+    const report = fleetReportService.getDailyReport({
+      since: range.since,
+      until: range.until,
+      roverIds: publicRoverIds(),
+    });
+    if (!report) return;
+    /*
+      Daily storage retains the exact metric report used for delivery, but the
+      Discord message intentionally has no raw JSON attachment. Admins need
+      actionable fleet comparisons here; the complete read-only evidence stays
+      on the reports page without turning routine events into notification noise.
+    */
+    fleetReportService.storage.saveDailyReport(range.reportDate, report);
+    const sent = await sendToChannel(
+      channelId,
+      `Daily fleet report for ${range.reportDate}`,
+      { embeds: [buildEmbed(range.reportDate, report)] },
+      { parse: [] },
+    );
+    if (sent) {
+      fleetReportService.storage.markDailyReportDelivery(range.reportDate, { deliveredAt: Date.now(), error: null });
+    } else {
+      fleetReportService.storage.markDailyReportDelivery(range.reportDate, { error: 'Discord delivery returned no message' });
+    }
+  }
+
+  function scheduleNext() {
+    if (!enabled || !channelId) return;
+    const next = nextRunAt({ zone, hour, minute });
+    const delay = Math.max(1000, next.toMillis() - Date.now());
+    timer = setTimeout(async () => {
+      try {
+        await deliverPreviousDay();
+      } catch (err) {
+        logger.warn('Daily fleet report delivery failed', { error: err.message });
+      } finally {
+        scheduleNext();
+      }
+    }, delay);
+    timer.unref?.();
+    logger.info('Scheduled daily fleet report', { nextRunAt: next.toISO(), channelId });
+  }
+
+  function start() {
+    scheduleNext();
+  }
+
+  function stop() {
+    if (timer) clearTimeout(timer);
+    timer = null;
+  }
+
+  return { start, stop, deliverPreviousDay };
+}
+
+module.exports = {
+  createFleetDailyReports,
+};

server/src/services/discordBotService/index.js

@@ -41,8 +41,14 @@ const {
   listVerifiedUsers,
   removeVerifiedUser,
   listDeterredUsers,
+  listMutedUsers,
   deterUser,
   undeterUser,
+  muteUser,
+  unmuteUser,
+  listAudioGainBoostUsers,
+  grantAudioGainBoost,
+  revokeAudioGainBoost,
 } = require('../verificationService');
 const {
   attachDmMessage: attachPrivateAccessDmMessage,
@@ -50,18 +56,23 @@ const {
   approveRequest: approvePrivateAccessRequest,
   denyRequest: denyPrivateAccessRequest,
 } = require('../privateRoverAccessRequestService');
-const { subscribe } = require('../eventBus');
+const { subscribe, publishEvent } = require('../eventBus');
+const funStatsService = require('../funStatsService');
+const { issueCommand } = require('../commandService');
 const { createPresenceManager } = require('./presence');
 const { createChannelIO } = require('./channelIO');
 const { createCommandHandlers } = require('../operatorCommandService');
+const { createCooldownGate } = require('../operatorCommandService/cooldowns');
 const { createDiscordTransportHandlers, createDiscordCommandRequest } = require('./commandAdapter');
 const { createIntegrations } = require('./integrations');
+const { createFleetDailyReports } = require('./fleetDailyReports');
+const fleetReportService = require('../fleetReportService');
 const { registerPreferredDeliveryProvider } = require('../replayDeliveryService');
 const {
   DEFAULT_ALLOWED_MENTIONS,
   createReplayCaptionBuilder,
   startDiscordTypingLoop,
-  sanitizeReplayTitleForFilename,
+  buildReplayFilename,
   firstAttachmentFromMessage,
   buildDiscordReplayMediaPayload,
   buildAcceptedMessage,
@@ -164,7 +175,9 @@ if (discordConfig?.channels?.replay) {
         if (progressMessage?.edit) {
           await progressMessage.edit({ content: buildStatusMessage(job, 'uploading'), allowedMentions: DEFAULT_ALLOWED_MENTIONS });
         }
-        const attachment = new AttachmentBuilder(buffer, { name: `${sanitizeReplayTitleForFilename(job.title)}.mp4` });
+        // Every delivery path uses the job creation time, so a Discord upload
+        // and a server-hosted fallback always expose the same replay filename.
+        const attachment = new AttachmentBuilder(buffer, { name: buildReplayFilename(job) });
         const body = replayCaption.build({ job, usedSources, missingSources });
         const uploadMessage = await channelIO.sendToChannel(context.channelId, body, { files: [attachment] }, DEFAULT_ALLOWED_MENTIONS);
         if (!uploadMessage) throw new Error('Discord upload did not return a message');
@@ -199,6 +212,10 @@ if (discordConfig?.channels?.replay) {
   });
 }
 
+// The Discord router is built once for the process, so one gate here covers every
+// guild and channel this bot answers in.
+const commandCooldowns = createCooldownGate();
+
 const commandDependencies = {
   logger,
   client,
@@ -238,9 +255,27 @@ const commandDependencies = {
   listVerifiedUsers,
   removeVerifiedUser,
   listDeterredUsers,
+  listMutedUsers,
   deterUser,
   undeterUser,
+  muteUser,
+  unmuteUser,
+  listAudioGainBoostUsers,
+  grantAudioGainBoost,
+  revokeAudioGainBoost,
   sanitizeMentions,
+  funStatsService,
+  commandCooldowns,
+  // A Discord bonk still plays the sound on the rover the target is driving; only
+  // the commands that need the caller's own socket are unavailable from here.
+  publishEvent,
+  /*
+    Discord has no socket behind a message, so the hardware-backed fun commands
+    cannot prove drive control and decline with an explanation instead. The text,
+    counter, and read-only fun commands work normally from here.
+  */
+  getActorSocket: () => null,
+  issueCommand,
   sendToChannel: channelIO.sendToChannel,
   isAdminUser,
   isLockdownAdminUser,
@@ -347,6 +382,17 @@ client.on('messageCreate', async (message) => {
 client.once('ready', () => {
   logger.info('Discord bot logged in', { tag: client.user?.tag });
   presence.schedulePresenceRotation();
+  // Discord is only a delivery consumer. Starting its scheduler after the bot
+  // is ready avoids failed sends during login while the collector continues to
+  // operate independently of Discord availability.
+  createFleetDailyReports({
+    logger,
+    discordConfig,
+    fleetConfig: config.fleetReports || {},
+    fleetReportService,
+    roverManager,
+    sendToChannel: channelIO.sendToChannel,
+  }).start();
 });
 
 client.login(discordConfig.token).catch((err) => {

server/src/services/embedHttpService/index.js

@@ -2,9 +2,14 @@
 // Purpose: Defines the embed Http Service module and the helpers/state used by this service unit.
 // Scope: Keeps runtime behavior unchanged while isolating responsibilities into a clear module boundary.
 const { app } = require('../../globals/http');
-const { renderIndexHtml, renderOgImage } = require('../embedService');
+const { renderIndexHtml, renderOgImage, renderWebManifest } = require('../embedService');
 
-app.get(['/', '/spectate', '/mini', '/display', '/scanner', '/database'], async (req, res) => {
+/*
+  Every client-side BrowserRouter entry point must also be an explicit HTTP
+  entry point. Including /ptz here lets direct loads and browser refreshes
+  receive the same rendered index document as navigation from the driver page.
+*/
+app.get(['/', '/spectate', '/mini', '/display', '/scanner', '/database', '/ptz', '/reports'], async (req, res) => {
   try {
     const html = await renderIndexHtml(req);
     res.type('html').send(html);
@@ -22,3 +27,13 @@ app.get('/og/preview.png', async (req, res) => {
     res.status(500).send('Failed to render embed image');
   }
 });
+
+app.get('/manifest.webmanifest', (req, res) => {
+  /*
+    The manifest varies with server configuration, so it is served by the
+    application rather than copied into Vite's static output. Revalidation
+    lets browsers pick up branding changes after the server is restarted.
+  */
+  res.set('Cache-Control', 'no-cache');
+  res.type('application/manifest+json').send(renderWebManifest());
+});

server/src/services/embedService/index.js

@@ -2,26 +2,60 @@
 // Purpose: Defines the embed Service module and the helpers/state used by this service unit.
 // Scope: Keeps runtime behavior unchanged while isolating responsibilities into a clear module boundary.
 const path = require('path');
+const fs = require('fs');
 const fsp = require('fs/promises');
 const sharp = require('sharp');
 
+const logger = require('../../globals/logger').child('embedService');
 const { getMode } = require('../modeManager');
 const roverManager = require('../roverManager');
 const { getActiveDrivers, getTurnQueues } = require('../turnService');
 const { getRoomCameras } = require('../roomCameraService');
 const { getRoomCameraState } = require('../roomCameraService');
-const { loadConfig } = require('../../helpers/configLoader');
+const { resolveDataPath } = require('../../helpers/dataPaths');
+const { resolveSiteMetadata } = require('../../helpers/siteMetadata');
 
 const INDEX_HTML_PATH = path.join(__dirname, '..', '..', '..', 'public', 'index.html');
 const BITMAP_PATH = path.join(__dirname, '..', '..', '..', 'public', 'bitmap.png');
+const ANALYTICS_HTML_PATH = resolveDataPath('analytics.html');
+const ANALYTICS_PLACEHOLDER = '<!-- analytics:inject -->';
+const SITE_METADATA_PLACEHOLDER = '<!-- site-metadata:inject -->';
 
 const OG_WIDTH = 1200;
 const OG_HEIGHT = 630;
-const BASE_BG = { r: 8, g: 12, b: 22 };
 
 let cachedIndexHtml = null;
 let cachedIndexMtimeMs = 0;
 
+/*
+  Analytics provider markup belongs to the server operator, not to the shared
+  web build. Loading the snippet once at process startup makes deployment
+  behavior predictable: replacing analytics.html takes effect on the next
+  normal server restart, and no analytics configuration needs to travel over
+  Socket.IO or be exposed through a JSON endpoint.
+
+  This file is intentionally trusted as raw HTML. Anyone able to write files in
+  the server data directory already controls the deployment, and allowing a
+  complete head snippet is what keeps this integration compatible with Umami,
+  Plausible, Matomo, or a custom provider without provider-specific server code.
+*/
+function loadAnalyticsHeadHtml() {
+  if (!fs.existsSync(ANALYTICS_HTML_PATH)) return '';
+
+  try {
+    return fs.readFileSync(ANALYTICS_HTML_PATH, 'utf8').trim();
+  } catch (err) {
+    /*
+      Analytics is observability-only, so a permissions or read error must not
+      prevent operators and drivers from loading the rover controls.
+    */
+    logger.warn('Unable to read analytics head HTML; continuing without analytics', err.message);
+    return '';
+  }
+}
+
+const analyticsHeadHtml = loadAnalyticsHeadHtml();
+
 function escapeHtml(value) {
   return String(value || '')
     .replace(/&/g, '&amp;')
@@ -52,6 +86,20 @@ function getBaseUrl(req) {
   return `${proto}://${host}`;
 }
 
+function getPagePath(req) {
+  /*
+    Canonical URLs should describe the page rather than a tracking/query
+    variant of it. Express's path value excludes the query string and is safe
+    to combine with either the configured public URL or the current request.
+  */
+  return req.path || '/';
+}
+
+function joinPublicUrl(baseUrl, pagePath) {
+  const normalizedPath = pagePath.startsWith('/') ? pagePath : `/${pagePath}`;
+  return `${baseUrl}${normalizedPath}`;
+}
+
 function getPrimaryRoomCamera() {
   const cameras = getRoomCameras();
   if (!cameras.length) return null;
@@ -86,33 +134,6 @@ function buildEmbedCopy(state, camera) {
     lockdown: 'locked',
   }[mode] || mode;
 
-  let title = 'Roomba Rover';
-  if (mode === 'lockdown') {
-    title = 'Private mode is on';
-  } else if (roversOnline === 0) {
-    title = 'Rovers offline - check back soon';
-  } else if (driverCount > 0) {
-    title = 'Rovers in use - drive a rover';
-  } else if (mode === 'turns') {
-    title = 'Controls open - jump in';
-  } else {
-    title = 'Controls open - drive a rover';
-  }
-
-  const descriptionParts = [];
-  descriptionParts.push(`${roversOnline} rover${roversOnline === 1 ? '' : 's'} online`);
-  if (driverCount > 0) {
-    descriptionParts.push(`${driverCount} driving`);
-  } else {
-    descriptionParts.push('no active drivers');
-  }
-  if (mode === 'lockdown') {
-    descriptionParts.push('privacy mode');
-  } else {
-    descriptionParts.push(modeLabel);
-  }
-  const description = descriptionParts.join(' | ');
-
   const statsParts = [
     `${roversOnline} online`,
     driverCount > 0 ? `${driverCount} driving` : 'no drivers',
@@ -125,20 +146,17 @@ function buildEmbedCopy(state, camera) {
 
   const cameraLabel = camera?.name || camera?.id || 'room cam';
   return {
-    title,
-    description,
-    subtitle: 'Control a live rover from your browser',
     stats: statsParts.join(' | '),
     cameraLabel: mode === 'lockdown' ? 'Room cams hidden' : `Room cam: ${cameraLabel}`,
   };
 }
 
-function buildMetaTags({ title, description, imageUrl, pageUrl }) {
+function buildMetaTags({ title, description, imageUrl, pageUrl, canonicalUrl }) {
   const safeTitle = escapeHtml(title);
   const safeDescription = escapeHtml(description);
   const safeImage = escapeHtml(imageUrl);
   const safeUrl = escapeHtml(pageUrl);
-  return [
+  const tags = [
     '<!-- embed meta -->',
     `<meta name="description" content="${safeDescription}" />`,
     `<meta property="og:title" content="${safeTitle}" />`,
@@ -153,7 +171,27 @@ function buildMetaTags({ title, description, imageUrl, pageUrl }) {
     `<meta name="twitter:title" content="${safeTitle}" />`,
     `<meta name="twitter:description" content="${safeDescription}" />`,
     `<meta name="twitter:image" content="${safeImage}" />`,
-    '<!-- /embed meta -->',
+  ];
+
+  /*
+    Only advertise a canonical address when the operator supplied a valid
+    public URL. Guessing from request headers would permanently identify a LAN
+    hostname or reverse-proxy hop as the public home of the instance.
+  */
+  if (canonicalUrl) {
+    tags.push(`<link rel="canonical" href="${escapeHtml(canonicalUrl)}" />`);
+  }
+  tags.push('<!-- /embed meta -->');
+  return tags.join('\n    ');
+}
+
+function buildSiteMetadataTags(siteMetadata) {
+  return [
+    '<!-- site metadata -->',
+    `<meta name="theme-color" content="${escapeHtml(siteMetadata.accentColor)}" />`,
+    `<meta name="apple-mobile-web-app-title" content="${escapeHtml(siteMetadata.shortName)}" />`,
+    `<title>${escapeHtml(siteMetadata.name)}</title>`,
+    '<!-- /site metadata -->',
   ].join('\n    ');
 }
 
@@ -165,23 +203,47 @@ async function renderIndexHtml(req) {
     activeDrivers: getActiveDrivers(),
     turnQueues: getTurnQueues(),
   };
-  const config = loadConfig();
+  const siteMetadata = resolveSiteMetadata();
-  const pageTitle = config?.site?.title || 'Roomba Rover';
   const camera = getPrimaryRoomCamera();
   const copy = buildEmbedCopy(state, camera);
   const cacheBust = Math.floor(Date.now() / (5 * 60 * 1000));
   const imageUrl = `${baseUrl}/og/preview.png?t=${cacheBust}`;
-  const pageUrl = `${baseUrl}${req.originalUrl || '/'}`;
+  const pagePath = getPagePath(req);
+  const canonicalUrl = siteMetadata.publicUrl
+    ? joinPublicUrl(siteMetadata.publicUrl, pagePath)
+    : null;
+  const pageUrl = canonicalUrl || joinPublicUrl(baseUrl, pagePath);
 
   const metaBlock = buildMetaTags({
-    title: pageTitle,
+    title: siteMetadata.name,
-    description: copy.description,
+    description: siteMetadata.description,
     imageUrl,
     pageUrl,
+    canonicalUrl,
   });
+  const siteMetadataBlock = buildSiteMetadataTags(siteMetadata);
 
   let html = await loadIndexHtml();
-  html = html.replace(/<title>.*?<\/title>/i, `<title>${escapeHtml(pageTitle)}</title>`);
+  /*
+    Prefer the explicit marker so the insertion point remains stable across
+    Vite output changes. The closing-head fallback also keeps deployed builds
+    made before the marker was introduced compatible with the runtime loader.
+  */
+  if (html.includes(ANALYTICS_PLACEHOLDER)) {
+    html = html.replace(ANALYTICS_PLACEHOLDER, analyticsHeadHtml);
+  } else if (analyticsHeadHtml) {
+    html = html.replace('</head>', `    ${analyticsHeadHtml}\n  </head>`);
+  }
+  /*
+    Keeping all instance-specific head values behind one marker prevents the
+    built index from carrying a second set of hardcoded titles and colors.
+    The fallback supports an older built index during a rolling deployment.
+  */
+  if (html.includes(SITE_METADATA_PLACEHOLDER)) {
+    html = html.replace(SITE_METADATA_PLACEHOLDER, siteMetadataBlock);
+  } else {
+    html = html.replace('</head>', `    ${siteMetadataBlock}\n  </head>`);
+  }
   if (html.includes('<!-- embed meta -->')) {
     html = html.replace(/<!-- embed meta -->[\s\S]*?<!-- \/embed meta -->/i, metaBlock);
   } else {
@@ -190,7 +252,7 @@ async function renderIndexHtml(req) {
   return html;
 }
 
-function buildOverlaySvg({ title, subtitle, stats, cameraLabel, hasFrame }) {
+function buildOverlaySvg({ title, subtitle, stats, cameraLabel, hasFrame, accentColor, accentTextColor }) {
   const titleSize = 64;
   const subtitleSize = 34;
   const statsSize = 30;
@@ -207,8 +269,8 @@ function buildOverlaySvg({ title, subtitle, stats, cameraLabel, hasFrame }) {
   </defs>
   <rect width="${OG_WIDTH}" height="${OG_HEIGHT}" fill="url(#fade)" />
   <rect x="56" y="48" width="210" height="40" rx="20" fill="rgba(0,0,0,0.55)" />
-  <rect x="58" y="50" width="206" height="36" rx="18" fill="#22d3ee" />
+  <rect x="58" y="50" width="206" height="36" rx="18" fill="${accentColor}" />
-  <text x="160" y="75" font-family="DejaVu Sans, Arial, sans-serif" font-size="20" font-weight="700" text-anchor="middle" fill="#001018">
+  <text x="160" y="75" font-family="DejaVu Sans, Arial, sans-serif" font-size="20" font-weight="700" text-anchor="middle" fill="${accentTextColor}">
     ${escapeXml(badgeText)}
   </text>
   <text x="64" y="410" font-family="DejaVu Sans, Arial, sans-serif" font-size="${titleSize}" font-weight="700" fill="#ffffff">
@@ -235,6 +297,7 @@ async function renderOgImage() {
   };
   const camera = getPrimaryRoomCamera();
   const copy = buildEmbedCopy(state, camera);
+  const siteMetadata = resolveSiteMetadata();
   const cameraState = state.mode === 'lockdown' || !camera ? null : getRoomCameraState(camera.id);
   const frame = cameraState?.frame || null;
   const hasFrame = Boolean(frame);
@@ -246,17 +309,20 @@ async function renderOgImage() {
           width: OG_WIDTH,
           height: OG_HEIGHT,
           channels: 3,
-          background: BASE_BG,
+          background: siteMetadata.backgroundColor,
         },
       });
 
   const overlaySvg = Buffer.from(
     buildOverlaySvg({
-      title: copy.title,
+      title: siteMetadata.name,
-      subtitle: copy.subtitle,
+      // The image must use the same resolved description as the page metadata and installed shortcut.
+      subtitle: siteMetadata.description,
       stats: copy.stats,
       cameraLabel: copy.cameraLabel,
       hasFrame,
+      accentColor: siteMetadata.accentColor,
+      accentTextColor: siteMetadata.accentTextColor,
     }),
   );
 
@@ -272,7 +338,36 @@ async function renderOgImage() {
   return base.composite(composite).png().toBuffer();
 }
 
+function renderWebManifest() {
+  const siteMetadata = resolveSiteMetadata();
+
+  /*
+    The manifest is generated from the same resolved values as the HTML and
+    social image, so browser tabs, installed shortcuts, and launch screens do
+    not drift into three separately configured identities.
+  */
+  return JSON.stringify({
+    name: siteMetadata.name,
+    short_name: siteMetadata.shortName,
+    description: siteMetadata.description,
+    start_url: '/',
+    scope: '/',
+    display: 'standalone',
+    background_color: siteMetadata.backgroundColor,
+    theme_color: siteMetadata.accentColor,
+    icons: [
+      {
+        src: '/bitmap.png',
+        sizes: '512x512',
+        type: 'image/png',
+        purpose: 'any',
+      },
+    ],
+  });
+}
+
 module.exports = {
   renderIndexHtml,
   renderOgImage,
+  renderWebManifest,
 };

server/src/services/fleetReportService/collector.js

@@ -0,0 +1,629 @@
+// Fleet Report Collector
+// Purpose: Converts existing server events and high-rate rover sensor frames into bounded historical evidence.
+// Scope: Performs passive normalization, battery-current integration, minute aggregation, and battery-session classification.
+const crypto = require('crypto');
+
+const MINUTE_MS = 60 * 1000;
+const FULL_WAIT_MS = 5 * 60 * 1000;
+const SESSION_KIND_CONFIRM_SAMPLES = 3;
+
+function finite(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function minimum(previous, value) {
+  if (value == null) return previous;
+  return previous == null ? value : Math.min(previous, value);
+}
+
+function maximum(previous, value) {
+  if (value == null) return previous;
+  return previous == null ? value : Math.max(previous, value);
+}
+
+function eventRoverId(event) {
+  const payload = event?.payload || {};
+  // Generic payload `id` fields are commonly message, request, or job IDs and
+  // must not be mistaken for rover identities. Producers use roverId (or an
+  // explicit rover object) whenever the existing privacy resolver should scope
+  // an event to a physical rover.
+  return payload.roverId || payload.rover?.id || null;
+}
+
+function inferVisibility(event) {
+  const payload = event?.payload || {};
+  // Producers that know a stricter visibility scope may attach it explicitly.
+  // Otherwise rover-scoped events are filtered later against the same visible
+  // roster that drives the live UI, while verification/auth details retain the
+  // existing lockdown-only boundary.
+  if (payload.visibility) return String(payload.visibility);
+  if (event?.source === 'verification' || event?.source === 'identity' || event?.source === 'auth') {
+    return 'lockdown';
+  }
+  return eventRoverId(event) ? 'rover' : 'global';
+}
+
+function inferSeverity(type = '') {
+  const value = String(type).toLowerCase();
+  if (/fault|critical|urgent|failed|failure/.test(value)) return 'critical';
+  if (/warn|offline|rejected|stopped|removed|denied/.test(value)) return 'warning';
+  if (/started|completed|online|resolved|updated/.test(value)) return 'notice';
+  return 'informational';
+}
+
+function batteryKey(roverId) {
+  // Until an admin registers a physical battery, the stable fallback keeps all
+  // observations attached to the rover without pretending the hardware has a
+  // serial number exposed by OI.
+  return `unregistered:${roverId}`;
+}
+
+function makeMinute(roverId, now) {
+  return {
+    roverId,
+    bucketTs: Math.floor(now / MINUTE_MS) * MINUTE_MS,
+    sampleCount: 0,
+    coverageMs: 0,
+    gapCount: 0,
+    chargedMah: 0,
+    dischargedMah: 0,
+    chargedWh: 0,
+    dischargedWh: 0,
+    movingDischargedWh: 0,
+    stationaryDischargedWh: 0,
+    movingMs: 0,
+    maximumSpeedMmPerSecond: null,
+    minVoltageMv: null,
+    maxVoltageMv: null,
+    voltageTotal: 0,
+    voltageCount: 0,
+    minCurrentMa: null,
+    maxCurrentMa: null,
+    currentTotal: 0,
+    currentCount: 0,
+    minTemperatureC: null,
+    maxTemperatureC: null,
+    temperatureTotal: 0,
+    temperatureCount: 0,
+    minChargeMah: null,
+    maxChargeMah: null,
+    lastChargeMah: null,
+    reportedCapacityMah: null,
+    dockedSamples: 0,
+    chargingSamples: 0,
+    commandCount: 0,
+    driveCommandCount: 0,
+    rejectedCommandCount: 0,
+    distanceMm: 0,
+    bumpCount: 0,
+    cliffCount: 0,
+    wheelDropCount: 0,
+    virtualWallCount: 0,
+    overcurrentEpisodeCount: 0,
+  };
+}
+
+function persistedMinute(minute) {
+  return {
+    roverId: minute.roverId,
+    bucketTs: minute.bucketTs,
+    sampleCount: minute.sampleCount,
+    coverageMs: Math.round(minute.coverageMs),
+    gapCount: minute.gapCount,
+    chargedMah: minute.chargedMah,
+    dischargedMah: minute.dischargedMah,
+    chargedWh: minute.chargedWh,
+    dischargedWh: minute.dischargedWh,
+    movingDischargedWh: minute.movingDischargedWh,
+    stationaryDischargedWh: minute.stationaryDischargedWh,
+    movingMs: Math.round(minute.movingMs),
+    maximumSpeedMmPerSecond: minute.maximumSpeedMmPerSecond,
+    minVoltageMv: minute.minVoltageMv,
+    maxVoltageMv: minute.maxVoltageMv,
+    avgVoltageMv: minute.voltageCount ? minute.voltageTotal / minute.voltageCount : null,
+    minCurrentMa: minute.minCurrentMa,
+    maxCurrentMa: minute.maxCurrentMa,
+    avgCurrentMa: minute.currentCount ? minute.currentTotal / minute.currentCount : null,
+    minTemperatureC: minute.minTemperatureC,
+    maxTemperatureC: minute.maxTemperatureC,
+    avgTemperatureC: minute.temperatureCount ? minute.temperatureTotal / minute.temperatureCount : null,
+    minChargeMah: minute.minChargeMah,
+    maxChargeMah: minute.maxChargeMah,
+    lastChargeMah: minute.lastChargeMah,
+    reportedCapacityMah: minute.reportedCapacityMah,
+    dockedSamples: minute.dockedSamples,
+    chargingSamples: minute.chargingSamples,
+    commandCount: minute.commandCount,
+    driveCommandCount: minute.driveCommandCount,
+    rejectedCommandCount: minute.rejectedCommandCount,
+    distanceMm: minute.distanceMm,
+    bumpCount: minute.bumpCount,
+    cliffCount: minute.cliffCount,
+    wheelDropCount: minute.wheelDropCount,
+    virtualWallCount: minute.virtualWallCount,
+    overcurrentEpisodeCount: minute.overcurrentEpisodeCount,
+  };
+}
+
+function newBatterySession(roverId, kind, now, sensors, state) {
+  return {
+    roverId,
+    batteryKey: state.batteryKey || batteryKey(roverId),
+    kind,
+    startedAt: now,
+    endedAt: null,
+    startChargeMah: finite(sensors?.batteryChargeMah),
+    endChargeMah: null,
+    chargedMah: 0,
+    dischargedMah: 0,
+    minVoltageMv: finite(sensors?.voltageMv),
+    maxVoltageMv: finite(sensors?.voltageMv),
+    minTemperatureC: finite(sensors?.batteryTemperatureC),
+    maxTemperatureC: finite(sensors?.batteryTemperatureC),
+    sampleCount: 0,
+    gapCount: 0,
+    status: 'open',
+    confidence: 'low',
+    qualificationReason: 'session is still open',
+    details: {
+      startedFromQualifiedFull: Boolean(state.fullQualifiedAt),
+      fullQualifiedAt: state.fullQualifiedAt,
+      warnMah: finite(state.lastBatteryState?.warn),
+      urgentMah: finite(state.lastBatteryState?.urgent),
+      configuredFullMah: finite(state.lastBatteryState?.full),
+    },
+  };
+}
+
+function observedSessionKind(sensors) {
+  const code = finite(sensors?.chargingState?.code);
+  const docked = Boolean(sensors?.chargingSources?.homeBase || sensors?.chargingSources?.internalCharger);
+  const current = finite(sensors?.currentMa);
+  if (docked && (code === 1 || code === 2 || code === 3 || (current != null && current > 25))) return 'charging';
+  if (!docked && current != null && current < -25) return 'discharging';
+  return 'idle';
+}
+
+function createCollector({ storage, logger, maximumIntegrationGapMs, minimumCapacityTestDepthPercent }) {
+  const roverStates = new Map();
+  const lastManagerSampleAt = new Map();
+  const diagnostics = {
+    startedAt: Date.now(),
+    eventsObserved: 0,
+    eventsStored: 0,
+    sensorFramesObserved: 0,
+    validBatteryFrames: 0,
+    integrationGaps: 0,
+    minuteWrites: 0,
+    sessionsCompleted: 0,
+    lastEventAt: null,
+    lastSensorAt: null,
+    lastError: null,
+  };
+
+  function stateFor(roverId, now) {
+    if (!roverStates.has(roverId)) {
+      roverStates.set(roverId, {
+        roverId,
+        lastAt: null,
+        minute: makeMinute(roverId, now),
+        candidateKind: null,
+        candidateCount: 0,
+        sessionKind: 'idle',
+        session: null,
+        waitingSince: null,
+        fullQualifiedAt: null,
+        lastBatteryState: null,
+        batteryKey: storage.getActiveBattery?.(roverId)?.batteryKey || batteryKey(roverId),
+        lastOdometerTotalMm: null,
+        safety: {
+          bump: false,
+          cliff: false,
+          wheelDrop: false,
+          virtualWall: false,
+          overcurrent: false,
+          overcurrentStartedAt: null,
+          overcurrentSamples: 0,
+        },
+      });
+    }
+    return roverStates.get(roverId);
+  }
+
+  function collectEvent(event = {}) {
+    diagnostics.eventsObserved += 1;
+    diagnostics.lastEventAt = Date.now();
+    try {
+      const normalized = {
+        ts: finite(event.ts) || Date.now(),
+        source: String(event.source || 'unknown'),
+        type: String(event.type || 'unknown'),
+        roverId: eventRoverId(event),
+        visibility: inferVisibility(event),
+        severity: inferSeverity(event.type),
+        correlationId: event?.payload?.correlationId || event?.payload?.jobId || event?.payload?.sessionId || null,
+        payload: event.payload ?? null,
+      };
+      if (storage.insertEvent(normalized)) diagnostics.eventsStored += 1;
+    } catch (err) {
+      diagnostics.lastError = err.message;
+      logger.warn('Fleet collector ignored malformed domain event', { error: err.message });
+    }
+  }
+
+  function updateMinute(minute, sensors, elapsedMs, chargedMah, dischargedMah, chargedWh, dischargedWh, gap) {
+    const voltage = finite(sensors?.voltageMv);
+    const current = finite(sensors?.currentMa);
+    const temperature = finite(sensors?.batteryTemperatureC);
+    const charge = finite(sensors?.batteryChargeMah);
+    const capacity = finite(sensors?.batteryCapacityMah);
+    minute.sampleCount += 1;
+    minute.coverageMs += elapsedMs;
+    minute.gapCount += gap ? 1 : 0;
+    minute.chargedMah += chargedMah;
+    minute.dischargedMah += dischargedMah;
+    minute.chargedWh += chargedWh;
+    minute.dischargedWh += dischargedWh;
+    /*
+      Movement classification deliberately consumes the center speed produced
+      by odometerService. That service already owns encoder rollover, physical
+      conversion, and impossible-jump rejection; duplicating those rules here
+      would allow reporting and the rover's actual odometer to disagree.
+    */
+    const speed = finite(sensors?.wheelSpeedsMmPerSecond?.center);
+    const moving = speed != null && Math.abs(speed) >= 1;
+    if (moving) {
+      minute.movingMs += elapsedMs;
+      minute.movingDischargedWh += dischargedWh;
+    } else {
+      minute.stationaryDischargedWh += dischargedWh;
+    }
+    minute.maximumSpeedMmPerSecond = maximum(minute.maximumSpeedMmPerSecond, speed == null ? null : Math.abs(speed));
+    minute.minVoltageMv = minimum(minute.minVoltageMv, voltage);
+    minute.maxVoltageMv = maximum(minute.maxVoltageMv, voltage);
+    if (voltage != null) { minute.voltageTotal += voltage; minute.voltageCount += 1; }
+    minute.minCurrentMa = minimum(minute.minCurrentMa, current);
+    minute.maxCurrentMa = maximum(minute.maxCurrentMa, current);
+    if (current != null) { minute.currentTotal += current; minute.currentCount += 1; }
+    minute.minTemperatureC = minimum(minute.minTemperatureC, temperature);
+    minute.maxTemperatureC = maximum(minute.maxTemperatureC, temperature);
+    if (temperature != null) { minute.temperatureTotal += temperature; minute.temperatureCount += 1; }
+    minute.minChargeMah = minimum(minute.minChargeMah, charge);
+    minute.maxChargeMah = maximum(minute.maxChargeMah, charge);
+    minute.lastChargeMah = charge;
+    minute.reportedCapacityMah = capacity;
+    if (sensors?.chargingSources?.homeBase) minute.dockedSamples += 1;
+    if (observedSessionKind(sensors) === 'charging') minute.chargingSamples += 1;
+  }
+
+  function finishSession(state, now, sensors, reason) {
+    const session = state.session;
+    if (!session) return;
+    session.endedAt = now;
+    session.endChargeMah = finite(sensors?.batteryChargeMah);
+    session.status = 'completed';
+
+    if (session.kind === 'discharging') {
+      const configuredFull = finite(session.details.configuredFullMah);
+      const startCharge = finite(session.startChargeMah);
+      const endCharge = finite(session.endChargeMah);
+      const reference = configuredFull || startCharge;
+      const observedDepth = reference && startCharge != null && endCharge != null
+        ? Math.max(0, ((startCharge - endCharge) / reference) * 100)
+        : 0;
+      const reachedLowEndpoint = Boolean(
+        state.lastBatteryState?.urgentActive ||
+        (finite(session.details.urgentMah) != null && endCharge != null && endCharge <= session.details.urgentMah),
+      );
+      const qualified = Boolean(
+        session.details.startedFromQualifiedFull &&
+        reachedLowEndpoint &&
+        observedDepth >= minimumCapacityTestDepthPercent &&
+        session.gapCount === 0,
+      );
+      session.details.observedDepthPercent = observedDepth;
+      session.details.reachedLowEndpoint = reachedLowEndpoint;
+      session.details.capacityTestQualified = qualified;
+      if (qualified) {
+        session.confidence = 'high';
+        session.qualificationReason = 'continuous qualified-full to low-endpoint discharge';
+      } else if (observedDepth >= 30 && session.gapCount <= 1) {
+        session.confidence = 'medium';
+        session.qualificationReason = reason || 'useful partial discharge; not a full capacity test';
+      } else {
+        session.confidence = 'low';
+        session.qualificationReason = reason || 'insufficient depth, endpoint, or telemetry coverage';
+      }
+    } else {
+      session.confidence = session.gapCount === 0 ? 'high' : session.gapCount <= 1 ? 'medium' : 'low';
+      session.qualificationReason = reason || 'charging session completed';
+    }
+
+    storage.insertBatterySession(session);
+    diagnostics.sessionsCompleted += 1;
+    state.session = null;
+  }
+
+  function applySessionKind(state, nextKind, now, sensors) {
+    if (nextKind === state.sessionKind) {
+      state.candidateKind = null;
+      state.candidateCount = 0;
+      return;
+    }
+    if (state.candidateKind !== nextKind) {
+      state.candidateKind = nextKind;
+      state.candidateCount = 1;
+      return;
+    }
+    state.candidateCount += 1;
+    if (state.candidateCount < SESSION_KIND_CONFIRM_SAMPLES) return;
+
+    finishSession(state, now, sensors, `state changed from ${state.sessionKind} to ${nextKind}`);
+    state.sessionKind = nextKind;
+    state.candidateKind = null;
+    state.candidateCount = 0;
+    if (nextKind === 'charging' || nextKind === 'discharging') {
+      state.session = newBatterySession(state.roverId, nextKind, now, sensors, state);
+      // A qualified-full marker is consumed by the next discharge. Leaving it
+      // set during the open session records the evidence in session details,
+      // while clearing it prevents later partial sessions from inheriting it.
+      if (nextKind === 'discharging') state.fullQualifiedAt = null;
+    }
+  }
+
+  function updateFullQualification(state, now, sensors) {
+    const waiting = finite(sensors?.chargingState?.code) === 4;
+    if (waiting) {
+      if (state.waitingSince == null) state.waitingSince = now;
+      if (now - state.waitingSince >= FULL_WAIT_MS && state.fullQualifiedAt == null) {
+        state.fullQualifiedAt = state.waitingSince + FULL_WAIT_MS;
+      }
+    } else {
+      state.waitingSince = null;
+    }
+  }
+
+  function collectSensor({ roverId, sensors, batteryState } = {}) {
+    diagnostics.sensorFramesObserved += 1;
+    diagnostics.lastSensorAt = Date.now();
+    if (!roverId || !sensors || finite(sensors.currentMa) == null) return;
+    diagnostics.validBatteryFrames += 1;
+    const now = Date.now();
+    const state = stateFor(String(roverId), now);
+    state.lastBatteryState = batteryState || state.lastBatteryState;
+    const elapsedMs = state.lastAt == null ? 0 : Math.max(0, now - state.lastAt);
+    const gap = elapsedMs > maximumIntegrationGapMs;
+    const validElapsedMs = gap ? 0 : elapsedMs;
+    if (gap) diagnostics.integrationGaps += 1;
+    const currentMa = finite(sensors.currentMa) || 0;
+    const deltaMah = currentMa * validElapsedMs / 3600000;
+    const chargedMah = Math.max(0, deltaMah);
+    const dischargedMah = Math.max(0, -deltaMah);
+    const voltageMv = finite(sensors.voltageMv);
+    /*
+      Millivolts multiplied by milliamps are microwatts. Dividing their
+      millisecond product by 3.6e12 therefore yields watt-hours. Integrating
+      voltage and current together here is required: multiplying independent
+      daily averages later would produce incorrect energy whenever load varies.
+    */
+    const deltaWh = voltageMv == null ? 0 : voltageMv * currentMa * validElapsedMs / 3.6e12;
+    const chargedWh = Math.max(0, deltaWh);
+    const dischargedWh = Math.max(0, -deltaWh);
+
+    const bucketTs = Math.floor(now / MINUTE_MS) * MINUTE_MS;
+    if (state.minute.bucketTs !== bucketTs) {
+      storage.upsertMinute(persistedMinute(state.minute));
+      diagnostics.minuteWrites += 1;
+      state.minute = makeMinute(state.roverId, now);
+    }
+    updateMinute(
+      state.minute,
+      sensors,
+      validElapsedMs,
+      chargedMah,
+      dischargedMah,
+      chargedWh,
+      dischargedWh,
+      gap,
+    );
+    const bumps = sensors?.bumpsAndWheelDrops || {};
+    const nextSafety = {
+      bump: Boolean(bumps.bumpLeft || bumps.bumpRight),
+      cliff: Boolean(sensors.cliffLeft || sensors.cliffFrontLeft || sensors.cliffFrontRight || sensors.cliffRight),
+      wheelDrop: Boolean(bumps.wheelDropLeft || bumps.wheelDropRight),
+      virtualWall: Boolean(sensors.virtualWall),
+      overcurrent: Boolean(
+        sensors?.wheelOvercurrents?.leftWheel || sensors?.wheelOvercurrents?.rightWheel ||
+        sensors?.wheelOvercurrents?.mainBrush || sensors?.wheelOvercurrents?.sideBrush,
+      ),
+    };
+    if (nextSafety.bump && !state.safety.bump) state.minute.bumpCount += 1;
+    if (nextSafety.cliff && !state.safety.cliff) state.minute.cliffCount += 1;
+    if (nextSafety.wheelDrop && !state.safety.wheelDrop) state.minute.wheelDropCount += 1;
+    if (nextSafety.virtualWall && !state.safety.virtualWall) state.minute.virtualWallCount += 1;
+    if (nextSafety.overcurrent) state.safety.overcurrentSamples += 1;
+    if (nextSafety.overcurrent && !state.safety.overcurrent) {
+      state.minute.overcurrentEpisodeCount += 1;
+      state.safety.overcurrentStartedAt = now;
+      state.safety.overcurrentSamples = 1;
+      collectEvent({
+        source: 'fleetReportService',
+        type: 'overcurrent.episode.started',
+        ts: now,
+        payload: { roverId: state.roverId, motors: sensors.wheelOvercurrents },
+      });
+    } else if (!nextSafety.overcurrent && state.safety.overcurrent) {
+      collectEvent({
+        source: 'fleetReportService',
+        type: 'overcurrent.episode.resolved',
+        ts: now,
+        payload: {
+          roverId: state.roverId,
+          startedAt: state.safety.overcurrentStartedAt,
+          durationMs: Math.max(0, now - (state.safety.overcurrentStartedAt || now)),
+          sampleCount: state.safety.overcurrentSamples,
+        },
+      });
+      state.safety.overcurrentStartedAt = null;
+      state.safety.overcurrentSamples = 0;
+    }
+    Object.assign(state.safety, nextSafety);
+    updateFullQualification(state, now, sensors);
+    applySessionKind(state, observedSessionKind(sensors), now, sensors);
+
+    if (state.session) {
+      const session = state.session;
+      session.sampleCount += 1;
+      session.gapCount += gap ? 1 : 0;
+      session.chargedMah += chargedMah;
+      session.dischargedMah += dischargedMah;
+      session.minVoltageMv = minimum(session.minVoltageMv, finite(sensors.voltageMv));
+      session.maxVoltageMv = maximum(session.maxVoltageMv, finite(sensors.voltageMv));
+      session.minTemperatureC = minimum(session.minTemperatureC, finite(sensors.batteryTemperatureC));
+      session.maxTemperatureC = maximum(session.maxTemperatureC, finite(sensors.batteryTemperatureC));
+    }
+    state.lastAt = now;
+  }
+
+  function collectCommand(command = {}) {
+    if (!command.roverId) return;
+    const now = finite(command.ts) || Date.now();
+    const state = stateFor(String(command.roverId), now);
+    const bucketTs = Math.floor(now / MINUTE_MS) * MINUTE_MS;
+    if (state.minute.bucketTs !== bucketTs) {
+      if (state.minute.sampleCount || state.minute.commandCount) {
+        storage.upsertMinute(persistedMinute(state.minute));
+        diagnostics.minuteWrites += 1;
+      }
+      state.minute = makeMinute(state.roverId, now);
+    }
+    state.minute.commandCount += 1;
+    if (command.type === 'drive' || command.type === 'motors') state.minute.driveCommandCount += 1;
+    if (command.outcome === 'rejected') state.minute.rejectedCommandCount += 1;
+
+    // Drive/motor commands can arrive at control-loop frequency. Their exact
+    // volume belongs in minute counters, while rejections and low-frequency
+    // actions remain individually inspectable. This preserves operational
+    // depth without turning normal held movement into an event-timeline flood.
+    if ((command.type !== 'drive' && command.type !== 'motors') || command.outcome === 'rejected') {
+      collectEvent({
+        source: 'commandService',
+        type: `command.${command.outcome || 'observed'}`,
+        ts: now,
+        payload: command,
+      });
+    }
+  }
+
+  function collectManagerEvent(kind, event = {}) {
+    const roverId = event.roverId ? String(event.roverId) : null;
+    if (kind === 'hostStats') {
+      const key = `${kind}:${roverId || 'unknown'}`;
+      const now = Date.now();
+      // Host statistics arrive periodically and change gradually. One exact
+      // sample every five minutes retains long-term diagnostic evidence while
+      // avoiding a timeline row for every routine host heartbeat.
+      if (now - (lastManagerSampleAt.get(key) || 0) < 5 * 60 * 1000) return;
+      lastManagerSampleAt.set(key, now);
+      collectEvent({
+        source: 'roverHost',
+        type: 'host.sample',
+        ts: event.receivedAt || now,
+        payload: { roverId, stats: event.stats || null },
+      });
+      return;
+    }
+    const payload = { ...event };
+    // Live rover records contain websocket handles, sets, and other runtime
+    // objects. The lifecycle facts are sufficient evidence and serialize
+    // predictably without copying those control-owned objects into storage.
+    delete payload.record;
+    collectEvent({
+      source: 'roverManager',
+      type: `roverManager.${kind}`,
+      payload,
+    });
+  }
+
+  function collectOdometer({ roverId, odometer } = {}) {
+    if (!roverId || !odometer) return;
+    const now = finite(odometer.updatedAt) || Date.now();
+    const state = stateFor(String(roverId), now);
+    const totalMm = finite(odometer.totalMm);
+    if (totalMm == null) return;
+    const bucketTs = Math.floor(now / MINUTE_MS) * MINUTE_MS;
+    if (state.minute.bucketTs !== bucketTs) {
+      if (state.minute.sampleCount || state.minute.commandCount || state.minute.distanceMm) {
+        storage.upsertMinute(persistedMinute(state.minute));
+        diagnostics.minuteWrites += 1;
+      }
+      state.minute = makeMinute(state.roverId, now);
+    }
+    if (state.lastOdometerTotalMm != null && totalMm >= state.lastOdometerTotalMm) {
+      // Odometer total is already rollover-corrected and sanity-filtered by its
+      // owning service. Only non-negative increments belong in this report;
+      // resets establish a new baseline instead of subtracting fleet distance.
+      state.minute.distanceMm += totalMm - state.lastOdometerTotalMm;
+    }
+    state.lastOdometerTotalMm = totalMm;
+  }
+
+  function flushMinutes() {
+    roverStates.forEach((state) => {
+      if (!state.minute.sampleCount && !state.minute.commandCount && !state.minute.distanceMm) return;
+      storage.upsertMinute(persistedMinute(state.minute));
+      diagnostics.minuteWrites += 1;
+    });
+  }
+
+  function getLiveState() {
+    return Array.from(roverStates.values()).map((state) => ({
+      roverId: state.roverId,
+      lastAt: state.lastAt,
+      sessionKind: state.sessionKind,
+      waitingSince: state.waitingSince,
+      fullQualifiedAt: state.fullQualifiedAt,
+      minute: persistedMinute(state.minute),
+      openSession: state.session ? {
+        ...state.session,
+        // The database serializer is not involved in this live response, so a
+        // defensive copy prevents UI consumers from mutating collector state.
+        details: { ...state.session.details },
+      } : null,
+    }));
+  }
+
+  function getDiagnostics() {
+    return {
+      ...diagnostics,
+      activeRovers: roverStates.size,
+      openSessions: Array.from(roverStates.values()).filter((state) => state.session).length,
+      instanceId: crypto.createHash('sha1').update(String(diagnostics.startedAt)).digest('hex').slice(0, 10),
+    };
+  }
+
+  function refreshBatteryIdentity(roverId) {
+    const id = String(roverId || '');
+    if (!id) return;
+    const state = roverStates.get(id);
+    if (!state) return;
+    state.batteryKey = storage.getActiveBattery?.(id)?.batteryKey || batteryKey(id);
+  }
+
+  return {
+    collectEvent,
+    collectSensor,
+    collectCommand,
+    collectManagerEvent,
+    collectOdometer,
+    flushMinutes,
+    getLiveState,
+    getDiagnostics,
+    refreshBatteryIdentity,
+  };
+}
+
+module.exports = {
+  createCollector,
+};

server/src/services/fleetReportService/collector.test.js

@@ -0,0 +1,138 @@
+// Fleet Report Collector Tests
+// Purpose: Verifies signed-current integration, gap rejection, and high-rate command noise reduction independently of SQLite.
+// Scope: Uses an in-memory storage double so tests exercise collection policy without touching development data files.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createCollector } = require('./collector');
+
+function makeHarness() {
+  const writes = { events: [], minutes: [], sessions: [] };
+  const storage = {
+    insertEvent(event) { writes.events.push(event); return { changes: 1 }; },
+    upsertMinute(minute) { writes.minutes.push({ ...minute }); return { changes: 1 }; },
+    insertBatterySession(session) { writes.sessions.push({ ...session }); return { changes: 1 }; },
+  };
+  const collector = createCollector({
+    storage,
+    logger: { warn() {} },
+    maximumIntegrationGapMs: 5000,
+    minimumCapacityTestDepthPercent: 60,
+  });
+  return { collector, writes };
+}
+
+function sensors(overrides = {}) {
+  return {
+    currentMa: -3600,
+    voltageMv: 14500,
+    batteryTemperatureC: 25,
+    batteryChargeMah: 2000,
+    batteryCapacityMah: 3000,
+    chargingState: { code: 0, label: 'not charging' },
+    chargingSources: { homeBase: false, internalCharger: false },
+    ...overrides,
+  };
+}
+
+test('integrates signed battery current while excluding long telemetry gaps', () => {
+  const { collector } = makeHarness();
+  const originalNow = Date.now;
+  let now = 1_000_000;
+  Date.now = () => now;
+  try {
+    collector.collectSensor({ roverId: 'alpha', sensors: sensors() });
+    now += 1000;
+    collector.collectSensor({ roverId: 'alpha', sensors: sensors() });
+    now += 6000;
+    collector.collectSensor({ roverId: 'alpha', sensors: sensors() });
+    const live = collector.getLiveState()[0].minute;
+    // -3600 mA for one valid second is exactly one discharged mAh. The six
+    // second interval exceeds the configured integration gap and adds no
+    // fictional throughput.
+    assert.equal(live.dischargedMah, 1);
+    assert.equal(live.chargedMah, 0);
+    assert.equal(live.gapCount, 1);
+    assert.equal(live.coverageMs, 1000);
+  } finally {
+    Date.now = originalNow;
+  }
+});
+
+test('integrates watt-hours and classifies energy with existing odometer speed', () => {
+  const { collector } = makeHarness();
+  const originalNow = Date.now;
+  let now = 1_500_000;
+  Date.now = () => now;
+  try {
+    collector.collectSensor({
+      roverId: 'alpha',
+      sensors: sensors({ wheelSpeedsMmPerSecond: { left: 200, right: 200, center: 200 } }),
+    });
+    now += 1000;
+    collector.collectSensor({
+      roverId: 'alpha',
+      sensors: sensors({ wheelSpeedsMmPerSecond: { left: 200, right: 200, center: 200 } }),
+    });
+    now += 1000;
+    collector.collectSensor({
+      roverId: 'alpha',
+      sensors: sensors({ wheelSpeedsMmPerSecond: { left: 0, right: 0, center: 0 } }),
+    });
+    const live = collector.getLiveState()[0].minute;
+    /*
+      A 14.5 V, 3.6 A discharge is 52.2 W. Two one-second intervals therefore
+      consume 52.2 / 1800 Wh; the first is moving and the second stationary.
+      This verifies that the collector uses odometer speed rather than deriving
+      movement from commands.
+    */
+    assert.ok(Math.abs(live.dischargedWh - (52.2 / 1800)) < 1e-12);
+    assert.ok(Math.abs(live.movingDischargedWh - (52.2 / 3600)) < 1e-12);
+    assert.ok(Math.abs(live.stationaryDischargedWh - (52.2 / 3600)) < 1e-12);
+    assert.equal(live.movingMs, 1000);
+    assert.equal(live.maximumSpeedMmPerSecond, 200);
+  } finally {
+    Date.now = originalNow;
+  }
+});
+
+test('uses cumulative odometer distance without recalculating encoder movement', () => {
+  const { collector } = makeHarness();
+  collector.collectOdometer({ roverId: 'alpha', odometer: { totalMm: 1000, updatedAt: 4_000_000 } });
+  collector.collectOdometer({ roverId: 'alpha', odometer: { totalMm: 1250, updatedAt: 4_001_000 } });
+  const live = collector.getLiveState()[0].minute;
+  assert.equal(live.distanceMm, 250);
+});
+
+test('aggregates drive commands into minute counters instead of event noise', () => {
+  const { collector, writes } = makeHarness();
+  const originalNow = Date.now;
+  Date.now = () => 2_000_000;
+  try {
+    for (let index = 0; index < 100; index += 1) {
+      collector.collectCommand({ roverId: 'alpha', type: 'drive', outcome: 'issued', ts: 2_000_000 + index });
+    }
+    collector.collectCommand({ roverId: 'alpha', type: 'drive', outcome: 'rejected', error: 'safety cooldown' });
+    collector.collectCommand({ roverId: 'alpha', type: 'horn', outcome: 'issued' });
+    const live = collector.getLiveState()[0].minute;
+    assert.equal(live.commandCount, 102);
+    assert.equal(live.driveCommandCount, 101);
+    assert.equal(live.rejectedCommandCount, 1);
+    assert.equal(writes.events.length, 2);
+    assert.deepEqual(writes.events.map((event) => event.type), ['command.rejected', 'command.issued']);
+  } finally {
+    Date.now = originalNow;
+  }
+});
+
+test('preserves chat content in structured global events', () => {
+  const { collector, writes } = makeHarness();
+  collector.collectEvent({
+    source: 'chat',
+    type: 'chat:message',
+    ts: 3_000_000,
+    payload: { text: 'hello fleet history', nickname: 'Otter' },
+  });
+  assert.equal(writes.events.length, 1);
+  assert.equal(writes.events[0].payload.text, 'hello fleet history');
+  assert.equal(writes.events[0].visibility, 'global');
+});

server/src/services/fleetReportService/index.js

@@ -0,0 +1,119 @@
+// Fleet Report Service
+// Purpose: Composes optional passive collection, storage, analysis, retention, and read-only transport.
+// Scope: This is the sole feature boundary; disabled installations register no collectors, timers, database, or sockets.
+const { loadConfig } = require('../../helpers/configLoader');
+const { isFeatureEnabled } = require('../../helpers/features');
+const logger = require('../../globals/logger').child('fleetReportService');
+
+if (!isFeatureEnabled('fleetReports')) {
+  module.exports = {
+    enabled: false,
+    getDailyReport: () => null,
+  };
+} else {
+  const { subscribeAll } = require('../eventBus');
+  const roverManager = require('../roverManager');
+  const { commandEvents } = require('../commandService');
+  const { odometerEvents } = require('../odometerService');
+  const { createStorage } = require('./storage');
+  const { createCollector } = require('./collector');
+  const { createReportBuilder } = require('./reportBuilder');
+  const { registerSocketGateway } = require('./socketGateway');
+
+  const config = loadConfig().fleetReports || {};
+  const batteryConfig = config.battery || {};
+  const retentionConfig = config.retention || {};
+  const maximumIntegrationGapMs = Math.max(
+    250,
+    (Number(batteryConfig.maximumIntegrationGapSeconds) || 5) * 1000,
+  );
+  const minimumCapacityTestDepthPercent = Math.max(
+    10,
+    Math.min(100, Number(batteryConfig.minimumCapacityTestDepthPercent) || 60),
+  );
+  const batteryEnabled = batteryConfig.enabled !== false;
+  const storage = createStorage({ logger });
+  const collector = createCollector({
+    storage,
+    logger,
+    maximumIntegrationGapMs,
+    minimumCapacityTestDepthPercent,
+  });
+  const reportBuilder = createReportBuilder({ storage, collector, roverManager });
+
+  storage.open();
+  const unsubscribeEvents = subscribeAll(collector.collectEvent);
+  if (batteryEnabled) roverManager.managerEvents.on('sensor', collector.collectSensor);
+  commandEvents.on('observation', collector.collectCommand);
+  odometerEvents.on('update', collector.collectOdometer);
+  const managerEventKinds = ['rover', 'hostStats', 'driver', 'switch', 'lock', 'private', 'privateSafety'];
+  const managerEventHandlers = new Map(managerEventKinds.map((kind) => {
+    const handler = (event) => collector.collectManagerEvent(kind, event);
+    roverManager.managerEvents.on(kind, handler);
+    return [kind, handler];
+  }));
+  registerSocketGateway({ roverManager, reportBuilder, storage, collector, logger });
+
+  // Periodic upserts bound data-loss on an unclean shutdown while still
+  // avoiding writes at the 20 Hz sensor-frame rate.
+  const flushTimer = setInterval(() => collector.flushMinutes(), 30 * 1000);
+  flushTimer.unref?.();
+
+  function retentionDays(value, fallback) {
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 ? number : fallback;
+  }
+
+  function pruneNow() {
+    const now = Date.now();
+    const detailedDays = retentionDays(retentionConfig.detailedDays, 0);
+    const minuteDays = retentionDays(retentionConfig.minuteSamplesDays, 0);
+    storage.prune({
+      detailedBefore: detailedDays === 0 ? 0 : now - detailedDays * 86400000,
+      minuteBefore: minuteDays === 0 ? 0 : now - minuteDays * 86400000,
+    });
+  }
+  pruneNow();
+  const retentionTimer = setInterval(pruneNow, 6 * 60 * 60 * 1000);
+  retentionTimer.unref?.();
+
+  function getDailyReport({ since, until, roverIds } = {}) {
+    const end = Number(until) || Date.now();
+    return reportBuilder.build({
+      since: Number(since) || end - 24 * 60 * 60 * 1000,
+      until: end,
+      roverIds: Array.isArray(roverIds) ? roverIds : undefined,
+      // Daily Discord output is intentionally metric-only. Avoiding the event
+      // query here also prevents irrelevant event volume from bloating the
+      // durable daily snapshot that supports delivery idempotency.
+      includeEvents: false,
+    });
+  }
+
+  logger.info('Fleet reporting enabled', {
+    databaseAvailable: storage.getDiagnostics().available,
+    maximumIntegrationGapMs,
+    minimumCapacityTestDepthPercent,
+    batteryEnabled,
+  });
+
+  module.exports = {
+    enabled: true,
+    getDailyReport,
+    collector,
+    storage,
+    reportBuilder,
+    // Exposed for controlled tests and graceful future shutdown wiring. Normal
+    // runtime leaves subscriptions active for the lifetime of the server.
+    stop() {
+      unsubscribeEvents();
+      if (batteryEnabled) roverManager.managerEvents.off('sensor', collector.collectSensor);
+      commandEvents.off('observation', collector.collectCommand);
+      odometerEvents.off('update', collector.collectOdometer);
+      managerEventHandlers.forEach((handler, kind) => roverManager.managerEvents.off(kind, handler));
+      clearInterval(flushTimer);
+      clearInterval(retentionTimer);
+      collector.flushMinutes();
+    },
+  };
+}

server/src/services/fleetReportService/reportBuilder.js

@@ -0,0 +1,298 @@
+// Fleet Report Builder
+// Purpose: Produces fleet-wide battery-health and energy-efficiency read models from passive evidence.
+// Scope: Keeps estimation, confidence, and comparison policy out of collection, transport, Discord, and UI code.
+
+const MINIMUM_EFFICIENCY_DISTANCE_MM = 25 * 1000;
+
+function sum(rows, key) {
+  return rows.reduce((total, row) => total + (Number(row?.[key]) || 0), 0);
+}
+
+function median(values) {
+  const usable = values.map(Number).filter(Number.isFinite).sort((a, b) => a - b);
+  if (!usable.length) return null;
+  const middle = Math.floor(usable.length / 2);
+  return usable.length % 2 ? usable[middle] : (usable[middle - 1] + usable[middle]) / 2;
+}
+
+function weightedAverage(rows, valueKey, weightKey = 'sampleCount') {
+  const weighted = rows.reduce((result, row) => {
+    const value = Number(row[valueKey]);
+    const weight = Number(row[weightKey]);
+    if (!Number.isFinite(value) || !Number.isFinite(weight) || weight <= 0) return result;
+    result.total += value * weight;
+    result.weight += weight;
+    return result;
+  }, { total: 0, weight: 0 });
+  return weighted.weight ? weighted.total / weighted.weight : null;
+}
+
+function minimum(rows, key) {
+  const values = rows.map((row) => Number(row[key])).filter(Number.isFinite);
+  return values.length ? Math.min(...values) : null;
+}
+
+function maximum(rows, key) {
+  const values = rows.map((row) => Number(row[key])).filter(Number.isFinite);
+  return values.length ? Math.max(...values) : null;
+}
+
+function confidenceForObservationCount(count, averageDepthPercent) {
+  /*
+    Confidence is intentionally continuous evidence summarized into a label,
+    not a pass/fail cycle judgment. Multiple partial observations can become
+    strong evidence, while shallow observations remain visible and useful.
+  */
+  if (count >= 5 && averageDepthPercent >= 25) return 'high';
+  if (count >= 2 && averageDepthPercent >= 10) return 'medium';
+  return 'low';
+}
+
+function buildBatteryHealth({ rover, sessions, registryEntry }) {
+  const referenceMah = Number(registryEntry?.ratedCapacityMah) || Number(rover.reportedCapacityMah) || null;
+  const batteryKey = registryEntry?.batteryKey
+    || sessions[0]?.batteryKey
+    || `unregistered:${rover.roverId}`;
+  const sameBattery = sessions.filter((session) => session.batteryKey === batteryKey);
+  const observations = sameBattery.flatMap((session) => {
+    if (session.kind !== 'discharging' || !referenceMah) return [];
+    const chargeDropMah = Number(session.startChargeMah) - Number(session.endChargeMah);
+    const dischargedMah = Number(session.dischargedMah);
+    if (!Number.isFinite(chargeDropMah) || chargeDropMah < 100 || !Number.isFinite(dischargedMah) || dischargedMah <= 0) {
+      return [];
+    }
+    const depthPercent = chargeDropMah / referenceMah * 100;
+    /*
+      Packet 25 provides the changing charge position while signed current
+      supplies an independent coulomb count. Extrapolating each partial slice
+      produces a capacity observation without requiring a full-to-empty run.
+      Depth is retained so callers can see exactly how much evidence supports
+      the estimate.
+    */
+    return [{
+      startedAt: session.startedAt,
+      endedAt: session.endedAt,
+      depthPercent,
+      estimatedUsableMah: dischargedMah / (chargeDropMah / referenceMah),
+      gapCount: Number(session.gapCount) || 0,
+    }];
+  });
+  const cleanObservations = observations.filter((observation) => observation.gapCount <= 1);
+  const measuredUsableMah = median(cleanObservations.map((observation) => observation.estimatedUsableMah));
+  const observedChargeHighMah = maximum(rover.minutes, 'maxChargeMah');
+  const observedChargeLowMah = minimum(rover.minutes, 'minChargeMah');
+  const observedUsableFloorMah = observedChargeHighMah != null && observedChargeLowMah != null
+    ? Math.max(0, observedChargeHighMah - observedChargeLowMah)
+    : null;
+  const averageDepthPercent = cleanObservations.length
+    ? sum(cleanObservations, 'depthPercent') / cleanObservations.length
+    : 0;
+  const baselineMah = Number(registryEntry?.healthyBaselineMah) || referenceMah;
+  const capacityRetentionPercent = measuredUsableMah && baselineMah
+    ? measuredUsableMah / baselineMah * 100
+    : null;
+  const nominalVoltageMv = rover.averageVoltageMv;
+
+  return {
+    batteryKey,
+    referenceMah,
+    baselineMah,
+    measuredUsableMah,
+    measuredUsableWh: measuredUsableMah && nominalVoltageMv
+      ? measuredUsableMah * nominalVoltageMv / 1e6
+      : null,
+    capacityRetentionPercent,
+    observedUsableFloorMah,
+    observedChargeHighMah,
+    observedChargeLowMah,
+    observationCount: cleanObservations.length,
+    averageObservationDepthPercent: averageDepthPercent,
+    confidence: confidenceForObservationCount(cleanObservations.length, averageDepthPercent),
+    confidenceReason: cleanObservations.length
+      ? `${cleanObservations.length} partial current/charge observations averaging ${averageDepthPercent.toFixed(1)}% depth`
+      : 'collecting partial discharge evidence',
+    dischargedThroughputMah: sum(sameBattery, 'dischargedMah'),
+    latestObservationAt: cleanObservations.reduce(
+      (latest, observation) => Math.max(latest, Number(observation.endedAt) || Number(observation.startedAt) || 0),
+      0,
+    ) || null,
+    observations: cleanObservations,
+  };
+}
+
+function groupByRover({ minutes, sessions, roster, batteryRegistry }) {
+  const rosterById = new Map(roster.map((rover) => [String(rover.id), rover]));
+  const minuteGroups = new Map();
+  minutes.forEach((minute) => {
+    const roverId = String(minute.roverId);
+    if (!minuteGroups.has(roverId)) minuteGroups.set(roverId, []);
+    minuteGroups.get(roverId).push(minute);
+  });
+
+  return Array.from(new Set([...rosterById.keys(), ...minuteGroups.keys()])).map((roverId) => {
+    const rows = minuteGroups.get(roverId) || [];
+    const distanceMm = sum(rows, 'distanceMm');
+    const dischargedWh = sum(rows, 'dischargedWh');
+    const movingDischargedWh = sum(rows, 'movingDischargedWh');
+    const movingMs = sum(rows, 'movingMs');
+    const latest = rows[rows.length - 1] || null;
+    const base = {
+      roverId,
+      name: rosterById.get(roverId)?.name || roverId,
+      color: rosterById.get(roverId)?.color || null,
+      online: Boolean(rosterById.get(roverId)),
+      minutes: rows,
+      sampleCount: sum(rows, 'sampleCount'),
+      coverageMs: sum(rows, 'coverageMs'),
+      gapCount: sum(rows, 'gapCount'),
+      distanceMm,
+      movingMs,
+      averageSpeedMmPerSecond: movingMs ? distanceMm / (movingMs / 1000) : null,
+      maximumSpeedMmPerSecond: maximum(rows, 'maximumSpeedMmPerSecond'),
+      chargedMah: sum(rows, 'chargedMah'),
+      dischargedMah: sum(rows, 'dischargedMah'),
+      chargedWh: sum(rows, 'chargedWh'),
+      dischargedWh,
+      movingDischargedWh,
+      stationaryDischargedWh: sum(rows, 'stationaryDischargedWh'),
+      overallWhPerKm: distanceMm >= MINIMUM_EFFICIENCY_DISTANCE_MM
+        ? dischargedWh / (distanceMm / 1e6)
+        : null,
+      movingWhPerKm: distanceMm >= MINIMUM_EFFICIENCY_DISTANCE_MM
+        ? movingDischargedWh / (distanceMm / 1e6)
+        : null,
+      efficiencyDistanceRequiredMm: Math.max(0, MINIMUM_EFFICIENCY_DISTANCE_MM - distanceMm),
+      averageVoltageMv: weightedAverage(rows, 'avgVoltageMv'),
+      averageCurrentMa: weightedAverage(rows, 'avgCurrentMa'),
+      minimumVoltageMv: minimum(rows, 'minVoltageMv'),
+      maximumVoltageMv: maximum(rows, 'maxVoltageMv'),
+      averageTemperatureC: weightedAverage(rows, 'avgTemperatureC'),
+      minimumTemperatureC: minimum(rows, 'minTemperatureC'),
+      maximumTemperatureC: maximum(rows, 'maxTemperatureC'),
+      latestChargeMah: latest?.lastChargeMah ?? null,
+      reportedCapacityMah: latest?.reportedCapacityMah ?? null,
+      lastSampleAt: latest ? latest.bucketTs + 60000 : null,
+    };
+    const registryEntry = batteryRegistry.find((battery) =>
+      String(battery.roverId) === roverId && battery.retiredAt == null,
+    );
+    base.batteryHealth = buildBatteryHealth({
+      rover: base,
+      sessions: sessions.filter((session) => String(session.roverId) === roverId),
+      registryEntry,
+    });
+    delete base.minutes;
+    return base;
+  }).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function buildAttention(roverRows, now) {
+  const attention = [];
+  roverRows.forEach((rover) => {
+    if (!rover.sampleCount) {
+      attention.push({
+        key: `telemetry:${rover.roverId}`,
+        roverId: rover.roverId,
+        severity: 'notice',
+        title: rover.online ? 'Battery metrics unavailable in this range' : 'Rover was not observed in this range',
+      });
+    }
+    if (rover.maximumTemperatureC >= 45) {
+      attention.push({
+        key: `temperature:${rover.roverId}`,
+        roverId: rover.roverId,
+        severity: rover.maximumTemperatureC >= 50 ? 'critical' : 'warning',
+        title: `Battery reached ${rover.maximumTemperatureC} °C`,
+      });
+    }
+    if (rover.batteryHealth.capacityRetentionPercent != null
+      && rover.batteryHealth.confidence !== 'low'
+      && rover.batteryHealth.capacityRetentionPercent < 80) {
+      attention.push({
+        key: `capacity:${rover.roverId}`,
+        roverId: rover.roverId,
+        severity: rover.batteryHealth.capacityRetentionPercent < 65 ? 'critical' : 'warning',
+        title: `Estimated usable capacity is ${rover.batteryHealth.capacityRetentionPercent.toFixed(1)}% of baseline`,
+      });
+    }
+    if (rover.online && rover.lastSampleAt && now - rover.lastSampleAt > 5 * 60 * 1000) {
+      attention.push({
+        key: `stale:${rover.roverId}`,
+        roverId: rover.roverId,
+        severity: 'warning',
+        title: 'Battery metrics are stale',
+      });
+    }
+  });
+  const rank = { critical: 0, warning: 1, notice: 2 };
+  return attention.sort((a, b) => rank[a.severity] - rank[b.severity]);
+}
+
+function createReportBuilder({ storage, collector, roverManager }) {
+  function build({ since, until, roverIds, includeEvents = false, eventLimit = 500 }) {
+    const visibleRoster = Array.from(roverManager.rovers?.values?.() || []).map((record) => ({
+      id: record.id,
+      name: record.name || record.id,
+      color: record.color || record.meta?.color || null,
+    }));
+    const requestedIds = Array.isArray(roverIds) ? roverIds.map(String) : null;
+    const roster = requestedIds
+      ? visibleRoster.filter((rover) => requestedIds.includes(String(rover.id)))
+      : visibleRoster;
+    const effectiveIds = requestedIds || roster.map((rover) => String(rover.id));
+    const minutes = storage.listMinutes({ since, until, roverIds: effectiveIds });
+    const batterySessions = storage.listBatterySessions({ since, until, roverIds: effectiveIds, limit: 2000 });
+    const batteryRegistry = storage.listBatteries(effectiveIds);
+    const roverRows = groupByRover({ minutes, sessions: batterySessions, roster, batteryRegistry });
+    const attention = buildAttention(roverRows, Date.now());
+    const distanceMm = sum(roverRows, 'distanceMm');
+    const dischargedWh = sum(roverRows, 'dischargedWh');
+    const movingDischargedWh = sum(roverRows, 'movingDischargedWh');
+
+    return {
+      generatedAt: Date.now(),
+      range: { since, until },
+      methodology: {
+        minimumEfficiencyDistanceMm: MINIMUM_EFFICIENCY_DISTANCE_MM,
+        historicalWhAvailable: false,
+      },
+      totals: {
+        roverCount: roverRows.length,
+        onlineRoverCount: roverRows.filter((rover) => rover.online).length,
+        distanceMm,
+        movingMs: sum(roverRows, 'movingMs'),
+        chargedWh: sum(roverRows, 'chargedWh'),
+        dischargedWh,
+        movingDischargedWh,
+        stationaryDischargedWh: sum(roverRows, 'stationaryDischargedWh'),
+        overallWhPerKm: distanceMm >= MINIMUM_EFFICIENCY_DISTANCE_MM
+          ? dischargedWh / (distanceMm / 1e6)
+          : null,
+        movingWhPerKm: distanceMm >= MINIMUM_EFFICIENCY_DISTANCE_MM
+          ? movingDischargedWh / (distanceMm / 1e6)
+          : null,
+        attentionCount: attention.filter((item) => item.severity !== 'notice').length,
+      },
+      rovers: roverRows,
+      attention,
+      batteryRegistry,
+      dailyReportHistory: storage.listDailyReports(365),
+      // Events remain available only for explicit advanced/debug consumers.
+      // Neither the normal UI nor Discord requests them.
+      events: includeEvents
+        ? storage.listEvents({ since, until, roverIds: effectiveIds, limit: eventLimit })
+        : [],
+      diagnostics: {
+        collector: collector.getDiagnostics(),
+        storage: storage.getDiagnostics(),
+      },
+    };
+  }
+
+  return { build };
+}
+
+module.exports = {
+  MINIMUM_EFFICIENCY_DISTANCE_MM,
+  createReportBuilder,
+};

server/src/services/fleetReportService/socketGateway.js

@@ -0,0 +1,96 @@
+// Fleet Report Socket Gateway
+// Purpose: Exposes read-only, visibility-filtered fleet history to browser clients.
+// Scope: Owns query validation and existing private/lockdown access boundaries; it performs no collection or analysis.
+const io = require('../../globals/io');
+const crypto = require('crypto');
+const { isAdmin, isLockdownAdmin } = require('../roleService');
+
+const MAX_RANGE_MS = 366 * 24 * 60 * 60 * 1000;
+
+function normalizeRange(payload = {}) {
+  const now = Date.now();
+  const until = Number.isFinite(Number(payload.until)) ? Number(payload.until) : now;
+  const requestedSince = Number.isFinite(Number(payload.since))
+    ? Number(payload.since)
+    : until - 24 * 60 * 60 * 1000;
+  const since = Math.max(0, Math.max(requestedSince, until - MAX_RANGE_MS));
+  return { since, until: Math.max(since + 1, until) };
+}
+
+function registerSocketGateway({ roverManager, reportBuilder, storage, collector, logger }) {
+  io.on('connection', (socket) => {
+    socket.on('fleetReports:get', (payload = {}, cb = () => {}) => {
+      try {
+        const { since, until } = normalizeRange(payload);
+        // getRosterForSocket is the canonical live private-rover visibility
+        // resolver. Historical queries use precisely those currently visible
+        // rover IDs so fleet totals cannot indirectly disclose a private rover.
+        const visibleRoverIds = roverManager.getRosterForSocket(socket).map((rover) => String(rover.id));
+        const requestedIds = Array.isArray(payload.roverIds)
+          ? payload.roverIds.map(String).filter((id) => visibleRoverIds.includes(id))
+          : visibleRoverIds;
+        const report = reportBuilder.build({
+          since,
+          until,
+          roverIds: requestedIds,
+          includeEvents: payload.includeEvents !== false,
+          eventLimit: payload.eventLimit,
+        });
+        // Lockdown-only events are deliberately removed after query assembly.
+        // They are global rather than rover-scoped, so rover filtering alone is
+        // insufficient to preserve the pre-existing lockdown privacy boundary.
+        if (!isLockdownAdmin(socket)) {
+          report.events = report.events.filter((event) => event.visibility !== 'lockdown');
+          report.totals.eventCountReturned = report.events.length;
+        }
+        if (payload.compact === true) {
+          // The Activities card now consumes the same all-rovers metric rows
+          // as fullscreen. The builder no longer attaches minute/session
+          // evidence by default, so compacting only removes archival metadata.
+          report.events = [];
+          report.dailyReportHistory = [];
+        }
+        cb({ ok: true, report });
+      } catch (err) {
+        logger.warn('Fleet report query failed', { socketId: socket.id, error: err.message });
+        cb({ error: 'Fleet report query failed' });
+      }
+    });
+
+    socket.on('fleetReports:replaceBattery', (payload = {}, cb = () => {}) => {
+      try {
+        if (!isAdmin(socket)) throw new Error('Admin access required');
+        const roverId = String(payload.roverId || '').trim();
+        if (!roverId || !roverManager.rovers.has(roverId)) throw new Error('Known online rover required');
+        const ratedCapacityMah = Number(payload.ratedCapacityMah);
+        if (!Number.isFinite(ratedCapacityMah) || ratedCapacityMah <= 0 || ratedCapacityMah > 65535) {
+          throw new Error('Rated capacity must be between 1 and 65535 mAh');
+        }
+        const installedAt = Number.isFinite(Number(payload.installedAt)) ? Number(payload.installedAt) : Date.now();
+        const entry = storage.replaceBattery({
+          roverId,
+          batteryKey: `battery:${roverId}:${installedAt}:${crypto.randomUUID().slice(0, 8)}`,
+          chemistry: String(payload.chemistry || '').trim() || null,
+          ratedCapacityMah: Math.round(ratedCapacityMah),
+          installedAt,
+          notes: String(payload.notes || '').trim() || null,
+        });
+        if (!entry) throw new Error('Battery registry write failed');
+        collector.refreshBatteryIdentity(roverId);
+        collector.collectEvent({
+          source: 'fleetReportService',
+          type: 'battery.replaced',
+          payload: { roverId, battery: entry },
+        });
+        cb({ ok: true, battery: entry });
+      } catch (err) {
+        logger.warn('Fleet battery replacement rejected', { socketId: socket.id, error: err.message });
+        cb({ error: err.message });
+      }
+    });
+  });
+}
+
+module.exports = {
+  registerSocketGateway,
+};

server/src/services/fleetReportService/storage.js

@@ -0,0 +1,533 @@
+// Fleet Report Storage
+// Purpose: Owns the reporting database, schema, bounded writes, and read queries.
+// Scope: Keeps SQLite details out of telemetry collection, analysis, UI transport, and Discord delivery.
+const fs = require('fs');
+const path = require('path');
+const Database = require('better-sqlite3');
+const { resolveDataPath } = require('../../helpers/dataPaths');
+
+const DB_PATH = resolveDataPath('fleet-reports.sqlite');
+
+function safeJson(value) {
+  try {
+    return JSON.stringify(value ?? null);
+  } catch (_err) {
+    // An unusual circular payload must not break the event subscriber. The
+    // placeholder still records that an event occurred and explains why its
+    // supporting payload is unavailable.
+    return JSON.stringify({ serializationError: true });
+  }
+}
+
+function parseJson(value, fallback = null) {
+  try {
+    return value == null ? fallback : JSON.parse(value);
+  } catch (_err) {
+    return fallback;
+  }
+}
+
+function createStorage({ logger }) {
+  let db = null;
+  let statements = null;
+
+  function open() {
+    if (db) return true;
+    try {
+      fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
+      db = new Database(DB_PATH);
+      db.pragma('journal_mode = WAL');
+      db.pragma('synchronous = NORMAL');
+      db.pragma('foreign_keys = ON');
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS fleet_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts INTEGER NOT NULL,
+          source TEXT NOT NULL,
+          type TEXT NOT NULL,
+          rover_id TEXT,
+          visibility TEXT NOT NULL DEFAULT 'global',
+          severity TEXT NOT NULL DEFAULT 'informational',
+          correlation_id TEXT,
+          payload_json TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_fleet_events_ts ON fleet_events(ts DESC);
+        CREATE INDEX IF NOT EXISTS idx_fleet_events_rover_ts ON fleet_events(rover_id, ts DESC);
+        CREATE INDEX IF NOT EXISTS idx_fleet_events_type_ts ON fleet_events(type, ts DESC);
+
+        CREATE TABLE IF NOT EXISTS fleet_minute_samples (
+          rover_id TEXT NOT NULL,
+          bucket_ts INTEGER NOT NULL,
+          sample_count INTEGER NOT NULL,
+          coverage_ms INTEGER NOT NULL,
+          gap_count INTEGER NOT NULL,
+          charged_mah REAL NOT NULL,
+          discharged_mah REAL NOT NULL,
+          charged_wh REAL NOT NULL DEFAULT 0,
+          discharged_wh REAL NOT NULL DEFAULT 0,
+          moving_discharged_wh REAL NOT NULL DEFAULT 0,
+          stationary_discharged_wh REAL NOT NULL DEFAULT 0,
+          moving_ms INTEGER NOT NULL DEFAULT 0,
+          maximum_speed_mm_per_second REAL,
+          min_voltage_mv INTEGER,
+          max_voltage_mv INTEGER,
+          avg_voltage_mv REAL,
+          min_current_ma INTEGER,
+          max_current_ma INTEGER,
+          avg_current_ma REAL,
+          min_temperature_c INTEGER,
+          max_temperature_c INTEGER,
+          avg_temperature_c REAL,
+          min_charge_mah INTEGER,
+          max_charge_mah INTEGER,
+          last_charge_mah INTEGER,
+          reported_capacity_mah INTEGER,
+          docked_samples INTEGER NOT NULL,
+          charging_samples INTEGER NOT NULL,
+          command_count INTEGER NOT NULL DEFAULT 0,
+          drive_command_count INTEGER NOT NULL DEFAULT 0,
+          rejected_command_count INTEGER NOT NULL DEFAULT 0,
+          distance_mm REAL NOT NULL DEFAULT 0,
+          bump_count INTEGER NOT NULL DEFAULT 0,
+          cliff_count INTEGER NOT NULL DEFAULT 0,
+          wheel_drop_count INTEGER NOT NULL DEFAULT 0,
+          virtual_wall_count INTEGER NOT NULL DEFAULT 0,
+          overcurrent_episode_count INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (rover_id, bucket_ts)
+        );
+        CREATE INDEX IF NOT EXISTS idx_fleet_minutes_ts ON fleet_minute_samples(bucket_ts DESC);
+
+        CREATE TABLE IF NOT EXISTS fleet_battery_sessions (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          rover_id TEXT NOT NULL,
+          battery_key TEXT NOT NULL,
+          kind TEXT NOT NULL,
+          started_at INTEGER NOT NULL,
+          ended_at INTEGER,
+          start_charge_mah INTEGER,
+          end_charge_mah INTEGER,
+          charged_mah REAL NOT NULL DEFAULT 0,
+          discharged_mah REAL NOT NULL DEFAULT 0,
+          min_voltage_mv INTEGER,
+          max_voltage_mv INTEGER,
+          min_temperature_c INTEGER,
+          max_temperature_c INTEGER,
+          sample_count INTEGER NOT NULL DEFAULT 0,
+          gap_count INTEGER NOT NULL DEFAULT 0,
+          status TEXT NOT NULL DEFAULT 'open',
+          confidence TEXT NOT NULL DEFAULT 'low',
+          qualification_reason TEXT,
+          details_json TEXT NOT NULL DEFAULT '{}'
+        );
+        CREATE INDEX IF NOT EXISTS idx_battery_sessions_rover_time ON fleet_battery_sessions(rover_id, started_at DESC);
+
+        CREATE TABLE IF NOT EXISTS fleet_batteries (
+          battery_key TEXT PRIMARY KEY,
+          rover_id TEXT NOT NULL,
+          chemistry TEXT,
+          rated_capacity_mah INTEGER,
+          installed_at INTEGER,
+          retired_at INTEGER,
+          healthy_baseline_mah REAL,
+          notes TEXT,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_fleet_batteries_rover ON fleet_batteries(rover_id, installed_at DESC);
+
+        CREATE TABLE IF NOT EXISTS fleet_daily_reports (
+          report_date TEXT PRIMARY KEY,
+          generated_at INTEGER NOT NULL,
+          report_json TEXT NOT NULL,
+          discord_delivered_at INTEGER,
+          discord_error TEXT
+        );
+      `);
+
+      // SQLite's CREATE TABLE IF NOT EXISTS does not add columns to an older
+      // reporting database. These narrow additive migrations keep development
+      // databases usable as collection coverage expands without coupling this
+      // optional feature to the identity database's migration history.
+      const minuteColumns = new Set(db.prepare('PRAGMA table_info(fleet_minute_samples)').all().map((column) => column.name));
+      [
+        ['command_count', 'INTEGER NOT NULL DEFAULT 0'],
+        ['drive_command_count', 'INTEGER NOT NULL DEFAULT 0'],
+        ['rejected_command_count', 'INTEGER NOT NULL DEFAULT 0'],
+        ['distance_mm', 'REAL NOT NULL DEFAULT 0'],
+        ['bump_count', 'INTEGER NOT NULL DEFAULT 0'],
+        ['cliff_count', 'INTEGER NOT NULL DEFAULT 0'],
+        ['wheel_drop_count', 'INTEGER NOT NULL DEFAULT 0'],
+        ['virtual_wall_count', 'INTEGER NOT NULL DEFAULT 0'],
+        ['overcurrent_episode_count', 'INTEGER NOT NULL DEFAULT 0'],
+        ['charged_wh', 'REAL NOT NULL DEFAULT 0'],
+        ['discharged_wh', 'REAL NOT NULL DEFAULT 0'],
+        ['moving_discharged_wh', 'REAL NOT NULL DEFAULT 0'],
+        ['stationary_discharged_wh', 'REAL NOT NULL DEFAULT 0'],
+        ['moving_ms', 'INTEGER NOT NULL DEFAULT 0'],
+        ['maximum_speed_mm_per_second', 'REAL'],
+      ].forEach(([name, definition]) => {
+        if (!minuteColumns.has(name)) db.exec(`ALTER TABLE fleet_minute_samples ADD COLUMN ${name} ${definition}`);
+      });
+
+      statements = {
+        insertEvent: db.prepare(`
+          INSERT INTO fleet_events (ts, source, type, rover_id, visibility, severity, correlation_id, payload_json)
+          VALUES (@ts, @source, @type, @roverId, @visibility, @severity, @correlationId, @payloadJson)
+        `),
+        upsertMinute: db.prepare(`
+          INSERT INTO fleet_minute_samples (
+            rover_id, bucket_ts, sample_count, coverage_ms, gap_count,
+            charged_mah, discharged_mah, min_voltage_mv, max_voltage_mv, avg_voltage_mv,
+            charged_wh, discharged_wh, moving_discharged_wh,
+            stationary_discharged_wh, moving_ms, maximum_speed_mm_per_second,
+            min_current_ma, max_current_ma, avg_current_ma, min_temperature_c,
+            max_temperature_c, avg_temperature_c, min_charge_mah, max_charge_mah,
+            last_charge_mah, reported_capacity_mah, docked_samples, charging_samples,
+            command_count, drive_command_count, rejected_command_count,
+            distance_mm, bump_count, cliff_count, wheel_drop_count,
+            virtual_wall_count, overcurrent_episode_count
+          ) VALUES (
+            @roverId, @bucketTs, @sampleCount, @coverageMs, @gapCount,
+            @chargedMah, @dischargedMah, @minVoltageMv, @maxVoltageMv, @avgVoltageMv,
+            @chargedWh, @dischargedWh, @movingDischargedWh,
+            @stationaryDischargedWh, @movingMs, @maximumSpeedMmPerSecond,
+            @minCurrentMa, @maxCurrentMa, @avgCurrentMa, @minTemperatureC,
+            @maxTemperatureC, @avgTemperatureC, @minChargeMah, @maxChargeMah,
+            @lastChargeMah, @reportedCapacityMah, @dockedSamples, @chargingSamples,
+            @commandCount, @driveCommandCount, @rejectedCommandCount,
+            @distanceMm, @bumpCount, @cliffCount, @wheelDropCount,
+            @virtualWallCount, @overcurrentEpisodeCount
+          )
+          ON CONFLICT(rover_id, bucket_ts) DO UPDATE SET
+            sample_count = excluded.sample_count,
+            coverage_ms = excluded.coverage_ms,
+            gap_count = excluded.gap_count,
+            charged_mah = excluded.charged_mah,
+            discharged_mah = excluded.discharged_mah,
+            charged_wh = excluded.charged_wh,
+            discharged_wh = excluded.discharged_wh,
+            moving_discharged_wh = excluded.moving_discharged_wh,
+            stationary_discharged_wh = excluded.stationary_discharged_wh,
+            moving_ms = excluded.moving_ms,
+            maximum_speed_mm_per_second = excluded.maximum_speed_mm_per_second,
+            min_voltage_mv = excluded.min_voltage_mv,
+            max_voltage_mv = excluded.max_voltage_mv,
+            avg_voltage_mv = excluded.avg_voltage_mv,
+            min_current_ma = excluded.min_current_ma,
+            max_current_ma = excluded.max_current_ma,
+            avg_current_ma = excluded.avg_current_ma,
+            min_temperature_c = excluded.min_temperature_c,
+            max_temperature_c = excluded.max_temperature_c,
+            avg_temperature_c = excluded.avg_temperature_c,
+            min_charge_mah = excluded.min_charge_mah,
+            max_charge_mah = excluded.max_charge_mah,
+            last_charge_mah = excluded.last_charge_mah,
+            reported_capacity_mah = excluded.reported_capacity_mah,
+            docked_samples = excluded.docked_samples,
+            charging_samples = excluded.charging_samples,
+            command_count = excluded.command_count,
+            drive_command_count = excluded.drive_command_count,
+            rejected_command_count = excluded.rejected_command_count
+            ,distance_mm = excluded.distance_mm
+            ,bump_count = excluded.bump_count
+            ,cliff_count = excluded.cliff_count
+            ,wheel_drop_count = excluded.wheel_drop_count
+            ,virtual_wall_count = excluded.virtual_wall_count
+            ,overcurrent_episode_count = excluded.overcurrent_episode_count
+        `),
+        insertSession: db.prepare(`
+          INSERT INTO fleet_battery_sessions (
+            rover_id, battery_key, kind, started_at, ended_at, start_charge_mah,
+            end_charge_mah, charged_mah, discharged_mah, min_voltage_mv,
+            max_voltage_mv, min_temperature_c, max_temperature_c, sample_count,
+            gap_count, status, confidence, qualification_reason, details_json
+          ) VALUES (
+            @roverId, @batteryKey, @kind, @startedAt, @endedAt, @startChargeMah,
+            @endChargeMah, @chargedMah, @dischargedMah, @minVoltageMv,
+            @maxVoltageMv, @minTemperatureC, @maxTemperatureC, @sampleCount,
+            @gapCount, @status, @confidence, @qualificationReason, @detailsJson
+          )
+        `),
+      };
+      return true;
+    } catch (err) {
+      logger.error('Failed to open fleet report database; reporting will remain fail-open', {
+        path: DB_PATH,
+        error: err.message,
+      });
+      if (db) {
+        try { db.close(); } catch (_closeErr) { /* Best-effort cleanup after failed initialization. */ }
+      }
+      db = null;
+      statements = null;
+      return false;
+    }
+  }
+
+  function runSafely(label, operation, fallback = null) {
+    if (!open()) return fallback;
+    try {
+      return operation();
+    } catch (err) {
+      // Reporting is observer-only. A failed write/query is visible in logs but
+      // is never allowed to propagate into a rover sensor or command callback.
+      logger.warn(`Fleet report storage ${label} failed`, { error: err.message });
+      return fallback;
+    }
+  }
+
+  function insertEvent(event) {
+    return runSafely('event write', () => statements.insertEvent.run({
+      ts: event.ts,
+      source: event.source,
+      type: event.type,
+      roverId: event.roverId || null,
+      visibility: event.visibility || 'global',
+      severity: event.severity || 'informational',
+      correlationId: event.correlationId || null,
+      payloadJson: safeJson(event.payload),
+    }));
+  }
+
+  function upsertMinute(sample) {
+    return runSafely('minute write', () => statements.upsertMinute.run(sample));
+  }
+
+  function insertBatterySession(session) {
+    return runSafely('battery session write', () => statements.insertSession.run({
+      ...session,
+      detailsJson: safeJson(session.details || {}),
+    }));
+  }
+
+  function listEvents({ since, until, roverIds, limit = 500, offset = 0, type = null }) {
+    return runSafely('event query', () => {
+      const clauses = ['ts >= ?', 'ts < ?'];
+      const params = [since, until];
+      if (type) {
+        clauses.push('type = ?');
+        params.push(type);
+      }
+      if (Array.isArray(roverIds)) {
+        if (roverIds.length === 0) clauses.push('rover_id IS NULL');
+        else {
+          clauses.push(`(rover_id IS NULL OR rover_id IN (${roverIds.map(() => '?').join(',')}))`);
+          params.push(...roverIds);
+        }
+      }
+      params.push(Math.max(1, Math.min(2000, Number(limit) || 500)), Math.max(0, Number(offset) || 0));
+      const rows = db.prepare(`
+        SELECT id, ts, source, type, rover_id AS roverId, visibility, severity,
+               correlation_id AS correlationId, payload_json AS payloadJson
+        FROM fleet_events
+        WHERE ${clauses.join(' AND ')}
+        ORDER BY ts DESC
+        LIMIT ? OFFSET ?
+      `).all(...params);
+      return rows.map(({ payloadJson, ...row }) => ({ ...row, payload: parseJson(payloadJson, {}) }));
+    }, []);
+  }
+
+  function listMinutes({ since, until, roverIds }) {
+    return runSafely('minute query', () => {
+      const clauses = ['bucket_ts >= ?', 'bucket_ts < ?'];
+      const params = [since, until];
+      if (Array.isArray(roverIds)) {
+        if (roverIds.length === 0) return [];
+        clauses.push(`rover_id IN (${roverIds.map(() => '?').join(',')})`);
+        params.push(...roverIds);
+      }
+      return db.prepare(`
+        SELECT rover_id AS roverId, bucket_ts AS bucketTs, sample_count AS sampleCount,
+               coverage_ms AS coverageMs, gap_count AS gapCount, charged_mah AS chargedMah,
+               discharged_mah AS dischargedMah, min_voltage_mv AS minVoltageMv,
+               charged_wh AS chargedWh, discharged_wh AS dischargedWh,
+               moving_discharged_wh AS movingDischargedWh,
+               stationary_discharged_wh AS stationaryDischargedWh,
+               moving_ms AS movingMs,
+               maximum_speed_mm_per_second AS maximumSpeedMmPerSecond,
+               max_voltage_mv AS maxVoltageMv, avg_voltage_mv AS avgVoltageMv,
+               min_current_ma AS minCurrentMa, max_current_ma AS maxCurrentMa,
+               avg_current_ma AS avgCurrentMa, min_temperature_c AS minTemperatureC,
+               max_temperature_c AS maxTemperatureC, avg_temperature_c AS avgTemperatureC,
+               min_charge_mah AS minChargeMah, max_charge_mah AS maxChargeMah,
+               last_charge_mah AS lastChargeMah, reported_capacity_mah AS reportedCapacityMah,
+               docked_samples AS dockedSamples, charging_samples AS chargingSamples,
+               command_count AS commandCount, drive_command_count AS driveCommandCount,
+               rejected_command_count AS rejectedCommandCount
+               ,distance_mm AS distanceMm, bump_count AS bumpCount,
+               cliff_count AS cliffCount, wheel_drop_count AS wheelDropCount,
+               virtual_wall_count AS virtualWallCount,
+               overcurrent_episode_count AS overcurrentEpisodeCount
+        FROM fleet_minute_samples
+        WHERE ${clauses.join(' AND ')}
+        ORDER BY bucket_ts ASC, rover_id ASC
+      `).all(...params);
+    }, []);
+  }
+
+  function listBatterySessions({ since, until, roverIds, limit = 500 }) {
+    return runSafely('battery session query', () => {
+      if (Array.isArray(roverIds) && roverIds.length === 0) return [];
+      const roverClause = Array.isArray(roverIds)
+        ? `AND rover_id IN (${roverIds.map(() => '?').join(',')})`
+        : '';
+      const params = [since, until, ...(roverIds || []), Math.max(1, Math.min(2000, Number(limit) || 500))];
+      return db.prepare(`
+        SELECT id, rover_id AS roverId, battery_key AS batteryKey, kind,
+               started_at AS startedAt, ended_at AS endedAt,
+               start_charge_mah AS startChargeMah, end_charge_mah AS endChargeMah,
+               charged_mah AS chargedMah, discharged_mah AS dischargedMah,
+               min_voltage_mv AS minVoltageMv, max_voltage_mv AS maxVoltageMv,
+               min_temperature_c AS minTemperatureC, max_temperature_c AS maxTemperatureC,
+               sample_count AS sampleCount, gap_count AS gapCount, status,
+               confidence, qualification_reason AS qualificationReason,
+               details_json AS detailsJson
+        FROM fleet_battery_sessions
+        WHERE started_at < ? AND COALESCE(ended_at, started_at) >= ? ${roverClause}
+        ORDER BY started_at DESC
+        LIMIT ?
+      `).all(until, since, ...(roverIds || []), params[params.length - 1]).map(({ detailsJson, ...row }) => ({
+        ...row,
+        details: parseJson(detailsJson, {}),
+      }));
+    }, []);
+  }
+
+  function prune({ detailedBefore, minuteBefore }) {
+    return runSafely('retention prune', () => db.transaction(() => {
+      const events = db.prepare('DELETE FROM fleet_events WHERE ts < ?').run(detailedBefore).changes;
+      const minutes = db.prepare('DELETE FROM fleet_minute_samples WHERE bucket_ts < ?').run(minuteBefore).changes;
+      return { events, minutes };
+    })());
+  }
+
+  function getDailyReport(reportDate) {
+    return runSafely('daily report query', () => {
+      const row = db.prepare(`
+        SELECT report_date AS reportDate, generated_at AS generatedAt,
+               report_json AS reportJson, discord_delivered_at AS discordDeliveredAt,
+               discord_error AS discordError
+        FROM fleet_daily_reports WHERE report_date = ?
+      `).get(reportDate);
+      if (!row) return null;
+      const { reportJson, ...metadata } = row;
+      return { ...metadata, report: parseJson(reportJson, null) };
+    });
+  }
+
+  function listBatteries(roverIds = null) {
+    return runSafely('battery registry query', () => {
+      if (Array.isArray(roverIds) && roverIds.length === 0) return [];
+      const clause = Array.isArray(roverIds)
+        ? `WHERE rover_id IN (${roverIds.map(() => '?').join(',')})`
+        : '';
+      return db.prepare(`
+        SELECT battery_key AS batteryKey, rover_id AS roverId, chemistry,
+               rated_capacity_mah AS ratedCapacityMah, installed_at AS installedAt,
+               retired_at AS retiredAt, healthy_baseline_mah AS healthyBaselineMah,
+               notes, updated_at AS updatedAt
+        FROM fleet_batteries ${clause}
+        ORDER BY rover_id ASC, installed_at DESC
+      `).all(...(roverIds || []));
+    }, []);
+  }
+
+  function getActiveBattery(roverId) {
+    return runSafely('active battery query', () => db.prepare(`
+      SELECT battery_key AS batteryKey, rover_id AS roverId, chemistry,
+             rated_capacity_mah AS ratedCapacityMah, installed_at AS installedAt,
+             healthy_baseline_mah AS healthyBaselineMah, notes, updated_at AS updatedAt
+      FROM fleet_batteries
+      WHERE rover_id = ? AND retired_at IS NULL
+      ORDER BY installed_at DESC
+      LIMIT 1
+    `).get(String(roverId)) || null);
+  }
+
+  function replaceBattery(entry) {
+    return runSafely('battery replacement write', () => db.transaction(() => {
+      const now = Date.now();
+      db.prepare('UPDATE fleet_batteries SET retired_at = ?, updated_at = ? WHERE rover_id = ? AND retired_at IS NULL')
+        .run(entry.installedAt || now, now, entry.roverId);
+      db.prepare(`
+        INSERT INTO fleet_batteries (
+          battery_key, rover_id, chemistry, rated_capacity_mah, installed_at,
+          retired_at, healthy_baseline_mah, notes, updated_at
+        ) VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?)
+      `).run(
+        entry.batteryKey,
+        entry.roverId,
+        entry.chemistry || null,
+        entry.ratedCapacityMah || null,
+        entry.installedAt || now,
+        entry.healthyBaselineMah || null,
+        entry.notes || null,
+        now,
+      );
+      return getActiveBattery(entry.roverId);
+    })());
+  }
+
+  function saveDailyReport(reportDate, report) {
+    return runSafely('daily report write', () => db.prepare(`
+      INSERT INTO fleet_daily_reports (report_date, generated_at, report_json)
+      VALUES (?, ?, ?)
+      ON CONFLICT(report_date) DO UPDATE SET
+        generated_at = excluded.generated_at,
+        report_json = excluded.report_json
+    `).run(reportDate, Date.now(), safeJson(report)));
+  }
+
+  function listDailyReports(limit = 90) {
+    return runSafely('daily report history query', () => db.prepare(`
+      SELECT report_date AS reportDate, generated_at AS generatedAt,
+             discord_delivered_at AS discordDeliveredAt, discord_error AS discordError,
+             length(report_json) AS reportBytes
+      FROM fleet_daily_reports
+      ORDER BY report_date DESC
+      LIMIT ?
+    `).all(Math.max(1, Math.min(1000, Number(limit) || 90))), []);
+  }
+
+  function markDailyReportDelivery(reportDate, { deliveredAt = null, error = null } = {}) {
+    return runSafely('daily delivery update', () => db.prepare(`
+      UPDATE fleet_daily_reports
+      SET discord_delivered_at = ?, discord_error = ?
+      WHERE report_date = ?
+    `).run(deliveredAt, error, reportDate));
+  }
+
+  function getDiagnostics() {
+    return runSafely('diagnostics query', () => ({
+      available: true,
+      path: DB_PATH,
+      bytes: fs.statSync(DB_PATH).size,
+      eventCount: db.prepare('SELECT COUNT(*) AS count FROM fleet_events').get().count,
+      minuteCount: db.prepare('SELECT COUNT(*) AS count FROM fleet_minute_samples').get().count,
+      sessionCount: db.prepare('SELECT COUNT(*) AS count FROM fleet_battery_sessions').get().count,
+    }), { available: false, path: DB_PATH });
+  }
+
+  return {
+    open,
+    insertEvent,
+    upsertMinute,
+    insertBatterySession,
+    listEvents,
+    listMinutes,
+    listBatterySessions,
+    prune,
+    getDailyReport,
+    saveDailyReport,
+    listDailyReports,
+    markDailyReportDelivery,
+    listBatteries,
+    getActiveBattery,
+    replaceBattery,
+    getDiagnostics,
+  };
+}
+
+module.exports = {
+  createStorage,
+};

server/src/services/funStatsService/index.js

@@ -0,0 +1,178 @@
+// Fun Stats Service
+// Purpose: Persists the running counters behind the social `rs` fun commands.
+// Scope: Owns storage and clamping only; command handlers decide what a counter means.
+const fs = require('fs');
+const path = require('path');
+const logger = require('../../globals/logger').child('funStatsService');
+const { resolveDataPath } = require('../../helpers/dataPaths');
+
+const STORE_PATH = resolveDataPath('fun-stats.json');
+
+// Counters are additive and never authoritative for anything but bragging
+// rights, so the ceiling only exists to keep a runaway loop from writing an
+// unbounded integer into the store.
+const MAX_COUNT = 1_000_000;
+const MAX_LABEL_LENGTH = 64;
+const ACTOR_COUNTERS = [
+  'bonksGiven',
+  'bonksTaken',
+  'hugsGiven',
+  'hugsTaken',
+  'slapsGiven',
+  'slapsTaken',
+];
+
+/*
+  This service deliberately keeps its own tiny JSON store rather than reusing
+  identityService.createJsonStore. Fun counters are keyed by an actor key that
+  spans transports (`user:<id>` for site chat, `discord:<id>` for Discord), and
+  a Discord id has no row in `users`, so it cannot live in `user_feature_state`
+  without violating that table's foreign key. Keeping storage local also means
+  the counters can be unit tested without opening the identity database.
+*/
+let cache = null;
+
+function clampCount(value) {
+  const count = Number(value);
+  if (!Number.isFinite(count) || count <= 0) return 0;
+  return Math.min(Math.floor(count), MAX_COUNT);
+}
+
+function normalizeLabel(value) {
+  const label = String(value || '').trim().replace(/\s+/g, ' ');
+  if (!label) return null;
+  return label.slice(0, MAX_LABEL_LENGTH);
+}
+
+function normalizeActor(raw = {}) {
+  const actor = { label: normalizeLabel(raw.label) };
+  ACTOR_COUNTERS.forEach((key) => {
+    actor[key] = clampCount(raw[key]);
+  });
+  actor.updatedAt = Number.isFinite(raw.updatedAt) ? raw.updatedAt : null;
+  return actor;
+}
+
+function normalizeStore(raw = {}) {
+  const actors = {};
+  const rawActors = raw && typeof raw.actors === 'object' && raw.actors ? raw.actors : {};
+  Object.keys(rawActors).forEach((key) => {
+    const actorKey = String(key || '').trim();
+    if (!actorKey) return;
+    actors[actorKey] = normalizeActor(rawActors[actorKey]);
+  });
+
+  const rovers = {};
+  const rawRovers = raw && typeof raw.rovers === 'object' && raw.rovers ? raw.rovers : {};
+  Object.keys(rawRovers).forEach((key) => {
+    const roverId = String(key || '').trim();
+    if (!roverId) return;
+    const entry = rawRovers[roverId] || {};
+    rovers[roverId] = {
+      pets: clampCount(entry.pets),
+      updatedAt: Number.isFinite(entry.updatedAt) ? entry.updatedAt : null,
+    };
+  });
+
+  return { actors, rovers };
+}
+
+function loadState() {
+  if (cache) return cache;
+  try {
+    cache = normalizeStore(JSON.parse(fs.readFileSync(STORE_PATH, 'utf8')));
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      logger.warn('Failed to load fun stats store', { path: STORE_PATH, error: err.message });
+    }
+    cache = normalizeStore({});
+  }
+  return cache;
+}
+
+function persistState(next) {
+  const normalized = normalizeStore(next);
+  try {
+    fs.mkdirSync(path.dirname(STORE_PATH), { recursive: true });
+    const tempPath = `${STORE_PATH}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tempPath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+    fs.renameSync(tempPath, STORE_PATH);
+  } catch (err) {
+    // A failed write must not break the command that triggered it. The joke
+    // still lands; only the tally is lost.
+    logger.warn('Failed to persist fun stats store', { path: STORE_PATH, error: err.message });
+  }
+  cache = normalized;
+  return cache;
+}
+
+function getActorStats(actorKey) {
+  const key = String(actorKey || '').trim();
+  if (!key) return normalizeActor({});
+  return { ...(loadState().actors[key] || normalizeActor({})) };
+}
+
+/*
+  `patch` is a map of counter name to increment. Unknown counter names are
+  ignored rather than stored so a typo in a handler cannot quietly create a
+  parallel counter that never shows up on the leaderboard.
+*/
+function bumpActorStats(actorKey, { label = null, ...patch } = {}) {
+  const key = String(actorKey || '').trim();
+  if (!key) return normalizeActor({});
+  const state = loadState();
+  const current = state.actors[key] || normalizeActor({});
+  const next = { ...current };
+  const resolvedLabel = normalizeLabel(label);
+  if (resolvedLabel) next.label = resolvedLabel;
+  ACTOR_COUNTERS.forEach((counter) => {
+    const delta = Number(patch[counter]);
+    if (!Number.isFinite(delta) || delta === 0) return;
+    next[counter] = clampCount(current[counter] + delta);
+  });
+  next.updatedAt = Date.now();
+  persistState({ ...state, actors: { ...state.actors, [key]: next } });
+  return { ...next };
+}
+
+function listActorStats() {
+  const { actors } = loadState();
+  return Object.keys(actors).map((actorKey) => ({ actorKey, ...actors[actorKey] }));
+}
+
+function bumpRoverPets(roverId, by = 1) {
+  const id = String(roverId || '').trim();
+  if (!id) return 0;
+  const state = loadState();
+  const current = state.rovers[id] || { pets: 0, updatedAt: null };
+  const delta = Number(by);
+  const next = {
+    pets: clampCount(current.pets + (Number.isFinite(delta) ? delta : 0)),
+    updatedAt: Date.now(),
+  };
+  persistState({ ...state, rovers: { ...state.rovers, [id]: next } });
+  return next.pets;
+}
+
+function getRoverPets(roverId) {
+  const id = String(roverId || '').trim();
+  if (!id) return 0;
+  return loadState().rovers[id]?.pets || 0;
+}
+
+// Tests drive the store through a temporary SERVER_DATA_DIR, so they need a way
+// to drop the module-level cache between cases.
+function resetCacheForTests() {
+  cache = null;
+}
+
+module.exports = {
+  ACTOR_COUNTERS,
+  STORE_PATH,
+  getActorStats,
+  bumpActorStats,
+  listActorStats,
+  bumpRoverPets,
+  getRoverPets,
+  resetCacheForTests,
+};

server/src/services/funStatsService/index.test.js

@@ -0,0 +1,131 @@
+// Fun Stats Service Tests
+// Purpose: Verifies counter persistence, clamping, and that a corrupt store degrades instead of throwing.
+// Scope: Runs against a temporary SERVER_DATA_DIR so the real data directory is never touched.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fun-stats-test-'));
+process.env.SERVER_DATA_DIR = dataDir;
+
+const funStatsService = require('./index');
+
+function reset() {
+  try {
+    fs.rmSync(funStatsService.STORE_PATH, { force: true });
+  } catch {
+    // A missing store is the normal starting state.
+  }
+  funStatsService.resetCacheForTests();
+}
+
+test('counters start at zero for an unknown actor', () => {
+  reset();
+  const stats = funStatsService.getActorStats('user:nobody');
+  assert.equal(stats.bonksGiven, 0);
+  assert.equal(stats.bonksTaken, 0);
+  assert.equal(stats.label, null);
+});
+
+test('bumping a counter accumulates and records the label', () => {
+  reset();
+  funStatsService.bumpActorStats('user:alice', { label: 'alice', bonksGiven: 1 });
+  const stats = funStatsService.bumpActorStats('user:alice', { label: 'alice', bonksGiven: 1 });
+  assert.equal(stats.bonksGiven, 2);
+  assert.equal(stats.label, 'alice');
+});
+
+test('counters are independent of one another', () => {
+  reset();
+  funStatsService.bumpActorStats('user:alice', { bonksGiven: 3, hugsGiven: 1 });
+  const stats = funStatsService.getActorStats('user:alice');
+  assert.equal(stats.bonksGiven, 3);
+  assert.equal(stats.hugsGiven, 1);
+  assert.equal(stats.slapsGiven, 0);
+});
+
+test('an unrecognized counter name is ignored rather than silently stored', () => {
+  reset();
+  funStatsService.bumpActorStats('user:alice', { notACounter: 5 });
+  const stats = funStatsService.getActorStats('user:alice');
+  assert.equal(stats.notACounter, undefined);
+});
+
+test('state survives a cold read from disk', () => {
+  reset();
+  funStatsService.bumpActorStats('user:alice', { label: 'alice', bonksGiven: 7 });
+  funStatsService.resetCacheForTests();
+  assert.equal(funStatsService.getActorStats('user:alice').bonksGiven, 7);
+});
+
+test('an empty actor key is refused so anonymous bumps cannot share a bucket', () => {
+  reset();
+  funStatsService.bumpActorStats('', { bonksGiven: 1 });
+  assert.deepEqual(funStatsService.listActorStats(), []);
+});
+
+test('rover pets accumulate per rover', () => {
+  reset();
+  assert.equal(funStatsService.bumpRoverPets('rover-1', 1), 1);
+  assert.equal(funStatsService.bumpRoverPets('rover-1', 1), 2);
+  assert.equal(funStatsService.bumpRoverPets('rover-2', 1), 1);
+  assert.equal(funStatsService.getRoverPets('rover-1'), 2);
+  assert.equal(funStatsService.getRoverPets('unknown'), 0);
+});
+
+test('listActorStats returns every actor with their key', () => {
+  reset();
+  funStatsService.bumpActorStats('user:alice', { label: 'alice', bonksGiven: 1 });
+  funStatsService.bumpActorStats('discord:4242', { label: 'dave', bonksGiven: 2 });
+  const keys = funStatsService.listActorStats().map((row) => row.actorKey).sort();
+  assert.deepEqual(keys, ['discord:4242', 'user:alice']);
+});
+
+test('negative and non-numeric deltas cannot drive a counter below zero', () => {
+  reset();
+  funStatsService.bumpActorStats('user:alice', { bonksGiven: 1 });
+  funStatsService.bumpActorStats('user:alice', { bonksGiven: -50 });
+  assert.equal(funStatsService.getActorStats('user:alice').bonksGiven, 0);
+
+  funStatsService.bumpActorStats('user:alice', { bonksGiven: Number.NaN });
+  assert.equal(funStatsService.getActorStats('user:alice').bonksGiven, 0);
+});
+
+test('labels are trimmed and length capped', () => {
+  reset();
+  const stats = funStatsService.bumpActorStats('user:alice', { label: `  ${'x'.repeat(200)}  `, bonksGiven: 1 });
+  assert.equal(stats.label.length, 64);
+});
+
+test('a corrupt store file degrades to empty instead of throwing', () => {
+  reset();
+  fs.mkdirSync(path.dirname(funStatsService.STORE_PATH), { recursive: true });
+  fs.writeFileSync(funStatsService.STORE_PATH, '{not json at all', 'utf8');
+  funStatsService.resetCacheForTests();
+
+  assert.deepEqual(funStatsService.listActorStats(), []);
+  // And it must still be writable afterwards.
+  assert.equal(funStatsService.bumpActorStats('user:alice', { bonksGiven: 1 }).bonksGiven, 1);
+});
+
+test('a store with the wrong shape is normalized rather than trusted', () => {
+  reset();
+  fs.mkdirSync(path.dirname(funStatsService.STORE_PATH), { recursive: true });
+  fs.writeFileSync(
+    funStatsService.STORE_PATH,
+    JSON.stringify({ actors: { 'user:alice': { bonksGiven: 'lots', label: 42 } }, rovers: 'nope' }),
+    'utf8',
+  );
+  funStatsService.resetCacheForTests();
+
+  const stats = funStatsService.getActorStats('user:alice');
+  assert.equal(stats.bonksGiven, 0);
+  assert.equal(stats.label, '42');
+  assert.equal(funStatsService.getRoverPets('rover-1'), 0);
+});
+
+test.after(() => {
+  fs.rmSync(dataDir, { recursive: true, force: true });
+});

server/src/services/homeAssistantService/index.js

@@ -78,6 +78,7 @@ module.exports = {
   setLightColor: runtimeEngine.setLightColor,
   setLightWhite: runtimeEngine.setLightWhite,
   setAllControllableEntitiesState: runtimeEngine.setAllControllableEntitiesState,
+  setRandomColorScene: runtimeEngine.setRandomColorScene,
   setLightsLockedOn: runtimeEngine.setLightsLockedOn,
   toggleLightsLockedOn: runtimeEngine.toggleLightsLockedOn,
   homeAssistantEvents: events,

server/src/services/homeAssistantService/runtimeEngine.js

@@ -196,6 +196,72 @@ function createRuntimeEngine(deps) {
     };
   }
 
+  function createBrightRandomRgbColor() {
+    // A completely random RGB triplet frequently produces colors that are very
+    // dark, gray, or visually indistinguishable from a bulb being off. Choosing
+    // a random hue at full saturation and brightness still gives every bulb a
+    // genuinely random color while keeping the requested room effect vivid.
+    const hueSegment = Math.random() * 6;
+    const segmentIndex = Math.floor(hueSegment);
+    const risingChannel = Math.round((hueSegment - segmentIndex) * 255);
+    const fallingChannel = 255 - risingChannel;
+
+    switch (segmentIndex) {
+      case 0: return [255, risingChannel, 0];
+      case 1: return [fallingChannel, 255, 0];
+      case 2: return [0, 255, risingChannel];
+      case 3: return [0, fallingChannel, 255];
+      case 4: return [risingChannel, 0, 255];
+      default: return [255, 0, fallingChannel];
+    }
+  }
+
+  async function setRandomColorScene(options = {}) {
+    const source = String(options?.source || 'homeAssistant:setRandomColorScene');
+    const entities = Array.from(entityConfig.values()).map((meta) => ({
+      meta,
+      state: entityState.get(meta.id) || buildState(meta, null),
+    }));
+
+    // RGB capability comes from Home Assistant's live supported_color_modes
+    // snapshot. This avoids a second operator-maintained list and makes newly
+    // replaced bulbs automatically participate once Home Assistant reports
+    // their capabilities. Everything else is turned off, including switches
+    // and white-only lights, exactly matching the scene's requested boundary.
+    const operations = entities.map(({ meta, state }) => {
+      if (state.supportsColor) {
+        return setLightColor(meta.id, createBrightRandomRgbColor());
+      }
+      return setEntityState(meta.id, 'off', { source: `${source}:non-rgb-off` });
+    });
+    const results = await Promise.allSettled(operations);
+    const failures = results
+      .map((result, index) => ({ result, entityId: entities[index].meta.id }))
+      .filter(({ result }) => result.status === 'rejected')
+      .map(({ result, entityId }) => ({ entityId, error: result.reason?.message || 'unknown error' }));
+    const succeeded = results
+      .map((result, index) => ({ result, entityId: entities[index].meta.id }))
+      .filter(({ result }) => result.status === 'fulfilled')
+      .map(({ entityId }) => entityId);
+
+    if (failures.length) {
+      logger.warn('Some Home Assistant random color scene updates failed', {
+        total: entities.length,
+        failed: failures.length,
+        failures,
+      });
+    }
+
+    return {
+      source,
+      total: entities.length,
+      colorLights: entities.filter(({ state }) => state.supportsColor).length,
+      nonColorEntities: entities.filter(({ state }) => !state.supportsColor).length,
+      succeeded,
+      failures,
+    };
+  }
+
   async function setEntityLockedOnWhite(entityId, options = {}) {
     const meta = entityConfig.get(entityId);
     const source = String(options?.source || 'homeAssistant:setEntityLockedOnWhite');
@@ -498,6 +564,7 @@ function createRuntimeEngine(deps) {
     setLightColor,
     setLightWhite,
     setAllControllableEntitiesState,
+    setRandomColorScene,
     setAllControllableEntitiesLockedOnWhite,
     setLightsLockedOn,
     toggleLightsLockedOn,

server/src/services/httpServer/index.js

@@ -4,7 +4,14 @@
 const { httpServer } = require('../../globals/http');
 const config = require('../../globals/config');
 const logger = require('../../globals/logger').child('httpServer');
+const { startMediaMtx } = require('../mediaMtxService');
 
 httpServer.listen(config.port, () => {
   logger.info(`Server listening on :${config.port}`);
+  /*
+    MediaMTX immediately calls the server's HTTP authorization route when clients connect.
+    Starting it from the listen callback guarantees that endpoint is reachable before the
+    first publisher attempts to authenticate.
+  */
+  startMediaMtx();
 });

server/src/services/identityAdminService/index.js

@@ -11,6 +11,7 @@ const {
   removeUserSignal,
   setVerified,
   setDeterrence,
+  setMuted,
   setFeatureState,
   deleteFeatureState,
 } = require('../identityService');
@@ -103,6 +104,14 @@ io.on('connection', (socket) => {
     }).id),
   }));
 
+  ackHandler(socket, 'identityAdmin:setMuted', ({ userId, enabled }) => ({
+    user: getUserForAdmin(setMuted(userId, {
+      enabled: Boolean(enabled),
+      actor: socket?.data?.user?.username || socket.id,
+      at: Date.now(),
+    }).id),
+  }));
+
   ackHandler(socket, 'identityAdmin:updateFeatureState', ({ userId, namespace, value }) => {
     const normalized = normalizeFeaturePayload(namespace, value);
     setFeatureState(userId, normalized.namespace, normalized.value);

server/src/services/identityService/index.js

@@ -17,7 +17,7 @@ const USER_ID_RE = /^usr_[a-f0-9]{32}$/;
 const DB_PATH = resolveDataPath('identity.sqlite');
 const LEGACY_VERIFICATION_PATH = resolveDataPath('verified-users.json');
 const LEGACY_BARCODE_PATH = resolveDataPath('barcode-games.json');
-const STORE_VERSION = 1;
+const STORE_VERSION = 3;
 const identityEvents = new EventEmitter();
 
 let db = null;
@@ -166,7 +166,13 @@ function ensureSchema(conn) {
       deterrence_enabled integer not null default 0,
       deterrence_reason text,
       deterrence_at integer,
-      deterrence_by text
+      deterrence_by text,
+      muted_enabled integer not null default 0,
+      muted_at integer,
+      muted_by text,
+      audio_gain_boost_enabled integer not null default 0,
+      audio_gain_boost_at integer,
+      audio_gain_boost_by text
     );
 
     create table if not exists verification_requests (
@@ -213,6 +219,34 @@ function ensureSchema(conn) {
 
     pragma user_version = ${STORE_VERSION};
   `);
+
+  /*
+    SQLite's `create table if not exists` leaves an existing table untouched.
+    Add the mute columns explicitly for installations created before store
+    version 2, and the audio gain boost columns for those created before store
+    version 3. The column-name check keeps every later startup idempotent.
+  */
+  const statusColumns = new Set(
+    conn.prepare('pragma table_info(user_status)').all().map((column) => column.name),
+  );
+  if (!statusColumns.has('muted_enabled')) {
+    conn.exec('alter table user_status add column muted_enabled integer not null default 0');
+  }
+  if (!statusColumns.has('muted_at')) {
+    conn.exec('alter table user_status add column muted_at integer');
+  }
+  if (!statusColumns.has('muted_by')) {
+    conn.exec('alter table user_status add column muted_by text');
+  }
+  if (!statusColumns.has('audio_gain_boost_enabled')) {
+    conn.exec('alter table user_status add column audio_gain_boost_enabled integer not null default 0');
+  }
+  if (!statusColumns.has('audio_gain_boost_at')) {
+    conn.exec('alter table user_status add column audio_gain_boost_at integer');
+  }
+  if (!statusColumns.has('audio_gain_boost_by')) {
+    conn.exec('alter table user_status add column audio_gain_boost_by text');
+  }
 }
 
 function createUser(conn = getDb(), ts = nowMs()) {
@@ -279,6 +313,20 @@ function mergeUsers(conn, targetUserId, sourceUserId) {
       where user_id = ?
     `).run(sourceStatus.deterrence_reason || null, sourceStatus.deterrence_at || ts, sourceStatus.deterrence_by || null, targetUserId);
   }
+  if (sourceStatus?.muted_enabled) {
+    /*
+      Identity merging must preserve the stricter moderation state. Otherwise
+      joining two signals could silently clear a mute merely because the
+      unmuted record happened to become the merge target.
+    */
+    conn.prepare(`
+      update user_status
+      set muted_enabled = 1,
+          muted_at = coalesce(muted_at, ?),
+          muted_by = coalesce(muted_by, ?)
+      where user_id = ?
+    `).run(sourceStatus.muted_at || ts, sourceStatus.muted_by || null, targetUserId);
+  }
 
   const sourceFeatures = conn.prepare('select namespace, data_json, created_at, updated_at from user_feature_state where user_id = ?').all(sourceUserId);
   sourceFeatures.forEach((feature) => {
@@ -382,6 +430,8 @@ function setSocketIdentityState(socket, user, identity = {}) {
   socket.data.verifiedRecordId = user.verified?.enabled ? user.id : null;
   socket.data.isDeterred = Boolean(user.deterrence?.enabled);
   socket.data.deterredRecordId = user.deterrence?.enabled ? user.id : null;
+  socket.data.isMuted = Boolean(user.deterrence?.muted);
+  socket.data.hasAudioGainBoost = Boolean(user.audioGainBoost?.enabled);
 }
 
 function identifySocket(socket, payload = {}) {
@@ -422,6 +472,7 @@ function identifySocket(socket, payload = {}) {
     fingerprintId: fingerprintId || null,
     isVerified: Boolean(user.verified?.enabled),
     isDeterred: Boolean(user.deterrence?.enabled),
+    isMuted: Boolean(user.deterrence?.muted),
   };
 }
 
@@ -468,6 +519,14 @@ function getUserById(userId, { conn = getDb(), includeFeatures = true } = {}) {
       reason: status.deterrence_reason || null,
       at: status.deterrence_at || null,
       by: status.deterrence_by || null,
+      muted: Boolean(status.muted_enabled),
+      mutedAt: status.muted_at || null,
+      mutedBy: status.muted_by || null,
+    },
+    audioGainBoost: {
+      enabled: Boolean(status.audio_gain_boost_enabled),
+      at: status.audio_gain_boost_at || null,
+      by: status.audio_gain_boost_by || null,
     },
     features,
   };
@@ -673,20 +732,61 @@ function setDeterrence(userId, { enabled = true, reason = null, actor = null, at
   return getUserById(id);
 }
 
+function setMuted(userId, { enabled = true, actor = null, at = nowMs() } = {}) {
+  const id = String(userId || '').trim();
+  if (!id) throw new Error('userId required');
+  ensureUserStatus(getDb(), id);
+  getDb().prepare(`
+    update user_status
+    set muted_enabled = ?, muted_at = ?, muted_by = ?
+    where user_id = ?
+  `).run(enabled ? 1 : 0, enabled ? at : null, enabled ? actor : null, id);
+  identityEvents.emit('change', { reason: enabled ? 'muted' : 'unmuted', userId: id });
+  return getUserById(id);
+}
+
+/*
+  The audio gain boost flag lets a trusted VIP raise their personal horn/TTS/mic
+  gain ceiling past the global admin gain settings. It stays a status column
+  rather than feature state so it can be filtered in SQL alongside the other
+  moderation flags and copied onto the socket at identify time.
+*/
+function setAudioGainBoost(userId, { enabled = true, actor = null, at = nowMs() } = {}) {
+  const id = String(userId || '').trim();
+  if (!id) throw new Error('userId required');
+  ensureUserStatus(getDb(), id);
+  getDb().prepare(`
+    update user_status
+    set audio_gain_boost_enabled = ?, audio_gain_boost_at = ?, audio_gain_boost_by = ?
+    where user_id = ?
+  `).run(enabled ? 1 : 0, enabled ? at : null, enabled ? actor : null, id);
+  identityEvents.emit('change', {
+    reason: enabled ? 'audio_gain_boost_granted' : 'audio_gain_boost_revoked',
+    userId: id,
+  });
+  return getUserById(id);
+}
+
 function isVerified(socket) {
   return Boolean(socket?.data?.isVerified);
 }
 
+function hasAudioGainBoost(socket) {
+  return Boolean(socket?.data?.hasAudioGainBoost);
+}
+
 function isDeterred(socket) {
   return Boolean(socket?.data?.isDeterred);
 }
 
-function listUsers({ verified = null, deterred = null } = {}) {
+function listUsers({ verified = null, deterred = null, muted = null, audioGainBoost = null } = {}) {
   const conn = getDb();
   let sql = 'select users.id from users join user_status on user_status.user_id = users.id';
   const where = [];
   if (verified !== null) where.push(`user_status.verified_enabled = ${verified ? 1 : 0}`);
   if (deterred !== null) where.push(`user_status.deterrence_enabled = ${deterred ? 1 : 0}`);
+  if (muted !== null) where.push(`user_status.muted_enabled = ${muted ? 1 : 0}`);
+  if (audioGainBoost !== null) where.push(`user_status.audio_gain_boost_enabled = ${audioGainBoost ? 1 : 0}`);
   if (where.length) sql += ` where ${where.join(' and ')}`;
   sql += ' order by users.updated_at desc';
   return conn.prepare(sql).all().map((row) => getUserById(row.id, { conn, includeFeatures: false }));
@@ -705,6 +805,12 @@ function userToLegacyIdentityEntry(user) {
     updatedAt: user.updatedAt,
     approvedBy: user.verified?.by || null,
     reason: user.deterrence?.reason || null,
+    muted: Boolean(user.deterrence?.muted),
+    mutedAt: user.deterrence?.mutedAt || null,
+    mutedBy: user.deterrence?.mutedBy || null,
+    audioGainBoost: Boolean(user.audioGainBoost?.enabled),
+    audioGainBoostAt: user.audioGainBoost?.at || null,
+    audioGainBoostBy: user.audioGainBoost?.by || null,
   };
 }
 
@@ -716,6 +822,14 @@ function listDeterredUsers() {
   return listUsers({ deterred: true }).map(userToLegacyIdentityEntry);
 }
 
+function listMutedUsers() {
+  return listUsers({ muted: true }).map(userToLegacyIdentityEntry);
+}
+
+function listAudioGainBoostUsers() {
+  return listUsers({ audioGainBoost: true }).map(userToLegacyIdentityEntry);
+}
+
 function resolveUserBySelector(selector, { includeDeterred = true, includeVerified = true } = {}) {
   const value = String(selector || '').trim();
   if (!value) return { error: 'selector_required' };
@@ -969,10 +1083,15 @@ module.exports = {
   listFeatureStates,
   setVerified,
   setDeterrence,
+  setMuted,
+  setAudioGainBoost,
   isVerified,
   isDeterred,
+  hasAudioGainBoost,
   listVerifiedUsers,
   listDeterredUsers,
+  listMutedUsers,
+  listAudioGainBoostUsers,
   resolveUserBySelector,
   userToLegacyIdentityEntry,
   createJsonStore,

server/src/services/mediaMtxService/config.js

@@ -0,0 +1,100 @@
+// MediaMTX Config Builder
+// Purpose: Converts the rover server's media settings into the complete MediaMTX runtime configuration.
+// Scope: Keeps deployment-specific hosts in config.yaml while keeping protocol policy owned by the application.
+const path = require('path');
+
+function normalizeAdditionalHosts(rawHosts) {
+  if (rawHosts == null) return [];
+  if (!Array.isArray(rawHosts)) {
+    throw new Error('media.additionalHosts must be a list');
+  }
+
+  /*
+    MediaMTX accepts both IP addresses and DNS names here. Preserve that flexibility because
+    an installation can need a public candidate and a LAN candidate at the same time. Empty
+    entries and duplicates are removed so a harmless config typo does not create redundant
+    ICE candidates, while the values themselves remain entirely instance-owned.
+  */
+  return [...new Set(rawHosts.map((value) => String(value || '').trim()).filter(Boolean))];
+}
+
+function buildMediaMtxConfig({ config, serverPort, snapshotWriterPath }) {
+  const media = config?.media || {};
+  let additionalHosts = normalizeAdditionalHosts(media.additionalHosts);
+  if (!additionalHosts.length && media.whepBaseUrl) {
+    try {
+      /*
+        Existing installations predate media.additionalHosts. Using the already-configured
+        WHEP hostname as a one-host migration default keeps them reachable on first restart;
+        administrators can still list every public and LAN candidate explicitly afterward.
+      */
+      additionalHosts = [new URL(media.whepBaseUrl).hostname].filter(Boolean);
+    } catch {
+      throw new Error('media.whepBaseUrl must be a valid URL when media.additionalHosts is empty');
+    }
+  }
+  const authPort = Number(serverPort) || 8080;
+
+  return {
+    logLevel: 'info',
+    api: true,
+    apiAddress: '127.0.0.1:9997',
+    metrics: true,
+    metricsAddress: '127.0.0.1:9998',
+    pprof: false,
+    pprofAddress: '127.0.0.1:9999',
+
+    /*
+      Rover publishers and readers always request TCP explicitly. Declaring only TCP here
+      also prevents MediaMTX from opening the separate RTP/RTCP UDP listeners, which are not
+      useful for this local-network deployment and performed poorly in the measured tests.
+    */
+    rtsp: true,
+    rtspAddress: ':8554',
+    rtspTransports: ['tcp'],
+    rtmp: false,
+    hls: false,
+
+    webrtc: true,
+    webrtcLocalUDPAddress: ':8189',
+    webrtcLocalTCPAddress: ':8189',
+    webrtcAdditionalHosts: additionalHosts,
+    webrtcICEServers2: [
+      { url: 'stun:stun.l.google.com:19302' },
+      { url: 'stun:stun1.l.google.com:19302' },
+      { url: 'stun:stun2.l.google.com:19302' },
+      { url: 'stun:stun3.l.google.com:19302' },
+      { url: 'stun:stun4.l.google.com:19302' },
+      { url: 'stun:stun.cloudflare.com:3478' },
+    ],
+
+    /*
+      Several server-local paths still use SRT: PTZ publishing, replay capture, and the snapshot
+      writer. Rover media moves to RTSP, but removing this listener would break those independent
+      consumers, so both listeners remain deliberately enabled.
+    */
+    srt: true,
+    srtAddress: ':9000',
+
+    authMethod: 'http',
+    authHTTPAddress: `http://127.0.0.1:${authPort}/mediamtx/auth`,
+    authHTTPExclude: [
+      { action: 'api' },
+      { action: 'metrics' },
+      { action: 'pprof' },
+    ],
+    paths: {
+      all: {
+        source: 'publisher',
+        sourceOnDemand: false,
+        runOnReady: path.resolve(snapshotWriterPath),
+        runOnReadyRestart: true,
+      },
+    },
+  };
+}
+
+module.exports = {
+  buildMediaMtxConfig,
+  normalizeAdditionalHosts,
+};

server/src/services/mediaMtxService/config.test.js

@@ -0,0 +1,45 @@
+// MediaMTX Config Builder Tests
+// Purpose: Pins the generated protocol policy and instance-specific ICE host handling.
+// Scope: Tests pure configuration output without starting listeners or leaving a child process running.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { buildMediaMtxConfig, normalizeAdditionalHosts } = require('./config');
+
+test('generates RTSP over TCP without deployment-specific hardcodes', () => {
+  const generated = buildMediaMtxConfig({
+    config: {
+      media: {
+        whepBaseUrl: 'http://media.internal:8889/video',
+        additionalHosts: ['public.example.com', '10.20.30.40'],
+      },
+    },
+    serverPort: 8123,
+    snapshotWriterPath: '/opt/multirover/rover-snapshot-writer.sh',
+  });
+
+  assert.equal(generated.rtsp, true);
+  assert.equal(generated.rtspAddress, ':8554');
+  assert.deepEqual(generated.rtspTransports, ['tcp']);
+  assert.equal(Object.hasOwn(generated, 'rtpAddress'), false);
+  assert.equal(Object.hasOwn(generated, 'rtcpAddress'), false);
+  assert.deepEqual(generated.webrtcAdditionalHosts, ['public.example.com', '10.20.30.40']);
+  assert.equal(generated.authHTTPAddress, 'http://127.0.0.1:8123/mediamtx/auth');
+});
+
+test('uses the configured WHEP hostname while an older config has no additionalHosts', () => {
+  const generated = buildMediaMtxConfig({
+    config: { media: { whepBaseUrl: 'https://second-server.example/video' } },
+    serverPort: 8080,
+    snapshotWriterPath: '/usr/local/bin/rover-snapshot-writer.sh',
+  });
+
+  assert.deepEqual(generated.webrtcAdditionalHosts, ['second-server.example']);
+});
+
+test('normalizes duplicate and empty additional hosts', () => {
+  assert.deepEqual(
+    normalizeAdditionalHosts([' media.local ', '', 'media.local', null, 'public.example']),
+    ['media.local', 'public.example'],
+  );
+  assert.throws(() => normalizeAdditionalHosts('media.local'), /must be a list/);
+});

server/src/services/mediaMtxService/index.js

@@ -0,0 +1,46 @@
+// MediaMTX Service
+// Purpose: Composes server configuration, runtime paths, and child-process supervision.
+// Scope: Starts MediaMTX only after the HTTP auth endpoint is listening and stops it with the server.
+const { loadConfig } = require('../../helpers/configLoader');
+const globalConfig = require('../../globals/config');
+const logger = require('../../globals/logger').child('mediamtx');
+const { createMediaMtxSupervisor } = require('./supervisor');
+
+const supervisor = createMediaMtxSupervisor({
+  config: loadConfig(),
+  serverPort: globalConfig.port,
+  logger,
+});
+
+function startMediaMtx() {
+  return supervisor.start();
+}
+
+/*
+  Other services already use process signal hooks for their own workers. This hook performs
+  only synchronous signal delivery; systemd's default control-group cleanup remains the final
+  guarantee if the parent is killed before the child finishes exiting.
+*/
+process.once('exit', () => supervisor.stop());
+
+function stopForSignal(signal) {
+  let completed = false;
+  const finish = () => {
+    if (completed) return;
+    completed = true;
+    process.exit(signal === 'SIGINT' ? 130 : 143);
+  };
+
+  supervisor.stop(finish);
+  /*
+    A wedged child must not make systemd wait indefinitely. This timer is deliberately unref'd
+    so it never keeps an otherwise-finished process alive; it is only a bound on graceful exit.
+  */
+  const forceExitTimer = setTimeout(finish, 5000);
+  forceExitTimer.unref?.();
+}
+
+process.once('SIGINT', () => stopForSignal('SIGINT'));
+process.once('SIGTERM', () => stopForSignal('SIGTERM'));
+
+module.exports = { startMediaMtx };

server/src/services/mediaMtxService/supervisor.js

@@ -0,0 +1,103 @@
+// MediaMTX Child Supervisor
+// Purpose: Writes the generated runtime configuration and owns the MediaMTX child process lifecycle.
+// Scope: Starts exactly one child, forwards its logs, and lets systemd restart the coherent server/media pair.
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const yaml = require('js-yaml');
+const { buildMediaMtxConfig } = require('./config');
+
+function createMediaMtxSupervisor(deps) {
+  const {
+    config,
+    serverPort,
+    logger,
+    mediaMtxBin = process.env.MEDIAMTX_BIN || '/usr/local/bin/mediamtx',
+    runtimeDir = process.env.MULTIROVER_RUNTIME_DIR || '/run/multirover',
+    snapshotWriterPath = process.env.ROVER_SNAPSHOT_WRITER_BIN || '/usr/local/bin/rover-snapshot-writer.sh',
+    spawnProcess = spawn,
+  } = deps;
+
+  let child = null;
+  let stopping = false;
+  let stoppedCallback = null;
+
+  function forwardLines(stream, level) {
+    let pending = '';
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+      pending += chunk;
+      const lines = pending.split(/\r?\n/);
+      pending = lines.pop() || '';
+      lines.filter(Boolean).forEach((line) => logger[level](line));
+    });
+    stream.on('end', () => {
+      if (pending) logger[level](pending);
+    });
+  }
+
+  function start() {
+    if (child) return child;
+
+    const runtimeConfig = buildMediaMtxConfig({ config, serverPort, snapshotWriterPath });
+    const configPath = path.join(runtimeDir, 'mediamtx.yml');
+    fs.mkdirSync(runtimeDir, { recursive: true, mode: 0o750 });
+    fs.writeFileSync(configPath, yaml.dump(runtimeConfig, { noRefs: true, lineWidth: 120 }), { mode: 0o640 });
+
+    logger.info(`Starting MediaMTX with generated config ${configPath}`);
+    child = spawnProcess(mediaMtxBin, [configPath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    forwardLines(child.stdout, 'info');
+    forwardLines(child.stderr, 'warn');
+
+    child.once('error', (err) => {
+      logger.error('Unable to start MediaMTX', err);
+      if (!stopping) {
+        /*
+          A spawn failure does not reliably emit the normal exit event on every platform.
+          Fail the parent here as well so the server can never stay nominally online without
+          its required media child and systemd gets the opportunity to repair the launch.
+        */
+        process.exit(1);
+      }
+    });
+    child.once('exit', (code, signal) => {
+      child = null;
+      if (stopping) {
+        stoppedCallback?.();
+        stoppedCallback = null;
+        return;
+      }
+
+      /*
+        MediaMTX is required for every live media path. Exiting the parent is intentionally
+        simpler and safer than maintaining a second retry policy inside Node: systemd already
+        restarts multirover.service, producing one clean server/MediaMTX lifecycle.
+      */
+      logger.error(`MediaMTX exited unexpectedly (code=${code ?? 'none'} signal=${signal || 'none'})`);
+      process.exit(1);
+    });
+    return child;
+  }
+
+  function stop(onStopped) {
+    stopping = true;
+    stoppedCallback = typeof onStopped === 'function' ? onStopped : null;
+    if (!child) {
+      stoppedCallback?.();
+      stoppedCallback = null;
+      return;
+    }
+    try {
+      child.kill('SIGTERM');
+    } catch (err) {
+      logger.warn('Unable to stop MediaMTX cleanly', err);
+    }
+  }
+
+  return { start, stop };
+}
+
+module.exports = { createMediaMtxSupervisor };

server/src/services/operatorCommandService/commands/deter.js

@@ -1,10 +1,45 @@
 // Operator Deter Command
 // Purpose: Handles deterrence moderation commands for lockdown admins.
 // Scope: Supports list, ban, and unban subcommands.
-const { mask, resolveIdentitySelector } = require('./resolvers');
+const { mask, normalizeSearchText, resolveIdentitySelector } = require('./resolvers');
 const { getCommandConfig } = require('../../operatorCommandService/config');
 
-function createDeterCommand({ listDeterredUsers, listVerifiedUsers, deterUser, undeterUser, sanitizeMentions, config }) {
+function findOnlineNicknameMatches(io, getNickname, selector) {
+  const normalizedSelector = normalizeSearchText(selector);
+  if (!normalizedSelector) return [];
+
+  const matchesByUserId = new Map();
+  const sockets = io?.sockets?.sockets;
+  if (!sockets || typeof sockets.forEach !== 'function') return [];
+
+  sockets.forEach((socket) => {
+    const nickname = getNickname(socket);
+    const userId = String(socket?.data?.userId || '').trim();
+    if (!userId || normalizeSearchText(nickname) !== normalizedSelector) return;
+
+    /*
+      One person may have multiple connected tabs or surfaces. Collapse those
+      sockets to the canonical user id so duplicate tabs do not manufacture an
+      ambiguous moderation target when they all represent the same identity.
+    */
+    if (!matchesByUserId.has(userId)) {
+      matchesByUserId.set(userId, { userId, nickname });
+    }
+  });
+
+  return Array.from(matchesByUserId.values());
+}
+
+function uniqueIdentityRecords(records = []) {
+  const byIdentity = new Map();
+  records.forEach((record) => {
+    const key = record?.userId || record?.id || record?.cookieUserId || record?.fingerprintId;
+    if (key && !byIdentity.has(key)) byIdentity.set(key, record);
+  });
+  return Array.from(byIdentity.values());
+}
+
+function createDeterCommand({ io, getNickname, listDeterredUsers, listMutedUsers, listVerifiedUsers, deterUser, undeterUser, muteUser, unmuteUser, sanitizeMentions, config }) {
   // Moderation usage errors use the same core prefix shown by organized help.
   const { prefix: commandPrefix } = getCommandConfig(config);
 
@@ -15,23 +50,58 @@ function createDeterCommand({ listDeterredUsers, listVerifiedUsers, deterUser, u
     }
     const action = (tokens.shift() || 'list').toLowerCase();
     if (action === 'list') {
-      const users = listDeterredUsers();
+      const deterredUsers = listDeterredUsers().map((entry) => ({ ...entry, deterred: true }));
-      if (!users.length) return message.reply({ content: 'No deterred users.', allowedMentions: { parse: [], repliedUser: false } });
+      const mutedUsers = listMutedUsers().map((entry) => ({ ...entry, muted: true }));
-      const lines = users.map((entry, idx) => `${idx + 1}. ${entry.userId || entry.id} | ${entry.nickname || 'unknown'} | ${mask(entry.cookieUserId)}`);
+      const usersById = new Map();
-      return message.reply({ content: ['Deterred users:', ...lines].join('\n').slice(0, 1900), allowedMentions: { parse: [], repliedUser: false } });
+      [...deterredUsers, ...mutedUsers].forEach((entry) => {
+        const userId = entry.userId || entry.id;
+        if (!userId) return;
+        const existing = usersById.get(userId) || {};
+        usersById.set(userId, {
+          ...existing,
+          ...entry,
+          deterred: Boolean(existing.deterred || entry.deterred),
+          muted: Boolean(existing.muted || entry.muted),
+        });
+      });
+      const users = Array.from(usersById.values());
+      if (!users.length) return message.reply({ content: 'No deterred or muted users.', allowedMentions: { parse: [], repliedUser: false } });
+      const lines = users.map((entry, idx) => {
+        const flags = [entry.deterred ? 'deterred' : '', entry.muted ? 'muted' : ''].filter(Boolean).join(', ');
+        return `${idx + 1}. ${entry.userId || entry.id} | ${entry.nickname || 'unknown'} | ${flags} | ${mask(entry.cookieUserId)}`;
+      });
+      return message.reply({ content: ['Moderated users:', ...lines].join('\n').slice(0, 1900), allowedMentions: { parse: [], repliedUser: false } });
     }
     if (action === 'ban') {
       const selector = tokens.join(' ').trim();
       if (!selector) return message.reply({ content: `Usage: \`${commandPrefix} deter ban <cookieUserId|nickname|ip>\``, allowedMentions: { parse: [], repliedUser: false } });
       try {
+        const onlineMatches = findOnlineNicknameMatches(io, getNickname, selector);
+        if (onlineMatches.length > 1) {
+          /*
+            Identical live nicknames are genuinely ambiguous, so do not guess
+            for a destructive command. Unlike the old generic error, this
+            response exposes stable selectors that the administrator can copy
+            directly into a follow-up command.
+          */
+          const choices = onlineMatches.map((match) => `${match.nickname} (${match.userId})`).join(', ');
+          return message.reply({
+            content: sanitizeMentions(`More than one online user is named ${selector}: ${choices}. Retry with \`${commandPrefix} deter ban <userId>\`.`),
+            allowedMentions: { parse: [], repliedUser: false },
+          });
+        }
+
+        let stableSelector = onlineMatches[0]?.userId || null;
+        if (!stableSelector) {
           const verifiedMatch = resolveIdentitySelector(selector, listVerifiedUsers(), { includeId: false });
           if (verifiedMatch.error && !/not found/i.test(verifiedMatch.error)) {
             return message.reply({ content: sanitizeMentions(verifiedMatch.error), allowedMentions: { parse: [], repliedUser: false } });
           }
+          stableSelector = verifiedMatch.record?.userId || verifiedMatch.record?.id || verifiedMatch.record?.cookieUserId || selector;
+        }
         // Ban reasons were deliberately removed from the command grammar. The
         // full remaining text is now always the selector, which lets lockdown
         // admins deter multi-word nicknames without quoting or delimiter rules.
-        const stableSelector = verifiedMatch.record?.userId || verifiedMatch.record?.id || verifiedMatch.record?.cookieUserId || selector;
         const deterred = deterUser(stableSelector, { actor: message.actor?.id || null });
         return message.reply({ content: sanitizeMentions(`${deterred.created ? 'Deterred' : 'Updated deterrence for'} ${deterred.nickname || 'unknown'} (${mask(deterred.cookieUserId)}).`), allowedMentions: { parse: [], repliedUser: false } });
       } catch (err) {
@@ -50,8 +120,47 @@ function createDeterCommand({ listDeterredUsers, listVerifiedUsers, deterUser, u
         return message.reply({ content: sanitizeMentions(`Failed to remove deterrence: ${err.message}`), allowedMentions: { parse: [], repliedUser: false } });
       }
     }
-    return message.reply({ content: `Unknown deter command. Use \`${commandPrefix} deter list\`, \`${commandPrefix} deter ban <selector>\`, or \`${commandPrefix} deter unban <selector>\`.`, allowedMentions: { parse: [], repliedUser: false } });
+    if (action === 'mute' || action === 'unmute') {
+      const selector = tokens.join(' ').trim();
+      if (!selector) return message.reply({ content: `Usage: \`${commandPrefix} deter ${action} <userId|cookieUserId|nickname|ip>\``, allowedMentions: { parse: [], repliedUser: false } });
+      try {
+        const onlineMatches = findOnlineNicknameMatches(io, getNickname, selector);
+        if (onlineMatches.length > 1) {
+          const choices = onlineMatches.map((match) => `${match.nickname} (${match.userId})`).join(', ');
+          return message.reply({
+            content: sanitizeMentions(`More than one online user is named ${selector}: ${choices}. Retry with \`${commandPrefix} deter ${action} <userId>\`.`),
+            allowedMentions: { parse: [], repliedUser: false },
+          });
+        }
+
+        let stableSelector = onlineMatches[0]?.userId || null;
+        if (!stableSelector) {
+          const storedCandidates = uniqueIdentityRecords([...listVerifiedUsers(), ...listMutedUsers()]);
+          const storedMatch = resolveIdentitySelector(selector, storedCandidates, { includeId: true });
+          if (storedMatch.error && !/not found/i.test(storedMatch.error)) {
+            return message.reply({ content: sanitizeMentions(storedMatch.error), allowedMentions: { parse: [], repliedUser: false } });
+          }
+          /*
+            Unverified users may not appear in the convenience candidate list.
+            Passing the original exact selector through lets verificationService
+            resolve any canonical identity without making fuzzy guesses here.
+          */
+          stableSelector = storedMatch.record?.userId || storedMatch.record?.id || storedMatch.record?.cookieUserId || selector;
+        }
+
+        const updated = action === 'mute'
+          ? muteUser(stableSelector, message.actor?.id || null)
+          : unmuteUser(stableSelector, message.actor?.id || null);
+        return message.reply({
+          content: sanitizeMentions(`${action === 'mute' ? 'Muted' : 'Unmuted'} ${updated.nickname || 'unknown'} (${mask(updated.cookieUserId)}).`),
+          allowedMentions: { parse: [], repliedUser: false },
+        });
+      } catch (err) {
+        return message.reply({ content: sanitizeMentions(`Failed to ${action} user: ${err.message}`), allowedMentions: { parse: [], repliedUser: false } });
+      }
+    }
+    return message.reply({ content: `Unknown deter command. Use \`${commandPrefix} deter list\`, \`${commandPrefix} deter ban <selector>\`, \`${commandPrefix} deter unban <selector>\`, \`${commandPrefix} deter mute <selector>\`, or \`${commandPrefix} deter unmute <selector>\`.`, allowedMentions: { parse: [], repliedUser: false } });
   };
 }
 
-module.exports = { createDeterCommand };
+module.exports = { createDeterCommand, findOnlineNicknameMatches, uniqueIdentityRecords };

server/src/services/operatorCommandService/commands/deter.test.js

@@ -0,0 +1,113 @@
+// Operator Deter Command Tests
+// Purpose: Verifies that live nickname identity takes precedence over ambiguous stored aliases.
+// Scope: Exercises only command target resolution with in-memory socket and identity doubles.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createDeterCommand } = require('./deter');
+
+function createSocket(id, userId, nickname) {
+  return { id, data: { userId, nickname } };
+}
+
+function createHarness(sockets = [], verifiedUsers = []) {
+  const deterCalls = [];
+  const muteCalls = [];
+  const replies = [];
+  const handler = createDeterCommand({
+    io: { sockets: { sockets: new Map(sockets.map((socket) => [socket.id, socket])) } },
+    getNickname: (socket) => socket?.data?.nickname || '',
+    listDeterredUsers: () => [],
+    listMutedUsers: () => [],
+    listVerifiedUsers: () => verifiedUsers,
+    deterUser: (selector) => {
+      deterCalls.push(selector);
+      return { created: true, nickname: 'Croissant', cookieUserId: 'cookie-croissant' };
+    },
+    undeterUser: () => null,
+    muteUser: (selector) => {
+      muteCalls.push({ action: 'mute', selector });
+      return { nickname: 'Croissant', cookieUserId: 'cookie-croissant' };
+    },
+    unmuteUser: (selector) => {
+      muteCalls.push({ action: 'unmute', selector });
+      return { nickname: 'Croissant', cookieUserId: 'cookie-croissant' };
+    },
+    sanitizeMentions: (value) => value,
+    config: { commands: { prefix: 'rs' } },
+  });
+  const message = {
+    actor: { id: 'admin', isLockdownAdmin: true },
+    reply: async (payload) => {
+      replies.push(payload);
+      return payload;
+    },
+  };
+  return { handler, message, deterCalls, muteCalls, replies };
+}
+
+test('prefers the one online exact nickname over ambiguous stored records', async () => {
+  const verifiedUsers = [
+    { userId: 'old-user', nickname: 'Croissant', cookieUserId: 'old-cookie' },
+    { userId: 'live-user', nickname: 'Croissant', cookieUserId: 'live-cookie' },
+  ];
+  const { handler, message, deterCalls } = createHarness([
+    createSocket('socket-1', 'live-user', 'Croissant'),
+  ], verifiedUsers);
+
+  await handler(message, ['ban', 'croissant']);
+
+  assert.deepEqual(deterCalls, ['live-user']);
+});
+
+test('collapses multiple sockets belonging to the same online identity', async () => {
+  const { handler, message, deterCalls } = createHarness([
+    createSocket('socket-1', 'live-user', 'Croissant'),
+    createSocket('socket-2', 'live-user', 'croissant'),
+  ]);
+
+  await handler(message, ['ban', 'Croissant']);
+
+  assert.deepEqual(deterCalls, ['live-user']);
+});
+
+test('returns usable user ids when different online identities share a nickname', async () => {
+  const { handler, message, deterCalls, replies } = createHarness([
+    createSocket('socket-1', 'user-one', 'Croissant'),
+    createSocket('socket-2', 'user-two', 'croissant'),
+  ]);
+
+  await handler(message, ['ban', 'croissant']);
+
+  assert.deepEqual(deterCalls, []);
+  assert.match(replies[0].content, /user-one/);
+  assert.match(replies[0].content, /user-two/);
+  assert.match(replies[0].content, /rs deter ban <userId>/);
+});
+
+test('mute uses the same exact online nickname preference as ban', async () => {
+  const verifiedUsers = [
+    { userId: 'old-user', nickname: 'Croissant', cookieUserId: 'old-cookie' },
+    { userId: 'live-user', nickname: 'Croissant', cookieUserId: 'live-cookie' },
+  ];
+  const { handler, message, muteCalls } = createHarness([
+    createSocket('socket-1', 'live-user', 'Croissant'),
+  ], verifiedUsers);
+
+  await handler(message, ['mute', 'croissant']);
+
+  assert.deepEqual(muteCalls, [{ action: 'mute', selector: 'live-user' }]);
+});
+
+test('unmute returns usable ids for genuinely duplicated online nicknames', async () => {
+  const { handler, message, muteCalls, replies } = createHarness([
+    createSocket('socket-1', 'user-one', 'Croissant'),
+    createSocket('socket-2', 'user-two', 'croissant'),
+  ]);
+
+  await handler(message, ['unmute', 'Croissant']);
+
+  assert.deepEqual(muteCalls, []);
+  assert.match(replies[0].content, /user-one/);
+  assert.match(replies[0].content, /user-two/);
+  assert.match(replies[0].content, /rs deter unmute <userId>/);
+});

server/src/services/operatorCommandService/commands/funHelpers.js

@@ -0,0 +1,174 @@
+// Operator Fun Command Helpers
+// Purpose: Shared actor identity, target lookup, and deterministic randomness for the fun commands.
+// Scope: No side effects; every function here is safe to call before permission checks pass.
+const { normalizeSearchText, normalizeText, resolveRoverSelector } = require('./resolvers');
+
+// Echoed user text is capped so a fun command cannot be used to shout a wall of
+// text into every bridged Discord channel.
+const MAX_ECHO_LENGTH = 180;
+const PLAIN_MENTIONS = { parse: [], repliedUser: false };
+
+/*
+  Fun counters have to survive across transports, so they are keyed by a stable
+  identity rather than a connection. Site chat resolves to the identity user id
+  that moderation already uses; Discord has no row in that database, so it gets
+  its own key space. An unidentified site socket falls back to its socket id,
+  which means its tally resets on reconnect — acceptable for a joke counter, and
+  much better than crediting every anonymous visitor to one shared bucket.
+*/
+function buildActorKey(request) {
+  const transport = normalizeText(request?.transport) || 'unknown';
+  if (transport === 'discord') {
+    const discordId = normalizeText(request?.actor?.id);
+    return discordId ? `discord:${discordId}` : null;
+  }
+  const userId = normalizeText(request?.actor?.userId);
+  if (userId) return `user:${userId}`;
+  const socketId = normalizeText(request?.actor?.id);
+  return socketId ? `socket:${socketId}` : null;
+}
+
+function actorLabel(request) {
+  return normalizeText(request?.actor?.label) || 'someone';
+}
+
+/*
+  Collapses every connected socket for one person onto their canonical user id so
+  extra browser tabs cannot make a target look ambiguous. Mirrors the same
+  approach the deter command uses for moderation targets.
+*/
+function findOnlineUsers(io, getNickname, selector) {
+  const normalizedSelector = normalizeSearchText(selector);
+  if (!normalizedSelector) return [];
+
+  const sockets = io?.sockets?.sockets;
+  if (!sockets || typeof sockets.forEach !== 'function') return [];
+
+  const byUserId = new Map();
+  sockets.forEach((socket) => {
+    const nickname = getNickname?.(socket);
+    if (normalizeSearchText(nickname) !== normalizedSelector) return;
+    const userId = normalizeText(socket?.data?.userId);
+    const key = userId || `socket:${normalizeText(socket?.id)}`;
+    if (!key) return;
+    if (!byUserId.has(key)) {
+      byUserId.set(key, { userId: userId || null, nickname: normalizeText(nickname), socket });
+    }
+  });
+
+  return Array.from(byUserId.values());
+}
+
+/*
+  A fun command should still work when the target is not a real user — bonking
+  "the dishwasher" is half the point. So an unmatched selector is not an error:
+  it becomes a plain label and simply credits nobody's tally. Ambiguity is
+  treated the same way, because guessing which of two identical nicknames took
+  the hit would be worse than crediting neither.
+*/
+function resolveFunTarget({ io, getNickname, selector }) {
+  const label = clampEcho(selector);
+  if (!label) return null;
+
+  const matches = findOnlineUsers(io, getNickname, selector);
+  if (matches.length === 1) {
+    const [match] = matches;
+    return {
+      label: match.nickname || label,
+      actorKey: match.userId ? `user:${match.userId}` : null,
+      socket: match.socket || null,
+      online: true,
+    };
+  }
+
+  return { label, actorKey: null, socket: null, online: false };
+}
+
+/*
+  Rover-scoped fun commands accept an explicit rover name and otherwise fall back
+  to whichever rover the caller is already attached to. Discord has no socket
+  behind it, so the fallback simply is not available there and the caller is asked
+  to name a rover rather than having one chosen for them.
+*/
+function createRoverResolver({ rovers, roverManager, getActorSocket, commandPrefix = 'rs' }) {
+  return function resolveTargetRover(selector, action = 'pet') {
+    const query = normalizeText(selector);
+    if (query) {
+      const resolved = resolveRoverSelector(query, rovers);
+      if (resolved.error) return { error: resolved.error };
+      return { id: resolved.id, name: resolved.label || resolved.id, record: resolved.record };
+    }
+
+    const socket = getActorSocket?.() || null;
+    if (!socket) return { error: `Name a rover: \`${commandPrefix} ${action} <rover>\`` };
+
+    // getPrimaryRoverForSocket takes a socket id and returns a rover id string.
+    const roverId = normalizeText(roverManager?.getPrimaryRoverForSocket?.(socket.id));
+    if (!roverId) return { error: 'You are not on a rover right now. Name one instead.' };
+    const record = rovers.get(roverId) || null;
+    return { id: roverId, name: record?.meta?.name || roverId, record, socket };
+  };
+}
+
+function clampEcho(value) {
+  const text = normalizeText(value).replace(/\s+/g, ' ');
+  if (!text) return '';
+  if (text.length <= MAX_ECHO_LENGTH) return text;
+  return `${text.slice(0, MAX_ECHO_LENGTH - 1)}…`;
+}
+
+/*
+  FNV-1a. Fun commands that judge something — `ship`, `rate`, `8ball` — use a
+  hash of the input instead of Math.random so the same question always gets the
+  same answer. Re-rolling until you like the verdict is not funny; a server that
+  stubbornly insists your ship rating is 4% is.
+*/
+function hashSeed(value) {
+  const text = normalizeSearchText(value);
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function pickBySeed(list, seed) {
+  const items = Array.isArray(list) ? list : [];
+  if (!items.length) return null;
+  return items[seed % items.length];
+}
+
+// Order-independent so `rs ship a b` and `rs ship b a` agree with each other.
+function pairSeed(left, right) {
+  const pair = [normalizeSearchText(left), normalizeSearchText(right)].sort();
+  return hashSeed(pair.join(' '));
+}
+
+function percentFromSeed(seed) {
+  return seed % 101;
+}
+
+function ordinal(count) {
+  const value = Number(count) || 0;
+  const mod100 = value % 100;
+  if (mod100 >= 11 && mod100 <= 13) return `${value}th`;
+  const suffix = { 1: 'st', 2: 'nd', 3: 'rd' }[value % 10] || 'th';
+  return `${value}${suffix}`;
+}
+
+module.exports = {
+  MAX_ECHO_LENGTH,
+  PLAIN_MENTIONS,
+  actorLabel,
+  buildActorKey,
+  clampEcho,
+  createRoverResolver,
+  findOnlineUsers,
+  hashSeed,
+  ordinal,
+  pairSeed,
+  percentFromSeed,
+  pickBySeed,
+  resolveFunTarget,
+};

server/src/services/operatorCommandService/commands/funHelpers.test.js

@@ -0,0 +1,162 @@
+// Operator Fun Helper Tests
+// Purpose: Locks down actor identity, target resolution, and the deterministic seeding the fun commands depend on.
+// Scope: Pure helpers plus in-memory socket doubles; nothing here touches the fun stats store.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const {
+  buildActorKey,
+  clampEcho,
+  createRoverResolver,
+  hashSeed,
+  ordinal,
+  pairSeed,
+  percentFromSeed,
+  pickBySeed,
+  resolveFunTarget,
+  MAX_ECHO_LENGTH,
+} = require('./funHelpers');
+
+function socket(id, userId, nickname) {
+  return { id, data: { userId, nickname } };
+}
+
+function harness(sockets = []) {
+  return {
+    io: { sockets: { sockets: new Map(sockets.map((entry) => [entry.id, entry])) } },
+    getNickname: (entry) => entry?.data?.nickname || '',
+  };
+}
+
+test('site chat keys on the identity user id, not the socket', () => {
+  assert.equal(
+    buildActorKey({ transport: 'web-chat', actor: { id: 'socket-1', userId: 'u-alice' } }),
+    'user:u-alice',
+  );
+});
+
+test('an unidentified site socket falls back to its socket id', () => {
+  assert.equal(
+    buildActorKey({ transport: 'web-chat', actor: { id: 'socket-1' } }),
+    'socket:socket-1',
+  );
+});
+
+test('discord actors get their own key space so ids cannot collide with identity ids', () => {
+  assert.equal(buildActorKey({ transport: 'discord', actor: { id: '4242' } }), 'discord:4242');
+});
+
+test('an actor with no usable id at all is rejected rather than sharing a bucket', () => {
+  assert.equal(buildActorKey({ transport: 'web-chat', actor: {} }), null);
+  assert.equal(buildActorKey({ transport: 'discord', actor: {} }), null);
+});
+
+test('a single online nickname resolves to that user and credits their tally', () => {
+  const { io, getNickname } = harness([socket('s1', 'u-bob', 'bob')]);
+  const resolved = resolveFunTarget({ io, getNickname, selector: 'BOB' });
+  assert.equal(resolved.label, 'bob');
+  assert.equal(resolved.actorKey, 'user:u-bob');
+  assert.equal(resolved.online, true);
+});
+
+test('multiple tabs for one person do not make the target ambiguous', () => {
+  const { io, getNickname } = harness([
+    socket('s1', 'u-bob', 'bob'),
+    socket('s2', 'u-bob', 'bob'),
+  ]);
+  const resolved = resolveFunTarget({ io, getNickname, selector: 'bob' });
+  assert.equal(resolved.actorKey, 'user:u-bob');
+});
+
+test('an unmatched selector still works but credits nobody', () => {
+  const { io, getNickname } = harness([socket('s1', 'u-bob', 'bob')]);
+  const resolved = resolveFunTarget({ io, getNickname, selector: 'the dishwasher' });
+  assert.equal(resolved.label, 'the dishwasher');
+  assert.equal(resolved.actorKey, null);
+  assert.equal(resolved.online, false);
+});
+
+test('two different people sharing a nickname credit neither', () => {
+  const { io, getNickname } = harness([
+    socket('s1', 'u-bob', 'bob'),
+    socket('s2', 'u-other', 'bob'),
+  ]);
+  const resolved = resolveFunTarget({ io, getNickname, selector: 'bob' });
+  assert.equal(resolved.actorKey, null);
+});
+
+test('echoed text is length capped so a fun command cannot shout a wall of text', () => {
+  const long = 'a'.repeat(500);
+  const clamped = clampEcho(long);
+  assert.equal(clamped.length, MAX_ECHO_LENGTH);
+  assert.ok(clamped.endsWith('…'));
+});
+
+test('ship is order independent so both spellings agree', () => {
+  assert.equal(pairSeed('alice', 'bob'), pairSeed('bob', 'alice'));
+});
+
+test('seeded verdicts are stable, so a rating cannot be rerolled by asking again', () => {
+  const first = percentFromSeed(pairSeed('alice', 'bob'));
+  const second = percentFromSeed(pairSeed('alice', 'bob'));
+  assert.equal(first, second);
+  assert.ok(first >= 0 && first <= 100);
+});
+
+test('hashSeed ignores case and surrounding whitespace', () => {
+  assert.equal(hashSeed('  Will It Dock '), hashSeed('will it dock'));
+});
+
+test('pickBySeed stays in range and tolerates an empty list', () => {
+  const list = ['a', 'b', 'c'];
+  for (let seed = 0; seed < 20; seed += 1) {
+    assert.ok(list.includes(pickBySeed(list, seed)));
+  }
+  assert.equal(pickBySeed([], 5), null);
+});
+
+test('ordinal handles the teens correctly', () => {
+  assert.equal(ordinal(1), '1st');
+  assert.equal(ordinal(2), '2nd');
+  assert.equal(ordinal(3), '3rd');
+  assert.equal(ordinal(4), '4th');
+  assert.equal(ordinal(11), '11th');
+  assert.equal(ordinal(12), '12th');
+  assert.equal(ordinal(13), '13th');
+  assert.equal(ordinal(21), '21st');
+  assert.equal(ordinal(111), '111th');
+});
+
+test('an explicit rover name wins over whatever the caller is attached to', () => {
+  const rovers = new Map([
+    ['rover-1', { id: 'rover-1', meta: { name: 'Roomba One' } }],
+    ['rover-2', { id: 'rover-2', meta: { name: 'Roomba Two' } }],
+  ]);
+  const resolve = createRoverResolver({
+    rovers,
+    roverManager: { getPrimaryRoverForSocket: () => 'rover-1' },
+    getActorSocket: () => ({ id: 's1' }),
+  });
+  assert.equal(resolve('Roomba Two').id, 'rover-2');
+});
+
+test('with no rover named the caller\'s current rover is used', () => {
+  const rovers = new Map([['rover-1', { id: 'rover-1', meta: { name: 'Roomba One' } }]]);
+  const resolve = createRoverResolver({
+    rovers,
+    roverManager: { getPrimaryRoverForSocket: (socketId) => (socketId === 's1' ? 'rover-1' : null) },
+    getActorSocket: () => ({ id: 's1' }),
+  });
+  const resolved = resolve('');
+  assert.equal(resolved.id, 'rover-1');
+  assert.equal(resolved.name, 'Roomba One');
+});
+
+test('without a socket the caller is asked to name a rover instead of one being chosen', () => {
+  const resolve = createRoverResolver({
+    rovers: new Map(),
+    roverManager: {},
+    getActorSocket: () => null,
+    commandPrefix: 'rs',
+  });
+  assert.match(resolve('', 'pet').error, /Name a rover/);
+});

server/src/services/operatorCommandService/commands/funRover.js

@@ -0,0 +1,285 @@
+// Operator Fun Rover Commands
+// Purpose: Implements the fun commands that actually make the fleet or the room do something (honk, boo, disco, spin, vibecheck).
+// Scope: Every handler here re-checks control and feature gating itself, because issueCommand bypasses the socket command guards.
+const { getCommandConfig } = require('../../operatorCommandService/config');
+const { describeWait } = require('../cooldowns');
+const {
+  PLAIN_MENTIONS,
+  actorLabel,
+  buildActorKey,
+  createRoverResolver,
+  hashSeed,
+  pickBySeed,
+  resolveFunTarget,
+} = require('./funHelpers');
+
+// Durations are deliberately short and are also bounded rover-side: roverd
+// enforces its own horn MaxDuration, so a lost stop command cannot leave a horn
+// sounding forever.
+const HONK_MS = 600;
+const HONK_FREQ_HZ = 440;
+const SPIN_MS = 1200;
+const SPIN_SPEED = 120;
+const DISCO_MS = 12 * 1000;
+const DISCO_TICK_MS = 750;
+
+const HONK_ACTOR_COOLDOWN_MS = 20 * 1000;
+const HONK_ROVER_COOLDOWN_MS = 8 * 1000;
+const BOO_COOLDOWN_MS = 30 * 1000;
+const SPIN_COOLDOWN_MS = 25 * 1000;
+const DISCO_COOLDOWN_MS = 2 * 60 * 1000;
+const VIBECHECK_COOLDOWN_MS = 5 * 1000;
+
+/*
+  Taunts are a fixed list rather than caller-supplied text on purpose. `boo` puts
+  audio out of a speaker in a room full of people, so letting it read arbitrary
+  input would turn a joke command into an unmoderated TTS channel aimed at
+  whoever is nearest the rover.
+*/
+const BOO_TAUNTS = [
+  'Boo.', 'Your driving is being reviewed.', 'That was a choice.',
+  'The wall was right there.', 'Someone in chat is laughing at you.',
+  'I have seen better parking from the Neato.', 'Boo. Respectfully.',
+  'This is a citizen\'s arrest.', 'Turn left. No, the other left.',
+];
+
+const VIBE_VERDICTS = [
+  'immaculate', 'acceptable', 'questionable', 'concerning', 'dire', 'unwell',
+];
+
+function describeBattery(batteryState) {
+  const display = Number(batteryState?.percentDisplay);
+  if (Number.isFinite(display)) return `${Math.round(display)}%`;
+  const percent = Number(batteryState?.percent);
+  if (Number.isFinite(percent)) return `${Math.round(percent * 100)}%`;
+  return 'unknown';
+}
+
+function createFunRoverCommands({
+  io,
+  rovers,
+  roverManager,
+  getNickname,
+  getActiveDrivers,
+  getActorSocket,
+  issueCommand,
+  homeAssistantService,
+  isFeatureEnabled,
+  sanitizeMentions,
+  cooldowns,
+  logger,
+  config,
+}) {
+  const { prefix: commandPrefix } = getCommandConfig(config);
+  const safe = (text) => (sanitizeMentions ? sanitizeMentions(text) : String(text || ''));
+  const resolveTargetRover = createRoverResolver({ rovers, roverManager, getActorSocket, commandPrefix });
+
+  function reply(message, content) {
+    return message.reply({ content: safe(content), allowedMentions: PLAIN_MENTIONS });
+  }
+
+  function gate(message, action, windowMs) {
+    const actorKey = buildActorKey(message);
+    if (!actorKey) return { error: 'Could not identify you well enough to do that.' };
+    const wait = cooldowns.consume(`${action}:${actorKey}`, windowMs);
+    if (wait > 0) return { error: `Slow down — try \`${commandPrefix} ${action}\` again in ${describeWait(wait)}.` };
+    return { actorKey, label: actorLabel(message) };
+  }
+
+  /*
+    issueCommand is the raw rover transport: it performs none of the ownership,
+    deterrence, or private-safety checks that the socket `command` handler applies.
+    Any fun command that moves hardware therefore has to prove control here, which
+    also means these commands are inherently site-chat only — a Discord message has
+    no socket and so can never satisfy canDrive.
+  */
+  function requireDriveControl(action, selector) {
+    const socket = getActorSocket?.() || null;
+    if (!socket) {
+      return { error: `\`${commandPrefix} ${action}\` only works from site chat, where you can actually be driving.` };
+    }
+    const rover = resolveTargetRover(selector, action);
+    if (rover.error) return { error: rover.error };
+    if (!roverManager?.canDrive?.(rover.id, socket)) {
+      return { error: `You need control of ${rover.name} to do that.` };
+    }
+    return { rover, socket };
+  }
+
+  function safeIssue(roverId, payload, context) {
+    try {
+      issueCommand(roverId, payload);
+      return true;
+    } catch (err) {
+      // Deferred stop commands routinely land after a rover drops off. That is
+      // expected, not an incident, so it is logged at debug volume and swallowed.
+      logger?.warn?.('Fun command could not reach rover', { roverId, context, error: err.message });
+      return false;
+    }
+  }
+
+  async function handleHonk(message, tokens = []) {
+    const control = requireDriveControl('honk', tokens.join(' '));
+    if (control.error) return reply(message, control.error);
+    const { rover } = control;
+
+    if (rover.record?.meta?.horn?.enabled === false) {
+      return reply(message, `${rover.name} has no horn fitted.`);
+    }
+
+    const gated = gate(message, 'honk', HONK_ACTOR_COOLDOWN_MS);
+    if (gated.error) return reply(message, gated.error);
+
+    // A second, rover-scoped window stops a group of drivers taking turns to
+    // honk the same rover continuously while each stays inside their own limit.
+    const roverWait = cooldowns.consume(`honk:rover:${rover.id}`, HONK_ROVER_COOLDOWN_MS);
+    if (roverWait > 0) {
+      return reply(message, `${rover.name} was just honked. Give it ${describeWait(roverWait)}.`);
+    }
+
+    if (!safeIssue(rover.id, { type: 'horn', horn: { action: 'start', waveform: 'sine', freqs: [HONK_FREQ_HZ] } }, 'honk:start')) {
+      return reply(message, `${rover.name} is offline.`);
+    }
+    setTimeout(() => safeIssue(rover.id, { type: 'horn', horn: { action: 'stop' } }, 'honk:stop'), HONK_MS);
+
+    return reply(message, `📢 HONK. (${rover.name})`);
+  }
+
+  async function handleSpin(message, tokens = []) {
+    const control = requireDriveControl('spin', tokens.join(' '));
+    if (control.error) return reply(message, control.error);
+    const { rover, socket } = control;
+
+    const gated = gate(message, 'spin', SPIN_COOLDOWN_MS);
+    if (gated.error) return reply(message, gated.error);
+
+    const maxWheelSpeed = Number(rover.record?.meta?.maxWheelSpeed);
+    const speed = Math.max(1, Math.min(SPIN_SPEED, Number.isFinite(maxWheelSpeed) && maxWheelSpeed > 0 ? maxWheelSpeed : SPIN_SPEED));
+    let driveDirect = { left: speed, right: -speed };
+    /*
+      Private rovers can carry a reduced speed ceiling that the socket path would
+      normally apply. Applying it explicitly keeps a fun command from being the one
+      way to exceed a limit an admin set for a specific rover.
+    */
+    const safeDrive = roverManager?.applyPrivateDriveSafety?.(rover.id, socket, driveDirect);
+    if (safeDrive) driveDirect = safeDrive;
+
+    if (!safeIssue(rover.id, { type: 'drive', driveDirect }, 'spin:start')) {
+      return reply(message, `${rover.name} is offline.`);
+    }
+    setTimeout(() => safeIssue(rover.id, { type: 'drive', driveDirect: { left: 0, right: 0 } }, 'spin:stop'), SPIN_MS);
+
+    return reply(message, `🌀 ${rover.name} is doing a spin.`);
+  }
+
+  async function handleBoo(message, tokens = []) {
+    const selector = tokens.join(' ').trim();
+    if (!selector) return reply(message, `Usage: \`${commandPrefix} boo <user>\``);
+
+    const gated = gate(message, 'boo', BOO_COOLDOWN_MS);
+    if (gated.error) return reply(message, gated.error);
+
+    const resolved = resolveFunTarget({ io, getNickname, selector });
+    if (!resolved) return reply(message, `Usage: \`${commandPrefix} boo <user>\``);
+    if (!resolved.online || !resolved.socket) {
+      return reply(message, `${resolved.label} is not here to be booed.`);
+    }
+
+    // Boo lands on the rover the target is actually driving, so it needs the
+    // active-driver map rather than merely which rovers they are watching.
+    const drivers = getActiveDrivers?.() || {};
+    const roverId = Object.keys(drivers).find((id) => drivers[id] === resolved.socket.id) || null;
+    if (!roverId) return reply(message, `${resolved.label} is not driving anything right now.`);
+
+    const record = rovers.get(String(roverId));
+    const roverName = record?.meta?.name || roverId;
+    if (record?.meta?.audio?.ttsEnabled === false) {
+      return reply(message, `${roverName} cannot speak.`);
+    }
+
+    const taunt = pickBySeed(BOO_TAUNTS, hashSeed(`${gated.actorKey}:${resolved.label}`));
+    if (!safeIssue(roverId, { type: 'tts', tts: { text: taunt, speak: true, engine: 'chromegtts' } }, 'boo')) {
+      return reply(message, `${roverName} is offline.`);
+    }
+
+    return reply(message, `👻 Booed ${resolved.label} through ${roverName}.`);
+  }
+
+  async function handleDisco(message) {
+    if (!homeAssistantService || !isFeatureEnabled?.('homeAssistant')) {
+      return reply(message, 'Room light controls are unavailable.');
+    }
+
+    // An admin lock on the room lights is a policy boundary. Disco is a scene
+    // change like `rs lights on`, so it must not be the one command that ignores it.
+    const lightPolicy = homeAssistantService.getLightPolicyState?.() || {};
+    if (lightPolicy.locked) {
+      return reply(message, 'Room lights are locked. No disco.');
+    }
+
+    const gated = gate(message, 'disco', DISCO_COOLDOWN_MS);
+    if (gated.error) return reply(message, gated.error);
+
+    const setAll = homeAssistantService.setAllControllableEntitiesState;
+    if (typeof setAll !== 'function') {
+      return reply(message, 'Room light controls are unavailable.');
+    }
+
+    const endsAt = Date.now() + DISCO_MS;
+    let on = false;
+    /*
+      Held in a local interval rather than the rewards effect store because a
+      disco is short and disposable. Nothing needs to survive a restart, and the
+      final tick always restores the lights to on.
+    */
+    const timer = setInterval(() => {
+      if (Date.now() >= endsAt) {
+        clearInterval(timer);
+        Promise.resolve(setAll('on')).catch((err) => {
+          logger?.warn?.('Disco could not restore lights', { error: err.message });
+        });
+        return;
+      }
+      on = !on;
+      Promise.resolve(setAll(on ? 'on' : 'off')).catch((err) => {
+        logger?.warn?.('Disco tick failed', { error: err.message });
+      });
+    }, DISCO_TICK_MS);
+
+    return reply(message, `🪩 Disco for ${Math.round(DISCO_MS / 1000)} seconds. Started by ${gated.label}.`);
+  }
+
+  async function handleVibecheck(message, tokens = []) {
+    const gated = gate(message, 'vibecheck', VIBECHECK_COOLDOWN_MS);
+    if (gated.error) return reply(message, gated.error);
+
+    const rover = resolveTargetRover(tokens.join(' '), 'vibecheck');
+    if (rover.error) return reply(message, rover.error);
+
+    const record = rover.record || rovers.get(rover.id) || null;
+    const battery = describeBattery(record?.batteryState);
+    const offline = !record?.ws;
+    const locked = Boolean(record?.locked);
+    const urgent = Boolean(record?.batteryState?.urgentActive);
+    const warn = Boolean(record?.batteryState?.warnActive);
+
+    let verdict;
+    if (offline) verdict = 'nonexistent — it is offline';
+    else if (urgent) verdict = 'dying';
+    else if (warn) verdict = 'running low';
+    else if (locked) verdict = 'locked out and sulking';
+    else verdict = pickBySeed(VIBE_VERDICTS, hashSeed(`${rover.id}:${battery}`));
+
+    return reply(message, `🔍 ${rover.name}: vibes are **${verdict}**. Battery ${battery}.`);
+  }
+
+  return {
+    honk: handleHonk,
+    boo: handleBoo,
+    disco: handleDisco,
+    spin: handleSpin,
+    vibecheck: handleVibecheck,
+  };
+}
+
+module.exports = { createFunRoverCommands, describeBattery };

server/src/services/operatorCommandService/commands/funRover.test.js

@@ -0,0 +1,297 @@
+// Operator Fun Rover Command Tests
+// Purpose: Verifies the control, feature, and lock checks the hardware-backed fun commands must make themselves.
+// Scope: issueCommand, roverManager, and Home Assistant are all doubles; no real rover or timer is involved.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createFunRoverCommands, describeBattery } = require('./funRover');
+const { createCooldownGate } = require('../cooldowns');
+
+const ALICE = { id: 's1', data: { userId: 'u-alice', nickname: 'alice' } };
+const BOB = { id: 's2', data: { userId: 'u-bob', nickname: 'bob' } };
+
+function createHarness({
+  canDrive = true,
+  socket = ALICE,
+  hornEnabled = true,
+  ttsEnabled = true,
+  online = true,
+  maxWheelSpeed = 300,
+  privateSafetyDrive = null,
+  activeDrivers = {},
+  homeAssistantService = null,
+  featureEnabled = false,
+  sockets = [ALICE, BOB],
+} = {}) {
+  const issued = [];
+  const record = {
+    id: 'rover-1',
+    ws: online ? {} : null,
+    locked: false,
+    meta: {
+      name: 'Roomba One',
+      maxWheelSpeed,
+      horn: { enabled: hornEnabled },
+      audio: { ttsEnabled },
+    },
+    batteryState: { percentDisplay: 74, warnActive: false, urgentActive: false },
+  };
+  const rovers = new Map([['rover-1', record]]);
+
+  const handlers = createFunRoverCommands({
+    io: { sockets: { sockets: new Map(sockets.map((entry) => [entry.id, entry])) } },
+    rovers,
+    roverManager: {
+      canDrive: () => canDrive,
+      getPrimaryRoverForSocket: () => 'rover-1',
+      applyPrivateDriveSafety: () => privateSafetyDrive,
+    },
+    getNickname: (entry) => entry?.data?.nickname || '',
+    getActiveDrivers: () => activeDrivers,
+    getActorSocket: () => socket,
+    issueCommand: (roverId, payload) => {
+      if (!record.ws) throw new Error('Rover offline');
+      issued.push({ roverId, ...payload });
+      return 'cmd-1';
+    },
+    homeAssistantService,
+    isFeatureEnabled: () => featureEnabled,
+    sanitizeMentions: (text) => String(text || '').replace(/@everyone/gi, '[everyone]'),
+    cooldowns: createCooldownGate(),
+    logger: { warn: () => {} },
+    config: { commands: { prefix: 'rs' } },
+  });
+
+  return { handlers, issued, record, rovers };
+}
+
+function message(actor = { id: 's1', userId: 'u-alice', label: 'alice' }) {
+  const replies = [];
+  return {
+    transport: 'web-chat',
+    actor,
+    replies,
+    reply: async (payload) => {
+      replies.push(payload);
+      return null;
+    },
+  };
+}
+
+test('honk starts the horn and schedules a stop', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const { handlers, issued } = createHarness();
+  const msg = message();
+  await handlers.honk(msg, []);
+
+  assert.match(msg.replies[0].content, /HONK/);
+  assert.deepEqual(issued.map((entry) => entry.horn.action), ['start']);
+
+  // The stop is deferred, so nothing has released the horn yet.
+  t.mock.timers.tick(1000);
+  assert.deepEqual(issued.map((entry) => entry.horn.action), ['start', 'stop']);
+});
+
+test('honk is refused without drive control', async () => {
+  const { handlers, issued } = createHarness({ canDrive: false });
+  const msg = message();
+  await handlers.honk(msg, []);
+
+  assert.match(msg.replies[0].content, /need control of Roomba One/);
+  assert.equal(issued.length, 0);
+});
+
+test('honk is refused from a transport with no socket, so Discord cannot drive hardware', async () => {
+  const { handlers, issued } = createHarness({ socket: null });
+  const msg = message({ id: '4242', label: 'DiscordUser' });
+  await handlers.honk(msg, []);
+
+  assert.match(msg.replies[0].content, /only works from site chat/);
+  assert.equal(issued.length, 0);
+});
+
+test('honk is refused on a rover with no horn fitted', async () => {
+  const { handlers, issued } = createHarness({ hornEnabled: false });
+  const msg = message();
+  await handlers.honk(msg, []);
+
+  assert.match(msg.replies[0].content, /no horn fitted/);
+  assert.equal(issued.length, 0);
+});
+
+test('a second driver cannot bypass the rover cooldown with their own fresh actor window', async () => {
+  const { handlers, issued } = createHarness();
+  await handlers.honk(message(), []);
+
+  const other = message({ id: 's2', userId: 'u-bob', label: 'bob' });
+  await handlers.honk(other, []);
+  assert.match(other.replies[0].content, /was just honked/);
+  // Only the first honk reached the rover.
+  assert.equal(issued.filter((entry) => entry.horn?.action === 'start').length, 1);
+});
+
+test('an offline rover reports offline instead of claiming a honk happened', async () => {
+  const { handlers } = createHarness({ online: false });
+  const msg = message();
+  await handlers.honk(msg, []);
+  assert.match(msg.replies[0].content, /is offline/);
+});
+
+test('spin clamps to the rover wheel speed ceiling and always stops itself', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const { handlers, issued } = createHarness({ maxWheelSpeed: 50 });
+  const msg = message();
+  await handlers.spin(msg, []);
+
+  assert.equal(issued[0].driveDirect.left, 50);
+  assert.equal(issued[0].driveDirect.right, -50);
+
+  t.mock.timers.tick(2000);
+  assert.deepEqual(issued[1].driveDirect, { left: 0, right: 0 });
+});
+
+test('spin honours a private rover safety override rather than bypassing it', async () => {
+  const { handlers, issued } = createHarness({ privateSafetyDrive: { left: 20, right: -20 } });
+  await handlers.spin(message(), []);
+  assert.deepEqual(issued[0].driveDirect, { left: 20, right: -20 });
+});
+
+test('spin is refused without drive control', async () => {
+  const { handlers, issued } = createHarness({ canDrive: false });
+  const msg = message();
+  await handlers.spin(msg, []);
+  assert.match(msg.replies[0].content, /need control/);
+  assert.equal(issued.length, 0);
+});
+
+test('boo speaks a canned taunt rather than any caller supplied text', async () => {
+  const { handlers, issued } = createHarness({ activeDrivers: { 'rover-1': 's2' } });
+  const msg = message();
+  await handlers.boo(msg, ['bob']);
+
+  assert.equal(issued.length, 1);
+  assert.equal(issued[0].type, 'tts');
+  // The spoken text must not contain anything the caller typed.
+  assert.doesNotMatch(issued[0].tts.text, /bob/i);
+  assert.ok(issued[0].tts.text.length > 0);
+});
+
+test('boo is refused when the target is not driving anything', async () => {
+  const { handlers, issued } = createHarness({ activeDrivers: {} });
+  const msg = message();
+  await handlers.boo(msg, ['bob']);
+
+  assert.match(msg.replies[0].content, /not driving anything/);
+  assert.equal(issued.length, 0);
+});
+
+test('boo is refused when the target is not online at all', async () => {
+  const { handlers, issued } = createHarness({ sockets: [ALICE] });
+  const msg = message();
+  await handlers.boo(msg, ['nobody-here']);
+
+  assert.match(msg.replies[0].content, /not here to be booed/);
+  assert.equal(issued.length, 0);
+});
+
+test('boo is refused on a rover that cannot speak', async () => {
+  const { handlers, issued } = createHarness({ ttsEnabled: false, activeDrivers: { 'rover-1': 's2' } });
+  const msg = message();
+  await handlers.boo(msg, ['bob']);
+
+  assert.match(msg.replies[0].content, /cannot speak/);
+  assert.equal(issued.length, 0);
+});
+
+test('disco is unavailable when the Home Assistant feature is off', async () => {
+  const calls = [];
+  const { handlers } = createHarness({
+    featureEnabled: false,
+    homeAssistantService: {
+      getLightPolicyState: () => ({}),
+      setAllControllableEntitiesState: (state) => calls.push(state),
+    },
+  });
+  const msg = message();
+  await handlers.disco(msg, []);
+
+  assert.match(msg.replies[0].content, /unavailable/);
+  assert.equal(calls.length, 0);
+});
+
+test('disco obeys the room light lock', async () => {
+  const calls = [];
+  const { handlers } = createHarness({
+    featureEnabled: true,
+    homeAssistantService: {
+      getLightPolicyState: () => ({ locked: true, lockState: 'on' }),
+      setAllControllableEntitiesState: (state) => calls.push(state),
+    },
+  });
+  const msg = message();
+  await handlers.disco(msg, []);
+
+  assert.match(msg.replies[0].content, /locked/);
+  assert.equal(calls.length, 0);
+});
+
+test('disco strobes while unlocked and restores the lights on when it ends', async (t) => {
+  t.mock.timers.enable({ apis: ['setInterval', 'setTimeout', 'Date'] });
+  const calls = [];
+  const { handlers } = createHarness({
+    featureEnabled: true,
+    homeAssistantService: {
+      getLightPolicyState: () => ({ locked: false }),
+      setAllControllableEntitiesState: (state) => {
+        calls.push(state);
+        return Promise.resolve();
+      },
+    },
+  });
+  const msg = message();
+  await handlers.disco(msg, []);
+  assert.match(msg.replies[0].content, /Disco/);
+
+  t.mock.timers.tick(3000);
+  assert.ok(calls.length >= 2, `expected several ticks, saw ${calls.length}`);
+  assert.ok(calls.includes('on') && calls.includes('off'));
+
+  // Past the end of the window the lights must be put back on and left alone.
+  t.mock.timers.tick(20 * 1000);
+  assert.equal(calls[calls.length - 1], 'on');
+  const settled = calls.length;
+  t.mock.timers.tick(20 * 1000);
+  assert.equal(calls.length, settled);
+});
+
+test('vibecheck reports the battery and never issues a command', async () => {
+  const { handlers, issued } = createHarness();
+  const msg = message();
+  await handlers.vibecheck(msg, []);
+
+  assert.match(msg.replies[0].content, /Roomba One/);
+  assert.match(msg.replies[0].content, /Battery 74%/);
+  assert.equal(issued.length, 0);
+});
+
+test('vibecheck leads with the real problem when the battery is urgent', async () => {
+  const { handlers, record } = createHarness();
+  record.batteryState = { percentDisplay: 4, warnActive: true, urgentActive: true };
+  const msg = message();
+  await handlers.vibecheck(msg, []);
+  assert.match(msg.replies[0].content, /dying/);
+});
+
+test('vibecheck reports an offline rover as offline', async () => {
+  const { handlers, record } = createHarness();
+  record.ws = null;
+  const msg = message();
+  await handlers.vibecheck(msg, []);
+  assert.match(msg.replies[0].content, /offline/);
+});
+
+test('describeBattery falls back through the available fields', () => {
+  assert.equal(describeBattery({ percentDisplay: 55.4 }), '55%');
+  assert.equal(describeBattery({ percent: 0.42 }), '42%');
+  assert.equal(describeBattery({}), 'unknown');
+  assert.equal(describeBattery(null), 'unknown');
+});

server/src/services/operatorCommandService/commands/funStats.js

@@ -0,0 +1,118 @@
+// Operator Fun Stats Commands
+// Purpose: Implements the fun commands that read or extend persistent counters (bonkboard, pet, snitch).
+// Scope: Reads the roster and the fun stats store; issues no rover commands.
+const { getCommandConfig } = require('../../operatorCommandService/config');
+const { describeWait } = require('../cooldowns');
+const { PLAIN_MENTIONS, actorLabel, buildActorKey, createRoverResolver } = require('./funHelpers');
+
+const PET_COOLDOWN_MS = 10 * 1000;
+const READ_COOLDOWN_MS = 5 * 1000;
+const LEADERBOARD_SIZE = 10;
+
+function formatLeaderboard(title, rows, counter) {
+  const ranked = rows
+    .filter((row) => Number(row[counter]) > 0)
+    .sort((left, right) => Number(right[counter]) - Number(left[counter]))
+    .slice(0, LEADERBOARD_SIZE);
+  if (!ranked.length) return null;
+  const lines = ranked.map((row, index) => `${index + 1}. ${row.label || 'unknown'} — ${row[counter]}`);
+  return [`**${title}**`, ...lines].join('\n');
+}
+
+function createFunStatsCommands({
+  io,
+  rovers,
+  getNickname,
+  getActiveDrivers,
+  getActorSocket,
+  roverManager,
+  sanitizeMentions,
+  funStatsService,
+  cooldowns,
+  config,
+}) {
+  const { prefix: commandPrefix } = getCommandConfig(config);
+  const safe = (text) => (sanitizeMentions ? sanitizeMentions(text) : String(text || ''));
+
+  function reply(message, content) {
+    return message.reply({ content: safe(content), allowedMentions: PLAIN_MENTIONS });
+  }
+
+  function gate(message, action, windowMs) {
+    const actorKey = buildActorKey(message);
+    if (!actorKey) return { error: 'Could not identify you well enough to do that.' };
+    const wait = cooldowns.consume(`${action}:${actorKey}`, windowMs);
+    if (wait > 0) return { error: `Slow down — try \`${commandPrefix} ${action}\` again in ${describeWait(wait)}.` };
+    return { actorKey, label: actorLabel(message) };
+  }
+
+  const resolveTargetRover = createRoverResolver({ rovers, roverManager, getActorSocket, commandPrefix });
+
+  async function handleBonkboard(message) {
+    const gated = gate(message, 'bonkboard', READ_COOLDOWN_MS);
+    if (gated.error) return reply(message, gated.error);
+
+    const rows = funStatsService.listActorStats();
+    const sections = [
+      formatLeaderboard('Most bonks dealt', rows, 'bonksGiven'),
+      formatLeaderboard('Most bonks taken', rows, 'bonksTaken'),
+      formatLeaderboard('Most hugs given', rows, 'hugsGiven'),
+    ].filter(Boolean);
+
+    if (!sections.length) {
+      return reply(message, `Nobody has been bonked yet. Fix that with \`${commandPrefix} bonk <user>\`.`);
+    }
+    return reply(message, sections.join('\n\n').slice(0, 1900));
+  }
+
+  async function handlePet(message, tokens = []) {
+    const gated = gate(message, 'pet', PET_COOLDOWN_MS);
+    if (gated.error) return reply(message, gated.error);
+
+    const rover = resolveTargetRover(tokens.join(' '), 'pet');
+    if (rover.error) return reply(message, rover.error);
+
+    const pets = funStatsService.bumpRoverPets(rover.id, 1);
+    return reply(message, `🤖 ${gated.label} pets ${rover.name}. It has now been petted ${pets} time${pets === 1 ? '' : 's'}.`);
+  }
+
+  /*
+    Reads the same active-driver map the turn system uses, so it reports real
+    control rather than who merely has the page open. Rovers with nobody driving
+    are listed too — an empty fleet is exactly what a snitch should report.
+  */
+  async function handleSnitch(message) {
+    const gated = gate(message, 'snitch', READ_COOLDOWN_MS);
+    if (gated.error) return reply(message, gated.error);
+
+    const drivers = getActiveDrivers?.() || {};
+    const sockets = io?.sockets?.sockets;
+    const lines = [];
+
+    rovers.forEach((record, roverId) => {
+      const id = String(roverId);
+      const name = record?.meta?.name || id;
+      const socketId = drivers[id];
+      const socket = socketId && sockets?.get ? sockets.get(socketId) : null;
+      const nickname = socket ? getNickname?.(socket) : null;
+      if (nickname) {
+        lines.push(`• ${name} — ${nickname}`);
+      } else if (socketId) {
+        lines.push(`• ${name} — someone who will not say their name`);
+      } else {
+        lines.push(`• ${name} — nobody`);
+      }
+    });
+
+    if (!lines.length) return reply(message, 'No rovers are online to snitch about.');
+    return reply(message, ['🕵️ Currently driving:', ...lines].join('\n').slice(0, 1900));
+  }
+
+  return {
+    bonkboard: handleBonkboard,
+    pet: handlePet,
+    snitch: handleSnitch,
+  };
+}
+
+module.exports = { createFunStatsCommands, formatLeaderboard };

server/src/services/operatorCommandService/commands/funStats.test.js

@@ -0,0 +1,166 @@
+// Operator Fun Stats Command Tests
+// Purpose: Verifies the leaderboard ordering, rover pet counting, and what snitch reports.
+// Scope: In-memory stats and roster doubles only.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createFunStatsCommands, formatLeaderboard } = require('./funStats');
+const { createCooldownGate } = require('../cooldowns');
+
+const ALICE = { id: 's1', data: { userId: 'u-alice', nickname: 'alice' } };
+const BOB = { id: 's2', data: { userId: 'u-bob', nickname: 'bob' } };
+
+function createHarness({
+  actorRows = [],
+  activeDrivers = {},
+  socket = ALICE,
+  rovers = new Map([
+    ['rover-1', { id: 'rover-1', meta: { name: 'Roomba One' } }],
+    ['rover-2', { id: 'rover-2', meta: { name: 'Roomba Two' } }],
+  ]),
+} = {}) {
+  const pets = new Map();
+  const handlers = createFunStatsCommands({
+    io: { sockets: { sockets: new Map([[ALICE.id, ALICE], [BOB.id, BOB]]) } },
+    rovers,
+    getNickname: (entry) => entry?.data?.nickname || '',
+    getActiveDrivers: () => activeDrivers,
+    getActorSocket: () => socket,
+    roverManager: { getPrimaryRoverForSocket: () => 'rover-1' },
+    sanitizeMentions: (text) => String(text || '').replace(/@everyone/gi, '[everyone]'),
+    funStatsService: {
+      listActorStats: () => actorRows,
+      bumpRoverPets: (roverId, by) => {
+        const next = (pets.get(roverId) || 0) + by;
+        pets.set(roverId, next);
+        return next;
+      },
+    },
+    cooldowns: createCooldownGate(),
+    config: { commands: { prefix: 'rs' } },
+  });
+  return { handlers, pets };
+}
+
+function message(actor = { id: 's1', userId: 'u-alice', label: 'alice' }) {
+  const replies = [];
+  return {
+    transport: 'web-chat',
+    actor,
+    replies,
+    reply: async (payload) => {
+      replies.push(payload);
+      return null;
+    },
+  };
+}
+
+test('the leaderboard sorts descending and drops zero scores', () => {
+  const rows = [
+    { label: 'alice', bonksGiven: 2 },
+    { label: 'bob', bonksGiven: 9 },
+    { label: 'carol', bonksGiven: 0 },
+  ];
+  const rendered = formatLeaderboard('Most bonks dealt', rows, 'bonksGiven');
+  const lines = rendered.split('\n');
+  assert.equal(lines[1], '1. bob — 9');
+  assert.equal(lines[2], '2. alice — 2');
+  assert.equal(lines.length, 3, 'carol should not appear with a zero score');
+});
+
+test('the leaderboard is capped at ten entries', () => {
+  const rows = Array.from({ length: 25 }, (_, index) => ({ label: `user${index}`, bonksGiven: index + 1 }));
+  const rendered = formatLeaderboard('Most bonks dealt', rows, 'bonksGiven');
+  assert.equal(rendered.split('\n').length - 1, 10);
+});
+
+test('an all-zero counter renders no section at all', () => {
+  assert.equal(formatLeaderboard('Most bonks dealt', [{ label: 'alice', bonksGiven: 0 }], 'bonksGiven'), null);
+});
+
+test('bonkboard says so when nothing has happened yet', async () => {
+  const { handlers } = createHarness({ actorRows: [] });
+  const msg = message();
+  await handlers.bonkboard(msg, []);
+  assert.match(msg.replies[0].content, /Nobody has been bonked yet/);
+});
+
+test('bonkboard renders each populated section', async () => {
+  const { handlers } = createHarness({
+    actorRows: [
+      { label: 'alice', bonksGiven: 3, bonksTaken: 0, hugsGiven: 1 },
+      { label: 'bob', bonksGiven: 0, bonksTaken: 3, hugsGiven: 0 },
+    ],
+  });
+  const msg = message();
+  await handlers.bonkboard(msg, []);
+
+  assert.match(msg.replies[0].content, /Most bonks dealt/);
+  assert.match(msg.replies[0].content, /Most bonks taken/);
+  assert.match(msg.replies[0].content, /Most hugs given/);
+});
+
+test('bonkboard sanitizes stored labels, so a hostile nickname cannot ping a guild', async () => {
+  const { handlers } = createHarness({ actorRows: [{ label: '@everyone', bonksGiven: 1 }] });
+  const msg = message();
+  await handlers.bonkboard(msg, []);
+  assert.doesNotMatch(msg.replies[0].content, /@everyone/);
+});
+
+test('pet counts against the rover the caller is on when none is named', async () => {
+  const { handlers, pets } = createHarness();
+  const msg = message();
+  await handlers.pet(msg, []);
+
+  assert.match(msg.replies[0].content, /pets Roomba One/);
+  assert.match(msg.replies[0].content, /petted 1 time\./);
+  assert.equal(pets.get('rover-1'), 1);
+});
+
+test('pet accepts an explicit rover and keeps a separate count per rover', async () => {
+  const { handlers, pets } = createHarness();
+  await handlers.pet(message(), ['Roomba Two']);
+  await handlers.pet(message({ id: 's2', userId: 'u-bob', label: 'bob' }), ['Roomba Two']);
+
+  assert.equal(pets.get('rover-2'), 2);
+  assert.equal(pets.get('rover-1'), undefined);
+});
+
+test('pet pluralizes the running total', async () => {
+  const { handlers } = createHarness();
+  await handlers.pet(message(), []);
+  const second = message({ id: 's2', userId: 'u-bob', label: 'bob' });
+  await handlers.pet(second, []);
+  assert.match(second.replies[0].content, /petted 2 times\./);
+});
+
+test('pet from a transport with no socket asks for a rover name', async () => {
+  const { handlers, pets } = createHarness({ socket: null });
+  const msg = message({ id: '4242', label: 'DiscordUser' });
+  await handlers.pet(msg, []);
+
+  assert.match(msg.replies[0].content, /Name a rover/);
+  assert.equal(pets.size, 0);
+});
+
+test('snitch names the active driver and reports idle rovers as nobody', async () => {
+  const { handlers } = createHarness({ activeDrivers: { 'rover-1': 's2' } });
+  const msg = message();
+  await handlers.snitch(msg, []);
+
+  assert.match(msg.replies[0].content, /Roomba One — bob/);
+  assert.match(msg.replies[0].content, /Roomba Two — nobody/);
+});
+
+test('snitch handles a driver socket that has already gone away', async () => {
+  const { handlers } = createHarness({ activeDrivers: { 'rover-1': 'ghost-socket' } });
+  const msg = message();
+  await handlers.snitch(msg, []);
+  assert.match(msg.replies[0].content, /Roomba One — someone who will not say their name/);
+});
+
+test('snitch reports an empty fleet rather than an empty message', async () => {
+  const { handlers } = createHarness({ rovers: new Map() });
+  const msg = message();
+  await handlers.snitch(msg, []);
+  assert.match(msg.replies[0].content, /No rovers are online/);
+});

server/src/services/operatorCommandService/commands/funText.js

@@ -0,0 +1,361 @@
+// Operator Fun Text Commands
+// Purpose: Implements the social, text-only `rs` commands (bonk, hug, slap, 8ball, roll, coin, ship, rate, uwu, wanted).
+// Scope: Text and counters only; nothing here touches rover hardware.
+const { getCommandConfig } = require('../../operatorCommandService/config');
+const { describeWait } = require('../cooldowns');
+const {
+  PLAIN_MENTIONS,
+  actorLabel,
+  buildActorKey,
+  clampEcho,
+  hashSeed,
+  ordinal,
+  pairSeed,
+  percentFromSeed,
+  pickBySeed,
+  resolveFunTarget,
+} = require('./funHelpers');
+
+const TEXT_COOLDOWN_MS = 4 * 1000;
+
+/*
+  The bonk sound gets its own, much longer rover-scoped window. Playing it
+  interrupts whatever that rover is forwarding — including a live microphone — so
+  the audio must not be spammable even though the text bonk stays snappy, and a
+  group of people bonking one driver cannot chain it either.
+*/
+const BONK_SOUND_ROVER_COOLDOWN_MS = 20 * 1000;
+
+const SLAP_ITEMS = [
+  'a large trout', 'a rolled-up service manual', 'a dead AA battery', 'a docking station',
+  'a suspiciously warm power brick', 'half a roll of duct tape', 'a decommissioned brush guard',
+  'a bag of loose screws', 'an unlabelled USB cable', 'a soggy floor sensor',
+  'the heaviest available wrench', 'a stack of unread pull requests',
+];
+
+const EIGHT_BALL_ANSWERS = [
+  'Yes.', 'No.', 'Absolutely.', 'Absolutely not.', 'Ask again once the battery is charged.',
+  'Signs point to the docking station.', 'The overseer says no.', 'Almost certainly.',
+  'Not while anyone is watching.', 'Outlook cloudy, sensors dirty.', 'Try it and find out.',
+  'That is a maintenance window problem.', 'Only on a Tuesday.', 'The rover has already decided.',
+];
+
+const HUG_FLAVOURS = [
+  'gently', 'aggressively', 'with both brush guards', 'at full wheel speed',
+  'for slightly too long', 'while beeping softly', 'without asking first',
+];
+
+const WANTED_CRIMES = [
+  'reckless docking', 'driving with the brush on indoors', 'excessive honking',
+  'unauthorised carpet donuts', 'battery hoarding', 'ignoring the global objective',
+  'parking in the doorway', 'nine consecutive turn skips', 'talking to the Neato',
+  'strobing the room lights for fun', 'stealing another rover\'s charger',
+];
+
+const RATE_SUFFIXES = [
+  'No further questions.', 'I stand by this.', 'Do not appeal.', 'Take it or leave it.',
+  'The sensors agree.', 'This rating is final.',
+];
+
+/*
+  A dice roll is one of the few places a fun command should be genuinely random:
+  the whole point is that nobody can predict it. Everything that passes judgement
+  on a thing (`ship`, `rate`, `8ball`, `wanted`) is seeded from the input instead,
+  so re-running it cannot reroll a verdict somebody disliked.
+*/
+function rollDice(count, sides) {
+  let total = 0;
+  const rolls = [];
+  for (let index = 0; index < count; index += 1) {
+    const value = 1 + Math.floor(Math.random() * sides);
+    rolls.push(value);
+    total += value;
+  }
+  return { rolls, total };
+}
+
+function parseDiceSpec(spec) {
+  const text = String(spec || '').trim().toLowerCase() || '1d6';
+  const match = /^(\d*)d(\d+)$/.exec(text);
+  if (!match) {
+    // A bare number is read as a single die with that many sides so `rs roll 20`
+    // does the obvious thing instead of erroring.
+    const bare = /^(\d+)$/.exec(text);
+    if (!bare) return { error: 'Roll format is `NdN`, for example `2d6`.' };
+    const sides = Number(bare[1]);
+    if (sides < 2 || sides > 1000) return { error: 'Dice need between 2 and 1000 sides.' };
+    return { count: 1, sides };
+  }
+  const count = match[1] === '' ? 1 : Number(match[1]);
+  const sides = Number(match[2]);
+  if (count < 1 || count > 20) return { error: 'Roll between 1 and 20 dice.' };
+  if (sides < 2 || sides > 1000) return { error: 'Dice need between 2 and 1000 sides.' };
+  return { count, sides };
+}
+
+function uwuify(text) {
+  return String(text || '')
+    .replace(/[rl]/g, 'w')
+    .replace(/[RL]/g, 'W')
+    .replace(/n([aeiou])/g, 'ny$1')
+    .replace(/N([aeiou])/g, 'Ny$1')
+    .replace(/ove/g, 'uv')
+    .replace(/!+/g, ' !!');
+}
+
+function createFunTextCommands({
+  io,
+  getNickname,
+  getActiveDrivers,
+  publishEvent,
+  sanitizeMentions,
+  funStatsService,
+  cooldowns,
+  config,
+}) {
+  const { prefix: commandPrefix } = getCommandConfig(config);
+  const safe = (text) => (sanitizeMentions ? sanitizeMentions(text) : String(text || ''));
+
+  /*
+    Announces the bonk so audioForwardService can play the sound on the rover the
+    target is driving. Published as an event rather than calling the audio pipeline
+    directly, matching how the charging-complete cue is wired: the command layer
+    stays unaware of ffmpeg, and a server without the sound installed simply has
+    nothing listening that can do anything.
+  */
+  function announceBonk(targetSocket, targetLabel, actorLabelText) {
+    if (!targetSocket || typeof publishEvent !== 'function') return;
+
+    const drivers = getActiveDrivers?.() || {};
+    const roverId = Object.keys(drivers).find((id) => drivers[id] === targetSocket.id) || null;
+    if (!roverId) return;
+
+    if (cooldowns.consume(`bonk:sound:${roverId}`, BONK_SOUND_ROVER_COOLDOWN_MS) > 0) return;
+
+    publishEvent({
+      source: 'funCommands',
+      type: 'fun.bonked',
+      payload: { roverId, targetLabel, actor: actorLabelText },
+    });
+  }
+
+  function reply(message, content) {
+    return message.reply({ content: safe(content), allowedMentions: PLAIN_MENTIONS });
+  }
+
+  /*
+    Every fun command runs through one gate so the cooldown, the actor identity,
+    and the "who am I talking about" resolution cannot drift apart between
+    commands. `needsTarget` commands reply with their own usage line when the
+    selector is missing rather than silently acting on nothing.
+  */
+  function gate(message, action, { windowMs = TEXT_COOLDOWN_MS } = {}) {
+    const actorKey = buildActorKey(message);
+    if (!actorKey) return { error: 'Could not identify you well enough to do that.' };
+    const wait = cooldowns.consume(`${action}:${actorKey}`, windowMs);
+    if (wait > 0) return { error: `Slow down — try \`${commandPrefix} ${action}\` again in ${describeWait(wait)}.` };
+    return { actorKey, label: actorLabel(message) };
+  }
+
+  function target(selector) {
+    return resolveFunTarget({ io, getNickname, selector });
+  }
+
+  /*
+    Shared shape for the three "do a thing to someone" commands. Only the verb,
+    the counter names, and the flavour text differ, and keeping them in one place
+    means a fix to self-targeting or tally credit applies to all of them.
+  */
+  function createInteraction({ action, counterGiven, counterTaken, selfReply, render, onApplied }) {
+    return async function handleInteraction(message, tokens = []) {
+      const selector = tokens.join(' ').trim();
+      if (!selector) {
+        return reply(message, `Usage: \`${commandPrefix} ${action} <user>\``);
+      }
+
+      const gated = gate(message, action);
+      if (gated.error) return reply(message, gated.error);
+
+      const resolved = target(selector);
+      if (!resolved) return reply(message, `Usage: \`${commandPrefix} ${action} <user>\``);
+
+      if (resolved.actorKey && resolved.actorKey === gated.actorKey) {
+        return reply(message, selfReply(gated.label));
+      }
+
+      funStatsService.bumpActorStats(gated.actorKey, { label: gated.label, [counterGiven]: 1 });
+      const targetStats = resolved.actorKey
+        ? funStatsService.bumpActorStats(resolved.actorKey, { label: resolved.label, [counterTaken]: 1 })
+        : null;
+
+      // Side effects run after the tallies so a failure in an optional extra (the
+      // bonk sound) cannot cost the user their recorded bonk.
+      onApplied?.({ actor: gated.label, resolved });
+
+      return reply(message, render({
+        actor: gated.label,
+        actorKey: gated.actorKey,
+        targetLabel: resolved.label,
+        targetOnline: resolved.online,
+        takenCount: targetStats ? targetStats[counterTaken] : null,
+      }));
+    };
+  }
+
+  const handleBonk = createInteraction({
+    action: 'bonk',
+    counterGiven: 'bonksGiven',
+    counterTaken: 'bonksTaken',
+    selfReply: (label) => `${label} bonked themselves. That is between you and the rover.`,
+    onApplied: ({ actor, resolved }) => announceBonk(resolved.socket, resolved.label, actor),
+    render: ({ targetLabel, takenCount }) => {
+      const tally = takenCount ? ` That is their ${ordinal(takenCount)} bonk.` : '';
+      return `🔨 Bonked ${targetLabel}.${tally}`;
+    },
+  });
+
+  const handleHug = createInteraction({
+    action: 'hug',
+    counterGiven: 'hugsGiven',
+    counterTaken: 'hugsTaken',
+    selfReply: (label) => `${label} hugged themselves. Genuinely fine. No notes.`,
+    render: ({ actor, targetLabel, takenCount }) => {
+      const flavour = pickBySeed(HUG_FLAVOURS, hashSeed(`${actor}:${targetLabel}:${takenCount || 0}`));
+      const tally = takenCount ? ` (${takenCount} total)` : '';
+      return `🫂 ${actor} hugs ${targetLabel} ${flavour}.${tally}`;
+    },
+  });
+
+  const handleSlap = createInteraction({
+    action: 'slap',
+    counterGiven: 'slapsGiven',
+    counterTaken: 'slapsTaken',
+    selfReply: (label) => `${label} slapped themselves with a large trout. Bold.`,
+    render: ({ actor, targetLabel, takenCount }) => {
+      // Seeding on the running count means the weapon changes every time without
+      // being unpredictable for the same repeat number.
+      const item = pickBySeed(SLAP_ITEMS, hashSeed(`${actor}:${targetLabel}:${takenCount || 0}`));
+      return `🐟 ${actor} slaps ${targetLabel} around a bit with ${item}.`;
+    },
+  });
+
+  async function handleEightBall(message, tokens = []) {
+    const question = clampEcho(tokens.join(' '));
+    if (!question) return reply(message, `Usage: \`${commandPrefix} 8ball <question>\``);
+
+    const gated = gate(message, '8ball');
+    if (gated.error) return reply(message, gated.error);
+
+    const answer = pickBySeed(EIGHT_BALL_ANSWERS, hashSeed(question));
+    return reply(message, `🎱 ${question}\n${answer}`);
+  }
+
+  async function handleRoll(message, tokens = []) {
+    const gated = gate(message, 'roll');
+    if (gated.error) return reply(message, gated.error);
+
+    const spec = parseDiceSpec(tokens.join(''));
+    if (spec.error) return reply(message, spec.error);
+
+    const { rolls, total } = rollDice(spec.count, spec.sides);
+    const detail = rolls.length > 1 ? ` (${rolls.join(' + ')})` : '';
+    return reply(message, `🎲 ${gated.label} rolled ${spec.count}d${spec.sides}: **${total}**${detail}`);
+  }
+
+  async function handleCoin(message) {
+    const gated = gate(message, 'coin');
+    if (gated.error) return reply(message, gated.error);
+    const side = Math.random() < 0.5 ? 'Heads' : 'Tails';
+    return reply(message, `🪙 ${side}.`);
+  }
+
+  async function handleShip(message, tokens = []) {
+    const parts = tokens.join(' ').split(/\s+(?:and|\+|&)\s+|\s*,\s*/i).map((part) => clampEcho(part)).filter(Boolean);
+    const [left, right] = parts.length >= 2 ? parts : [parts[0], null];
+    if (!left || !right) {
+      return reply(message, `Usage: \`${commandPrefix} ship <a> and <b>\``);
+    }
+
+    const gated = gate(message, 'ship');
+    if (gated.error) return reply(message, gated.error);
+
+    const score = percentFromSeed(pairSeed(left, right));
+    const verdict = score >= 90 ? 'Get them a shared charging dock.'
+      : score >= 65 ? 'Promising.'
+        : score >= 35 ? 'Needs work.'
+          : score >= 10 ? 'The sensors are not hopeful.'
+            : 'Absolutely not.';
+    return reply(message, `💞 ${left} + ${right} = **${score}%**. ${verdict}`);
+  }
+
+  async function handleRate(message, tokens = []) {
+    const thing = clampEcho(tokens.join(' '));
+    if (!thing) return reply(message, `Usage: \`${commandPrefix} rate <thing>\``);
+
+    const gated = gate(message, 'rate');
+    if (gated.error) return reply(message, gated.error);
+
+    const seed = hashSeed(thing);
+    const score = seed % 11;
+    const suffix = pickBySeed(RATE_SUFFIXES, seed);
+    return reply(message, `📊 I rate ${thing} **${score}/10**. ${suffix}`);
+  }
+
+  async function handleUwu(message, tokens = []) {
+    const text = clampEcho(tokens.join(' '));
+    if (!text) return reply(message, `Usage: \`${commandPrefix} uwu <text>\``);
+
+    const gated = gate(message, 'uwu');
+    if (gated.error) return reply(message, gated.error);
+
+    return reply(message, uwuify(text));
+  }
+
+  async function handleWanted(message, tokens = []) {
+    const selector = tokens.join(' ').trim();
+    if (!selector) return reply(message, `Usage: \`${commandPrefix} wanted <user>\``);
+
+    const gated = gate(message, 'wanted');
+    if (gated.error) return reply(message, gated.error);
+
+    const resolved = target(selector);
+    if (!resolved) return reply(message, `Usage: \`${commandPrefix} wanted <user>\``);
+
+    const seed = hashSeed(resolved.label);
+    const crime = pickBySeed(WANTED_CRIMES, seed);
+    // Bounty is seeded so a given name always carries the same price. Somebody
+    // being permanently worth 12 credits is funnier than a fresh number each time.
+    const bounty = 25 + (seed % 4776);
+    const stats = resolved.actorKey ? funStatsService.getActorStats(resolved.actorKey) : null;
+    const priors = stats && stats.bonksTaken ? `\nPrior bonks on record: ${stats.bonksTaken}.` : '';
+    return reply(message, [
+      '```',
+      '        WANTED',
+      `  ${resolved.label}`,
+      `  for ${crime}`,
+      `  reward: ${bounty} credits`,
+      '```',
+    ].join('\n') + priors);
+  }
+
+  return {
+    bonk: handleBonk,
+    hug: handleHug,
+    slap: handleSlap,
+    '8ball': handleEightBall,
+    roll: handleRoll,
+    coin: handleCoin,
+    ship: handleShip,
+    rate: handleRate,
+    uwu: handleUwu,
+    wanted: handleWanted,
+  };
+}
+
+module.exports = {
+  createFunTextCommands,
+  // Exported for tests: the parsing and transform rules are the parts most
+  // likely to regress, and they are pure.
+  parseDiceSpec,
+  uwuify,
+};

server/src/services/operatorCommandService/commands/funText.test.js

@@ -0,0 +1,304 @@
+// Operator Fun Text Command Tests
+// Purpose: Verifies tally credit, self-targeting, cooldown refusal, mention sanitizing, and dice parsing.
+// Scope: Uses an in-memory stats double so no test touches the fun stats file.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createFunTextCommands, parseDiceSpec, uwuify } = require('./funText');
+const { createCooldownGate } = require('../cooldowns');
+
+function createStatsDouble() {
+  const store = new Map();
+  return {
+    calls: [],
+    bumpActorStats(actorKey, { label = null, ...patch } = {}) {
+      this.calls.push({ actorKey, label, patch });
+      const current = store.get(actorKey) || {};
+      const next = { ...current, label: label || current.label };
+      Object.keys(patch).forEach((key) => {
+        next[key] = (Number(current[key]) || 0) + Number(patch[key] || 0);
+      });
+      store.set(actorKey, next);
+      return next;
+    },
+    getActorStats(actorKey) {
+      return store.get(actorKey) || {};
+    },
+    listActorStats() {
+      return Array.from(store.entries()).map(([actorKey, value]) => ({ actorKey, ...value }));
+    },
+  };
+}
+
+function createHarness({ sockets = [], activeDrivers = {} } = {}) {
+  const stats = createStatsDouble();
+  const events = [];
+  const handlers = createFunTextCommands({
+    io: { sockets: { sockets: new Map(sockets.map((entry) => [entry.id, entry])) } },
+    getNickname: (entry) => entry?.data?.nickname || '',
+    getActiveDrivers: () => activeDrivers,
+    publishEvent: (event) => events.push(event),
+    // Matches the real sanitizer so tests exercise the actual escaping rules.
+    sanitizeMentions: (text) => String(text || '')
+      .replace(/<(@[!&]?\d+|#\d+)>/g, '[ping removed]')
+      .replace(/@everyone/gi, '[everyone]')
+      .replace(/@here/gi, '[here]'),
+    funStatsService: stats,
+    cooldowns: createCooldownGate(),
+    config: { commands: { prefix: 'rs' } },
+  });
+  return { handlers, stats, events };
+}
+
+function message(actor = { id: 's1', userId: 'u-alice', label: 'alice' }) {
+  const replies = [];
+  return {
+    transport: 'web-chat',
+    actor,
+    replies,
+    reply: async (payload) => {
+      replies.push(payload);
+      return null;
+    },
+  };
+}
+
+const bob = { id: 's2', data: { userId: 'u-bob', nickname: 'bob' } };
+
+test('bonk credits both sides and reports the running tally', async () => {
+  const { handlers, stats } = createHarness({ sockets: [bob] });
+  const msg = message();
+  await handlers.bonk(msg, ['bob']);
+
+  assert.match(msg.replies[0].content, /Bonked bob\./);
+  assert.match(msg.replies[0].content, /1st bonk/);
+  assert.deepEqual(
+    stats.calls.map((call) => [call.actorKey, Object.keys(call.patch)[0]]),
+    [['user:u-alice', 'bonksGiven'], ['user:u-bob', 'bonksTaken']],
+  );
+});
+
+test('the tally ordinal advances across repeat bonks', async () => {
+  const { handlers } = createHarness({ sockets: [bob] });
+  await handlers.bonk(message(), ['bob']);
+  // A second actor avoids the first actor's cooldown while still hitting bob.
+  const second = message({ id: 's3', userId: 'u-carol', label: 'carol' });
+  await handlers.bonk(second, ['bob']);
+  assert.match(second.replies[0].content, /2nd bonk/);
+});
+
+test('bonking an offline name still replies but credits nobody', async () => {
+  const { handlers, stats } = createHarness({ sockets: [bob] });
+  const msg = message();
+  await handlers.bonk(msg, ['the', 'dishwasher']);
+
+  assert.match(msg.replies[0].content, /Bonked the dishwasher\./);
+  assert.doesNotMatch(msg.replies[0].content, /bonk\b.*\dst|\dnd|\drd|\dth/);
+  assert.deepEqual(stats.calls.map((call) => call.actorKey), ['user:u-alice']);
+});
+
+test('self-bonking is a special case and records nothing', async () => {
+  const alice = { id: 's1', data: { userId: 'u-alice', nickname: 'alice' } };
+  const { handlers, stats } = createHarness({ sockets: [alice] });
+  const msg = message();
+  await handlers.bonk(msg, ['alice']);
+
+  assert.match(msg.replies[0].content, /themselves/);
+  assert.equal(stats.calls.length, 0);
+});
+
+test('a repeat inside the cooldown window is refused and records nothing extra', async () => {
+  const { handlers, stats } = createHarness({ sockets: [bob] });
+  await handlers.bonk(message(), ['bob']);
+  const countAfterFirst = stats.calls.length;
+
+  const second = message();
+  await handlers.bonk(second, ['bob']);
+  assert.match(second.replies[0].content, /Slow down/);
+  assert.equal(stats.calls.length, countAfterFirst);
+});
+
+test('cooldowns are per command, so a bonk does not block a hug', async () => {
+  const { handlers } = createHarness({ sockets: [bob] });
+  await handlers.bonk(message(), ['bob']);
+  const hug = message();
+  await handlers.hug(hug, ['bob']);
+  assert.doesNotMatch(hug.replies[0].content, /Slow down/);
+});
+
+test('a missing target replies with usage and does not burn the cooldown', async () => {
+  const { handlers } = createHarness({ sockets: [bob] });
+  const first = message();
+  await handlers.bonk(first, []);
+  assert.match(first.replies[0].content, /Usage: `rs bonk <user>`/);
+
+  const second = message();
+  await handlers.bonk(second, ['bob']);
+  assert.match(second.replies[0].content, /Bonked bob/);
+});
+
+test('every reply is sanitized so a fun command cannot ping a whole guild', async () => {
+  const { handlers } = createHarness();
+  const msg = message();
+  await handlers.bonk(msg, ['@everyone']);
+  assert.doesNotMatch(msg.replies[0].content, /@everyone/);
+  assert.match(msg.replies[0].content, /\[everyone\]/);
+
+  const roleMsg = message({ id: 's9', userId: 'u-dave', label: 'dave' });
+  await handlers.slap(roleMsg, ['<@&123456>']);
+  assert.match(roleMsg.replies[0].content, /\[ping removed\]/);
+});
+
+test('an actor with no identity at all is refused rather than sharing a tally', async () => {
+  const { handlers, stats } = createHarness({ sockets: [bob] });
+  const msg = message({ label: 'ghost' });
+  await handlers.bonk(msg, ['bob']);
+  assert.match(msg.replies[0].content, /Could not identify you/);
+  assert.equal(stats.calls.length, 0);
+});
+
+test('ship agrees with itself regardless of argument order', async () => {
+  const { handlers } = createHarness();
+  const forward = message();
+  await handlers.ship(forward, ['alice', 'and', 'bob']);
+
+  const { handlers: other } = createHarness();
+  const backward = message();
+  await other.ship(backward, ['bob', 'and', 'alice']);
+
+  const score = (text) => /\*\*(\d+)%\*\*/.exec(text)[1];
+  assert.equal(score(forward.replies[0].content), score(backward.replies[0].content));
+});
+
+test('ship needs two sides', async () => {
+  const { handlers } = createHarness();
+  const msg = message();
+  await handlers.ship(msg, ['alice']);
+  assert.match(msg.replies[0].content, /Usage: `rs ship/);
+});
+
+test('8ball gives the same answer to the same question', async () => {
+  const first = createHarness();
+  const a = message();
+  await first.handlers['8ball'](a, ['will', 'it', 'dock']);
+
+  const second = createHarness();
+  const b = message();
+  await second.handlers['8ball'](b, ['WILL', 'IT', 'DOCK']);
+
+  assert.equal(a.replies[0].content.split('\n')[1], b.replies[0].content.split('\n')[1]);
+});
+
+test('rate stays inside 0 to 10', async () => {
+  for (const thing of ['carpet', 'the dock', 'a', 'zzzzzz', 'rover 3']) {
+    const { handlers } = createHarness();
+    const msg = message();
+    await handlers.rate(msg, [thing]);
+    const score = Number(/\*\*(\d+)\/10\*\*/.exec(msg.replies[0].content)[1]);
+    assert.ok(score >= 0 && score <= 10, `${thing} scored ${score}`);
+  }
+});
+
+test('dice specs parse the accepted forms and reject the rest', () => {
+  assert.deepEqual(parseDiceSpec('2d6'), { count: 2, sides: 6 });
+  assert.deepEqual(parseDiceSpec('d20'), { count: 1, sides: 20 });
+  assert.deepEqual(parseDiceSpec(''), { count: 1, sides: 6 });
+  // A bare number is read as one die of that many sides.
+  assert.deepEqual(parseDiceSpec('20'), { count: 1, sides: 20 });
+  assert.match(parseDiceSpec('21d6').error, /between 1 and 20 dice/);
+  assert.match(parseDiceSpec('1d1').error, /2 and 1000 sides/);
+  assert.match(parseDiceSpec('1d2000').error, /2 and 1000 sides/);
+  assert.match(parseDiceSpec('banana').error, /NdN/);
+});
+
+test('roll totals stay within the possible range for the spec', async () => {
+  for (let attempt = 0; attempt < 25; attempt += 1) {
+    const { handlers } = createHarness();
+    const msg = message();
+    await handlers.roll(msg, ['3d6']);
+    const total = Number(/\*\*(\d+)\*\*/.exec(msg.replies[0].content)[1]);
+    assert.ok(total >= 3 && total <= 18, `rolled ${total}`);
+  }
+});
+
+test('uwu transforms text without dropping it', () => {
+  assert.equal(uwuify('hello world'), 'hewwo wowwd');
+  assert.equal(uwuify('love'), 'wuv');
+  assert.equal(uwuify('nice'), 'nyice');
+});
+
+test('bonking someone who is driving announces the sound for their rover', async () => {
+  const { handlers, events } = createHarness({ sockets: [bob], activeDrivers: { 'rover-1': 's2' } });
+  await handlers.bonk(message(), ['bob']);
+
+  assert.equal(events.length, 1);
+  assert.equal(events[0].type, 'fun.bonked');
+  assert.equal(events[0].payload.roverId, 'rover-1');
+  assert.equal(events[0].payload.targetLabel, 'bob');
+});
+
+test('bonking someone who is not driving announces nothing', async () => {
+  const { handlers, events } = createHarness({ sockets: [bob], activeDrivers: {} });
+  const msg = message();
+  await handlers.bonk(msg, ['bob']);
+
+  // The text bonk still lands and is still tallied; only the sound is skipped.
+  assert.match(msg.replies[0].content, /Bonked bob/);
+  assert.equal(events.length, 0);
+});
+
+test('bonking a name that is not a real user announces nothing', async () => {
+  const { handlers, events } = createHarness({ sockets: [bob], activeDrivers: { 'rover-1': 's2' } });
+  await handlers.bonk(message(), ['the dishwasher']);
+  assert.equal(events.length, 0);
+});
+
+test('the bonk sound is rate limited per rover so it cannot interrupt a mic repeatedly', async () => {
+  const { handlers, events } = createHarness({ sockets: [bob], activeDrivers: { 'rover-1': 's2' } });
+  await handlers.bonk(message(), ['bob']);
+  // A different actor has their own text cooldown but must not get a second sound.
+  await handlers.bonk(message({ id: 's3', userId: 'u-carol', label: 'carol' }), ['bob']);
+  await handlers.bonk(message({ id: 's4', userId: 'u-erin', label: 'erin' }), ['bob']);
+
+  assert.equal(events.length, 1);
+});
+
+test('a self-bonk never announces a sound', async () => {
+  const alice = { id: 's1', data: { userId: 'u-alice', nickname: 'alice' } };
+  const { handlers, events } = createHarness({ sockets: [alice], activeDrivers: { 'rover-1': 's1' } });
+  await handlers.bonk(message(), ['alice']);
+  assert.equal(events.length, 0);
+});
+
+test('hug and slap do not announce a bonk sound', async () => {
+  const { handlers, events } = createHarness({ sockets: [bob], activeDrivers: { 'rover-1': 's2' } });
+  await handlers.hug(message(), ['bob']);
+  await handlers.slap(message(), ['bob']);
+  assert.equal(events.length, 0);
+});
+
+test('a transport with no publishEvent still bonks normally', async () => {
+  const stats = createStatsDouble();
+  const handlers = createFunTextCommands({
+    io: { sockets: { sockets: new Map([[bob.id, bob]]) } },
+    getNickname: (entry) => entry?.data?.nickname || '',
+    getActiveDrivers: () => ({ 'rover-1': 's2' }),
+    publishEvent: undefined,
+    sanitizeMentions: (text) => String(text || ''),
+    funStatsService: stats,
+    cooldowns: createCooldownGate(),
+    config: { commands: { prefix: 'rs' } },
+  });
+  const msg = message();
+  await handlers.bonk(msg, ['bob']);
+  assert.match(msg.replies[0].content, /Bonked bob/);
+});
+
+test('wanted includes prior bonks when the target has any on record', async () => {
+  const { handlers } = createHarness({ sockets: [bob] });
+  await handlers.bonk(message(), ['bob']);
+
+  const msg = message({ id: 's4', userId: 'u-erin', label: 'erin' });
+  await handlers.wanted(msg, ['bob']);
+  assert.match(msg.replies[0].content, /WANTED/);
+  assert.match(msg.replies[0].content, /Prior bonks on record: 1/);
+});

server/src/services/operatorCommandService/commands/gain.js

@@ -0,0 +1,180 @@
+// Operator Gain Command
+// Purpose: Handles the audio gain boost permission for VIPs.
+// Scope: Supports list, grant, and revoke subcommands; resolution stays VIP-only.
+const { mask, normalizeSearchText, resolveIdentitySelector } = require('./resolvers');
+const { getCommandConfig } = require('../../operatorCommandService/config');
+
+/*
+  Every connected socket's canonical user id. One person can hold several sockets
+  across tabs, so this is a set of identities rather than a count of connections.
+*/
+function collectOnlineUserIds(io) {
+  const online = new Set();
+  const sockets = io?.sockets?.sockets;
+  if (!sockets || typeof sockets.forEach !== 'function') return online;
+  sockets.forEach((socket) => {
+    const userId = String(socket?.data?.userId || '').trim();
+    if (userId) online.add(userId);
+  });
+  return online;
+}
+
+/*
+  Candidates whose identity fields equal the selector outright. Nicknames are not
+  unique — the same person re-verifying from a new browser produces a second
+  verified record with the same name — so an exact nickname match can legitimately
+  return several records.
+*/
+function findExactMatches(selector, candidates) {
+  const needle = normalizeSearchText(selector);
+  if (!needle) return [];
+  return (Array.isArray(candidates) ? candidates : []).filter((record) => (
+    normalizeSearchText(record?.nickname) === needle
+    || normalizeSearchText(record?.userId) === needle
+    || normalizeSearchText(record?.id) === needle
+    || normalizeSearchText(record?.cookieUserId) === needle
+    || normalizeSearchText(record?.fingerprintId) === needle
+  ));
+}
+
+function createGainCommand({
+  io,
+  listVerifiedUsers,
+  listAudioGainBoostUsers,
+  grantAudioGainBoost,
+  revokeAudioGainBoost,
+  sanitizeMentions,
+  config,
+}) {
+  // Usage text comes from the same core prefix that both transports parse.
+  const { prefix: commandPrefix } = getCommandConfig(config);
+  const plain = { parse: [], repliedUser: false };
+
+  function usage(subcommand) {
+    return `Usage: \`${commandPrefix} gain ${subcommand} <nickname|userId|cookieUserId>\``;
+  }
+
+  /*
+    Duplicate nicknames used to make `gain grant <name>` unusable: the shared
+    resolver refuses on ambiguity, which is right for destructive commands like
+    deter and kick but wrong here. Granting a volume ceiling to the wrong one of
+    two accounts belonging to the same person is recoverable, so this command
+    picks one and says which.
+
+    The online account wins, because that is who the admin is reacting to. With
+    nobody online the first stored record is used. The shared fuzzy resolver still
+    handles the no-exact-match case so typo tolerance and its error text are
+    unchanged.
+  */
+  function resolveBoostTarget(selector, candidates) {
+    const exact = findExactMatches(selector, candidates);
+    if (exact.length === 1) return { record: exact[0] };
+
+    if (exact.length > 1) {
+      const onlineUserIds = collectOnlineUserIds(io);
+      const onlineMatches = exact.filter((record) => {
+        const userId = String(record?.userId || '').trim();
+        return userId && onlineUserIds.has(userId);
+      });
+      if (onlineMatches.length) {
+        return { record: onlineMatches[0], duplicates: exact.length, picked: 'online' };
+      }
+      return { record: exact[0], duplicates: exact.length, picked: 'first' };
+    }
+
+    return resolveIdentitySelector(selector, candidates, { includeId: false });
+  }
+
+  function describePick(resolved) {
+    if (!resolved.duplicates) return '';
+    if (resolved.picked === 'online') {
+      return ` ${resolved.duplicates} accounts share that name; picked the one that is online.`;
+    }
+    return ` ${resolved.duplicates} accounts share that name and none are online; picked the first.`;
+  }
+
+  function helpText() {
+    return [
+      '**Audio gain boost**',
+      'Raises a user\'s volume ceiling past the global gains, still bounded by the hard caps.',
+      '',
+      `\`${commandPrefix} gain list\` — show everyone who holds the boost.`,
+      `\`${commandPrefix} gain grant <vip>\` — give the boost to a verified user.`,
+      `\`${commandPrefix} gain revoke <vip>\` — take the boost away.`,
+      `\`${commandPrefix} gain help\` — show this.`,
+      '',
+      'A user can be named by nickname, userId, or cookieUserId. Only verified (VIP)',
+      'users can be granted the boost. If several accounts share a nickname, the one',
+      'that is currently online is used.',
+    ].join('\n');
+  }
+
+  /*
+    The boost is a VIP-only permission, so candidate matching runs against the
+    verified list rather than every known identity. A nickname that only belongs
+    to an unverified visitor therefore reports "not found" instead of resolving
+    to someone who cannot hold the flag anyway.
+  */
+  async function applyBoost(message, tokens, enabled) {
+    const selector = tokens.join(' ').trim();
+    if (!selector) {
+      return message.reply({ content: usage(enabled ? 'grant' : 'revoke'), allowedMentions: plain });
+    }
+    const candidates = enabled ? listVerifiedUsers() : listAudioGainBoostUsers();
+    const resolved = resolveBoostTarget(selector, candidates);
+    if (resolved.error) {
+      return message.reply({ content: sanitizeMentions(resolved.error), allowedMentions: plain });
+    }
+    const target = resolved.record.userId || resolved.record.id || resolved.record.cookieUserId;
+    try {
+      const actor = message.actor?.id || null;
+      const user = enabled ? grantAudioGainBoost(target, actor) : revokeAudioGainBoost(target, actor);
+      const verb = enabled ? 'Granted' : 'Revoked';
+      return message.reply({
+        content: sanitizeMentions(`${verb} audio gain boost for ${user.nickname || 'unknown'} (${mask(user.cookieUserId)}).${describePick(resolved)}`),
+        allowedMentions: plain,
+      });
+    } catch (err) {
+      return message.reply({
+        content: sanitizeMentions(`Failed to update audio gain boost: ${err.message}`),
+        allowedMentions: plain,
+      });
+    }
+  }
+
+  return async function handleGainCommand(message, tokens) {
+    if (!message.actor?.isAdmin) {
+      await message.reply({ content: 'Only admins can manage audio gain boosts.', allowedMentions: plain });
+      return;
+    }
+    const action = (tokens.shift() || 'list').toLowerCase();
+
+    if (action === 'help') {
+      return message.reply({ content: helpText(), allowedMentions: plain });
+    }
+
+    if (action === 'list') {
+      const users = listAudioGainBoostUsers();
+      if (!users.length) {
+        return message.reply({ content: 'No users hold an audio gain boost.', allowedMentions: plain });
+      }
+      const lines = users.map((entry, idx) => (
+        `${idx + 1}. ${entry.nickname || 'unknown'} | ${entry.userId || entry.id} | ${mask(entry.cookieUserId)}`
+      ));
+      return message.reply({
+        content: sanitizeMentions(['Audio gain boost holders:', ...lines].join('\n').slice(0, 1900)),
+        allowedMentions: plain,
+      });
+    }
+
+    if (action === 'grant') return applyBoost(message, tokens, true);
+    if (action === 'revoke') return applyBoost(message, tokens, false);
+
+    return message.reply({
+      content: `Unknown gain command.\n${helpText()}`,
+      allowedMentions: plain,
+    });
+  };
+}
+
+module.exports = { createGainCommand };

server/src/services/operatorCommandService/commands/gain.test.js

@@ -0,0 +1,258 @@
+// Operator Gain Command Tests
+// Purpose: Verifies the audio gain boost command stays admin-only and VIP-only.
+// Scope: Exercises command target resolution with in-memory identity doubles.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { createGainCommand } = require('./gain');
+
+const VIPS = [
+  { userId: 'usr-vip', nickname: 'Croissant', cookieUserId: 'cookie-croissant' },
+  { userId: 'usr-other', nickname: 'Baguette', cookieUserId: 'cookie-baguette' },
+];
+
+// Two verified records sharing one nickname. This is the real shape behind the
+// "matched multiple records" failure: one person re-verifying from a new browser
+// produces a second record with the same name and a different cookie id.
+const DUPLICATE_SAULS = [
+  { userId: 'usr-saul-a', nickname: 'Saul', cookieUserId: 'cu_a28ffffffff33ab5c' },
+  { userId: 'usr-saul-b', nickname: 'Saul', cookieUserId: 'cu_5a5ffffffffb6add3' },
+];
+
+function createSocketRegistry(onlineUserIds = []) {
+  const sockets = new Map();
+  onlineUserIds.forEach((userId, index) => {
+    // Two sockets per identity, so the resolver must dedupe rather than count
+    // connections.
+    sockets.set(`s${index}a`, { id: `s${index}a`, data: { userId } });
+    sockets.set(`s${index}b`, { id: `s${index}b`, data: { userId } });
+  });
+  return { sockets: { sockets } };
+}
+
+function createHarness({ verified = VIPS, boosted = [], isAdmin = true, online = [] } = {}) {
+  const calls = [];
+  const replies = [];
+  const handler = createGainCommand({
+    io: createSocketRegistry(online),
+    listVerifiedUsers: () => verified,
+    listAudioGainBoostUsers: () => boosted,
+    grantAudioGainBoost: (selector, actor) => {
+      calls.push({ action: 'grant', selector, actor });
+      return { nickname: 'Croissant', cookieUserId: 'cookie-croissant' };
+    },
+    revokeAudioGainBoost: (selector, actor) => {
+      calls.push({ action: 'revoke', selector, actor });
+      return { nickname: 'Croissant', cookieUserId: 'cookie-croissant' };
+    },
+    sanitizeMentions: (value) => value,
+    config: { commands: { prefix: 'rs' } },
+  });
+  const message = {
+    actor: { id: 'admin', isAdmin },
+    reply: async (payload) => {
+      replies.push(payload);
+      return payload;
+    },
+  };
+  return { handler, message, calls, replies };
+}
+
+test('non-admins cannot manage the boost', async () => {
+  const { handler, message, calls, replies } = createHarness({ isAdmin: false });
+
+  await handler(message, ['grant', 'Croissant']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /Only admins/);
+});
+
+test('grant resolves a VIP nickname to its stable user id', async () => {
+  const { handler, message, calls } = createHarness();
+
+  await handler(message, ['grant', 'croissant']);
+
+  assert.deepEqual(calls, [{ action: 'grant', selector: 'usr-vip', actor: 'admin' }]);
+});
+
+test('grant refuses a nickname that belongs to no VIP', async () => {
+  const { handler, message, calls, replies } = createHarness({ verified: [] });
+
+  await handler(message, ['grant', 'Stranger']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /not found/i);
+});
+
+test('revoke only matches users who currently hold the boost', async () => {
+  const { handler, message, calls, replies } = createHarness({ boosted: [] });
+
+  await handler(message, ['revoke', 'Croissant']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /not found/i);
+});
+
+test('revoke resolves against the boosted list', async () => {
+  const { handler, message, calls } = createHarness({ boosted: [VIPS[0]] });
+
+  await handler(message, ['revoke', 'Croissant']);
+
+  assert.deepEqual(calls, [{ action: 'revoke', selector: 'usr-vip', actor: 'admin' }]);
+});
+
+test('grant without a target prints usage instead of acting', async () => {
+  const { handler, message, calls, replies } = createHarness();
+
+  await handler(message, ['grant']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /rs gain grant/);
+});
+
+test('list defaults when no subcommand is given', async () => {
+  const { handler, message, replies } = createHarness({ boosted: [VIPS[0]] });
+
+  await handler(message, []);
+
+  assert.match(replies[0].content, /Croissant/);
+  assert.match(replies[0].content, /usr-vip/);
+});
+
+test('list reports an empty holder set', async () => {
+  const { handler, message, replies } = createHarness({ boosted: [] });
+
+  await handler(message, ['list']);
+
+  assert.match(replies[0].content, /No users hold/);
+});
+
+test('duplicate nicknames resolve to the account that is online', async () => {
+  const { handler, message, calls, replies } = createHarness({
+    verified: DUPLICATE_SAULS,
+    online: ['usr-saul-b'],
+  });
+
+  await handler(message, ['grant', 'Saul']);
+
+  assert.deepEqual(calls, [{ action: 'grant', selector: 'usr-saul-b', actor: 'admin' }]);
+  assert.doesNotMatch(replies[0].content, /matched multiple records/i);
+  assert.match(replies[0].content, /2 accounts share that name; picked the one that is online/);
+});
+
+test('duplicate nicknames fall back to the first record when nobody is online', async () => {
+  const { handler, message, calls, replies } = createHarness({
+    verified: DUPLICATE_SAULS,
+    online: [],
+  });
+
+  await handler(message, ['grant', 'Saul']);
+
+  assert.deepEqual(calls, [{ action: 'grant', selector: 'usr-saul-a', actor: 'admin' }]);
+  assert.match(replies[0].content, /none are online; picked the first/);
+});
+
+test('an unrelated online user does not influence the pick', async () => {
+  const { handler, message, calls } = createHarness({
+    verified: DUPLICATE_SAULS,
+    online: ['usr-somebody-else'],
+  });
+
+  await handler(message, ['grant', 'Saul']);
+
+  assert.deepEqual(calls, [{ action: 'grant', selector: 'usr-saul-a', actor: 'admin' }]);
+});
+
+test('several duplicates online pick one deterministically rather than refusing', async () => {
+  const { handler, message, calls, replies } = createHarness({
+    verified: DUPLICATE_SAULS,
+    online: ['usr-saul-a', 'usr-saul-b'],
+  });
+
+  await handler(message, ['grant', 'Saul']);
+
+  assert.deepEqual(calls, [{ action: 'grant', selector: 'usr-saul-a', actor: 'admin' }]);
+  assert.match(replies[0].content, /picked the one that is online/);
+});
+
+test('revoke disambiguates the same way against the boosted list', async () => {
+  const { handler, message, calls } = createHarness({
+    boosted: DUPLICATE_SAULS,
+    online: ['usr-saul-b'],
+  });
+
+  await handler(message, ['revoke', 'Saul']);
+
+  assert.deepEqual(calls, [{ action: 'revoke', selector: 'usr-saul-b', actor: 'admin' }]);
+});
+
+test('a unique nickname reports no disambiguation note', async () => {
+  const { handler, message, replies } = createHarness();
+
+  await handler(message, ['grant', 'Croissant']);
+
+  assert.doesNotMatch(replies[0].content, /accounts share that name/);
+});
+
+test('an exact cookieUserId still selects one record out of a duplicate pair', async () => {
+  const { handler, message, calls } = createHarness({ verified: DUPLICATE_SAULS });
+
+  await handler(message, ['grant', 'cu_5a5ffffffffb6add3']);
+
+  assert.deepEqual(calls, [{ action: 'grant', selector: 'usr-saul-b', actor: 'admin' }]);
+});
+
+test('a typo still resolves through the fuzzy matcher', async () => {
+  const { handler, message, calls } = createHarness();
+
+  await handler(message, ['grant', 'Croissnat']);
+
+  assert.deepEqual(calls, [{ action: 'grant', selector: 'usr-vip', actor: 'admin' }]);
+});
+
+test('help lists every subcommand', async () => {
+  const { handler, message, calls, replies } = createHarness();
+
+  await handler(message, ['help']);
+
+  assert.deepEqual(calls, [], 'help must not change anything');
+  for (const fragment of ['rs gain list', 'rs gain grant <vip>', 'rs gain revoke <vip>', 'rs gain help']) {
+    assert.ok(replies[0].content.includes(fragment), `help should mention ${fragment}`);
+  }
+});
+
+test('an unknown subcommand falls back to the same help text', async () => {
+  const { handler, message, calls, replies } = createHarness();
+
+  await handler(message, ['sideways']);
+
+  assert.deepEqual(calls, []);
+  assert.match(replies[0].content, /Unknown gain command/);
+  assert.ok(replies[0].content.includes('rs gain grant <vip>'));
+});
+
+test('help stays admin-only like the rest of the command', async () => {
+  const { handler, message, replies } = createHarness({ isAdmin: false });
+
+  await handler(message, ['help']);
+
+  assert.match(replies[0].content, /Only admins/);
+});
+
+test('a service rejection is surfaced instead of thrown', async () => {
+  const { handler, message, replies } = createHarness();
+  const failing = createGainCommand({
+    io: createSocketRegistry([]),
+    listVerifiedUsers: () => VIPS,
+    listAudioGainBoostUsers: () => [],
+    grantAudioGainBoost: () => {
+      throw new Error('Only verified VIPs can be granted an audio gain boost.');
+    },
+    revokeAudioGainBoost: () => null,
+    sanitizeMentions: (value) => value,
+    config: { commands: { prefix: 'rs' } },
+  });
+
+  await failing(message, ['grant', 'Croissant']);
+
+  assert.match(replies[0].content, /Only verified VIPs/);
+});

server/src/services/operatorCommandService/commands/lights.js

@@ -33,6 +33,34 @@ function createLightsCommand({ homeAssistantService, sanitizeMentions, config })
       return;
     }
 
+    const isAdmin = Boolean(message.actor?.isAdmin);
+    const adminActions = new Set(['status', 'lock', 'unlock']);
+
+    // The lights namespace intentionally contains both public feature actions
+    // and room-policy actions. The shared dispatcher applies the current server
+    // mode to the feature as a whole; this focused check preserves the stronger
+    // historical permission on status/lock/unlock without making on/off/colors
+    // admin-only during normal open or turns operation.
+    if (adminActions.has(action) && !isAdmin) {
+      await message.reply({
+        content: 'Only admins can manage the room-light lock.',
+        allowedMentions: { parse: [], repliedUser: false },
+      });
+      return;
+    }
+
+    // An active lock is a policy boundary for ordinary feature commands. Admin
+    // lock management remains available, but public scene commands must not
+    // silently defeat a locked-on or locked-off room state.
+    const lightPolicy = homeAssistantService.getLightPolicyState?.() || {};
+    if ((action === 'on' || action === 'off' || action === 'colors') && lightPolicy.locked) {
+      await message.reply({
+        content: describeLightPolicy(lightPolicy),
+        allowedMentions: { parse: [], repliedUser: false },
+      });
+      return;
+    }
+
     if (action === 'status') {
       await message.reply({
         content: describeLightPolicy(homeAssistantService.getLightPolicyState?.() || {}),
@@ -41,9 +69,35 @@ function createLightsCommand({ homeAssistantService, sanitizeMentions, config })
       return;
     }
 
+    if (action === 'on' || action === 'off' || action === 'colors') {
+      try {
+        const result = action === 'colors'
+          ? await homeAssistantService.setRandomColorScene({ source: 'bot-command:lights:colors' })
+          : await homeAssistantService.setAllControllableEntitiesState(action, {
+            source: `bot-command:lights:${action}`,
+          });
+        const failed = result?.failures?.length || 0;
+        const succeeded = result?.succeeded?.length || 0;
+        const description = action === 'colors'
+          ? `Applied random colors to ${result?.colorLights || 0} RGB lights and requested off for ${result?.nonColorEntities || 0} non-RGB lights.`
+          : `Turned ${action} ${succeeded} room lights.`;
+        const failureSuffix = failed ? ` ${failed} failed.` : '';
+        await message.reply({
+          content: sanitizeMentions(`${description}${failureSuffix}`),
+          allowedMentions: { parse: [], repliedUser: false },
+        });
+      } catch (err) {
+        await message.reply({
+          content: sanitizeMentions(`Failed to update room lights: ${err.message}`),
+          allowedMentions: { parse: [], repliedUser: false },
+        });
+      }
+      return;
+    }
+
     if (action !== 'lock' && action !== 'unlock') {
       await message.reply({
-        content: `Invalid lights command. Use \`${commandPrefix} lights lock\`, \`${commandPrefix} lights unlock\`, or \`${commandPrefix} lights status\`.`,
+        content: `Invalid lights command. Use \`${commandPrefix} lights on\`, \`${commandPrefix} lights off\`, \`${commandPrefix} lights colors\`, \`${commandPrefix} lights lock\`, \`${commandPrefix} lights unlock\`, or \`${commandPrefix} lights status\`.`,
         allowedMentions: { parse: [], repliedUser: false },
       });
       return;

server/src/services/operatorCommandService/commands/resolvers.js

@@ -146,7 +146,7 @@ function resolveIdentitySelector(selector, records = [], options = {}) {
     ],
   });
   const results = fuse.search(query);
-  if (!results.length) return { error: buildResultError('not_found', 'Selector', candidates) };
+  if (!results.length) return { error: buildResultError('not_found', 'User', candidates) };
 
   const first = results[0];
   const second = results[1];

server/src/services/operatorCommandService/cooldowns.js

@@ -0,0 +1,70 @@
+// Operator Command Cooldowns
+// Purpose: Rate limits individual commands per actor without coupling to a transport.
+// Scope: In-memory only; a restart clears every cooldown by design.
+const DEFAULT_SWEEP_INTERVAL_MS = 60 * 1000;
+
+/*
+  Fun commands are reachable from both site chat and Discord, and site chat's own
+  rate limit only bounds messages per socket rather than a specific command. A
+  per-actor, per-command gate is what stops one person turning `rs honk` into a
+  siren, and it is deliberately in-memory: a cooldown that survives a restart
+  would be a moderation feature, not a spam guard.
+*/
+function createCooldownGate({ sweepIntervalMs = DEFAULT_SWEEP_INTERVAL_MS } = {}) {
+  const expiries = new Map();
+  let lastSweep = 0;
+
+  function sweep(now) {
+    if (now - lastSweep < sweepIntervalMs) return;
+    lastSweep = now;
+    expiries.forEach((expiresAt, key) => {
+      if (expiresAt <= now) expiries.delete(key);
+    });
+  }
+
+  function remaining(key, now = Date.now()) {
+    const expiresAt = expiries.get(String(key));
+    if (!expiresAt) return 0;
+    return Math.max(0, expiresAt - now);
+  }
+
+  /*
+    Returns the remaining wait when the gate is closed, or 0 after arming the
+    next window. Callers therefore treat any non-zero result as a refusal, and a
+    refused call never extends the existing window.
+  */
+  function consume(key, windowMs, now = Date.now()) {
+    const normalizedKey = String(key || '').trim();
+    if (!normalizedKey) return 0;
+    const window = Number(windowMs);
+    if (!Number.isFinite(window) || window <= 0) return 0;
+
+    sweep(now);
+    const wait = remaining(normalizedKey, now);
+    if (wait > 0) return wait;
+    expiries.set(normalizedKey, now + window);
+    return 0;
+  }
+
+  function clear(key) {
+    expiries.delete(String(key || '').trim());
+  }
+
+  function reset() {
+    expiries.clear();
+    lastSweep = 0;
+  }
+
+  return { consume, remaining, clear, reset };
+}
+
+function describeWait(waitMs) {
+  const seconds = Math.ceil(Number(waitMs || 0) / 1000);
+  if (seconds <= 1) return '1s';
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds % 60;
+  return rest ? `${minutes}m ${rest}s` : `${minutes}m`;
+}
+
+module.exports = { createCooldownGate, describeWait };