v6.2.3

changelog.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 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.2.3",
   "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"

readme.hints.md

@@ -107,8 +107,27 @@ The Node.js watcher includes automatic recovery mechanisms based on learnings fr
 - Files created after initial scan are properly detected
 - Untracked file deletions emit `unlink` events instead of being silently dropped
 
+**Event Deferral During Initial Scan (v6.2.2+):**
+- Events are queued until initial scan completes
+- Prevents race conditions where events arrive before `watchedFiles` is populated
+- Deferred events are processed after scan completes
+
+**Event Sequence Tracking (v6.2.2+):**
+- Debounce now tracks ALL events in sequence, not just the last one
+- Prevents losing intermediate events (e.g., add→change→delete no longer loses add)
+- Intelligent processing of event sequences:
+  - Delete+recreate with inode change → emits `unlink` then `add`
+  - Rapid create+delete → emits both events
+  - Multiple changes → single `change` event (debouncing)
+
+**Post-Stop Event Guards (v6.2.2+):**
+- `handleFsEvent()` returns early if watcher is stopped
+- Pending emits are cleared BEFORE setting `_isWatching = false`
+- Prevents orphaned timeouts and events after `stop()`
+
 **Verbose logging:**
 - All lifecycle events logged with `[smartwatch]` prefix
+- Event sequences logged for debugging complex scenarios
 - Helps debug watcher issues in production
 
 Example log output:
@@ -118,9 +137,9 @@ Example log output:
 [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] Processing event sequence for ./src/file.ts: [rename, rename, change]
-[smartwatch] fs.watch watches inode, not path - restarting watcher
 [smartwatch] File inode changed (delete+recreate): ./src/file.ts
