ocuclaw 0.1.0 → 1.3.0

package/dist/runtime/downstream-server.js

@@ -1,4 +1,6 @@
 import * as WebSocketModule from "ws";
+import { createRelayClientNudgeController } from "./relay-client-nudge-controller.js";
+import * as RelayWorkerProtocol from "./relay-worker-protocol.js";
 
 // `ws` exposes different server entrypoints across ESM/CJS consumers.
 const WebSocket =
@@ -6,6 +8,12 @@ const WebSocket =
 const WebSocketServer =
   WebSocketModule.WebSocketServer || WebSocketModule.Server || WebSocket.Server;
 
+// Bounded wait for the single app client to answer a forwarded automation
+// state request. Pending entries are otherwise cleared only by a matching
+// reply or a disconnect, so a connected-but-silent app would leave the
+// requester waiting forever.
+const AUTOMATION_STATE_REPLY_TIMEOUT_MS = 1500;
+
 function normalizeLogger(logger) {
   if (!logger || typeof logger !== "object") {
     return console;
@@ -60,54 +68,93 @@ function createDownstreamServer(opts) {
   const getCurrentStatus = opts.getCurrentStatus;
   const getCurrentDebugConfig = opts.getCurrentDebugConfig || null;
   const getCurrentResumeState = opts.getCurrentResumeState || null;
+  const getAgentAvatarDataUriByHash =
+    typeof opts.getAgentAvatarDataUriByHash === "function"
+      ? opts.getAgentAvatarDataUriByHash
+      : () => null;
   const token = opts.token;
   const onClientConnected = opts.onClientConnected || null;
   const onClientDisconnected = opts.onClientDisconnected || null;
   const onTransportControl = opts.onTransportControl || null;
+  const relayHealth = opts.relayHealth || null;
+  const sendBufferSnapshotForTest =
+    typeof opts.sendBufferSnapshotForTest === "function"
+      ? opts.sendBufferSnapshotForTest
+      : null;
+  const getPluginVersion =
+    typeof opts.getPluginVersion === "function" ? opts.getPluginVersion : null;
+  const getRequiresClientVersion =
+    typeof opts.getRequiresClientVersion === "function" ? opts.getRequiresClientVersion : null;
+  const pluginId =
+    typeof opts.pluginId === "string" && opts.pluginId.trim().length > 0
+      ? opts.pluginId.trim()
+      : null;
+  const runPluginUpdate =
+    typeof opts.runPluginUpdate === "function" ? opts.runPluginUpdate : null;
+  const runGatewayRestart =
+    typeof opts.runGatewayRestart === "function" ? opts.runGatewayRestart : null;
+  const sessionService =
+    opts.sessionService && typeof opts.sessionService === "object"
+      ? opts.sessionService
+      : null;
   const protocolHelloTimeoutMs = Number.isFinite(opts.protocolHelloTimeoutMs)
     ? Math.max(0, Math.floor(opts.protocolHelloTimeoutMs))
-    : 120;
+    : 10000;
   const externalDebugToolsEnabled = opts.externalDebugToolsEnabled !== false;
   const resumeHandshakeTimeoutMs = Number.isFinite(opts.resumeHandshakeTimeoutMs)
     ? Math.max(0, Math.floor(opts.resumeHandshakeTimeoutMs))
-    : 120;
-  const nudgeActiveIntervalMs = Number.isFinite(opts.nudgeActiveIntervalMs)
-    ? Math.max(1, Math.floor(opts.nudgeActiveIntervalMs))
-    : 150;
-  const nudgeSlowIntervalMs = Number.isFinite(opts.nudgeSlowIntervalMs)
-    ? Math.max(1, Math.floor(opts.nudgeSlowIntervalMs))
-    : 1000;
-  const nudgeIdleDeactivateMs = Number.isFinite(opts.nudgeIdleDeactivateMs)
-    ? Math.max(0, Math.floor(opts.nudgeIdleDeactivateMs))
-    : 5000;
-  const nudgeHeartbeatIntervalMs = Number.isFinite(opts.nudgeHeartbeatIntervalMs)
-    ? Math.max(1, Math.floor(opts.nudgeHeartbeatIntervalMs))
-    : 10000;
-  const nudgeHardTimeoutMs = Number.isFinite(opts.nudgeHardTimeoutMs)
-    ? Math.max(1, Math.floor(opts.nudgeHardTimeoutMs))
-    : 60000;
-  const nudgeStaleHeartbeatThresholdMs = nudgeHeartbeatIntervalMs * 2;
-  const RENDER_NUDGE_FRAME = JSON.stringify({ type: "render_nudge" });
-
+    : 1500;
   /** @type {Map<string, WebSocket>} */
   const clients = new Map();
   /** @type {Map<string, {selectedVersion: "v2"|null, supportedProtocolVersions: string[], clientName: string|null, clientVersion: string|null, sessionKey: string|null, reason: string|null}>} */
   const protocolState = new Map();
   /** @type {Map<string, {pagesSynced: boolean, statusSynced: boolean, approvalsSynced: boolean, debugConfigSynced: boolean, resumeReceived: boolean, timer: any}>} */
   const syncState = new Map();
-  /** @type {Map<string, {visibilityState: "hidden"|"visible"|"blurred"|null, streamChars: number|null, lastHeartbeatAtMs: number|null, lastRelayStreamingActivityAtMs: number|null, interactionStage: "idle"|"listening"|"voice_handoff"|"thinking"|"streaming"|"post_turn_drain", cadenceBucket: "idle"|"active_non_stream"|"active_stream", nudgeActive: boolean, nudgeIntervalMs: number|null, nudgeStartedAtMs: number|null, lastNudgeAtMs: number|null, stalledHeartbeatCount: number, nudgeTimer: any, idleDeactivateTimer: any, staleHeartbeatTimer: any, hardTimeoutTimer: any}>} */
-  const clientNudgeState = new Map();
+  /** @type {Map<string, {clientDebugEnabled: boolean|null, runtimeDiagnosticsVisible: boolean|null, perfNoisyDebugMuted: boolean|null, perfPayloadLiteMode: boolean|null, activeSessionKey: string|null, bundleIdentity: {kind: string|null, mode: string|null, host: string|null, port: number|null, servedDistPath: string|null}|null, runtimeContext: string|null, glasses: {connected: boolean, batteryPercent: number|null, statusAgeMs: number|null}|null, emittedAtMs: number|null, updatedAtMs: number}>} */
+  const clientReadinessSnapshotState = new Map();
+  /** @type {Map<string, {requesterClientId: string, targetClientId: string, createdAtMs: number}>} */
+  const pendingReadinessProbeRequests = new Map();
+  /** @type {Map<string, {requesterClientId: string, targetClientId: string, createdAtMs: number, expiryTimer: any}>} */
+  const pendingAutomationStateRequests = new Map();
   /** @type {Map<string, string>} */
   const unresolvedApprovals = new Map();
+  const nudgeController = createRelayClientNudgeController({
+    thresholds: {
+      nudgeActiveIntervalMs: opts.nudgeActiveIntervalMs,
+      nudgeSlowIntervalMs: opts.nudgeSlowIntervalMs,
+      nudgeIdleDeactivateMs: opts.nudgeIdleDeactivateMs,
+      nudgeHeartbeatIntervalMs: opts.nudgeHeartbeatIntervalMs,
+      nudgeHardTimeoutMs: opts.nudgeHardTimeoutMs,
+    },
+    isAppClient,
+    sendFrame(clientId, frame) {
+      const ws = clients.get(clientId);
+      if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+      sendMessageToClient(clientId, ws, frame);
+      return true;
+    },
+  });
   let nextClientId = 1;
+  let pendingHandlerPromiseCount = 0;
   const APP_PROTOCOL = {
     approvalRequest: "ocuclaw.approval.request",
     approvalResolved: "ocuclaw.approval.resolved",
+    automationStateGet: "ocuclaw.automation.state.get",
+    automationStateSnapshot: "ocuclaw.automation.state.snapshot",
+    avatarBlob: "ocuclaw.avatar.blob",
+    avatarFetch: "ocuclaw.avatar.fetch",
     debugConfigSnapshot: "ocuclaw.debug.config.snapshot",
     pages: "ocuclaw.view.pages.snapshot",
+    readinessProbeAck: "ocuclaw.readiness.probe.ack",
+    readinessProbeRequest: "ocuclaw.readiness.probe.request",
+    readinessSnapshot: "ocuclaw.readiness.snapshot",
     resume: "ocuclaw.sync.resume",
     resumeAck: "ocuclaw.sync.resume.ack",
+    restartGateway: "ocuclaw.restartGateway",
+    restartGatewayAck: "ocuclaw.restartGatewayAck",
     status: "ocuclaw.runtime.status",
+    updatePlugin: "ocuclaw.updatePlugin",
+    updatePluginResult: "ocuclaw.updatePluginResult",
   };
   const REMOVED_V1_APP_TYPES = new Set([
     "approvalResponse",
@@ -149,7 +196,10 @@ function createDownstreamServer(opts) {
     }
 
     const nextRole =
-      messageType === "remote-control" ? "control" : "app";
+      messageType === "remote-control" ||
+      messageType === APP_PROTOCOL.automationStateGet
+        ? "control"
+        : "app";
     if (meta.role === "unknown") {
       meta.role = nextRole;
       return;
@@ -159,13 +209,6 @@ function createDownstreamServer(opts) {
     }
   }
 
-  function parseRevision(value) {
-    if (!Number.isFinite(Number(value))) return null;
-    const num = Math.floor(Number(value));
-    if (num < 0) return null;
-    return num;
-  }
-
   function parseBool(value) {
     if (value === true || value === false) return value;
     if (typeof value === "number") return value !== 0;
@@ -174,6 +217,20 @@ function createDownstreamServer(opts) {
     return normalized === "true" || normalized === "1" || normalized === "yes";
   }
 
+  function parseOptionalBoolean(value) {
+    if (value === true || value === false) return value;
+    if (typeof value === "number") return value !== 0;
+    if (typeof value !== "string") return null;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true" || normalized === "1" || normalized === "yes") {
+      return true;
+    }
+    if (normalized === "false" || normalized === "0" || normalized === "no") {
+      return false;
+    }
+    return null;
+  }
+
   function parseOptionalTrimmedString(value) {
     if (typeof value !== "string") return null;
     const trimmed = value.trim();
@@ -262,6 +319,134 @@ function createDownstreamServer(opts) {
         parseOptionalTrimmedString(value.clientId),
       clientVersion: parseOptionalTrimmedString(value.clientVersion),
       sessionKey: parseOptionalTrimmedString(value.sessionKey),
+      readinessSnapshot: parseReadinessSnapshot(value.readinessSnapshot),
+    };
+  }
+
+  function parseReadinessBundleIdentity(value) {
+    if (!value || typeof value !== "object") {
+      return null;
+    }
+    const kind = parseOptionalTrimmedString(value.kind || value.lane);
+    const mode = parseOptionalTrimmedString(value.mode);
+    const host = parseOptionalTrimmedString(value.host);
+    const port = parseOptionalNonNegativeInt(value.port);
+    const servedDistPath =
+      parseOptionalTrimmedString(value.servedDistPath) ||
+      parseOptionalTrimmedString(value.staticDir);
+    if (!kind && !mode && !host && port === null && !servedDistPath) {
+      return null;
+    }
+    return {
+      kind: kind || null,
+      mode: mode || null,
+      host: host || null,
+      port,
+      servedDistPath: servedDistPath || null,
+    };
+  }
+
+  function parseReadinessRuntimeContext(value) {
+    const s = parseOptionalTrimmedString(value);
+    return s === "native_app" || s === "simulator" || s === "browser" ? s : null;
+  }
+
+  function parseReadinessGlasses(value) {
+    if (!value || typeof value !== "object") {
+      return null;
+    }
+    const connected = parseOptionalBoolean(value.connected);
+    if (connected === null) {
+      return null;
+    }
+    let batteryPercent = parseOptionalNonNegativeInt(value.batteryPercent);
+    if (batteryPercent !== null) {
+      batteryPercent = Math.min(100, batteryPercent);
+    }
+    const statusAgeMs = parseOptionalNonNegativeInt(value.statusAgeMs);
+    return { connected, batteryPercent, statusAgeMs };
+  }
+
+  function parseReadinessSnapshot(value) {
+    if (!value || typeof value !== "object") {
+      return null;
+    }
+    const clientDebugEnabled = parseOptionalBoolean(value.clientDebugEnabled);
+    const runtimeDiagnosticsVisible = parseOptionalBoolean(
+      value.runtimeDiagnosticsVisible,
+    );
+    const perfNoisyDebugMuted = parseOptionalBoolean(value.perfNoisyDebugMuted);
+    const perfPayloadLiteMode = parseOptionalBoolean(value.perfPayloadLiteMode);
+    const activeSessionKey =
+      parseOptionalTrimmedString(value.activeSessionKey) ||
+      parseOptionalTrimmedString(value.sessionKey);
+    const bundleIdentity = parseReadinessBundleIdentity(
+      value.bundleIdentity || value.bundle,
+    );
+    const runtimeContext = parseReadinessRuntimeContext(value.runtimeContext);
+    const glasses = parseReadinessGlasses(value.glasses);
+    const emittedAtMs = parseOptionalNonNegativeInt(value.emittedAtMs);
+    if (
+      clientDebugEnabled === null &&
+      runtimeDiagnosticsVisible === null &&
+      perfNoisyDebugMuted === null &&
+      perfPayloadLiteMode === null &&
+      !activeSessionKey &&
+      !bundleIdentity &&
+      !runtimeContext &&
+      !glasses &&
+      emittedAtMs === null
+    ) {
+      return null;
+    }
+    return {
+      clientDebugEnabled,
+      runtimeDiagnosticsVisible,
+      perfNoisyDebugMuted,
+      perfPayloadLiteMode,
+      activeSessionKey: activeSessionKey || null,
+      bundleIdentity,
+      runtimeContext,
+      glasses,
+      emittedAtMs,
+      updatedAtMs: Date.now(),
+    };
+  }
+
+  function parseReadinessProbeAck(value) {
+    if (!value || value.type !== APP_PROTOCOL.readinessProbeAck) {
+      return null;
+    }
+    const requestId = parseOptionalTrimmedString(value.requestId);
+    if (!requestId) {
+      return null;
+    }
+    return {
+      requestId,
+      ok: value.ok !== false,
+      reasonCode: parseOptionalTrimmedString(value.reasonCode),
+      message: parseOptionalTrimmedString(value.message),
+      activeSessionKey:
+        parseOptionalTrimmedString(value.activeSessionKey) ||
+        parseOptionalTrimmedString(value.sessionKey),
+      emittedAtMs: parseOptionalNonNegativeInt(value.emittedAtMs),
+    };
+  }
+
+  function parseAutomationStateSnapshot(value) {
+    if (!value || value.type !== APP_PROTOCOL.automationStateSnapshot) {
+      return null;
+    }
+    const requestId = parseOptionalTrimmedString(value.requestId);
+    if (!requestId) {
+      return null;
+    }
+    return {
+      requestId,
+      ok: value.ok !== false,
+      state: value.state && typeof value.state === "object" ? value.state : null,
+      reasonCode: parseOptionalTrimmedString(value.reasonCode),
+      message: parseOptionalTrimmedString(value.message),
     };
   }
 
@@ -292,7 +477,7 @@ function createDownstreamServer(opts) {
     return classifyClientKindFromName(clientName);
   }
 
-  function countConnectedAppClients(excludeClientId = null) {
+  function countConnectedAppClients(excludeClientId = null, sessionKey = null) {
     let count = 0;
     for (const [clientId, ws] of clients) {
       if (excludeClientId && clientId === excludeClientId) {
@@ -301,7 +486,14 @@ function createDownstreamServer(opts) {
       if (!ws || ws.readyState !== WebSocket.OPEN) {
         continue;
       }
-      if (classifyClientKind(protocolState.get(clientId)) !== "app") {
+      const protocol = protocolState.get(clientId);
+      if (classifyClientKind(protocol) !== "app") {
+        continue;
+      }
+      // When sessionKey is provided, only count app clients bound to that
+      // session — lets callers ask "is this session's last app gone?"
+      // without being masked by apps in other sessions.
+      if (sessionKey != null && (!protocol || protocol.sessionKey !== sessionKey)) {
         continue;
       }
       count += 1;
@@ -349,27 +541,16 @@ function createDownstreamServer(opts) {
     };
   }
 
-  function interactionStageBucket(stage) {
-    switch (stage) {
-      case "listening":
-      case "voice_handoff":
-      case "thinking":
-        return "active_non_stream";
-      case "streaming":
-      case "post_turn_drain":
-        return "active_stream";
-      default:
-        return "idle";
-    }
-  }
-
   function formatProtocolHelloAck(payload) {
-    return JSON.stringify({
-      type: "protocolHelloAck",
+    const pluginVersion = getPluginVersion ? getPluginVersion() : null;
+    const requiresClientVersion = getRequiresClientVersion ? getRequiresClientVersion() : null;
+    return RelayWorkerProtocol.formatProtocolHelloAck({
       protocolVersion: payload.protocolVersion,
       supportedProtocolVersions: payload.supportedProtocolVersions || ["v2"],
-      reason: payload.reason || null,
-      deprecatedV1: false,
+      reason: payload.reason,
+      pluginVersion,
+      requiresClientVersion,
+      pluginId,
     });
   }
 
@@ -389,436 +570,125 @@ function createDownstreamServer(opts) {
     return state;
   }
 
-  function createClientNudgeState() {
+  function cloneReadinessBundleIdentity(value) {
+    if (!value) return null;
     return {
-      visibilityState: null,
-      streamChars: null,
-      lastHeartbeatAtMs: null,
-      lastRelayStreamingActivityAtMs: null,
-      interactionStage: "idle",
-      cadenceBucket: "idle",
-      nudgeActive: false,
-      nudgeIntervalMs: null,
-      nudgeStartedAtMs: null,
-      lastNudgeAtMs: null,
-      stalledHeartbeatCount: 0,
-      nudgeTimer: null,
-      idleDeactivateTimer: null,
-      staleHeartbeatTimer: null,
-      hardTimeoutTimer: null,
+      kind: value.kind || null,
+      mode: value.mode || null,
+      host: value.host || null,
+      port: Number.isFinite(value.port) ? value.port : null,
+      servedDistPath: value.servedDistPath || null,
     };
   }
 
-  function ensureClientNudgeState(clientId) {
-    let state = clientNudgeState.get(clientId);
-    if (!state) {
-      state = createClientNudgeState();
-      clientNudgeState.set(clientId, state);
-    }
-    return state;
-  }
-
-  function cloneClientNudgeState(state) {
-    if (!state) return null;
+  function cloneReadinessGlasses(value) {
+    if (!value) return null;
+    // The dedicated ocuclaw.readiness.snapshot frame is stored raw via clone
+    // (no parseReadinessGlasses pass), so clamp/validate defensively here too.
+    const batteryPercent = Number.isFinite(value.batteryPercent)
+      ? Math.min(100, Math.max(0, value.batteryPercent))
+      : null;
+    const statusAgeMs =
+      Number.isFinite(value.statusAgeMs) && value.statusAgeMs >= 0
+        ? value.statusAgeMs
+        : null;
     return {
-      visibilityState: state.visibilityState || null,
-      streamChars: Number.isFinite(state.streamChars) ? state.streamChars : null,
-      lastHeartbeatAtMs: Number.isFinite(state.lastHeartbeatAtMs)
-        ? state.lastHeartbeatAtMs
-        : null,
-      lastRelayStreamingActivityAtMs: Number.isFinite(
-        state.lastRelayStreamingActivityAtMs,
-      )
-        ? state.lastRelayStreamingActivityAtMs
-        : null,
-      interactionStage: state.interactionStage || "idle",
-      cadenceBucket: state.cadenceBucket || "idle",
-      nudgeActive: !!state.nudgeActive,
-      nudgeIntervalMs: Number.isFinite(state.nudgeIntervalMs)
-        ? state.nudgeIntervalMs
-        : null,
-      nudgeStartedAtMs: Number.isFinite(state.nudgeStartedAtMs)
-        ? state.nudgeStartedAtMs
-        : null,
-      lastNudgeAtMs: Number.isFinite(state.lastNudgeAtMs)
-        ? state.lastNudgeAtMs
-        : null,
-      stalledHeartbeatCount: Number.isFinite(state.stalledHeartbeatCount)
-        ? state.stalledHeartbeatCount
-        : 0,
+      connected: value.connected === true,
+      batteryPercent,
+      statusAgeMs,
     };
   }
 
-  function clearClientNudgeTimer(state, key, clearFn = clearTimeout) {
-    if (!state || !state[key]) return;
-    clearFn(state[key]);
-    state[key] = null;
-  }
-
-  function clearClientNudgeTimers(clientId) {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
-    clearClientNudgeTimer(state, "idleDeactivateTimer");
-    clearClientNudgeTimer(state, "staleHeartbeatTimer");
-    clearClientNudgeTimer(state, "hardTimeoutTimer");
-  }
-
-  function isStreamingBroadcastType(messageType) {
-    return (
-      messageType === "streaming" ||
-      messageType === "ocuclaw.message.stream.delta"
-    );
-  }
-
-  function isPagesBroadcastType(messageType) {
-    return messageType === "pages" || messageType === APP_PROTOCOL.pages;
-  }
-
-  function isActivityBroadcastType(messageType) {
-    return messageType === "activity" || messageType === "ocuclaw.activity.update";
-  }
-
-  function isListenCommittedBroadcastType(messageType) {
-    return messageType === "listen-committed";
-  }
-
-  function isListenEndedBroadcastType(messageType) {
-    return messageType === "listen-ended";
-  }
-
-  function resetClientStallTracking(state) {
-    if (!state) return;
-    state.stalledHeartbeatCount = 0;
-  }
-
-  function hasStaleHeartbeat(state, now = Date.now()) {
-    if (!state || !Number.isFinite(state.lastHeartbeatAtMs)) {
-      return false;
-    }
-    return now - state.lastHeartbeatAtMs >= nudgeStaleHeartbeatThresholdMs;
-  }
-
-  function isVisibilityDegraded(state) {
-    return (
-      !!state &&
-      (state.visibilityState === "hidden" || state.visibilityState === "blurred")
-    );
-  }
-
-  function sendRenderNudge(clientId) {
-    const ws = clients.get(clientId);
-    if (!ws || ws.readyState !== WebSocket.OPEN) {
-      stopClientNudges(clientId, "socket_unavailable");
-      return;
-    }
-    sendMessageToClient(clientId, ws, RENDER_NUDGE_FRAME);
-    ensureClientNudgeState(clientId).lastNudgeAtMs = Date.now();
-  }
-
-  function scheduleClientHardTimeout(clientId) {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "hardTimeoutTimer");
-    if (!state.nudgeActive) return;
-    state.hardTimeoutTimer = setTimeout(() => {
-      state.hardTimeoutTimer = null;
-      setClientInteractionStage(clientId, "idle", {
-        reason: "nudge_hard_timeout",
-        deactivateImmediately: true,
-      });
-    }, nudgeHardTimeoutMs);
-  }
-
-  function startClientNudges(
-    clientId,
-    intervalMs,
-    reason = "nudge_start",
-    sendImmediately = false,
-  ) {
-    if (!isAppClient(clientId)) return;
-    const ws = clients.get(clientId);
-    if (!ws || ws.readyState !== WebSocket.OPEN) return;
-    const state = ensureClientNudgeState(clientId);
-    const nextIntervalMs = Math.max(1, Math.floor(intervalMs));
-    const wasActive = !!state.nudgeActive;
-    const intervalChanged = state.nudgeIntervalMs !== nextIntervalMs;
-    state.cadenceBucket = interactionStageBucket(state.interactionStage);
-    if (!wasActive) {
-      state.nudgeActive = true;
-      state.nudgeStartedAtMs = Date.now();
-    }
-    if (wasActive && !intervalChanged) {
-      return;
-    }
-    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
-    state.nudgeActive = true;
-    state.nudgeIntervalMs = nextIntervalMs;
-    state.nudgeTimer = setInterval(() => {
-      sendRenderNudge(clientId);
-    }, nextIntervalMs);
-    if (!wasActive) {
-      scheduleClientHardTimeout(clientId);
-      if (sendImmediately) {
-        sendRenderNudge(clientId);
-      }
-    }
-  }
-
-  function stopClientNudges(clientId, _reason = "nudge_stop") {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
-    clearClientNudgeTimer(state, "idleDeactivateTimer");
-    clearClientNudgeTimer(state, "hardTimeoutTimer");
-    state.nudgeActive = false;
-    state.nudgeIntervalMs = null;
-    state.nudgeStartedAtMs = null;
-    resetClientStallTracking(state);
-    scheduleClientStaleHeartbeatCheck(clientId);
+  function cloneReadinessSnapshot(value) {
+    if (!value) return null;
+    return {
+      clientDebugEnabled:
+        value.clientDebugEnabled === true || value.clientDebugEnabled === false
+          ? value.clientDebugEnabled
+          : null,
+      runtimeDiagnosticsVisible:
+        value.runtimeDiagnosticsVisible === true ||
+        value.runtimeDiagnosticsVisible === false
+          ? value.runtimeDiagnosticsVisible
+          : null,
+      perfNoisyDebugMuted:
+        value.perfNoisyDebugMuted === true || value.perfNoisyDebugMuted === false
+          ? value.perfNoisyDebugMuted
+          : null,
+      perfPayloadLiteMode:
+        value.perfPayloadLiteMode === true || value.perfPayloadLiteMode === false
+          ? value.perfPayloadLiteMode
+          : null,
+      activeSessionKey: value.activeSessionKey || null,
+      bundleIdentity: cloneReadinessBundleIdentity(value.bundleIdentity),
+      runtimeContext:
+        value.runtimeContext === "native_app" ||
+        value.runtimeContext === "simulator" ||
+        value.runtimeContext === "browser"
+          ? value.runtimeContext
+          : null,
+      glasses: cloneReadinessGlasses(value.glasses),
+      emittedAtMs: Number.isFinite(value.emittedAtMs) ? value.emittedAtMs : null,
+      updatedAtMs: Number.isFinite(value.updatedAtMs) ? value.updatedAtMs : null,
+    };
   }
 
-  function scheduleClientIdleDeactivation(clientId) {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "idleDeactivateTimer");
-    if (!state.nudgeActive || state.interactionStage !== "idle") {
-      return;
-    }
-    state.idleDeactivateTimer = setTimeout(() => {
-      state.idleDeactivateTimer = null;
-      const currentState = clientNudgeState.get(clientId);
-      if (!currentState || currentState.interactionStage !== "idle") {
-        return;
-      }
-      stopClientNudges(clientId, "idle_grace_elapsed");
-    }, nudgeIdleDeactivateMs);
+  function updateClientReadinessSnapshot(clientId, snapshot) {
+    if (!clientId || !snapshot) return null;
+    const next = cloneReadinessSnapshot({
+      ...snapshot,
+      updatedAtMs: Date.now(),
+    });
+    clientReadinessSnapshotState.set(clientId, next);
+    return next;
   }
 
-  function scheduleClientStaleHeartbeatCheck(clientId) {
-    const state = clientNudgeState.get(clientId);
-    if (!state) return;
-    clearClientNudgeTimer(state, "staleHeartbeatTimer");
-    if (
-      state.nudgeActive ||
-      interactionStageBucket(state.interactionStage) === "idle" ||
-      !Number.isFinite(state.lastHeartbeatAtMs)
-    ) {
-      return;
-    }
-    const delayMs = Math.max(
-      0,
-      (state.lastHeartbeatAtMs + nudgeStaleHeartbeatThresholdMs) - Date.now(),
-    );
-    state.staleHeartbeatTimer = setTimeout(() => {
-      state.staleHeartbeatTimer = null;
-      const currentState = clientNudgeState.get(clientId);
+  function clearPendingReadinessProbesForClient(clientId) {
+    if (!clientId) return;
+    for (const [requestId, pending] of pendingReadinessProbeRequests) {
+      if (!pending) continue;
       if (
-        !currentState ||
-        currentState.nudgeActive ||
-        interactionStageBucket(currentState.interactionStage) === "idle"
+        pending.requesterClientId === clientId ||
+        pending.targetClientId === clientId
       ) {
-        return;
-      }
-      if (!hasStaleHeartbeat(currentState)) {
-        scheduleClientStaleHeartbeatCheck(clientId);
-        return;
-      }
-      startClientNudges(
-        clientId,
-        nudgeActiveIntervalMs,
-        "stale_heartbeat_fallback",
-        true,
-      );
-    }, delayMs);
-  }
-
-  function maybeActivateClientNudges(clientId, reason = "nudge_eval") {
-    const state = clientNudgeState.get(clientId);
-    if (!state || !isAppClient(clientId)) return;
-    state.cadenceBucket = interactionStageBucket(state.interactionStage);
-    if (state.cadenceBucket === "idle") {
-      clearClientNudgeTimer(state, "staleHeartbeatTimer");
-      return;
-    }
-    if (state.nudgeActive) {
-      return;
-    }
-    if (isVisibilityDegraded(state) || hasStaleHeartbeat(state)) {
-      startClientNudges(clientId, nudgeActiveIntervalMs, reason, true);
-      return;
-    }
-    scheduleClientStaleHeartbeatCheck(clientId);
-  }
-
-  function setClientInteractionStage(clientId, nextStage, options = {}) {
-    if (!isAppClient(clientId)) return;
-    const state = ensureClientNudgeState(clientId);
-    const reason = options.reason || "interaction_stage";
-    const deactivateImmediately = options.deactivateImmediately === true;
-    state.interactionStage = nextStage;
-    state.cadenceBucket = interactionStageBucket(nextStage);
-    if (state.cadenceBucket !== "active_stream") {
-      resetClientStallTracking(state);
-    }
-    if (state.cadenceBucket === "idle") {
-      clearClientNudgeTimer(state, "staleHeartbeatTimer");
-      if (deactivateImmediately) {
-        stopClientNudges(clientId, reason);
-      } else {
-        scheduleClientIdleDeactivation(clientId);
+        pendingReadinessProbeRequests.delete(requestId);
       }
-      return;
     }
-    clearClientNudgeTimer(state, "idleDeactivateTimer");
-    if (
-      state.cadenceBucket === "active_non_stream" &&
-      state.nudgeActive &&
-      state.nudgeIntervalMs !== nudgeActiveIntervalMs
-    ) {
-      startClientNudges(clientId, nudgeActiveIntervalMs, reason, false);
-    }
-    maybeActivateClientNudges(clientId, reason);
   }
 
-  function observeRelayStreamingActivity(clientId, atMs) {
-    if (!isAppClient(clientId)) return;
-    const state = ensureClientNudgeState(clientId);
-    state.lastRelayStreamingActivityAtMs = atMs;
-    resetClientStallTracking(state);
-    if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
-      startClientNudges(clientId, nudgeActiveIntervalMs, "relay_stream_progress");
-      return;
-    }
-    maybeActivateClientNudges(clientId, "relay_stream_activity");
-  }
-
-  function updateClientNudgeHeartbeat(clientId, ping) {
-    const state = ensureClientNudgeState(clientId);
-    const previousHeartbeatAtMs = Number.isFinite(state.lastHeartbeatAtMs)
-      ? state.lastHeartbeatAtMs
-      : null;
-    const previousStreamChars = Number.isFinite(state.streamChars)
-      ? state.streamChars
-      : null;
-    const nextStreamChars = Number.isFinite(ping.streamChars) ? ping.streamChars : null;
-    const streamAdvanced =
-      nextStreamChars !== null &&
-      (previousStreamChars === null || nextStreamChars > previousStreamChars);
-    const relayStreamAdvanced =
-      previousHeartbeatAtMs !== null &&
-      Number.isFinite(state.lastRelayStreamingActivityAtMs) &&
-      state.lastRelayStreamingActivityAtMs > previousHeartbeatAtMs;
-    state.streamChars = nextStreamChars;
-    if (ping.visibilityState) {
-      state.visibilityState = ping.visibilityState;
-    }
-    state.lastHeartbeatAtMs = Date.now();
-    state.cadenceBucket = interactionStageBucket(state.interactionStage);
-    if (state.visibilityState === "visible") {
-      stopClientNudges(clientId, "heartbeat_visible");
-    }
-    if (state.cadenceBucket === "active_stream") {
-      if (streamAdvanced || relayStreamAdvanced) {
-        resetClientStallTracking(state);
-        if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
-          startClientNudges(
-            clientId,
-            nudgeActiveIntervalMs,
-            streamAdvanced
-              ? "heartbeat_stream_progress"
-              : "relay_stream_progress",
-            false,
-          );
-        }
-      } else if (state.nudgeActive) {
-        state.stalledHeartbeatCount += 1;
-        if (
-          state.stalledHeartbeatCount >= 3 &&
-          state.nudgeIntervalMs !== nudgeSlowIntervalMs
-        ) {
-          startClientNudges(
-            clientId,
-            nudgeSlowIntervalMs,
-            "stream_stalled_decelerated",
-            false,
-          );
-        }
-      }
-    } else {
-      resetClientStallTracking(state);
-      if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
-        startClientNudges(clientId, nudgeActiveIntervalMs, "non_stream_fast", false);
+  function clearPendingAutomationStateRequestsForClient(clientId) {
+    if (!clientId) return;
+    for (const [requestId, pending] of pendingAutomationStateRequests) {
+      if (!pending) continue;
+      if (
+        pending.requesterClientId === clientId ||
+        pending.targetClientId === clientId
+      ) {
+        if (pending.expiryTimer) clearTimeout(pending.expiryTimer);
+        pendingAutomationStateRequests.delete(requestId);
       }
     }
-    maybeActivateClientNudges(clientId, "heartbeat_update");
   }
 
-  function updateClientVisibilityState(clientId, visibilityState) {
-    const state = ensureClientNudgeState(clientId);
-    state.visibilityState = visibilityState;
-    if (visibilityState === "visible") {
-      stopClientNudges(clientId, "visibility_visible");
-      return;
-    }
-    maybeActivateClientNudges(clientId, "visibility_hidden");
+  function buildReadinessClientEntry(clientId) {
+    const protocol = protocolState.get(clientId);
+    return {
+      clientId,
+      clientKind: classifyClientKind(protocol),
+      clientName: protocol && protocol.clientName ? protocol.clientName : null,
+      clientVersion: protocol && protocol.clientVersion ? protocol.clientVersion : null,
+      protocolSessionKey: protocol && protocol.sessionKey ? protocol.sessionKey : null,
+      readinessSnapshot: cloneReadinessSnapshot(
+        clientReadinessSnapshotState.get(clientId) || null,
+      ),
+    };
   }
 
-  function applyBroadcastInteractionStage(messageType, parsed, relayStreamingActivityAtMs) {
-    for (const [clientId] of clients) {
-      if (!isAppClient(clientId)) {
-        continue;
-      }
-      if (relayStreamingActivityAtMs !== null) {
-        setClientInteractionStage(clientId, "streaming", {
-          reason: "relay_streaming",
-        });
-        observeRelayStreamingActivity(clientId, relayStreamingActivityAtMs);
-        continue;
-      }
-      if (isListenCommittedBroadcastType(messageType)) {
-        setClientInteractionStage(clientId, "voice_handoff", {
-          reason: "listen_committed",
-        });
-        continue;
-      }
-      if (isListenEndedBroadcastType(messageType)) {
-        setClientInteractionStage(clientId, "idle", {
-          reason: "listen_ended",
-          deactivateImmediately: true,
-        });
-        continue;
-      }
-      if (isActivityBroadcastType(messageType)) {
-        const activityState = parseOptionalTrimmedString(parsed && parsed.state);
-        const normalizedActivity = activityState ? activityState.toLowerCase() : null;
-        const currentStage = ensureClientNudgeState(clientId).interactionStage;
-        if (normalizedActivity === "thinking") {
-          setClientInteractionStage(clientId, "thinking", {
-            reason: "activity_thinking",
-          });
-        } else if (normalizedActivity === "idle") {
-          if (currentStage === "streaming" || currentStage === "post_turn_drain") {
-            setClientInteractionStage(clientId, "post_turn_drain", {
-              reason: "activity_idle_stream_drain",
-            });
-          } else {
-            setClientInteractionStage(clientId, "idle", {
-              reason: "activity_idle",
-            });
-          }
-        }
-        continue;
-      }
-      if (isPagesBroadcastType(messageType)) {
-        const currentState = ensureClientNudgeState(clientId);
-        if (interactionStageBucket(currentState.interactionStage) !== "idle") {
-          setClientInteractionStage(clientId, "post_turn_drain", {
-            reason: "pages_snapshot",
-          });
-        }
-      }
-    }
+  function isStreamingBroadcastType(messageType) {
+    return (
+      messageType === "streaming" ||
+      messageType === "ocuclaw.message.stream.delta"
+    );
   }
 
   function updateProtocolSessionKey(clientId, value) {
@@ -881,11 +751,233 @@ function createDownstreamServer(opts) {
     }, resumeHandshakeTimeoutMs);
   }
 
-  function sendMessageToClient(clientId, ws, message) {
+  function parseMessageTypeForHealth(message) {
+    try {
+      const parsed = JSON.parse(message);
+      return parsed && typeof parsed.type === "string" ? parsed.type : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  function sendMessageToClient(clientId, ws, message, knownMessageType) {
     if (!ws || ws.readyState !== WebSocket.OPEN) {
       return;
     }
     ws.send(message);
+    if (relayHealth && typeof relayHealth.observeSendBuffer === "function") {
+      const bufferedAmountBytes = sendBufferSnapshotForTest
+        ? sendBufferSnapshotForTest(ws)
+        : Number.isFinite(ws.bufferedAmount)
+          ? ws.bufferedAmount
+          : null;
+      relayHealth.observeSendBuffer({
+        clientId,
+        messageType:
+          knownMessageType !== undefined
+            ? knownMessageType
+            : parseMessageTypeForHealth(message),
+        bufferedAmountBytes,
+      });
+    }
+  }
+
+  function forwardReadinessProbeAck(clientId, ack) {
+    if (!ack || !ack.requestId) {
+      return;
+    }
+    const pending = pendingReadinessProbeRequests.get(ack.requestId);
+    if (!pending || pending.targetClientId !== clientId) {
+      return;
+    }
+    pendingReadinessProbeRequests.delete(ack.requestId);
+    const requesterWs = clients.get(pending.requesterClientId);
+    if (!requesterWs || requesterWs.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    const protocol = protocolState.get(clientId);
+    const message =
+      handler && typeof handler.formatReadinessProbeAck === "function"
+        ? handler.formatReadinessProbeAck({
+            ok: ack.ok !== false,
+            requestId: ack.requestId,
+            reasonCode: ack.reasonCode || null,
+            message: ack.message || null,
+            activeSessionKey: ack.activeSessionKey || null,
+            emittedAtMs: ack.emittedAtMs,
+            clientId,
+            clientName: protocol && protocol.clientName ? protocol.clientName : null,
+            clientVersion:
+              protocol && protocol.clientVersion ? protocol.clientVersion : null,
+          })
+        : JSON.stringify({
+            type: APP_PROTOCOL.readinessProbeAck,
+            ok: ack.ok !== false,
+            requestId: ack.requestId,
+            reasonCode: ack.reasonCode || null,
+            message: ack.message || null,
+            activeSessionKey: ack.activeSessionKey || null,
+            emittedAtMs: ack.emittedAtMs,
+            clientId,
+            clientName: protocol && protocol.clientName ? protocol.clientName : null,
+            clientVersion:
+              protocol && protocol.clientVersion ? protocol.clientVersion : null,
+          });
+    sendMessageToClient(pending.requesterClientId, requesterWs, message);
+  }
+
+  function forwardAutomationStateSnapshot(clientId, snapshot) {
+    if (!snapshot || !snapshot.requestId) {
+      return;
+    }
+    const pending = pendingAutomationStateRequests.get(snapshot.requestId);
+    if (!pending || pending.targetClientId !== clientId) {
+      return;
+    }
+    if (pending.expiryTimer) clearTimeout(pending.expiryTimer);
+    pendingAutomationStateRequests.delete(snapshot.requestId);
+    const requesterWs = clients.get(pending.requesterClientId);
+    if (!requesterWs || requesterWs.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    const message =
+      handler && typeof handler.formatAutomationStateSnapshot === "function"
+        ? handler.formatAutomationStateSnapshot({
+            ok: snapshot.ok !== false,
+            requestId: snapshot.requestId,
+            state: snapshot.state || null,
+            reasonCode: snapshot.reasonCode || null,
+            message: snapshot.message || null,
+          })
+        : JSON.stringify({
+            type: APP_PROTOCOL.automationStateSnapshot,
+            ok: snapshot.ok !== false,
+            requestId: snapshot.requestId,
+            state: snapshot.state || null,
+            reasonCode: snapshot.reasonCode || null,
+            message: snapshot.message || null,
+          });
+    sendMessageToClient(pending.requesterClientId, requesterWs, message);
+  }
+
+  function expirePendingAutomationStateRequest(requestId) {
+    const pending = pendingAutomationStateRequests.get(requestId);
+    if (!pending) {
+      return;
+    }
+    if (pending.expiryTimer) clearTimeout(pending.expiryTimer);
+    pendingAutomationStateRequests.delete(requestId);
+    const requesterWs = clients.get(pending.requesterClientId);
+    if (!requesterWs || requesterWs.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    const message =
+      handler && typeof handler.formatAutomationStateSnapshot === "function"
+        ? handler.formatAutomationStateSnapshot({
+            ok: false,
+            requestId,
+            state: null,
+            reasonCode: "snapshot_unavailable",
+            message: "Automation state snapshot is unavailable",
+          })
+        : JSON.stringify({
+            type: APP_PROTOCOL.automationStateSnapshot,
+            ok: false,
+            requestId,
+            state: null,
+            reasonCode: "snapshot_unavailable",
+            message: "Automation state snapshot is unavailable",
+          });
+    sendMessageToClient(pending.requesterClientId, requesterWs, message);
+  }
+
+  function buildAutomationStateDispatchResult(senderId, parsed) {
+    const requestId = parseOptionalTrimmedString(parsed && parsed.requestId);
+    const sessionKey = parseOptionalTrimmedString(parsed && parsed.sessionKey);
+    const snapshot = getReadinessSnapshot();
+    const targetEntry =
+      snapshot &&
+      snapshot.connectedClientCount === 1 &&
+      snapshot.fanoutRecipientCount === 1 &&
+      Array.isArray(snapshot.clients) &&
+      snapshot.clients.length === 1
+        ? snapshot.clients[0]
+        : null;
+    const targetClientId =
+      targetEntry && typeof targetEntry.clientId === "string"
+        ? targetEntry.clientId
+        : null;
+    const readinessPublished =
+      !!(
+        targetEntry &&
+        targetEntry.readinessSnapshot &&
+        Number.isFinite(targetEntry.readinessSnapshot.emittedAtMs)
+      );
+
+    const formatFailure = (reasonCode, message) => ({
+      unicast:
+        handler && typeof handler.formatAutomationStateSnapshot === "function"
+          ? handler.formatAutomationStateSnapshot({
+              ok: false,
+              requestId,
+              reasonCode,
+              message,
+            })
+          : JSON.stringify({
+              type: APP_PROTOCOL.automationStateSnapshot,
+              ok: false,
+              requestId,
+              reasonCode,
+              message,
+            }),
+    });
+
+    if (!requestId) {
+      return formatFailure(
+        "snapshot_unavailable",
+        "automation state request requires requestId",
+      );
+    }
+    if (
+      !snapshot ||
+      snapshot.connectedClientCount <= 0 ||
+      snapshot.fanoutRecipientCount <= 0
+    ) {
+      return formatFailure("no_downstream_client", "No downstream app client connected");
+    }
+    if (
+      snapshot.connectedClientCount > 1 ||
+      snapshot.fanoutRecipientCount > 1 ||
+      !targetClientId
+    ) {
+      return formatFailure(
+        "multi_recipient_fanout",
+        "Multiple downstream app clients connected",
+      );
+    }
+    if (!readinessPublished) {
+      return formatFailure(
+        "snapshot_unavailable",
+        "Automation state snapshot is unavailable",
+      );
+    }
+    return {
+      automationStateRequest: {
+        requestId,
+        targetClientId,
+        message:
+          handler && typeof handler.formatAutomationStateRequest === "function"
+            ? handler.formatAutomationStateRequest({
+                requestId,
+                sessionKey: sessionKey || null,
+              })
+            : JSON.stringify({
+                type: APP_PROTOCOL.automationStateGet,
+                requestId,
+                sessionKey: sessionKey || null,
+              }),
+      },
+    };
   }
 
   function getServerResumeState() {
@@ -894,30 +986,17 @@ function createDownstreamServer(opts) {
     }
     const state = getCurrentResumeState() || {};
     return {
-      pagesRevision: parseRevision(state.pagesRevision),
-      statusRevision: parseRevision(state.statusRevision),
+      pagesRevision: RelayWorkerProtocol.parseNonNegativeRevision(
+        state.pagesRevision,
+      ),
+      statusRevision: RelayWorkerProtocol.parseNonNegativeRevision(
+        state.statusRevision,
+      ),
     };
   }
 
   function formatResumeAck(payload) {
-    return JSON.stringify({
-      type: APP_PROTOCOL.resumeAck,
-      reason: payload.reason || null,
-      sentPages: !!payload.sentPages,
-      sentStatus: !!payload.sentStatus,
-      sentApprovals:
-        Number.isFinite(payload.sentApprovals) && payload.sentApprovals > 0
-          ? Math.floor(payload.sentApprovals)
-          : 0,
-      pagesRevision:
-        payload.pagesRevision === null || payload.pagesRevision === undefined
-          ? null
-          : payload.pagesRevision,
-      statusRevision:
-        payload.statusRevision === null || payload.statusRevision === undefined
-          ? null
-          : payload.statusRevision,
-    });
+    return RelayWorkerProtocol.formatResumeAck(payload);
   }
 
   function isSnapshotSynced(sync) {
@@ -971,10 +1050,10 @@ function createDownstreamServer(opts) {
     const status = getCurrentStatus();
     const debugConfig = getCurrentDebugConfig ? getCurrentDebugConfig() : null;
     const state = getServerResumeState();
-    const clientPagesRevision = parseRevision(
+    const clientPagesRevision = RelayWorkerProtocol.parseNonNegativeRevision(
       resumeRequest && resumeRequest.pagesRevision,
     );
-    const clientStatusRevision = parseRevision(
+    const clientStatusRevision = RelayWorkerProtocol.parseNonNegativeRevision(
       resumeRequest && resumeRequest.statusRevision,
     );
     const clientHasPagesState = parseBool(
@@ -1059,12 +1138,6 @@ function createDownstreamServer(opts) {
   if (opts.httpServer) {
     wss = new WebSocketServer({ noServer: true });
     opts.httpServer.on("upgrade", (req, socket, head) => {
-      const url = new URL(req.url, `http://${req.headers.host}`);
-      if (url.searchParams.get("token") !== token) {
-        socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
-        socket.destroy();
-        return;
-      }
       wss.handleUpgrade(req, socket, head, (ws) => {
         wss.emit("connection", ws, req);
       });
@@ -1073,14 +1146,15 @@ function createDownstreamServer(opts) {
     wss = new WebSocketServer({
       host: opts.host,
       port: opts.port,
-      verifyClient: ({ req }) => {
-        const url = new URL(req.url, `http://${req.headers.host}`);
-        return url.searchParams.get("token") === token;
-      },
     });
   }
 
   wss.on("connection", (ws, req) => {
+    const requestUrl = new URL(req.url, `http://${req.headers.host}`);
+    if (requestUrl.searchParams.get("token") !== token) {
+      ws.close(4001, "invalid_token");
+      return;
+    }
     const clientId = `client-${nextClientId++}`;
     clients.set(clientId, ws);
     const connectedAtMs = Date.now();
@@ -1097,7 +1171,7 @@ function createDownstreamServer(opts) {
       connectedEventEmitted: false,
     };
     ensureProtocolState(clientId);
-    clientNudgeState.set(clientId, createClientNudgeState());
+    nudgeController.addClient(clientId);
     const currentPages = getCurrentPages();
     const currentStatus = getCurrentStatus();
     syncState.set(clientId, {
@@ -1156,7 +1230,7 @@ function createDownstreamServer(opts) {
 
       // Intercept application-level ping — respond with pong, skip handler
       if (enrichedPing) {
-        updateClientNudgeHeartbeat(clientId, enrichedPing);
+        nudgeController.updateHeartbeat(clientId, enrichedPing);
         ws.send(JSON.stringify({ type: "pong", ts: parsed.ts }));
         return;
       }
@@ -1191,6 +1265,9 @@ function createDownstreamServer(opts) {
           clientVersion: protocolHello.clientVersion,
           sessionKey: protocolHello.sessionKey,
         });
+        if (protocolHello.readinessSnapshot) {
+          updateClientReadinessSnapshot(clientId, protocolHello.readinessSnapshot);
+        }
         logger.info(
           `[downstream] ${clientId} identified protocol=${state.selectedVersion || "n/a"} client=${describeProtocolClient(state)} kind=${classifyClientKind(state)} session=${state.sessionKey || "n/a"}`,
         );
@@ -1244,6 +1321,29 @@ function createDownstreamServer(opts) {
         return;
       }
 
+      if (parsed && parsed.type === APP_PROTOCOL.readinessSnapshot) {
+        if (classifyClientKind(state) === "app") {
+          updateClientReadinessSnapshot(clientId, parsed);
+        }
+        return;
+      }
+
+      const readinessProbeAck = parseReadinessProbeAck(parsed);
+      if (readinessProbeAck) {
+        if (classifyClientKind(state) === "app") {
+          forwardReadinessProbeAck(clientId, readinessProbeAck);
+        }
+        return;
+      }
+
+      const automationStateSnapshot = parseAutomationStateSnapshot(parsed);
+      if (automationStateSnapshot) {
+        if (classifyClientKind(state) === "app") {
+          forwardAutomationStateSnapshot(clientId, automationStateSnapshot);
+        }
+        return;
+      }
+
       if (parsed && parsed.type === APP_PROTOCOL.resume) {
         const sync = syncState.get(clientId);
         if (sync) sync.resumeReceived = true;
@@ -1254,15 +1354,25 @@ function createDownstreamServer(opts) {
         return;
       }
 
+      if (parsed && parsed.type === APP_PROTOCOL.automationStateGet) {
+        const result = handler.handleMessage(clientId, raw);
+        if (result !== null && result !== undefined) {
+          processResult(clientId, result);
+        } else {
+          processResult(clientId, buildAutomationStateDispatchResult(clientId, parsed));
+        }
+        return;
+      }
+
       const visibilityControl = parseVisibilityControl(parsed);
       const drainCompleteControl = parseDrainCompleteControl(parsed);
       const transportControl = visibilityControl || drainCompleteControl;
       if (transportControl) {
         const protocol = protocolState.get(clientId);
         if (transportControl.type === "visibility") {
-          updateClientVisibilityState(clientId, transportControl.state);
+          nudgeController.updateVisibilityState(clientId, transportControl.state);
         } else {
-          setClientInteractionStage(clientId, "idle", {
+          nudgeController.setInteractionStage(clientId, "idle", {
             reason: "drain_complete",
             deactivateImmediately: true,
           });
@@ -1295,6 +1405,229 @@ function createDownstreamServer(opts) {
         return;
       }
 
+      if (parsed && parsed.type === APP_PROTOCOL.updatePlugin) {
+        if (!runPluginUpdate) {
+          logger.warn(
+            `[downstream] ${clientId} updatePlugin requested but no runPluginUpdate is configured`,
+          );
+          return;
+        }
+        const requestId =
+          parseOptionalTrimmedString(parsed.requestId) || null;
+        logger.info(
+          `[downstream] ${clientId} updatePlugin requested requestId=${requestId || "n/a"}`,
+        );
+        runPluginUpdate()
+          .then((result) => {
+            if (ws.readyState !== WebSocket.OPEN) return;
+            const payload = { type: APP_PROTOCOL.updatePluginResult };
+            if (requestId) payload.requestId = requestId;
+            if (result && result.ok === true) {
+              payload.ok = true;
+            } else {
+              payload.ok = false;
+              if (result && typeof result.reason === "string") {
+                payload.reason = result.reason;
+              }
+              if (result && typeof result.exitCode === "number") {
+                payload.exitCode = result.exitCode;
+              }
+              if (result && typeof result.stderrTail === "string" && result.stderrTail.length > 0) {
+                payload.stderrTail = result.stderrTail;
+              }
+            }
+            sendMessageToClient(clientId, ws, JSON.stringify(payload));
+          })
+          .catch((err) => {
+            logger.error(
+              `[downstream] ${clientId} updatePlugin threw: ${err && err.message ? err.message : err}`,
+            );
+            if (ws.readyState !== WebSocket.OPEN) return;
+            const payload = {
+              type: APP_PROTOCOL.updatePluginResult,
+              ok: false,
+              reason: "spawn_failed",
+            };
+            if (requestId) payload.requestId = requestId;
+            sendMessageToClient(clientId, ws, JSON.stringify(payload));
+          });
+        return;
+      }
+
+      if (parsed && parsed.type === APP_PROTOCOL.restartGateway) {
+        if (!runGatewayRestart) {
+          logger.warn(
+            `[downstream] ${clientId} restartGateway requested but no runGatewayRestart is configured`,
+          );
+          return;
+        }
+        const requestId =
+          parseOptionalTrimmedString(parsed.requestId) || null;
+        logger.info(
+          `[downstream] ${clientId} restartGateway requested requestId=${requestId || "n/a"}`,
+        );
+        runGatewayRestart()
+          .then((result) => {
+            if (ws.readyState !== WebSocket.OPEN) return;
+            const payload = {
+              type: APP_PROTOCOL.restartGatewayAck,
+              ok: !!(result && result.ok),
+              started: !!(result && result.started),
+            };
+            if (requestId) payload.requestId = requestId;
+            if (result && typeof result.reason === "string") {
+              payload.reason = result.reason;
+            }
+            sendMessageToClient(clientId, ws, JSON.stringify(payload));
+          })
+          .catch((err) => {
+            logger.error(
+              `[downstream] ${clientId} restartGateway threw: ${err && err.message ? err.message : err}`,
+            );
+            if (ws.readyState !== WebSocket.OPEN) return;
+            const payload = {
+              type: APP_PROTOCOL.restartGatewayAck,
+              ok: false,
+              started: false,
+              reason: "spawn_failed",
+            };
+            if (requestId) payload.requestId = requestId;
+            sendMessageToClient(clientId, ws, JSON.stringify(payload));
+          });
+        return;
+      }
+
+      if (parsed && parsed.type === "ocuclaw.session.pinned.set") {
+        if (!sessionService) {
+          if (ws.readyState === WebSocket.OPEN) {
+            sendMessageToClient(
+              clientId,
+              ws,
+              JSON.stringify({ type: "error", error: "session_service_unavailable" }),
+            );
+          }
+          return;
+        }
+        const sessionKey = typeof parsed.sessionKey === "string" ? parsed.sessionKey : "";
+        const pinned = parsed.pinned;
+        const kind = parsed.kind;
+        if (
+          !sessionKey ||
+          typeof pinned !== "boolean" ||
+          (kind !== "ocuclaw" && kind !== "evenai")
+        ) {
+          if (ws.readyState === WebSocket.OPEN) {
+            sendMessageToClient(
+              clientId,
+              ws,
+              JSON.stringify({ type: "error", error: "invalid_session_pin_request" }),
+            );
+          }
+          return;
+        }
+        const result = sessionService.setSessionPinned(kind, sessionKey, pinned);
+        if (!result.ok && result.reason === "cap") {
+          if (ws.readyState === WebSocket.OPEN) {
+            sendMessageToClient(
+              clientId,
+              ws,
+              JSON.stringify({ type: "error", error: "pin_cap_reached" }),
+            );
+          }
+          return;
+        }
+        if (!result.ok) {
+          if (ws.readyState === WebSocket.OPEN) {
+            sendMessageToClient(
+              clientId,
+              ws,
+              JSON.stringify({ type: "error", error: "invalid_session_pin_request" }),
+            );
+          }
+          return;
+        }
+        if (typeof sessionService.broadcastSessionsForKind === "function") {
+          Promise.resolve(sessionService.broadcastSessionsForKind(kind)).catch((err) => {
+            logger.error(
+              `[downstream] broadcastSessionsForKind failed: ${err && err.message ? err.message : err}`,
+            );
+          });
+        }
+        return;
+      }
+
+      if (parsed && parsed.type === "ocuclaw.session.delete") {
+        if (!sessionService) {
+          if (ws.readyState === WebSocket.OPEN) {
+            sendMessageToClient(
+              clientId,
+              ws,
+              JSON.stringify({ type: "error", error: "session_service_unavailable" }),
+            );
+          }
+          return;
+        }
+        const sessionKeys = Array.isArray(parsed.sessionKeys) ? parsed.sessionKeys : null;
+        const kind = parsed.kind;
+        const switchBeforeDelete = parsed.switchBeforeDelete === true;
+        if (
+          !sessionKeys ||
+          sessionKeys.length === 0 ||
+          sessionKeys.some((k) => typeof k !== "string" || !k) ||
+          (kind !== "ocuclaw" && kind !== "evenai")
+        ) {
+          if (ws.readyState === WebSocket.OPEN) {
+            sendMessageToClient(
+              clientId,
+              ws,
+              JSON.stringify({ type: "error", error: "invalid_session_delete_request" }),
+            );
+          }
+          return;
+        }
+        const action = switchBeforeDelete
+          ? sessionService.switchAndDeleteSessions(kind, sessionKeys)
+          : sessionService.deleteSessions(kind, sessionKeys);
+        Promise.resolve(action)
+          .then(() => {
+            if (typeof sessionService.broadcastSessionsForKind === "function") {
+              return sessionService.broadcastSessionsForKind(kind);
+            }
+            return null;
+          })
+          .catch((err) => {
+            logger.error(
+              `[downstream] session.delete pipeline failed: ${err && err.message ? err.message : err}`,
+            );
+          });
+        return;
+      }
+
+      if (parsed && parsed.type === APP_PROTOCOL.avatarFetch) {
+        if (state.selectedVersion !== "v2") return;
+        const requestedAgentName =
+          typeof parsed.agentName === "string" ? parsed.agentName : null;
+        const requestedHash =
+          typeof parsed.hash === "string" && /^[0-9a-f]{64}$/.test(parsed.hash)
+            ? parsed.hash
+            : null;
+        if (!requestedAgentName || !requestedHash) {
+          // Malformed request — silently drop. The WebUI guards against this.
+          return;
+        }
+        const dataUri = getAgentAvatarDataUriByHash(requestedHash);
+        const payload = {
+          type: APP_PROTOCOL.avatarBlob,
+          agentName: requestedAgentName,
+          hash: requestedHash,
+          dataUri: dataUri || null,
+        };
+        if (ws.readyState === WebSocket.OPEN) {
+          sendMessageToClient(clientId, ws, JSON.stringify(payload));
+        }
+        return;
+      }
+
       const result = handler.handleMessage(clientId, raw);
       processResult(clientId, result);
     });
@@ -1307,8 +1640,10 @@ function createDownstreamServer(opts) {
       const protocol = protocolState.get(clientId);
       syncState.delete(clientId);
       protocolState.delete(clientId);
-      clearClientNudgeTimers(clientId);
-      clientNudgeState.delete(clientId);
+      clientReadinessSnapshotState.delete(clientId);
+      clearPendingReadinessProbesForClient(clientId);
+      clearPendingAutomationStateRequestsForClient(clientId);
+      nudgeController.deleteClient(clientId);
       handler.removeClient(clientId);
       clients.delete(clientId);
       const lifetimeMs = Date.now() - connectedAtMs;
@@ -1354,15 +1689,36 @@ function createDownstreamServer(opts) {
    * @param {string} senderId - Client ID that sent the original message
    * @param {object|null|Promise} result - Handler return value
    */
+  function sendUnicastResult(senderId, unicast) {
+    const frames = Array.isArray(unicast) ? unicast : [unicast];
+    const ws = clients.get(senderId);
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    for (const frame of frames) {
+      if (typeof frame === "string") {
+        sendMessageToClient(senderId, ws, frame);
+      }
+    }
+  }
+
   function processResult(senderId, result) {
     if (result === null || result === undefined) {
       return;
     }
 
     if (typeof result.then === "function") {
+      pendingHandlerPromiseCount += 1;
+      if (relayHealth && typeof relayHealth.emitQueueDepth === "function") {
+        relayHealth.emitQueueDepth({
+          pendingHandlerPromises: pendingHandlerPromiseCount,
+        });
+      }
       result.then(
-        (resolved) => processResult(senderId, resolved),
+        (resolved) => {
+          pendingHandlerPromiseCount = Math.max(0, pendingHandlerPromiseCount - 1);
+          processResult(senderId, resolved);
+        },
         (err) => {
+          pendingHandlerPromiseCount = Math.max(0, pendingHandlerPromiseCount - 1);
           logger.error(
             `[downstream] Error processing message from ${senderId}:`,
             err,
@@ -1373,9 +1729,110 @@ function createDownstreamServer(opts) {
     }
 
     if (result.unicast) {
-      const ws = clients.get(senderId);
-      if (ws && ws.readyState === WebSocket.OPEN) {
-        sendMessageToClient(senderId, ws, result.unicast);
+      sendUnicastResult(senderId, result.unicast);
+    }
+
+    if (result.followup && typeof result.followup.then === "function") {
+      processResult(senderId, result.followup);
+    }
+
+    if (result.readinessProbe) {
+      const requestId = parseOptionalTrimmedString(
+        result.readinessProbe.requestId,
+      );
+      const targetClientId = parseOptionalTrimmedString(
+        result.readinessProbe.targetClientId,
+      );
+      const message =
+        typeof result.readinessProbe.message === "string"
+          ? result.readinessProbe.message
+          : null;
+      const targetWs = targetClientId ? clients.get(targetClientId) : null;
+      if (
+        !requestId ||
+        !targetClientId ||
+        !message ||
+        !targetWs ||
+        targetWs.readyState !== WebSocket.OPEN ||
+        !isAppClient(targetClientId)
+      ) {
+        const requesterWs = clients.get(senderId);
+        if (
+          requesterWs &&
+          requesterWs.readyState === WebSocket.OPEN &&
+          handler &&
+          typeof handler.formatReadinessProbeAck === "function"
+        ) {
+          sendMessageToClient(
+            senderId,
+            requesterWs,
+            handler.formatReadinessProbeAck({
+              ok: false,
+              requestId,
+              reasonCode: "no_downstream_client",
+              message: "No downstream app client connected",
+            }),
+          );
+        }
+      } else {
+        pendingReadinessProbeRequests.set(requestId, {
+          requesterClientId: senderId,
+          targetClientId,
+          createdAtMs: Date.now(),
+        });
+        sendMessageToClient(targetClientId, targetWs, message);
+      }
+    }
+
+    if (result.automationStateRequest) {
+      const requestId = parseOptionalTrimmedString(
+        result.automationStateRequest.requestId,
+      );
+      const targetClientId = parseOptionalTrimmedString(
+        result.automationStateRequest.targetClientId,
+      );
+      const message =
+        typeof result.automationStateRequest.message === "string"
+          ? result.automationStateRequest.message
+          : null;
+      const targetWs = targetClientId ? clients.get(targetClientId) : null;
+      if (
+        !requestId ||
+        !targetClientId ||
+        !message ||
+        !targetWs ||
+        targetWs.readyState !== WebSocket.OPEN ||
+        !isAppClient(targetClientId)
+      ) {
+        const requesterWs = clients.get(senderId);
+        if (
+          requesterWs &&
+          requesterWs.readyState === WebSocket.OPEN &&
+          handler &&
+          typeof handler.formatAutomationStateSnapshot === "function"
+        ) {
+          sendMessageToClient(
+            senderId,
+            requesterWs,
+            handler.formatAutomationStateSnapshot({
+              ok: false,
+              requestId,
+              reasonCode: "snapshot_unavailable",
+              message: "Automation state snapshot is unavailable",
+            }),
+          );
+        }
+      } else {
+        pendingAutomationStateRequests.set(requestId, {
+          requesterClientId: senderId,
+          targetClientId,
+          createdAtMs: Date.now(),
+          expiryTimer: setTimeout(
+            () => expirePendingAutomationStateRequest(requestId),
+            AUTOMATION_STATE_REPLY_TIMEOUT_MS,
+          ),
+        });
+        sendMessageToClient(targetClientId, targetWs, message);
       }
     }
 
@@ -1439,11 +1896,7 @@ function createDownstreamServer(opts) {
       : null;
     for (const [clientId, ws] of clients) {
       if (ws.readyState === WebSocket.OPEN) {
-        sendMessageToClient(clientId, ws, message);
-        if (relayStreamingActivityAtMs !== null) {
-          ensureClientNudgeState(clientId).lastRelayStreamingActivityAtMs =
-            relayStreamingActivityAtMs;
-        }
+        sendMessageToClient(clientId, ws, message, messageType);
         if (
           messageType === "pages" ||
           messageType === "status" ||
@@ -1454,7 +1907,11 @@ function createDownstreamServer(opts) {
         }
       }
     }
-    applyBroadcastInteractionStage(messageType, parsed, relayStreamingActivityAtMs);
+    nudgeController.applyBroadcastInteractionStage(
+      messageType,
+      parsed,
+      relayStreamingActivityAtMs,
+    );
   }
 
   /**
@@ -1480,7 +1937,7 @@ function createDownstreamServer(opts) {
       if (ws.readyState !== WebSocket.OPEN) {
         continue;
       }
-      sendMessageToClient(clientId, ws, message);
+      sendMessageToClient(clientId, ws, message, messageType);
       if (
         messageType === "pages" ||
         messageType === "status" ||
@@ -1515,8 +1972,39 @@ function createDownstreamServer(opts) {
     return Array.from(clients.keys());
   }
 
-  function getConnectedAppCount(excludeClientId = null) {
-    return countConnectedAppClients(excludeClientId);
+  function getConnectedAppCount(excludeClientId = null, sessionKey = null) {
+    return countConnectedAppClients(excludeClientId, sessionKey);
+  }
+
+  function getReadinessSnapshot() {
+    const clientsOut = [];
+    let latestUpdatedAtMs = null;
+    for (const [clientId, ws] of clients) {
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        continue;
+      }
+      if (!isAppClient(clientId)) {
+        continue;
+      }
+      const entry = buildReadinessClientEntry(clientId);
+      clientsOut.push(entry);
+      const updatedAtMs =
+        entry &&
+        entry.readinessSnapshot &&
+        Number.isFinite(entry.readinessSnapshot.updatedAtMs)
+          ? entry.readinessSnapshot.updatedAtMs
+          : null;
+      if (updatedAtMs !== null && (latestUpdatedAtMs === null || updatedAtMs > latestUpdatedAtMs)) {
+        latestUpdatedAtMs = updatedAtMs;
+      }
+    }
+    clientsOut.sort((left, right) => String(left.clientId).localeCompare(String(right.clientId)));
+    return {
+      connectedClientCount: clientsOut.length,
+      fanoutRecipientCount: clientsOut.length,
+      updatedAtMs: latestUpdatedAtMs,
+      clients: clientsOut,
+    };
   }
 
   /**
@@ -1530,10 +2018,13 @@ function createDownstreamServer(opts) {
         if (sync.timer) clearTimeout(sync.timer);
       }
       syncState.clear();
-      for (const [clientId] of clientNudgeState) {
-        clearClientNudgeTimers(clientId);
+      nudgeController.clear();
+      clientReadinessSnapshotState.clear();
+      pendingReadinessProbeRequests.clear();
+      for (const [, pending] of pendingAutomationStateRequests) {
+        if (pending && pending.expiryTimer) clearTimeout(pending.expiryTimer);
       }
-      clientNudgeState.clear();
+      pendingAutomationStateRequests.clear();
       for (const [, ws] of clients) {
         ws.close();
       }
@@ -1547,9 +2038,10 @@ function createDownstreamServer(opts) {
     unicast,
     getClientIds,
     getConnectedAppCount,
+    getReadinessSnapshot,
     closeConnectedAppClients,
     getClientNudgeState(clientId) {
-      return cloneClientNudgeState(clientNudgeState.get(clientId) || null);
+      return nudgeController.getClientState(clientId);
     },
     close,
     get httpServer() {