fix: handle concurrent file edits and symlink loops in watcher/builder

Add readFileSafe helper that retries on transient OS errors
(EBUSY/EACCES/EPERM) from editors performing non-atomic saves.
Replace bare readFileSync calls in builder.js (3 sites) and
watcher.js (1 site).

Add symlink loop detection to collectFiles via realpathSync tracking
of visited directories, preventing infinite recursion from circular
symlinks.

Update architecture.md sections #7, #15, and summary table to
reflect these fixes.

Impact: 5 functions changed, 5 affected

Author: github-actions[bot]

generated/architecture.md

@@ -228,7 +228,7 @@ Consumers receive an engine object and call methods on it. They never branch on
 
 **Current state:** The entire build pipeline is synchronous batch processing. Parse all files → insert all nodes → build all edges. The watcher does per-file updates but reimplements the pipeline in a simpler form.
 
-**Problem:** For large repos (10K+ files), the user waits for the entire pipeline to complete before seeing anything. There's no progress reporting during parsing. There's no way to cancel a build mid-flight. The watcher's simplified pipeline diverges from the main build path (different code, different edge cases).
+**Problem:** For large repos (10K+ files), the user waits for the entire pipeline to complete before seeing anything. There's no progress reporting during parsing. There's no way to cancel a build mid-flight. The watcher's simplified pipeline diverges from the main build path (different code, different edge cases). *(Note: two concrete edge cases — concurrent file edits causing EBUSY/EACCES during read, and symlink loops causing infinite recursion in `collectFiles` — have been fixed. `readFileSafe` retries on transient OS errors and is shared between `builder.js` and `watcher.js`. `collectFiles` tracks visited real paths to break symlink cycles.)*
 
 **Ideal architecture — event-driven pipeline:**
 
@@ -473,6 +473,8 @@ This is a simple LRU or TTL cache that sits between the analysis layer and the r
 
 **Problem:** Bug fixes to edge building in `builder.js` must be separately applied to `watcher.js`. The watcher's edge building is simpler (no barrel resolution, simpler confidence) which means watch-mode graphs are subtly different from full-build graphs.
 
+**Partial progress:** `readFileSafe` (exported from `builder.js`, imported by `watcher.js`) is the first shared utility between the two modules. It retries on transient OS errors (EBUSY/EACCES/EPERM) that occur when editors perform non-atomic saves, replacing bare `readFileSync` calls in both code paths. This is a small step toward the shared-stages goal.
+
 **Ideal fix:** The pipeline architecture from point #4 eliminates this entirely. Watch mode uses the same pipeline stages, just triggered per-file instead of per-project. The `insertNodes` and `buildEdges` stages are literally the same functions.
 
 ---
@@ -583,7 +585,7 @@ Consumers can only import from the documented entry points. Internal modules are
 | 9 | Transitive import-aware confidence | Low-Medium | Accuracy |
 | 14 | Query result caching | Low | Performance |
 | 8 | Config profiles for monorepos | Low | Feature |
-| 15 | Unify watcher/builder code paths | Low | Falls out of #4 |
+| 15 | Unify watcher/builder code paths | Low | Falls out of #4 (partial: `readFileSafe` shared) |
 
 Items 1–4 and 6 are foundational — they restructure the core and everything else becomes easier after them. Items 13 and 7 are the most impactful feature-level changes. Items 14–15 are natural consequences of earlier changes.
 

src/builder.js

@@ -43,8 +43,28 @@ const BUILTIN_RECEIVERS = new Set([
   'require',
 ]);
 
-export function collectFiles(dir, files = [], config = {}, directories = null) {
+export function collectFiles(
+  dir,
+  files = [],
+  config = {},
+  directories = null,
+  _visited = new Set(),
+) {
   const trackDirs = directories !== null;
+
+  // Resolve real path to detect symlink loops
+  let realDir;
+  try {
+    realDir = fs.realpathSync(dir);
+  } catch {
+    return trackDirs ? { files, directories } : files;
+  }
+  if (_visited.has(realDir)) {
+    warn(`Symlink loop detected, skipping: ${dir}`);
+    return trackDirs ? { files, directories } : files;
+  }
+  _visited.add(realDir);
+
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -67,7 +87,7 @@ export function collectFiles(dir, files = [], config = {}, directories = null) {
 
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      collectFiles(full, files, config, directories);
+      collectFiles(full, files, config, directories, _visited);
     } else if (EXTENSIONS.has(path.extname(entry.name))) {
       files.push(full);
       hasFiles = true;
@@ -125,6 +145,27 @@ function fileStat(filePath) {
   }
 }
 
+/**
+ * Read a file with retry on transient errors (EBUSY/EACCES/EPERM).
+ * Editors performing non-atomic saves can cause these during mid-write.
+ */
+const TRANSIENT_CODES = new Set(['EBUSY', 'EACCES', 'EPERM']);
+const RETRY_DELAY_MS = 50;
+
+export function readFileSafe(filePath, retries = 2) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return fs.readFileSync(filePath, 'utf-8');
+    } catch (err) {
+      if (attempt < retries && TRANSIENT_CODES.has(err.code)) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, RETRY_DELAY_MS);
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
 /**
  * Determine which files have changed since last build.
  * Three-tier cascade:
@@ -193,7 +234,7 @@ function getChangedFiles(db, allFiles, rootDir) {
 
         let content;
         try {
-          content = fs.readFileSync(absPath, 'utf-8');
+          content = readFileSafe(absPath);
         } catch {
           continue;
         }
@@ -256,7 +297,7 @@ function getChangedFiles(db, allFiles, rootDir) {
   for (const item of needsHash) {
     let content;
     try {
-      content = fs.readFileSync(item.file, 'utf-8');
+      content = readFileSafe(item.file);
     } catch {
       continue;
     }
@@ -459,7 +500,7 @@ export async function buildGraph(rootDir, opts = {}) {
           const absPath = path.join(rootDir, relPath);
           let code;
           try {
-            code = fs.readFileSync(absPath, 'utf-8');
+            code = readFileSafe(absPath);
           } catch {
             code = null;
           }

src/watcher.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { readFileSafe } from './builder.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
 import { initSchema, openDb } from './db.js';
 import { appendJournalEntries } from './journal.js';
@@ -35,7 +36,7 @@ async function updateFile(_db, rootDir, filePath, stmts, engineOpts, cache) {
 
   let code;
   try {
-    code = fs.readFileSync(filePath, 'utf-8');
+    code = readFileSafe(filePath);
   } catch (err) {
     warn(`Cannot read ${relPath}: ${err.message}`);
     return null;