feat(cli): Add comprehensive error handling and crash recovery system

- Add ErrorScreen component with styled error display, stack traces, and Discord link
- Add crash error state management to chat store
- Integrate error screen into Chat component
- Extend keyboard handlers to dismiss errors (C/ESC) or exit (R)
- Add process-level error handlers for uncaught exceptions and promise rejections
- Suppress Opentui console errors by intercepting stderr/stdout
- Disable Opentui's built-in console overlay in favor of custom error screen

Author: brandonkachen

cli/src/chat.tsx

@@ -4,6 +4,7 @@ import { useShallow } from 'zustand/react/shallow'
 
 import { routeUserPrompt } from './commands/router'
 import { AgentModeToggle } from './components/agent-mode-toggle'
+import { ErrorScreen } from './components/error-screen'
 import { LoginModal } from './components/login-modal'
 import { MessageRenderer } from './components/message-renderer'
 import {
@@ -119,6 +120,8 @@ export const Chat = ({
     setHasReceivedPlanResponse,
     lastMessageMode,
     setLastMessageMode,
+    crashError,
+    setCrashError,
     resetChatStore,
   } = useChatStore(
     useShallow((store) => ({
@@ -151,6 +154,8 @@ export const Chat = ({
       setHasReceivedPlanResponse: store.setHasReceivedPlanResponse,
       lastMessageMode: store.lastMessageMode,
       setLastMessageMode: store.setLastMessageMode,
+      crashError: store.crashError,
+      setCrashError: store.setCrashError,
       resetChatStore: store.reset,
     })),
   )
@@ -284,6 +289,10 @@ export const Chat = ({
     setInputValue,
   })
 
+  const handleDismissCrashError = useCallback(() => {
+    setCrashError(null)
+  }, [setCrashError])
+
   const [scrollIndicatorHovered, setScrollIndicatorHovered] = useState(false)
 
   const {
@@ -486,6 +495,9 @@ export const Chat = ({
     onCtrlC: handleCtrlC,
     historyNavUpEnabled,
     historyNavDownEnabled,
+    hasCrashError: crashError !== null,
+    onDismissCrashError: handleDismissCrashError,
+    onRestartApp: resetChatStore,
   })
 
   const { tree: messageTree, topLevelMessages } = useMemo(
@@ -849,6 +861,15 @@ export const Chat = ({
           hasInvalidCredentials={hasInvalidCredentials}
         />
       )}
+
+      {/* Error Screen Overlay - show when a crash error occurs */}
+      {crashError && (
+        <ErrorScreen
+          error={crashError}
+          onDismiss={handleDismissCrashError}
+          onRestart={resetChatStore}
+        />
+      )}
     </box>
   )
 }

cli/src/components/error-screen.tsx

@@ -0,0 +1,227 @@
+import { TextAttributes } from '@opentui/core'
+import React, { useCallback } from 'react'
+
+import { useTheme } from '../hooks/use-theme'
+import { BORDER_CHARS } from '../utils/ui-constants'
+
+import type { CrashError } from '../state/chat-store'
+
+interface ErrorScreenProps {
+  error: CrashError
+  onDismiss: () => void
+  onRestart?: () => void
+}
+
+export const ErrorScreen = ({ error, onDismiss, onRestart }: ErrorScreenProps) => {
+  const theme = useTheme()
+
+  // Clear the screen when error screen mounts
+  React.useEffect(() => {
+    // Clear the terminal to remove any console output
+    process.stdout.write('\x1b[2J\x1b[3J\x1b[H')
+  }, [])
+
+  const handleDismiss = useCallback(
+    (e?: any) => {
+      if (e && e.stopPropagation) {
+        e.stopPropagation()
+      }
+      onDismiss()
+    },
+    [onDismiss],
+  )
+
+  const handleRestart = useCallback(
+    (e?: any) => {
+      if (e && e.stopPropagation) {
+        e.stopPropagation()
+      }
+      // For a proper restart after an error, exit the process
+      // The user's shell or process manager can restart it
+      process.exit(1)
+    },
+    [onRestart],
+  )
+
+  const errorTime = new Date(error.timestamp).toLocaleTimeString()
+
+  return (
+    <box
+      style={{
+        position: 'absolute',
+        left: 0,
+        top: 0,
+        width: '100%',
+        height: '100%',
+        backgroundColor: '#000000',
+        flexDirection: 'column',
+        justifyContent: 'center',
+        alignItems: 'center',
+        zIndex: 999999, // Extremely high z-index to ensure we're always on top
+      }}
+    >
+      <box
+        style={{
+          width: '80%',
+          maxWidth: 100,
+          borderStyle: 'double',
+          borderColor: theme.error,
+          customBorderChars: BORDER_CHARS,
+          backgroundColor: theme.background,
+          flexDirection: 'column',
+          gap: 1,
+          paddingLeft: 2,
+          paddingRight: 2,
+          paddingTop: 1,
+          paddingBottom: 1,
+        }}
+      >
+        <box style={{ flexDirection: 'column', gap: 0 }}>
+          <text style={{ wrapMode: 'word' }}>
+            <span fg={theme.error} attributes={TextAttributes.BOLD}>
+              ⚠ Application Error
+            </span>
+          </text>
+          <text style={{ wrapMode: 'word' }}>
+            <span fg={theme.muted}>at {errorTime}</span>
+          </text>
+        </box>
+
+        <box
+          style={{
+            flexDirection: 'column',
+            gap: 1,
+            paddingLeft: 1,
+            paddingRight: 1,
+            paddingTop: 1,
+            paddingBottom: 1,
+            backgroundColor: theme.secondary,
+          }}
+        >
+          <text>
+            <span fg={theme.foreground}>
+              This error has been shared with the team.{'\n'}
+              Feel free to join the discussion at:{'\n'}
+            </span>
+            <span fg={theme.info} attributes={TextAttributes.UNDERLINE}>
+              https://codebuff.com/discord
+            </span>
+          </text>
+        </box>
+
+        <box
+          style={{
+            flexDirection: 'column',
+            gap: 0,
+            backgroundColor: theme.secondary,
+            paddingLeft: 1,
+            paddingRight: 1,
+            paddingTop: 0,
+            paddingBottom: 0,
+          }}
+        >
+          <text style={{ wrapMode: 'word' }}>
+            <span fg={theme.foreground}>{error.message}</span>
+          </text>
+        </box>
+
+        {error.stack && (
+          <box
+            style={{
+              flexDirection: 'column',
+              gap: 0,
+              maxHeight: 10,
+            }}
+          >
+            <text style={{ wrapMode: 'word' }}>
+              <span fg={theme.muted} attributes={TextAttributes.ITALIC}>
+                Stack trace:
+              </span>
+            </text>
+            <scrollbox
+              scrollX={false}
+              scrollbarOptions={{ visible: false }}
+              style={{
+                flexGrow: 1,
+                rootOptions: {
+                  flexGrow: 1,
+                  padding: 0,
+                  gap: 0,
+                  flexDirection: 'column',
+                },
+                wrapperOptions: {
+                  flexGrow: 1,
+                  border: false,
+                },
+                contentOptions: {
+                  flexDirection: 'column',
+                  gap: 0,
+                },
+              }}
+            >
+              <text style={{ wrapMode: 'word' }}>
+                <span fg={theme.muted}>{error.stack}</span>
+              </text>
+            </scrollbox>
+          </box>
+        )}
+
+        <box
+          style={{
+            flexDirection: 'row',
+            gap: 2,
+            justifyContent: 'center',
+          }}
+        >
+          <box
+            style={{
+              backgroundColor: theme.secondary,
+              paddingLeft: 2,
+              paddingRight: 2,
+              borderStyle: 'single',
+              borderColor: theme.muted,
+            }}
+            onMouseDown={handleDismiss}
+          >
+            <text>
+              <span fg={theme.foreground} attributes={TextAttributes.BOLD}>
+                [C] Continue
+              </span>
+            </text>
+          </box>
+          {onRestart && (
+            <box
+              style={{
+                backgroundColor: theme.info,
+                paddingLeft: 2,
+                paddingRight: 2,
+                borderStyle: 'single',
+                borderColor: theme.info,
+              }}
+              onMouseDown={handleRestart}
+            >
+              <text>
+                <span fg={theme.background} attributes={TextAttributes.BOLD}>
+                  [R] Exit
+                </span>
+              </text>
+            </box>
+          )}
+        </box>
+        <box
+          style={{
+            flexDirection: 'column',
+            gap: 0,
+            alignItems: 'center',
+          }}
+        >
+          <text style={{ wrapMode: 'word' }}>
+            <span fg={theme.muted} attributes={TextAttributes.ITALIC}>
+              Press ESC/C to continue or R to exit
+            </span>
+          </text>
+        </box>
+      </box>
+    </box>
+  )
+}

cli/src/hooks/use-keyboard-handlers.ts

@@ -18,6 +18,9 @@ interface KeyboardHandlersConfig {
   onCtrlC: () => boolean
   historyNavUpEnabled: boolean
   historyNavDownEnabled: boolean
+  hasCrashError: boolean
+  onDismissCrashError: () => void
+  onRestartApp?: () => void
 }
 
 export const useKeyboardHandlers = ({
@@ -35,13 +38,43 @@ export const useKeyboardHandlers = ({
   onCtrlC,
   historyNavUpEnabled,
   historyNavDownEnabled,
+  hasCrashError,
+  onDismissCrashError,
+  onRestartApp,
 }: KeyboardHandlersConfig) => {
   useKeyboard(
     useCallback(
       (key) => {
         const isEscape = key.name === 'escape'
         const isCtrlC = key.ctrl && key.name === 'c'
 
+        // Handle keyboard shortcuts when crash error is visible
+        if (hasCrashError) {
+          // ESC or C key to continue
+          if (isEscape || (!key.ctrl && key.name === 'c')) {
+            if (
+              'preventDefault' in key &&
+              typeof key.preventDefault === 'function'
+            ) {
+              key.preventDefault()
+            }
+            onDismissCrashError()
+            return
+          }
+
+          // R key to restart
+          if (!key.ctrl && key.name === 'r' && onRestartApp) {
+            if (
+              'preventDefault' in key &&
+              typeof key.preventDefault === 'function'
+            ) {
+              key.preventDefault()
+            }
+            onRestartApp()
+            return
+          }
+        }
+
         if ((isEscape || isCtrlC) && (isStreaming || isWaitingForResponse)) {
           if (
             'preventDefault' in key &&
@@ -68,7 +101,15 @@ export const useKeyboardHandlers = ({
           }
         }
       },
-      [isStreaming, isWaitingForResponse, abortControllerRef, onCtrlC],
+      [
+        isStreaming,
+        isWaitingForResponse,
+        abortControllerRef,
+        onCtrlC,
+        hasCrashError,
+        onDismissCrashError,
+        onRestartApp,
+      ],
     ),
   )