fix alerts reconnect backoff and clipboard availability checks

refactor terminal page into renderer, catalog, and session hooks
also bump beta cuz why not
2026-10-01 14:55:26 +07:00 · 2026-10-01 14:26:50 +07:00 · 2026-10-01 11:33:06 +07:00 · 2026-10-01 11:32:26 +07:00 · 2026-10-01 10:59:36 +07:00 · 2026-09-11 05:39:43 +07:00
54 changed files with 2856 additions and 1138 deletions
@@ -1 +1,10 @@
-SQLX_OFFLINE=true
+# Live mode (local dev): query! macros validate every query against the real
+# schema on each build, so the .sqlx cache is only needed for DB-less builds.
+# Run scripts/prepare_sqlx_sqlite.sh once first — it creates and migrates the DB.
+# Use an absolute path so builds work from any working directory.
+# Replace the placeholder below with the DATABASE_URL printed by the script.
+DATABASE_URL=sqlite:///absolute/path/to/wakey-prepare.sqlite3
+
+# Offline mode (CI / packaging): force the committed .sqlx cache.
+# Takes precedence over DATABASE_URL when set.
+#SQLX_OFFLINE=true
@@ -20,3 +20,6 @@ target/
 .env

 .codex
+
+# sqlx prepare DB (created by scripts/prepare_sqlx_sqlite.sh)
+wakey-prepare.sqlite3*
@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO audit_events\n             (event_key, event_id, ts_unix, actor_type, actor_id, agent_id, request_id,\n              event_type, outcome, latency_ms, message, metadata_json)\n             VALUES (?1, ?2, ?3, 'test', NULL, NULL, NULL, 'test', 'ok', NULL, 'old', '{}')",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "6ce45cc94cbfdd948aad5fb986f9b5976c79bb63759bc9ecff1a7873e2d70137"
+}
@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT COUNT(*) FROM alert_transitions WHERE transition_id = ?1",
+  "describe": {
+    "columns": [
+      {
+        "name": "COUNT(*)",
+        "ordinal": 0,
+        "type_info": "Integer"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "b324587b94ee2e98dc8eff5f6735303a2784b74f49068ce8e946cedcd8d12c4e"
+}
@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT COUNT(*) FROM audit_events WHERE message = ?1",
+  "describe": {
+    "columns": [
+      {
+        "name": "COUNT(*)",
+        "ordinal": 0,
+        "type_info": "Integer"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "bd1666cea8840df04ddcdc8a0c42b9b7771f9bf63c45613c4b6f8b86be479d70"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM audit_events WHERE ts_unix < ?1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "ca612fee8c80f815b33dbc088cc7e0a7552f1f4e38390959e14ea5cc765bf2c7"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM alert_transitions WHERE ts_unix < ?1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "ce850a32c8702595bbc3207bf86d53209c48be145562192b3a8f84903d39eac1"
+}
@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT COUNT(*) FROM audit_events WHERE event_id = ?1",
+  "describe": {
+    "columns": [
+      {
+        "name": "COUNT(*)",
+        "ordinal": 0,
+        "type_info": "Integer"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "dc7056b7421dcc83648cbd360273ebcce1156ce0f7da2d39f054025ab9b66b6b"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO alert_transitions\n             (transition_key, transition_id, ts_unix, alert_id, kind, agent_id,\n              from_status, to_status, message, metadata_json)\n             VALUES (?1, ?2, ?3, 'alert-old', 'test', NULL, NULL, 'active', 'old', '{}')",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "e83a43217a3bfaacd2f5e76df1fd05447558646fb2b47963751a7ab53b3a99b6"
+}
@@ -3624,7 +3624,7 @@ dependencies = [

 [[package]]
 name = "wakey"
-version = "0.3.5"
+version = "0.3.6"
 dependencies = [
 "anyhow",
 "chrono",
@@ -3645,7 +3645,7 @@ dependencies = [

 [[package]]
 name = "wakey-agent"
-version = "0.3.5"
+version = "0.3.6"
 dependencies = [
 "anyhow",
 "clap",
@@ -3670,7 +3670,7 @@ dependencies = [

 [[package]]
 name = "wakey-control-plane"
-version = "0.3.5"
+version = "0.3.6"
 dependencies = [
 "anyhow",
 "axum",
@@ -3699,7 +3699,7 @@ dependencies = [

 [[package]]
 name = "wakey-core"
-version = "0.3.5"
+version = "0.3.6"
 dependencies = [
 "macaddr",
 "serde",
@@ -3711,7 +3711,7 @@ dependencies = [

 [[package]]
 name = "wakey-linux"
-version = "0.3.5"
+version = "0.3.6"
 dependencies = [
 "anyhow",
 "futures",
@@ -1,6 +1,6 @@
 [package]
 name = "wakey"
-version = "0.3.5"
+version = "0.3.6"
 edition = "2024"
 publish = ["gitea"]

@@ -207,10 +207,23 @@ Control-plane admin API includes token management endpoints:
 - `GET /api/v1/control/audit/events?agent_id=<id>&event_type=<type>&limit=<n>`
 - `GET /api/v1/control/alerts?lookback_seconds=900`
 - `GET /api/v1/control/alerts/history?since_unix=<ts>&limit=<n>`
- `GET /api/v1/control/alerts/ws` (websocket snapshots + recent transitions)
+- `GET /api/v1/control/alerts/ws` (websocket snapshots, recent transitions, and evaluator health)
+- `GET /api/v1/control/terminals/events/ws` (websocket session-list invalidations)
 - `DELETE /api/v1/control/agents/{agent_id}`
 - `PATCH /api/v1/control/agents/{agent_id}/nickname`

+Alert evaluation runs once per control plane every five seconds. The alerts GET
+returns `503 alerts_unavailable` until a successful evaluation, after evaluation
+failure, or when its snapshot is stale. The existing alerts stream also sends
+`alerts_health` messages with `available` and an optional `reason`; the UI keeps
+the last results visible with a stale warning until recovery. Custom alert-rule
+query overrides are rejected with `400 unsupported_alert_override`.
+
+Terminal session events carry only `sessions_changed` invalidations. Clients
+refetch the session list after changes or reconnection and retain a 15-second
+fallback refresh. Events do not grant session ownership; attachment still uses
+the existing server-side locking and scoped credentials.
+
 If commands still appear silent, verify both processes are running with `-v`
 and that `RUST_LOG` is not overriding to a stricter level.

@@ -72,6 +72,10 @@ When the operator socket disconnects, the session becomes detached. Navigation,

 The operator UI lists live sessions as tabs and stores only the active terminal ID in browser-tab-scoped `sessionStorage`. On reload it prefers that ID and briefly waits for the previous WebSocket to detach before requesting a fresh attachment credential. The stored ID is a navigation hint, not an ownership credential; another attached operator still locks the session at the control plane.

+The protected `/api/v1/control/terminals/events/ws` stream sends `sessions_changed` invalidations when the volatile session catalog or attachment ownership changes. These events contain no terminal bytes or attachment credentials: browsers refetch the ordinary session list, coalescing bursts and repeating a fetch if another event arrives during it. Subscribing and reconnecting also invalidate the list. The 15-second refresh remains a recovery fallback; the stream is a freshness hint, never an authorization or locking mechanism.
+
+The React page composes three custom hooks rather than owning every resource itself. `useXterm` owns the single renderer, its addons, fitting, fonts, and display operations. `useTerminalSessions` owns the catalog subscription, coalesced refreshes, and fallback timer. `useTerminalSession` owns active attachment, input, restoration, and session operations. The attachment hook waits for renderer readiness; stable renderer operations prevent ordinary state updates from rebuilding the terminal or reconnecting its transport. Each hook cleans up its own resources on unmount, which detaches the browser without deleting the agent-owned PTY.
+
 After operator attachment, the control plane sends a `snapshot` request. The agent serializes up to 1,000 retained physical rows followed by its parsed current screen and input modes as terminal escape bytes, sends them before subsequent live output, and then signals the PTY's current foreground process group with `SIGWINCH`. Historical rows retain their terminal attributes and are replayed as ordinary terminal output so xterm builds its native scrollback; the final formatted state restores the exact live screen. The signal lets full-screen applications redraw without assuming that the original shell remains in the foreground. Signal failure is logged but never terminates the session. The connected browser independently retains up to 10,000 rows because that memory belongs to the operator device rather than the agent host.

 Wakey carries a small, read-only extension to `vt100` because its public API exposes only the active grid. A snapshot streams bounded history from the primary grid, redraws that grid with its saved cursor and attributes, and then reconstructs the alternate grid when a full-screen application is active. The parser is never resized or switched while taking a snapshot. Consequently, reconnecting during `btop` restores the application while preserving the hidden shell history and state that reappear when it exits.
@@ -2,7 +2,7 @@
 set -eu

 ROOT="$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)"
-DB="${SQLX_PREPARE_DB:-/tmp/wakey-sqlx-prepare.sqlite3}"
+DB="${SQLX_PREPARE_DB:-$ROOT/wakey-prepare.sqlite3}"
 DATABASE_URL="sqlite://$DB"

 if ! cargo sqlx --version >/dev/null 2>&1; then
@@ -23,3 +23,5 @@ cp .sqlx/*.json wakey-control-plane/.sqlx/

 echo "SQLx metadata prepared in $ROOT/.sqlx"
 echo "SQLx package metadata mirrored in $ROOT/wakey-control-plane/.sqlx"
+echo "Prepare DB (referenced by .env for live compile-time checking): $DB"
+echo "DATABASE_URL=$DATABASE_URL"
@@ -15,13 +15,13 @@
    "@base-ui/react": "^1.4.0",
    "@fontsource-variable/inter": "^5.2.8",
    "@tailwindcss/vite": "^4.2.2",
-    "@xterm/addon-clipboard": "0.3.0-beta.290",
-    "@xterm/addon-fit": "0.12.0-beta.290",
-    "@xterm/addon-image": "0.10.0-beta.290",
-    "@xterm/addon-unicode-graphemes": "0.5.0-beta.290",
-    "@xterm/addon-unicode11": "0.10.0-beta.290",
-    "@xterm/addon-web-links": "0.13.0-beta.290",
-    "@xterm/xterm": "6.1.0-beta.290",
+    "@xterm/addon-clipboard": "0.3.0-beta.301",
+    "@xterm/addon-fit": "0.12.0-beta.301",
+    "@xterm/addon-image": "0.10.0-beta.301",
+    "@xterm/addon-unicode-graphemes": "0.5.0-beta.301",
+    "@xterm/addon-unicode11": "0.10.0-beta.301",
+    "@xterm/addon-web-links": "0.13.0-beta.301",
+    "@xterm/xterm": "6.1.0-beta.301",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "lucide-react": "^1.8.0",
@@ -18,26 +18,26 @@ importers:
        specifier: ^4.2.2
        version: 4.2.2([email protected](@types/[email protected])([email protected]))
      '@xterm/addon-clipboard':
-        specifier: 0.3.0-beta.290
-        version: 0.3.0-beta.290(@xterm/[email protected].290)
+        specifier: 0.3.0-beta.301
+        version: 0.3.0-beta.301(@xterm/[email protected].301)
      '@xterm/addon-fit':
-        specifier: 0.12.0-beta.290
-        version: 0.12.0-beta.290(@xterm/[email protected].290)
+        specifier: 0.12.0-beta.301
+        version: 0.12.0-beta.301(@xterm/[email protected].301)
      '@xterm/addon-image':
-        specifier: 0.10.0-beta.290
-        version: 0.10.0-beta.290(@xterm/[email protected].290)
+        specifier: 0.10.0-beta.301
+        version: 0.10.0-beta.301(@xterm/[email protected].301)
      '@xterm/addon-unicode-graphemes':
-        specifier: 0.5.0-beta.290
-        version: 0.5.0-beta.290(@xterm/[email protected].290)
+        specifier: 0.5.0-beta.301
+        version: 0.5.0-beta.301(@xterm/[email protected].301)
      '@xterm/addon-unicode11':
-        specifier: 0.10.0-beta.290
-        version: 0.10.0-beta.290(@xterm/[email protected].290)
+        specifier: 0.10.0-beta.301
+        version: 0.10.0-beta.301(@xterm/[email protected].301)
      '@xterm/addon-web-links':
-        specifier: 0.13.0-beta.290
-        version: 0.13.0-beta.290(@xterm/[email protected].290)
+        specifier: 0.13.0-beta.301
+        version: 0.13.0-beta.301(@xterm/[email protected].301)
      '@xterm/xterm':
-        specifier: 6.1.0-beta.290
-        version: 6.1.0-beta.290
+        specifier: 6.1.0-beta.301
+        version: 6.1.0-beta.301
      class-variance-authority:
        specifier: ^0.7.1
        version: 0.7.1
@@ -836,38 +836,38 @@ packages:
    peerDependencies:
      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0

-  '@xterm/[email protected].290':
-    resolution: {integrity: sha512-ky44+eNKIxL9clMgrWCBRSRe1Y6Oj+ayNavySfFioScxpuyicu/GYaF7n97eqW3FW0eClElCtsK+wJ6AGqnJmw==}
+  '@xterm/[email protected].301':
+    resolution: {integrity: sha512-DRL0EybPhWzgndaTeakVbh/HvJF7yzxRtfNCnIudFZQaGugFYsEUZNOaV2NZev8z5kLwor6miH1j3DNMI8Paxg==}
    peerDependencies:
-      '@xterm/xterm': ^6.1.0-beta.290
+      '@xterm/xterm': ^6.1.0-beta.301

-  '@xterm/[email protected].290':
-    resolution: {integrity: sha512-mJ77s82VhARA8XhuWcUnWYKAZkEDzSnCzgBrT9qjHJlHWr+G5duDZcOBnxnVVNtp21LDKaONr3c7IxuLii1XNg==}
+  '@xterm/[email protected].301':
+    resolution: {integrity: sha512-MukRyJLAFQrW/++aM209jBZ8G9J/Ioe4SGS6c3ba87v+zYuX/I66JrDB7sVfykQ9t7DlT+c1MWl1jTlX2kyx1w==}
    peerDependencies:
-      '@xterm/xterm': ^6.1.0-beta.290
+      '@xterm/xterm': ^6.1.0-beta.304

-  '@xterm/[email protected].290':
-    resolution: {integrity: sha512-gzQfH3tACsdf52n0lY3QMwLY7HcII1ce+IvzphWs9UucQIZ3rBKjEkYz4sxBhhEP1Eb6dNn1uerrfoJECmcyGg==}
+  '@xterm/[email protected].301':
+    resolution: {integrity: sha512-PJZL4GlQ1ReIgbffFMaOAFxc3wOit21/G2UEM82RpH3hNHjn6MH8ilz3ToDeBjYuOqU7ienBaeIuMbNktX4/HA==}
    peerDependencies:
-      '@xterm/xterm': ^6.1.0-beta.290
+      '@xterm/xterm': ^6.1.0-beta.304

-  '@xterm/[email protected].290':
-    resolution: {integrity: sha512-c0hF4HJrbZUlb1cVXNldl6YRf+Udoe3nc80djNnxSzjHgmryT09DhL4U4IDcCqSkzgwMENnN65mexlYKyNXNBw==}
+  '@xterm/[email protected].301':
+    resolution: {integrity: sha512-EBZIZYS6RItWTGO/KpLqV6y3IKGYyugbP07lK0x6G7185FVA61L2t0/XVtVEQNpczsbPo8zAxBhpoV72TP8CYw==}
    peerDependencies:
-      '@xterm/xterm': ^6.1.0-beta.290
+      '@xterm/xterm': ^6.1.0-beta.304

-  '@xterm/[email protected].290':
-    resolution: {integrity: sha512-tSmvf6hX1tT4RAgqbC8moZc/2oLR3qkaAL0xHaSMPd5bch2wkSvjfTxDfb3cfXJLyKCkWR+uwH54JYNOnCTW5g==}
+  '@xterm/[email protected].301':
+    resolution: {integrity: sha512-SS5BzfbvfFIikE4xZFAtHu6n0Kl5R1ZCPx41RL2WULLSE+HFo/WmYee53tMxNK/QUjpcQWepeVB7HebCPhHnig==}
    peerDependencies:
-      '@xterm/xterm': ^6.1.0-beta.290
+      '@xterm/xterm': ^6.1.0-beta.304

-  '@xterm/[email protected].290':
-    resolution: {integrity: sha512-p0OL4dPrmETt+6sFUniSjiV2g5nV35ckipVZQv1uuZ8GKtHYvlDTJj4Fr+cHzrsNmDhceaaiIW6fMPynJtCm1w==}
+  '@xterm/[email protected].301':
+    resolution: {integrity: sha512-BpY297K+FGLsTQemnA6uOg6hk85DwVuUvWCqE9rIAcDxOOC7fP9GKAZTIfaEos/EZk2Ei23vD6w0P5Br6+RU7Q==}
    peerDependencies:
-      '@xterm/xterm': ^6.1.0-beta.290
+      '@xterm/xterm': ^6.1.0-beta.304

-  '@xterm/[email protected].290':
-    resolution: {integrity: sha512-lbzQN1cx0h9uLUWQM7l6HxjP0qPMoqhc1ahlwmqgbSALpTeOUAQfMhMhHr0TSGRIcv7S4grvhhzQCb6teFrZ7Q==}
+  '@xterm/[email protected].301':
+    resolution: {integrity: sha512-y1pH42+Mx+h5E2xDgyilYXBKYkn8/6+anToiTmIt8gVww/2gHFqheK0vW+m9LADQsZ5AFs+SQvcK+tOyxWfRJA==}

  [email protected]:
    resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
@@ -2862,31 +2862,31 @@ snapshots:
    transitivePeerDependencies:
      - supports-color

-  '@xterm/[email protected].290(@xterm/[email protected].290)':
+  '@xterm/[email protected].301(@xterm/[email protected].301)':
    dependencies:
-      '@xterm/xterm': 6.1.0-beta.290
+      '@xterm/xterm': 6.1.0-beta.301

-  '@xterm/[email protected].290(@xterm/[email protected].290)':
+  '@xterm/[email protected].301(@xterm/[email protected].301)':
    dependencies:
-      '@xterm/xterm': 6.1.0-beta.290
+      '@xterm/xterm': 6.1.0-beta.301

-  '@xterm/[email protected].290(@xterm/[email protected].290)':
+  '@xterm/[email protected].301(@xterm/[email protected].301)':
    dependencies:
-      '@xterm/xterm': 6.1.0-beta.290
+      '@xterm/xterm': 6.1.0-beta.301

-  '@xterm/[email protected].290(@xterm/[email protected].290)':
+  '@xterm/[email protected].301(@xterm/[email protected].301)':
    dependencies:
-      '@xterm/xterm': 6.1.0-beta.290
+      '@xterm/xterm': 6.1.0-beta.301

-  '@xterm/[email protected].290(@xterm/[email protected].290)':
+  '@xterm/[email protected].301(@xterm/[email protected].301)':
    dependencies:
-      '@xterm/xterm': 6.1.0-beta.290
+      '@xterm/xterm': 6.1.0-beta.301

-  '@xterm/[email protected].290(@xterm/[email protected].290)':
+  '@xterm/[email protected].301(@xterm/[email protected].301)':
    dependencies:
-      '@xterm/xterm': 6.1.0-beta.290
+      '@xterm/xterm': 6.1.0-beta.301

-  '@xterm/[email protected].290': {}
+  '@xterm/[email protected].301': {}

  [email protected]:
    dependencies:
@@ -1,4 +1,4 @@
-import { lazy, Suspense, useEffect, useState } from "react";
+import { lazy, Suspense, useEffect, useRef, useState } from "react";
 import { Navigate, Route, Routes } from "react-router-dom";
 import { toast } from "sonner";

@@ -40,22 +40,48 @@ export function App() {
  const [history, setHistory] = useState<AlertTransition[]>([]);
  const [audit, setAudit] = useState<AuditEvent[]>([]);
  const [selectedAgentId, setSelectedAgentId] = useState("");
+  const [alertsHealth, setAlertsHealth] = useState<{
+    available: boolean;
+    reason?: string;
+  } | null>(null);
+  const [alertsStreamConnected, setAlertsStreamConnected] = useState(false);
+  const streamHealthReceived = useRef(false);
+  const alertsRevision = useRef(0);

  const [state, setState] = useState<LoadState>("idle");

+  async function loadAlertsWithoutBlocking() {
+    try {
+      const nextAlerts = await fetchAlerts();
+      if (!streamHealthReceived.current) {
+        setAlertsHealth({ available: true });
+      }
+      return nextAlerts;
+    } catch (err) {
+      if (!streamHealthReceived.current) {
+        setAlertsHealth({ available: false, reason: String(err) });
+      }
+      return null;
+    }
+  }
+
  async function loadAll() {
+    const revision = alertsRevision.current;
    setState("loading");
    try {
      const [nextAgents, nextAlerts, nextHistory, nextAudit] =
        await Promise.all([
          fetchAgents(),
-          fetchAlerts(),
+          loadAlertsWithoutBlocking(),
          fetchAlertHistory(20),
          fetchAudit(30),
        ]);
      setAgents(nextAgents);
-      setAlerts(nextAlerts);
-      setHistory(nextHistory);
+      // Streamed state wins over HTTP requests started before its arrival.
+      if (revision === alertsRevision.current) {
+        if (nextAlerts) setAlerts(nextAlerts);
+        setHistory(nextHistory);
+      }
      setAudit(nextAudit);
      const firstConnectedAgentId =
        nextAgents.find((agent) => agent.connected)?.agent_id ?? "";
@@ -100,12 +126,15 @@ export function App() {
  }

  async function refreshAlertsAndHistory() {
+    const revision = alertsRevision.current;
    const [nextAlerts, nextHistory] = await Promise.all([
-      fetchAlerts(),
+      loadAlertsWithoutBlocking(),
      fetchAlertHistory(20),
    ]);
-    setAlerts(nextAlerts);
-    setHistory(nextHistory);
+    if (revision === alertsRevision.current) {
+      if (nextAlerts) setAlerts(nextAlerts);
+      setHistory(nextHistory);
+    }
  }

  useEffect(() => {
@@ -113,30 +142,87 @@ export function App() {
  }, []);

  useEffect(() => {
-    const wsUrl = `${window.location.protocol === "https:" ? "wss" : "ws"}://${window.location.host}/api/v1/control/alerts/ws`;
-    const ws = new WebSocket(wsUrl);
+    let socket: WebSocket | null = null;
+    let disposed = false;
+    let attempt = 0;
+    let openedAt = 0;
+    let reconnectTimer: number | undefined;

-    ws.onmessage = (evt) => {
-      try {
-        const payload = JSON.parse(String(evt.data)) as {
-          alerts?: Alert[];
-          recent_transitions?: AlertTransition[];
-        };
-        if (payload.alerts) setAlerts(payload.alerts);
-        if (payload.recent_transitions) setHistory(payload.recent_transitions);
-      } catch {
-        // Ignore malformed stream payloads and keep current UI state.
-      }
+    const resync = () => {
+      const generation = alertsRevision.current;
+      void Promise.all([fetchAlerts(), fetchAlertHistory(20)])
+        .then(([nextAlerts, nextHistory]) => {
+          // A WS snapshot delivered while this request was in flight is newer.
+          if (disposed || generation !== alertsRevision.current) return;
+          setAlerts(nextAlerts);
+          setHistory(nextHistory);
+        })
+        .catch(() => undefined);
    };

-    ws.onerror = () => {
-      const id = window.setInterval(() => {
-        void refreshAlertsAndHistory().catch(() => undefined);
-      }, 8000);
-      ws.onclose = () => window.clearInterval(id);
+    const connect = () => {
+      if (disposed) return;
+      const wsUrl = `${window.location.protocol === "https:" ? "wss" : "ws"}://${window.location.host}/api/v1/control/alerts/ws`;
+      socket = new WebSocket(wsUrl);
+
+      socket.onopen = () => {
+        if (disposed) return;
+        openedAt = Date.now();
+        setAlertsStreamConnected(true);
+        // Pull anything missed while the stream was down.
+        resync();
+      };
+
+      socket.onmessage = (evt) => {
+        if (disposed) return;
+        alertsRevision.current += 1;
+        try {
+          const payload = JSON.parse(String(evt.data)) as {
+            type?: string;
+            available?: boolean;
+            reason?: string;
+            alerts?: Alert[];
+            recent_transitions?: AlertTransition[];
+          };
+          if (payload.type === "alerts_health") {
+            streamHealthReceived.current = true;
+            setAlertsHealth({
+              available: payload.available === true,
+              reason: payload.reason,
+            });
+            return;
+          }
+          if (payload.alerts) setAlerts(payload.alerts);
+          if (payload.recent_transitions)
+            setHistory(payload.recent_transitions);
+        } catch {
+          // Ignore malformed stream payloads and keep current UI state.
+        }
+      };
+
+      socket.onclose = () => {
+        socket = null;
+        if (disposed) return;
+        setAlertsStreamConnected(false);
+        // Only a connection that stayed up proves the stream is healthy; an
+        // accept-then-close server must not pin us to the first backoff step.
+        if (openedAt && Date.now() - openedAt > 10_000) attempt = 0;
+        openedAt = 0;
+        // Browsers never reconnect a WebSocket on their own.
+        const delay =
+          Math.min(30_000, 1000 * 2 ** attempt) + Math.random() * 1000;
+        attempt += 1;
+        reconnectTimer = window.setTimeout(connect, delay);
+      };
    };

-    return () => ws.close();
+    connect();
+
+    return () => {
+      disposed = true;
+      if (reconnectTimer !== undefined) window.clearTimeout(reconnectTimer);
+      socket?.close();
+    };
  }, []);

  return (
@@ -175,6 +261,8 @@ export function App() {
                transitions={history}
                audit={audit}
                loading={state === "loading"}
+                alertsHealth={alertsHealth}
+                alertsStreamConnected={alertsStreamConnected}
                onRefresh={loadAll}
              />
            }
@@ -217,6 +305,8 @@ export function App() {
              <AlertsPage
                alerts={alerts}
                transitions={history}
+                alertsHealth={alertsHealth}
+                alertsStreamConnected={alertsStreamConnected}
                onRefresh={refreshAlertsAndHistory}
              />
            }
@@ -16,10 +16,18 @@ import { Textarea } from "@/components/ui/textarea";
 type Props = {
  alerts: Alert[];
  transitions: AlertTransition[];
+  alertsHealth: { available: boolean; reason?: string } | null;
+  alertsStreamConnected: boolean;
  onRefresh: () => Promise<void>;
 };

-export function AlertsPage({ alerts, transitions, onRefresh }: Props) {
+export function AlertsPage({
+  alerts,
+  transitions,
+  alertsHealth,
+  alertsStreamConnected,
+  onRefresh,
+}: Props) {
  const [severity, setSeverity] = useState("all");
  const [status, setStatus] = useState("all");
  const [kind, setKind] = useState("all");
@@ -66,9 +74,27 @@ export function AlertsPage({ alerts, transitions, onRefresh }: Props) {
      <Card>
        <CardHeader className="flex items-center justify-between gap-2">
          <CardTitle>Active Alerts</CardTitle>
-          <Button size="sm" variant="outline" onClick={() => void onRefresh()}>
-            Refresh
-          </Button>
+          <div className="flex flex-wrap items-center justify-end gap-x-3 gap-y-1">
+            <div
+              aria-live="polite"
+              className="text-right text-xs text-muted-foreground"
+            >
+              {!alertsStreamConnected && <div>Alert stream disconnected</div>}
+              {alertsHealth?.available === false && (
+                <div>
+                  Alert results may be stale or unavailable
+                  {alertsHealth.reason ? `: ${alertsHealth.reason}` : ""}
+                </div>
+              )}
+            </div>
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => void onRefresh()}
+            >
+              Refresh
+            </Button>
+          </div>
        </CardHeader>
        <CardContent className="space-y-3">
          <div className="grid gap-2 sm:grid-cols-3">
@@ -27,6 +27,8 @@ type Props = {
  transitions: AlertTransition[];
  audit: AuditEvent[];
  loading: boolean;
+  alertsHealth: { available: boolean; reason?: string } | null;
+  alertsStreamConnected: boolean;
  onRefresh: () => void;
 };

@@ -66,6 +68,8 @@ export function DashboardPage({
  transitions,
  audit,
  loading,
+  alertsHealth,
+  alertsStreamConnected,
  onRefresh,
 }: Props) {
  const connected = agents.filter((a) => a.connected).length;
@@ -165,6 +169,20 @@ export function DashboardPage({
          </Link>
        </CardHeader>
        <CardContent>
+          {(!alertsStreamConnected || alertsHealth?.available === false) && (
+            <div
+              aria-live="polite"
+              className="mb-2 text-xs text-muted-foreground"
+            >
+              {!alertsStreamConnected && <div>Alert stream disconnected</div>}
+              {alertsHealth?.available === false && (
+                <div>
+                  Alert results may be stale or unavailable
+                  {alertsHealth.reason ? `: ${alertsHealth.reason}` : ""}
+                </div>
+              )}
+            </div>
+          )}
          <div className="text-2xl font-bold tabular-nums">{alerts.length}</div>
          {Object.keys(severityBuckets).length > 0 ? (
            <div className="mt-2 flex flex-wrap gap-1.5">
@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { Inbox, MoreHorizontal, RefreshCw, Search, Zap } from "lucide-react";
 import { toast } from "sonner";

@@ -69,8 +69,12 @@ export function DevicesPage({ agents, onAfterWake, onRefresh }: Props) {
  const [refreshing, setRefreshing] = useState(false);
  const [wakeBusyKey, setWakeBusyKey] = useState("");
  const [details, setDetails] = useState<FleetDevice | null>(null);
+  const loadSeqRef = useRef(0);

  async function loadFleet() {
+    // Latest request wins: filter changes and debounced searches overlap, and
+    // an older response must never overwrite fresher state.
+    const seq = ++loadSeqRef.current;
    setLoading(true);
    try {
      const [nextDevices, nextKnownDevices] = await Promise.all([
@@ -84,12 +88,14 @@ export function DevicesPage({ agents, onAfterWake, onRefresh }: Props) {
        }),
        fetchKnownDevices(),
      ]);
+      if (seq !== loadSeqRef.current) return;
      setDevices(nextDevices);
      setKnownDevices(nextKnownDevices);
    } catch (err) {
+      if (seq !== loadSeqRef.current) return;
      toast.error("Failed to load fleet", { description: String(err) });
    } finally {
-      setLoading(false);
+      if (seq === loadSeqRef.current) setLoading(false);
    }
  }

@@ -152,7 +158,13 @@ export function DevicesPage({ agents, onAfterWake, onRefresh }: Props) {
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [presence, known, agentId]);

+  // The filter effect above already loads on mount; only react to query edits.
+  const mountedRef = useRef(false);
  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true;
+      return;
+    }
    const timer = window.setTimeout(() => void loadFleet(), 220);
    return () => window.clearTimeout(timer);
    // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -1,23 +1,8 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-import { ClipboardAddon } from "@xterm/addon-clipboard";
-import { FitAddon } from "@xterm/addon-fit";
-import { ImageAddon } from "@xterm/addon-image";
-import { Unicode11Addon } from "@xterm/addon-unicode11";
-import { UnicodeGraphemesAddon } from "@xterm/addon-unicode-graphemes";
-import { WebLinksAddon } from "@xterm/addon-web-links";
-import { Terminal as XTerm } from "@xterm/xterm";
+import { useEffect, useRef, useState } from "react";
 import { Eraser, Keyboard, RotateCcw, Terminal } from "lucide-react";
 import { toast } from "sonner";

-import {
-  APIError,
-  type Agent,
-  type TerminalSession,
-  attachTerminal,
-  closeTerminal,
-  createTerminal,
-  listTerminals,
-} from "@/api";
+import type { Agent } from "@/api";
 import { AgentSelector, displayAgentLabel } from "@/components/AgentSelector";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -26,24 +11,11 @@ import {
  TooltipContent,
  TooltipTrigger,
 } from "@/components/ui/tooltip";
-import {
-  MAX_TERMINAL_FONT_SIZE,
-  MIN_TERMINAL_FONT_SIZE,
-  TerminalAccessoryBar,
-} from "@/pages/terminal/TerminalAccessoryBar";
+import { TerminalAccessoryBar } from "@/pages/terminal/TerminalAccessoryBar";
 import { TerminalSessionTabs } from "@/pages/terminal/TerminalSessionTabs";
-import {
-  NO_TERMINAL_MODIFIERS,
-  applyTerminalModifiers,
-  mergeTerminalSession,
-  orderTerminalSessions,
-  reconcileTerminalSessions,
-  restoreCandidates,
-  visibleTerminalText,
-  type TerminalConnectionState,
-  type TerminalModifiers,
-} from "@/pages/terminal/sessionUtils";
-import { loadTerminalFontFamily } from "@/terminal/terminalFonts";
+import { useTerminalSession } from "@/pages/terminal/useTerminalSession";
+import { useTerminalSessions } from "@/pages/terminal/useTerminalSessions";
+import { useXterm } from "@/pages/terminal/useXterm";

 type Props = {
  agents: Agent[];
@@ -51,11 +23,6 @@ type Props = {
  onSelectAgent: (agentId: string) => void;
 };

-const REMEMBERED_TERMINAL_KEY = "wakey.active-terminal-id";
-const TERMINAL_OPERATOR_KEY = "wakey.terminal-operator-id";
-const DEFAULT_TERMINAL_FONT_SIZE = 14;
-const TERMINAL_TOUCH_SLOP_PX = 8;
-
 type TerminalTouch = {
  pointerId: number;
  startX: number;
@@ -63,31 +30,7 @@ type TerminalTouch = {
  moved: boolean;
 };

-// polyfill for testing in browsers that don't support crypto.randomUUID()
-const thing = () =>
-  (String(1e7) + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, (c: string) => {
-    const num = Number(c);
-    return (
-      num ^
-      (window.crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (num / 4)))
-    ).toString(16);
-  });
-
-function terminalOperatorId(): string {
-  // Session storage survives route unmounts but remains scoped to this browser
-  // tab. The ID coordinates attachment ownership; API authentication remains
-  // the security boundary.
-  const remembered = window.sessionStorage.getItem(TERMINAL_OPERATOR_KEY);
-  if (remembered) return remembered;
-  const created = window.crypto.randomUUID?.() ?? thing();
-  window.sessionStorage.setItem(TERMINAL_OPERATOR_KEY, created);
-  return created;
-}
-
-function websocketUrl(path: string): string {
-  const scheme = window.location.protocol === "https:" ? "wss:" : "ws:";
-  return `${scheme}//${window.location.host}${path}`;
-}
+const TERMINAL_TOUCH_SLOP_PX = 8;

 export function TerminalPage({
  agents,
@@ -96,33 +39,24 @@ export function TerminalPage({
 }: Props) {
  const pageRef = useRef<HTMLElement>(null);
  const hostRef = useRef<HTMLDivElement>(null);
-  const terminalRef = useRef<XTerm | null>(null);
-  const fitRef = useRef<FitAddon | null>(null);
-  const socketRef = useRef<WebSocket | null>(null);
-  const activeSessionRef = useRef<TerminalSession | null>(null);
-  const selectedAgentIdRef = useRef(selectedAgentId);
-  const lastTerminalSizeRef = useRef({ rows: 0, cols: 0 });
-  const modifiersRef = useRef<TerminalModifiers>(NO_TERMINAL_MODIFIERS);
  const terminalTouchRef = useRef<TerminalTouch | null>(null);
  const terminalInputFocusedBeforeAccessoryRef = useRef(false);
-  const [sessions, setSessions] = useState<TerminalSession[]>([]);
-  const [session, setSession] = useState<TerminalSession | null>(null);
-  const [connection, setConnection] = useState<TerminalConnectionState>("idle");
-  const [sessionTitles, setSessionTitles] = useState<Record<string, string>>(
-    {},
-  );
-  const [terminalFontFamily, setTerminalFontFamily] = useState<string>();
-  const [terminalFontSize, setTerminalFontSize] = useState(
-    DEFAULT_TERMINAL_FONT_SIZE,
-  );
  const [nowUnix, setNowUnix] = useState(() => Math.floor(Date.now() / 1000));
-  const [modifiers, setModifiers] = useState<TerminalModifiers>(
-    NO_TERMINAL_MODIFIERS,
-  );
  const [accessoriesOpen, setAccessoriesOpen] = useState(
    () => window.matchMedia("(pointer: coarse), (max-width: 640px)").matches,
  );
-  const [operatorId] = useState(terminalOperatorId);
+
+  const catalog = useTerminalSessions();
+  const { sessions } = catalog;
+  const terminal = useXterm({
+    pageRef,
+    hostRef,
+  });
+  const terminalSession = useTerminalSession({
+    terminal: terminal.terminal,
+    catalog,
+    selectedAgentId,
+  });

  useEffect(() => {
    const clock = window.setInterval(
@@ -132,9 +66,6 @@ export function TerminalPage({
    return () => window.clearInterval(clock);
  }, []);

-  activeSessionRef.current = session;
-  selectedAgentIdRef.current = selectedAgentId;
-
  const selectedAgent = agents.find(
    (agent) => agent.agent_id === selectedAgentId,
  );
@@ -150,89 +81,25 @@ export function TerminalPage({
  const canRequestStart = Boolean(
    selectedAgent?.connected &&
    selectedAgent.capabilities.includes("terminal") &&
-    connection !== "connecting",
+    terminalSession.connection !== "connecting" &&
+    terminal.terminal.ready,
  );
-  const terminalInputReady = connection === "ready";
+  const terminalInputReady = terminalSession.connection === "ready";

-  const detachTransport = useCallback(() => {
-    const socket = socketRef.current;
-    socketRef.current = null;
-    socket?.close();
-  }, []);
-
-  const writeTerminalData = useCallback(
-    (data: string, consumeModifiers = false) => {
-      const socket = socketRef.current;
-      if (socket?.readyState !== WebSocket.OPEN) return;
-      const activeModifiers = modifiersRef.current;
-      const output = consumeModifiers
-        ? applyTerminalModifiers(data, activeModifiers)
-        : data;
-      socket.send(new TextEncoder().encode(output));
-      if (consumeModifiers && (activeModifiers.ctrl || activeModifiers.meta)) {
-        modifiersRef.current = NO_TERMINAL_MODIFIERS;
-        setModifiers(NO_TERMINAL_MODIFIERS);
-      }
-    },
-    [],
-  );
-
-  const toggleModifier = useCallback((modifier: keyof TerminalModifiers) => {
-    setModifiers((current) => {
-      const next = { ...current, [modifier]: !current[modifier] };
-      modifiersRef.current = next;
-      return next;
-    });
-    window.requestAnimationFrame(() => terminalRef.current?.focus());
-  }, []);
-
-  const copyTerminalText = useCallback(async () => {
-    const terminal = terminalRef.current;
-    if (!terminal) return;
-    const text = terminal.hasSelection()
-      ? terminal.getSelection()
-      : visibleTerminalText(terminal);
-    if (!text) {
-      toast.info("Nothing to copy");
+  function start() {
+    if (agentAtSessionLimit) {
+      toast.error("Terminal session limit reached", {
+        description: `${selectedAgent ? displayAgentLabel(selectedAgent) : selectedAgentId} already reached the active session limit. Close one before opening another.`,
+      });
      return;
    }
-    try {
-      await navigator.clipboard.writeText(text);
-      toast.success(
-        terminal.hasSelection() ? "Selection copied" : "Visible screen copied",
-      );
-    } catch (error) {
-      toast.error("Clipboard access was denied", {
-        description: String(error),
-      });
-    }
-  }, []);
+    void terminalSession.start();
+  }

-  const pasteTerminalText = useCallback(async () => {
-    try {
-      const text = await navigator.clipboard.readText();
-      if (text) writeTerminalData(text);
-      terminalRef.current?.focus();
-    } catch (error) {
-      toast.error("Clipboard access was denied", {
-        description: String(error),
-      });
-    }
-  }, [writeTerminalData]);
-
-  const writeAccessoryKey = useCallback(
-    (data: string) => {
-      writeTerminalData(data);
-      window.requestAnimationFrame(() => terminalRef.current?.focus());
-    },
-    [writeTerminalData],
-  );
-
-  const toggleTerminalKeyboard = useCallback(() => {
-    const terminal = terminalRef.current;
-    if (!terminal) return;
+  function toggleTerminalKeyboard() {
+    const terminalInstance = terminal.terminal;
    const blurTerminalInput = () => {
-      terminal.textarea?.blur();
+      terminalInstance.blurInput();
      const activeElement = document.activeElement;
      if (
        activeElement instanceof HTMLElement &&
@@ -247,506 +114,10 @@ export function TerminalPage({
    terminalInputFocusedBeforeAccessoryRef.current = false;
    if (shouldHide) {
      blurTerminalInput();
-      // Base UI may restore the previously focused element as its pointer
-      // interaction completes. Dismiss the soft keyboard after that cycle too.
+      // Base UI may restore the previously focused element after pointer handling.
      window.requestAnimationFrame(blurTerminalInput);
    } else {
-      terminal.focus();
-    }
-  }, []);
-
-  const sendResize = useCallback(() => {
-    const terminal = terminalRef.current;
-    const socket = socketRef.current;
-    if (!terminal || socket?.readyState !== WebSocket.OPEN) return;
-    if (
-      lastTerminalSizeRef.current.rows === terminal.rows &&
-      lastTerminalSizeRef.current.cols === terminal.cols
-    ) {
-      return;
-    }
-    lastTerminalSizeRef.current = {
-      rows: terminal.rows,
-      cols: terminal.cols,
-    };
-    socket.send(
-      JSON.stringify({
-        type: "resize",
-        rows: terminal.rows,
-        cols: terminal.cols,
-      }),
-    );
-  }, []);
-
-  const changeTerminalFontSize = useCallback(
-    (delta: number) => {
-      const terminal = terminalRef.current;
-      if (!terminal) return;
-      const current = terminal.options.fontSize ?? DEFAULT_TERMINAL_FONT_SIZE;
-      const next = Math.min(
-        MAX_TERMINAL_FONT_SIZE,
-        Math.max(MIN_TERMINAL_FONT_SIZE, current + delta),
-      );
-      if (next === current) return;
-      terminal.options.fontSize = next;
-      setTerminalFontSize(next);
-      window.requestAnimationFrame(() => {
-        fitRef.current?.fit();
-        sendResize();
-      });
-    },
-    [sendResize],
-  );
-
-  const connect = useCallback(
-    (nextSession: TerminalSession) => {
-      if (!nextSession.attachment_token) {
-        throw new Error(
-          "Control plane did not issue a terminal attachment token",
-        );
-      }
-      detachTransport();
-      setSession(nextSession);
-      activeSessionRef.current = nextSession;
-      setSessions((current) =>
-        mergeTerminalSession(current, {
-          ...nextSession,
-          operator_attached: true,
-        }),
-      );
-      window.sessionStorage.setItem(
-        REMEMBERED_TERMINAL_KEY,
-        nextSession.terminal_id,
-      );
-      setConnection("connecting");
-      const socket = new WebSocket(websocketUrl(nextSession.websocket_url));
-      socket.binaryType = "arraybuffer";
-      socketRef.current = socket;
-
-      socket.onopen = () => {
-        socket.send(
-          JSON.stringify({
-            type: "attach",
-            attachment_token: nextSession.attachment_token,
-            operator_id: operatorId,
-          }),
-        );
-        fitRef.current?.fit();
-        sendResize();
-      };
-      socket.onmessage = (event) => {
-        if (socketRef.current !== socket) return;
-        if (typeof event.data !== "string") {
-          terminalRef.current?.write(new Uint8Array(event.data as ArrayBuffer));
-          return;
-        }
-        try {
-          const control = JSON.parse(event.data) as {
-            type: string;
-            exit_code?: number | null;
-            message?: string;
-          };
-          if (control.type === "ready") {
-            setConnection("ready");
-            window.requestAnimationFrame(() => {
-              fitRef.current?.fit();
-              lastTerminalSizeRef.current = { rows: 0, cols: 0 };
-              sendResize();
-              terminalRef.current?.focus();
-            });
-          } else if (control.type === "exited") {
-            setConnection("exited");
-            terminalRef.current?.writeln(
-              `\r\n[process exited${control.exit_code == null ? "" : ` ${control.exit_code}`}]`,
-            );
-          } else if (control.type === "error") {
-            setConnection("exited");
-            terminalRef.current?.writeln(
-              `\r\n[terminal error: ${control.message ?? "unknown error"}]`,
-            );
-          }
-        } catch {
-          terminalRef.current?.writeln("\r\n[invalid terminal control frame]");
-        }
-      };
-      socket.onerror = () => {
-        if (socketRef.current !== socket) return;
-        terminalRef.current?.writeln("\r\n[terminal transport error]");
-      };
-      socket.onclose = () => {
-        if (socketRef.current !== socket) return;
-        socketRef.current = null;
-        setSessions((current) =>
-          current.map((item) =>
-            item.terminal_id === nextSession.terminal_id
-              ? { ...item, operator_attached: false }
-              : item,
-          ),
-        );
-        setConnection((current) => {
-          if (current === "exited") return current;
-          return "disconnected";
-        });
-      };
-    },
-    [detachTransport, operatorId, sendResize],
-  );
-
-  useEffect(() => {
-    let cancelled = false;
-    void loadTerminalFontFamily().then((fontFamily) => {
-      if (!cancelled) setTerminalFontFamily(fontFamily);
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, []);
-
-  useEffect(() => {
-    const viewport = window.visualViewport;
-    const updateViewportHeight = () => {
-      const height = Math.round(viewport?.height ?? window.innerHeight);
-      pageRef.current?.style.setProperty(
-        "--terminal-visual-viewport-height",
-        `${height}px`,
-      );
-    };
-    updateViewportHeight();
-    viewport?.addEventListener("resize", updateViewportHeight);
-    viewport?.addEventListener("scroll", updateViewportHeight);
-    window.addEventListener("resize", updateViewportHeight);
-    return () => {
-      viewport?.removeEventListener("resize", updateViewportHeight);
-      viewport?.removeEventListener("scroll", updateViewportHeight);
-      window.removeEventListener("resize", updateViewportHeight);
-    };
-  }, []);
-
-  useEffect(() => {
-    if (!hostRef.current || !terminalFontFamily) return;
-    const terminal = new XTerm({
-      cursorBlink: true,
-      convertEol: false,
-      fontFamily: terminalFontFamily,
-      fontSize: DEFAULT_TERMINAL_FONT_SIZE,
-      lineHeight: 1.1,
-      // xterm uses this width for its internal scrollbar as well as the
-      // overview ruler. Reserve a larger touch target on coarse pointers.
-      scrollbar: {
-        width: window.matchMedia("(pointer: coarse)").matches ? 22 : 16,
-      },
-      scrollback: 10_000,
-      theme: {
-        background: "#0b1117",
-        foreground: "#e5e7eb",
-        cursor: "#6ee7a8",
-        scrollbarSliderBackground: "#52617099",
-        scrollbarSliderHoverBackground: "#6b7c8dcc",
-        scrollbarSliderActiveBackground: "#8294a6",
-      },
-      allowProposedApi: true, // this for unicode11 addon. FOR SOME reason xtermjs doesnt tell me this in the readme.
-    });
-    terminal.loadAddon(new Unicode11Addon());
-    terminal.unicode.activeVersion = "11";
-    terminal.loadAddon(new UnicodeGraphemesAddon());
-    terminal.loadAddon(new WebLinksAddon());
-    terminal.loadAddon(
-      new ImageAddon({
-        // // Keep image terminals useful on phones without accepting the addon's
-        // // much larger default decode and retained-canvas memory ceilings.
-        // pixelLimit: 4 * 1024 * 1024,
-        // sixelSizeLimit: 8 * 1024 * 1024,
-        // iipSizeLimit: 8 * 1024 * 1024,
-        // storageLimit: 32,
-      }),
-    );
-    const fit = new FitAddon();
-    terminal.loadAddon(new ClipboardAddon());
-    terminal.loadAddon(fit);
-    terminal.open(hostRef.current);
-    terminal.attachCustomKeyEventHandler((event) => {
-      const copiesTerminalSelection =
-        event.type === "keydown" &&
-        event.ctrlKey &&
-        event.shiftKey &&
-        event.code === "KeyC";
-      if (!copiesTerminalSelection) return true;
-
-      // Chromium reserves Ctrl+Shift+C for DevTools. Other clipboard shortcuts
-      // fall through to xterm's native copy/paste event handlers.
-      event.preventDefault();
-      event.stopPropagation();
-      if (terminal.hasSelection()) {
-        if (!navigator.clipboard) {
-          toast.error("Clipboard access requires HTTPS or localhost");
-        } else {
-          void navigator.clipboard
-            .writeText(terminal.getSelection())
-            .catch((error) =>
-              toast.error("Clipboard access was denied", {
-                description: String(error),
-              }),
-            );
-        }
-      }
-      return false;
-    });
-    const titleChange = terminal.onTitleChange((title) => {
-      const terminalId = activeSessionRef.current?.terminal_id;
-      if (!terminalId) return;
-      const normalized = title.trim();
-      setSessionTitles((current) => {
-        if (current[terminalId] === normalized) return current;
-        if (!normalized) {
-          const next = { ...current };
-          delete next[terminalId];
-          return next;
-        }
-        return { ...current, [terminalId]: normalized };
-      });
-    });
-    fit.fit();
-    terminalRef.current = terminal;
-    fitRef.current = fit;
-
-    async function restoreTerminalSession() {
-      try {
-        const listed = await listTerminals();
-        if (cancelled) return;
-        setSessions(orderTerminalSessions(listed));
-        const rememberedId = window.sessionStorage.getItem(
-          REMEMBERED_TERMINAL_KEY,
-        );
-        const candidates = restoreCandidates(
-          listed,
-          rememberedId,
-          selectedAgentIdRef.current,
-        );
-
-        for (const candidate of candidates) {
-          setConnection("connecting");
-          try {
-            const attached = await attachTerminal(
-              candidate.terminal_id,
-              operatorId,
-            );
-            if (cancelled) return;
-            terminal.reset();
-            connect(attached);
-            return;
-          } catch (error) {
-            if (
-              !(error instanceof APIError) ||
-              error.code !== "terminal_operator_already_attached"
-            ) {
-              throw error;
-            }
-          }
-        }
-        setConnection("idle");
-      } catch (error) {
-        if (cancelled) return;
-        setConnection("idle");
-        toast.error("Could not restore terminal session", {
-          description: String(error),
-        });
-      }
-    }
-
-    let cancelled = false;
-    const input = terminal.onData((data) => writeTerminalData(data, true));
-    let resizeFrame = 0;
-    let lastHostWidth = 0;
-    let lastHostHeight = 0;
-    const resizeObserver = new ResizeObserver(([entry]) => {
-      const width = Math.round(entry.contentRect.width);
-      const height = Math.round(entry.contentRect.height);
-      if (width === lastHostWidth && height === lastHostHeight) return;
-      lastHostWidth = width;
-      lastHostHeight = height;
-      window.cancelAnimationFrame(resizeFrame);
-      resizeFrame = window.requestAnimationFrame(() => {
-        fit.fit();
-        sendResize();
-      });
-    });
-    resizeObserver.observe(hostRef.current);
-    void restoreTerminalSession();
-    const sessionRefresh = window.setInterval(() => {
-      void listTerminals()
-        .then((listed) => {
-          if (!cancelled) {
-            setSessions((current) =>
-              reconcileTerminalSessions(current, listed),
-            );
-          }
-        })
-        .catch(() => {
-          // The attached terminal transport remains authoritative while a
-          // background list refresh is temporarily unavailable.
-        });
-    }, 5000);
-
-    return () => {
-      cancelled = true;
-      input.dispose();
-      titleChange.dispose();
-      resizeObserver.disconnect();
-      window.cancelAnimationFrame(resizeFrame);
-      window.clearInterval(sessionRefresh);
-      detachTransport();
-      terminal.dispose();
-      terminalRef.current = null;
-      fitRef.current = null;
-    };
-  }, [
-    connect,
-    detachTransport,
-    sendResize,
-    terminalFontFamily,
-    writeTerminalData,
-  ]);
-
-  async function start() {
-    if (!selectedAgentId || !terminalRef.current) return;
-    if (agentAtSessionLimit) {
-      toast.error("Terminal session limit reached", {
-        description: `${selectedAgent ? displayAgentLabel(selectedAgent) : selectedAgentId} already reached the active session limit. Close one before opening another.`,
-      });
-      return;
-    }
-    const previousSession = activeSessionRef.current;
-    detachTransport();
-    if (previousSession) {
-      setSessions((current) =>
-        current.map((item) =>
-          item.terminal_id === previousSession.terminal_id
-            ? { ...item, operator_attached: false }
-            : item,
-        ),
-      );
-    }
-    setConnection("connecting");
-    terminalRef.current.reset();
-    try {
-      fitRef.current?.fit();
-      const created = await createTerminal(
-        selectedAgentId,
-        terminalRef.current.rows,
-        terminalRef.current.cols,
-      );
-      connect(created);
-    } catch (error) {
-      setSession(null);
-      activeSessionRef.current = null;
-      setConnection("idle");
-      toast.error("Could not start terminal", { description: String(error) });
-    }
-  }
-
-  async function activateSession(nextSession: TerminalSession) {
-    if (nextSession.terminal_id === session?.terminal_id) return;
-    if (nextSession.operator_attached) return;
-
-    const previousSession = activeSessionRef.current;
-    detachTransport();
-    if (previousSession) {
-      setSessions((current) =>
-        current.map((item) =>
-          item.terminal_id === previousSession.terminal_id
-            ? { ...item, operator_attached: false }
-            : item,
-        ),
-      );
-    }
-    setSession(null);
-    activeSessionRef.current = null;
-    setConnection("connecting");
-    terminalRef.current?.reset();
-    window.sessionStorage.setItem(
-      REMEMBERED_TERMINAL_KEY,
-      nextSession.terminal_id,
-    );
-
-    try {
-      const attached = await attachTerminal(
-        nextSession.terminal_id,
-        operatorId,
-      );
-      connect(attached);
-    } catch (error) {
-      setConnection("idle");
-      toast.error("Could not attach terminal session", {
-        description: String(error),
-      });
-      void listTerminals()
-        .then((listed) =>
-          setSessions((current) => reconcileTerminalSessions(current, listed)),
-        )
-        .catch(() => undefined);
-    }
-  }
-
-  async function reconnect() {
-    if (!session) return;
-    detachTransport();
-    try {
-      terminalRef.current?.reset();
-      setConnection("connecting");
-      const attached = await attachTerminal(session.terminal_id, operatorId);
-      connect(attached);
-    } catch (error) {
-      setConnection("disconnected");
-      toast.error("Terminal session is no longer available", {
-        description: String(error),
-      });
-    }
-  }
-
-  async function closeSession(closingSession: TerminalSession) {
-    const closingId = closingSession.terminal_id;
-    const closesActiveSession =
-      closingId === activeSessionRef.current?.terminal_id;
-    const remaining = sessions.filter((item) => item.terminal_id !== closingId);
-    const fallback = remaining.find((item) => !item.operator_attached);
-
-    if (closesActiveSession) {
-      if (socketRef.current?.readyState === WebSocket.OPEN) {
-        socketRef.current.send(JSON.stringify({ type: "close" }));
-      }
-      detachTransport();
-    }
-    try {
-      await closeTerminal(closingId);
-    } catch (error) {
-      toast.error("Terminal cleanup failed", { description: String(error) });
-      void listTerminals()
-        .then((listed) =>
-          setSessions((current) => reconcileTerminalSessions(current, listed)),
-        )
-        .catch(() => undefined);
-      return;
-    }
-
-    setSessions((current) =>
-      current.filter((item) => item.terminal_id !== closingId),
-    );
-    setSessionTitles((current) => {
-      const next = { ...current };
-      delete next[closingId];
-      return next;
-    });
-    if (window.sessionStorage.getItem(REMEMBERED_TERMINAL_KEY) === closingId) {
-      window.sessionStorage.removeItem(REMEMBERED_TERMINAL_KEY);
-    }
-    if (closesActiveSession) {
-      setSession(null);
-      activeSessionRef.current = null;
-      setConnection("idle");
-      // xterm.clear() deliberately preserves the active cursor line. Closing
-      // a session should discard its complete screen and terminal modes.
-      terminalRef.current?.reset();
-      if (fallback) void activateSession(fallback);
+      terminalInstance.focus();
    }
  }

@@ -770,13 +141,13 @@ export function TerminalPage({
            )}
            value={selectedAgentId}
            onChange={onSelectAgent}
-            disabled={connection === "connecting"}
+            disabled={terminalSession.connection === "connecting"}
            className="w-full min-w-0 sm:w-64"
          />
        </div>
      </header>

-      {!selectedAgent && connection === "idle" ? (
+      {!selectedAgent && terminalSession.connection === "idle" ? (
        <p className="terminal-notice">
          No connected terminal-capable agent is selected.
        </p>
@@ -791,33 +162,33 @@ export function TerminalPage({
          <TerminalSessionTabs
            agents={agents}
            sessions={sessions}
-            activeTerminalId={session?.terminal_id}
-            connection={connection}
-            sessionTitles={sessionTitles}
+            activeTerminalId={terminalSession.session?.terminal_id}
+            connection={terminalSession.connection}
+            sessionTitles={terminal.sessionTitles}
            nowUnix={nowUnix}
            canRequestStart={canRequestStart}
            agentAtSessionLimit={agentAtSessionLimit}
            selectedAgentSessionLimit={selectedAgentSessionLimit}
-            onActivate={(item) => void activateSession(item)}
-            onClose={(item) => void closeSession(item)}
-            onStart={() => void start()}
+            onActivate={(item) => void terminalSession.activate(item)}
+            onClose={(item) => void terminalSession.close(item)}
+            onStart={start}
          />

          <div className="terminal-frame-actions">
            <Badge
              variant="outline"
              className="terminal-status"
-              data-state={connection}
+              data-state={terminalSession.connection}
            >
              <span aria-hidden />
-              {connection}
+              {terminalSession.connection}
            </Badge>
-            {connection === "disconnected" ? (
+            {terminalSession.connection === "disconnected" ? (
              <Button
                type="button"
                size="sm"
                variant="ghost"
-                onClick={reconnect}
+                onClick={() => void terminalSession.reconnect()}
              >
                <RotateCcw className="size-4" aria-hidden />
                Reconnect
@@ -850,9 +221,9 @@ export function TerminalPage({
                  type="button"
                  size="icon"
                  variant="ghost"
-                  disabled={connection === "idle"}
+                  disabled={terminalSession.connection === "idle"}
                  aria-label="Clear terminal"
-                  onClick={() => terminalRef.current?.clear()}
+                  onClick={terminal.terminal.clear}
                >
                  <Eraser className="size-4" aria-hidden />
                </Button>
@@ -864,20 +235,22 @@ export function TerminalPage({
        {accessoriesOpen ? (
          <TerminalAccessoryBar
            inputReady={terminalInputReady}
-            modifiers={modifiers}
-            fontSize={terminalFontSize}
+            modifiers={terminalSession.modifiers}
+            fontSize={terminal.fontSize}
            onRememberInputFocus={() => {
              terminalInputFocusedBeforeAccessoryRef.current = Boolean(
                hostRef.current?.contains(document.activeElement),
              );
            }}
-            onToggleModifier={toggleModifier}
-            onWriteKey={writeAccessoryKey}
-            onScrollPages={(pages) => terminalRef.current?.scrollPages(pages)}
-            onCopy={() => void copyTerminalText()}
-            onPaste={() => void pasteTerminalText()}
+            onToggleModifier={terminalSession.toggleModifier}
+            onWriteKey={terminalSession.writeAccessoryKey}
+            onScrollPages={terminal.terminal.scrollPages}
+            onCopy={() => void terminal.terminal.copy()}
+            onPaste={() =>
+              void terminal.terminal.paste(terminalSession.writeTerminalData)
+            }
            onToggleKeyboard={toggleTerminalKeyboard}
-            onChangeFontSize={changeTerminalFontSize}
+            onChangeFontSize={terminal.terminal.changeFontSize}
          />
        ) : null}
        <div
@@ -885,7 +258,7 @@ export function TerminalPage({
          ref={hostRef}
          onPointerDown={(event) => {
            if (event.pointerType !== "touch") {
-              terminalRef.current?.focus();
+              terminal.terminal.focus();
              return;
            }
            terminalTouchRef.current = {
@@ -914,7 +287,7 @@ export function TerminalPage({
              !touch.moved &&
              event.pointerType === "touch"
            ) {
-              terminalRef.current?.focus();
+              terminal.terminal.focus();
            }
          }}
          onPointerCancel={() => {
@@ -150,10 +150,14 @@ export function TerminalSessionTabs({
                <button
                  type="button"
                  className="terminal-tab-close"
-                  disabled={locked}
+                  disabled={locked || connection === "connecting"}
                  aria-label={`Close ${agentLabel} terminal session`}
                  title={
-                    locked ? "Attached in another browser" : "Close session"
+                    locked
+                      ? "Attached in another browser"
+                      : connection === "connecting"
+                        ? "Connecting — wait before closing"
+                        : "Close session"
                  }
                  onClick={() => onClose(item)}
                >
@@ -0,0 +1,434 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+
+import {
+  APIError,
+  attachTerminal,
+  closeTerminal,
+  createTerminal,
+  type TerminalSession,
+} from "@/api";
+import {
+  NO_TERMINAL_MODIFIERS,
+  applyTerminalModifiers,
+  orderTerminalSessions,
+  restoreCandidates,
+  type TerminalConnectionState,
+  type TerminalModifiers,
+} from "@/pages/terminal/sessionUtils";
+import type { TerminalCatalog } from "@/pages/terminal/useTerminalSessions";
+import type { TerminalPort } from "@/pages/terminal/useXterm";
+
+const REMEMBERED_TERMINAL_KEY = "wakey.active-terminal-id";
+const TERMINAL_OPERATOR_KEY = "wakey.terminal-operator-id";
+
+// Fallback for browsers that do not implement crypto.randomUUID().
+const randomId = () =>
+  (String(1e7) + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, (c: string) => {
+    const num = Number(c);
+    return (
+      num ^
+      (window.crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (num / 4)))
+    ).toString(16);
+  });
+
+function terminalOperatorId(): string {
+  const remembered = window.sessionStorage.getItem(TERMINAL_OPERATOR_KEY);
+  if (remembered) return remembered;
+  const created = window.crypto.randomUUID?.() ?? randomId();
+  window.sessionStorage.setItem(TERMINAL_OPERATOR_KEY, created);
+  return created;
+}
+
+function websocketUrl(path: string): string {
+  const scheme = window.location.protocol === "https:" ? "wss:" : "ws:";
+  return `${scheme}//${window.location.host}${path}`;
+}
+
+type Options = {
+  terminal: TerminalPort;
+  catalog: TerminalCatalog;
+  selectedAgentId: string;
+};
+
+export function useTerminalSession({
+  terminal,
+  catalog,
+  selectedAgentId,
+}: Options) {
+  const socketRef = useRef<WebSocket | null>(null);
+  const activeSessionRef = useRef<TerminalSession | null>(null);
+  const mountedRef = useRef(false);
+  const selectedAgentIdRef = useRef(selectedAgentId);
+  const catalogRef = useRef(catalog);
+  const [session, setSession] = useState<TerminalSession | null>(null);
+  const [connection, setConnection] = useState<TerminalConnectionState>("idle");
+  const [modifiers, setModifiers] = useState<TerminalModifiers>(
+    NO_TERMINAL_MODIFIERS,
+  );
+  const [operatorId] = useState(terminalOperatorId);
+
+  selectedAgentIdRef.current = selectedAgentId;
+  catalogRef.current = catalog;
+  activeSessionRef.current = session;
+
+  const detachTransport = useCallback(() => {
+    const socket = socketRef.current;
+    socketRef.current = null;
+    socket?.close();
+  }, []);
+
+  const writeTerminalData = useCallback(
+    (data: string, consumeModifiers = false) => {
+      const socket = socketRef.current;
+      if (socket?.readyState !== WebSocket.OPEN) return;
+      const output = consumeModifiers
+        ? applyTerminalModifiers(data, modifiersRef.current)
+        : data;
+      socket.send(new TextEncoder().encode(output));
+      if (
+        consumeModifiers &&
+        (modifiersRef.current.ctrl || modifiersRef.current.meta)
+      ) {
+        modifiersRef.current = NO_TERMINAL_MODIFIERS;
+        setModifiers(NO_TERMINAL_MODIFIERS);
+      }
+    },
+    [],
+  );
+
+  const modifiersRef = useRef(modifiers);
+  modifiersRef.current = modifiers;
+
+  const connect = useCallback(
+    (nextSession: TerminalSession) => {
+      if (!nextSession.attachment_token) {
+        throw new Error(
+          "Control plane did not issue a terminal attachment token",
+        );
+      }
+      detachTransport();
+      setSession(nextSession);
+      activeSessionRef.current = nextSession;
+      terminal.setActiveTerminalId(nextSession.terminal_id);
+      catalogRef.current.merge({ ...nextSession, operator_attached: true });
+      window.sessionStorage.setItem(
+        REMEMBERED_TERMINAL_KEY,
+        nextSession.terminal_id,
+      );
+      setConnection("connecting");
+      const socket = new WebSocket(websocketUrl(nextSession.websocket_url));
+      socket.binaryType = "arraybuffer";
+      socketRef.current = socket;
+
+      socket.onopen = () => {
+        if (socketRef.current !== socket) return;
+        socket.send(
+          JSON.stringify({
+            type: "attach",
+            attachment_token: nextSession.attachment_token,
+            operator_id: operatorId,
+          }),
+        );
+        terminal.fit();
+        terminal.sendResize((message) => socket.send(message));
+      };
+      socket.onmessage = (event) => {
+        if (socketRef.current !== socket) return;
+        if (typeof event.data !== "string") {
+          terminal.write(new Uint8Array(event.data as ArrayBuffer));
+          return;
+        }
+        try {
+          const control = JSON.parse(event.data) as {
+            type: string;
+            exit_code?: number | null;
+            message?: string;
+          };
+          if (control.type === "ready") {
+            setConnection("ready");
+            void catalogRef.current.refresh().catch(() => undefined);
+            window.requestAnimationFrame(() => {
+              terminal.fit();
+              terminal.sendResize((message) => socket.send(message), true);
+              terminal.focus();
+            });
+          } else if (control.type === "exited") {
+            setConnection("exited");
+            terminal.writeLine(
+              `\r\n[process exited${control.exit_code == null ? "" : ` ${control.exit_code}`}]`,
+            );
+          } else if (control.type === "error") {
+            setConnection("exited");
+            terminal.writeLine(
+              `\r\n[terminal error: ${control.message ?? "unknown error"}]`,
+            );
+          }
+        } catch {
+          terminal.writeLine("\r\n[invalid terminal control frame]");
+        }
+      };
+      socket.onerror = () => {
+        if (socketRef.current !== socket) return;
+        terminal.writeLine("\r\n[terminal transport error]");
+      };
+      socket.onclose = () => {
+        if (socketRef.current !== socket) return;
+        socketRef.current = null;
+        catalogRef.current.markDetached(nextSession.terminal_id);
+        setConnection((current) =>
+          current === "exited" ? current : "disconnected",
+        );
+        void catalogRef.current.refresh().catch(() => undefined);
+      };
+    },
+    [detachTransport, operatorId, terminal],
+  );
+
+  const activate = useCallback(
+    async (nextSession: TerminalSession) => {
+      if (nextSession.terminal_id === activeSessionRef.current?.terminal_id)
+        return;
+      if (nextSession.operator_attached) return;
+
+      const previousSession = activeSessionRef.current;
+      detachTransport();
+      if (previousSession)
+        catalogRef.current.markDetached(previousSession.terminal_id);
+      setSession(null);
+      activeSessionRef.current = null;
+      terminal.setActiveTerminalId(undefined);
+      setConnection("connecting");
+      terminal.reset();
+      window.sessionStorage.setItem(
+        REMEMBERED_TERMINAL_KEY,
+        nextSession.terminal_id,
+      );
+
+      try {
+        const attached = await attachTerminal(
+          nextSession.terminal_id,
+          operatorId,
+        );
+        if (!mountedRef.current) return;
+        connect(attached);
+      } catch (error) {
+        if (!mountedRef.current) return;
+        setConnection("idle");
+        toast.error("Could not attach terminal session", {
+          description: String(error),
+        });
+        void catalogRef.current.refresh().catch(() => undefined);
+      }
+    },
+    [connect, detachTransport, operatorId, terminal],
+  );
+
+  const start = useCallback(async () => {
+    const dimensions = terminal.dimensions();
+    if (!selectedAgentIdRef.current || !dimensions) return;
+    const previousSession = activeSessionRef.current;
+    detachTransport();
+    if (previousSession)
+      catalogRef.current.markDetached(previousSession.terminal_id);
+    setConnection("connecting");
+    terminal.reset();
+    try {
+      terminal.fit();
+      const fittedDimensions = terminal.dimensions() ?? dimensions;
+      const created = await createTerminal(
+        selectedAgentIdRef.current,
+        fittedDimensions.rows,
+        fittedDimensions.cols,
+      );
+      if (!mountedRef.current) return;
+      connect(created);
+    } catch (error) {
+      if (!mountedRef.current) return;
+      setSession(null);
+      activeSessionRef.current = null;
+      terminal.setActiveTerminalId(undefined);
+      setConnection("idle");
+      toast.error("Could not start terminal", { description: String(error) });
+    }
+  }, [connect, detachTransport, terminal]);
+
+  const reconnect = useCallback(async () => {
+    const currentSession = activeSessionRef.current;
+    if (!currentSession) return;
+    detachTransport();
+    try {
+      terminal.reset();
+      setConnection("connecting");
+      const attached = await attachTerminal(
+        currentSession.terminal_id,
+        operatorId,
+      );
+      if (!mountedRef.current) return;
+      connect(attached);
+    } catch (error) {
+      if (!mountedRef.current) return;
+      setConnection("disconnected");
+      toast.error("Terminal session is no longer available", {
+        description: String(error),
+      });
+    }
+  }, [connect, detachTransport, operatorId, terminal]);
+
+  const close = useCallback(
+    async (closingSession: TerminalSession) => {
+      const closingId = closingSession.terminal_id;
+      const closesActiveSession =
+        closingId === activeSessionRef.current?.terminal_id;
+      const remaining = catalogRef.current
+        .getSessions()
+        .filter((item) => item.terminal_id !== closingId);
+      const fallback = remaining.find((item) => !item.operator_attached);
+
+      if (closesActiveSession) {
+        if (socketRef.current?.readyState === WebSocket.OPEN) {
+          socketRef.current.send(JSON.stringify({ type: "close" }));
+        }
+        detachTransport();
+      }
+      try {
+        await closeTerminal(closingId);
+      } catch (error) {
+        if (!mountedRef.current) return;
+        toast.error("Terminal cleanup failed", { description: String(error) });
+        void catalogRef.current.refresh().catch(() => undefined);
+        return;
+      }
+      if (!mountedRef.current) return;
+
+      catalogRef.current.remove(closingId);
+      terminal.forgetTitle(closingId);
+      if (
+        window.sessionStorage.getItem(REMEMBERED_TERMINAL_KEY) === closingId
+      ) {
+        window.sessionStorage.removeItem(REMEMBERED_TERMINAL_KEY);
+      }
+      if (closesActiveSession) {
+        setSession(null);
+        activeSessionRef.current = null;
+        terminal.setActiveTerminalId(undefined);
+        setConnection("idle");
+        // reset discards the complete screen and terminal modes; clear() does not.
+        terminal.reset();
+        if (fallback) void activate(fallback);
+      }
+    },
+    [activate, detachTransport, terminal],
+  );
+
+  const toggleModifier = useCallback(
+    (modifier: keyof TerminalModifiers) => {
+      setModifiers((current) => {
+        const next = { ...current, [modifier]: !current[modifier] };
+        modifiersRef.current = next;
+        return next;
+      });
+      window.requestAnimationFrame(() => terminal.focus());
+    },
+    [terminal],
+  );
+
+  const writeAccessoryKey = useCallback(
+    (data: string) => {
+      writeTerminalData(data);
+      window.requestAnimationFrame(() => terminal.focus());
+    },
+    [terminal, writeTerminalData],
+  );
+
+  // Transport input/resize subscriptions and restoration begin only once xterm is usable.
+  useEffect(() => {
+    if (!terminal.ready) return;
+    mountedRef.current = true;
+    const input = terminal.onInput((data) => writeTerminalData(data, true));
+    const resize = terminal.onResize(() => {
+      const socket = socketRef.current;
+      if (socket?.readyState === WebSocket.OPEN) {
+        terminal.sendResize((message) => socket.send(message));
+      }
+    });
+
+    let cancelled = false;
+    async function restoreTerminalSession() {
+      try {
+        const listed = await catalogRef.current.refresh();
+        if (cancelled) return;
+        const rememberedId = window.sessionStorage.getItem(
+          REMEMBERED_TERMINAL_KEY,
+        );
+        const candidates = restoreCandidates(
+          orderTerminalSessions(listed),
+          rememberedId,
+          selectedAgentIdRef.current,
+        );
+
+        for (const candidate of candidates) {
+          if (cancelled) return;
+          setConnection("connecting");
+          try {
+            const attached = await attachTerminal(
+              candidate.terminal_id,
+              operatorId,
+            );
+            if (cancelled) return;
+            terminal.reset();
+            connect(attached);
+            return;
+          } catch (error) {
+            if (
+              !(error instanceof APIError) ||
+              error.code !== "terminal_operator_already_attached"
+            ) {
+              throw error;
+            }
+          }
+        }
+        if (!cancelled) setConnection("idle");
+      } catch (error) {
+        if (cancelled) return;
+        setConnection("idle");
+        toast.error("Could not restore terminal session", {
+          description: String(error),
+        });
+      }
+    }
+
+    void restoreTerminalSession();
+    return () => {
+      cancelled = true;
+      mountedRef.current = false;
+      input.dispose();
+      resize.dispose();
+      detachTransport();
+    };
+  }, [
+    terminal.ready,
+    terminal.onInput,
+    terminal.onResize,
+    terminal.reset,
+    terminal.sendResize,
+    terminal,
+    connect,
+    detachTransport,
+    operatorId,
+    writeTerminalData,
+  ]);
+
+  return {
+    session,
+    connection,
+    modifiers,
+    start,
+    activate,
+    reconnect,
+    close,
+    writeTerminalData,
+    writeAccessoryKey,
+    toggleModifier,
+  };
+}
@@ -0,0 +1,157 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { listTerminals, type TerminalSession } from "@/api";
+import {
+  mergeTerminalSession,
+  reconcileTerminalSessions,
+} from "@/pages/terminal/sessionUtils";
+
+function websocketUrl(path: string): string {
+  const scheme = window.location.protocol === "https:" ? "wss:" : "ws:";
+  return `${scheme}//${window.location.host}${path}`;
+}
+
+export function useTerminalSessions() {
+  const [sessions, setSessions] = useState<TerminalSession[]>([]);
+  const sessionsRef = useRef(sessions);
+  const refreshRef = useRef<() => Promise<TerminalSession[]>>(async () => []);
+
+  sessionsRef.current = sessions;
+
+  const refresh = useCallback(() => refreshRef.current(), []);
+  const merge = useCallback((session: TerminalSession) => {
+    setSessions((current) => mergeTerminalSession(current, session));
+  }, []);
+  const markDetached = useCallback((terminalId: string) => {
+    setSessions((current) =>
+      current.map((item) =>
+        item.terminal_id === terminalId
+          ? { ...item, operator_attached: false }
+          : item,
+      ),
+    );
+  }, []);
+  const remove = useCallback((terminalId: string) => {
+    setSessions((current) =>
+      current.filter((item) => item.terminal_id !== terminalId),
+    );
+  }, []);
+  const reconcile = useCallback((listed: TerminalSession[]) => {
+    setSessions((current) => reconcileTerminalSessions(current, listed));
+  }, []);
+  const getSessions = useCallback(() => sessionsRef.current, []);
+
+  // The catalog stream and fallback timer live for the page mount, independent of active sessions.
+  useEffect(() => {
+    let cancelled = false;
+    let refreshInFlight: Promise<TerminalSession[]> | null = null;
+    let refreshRequested = false;
+    let eventsSocket: WebSocket | null = null;
+    let reconnectTimer = 0;
+    let healthyTimer = 0;
+    let reconnectAttempt = 0;
+
+    const refreshSessions = (): Promise<TerminalSession[]> => {
+      if (refreshInFlight) {
+        // Coalesce bursts and fetch again if another invalidation arrives in flight.
+        refreshRequested = true;
+        return refreshInFlight;
+      }
+      refreshInFlight = (async () => {
+        let listed: TerminalSession[] = [];
+        do {
+          refreshRequested = false;
+          listed = await listTerminals();
+          if (!cancelled) {
+            setSessions((current) =>
+              reconcileTerminalSessions(current, listed),
+            );
+          }
+        } while (refreshRequested && !cancelled);
+        return listed;
+      })().finally(() => {
+        refreshInFlight = null;
+        if (refreshRequested && !cancelled) {
+          void refreshSessions().catch(() => undefined);
+        }
+      });
+      return refreshInFlight;
+    };
+
+    refreshRef.current = refreshSessions;
+
+    const connectEvents = () => {
+      if (cancelled) return;
+      const socket = new WebSocket(
+        websocketUrl("/api/v1/control/terminals/events/ws"),
+      );
+      eventsSocket = socket;
+      socket.onmessage = (event) => {
+        if (cancelled || eventsSocket !== socket) return;
+        if (typeof event.data !== "string") return;
+        try {
+          const message = JSON.parse(event.data) as { type?: string };
+          if (message.type === "sessions_changed") {
+            void refreshSessions().catch(() => undefined);
+          }
+        } catch {
+          // Invalidations are hints; the periodic recovery fetch remains active.
+        }
+      };
+      socket.onopen = () => {
+        void refreshSessions().catch(() => undefined);
+        window.clearTimeout(healthyTimer);
+        healthyTimer = window.setTimeout(() => {
+          if (eventsSocket === socket && socket.readyState === WebSocket.OPEN) {
+            reconnectAttempt = 0;
+          }
+        }, 10_000);
+      };
+      socket.onclose = () => {
+        if (cancelled || eventsSocket !== socket) return;
+        window.clearTimeout(healthyTimer);
+        const ceiling = Math.min(500 * 2 ** reconnectAttempt, 12_000);
+        const delay = Math.min(
+          Math.round(ceiling * (0.8 + Math.random() * 0.4)),
+          15_000,
+        );
+        reconnectAttempt = Math.min(reconnectAttempt + 1, 5);
+        reconnectTimer = window.setTimeout(connectEvents, delay);
+      };
+      socket.onerror = () => socket.close();
+    };
+
+    connectEvents();
+    void refreshSessions().catch(() => undefined);
+    const refreshTimer = window.setInterval(() => {
+      void refreshSessions().catch(() => undefined);
+    }, 15_000);
+    const refreshOnFocus = () => {
+      void refreshSessions().catch(() => undefined);
+    };
+    window.addEventListener("focus", refreshOnFocus);
+
+    return () => {
+      cancelled = true;
+      window.clearInterval(refreshTimer);
+      window.removeEventListener("focus", refreshOnFocus);
+      window.clearTimeout(reconnectTimer);
+      window.clearTimeout(healthyTimer);
+      eventsSocket?.close();
+      eventsSocket = null;
+      refreshRef.current = async () => [];
+    };
+  }, []);
+
+  return {
+    sessions,
+    refresh,
+    merge,
+    markDetached,
+    remove,
+    reconcile,
+    getSessions,
+  };
+}
+
+export type TerminalCatalog = ReturnType<typeof useTerminalSessions>;
@@ -0,0 +1,371 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
+import { ClipboardAddon } from "@xterm/addon-clipboard";
+import { FitAddon } from "@xterm/addon-fit";
+import { ImageAddon } from "@xterm/addon-image";
+import { Unicode11Addon } from "@xterm/addon-unicode11";
+import { UnicodeGraphemesAddon } from "@xterm/addon-unicode-graphemes";
+import { WebLinksAddon } from "@xterm/addon-web-links";
+import { Terminal as XTerm } from "@xterm/xterm";
+import { toast } from "sonner";
+
+import {
+  MAX_TERMINAL_FONT_SIZE,
+  MIN_TERMINAL_FONT_SIZE,
+} from "@/pages/terminal/TerminalAccessoryBar";
+import { visibleTerminalText } from "@/pages/terminal/sessionUtils";
+import { loadTerminalFontFamily } from "@/terminal/terminalFonts";
+
+const DEFAULT_TERMINAL_FONT_SIZE = 14;
+
+// Stable behavioral surface shared with session transport and page controls.
+export type TerminalPort = {
+  clear: () => void;
+  copy: () => Promise<void>;
+  dimensions: () => { rows: number; cols: number } | null;
+  forgetTitle: (terminalId: string) => void;
+  fit: () => void;
+  focus: () => void;
+  blurInput: () => void;
+  onInput: (handler: (data: string) => void) => { dispose: () => void };
+  onResize: (handler: () => void) => { dispose: () => void };
+  paste: (write: (data: string) => void) => Promise<void>;
+  reset: () => void;
+  scrollPages: (pages: number) => void;
+  sendResize: (send: (message: string) => void, force?: boolean) => void;
+  changeFontSize: (delta: number) => void;
+  setActiveTerminalId: (terminalId: string | undefined) => void;
+  write: (data: Uint8Array) => void;
+  writeLine: (line: string) => void;
+  ready: boolean;
+};
+
+type Options = {
+  pageRef: RefObject<HTMLElement | null>;
+  hostRef: RefObject<HTMLDivElement | null>;
+};
+
+export function useXterm({ pageRef, hostRef }: Options) {
+  const terminalRef = useRef<XTerm | null>(null);
+  const fitRef = useRef<FitAddon | null>(null);
+  const activeTerminalIdRef = useRef<string | undefined>(undefined);
+  const lastSizeRef = useRef({ rows: 0, cols: 0 });
+  const resizeListenersRef = useRef(new Set<() => void>());
+  const [fontFamily, setFontFamily] = useState<string>();
+  const [ready, setReady] = useState(false);
+  const [fontSize, setFontSize] = useState(DEFAULT_TERMINAL_FONT_SIZE);
+  const [sessionTitles, setSessionTitles] = useState<Record<string, string>>(
+    {},
+  );
+
+  const setActiveTerminalId = useCallback((terminalId: string | undefined) => {
+    activeTerminalIdRef.current = terminalId;
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    void loadTerminalFontFamily().then((loadedFontFamily) => {
+      if (!cancelled) setFontFamily(loadedFontFamily);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  useEffect(() => {
+    const viewport = window.visualViewport;
+    const updateViewportHeight = () => {
+      const height = Math.round(viewport?.height ?? window.innerHeight);
+      pageRef.current?.style.setProperty(
+        "--terminal-visual-viewport-height",
+        `${height}px`,
+      );
+    };
+    updateViewportHeight();
+    viewport?.addEventListener("resize", updateViewportHeight);
+    viewport?.addEventListener("scroll", updateViewportHeight);
+    window.addEventListener("resize", updateViewportHeight);
+    return () => {
+      viewport?.removeEventListener("resize", updateViewportHeight);
+      viewport?.removeEventListener("scroll", updateViewportHeight);
+      window.removeEventListener("resize", updateViewportHeight);
+    };
+  }, [pageRef]);
+
+  const sendResize = useCallback(
+    (send: (message: string) => void, force = false) => {
+      const terminal = terminalRef.current;
+      if (!terminal) return;
+      if (
+        !force &&
+        lastSizeRef.current.rows === terminal.rows &&
+        lastSizeRef.current.cols === terminal.cols
+      ) {
+        return;
+      }
+      lastSizeRef.current = { rows: terminal.rows, cols: terminal.cols };
+      send(
+        JSON.stringify({
+          type: "resize",
+          rows: terminal.rows,
+          cols: terminal.cols,
+        }),
+      );
+    },
+    [],
+  );
+
+  const fit = useCallback(() => fitRef.current?.fit(), []);
+  const focus = useCallback(() => terminalRef.current?.focus(), []);
+  const blurInput = useCallback(
+    () => terminalRef.current?.textarea?.blur(),
+    [],
+  );
+  const reset = useCallback(() => terminalRef.current?.reset(), []);
+  const clear = useCallback(() => terminalRef.current?.clear(), []);
+  const write = useCallback(
+    (data: Uint8Array) => terminalRef.current?.write(data),
+    [],
+  );
+  const writeLine = useCallback(
+    (line: string) => terminalRef.current?.writeln(line),
+    [],
+  );
+  const dimensions = useCallback(() => {
+    const terminal = terminalRef.current;
+    return terminal ? { rows: terminal.rows, cols: terminal.cols } : null;
+  }, []);
+  const forgetTitle = useCallback((terminalId: string) => {
+    setSessionTitles((current) => {
+      if (!(terminalId in current)) return current;
+      const next = { ...current };
+      delete next[terminalId];
+      return next;
+    });
+  }, []);
+  const onInput = useCallback(
+    (handler: (data: string) => void) =>
+      terminalRef.current?.onData(handler) ?? { dispose: () => {} },
+    [],
+  );
+  const onResize = useCallback((handler: () => void) => {
+    resizeListenersRef.current.add(handler);
+    return { dispose: () => resizeListenersRef.current.delete(handler) };
+  }, []);
+  const scrollPages = useCallback(
+    (pages: number) => terminalRef.current?.scrollPages(pages),
+    [],
+  );
+  const copy = useCallback(async () => {
+    const terminal = terminalRef.current;
+    if (!terminal) return;
+    const text = terminal.hasSelection()
+      ? terminal.getSelection()
+      : visibleTerminalText(terminal);
+    if (!text) {
+      toast.info("Nothing to copy");
+      return;
+    }
+    if (!navigator.clipboard) {
+      toast.error("Clipboard access requires HTTPS or localhost");
+      return;
+    }
+    try {
+      await navigator.clipboard.writeText(text);
+      toast.success(
+        terminal.hasSelection() ? "Selection copied" : "Visible screen copied",
+      );
+    } catch (error) {
+      toast.error("Clipboard access was denied", {
+        description: String(error),
+      });
+    }
+  }, []);
+  const paste = useCallback(async (writeData: (data: string) => void) => {
+    if (!navigator.clipboard) {
+      toast.error("Clipboard access requires HTTPS or localhost");
+      return;
+    }
+    try {
+      const text = await navigator.clipboard.readText();
+      if (text) writeData(text);
+      terminalRef.current?.focus();
+    } catch (error) {
+      toast.error("Clipboard access was denied", {
+        description: String(error),
+      });
+    }
+  }, []);
+  const changeFontSize = useCallback((delta: number) => {
+    const terminal = terminalRef.current;
+    if (!terminal) return;
+    const current = terminal.options.fontSize ?? DEFAULT_TERMINAL_FONT_SIZE;
+    const next = Math.min(
+      MAX_TERMINAL_FONT_SIZE,
+      Math.max(MIN_TERMINAL_FONT_SIZE, current + delta),
+    );
+    if (next === current) return;
+    terminal.options.fontSize = next;
+    setFontSize(next);
+    window.requestAnimationFrame(() => {
+      fitRef.current?.fit();
+      resizeListenersRef.current.forEach((handler) => handler());
+    });
+  }, []);
+
+  // Wait for the font before creating xterm; this effect owns the instance and its observers.
+  useEffect(() => {
+    if (!hostRef.current || !fontFamily) return;
+    const terminal = new XTerm({
+      cursorBlink: true,
+      convertEol: false,
+      fontFamily,
+      fontSize: DEFAULT_TERMINAL_FONT_SIZE,
+      lineHeight: 1.1,
+      scrollbar: {
+        width: window.matchMedia("(pointer: coarse)").matches ? 22 : 16,
+      },
+      scrollback: 10_000,
+      theme: {
+        background: "#0b1117",
+        foreground: "#e5e7eb",
+        cursor: "#6ee7a8",
+        scrollbarSliderBackground: "#52617099",
+        scrollbarSliderHoverBackground: "#6b7c8dcc",
+        scrollbarSliderActiveBackground: "#8294a6",
+      },
+      allowProposedApi: true,
+    });
+    terminal.loadAddon(new Unicode11Addon());
+    terminal.unicode.activeVersion = "11";
+    terminal.loadAddon(new UnicodeGraphemesAddon());
+    terminal.loadAddon(new WebLinksAddon());
+    terminal.loadAddon(new ImageAddon({}));
+    const fitAddon = new FitAddon();
+    terminal.loadAddon(new ClipboardAddon());
+    terminal.loadAddon(fitAddon);
+    terminal.open(hostRef.current);
+    terminal.attachCustomKeyEventHandler((event) => {
+      const copiesTerminalSelection =
+        event.type === "keydown" &&
+        event.ctrlKey &&
+        event.shiftKey &&
+        event.code === "KeyC";
+      if (!copiesTerminalSelection) return true;
+      event.preventDefault();
+      event.stopPropagation();
+      if (terminal.hasSelection()) {
+        if (!navigator.clipboard) {
+          toast.error("Clipboard access requires HTTPS or localhost");
+        } else {
+          void navigator.clipboard
+            .writeText(terminal.getSelection())
+            .catch((error) =>
+              toast.error("Clipboard access was denied", {
+                description: String(error),
+              }),
+            );
+        }
+      }
+      return false;
+    });
+    const titleChange = terminal.onTitleChange((title) => {
+      const terminalId = activeTerminalIdRef.current;
+      if (!terminalId) return;
+      const normalized = title.trim();
+      setSessionTitles((current) => {
+        if (current[terminalId] === normalized) return current;
+        if (!normalized) {
+          const next = { ...current };
+          delete next[terminalId];
+          return next;
+        }
+        return { ...current, [terminalId]: normalized };
+      });
+    });
+    fitAddon.fit();
+    // Consumers subscribe only after this transition; the port methods stay stable.
+    terminalRef.current = terminal;
+    fitRef.current = fitAddon;
+    setReady(true);
+
+    let resizeFrame = 0;
+    let lastHostWidth = 0;
+    let lastHostHeight = 0;
+    const resizeObserver = new ResizeObserver(([entry]) => {
+      const width = Math.round(entry.contentRect.width);
+      const height = Math.round(entry.contentRect.height);
+      if (width === lastHostWidth && height === lastHostHeight) return;
+      lastHostWidth = width;
+      lastHostHeight = height;
+      window.cancelAnimationFrame(resizeFrame);
+      resizeFrame = window.requestAnimationFrame(() => {
+        fitAddon.fit();
+        resizeListenersRef.current.forEach((handler) => handler());
+      });
+    });
+    resizeObserver.observe(hostRef.current);
+
+    return () => {
+      titleChange.dispose();
+      resizeObserver.disconnect();
+      resizeListenersRef.current.clear();
+      window.cancelAnimationFrame(resizeFrame);
+      terminal.dispose();
+      terminalRef.current = null;
+      fitRef.current = null;
+      setReady(false);
+    };
+  }, [fontFamily, hostRef]);
+
+  const terminal = useMemo<TerminalPort>(
+    () => ({
+      clear,
+      copy,
+      dimensions,
+      forgetTitle,
+      fit,
+      focus,
+      blurInput,
+      onInput,
+      onResize,
+      paste,
+      reset,
+      scrollPages,
+      sendResize,
+      changeFontSize,
+      setActiveTerminalId,
+      write,
+      writeLine,
+      ready,
+    }),
+    [
+      clear,
+      copy,
+      dimensions,
+      forgetTitle,
+      fit,
+      focus,
+      blurInput,
+      onInput,
+      onResize,
+      paste,
+      reset,
+      scrollPages,
+      sendResize,
+      changeFontSize,
+      setActiveTerminalId,
+      write,
+      writeLine,
+      ready,
+    ],
+  );
+
+  return { terminal, fontSize, sessionTitles };
+}
@@ -1,6 +1,6 @@
 [package]
 name = "wakey-agent"
-version = "0.3.5"
+version = "0.3.6"
 edition = "2024"
 publish = ["gitea"]

@@ -109,6 +109,10 @@ impl RelayOutputBuffer {
            self.snapshot_pending = false;
        }
    }
+
+    fn live_sender(&self) -> Option<mpsc::Sender<Message>> {
+        self.sender.clone()
+    }
 }

 impl TerminalState {
@@ -465,12 +469,12 @@ async fn run_terminal(
        None => terminate_process_group(&mut child, process_group).await?,
    };
    if relay_output.is_connected() {
-        let control = TerminalControl::Exited {
+        let exit_frame = serde_json::to_string(&TerminalControl::Exited {
            exit_code: status.code(),
-        };
-        if let Ok(text) = serde_json::to_string(&control) {
-            relay_output.queue_frame(Message::Text(text.into()));
-        }
+        })
+        .ok()
+        .map(|text| Message::Text(text.into()));
+        flush_relay_output(&mut relay_output, exit_frame, PTY_EXIT_DRAIN_TIMEOUT).await;
    }
    info!(terminal_id = %terminal_id, exit_code = ?status.code(), requested_close, ttl_expired, "terminal worker exited");
    Ok(())
@@ -518,7 +522,7 @@ async fn run_terminal_relay(relay: RelayConnection) -> Result<()> {
    let (stream, _) = tokio_tungstenite::connect_async(ws_url.as_str())
        .await
        .context("failed to connect terminal relay websocket")?;
-    let (mut sink, mut source) = stream.split();
+    let (mut sink, source) = stream.split();
    send_json(
        &mut sink,
        &TerminalAgentHandshake::Auth {
@@ -537,40 +541,61 @@ async fn run_terminal_relay(relay: RelayConnection) -> Result<()> {
        .await
        .map_err(|_| anyhow::anyhow!("terminal worker stopped"))?;

-    let mut output = relay.output_rx;
+    relay_loop(source, sink, relay.input, relay.generation, relay.output_rx).await
+}
+
+async fn relay_loop<S, St>(
+    mut source: St,
+    mut sink: S,
+    input: mpsc::Sender<RelayInput>,
+    generation: u64,
+    mut output: mpsc::Receiver<Message>,
+) -> Result<()>
+where
+    S: futures_util::Sink<Message, Error = tokio_tungstenite::tungstenite::Error> + Unpin,
+    St: futures_util::Stream<
+            Item = std::result::Result<Message, tokio_tungstenite::tungstenite::Error>,
+        > + Unpin,
+{
+    let mut worker_stopped = false;
+    let mut worker_stop_deadline: Option<tokio::time::Instant> = None;
+    // Reserve at most one control so a full worker queue cannot block output.
+    let mut pending_input = None;
+    let mut close_after_input = false;
    loop {
        tokio::select! {
            biased;
-            incoming = source.next() => {
+            _ = async {
+                match worker_stop_deadline {
+                    Some(deadline) => tokio::time::sleep_until(deadline).await,
+                    None => std::future::pending().await,
+                }
+            } => break,
+            incoming = source.next(), if !worker_stopped && pending_input.is_none() => {
                let Some(message) = incoming else { break; };
                match message.context("terminal relay websocket receive failed")? {
                    Message::Binary(bytes) => {
-                        relay.input.send(RelayInput::Binary {
-                            generation: relay.generation,
+                        pending_input = Some(RelayInput::Binary {
+                            generation,
                            bytes: bytes.to_vec(),
-                        }).await.map_err(|_| anyhow::anyhow!("terminal worker stopped"))?;
+                        });
                    }
                    Message::Text(text) => match serde_json::from_str::<TerminalControl>(&text)
                        .context("invalid terminal control frame")?
                    {
                        TerminalControl::Resize { rows, cols } => {
-                            relay.input.send(RelayInput::Resize {
-                                generation: relay.generation,
+                            pending_input = Some(RelayInput::Resize {
+                                generation,
                                rows,
                                cols,
-                            }).await
-                                .map_err(|_| anyhow::anyhow!("terminal worker stopped"))?;
+                            });
                        }
                        TerminalControl::Snapshot => {
-                            relay.input.send(RelayInput::Snapshot {
-                                generation: relay.generation,
-                            }).await.map_err(|_| anyhow::anyhow!("terminal worker stopped"))?;
+                            pending_input = Some(RelayInput::Snapshot { generation });
                        }
                        TerminalControl::Close => {
-                            let _ = relay.input.send(RelayInput::Close {
-                                generation: relay.generation,
-                            }).await;
-                            break;
+                            pending_input = Some(RelayInput::Close { generation });
+                            close_after_input = true;
                        }
                        _ => anyhow::bail!("terminal control frame has invalid direction"),
                    },
@@ -582,9 +607,32 @@ async fn run_terminal_relay(relay: RelayConnection) -> Result<()> {
                    Message::Frame(_) => {}
                }
            }
+            permit = input.reserve(), if !worker_stopped && pending_input.is_some() => {
+                match permit {
+                    Ok(permit) => {
+                        permit.send(pending_input.take().expect("pending terminal input"));
+                        if close_after_input {
+                            break;
+                        }
+                    }
+                    Err(_) => {
+                        worker_stopped = true;
+                        pending_input = None;
+                        worker_stop_deadline =
+                            Some(tokio::time::Instant::now() + PTY_EXIT_DRAIN_TIMEOUT);
+                    }
+                }
+            }
            outgoing = output.recv() => {
                let Some(message) = outgoing else { break; };
-                sink.send(message).await.context("failed to send terminal relay output")?;
+                if let Some(deadline) = worker_stop_deadline {
+                    tokio::time::timeout_at(deadline, sink.send(message))
+                        .await
+                        .context("terminal relay output drain timed out")?
+                        .context("failed to send terminal relay output")?;
+                } else {
+                    sink.send(message).await.context("failed to send terminal relay output")?;
+                }
            }
        }
    }
@@ -600,6 +648,43 @@ async fn reserve_relay_output(
    }
 }

+/// Flushes frames the select loop left pending, then sends the exit lifecycle
+/// frame behind them, bounded by `deadline`: a relay that stays saturated past
+/// it drops the backlog rather than holding worker shutdown open. Queuing the
+/// exit frame without this would drop it together with the pending buffer when
+/// the worker returns.
+async fn flush_relay_output(
+    relay_output: &mut RelayOutputBuffer,
+    exit_frame: Option<Message>,
+    deadline: Duration,
+) {
+    let _ = tokio::time::timeout(deadline, async {
+        while relay_output.has_pending() {
+            let sender = relay_output.pending_sender();
+            match reserve_relay_output(sender).await {
+                Ok(permit) => relay_output.send_reserved(permit),
+                Err(()) => {
+                    relay_output.disconnect();
+                    return;
+                }
+            }
+        }
+        let Some(frame) = exit_frame else {
+            return;
+        };
+        let sender = relay_output
+            .pending_sender()
+            .or_else(|| relay_output.live_sender());
+        match reserve_relay_output(sender).await {
+            Ok(permit) => {
+                permit.send(frame);
+            }
+            Err(()) => relay_output.disconnect(),
+        }
+    })
+    .await;
+}
+
 #[cfg(not(unix))]
 async fn run_terminal(
    _config: &AgentConfig,
@@ -786,6 +871,102 @@ mod tests {
        );
    }

+    #[tokio::test]
+    async fn exit_frame_is_delivered_after_saturated_relay_drains() {
+        let (tx, mut rx) = mpsc::channel(RELAY_OUTPUT_QUEUE);
+        let mut relay_output = RelayOutputBuffer::default();
+        relay_output.connect(tx);
+
+        let total = RELAY_OUTPUT_QUEUE * 2;
+        for i in 0..total {
+            relay_output.queue_frame(Message::Text(format!("out-{i}").into()));
+        }
+        assert!(relay_output.has_pending());
+
+        let collected = tokio::spawn(async move {
+            let mut frames = Vec::new();
+            while let Some(frame) = rx.recv().await {
+                frames.push(frame);
+            }
+            frames
+        });
+
+        let exit_frame = serde_json::to_string(&TerminalControl::Exited { exit_code: Some(0) })
+            .expect("exit frame encodes");
+        flush_relay_output(
+            &mut relay_output,
+            Some(Message::Text(exit_frame.clone().into())),
+            PTY_EXIT_DRAIN_TIMEOUT,
+        )
+        .await;
+        relay_output.disconnect();
+
+        let mut frames = collected.await.expect("relay reader completes");
+        assert_eq!(frames.len(), total + 1);
+        let Some(Message::Text(last)) = frames.pop() else {
+            panic!("last frame should be the exit control frame");
+        };
+        assert_eq!(last.as_str(), exit_frame);
+        for (i, frame) in frames.iter().enumerate() {
+            let Message::Text(payload) = frame else {
+                panic!("expected text frame at position {i}, got {frame:?}");
+            };
+            assert_eq!(payload.as_str(), format!("out-{i}"));
+        }
+    }
+
+    #[tokio::test]
+    async fn relay_drains_final_output_after_worker_stops_during_concurrent_controls() {
+        let (input, input_rx) = mpsc::channel(RELAY_INPUT_QUEUE);
+        drop(input_rx);
+        let (output_tx, output_rx) = mpsc::channel(RELAY_OUTPUT_QUEUE);
+        output_tx
+            .send(Message::Binary(vec![1, 2, 3].into()))
+            .await
+            .expect("live output queues");
+        let exit_frame = serde_json::to_string(&TerminalControl::Exited { exit_code: Some(0) })
+            .expect("exit frame encodes");
+        output_tx
+            .send(Message::Text(exit_frame.clone().into()))
+            .await
+            .expect("exit output queues");
+        drop(output_tx);
+
+        let source = futures_util::stream::iter([
+            Ok(Message::Binary(vec![4].into())),
+            Ok(Message::Text(
+                serde_json::to_string(&TerminalControl::Resize {
+                    rows: 30,
+                    cols: 100,
+                })
+                .expect("resize encodes")
+                .into(),
+            )),
+            Ok(Message::Text(
+                serde_json::to_string(&TerminalControl::Snapshot)
+                    .expect("snapshot encodes")
+                    .into(),
+            )),
+        ]);
+        let delivered = Arc::new(Mutex::new(Vec::new()));
+        let sink = futures_util::sink::unfold(delivered.clone(), |delivered, frame| async move {
+            delivered.lock().expect("delivered frames").push(frame);
+            Ok::<_, tokio_tungstenite::tungstenite::Error>(delivered)
+        });
+
+        relay_loop(source, Box::pin(sink), input, 7, output_rx)
+            .await
+            .expect("relay drains after worker completion");
+
+        let delivered = delivered.lock().expect("delivered frames");
+        assert_eq!(delivered.len(), 2);
+        assert_eq!(delivered[0].clone().into_data(), vec![1, 2, 3]);
+        let Message::Text(exit) = &delivered[1] else {
+            panic!("exit control should follow final bytes");
+        };
+        assert_eq!(exit.as_str(), exit_frame);
+    }
+
    #[test]
    fn open_rejects_invalid_initial_size_before_spawning() {
        let mut config = crate::config::DEFAULT_CONFIG.clone();
@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO audit_events\n             (event_key, event_id, ts_unix, actor_type, actor_id, agent_id, request_id,\n              event_type, outcome, latency_ms, message, metadata_json)\n             VALUES (?1, ?2, ?3, 'test', NULL, NULL, NULL, 'test', 'ok', NULL, 'old', '{}')",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "6ce45cc94cbfdd948aad5fb986f9b5976c79bb63759bc9ecff1a7873e2d70137"
+}
@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT COUNT(*) FROM alert_transitions WHERE transition_id = ?1",
+  "describe": {
+    "columns": [
+      {
+        "name": "COUNT(*)",
+        "ordinal": 0,
+        "type_info": "Integer"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "b324587b94ee2e98dc8eff5f6735303a2784b74f49068ce8e946cedcd8d12c4e"
+}
@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT COUNT(*) FROM audit_events WHERE message = ?1",
+  "describe": {
+    "columns": [
+      {
+        "name": "COUNT(*)",
+        "ordinal": 0,
+        "type_info": "Integer"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "bd1666cea8840df04ddcdc8a0c42b9b7771f9bf63c45613c4b6f8b86be479d70"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM audit_events WHERE ts_unix < ?1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "ca612fee8c80f815b33dbc088cc7e0a7552f1f4e38390959e14ea5cc765bf2c7"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM alert_transitions WHERE ts_unix < ?1",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "ce850a32c8702595bbc3207bf86d53209c48be145562192b3a8f84903d39eac1"
+}
@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT COUNT(*) FROM audit_events WHERE event_id = ?1",
+  "describe": {
+    "columns": [
+      {
+        "name": "COUNT(*)",
+        "ordinal": 0,
+        "type_info": "Integer"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "dc7056b7421dcc83648cbd360273ebcce1156ce0f7da2d39f054025ab9b66b6b"
+}
@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO alert_transitions\n             (transition_key, transition_id, ts_unix, alert_id, kind, agent_id,\n              from_status, to_status, message, metadata_json)\n             VALUES (?1, ?2, ?3, 'alert-old', 'test', NULL, NULL, 'active', 'old', '{}')",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "e83a43217a3bfaacd2f5e76df1fd05447558646fb2b47963751a7ab53b3a99b6"
+}
@@ -1,6 +1,6 @@
 [package]
 name = "wakey-control-plane"
-version = "0.3.5"
+version = "0.3.6"
 edition = "2024"
 publish = ["gitea"]

@@ -1,4 +1,5 @@
 use std::collections::{BTreeMap, HashSet};
+use std::sync::Arc;
 use std::time::{SystemTime, UNIX_EPOCH};

 use axum::Json;
@@ -7,12 +8,14 @@ use axum::extract::{Query, State};
 use axum::http::StatusCode;
 use axum::response::IntoResponse;
 use serde::Deserialize;
+use tokio::select;
+use tokio::sync::{RwLock, broadcast};
 use tokio::time::Duration;
 use tracing::warn;

 use crate::api::ApiError;
 use crate::runtime::AppState;
-use crate::state::{AlertState, AuditEvent, AuditEventFilter};
+use crate::state::{AlertState, AlertTransition, AuditEvent, AuditEventFilter};

 struct AlertBuildContext<'a> {
    now_unix: u64,
@@ -26,21 +29,14 @@ struct AlertBuildContext<'a> {
    enroll_rejected_threshold: u64,
 }

-#[derive(Debug, Deserialize)]
-pub struct ActiveAlertsQuery {
-    pub lookback_seconds: Option<u64>,
-    pub timeout_threshold: Option<u64>,
-    pub auth_rejected_threshold: Option<u64>,
-    pub enroll_rejected_threshold: Option<u64>,
-}
-
 #[derive(Debug, Deserialize)]
 pub struct AlertHistoryQuery {
    pub since_unix: Option<u64>,
    pub limit: Option<usize>,
 }

-#[derive(Debug, Deserialize, Clone)]
+#[derive(Debug, Clone, Deserialize)]
+#[serde(default)]
 pub struct AlertRuleConfig {
    pub lookback_seconds: Option<u64>,
    pub timeout_threshold: Option<u64>,
@@ -48,25 +44,255 @@ pub struct AlertRuleConfig {
    pub enroll_rejected_threshold: Option<u64>,
 }

-pub async fn active_alerts(
-    State(state): State<AppState>,
-    Query(query): Query<ActiveAlertsQuery>,
-) -> Result<impl IntoResponse, ApiError> {
-    let alerts = evaluate_alerts(
-        &state,
-        AlertRuleConfig {
-            lookback_seconds: query.lookback_seconds,
-            timeout_threshold: query.timeout_threshold,
-            auth_rejected_threshold: query.auth_rejected_threshold,
-            enroll_rejected_threshold: query.enroll_rejected_threshold,
-        },
-    )
-    .await?;
+impl Default for AlertRuleConfig {
+    fn default() -> Self {
+        Self {
+            lookback_seconds: Some(900),
+            timeout_threshold: Some(3),
+            auth_rejected_threshold: Some(3),
+            enroll_rejected_threshold: Some(5),
+        }
+    }
+}

-    if let Err(err) = state.store.sync_alert_transitions(&alerts).await {
-        warn!(error = %err, "failed to sync alert transitions");
+impl AlertRuleConfig {
+    fn validate(&self) -> Result<(), ApiError> {
+        let defaults = Self::default();
+        let overrides = [
+            (
+                "lookback_seconds",
+                self.lookback_seconds,
+                defaults.lookback_seconds,
+            ),
+            (
+                "timeout_threshold",
+                self.timeout_threshold,
+                defaults.timeout_threshold,
+            ),
+            (
+                "auth_rejected_threshold",
+                self.auth_rejected_threshold,
+                defaults.auth_rejected_threshold,
+            ),
+            (
+                "enroll_rejected_threshold",
+                self.enroll_rejected_threshold,
+                defaults.enroll_rejected_threshold,
+            ),
+        ];
+        if let Some((field, _, _)) = overrides
+            .into_iter()
+            .find(|(_, requested, default)| requested.is_some() && requested != default)
+        {
+            return Err(ApiError::new(
+                StatusCode::BAD_REQUEST,
+                "unsupported_alert_override",
+                format!("custom alert {field} is not supported; omit it or use its default value"),
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[derive(Clone, Default)]
+pub struct AlertsSnapshot {
+    pub ts_unix: u64,
+    pub alerts: Vec<AlertState>,
+    pub recent_transitions: Vec<AlertTransition>,
+}
+
+/// Holds the latest alert snapshot computed by the background evaluator and
+/// broadcasts each new snapshot to connected `alerts/ws` subscribers.
+#[derive(Clone)]
+pub struct AlertsHub {
+    tx: broadcast::Sender<String>,
+    status: Arc<RwLock<HubStatus>>,
+}
+
+#[derive(Default)]
+struct HubStatus {
+    latest_payload: Option<String>,
+    latest_alerts: Vec<AlertState>,
+    last_success_unix: Option<u64>,
+    failure: Option<String>,
+    last_health_available: Option<bool>,
+}
+
+const ALERT_SNAPSHOT_MAX_AGE_SECS: u64 = 15;
+
+impl Default for AlertsHub {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl AlertsHub {
+    pub fn new() -> Self {
+        let (tx, _) = broadcast::channel(16);
+        Self {
+            tx,
+            status: Arc::new(RwLock::new(HubStatus::default())),
+        }
    }

+    pub fn subscribe(&self) -> broadcast::Receiver<String> {
+        self.tx.subscribe()
+    }
+
+    pub async fn latest_alerts(&self) -> Vec<AlertState> {
+        self.status.read().await.latest_alerts.clone()
+    }
+
+    async fn mark_unavailable(&self, reason: impl Into<String>) {
+        let mut status = self.status.write().await;
+        if status.failure.is_some() {
+            return;
+        }
+        status.failure = Some(reason.into());
+        let reason = status.failure.as_deref().unwrap_or_default().to_owned();
+        status.last_health_available = Some(false);
+        self.broadcast_health(false, Some(reason));
+    }
+
+    async fn unavailable_reason(&self) -> Option<String> {
+        let status = self.status.read().await;
+        evaluator_unavailable_reason(&status, now_unix())
+    }
+
+    async fn resync_payloads(&self) -> (String, Option<String>) {
+        let status = self.status.read().await;
+        (
+            encode_health(evaluator_unavailable_reason(&status, now_unix())),
+            status.latest_payload.clone(),
+        )
+    }
+
+    async fn broadcast_health_if_changed(&self) {
+        let mut status = self.status.write().await;
+        if status.last_success_unix.is_none() || status.failure.is_some() {
+            return;
+        }
+        let reason = evaluator_unavailable_reason(&status, now_unix());
+        let available = reason.is_none();
+        if status.last_health_available == Some(available) {
+            return;
+        }
+        status.last_health_available = Some(available);
+        self.broadcast_health(available, reason);
+    }
+
+    fn broadcast_health(&self, available: bool, reason: Option<String>) {
+        let _ = self.tx.send(encode_health_message(available, reason));
+    }
+
+    pub async fn publish(&self, snapshot: AlertsSnapshot) {
+        let payload = serde_json::json!({
+            "type": "alerts_snapshot",
+            "ts_unix": snapshot.ts_unix,
+            "alerts": snapshot.alerts,
+            "recent_transitions": snapshot.recent_transitions,
+        });
+        let Ok(encoded) = serde_json::to_string(&payload) else {
+            warn!("failed to encode alerts snapshot payload");
+            return;
+        };
+        let mut status = self.status.write().await;
+        let was_unavailable = evaluator_unavailable_reason(&status, now_unix()).is_some();
+        status.latest_alerts = snapshot.alerts;
+        status.latest_payload = Some(encoded.clone());
+        status.last_success_unix = Some(snapshot.ts_unix);
+        status.failure = None;
+        let available = evaluator_unavailable_reason(&status, now_unix()).is_none();
+        if available {
+            status.last_health_available = Some(true);
+        }
+        if was_unavailable && available {
+            self.broadcast_health(true, None);
+        }
+        let _ = self.tx.send(encoded);
+    }
+}
+
+fn evaluator_unavailable_reason(status: &HubStatus, now: u64) -> Option<String> {
+    if let Some(failure) = &status.failure {
+        return Some(failure.clone());
+    }
+    match status.last_success_unix {
+        Some(ts) if now.saturating_sub(ts) <= ALERT_SNAPSHOT_MAX_AGE_SECS => None,
+        Some(_) => Some("alert evaluator snapshot is stale".into()),
+        None => Some("alert evaluator has not produced a snapshot yet".into()),
+    }
+}
+
+fn encode_health(reason: Option<String>) -> String {
+    encode_health_message(reason.is_none(), reason)
+}
+
+fn encode_health_message(available: bool, reason: Option<String>) -> String {
+    let mut message = serde_json::json!({
+        "type": "alerts_health",
+        "available": available,
+    });
+    if let Some(reason) = reason {
+        message["reason"] = serde_json::Value::String(reason);
+    }
+    message.to_string()
+}
+
+/// Background task that owns alert evaluation: on a fixed ticker it recomputes
+/// the snapshot, persists transitions, and publishes to subscribers so neither
+/// the GET endpoint nor individual WS clients evaluate alerts themselves.
+pub async fn run_alert_evaluator(state: AppState) {
+    let config = AlertRuleConfig::default();
+    let mut tick = tokio::time::interval(Duration::from_secs(5));
+    tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+    loop {
+        tick.tick().await;
+        let alerts = match evaluate_alerts(&state, &config).await {
+            Ok(alerts) => alerts,
+            Err(err) => {
+                warn!(code = %err.code, "failed to evaluate alerts in background task");
+                state.alerts.mark_unavailable(err.message.clone()).await;
+                continue;
+            }
+        };
+
+        if let Err(err) = state.store.sync_alert_transitions(&alerts).await {
+            warn!(error = %err, "failed to sync alert transitions in background task");
+        }
+
+        let recent_transitions = match state.store.list_alert_transitions(None, 20).await {
+            Ok(history) => history,
+            Err(err) => {
+                warn!(error = %err, "failed to load alert transition history for snapshot");
+                Vec::new()
+            }
+        };
+
+        state
+            .alerts
+            .publish(AlertsSnapshot {
+                ts_unix: now_unix(),
+                alerts,
+                recent_transitions,
+            })
+            .await;
+    }
+}
+
+pub async fn active_alerts(
+    State(state): State<AppState>,
+    Query(config): Query<AlertRuleConfig>,
+) -> Result<impl IntoResponse, ApiError> {
+    config.validate()?;
+    if let Some(reason) = state.alerts.unavailable_reason().await {
+        return Err(ApiError::new(
+            StatusCode::SERVICE_UNAVAILABLE,
+            "alerts_unavailable",
+            reason,
+        ));
+    }
+    let alerts = state.alerts.latest_alerts().await;
    Ok((StatusCode::OK, Json(alerts)))
 }

@@ -94,64 +320,62 @@ pub async fn alert_history(
 pub async fn alerts_stream(
    ws: WebSocketUpgrade,
    State(state): State<AppState>,
-    Query(query): Query<ActiveAlertsQuery>,
 ) -> impl IntoResponse {
-    let config = AlertRuleConfig {
-        lookback_seconds: query.lookback_seconds,
-        timeout_threshold: query.timeout_threshold,
-        auth_rejected_threshold: query.auth_rejected_threshold,
-        enroll_rejected_threshold: query.enroll_rejected_threshold,
-    };
-    ws.on_upgrade(move |socket| alerts_stream_socket(state, socket, config))
+    ws.on_upgrade(move |socket| alerts_stream_socket(state, socket))
 }

-async fn alerts_stream_socket(state: AppState, mut socket: WebSocket, config: AlertRuleConfig) {
-    let mut tick = tokio::time::interval(Duration::from_secs(5));
+async fn alerts_stream_socket(state: AppState, mut socket: WebSocket) {
+    let mut rx = state.alerts.subscribe();
+    let mut freshness_tick = tokio::time::interval(Duration::from_secs(1));
+    freshness_tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+    let (health, snapshot) = state.alerts.resync_payloads().await;
+    if socket.send(Message::Text(health.into())).await.is_err() {
+        return;
+    }
+    if let Some(encoded) = snapshot
+        && socket.send(Message::Text(encoded.into())).await.is_err()
+    {
+        return;
+    }
+
    loop {
-        tick.tick().await;
-        let alerts = match evaluate_alerts(&state, config.clone()).await {
-            Ok(alerts) => alerts,
-            Err(err) => {
-                warn!(code = %err.code, "failed to evaluate alerts for stream");
-                continue;
+        select! {
+            incoming = socket.recv() => {
+                match incoming {
+                    Some(Ok(Message::Close(_))) | None | Some(Err(_)) => break,
+                    Some(Ok(_)) => {}
+                }
            }
-        };
-
-        if let Err(err) = state.store.sync_alert_transitions(&alerts).await {
-            warn!(error = %err, "failed to sync alert transitions in stream");
-        }
-
-        let history = match state.store.list_alert_transitions(None, 20).await {
-            Ok(h) => h,
-            Err(err) => {
-                warn!(error = %err, "failed to load alert transition history for stream");
-                Vec::new()
+            update = rx.recv() => {
+                match update {
+                    Ok(encoded) => {
+                        if socket.send(Message::Text(encoded.into())).await.is_err() {
+                            break;
+                        }
+                    }
+                    Err(broadcast::error::RecvError::Lagged(_)) => {
+                        let (health, snapshot) = state.alerts.resync_payloads().await;
+                        if socket.send(Message::Text(health.into())).await.is_err() {
+                            break;
+                        }
+                        if let Some(encoded) = snapshot
+                            && socket.send(Message::Text(encoded.into())).await.is_err()
+                        {
+                            break;
+                        }
+                    }
+                    Err(broadcast::error::RecvError::Closed) => break,
+                }
            }
-        };
-
-        let payload = serde_json::json!({
-            "type": "alerts_snapshot",
-            "ts_unix": now_unix(),
-            "alerts": alerts,
-            "recent_transitions": history,
-        });
-        let encoded = match serde_json::to_string(&payload) {
-            Ok(s) => s,
-            Err(err) => {
-                warn!(error = %err, "failed to encode alerts stream payload");
-                continue;
-            }
-        };
-
-        if socket.send(Message::Text(encoded.into())).await.is_err() {
-            break;
+            _ = freshness_tick.tick() => state.alerts.broadcast_health_if_changed().await,
        }
    }
 }

 async fn evaluate_alerts(
    state: &AppState,
-    config: AlertRuleConfig,
+    config: &AlertRuleConfig,
 ) -> Result<Vec<AlertState>, ApiError> {
    let lookback_seconds = config.lookback_seconds.unwrap_or(900).clamp(60, 86_400);
    let timeout_threshold = config.timeout_threshold.unwrap_or(3).max(1);
@@ -161,7 +385,14 @@ async fn evaluate_alerts(
    let now = now_unix();
    let since_unix = now.saturating_sub(lookback_seconds);

-    let enrolled_agents = state.store.list_agents().await;
+    let enrolled_agents = state.store.list_agents().await.map_err(|err| {
+        warn!(error = %err, "failed listing agents for alert evaluation");
+        ApiError::new(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "alerts_query_failed",
+            err.to_string(),
+        )
+    })?;
    let connected_agents = state
        .sessions
        .read()
@@ -359,9 +590,11 @@ fn now_unix() -> u64 {
 mod tests {
    use std::collections::HashSet;

+    use axum::http::StatusCode;
+
    use crate::state::AuditEvent;

-    use super::{AlertBuildContext, build_alerts};
+    use super::{AlertBuildContext, AlertRuleConfig, AlertsHub, AlertsSnapshot, build_alerts};

    fn event(agent_id: Option<&str>, event_type: &str, outcome: &str, ts_unix: u64) -> AuditEvent {
        AuditEvent {
@@ -450,4 +683,146 @@ mod tests {
                .any(|a| a.kind == "enroll_reject_spike" && a.agent_id.is_none())
        );
    }
+
+    #[test]
+    fn alert_rule_config_accepts_omitted_and_default_values() {
+        AlertRuleConfig::default().validate().unwrap();
+        AlertRuleConfig {
+            lookback_seconds: None,
+            timeout_threshold: None,
+            auth_rejected_threshold: None,
+            enroll_rejected_threshold: None,
+        }
+        .validate()
+        .unwrap();
+    }
+
+    #[test]
+    fn alert_rule_config_rejects_custom_overrides() {
+        let configs = [
+            AlertRuleConfig {
+                lookback_seconds: Some(300),
+                ..Default::default()
+            },
+            AlertRuleConfig {
+                timeout_threshold: Some(4),
+                ..Default::default()
+            },
+            AlertRuleConfig {
+                auth_rejected_threshold: Some(4),
+                ..Default::default()
+            },
+            AlertRuleConfig {
+                enroll_rejected_threshold: Some(6),
+                ..Default::default()
+            },
+        ];
+
+        for config in configs {
+            let error = config.validate().unwrap_err();
+            assert_eq!(error.status, StatusCode::BAD_REQUEST);
+            assert_eq!(error.code, "unsupported_alert_override");
+            assert!(error.message.contains("not supported"));
+        }
+    }
+
+    #[tokio::test]
+    async fn alert_hub_reports_initial_failure_and_recovers_on_snapshot() {
+        let hub = AlertsHub::new();
+        assert!(hub.unavailable_reason().await.is_some());
+        let mut updates = hub.subscribe();
+
+        hub.mark_unavailable("store query failed").await;
+        assert_eq!(
+            hub.unavailable_reason().await.as_deref(),
+            Some("store query failed")
+        );
+        let failure: serde_json::Value =
+            serde_json::from_str(&updates.try_recv().unwrap()).unwrap();
+        assert_eq!(failure["type"], "alerts_health");
+        assert_eq!(failure["available"], false);
+        assert_eq!(failure["reason"], "store query failed");
+
+        hub.mark_unavailable("same outage, later attempt").await;
+        assert!(
+            updates.try_recv().is_err(),
+            "failure notifications deduplicate"
+        );
+
+        hub.publish(AlertsSnapshot {
+            ts_unix: super::now_unix(),
+            alerts: Vec::new(),
+            recent_transitions: Vec::new(),
+        })
+        .await;
+        assert_eq!(hub.unavailable_reason().await, None);
+        let recovery: serde_json::Value =
+            serde_json::from_str(&updates.try_recv().unwrap()).unwrap();
+        assert_eq!(recovery["type"], "alerts_health");
+        assert_eq!(recovery["available"], true);
+        assert_eq!(recovery.get("reason"), None);
+        let snapshot: serde_json::Value =
+            serde_json::from_str(&updates.try_recv().unwrap()).unwrap();
+        assert_eq!(snapshot["type"], "alerts_snapshot");
+    }
+
+    #[tokio::test]
+    async fn alert_hub_rejects_stale_snapshots() {
+        let hub = AlertsHub::new();
+        hub.publish(AlertsSnapshot {
+            ts_unix: 0,
+            alerts: Vec::new(),
+            recent_transitions: Vec::new(),
+        })
+        .await;
+        assert_eq!(
+            hub.unavailable_reason().await.as_deref(),
+            Some("alert evaluator snapshot is stale")
+        );
+    }
+
+    #[tokio::test]
+    async fn alert_hub_initial_resync_marks_cached_snapshot_stale() {
+        let hub = AlertsHub::new();
+        let (initial_health, initial_snapshot) = hub.resync_payloads().await;
+        let initial_health: serde_json::Value = serde_json::from_str(&initial_health).unwrap();
+        assert_eq!(initial_health["available"], false);
+        assert_eq!(
+            initial_health["reason"],
+            "alert evaluator has not produced a snapshot yet"
+        );
+        assert!(initial_snapshot.is_none());
+
+        hub.publish(AlertsSnapshot {
+            ts_unix: 0,
+            alerts: Vec::new(),
+            recent_transitions: Vec::new(),
+        })
+        .await;
+        let (stale_health, cached_snapshot) = hub.resync_payloads().await;
+        let stale_health: serde_json::Value = serde_json::from_str(&stale_health).unwrap();
+        assert_eq!(stale_health["available"], false);
+        assert_eq!(stale_health["reason"], "alert evaluator snapshot is stale");
+        assert!(cached_snapshot.is_some());
+    }
+
+    #[tokio::test]
+    async fn alert_hub_broadcasts_stale_transition_once() {
+        let hub = AlertsHub::new();
+        let mut updates = hub.subscribe();
+        hub.publish(AlertsSnapshot {
+            ts_unix: 0,
+            alerts: Vec::new(),
+            recent_transitions: Vec::new(),
+        })
+        .await;
+        let _snapshot = updates.try_recv().unwrap();
+
+        hub.broadcast_health_if_changed().await;
+        let stale: serde_json::Value = serde_json::from_str(&updates.try_recv().unwrap()).unwrap();
+        assert_eq!(stale["available"], false);
+        assert_eq!(stale["reason"], "alert evaluator snapshot is stale");
+        hub.broadcast_health_if_changed().await;
+        assert!(updates.try_recv().is_err());
+    }
 }
@@ -40,7 +40,18 @@ pub struct RelayCommandResponse {
 }

 pub async fn list_agents(State(state): State<AppState>) -> Result<impl IntoResponse, ApiError> {
-    let enrolled = state.store.list_agents_with_nicknames().await;
+    let enrolled = state
+        .store
+        .list_agents_with_nicknames()
+        .await
+        .map_err(|err| {
+            warn!(error = %err, "failed listing agents");
+            ApiError::new(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "list_agents_failed",
+                err.to_string(),
+            )
+        })?;
    let sessions = state.sessions.read().await;

    let agents = enrolled
@@ -120,9 +131,9 @@ pub async fn relay_agent_command(
        .insert(request_id_string.clone(), pending_tx);

    info!("dispatching command to agent");
-    if let Err(err) = state
+    state
        .store
-        .append_audit_event(AuditEventInput {
+        .audit(AuditEventInput {
            actor_type: "admin_api".into(),
            actor_id: None,
            agent_id: Some(agent_id.to_string()),
@@ -133,10 +144,7 @@ pub async fn relay_agent_command(
            message: "dispatched command to connected agent".into(),
            metadata: serde_json::json!({ "command": command_kind }),
        })
-        .await
-    {
-        warn!(error = %err, "failed to append audit event for command dispatch");
-    }
+        .await;

    if let Err(err) = tx.send(SessionEvent::Message(ServerMessage::Command {
        request_id,
@@ -144,9 +152,9 @@ pub async fn relay_agent_command(
    })) {
        state.pending.lock().await.remove(&request_id_string);
        warn!(error = %err, "failed sending command to agent session");
-        if let Err(audit_err) = state
+        state
            .store
-            .append_audit_event(AuditEventInput {
+            .audit(AuditEventInput {
                actor_type: "admin_api".into(),
                actor_id: None,
                agent_id: Some(agent_id.to_string()),
@@ -157,10 +165,7 @@ pub async fn relay_agent_command(
                message: err.to_string(),
                metadata: serde_json::json!({ "command": command_kind }),
            })
-            .await
-        {
-            warn!(error = %audit_err, "failed to append audit event for command send failure");
-        }
+            .await;
        return Err(ApiError::new(
            StatusCode::BAD_GATEWAY,
            "agent_send_failed",
@@ -177,9 +182,9 @@ pub async fn relay_agent_command(
    let response = match outcome {
        Ok(Ok(AgentReply::Result(result))) => {
            info!("agent command completed");
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: Some(agent_id.to_string()),
@@ -190,10 +195,7 @@ pub async fn relay_agent_command(
                    message: "agent command completed".into(),
                    metadata: serde_json::json!({ "command": command_kind }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for command success");
-            }
+                .await;
            RelayCommandResponse {
                request_id: request_id_string,
                status: "ok".into(),
@@ -203,9 +205,9 @@ pub async fn relay_agent_command(
        }
        Ok(Ok(AgentReply::Error(error))) => {
            warn!(code = %error.code, "agent command returned error");
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: Some(agent_id.to_string()),
@@ -216,10 +218,7 @@ pub async fn relay_agent_command(
                    message: error.message.clone(),
                    metadata: serde_json::json!({ "command": command_kind, "code": error.code }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for command error result");
-            }
+                .await;
            RelayCommandResponse {
                request_id: request_id_string,
                status: "error".into(),
@@ -229,9 +228,9 @@ pub async fn relay_agent_command(
        }
        Ok(Err(_)) => {
            warn!("agent response channel dropped");
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: Some(agent_id.to_string()),
@@ -242,10 +241,7 @@ pub async fn relay_agent_command(
                    message: "agent response channel dropped".into(),
                    metadata: serde_json::json!({ "command": command_kind }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for dropped response");
-            }
+                .await;
            return Err(ApiError::new(
                StatusCode::BAD_GATEWAY,
                "agent_response_dropped",
@@ -258,9 +254,9 @@ pub async fn relay_agent_command(
                timeout_ms = timeout.as_millis() as u64,
                "agent command timed out"
            );
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: Some(agent_id.to_string()),
@@ -271,10 +267,7 @@ pub async fn relay_agent_command(
                    message: "agent command timed out".into(),
                    metadata: serde_json::json!({ "command": command_kind, "timeout_ms": timeout.as_millis() as u64 }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for timeout");
-            }
+                .await;
            return Err(ApiError::new(
                StatusCode::GATEWAY_TIMEOUT,
                "agent_timeout",
@@ -74,9 +74,9 @@ pub async fn enroll(
    match state.store.enroll(&req.enroll_token).await {
        Ok(issued) => {
            info!(agent_id = %issued.agent_id, "agent enrollment accepted");
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "agent".into(),
                    actor_id: Some(issued.agent_id.clone()),
                    agent_id: Some(issued.agent_id.clone()),
@@ -87,10 +87,7 @@ pub async fn enroll(
                    message: "agent enrollment accepted".into(),
                    metadata: serde_json::json!({}),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for enroll success");
-            }
+                .await;
            Ok((
                StatusCode::OK,
                Json(EnrollResponse {
@@ -102,9 +99,9 @@ pub async fn enroll(
        }
        Err(err) => {
            warn!(error = %err, "agent enrollment rejected");
-            if let Err(audit_err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "agent".into(),
                    actor_id: None,
                    agent_id: None,
@@ -115,10 +112,7 @@ pub async fn enroll(
                    message: err.to_string(),
                    metadata: serde_json::json!({}),
                })
-                .await
-            {
-                warn!(error = %audit_err, "failed to append audit event for enroll rejection");
-            }
+                .await;
            Err(ApiError::new(
                StatusCode::UNAUTHORIZED,
                "enrollment_rejected",
@@ -145,9 +139,9 @@ pub async fn issue_enroll_token(
                expires_at_unix = issued.expires_at_unix,
                "issued enroll token"
            );
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: None,
@@ -161,10 +155,7 @@ pub async fn issue_enroll_token(
                        "expires_at_unix": issued.expires_at_unix,
                    }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for token issuance");
-            }
+                .await;
            Ok((
                StatusCode::OK,
                Json(IssueEnrollTokenResponse {
@@ -189,9 +180,9 @@ pub async fn list_enroll_tokens(
 ) -> Result<impl IntoResponse, ApiError> {
    match state.store.list_enroll_tokens().await {
        Ok(tokens) => {
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: None,
@@ -204,10 +195,7 @@ pub async fn list_enroll_tokens(
                        "count": tokens.len(),
                    }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for token listing");
-            }
+                .await;
            let body = tokens
                .into_iter()
                .map(|t| EnrollTokenStatus {
@@ -235,9 +223,9 @@ pub async fn revoke_enroll_token(
 ) -> Result<impl IntoResponse, ApiError> {
    match state.store.revoke_enroll_token(&token).await {
        Ok(revoked) => {
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: None,
@@ -256,10 +244,7 @@ pub async fn revoke_enroll_token(
                    },
                    metadata: serde_json::json!({ "token": token }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for token revoke");
-            }
+                .await;
            Ok((
                StatusCode::OK,
                Json(RevokeEnrollTokenResponse { token, revoked }),
@@ -289,9 +274,9 @@ pub async fn revoke_agent(
                }
            }

-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: Some(agent_id.clone()),
@@ -310,10 +295,7 @@ pub async fn revoke_agent(
                    },
                    metadata: serde_json::json!({ "agent_id": agent_id }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for agent revoke");
-            }
+                .await;

            Ok((
                StatusCode::OK,
@@ -349,9 +331,9 @@ pub async fn set_agent_nickname(
        .await
    {
        Ok(updated) => {
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "admin_api".into(),
                    actor_id: None,
                    agent_id: Some(agent_id.clone()),
@@ -373,10 +355,7 @@ pub async fn set_agent_nickname(
                        "nickname": normalized,
                    }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for nickname set");
-            }
+                .await;

            Ok((
                StatusCode::OK,
@@ -4,11 +4,12 @@ use axum::Json;
 use axum::extract::{Query, State};
 use axum::http::StatusCode;
 use axum::response::IntoResponse;
+use futures_util::StreamExt;
 use tracing::warn;
 use wakey_agent::protocol::{AgentCommand, InventoryRequest, WakeRequest};

 use crate::api::ApiError;
-use crate::api::commands::relay_agent_command;
+use crate::api::commands::{RelayCommandResponse, relay_agent_command};
 use crate::runtime::AppState;

 mod build;
@@ -26,6 +27,8 @@ use types::{
    RefreshFleetDevicesResponse, WakeFleetDeviceRequest, WakeFleetDeviceResponse,
 };

+const REFRESH_CONCURRENCY: usize = 8;
+
 pub async fn list_fleet_devices(
    State(state): State<AppState>,
    Query(query): Query<ListFleetDevicesQuery>,
@@ -47,95 +50,41 @@ pub async fn refresh_fleet_devices(
    State(state): State<AppState>,
    Json(req): Json<RefreshFleetDevicesRequest>,
 ) -> Result<impl IntoResponse, ApiError> {
-    let mut agent_ids = if req.agent_ids.is_empty() {
+    let agent_ids = if req.agent_ids.is_empty() {
        let sessions = state.sessions.read().await;
        sessions.keys().cloned().collect::<Vec<_>>()
    } else {
        req.agent_ids.clone()
    };
-    agent_ids.sort();
-    agent_ids.dedup();
+    let agent_ids = normalize_refresh_agent_ids(agent_ids);

-    let mut results = Vec::with_capacity(agent_ids.len());
-    let mut total_accepted = 0usize;
-    for agent_id in agent_ids {
-        let response = relay_agent_command(
-            &state,
-            &agent_id,
-            AgentCommand::Inventory(InventoryRequest {
-                query: None,
-                name: None,
-                ips: Vec::new(),
-                devs: Vec::new(),
-                nuds: Vec::new(),
-                macs: Vec::new(),
-            }),
-            req.timeout_ms,
-        )
-        .await;
-
-        match response {
-            Ok(response) if response.status == "ok" => {
-                let Some(result) = response.result else {
-                    results.push(RefreshFleetAgentResult {
-                        agent_id,
-                        status: "error".into(),
-                        accepted: 0,
-                        error: Some("inventory command returned no result".into()),
-                    });
-                    continue;
-                };
-                match serde_json::from_value::<wakey_core::DeviceInventory>(result)
-                    .map(|i| i.devices)
-                {
-                    Ok(devices) => {
-                        match state
-                            .store
-                            .replace_agent_device_snapshot(&agent_id, &devices)
-                            .await
-                        {
-                            Ok(accepted) => {
-                                total_accepted = total_accepted.saturating_add(accepted);
-                                results.push(RefreshFleetAgentResult {
-                                    agent_id,
-                                    status: "ok".into(),
-                                    accepted,
-                                    error: None,
-                                });
-                            }
-                            Err(err) => results.push(RefreshFleetAgentResult {
-                                agent_id,
-                                status: "error".into(),
-                                accepted: 0,
-                                error: Some(err.to_string()),
-                            }),
-                        }
-                    }
-                    Err(err) => results.push(RefreshFleetAgentResult {
-                        agent_id,
-                        status: "error".into(),
-                        accepted: 0,
-                        error: Some(err.to_string()),
-                    }),
-                }
-            }
-            Ok(response) => results.push(RefreshFleetAgentResult {
-                agent_id,
-                status: "error".into(),
-                accepted: 0,
-                error: response
-                    .error
-                    .map(|error| error.message)
-                    .or_else(|| Some("inventory command failed".into())),
-            }),
-            Err(err) => results.push(RefreshFleetAgentResult {
-                agent_id,
-                status: "error".into(),
-                accepted: 0,
-                error: Some(format!("{}: {}", err.status, err.message)),
-            }),
+    let results = futures_util::stream::iter(agent_ids.into_iter().map(|agent_id| {
+        let state = state.clone();
+        async move {
+            let response = relay_agent_command(
+                &state,
+                &agent_id,
+                AgentCommand::Inventory(InventoryRequest {
+                    query: None,
+                    name: None,
+                    ips: Vec::new(),
+                    devs: Vec::new(),
+                    nuds: Vec::new(),
+                    macs: Vec::new(),
+                }),
+                req.timeout_ms,
+            )
+            .await;
+            refresh_fleet_agent_result(&state, &agent_id, response).await
        }
-    }
+    }))
+    .buffer_unordered(REFRESH_CONCURRENCY)
+    .collect::<Vec<_>>()
+    .await;
+
+    let mut results = results;
+    results.sort_by(|a, b| a.agent_id.cmp(&b.agent_id));
+    let total_accepted = results.iter().map(|result| result.accepted).sum::<usize>();

    Ok((
        StatusCode::OK,
@@ -146,6 +95,76 @@ pub async fn refresh_fleet_devices(
    ))
 }

+fn normalize_refresh_agent_ids(mut agent_ids: Vec<String>) -> Vec<String> {
+    agent_ids.sort();
+    agent_ids.dedup();
+    agent_ids
+}
+
+async fn refresh_fleet_agent_result(
+    state: &AppState,
+    agent_id: &str,
+    response: Result<RelayCommandResponse, ApiError>,
+) -> RefreshFleetAgentResult {
+    match response {
+        Ok(response) if response.status == "ok" => {
+            let Some(result) = response.result else {
+                return RefreshFleetAgentResult {
+                    agent_id: agent_id.to_string(),
+                    status: "error".into(),
+                    accepted: 0,
+                    error: Some("inventory command returned no result".into()),
+                };
+            };
+            match serde_json::from_value::<wakey_core::DeviceInventory>(result)
+                .map(|inventory| inventory.devices)
+            {
+                Ok(devices) => {
+                    match state
+                        .store
+                        .replace_agent_device_snapshot(agent_id, &devices)
+                        .await
+                    {
+                        Ok(accepted) => RefreshFleetAgentResult {
+                            agent_id: agent_id.to_string(),
+                            status: "ok".into(),
+                            accepted,
+                            error: None,
+                        },
+                        Err(err) => RefreshFleetAgentResult {
+                            agent_id: agent_id.to_string(),
+                            status: "error".into(),
+                            accepted: 0,
+                            error: Some(err.to_string()),
+                        },
+                    }
+                }
+                Err(err) => RefreshFleetAgentResult {
+                    agent_id: agent_id.to_string(),
+                    status: "error".into(),
+                    accepted: 0,
+                    error: Some(err.to_string()),
+                },
+            }
+        }
+        Ok(response) => RefreshFleetAgentResult {
+            agent_id: agent_id.to_string(),
+            status: "error".into(),
+            accepted: 0,
+            error: response
+                .error
+                .map(|error| error.message)
+                .or_else(|| Some("inventory command failed".into())),
+        },
+        Err(err) => RefreshFleetAgentResult {
+            agent_id: agent_id.to_string(),
+            status: "error".into(),
+            accepted: 0,
+            error: Some(format!("{}: {}", err.status, err.message)),
+        },
+    }
+}
+
 pub async fn wake_fleet_device(
    State(state): State<AppState>,
    Json(req): Json<WakeFleetDeviceRequest>,
@@ -243,7 +262,7 @@ async fn load_fleet_devices(
        let sessions = state.sessions.read().await;
        sessions.keys().cloned().collect::<BTreeSet<_>>()
    };
-    let agents = state.store.list_agents_with_nicknames().await;
+    let agents = state.store.list_agents_with_nicknames().await?;
    let agent_status = agents
        .into_iter()
        .map(|(agent_id, nickname)| {
@@ -8,9 +8,23 @@ use super::build::{
    AgentRuntimeStatus, FleetBuildContext, build_fleet_devices, filter_fleet_devices,
    known_device_summary,
 };
+use super::normalize_refresh_agent_ids;
 use super::types::ListFleetDevicesQuery;
 use crate::state::{AgentDeviceRow, AgentDeviceWithChildren, DeviceIdentifier, KnownDevice};

+#[test]
+fn refresh_agent_selection_keeps_all_agents_beyond_previous_cap() {
+    let ids = (0..140)
+        .map(|index| format!("agent-{index:03}"))
+        .collect::<Vec<_>>();
+
+    let selected = normalize_refresh_agent_ids(ids);
+
+    assert_eq!(selected.len(), 140);
+    assert_eq!(selected.first().map(String::as_str), Some("agent-000"));
+    assert_eq!(selected.last().map(String::as_str), Some("agent-139"));
+}
+
 fn context(connected: &[&str]) -> FleetBuildContext {
    FleetBuildContext {
        agent_status: connected
@@ -7,7 +7,7 @@ mod commands;
 mod control;
 mod terminals;

-pub use alerts::{active_alerts, alert_history, alerts_stream};
+pub use alerts::{AlertsHub, active_alerts, alert_history, alerts_stream, run_alert_evaluator};
 pub use audit::list_audit_events;
 pub use commands::{list_agents, run_command};
 pub use control::{
@@ -19,7 +19,7 @@ pub use control::{
 };
 pub use terminals::{
    agent_terminal_ws, attach_terminal, close_terminal, create_terminal, get_terminal,
-    list_terminals, operator_terminal_ws,
+    list_terminals, operator_terminal_ws, terminal_events_ws,
 };

 use axum::response::{IntoResponse, Response};
@@ -6,6 +6,7 @@ use axum::response::Response;
 use futures_util::{SinkExt, StreamExt};
 use serde::{Deserialize, Serialize};
 use std::time::Duration;
+use tokio::sync::broadcast;
 use tracing::{info, warn};
 use wakey_agent::protocol::{
    AgentCapability, DEFAULT_TERMINAL_MAX_SESSIONS, DEFAULT_TERMINAL_SESSION_TTL_SECONDS,
@@ -244,6 +245,49 @@ pub async fn operator_terminal_ws(
        .on_upgrade(move |socket| handle_operator_terminal_socket(state, terminal_id, socket))
 }

+pub async fn terminal_events_ws(ws: WebSocketUpgrade, State(state): State<AppState>) -> Response {
+    ws.on_upgrade(move |socket| handle_terminal_events_socket(state, socket))
+}
+
+async fn handle_terminal_events_socket(state: AppState, socket: WebSocket) {
+    let mut events = state.terminals.subscribe();
+    let (mut write, mut read) = socket.split();
+    if write
+        .send(Message::Text(r#"{"type":"sessions_changed"}"#.into()))
+        .await
+        .is_err()
+    {
+        return;
+    }
+
+    loop {
+        tokio::select! {
+            event = events.recv() => {
+                match event {
+                    Ok(()) | Err(broadcast::error::RecvError::Lagged(_)) => {
+                        if write.send(Message::Text(r#"{"type":"sessions_changed"}"#.into())).await.is_err() {
+                            break;
+                        }
+                    }
+                    Err(broadcast::error::RecvError::Closed) => break,
+                }
+            }
+            incoming = read.next() => {
+                match incoming {
+                    Some(Ok(Message::Ping(payload))) => {
+                        if write.send(Message::Pong(payload)).await.is_err() {
+                            break;
+                        }
+                    }
+                    Some(Ok(Message::Pong(_))) => {}
+                    Some(Ok(Message::Close(_))) | None | Some(Err(_)) => break,
+                    Some(Ok(Message::Text(_))) | Some(Ok(Message::Binary(_))) => {}
+                }
+            }
+        }
+    }
+}
+
 async fn handle_agent_terminal_socket(state: AppState, terminal_id: String, mut socket: WebSocket) {
    let auth = match receive_text_handshake(&mut socket).await.and_then(|text| {
        serde_json::from_str::<TerminalAgentHandshake>(&text).map_err(|_| "invalid handshake")
@@ -649,9 +693,9 @@ async fn append_terminal_audit(
    terminal_id: &str,
    audit: TerminalAudit<'_>,
 ) {
-    if let Err(err) = state
+    state
        .store
-        .append_audit_event(AuditEventInput {
+        .audit(AuditEventInput {
            actor_type: audit.actor_type.into(),
            actor_id: None,
            agent_id: Some(agent_id.to_string()),
@@ -662,10 +706,7 @@ async fn append_terminal_audit(
            message: audit.message.into(),
            metadata: audit.metadata,
        })
-        .await
-    {
-        warn!(terminal_id, event_type = audit.event_type, error = %err, "failed to append terminal audit event");
-    }
+        .await;
 }

 fn validate_size(rows: u16, cols: u16) -> Result<(), ApiError> {
@@ -13,7 +13,6 @@ pub struct DaemonConfig {
    pub state_file: PathBuf,
    pub command_timeout: Duration,
    pub enroll_token_ttl: Duration,
-    #[allow(dead_code)]
    pub observation_retention: Duration,
    pub pid_file: PathBuf,
    pub ui_dist_dir: PathBuf,
@@ -43,6 +43,7 @@ pub struct AppState {
    pub command_timeout: Duration,
    pub enroll_token_ttl: Duration,
    pub terminals: terminals::TerminalRegistry,
+    pub alerts: api::AlertsHub,
 }

 #[derive(Clone)]
@@ -147,6 +148,10 @@ fn control_api_routes() -> Router<AppState> {
            "/api/v1/control/terminals",
            get(api::list_terminals).post(api::create_terminal),
        )
+        .route(
+            "/api/v1/control/terminals/events/ws",
+            get(api::terminal_events_ws),
+        )
        .route(
            "/api/v1/control/terminals/{terminal_id}",
            get(api::get_terminal).delete(api::close_terminal),
@@ -182,8 +187,11 @@ pub async fn serve(daemon: config::DaemonConfig) -> Result<()> {
        command_timeout: daemon.command_timeout,
        enroll_token_ttl: daemon.enroll_token_ttl,
        terminals: terminals::TerminalRegistry::new(),
+        alerts: api::AlertsHub::new(),
    };

+    tokio::spawn(api::run_alert_evaluator(app_state.clone()));
+
    // Keep route classes explicit so edge policy can map directly:
    // - public_api_routes: intended internet-facing agent endpoints
    // - control_api_routes: intended admin-only endpoints behind Access
@@ -231,6 +239,18 @@ pub async fn serve(daemon: config::DaemonConfig) -> Result<()> {
                        }
                        Err(err) => warn!(error = %err, "periodic gc failed"),
                    }
+                    match app_state.store.gc_retention(daemon.observation_retention).await {
+                        Ok(stats) => {
+                            if stats.audit_events_removed > 0 || stats.alert_transitions_removed > 0 {
+                                info!(
+                                    audit_events_removed = stats.audit_events_removed,
+                                    alert_transitions_removed = stats.alert_transitions_removed,
+                                    "periodic gc pruned rows older than retention window"
+                                );
+                            }
+                        }
+                        Err(err) => warn!(error = %err, "periodic retention gc failed"),
+                    }
                }
                join = &mut server => {
                    let _ = remove_pid_file(&daemon.pid_file);
@@ -2,7 +2,7 @@ use std::collections::{HashMap, VecDeque};
 use std::sync::Arc;
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};

-use tokio::sync::{Mutex, mpsc};
+use tokio::sync::{Mutex, broadcast, mpsc};
 use uuid::Uuid;
 use wakey_agent::protocol::{AgentTerminalSession, TerminalId};

@@ -12,6 +12,7 @@ pub const TERMINAL_PENDING_AGENT_BYTES: usize = 256 * 1024;
 pub const TERMINAL_ATTACH_TIMEOUT: Duration = Duration::from_secs(10);
 const TERMINAL_TOMBSTONE_TTL: Duration = Duration::from_secs(5 * 60);
 const TERMINAL_MAX_TOMBSTONES: usize = 1024;
+const TERMINAL_EVENTS_CAPACITY: usize = 32;

 #[derive(Clone, Debug)]
 pub enum TerminalRelayFrame {
@@ -24,6 +25,7 @@ pub enum TerminalRelayFrame {
 pub struct TerminalRegistry {
    inner: Arc<Mutex<HashMap<String, TerminalSession>>>,
    closed: Arc<Mutex<HashMap<String, Instant>>>,
+    events: broadcast::Sender<()>,
 }

 struct TerminalSession {
@@ -69,12 +71,22 @@ impl Default for TerminalRegistry {

 impl TerminalRegistry {
    pub fn new() -> Self {
+        let (events, _) = broadcast::channel(TERMINAL_EVENTS_CAPACITY);
        Self {
            inner: Arc::new(Mutex::new(HashMap::new())),
            closed: Arc::new(Mutex::new(HashMap::new())),
+            events,
        }
    }

+    pub fn subscribe(&self) -> broadcast::Receiver<()> {
+        self.events.subscribe()
+    }
+
+    fn notify_changed(&self) {
+        let _ = self.events.send(());
+    }
+
    #[cfg(test)]
    async fn create(&self, agent_id: String) -> Result<CreatedTerminal, &'static str> {
        self.create_with_limits(
@@ -95,13 +107,17 @@ impl TerminalRegistry {
        session_ttl_seconds: u64,
    ) -> Result<CreatedTerminal, &'static str> {
        let mut sessions = self.inner.lock().await;
-        prune_expired_sessions(&mut sessions);
+        let pruned = prune_expired_sessions(&mut sessions) > 0;
        if sessions
            .values()
            .filter(|session| session.agent_id == agent_id)
            .count()
            >= max_sessions.max(1)
        {
+            drop(sessions);
+            if pruned {
+                self.notify_changed();
+            }
            return Err("agent_terminal_limit_reached");
        }

@@ -112,8 +128,13 @@ impl TerminalRegistry {
            .duration_since(UNIX_EPOCH)
            .unwrap_or_default()
            .as_secs();
-        let expiry = expiry_for_created_at(created_at_unix, session_ttl_seconds)
-            .ok_or("terminal_ttl_invalid")?;
+        let Some(expiry) = expiry_for_created_at(created_at_unix, session_ttl_seconds) else {
+            drop(sessions);
+            if pruned {
+                self.notify_changed();
+            }
+            return Err("terminal_ttl_invalid");
+        };
        sessions.insert(
            terminal_id.clone(),
            TerminalSession {
@@ -133,6 +154,8 @@ impl TerminalRegistry {
                operator_detached_at: None,
            },
        );
+        drop(sessions);
+        self.notify_changed();

        Ok(CreatedTerminal {
            terminal_id,
@@ -145,6 +168,7 @@ impl TerminalRegistry {

    pub async fn remove(&self, terminal_id: &str) -> Option<String> {
        let session = self.inner.lock().await.remove(terminal_id)?;
+        self.notify_changed();
        self.remember_closed(terminal_id).await;
        if let Some(tx) = session.agent_tx {
            let _ =
@@ -196,10 +220,10 @@ impl TerminalRegistry {
            })
            .map(|session| session.terminal_id.as_str())
            .collect::<std::collections::HashSet<_>>();
-        let stale_ids = {
+        let (stale_ids, pruned) = {
            let mut sessions = self.inner.lock().await;
-            prune_expired_sessions(&mut sessions);
-            sessions
+            let pruned = prune_expired_sessions(&mut sessions) > 0;
+            let stale_ids = sessions
                .iter()
                .filter(|(terminal_id, session)| {
                    session.agent_id == agent_id
@@ -207,13 +231,18 @@ impl TerminalRegistry {
                        && !reported_ids.contains(terminal_id.as_str())
                })
                .map(|(terminal_id, _)| terminal_id.clone())
-                .collect::<Vec<_>>()
+                .collect::<Vec<_>>();
+            (stale_ids, pruned)
        };
+        if pruned {
+            self.notify_changed();
+        }
        for terminal_id in stale_ids {
            self.remove(&terminal_id).await;
        }

        let mut credentials = Vec::new();
+        let mut changed = false;
        let mut sessions = self.inner.lock().await;
        for reported_session in reported {
            let Some(expiry) = expiry_for_created_at(
@@ -223,9 +252,9 @@ impl TerminalRegistry {
                continue;
            };
            let terminal_id = reported_session.terminal_id.as_str().to_string();
-            let session = sessions
-                .entry(terminal_id)
-                .or_insert_with(|| TerminalSession {
+            let session = sessions.entry(terminal_id).or_insert_with(|| {
+                changed = true;
+                TerminalSession {
                    agent_id: agent_id.to_string(),
                    created_at_unix: reported_session.created_at_unix,
                    expiry,
@@ -240,7 +269,8 @@ impl TerminalRegistry {
                    operator_id: None,
                    operator_connection_id: None,
                    operator_detached_at: Some(Instant::now()),
-                });
+                }
+            });
            if session.agent_id != agent_id || session.agent_tx.is_some() {
                continue;
            }
@@ -249,14 +279,24 @@ impl TerminalRegistry {
            session.relay_token = Some(token.clone());
            credentials.push((reported_session.terminal_id.clone(), token));
        }
+        drop(sessions);
+        if changed {
+            self.notify_changed();
+        }
        credentials
    }

    pub async fn detach_agent(&self, terminal_id: &str) -> Option<String> {
        let mut sessions = self.inner.lock().await;
        let session = sessions.get_mut(terminal_id)?;
+        let changed = session.agent_tx.is_some();
        session.agent_tx = None;
-        Some(session.agent_id.clone())
+        let agent_id = session.agent_id.clone();
+        drop(sessions);
+        if changed {
+            self.notify_changed();
+        }
+        Some(agent_id)
    }

    /// Issues a token while atomically handing this operator's attachment to
@@ -269,17 +309,21 @@ impl TerminalRegistry {
    ) -> Result<String, &'static str> {
        validate_operator_id(operator_id)?;
        let mut sessions = self.inner.lock().await;
-        let target = active_session(&mut sessions, terminal_id)?;
+        let target = active_session(&mut sessions, terminal_id, &self.events)?;
        if target.operator_tx.is_some() && target.operator_id.as_deref() != Some(operator_id) {
            return Err("terminal_operator_already_attached");
        }

-        detach_operator_sessions(&mut sessions, operator_id);
+        let detached = detach_operator_sessions(&mut sessions, operator_id);

-        let session = active_session(&mut sessions, terminal_id)?;
+        let session = active_session(&mut sessions, terminal_id, &self.events)?;
        let token = new_token();
        session.attachment_token = Some(token.clone());
        session.attachment_operator_id = Some(operator_id.to_string());
+        drop(sessions);
+        if detached {
+            self.notify_changed();
+        }
        Ok(token)
    }

@@ -290,7 +334,7 @@ impl TerminalRegistry {
        relay_token: &str,
    ) -> Result<(mpsc::Receiver<TerminalRelayFrame>, Vec<TerminalRelayFrame>), &'static str> {
        let mut sessions = self.inner.lock().await;
-        let session = active_session(&mut sessions, terminal_id)?;
+        let session = active_session(&mut sessions, terminal_id, &self.events)?;
        if session.agent_id != agent_id {
            return Err("terminal_agent_mismatch");
        }
@@ -306,6 +350,8 @@ impl TerminalRegistry {
        session.agent_tx = Some(tx);
        let pending = session.pending_agent.drain(..).collect();
        session.pending_agent_bytes = 0;
+        drop(sessions);
+        self.notify_changed();
        Ok((rx, pending))
    }

@@ -317,7 +363,7 @@ impl TerminalRegistry {
    ) -> Result<mpsc::Receiver<TerminalRelayFrame>, &'static str> {
        validate_operator_id(operator_id)?;
        let mut sessions = self.inner.lock().await;
-        let session = active_session(&mut sessions, terminal_id)?;
+        let session = active_session(&mut sessions, terminal_id, &self.events)?;
        if session.operator_tx.is_some() {
            return Err("terminal_operator_already_attached");
        }
@@ -336,7 +382,7 @@ impl TerminalRegistry {
        // WebSocket presents that token, it still atomically releases any
        // older session held by the same browser tab.
        detach_operator_sessions(&mut sessions, operator_id);
-        let session = active_session(&mut sessions, terminal_id)?;
+        let session = active_session(&mut sessions, terminal_id, &self.events)?;
        session.attachment_token = None;
        session.attachment_operator_id = None;
        session.operator_detached_at = None;
@@ -344,6 +390,8 @@ impl TerminalRegistry {
        session.operator_tx = Some(tx);
        session.operator_id = Some(operator_id.to_string());
        session.operator_connection_id = Some(attachment_token.to_string());
+        drop(sessions);
+        self.notify_changed();
        Ok(rx)
    }

@@ -357,7 +405,7 @@ impl TerminalRegistry {
        // leave input stranded in the pre-attachment queue.
        let tx = {
            let mut sessions = self.inner.lock().await;
-            let session = active_session(&mut sessions, terminal_id)?;
+            let session = active_session(&mut sessions, terminal_id, &self.events)?;
            if let Some(tx) = session.agent_tx.clone() {
                tx
            } else {
@@ -385,7 +433,7 @@ impl TerminalRegistry {
    ) -> Result<(), &'static str> {
        let operator_tx = {
            let mut sessions = self.inner.lock().await;
-            let session = active_session(&mut sessions, terminal_id)?;
+            let session = active_session(&mut sessions, terminal_id, &self.events)?;
            session.operator_tx.clone()
        };

@@ -397,13 +445,19 @@ impl TerminalRegistry {
                    // Detach its stale sender; the agent's parsed screen remains
                    // authoritative and will reconstruct the next attachment.
                    let mut sessions = self.inner.lock().await;
-                    let session = active_session(&mut sessions, terminal_id)?;
+                    let session = active_session(&mut sessions, terminal_id, &self.events)?;
+                    let mut changed = false;
                    if session
                        .operator_tx
                        .as_ref()
                        .is_some_and(|current| current.same_channel(&tx))
                    {
                        clear_operator_attachment(session);
+                        changed = true;
+                    }
+                    drop(sessions);
+                    if changed {
+                        self.notify_changed();
                    }
                    return Ok(());
                }
@@ -445,25 +499,36 @@ impl TerminalRegistry {
        }
        let detached_at = Instant::now();
        clear_operator_attachment(session);
+        drop(sessions);
+        self.notify_changed();
        Some(detached_at)
    }

    pub async fn summary(&self, terminal_id: &str) -> Option<TerminalSummary> {
        let mut sessions = self.inner.lock().await;
-        prune_expired_sessions(&mut sessions);
-        sessions
+        let pruned = prune_expired_sessions(&mut sessions) > 0;
+        let summary = sessions
            .get(terminal_id)
-            .map(|session| terminal_summary(terminal_id, session))
+            .map(|session| terminal_summary(terminal_id, session));
+        drop(sessions);
+        if pruned {
+            self.notify_changed();
+        }
+        summary
    }

    pub async fn summaries(&self) -> Vec<TerminalSummary> {
        let mut sessions = self.inner.lock().await;
-        prune_expired_sessions(&mut sessions);
+        let removed = prune_expired_sessions(&mut sessions);
        let mut summaries = sessions
            .iter()
            .map(|(terminal_id, session)| terminal_summary(terminal_id, session))
            .collect::<Vec<_>>();
        summaries.sort_by_key(|session| std::cmp::Reverse(session.created_at_unix));
+        drop(sessions);
+        if removed > 0 {
+            self.notify_changed();
+        }
        summaries
    }
 }
@@ -482,12 +547,14 @@ fn terminal_summary(terminal_id: &str, session: &TerminalSession) -> TerminalSum
 fn active_session<'a>(
    sessions: &'a mut HashMap<String, TerminalSession>,
    terminal_id: &str,
+    events: &broadcast::Sender<()>,
 ) -> Result<&'a mut TerminalSession, &'static str> {
    if sessions
        .get(terminal_id)
        .is_some_and(|session| session.expiry.is_expired(Instant::now()))
    {
        sessions.remove(terminal_id);
+        let _ = events.send(());
        return Err("terminal_expired");
    }
    sessions.get_mut(terminal_id).ok_or("terminal_not_found")
@@ -500,12 +567,18 @@ fn validate_operator_id(operator_id: &str) -> Result<(), &'static str> {
    Ok(())
 }

-fn detach_operator_sessions(sessions: &mut HashMap<String, TerminalSession>, operator_id: &str) {
+fn detach_operator_sessions(
+    sessions: &mut HashMap<String, TerminalSession>,
+    operator_id: &str,
+) -> bool {
+    let mut detached = false;
    for session in sessions.values_mut() {
        if session.operator_id.as_deref() == Some(operator_id) {
            clear_operator_attachment(session);
+            detached = true;
        }
    }
+    detached
 }

 fn clear_operator_attachment(session: &mut TerminalSession) {
@@ -523,9 +596,11 @@ fn prune_tombstones(closed: &mut HashMap<String, Instant>) {
    closed.retain(|_, closed_at| closed_at.elapsed() < TERMINAL_TOMBSTONE_TTL);
 }

-fn prune_expired_sessions(sessions: &mut HashMap<String, TerminalSession>) {
+fn prune_expired_sessions(sessions: &mut HashMap<String, TerminalSession>) -> usize {
    let now = Instant::now();
+    let old_len = sessions.len();
    sessions.retain(|_, session| !session.expiry.is_expired(now));
+    old_len - sessions.len()
 }

 #[derive(Clone, Copy, Debug)]
@@ -990,4 +1065,127 @@ mod tests {

        assert!(registry.summary(&created.terminal_id).await.is_some());
    }
+
+    #[tokio::test]
+    async fn session_events_invalidate_mutations_but_not_reads_or_terminal_bytes() {
+        let registry = TerminalRegistry::new();
+        let mut events = registry.subscribe();
+        let created = registry.create("router".into()).await.expect("create");
+        assert!(events.try_recv().is_ok());
+
+        registry.summaries().await;
+        registry.summary(&created.terminal_id).await;
+        assert!(events.try_recv().is_err(), "ordinary reads emit no event");
+
+        let mut operator = registry
+            .attach_operator(&created.terminal_id, &created.attachment_token, OPERATOR_A)
+            .await
+            .expect("attach operator");
+        assert!(events.try_recv().is_ok());
+        registry
+            .relay_from_agent(
+                &created.terminal_id,
+                TerminalRelayFrame::Binary(b"terminal output".to_vec()),
+            )
+            .await
+            .expect("relay terminal bytes");
+        operator.recv().await.expect("terminal bytes delivered");
+        assert!(events.try_recv().is_err(), "terminal bytes emit no event");
+
+        registry
+            .detach_operator(&created.terminal_id, &created.attachment_token)
+            .await
+            .expect("detach operator");
+        assert!(events.try_recv().is_ok());
+        registry.remove(&created.terminal_id).await.expect("remove");
+        assert!(events.try_recv().is_ok());
+    }
+
+    #[tokio::test]
+    async fn lagged_session_receiver_recovers_with_latest_invalidation() {
+        let registry = TerminalRegistry::new();
+        let mut events = registry.subscribe();
+        for _ in 0..(TERMINAL_EVENTS_CAPACITY + 3) {
+            registry
+                .create_with_limits("router".into(), TERMINAL_EVENTS_CAPACITY + 3, 0)
+                .await
+                .expect("create");
+        }
+
+        assert!(matches!(
+            events.try_recv(),
+            Err(broadcast::error::TryRecvError::Lagged(_))
+        ));
+        assert!(events.try_recv().is_ok());
+        assert_eq!(
+            registry.summaries().await.len(),
+            TERMINAL_EVENTS_CAPACITY + 3
+        );
+    }
+
+    #[tokio::test]
+    async fn agent_attach_detach_and_reconciliation_invalidate_catalog_changes() {
+        let registry = TerminalRegistry::new();
+        let mut events = registry.subscribe();
+        let terminal_id = TerminalId::new("reconciled-session").expect("terminal id");
+        let reported = AgentTerminalSession {
+            terminal_id: terminal_id.clone(),
+            created_at_unix: 0,
+            session_ttl_seconds: 0,
+        };
+
+        let credentials = registry
+            .reconcile_agent_sessions("router", std::slice::from_ref(&reported))
+            .await;
+        assert_eq!(credentials.len(), 1);
+        assert!(events.try_recv().is_ok(), "adoption changes the catalog");
+
+        let (_, relay_token) = &credentials[0];
+        registry
+            .attach_agent(terminal_id.as_str(), "router", relay_token)
+            .await
+            .expect("attach agent");
+        assert!(events.try_recv().is_ok());
+        registry
+            .detach_agent(terminal_id.as_str())
+            .await
+            .expect("detach agent");
+        assert!(events.try_recv().is_ok());
+
+        registry.reconcile_agent_sessions("router", &[]).await;
+        assert!(
+            events.try_recv().is_ok(),
+            "reconciliation removes stale session"
+        );
+        assert!(registry.summary(terminal_id.as_str()).await.is_none());
+        assert!(events.try_recv().is_err());
+    }
+
+    #[tokio::test]
+    async fn pruning_sibling_keeps_requested_summary_and_notifies_once() {
+        let registry = TerminalRegistry::new();
+        let mut events = registry.subscribe();
+        let expired = registry.create("router".into()).await.expect("expired");
+        let live = registry.create("router".into()).await.expect("live");
+        events.try_recv().expect("expired create event");
+        events.try_recv().expect("live create event");
+        registry
+            .inner
+            .lock()
+            .await
+            .get_mut(&expired.terminal_id)
+            .expect("expired session")
+            .expiry = TerminalExpiry::Finite {
+            deadline: Instant::now(),
+            unix: expired.created_at_unix,
+        };
+
+        let summary = registry
+            .summary(&live.terminal_id)
+            .await
+            .expect("live sibling remains available");
+        assert_eq!(summary.terminal_id, live.terminal_id);
+        assert!(matches!(events.try_recv(), Ok(())));
+        assert!(events.try_recv().is_err());
+    }
 }
@@ -5,6 +5,7 @@ pub use store::Store;
 #[cfg(test)]
 pub use types::AgentDeviceRow;
 pub use types::{
-    AgentDeviceWithChildren, AlertState, AuditEvent, AuditEventFilter, AuditEventInput,
-    DeviceIdentifier, DeviceIdentifierInput, KnownDevice, KnownDeviceInput, KnownDeviceSummary,
+    AgentDeviceWithChildren, AlertState, AlertTransition, AuditEvent, AuditEventFilter,
+    AuditEventInput, DeviceIdentifier, DeviceIdentifierInput, KnownDevice, KnownDeviceInput,
+    KnownDeviceSummary,
 };
@@ -10,7 +10,7 @@ use uuid::Uuid;
 use crate::state::types::{
    AlertState, AlertTransition, AuditEvent, AuditEventFilter, AuditEventInput, DeviceIdentifier,
    DeviceIdentifierInput, EnrollTokenInfo, IssuedAgent, IssuedEnrollToken, KnownDevice,
-    KnownDeviceInput, StateStats,
+    KnownDeviceInput, RetentionStats, StateStats,
 };

 pub struct Store {
@@ -103,6 +103,124 @@ mod tests {
        assert_eq!(exists, 0);
    }

+    #[tokio::test]
+    async fn enroll_rejects_negative_expiry() {
+        let ts = TestStore::new().await;
+        sqlx::query!(
+            "INSERT INTO enroll_tokens (token, expires_at_unix) VALUES (?1, ?2)",
+            "enr-negative-expiry-test",
+            -1_i64
+        )
+        .execute(&ts.store().pool)
+        .await
+        .expect("insert should succeed");
+
+        let err = ts
+            .store()
+            .enroll("enr-negative-expiry-test")
+            .await
+            .expect_err("negative expiry should be treated as expired");
+
+        assert!(err.to_string().contains("expired"));
+        let exists = sqlx::query_scalar!(
+            "SELECT COUNT(*) FROM enroll_tokens WHERE token = ?1",
+            "enr-negative-expiry-test"
+        )
+        .fetch_one(&ts.store().pool)
+        .await
+        .expect("read should succeed");
+        assert_eq!(exists, 0);
+    }
+
+    #[tokio::test]
+    async fn gc_retention_prunes_old_audit_and_alert_history() {
+        let ts = TestStore::new().await;
+
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .expect("clock should be after epoch")
+            .as_secs() as i64;
+        let old_ts = now - 86_400;
+        let old_evt = format!("{:020}:old-evt", old_ts);
+        sqlx::query!(
+            "INSERT INTO audit_events
+             (event_key, event_id, ts_unix, actor_type, actor_id, agent_id, request_id,
+              event_type, outcome, latency_ms, message, metadata_json)
+             VALUES (?1, ?2, ?3, 'test', NULL, NULL, NULL, 'test', 'ok', NULL, 'old', '{}')",
+            old_evt,
+            "old-evt",
+            old_ts
+        )
+        .execute(&ts.store().pool)
+        .await
+        .expect("old audit event should insert");
+
+        let old_atr = format!("{:020}:old-atr", old_ts);
+        sqlx::query!(
+            "INSERT INTO alert_transitions
+             (transition_key, transition_id, ts_unix, alert_id, kind, agent_id,
+              from_status, to_status, message, metadata_json)
+             VALUES (?1, ?2, ?3, 'alert-old', 'test', NULL, NULL, 'active', 'old', '{}')",
+            old_atr,
+            "old-atr",
+            old_ts
+        )
+        .execute(&ts.store().pool)
+        .await
+        .expect("old alert transition should insert");
+
+        ts.store()
+            .append_audit_event(crate::state::AuditEventInput {
+                actor_type: "test".into(),
+                actor_id: None,
+                agent_id: None,
+                request_id: None,
+                event_type: "test".into(),
+                outcome: "ok".into(),
+                latency_ms: None,
+                message: "fresh".into(),
+                metadata: serde_json::json!({}),
+            })
+            .await
+            .expect("fresh audit event should insert");
+
+        let stats = ts
+            .store()
+            .gc_retention(Duration::from_secs(3600))
+            .await
+            .expect("retention gc should succeed");
+
+        assert_eq!(stats.audit_events_removed, 1);
+        assert_eq!(stats.alert_transitions_removed, 1);
+
+        let old_audit_gone = sqlx::query_scalar!(
+            "SELECT COUNT(*) FROM audit_events WHERE event_id = ?1",
+            "old-evt"
+        )
+        .fetch_one(&ts.store().pool)
+        .await
+        .expect("read should succeed");
+        assert_eq!(old_audit_gone, 0);
+
+        let fresh_audit_remains = sqlx::query_scalar!(
+            "SELECT COUNT(*) FROM audit_events WHERE message = ?1",
+            "fresh"
+        )
+        .fetch_one(&ts.store().pool)
+        .await
+        .expect("read should succeed");
+        assert_eq!(fresh_audit_remains, 1);
+
+        let old_transition_gone = sqlx::query_scalar!(
+            "SELECT COUNT(*) FROM alert_transitions WHERE transition_id = ?1",
+            "old-atr"
+        )
+        .fetch_one(&ts.store().pool)
+        .await
+        .expect("read should succeed");
+        assert_eq!(old_transition_gone, 0);
+    }
+
    #[tokio::test]
    async fn enroll_rejects_expired_token() {
        let ts = TestStore::new().await;
@@ -209,7 +327,11 @@ mod tests {
            .expect("nickname set should succeed");
        assert!(updated);

-        let listed = ts.store().list_agents_with_nicknames().await;
+        let listed = ts
+            .store()
+            .list_agents_with_nicknames()
+            .await
+            .expect("list agents with nicknames should succeed");
        assert!(listed.iter().any(|(id, name)| {
            id == &issued.agent_id && name.as_deref() == Some("kitchen-router")
        }));
@@ -221,7 +343,11 @@ mod tests {
            .expect("nickname clear should succeed");
        assert!(cleared);

-        let listed = ts.store().list_agents_with_nicknames().await;
+        let listed = ts
+            .store()
+            .list_agents_with_nicknames()
+            .await
+            .expect("list agents with nicknames should succeed");
        assert!(
            listed
                .iter()
@@ -1,6 +1,25 @@
 use super::*;

 impl Store {
+    /// Best-effort audit append: logs the failure with event context instead of
+    /// bubbling it up. Auditing must never fail the operation that triggered it.
+    pub async fn audit(&self, input: AuditEventInput) {
+        let event_type = input.event_type.clone();
+        let outcome = input.outcome.clone();
+        let agent_id = input.agent_id.clone();
+        let request_id = input.request_id.clone();
+        if let Err(err) = self.append_audit_event(input).await {
+            warn!(
+                error = %err,
+                event_type = %event_type,
+                outcome = %outcome,
+                agent_id = ?agent_id,
+                request_id = ?request_id,
+                "failed to append audit event"
+            );
+        }
+    }
+
    pub async fn append_audit_event(&self, input: AuditEventInput) -> Result<AuditEvent> {
        let event = AuditEvent {
            event_id: format!("evt-{}", Uuid::new_v4()),
@@ -154,6 +154,37 @@ impl Store {
        Ok(removed)
    }

+    /// Prunes audit and alert history older than the retention window.
+    ///
+    /// Runs from the daemon's periodic maintenance loop; both tables have a
+    /// `ts_unix` index so the deletes stay cheap as history grows.
+    pub async fn gc_retention(&self, older_than: Duration) -> Result<RetentionStats> {
+        let cutoff = i64::try_from(now_unix().saturating_sub(older_than.as_secs().max(1)))
+            .context("retention cutoff does not fit SQLite integer")?;
+        let audit_events_removed =
+            sqlx::query!("DELETE FROM audit_events WHERE ts_unix < ?1", cutoff)
+                .execute(&self.pool)
+                .await
+                .context("failed pruning old audit events")?
+                .rows_affected();
+        let alert_transitions_removed =
+            sqlx::query!("DELETE FROM alert_transitions WHERE ts_unix < ?1", cutoff)
+                .execute(&self.pool)
+                .await
+                .context("failed pruning old alert transitions")?
+                .rows_affected();
+        if audit_events_removed > 0 || alert_transitions_removed > 0 {
+            info!(
+                audit_events_removed,
+                alert_transitions_removed, "pruned state rows older than retention window"
+            );
+        }
+        Ok(RetentionStats {
+            audit_events_removed,
+            alert_transitions_removed,
+        })
+    }
+
    async fn ensure_schema_version(&self) -> Result<()> {
        match sqlx::query_scalar!("SELECT value FROM meta WHERE key = ?1", SCHEMA_VERSION_KEY)
            .fetch_optional(&self.pool)
@@ -17,7 +17,8 @@ impl Store {
        };

        let now = now_unix();
-        if expires_at_unix as u64 <= now {
+        let now_i64 = i64::try_from(now).context("current time does not fit SQLite integer")?;
+        if expires_at_unix <= now_i64 {
            sqlx::query!("DELETE FROM enroll_tokens WHERE token = ?1", enroll_token)
                .execute(&mut *tx)
                .await
@@ -165,20 +166,16 @@ impl Store {
        }
    }

-    pub async fn list_agents(&self) -> Vec<String> {
-        match sqlx::query_scalar!(r#"SELECT agent_id as "agent_id!" FROM agents ORDER BY agent_id"#)
-            .fetch_all(&self.pool)
-            .await
-        {
-            Ok(out) => out,
-            Err(err) => {
-                warn!(error = %err, "failed to list agents from state db");
-                Vec::new()
-            }
-        }
+    pub async fn list_agents(&self) -> Result<Vec<String>> {
+        let ids =
+            sqlx::query_scalar!(r#"SELECT agent_id as "agent_id!" FROM agents ORDER BY agent_id"#)
+                .fetch_all(&self.pool)
+                .await
+                .context("failed listing agents from state db")?;
+        Ok(ids)
    }

-    pub async fn list_agents_with_nicknames(&self) -> Vec<(String, Option<String>)> {
+    pub async fn list_agents_with_nicknames(&self) -> Result<Vec<(String, Option<String>)>> {
        let rows = sqlx::query!(
            r#"SELECT agents.agent_id as "agent_id!", agent_meta.nickname
             FROM agents
@@ -186,23 +183,19 @@ impl Store {
             ORDER BY agents.agent_id"#,
        )
        .fetch_all(&self.pool)
-        .await;
+        .await
+        .context("failed listing agents from state db")?;

-        match rows {
-            Ok(rows) => rows
-                .into_iter()
-                .map(|row| {
-                    let nickname = row
-                        .nickname
-                        .map(|v| v.trim().to_string())
-                        .filter(|v| !v.is_empty());
-                    (row.agent_id, nickname)
-                })
-                .collect(),
-            Err(err) => {
-                warn!(error = %err, "failed to list agents from state db");
-                Vec::new()
-            }
-        }
+        let agents = rows
+            .into_iter()
+            .map(|row| {
+                let nickname = row
+                    .nickname
+                    .map(|v| v.trim().to_string())
+                    .filter(|v| !v.is_empty());
+                (row.agent_id, nickname)
+            })
+            .collect();
+        Ok(agents)
    }
 }
@@ -32,6 +32,12 @@ pub struct StateStats {
    pub expired_enroll_token_count: usize,
 }

+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RetentionStats {
+    pub audit_events_removed: u64,
+    pub alert_transitions_removed: u64,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct KnownDevice {
    pub device_id: String,
@@ -159,9 +159,9 @@ async fn handle_agent_socket(state: AppState, socket: WebSocket) {
            sessions.remove(&agent_id);
        }
        drop(sessions);
-        if let Err(err) = state
+        state
            .store
-            .append_audit_event(AuditEventInput {
+            .audit(AuditEventInput {
                actor_type: "agent".into(),
                actor_id: Some(agent_id.clone()),
                agent_id: Some(agent_id),
@@ -172,10 +172,7 @@ async fn handle_agent_socket(state: AppState, socket: WebSocket) {
                message: "agent websocket disconnected".into(),
                metadata: serde_json::json!({}),
            })
-            .await
-        {
-            warn!(error = %err, "failed to append audit event for ws disconnect");
-        }
+            .await;
    }

    writer.abort();
@@ -251,9 +248,9 @@ async fn process_agent_text(
                .await
            {
                warn!(agent_id = %agent_id, "agent auth rejected");
-                if let Err(err) = state
+                state
                    .store
-                    .append_audit_event(AuditEventInput {
+                    .audit(AuditEventInput {
                        actor_type: "agent".into(),
                        actor_id: Some(agent_id.clone()),
                        agent_id: Some(agent_id),
@@ -267,10 +264,7 @@ async fn process_agent_text(
                            "hello_to_auth_ms": hello_to_auth_ms,
                        }),
                    })
-                    .await
-                {
-                    warn!(error = %err, "failed to append audit event for auth rejection");
-                }
+                    .await;
                anyhow::bail!("agent auth rejected");
            }
            state.sessions.write().await.insert(
@@ -284,9 +278,9 @@ async fn process_agent_text(
            );
            connection.authed_agent_id = Some(agent_id.clone());
            info!(agent_id = %agent_id, connect_to_auth_ms, hello_to_auth_ms = hello_to_auth_ms.unwrap_or(0), "agent authenticated");
-            if let Err(err) = state
+            state
                .store
-                .append_audit_event(AuditEventInput {
+                .audit(AuditEventInput {
                    actor_type: "agent".into(),
                    actor_id: Some(agent_id.clone()),
                    agent_id: Some(agent_id),
@@ -300,10 +294,7 @@ async fn process_agent_text(
                        "hello_to_auth_ms": hello_to_auth_ms,
                    }),
                })
-                .await
-            {
-                warn!(error = %err, "failed to append audit event for auth success");
-            }
+                .await;
            let _ = tx.send(SessionEvent::Message(ServerMessage::SyncDeviceSnapshot));
        }
        IncomingClientMessage::Heartbeat { agent_id } => {
@@ -1,6 +1,6 @@
 [package]
 name = "wakey-core"
-version = "0.3.5"
+version = "0.3.6"
 edition = "2024"
 publish = ["gitea"]

@@ -1,6 +1,6 @@
 [package]
 name = "wakey-linux"
-version = "0.3.5"
+version = "0.3.6"
 edition = "2024"
 publish = ["gitea"]