Windows: stale port holder + aggressive spawn cooldown blocks prompts for ~15 min (fail-loud threshold 3 too low)

[renato-proxtech]

Summary

On Windows, when the worker's fixed port is already held by a stale/orphaned worker (common with concurrent Claude Code sessions sharing the singleton worker), every spawn attempt fails with Is port <port> in use?. The spawn cooldown then suppresses retries for ~15 minutes, during which the worker stays down. Because the hook fail-loud counter increments on every hook in that window and the default CLAUDE_MEM_HOOK_FAIL_LOUD_THRESHOLD is only 3, the plugin starts blocking user prompts within seconds of the worker going down and stays blocking for the whole outage.

Net effect: a transient port conflict turns into ~15 minutes of blocked prompts (claude-mem worker unreachable for N consecutive hooks.), even though the worker self-heals once the stale port holder is released.

Environment

• claude-mem: 13.6.2 (latest, installed via marketplace)
• OS: Windows 11 Pro (10.0.26200)
• Runtime: bun 1.3.13, node 24.14.1
• Claude Code CLI: v2.1.181
• CLAUDE_MEM_WORKER_PORT: pinned to a fixed value in settings.json
• Multiple concurrent Claude Code sessions on the same user/machine (sharing the one singleton worker)

What I observed (log excerpts)

Outage ran ~15 minutes, from the first bind failure at 20:00:04 to recovery at 20:15:20.

[20:00:04.787] [ERROR] [SYSTEM] ✗ Worker failed to start  Failed to start server. Is port 41777 in use?
[20:00:13.823] [WARN ] [SYSTEM] Worker unavailable on Windows — skipping spawn (recent attempt failed within cooldown)
[20:00:13.855] [INFO ] [SYSTEM] Another launcher holds the spawn lock — skipping lazy-spawn and waiting for its worker
[20:00:29.412] [WARN ] [SYSTEM] Spawn-lock holder's worker port did not open within the cold-boot wait (~15s)
[20:00:35.264] [ERROR] [SYSTEM] ✗ Worker failed to start  Failed to start server. Is port 41777 in use?
...  (repeats every ~20-40s for ~15 min)  ...
[20:15:20.441] worker.pid rewritten, fresh worker bound the port successfully

The UserPromptSubmit hook surfaced: claude-mem worker unreachable for 58 consecutive hooks. and blocked the prompt.

Root cause (my read)

1. The worker is a singleton on a fixed port. When a stale worker process keeps the port bound but is not answering health checks, new spawns fail at bind.
2. The Windows spawn cooldown ("recent attempt failed within cooldown") suppresses retries instead of forcing a rebind / reaping the stale holder, so the down state persists for ~15 min.
3. The fail-loud threshold default of 3 is far too low relative to how often hooks fire (PostToolUse fires per tool call), so the block trips almost immediately and lasts the entire outage.

Suggested fixes

1. Reap the stale port holder (or fall back to a fresh ephemeral port) when bind fails with "port in use" and no healthy worker answers, instead of entering a long cooldown.
2. Shorten or bypass the cooldown specifically for the "port in use but no healthy worker" case, since that is exactly when a fast retry/reap is needed.
3. Raise the default CLAUDE_MEM_HOOK_FAIL_LOUD_THRESHOLD (3 is too sensitive on Windows where transient worker restarts are common), or make the hook fail-open by default and only fail-loud after a sustained, time-based outage rather than a raw consecutive-hook count.

Workaround

Setting CLAUDE_MEM_HOOK_FAIL_LOUD_THRESHOLD to 30 in settings.json stops transient worker restarts from blocking prompts (memory capture just pauses and resumes when the worker recovers). Manually killing the stale worker (worker.pid) + removing supervisor.json forces a clean respawn for the rare hard hang.

[quinnmacro]

Reproduced on my setup — adding my experience as a second data point.

Environment:

• OS: Windows 11
• Runtime: bun 1.3.12, Node v24.14.1
• claude-mem: 13.6.2 (latest)
• Claude Code CLI: multiple concurrent sessions on the same machine
• Worker port: 37778 (fixed)

What I saw in my logs:

Data across several days of regular multi-window usage:

Date	Log lines	Worker start fails	Cooldown skips	Health fails
2026-06-15	59,378	729	347	381
2026-06-16	108,208	89	27	24
2026-06-18	122,825	788	344	391
2026-06-19	7,018	-	-	38

Typical outage pattern on 6/18:

1. Worker dies or becomes unresponsive
2. Next hook tries to lazy-spawn → bind fails on port 37778
3. Windows spawn cooldown kicks in → no retries for ~15 min
4. Every PostToolUse hook fires frequently, consecutive failure counter climbs past default threshold of 3
5. Within seconds: prompts are blocked

A single port conflict turns into ~15 minutes of complete Claude Code paralysis across all my open windows.

The most damaging part for my workflow: when the worker goes down, it blocks ALL concurrent Claude Code windows simultaneously, not just the one that triggered the spawn. This makes multi-window work feel quite fragile.

Workarounds I am using now (still on v13.6.2):

1. CLAUDE_MEM_HOOK_FAIL_LOUD_THRESHOLD=30 (gives worker ~2-3 min to self-heal before blocking)
2. CLAUDE_MEM_WORKER_HOST=127.0.0.1 (avoids IPv6 localhost resolution timeout, cf. [Windows] Hook times out after 29s — localhost resolves to ::1 (IPv6) first but worker only listens on 127.0.0.1 (IPv4) #2992)
3. Wrote a small watchdog.py loop (checks health every 30s, kills stale PIDs, refreshes failure counter, restarts worker)

With these workarounds it is much more stable, but the underlying race condition between stale port holder and new spawns still exists. Looking forward to the fix!

[thedotmack]

Consolidating into #3603 (plan-15). The root cause and fix sequencing are tracked there alongside the rest of the cluster — please follow that issue for progress.