refactor(kernel-browser-runtime): Address PR review concerns

- Add test coverage for handlerPromise with delayed resolution
- Fix documentation to clarify caching behavior (not buffering)
- Add explicit error handling for handlerPromise rejection
- Rename handlerReady to handlerResolution for clarity

Co-authored-by: Erik Marks <rekmarks@users.noreply.github.com>

Author: github-actions[bot]

packages/kernel-browser-runtime/src/internal-comms/internal-connections.test.ts

@@ -455,5 +455,183 @@ describe('internal-connections', () => {
         expect.any(Error),
       );
     });
+
+    it('should handle messages with handlerPromise after resolution', async () => {
+      const handlerPromise = Promise.resolve(mockHandleMessage);
+
+      receiveInternalConnections({
+        handlerPromise,
+        logger,
+      });
+
+      const controlChannel = MockBroadcastChannel.channels.get(
+        COMMS_CONTROL_CHANNEL_NAME,
+      );
+      controlChannel?.onmessage?.(
+        new MessageEvent('message', {
+          data: {
+            method: 'init',
+            params: { channelName: 'internal-process-channel' },
+          },
+        }),
+      );
+
+      await delay();
+      const commsStream = streamInstances[0]!;
+      expect(commsStream).toBeDefined();
+      const commsStreamWriteSpy = vi.spyOn(commsStream, 'write');
+
+      const commsChannel = MockBroadcastChannel.channels.get(
+        'internal-process-channel',
+      )!;
+
+      // Send first message
+      commsChannel.onmessage?.(
+        new MessageEvent('message', {
+          data: {
+            method: 'getStatus',
+            params: null,
+            id: 1,
+          },
+        }),
+      );
+      await delay();
+
+      expect(mockHandleMessage).toHaveBeenCalledWith({
+        method: 'getStatus',
+        params: null,
+        id: 1,
+      });
+      expect(commsStreamWriteSpy).toHaveBeenCalledWith({
+        jsonrpc: '2.0',
+        id: 1,
+        result: { vats: [], clusterConfig: makeClusterConfig() },
+      });
+
+      // Send second message to verify caching (handler should be used directly)
+      commsChannel.onmessage?.(
+        new MessageEvent('message', {
+          data: {
+            method: 'getStatus',
+            params: null,
+            id: 2,
+          },
+        }),
+      );
+      await delay();
+
+      expect(mockHandleMessage).toHaveBeenCalledTimes(2);
+      expect(commsStreamWriteSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it('should queue messages until handlerPromise resolves', async () => {
+      let resolveHandler: (handler: typeof mockHandleMessage) => void;
+      const handlerPromise = new Promise<typeof mockHandleMessage>((resolve) => {
+        resolveHandler = resolve;
+      });
+
+      receiveInternalConnections({
+        handlerPromise,
+        logger,
+      });
+
+      const controlChannel = MockBroadcastChannel.channels.get(
+        COMMS_CONTROL_CHANNEL_NAME,
+      );
+      controlChannel?.onmessage?.(
+        new MessageEvent('message', {
+          data: {
+            method: 'init',
+            params: { channelName: 'internal-process-channel' },
+          },
+        }),
+      );
+
+      await delay();
+      const commsStream = streamInstances[0]!;
+      expect(commsStream).toBeDefined();
+      const commsStreamWriteSpy = vi.spyOn(commsStream, 'write');
+
+      const commsChannel = MockBroadcastChannel.channels.get(
+        'internal-process-channel',
+      )!;
+
+      // Send message before handler is ready
+      commsChannel.onmessage?.(
+        new MessageEvent('message', {
+          data: {
+            method: 'getStatus',
+            params: null,
+            id: 1,
+          },
+        }),
+      );
+
+      // Handler should not be called yet
+      await delay();
+      expect(mockHandleMessage).not.toHaveBeenCalled();
+      expect(commsStreamWriteSpy).not.toHaveBeenCalled();
+
+      // Now resolve the handler
+      resolveHandler!(mockHandleMessage);
+      await delay();
+
+      // Now the message should be handled
+      expect(mockHandleMessage).toHaveBeenCalledWith({
+        method: 'getStatus',
+        params: null,
+        id: 1,
+      });
+      expect(commsStreamWriteSpy).toHaveBeenCalledWith({
+        jsonrpc: '2.0',
+        id: 1,
+        result: { vats: [], clusterConfig: makeClusterConfig() },
+      });
+    });
+
+    it('should handle handlerPromise rejection', async () => {
+      const handlerError = new Error('Handler initialization failed');
+      const handlerPromise = Promise.reject(handlerError);
+
+      receiveInternalConnections({
+        handlerPromise,
+        logger,
+      });
+
+      const controlChannel = MockBroadcastChannel.channels.get(
+        COMMS_CONTROL_CHANNEL_NAME,
+      );
+      controlChannel?.onmessage?.(
+        new MessageEvent('message', {
+          data: {
+            method: 'init',
+            params: { channelName: 'internal-process-channel' },
+          },
+        }),
+      );
+
+      await delay();
+      const commsChannel = MockBroadcastChannel.channels.get(
+        'internal-process-channel',
+      )!;
+
+      // Send message - should trigger error handling
+      commsChannel.onmessage?.(
+        new MessageEvent('message', {
+          data: {
+            method: 'getStatus',
+            params: null,
+            id: 1,
+          },
+        }),
+      );
+
+      await delay();
+
+      expect(logger.error).toHaveBeenCalledWith(
+        'Error initializing message handler for internal process "internal-process-channel":',
+        handlerError,
+      );
+    });
   });
 });

