fix(terminal): improve stream closure handling and memory leak prevention (#331)

- Add dispose() method to OutputStreamProcessor to properly release callbacks
- Add isDisposed() check to prevent using disposed processor
- Enhance stream closure handling with multi-level checks
- Track terminal disposal state to prevent writes after cleanup
- Add try-catch around buffer access during deferred processing
- Fix memory leak by clearing ackCallback and pendingCallback on dispose

These changes address:
1. Memory leaks from closure references in output processor
2. Crashes when writing to disposed terminal
3. Race conditions during terminal cleanup
4. Buffer access errors during disposal

Co-authored-by: Droid Agent <droid@factory.ai>

Author: echobt

cortex-gui/src/components/TerminalPanel.tsx

@@ -358,6 +358,24 @@ class OutputStreamProcessor {
     this.pendingCallback = null;
     this.pendingAckBytes = 0;
   }
+
+  /**
+   * Dispose and release all resources to prevent memory leaks
+   * Should be called when the terminal is being destroyed
+   */
+  dispose(): void {
+    this.cancel();
+    // Clear callbacks to prevent memory leaks from closures holding references
+    this.ackCallback = null;
+    this.pendingCallback = null;
+  }
+
+  /**
+   * Check if the processor has been disposed
+   */
+  isDisposed(): boolean {
+    return this.ackCallback === null && this.pendingCallback === null && this.bufferChunks.length === 0;
+  }
 }
 
 /**
@@ -1708,18 +1726,55 @@ export function TerminalPanel() {
       resizeTerminal(terminalInfo.id, cols, rows).catch(console.error);
     });
 
-    // Subscribe to terminal output with chunked processing
+    // Track if this terminal instance has been disposed to prevent writes after cleanup
+    let isTerminalDisposed = false;
+    
+    // Subscribe to terminal output with robust stream closure handling
     const unsubscribe = subscribeToOutput((output) => {
+      // Early exit if terminal has been disposed
+      if (isTerminalDisposed) {
+        return;
+      }
+      
       if (output.terminal_id === terminalInfo.id) {
         // Write output directly to terminal - no chunking for real-time TUI responsiveness
         // Guard against writing to a disposed terminal to prevent crashes
         try {
-          // Check if terminal is still usable before writing
-          if (terminal.element && !terminal.element.classList.contains('disposed')) {
-            terminal.write(output.data);
+          // Multi-level check for terminal availability:
+          // 1. Check our local disposed flag (fastest)
+          // 2. Check if terminal element exists
+          // 3. Check if terminal is marked as disposed via class
+          // 4. Check if the terminal is in the instances map (hasn't been cleaned up)
+          if (isTerminalDisposed) {
+            return;
           }
+          
+          if (!terminal.element) {
+            console.debug(`[Terminal] Terminal ${terminalInfo.id} element is null, marking as disposed`);
+            isTerminalDisposed = true;
+            return;
+          }
+          
+          if (terminal.element.classList.contains('disposed')) {
+            console.debug(`[Terminal] Terminal ${terminalInfo.id} is disposed, skipping output`);
+            isTerminalDisposed = true;
+            return;
+          }
+          
+          // Check if terminal instance still exists in our map
+          const instance = terminalInstances.get(terminalInfo.id);
+          if (!instance) {
+            console.debug(`[Terminal] Terminal ${terminalInfo.id} instance not found, marking as disposed`);
+            isTerminalDisposed = true;
+            return;
+          }
+          
+          // Safe to write
+          terminal.write(output.data);
         } catch (e) {
           // Terminal may be disposed or in an invalid state - this is expected during cleanup
+          // Mark as disposed to prevent further write attempts
+          isTerminalDisposed = true;
           console.debug(`[Terminal] Stream write failed for ${terminalInfo.id}, terminal may be closing:`, e);
           return; // Skip further processing for this output
         }
@@ -1728,6 +1783,11 @@ export function TerminalPanel() {
         // Use requestIdleCallback for lower priority tasks
         if (quickFixEnabled() || stickyScrollSettings.enabled) {
           requestAnimationFrame(() => {
+            // Double-check terminal is still valid before deferred processing
+            if (isTerminalDisposed || !terminalInstances.has(terminalInfo.id)) {
+              return;
+            }
+            
             if (quickFixEnabled()) {
               setTerminalOutputs(terminalInfo.id, (prev) => {
                 const newOutput = (prev || "") + output.data;
@@ -1739,16 +1799,22 @@ export function TerminalPanel() {
             }
 
             if (stickyScrollSettings.enabled) {
-              const lines = output.data.split(/\r?\n/);
-              const baseLineNumber = terminal.buffer.active.baseY + terminal.buffer.active.cursorY;
-              lines.forEach((line, index) => {
-                if (line.trim()) {
-                  processStickyScrollLine(terminalInfo.id, baseLineNumber + index, line);
-                }
-              });
-              const scrollLine = terminal.buffer.active.viewportY;
-              const totalLines = terminal.buffer.active.length;
-              updateTerminalScrollPosition(terminalInfo.id, scrollLine, totalLines);
+              // Safely access terminal buffer - may throw if disposed
+              try {
+                const lines = output.data.split(/\r?\n/);
+                const baseLineNumber = terminal.buffer.active.baseY + terminal.buffer.active.cursorY;
+                lines.forEach((line, index) => {
+                  if (line.trim()) {
+                    processStickyScrollLine(terminalInfo.id, baseLineNumber + index, line);
+                  }
+                });
+                const scrollLine = terminal.buffer.active.viewportY;
+                const totalLines = terminal.buffer.active.length;
+                updateTerminalScrollPosition(terminalInfo.id, scrollLine, totalLines);
+              } catch (bufferError) {
+                // Terminal buffer may be invalid during disposal
+                console.debug(`[Terminal] Buffer access failed for ${terminalInfo.id}:`, bufferError);
+              }
             }
           });
         }
@@ -1897,9 +1963,10 @@ export function TerminalPanel() {
     }
 
     // Clean up output processor (cancel pending flush timeouts)
+    // Properly dispose the output processor to prevent memory leaks
     const processor = outputProcessors.get(terminalId);
     if (processor) {
-      processor.cancel();
+      processor.dispose();
       outputProcessors.delete(terminalId);
     }
 
@@ -2451,9 +2518,9 @@ export function TerminalPanel() {
       });
       terminalInstances.clear();
 
-      // Clean up output processors (cancel pending flush timeouts)
+      // Clean up output processors (dispose to prevent memory leaks)
       outputProcessors.forEach((processor) => {
-        processor.cancel();
+        processor.dispose();
       });
       outputProcessors.clear();