v6.3.0

changelog.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 2025-12-11 - 6.3.0 - feat(watchers)
+Integrate chokidar-based Node watcher, expose awaitWriteFinish options, and update docs/tests
+
+- Add chokidar dependency and implement NodeWatcher as a chokidar wrapper for Node.js/Bun
+- Expose awaitWriteFinish, stabilityThreshold and pollInterval in IWatcherOptions and wire them into the NodeWatcher
+- Update watcher factory to return NodeWatcher for Node/Bun and DenoWatcher for Deno
+- Adjust tests to wait for chokidar readiness and to expect chokidar's atomic handling (delete+recreate -> change)
+- Revise README and technical hints to document chokidar usage and cross-runtime behavior
+
+## 2025-12-11 - 6.2.5 - fix(watcher.node)
+Normalize paths and improve Node watcher robustness: restart/rescan on errors (including ENOSPC), clear stale state, and remove legacy throttler
+
+- Normalize all paths to absolute at watcher entry points (watchPath, handleFsEvent, scanDirectory) to avoid relative/absolute mismatch bugs
+- On watcher restart: clear pending unlink timeouts, dispose stale DirEntry data, and perform a rescan to catch files created during the restart window
+- Trigger watcher restart on ENOSPC (inotify limit) errors instead of only logging the error
+- Remove the previous Throttler implementation and rely on the existing debounce + event-sequence tracking to handle rapid events
+- Atomic write handling and queued unlink behavior preserved; pending unlinks are cleared for restarted base paths to avoid stale events
+
+## 2025-12-11 - 6.2.4 - fix(tests)
+Stabilize tests and document chokidar-inspired Node watcher architecture
+
+- test: add waitForFileEvent helper to wait for events for a specific file (reduces test flakiness)
+- test: add small delays after unlink cleanup to account for atomic/temp-file debounce windows
+- docs: expand readme.hints.md with a detailed Node watcher architecture section (DirEntry, Throttler, atomic write handling, closer registry, constants and config)
+- docs: list updated test files and coverage scenarios (inode detection, atomic writes, stress tests)
+
+## 2025-12-11 - 6.2.3 - fix(watcher.node)
+Improve handling of temporary files from atomic editor writes in Node watcher
+
+- Detect temporary files produced by atomic editor saves and attempt to map them to the real target file instead of silently skipping the event
+- Add getTempFileTarget() to extract the real file path from temp filenames (supports patterns like file.ts.tmp.PID.TIMESTAMP and generic .tmp.*)
+- When a temp-file event is seen, queue a corresponding event for the resolved real file after a short delay (50ms) to allow rename/replace to complete
+- Add logging around temp file detection and real-file checks to aid debugging
+
+## 2025-12-11 - 6.2.2 - fix(watcher.node)
+Defer events during initial scan, track full event sequences, and harden watcher shutdown
+
+- Defer fs.watch events that arrive during the initial directory scan and process them after the scan completes to avoid race conditions where watchedFiles isn't populated.
+- Debounce now tracks the full sequence of events per file (rename/change) instead of collapsing to the last event, preventing intermediate events from being lost.
+- Detect delete+recreate via inode changes and emit unlink then add when appropriate; handle rapid create+delete sequences by emitting both events.
+- During stop(), cancel pending debounced emits before flipping _isWatching and make handleFsEvent return early when watcher is stopped to prevent orphaned timeouts and post-stop emits.
+- Add verbose logging of event sequences to aid debugging of complex fs event scenarios.
+- Update tests to expect unlink + add for inode replacement scenarios.
+- Version bump from 6.2.1 → 6.2.2
+
+## 2025-12-10 - 6.2.1 - fix(watcher.node)
+Handle fs.watch close without spurious restarts; add tests and improve test runner
+
+- Prevent spurious restarts and noisy warnings on fs.watch 'close' by checking the internal isWatching flag before logging and restarting (ts/watchers/watcher.node.ts).
+- Add comprehensive test suites covering basic operations, inode-change detection, atomic writes and stress scenarios (test/test.basic.ts, test/test.inode.ts, test/test.stress.ts).
+- Remove outdated test (test/test.ts) and delete the test asset test/assets/hi.txt.
+- Update test script in package.json to enable verbose logging, write a logfile and increase timeout to 120s to reduce flakiness in test runs.
+
 ## 2025-12-10 - 6.2.0 - feat(watchers)
 Improve Node watcher robustness: file-level inode tracking, abortable restarts, restart race guards, and untracked-file handling
 

package.json

