Can peruse drop chokidar for Bun's fs.watch?

Research date: 2026-09-22. Machine: Linux 6.8.0-139-generic x86_64, Bun 1.4.2,
chokidar 4.0.3 (from /home/talkasab/peruse/node_modules, read-only).
Nothing inside /home/talkasab/peruse was modified; the repo was only watched
(read-only) during test E5.

Bottom line: yes — drop chokidar. Every documented reason peruse chose
chokidar in July 2026 has been retired by Bun's fs.watch rewrite in v1.3.14
(2026-05-13), and the single failure that motivated peruse's largest piece of
watcher machinery (issue #17, the symlink scan stall) is a chokidar bug that
Bun's watcher does not have. I reproduced that stall against chokidar on this
machine today and confirmed Bun is immune. Caveats and risks are in §5.

1. Machine caveat (read this before trusting the numbers)

This host has non-default inotify sysctls:

ulimit -n soft and hard are both 1048576.

Two consequences: the ENOSPC (watch-limit exhaustion) path could not be
exercised, and the queue-overflow test (§3, S2) is weaker than it looks because
the kernel queue here is 64x the usual size. I tried to run a probe under
unshare -Ur with fs.inotify.max_user_watches=16; user-namespace creation is
blocked on this host (unshare: write failed /proc/self/uid_map: Operation not permitted), so that probe is untested, for both watchers equally.

2. Web research

2.1 The rewrite: Bun v1.3.14, 2026-05-13

https://bun.com/blog/bun-v1.3.14

"Bun's fs.watch() implementation on POSIX platforms has been completely
rewritten to talk directly to the OS file-watching APIs (inotify, FSEvents,
kqueue) instead of routing through Bun's internal bundler watcher."

Specific items from that release:

• Recursive new-directory pickup fixed. Previously "directories created
  after the watch started were never tracked, so files inside them were
  invisible to the watcher." This was the headline recursive: true defect on
  Linux and it is fixed.
• Delete-and-recreate fixed. "deleted-and-recreated files emit change
  events again … the new inotify watch descriptor is correctly registered on
  recreation."
• macOS. "uses FSEvents exclusively for both files and directories, matching
  libuv's behavior and halving the thread overhead." macOS no longer spins up
  two watcher threads.

Directly relevant to peruse's history: the fd-exhaustion saga in
docs/DEVLOG.md:1400 ("under Bun each watched path holds fds (files too, ~2–3
each), stock macOS shells give 256") is a kqueue/macOS phenomenon. kqueue
requires one open descriptor per watched entry; FSEvents does not. Bun's move to
FSEvents-only on macOS removes that cost for Bun's own watcher.

2.2 recursive: true on Linux

Supported and emulated by Bun (inotify has no kernel recursion). Bun walks the
tree and adds one inotify watch per directory, including directories created
later. Confirmed empirically in §3 (E1, S1, R1–R3). The filename argument
arrives as a path relative to the watched root — the old basename-vs-relative
inconsistency was oven-sh/bun#29677, closed as
completed 2026-07-24. Every one of the ~2,700 distinct paths I observed came
back relative and correctly spelled, including .git/objects/f7/tmp_obj_YPgasB.

2.3 Event reliability: what is fixed, what is still open

Closed as completed (all in the last three months):

#36328 and #39070 are exactly the "drops events" reputation. Both fixed.
I re-ran the #42570 repro in all four shapes (pre-watched/not ×
recursive/not) on 1.4.2: all four caught the post-recreate write (§3, R1–R3).

Still open, Linux-relevant:

Discussion oven-sh/bun#1571 (the citation in
docs/design-history.md:91) is resolved: the maintainer committed to a
built-in watch API in Dec 2022, implemented Jan 2024. Its most recent substantive
comment is from October 2024 — a user seeing fewer events than chokidar on
~350 Angular build outputs. That complaint predates the 1.3.14 rewrite by 19
months and is superseded by the closed issues above. The design-history
citation is now stale.

2.4 Bun 1.4 behavior change

From the 1.4 breaking-changes list,
oven-sh/bun#28792 (closed, 2026-04-02):

