v6.1.0

changelog.md

@@ -1,5 +1,37 @@
 # 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
+
+- Add maxWaitTime option (ms) to IWatcherOptions and WriteStabilizer to cap how long stabilization will wait (default: 1000ms).
+- WriteStabilizer: reduce default stabilityThreshold from 300ms to 100ms and track write start time to enforce maxWaitTime and avoid indefinite polling.
+- Node and Deno watchers: detect and ignore common temporary/editor files (e.g. *.tmp.*, *.swp, *.swx, trailing ~, .#*) to prevent spurious events from atomic saves.
+- Node watcher: treat rename (atomic-save) events as already-complete files and emit add/change immediately without stabilization.
+- Deno watcher: use the configured maxWaitTime and polling-based stabilization for modify events to ensure consistent behavior across runtimes.
+
 ## 2025-11-30 - 5.0.0 - BREAKING CHANGE(@push.rocks/smartwatch)
 Rename package and update branding/docs: switch from @push.rocks/smartchok to @push.rocks/smartwatch, update repository/homepage/bugs URLs and author, and refresh README examples and install instructions.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartwatch",
-  "version": "5.0.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.0.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,8 +132,7 @@ export class Smartwatch {
       basePaths: watchPaths,
       depth: 4,
       followSymlinks: false,
-      stabilityThreshold: 300,
-      pollInterval: 100
+      debounceMs: 100
     });
 
     // Subscribe to watcher events and dispatch to appropriate subjects

ts/utils/write-stabilizer.ts

@@ -1,97 +0,0 @@
-import * as fs from 'fs';
-
-interface IPendingWrite {
-  lastSize: number;
-  lastChange: 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 = 300,
-    private pollInterval: number = 100
-  ) {}
-
-  /**
-   * 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 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();
-
-          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: Date.now(),
-        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,6 +28,5 @@ export const defaultWatcherOptions: IWatcherOptions = {
   basePaths: [],
   depth: 4,
   followSymlinks: false,
-  stabilityThreshold: 300,
-  pollInterval: 100
+  debounceMs: 100
 };

ts/watchers/interfaces.ts

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

ts/watchers/watcher.deno.ts

@@ -65,15 +65,27 @@ 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();
-  private throttleMs = 50;
-  private pendingWrites: Map<string, ReturnType<typeof setTimeout>> = new Map();
+
+  // Debounce: pending emits per file path
+  private pendingEmits: Map<string, ReturnType<typeof setTimeout>> = new Map();
 
   public readonly events$ = new smartrx.rxjs.Subject<IWatchEvent>();
 
   constructor(private options: IWatcherOptions) {}
 
+  /**
+   * Check if a file is a temporary file created by editors
+   */
+  private isTemporaryFile(filePath: string): boolean {
+    const basename = filePath.split('/').pop() || '';
+    // Editor temp files: *.tmp.*, *.swp, *.swx, *~, .#*
+    if (basename.includes('.tmp.')) return true;
+    if (basename.endsWith('.swp') || basename.endsWith('.swx')) return true;
+    if (basename.endsWith('~')) return true;
+    if (basename.startsWith('.#')) return true;
+    return false;
+  }
+
   get isWatching(): boolean {
     return this._isWatching;
   }
