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,14 @@ export const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Termi
         }
         pendingWorktreeConfigRef.current = null;
       }
+      // Auto-resume: enqueue non-active terminals for staggered resume
+      if (!isActive && !hasAttemptedAutoResumeRef.current) {
+        const currentTerminal = useTerminalStore.getState().terminals.find(t => t.id === id);
+        if (currentTerminal?.pendingClaudeResume) {
+          hasAttemptedAutoResumeRef.current = true;
+          enqueueAutoResume(id);
+        }
+      }
     },
     onError: (error) => {
       // Clear pending config on error to prevent stale config from being applied
@@ -573,6 +581,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 +640,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,80 @@ 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;
+
+let autoResumeQueue: string[] = [];
+let autoResumeTimer: ReturnType<typeof setTimeout> | null = null;
+let autoResumeProcessing = false;
+
+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;
+  }
+  autoResumeProcessing = false;
+  debugLog('[AutoResume] Queue cleared');
+}
+
+async function processAutoResumeQueue(): Promise<void> {
+  if (autoResumeProcessing) return;
+  autoResumeProcessing = true;
+  debugLog(`[AutoResume] Processing queue, ${autoResumeQueue.length} terminals`);
+
+  while (autoResumeQueue.length > 0) {
+    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}`);
+    useTerminalStore.getState().setPendingClaudeResume(terminalId, false);
+    window.electronAPI.activateDeferredClaudeResume(terminalId);
+
+    // Stagger delay between resumes
+    if (autoResumeQueue.length > 0) {
+      await new Promise(resolve => setTimeout(resolve, AUTO_RESUME_STAGGER_MS));
+    }
+  }
+
+  autoResumeProcessing = false;
+  debugLog('[AutoResume] Queue processing complete');
+}
+
 export type TerminalStatus = 'idle' | 'running' | 'claude-active' | 'exited';
 
 export interface Terminal {
@@ -507,6 +581,7 @@ export async function restoreTerminalSessions(projectPath: string): Promise<void
     return;
   }
   restoringProjects.add(projectPath);
+  clearAutoResumeQueue();
 
   try {
     const store = useTerminalStore.getState();