fix: log WebUI shutdown diagnostics

Author: ai-ag2026

CHANGELOG.md

@@ -3,6 +3,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- WebUI now logs structured shutdown diagnostics when the server exits or `/api/shutdown` is called, including active stream IDs to help diagnose interrupted turns after restarts.
+
 ## [v0.51.157] — 2026-05-28 — Release EC (stage-batch39 — 5-PR mixed-risk cleanup: gateway prefill forward + prefill budget + compressed-continuation sidebar + browser-transcript memory guidance + reasoning max parity)
 
 ### Added

api/routes.py

@@ -3854,6 +3854,18 @@ def _serve_shell_unavailable(handler, exc: Exception) -> bool:
 
 def _handle_shutdown(handler) -> bool:
     """Shut down the WebUI server process."""
+    headers = getattr(handler, "headers", {})
+    ua = headers.get("User-Agent", "no-ua") if hasattr(headers, "get") else "no-ua"
+    remote = "unknown"
+    if getattr(handler, "client_address", None):
+        remote = handler.client_address[0]
+    logger.info(
+        "[shutdown-request] remote=%s method=%s path=%s ua=%s",
+        remote,
+        getattr(handler, "command", "unknown"),
+        getattr(handler, "path", "unknown"),
+        ua,
+    )
     j(handler, {"status": "shutting_down"})
     import signal
     import threading

server.py

@@ -8,6 +8,7 @@
 import re
 import socket
 import sys
+import threading
 import time
 import traceback
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -403,6 +404,37 @@ def _raise_fd_soft_limit(target: int = 4096) -> dict:
     return {"status": "raised", "soft": desired, "hard": hard, "previous_soft": soft}
 
 
+_SHUTDOWN_AUDIT_LOGGED = False
+
+
+def _log_shutdown_audit(reason: str = "serve_forever_exit") -> None:
+    """Log runtime context when the WebUI server is exiting."""
+    global _SHUTDOWN_AUDIT_LOGGED
+    if _SHUTDOWN_AUDIT_LOGGED:
+        return
+    _SHUTDOWN_AUDIT_LOGGED = True
+
+    active_sessions = []
+    try:
+        from api.models import SESSIONS
+        for sid, session in SESSIONS.items():
+            stream_id = getattr(session, "active_stream_id", None)
+            if stream_id:
+                pending = bool(getattr(session, "pending_user_message", None))
+                active_sessions.append(f"sid={sid} stream={stream_id} pending={pending}")
+    except Exception:
+        logger.debug("Failed to collect active-session shutdown audit state", exc_info=True)
+
+    logger.info(
+        "[shutdown-audit] reason=%s pid=%s thread=%s(%s) active_sessions=[%s]",
+        reason,
+        os.getpid(),
+        threading.current_thread().name,
+        threading.current_thread().ident,
+        "; ".join(active_sessions) if active_sessions else "none",
+    )
+
+
 def main() -> None:
     from api.config import print_startup_config, verify_hermes_imports, _HERMES_FOUND
 
@@ -516,6 +548,7 @@ def main() -> None:
     try:
         httpd.serve_forever()
     finally:
+        _log_shutdown_audit()
         # Stop the gateway watcher on shutdown
         try:
             from api.gateway_watcher import stop_watcher

tests/test_shutdown_audit_logging.py

@@ -0,0 +1,67 @@
+import logging
+import types
+import threading
+
+
+def test_server_shutdown_audit_logs_active_stream_context(monkeypatch, caplog):
+    import server
+    from api import models
+
+    monkeypatch.setattr(server, "_SHUTDOWN_AUDIT_LOGGED", False)
+    monkeypatch.setitem(
+        models.SESSIONS,
+        "session-1",
+        types.SimpleNamespace(active_stream_id="stream-1", pending_user_message="hello"),
+    )
+    monkeypatch.setitem(
+        models.SESSIONS,
+        "session-2",
+        types.SimpleNamespace(active_stream_id=None, pending_user_message=None),
+    )
+
+    caplog.set_level(logging.INFO, logger="server")
+    server._log_shutdown_audit(reason="test-exit")
+
+    logged = "\n".join(record.getMessage() for record in caplog.records)
+    assert "[shutdown-audit]" in logged
+    assert "reason=test-exit" in logged
+    assert "sid=session-1 stream=stream-1 pending=True" in logged
+    assert "session-2" not in logged
+
+
+def test_shutdown_route_logs_request_context_without_starting_real_shutdown(monkeypatch, caplog):
+    from api import routes
+
+    responses = []
+    monkeypatch.setattr(routes, "j", lambda handler, payload, **kw: responses.append(payload) or True)
+
+    started_threads = []
+
+    class FakeThread:
+        def __init__(self, target, daemon=False):
+            self.target = target
+            self.daemon = daemon
+
+        def start(self):
+            started_threads.append((self.target, self.daemon))
+
+    monkeypatch.setattr(threading, "Thread", FakeThread)
+
+    handler = types.SimpleNamespace(
+        client_address=("127.0.0.1", 12345),
+        command="POST",
+        path="/api/shutdown",
+        headers={"User-Agent": "pytest-agent"},
+    )
+
+    caplog.set_level(logging.INFO, logger="api.routes")
+    assert routes._handle_shutdown(handler) is True
+
+    logged = "\n".join(record.getMessage() for record in caplog.records)
+    assert "[shutdown-request]" in logged
+    assert "remote=127.0.0.1" in logged
+    assert "method=POST" in logged
+    assert "path=/api/shutdown" in logged
+    assert "ua=pytest-agent" in logged
+    assert responses == [{"status": "shutting_down"}]
+    assert started_threads and started_threads[0][1] is True