+[smartwatch]   Previous inode: 12345, current: 67890
 ```
 
 ### Known fs.watch Limitations

test/assets/hi.txt

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

test/test.basic.ts

@@ -0,0 +1,127 @@
+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);
+    });
+  });
+}
+
+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');
+});
+
+tap.test('should detect ADD event for new files', async () => {
+  const addObservable = await testSmartwatch.getObservableFor('add');
+  const eventPromise = waitForEvent(addObservable);
+
+  // 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);
+});
+
+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(200);
+
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const eventPromise = waitForEvent(changeObservable);
+
+  // 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);
+});
+
+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(200);
+
+  const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
+  const eventPromise = waitForEvent(unlinkObservable);
+
+  // 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,135 @@
+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);
+    });
+  });
+}
+
+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');
+});
+
+tap.test('should detect delete+recreate (inode change scenario)', async () => {
+  // This simulates what many editors do: delete file, create new file
+  const testFile = path.join(TEST_DIR, 'inode-test.txt');
+
+  // Create initial file
+  await smartfile.memory.toFs('initial content', testFile);
+  await delay(200);
+
+  // Get the initial inode
+  const initialStats = await fs.promises.stat(testFile);
+  const initialInode = initialStats.ino;
+  console.log(`[test] Initial inode: ${initialInode}`);
+
+  // With event sequence tracking, delete+recreate emits: unlink, then add
+  // This is more accurate than just emitting 'change'
+  const unlinkObservable = await testSmartwatch.getObservableFor('unlink');
+  const addObservable = await testSmartwatch.getObservableFor('add');
+  const unlinkPromise = waitForEvent(unlinkObservable, 3000);
+  const addPromise = waitForEvent(addObservable, 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);
+
+  // Should detect both unlink and add events for delete+recreate
+  const [[unlinkPath], [addPath]] = await Promise.all([unlinkPromise, addPromise]);
+  expect(unlinkPath).toInclude('inode-test.txt');
+  expect(addPath).toInclude('inode-test.txt');
+  console.log(`[test] Detected unlink + add events for delete+recreate`);
+
+  // Cleanup
+  await fs.promises.unlink(testFile);
+});
+
+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(200);
+
+  const changeObservable = await testSmartwatch.getObservableFor('change');
+  const eventPromise = waitForEvent(changeObservable, 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,174 @@
+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');
+});
+
+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.2.3',
   description: 'A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.'
 }

ts/watchers/watcher.node.ts

@@ -12,7 +12,12 @@ export class NodeWatcher implements IWatcher {
   private _isWatching = false;
 
   // Debounce: pending emits per file path
-  private pendingEmits: Map<string, NodeJS.Timeout> = new Map();
+  // Fix 2: Track event sequence instead of just last event type
+  // This prevents losing intermediate events (add→change→delete should not lose add)
+  private pendingEmits: Map<string, {
+    timeout: NodeJS.Timeout;
+    events: Array<'rename' | 'change'>;
+  }> = new Map();
 
   // Restart tracking
   private restartDelays: Map<string, number> = new Map();
@@ -34,6 +39,11 @@ export class NodeWatcher implements IWatcher {
   // Prevent concurrent restarts for the same path (health check + error can race)
   private restartingPaths: Set<string> = new Set();
 
+  // Initial scan state - events are deferred until scan completes to avoid race conditions
+  // Without this, events can arrive before watchedFiles is populated, causing inconsistent state
+  private initialScanComplete: boolean = false;
+  private deferredEvents: Array<{basePath: string; filename: string; eventType: string}> = [];
+
   // Configuration constants
   private static readonly MAX_RETRIES = 3;
   private static readonly INITIAL_RESTART_DELAY = 1000;
@@ -217,6 +227,35 @@ export class NodeWatcher implements IWatcher {
     return false;
   }
 
+  /**
+   * Extract the real file path from a temporary file path
+   * Used to detect atomic writes where only the temp file event is emitted
+   *
+   * Patterns:
+   * - Claude Code: file.ts.tmp.PID.TIMESTAMP -> file.ts
+   * - Vim swap: .file.ts.swp -> file.ts (but we don't handle this case)
+   */
+  private getTempFileTarget(tempFilePath: string): string | null {
+    const basename = path.basename(tempFilePath);
+
+    // Claude Code pattern: file.ts.tmp.PID.TIMESTAMP
+    // Match: anything.tmp.digits.digits
+    const claudeMatch = basename.match(/^(.+)\.tmp\.\d+\.\d+$/);
+    if (claudeMatch) {
+      const realBasename = claudeMatch[1];
+      return path.join(path.dirname(tempFilePath), realBasename);
+    }
+
+    // Generic .tmp. pattern: file.ts.tmp.something -> file.ts
+    const tmpMatch = basename.match(/^(.+)\.tmp\.[^.]+$/);
+    if (tmpMatch) {
+      const realBasename = tmpMatch[1];
+      return path.join(path.dirname(tempFilePath), realBasename);
+    }
+
+    return null;
+  }
+
   get isWatching(): boolean {
     return this._isWatching;
   }
@@ -229,7 +268,12 @@ export class NodeWatcher implements IWatcher {
     console.log(`[smartwatch] Starting watcher for ${this.options.basePaths.length} base path(s)...`);
 
     try {
+      // Reset initial scan state
+      this.initialScanComplete = false;
+      this.deferredEvents = [];
+
       // Start watching each base path
+      // NOTE: Events may arrive immediately but will be deferred until scan completes
       for (const basePath of this.options.basePaths) {
         await this.watchPath(basePath, 0);
       }
@@ -240,10 +284,21 @@ export class NodeWatcher implements IWatcher {
       this.startHealthCheck();
 
       // Perform initial scan to emit 'add' events for existing files
+      // This populates watchedFiles and fileInodes BEFORE we process events
       for (const basePath of this.options.basePaths) {
         await this.scanDirectory(basePath, 0);
       }
 
+      // Mark scan complete and process any events that arrived during scan
+      this.initialScanComplete = true;
+      if (this.deferredEvents.length > 0) {
+        console.log(`[smartwatch] Processing ${this.deferredEvents.length} deferred events from initial scan window`);
+        for (const event of this.deferredEvents) {
+          this.handleFsEvent(event.basePath, event.filename, event.eventType);
+        }
+        this.deferredEvents = [];
+      }
+
       // Emit ready event
       this.safeEmit({ type: 'ready', path: '' });
       console.log(`[smartwatch] Watcher started with ${this.watchers.size} active watcher(s)`);
@@ -256,6 +311,15 @@ export class NodeWatcher implements IWatcher {
 
   async stop(): Promise<void> {
     console.log('[smartwatch] Stopping watcher...');
+
+    // Fix 4: Cancel pending debounced emits FIRST (before flag changes)
+    // This prevents handleFsEvent from creating new pendingEmits during shutdown
+    for (const pending of this.pendingEmits.values()) {
+      clearTimeout(pending.timeout);
+    }
+    this.pendingEmits.clear();
+
+    // NOW set the flag - handleFsEvent will return early after this
     this._isWatching = false;
 
     // Stop health check monitoring
@@ -268,12 +332,6 @@ export class NodeWatcher implements IWatcher {
     }
     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}`);
@@ -289,6 +347,10 @@ export class NodeWatcher implements IWatcher {
     this.fileInodes.clear();
     this.restartingPaths.clear();
 
+    // Fix 5: Reset initial scan state
+    this.initialScanComplete = false;
+    this.deferredEvents = [];
+
     console.log('[smartwatch] Watcher stopped');
   }
 
