Skip to content

fix(watcher): a deleted link target no longer pins a CPU core on Windows - #2938

Merged
colbymchenry merged 1 commit into
mainfrom
claude/fix-watcher-gone-link-target
Oct 27, 2026
Merged

colbymchenry merged 1 commit into
mainfrom
claude/fix-watcher-gone-link-target

Conversation

@colbymchenry

@colbymchenry colbymchenry commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Summary

On Windows, deleting the folder that a directory link in a project points to (a junction to a library outside the project, say) no longer makes the CodeGraph server pin a CPU core until it is restarted. Before, the storm also kept the server from picking up later edits. Now the link's files drop out of the index and the rest of the project keeps auto-syncing. A project folder that disappears while watched turns auto-sync off with a clear reason.

Root cause

On Windows, libuv reports a watched folder that is being deleted by the folder's own absolute path, \\?\D:\…\proj\libs. It then re-arms the read, which fails the same way at once. Measured on Node 22.22 / libuv 1.51: 70,009 such events in 500 ms of a plain fs.watch, until close().

The watcher gives each directory link in a project its own recursive stream, so deleting a link's target outside the project starts that storm. FileWatcher.handleDirEvent joined the absolute name onto the watched folder, got a path that doesn't exist, and scheduled a full sync. Nothing closed the stream.

The storm also re-armed the debounce on every event, so no sync ever ran: the deleted files stayed in the index, and later edits were never synced. The project root's stream (startRecursive) had the same blind spot.

Fix

handleDirEvent, which both stream callbacks (startRecursive, watchDirectory) use, now treats an absolute name as the watched folder itself reporting it is gone:

  • The first such event on a stream arms one check 200 ms later; the rest of the burst finds it armed, so a burst costs no fs call at all.
  • For a link's stream: if the link no longer leads to the folder it watched (deleted, or pointed elsewhere), the check calls unwatchDir(dir) and scheduleTreeRefresh(). The refresh's full sync drops the link's files, and a link that leads somewhere live is watched anew.
  • For the project root: if it is gone, the watcher degrades with "The project folder was deleted or moved away while watched; auto-sync disabled…", which closes every stream.

A normal event pays one path.isAbsolute check. Pending checks are cleared in unwatchDir and stop.

Validation (Windows 11, Node 22.22, libuv 1.51)

Real MCP server (direct mode, projectPath) over a fresh fixture: proj with a junction libs → outside, indexed. outside is then deleted. CPU is for the server's process tree.

main fix
CPU in the four 3 s windows after the delete +3484, +3406, +3391, +3281 ms +296, 0, 0, +79 ms
CPU in a final 3 s window, after the edit check +3484 ms +15 ms
the linked symbol after the delete still indexed dropped
an edit to src/a.ts afterwards never synced synced (Auto-synced 1 file(s))

An earlier run with the original probe gave the same picture: main +3376/+3124/+3094/+3125 ms, fix +375/+234/0/0 ms.

New tests in watcher.test.ts:

  • link storm (fake fs.watch): 10,000 self-named events cost no fs call; the stream closes once; a full sync runs; the dangling link is not watched again; the project stays watched and healthy. A self-named event while the link still leads to its folder keeps the stream.
  • root storm (fake fs.watch): degrades once, with the reason, and closes the stream; a late burst changes nothing.
  • real junction, Windows-gated: deleting the target must leave the link's stream quiet within 10 s, the watcher still active.
  • Red/green: all 3 fail on main's watcher.ts, which made 30,000 fs calls for the burst, never degraded, and never went quiet. The file passes 61/61 with the fix.

Full suite on this commit: 767 files passed, 6 skipped; 9,151 tests passed, 0 failed, 85 skipped (Windows 11, kernel built, CODEGRAPH_KERNEL_EXPECT=1, CODEGRAPH_NO_DAEMON unset).

Notes

  • On Windows the project root itself can't be deleted while its index is open inside it, so the real storm comes from links. The root guard is covered by the fake-fs.watch test.
  • A link whose target is restored later is picked up on the next tree refresh, as for a link whose target appears after startup. That is unchanged.

Credit

Reported in #2487 by @L0garithmic; this reimplements the fix independently. Their PR identified the libuv storm and the throttle shape, and guarded the project root. This one also covers the directory-link streams, where the storm actually happens with an index open.

🤖 Generated with Claude Code

@colbymchenry
colbymchenry force-pushed the claude/fix-watcher-gone-link-target branch 3 times, most recently from 21aa469 to ece95fe Compare October 27, 2026 22:58
On Windows, libuv reports a watched folder that is being deleted by the
folder's own absolute path (\\?\D:\...) and re-arms the read, which fails
the same way at once: about 70,000 events in half a second until the
stream is closed. The watcher gives each directory link in a project its
own recursive stream, so deleting a link's target outside the project
started that storm. handleDirEvent joined the absolute name onto the
watched folder, got a path that doesn't exist, scheduled a full sync and
nothing else. The stream was never closed, the server held a core until
restart, and the storm kept re-arming the debounce, so no sync ever ran:
the deleted files stayed in the index and later edits never auto-synced.
The project root's stream had the same blind spot.

Fix: handleDirEvent, which both stream callbacks use, now treats an
absolute name as the watched folder itself reporting it is gone. The
first such event on a stream arms one check 200 ms later; the rest of the
burst finds it armed. The check closes a link's stream when the link no
longer leads to the folder it watched (deleted, or pointed elsewhere) and
re-reads the tree, whose full sync drops the link's files; a link that
leads somewhere live is watched anew. A project root that is gone
degrades the watcher with a "project folder was deleted or moved away"
reason, which closes every stream. A normal event pays one
path.isAbsolute check.

Validation (Windows 11, Node 22.22, libuv 1.51):
- Raw probe: fs.watch on a junction whose target is deleted gets 70,009
  events named \\?\<the junction> in 500 ms (499 ms CPU), and none after
  close().
- Real MCP server over a project with a junction libs -> outside, outside
  deleted: main used 3484, 3406, 3391, 3281 ms of CPU per 3 s window and
  kept the linked symbol; an edit afterwards never synced. With the fix:
  296, 0, 0, 79 ms; the linked symbol left the index; the edit synced.
- New watcher tests: a fake fs.watch link storm (10,000 self-named
  events cost no fs call, the stream closes once, a full sync runs, the
  project stays watched), a fake root storm (degrades once, closes the
  stream), and a Windows-gated real junction whose storm must go quiet.
  All 3 fail on main's watcher.ts; watcher.test.ts passes 61/61.

Reported in PR #2487 by @L0garithmic; this reimplements the fix
independently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant