fix: resolve project-switch freeze from sync file I/O and watcher storm

- Convert listFilesWalk and listAllFiles from sync to async with event loop yielding
- Replace per-directory fs.watch swarm with single recursive watcher per project
- Gate ProjectFilesPanel fetching/watching behind enabled prop to skip work when panel is hidden

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: OpenSource03

electron/src/ipc/files.ts

@@ -48,17 +48,22 @@ function isIgnoredByPatterns(name: string, patterns: string[]): boolean {
   return false;
 }
 
-function listFilesWalk(cwd: string, maxFiles = 10000): string[] {
+function yieldToEventLoop(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+async function listFilesWalk(cwd: string, maxFiles = 10000): Promise<string[]> {
   const files: string[] = [];
   const queue: string[] = [""];
+  let visitedDirs = 0;
 
   while (queue.length > 0 && files.length < maxFiles) {
     const rel = queue.shift()!;
     const abs = rel ? path.join(cwd, rel) : cwd;
 
     let entries: fs.Dirent[];
     try {
-      entries = fs.readdirSync(abs, { withFileTypes: true });
+      entries = await fs.promises.readdir(abs, { withFileTypes: true });
     } catch {
       continue;
     }
@@ -78,6 +83,11 @@ function listFilesWalk(cwd: string, maxFiles = 10000): string[] {
         files.push(entryRel);
       }
     }
+
+    visitedDirs += 1;
+    if (visitedDirs % 25 === 0) {
+      await yieldToEventLoop();
+    }
   }
 
   return files.sort();
@@ -88,119 +98,27 @@ async function listProjectFiles(cwd: string): Promise<string[]> {
     return await listFilesGit(cwd);
   } catch {
     log("FILES:LIST", "Not a git repo, falling back to filesystem walk");
-    return listFilesWalk(cwd);
+    return await listFilesWalk(cwd);
   }
 }
 
 /** Dirs to skip in the full filesystem walk (VCS internals + massive dependency dirs). */
 const EXPLORER_SKIP = new Set([".git", ".hg", ".svn", "node_modules"]);
 
+// ── Recursive file watcher ──
+// Uses a single fs.watch(cwd, { recursive: true }) per project root.
+// macOS (FSEvents) and Windows (ReadDirectoryChangesW) handle this natively
+// with one kernel-level watcher for the entire subtree — no directory walking,
+// no thousands of individual watchers, instant setup and teardown.
+
 interface ProjectWatchState {
   refCount: number;
-  watchers: Map<string, fs.FSWatcher>;
+  watcher: fs.FSWatcher;
   notifyTimer?: ReturnType<typeof setTimeout>;
-  syncTimer?: ReturnType<typeof setTimeout>;
 }
 
 const projectWatchers = new Map<string, ProjectWatchState>();
 
-function collectWatchDirs(cwd: string, maxDirs = 5000): string[] {
-  const dirs = [cwd];
-  const queue = [cwd];
-
-  while (queue.length > 0 && dirs.length < maxDirs) {
-    const dir = queue.shift()!;
-
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      if (!entry.isDirectory() || EXPLORER_SKIP.has(entry.name)) continue;
-      const childDir = path.join(dir, entry.name);
-      dirs.push(childDir);
-      queue.push(childDir);
-      if (dirs.length >= maxDirs) break;
-    }
-  }
-
-  return dirs;
-}
-
-function closeProjectWatchers(state: ProjectWatchState): void {
-  if (state.notifyTimer) clearTimeout(state.notifyTimer);
-  if (state.syncTimer) clearTimeout(state.syncTimer);
-  for (const watcher of state.watchers.values()) {
-    watcher.close();
-  }
-  state.watchers.clear();
-}
-
-function scheduleWatcherNotify(
-  cwd: string,
-  getMainWindow: () => BrowserWindow | null,
-): void {
-  const state = projectWatchers.get(cwd);
-  if (!state || state.notifyTimer) return;
-
-  state.notifyTimer = setTimeout(() => {
-    const current = projectWatchers.get(cwd);
-    if (!current) return;
-    current.notifyTimer = undefined;
-    safeSend(getMainWindow, "files:changed", { cwd });
-  }, 150);
-}
-
-function syncProjectWatchers(
-  cwd: string,
-  getMainWindow: () => BrowserWindow | null,
-): void {
-  const state = projectWatchers.get(cwd);
-  if (!state) return;
-
-  const nextDirs = new Set(collectWatchDirs(cwd));
-
-  for (const [dir, watcher] of state.watchers) {
-    if (nextDirs.has(dir)) continue;
-    watcher.close();
-    state.watchers.delete(dir);
-  }
-
-  for (const dir of nextDirs) {
-    if (state.watchers.has(dir)) continue;
-    try {
-      const watcher = fs.watch(dir, { persistent: false }, () => {
-        scheduleWatcherNotify(cwd, getMainWindow);
-        scheduleWatcherSync(cwd, getMainWindow);
-      });
-      watcher.on("error", () => {
-        scheduleWatcherSync(cwd, getMainWindow);
-      });
-      state.watchers.set(dir, watcher);
-    } catch {
-      // Ignore transient watch failures; the next sync will retry.
-    }
-  }
-}
-
-function scheduleWatcherSync(
-  cwd: string,
-  getMainWindow: () => BrowserWindow | null,
-): void {
-  const state = projectWatchers.get(cwd);
-  if (!state || state.syncTimer) return;
-
-  state.syncTimer = setTimeout(() => {
-    const current = projectWatchers.get(cwd);
-    if (!current) return;
-    current.syncTimer = undefined;
-    syncProjectWatchers(cwd, getMainWindow);
-  }, 250);
-}
-
 function startProjectWatcher(
   cwd: string,
   getMainWindow: () => BrowserWindow | null,
@@ -211,12 +129,31 @@ function startProjectWatcher(
     return;
   }
 
-  const state: ProjectWatchState = {
-    refCount: 1,
-    watchers: new Map(),
-  };
-  projectWatchers.set(cwd, state);
-  syncProjectWatchers(cwd, getMainWindow);
+  const watcher = fs.watch(cwd, { recursive: true, persistent: false }, (_eventType, filename) => {
+    // Ignore changes in directories we don't care about (node_modules, .git, etc.)
+    if (filename) {
+      const firstSegment = filename.split(path.sep)[0];
+      if (ALWAYS_SKIP.has(firstSegment) || firstSegment.startsWith(".")) return;
+    }
+
+    const state = projectWatchers.get(cwd);
+    if (!state || state.notifyTimer) return;
+
+    // Debounce: coalesce rapid changes into a single notification
+    state.notifyTimer = setTimeout(() => {
+      const current = projectWatchers.get(cwd);
+      if (!current) return;
+      current.notifyTimer = undefined;
+      safeSend(getMainWindow, "files:changed", { cwd });
+    }, 200);
+  });
+
+  watcher.on("error", () => {
+    // Watcher died (directory deleted, permissions, etc.) — clean up silently
+    stopProjectWatcher(cwd);
+  });
+
+  projectWatchers.set(cwd, { refCount: 1, watcher });
 }
 
 function stopProjectWatcher(cwd: string): void {
@@ -226,7 +163,8 @@ function stopProjectWatcher(cwd: string): void {
   state.refCount = Math.max(0, state.refCount - 1);
   if (state.refCount > 0) return;
 
-  closeProjectWatchers(state);
+  if (state.notifyTimer) clearTimeout(state.notifyTimer);
+  state.watcher.close();
   projectWatchers.delete(cwd);
 }
 
@@ -235,17 +173,18 @@ function stopProjectWatcher(cwd: string): void {
  * Only skips VCS internals and node_modules (too massive).
  * Used by the "Project Files" explorer panel.
  */
-function listAllFiles(cwd: string, maxFiles = 10000): string[] {
+async function listAllFiles(cwd: string, maxFiles = 10000): Promise<string[]> {
   const files: string[] = [];
   const queue: string[] = [""];
+  let visitedDirs = 0;
 
   while (queue.length > 0 && files.length < maxFiles) {
     const rel = queue.shift()!;
     const abs = rel ? path.join(cwd, rel) : cwd;
 
     let entries: fs.Dirent[];
     try {
-      entries = fs.readdirSync(abs, { withFileTypes: true });
+      entries = await fs.promises.readdir(abs, { withFileTypes: true });
     } catch {
       continue;
     }
@@ -260,6 +199,11 @@ function listAllFiles(cwd: string, maxFiles = 10000): string[] {
         files.push(entryRel);
       }
     }
+
+    visitedDirs += 1;
+    if (visitedDirs % 25 === 0) {
+      await yieldToEventLoop();
+    }
   }
 
   return files.sort();
@@ -348,7 +292,7 @@ export function register(getMainWindow: () => BrowserWindow | null): void {
 
   ipcMain.handle("files:list-all", async (_event, cwd: string) => {
     try {
-      const files = listAllFiles(cwd);
+      const files = await listAllFiles(cwd);
       const dirSet = new Set<string>();
       for (const file of files) {
         const parts = file.split("/");

package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnss",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "productName": "Harnss",
   "description": "Harness your AI coding agents — one desktop app for Claude Code, Codex, and any ACP agent",
   "author": {
@@ -31,7 +31,7 @@
   "packageManager": "pnpm@10.26.0",
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.15.0",
-    "@anthropic-ai/claude-agent-sdk": "^0.2.71",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.72",
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@monaco-editor/react": "^4.7.0",

pnpm-lock.yaml

@@ -694,6 +694,7 @@ Link: ${issue.url}`;
               "project-files": (
                 <ProjectFilesPanel
                   cwd={activeProjectPath}
+                  enabled={activeTools.has("project-files")}
                   onPreviewFile={handlePreviewFile}
                 />
               ),
@@ -843,6 +844,7 @@ Link: ${issue.url}`;
             "project-files": (
               <ProjectFilesPanel
                 cwd={activeProjectPath}
+                enabled={activeTools.has("project-files")}
                 onPreviewFile={handlePreviewFile}
               />
             ),

src/components/AppLayout.tsx

@@ -53,16 +53,18 @@ function getFileIconColor(extension?: string): string {
 
 interface ProjectFilesPanelProps {
   cwd?: string;
+  enabled: boolean;
   onPreviewFile?: (filePath: string, sourceRect: DOMRect) => void;
 }
 
 // ── Component ──
 
 export const ProjectFilesPanel = memo(function ProjectFilesPanel({
   cwd,
+  enabled,
   onPreviewFile,
 }: ProjectFilesPanelProps) {
-  const { tree, loading, error, refresh } = useProjectFiles(cwd);
+  const { tree, loading, error, refresh } = useProjectFiles(cwd, enabled);
 
   const [expandedDirs, setExpandedDirs] = useState<Set<string>>(() => new Set());
   const [searchQuery, setSearchQuery] = useState("");

src/components/ProjectFilesPanel.tsx

@@ -14,7 +14,10 @@ interface UseProjectFilesReturn {
  * Fetches the project file list via IPC and builds a nested tree.
  * Re-fetches when `cwd` changes. Returns loading/error states.
  */
-export function useProjectFiles(cwd: string | undefined): UseProjectFilesReturn {
+export function useProjectFiles(
+  cwd: string | undefined,
+  enabled: boolean,
+): UseProjectFilesReturn {
   const [tree, setTree] = useState<FileTreeNode[] | null>(null);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -46,15 +49,16 @@ export function useProjectFiles(cwd: string | undefined): UseProjectFilesReturn
   }, []);
 
   useEffect(() => {
-    if (!cwd) {
+    if (!cwd || !enabled) {
+      fetchIdRef.current += 1;
       setTree(null);
       setLoading(false);
       setError(null);
       return;
     }
 
     fetchFiles(cwd);
-  }, [cwd, fetchFiles]);
+  }, [cwd, enabled, fetchFiles]);
 
   const scheduleRefresh = useCallback((dir: string) => {
     clearTimeout(refreshTimerRef.current);
@@ -64,7 +68,7 @@ export function useProjectFiles(cwd: string | undefined): UseProjectFilesReturn
   }, [fetchFiles]);
 
   useEffect(() => {
-    if (!cwd) return;
+    if (!cwd || !enabled) return;
 
     void window.claude.files.watch(cwd);
     const unsubscribe = window.claude.files.onChanged(({ cwd: changedCwd }) => {
@@ -89,11 +93,11 @@ export function useProjectFiles(cwd: string | undefined): UseProjectFilesReturn
       clearTimeout(refreshTimerRef.current);
       void window.claude.files.unwatch(cwd);
     };
-  }, [cwd, scheduleRefresh]);
+  }, [cwd, enabled, scheduleRefresh]);
 
   const refresh = useCallback(() => {
-    if (cwd) fetchFiles(cwd);
-  }, [cwd, fetchFiles]);
+    if (cwd && enabled) fetchFiles(cwd);
+  }, [cwd, enabled, fetchFiles]);
 
   return { tree, loading, error, refresh };
 }