claude-code - 💡(How to fix) Fix claude agents deadlocks when launched with UNC / SMB-mapped working directory (Windows 11)

Summary

claude agents (Claude Code v2.1.139, Windows 11) deadlocks indefinitely when launched with a working directory on a SMB-mapped drive / UNC path. The foreground process becomes silent — no output, no Ctrl+C handling. Closing the terminal window leaves the process running as a child of the Claude daemon. Other Claude Code sessions in the same shell environment continue working; only the agents subcommand wedges.

Environment

• Claude Code: 2.1.139 (CLI at C:\Users\<user>\.local\bin\claude.exe)
• OS: Windows 11 Pro 10.0.26200
• Shell: PowerShell 7, Windows Terminal
• CWD when launched: V:\dansvault → mapped to \mercer\vault\dansvault (SMB share on local LAN, kernel SMB session healthy throughout the hang)

Proof it's NOT a server-side SMB issue

• Ping to SMB host: 0 ms during hang.
• Get-SmbConnection shows TCP 445 Established (PID 4 / System) at moment of hang.
• Get-ChildItem V:\dansvault from a separate PowerShell returns instantly during the hang.
• Zero SMB / Mup / Rdr / LanmanWorkstation events in the System log around hang time.
• Zero Application Hang / Application Error / WER events for node.exe or claude.exe.

Proof of a real deadlock (5-second perf sample)

Zero CPU progress, 51 threads parked, working set stable. Rules out V8 GC death-spiral, runaway loop, and OOM.

Likely root cause — directory handle on the UNC root

handle.exe against the frozen PID reports:

58: File   \Device\Mup\mercer\vault\dansvault\

That's a directory handle on the Multiple UNC Provider for the cwd. Combined with the 51-threads-at-zero-CPU pattern, this is consistent with a ReadDirectoryChangesW (or equivalent libuv uv_fs_event / chokidar / fs.watch) subscription that the agents subsystem opens to monitor agent/skill files in the project root.

ReadDirectoryChangesW over UNC has documented edge cases — notifications can be lost or never delivered when the SMB session renegotiates, when offline caching is enabled, or when oplock breaks intersect with watcher buffer fills. The hypothesis is that an I/O completion never returns and a sync code path is waiting on it. Without symbols I can't confirm which thread / which path, but the handle list plus zero-progress signature points firmly there.

Reproduction (suggested)

1. On Windows 11, map an SMB share as a drive letter (net use V: \<host>\<share>).
2. cd V:\<some dir>.
3. claude agents. Leave it running.
4. Hang reproduces within minutes in our environment.

We have observed it on this box across several days, in different terminal windows, with both freshly-launched and long-running invocations. Always claude agents specifically, never the regular session worker.

Daemon behaviour

Claude daemon (claude.exe daemon run) does not detect the wedge. The frozen worker stays in the roster indefinitely. daemon.log shows two unrelated worker kills earlier in the day (bg settled <id> (killed)) but never reaps the hung agents process.

Artifacts captured (available on request)

• agents-62300.dmp — 855 MB full memory dump (procdump -ma) — contains all 51 thread stacks + heap.
• 02-handles.txt — Sysinternals handle list output.
• Process metadata + 5-sample perf trace.

Path on reporter's machine: C:\Users\<user>\Desktop\claude-agents-hang-20260512-150624\. Happy to upload the dump out-of-band if Anthropic wants it.

Workaround

Launch Claude Code from a local-disk working directory (e.g. mirror V:\dansvault to C:\dansvault). The hang has not reproduced when cwd is on local NTFS.

Why this matters

The new agents subcommand is otherwise great, but on Windows + UNC workflows (which is common for users keeping work on NAS/server shares) it's a hard wedge that requires force-closing the terminal and leaves orphaned worker processes behind. The daemon's own health-check doesn't notice, so RAM accumulates.