Keep socket listener active during deployment

docs/setup.md

@@ -169,6 +169,13 @@ systemctl daemon-reload
 systemctl restart uce.service
 ```
 
+When `uce.socket` is active, restart only `uce.service` (or use
+`scripts/systemd/manage-uce-service.sh restart`). The socket unit must retain
+ownership of the FastCGI listener while workers change. Restarting
+`uce.socket` alongside the service removes that listener briefly and can expose
+HTTP 502 responses through nginx. Restart the socket unit only to repair the
+socket itself, with an explicit outage window.
+
 ## Runtime configuration
 
 Create `/etc/uce/settings.cfg` from `etc/uce/settings.cfg` and adjust paths to your checkout root. Replace checkout-specific settings such as `WASM_CORE_PATH` with `<UCE_REPO_ROOT>/bin/wasm/core.wasm` or leave it relative to `COMPILER_SYS_PATH` as appropriate.

docs/wasm-runtime-architecture.md

@@ -192,6 +192,9 @@ the service and its post-fork workers restart. Direct launches without systemd
 activation retain the existing configured Unix/TCP listener behavior.
 The service preserves its runtime directory across service restarts because the
 socket unit, not the service unit, owns a listener path inside that directory.
+Normal deployments therefore restart only `uce.service`; restarting
+`uce.socket` at the same time removes the listener and forfeits the zero-gap
+handoff.
 On termination the parent asks render workers to close their listeners, finish
 accepted connections within the bounded worker drain interval, and only then
 exits. This prevents an accepted FastCGI request from being reset at handoff;

scripts/test_socket_activation.sh

@@ -24,6 +24,9 @@ inode_before=$(stat -c %i "$socket_path")
 load_pid=$!
 sleep 0.05
 systemctl restart "$service_name"
+systemctl is-active --quiet "$socket_name"
+inode_during=$(stat -c %i "$socket_path")
+[[ "$inode_during" = "$inode_before" ]]
 wait "$load_pid"
 
 inode_after=$(stat -c %i "$socket_path")