fix(devframe): reject on server listen errors instead of hanging

startHttpAndWs's owned-server listen had no 'error' listener, so a
failed bind (e.g. EADDRINUSE) emitted 'error' with nobody attached —
an uncaughtException — while the listen promise never settled,
leaving createDevServer permanently pending. A caller doing
try { await createDevServer(...) } catch {} could not observe the
failure at all.

Attach a listen-scoped 'error' handler and reject with it. The WS RPC
transport is already attached by the time listen runs, so tear it
down via closeWs() before throwing to avoid leaking it and its peers.

The rejection is a new DF0052 diagnostic carrying the original node
error as `cause`, so callers can still branch on `error.cause.code`
(e.g. 'EADDRINUSE') while getting an actionable message and fix hint.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: dvcolomban

docs/errors/DF0052.md

@@ -0,0 +1,29 @@
+---
+outline: deep
+---
+
+# DF0052: HTTP Server Failed to Listen
+
+## Message
+
+> Failed to listen on `{host}:{port}`: `{reason}`
+
+## Cause
+
+`startHttpAndWs` tried to bind the HTTP server it owns to `host:port` and the underlying `listen()` call failed — most commonly `EADDRINUSE` (another process, often a previous devframe instance, is already bound to that port) or `EACCES` (insufficient permissions, typically a privileged port). The WS RPC transport is torn down before this error surfaces, so nothing is leaked.
+
+## Example
+
+```ts
+// A previous instance is still bound to 4096:
+// await startHttpAndWs({ context, host: 'localhost', port: 4096 }) → DF0052
+```
+
+## Fix
+
+- Free the port, or pick another via `--port`, `cli.port` / `cli.portRange` on the definition, or `devMiddleware.port` on `viteDevBridge`.
+- The original node error is available as `error.cause` — check `error.cause.code` (e.g. `'EADDRINUSE'`) to branch on the failure kind programmatically.
+
+## Source
+
+- [`packages/devframe/src/node/server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/server.ts) — `startHttpAndWs()` throws this when its owned HTTP server's `listen()` fails.

packages/devframe/src/node/__tests__/server.test.ts

@@ -100,3 +100,19 @@ describe('startHttpAndWs rpcOptions passthrough', () => {
     }
   })
 })
+
+describe('startHttpAndWs listen failures', () => {
+  it('rejects when the port is already taken instead of hanging', async () => {
+    const host = '127.0.0.1'
+    const first = await startHttpAndWs({ context: await createTestContext(), host, port: 0, auth: false })
+
+    try {
+      await expect(
+        startHttpAndWs({ context: await createTestContext(), host, port: first.port, auth: false }),
+      ).rejects.toThrow(expect.objectContaining({ code: 'DF0052' }))
+    }
+    finally {
+      await first.close()
+    }
+  })
+})

packages/devframe/src/node/diagnostics.ts

@@ -112,5 +112,9 @@ export const diagnostics = defineDiagnostics({
       why: (p: { port: number }) => `The devframe instance on port ${p.port} has no MCP endpoint.`,
       fix: 'Restart the instance with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again.',
     },
+    DF0052: {
+      why: (p: { host: string, port: number, reason: string }) => `Failed to listen on ${p.host}:${p.port}: ${p.reason}`,
+      fix: 'The port is likely already taken by another process (often a previous devframe instance). Free it, or pick another via `--port`, `cli.port` / `cli.portRange` on the definition, or `devMiddleware.port` on `viteDevBridge`. The original node error is available as `error.cause`.',
+    },
   },
 })

packages/devframe/src/node/server.ts

@@ -254,9 +254,25 @@ export async function startHttpAndWs(options: StartHttpAndWsOptions): Promise<St
   // Only start listening on a server we created. A shared server is already
   // (or about to be) listening under the caller's control.
   if (ownsHttpServer) {
-    await new Promise<void>((resolveListen) => {
-      httpServer.listen(port, bindHost, () => resolveListen())
-    })
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const onError = (error: Error): void => reject(error)
+        // Without this listener a failed bind emits `error` with nobody
+        // attached — an uncaughtException — and the `listen` callback never
+        // fires, so this promise never settles.
+        httpServer.once('error', onError)
+        httpServer.listen(port, bindHost, () => {
+          httpServer.removeListener('error', onError)
+          resolve()
+        })
+      })
+    }
+    catch (error) {
+      // The WS transport is already attached above, so tear it down before
+      // surfacing the failure rather than leaking it and its peers.
+      await closeWs().catch(() => {})
+      throw diagnostics.DF0052({ host: bindHost, port, reason: (error as Error).message, cause: error as Error })
+    }
   }
 
   const address = httpServer.address()