Merge remote-tracking branch 'origin/main' into dvcol/on-peer-disconnect

# Conflicts:
#	packages/devframe/src/node/__tests__/server.test.ts

Author: antfubot

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.

docs/errors/DF8206.md

@@ -0,0 +1,21 @@
+---
+outline: deep
+---
+
+# DF8206: Terminal Session Restart on Closed Stream
+
+## Message
+
+> Terminal session "`{id}`" cannot be restarted — its output stream is already closed
+
+## Cause
+
+`restart()` was called on a `startChildProcess()` or `startPtySession()` session whose output stream is already closed. The stream closes irreversibly on a natural process exit or after `terminate()` — it backs a single-use `ReadableStream` controller that cannot be reopened, so restarting in place is not possible once it has closed.
+
+## Fix
+
+Drop the spent session with `ctx.terminals.remove(session)`, then spawn a replacement via `ctx.terminals.startChildProcess()` or `ctx.terminals.startPtySession()` with a fresh id.
+
+## Source
+
+- [`packages/hub/src/node/host-terminals.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-terminals.ts) — the `restart()` handle returned by `startChildProcess()` and `startPtySession()` throws this once the session's stream has closed.

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

@@ -144,3 +144,19 @@ describe('startHttpAndWs onPeerConnect / onPeerDisconnect', () => {
     }
   })
 })
+
+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

@@ -263,9 +263,30 @@ 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 instanceof Error ? error.message : String(error),
+        cause: error,
+      })
+    }
   }
 
   const address = httpServer.address()

packages/hub/src/node/__tests__/host-terminals.test.ts

@@ -163,7 +163,7 @@ describe('devframeTerminalHost stream lifecycle', () => {
     expect(session.buffer!.includes('line-0')).toBe(false)
   })
 
-  it('does not restart a terminated child-process session', async () => {
+  it('rejects restarting a terminated child-process session', async () => {
     const { host, sinks } = createTerminalHost()
     const session = await host.startChildProcess(
       { command: process.execPath, args: ['-e', 'setInterval(() => {}, 1000)'] },
@@ -173,7 +173,7 @@ describe('devframeTerminalHost stream lifecycle', () => {
     await waitUntil(() => {
       expect(sinks.get('child')?.closed).toBe(true)
     })
-    await session.restart()
+    await expect(session.restart()).rejects.toThrow(expect.objectContaining({ code: 'DF8206' }))
     // Stream stays closed; no orphan output stream.
     expect(sinks.get('child')?.closed).toBe(true)
   })
@@ -509,9 +509,9 @@ describe('devframeTerminalHost PTY status lifecycle', () => {
     await waitUntil(() => {
       expect(session.status).toBe('stopped')
     })
-    // The stream is closed for good, so `restart()` is a no-op — the session
+    // The stream is closed for good, so `restart()` rejects — the session
     // stays reported as stopped rather than flipping back to running.
-    await session.restart()
+    await expect(session.restart()).rejects.toThrow(expect.objectContaining({ code: 'DF8206' }))
     expect(session.status).toBe('stopped')
   })
 })

packages/hub/src/node/diagnostics.ts

@@ -67,6 +67,10 @@ export const diagnostics = defineDiagnostics({
       why: (p: { id: string }) => `Terminal session "${p.id}" is not restartable`,
       fix: 'It was registered with `restartable: false`; restart it through its owner\'s controls, or spawn it with `restartable: true` (the default) to allow in-place restarts.',
     },
+    DF8206: {
+      why: (p: { id: string }) => `Terminal session "${p.id}" cannot be restarted — its output stream is already closed`,
+      fix: 'The session already exited (or was terminated) and its stream is spent. Drop it with `ctx.terminals.remove(session)`, then spawn a replacement via `ctx.terminals.startChildProcess()` or `ctx.terminals.startPtySession()` with a fresh id.',
+    },
     DF8400: {
       why: (p: { id: string }) => `Command "${p.id}" is already registered`,
     },

packages/hub/src/node/host-terminals.ts

@@ -322,7 +322,7 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
 
     const restart = async () => {
       if (streamClosed)
-        return
+        throw diagnostics.DF8206({ id: terminal.id })
       cp?.kill()
       cp = createChildProcess()
       markStatus('running')
@@ -497,7 +497,7 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
       },
       restart: async () => {
         if (streamClosed)
-          return
+          throw diagnostics.DF8206({ id: terminal.id })
         pty?.kill()
         pty = spawnPty()
         markStatus('running')

packages/hub/src/types/terminals.ts

@@ -114,6 +114,7 @@ export interface DevframeChildProcessTerminalSession extends DevframeTerminalSes
    */
   getResult: () => DevframeChildProcessResult
   terminate: () => Promise<void>
+  /** Throws `DF8206` once the session's output stream has closed (after a natural exit or `terminate()`) — drop it with `ctx.terminals.remove(session)` and start a fresh session instead. */
   restart: () => Promise<void>
 }
 
@@ -139,5 +140,6 @@ export interface DevframePtyTerminalSession extends DevframeTerminalSession {
   /** Current foreground process name, when the backend can resolve it. */
   getProcessName: () => string | undefined
   terminate: () => Promise<void>
+  /** Throws `DF8206` once the session's output stream has closed (after a natural exit or `terminate()`) — drop it with `ctx.terminals.remove(session)` and start a fresh session instead. */
   restart: () => Promise<void>
 }