fix(watcher): handle vim atomic save race on macOS

src/CLAUDE.md

@@ -7,6 +7,6 @@ Syntax reminders:
 
 Conventions:
 
-- Prefer `@import` at the **bottom** of the file.
-- It's `@import("bun")` not `@import("root").bun`
+- Prefer `@import` at the **bottom** of the file, but the auto formatter will move them so you don't need to worry about it.
+- Prefer `@import("bun")`. Not `@import("root").bun` or `@import("../bun.zig")`.
 - You must be patient with the build.

src/Watcher.zig

@@ -312,6 +312,48 @@ fn watchLoop(this: *Watcher) bun.sys.Maybe(void) {
     return .success;
 }
 
+/// Register a file descriptor with kqueue on macOS without validation.
+///
+/// Preconditions (caller must ensure):
+/// - `fd` is a valid, open file descriptor
+/// - `fd` is not already registered with this kqueue
+/// - `watchlist_id` matches the entry's index in the watchlist
+///
+/// Note: This function does not propagate kevent registration errors.
+/// If registration fails, the file will not be watched but no error is returned.
+pub fn addFileDescriptorToKQueueWithoutChecks(this: *Watcher, fd: bun.FileDescriptor, watchlist_id: usize) void {
+    const KEvent = std.c.Kevent;
+
+    // https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/kqueue.2.html
+    var event = std.mem.zeroes(KEvent);
+
+    event.flags = std.c.EV.ADD | std.c.EV.CLEAR | std.c.EV.ENABLE;
+    // we want to know about the vnode
+    event.filter = std.c.EVFILT.VNODE;
+
+    event.fflags = std.c.NOTE.WRITE | std.c.NOTE.RENAME | std.c.NOTE.DELETE;
+
+    // id
+    event.ident = @intCast(fd.native());
+
+    // Store the index for fast filtering later
+    event.udata = @as(usize, @intCast(watchlist_id));
+    var events: [1]KEvent = .{event};
+
+    // This took a lot of work to figure out the right permutation
+    // Basically:
+    // - We register the event here.
+    // our while(true) loop above receives notification of changes to any of the events created here.
+    _ = std.posix.system.kevent(
+        this.platform.fd.unwrap().?.native(),
+        @as([]KEvent, events[0..1]).ptr,
+        1,
+        @as([]KEvent, events[0..1]).ptr,
+        0,
+        null,
+    );
+}
+
 fn appendFileAssumeCapacity(
     this: *Watcher,
     fd: bun.FileDescriptor,
@@ -350,36 +392,7 @@ fn appendFileAssumeCapacity(
     };
 
     if (comptime Environment.isMac) {
-        const KEvent = std.c.Kevent;
-
-        // https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/kqueue.2.html
-        var event = std.mem.zeroes(KEvent);
-
-        event.flags = std.c.EV.ADD | std.c.EV.CLEAR | std.c.EV.ENABLE;
-        // we want to know about the vnode
-        event.filter = std.c.EVFILT.VNODE;
-
-        event.fflags = std.c.NOTE.WRITE | std.c.NOTE.RENAME | std.c.NOTE.DELETE;
-
-        // id
-        event.ident = @intCast(fd.native());
-
-        // Store the hash for fast filtering later
-        event.udata = @as(usize, @intCast(watchlist_id));
-        var events: [1]KEvent = .{event};
-
-        // This took a lot of work to figure out the right permutation
-        // Basically:
-        // - We register the event here.
-        // our while(true) loop above receives notification of changes to any of the events created here.
-        _ = std.posix.system.kevent(
-            this.platform.fd.unwrap().?.native(),
-            @as([]KEvent, events[0..1]).ptr,
-            1,
-            @as([]KEvent, events[0..1]).ptr,
-            0,
-            null,
-        );
+        this.addFileDescriptorToKQueueWithoutChecks(fd, watchlist_id);
     } else if (comptime Environment.isLinux) {
         // var file_path_to_use_ = std.mem.trimRight(u8, file_path_, "/");
         // var buf: [bun.MAX_PATH_BYTES+1]u8 = undefined;
@@ -612,6 +625,68 @@ pub fn addDirectory(
     return this.appendDirectoryAssumeCapacity(fd, file_path, hash, clone_file_path);
 }
 
+pub fn addFileByPathSlow(
+    this: *Watcher,
+    file_path: string,
+    loader: options.Loader,
+) bool {
+    const hash = getHash(file_path);
+
+    // Check if already watched (with lock to avoid race with removal)
+    {
+        this.mutex.lock();
+        const already_watched = this.indexOf(hash) != null;
+        this.mutex.unlock();
+
+        if (already_watched) {
+            return true;
+        }
+    }
+
+    // Only open fd if we might need it
+    var fd: bun.FileDescriptor = bun.invalid_fd;
+    if (Environment.isMac) {
+        const path_z = std.posix.toPosixPath(file_path) catch return false;
+        switch (bun.sys.open(&path_z, bun.c.O_EVTONLY, 0)) {
+            .result => |opened| fd = opened,
+            .err => return false,
+        }
+    }
+
+    const res = this.addFile(fd, file_path, hash, loader, bun.invalid_fd, null, true);
+    switch (res) {
+        .result => {
+            // On macOS, addFile may have found the file already watched (race)
+            // and returned success without using our fd. Close it if unused.
+            if (comptime Environment.isMac) {
+                if (fd.isValid()) {
+                    this.mutex.lock();
+                    const maybe_idx = this.indexOf(hash);
+                    const stored_fd = if (maybe_idx) |idx|
+                        this.watchlist.items(.fd)[idx]
+                    else
+                        bun.invalid_fd;
+                    this.mutex.unlock();
+
+                    // Only close if entry exists and stored fd differs from ours.
+                    // Race scenarios:
+                    // 1. Entry removed (maybe_idx == null): our fd was stored then closed by flushEvictions → don't close
+                    // 2. Entry exists with different fd: another thread added entry, addFile didn't use our fd → close ours
+                    // 3. Entry exists with same fd: our fd was stored → don't close
+                    if (maybe_idx != null and stored_fd.native() != fd.native()) {
+                        fd.close();
+                    }
+                }
+            }
+            return true;
+        },
+        .err => {
+            if (fd.isValid()) fd.close();
+            return false;
+        },
+    }
+}
+
 pub fn addFile(
     this: *Watcher,
     fd: bun.FileDescriptor,

src/bun.js.zig

@@ -311,8 +311,8 @@ pub const Run = struct {
         }
 
         switch (this.ctx.debug.hot_reload) {
-            .hot => jsc.hot_reloader.HotReloader.enableHotModuleReloading(vm),
-            .watch => jsc.hot_reloader.WatchReloader.enableHotModuleReloading(vm),
+            .hot => jsc.hot_reloader.HotReloader.enableHotModuleReloading(vm, this.entry_path),
+            .watch => jsc.hot_reloader.WatchReloader.enableHotModuleReloading(vm, this.entry_path),
             else => {},
         }
 
@@ -328,6 +328,7 @@ pub const Run = struct {
                 promise.setHandled(vm.global.vm());
 
                 if (vm.hot_reload != .none or handled) {
+                    vm.addMainToWatcherIfNeeded();
                     vm.eventLoop().tick();
                     vm.eventLoop().tickPossiblyForever();
                 } else {
@@ -389,21 +390,21 @@ pub const Run = struct {
 
         {
             if (this.vm.isWatcherEnabled()) {
-                vm.handlePendingInternalPromiseRejection();
+                vm.reportExceptionInHotReloadedModuleIfNeeded();
 
                 while (true) {
                     while (vm.isEventLoopAlive()) {
                         vm.tick();
 
                         // Report exceptions in hot-reloaded modules
-                        vm.handlePendingInternalPromiseRejection();
+                        vm.reportExceptionInHotReloadedModuleIfNeeded();
 
                         vm.eventLoop().autoTickActive();
                     }
 
                     vm.onBeforeExit();
 
-                    vm.handlePendingInternalPromiseRejection();
+                    vm.reportExceptionInHotReloadedModuleIfNeeded();
 
                     vm.eventLoop().tickPossiblyForever();
                 }

src/bun.js/VirtualMachine.zig

@@ -677,12 +677,28 @@ pub fn uncaughtException(this: *jsc.VirtualMachine, globalObject: *JSGlobalObjec
     return handled;
 }
 
-pub fn handlePendingInternalPromiseRejection(this: *jsc.VirtualMachine) void {
-    var promise = this.pending_internal_promise.?;
+pub fn reportExceptionInHotReloadedModuleIfNeeded(this: *jsc.VirtualMachine) void {
+    const promise_opt = this.pending_internal_promise;
+    if (promise_opt == null) {
+        this.addMainToWatcherIfNeeded();
+        return;
+    }
+    var promise = promise_opt.?;
+
     if (promise.status(this.global.vm()) == .rejected and !promise.isHandled(this.global.vm())) {
         this.unhandledRejection(this.global, promise.result(this.global.vm()), promise.asValue());
         promise.setHandled(this.global.vm());
     }
+
+    this.addMainToWatcherIfNeeded();
+}
+
+pub fn addMainToWatcherIfNeeded(this: *jsc.VirtualMachine) void {
+    if (this.isWatcherEnabled()) {
+        const main = this.main;
+        if (main.len == 0) return;
+        _ = this.bun_watcher.addFileByPathSlow(main, this.transpiler.options.loader(std.fs.path.extension(main)));
+    }
 }
 
 pub fn defaultOnUnhandledRejection(this: *jsc.VirtualMachine, _: *JSGlobalObject, value: JSValue) void {