v6.1.0

changelog.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2025-12-08 - 6.1.0 - feat(watcher.node)
+Add automatic restart, periodic health checks, and safe event emission to Node watcher; improve logging and stat handling
+
+- NodeWatcher: introduced safeEmit() to isolate subscriber errors and prevent watcher crashes
+- Auto-restart on failure with exponential backoff (1s → 30s) and up to 3 retry attempts per watched base path
+- Periodic health checks (every 30s) to detect missing watched paths and trigger automatic restarts
+- Handle unexpected FSWatcher 'close' events and restart watchers when they close silently
+- Verbose lifecycle logging with `[smartwatch]` prefix for start/stop/health/restart events
+- Clear restart tracking and stop health checks on watcher.stop() to ensure clean shutdown
+- Improved statSafe() to normalize followSymlinks logic and log non-ENO errors as warnings
+- Updated readme.hints.md documenting the new robustness features (v6.1.0+)
+
+## 2025-12-08 - 6.0.0 - BREAKING CHANGE(watchers)
+Replace polling-based write stabilization with debounce-based event coalescing and simplify watcher options
+
+- Remove polling-based WriteStabilizer (ts/utils/write-stabilizer.ts) and related waitForWriteFinish logic
+- Introduce debounce-based coalescing (debounceMs) for Node and Deno watchers (ts/watchers/watcher.node.ts, ts/watchers/watcher.deno.ts)
+- Change IWatcherOptions: remove stabilityThreshold/pollInterval/maxWaitTime and add debounceMs
+- Default watcher options updated to use debounceMs = 100
+- Node/Deno watchers now skip editor temp files earlier, debounce duplicate events, and emit events directly (no size polling)
+- Updated default watcher creation in Smartwatch to pass debounceMs
+- Update package.json build script to run 'tsbuild tsfolders'
+
 ## 2025-12-08 - 5.1.0 - feat(watchers)
 Improve write stabilization and ignore temporary editor files
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartwatch",
-  "version": "5.1.0",
+  "version": "6.1.0",
   "private": false,
   "description": "A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.",
   "main": "dist_ts/index.js",
