Windows: automatic plugin update kills stale worker but fails to restart when the old port remains bound

[github-actions[bot]]

Originally posted as issue #3780 by @F12tcl
#3780

Environment

• OS: Windows 11
• Claude Code: 2.1.250
• claude-mem: upgraded from 13.16.0 to 13.16.1
• Runtime: Bun on Windows
• Worker host: 127.0.0.1
• Original worker port: 37777

Problem

After claude-mem automatically updated from 13.16.0 to 13.16.1, the old worker was detected as a version mismatch and terminated. However, the worker port remained bound to the old PID even after the process no longer existed.

As a result, claude-mem repeatedly detected the port as occupied but could not connect to the worker health endpoint or start the new worker.

Relevant log sequence

The old worker initially started normally:

[2026-08-26 12:13:06.429] Worker started {host=127.0.0.1, port=37777, pid=10912}
[2026-08-26 12:13:07.241] Worker started successfully

After the plugin was updated:

[2026-08-27 10:10:45.442] Worker version mismatch — killing stale worker {pluginVersion=13.16.1, workerVersion=13.16.0}
[2026-08-27 10:11:39.634] Removing stale PID file (worker process is dead or PID has been reused) {pid=10912, port=37777}

After that, startup repeatedly failed:

Port in use, waiting for worker to become healthy
Port in use but worker not responding to health checks
Worker failed to start before hook, handler will proceed gracefully
Worker port did not open after lazy-spawn within the cold-boot wait

##Observed Windows state
tasklist and Get-Process confirmed that PID 10912 no longer existed, but Windows still reported:

TCP 127.0.0.1:37777  0.0.0.0:0  LISTENING  10912

There were also multiple CLOSE_WAIT and FIN_WAIT_2 connections associated with the same port.
The health endpoint was unreachable:

http://127.0.0.1:37777/api/health
→ connection refused

The standard worker restart command could not recover because it waited for port 37777 to become free:

Shutdown request failed unexpectedly
Port still bound entering restart fallback — verifying current port owner instead of spawning

Impact

• Automatic updates leave the worker unavailable.
• Hooks repeatedly fail or continue in degraded mode.
• The stale port prevents both normal startup and restart.
• The issue requires manual intervention.
  Workaround
  Changing CLAUDE_MEM_WORKER_PORT from 37777 to an unused port (37778) allowed the worker to start successfully.
  The new worker then passed:
• /api/health with HTTP 200
• Database initialization
• Search service initialization
• MCP loopback self-check
• Standard restart verification
  Expected behavior
  After a plugin update:

1. The old worker should shut down gracefully.
2. The launcher should wait until the old port is actually free.
3. The new worker should start automatically.
4. The launcher should verify that /api/health reports the new plugin version.
5. If the old port remains stuck on Windows, the launcher should recover automatically or fall back to another port.
   Possible implementation direction

• Trigger worker-service restart directly after a successful plugin update instead of only emitting an upgrade hint.
• Make the restart flow version-aware and verify the new worker version through /api/health.
• On Windows, verify the process PID, command line, and process start time before attempting to terminate it.
• Add a bounded retry/backoff for port cleanup.
• If the port remains bound but the owning process no longer exists, avoid waiting indefinitely and use a configured fallback port or another recovery path.
• Consider keeping a stable supervisor process that owns the port while worker versions are replaced underneath it.
  Could this be a known Bun/Windows socket cleanup issue, or should the worker upgrade/restart flow handle this state explicitly?

[lab1207]

Your logs map precisely onto the restart flow in current main, and they show the gap is in the recovery path, not the kill. Walking it (src/services/worker-spawner.ts + src/shared/port-reclaim.ts):

What worked. The version-mismatch kill fired correctly, and the stale PID file was removed once the process was confirmed dead. That half is fine.

Where your case lands. With the port bound and health unreachable, the spawner calls reclaimGhostListeningPort. That function only ever kills chroma sidecars — descendants of the dead owner by parent chain, or sidecars whose command line names this install's data dir. Your report shows a dead PID still LISTENING with no surviving sidecar holding it, which resolves to reclaimed: false, reason: 'no-chroma-descendants' — by design there is nothing safe to kill, so the spawner returns 'dead' on every subsequent attempt. Forever, until a human changes the port. Your workaround is the only exit the current code offers.

To your closing question (Bun bug vs restart-flow gap): the flow gap. A dead PID still showing LISTENING plus CLOSE_WAIT/FIN_WAIT_2 entries is Windows holding the orphaned socket transiently — no user-space kill target exists, so no amount of terminate logic fixes that instant. What the restart flow is missing for exactly this state:

1. Bounded retry with backoff on the same port before declaring dead — zombie rows clear on their own in seconds to minutes, and every one of your failed startups may have just been too early.
2. Automatic fallback to a free port after the bound expires (your manual 37777→37778, automated), then verify /api/health reports the new plugin version before calling it done.
3. Possible prevention: check whether the version-mismatch kill terminates the whole worker tree or just the PID — an inherited listening socket orphaned by a tree that wasn't fully reaped is what creates this state. Tree-kill on the mismatch path (the codebase already has killProcessTree with start-token identity) would shrink the window.

So: not Bun-specific, and not fixable by waiting on socket cleanup — the launcher needs the retry-then-fallback path for the no-chroma-descendants outcome.