@@ -1,12 +1,12 @@
 {
   "name": "@push.rocks/smartwatch",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "private": false,
   "description": "A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "scripts": {
-    "test": "(npm run prepareTest && tstest test/)",
+    "test": "(npm run prepareTest && tstest test/ --verbose --logfile --timeout 120)",
     "prepareTest": "(rm -f ./test/assets/hi.txt)",
     "build": "tsbuild tsfolders",
     "buildDocs": "tsdoc"
@@ -29,6 +29,7 @@
     "@push.rocks/smartenv": "^6.0.0",
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartrx": "^3.0.10",
+    "chokidar": "^5.0.0",
     "picomatch": "^4.0.3"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -20,6 +20,9 @@ importers:
       '@push.rocks/smartrx':
         specifier: ^3.0.10
         version: 3.0.10
+      chokidar:
+        specifier: ^5.0.0
+        version: 5.0.0
       picomatch:
         specifier: ^4.0.3
         version: 4.0.3
@@ -2199,6 +2202,10 @@ packages:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
 
+  chokidar@5.0.0:
+    resolution: {integrity: sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==}
+    engines: {node: '>= 20.19.0'}
+
   chromium-bidi@5.1.0:
     resolution: {integrity: sha512-9MSRhWRVoRPDG0TgzkHrshFSJJNZzfY5UFqUMuksg7zL1yoZIZ3jLB0YAgHclbiAxPI86pBnwDX1tbzoiV8aFw==}
     peerDependencies:
@@ -3631,6 +3638,10 @@ packages:
     resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
     engines: {node: '>= 14.18.0'}
 
+  readdirp@5.0.0:
+    resolution: {integrity: sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ==}
+    engines: {node: '>= 20.19.0'}
+
   reflect-metadata@0.2.2:
     resolution: {integrity: sha512-urBwgfrvVP/eAyXx4hluJivBKzuEbSQs9rKWCrCkbSxNv8mxPcUZKeuoF3Uy4mJl3Lwprp6yy5/39VWigZ4K6Q==}
 
@@ -7900,6 +7911,10 @@ snapshots:
     dependencies:
       readdirp: 4.1.2
 
+  chokidar@5.0.0:
+    dependencies:
+      readdirp: 5.0.0
+
   chromium-bidi@5.1.0(devtools-protocol@0.0.1452169):
     dependencies:
       devtools-protocol: 0.0.1452169
@@ -9627,6 +9642,8 @@ snapshots:
 
   readdirp@4.1.2: {}
 
+  readdirp@5.0.0: {}
+
   reflect-metadata@0.2.2: {}
 
   regenerator-runtime@0.14.1: {}

readme.hints.md

@@ -1,14 +1,16 @@
-# smartchok - Technical Hints
+# smartwatch - Technical Hints
 
-## Native File Watching (v2.0.0+)
+## Native File Watching (v6.0.0+)
 
-The module now uses native file watching APIs instead of chokidar, providing cross-runtime support for Node.js, Deno, and Bun.
+The module provides cross-runtime file watching support:
+- **Node.js/Bun**: Uses [chokidar](https://github.com/paulmillr/chokidar) v5
+- **Deno**: Uses native `Deno.watchFs()`
 
 ### Exported Class
 
-The package exports the `Smartwatch` class (not `Smartchok`):
+The package exports the `Smartwatch` class:
 ```typescript
-import { Smartwatch } from '@push.rocks/smartchok';
+import { Smartwatch } from '@push.rocks/smartwatch';
 ```
 
 ### Architecture
@@ -16,119 +18,74 @@ import { Smartwatch } from '@push.rocks/smartchok';
 ```
 ts/
 ├── smartwatch.classes.smartwatch.ts   # Main Smartwatch class
-├── smartwatch.plugins.ts              # Dependencies (smartenv, picomatch, etc.)
+├── smartwatch.plugins.ts              # Dependencies
 ├── watchers/
 │   ├── index.ts                       # Factory with runtime detection
 │   ├── interfaces.ts                  # IWatcher interface and types
-│   ├── watcher.node.ts                # Node.js/Bun implementation (fs.watch)
-│   └── watcher.deno.ts                # Deno implementation (Deno.watchFs)
+│   ├── watcher.node.ts                # Node.js/Bun: chokidar wrapper
+│   └── watcher.deno.ts                # Deno: Deno.watchFs wrapper
 └── utils/
     └── write-stabilizer.ts            # awaitWriteFinish polling implementation
 ```
 
 ### Runtime Detection
 
-Uses `@push.rocks/smartenv` v6.x for runtime detection:
-- **Node.js/Bun**: Uses native `fs.watch()` with `{ recursive: true }`
+Uses `@push.rocks/smartenv` for runtime detection:
+- **Node.js/Bun**: Uses chokidar (battle-tested file watcher)
 - **Deno**: Uses `Deno.watchFs()` async iterable
 
 ### Dependencies
 
-- **picomatch**: Glob pattern matching (zero deps, well-maintained)
-- **@push.rocks/smartenv**: Runtime detection (Node.js, Deno, Bun)
+- **chokidar**: Battle-tested file watcher for Node.js/Bun
+- **picomatch**: Glob pattern matching (zero deps)
+- **@push.rocks/smartenv**: Runtime detection
 - **@push.rocks/smartrx**: RxJS Subject/Observable management
 - **@push.rocks/smartpromise**: Deferred promise utilities
 - **@push.rocks/lik**: Stringmap for pattern storage
 
-### Why picomatch?
+### Chokidar Features (Node.js/Bun)
 
-Native file watching APIs don't support glob patterns. Picomatch provides glob pattern matching with:
-- Zero dependencies
-- 164M+ weekly downloads
-- Excellent security profile
-- Full glob syntax support
+The Node.js watcher (`ts/watchers/watcher.node.ts`) is a thin ~100 line wrapper around chokidar v5:
+
+```typescript
+chokidar.watch(paths, {
+  persistent: true,
+  ignoreInitial: false,
+  followSymlinks: options.followSymlinks,
+  depth: options.depth,
+  atomic: true,  // Handles atomic writes (delete+recreate, temp+rename)
+  awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+});
+```
+
+**Chokidar handles all edge cases:**
+- Atomic writes (temp file + rename pattern) → emits single 'change' event
+- Delete + recreate detection → emits single 'change' event
+- Inode tracking
+- Cross-platform differences (inotify, FSEvents, etc.)
+- Debouncing
+- Write stabilization
+- ENOSPC (inotify limit) errors
 
 ### Event Handling
 
-Native events are normalized to a consistent interface:
+Events are normalized across all runtimes:
 
-| Node.js/Bun Event | Deno Event | Normalized Event |
-|-------------------|------------|------------------|
-| `rename` (file exists) | `create` | `add` |
-| `rename` (file gone) | `remove` | `unlink` |
-| `change` | `modify` | `change` |
-
-### awaitWriteFinish Implementation
-
-The `WriteStabilizer` class replaces chokidar's built-in write stabilization:
-- Polls file size until stable (configurable threshold: 300ms default)
-- Configurable poll interval (100ms default)
-- Handles file deletion during write detection
+| Event | Description |
+|-------|-------------|
+| `add` | File added |
+| `change` | File modified |
+| `unlink` | File removed |
+| `addDir` | Directory added |
+| `unlinkDir` | Directory removed |
+| `ready` | Initial scan complete |
+| `error` | Error occurred |
 
 ### Platform Requirements
 
-- **Node.js 20+**: Required for native recursive watching on all platforms
+- **Node.js 20+**: Required for chokidar v5
 - **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 based on learnings from [chokidar](https://github.com/paulmillr/chokidar) and known [fs.watch issues](https://github.com/nodejs/node/issues/47058):
-
-**Auto-restart on failure:**
-- Watchers automatically restart when errors occur
-- Exponential backoff (1s → 30s max)
-- Maximum 3 retry attempts before giving up
-- **v6.2.0+**: Race condition guards prevent orphan watchers when `stop()` is called during restart
-
-**Inode tracking (critical for long-running watchers):**
-- `fs.watch()` watches the **inode**, not the path!
-- When directories are replaced (git checkout, atomic saves), the inode changes
-- Health check detects inode changes and restarts the watcher
-- **v6.2.0+**: File-level inode tracking detects delete+recreate (common editor save pattern)
-- This is the most common cause of "watcher stops working after some time"
-
-**Health check monitoring:**
-- 30-second periodic health checks
-- Detects when watched paths disappear
-- Detects inode changes (directory replacement)
-- Detects ENOSPC errors (inotify limit exceeded)
-- **v6.2.0+**: Protected against dual-restart race conditions (health check + error handler)
-
-**ENOSPC detection (Linux inotify limit):**
-- Detects when `/proc/sys/fs/inotify/max_user_watches` is exceeded
-- Logs fix command: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`
-
-**Error isolation:**
-- Subscriber errors don't crash the watcher
-- All events emitted via `safeEmit()` with try-catch
-
-**Untracked file handling (v6.2.0+):**
-- Files created after initial scan are properly detected
-- Untracked file deletions emit `unlink` events instead of being silently dropped
-
-**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
-[smartwatch] Inode changed for ./src: 12345 -> 67890
-[smartwatch] fs.watch watches inode, not path - restarting watcher
-[smartwatch] File inode changed (delete+recreate): ./src/file.ts
-```
-
-### Known fs.watch Limitations
-
-1. **Watches inode, not path** - If a directory is replaced, watcher goes stale
-2. **inotify limits on Linux** - Default `max_user_watches` (8192) may be too low
-3. **No events for some atomic writes** - Some editors' save patterns may not trigger events
-4. **Platform differences** - Linux uses inotify, macOS uses FSEvents/kqueue
+- **Bun**: Uses Node.js compatibility layer with chokidar
 
 ### Testing
 
@@ -136,10 +93,20 @@ Example log output:
 pnpm test
 ```
 
+Test files:
+- **test.basic.ts** - Core functionality (add, change, unlink events)
+- **test.inode.ts** - Atomic write detection (delete+recreate, temp+rename)
+- **test.stress.ts** - Rapid modifications, many files, interleaved operations
+
 Tests verify:
 - Creating Smartwatch instance
 - Adding glob patterns
-- Receiving 'add' events for new files
+- Receiving 'add', 'change', 'unlink' events
+- Atomic write detection (delete+recreate → change event)
+- Temp file + rename pattern detection
+- Rapid file modifications (debouncing)
+- Many files created rapidly
+- Interleaved add/change/delete operations
 - Graceful shutdown
 
 ## Dev Dependencies

test/assets/hi.txt

@@ -1 +0,0 @@
-HI

test/test.basic.ts

@@ -0,0 +1,159 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as smartwatch from '../ts/index.js';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartrx from '@push.rocks/smartrx';
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Skip in CI
+if (process.env.CI) {
+  process.exit(0);
+}
+
+const TEST_DIR = './test/assets';
+
+// Helper to delay
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// Helper to wait for an event with timeout
+async function waitForEvent<T>(
+  observable: smartrx.rxjs.Observable<T>,
+  timeoutMs: number = 5000
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      subscription.unsubscribe();
+      reject(new Error(`Timeout waiting for event after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const subscription = observable.subscribe((value) => {
+      clearTimeout(timeout);
+      subscription.unsubscribe();
+      resolve(value);
+    });
+  });
+}
+
+// Helper to wait for a specific file's event (filters by filename)
+async function waitForFileEvent<T extends [string, ...any[]]>(
+  observable: smartrx.rxjs.Observable<T>,
+  expectedFile: string,
+  timeoutMs: number = 5000
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      subscription.unsubscribe();
+      reject(new Error(`Timeout waiting for event on ${expectedFile} after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const subscription = observable.subscribe((value) => {
+      const [filePath] = value;
+      if (filePath.includes(expectedFile)) {
+        clearTimeout(timeout);
+        subscription.unsubscribe();
+        resolve(value);
+      }
+      // Otherwise keep waiting for the right file
+    });
+  });
+}
+
+let testSmartwatch: smartwatch.Smartwatch;
+
+// ===========================================
+// BASIC TESTS
+// ===========================================
+
+tap.test('should create a new instance', async () => {
+  testSmartwatch = new smartwatch.Smartwatch([]);
+  expect(testSmartwatch).toBeInstanceOf(smartwatch.Smartwatch);
+});
+
+tap.test('should add paths and start watching', async () => {
+  testSmartwatch.add([`${TEST_DIR}/**/*.txt`]);
+  await testSmartwatch.start();
+  expect(testSmartwatch.status).toEqual('watching');
+  // Wait for chokidar to be ready
+  await delay(500);
+});
+
+tap.test('should detect ADD event for new files', async () => {
+  const addObservable = await testSmartwatch.getObservableFor('add');
+
+  // Subscribe FIRST, then create file
+  const eventPromise = waitForFileEvent(addObservable, 'add-test.txt');
+
+  // Create a new file
+  const testFile = path.join(TEST_DIR, 'add-test.txt');
+  await smartfile.memory.toFs('test content', testFile);
+
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('add-test.txt');
+
+  // Cleanup
+  await fs.promises.unlink(testFile);
+  await delay(200);
+});
+
+tap.test('should detect CHANGE event for modified files', async () => {
+  // First create the file
+  const testFile = path.join(TEST_DIR, 'change-test.txt');
+  await smartfile.memory.toFs('initial content', testFile);
+
+  // Wait for add event to complete
+  await delay(300);
+
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const eventPromise = waitForFileEvent(changeObservable, 'change-test.txt');
+
+  // Modify the file
+  await smartfile.memory.toFs('modified content', testFile);
+
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('change-test.txt');
+
+  // Cleanup
+  await fs.promises.unlink(testFile);
+  await delay(200);
+});
+
+tap.test('should detect UNLINK event for deleted files', async () => {
+  // First create the file
+  const testFile = path.join(TEST_DIR, 'unlink-test.txt');
+  await smartfile.memory.toFs('to be deleted', testFile);
+
+  // Wait for add event to complete
+  await delay(300);
+
+  const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
+
+  // Use file-specific wait to handle any pending unlinks from other tests
+  const eventPromise = waitForFileEvent(unlinkObservable, 'unlink-test.txt');
+
+  // Delete the file
+  await fs.promises.unlink(testFile);
+
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('unlink-test.txt');
+});
+
+tap.test('should stop the watch process', async () => {
+  await testSmartwatch.stop();
+  expect(testSmartwatch.status).toEqual('idle');
+});
+
+tap.test('cleanup: remove any remaining test files', async () => {
+  const files = await fs.promises.readdir(TEST_DIR);
+  for (const file of files) {
+    if (file.startsWith('add-') || file.startsWith('change-') || file.startsWith('unlink-')) {
+      try {
+        await fs.promises.unlink(path.join(TEST_DIR, file));
+      } catch {
+        // Ignore
+      }
+    }
+  }
+});
+
+export default tap.start();

test/test.inode.ts

@@ -0,0 +1,143 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as smartwatch from '../ts/index.js';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartrx from '@push.rocks/smartrx';
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Skip in CI
+if (process.env.CI) {
+  process.exit(0);
+}
+
+const TEST_DIR = './test/assets';
+
+// Helper to delay
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// Helper to wait for an event with timeout (filters by filename)
+async function waitForFileEvent<T extends [string, ...any[]]>(
+  observable: smartrx.rxjs.Observable<T>,
+  expectedFile: string,
+  timeoutMs: number = 5000
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      subscription.unsubscribe();
+      reject(new Error(`Timeout waiting for event on ${expectedFile} after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const subscription = observable.subscribe((value) => {
+      const [filePath] = value;
+      if (filePath.includes(expectedFile)) {
+        clearTimeout(timeout);
+        subscription.unsubscribe();
+        resolve(value);
+      }
+    });
+  });
+}
+
+let testSmartwatch: smartwatch.Smartwatch;
+
+// ===========================================
+// INODE CHANGE DETECTION TESTS
+// ===========================================
+
+tap.test('setup: start watcher', async () => {
+  testSmartwatch = new smartwatch.Smartwatch([`${TEST_DIR}/**/*.txt`]);
+  await testSmartwatch.start();
+  expect(testSmartwatch.status).toEqual('watching');
+  // Wait for chokidar to be ready
+  await delay(500);
+});
+
+tap.test('should detect delete+recreate as change event (atomic handling)', async () => {
+  // Chokidar with atomic: true handles delete+recreate as a single change event
+  // This is the expected behavior for editor save patterns
+  const testFile = path.join(TEST_DIR, 'inode-test.txt');
+
+  // Clean up any leftover file from previous runs
+  try { await fs.promises.unlink(testFile); } catch {}
+  await delay(100);
+
+  // Create initial file
+  await smartfile.memory.toFs('initial content', testFile);
+  await delay(300);
+
+  // Get the initial inode
+  const initialStats = await fs.promises.stat(testFile);
+  const initialInode = initialStats.ino;
+  console.log(`[test] Initial inode: ${initialInode}`);
+
+  // Chokidar's atomic handling will emit a single 'change' event
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const eventPromise = waitForFileEvent(changeObservable, 'inode-test.txt', 3000);
+
+  // Delete and recreate (this creates a new inode)
+  await fs.promises.unlink(testFile);
+  await smartfile.memory.toFs('recreated content', testFile);
+
+  // Check inode changed
+  const newStats = await fs.promises.stat(testFile);
+  const newInode = newStats.ino;
+  console.log(`[test] New inode: ${newInode}`);
+  expect(newInode).not.toEqual(initialInode);
+
+  // Chokidar detects this as a change (atomic write pattern)
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('inode-test.txt');
+  console.log(`[test] Detected change event for delete+recreate (atomic handling)`);
+
+  // Cleanup
+  await fs.promises.unlink(testFile);
+  await delay(200);
+});
+
+tap.test('should detect atomic write pattern (temp file + rename)', async () => {
+  // This simulates what Claude Code and many editors do:
+  // 1. Write to temp file (file.txt.tmp.12345)
+  // 2. Rename temp file to target file
+  const testFile = path.join(TEST_DIR, 'atomic-test.txt');
+  const tempFile = path.join(TEST_DIR, 'atomic-test.txt.tmp.12345');
+
+  // Create initial file
+  await smartfile.memory.toFs('initial content', testFile);
+  await delay(300);
+
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const eventPromise = waitForFileEvent(changeObservable, 'atomic-test.txt', 3000);
+
+  // Atomic write: create temp file then rename
+  await smartfile.memory.toFs('atomic content', tempFile);
+  await fs.promises.rename(tempFile, testFile);
+
+  // Should detect the change to the target file
+  const [filePath] = await eventPromise;
+  expect(filePath).toInclude('atomic-test.txt');
+  expect(filePath).not.toInclude('.tmp.');
+
+  // Cleanup
+  await fs.promises.unlink(testFile);
+});
+
+tap.test('teardown: stop watcher', async () => {
+  await testSmartwatch.stop();
+  expect(testSmartwatch.status).toEqual('idle');
+});
+
+tap.test('cleanup: remove test files', async () => {
+  const files = await fs.promises.readdir(TEST_DIR);
+  for (const file of files) {
+    if (file.startsWith('inode-') || file.startsWith('atomic-')) {
+      try {
+        await fs.promises.unlink(path.join(TEST_DIR, file));
+      } catch {
+        // Ignore
+      }
+    }
+  }
+});
+
+export default tap.start();

