Do not index a directory the watcher could not read or classify

[JesseHerrick]

Closes four gaps in how nested worktrees and unreadable directories are handled (#111, and the worktree-move fix in #110). The last one is the cause of the flaky TestFSNotifyWatcherSkipsWorktreeAddedWhileRunning failures in CI.

Summary

• Two reads of one .git file could disagree (the cause of the CI flake). git 2.48 and later rename a worktree on git worktree move and then write its .git file again in place (truncate, then write; confirmed with strace on git 2.55). The watcher's walk asked "is this a worktree?" and "is its .git file still being written?" with two separate reads. The first could see the truncated file and the second the complete one, so a worktree was neither, and every file in it was reported as a plain directory. git 2.47 does not write the file again, which is why it only showed up on CI's newer git.

• A directory that the watcher cannot read was skipped silently. walkDirectories returned when ReadDir failed, for example when the process had no file descriptor left (the kqueue backend uses one per watched file). The subtree below it was not watched, not marked failed and never retried, so the coverage report said nothing. The Create handler then reported every file in it as if it were a plain directory, also when it was a worktree that had been moved into place.

• The index walks did not skip a worktree that git is still moving. git worktree move renames the directory and then writes its .git file again in place. Send generated functions to the line that declared them #110 made the watchers treat a .git file that names no git directory yet as a pending worktree, but WalkElixirFiles and CollectElixirFilesParallel did not, so a reconcile or a first build at that moment indexed the whole worktree.

Changes

• parser.GitFile and parser.GitFileFromEntries return one state (none, plain, worktree, unsettled) from one read of the .git file. The fsnotify walk and pending check, the FSEvents handler and its later check, both index walks, and the runtime's removal of a reported worktree use it. Same cost as before: no syscall for a directory without a .git entry, one read for a directory with one.

• walkDirectories marks a directory it cannot read as failed. The coverage report then says that the tree is not covered, and the retry timer reads it again. A retry clears the failure only when it could read the directory.

• The Create handler does not report the files of a directory that it could not read. When coverage comes back, the runtime reconciles, and that walk indexes the files of a plain directory and skips a worktree.

• Both index walks skip a nested directory whose .git file names no git directory yet, as the watchers do.

• The watcher's directory reads can be replaced in tests (readDir), so a failed read can be simulated without timing.

Validation

• TestWatcherDoesNotReportDirectoryItCouldNotRead: a worktree moved into place and a plain directory, each with a failed read, a retry that still fails, and a retry that works. Nothing is reported from the unreadable directory, the coverage goes degraded and then restored, and the retry classifies the directory. With the old behavior, the test reports the moved-in worktree's files.
• TestWalkAndCollectSkipUnsettledGitFile: both walks skip a directory with an empty .git file. Without the change, both index it.
• TestGitFileStates (each state) and TestGitFileReadsTheFileOnce, which serves an empty file on the first read and a complete one on the second, as git does: one classification reads once and answers "unsettled".
• Reproduced the CI failure in a Linux container like CI (Ubuntu 24.04, git 2.55): TestFSNotifyWatcherSkipsWorktreeAddedWhileRunning failed in 2 of 20 race runs before the change. After it: 100 of 100 with git 2.55, and 50 of 50 with git 2.47. Tracing the failing run showed the walk deciding "not a worktree" while the .git file and git's records were valid a moment later.
• The unreadable-directory fix in the first commit is a separate real gap (proven by its own test), but it was not the cause of the CI flake, as this PR first said.
• go test ./..., go test -race on internal/workspace and internal/parser, ten race runs of every watcher test, and golangci-lint pass. No change to the walk for directories without a .git entry, so the walk costs the same.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes when directories are indexed and how nested worktrees are detected; wrong behavior could skip or duplicate index content, but scope is filesystem watching and walks only.

Overview
Fixes incorrect indexing when a git worktree is moved into the project or when the file watcher cannot read a directory (e.g. EMFILE).

Single-read .git classification — Replaces separate “linked worktree?” and “unsettled .git file?” checks with GitFile / GitFileFromEntries, which classify a directory in one read (WorktreeGitFile, UnsettledGitFile, PlainGitFile, etc.). That closes a race on git 2.48+ where two reads could see an empty then complete .git file and treat a worktree as a normal folder (the CI flake). Index walks (WalkElixirFiles, CollectElixirFilesParallel), fsnotify/FSEvents, and runtime removal all use this API; unsettled (empty) .git files are skipped like settled worktrees.

Unreadable directories — walkDirectories no longer silently skips failed ReadDir: it marks the path failed, reports degraded coverage, and retries later. On Create, files under a directory that could not be read are not indexed immediately (it might be a moved-in worktree); readable-but-unwatchable dirs are still indexed at once.

CHANGELOG documents the fix; new tests cover unsettled .git, single-read behavior, unreadable dirs, and watch-at-limit cases.

^{Reviewed by Cursor Bugbot for commit 69703fa. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1181bba. Configure here.}