@@ -339,8 +401,9 @@ export class NodeWatcher implements IWatcher {
 
         // Handle 'close' event - fs.watch can close without error
         watcher.on('close', () => {
-          console.warn(`[smartwatch] FSWatcher closed unexpectedly for ${watchPath}`);
+          // Only log/restart if we didn't intentionally stop
           if (this._isWatching) {
+            console.warn(`[smartwatch] FSWatcher closed unexpectedly for ${watchPath}`);
             this.restartWatcher(watchPath, new Error('Watcher closed unexpectedly'));
           }
         });
@@ -362,38 +425,85 @@ export class NodeWatcher implements IWatcher {
     filename: string,
     eventType: 'rename' | 'change' | string
   ): void {
-    const fullPath = path.join(basePath, filename);
+    // Fix 3: Guard against post-stop events (events queued before watcher closed)
-
+    if (!this._isWatching) {
-    // 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
+    // Fix 1: Defer events until initial scan completes
-    const existing = this.pendingEmits.get(fullPath);
+    // This prevents race conditions where events arrive before watchedFiles is populated
-    if (existing) {
+    if (!this.initialScanComplete) {
-      clearTimeout(existing);
+      this.deferredEvents.push({ basePath, filename, eventType });
+      return;
     }
 
-    // Schedule debounced emit
+    const fullPath = path.join(basePath, filename);
-    const timeout = setTimeout(() => {
-      this.pendingEmits.delete(fullPath);
-      this.emitFileEvent(fullPath, eventType);
-    }, this.options.debounceMs);
 
-    this.pendingEmits.set(fullPath, timeout);
+    // Handle temporary files from atomic writes (Claude Code, editors, etc.)
+    // Pattern: editor writes to file.tmp.xxx then renames to file
+    // Problem: fs.watch on Linux may ONLY emit event for the temp file, not the target!
+    // Solution: When we see a temp file event, also check the corresponding real file
+    if (this.isTemporaryFile(fullPath)) {
+      console.log(`[smartwatch] Detected temp file event: ${filename}`);
+
+      // Extract the real file path from the temp file path
+      // Pattern: file.ts.tmp.PID.TIMESTAMP -> file.ts
+      const realFilePath = this.getTempFileTarget(fullPath);
+      if (realFilePath) {
+        console.log(`[smartwatch] Checking corresponding real file: ${realFilePath}`);
+        // Queue an event for the REAL file - this is the actual file that changed
+        // Use a short delay to let the rename complete
+        setTimeout(() => {
+          if (this._isWatching) {
+            this.handleFsEvent(basePath, path.relative(basePath, realFilePath), 'change');
+          }
+        }, 50);
+      }
+      return;
+    }
+
+    // Fix 2: Track event sequence in debounce instead of collapsing to last event
+    // This ensures we don't lose intermediate events (e.g., add→change→delete)
+    const existing = this.pendingEmits.get(fullPath);
+    if (existing) {
+      // Cancel existing timeout but KEEP the event sequence
+      clearTimeout(existing.timeout);
+      // Add this event to the sequence
+      existing.events.push(eventType as 'rename' | 'change');
+      // Reschedule the emit with the accumulated events
+      existing.timeout = setTimeout(() => {
+        const pending = this.pendingEmits.get(fullPath);
+        if (pending) {
+          this.pendingEmits.delete(fullPath);
+          this.emitFileEvent(fullPath, pending.events);
+        }
+      }, this.options.debounceMs);
+    } else {
+      // First event for this file - create new sequence
+      const timeout = setTimeout(() => {
+        const pending = this.pendingEmits.get(fullPath);
+        if (pending) {
+          this.pendingEmits.delete(fullPath);
+          this.emitFileEvent(fullPath, pending.events);
+        }
+      }, this.options.debounceMs);
+
+      this.pendingEmits.set(fullPath, {
+        timeout,
+        events: [eventType as 'rename' | 'change']
+      });
+    }
   }
 
   /**
    * Emit the actual file event after debounce
    *
-   * Handles file inode tracking to detect delete+recreate scenarios:
+   * Fix 2: Now receives event sequence instead of single event type
+   * This allows intelligent processing of rapid event sequences:
+   * - add→change→delete: File was created and deleted rapidly
+   * - rename→rename: File was deleted and recreated (or vice versa)
+   *
+   * Also 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
@@ -401,92 +511,98 @@ export class NodeWatcher implements IWatcher {
    */
   private async emitFileEvent(
     fullPath: string,
-    eventType: 'rename' | 'change' | string
+    eventSequence: Array<'rename' | 'change'>
   ): Promise<void> {
     try {
       const stats = await this.statSafe(fullPath);
+      const wasWatched = this.watchedFiles.has(fullPath);
+      const previousInode = this.fileInodes.get(fullPath);
 
-      if (eventType === 'rename') {
+      // Analyze event sequence to understand what happened
-        // 'rename' can mean add or unlink - check if file exists
+      const hasRename = eventSequence.includes('rename');
-        if (stats) {
+      const hasChange = eventSequence.includes('change');
-          // File exists - it's either a new file or was renamed to this location
+      const renameCount = eventSequence.filter(e => e === 'rename').length;
-          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
+      // Log sequence for debugging complex scenarios
-            this.fileInodes.set(fullPath, currentInode);
+      if (eventSequence.length > 1) {
+        console.log(`[smartwatch] Processing event sequence for ${fullPath}: [${eventSequence.join(', ')}]`);
+      }
+
+      if (stats) {
+        // File EXISTS now
+        const currentInode = BigInt(stats.ino);
+        const inodeChanged = previousInode !== undefined && previousInode !== currentInode;
+
+        if (stats.isDirectory()) {
+          if (!wasWatched) {
             this.watchedFiles.add(fullPath);
-
+            this.safeEmit({ type: 'addDir', path: fullPath, stats });
-            // 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
-              });
-            }
           }
+          // Directories don't track inodes at file level
         } else {
-          // File doesn't exist - it was deleted
+          // Update tracking
-          if (this.watchedFiles.has(fullPath)) {
+          this.fileInodes.set(fullPath, currentInode);
-            const wasDir = this.isKnownDirectory(fullPath);
+          this.watchedFiles.add(fullPath);
-            this.watchedFiles.delete(fullPath);
+
-            this.fileInodes.delete(fullPath); // Clean up inode tracking
+          if (!wasWatched) {
+            // File wasn't tracked before - this is an add
+            // Even if there were multiple events, the end result is a new file
+            this.safeEmit({ type: 'add', path: fullPath, stats });
+          } else if (inodeChanged) {
+            // File was recreated with different inode (delete+recreate)
+            console.log(`[smartwatch] File inode changed (delete+recreate): ${fullPath}`);
+            console.log(`[smartwatch]   Previous inode: ${previousInode}, current: ${currentInode}`);
+            // Multiple rename events with inode change = delete+recreate pattern
+            // Emit unlink for the old file, then add for the new one
+            if (renameCount >= 2) {
+              this.safeEmit({ type: 'unlink', path: fullPath });
+              this.safeEmit({ type: 'add', path: fullPath, stats });
+            } else {
+              // Single rename with inode change = atomic save (emit as change)
+              this.safeEmit({ type: 'change', path: fullPath, stats });
+            }
+          } else if (hasChange || hasRename) {
+            // File exists, was tracked, inode same - content changed
+            this.safeEmit({ type: 'change', path: fullPath, stats });
+          }
+        }
+      } else {
+        // File does NOT exist now - it was deleted
+        const wasDir = this.isKnownDirectory(fullPath);
+
+        if (wasWatched) {
+          // File was tracked and is now gone
+          this.watchedFiles.delete(fullPath);
+          this.fileInodes.delete(fullPath);
+
+          // If there were multiple events, file may have been created then deleted
+          if (renameCount >= 2 && !wasDir) {
+            // add→delete sequence - emit both events
+            console.log(`[smartwatch] File created and deleted rapidly: ${fullPath}`);
+            this.safeEmit({ type: 'add', path: fullPath });
+            this.safeEmit({ type: 'unlink', path: fullPath });
+          } else {
             this.safeEmit({
               type: wasDir ? 'unlinkDir' : 'unlink',
               path: fullPath
             });
-          } else {
+          }
-            // Fix #4: File wasn't tracked but was deleted - still emit event
+        } else {
-            // This handles files created after initial scan that we may have missed
+          // File wasn't tracked - but events occurred for it
+          this.fileInodes.delete(fullPath);
+
+          if (renameCount >= 2) {
+            // Multiple rename events for untracked file that doesn't exist
+            // Likely: created → deleted rapidly
+            console.log(`[smartwatch] Untracked file created and deleted: ${fullPath}`);
+            this.safeEmit({ type: 'add', path: fullPath });
+            this.safeEmit({ type: 'unlink', path: fullPath });
+          } else if (hasRename) {
+            // Single event for file that doesn't exist and wasn't tracked
             console.log(`[smartwatch] Untracked file deleted: ${fullPath}`);
-            this.fileInodes.delete(fullPath);
             this.safeEmit({ type: 'unlink', path: fullPath });
           }
-        }
+          // If only 'change' events for non-existent untracked file, ignore
-      } 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) {