test/test.stress.ts

@@ -0,0 +1,176 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+import * as smartwatch from '../ts/index.js';
+import * as smartfile from '@push.rocks/smartfile';
+import * as smartrx from '@push.rocks/smartrx';
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Skip in CI
+if (process.env.CI) {
+  process.exit(0);
+}
+
+const TEST_DIR = './test/assets';
+
+// Helper to delay
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+// Helper to collect events
+function collectEvents<T>(
+  observable: smartrx.rxjs.Observable<T>,
+  durationMs: number
+): Promise<T[]> {
+  return new Promise((resolve) => {
+    const events: T[] = [];
+    const subscription = observable.subscribe((value) => {
+      events.push(value);
+    });
+
+    setTimeout(() => {
+      subscription.unsubscribe();
+      resolve(events);
+    }, durationMs);
+  });
+}
+
+let testSmartwatch: smartwatch.Smartwatch;
+
+// ===========================================
+// STRESS TESTS
+// ===========================================
+
+tap.test('setup: start watcher', async () => {
+  testSmartwatch = new smartwatch.Smartwatch([`${TEST_DIR}/**/*.txt`]);
+  await testSmartwatch.start();
+  expect(testSmartwatch.status).toEqual('watching');
+  // Wait for chokidar to be ready
+  await delay(500);
+});
+
+tap.test('STRESS: rapid file modifications', async () => {
+  const testFile = path.join(TEST_DIR, 'stress-rapid.txt');
+
+  // Create initial file
+  await smartfile.memory.toFs('initial', testFile);
+  await delay(200);
+
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+
+  // Rapidly modify the file 20 times
+  const RAPID_CHANGES = 20;
+  const eventCollector = collectEvents(changeObservable, 3000);
+
+  for (let i = 0; i < RAPID_CHANGES; i++) {
+    await smartfile.memory.toFs(`content ${i}`, testFile);
+    await delay(10); // 10ms between writes
+  }
+
+  const events = await eventCollector;
+  console.log(`[test] Rapid changes: sent ${RAPID_CHANGES}, received ${events.length} events`);
+
+  // Due to debouncing, we won't get all events, but we should get at least some
+  expect(events.length).toBeGreaterThan(0);
+
+  // Cleanup
+  await fs.promises.unlink(testFile);
+});
+
+tap.test('STRESS: many files created rapidly', async () => {
+  const FILE_COUNT = 20;
+  const files: string[] = [];
+
+  const addObservable = await testSmartwatch.getObservableFor('add');
+  const eventCollector = collectEvents(addObservable, 5000);
+
+  // Create many files rapidly
+  for (let i = 0; i < FILE_COUNT; i++) {
+    const file = path.join(TEST_DIR, `stress-many-${i}.txt`);
+    files.push(file);
+    await smartfile.memory.toFs(`content ${i}`, file);
+    await delay(20); // 20ms between creates
+  }
+
+  const events = await eventCollector;
+  console.log(`[test] Many files: created ${FILE_COUNT}, detected ${events.length} events`);
+
+  // Should detect most or all files
+  expect(events.length).toBeGreaterThanOrEqual(FILE_COUNT * 0.8); // Allow 20% tolerance
+
+  // Cleanup all files
+  for (const file of files) {
+    try {
+      await fs.promises.unlink(file);
+    } catch {
+      // Ignore if already deleted
+    }
+  }
+});
+
+tap.test('STRESS: interleaved add/change/delete operations', async () => {
+  const testFiles = [
+    path.join(TEST_DIR, 'stress-interleave-1.txt'),
+    path.join(TEST_DIR, 'stress-interleave-2.txt'),
+    path.join(TEST_DIR, 'stress-interleave-3.txt'),
+  ];
+
+  // Create initial files
+  for (const file of testFiles) {
+    await smartfile.memory.toFs('initial', file);
+  }
+  await delay(300);
+
+  const addObservable = await testSmartwatch.getObservableFor('add');
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
+
+  const addEvents = collectEvents(addObservable, 3000);
+  const changeEvents = collectEvents(changeObservable, 3000);
+  const unlinkEvents = collectEvents(unlinkObservable, 3000);
+
+  // Interleaved operations
+  await smartfile.memory.toFs('changed 1', testFiles[0]); // change
+  await delay(50);
+  await fs.promises.unlink(testFiles[1]); // delete
+  await delay(50);
+  await smartfile.memory.toFs('recreated 1', testFiles[1]); // add (recreate)
+  await delay(50);
+  await smartfile.memory.toFs('changed 2', testFiles[2]); // change
+  await delay(50);
+
+  const [adds, changes, unlinks] = await Promise.all([addEvents, changeEvents, unlinkEvents]);
+
+  console.log(`[test] Interleaved: adds=${adds.length}, changes=${changes.length}, unlinks=${unlinks.length}`);
+
+  // Should have detected some events of each type
+  expect(changes.length).toBeGreaterThan(0);
+
+  // Cleanup
+  for (const file of testFiles) {
+    try {
+      await fs.promises.unlink(file);
+    } catch {
+      // Ignore
+    }
+  }
+});
+
+tap.test('teardown: stop watcher', async () => {
+  await testSmartwatch.stop();
+  expect(testSmartwatch.status).toEqual('idle');
+});
+
+tap.test('cleanup: remove stress test files', async () => {
+  const files = await fs.promises.readdir(TEST_DIR);
+  for (const file of files) {
+    if (file.startsWith('stress-')) {
+      try {
+        await fs.promises.unlink(path.join(TEST_DIR, file));
+      } catch {
+        // Ignore
+      }
+    }
+  }
+});
+
+export default tap.start();

