feat(error-handling): implement workflow error handling and error modal

add error behavior evaluation and handling throughout workflow execution
introduce error modal in TUI to display workflow errors
add global error toast utility for consistent error display
update workflow status types to include error state

Author: moazbuilds

src/cli/tui/app-shell.tsx

@@ -110,6 +110,16 @@ export function App(props: { initialToast?: InitialToast }) {
   const toast = useToast()
   const kv = useKV()
 
+  // Global error handler - any part of the app can emit 'app:error' to show a toast
+  const handleAppError = (data: { message: string; duration?: number }) => {
+    toast.show({
+      variant: "error",
+      message: data.message,
+      duration: data.duration ?? 0, // permanent by default
+    })
+  }
+  ;(process as NodeJS.EventEmitter).on('app:error', handleAppError)
+
   const [ctrlCPressed, setCtrlCPressed] = createSignal(false)
   let ctrlCTimeout: NodeJS.Timeout | null = null
   const [view, setView] = createSignal<"home" | "onboard" | "workflow">("home")
@@ -175,7 +185,9 @@ export function App(props: { initialToast?: InitialToast }) {
     pendingWorkflowStart = () => {
       import("../../workflows/execution/queue.js").then(({ runWorkflowQueue }) => {
         runWorkflowQueue({ cwd, specificationPath: specPath }).catch((error) => {
-          console.error("Workflow failed:", error)
+          // Emit error event to show toast with actual error message
+          const errorMsg = error instanceof Error ? error.message : String(error)
+          ;(process as NodeJS.EventEmitter).emit('app:error', { message: errorMsg })
         })
       })
     }

src/cli/tui/routes/workflow/adapters/opentui.ts

@@ -6,6 +6,7 @@
  */
 
 import type { WorkflowEvent } from "../../../../../workflows/events/index.js"
+import { debug } from "../../../../../shared/logging/logger.js"
 import type { AgentStatus, SubAgentState, LoopState, ChainedState, InputState, TriggeredAgentState } from "../state/types.js"
 import { BaseUIAdapter } from "./base.js"
 import type { UIAdapterOptions } from "./types.js"
@@ -40,7 +41,7 @@ export interface UIActions {
   batchAddSubAgents(parentId: string, subAgents: SubAgentState[]): void
   updateSubAgentStatus(subAgentId: string, status: AgentStatus): void
   clearSubAgents(parentId: string): void
-  setWorkflowStatus(status: "running" | "stopping" | "completed" | "stopped" | "checkpoint" | "paused"): void
+  setWorkflowStatus(status: "running" | "stopping" | "completed" | "stopped" | "checkpoint" | "paused" | "error"): void
   setCheckpointState(checkpoint: { active: boolean; reason?: string } | null): void
   setInputState(inputState: InputState | null): void
   /** @deprecated Use setInputState instead */
@@ -94,6 +95,7 @@ export class OpenTUIAdapter extends BaseUIAdapter {
         break
 
       case "workflow:status":
+        debug(`[DEBUG Adapter] Received workflow:status event with status=${event.status}`)
         this.actions.setWorkflowStatus(event.status)
         break
 

src/cli/tui/routes/workflow/components/modals/error-modal.tsx

@@ -0,0 +1,69 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * Error Modal
+ *
+ * Displays workflow errors.
+ */
+
+import { useKeyboard, useTerminalDimensions } from "@opentui/solid"
+import { useTheme } from "@tui/shared/context/theme"
+import { ModalBase, ModalHeader, ModalFooter } from "@tui/shared/components/modal"
+
+export interface ErrorModalProps {
+  message: string
+  onClose: () => void
+}
+
+export function ErrorModal(props: ErrorModalProps) {
+  const themeCtx = useTheme()
+  const dimensions = useTerminalDimensions()
+
+  const modalWidth = () => {
+    const safeWidth = Math.max(50, (dimensions()?.width ?? 80) - 8)
+    return Math.min(safeWidth, 80)
+  }
+
+  const modalHeight = () => {
+    const safeHeight = Math.max(15, (dimensions()?.height ?? 30) - 6)
+    return Math.min(safeHeight, 25)
+  }
+
+  useKeyboard((evt) => {
+    if (evt.name === "return" || evt.name === "escape" || evt.name === "q") {
+      evt.preventDefault()
+      props.onClose()
+      return
+    }
+  })
+
+  // Calculate content height (modal height minus header, footer, padding)
+  const contentHeight = () => modalHeight() - 7
+
+  return (
+    <ModalBase width={modalWidth()}>
+      <ModalHeader title="Workflow Error" icon="!" iconColor={themeCtx.theme.error} />
+      <box
+        paddingLeft={2}
+        paddingRight={2}
+        paddingTop={1}
+        paddingBottom={1}
+        height={contentHeight()}
+        overflow="scroll"
+      >
+        <text fg={themeCtx.theme.error}>{props.message}</text>
+      </box>
+      <box flexDirection="row" justifyContent="center" paddingBottom={1}>
+        <box
+          paddingLeft={2}
+          paddingRight={2}
+          backgroundColor={themeCtx.theme.textMuted}
+          borderColor={themeCtx.theme.textMuted}
+          border
+        >
+          <text fg={themeCtx.theme.background}>Close</text>
+        </box>
+      </box>
+      <ModalFooter shortcuts="[ENTER/Esc/Q] Close" />
+    </ModalBase>
+  )
+}

src/cli/tui/routes/workflow/components/modals/index.ts

@@ -8,3 +8,4 @@ export { CheckpointModal, type CheckpointModalProps } from "./checkpoint-modal"
 export { LogViewer, type LogViewerProps } from "./log-viewer"
 export { HistoryView, type HistoryViewProps } from "./history-view"
 export { StopModal, type StopModalProps } from "./stop-modal"
+export { ErrorModal, type ErrorModalProps } from "./error-modal"

src/cli/tui/routes/workflow/state/types.ts

@@ -55,7 +55,7 @@ export interface LoopState {
   reason?: string
 }
 
-export type WorkflowStatus = "running" | "stopping" | "completed" | "stopped" | "checkpoint" | "paused"
+export type WorkflowStatus = "running" | "stopping" | "completed" | "stopped" | "checkpoint" | "paused" | "error"
 
 export interface CheckpointState {
   active: boolean

src/cli/tui/routes/workflow/workflow-shell.tsx

@@ -14,7 +14,7 @@ import { useUIState } from "./context/ui-state"
 import { AgentTimeline } from "./components/timeline"
 import { OutputWindow, TelemetryBar, StatusFooter } from "./components/output"
 import { formatRuntime } from "./state/formatters"
-import { CheckpointModal, LogViewer, HistoryView, StopModal } from "./components/modals"
+import { CheckpointModal, LogViewer, HistoryView, StopModal, ErrorModal } from "./components/modals"
 import { OpenTUIAdapter } from "./adapters/opentui"
 import { useLogStream } from "./hooks/useLogStream"
 import { useSubAgentSync } from "./hooks/useSubAgentSync"
@@ -90,7 +90,21 @@ export function WorkflowShell(props: WorkflowShellProps) {
     ui.actions.setWorkflowStatus("stopped")
   }
 
+  // Error modal state
+  const [errorMessage, setErrorMessage] = createSignal<string | null>(null)
+  const isErrorModalActive = () => errorMessage() !== null
+
+  const handleWorkflowError = (data: { reason: string }) => {
+    setErrorMessage(data.reason)
+    ui.actions.setWorkflowStatus("error")
+  }
+
+  const handleErrorModalClose = () => {
+    setErrorMessage(null)
+  }
+
   onMount(() => {
+    ;(process as NodeJS.EventEmitter).on('workflow:error', handleWorkflowError)
     ;(process as NodeJS.EventEmitter).on('workflow:stopping', handleStopping)
     ;(process as NodeJS.EventEmitter).on('workflow:user-stop', handleUserStop)
     if (props.eventBus) {
@@ -102,6 +116,7 @@ export function WorkflowShell(props: WorkflowShellProps) {
   })
 
   onCleanup(() => {
+    ;(process as NodeJS.EventEmitter).off('workflow:error', handleWorkflowError)
     ;(process as NodeJS.EventEmitter).off('workflow:stopping', handleStopping)
     ;(process as NodeJS.EventEmitter).off('workflow:user-stop', handleUserStop)
     if (adapter) {
@@ -275,7 +290,7 @@ export function WorkflowShell(props: WorkflowShellProps) {
     getState: state,
     actions: ui.actions,
     calculateVisibleItems: getVisibleItems,
-    isModalBlocking: () => isCheckpointActive() || modals.isLogViewerActive() || modals.isHistoryActive() || modals.isHistoryLogViewerActive() || showStopModal(),
+    isModalBlocking: () => isCheckpointActive() || modals.isLogViewerActive() || modals.isHistoryActive() || modals.isHistoryLogViewerActive() || showStopModal() || isErrorModalActive(),
     isPromptBoxFocused: () => isPromptBoxFocused(),
     isWaitingForInput,
     hasQueuedPrompts,
@@ -360,6 +375,12 @@ export function WorkflowShell(props: WorkflowShellProps) {
           <StopModal onConfirm={handleStopConfirm} onCancel={handleStopCancel} />
         </box>
       </Show>
+
+      <Show when={isErrorModalActive()}>
+        <box position="absolute" left={0} top={0} width="100%" height="100%" zIndex={2000}>
+          <ErrorModal message={errorMessage()!} onClose={handleErrorModalClose} />
+        </box>
+      </Show>
     </box>
   )
 }

src/cli/tui/shared/context/toast.tsx

@@ -33,9 +33,12 @@ export const { use: useToast, provider: ToastProvider } = createSimpleContext({
         setStore("current", rest)
 
         if (timeoutHandle) clearTimeout(timeoutHandle)
-        timeoutHandle = setTimeout(() => {
-          setStore("current", null)
-        }, duration)
+        // Only set timeout if duration > 0 (duration 0 means permanent toast)
+        if (duration > 0) {
+          timeoutHandle = setTimeout(() => {
+            setStore("current", null)
+          }, duration)
+        }
       },
       dismiss() {
         if (timeoutHandle) clearTimeout(timeoutHandle)

src/shared/utils/errors.ts

@@ -0,0 +1,9 @@
+/**
+ * Global error toast utility
+ *
+ * Usage: emitAppError("Something went wrong")
+ * Usage: emitAppError("Error message", 5000) // auto-dismiss after 5 seconds
+ */
+export function emitAppError(message: string, duration?: number): void {
+  ;(process as NodeJS.EventEmitter).emit('app:error', { message, duration })
+}

src/shared/utils/index.ts

@@ -1,2 +1,3 @@
 export * from './path.js';
 export * from './terminal.js';
+export * from './errors.js';

src/workflows/behaviors/error/controller.ts

@@ -0,0 +1,44 @@
+import type { WorkflowStep } from '../../templates/index.js';
+import { isModuleStep } from '../../templates/types.js';
+import { evaluateErrorBehavior } from './evaluator.js';
+import { formatAgentLog } from '../../../shared/logging/index.js';
+import type { WorkflowEventEmitter } from '../../events/emitter.js';
+
+export interface ErrorDecision {
+  shouldStopWorkflow: boolean;
+  reason?: string;
+}
+
+export async function handleErrorLogic(
+  step: WorkflowStep,
+  output: string,
+  cwd: string,
+  emitter?: WorkflowEventEmitter,
+): Promise<ErrorDecision | null> {
+  // Only module steps can have error behavior
+  if (!isModuleStep(step)) {
+    return null;
+  }
+
+  const errorDecision = await evaluateErrorBehavior({
+    output,
+    cwd,
+  });
+
+  if (errorDecision?.shouldStopWorkflow) {
+    const message = `${step.agentName} reported an error` +
+      `${errorDecision.reason ? `: ${errorDecision.reason}` : ''}.`;
+
+    emitter?.logMessage(step.agentId, message);
+    if (!emitter) {
+      console.log(formatAgentLog(step.agentId, message));
+    }
+
+    return {
+      shouldStopWorkflow: true,
+      reason: errorDecision.reason,
+    };
+  }
+
+  return null;
+}