packages/kernel-browser-runtime/src/internal-comms/internal-connections.ts

@@ -123,8 +123,8 @@ type ReceiveConnectionsOptions = Omit<Options, 'label'> &
  * @param options.handler - The function to handle internal messages. Mutually exclusive
  * with `handlerPromise`.
  * @param options.handlerPromise - A promise that resolves to the handler function.
- * Messages will be buffered until the handler is ready, then subsequent messages are
- * handled directly. Mutually exclusive with `handler`.
+ * Incoming messages await handler initialization once, then the resolved handler is
+ * cached and used directly for all subsequent messages. Mutually exclusive with `handler`.
  * @param options.logger - The logger instance.
  * @param options.controlChannelName - The name of the control channel. Must match
  * the name used by {@link connectToKernel} on the other end.
@@ -137,18 +137,24 @@ export const receiveInternalConnections = ({
 }: ReceiveConnectionsOptions): void => {
   // Support both direct handler and promise-based handler
   let handler: HandleInternalMessage | null = null;
-  let handlerReady: Promise<HandleInternalMessage>;
+  let handlerResolution: Promise<HandleInternalMessage>;
 
   if (directHandler !== undefined) {
     // Direct handler - use immediately
     handler = directHandler;
-    handlerReady = Promise.resolve(directHandler);
+    handlerResolution = Promise.resolve(directHandler);
   } else {
     // Promise-based handler - cache once resolved
-    handlerReady = handlerPromise.then((resolvedHandler) => {
-      handler = resolvedHandler;
-      return resolvedHandler;
-    });
+    handlerResolution = handlerPromise.then(
+      (resolvedHandler) => {
+        handler = resolvedHandler;
+        return resolvedHandler;
+      },
+      (error) => {
+        // Re-throw to propagate initialization errors to message handlers
+        throw error;
+      },
+    );
   }
 
   const seenChannels = new Set<string>();
@@ -177,19 +183,39 @@ export const receiveInternalConnections = ({
             `Received message from internal process "${channelName}": ${JSON.stringify(message)}`,
           );
 
-          // Use cached handler if available, otherwise await once
-          const messageHandler = handler ?? (await handlerReady);
-          const reply = await messageHandler(message);
-          if (reply !== undefined) {
-            await kernelRpcStream.write(reply);
+          try {
+            // Use cached handler if available, otherwise await once
+            const messageHandler = handler ?? (await handlerResolution);
+            const reply = await messageHandler(message);
+            if (reply !== undefined) {
+              await kernelRpcStream.write(reply);
+            }
+          } catch (error) {
+            // Check if this is a handler initialization error
+            if (handler === null) {
+              logger.error(
+                `Error initializing message handler for internal process "${channelName}":`,
+                error,
+              );
+            } else {
+              logger.error(
+                `Error handling message from internal process "${channelName}":`,
+                error,
+              );
+            }
+            throw error;
           }
         });
       })
       .catch((error) => {
-        logger.error(
-          `Error handling message from internal process "${channelName}":`,
-          error,
-        );
+        // This catch handles connection errors and re-thrown handler errors
+        if (handler !== null) {
+          logger.error(
+            `Error handling message from internal process "${channelName}":`,
+            error,
+          );
+        }
+        // Initialization errors are already logged in the try-catch above
       })
       .finally(() => {
         logger.debug(`Closed connection to internal process "${channelName}"`);