test/test.ts

@@ -1,50 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import * as smartwatch from '../ts/index.js';
-import * as smartfile from '@push.rocks/smartfile';
-import * as smartpromise from '@push.rocks/smartpromise';
-import * as smartrx from '@push.rocks/smartrx';
-
-import * as fs from 'fs';
-
-// the module to test
-if (process.env.CI) {
-  process.exit(0);
-}
-
-let testSmartwatch: smartwatch.Smartwatch;
-let testAddObservable: smartrx.rxjs.Observable<[string, fs.Stats]>;
-let testSubscription: smartrx.rxjs.Subscription;
-tap.test('should create a new instance', async () => {
-  testSmartwatch = new smartwatch.Smartwatch([]);
-  expect(testSmartwatch).toBeInstanceOf(smartwatch.Smartwatch);
-});
-
-tap.test('should add some files to watch and start', async () => {
-  testSmartwatch.add(['./test/**/*.txt']);
-  await testSmartwatch.start()
-  testSmartwatch.add(['./test/**/*.md']);
-});
-
-tap.test('should get an observable for a certain event', async () => {
-  await testSmartwatch.getObservableFor('add').then(async (observableArg) => {
-    testAddObservable = observableArg;
-  });
-});
-
-tap.test('should register an add operation', async () => {
-  let testDeferred = smartpromise.defer();
-  testSubscription = testAddObservable.subscribe(pathArg => {
-    const pathResult = pathArg[0];
-    console.log(pathResult);
-    testDeferred.resolve();
-  });
-  smartfile.memory.toFs('HI', './test/assets/hi.txt');
-  await testDeferred.promise;
-});
-
-tap.test('should stop the watch process', async (tools) => {
-  await tools.delayFor(10000);
-  testSmartwatch.stop();
-});
-
-export default tap.start();