@@ -84,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;
@@ -109,11 +119,11 @@ export class DenoWatcher implements IWatcher {
   async stop(): Promise<void> {
     this._isWatching = false;
 
-    // Cancel all pending write stabilizations
-    for (const timeout of this.pendingWrites.values()) {
+    // Cancel all pending debounced emits
+    for (const timeout of this.pendingEmits.values()) {
       clearTimeout(timeout);
     }
-    this.pendingWrites.clear();
+    this.pendingEmits.clear();
 
     // Close the watcher
     if (this.watcher) {
@@ -122,7 +132,6 @@ export class DenoWatcher implements IWatcher {
     }
 
     this.watchedFiles.clear();
-    this.recentEvents.clear();
   }
 
   /**
@@ -140,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) {
@@ -151,46 +160,56 @@ 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;
     }
 
-    // Throttle duplicate events
-    if (!this.shouldEmit(filePath, kind)) {
+    // Skip temporary files created by editors (atomic saves)
+    if (this.isTemporaryFile(filePath)) {
       return;
     }
 
+    // Debounce: cancel any pending emit for this file
+    const existing = this.pendingEmits.get(filePath);
+    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') {
         const stats = await this.statSafe(filePath);
         if (stats) {
-          // Wait for write to stabilize
-          await this.waitForWriteFinish(filePath);
-          const finalStats = await this.statSafe(filePath);
-
-          if (finalStats) {
           this.watchedFiles.add(filePath);
-            const eventType: TWatchEventType = finalStats.isDirectory() ? 'addDir' : 'add';
-            this.events$.next({ type: eventType, path: filePath, stats: finalStats });
-          }
+          const eventType: TWatchEventType = stats.isDirectory() ? 'addDir' : 'add';
+          this.events$.next({ type: eventType, path: filePath, stats });
         }
       } else if (kind === 'modify') {
         const stats = await this.statSafe(filePath);
         if (stats && !stats.isDirectory()) {
-          // Wait for write to stabilize
-          await this.waitForWriteFinish(filePath);
-          const finalStats = await this.statSafe(filePath);
-
-          if (finalStats) {
-            this.events$.next({ type: 'change', path: filePath, stats: finalStats });
-          }
+          this.events$.next({ type: 'change', path: filePath, stats });
         }
       } else if (kind === 'remove') {
         const wasDirectory = this.isKnownDirectory(filePath);
@@ -205,43 +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 poll = async () => {
-        try {
-          const stats = await this.statSafe(filePath);
-          if (!stats) {
-            resolve();
-            return;
-          }
-
-          const now = Date.now();
-          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
    */
@@ -253,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) {
@@ -299,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,17 +10,129 @@ 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();
-  private throttleMs = 50;
+
+  // Debounce: pending emits per file path
+  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) {
-    this.writeStabilizer = new WriteStabilizer(
-      options.stabilityThreshold,
-      options.pollInterval
-    );
+  constructor(private options: IWatcherOptions) {}
+
+  /**
+   * Safely emit an event, catching any subscriber errors
+   */
+  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');
+    }
+  }
+
+  /**
+   * Check if a file is a temporary file created by editors
+   */
+  private isTemporaryFile(filePath: string): boolean {
+    const basename = path.basename(filePath);
+    // Editor temp files: *.tmp.*, *.swp, *.swx, *~, .#*
+    if (basename.includes('.tmp.')) return true;
+    if (basename.endsWith('.swp') || basename.endsWith('.swx')) return true;
+    if (basename.endsWith('~')) return true;
+    if (basename.startsWith('.#')) return true;
+    return false;
   }
 
   get isWatching(): boolean {
@@ -33,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) {
@@ -41,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');
   }
 
   /**
@@ -94,31 +227,67 @@ 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);
 
-    // Throttle duplicate events
-    if (!this.shouldEmit(fullPath, eventType)) {
+    // Skip temporary files created by editors (atomic saves)
+    if (this.isTemporaryFile(fullPath)) {
       return;
     }
 
+    // Debounce: cancel any pending emit for this file
+    const existing = this.pendingEmits.get(fullPath);
+    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);
 
@@ -129,33 +298,23 @@ 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 {
-            // Wait for write to stabilize before emitting
-            try {
-              const stableStats = await this.writeStabilizer.waitForWriteFinish(fullPath);
             const wasWatched = this.watchedFiles.has(fullPath);
             this.watchedFiles.add(fullPath);
-              this.events$.next({
+            this.safeEmit({
               type: wasWatched ? 'change' : 'add',
               path: fullPath,
-                stats: stableStats
+              stats
             });
-            } catch {
-              // File was deleted during stabilization
-              if (this.watchedFiles.has(fullPath)) {
-                this.watchedFiles.delete(fullPath);
-                this.events$.next({ type: 'unlink', path: fullPath });
-              }
-            }
           }
         } else {
           // File doesn't exist - it was deleted
           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
             });
@@ -164,28 +323,22 @@ export class NodeWatcher implements IWatcher {
       } else if (eventType === 'change') {
         // 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 {
-            // File was deleted during write
-            if (this.watchedFiles.has(fullPath)) {
+        } else if (!stats && this.watchedFiles.has(fullPath)) {
+          // File was deleted
           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 });
     }
   }
 
@@ -202,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) {
@@ -210,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 });
       }
     }
   }
@@ -229,12 +388,16 @@ export class NodeWatcher implements IWatcher {
    */
   private async statSafe(filePath: string): Promise<fs.Stats | null> {
     try {
-      if (this.options.followSymlinks) {
-        return await fs.promises.stat(filePath);
-      } else {
-        return await fs.promises.lstat(filePath);
+      return await (this.options.followSymlinks
+        ? fs.promises.stat(filePath)
+        : 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;
     }
   }
@@ -251,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;
-  }
 }