test: Harden browser contract-test adapter against unanswered-command hangs (#1399)

## Summary

The browser SDK contract-test **adapter** (`startAdapter.ts`) forwarded
each command to the browser entity over WebSocket and waited **forever**
for a reply. If the browser ever missed one reply, that REST request —
and therefore the harness — hung indefinitely (even capability/status
queries returned `000`), with no recovery path. This permanently wedged
the service, which is especially painful when reusing one service across
many runs (e.g. flake hunting).

This PR makes the adapter resilient:

- **Timeout on `send()`** (`ADAPTER_REQUEST_TIMEOUT_MS`, default
**30s**). A stalled command now fails that single request with **HTTP
500** so the harness fails that one test and continues, instead of
wedging the whole chain.
- **Reject in-flight commands on WebSocket close**, so no REST request
is left waiting on a dead socket.
- **Error handler on REST `listen()`** so a silent bind failure (e.g.
the port still being held → "WS up but REST never bound") is logged
instead of disappearing.

Changes are confined to test tooling; no SDK runtime code is touched.

## Verification
5 consecutive full suites against one reused adapter/browser stayed
green — `ec=0, fail=0`, adapter responsive at ~1 ms throughout. The
timeout path turns a previously-permanent hang into a single failed
request the harness can recover from.

## Notes
- An earlier revision of this branch also had the entity destroy
leftover clients on `getCapabilities`. **That was removed**:
`getCapabilities` is not a safe "new run" signal because multiple
harnesses can drive one entity concurrently, so it could wipe another
run's active clients. The lingering-final-client cleanup needs a
different, run-aware approach and is out of scope here.
- `packages/sdk/browser/example-fdv2/src/app.ts` has unrelated local
debugging tweaks and is intentionally not part of this branch.

## Test coverage
This tooling package has no unit-test harness; validation was
integration-based (above).

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Only internal contract-test adapter tooling is modified; no production
SDK or auth/data paths are affected.
> 
> **Overview**
> The contract-test **adapter** (`startAdapter`) no longer waits
indefinitely for browser-entity WebSocket replies. **`send()`** now uses
a configurable timeout (`requestTimeoutMs` /
`ADAPTER_REQUEST_TIMEOUT_MS`, default **30s**) and rejects with a clear
error; **`waiters`** are scoped **per WebSocket** and include timers
plus **reject on socket close**, so a dropped connection does not leave
unrelated REST calls stuck.
> 
> Async REST routes are wrapped with a **`guard`** that maps failures
(timeout, closed socket, etc.) to **HTTP 500** instead of unhandled
rejections that could hang the harness. The REST **`listen()`** server
also gets an **`error`** handler so bind failures (e.g. `EADDRINUSE`)
are logged.
> 
> Changes are limited to internal contract-test tooling; SDK runtime is
unchanged.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
d62dc65. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

packages/tooling/contract-test-utils/src/adapter/startAdapter.ts

@@ -10,42 +10,97 @@ import { WebSocketServer } from 'ws';
 export interface AdapterOptions {
   restPort?: number;
   wsPort?: number;
+  /**
+   * How long (ms) the adapter waits for the browser entity to answer a command
+   * before failing the REST request. Prevents a single unanswered command from
+   * wedging the adapter (and therefore the test harness) indefinitely.
+   * Override with ADAPTER_REQUEST_TIMEOUT_MS. Defaults to 30s.
+   */
+  requestTimeoutMs?: number;
+}
+
+/**
+ * Tracks an outstanding command sent to the browser entity, awaiting its
+ * response over the WebSocket.
+ */
+interface Waiter {
+  resolve: (data: any) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
 }
 
 let server: http.Server | undefined;
 
 export function startAdapter(options?: AdapterOptions) {
   const restPort = options?.restPort ?? 8000;
   const wsPort = options?.wsPort ?? 8001;
+  const requestTimeoutMs =
+    options?.requestTimeoutMs ?? Number(process.env.ADAPTER_REQUEST_TIMEOUT_MS ?? 30000);
 
   const wss = new WebSocketServer({ port: wsPort });
-  const waiters: Record<string, (data: unknown) => void> = {};
 
   console.log('Running contract test harness adapter.');
   wss.on('connection', async (ws) => {
     ws.on('error', console.error);
 
+    // Outstanding commands awaiting a response over THIS socket. Scoped per
+    // connection (not shared across the adapter) so that closing one socket
+    // only fails its own in-flight commands and never rejects waiters that
+    // belong to another, e.g. reconnecting, connection.
+    const waiters: Record<string, Waiter> = {};
+
     ws.on('message', (stringData: string) => {
       const data = JSON.parse(stringData);
-      if (Object.prototype.hasOwnProperty.call(waiters, data.reqId)) {
-        waiters[data.reqId](data);
+      const waiter = waiters[data.reqId];
+      if (waiter) {
+        clearTimeout(waiter.timer);
         delete waiters[data.reqId];
+        waiter.resolve(data);
       } else {
         console.error('Did not find outstanding request', data.reqId);
       }
     });
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const send = (data: { [key: string]: unknown; reqId: string }): Promise<any> => {
-      let resolver: (data: unknown) => void;
-      const waiter = new Promise((resolve) => {
-        resolver = resolve;
+    // When this socket drops, fail its outstanding commands instead of leaving
+    // those REST requests (and the harness) hanging forever.
+    ws.on('close', () => {
+      Object.keys(waiters).forEach((reqId) => {
+        const waiter = waiters[reqId];
+        clearTimeout(waiter.timer);
+        delete waiters[reqId];
+        waiter.reject(new Error('WebSocket connection to entity closed before a response was received.'));
       });
-      // @ts-expect-error The body of the above assignment runs sequentially.
-      waiters[data.reqId] = resolver;
-      ws.send(JSON.stringify(data));
-      return waiter;
-    };
+    });
+
+    const send = (data: { [key: string]: unknown; reqId: string }): Promise<any> =>
+      new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          delete waiters[data.reqId];
+          reject(
+            new Error(
+              `Adapter timed out after ${requestTimeoutMs}ms awaiting entity response to '${data.command}' (reqId ${data.reqId}).`,
+            ),
+          );
+        }, requestTimeoutMs);
+        waiters[data.reqId] = { resolve, reject, timer };
+        ws.send(JSON.stringify(data));
+      });
+
+    // Wrap async route handlers so an unanswered/timed-out command produces a
+    // 500 for that single request rather than an unhandled rejection that
+    // leaves the request — and the harness — hanging.
+    const guard =
+      (
+        handler: (req: express.Request, res: express.Response) => Promise<void>,
+      ): express.RequestHandler =>
+      (req, res) => {
+        handler(req, res).catch((err) => {
+          console.error('Adapter request failed:', err);
+          if (!res.headersSent) {
+            res.status(500).send(String(err));
+          }
+        });
+      };
 
     if (server) {
       await util.promisify(server.close).call(server);
@@ -63,54 +118,71 @@ export function startAdapter(options?: AdapterOptions) {
     );
     app.use(bodyParser.json());
 
-    app.get('/', async (_req, res) => {
-      const commandResult = await send({ command: 'getCapabilities', reqId: randomUUID() });
-      res.header('Content-Type', 'application/json');
-      res.json(commandResult);
-    });
+    app.get(
+      '/',
+      guard(async (_req, res) => {
+        const commandResult = await send({ command: 'getCapabilities', reqId: randomUUID() });
+        res.header('Content-Type', 'application/json');
+        res.json(commandResult);
+      }),
+    );
 
     app.delete('/', () => {
       process.exit();
     });
 
-    app.post('/', async (req, res) => {
-      const commandResult = await send({
-        command: 'createClient',
-        body: req.body,
-        reqId: randomUUID(),
-      });
-      if (commandResult.resourceUrl) {
-        res.set('Location', commandResult.resourceUrl);
-      }
-      if (commandResult.status) {
-        res.status(commandResult.status);
-      }
-      res.send();
-    });
+    app.post(
+      '/',
+      guard(async (req, res) => {
+        const commandResult = await send({
+          command: 'createClient',
+          body: req.body,
+          reqId: randomUUID(),
+        });
+        if (commandResult.resourceUrl) {
+          res.set('Location', commandResult.resourceUrl);
+        }
+        if (commandResult.status) {
+          res.status(commandResult.status);
+        }
+        res.send();
+      }),
+    );
 
-    app.post('/clients/:id', async (req, res) => {
-      const commandResult = await send({
-        command: 'runCommand',
-        id: req.params.id,
-        body: req.body,
-        reqId: randomUUID(),
-      });
-      if (commandResult.status) {
-        res.status(commandResult.status);
-      }
-      if (commandResult.body) {
-        res.write(JSON.stringify(commandResult.body));
-      }
-      res.send();
-    });
+    app.post(
+      '/clients/:id',
+      guard(async (req, res) => {
+        const commandResult = await send({
+          command: 'runCommand',
+          id: req.params.id,
+          body: req.body,
+          reqId: randomUUID(),
+        });
+        if (commandResult.status) {
+          res.status(commandResult.status);
+        }
+        if (commandResult.body) {
+          res.write(JSON.stringify(commandResult.body));
+        }
+        res.send();
+      }),
+    );
 
-    app.delete('/clients/:id', async (req, res) => {
-      await send({ command: 'deleteClient', id: req.params.id, reqId: randomUUID() });
-      res.send();
-    });
+    app.delete(
+      '/clients/:id',
+      guard(async (req, res) => {
+        await send({ command: 'deleteClient', id: req.params.id, reqId: randomUUID() });
+        res.send();
+      }),
+    );
 
     server = app.listen(restPort, () => {
       console.log('Listening on port %d', restPort);
     });
+    // Surface bind failures (e.g. EADDRINUSE) instead of silently never
+    // logging "Listening on port".
+    server.on('error', (err) => {
+      console.error(`REST server error on port ${restPort}:`, err);
+    });
   });
 }