"recursive fs.watch() emits 'error' for subdirectories it cannot watch
instead of swallowing the failure"
(PR #36415)

This is a real gain for peruse: a subtree that cannot be watched (EACCES,
and presumably ENOSPC) now surfaces instead of vanishing. Verified: an
unreadable subdirectory produced EPERM EACCES: permission denied, watch '…/locked' on the watcher's error event while sibling coverage kept working.
Compare with the silent chokidar failure mode that peruse's issue #17
machinery exists to paper over.

2.5 Active churn (this matters)

Four fs.watch pull requests opened in the week before this research:

• #43064 report a watched symlink under its own name on Linux
• #43083 report a directory's attribute change as rename on Linux
• #43090 watch symlink entries of a recursive tree on Linux — open as of 2026-09-17. Description: "The walk now reports symlink entries … Every event on that watch is reported as a rename of the link itself, like Node. The walk never descends into a link target, so a link to an ancestor cannot loop." Targets must be regular files or directories; others (e.g. /dev/stdout) are skipped.
• #43715 run nextTicks and microtasks between the events of one batch

#43090 would change what peruse sees for symlinks: link entries would start
reporting, though still without descending. Since peruse coalesces and re-fetches
the tree, extra events are harmless; the no-descent guarantee is what matters and
the PR preserves it explicitly.

2.6 chokidar on Bun

No chokidar-specific Bun breakage found, and none observed here. chokidar 4.0.3
runs on Bun 1.4.2 and delegates to node:fs.watch, so the two share a backend.
That is why both show one inotify instance in §3 — the difference is entirely
in how many paths each one registers.

3. Empirical results

Scripts (all in the scratchpad): harness.js (burst), edges.js (edge cases),
stress.js (scale/queue/git), recreate.js + rewatch.js (#42570 shapes),
errs.js (error surfaces). Both watchers ran the identical workload;
chokidar with { ignoreInitial: true, followSymlinks: false }, matching
server/index.js:787.

3.1 Coverage burst — 200 dirs x 20 files, 1,940 mixed operations

No misses and no parent-only attributions on either side. Nothing was scored by
event type, only by whether the changed path was named — which is all peruse's
noteChange needs.

Bun holds one inotify watch per DIRECTORY. chokidar holds one per FILE and per
directory — 20.8x more on this tree. Bun is chattier per event (~2.2 raw
events per operation vs 1.3) because it does not classify; peruse coalesces into
200 ms batches anyway, so that costs nothing.

Correction to ARCHITECTURE.md: the note that "chokidar holds fds per
watched file under Bun" no longer describes Linux. Under Bun 1.4.2, 4,203
chokidar watches cost zero additional file descriptors — one shared inotify
instance with 4,203 watch descriptors. The fd-per-path cost is macOS/kqueue, as
server/index.js:538 already says in its own comment ("Crucial on macOS, where
each watched directory costs a file descriptor (kqueue, default ulimit 256)").
The peruse watch budget on Linux is therefore governing the wrong resource: the
binding limit is fs.inotify.max_user_watches, not ulimit -n.

3.2 Edge cases

3.3 Scale and semantics

S4 is worth calling out: ARCHITECTURE.md:266 documents this shape as an
accepted blind spot of the snapshot-reconciliation fallback. inotify's IN_MODIFY
does not consult mtime, so a plain recursive fs.watch catches it. Dropping the
snapshot fallback would remove that documented limitation rather than inherit it.

3.4 Delete/recreate and directory churn

R3 is a chokidar defect Bun does not share, and it is a realistic shape
(blue-green output directories, mv dist.new dist).

3.5 Error surfaces (Bun 1.4.2)

4. Would Bun's fs.watch alone satisfy peruse?

Against the requirement list:

What peruse would reimplement, and how much code

Added (roughly 25–40 lines):

1. Event-level ignore filtering — skipRel already exists (server/index.js:618);
   it just moves from chokidar's ignored callback into the fs.watch callback.
   Near-zero new code.
2. Null-filename guard for the recursive-root event (issue #43066). One line.
3. ready resolves right after the fs.watch call, with the existing
   RuntimeClosedError contract preserved. A few lines.
4. error handler: same rate-limited logging as today, plus an ENOSPC-specific
   message telling the user to raise fs.inotify.max_user_watches. ~15 lines.

Deleted (roughly 220–280 lines of server/index.js):

• SURVIVABLE_LINK_ERRORS and findScanBreakingLinks (~lines 434–497).
• The whole recovery subsystem: fallbackWatchers, fallbackSnapshots,
  reconcileTimers, verifyTimers, snapshotDirectory, dropFallback,
  scheduleVerification, reconcileFallback, scheduleReconcile,
  installFallback, recoverSubtree (~lines 597–612 and 647–762).
• The stall watchdog and its heartbeat plumbing (~lines 818–845).
• The watchable / softFd gate and the WATCH_BUDGET admission set, or a
  rewrite of the budget in terms of inotify watches rather than fds.
• Plausibly bin/peruse.js's ulimit re-exec, on Linux at least.

Net: peruse gets smaller, loses its only runtime dependency, and deletes the
subsystem that has produced the most incident history in the dev log — all of
which is squarely the project's "minimum code, maximum leverage" principle.

5. Recommendation: drop chokidar, with three guards

Confidence is high on Linux, medium on macOS (untestable here).

Evidence for:

1. The founding rationale is void. Discussion 1571 is resolved; its last
   complaint predates the 1.3.14 rewrite by 19 months; the specific
   event-dropping issues (#36328, #39070, #7919) are closed as completed. Both
   watchers scored 1,940/1,940 and 20,000/20,000 here.
2. peruse's worst bug is a chokidar bug. Issue Directories containing a dangling symlink silently lose live updates #17 — the ENOTDIR link that
   leaves ready pending forever and silently unwatches a directory — reproduced
   against chokidar on this machine today (E3) and did not reproduce against Bun.
   ~250 lines of peruse exist only to survive it.
3. 20x cheaper kernel resources. 202 vs 4,203 watches on the synthetic tree;
   606 vs 8,380 on the real repo; 4,041 vs 24,150 on the 4,000-dir tree.
4. 14x faster startup on the real repo (15 ms vs 356 ms) and no readiness
   race to wait out — the first project request stops blocking on a scan.
5. Strictly better on two real shapes: the rename-swapped directory (R3,
   chokidar missed it entirely) and the timestamp-preserving in-place rewrite
   that ARCHITECTURE.md documents as a known blind spot.
6. Failures are now loud, not silent (Bun 1.4's error events for
   unwatchable subtrees).

Risks and the guards for them:

1. No install-time ignore (the only structural regression). A recursive watch
   registers node_modules and .git/objects whether or not peruse wants them.
   On this repo that is 606 watches instead of 16 — a 38x amplification that is
   still absolutely trivial. On a large JS monorepo (30k+ directories under
   node_modules) against a stock max_user_watches of 8192, it is exhaustion.
   Guard: handle the ENOSPC error event with a message naming
   fs.inotify.max_user_watches. If that proves insufficient, the escape hatch
   is not chokidar — it is peruse's own traversal calling
   fs.watch(dir, { recursive: false }) on admitted directories only
   (~120–180 lines, per-directory cost, full ignore control, still no
   dependency). Do not build that pre-emptively; measure first.
2. Queue overflow is unproven. IN_Q_OVERFLOW handling could not be tested
   because this kernel's queue is 64x the default, and issue #42936 states the
   inotify backend shares the Windows gap (where a fix landed via PR #42951).
   Guard: a regression test on a stock-configured machine, and treat a
   <null>/undefined filename as "invalidate the whole tree" — which is cheap,
   because peruse's SSE clients already re-fetch the tree on any event.
3. The area is churning right now. Four fs.watch PRs opened in the week
   before this research, one of which (#43090) changes symlink-entry reporting.
   Guard: declare a Bun floor. package.json currently has no engines field;
   add >=1.3.14 at minimum, preferably >=1.4.0 for the error-event
   behavior, and pin each relied-upon behavior with a test — the project's own
   practice of proving regression tests RED first applies here.
4. macOS is unverified. Bun's rewrite moved macOS to FSEvents-only, which
   should remove the fd-per-path cost that caused peruse's fd-exhaustion saga.
   But chokidar-on-Bun watches per file, so on macOS it may now be worse than
   the measurements above suggest, not better. Guard: run harness.js and
   edges.js unchanged on a Mac before release; they need no modification.

Not recommended: keep chokidar (pays 20x the kernel watches, keeps the
dependency, keeps ~250 lines of workaround, and still carries the E3 stall and
the R3 rename-swap miss), or a hybrid that runs both (doubles the watch
count and the failure surface for no benefit — the fallback machinery exists to
compensate for chokidar, and without chokidar there is nothing to compensate for).

URLs

• https://bun.com/blog/bun-v1.3.14 — the POSIX fs.watch rewrite, 2026-05-13
• `Bun.watch` - fast and reliable file watching api oven-sh/bun#1571 — the docs/design-history.md:91 citation; resolved, last substantive comment Oct 2024
• List of breaking changes for 1.4 oven-sh/bun#28792 — Bun 1.4 breaking changes (closed 2026-04-02)
• fs.watch: surface inotify_add_watch subtree failures as 'error' events oven-sh/bun#36415 — surface inotify_add_watch subtree failures as error events
• fs.watch: a previously-watched directory path stays inert after delete+recreate (Linux) oven-sh/bun#42570 — delete+recreate inert (closed completed 2026-09-20); did not reproduce on 1.4.2
• fs.watch(Linux): atomic saves never report the rename destination oven-sh/bun#36328 — atomic saves never report the rename destination (closed completed 2026-08-10)
• fs.watch on macOS reports only one file per ~40ms window, so bulk changes are mostly lost oven-sh/bun#39070 — macOS ~40 ms window drops bulk changes (closed completed 2026-08-15)
• fs.watch with recursive: true: inconsistent filename (basename vs relative path) oven-sh/bun#29677 — recursive filename basename vs relative path (closed completed 2026-07-24)
• fs.watch skips save events oven-sh/bun#7919 — fs.watch skips save events (closed completed)
• [Node Incompatibility] fs.watch on directory doesn't report change events for files created after watch oven-sh/bun#23992 — directory watch missed files created after watch (historical)
• fs.watch recursive on Linux: no event for a change behind a symlink entry that points outside the tree (regression in 1.3.14) oven-sh/bun#43065 — open — no event behind a symlink pointing outside the tree (1.3.14 regression)
• fs.watch on Linux: an event about the watched directory itself differs from Node (event type, filename for a trailing slash, recursive root) oven-sh/bun#43066 — open — watched-directory-itself event differs from Node; recursive root gives change + undefined filename
• fs.watch goes to infinite loop with big files oven-sh/bun#6955 — open — infinite loop with big files (2023)
• watch doesn't trigger on file writes on macOS oven-sh/bun#14568 — open — no trigger on file writes on macOS (2024, pre-rewrite)
• Windows watcher: a ReadDirectoryChangesW buffer overflow drops the changes and nothing reloads oven-sh/bun#42936 — open — Windows ReadDirectoryChangesW overflow drops changes; notes the inotify IN_Q_OVERFLOW gap
• Windows watcher: treat every watched path as changed after a ReadDirectoryChangesW overflow oven-sh/bun#42951 — treat every watched path as changed after a Windows overflow
• fs.watch: report a watched symlink under its own name on Linux oven-sh/bun#43064 — open — report a watched symlink under its own name on Linux
• fs.watch: report a directory's attribute change as rename on Linux oven-sh/bun#43083 — open — report a directory's attribute change as rename on Linux
• fs.watch: watch symlink entries of a recursive tree on Linux oven-sh/bun#43090 — open — watch symlink entries of a recursive tree on Linux (never descends)
• fs.watch: run nextTicks and microtasks between the events of one batch oven-sh/bun#43715 — open — run nextTicks and microtasks between the events of one batch
• fs.watch/fs.watchFile: remove unsafe from the watcher modules oven-sh/bun#40200 — remove unsafe from the watcher modules
• --hot/--watch causes fs.watch to drop filechange events oven-sh/bun#4854 — --hot/--watch drops file-change events (historical)
• https://manpages.debian.org/testing/fswatch/fswatch.7.en.html — kqueue needs one fd per watched entry; FSEvents does not (background for the macOS cost model)

Scratchpad artifacts

harness.js, edges.js, stress.js, recreate.js, rewatch.js, errs.js,
out-bun-burst.json, out-chokidar-burst.json, out-edges-bun.json,
out-edges-chokidar.json, out-stress-bun.json, out-stress-chokidar.json,
out-recreate-bun.json, and the matching *.log files, all under
/tmp/claude-1001/-home-talkasab-peruse/e3fafb89-3d10-4a60-b3c0-d1fe62ffe04a/scratchpad/.