feat: sequential port discovery for standalone PWA mesh discovery

Web server walks up from coordinatorPort+1 (19877 by default) instead
of using a random port. The standalone PWA probes the same range on
localhost to find the mesh WebSocket endpoint.

When served from GitHub Pages or any non-localhost host, the PWA:
- Skips the direct server WebSocket (CommsWs)
- Gracefully handles REST API failures (MeshClient provides state)
- Probes localhost:19877..19886 for the mesh WS endpoint

Author: Mearman

src/bridges/pi/index.ts

@@ -146,7 +146,7 @@ export default function (pi: ExtensionAPI) {
         cwd: process.cwd(),
         pid: process.pid,
       });
-      webHandle = await tryStartWebServer(webCtrl);
+      webHandle = await tryStartWebServer(webCtrl, store.coordinatorPort);
     }
 
     refreshStatus();

src/bridges/user/web/frontend/main.tsx

@@ -143,9 +143,16 @@ function sendAction(action: Action): void {
 }
 
 async function refreshState(): Promise<void> {
-  const [agents, rooms] = await Promise.all([fetchAgents(), fetchRooms()]);
-  state.setAgents(agents);
-  state.setRooms(rooms);
+  try {
+    const [agents, rooms] = await Promise.all([
+      fetchAgents(),
+      fetchRooms(),
+    ]);
+    state.setAgents(agents);
+    state.setRooms(rooms);
+  } catch {
+    // REST API unavailable (standalone PWA) — MeshClient provides state
+  }
 }
 
 async function onJoinRoom(roomId: string): Promise<void> {
@@ -275,7 +282,12 @@ state.subscribe(rerender);
 
 const deepLink = parseDeepLink(location.search);
 
-ws.connect();
+// Only connect the direct server WebSocket when served from localhost.
+// On GitHub Pages / standalone deployments, only MeshClient is used.
+const localPattern = /^(localhost|127\.\d+\.\d+\.\d+)(:\d+)?$/;
+if (localPattern.test(location.host)) {
+  ws.connect();
+}
 
 // Initial state fetch, then resolve any deep link from the URL
 void refreshState().then(() => {

src/bridges/user/web/frontend/mesh-client.ts

@@ -119,10 +119,21 @@ export class MeshClient {
 
     worker.port.start();
 
-    // Tell the worker to connect to the mesh WS endpoint
-    const proto = location.protocol === "https:" ? "wss:" : "ws:";
-    const url = `${proto}//${location.host}/ws/mesh`;
-    this.postToWorker({ type: "init", url });
+    // Discover the web server — walk up from 19877 matching the server's
+    // port discovery. If served by the local server (location.host is
+    // localhost/127.0.0.1), use that directly. Otherwise probe localhost.
+    const localPattern = /^(localhost|127\.\d+\.\d+\.\d+)(:\d+)?$/;
+    const isLocal = localPattern.test(location.host);
+    if (isLocal) {
+      const proto = location.protocol === "https:" ? "wss:" : "ws:";
+      const url = `${proto}//${location.host}/ws/mesh`;
+      this.postToWorker({ type: "init", url });
+    } else {
+      // Standalone PWA (e.g. GitHub Pages) — probe localhost ports.
+      // The web server binds at coordinatorPort + 1, walking up if taken.
+      // Coordinator defaults to 19876, so web server starts at 19877.
+      this.probeLocalMesh(19877, 10);
+    }
   }
 
   /** Get the current mesh state (snapshot). */
@@ -153,6 +164,35 @@ export class MeshClient {
     this.pendingActions.clear();
   }
 
+  /**
+   * Probe localhost ports sequentially for the web server's /ws/mesh endpoint.
+   * Matches the server's port discovery: starts at 19877, walks up.
+   * Sends an init message to the worker on first successful WS upgrade.
+   */
+  private probeLocalMesh(basePort: number, maxAttempts: number): void {
+    let attempts = 0;
+
+    const tryPort = (port: number): void => {
+      if (attempts >= maxAttempts) return;
+      attempts++;
+
+      const url = `ws://127.0.0.1:${String(port)}/ws/mesh`;
+      // Quick HTTP fetch to check if anything is listening and speaks our protocol.
+      // A WebSocket upgrade would be cleaner but fetch is simpler and avoids
+      // a visible WS error in the console.
+      fetch(`http://127.0.0.1:${String(port)}/`, { mode: "no-cors" })
+        .then(() => {
+          // Something responded — try connecting via the worker
+          this.postToWorker({ type: "init", url });
+        })
+        .catch(() => {
+          tryPort(port + 1);
+        });
+    };
+
+    tryPort(basePort);
+  }
+
   private postToWorker(msg: unknown): void {
     if (this.worker) {
       this.worker.port.postMessage(JSON.stringify(msg));

src/bridges/user/web/server.ts

@@ -32,6 +32,47 @@ import type {
 
 const WEB_HOST = "127.0.0.1";
 
+/** Maximum number of ports to try when searching for a free one. */
+const WEB_PORT_MAX_ATTEMPTS = 10;
+
+// ---------------------------------------------------------------------------
+// Port discovery — walk up from 19877
+// ---------------------------------------------------------------------------
+
+/**
+ * Try binding sequentially from WEB_PORT_BASE.
+ * Returns the first port that succeeds, or undefined if all are taken.
+ */
+function findFreePort(
+  base: number,
+  maxAttempts: number = WEB_PORT_MAX_ATTEMPTS,
+): Promise<number | undefined> {
+  return new Promise((resolve) => {
+    let attempts = 0;
+
+    function tryPort(port: number): void {
+      if (attempts >= maxAttempts) {
+        resolve(undefined);
+        return;
+      }
+      attempts++;
+
+      const probe = http.createServer();
+      probe.on("error", () => {
+        probe.close();
+        tryPort(port + 1);
+      });
+      probe.listen(port, WEB_HOST, () => {
+        const addr = probe.address();
+        const actualPort = typeof addr === "object" && addr ? addr.port : port;
+        probe.close(() => resolve(actualPort));
+      });
+    }
+
+    tryPort(base);
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Static assets — loaded into memory at module load
 // ---------------------------------------------------------------------------
@@ -105,8 +146,12 @@ export interface WebServerHandle {
  */
 export async function tryStartWebServer(
   controller?: ChatController,
+  coordinatorPort?: number,
 ): Promise<WebServerHandle | undefined> {
-  return createWebServer(0, controller);
+  const base = (coordinatorPort ?? 19876) + 1;
+  const port = await findFreePort(base);
+  if (port === undefined) return undefined;
+  return createWebServer(port, controller);
 }
 
 /**