feat(terminal): centralized auto-resume queue for terminal recovery

apps/frontend/src/renderer/components/Terminal.tsx

@@ -3,7 +3,7 @@ import { useDroppable, useDndContext } from '@dnd-kit/core';
 import '@xterm/xterm/css/xterm.css';
 import { FileDown } from 'lucide-react';
 import { cn } from '../lib/utils';
-import { useTerminalStore } from '../stores/terminal-store';
+import { useTerminalStore, enqueueAutoResume, dequeueAutoResume } from '../stores/terminal-store';
 import { useSettingsStore } from '../stores/settings-store';
 import { useToast } from '../hooks/use-toast';
 import type { TerminalProps } from './terminal/types';
@@ -381,6 +381,17 @@ export const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Termi
         }
         pendingWorktreeConfigRef.current = null;
       }
+      // Auto-resume: enqueue non-active terminals for staggered resume
+      // Read current active state from store to avoid stale closure value
+      const currentActiveId = useTerminalStore.getState().activeTerminalId;
+      const isCurrentlyActive = currentActiveId === id;
+
+      if (!isCurrentlyActive) {
+        const currentTerminal = useTerminalStore.getState().terminals.find(t => t.id === id);
+        if (currentTerminal?.pendingClaudeResume) {
+          enqueueAutoResume(id);
+        }
+      }
     },
     onError: (error) => {
       // Clear pending config on error to prevent stale config from being applied
@@ -573,6 +584,8 @@ export const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Termi
 
     // Check if both conditions are met for auto-resume
     if (isActive && terminal?.pendingClaudeResume) {
+      // Remove from queue since active terminal handles its own resume
+      dequeueAutoResume(id);
       // Defer the resume slightly to ensure all React state updates have propagated
       // This fixes the race condition where isActive and pendingClaudeResume might update
       // at different times during the restoration flow
@@ -630,6 +643,7 @@ export const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Termi
 
     return () => {
       isMountedRef.current = false;
+      dequeueAutoResume(id);
       cleanupAutoNaming();
 
       // Clear post-creation dimension check timeout to prevent operations on unmounted component

apps/frontend/src/renderer/stores/terminal-store.ts

@@ -76,6 +76,110 @@ export function writeToTerminal(terminalId: string, data: string): void {
   }
 }
 
+// === Auto-Resume Queue Coordinator ===
+// Coordinates staggered auto-resume of non-active terminals after app restart.
+// Each terminal enqueues itself when its PTY is confirmed ready (onCreated).
+// A single coordinator processes the queue with stagger delays.
+
+const AUTO_RESUME_INITIAL_DELAY_MS = 1500;
+const AUTO_RESUME_STAGGER_MS = 500;
+
+// Auto-resume queue state (single-threaded JS assumption - see processAutoResumeQueue)
+let autoResumeQueue: string[] = [];
+let autoResumeTimer: ReturnType<typeof setTimeout> | null = null;
+let autoResumeProcessing = false;
+let autoResumeGeneration = 0; // Generation counter to abort stale processing runs
+let isResumingAll = false; // Concurrency guard for resumeAllPendingClaude
+
+export function enqueueAutoResume(terminalId: string): void {
+  if (autoResumeQueue.includes(terminalId)) return;
+  autoResumeQueue.push(terminalId);
+  debugLog(`[AutoResume] Enqueued terminal: ${terminalId}, queue size: ${autoResumeQueue.length}`);
+
+  // Start initial delay timer on first enqueue only
+  if (autoResumeTimer === null && !autoResumeProcessing) {
+    debugLog(`[AutoResume] Starting initial delay (${AUTO_RESUME_INITIAL_DELAY_MS}ms)`);
+    autoResumeTimer = setTimeout(() => {
+      autoResumeTimer = null;
+      processAutoResumeQueue();
+    }, AUTO_RESUME_INITIAL_DELAY_MS);
+  }
+}
+
+export function dequeueAutoResume(terminalId: string): void {
+  const idx = autoResumeQueue.indexOf(terminalId);
+  if (idx !== -1) {
+    autoResumeQueue.splice(idx, 1);
+    debugLog(`[AutoResume] Dequeued terminal: ${terminalId}, queue size: ${autoResumeQueue.length}`);
+  }
+}
+
+export function clearAutoResumeQueue(): void {
+  autoResumeQueue = [];
+  if (autoResumeTimer !== null) {
+    clearTimeout(autoResumeTimer);
+    autoResumeTimer = null;
+  }
+  // Don't reset autoResumeProcessing here - the generation counter is sufficient
+  // to abort stale processing runs. Resetting the flag here creates a race condition
+  // where clearAutoResumeQueue() could allow a new processAutoResumeQueue() to start
+  // before the aborted one has fully exited.
+  autoResumeGeneration++; // Increment generation to abort any in-flight processing
+  debugLog('[AutoResume] Queue cleared');
+}
+
+/**
+ * Shared helper to resume a terminal's Claude session with consistent behavior.
+ * Clears the pending flag and triggers IPC activation.
+ */
+function resumeTerminalClaudeSession(terminalId: string): void {
+  useTerminalStore.getState().setPendingClaudeResume(terminalId, false);
+  window.electronAPI.activateDeferredClaudeResume(terminalId);
+}
+
+async function processAutoResumeQueue(): Promise<void> {
+  if (autoResumeProcessing) return;
+  autoResumeProcessing = true;
+  const generation = autoResumeGeneration; // Capture generation to detect cancellation
+  debugLog(`[AutoResume] Processing queue (generation ${generation}), ${autoResumeQueue.length} terminals`);
+
+  while (autoResumeQueue.length > 0) {
+    // Check if this processing run has been cancelled
+    if (generation !== autoResumeGeneration) {
+      debugLog(`[AutoResume] Generation mismatch (${generation} !== ${autoResumeGeneration}) — aborting stale processing`);
+      return; // Don't reset autoResumeProcessing — the new run owns it
+    }
+
+    const terminalId = autoResumeQueue.shift()!;
+
+    // Check if terminal still needs resume
+    const terminal = useTerminalStore.getState().terminals.find(t => t.id === terminalId);
+    if (!terminal?.pendingClaudeResume) {
+      debugLog(`[AutoResume] Skipping ${terminalId} — no longer pending`);
+      continue;
+    }
+
+    debugLog(`[AutoResume] Resuming terminal: ${terminalId}`);
+    resumeTerminalClaudeSession(terminalId);
+
+    // Stagger delay between resumes
+    if (autoResumeQueue.length > 0) {
+      await new Promise(resolve => setTimeout(resolve, AUTO_RESUME_STAGGER_MS));
+      // Re-check generation after await (may have been cancelled during stagger delay)
+      if (generation !== autoResumeGeneration) {
+        debugLog(`[AutoResume] Generation mismatch after stagger — aborting stale processing`);
+        return;
+      }
+    }
+  }
+
+  // Only reset processing flag if this is still the current generation
+  if (generation === autoResumeGeneration) {
+    autoResumeProcessing = false;
+  }
+  debugLog('[AutoResume] Queue processing complete');
+}
+
 export type TerminalStatus = 'idle' | 'running' | 'claude-active' | 'exited';
 
 export interface Terminal {
@@ -434,35 +538,51 @@ export const useTerminalStore = create<TerminalState>((set, get) => ({
   },
 
   resumeAllPendingClaude: async () => {
-    const state = get();
-
-    // Filter terminals with pending Claude resume
-    const pendingTerminals = state.terminals.filter(t => t.pendingClaudeResume === true);
-
-    if (pendingTerminals.length === 0) {
-      debugLog('[TerminalStore] No terminals with pending Claude resume');
+    // Concurrency guard - prevent multiple simultaneous executions
+    if (isResumingAll) {
+      debugLog('[TerminalStore] Resume All already in progress — skipping');
       return;
     }
+    isResumingAll = true;
 
-    debugLog(`[TerminalStore] Resuming ${pendingTerminals.length} pending Claude sessions with 500ms stagger`);
+    try {
+      // Clear auto-resume queue to prevent redundant processing
+      clearAutoResumeQueue();
 
-    // Iterate through terminals with staggered delays
-    for (let i = 0; i < pendingTerminals.length; i++) {
-      const terminal = pendingTerminals[i];
-      // Clear the pending flag BEFORE IPC call to prevent race condition
-      // with auto-resume effect in Terminal.tsx (which checks this flag on a 100ms timeout)
-      get().setPendingClaudeResume(terminal.id, false);
+      const state = get();
 
-      debugLog(`[TerminalStore] Activating deferred Claude resume for terminal: ${terminal.id}`);
-      window.electronAPI.activateDeferredClaudeResume(terminal.id);
+      // Filter terminals with pending Claude resume
+      const pendingTerminals = state.terminals.filter(t => t.pendingClaudeResume === true);
 
-      // Wait 500ms before processing next terminal (staggered delay)
-      if (i < pendingTerminals.length - 1) {
-        await new Promise(resolve => setTimeout(resolve, 500));
+      if (pendingTerminals.length === 0) {
+        debugLog('[TerminalStore] No terminals with pending Claude resume');
+        return;
       }
-    }
 
-    debugLog('[TerminalStore] Completed resuming all pending Claude sessions');
+      debugLog(`[TerminalStore] Resuming ${pendingTerminals.length} pending Claude sessions with ${AUTO_RESUME_STAGGER_MS}ms stagger`);
+
+      // Iterate through terminals with staggered delays
+      for (let i = 0; i < pendingTerminals.length; i++) {
+        const terminal = pendingTerminals[i];
+
+        try {
+          debugLog(`[TerminalStore] Activating deferred Claude resume for terminal: ${terminal.id}`);
+          resumeTerminalClaudeSession(terminal.id);
+        } catch (error) {
+          // Log error and continue processing remaining terminals
+          debugError(`[TerminalStore] Error resuming terminal ${terminal.id}:`, error);
+        }
+
+        // Wait before processing next terminal (staggered delay)
+        if (i < pendingTerminals.length - 1) {
+          await new Promise(resolve => setTimeout(resolve, AUTO_RESUME_STAGGER_MS));
+        }
+      }
+
+      debugLog('[TerminalStore] Completed resuming all pending Claude sessions');
+    } finally {
+      isResumingAll = false;
+    }
   },
 
   getTerminal: (id: string) => {
@@ -507,6 +627,7 @@ export async function restoreTerminalSessions(projectPath: string): Promise<void
     return;
   }
   restoringProjects.add(projectPath);
+  clearAutoResumeQueue();
 
   try {
     const store = useTerminalStore.getState();
@@ -579,3 +700,7 @@ export async function restoreTerminalSessions(projectPath: string): Promise<void
     restoringProjects.delete(projectPath);
   }
 }
+
+// NOTE: HMR cleanup for auto-resume queue state would be beneficial during development
+// to clear timers on hot reload, but requires augmenting ImportMeta types in vite-env.d.ts.
+// The generation counter provides sufficient protection against stale processing runs.