ts/00_commitinfo_data.ts

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

ts/watchers/interfaces.ts

@@ -28,6 +28,12 @@ export interface IWatcherOptions {
   followSymlinks: boolean;
   /** Debounce time in ms - events for the same file within this window are coalesced */
   debounceMs: number;
+  /** Whether to wait for writes to stabilize before emitting events */
+  awaitWriteFinish?: boolean;
+  /** How long file size must remain constant before emitting event (ms) */
+  stabilityThreshold?: number;
+  /** How often to poll file size during write detection (ms) */
+  pollInterval?: number;
 }
 
 /**

ts/watchers/watcher.node.ts

@@ -1,252 +1,80 @@
 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 * as chokidar from 'chokidar';
+import type { IWatcher, IWatcherOptions, IWatchEvent } from './interfaces.js';
 
 /**
- * Node.js/Bun file watcher using native fs.watch API
+ * Node.js/Bun file watcher using chokidar
+ *
+ * Chokidar handles all the edge cases:
+ * - Atomic writes (temp file + rename)
+ * - Inode tracking
+ * - Cross-platform differences
+ * - Debouncing
+ * - Write stabilization
  */
 export class NodeWatcher implements IWatcher {
-  private watchers: Map<string, fs.FSWatcher> = new Map();
-  private watchedFiles: Set<string> = new Set();
+  private watcher: chokidar.FSWatcher | null = null;
   private _isWatching = false;
 
-  // 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;
-
-  // Inode tracking - detect when directories are replaced (atomic saves, etc.)
-  // fs.watch watches the inode, not the path. If inode changes, we need to restart.
-  private watchedInodes: Map<string, bigint> = new Map();
-
-  // File inode tracking - detect when individual files are deleted and recreated
-  // This is critical: editors delete+recreate files, fs.watch watches OLD inode!
-  // See: https://github.com/paulmillr/chokidar/issues/972
-  private fileInodes: Map<string, bigint> = new Map();
-
-  // Abort controllers for pending restart delays - prevents orphan watchers on stop()
-  private restartAbortControllers: Map<string, AbortController> = new Map();
-
-  // Prevent concurrent restarts for the same path (health check + error can race)
-  private restartingPaths: Set<string> = new Set();
-
-  // 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) {}
 
-  /**
-   * 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
-   * Includes guards against:
-   * - Dual restart race condition (health check + error handler calling simultaneously)
-   * - Orphan watchers when stop() is called during restart delay
-   */
-  private async restartWatcher(basePath: string, error: Error): Promise<void> {
-    // Guard: Prevent concurrent restarts for the same path
-    if (this.restartingPaths.has(basePath)) {
-      console.log(`[smartwatch] Restart already in progress for ${basePath}, skipping`);
-      return;
-    }
-    this.restartingPaths.add(basePath);
-
-    try {
-      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 with AbortController (so stop() can cancel)
-      const delay = this.restartDelays.get(basePath) || NodeWatcher.INITIAL_RESTART_DELAY;
-      console.log(`[smartwatch] Waiting ${delay}ms before restart...`);
-
-      const abortController = new AbortController();
-      this.restartAbortControllers.set(basePath, abortController);
-
-      try {
-        await new Promise<void>((resolve, reject) => {
-          const timeout = setTimeout(resolve, delay);
-          abortController.signal.addEventListener('abort', () => {
-            clearTimeout(timeout);
-            reject(new Error('Restart aborted by stop()'));
-          });
-        });
-      } catch (abortError) {
-        console.log(`[smartwatch] Restart aborted for ${basePath}`);
-        return; // stop() was called, don't continue
-      } finally {
-        this.restartAbortControllers.delete(basePath);
-      }
-
-      // Double-check we're still watching after the delay
-      if (!this._isWatching) {
-        console.log(`[smartwatch] Watcher stopped during restart delay, aborting`);
-        return;
-      }
-
-      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);
-        // Clear restartingPaths before recursive call
-        this.restartingPaths.delete(basePath);
-        this.restartWatcher(basePath, restartError as Error); // Recursive retry
-        return; // Don't delete from restartingPaths again in finally
-      }
-    } finally {
-      this.restartingPaths.delete(basePath);
-    }
-  }
-
-  /**
-   * Start periodic health checks to detect silent failures
-   * Checks for:
-   * 1. Path no longer exists
-   * 2. Inode changed (directory was replaced - fs.watch watches inode, not path!)
-   */
-  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) {
-        try {
-          const stats = await fs.promises.stat(basePath);
-          const currentInode = stats.ino;
-          const previousInode = this.watchedInodes.get(basePath);
-
-          if (!stats) {
-            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'));
-          } else if (previousInode !== undefined && BigInt(currentInode) !== previousInode) {
-            // CRITICAL: Inode changed! fs.watch is now watching a stale inode.
-            // This happens when the directory is replaced (atomic operations, git checkout, etc.)
-            console.warn(`[smartwatch] Inode changed for ${basePath}: ${previousInode} -> ${currentInode}`);
-            console.warn('[smartwatch] fs.watch watches inode, not path - restarting watcher');
-            this.restartWatcher(basePath, new Error('Inode changed - directory was replaced'));
-          }
-        } catch (error: any) {
-          if (error.code === 'ENOENT') {
-            console.error(`[smartwatch] Health check failed: ${basePath} no longer exists`);
-            this.restartWatcher(basePath, new Error('Watched path disappeared'));
-          } else if (error.code === 'ENOSPC') {
-            // inotify watch limit exceeded - critical system issue
-            console.error(`[smartwatch] ENOSPC: inotify watch limit exceeded!`);
-            console.error('[smartwatch] Fix: echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p');
-            this.safeEmit({ type: 'error', path: basePath, error });
-          } else {
-            console.error(`[smartwatch] Health check error for ${basePath}:`, error);
-          }
-        }
-      }
-    }, 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 {
     return this._isWatching;
   }
 
   async start(): Promise<void> {
-    if (this._isWatching) {
-      return;
-    }
+    if (this._isWatching) return;
 
-    console.log(`[smartwatch] Starting watcher for ${this.options.basePaths.length} base path(s)...`);
+    console.log(`[smartwatch] Starting chokidar watcher for ${this.options.basePaths.length} base path(s)...`);
 
     try {
-      // Start watching each base path
-      for (const basePath of this.options.basePaths) {
-        await this.watchPath(basePath, 0);
-      }
+      // Resolve all paths to absolute
+      const absolutePaths = this.options.basePaths.map(p => path.resolve(p));
+
+      this.watcher = chokidar.watch(absolutePaths, {
+        persistent: true,
+        ignoreInitial: false,
+        followSymlinks: this.options.followSymlinks,
+        depth: this.options.depth,
+        atomic: true, // Handle atomic writes
+        awaitWriteFinish: this.options.awaitWriteFinish ? {
+          stabilityThreshold: this.options.stabilityThreshold || 300,
+          pollInterval: this.options.pollInterval || 100,
+        } : false,
+      });
+
+      // Wire up all events
+      this.watcher
+        .on('add', (filePath: string, stats?: fs.Stats) => {
+          this.safeEmit({ type: 'add', path: filePath, stats });
+        })
+        .on('change', (filePath: string, stats?: fs.Stats) => {
+          this.safeEmit({ type: 'change', path: filePath, stats });
+        })
+        .on('unlink', (filePath: string) => {
+          this.safeEmit({ type: 'unlink', path: filePath });
+        })
+        .on('addDir', (filePath: string, stats?: fs.Stats) => {
+          this.safeEmit({ type: 'addDir', path: filePath, stats });
+        })
+        .on('unlinkDir', (filePath: string) => {
+          this.safeEmit({ type: 'unlinkDir', path: filePath });
+        })
+        .on('error', (error: Error) => {
+          console.error('[smartwatch] Chokidar error:', error);
+          this.safeEmit({ type: 'error', path: '', error });
+        })
+        .on('ready', () => {
+          console.log('[smartwatch] Chokidar ready - initial scan complete');
+          this.safeEmit({ type: 'ready', path: '' });
+        });
 
       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.safeEmit({ type: 'ready', path: '' });
-      console.log(`[smartwatch] Watcher started with ${this.watchers.size} active watcher(s)`);
+      console.log('[smartwatch] Watcher started');
     } catch (error: any) {
       console.error('[smartwatch] Failed to start watcher:', error);
       this.safeEmit({ type: 'error', path: '', error });
@@ -256,316 +84,22 @@ export class NodeWatcher implements IWatcher {
 
   async stop(): Promise<void> {
     console.log('[smartwatch] Stopping watcher...');
+
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+
     this._isWatching = false;
-
-    // Stop health check monitoring
-    this.stopHealthCheck();
-
-    // Abort all pending restart delays (prevents orphan watchers)
-    for (const [path, controller] of this.restartAbortControllers) {
-      console.log(`[smartwatch] Aborting pending restart for: ${path}`);
-      controller.abort();
-    }
-    this.restartAbortControllers.clear();
-
-    // 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();
-
-    // Clear all tracking state
-    this.restartDelays.clear();
-    this.restartAttempts.clear();
-    this.watchedInodes.clear();
-    this.fileInodes.clear();
-    this.restartingPaths.clear();
-
     console.log('[smartwatch] Watcher stopped');
   }
 
-  /**
-   * Start watching a path (file or directory)
-   */
-  private async watchPath(watchPath: string, depth: number): Promise<void> {
-    if (depth > this.options.depth) {
-      return;
-    }
-
+  /** Safely emit an event, isolating subscriber errors */
+  private safeEmit(event: IWatchEvent): void {
     try {
-      const stats = await this.statSafe(watchPath);
-      if (!stats) {
-        return;
-      }
-
-      if (stats.isDirectory()) {
-        // Store inode for health check - fs.watch watches inode, not path!
-        // If inode changes (directory replaced), watcher becomes stale
-        this.watchedInodes.set(watchPath, BigInt(stats.ino));
-
-        // Watch the directory with recursive option (Node.js 20+ supports this on all platforms)
-        const watcher = fs.watch(
-          watchPath,
-          { recursive: true, persistent: true },
-          (eventType, filename) => {
-            if (filename) {
-              this.handleFsEvent(watchPath, filename, eventType);
-            }
-          }
-        );
-
-        watcher.on('error', (error: NodeJS.ErrnoException) => {
-          console.error(`[smartwatch] FSWatcher error event on ${watchPath}:`, error);
-
-          // Detect inotify watch limit exceeded - common cause of "stops working"
-          if (error.code === 'ENOSPC') {
-            console.error('[smartwatch] CRITICAL: inotify watch limit exceeded!');
-            console.error('[smartwatch] Fix with: echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p');
-          }
-
-          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) {
-      console.error(`[smartwatch] Failed to watch path ${watchPath}:`, error);
-      this.safeEmit({ type: 'error', path: watchPath, error });
+      this.events$.next(event);
+    } catch (error) {
+      console.error('[smartwatch] Subscriber threw error (isolated):', error);
     }
   }
-
-  /**
-   * Handle raw fs.watch events - debounce and normalize them
-   */
-  private handleFsEvent(
-    basePath: string,
-    filename: string,
-    eventType: 'rename' | 'change' | string
-  ): void {
-    const fullPath = path.join(basePath, filename);
-
-    // Skip temporary files - but ONLY pure temp files, not the target of atomic writes
-    // Atomic writes: editor writes to file.tmp.xxx then renames to file
-    // We need to detect the final file, so only skip files that ARE temp files
-    // and haven't been renamed to the real file yet
-    if (this.isTemporaryFile(fullPath)) {
-      // For temp files, we still want to track if they get renamed TO a real file
-      // The 'rename' event fires for both source and target, so we'll catch the real file
-      console.log(`[smartwatch] Skipping temp file event: ${filename}`);
-      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
-   *
-   * Handles file inode tracking to detect delete+recreate scenarios:
-   * - fs.watch watches the inode, not the path
-   * - When editors delete+recreate files, the inode changes
-   * - Without inode tracking, events for the new file would be missed
-   * - See: https://github.com/paulmillr/chokidar/issues/972
-   */
-  private async emitFileEvent(
-    fullPath: string,
-    eventType: 'rename' | 'change' | string
-  ): Promise<void> {
-    try {
-      const stats = await this.statSafe(fullPath);
-
-      if (eventType === 'rename') {
-        // 'rename' can mean add or unlink - check if file exists
-        if (stats) {
-          // File exists - it's either a new file or was renamed to this location
-          if (stats.isDirectory()) {
-            if (!this.watchedFiles.has(fullPath)) {
-              this.watchedFiles.add(fullPath);
-              this.safeEmit({ type: 'addDir', path: fullPath, stats });
-            }
-          } else {
-            const wasWatched = this.watchedFiles.has(fullPath);
-            const currentInode = BigInt(stats.ino);
-            const previousInode = this.fileInodes.get(fullPath);
-
-            // Track file inode for delete+recreate detection
-            this.fileInodes.set(fullPath, currentInode);
-            this.watchedFiles.add(fullPath);
-
-            // Check if file was recreated with different inode (delete+recreate scenario)
-            if (wasWatched && previousInode !== undefined && previousInode !== currentInode) {
-              console.log(`[smartwatch] File inode changed (delete+recreate): ${fullPath}`);
-              console.log(`[smartwatch]   Previous inode: ${previousInode}, current: ${currentInode}`);
-              // Emit as 'change' since the file content likely changed
-              this.safeEmit({ type: 'change', path: fullPath, stats });
-            } else {
-              this.safeEmit({
-                type: wasWatched ? 'change' : 'add',
-                path: fullPath,
-                stats
-              });
-            }
-          }
-        } else {
-          // File doesn't exist - it was deleted
-          if (this.watchedFiles.has(fullPath)) {
-            const wasDir = this.isKnownDirectory(fullPath);
-            this.watchedFiles.delete(fullPath);
-            this.fileInodes.delete(fullPath); // Clean up inode tracking
-            this.safeEmit({
-              type: wasDir ? 'unlinkDir' : 'unlink',
-              path: fullPath
-            });
-          } else {
-            // Fix #4: File wasn't tracked but was deleted - still emit event
-            // This handles files created after initial scan that we may have missed
-            console.log(`[smartwatch] Untracked file deleted: ${fullPath}`);
-            this.fileInodes.delete(fullPath);
-            this.safeEmit({ type: 'unlink', path: fullPath });
-          }
-        }
-      } else if (eventType === 'change') {
-        // File was modified
-        if (stats && !stats.isDirectory()) {
-          const wasWatched = this.watchedFiles.has(fullPath);
-          const currentInode = BigInt(stats.ino);
-          const previousInode = this.fileInodes.get(fullPath);
-
-          // Track file inode
-          this.fileInodes.set(fullPath, currentInode);
-
-          if (!wasWatched) {
-            // This is actually an 'add' - file wasn't being watched before
-            this.watchedFiles.add(fullPath);
-            this.safeEmit({ type: 'add', path: fullPath, stats });
-          } else if (previousInode !== undefined && previousInode !== currentInode) {
-            // Inode changed during 'change' event - file was replaced
-            console.log(`[smartwatch] File replaced (inode change on modify): ${fullPath}`);
-            this.safeEmit({ type: 'change', path: fullPath, stats });
-          } else {
-            this.safeEmit({ type: 'change', path: fullPath, stats });
-          }
-        } else if (!stats && this.watchedFiles.has(fullPath)) {
-          // File was deleted
-          this.watchedFiles.delete(fullPath);
-          this.fileInodes.delete(fullPath);
-          this.safeEmit({ type: 'unlink', path: fullPath });
-        } else if (!stats && !this.watchedFiles.has(fullPath)) {
-          // Fix #4: Untracked file deleted during 'change' event
-          console.log(`[smartwatch] Untracked file deleted (change event): ${fullPath}`);
-          this.fileInodes.delete(fullPath);
-          this.safeEmit({ type: 'unlink', path: fullPath });
-        }
-      }
-    } catch (error: any) {
-      this.safeEmit({ type: 'error', path: fullPath, error });
-    }
-  }
-
-  /**
-   * Scan directory and emit 'add' events for existing files
-   */
-  private async scanDirectory(dirPath: string, depth: number): Promise<void> {
-    if (depth > this.options.depth) {
-      return;
-    }
-
-    try {
-      const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
-
-      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) {
-          continue;
-        }
-
-        if (entry.isDirectory()) {
-          this.watchedFiles.add(fullPath);
-          this.safeEmit({ type: 'addDir', path: fullPath, stats });
-          await this.scanDirectory(fullPath, depth + 1);
-        } else if (entry.isFile()) {
-          this.watchedFiles.add(fullPath);
-          // Track file inode for delete+recreate detection
-          this.fileInodes.set(fullPath, BigInt(stats.ino));
-          this.safeEmit({ type: 'add', path: fullPath, stats });
-        }
-      }
-    } catch (error: any) {
-      if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
-        this.safeEmit({ type: 'error', path: dirPath, error });
-      }
-    }
-  }
-
-  /**
-   * Safely stat a path, returning null if it doesn't exist
-   */
-  private async statSafe(filePath: string): Promise<fs.Stats | null> {
-    try {
-      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;
-      }
-      // Log other errors (permission, I/O) but still return null
-      console.warn(`[smartwatch] statSafe warning for ${filePath}: ${error.code} - ${error.message}`);
-      return null;
-    }
-  }
-
-  /**
-   * Check if a path was known to be a directory (for proper unlink event type)
-   */
-  private isKnownDirectory(filePath: string): boolean {
-    // Check if any watched files are children of this path
-    for (const watched of this.watchedFiles) {
-      if (watched.startsWith(filePath + path.sep)) {
-        return true;
-      }
-    }
-    return false;
-  }
 }