fix: prevent dependency graph from going blank during agent activity

- Memoize onNodeClick callback in App.tsx to prevent unnecessary re-renders
- Add useRef pattern in DependencyGraph to store callback without triggering
  useMemo recalculation when callback identity changes
- Add hash-based change detection to only update ReactFlow state when
  actual graph data changes (node status, edges), not on every parent render
- Add GraphErrorBoundary class component to catch ReactFlow rendering errors
  and provide a "Reload Graph" recovery button instead of blank screen
- Wrap DependencyGraph with error boundary and resetKey for graceful recovery

The root cause was frequent WebSocket updates during active agent sessions
causing parent re-renders, which created new inline callback functions,
triggering useMemo/useEffect chains that corrupted ReactFlow's internal state
over time (approximately 1 minute of continuous updates).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ui/src/App.tsx

@@ -125,6 +125,17 @@ function App() {
     }
   }, [])
 
+  // Handle graph node click - memoized to prevent DependencyGraph re-renders
+  const handleGraphNodeClick = useCallback((nodeId: number) => {
+    const allFeatures = [
+      ...(features?.pending ?? []),
+      ...(features?.in_progress ?? []),
+      ...(features?.done ?? [])
+    ]
+    const feature = allFeatures.find(f => f.id === nodeId)
+    if (feature) setSelectedFeature(feature)
+  }, [features])
+
   // Validate stored project exists (clear if project was deleted)
   useEffect(() => {
     if (selectedProject && projects && !projects.some(p => p.name === selectedProject)) {
@@ -386,16 +397,7 @@ function App() {
                 {graphData ? (
                   <DependencyGraph
                     graphData={graphData}
-                    onNodeClick={(nodeId) => {
+                    onNodeClick={handleGraphNodeClick}
-                      // Find the feature and open the modal
-                      const allFeatures = [
-                        ...(features?.pending ?? []),
-                        ...(features?.in_progress ?? []),
-                        ...(features?.done ?? [])
-                      ]
-                      const feature = allFeatures.find(f => f.id === nodeId)
-                      if (feature) setSelectedFeature(feature)
-                    }}
                   />
                 ) : (
                   <div className="h-full flex items-center justify-center">

ui/src/components/DependencyGraph.tsx

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useMemo, useState } from 'react'
+import { Component, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { ErrorInfo, ReactNode } from 'react'
 import {
   ReactFlow,
   Background,
@@ -14,7 +15,7 @@ import {
   Handle,
 } from '@xyflow/react'
 import dagre from 'dagre'
-import { CheckCircle2, Circle, Loader2, AlertTriangle } from 'lucide-react'
+import { CheckCircle2, Circle, Loader2, AlertTriangle, RefreshCw } from 'lucide-react'
 import type { DependencyGraph as DependencyGraphData, GraphNode } from '../lib/types'
 import '@xyflow/react/dist/style.css'
 
@@ -27,6 +28,62 @@ interface DependencyGraphProps {
   onNodeClick?: (nodeId: number) => void
 }
 
+// Error boundary to catch and recover from ReactFlow rendering errors
+interface ErrorBoundaryProps {
+  children: ReactNode
+  onReset?: () => void
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean
+  error: Error | null
+}
+
+class GraphErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props)
+    this.state = { hasError: false, error: null }
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error }
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('DependencyGraph error:', error, errorInfo)
+  }
+
+  handleReset = () => {
+    this.setState({ hasError: false, error: null })
+    this.props.onReset?.()
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div className="h-full w-full flex items-center justify-center bg-neo-neutral-100">
+          <div className="text-center p-6">
+            <AlertTriangle size={48} className="mx-auto mb-4 text-neo-warning" />
+            <div className="text-neo-text font-bold mb-2">Graph rendering error</div>
+            <div className="text-sm text-neo-text-secondary mb-4">
+              The dependency graph encountered an issue.
+            </div>
+            <button
+              onClick={this.handleReset}
+              className="inline-flex items-center gap-2 px-4 py-2 bg-neo-accent text-white rounded border-2 border-neo-border shadow-neo-sm hover:shadow-neo-md transition-all"
+            >
+              <RefreshCw size={16} />
+              Reload Graph
+            </button>
+          </div>
+        </div>
+      )
+    }
+
+    return this.props.children
+  }
+}
+
 // Custom node component
 function FeatureNode({ data }: { data: GraphNode & { onClick?: () => void } }) {
   const statusColors = {
@@ -127,10 +184,22 @@ function getLayoutedElements(
   return { nodes: layoutedNodes, edges }
 }
 
-export function DependencyGraph({ graphData, onNodeClick }: DependencyGraphProps) {
+function DependencyGraphInner({ graphData, onNodeClick }: DependencyGraphProps) {
   const [direction, setDirection] = useState<'TB' | 'LR'>('LR')
 
+  // Use ref for callback to avoid triggering re-renders when callback identity changes
+  const onNodeClickRef = useRef(onNodeClick)
+  useEffect(() => {
+    onNodeClickRef.current = onNodeClick
+  }, [onNodeClick])
+
+  // Create a stable click handler that uses the ref
+  const handleNodeClick = useCallback((nodeId: number) => {
+    onNodeClickRef.current?.(nodeId)
+  }, [])
+
   // Convert graph data to React Flow format
+  // Only recalculate when graphData or direction changes (not when onNodeClick changes)
   const initialElements = useMemo(() => {
     const nodes: Node[] = graphData.nodes.map((node) => ({
       id: String(node.id),
@@ -138,7 +207,7 @@ export function DependencyGraph({ graphData, onNodeClick }: DependencyGraphProps
       position: { x: 0, y: 0 },
       data: {
         ...node,
-        onClick: () => onNodeClick?.(node.id),
+        onClick: () => handleNodeClick(node.id),
       },
     }))
 
@@ -156,20 +225,36 @@ export function DependencyGraph({ graphData, onNodeClick }: DependencyGraphProps
     }))
 
     return getLayoutedElements(nodes, edges, direction)
-  }, [graphData, direction, onNodeClick])
+  }, [graphData, direction, handleNodeClick])
 
   const [nodes, setNodes, onNodesChange] = useNodesState(initialElements.nodes)
   const [edges, setEdges, onEdgesChange] = useEdgesState(initialElements.edges)
 
-  // Update layout when data or direction changes
+  // Update layout when initialElements changes
+  // Using a ref to track previous graph data to avoid unnecessary updates
+  const prevGraphDataRef = useRef<string>('')
+  const prevDirectionRef = useRef<'TB' | 'LR'>(direction)
+
   useEffect(() => {
-    const { nodes: layoutedNodes, edges: layoutedEdges } = getLayoutedElements(
+    // Create a simple hash of the graph data to detect actual changes
-      initialElements.nodes,
+    const graphHash = JSON.stringify({
-      initialElements.edges,
+      nodes: graphData.nodes.map(n => ({ id: n.id, status: n.status })),
-      direction
+      edges: graphData.edges,
-    )
+    })
-    setNodes(layoutedNodes)
+
-    setEdges(layoutedEdges)
+    // Only update if graph data or direction actually changed
+    if (graphHash !== prevGraphDataRef.current || direction !== prevDirectionRef.current) {
+      prevGraphDataRef.current = graphHash
+      prevDirectionRef.current = direction
+
+      const { nodes: layoutedNodes, edges: layoutedEdges } = getLayoutedElements(
+        initialElements.nodes,
+        initialElements.edges,
+        direction
+      )
+      setNodes(layoutedNodes)
+      setEdges(layoutedEdges)
+    }
   }, [graphData, direction, setNodes, setEdges, initialElements])
 
   const onLayout = useCallback(
@@ -287,3 +372,20 @@ export function DependencyGraph({ graphData, onNodeClick }: DependencyGraphProps
     </div>
   )
 }
+
+// Wrapper component with error boundary for stability
+export function DependencyGraph({ graphData, onNodeClick }: DependencyGraphProps) {
+  // Use a key based on graph data length to force remount on structural changes
+  // This helps recover from corrupted ReactFlow state
+  const [resetKey, setResetKey] = useState(0)
+
+  const handleReset = useCallback(() => {
+    setResetKey(k => k + 1)
+  }, [])
+
+  return (
+    <GraphErrorBoundary key={resetKey} onReset={handleReset}>
+      <DependencyGraphInner graphData={graphData} onNodeClick={onNodeClick} />
+    </GraphErrorBoundary>
+  )
+}