fix(hub): handle PTY restart failures

Author: dvcolomban

docs/content/5.add-ons/1.devframes/6.terminals.md

@@ -61,7 +61,7 @@ Mounted into a hub, the devframe spawns on its own channel (`devframes:plugin:te
 
 `ctx.terminals` is the source of truth; the devframe, the sole PTY provider, duck-types a minimal `register` / `update` / `events` shape to run without `@devframes/hub`.
 
-Both spawned session types carry a `getResult()` accessor. A `startChildProcess()` result is an `await`able `{ stdout, stderr, exitCode }` with live process getters and `kill()`. A `startPtySession()` result captures its merged terminal stream as an `await`able `{ output, exitCode, signal }` with live `pid`, `exitCode`, and `killed` getters.
+Both spawned terminal session types carry a `getResult()` accessor. A `startChildProcess()` result is an `await`able `{ stdout, stderr, exitCode }` with live process getters and `kill()`. A `startPtySession()` result captures its merged terminal stream as an `await`able `{ output, exitCode, signal }` with live `pid`, `exitCode`, and `killed` getters. `killed` is the portable termination indicator; `signal` is present when the PTY backend reports one.
 
 ## Focusing a session
 

docs/content/6.errors/DF8203.md

@@ -21,4 +21,4 @@ directory does not exist, or spawning was denied by the OS.
 
 ## Source
 
-- [`packages/hub/src/node/host-terminals.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-terminals.ts) — `DevframeTerminalsHost.startPtySession()` throws this when the initial `zigpty` spawn fails.
+- [`packages/hub/src/node/host-terminals.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-terminals.ts) — `DevframeTerminalsHost.startPtySession()` throws this when an initial or restart `zigpty` spawn fails.

docs/content/8.references/6.hub-api.md

@@ -14,7 +14,7 @@ What `DevframeHubContext` adds to `DevframeNodeContext` — [Hub](/guide/hub).
 | Subsystem | API | Purpose |
 |---|---|---|
 | `ctx.docks` | `register / update / values / activate` | Dock entries (iframes, launchers, custom-render) and groups; `activate(dockId, params?)` sets the active dock ([Cross-iframe dock activation](/guide/hub#cross-iframe-dock-activation)). |
-| `ctx.terminals` | `register / startChildProcess` | Aggregate terminal sessions, streaming output ([Terminals](/add-ons/devframes/terminals#hub-aggregation)). |
+| `ctx.terminals` | `register / startChildProcess / startPtySession` | Aggregate terminal sessions, streaming output ([Terminals](/add-ons/devframes/terminals#hub-aggregation)). |
 | `ctx.messages` | `add / update / remove / clear` | Server-side toast/notification queue (FIFO, capped at 1000). |
 | `ctx.commands` | `register / execute / list` | Hierarchical command palette with keybindings and `when` clauses. |
 

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

@@ -5,6 +5,19 @@ import { describe, expect, it, vi } from 'vitest'
 import { hasNative } from 'zigpty'
 import { DevframeTerminalsHost } from '../host-terminals'
 
+const zigptyModuleMock = vi.hoisted(() => ({
+  spawn: vi.fn(),
+}))
+
+vi.mock('zigpty', async (importOriginal) => {
+  const originalModule = await importOriginal<typeof import('zigpty')>()
+  zigptyModuleMock.spawn.mockImplementation(originalModule.spawn)
+  return {
+    ...originalModule,
+    spawn: zigptyModuleMock.spawn,
+  }
+})
+
 const NODE = process.execPath
 // A real PTY works wherever zigpty's native bindings load (incl. Windows
 // ConPTY); skip when they're unavailable.
@@ -419,6 +432,8 @@ describe('devframeTerminalHost interactive PTY sessions', () => {
   })
 
   itPty('getResult() resolves merged PTY output after natural exit', async () => {
+    expect.assertions(9)
+
     const { host } = createTerminalHost()
 
     const session = await host.startPtySession({
@@ -441,6 +456,8 @@ describe('devframeTerminalHost interactive PTY sessions', () => {
   })
 
   itPty('getResult() preserves a non-zero PTY exit code', async () => {
+    expect.assertions(3)
+
     const { host } = createTerminalHost()
 
     const session = await host.startPtySession({
@@ -459,6 +476,8 @@ describe('devframeTerminalHost interactive PTY sessions', () => {
   })
 
   itPty('getResult() marks a terminated PTY run as killed', async () => {
+    expect.assertions(4)
+
     const { host } = createTerminalHost()
 
     const session = await host.startPtySession({
@@ -467,7 +486,8 @@ describe('devframeTerminalHost interactive PTY sessions', () => {
     }, { id: 'pty-result-terminate', title: 'PTY result terminate' })
     const result = session.getResult()
     await waitUntil(() => {
-      expect(session.buffer?.join('')).toContain('started')
+      if (!session.buffer?.join('').includes('started'))
+        throw new Error('PTY output has not started')
     })
 
     await session.terminate()
@@ -477,30 +497,16 @@ describe('devframeTerminalHost interactive PTY sessions', () => {
     await expect(result).resolves.toMatchObject({
       output: expect.stringContaining('started'),
       exitCode: undefined,
-      signal: expect.any(Number),
     })
-  })
-
-  itPty('isolates getResult() output between independently spawned PTY sessions', async () => {
-    const { host } = createTerminalHost()
-
-    const firstSession = await host.startPtySession({
-      command: NODE,
-      args: ['-e', 'process.stdout.write("first-run")'],
-    }, { id: 'pty-result-first', title: 'First PTY result' })
-    const secondSession = await host.startPtySession({
-      command: NODE,
-      args: ['-e', 'process.stdout.write("second-run")'],
-    }, { id: 'pty-result-second', title: 'Second PTY result' })
-
-    const [firstOutput, secondOutput] = await Promise.all([firstSession.getResult(), secondSession.getResult()])
-    expect(firstOutput.output).toContain('first-run')
-    expect(firstOutput.output).not.toContain('second-run')
-    expect(secondOutput.output).toContain('second-run')
-    expect(secondOutput.output).not.toContain('first-run')
+    if (process.platform === 'win32')
+      await expect(result).resolves.toHaveProperty('signal', undefined)
+    else
+      await expect(result).resolves.toHaveProperty('signal', expect.any(Number))
   })
 
   itPty('getResult() isolates the previous PTY run after restart()', async () => {
+    expect.assertions(8)
+
     const { host } = createTerminalHost()
 
     const session = await host.startPtySession({
@@ -509,15 +515,17 @@ describe('devframeTerminalHost interactive PTY sessions', () => {
     }, { id: 'pty-result-restart', title: 'PTY result restart' })
     const firstResult = session.getResult()
     await waitUntil(() => {
-      expect(session.buffer?.join('')).toContain(`run:${firstResult.pid}`)
+      if (!session.buffer?.join('').includes(`run:${firstResult.pid}`))
+        throw new Error('First PTY run has not started')
     })
 
     await session.restart()
     const secondResult = session.getResult()
     expect(secondResult).not.toBe(firstResult)
     expect(secondResult.pid).not.toBe(firstResult.pid)
     await waitUntil(() => {
-      expect(session.buffer?.join('')).toContain(`run:${secondResult.pid}`)
+      if (!session.buffer?.join('').includes(`run:${secondResult.pid}`))
+        throw new Error('Second PTY run has not started')
     })
 
     await session.terminate()
@@ -530,6 +538,33 @@ describe('devframeTerminalHost interactive PTY sessions', () => {
     expect(secondOutput.output).not.toContain(`run:${firstResult.pid}`)
   })
 
+  itPty('reports a structured error when restart fails to spawn a PTY', async () => {
+    expect.assertions(5)
+
+    const { host } = createTerminalHost()
+    const session = await host.startPtySession({
+      command: NODE,
+      args: ['-e', 'process.stdout.write("started"); setInterval(() => {}, 4000)'],
+    }, { id: 'pty-result-restart-error', title: 'PTY result restart error' })
+    const result = session.getResult()
+    await waitUntil(() => {
+      if (!session.buffer?.join('').includes('started'))
+        throw new Error('PTY output has not started')
+    })
+    zigptyModuleMock.spawn.mockImplementationOnce(() => {
+      throw new Error('restart spawn failed')
+    })
+
+    await expect(session.restart()).rejects.toThrow(expect.objectContaining({ code: 'DF8203' }))
+    expect(session.status).toBe('error')
+    expect(session.getProcessName()).toBeUndefined()
+    expect(session.getResult()).toBe(result)
+    await expect(result).resolves.toMatchObject({
+      output: expect.stringContaining('started'),
+      exitCode: undefined,
+    })
+  })
+
   itPty('does not accept resize after termination without throwing', async () => {
     const { host } = createTerminalHost()
 

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

@@ -421,7 +421,7 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
 
     const spawnPty = (): IPty => {
       const currentRun = ++runId
-      const proc = spawn(executeOptions.command, executeOptions.args ?? [], {
+      const ptyProcess = spawn(executeOptions.command, executeOptions.args ?? [], {
         name: PTY_TERM_NAME,
         cols,
         rows,
@@ -456,41 +456,42 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
         })
       }
 
-      proc.onData((data) => {
+      ptyProcess.onData((data) => {
         const text = typeof data === 'string' ? data : data.toString('utf8')
         outputChunks.push(text)
         if (!streamClosed && currentRun === runId)
           controller?.enqueue(text)
       })
-      proc.onExit(({ exitCode, signal }) => {
+      ptyProcess.onExit(({ exitCode, signal }) => {
         settle(exitCode, signal)
         if (currentRun !== runId)
           return
         closeStream()
-        // A signal kill (terminate()/restart()) is a deliberate stop; a clean
-        // exit is a deliberate stop too. Only an unsignalled non-zero exit
-        // code is a crash, matching the child-process comment above.
+        /**
+         * A signal kill (terminate()/restart()) and a clean exit are deliberate stops.
+         * Only an unsignalled non-zero exit code is a crash, matching the child-process path.
+         */
         markStatus(signal === 0 && exitCode !== 0 ? 'error' : 'stopped')
       })
       currentResult = {
         get pid() {
-          return proc.pid
+          return ptyProcess.pid
         },
         get exitCode() {
-          return killed ? undefined : (proc.exitCode ?? settledExitCode)
+          return killed ? undefined : (ptyProcess.exitCode ?? settledExitCode)
         },
         get killed() {
           return killed
         },
         then: (onfulfilled, onrejected) => outputPromise.then(onfulfilled, onrejected),
       }
       killCurrentRun = () => {
-        if (proc.exitCode !== null)
+        if (ptyProcess.exitCode !== null)
           return
         killed = true
-        proc.kill()
+        ptyProcess.kill()
       }
-      return proc
+      return ptyProcess
     }
 
     try {
@@ -547,7 +548,18 @@ export class DevframeTerminalsHost implements DevframeTerminalsHostType {
         if (streamClosed)
           throw diagnostics.DF8206({ id: terminal.id })
         killCurrentRun?.()
-        pty = spawnPty()
+        pty = undefined
+        try {
+          pty = spawnPty()
+        }
+        catch (error) {
+          errorStream(error)
+          markStatus('error')
+          throw diagnostics.DF8203({
+            command: executeOptions.command,
+            reason: error instanceof Error ? error.message : String(error),
+          })
+        }
         markStatus('running')
       },
     }