Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(troubleshooting): add `wt list` fsmonitor hang (#2194)

Maximilian Roos8f7aa4663034
diff --git a/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.md
index fcdacf651..363e8e96f 100644
--- a/skills/worktrunk/reference/troubleshooting.md
+++ b/skills/worktrunk/reference/troubleshooting.md
@@ -74,6 +74,50 @@ pre-start = "npm install"
post-start = "npm run build"
```
+## List
+
+### `wt list` times out after 120s
+
+The timeout warning names the tasks that didn't finish:
+
+```
+wt list timed out after 120s (170 results received)
+Blocked tasks:
+ <branch>: working-tree-diff, working-tree-conflicts
+```
+
+Both tasks run `git status --porcelain` first. When the named worktree has `core.fsmonitor=true` and its `git fsmonitor--daemon` is wedged, `git status` blocks until the IPC attempt fails (several minutes), and the 120s drain deadline fires first.
+
+Confirm by running `git status` in the affected worktree:
+
+```bash
+cd <worktree>
+time git --no-optional-locks status --porcelain
+# error: could not read IPC response → hung daemon
+```
+
+List running daemons with their IPC socket (identifies which worktree each serves):
+
+```bash
+for pid in $(pgrep -f 'git fsmonitor--daemon'); do
+ sock=$(lsof -p $pid 2>/dev/null | grep 'fsmonitor--daemon.ipc' | awk '{print $NF}' | head -1)
+ printf "%6d %s\n" "$pid" "$sock"
+done
+```
+
+Sockets listed as bare `fsmonitor--daemon.ipc` (no resolved path) belong to deleted worktrees — safe to kill:
+
+```bash
+for pid in $(pgrep -f 'git fsmonitor--daemon'); do
+ sock=$(lsof -p $pid 2>/dev/null | grep 'fsmonitor--daemon.ipc' | awk '{print $NF}' | head -1)
+ [ "$sock" = "fsmonitor--daemon.ipc" ] && kill -9 $pid
+done
+```
+
+For a specific hung worktree, kill the daemon whose socket path matches it, or just `pkill -9 -f 'git fsmonitor--daemon'` and let the next `wt list` respawn the live ones. Disabling fsmonitor globally (`git config --global core.fsmonitor false`) avoids the class of problem entirely at the cost of some `git status` speed on large repos.
+
+Daemons leak when a worktree is removed while its daemon is already unresponsive — `wt remove` calls `git fsmonitor--daemon stop`, but a daemon that can't answer its IPC can't be stopped through it.
+
## PowerShell on Windows
### PowerShell profiles not created