feat(web-server): use dynamic port and return structured handle

Replace fixed port 3000 with OS-assigned port (port 0), eliminating
port conflicts between multiple bridge instances. Return a WebServerHandle
struct (server, controller, wss) instead of bare http.Server so callers
can shut down all components. Remove the now-unnecessary isPortAlive()
port probe and unused net import. Simplify runWeb() to reuse
createWebServer(). Expose ChatController.meshStore for handle cleanup.

Update all other bridges (claude-code, codex, mcp, opencode) to call
tryStartWebServer() without await since it is now synchronous.

Author: Mearman

src/bridges/claude-code/channel.ts

@@ -105,7 +105,7 @@ export async function run(): Promise<void> {
   // -----------------------------------------------------------------------
 
   await store.init();
-  await tryStartWebServer();
+  tryStartWebServer();
   await mcp.connect(new StdioServerTransport());
 
   const reg = await ensureRegistered({

src/bridges/codex/tool.ts

@@ -96,7 +96,7 @@ export async function run(): Promise<void> {
   // -----------------------------------------------------------------------
 
   await store.init();
-  await tryStartWebServer();
+  tryStartWebServer();
   await mcp.connect(new StdioServerTransport());
 
   const reg = await ensureRegistered({

src/bridges/mcp/index.ts

@@ -97,7 +97,7 @@ export async function run(): Promise<void> {
   // -----------------------------------------------------------------------
 
   await store.init();
-  await tryStartWebServer();
+  tryStartWebServer();
   await mcp.connect(new StdioServerTransport());
 
   const reg = await ensureRegistered({

src/bridges/opencode/plugin.ts

@@ -53,7 +53,7 @@ export const AgentCommsPlugin = async (opts: {
   const client = opts.client;
 
   await store.init();
-  await tryStartWebServer();
+  tryStartWebServer();
 
   const reg = await ensureRegistered({
     cwd: process.cwd(),

src/bridges/user/controller.ts

@@ -26,6 +26,11 @@ import type {
 
 export class ChatController extends EventEmitter {
   private store: MeshStore;
+
+  /** Expose the underlying MeshStore for handle cleanup. */
+  get meshStore(): MeshStore {
+    return this.store;
+  }
   private tool: CommsTool;
   private ctx!: CommsContext;
   private currentRoom: string | undefined;

src/bridges/user/web/server.ts

@@ -17,39 +17,39 @@
  */
 
 import * as http from "node:http";
-import * as net from "node:net";
 import { WebSocketServer, type WebSocket } from "ws";
 import { ChatController } from "../controller.js";
 import { FRONTEND_HTML } from "./index.html.js";
 
-const DEFAULT_WEB_PORT = 3000;
 const WEB_HOST = "127.0.0.1";
 
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface WebServerHandle {
+  server: http.Server;
+  controller: ChatController;
+  wss: WebSocketServer;
+}
+
 // ---------------------------------------------------------------------------
 // Auto-start — called by every bridge after MeshStore.init()
 // ---------------------------------------------------------------------------
 
 /**
- * Try to start the web UI server on the well-known port.
- * Returns the server if this bridge won the race, or undefined if another
- * bridge is already serving. The server runs independently with its own
- * MeshStore that syncs state from the mesh.
+ * Start the web UI server on an OS-assigned port.
+ * Returns the server handle, or undefined if port discovery fails.
  */
-export async function tryStartWebServer(
-  port = DEFAULT_WEB_PORT,
-): Promise<http.Server | undefined> {
-  const alive = await isPortAlive(port, WEB_HOST);
-  if (alive) return undefined;
-
-  const server = createWebServer(port);
-  return server;
+export function tryStartWebServer(): WebServerHandle | undefined {
+  return createWebServer();
 }
 
 /**
- * Create and start the web server. Used by tryStartWebServer (auto-start)
- * and runWeb (standalone `npx agent-comms chat` mode).
+ * Create and start the web server on a dynamic port.
+ * Used by tryStartWebServer (auto-start) and runWeb (standalone mode).
  */
-export function createWebServer(port = DEFAULT_WEB_PORT): http.Server {
+export function createWebServer(port = 0): WebServerHandle {
   const controller = new ChatController("Dashboard");
   void controller.init();
 
@@ -63,57 +63,35 @@ export function createWebServer(port = DEFAULT_WEB_PORT): http.Server {
   });
 
   server.listen(port, WEB_HOST, () => {
-    console.log(`Agent Comms web UI: http://${WEB_HOST}:${String(port)}`);
+    const addr = server.address();
+    const actualPort = typeof addr === "object" && addr ? addr.port : port;
+    console.log(`Agent Comms web UI: http://${WEB_HOST}:${String(actualPort)}`);
   });
 
-  return server;
-}
-
-function isPortAlive(port: number, host: string): Promise<boolean> {
-  return new Promise((resolve) => {
-    const socket = new net.Socket();
-    socket.connect(port, host, () => {
-      socket.destroy();
-      resolve(true);
-    });
-    socket.on("error", () => {
-      socket.destroy();
-      resolve(false);
-    });
-  });
+  return { server, controller, wss };
 }
 
 // ---------------------------------------------------------------------------
 // Standalone mode — `npx agent-comms chat`
 // ---------------------------------------------------------------------------
 
-export async function runWeb(
-  userName: string,
-  port = DEFAULT_WEB_PORT,
-): Promise<void> {
-  const controller = new ChatController(userName);
-  await controller.init();
-
-  const server = http.createServer((req, res) => {
-    handleRequest(req, res, controller);
-  });
-
-  const wss = new WebSocketServer({ server });
-
-  wss.on("connection", (ws) => {
-    handleWebSocket(ws, controller);
-  });
+export function runWeb(userName: string, port = 0): void {
+  const handle = createWebServer(port);
 
-  server.listen(port, () => {
-    console.log(`Agent Comms web UI: http://localhost:${String(port)}`);
-    console.log(`Connected as ${userName} (user) [${controller.agentId}]`);
+  handle.server.on("listening", () => {
+    const addr = handle.server.address();
+    const actualPort = typeof addr === "object" && addr ? addr.port : port;
+    console.log(`Agent Comms web UI: http://localhost:${String(actualPort)}`);
+    console.log(
+      `Connected as ${userName} (user) [${handle.controller.agentId}]`,
+    );
   });
 
   // Graceful shutdown
   const cleanup = async (): Promise<void> => {
-    wss.close();
-    server.close();
-    await controller.shutdown();
+    handle.wss.close();
+    handle.server.close();
+    await handle.controller.shutdown();
     process.exit(0);
   };