@@ -8,7 +8,7 @@
   "scripts": {
     "test": "(npm run prepareTest && tstest test/)",
     "prepareTest": "(rm -f ./test/assets/hi.txt)",
-    "build": "tsbuild",
+    "build": "tsbuild tsfolders",
     "buildDocs": "tsdoc"
   },
   "repository": {

readme.hints.md

@@ -71,6 +71,37 @@ The `WriteStabilizer` class replaces chokidar's built-in write stabilization:
 - **Deno**: Works on all versions with `Deno.watchFs()`
 - **Bun**: Uses Node.js compatibility layer
 
+### Robustness Features (v6.1.0+)
+
+The Node.js watcher includes automatic recovery mechanisms:
+
+**Auto-restart on failure:**
+- Watchers automatically restart when errors occur
+- Exponential backoff (1s → 30s max)
+- Maximum 3 retry attempts before giving up
+
+**Health check monitoring:**
+- 30-second periodic health checks
+- Detects when watched paths disappear
+- Triggers automatic restart when issues detected
+
+**Error isolation:**
+- Subscriber errors don't crash the watcher
+- All events emitted via `safeEmit()` with try-catch
+
+**Verbose logging:**
+- All lifecycle events logged with `[smartwatch]` prefix
+- Helps debug watcher issues in production
+
+Example log output:
+```
+[smartwatch] Starting watcher for 1 base path(s)...
+[smartwatch] Started watching: ./test/assets/
+[smartwatch] Starting health check (every 30s)
+[smartwatch] Watcher started with 1 active watcher(s)
+[smartwatch] Health check: 1 watchers active
+```
+
 ### Testing
 
 ```bash

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartwatch',
-  version: '5.1.0',
+  version: '6.1.0',
   description: 'A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.'
 }

ts/smartwatch.classes.smartwatch.ts

@@ -132,9 +132,7 @@ export class Smartwatch {
       basePaths: watchPaths,
       depth: 4,
       followSymlinks: false,
-      stabilityThreshold: 100,
+      debounceMs: 100
-      pollInterval: 100,
-      maxWaitTime: 1000
     });
 
     // Subscribe to watcher events and dispatch to appropriate subjects

ts/utils/write-stabilizer.ts

@@ -1,109 +0,0 @@
-import * as fs from 'fs';
-
-interface IPendingWrite {
-  lastSize: number;
-  lastChange: number;
-  startTime: number;
-  timeoutId: ReturnType<typeof setTimeout>;
-  resolve: (stats: fs.Stats) => void;
-  reject: (error: Error) => void;
-}
-
-/**
- * Implements awaitWriteFinish functionality by polling file size until stable.
- * This replaces chokidar's built-in write stabilization.
- */
-export class WriteStabilizer {
-  private pendingWrites = new Map<string, IPendingWrite>();
-
-  constructor(
-    private stabilityThreshold: number = 100,
-    private pollInterval: number = 100,
-    private maxWaitTime: number = 1000
-  ) {}
-
-  /**
-   * Wait for a file write to complete by polling until size is stable
-   */
-  async waitForWriteFinish(filePath: string): Promise<fs.Stats> {
-    // Cancel any existing pending check for this file
-    this.cancel(filePath);
-
-    return new Promise((resolve, reject) => {
-      const startTime = Date.now();
-
-      const poll = async () => {
-        try {
-          const stats = await fs.promises.stat(filePath);
-          const pending = this.pendingWrites.get(filePath);
-
-          if (!pending) {
-            // Was cancelled
-            return;
-          }
-
-          const now = Date.now();
-
-          // Check if we've exceeded max wait time - emit with current stats
-          if (now - pending.startTime >= this.maxWaitTime) {
-            this.pendingWrites.delete(filePath);
-            resolve(stats);
-            return;
-          }
-
-          if (stats.size !== pending.lastSize) {
-            // Size changed - file is still being written, reset timer
-            pending.lastSize = stats.size;
-            pending.lastChange = now;
-            pending.timeoutId = setTimeout(poll, this.pollInterval);
-          } else if (now - pending.lastChange >= this.stabilityThreshold) {
-            // Size has been stable for the threshold duration
-            this.pendingWrites.delete(filePath);
-            resolve(stats);
-          } else {
-            // Size is the same but not yet past threshold
-            pending.timeoutId = setTimeout(poll, this.pollInterval);
-          }
-        } catch (error: any) {
-          this.pendingWrites.delete(filePath);
-          if (error.code === 'ENOENT') {
-            // File was deleted during polling
-            reject(new Error(`File was deleted: ${filePath}`));
-          } else {
-            reject(error);
-          }
-        }
-      };
-
-      this.pendingWrites.set(filePath, {
-        lastSize: -1,
-        lastChange: startTime,
-        startTime: startTime,
-        timeoutId: setTimeout(poll, this.pollInterval),
-        resolve,
-        reject
-      });
-    });
-  }
-
-  /**
-   * Cancel any pending write stabilization for a file
-   */
-  cancel(filePath: string): void {
-    const pending = this.pendingWrites.get(filePath);
-    if (pending) {
-      clearTimeout(pending.timeoutId);
-      this.pendingWrites.delete(filePath);
-    }
-  }
-
-  /**
-   * Cancel all pending write stabilizations
-   */
-  cancelAll(): void {
-    for (const [filePath, pending] of this.pendingWrites) {
-      clearTimeout(pending.timeoutId);
-    }
-    this.pendingWrites.clear();
-  }
-}

ts/watchers/index.ts

@@ -28,7 +28,5 @@ export const defaultWatcherOptions: IWatcherOptions = {
   basePaths: [],
   depth: 4,
   followSymlinks: false,
-  stabilityThreshold: 100,
+  debounceMs: 100
-  pollInterval: 100,
-  maxWaitTime: 1000
 };

ts/watchers/interfaces.ts

@@ -26,12 +26,8 @@ export interface IWatcherOptions {
   depth: number;
   /** Whether to follow symbolic links */
   followSymlinks: boolean;
-  /** Stability threshold for write detection (ms) */
+  /** Debounce time in ms - events for the same file within this window are coalesced */
-  stabilityThreshold: number;
+  debounceMs: number;
-  /** Poll interval for write detection (ms) */
-  pollInterval: number;
-  /** Maximum time to wait for write stabilization (ms) */
-  maxWaitTime: number;
 }
 
 /**

ts/watchers/watcher.deno.ts

@@ -65,10 +65,9 @@ export class DenoWatcher implements IWatcher {
   private watcher: ReturnType<typeof Deno.watchFs> | null = null;
   private watchedFiles: Set<string> = new Set();
   private _isWatching = false;
-  private abortController: AbortController | null = null;
+
-  private recentEvents: Map<string, number> = new Map();
+  // Debounce: pending emits per file path
-  private throttleMs = 50;
+  private pendingEmits: Map<string, ReturnType<typeof setTimeout>> = new Map();
-  private pendingWrites: Map<string, ReturnType<typeof setTimeout>> = new Map();
 
   public readonly events$ = new smartrx.rxjs.Subject<IWatchEvent>();
 
@@ -97,8 +96,6 @@ export class DenoWatcher implements IWatcher {
     }
 
     try {
-      this.abortController = new AbortController();
-
       // Start watching all base paths
       this.watcher = Deno.watchFs(this.options.basePaths, { recursive: true });
       this._isWatching = true;
@@ -122,11 +119,11 @@ export class DenoWatcher implements IWatcher {
   async stop(): Promise<void> {
     this._isWatching = false;
 
-    // Cancel all pending write stabilizations
+    // Cancel all pending debounced emits
-    for (const timeout of this.pendingWrites.values()) {
+    for (const timeout of this.pendingEmits.values()) {
       clearTimeout(timeout);
     }
-    this.pendingWrites.clear();
+    this.pendingEmits.clear();
 
     // Close the watcher
     if (this.watcher) {
@@ -135,7 +132,6 @@ export class DenoWatcher implements IWatcher {
     }
 
     this.watchedFiles.clear();
-    this.recentEvents.clear();
   }
 
   /**
@@ -153,7 +149,7 @@ export class DenoWatcher implements IWatcher {
         }
 
         for (const filePath of event.paths) {
-          await this.handleDenoEvent(event.kind, filePath);
+          this.handleDenoEvent(event.kind, filePath);
         }
       }
     } catch (error: any) {
@@ -164,12 +160,12 @@ export class DenoWatcher implements IWatcher {
   }
 
   /**
-   * Handle a Deno file system event
+   * Handle a Deno file system event - debounce and normalize
    */
-  private async handleDenoEvent(
+  private handleDenoEvent(
     kind: 'create' | 'modify' | 'remove' | 'access' | 'any' | 'other',
     filePath: string
-  ): Promise<void> {
+  ): void {
     // Ignore 'access' events (just reading the file)
     if (kind === 'access') {
       return;
@@ -180,14 +176,30 @@ export class DenoWatcher implements IWatcher {
       return;
     }
 
-    // Throttle duplicate events
+    // Debounce: cancel any pending emit for this file
-    if (!this.shouldEmit(filePath, kind)) {
+    const existing = this.pendingEmits.get(filePath);
-      return;
+    if (existing) {
+      clearTimeout(existing);
     }
 
+    // Schedule debounced emit
+    const timeout = setTimeout(() => {
+      this.pendingEmits.delete(filePath);
+      this.emitFileEvent(filePath, kind);
+    }, this.options.debounceMs);
+
+    this.pendingEmits.set(filePath, timeout);
+  }
+
+  /**
+   * Emit the actual file event after debounce
+   */
+  private async emitFileEvent(
+    filePath: string,
+    kind: 'create' | 'modify' | 'remove' | 'access' | 'any' | 'other'
+  ): Promise<void> {
     try {
       if (kind === 'create') {
-        // Create events (atomic saves) don't need stabilization - file is already complete
         const stats = await this.statSafe(filePath);
         if (stats) {
           this.watchedFiles.add(filePath);
@@ -195,16 +207,9 @@ export class DenoWatcher implements IWatcher {
           this.events$.next({ type: eventType, path: filePath, stats });
         }
       } else if (kind === 'modify') {
-        // Modify events are in-place writes - use stabilization
         const stats = await this.statSafe(filePath);
         if (stats && !stats.isDirectory()) {
-          // Wait for write to stabilize
+          this.events$.next({ type: 'change', path: filePath, stats });
-          await this.waitForWriteFinish(filePath);
-          const finalStats = await this.statSafe(filePath);
-
-          if (finalStats) {
-            this.events$.next({ type: 'change', path: filePath, stats: finalStats });
-          }
         }
       } else if (kind === 'remove') {
         const wasDirectory = this.isKnownDirectory(filePath);
@@ -219,52 +224,6 @@ export class DenoWatcher implements IWatcher {
     }
   }
 
-  /**
-   * Wait for file write to complete (polling-based)
-   */
-  private async waitForWriteFinish(filePath: string): Promise<void> {
-    return new Promise((resolve) => {
-      let lastSize = -1;
-      let lastChange = Date.now();
-      const startTime = Date.now();
-
-      const poll = async () => {
-        try {
-          const stats = await this.statSafe(filePath);
-          if (!stats) {
-            resolve();
-            return;
-          }
-
-          const now = Date.now();
-
-          // Check if we've exceeded max wait time - resolve immediately
-          if (now - startTime >= this.options.maxWaitTime) {
-            this.pendingWrites.delete(filePath);
-            resolve();
-            return;
-          }
-
-          if (stats.size !== lastSize) {
-            lastSize = stats.size;
-            lastChange = now;
-            this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
-          } else if (now - lastChange >= this.options.stabilityThreshold) {
-            this.pendingWrites.delete(filePath);
-            resolve();
-          } else {
-            this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
-          }
-        } catch {
-          this.pendingWrites.delete(filePath);
-          resolve();
-        }
-      };
-
-      this.pendingWrites.set(filePath, setTimeout(poll, this.options.pollInterval));
-    });
-  }
-
   /**
    * Scan directory and emit 'add' events for existing files
    */
@@ -276,6 +235,12 @@ export class DenoWatcher implements IWatcher {
     try {
       for await (const entry of Deno.readDir(dirPath)) {
         const fullPath = `${dirPath}/${entry.name}`;
+
+        // Skip temp files during initial scan too
+        if (this.isTemporaryFile(fullPath)) {
+          continue;
+        }
+
         const stats = await this.statSafe(fullPath);
 
         if (!stats) {
@@ -322,31 +287,4 @@ export class DenoWatcher implements IWatcher {
     }
     return false;
   }
-
-  /**
-   * Throttle duplicate events
-   */
-  private shouldEmit(filePath: string, eventType: string): boolean {
-    const key = `${filePath}:${eventType}`;
-    const now = Date.now();
-    const lastEmit = this.recentEvents.get(key);
-
-    if (lastEmit && now - lastEmit < this.throttleMs) {
-      return false;
-    }
-
-    this.recentEvents.set(key, now);
-
-    // Clean up old entries periodically
-    if (this.recentEvents.size > 1000) {
-      const cutoff = now - this.throttleMs * 2;
-      for (const [k, time] of this.recentEvents) {
-        if (time < cutoff) {
-          this.recentEvents.delete(k);
-        }
-      }
-    }
-
-    return true;
-  }
 }

ts/watchers/watcher.node.ts

@@ -2,7 +2,6 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as smartrx from '@push.rocks/smartrx';
 import type { IWatcher, IWatcherOptions, IWatchEvent, TWatchEventType } from './interfaces.js';
-import { WriteStabilizer } from '../utils/write-stabilizer.js';
 
 /**
  * Node.js/Bun file watcher using native fs.watch API
@@ -11,18 +10,116 @@ export class NodeWatcher implements IWatcher {
   private watchers: Map<string, fs.FSWatcher> = new Map();
   private watchedFiles: Set<string> = new Set();
   private _isWatching = false;
-  private writeStabilizer: WriteStabilizer;
+
-  private recentEvents: Map<string, number> = new Map();
+  // Debounce: pending emits per file path
-  private throttleMs = 50;
+  private pendingEmits: Map<string, NodeJS.Timeout> = new Map();
+
+  // Restart tracking
+  private restartDelays: Map<string, number> = new Map();
+  private restartAttempts: Map<string, number> = new Map();
+  private healthCheckInterval: NodeJS.Timeout | null = null;
+
+  // Configuration constants
+  private static readonly MAX_RETRIES = 3;
+  private static readonly INITIAL_RESTART_DELAY = 1000;
+  private static readonly MAX_RESTART_DELAY = 30000;
+  private static readonly HEALTH_CHECK_INTERVAL = 30000;
 
   public readonly events$ = new smartrx.rxjs.Subject<IWatchEvent>();
 
-  constructor(private options: IWatcherOptions) {
+  constructor(private options: IWatcherOptions) {}
-    this.writeStabilizer = new WriteStabilizer(
+
-      options.stabilityThreshold,
+  /**
-      options.pollInterval,
+   * Safely emit an event, catching any subscriber errors
-      options.maxWaitTime
+   */
-    );
+  private safeEmit(event: IWatchEvent): void {
+    try {
+      this.events$.next(event);
+    } catch (error) {
+      console.error('[smartwatch] Subscriber threw error (isolated):', error);
+      // Don't let subscriber errors kill the watcher
+    }
+  }
+
+  /**
+   * Restart a watcher after an error with exponential backoff
+   */
+  private async restartWatcher(basePath: string, error: Error): Promise<void> {
+    const attempts = (this.restartAttempts.get(basePath) || 0) + 1;
+    this.restartAttempts.set(basePath, attempts);
+
+    console.log(`[smartwatch] Watcher error for ${basePath}: ${error.message}`);
+    console.log(`[smartwatch] Restart attempt ${attempts}/${NodeWatcher.MAX_RETRIES}`);
+
+    if (attempts > NodeWatcher.MAX_RETRIES) {
+      console.error(`[smartwatch] Max retries exceeded for ${basePath}, giving up`);
+      this.safeEmit({
+        type: 'error',
+        path: basePath,
+        error: new Error(`Max restart retries (${NodeWatcher.MAX_RETRIES}) exceeded`)
+      });
+      return;
+    }
+
+    // Close failed watcher
+    const oldWatcher = this.watchers.get(basePath);
+    if (oldWatcher) {
+      try {
+        oldWatcher.close();
+      } catch {
+        // Ignore close errors
+      }
+      this.watchers.delete(basePath);
+    }
+
+    // Exponential backoff
+    const delay = this.restartDelays.get(basePath) || NodeWatcher.INITIAL_RESTART_DELAY;
+    console.log(`[smartwatch] Waiting ${delay}ms before restart...`);
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    this.restartDelays.set(basePath, Math.min(delay * 2, NodeWatcher.MAX_RESTART_DELAY));
+
+    try {
+      await this.watchPath(basePath, 0);
+      console.log(`[smartwatch] Successfully restarted watcher for ${basePath}`);
+      this.restartDelays.set(basePath, NodeWatcher.INITIAL_RESTART_DELAY);
+      this.restartAttempts.set(basePath, 0);
+    } catch (restartError) {
+      console.error(`[smartwatch] Restart failed for ${basePath}:`, restartError);
+      this.restartWatcher(basePath, restartError as Error); // Recursive retry
+    }
+  }
+
+  /**
+   * Start periodic health checks to detect silent failures
+   */
+  private startHealthCheck(): void {
+    console.log('[smartwatch] Starting health check (every 30s)');
+    this.healthCheckInterval = setInterval(async () => {
+      console.log(`[smartwatch] Health check: ${this.watchers.size} watchers active`);
+      for (const [basePath] of this.watchers) {
+        const stats = await this.statSafe(basePath);
+        if (!stats && this._isWatching) {
+          console.error(`[smartwatch] Health check failed: ${basePath} no longer exists`);
+          this.safeEmit({
+            type: 'error',
+            path: basePath,
+            error: new Error('Watched path no longer exists')
+          });
+          this.restartWatcher(basePath, new Error('Watched path disappeared'));
+        }
+      }
+    }, NodeWatcher.HEALTH_CHECK_INTERVAL);
+  }
+
+  /**
+   * Stop health check interval
+   */
+  private stopHealthCheck(): void {
+    if (this.healthCheckInterval) {
+      clearInterval(this.healthCheckInterval);
+      this.healthCheckInterval = null;
+      console.log('[smartwatch] Stopped health check');
+    }
   }
 
   /**
@@ -47,6 +144,8 @@ export class NodeWatcher implements IWatcher {
       return;
     }
 
+    console.log(`[smartwatch] Starting watcher for ${this.options.basePaths.length} base path(s)...`);
+
     try {
       // Start watching each base path
       for (const basePath of this.options.basePaths) {
@@ -55,30 +154,50 @@ export class NodeWatcher implements IWatcher {
 
       this._isWatching = true;
 
+      // Start health check monitoring
+      this.startHealthCheck();
+
       // Perform initial scan to emit 'add' events for existing files
       for (const basePath of this.options.basePaths) {
         await this.scanDirectory(basePath, 0);
       }
 
       // Emit ready event
-      this.events$.next({ type: 'ready', path: '' });
+      this.safeEmit({ type: 'ready', path: '' });
+      console.log(`[smartwatch] Watcher started with ${this.watchers.size} active watcher(s)`);
     } catch (error: any) {
-      this.events$.next({ type: 'error', path: '', error });
+      console.error('[smartwatch] Failed to start watcher:', error);
+      this.safeEmit({ type: 'error', path: '', error });
       throw error;
     }
   }
 
   async stop(): Promise<void> {
+    console.log('[smartwatch] Stopping watcher...');
     this._isWatching = false;
-    this.writeStabilizer.cancelAll();
+
+    // Stop health check monitoring
+    this.stopHealthCheck();
+
+    // Cancel all pending debounced emits
+    for (const timeout of this.pendingEmits.values()) {
+      clearTimeout(timeout);
+    }
+    this.pendingEmits.clear();
 
     // Close all watchers
     for (const [watchPath, watcher] of this.watchers) {
+      console.log(`[smartwatch] Closing watcher for: ${watchPath}`);
       watcher.close();
     }
     this.watchers.clear();
     this.watchedFiles.clear();
-    this.recentEvents.clear();
+
+    // Clear restart tracking state
+    this.restartDelays.clear();
+    this.restartAttempts.clear();
+
+    console.log('[smartwatch] Watcher stopped');
   }
 
   /**
@@ -108,24 +227,38 @@ export class NodeWatcher implements IWatcher {
         );
 
         watcher.on('error', (error) => {
-          this.events$.next({ type: 'error', path: watchPath, error });
+          console.error(`[smartwatch] FSWatcher error event on ${watchPath}:`, error);
+          this.safeEmit({ type: 'error', path: watchPath, error });
+          if (this._isWatching) {
+            this.restartWatcher(watchPath, error);
+          }
+        });
+
+        // Handle 'close' event - fs.watch can close without error
+        watcher.on('close', () => {
+          console.warn(`[smartwatch] FSWatcher closed unexpectedly for ${watchPath}`);
+          if (this._isWatching) {
+            this.restartWatcher(watchPath, new Error('Watcher closed unexpectedly'));
+          }
         });
 
         this.watchers.set(watchPath, watcher);
+        console.log(`[smartwatch] Started watching: ${watchPath}`);
       }
     } catch (error: any) {
-      this.events$.next({ type: 'error', path: watchPath, error });
+      console.error(`[smartwatch] Failed to watch path ${watchPath}:`, error);
+      this.safeEmit({ type: 'error', path: watchPath, error });
     }
   }
 
   /**
-   * Handle raw fs.watch events and normalize them
+   * Handle raw fs.watch events - debounce and normalize them
    */
-  private async handleFsEvent(
+  private handleFsEvent(
     basePath: string,
     filename: string,
     eventType: 'rename' | 'change' | string
-  ): Promise<void> {
+  ): void {
     const fullPath = path.join(basePath, filename);
 
     // Skip temporary files created by editors (atomic saves)
@@ -133,11 +266,28 @@ export class NodeWatcher implements IWatcher {
       return;
     }
 
-    // Throttle duplicate events
+    // Debounce: cancel any pending emit for this file
-    if (!this.shouldEmit(fullPath, eventType)) {
+    const existing = this.pendingEmits.get(fullPath);
-      return;
+    if (existing) {
+      clearTimeout(existing);
     }
 
+    // Schedule debounced emit
+    const timeout = setTimeout(() => {
+      this.pendingEmits.delete(fullPath);
+      this.emitFileEvent(fullPath, eventType);
+    }, this.options.debounceMs);
+
+    this.pendingEmits.set(fullPath, timeout);
+  }
+
+  /**
+   * Emit the actual file event after debounce
+   */
+  private async emitFileEvent(
+    fullPath: string,
+    eventType: 'rename' | 'change' | string
+  ): Promise<void> {
     try {
       const stats = await this.statSafe(fullPath);
 
@@ -148,13 +298,12 @@ export class NodeWatcher implements IWatcher {
           if (stats.isDirectory()) {
             if (!this.watchedFiles.has(fullPath)) {
               this.watchedFiles.add(fullPath);
-              this.events$.next({ type: 'addDir', path: fullPath, stats });
+              this.safeEmit({ type: 'addDir', path: fullPath, stats });
             }
           } else {
-            // Rename events (atomic saves) don't need stabilization - file is already complete
             const wasWatched = this.watchedFiles.has(fullPath);
             this.watchedFiles.add(fullPath);
-            this.events$.next({
+            this.safeEmit({
               type: wasWatched ? 'change' : 'add',
               path: fullPath,
               stats
@@ -165,37 +314,31 @@ export class NodeWatcher implements IWatcher {
           if (this.watchedFiles.has(fullPath)) {
             const wasDir = this.isKnownDirectory(fullPath);
             this.watchedFiles.delete(fullPath);
-            this.events$.next({
+            this.safeEmit({
               type: wasDir ? 'unlinkDir' : 'unlink',
               path: fullPath
             });
           }
         }
       } else if (eventType === 'change') {
-        // File was modified in-place - use stabilization for streaming writes
+        // File was modified
         if (stats && !stats.isDirectory()) {
-          try {
-            const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath);
-            // Check if this is a new file (not yet in watchedFiles)
           const wasWatched = this.watchedFiles.has(fullPath);
           if (!wasWatched) {
             // This is actually an 'add' - file wasn't being watched before
             this.watchedFiles.add(fullPath);
-              this.events$.next({ type: 'add', path: fullPath, stats: stableStats });
+            this.safeEmit({ type: 'add', path: fullPath, stats });
           } else {
-              this.events$.next({ type: 'change', path: fullPath, stats: stableStats });
+            this.safeEmit({ type: 'change', path: fullPath, stats });
           }
-          } catch {
+        } else if (!stats && this.watchedFiles.has(fullPath)) {
-            // File was deleted during write
+          // File was deleted
-            if (this.watchedFiles.has(fullPath)) {
           this.watchedFiles.delete(fullPath);
-              this.events$.next({ type: 'unlink', path: fullPath });
+          this.safeEmit({ type: 'unlink', path: fullPath });
-            }
-          }
         }
       }
     } catch (error: any) {
-      this.events$.next({ type: 'error', path: fullPath, error });
+      this.safeEmit({ type: 'error', path: fullPath, error });
     }
   }
 
@@ -212,6 +355,12 @@ export class NodeWatcher implements IWatcher {
 
       for (const entry of entries) {
         const fullPath = path.join(dirPath, entry.name);
+
+        // Skip temp files during initial scan too
+        if (this.isTemporaryFile(fullPath)) {
+          continue;
+        }
+
         const stats = await this.statSafe(fullPath);
 
         if (!stats) {
@@ -220,16 +369,16 @@ export class NodeWatcher implements IWatcher {
 
         if (entry.isDirectory()) {
           this.watchedFiles.add(fullPath);
-          this.events$.next({ type: 'addDir', path: fullPath, stats });
+          this.safeEmit({ type: 'addDir', path: fullPath, stats });
           await this.scanDirectory(fullPath, depth + 1);
         } else if (entry.isFile()) {
           this.watchedFiles.add(fullPath);
-          this.events$.next({ type: 'add', path: fullPath, stats });
+          this.safeEmit({ type: 'add', path: fullPath, stats });
         }
       }
     } catch (error: any) {
       if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
-        this.events$.next({ type: 'error', path: dirPath, error });
+        this.safeEmit({ type: 'error', path: dirPath, error });
       }
     }
   }
@@ -239,12 +388,16 @@ export class NodeWatcher implements IWatcher {
    */
   private async statSafe(filePath: string): Promise<fs.Stats | null> {
     try {
-      if (this.options.followSymlinks) {
+      return await (this.options.followSymlinks
-        return await fs.promises.stat(filePath);
+        ? fs.promises.stat(filePath)
-      } else {
+        : fs.promises.lstat(filePath));
-        return await fs.promises.lstat(filePath);
+    } catch (error: any) {
+      // Only silently return null for expected "file doesn't exist" errors
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+        return null;
       }
-    } catch {
+      // Log other errors (permission, I/O) but still return null
+      console.warn(`[smartwatch] statSafe warning for ${filePath}: ${error.code} - ${error.message}`);
       return null;
     }
   }
@@ -261,31 +414,4 @@ export class NodeWatcher implements IWatcher {
     }
     return false;
   }
-
-  /**
-   * Throttle duplicate events
-   */
-  private shouldEmit(filePath: string, eventType: string): boolean {
-    const key = `${filePath}:${eventType}`;
-    const now = Date.now();
-    const lastEmit = this.recentEvents.get(key);
-
-    if (lastEmit && now - lastEmit < this.throttleMs) {
-      return false;
-    }
-
-    this.recentEvents.set(key, now);
-
-    // Clean up old entries periodically
-    if (this.recentEvents.size > 1000) {
-      const cutoff = now - this.throttleMs * 2;
-      for (const [k, time] of this.recentEvents) {
-        if (time < cutoff) {
-          this.recentEvents.delete(k);
-        }
-      }
-    }
-
-    return true;
-  }
 }