StdioBridgeHost enters zombie state after Python server restart — accepts connections but never processes commands

[dsarno]

Summary

When the Python MCP server process restarts (e.g., via /mcp reconnect in Claude Code), Unity's StdioBridgeHost socket listener enters a zombie state — it accepts new TCP connections on port 6404 but never processes the incoming command data. The Unity Editor UI appears completely normal ("Session Active", green dot), and the server successfully connects and sends data, but Unity never responds.

Restarting the session from the Unity side (End Session + Start Session) immediately fixes the issue.

Reproduction Steps

1. Open a Unity project with MCP for Unity running (stdio transport, port 6404)
2. Connect from Claude Code — verify tool calls work
3. Run /mcp in Claude Code to reconnect (this kills and restarts the Python server process)
4. Immediately make tool calls — they all timeout

Observed Behavior

• Server discovers Unity on port 6404 (correct)
• TCP connections succeed (connect took 0.002s)
• Data sends succeed (sendall took 0.000s)
• Unity never responds — every command hits the 1-second socket timeout
• All 6 retry attempts fail for every command
• This persists indefinitely (tested for several minutes)
• Unity Editor UI shows "Session Active" with green dot, no errors in Console

Server Logs

14:10:29 [INFO]  send_command_with_retry START command=get_project_info
14:10:29 [INFO]  Discovered 1 Unity instances
14:10:29 [INFO]  connect took 0.001s command=get_project_info
14:10:29 [INFO]  sendall took 0.000s command=get_project_info
14:10:59 [WARN]  Socket timeout during framed receive
14:10:59 [WARN]  Unity communication attempt 1 failed: Timeout receiving Unity response
... (repeats through attempt 6, every command)

Key detail: the first timeout on get_project_info takes 30 seconds (14:10:29 → 14:10:59), suggesting a longer initial timeout. Subsequent retries timeout at 1 second each.

Expected Behavior

When the Python server restarts and opens new TCP connections to the same port, Unity should process commands from the new connections normally.

Root Cause Hypothesis

When the old Python server process dies, its TCP connections to Unity's socket listener are severed. The StdioBridgeHost may not properly clean up the old connection state, so when new connections arrive on the same port, the accept/read loop is stuck or blocked on the stale connection. The socket is listening (connections succeed) but the command dispatcher never reads from the new connections.

Resolution

End Session + Start Session in the Unity MCP window immediately fixes it, confirming the issue is in Unity-side socket state management.

Environment

• Unity 2021.3.45f2 (macOS)
• MCP for Unity v9.4.7-beta.8
• Stdio transport, port 6404
• Claude Code client

Notes

• This is not related to PR feat(stdio): add MCP tool toggle support with tools/list_changed notifications #763 (tool toggle). The socket listener and command processing code in StdioBridgeHost are untouched by that PR.
• telemetry_ping appears to succeed during the failure because it's handled server-side without a Unity round-trip.
• Reproduced on 2026-02-19. A previous session showed a different failure mode ("Discovered 0 Unity instances") which may be a separate intermittent issue or the same underlying cause manifesting differently.

[dsarno]

Updated Root Cause: Domain Reload Leaves Bridge in Zombie State

Summary

After a domain reload (script compilation), StdioBridgeHost can enter a zombie state where it accepts TCP connections and receives data, but never processes commands or sends responses. This is a pre-existing bug on upstream/beta, not a regression from PR #763.

Evidence

Confirmed on upstream/beta (v9.4.7-beta.8, commit 12dd9bd):

Server logs show a tool call at 14:58:36 that connected successfully, sent data, but never received a response:

14:57:27 — Server startup, auto-selected UnityMCPTests@cc8756d4 (port 6404) ✓
14:58:36 — read_console: connect=0.000s, sendall=0.000s
           (no receive — hung indefinitely, Unity never responded)
14:59:01 — Server killed by /mcp reconnect

The bridge was in this zombie state after a domain reload triggered by switching git branches (which modified C# files in the Unity package, causing recompilation).

Reproduction pattern:

1. Unity session is active and working
2. Something triggers a domain reload (script creation/deletion, branch switch, manual recompile)
3. StdioBridgeReloadHandler stops and restarts the bridge across the reload
4. After reload, the bridge appears healthy (port 6404 open, accepts connections, handshake works)
5. But commands sent to the bridge are never processed — all tool calls timeout
6. End Session + Start Session in Unity fixes it immediately

Additional observation — create_script always returns "reloading":

When create_script is called, Unity responds with "reloading" in a tight retry loop (every 250ms) for the entire retry window, even though the Unity UI shows the domain reload finished much earlier. Each retry creates a new TCP connection, sends the command, and gets a 258-byte "reloading" response in ~45ms. Unity IS responding, but always with "reloading." This appears to be a separate issue where the reloading state persists longer than the actual reload, or where the command itself re-triggers the reload check.

Root Cause Hypothesis

StdioBridgeReloadHandler.OnBeforeAssemblyReload() stops the bridge with:

var stopTask = MCPServiceLocator.TransportManager.StopAsync(TransportMode.Stdio);
try { stopTask.Wait(500); } catch { }  // Only 500ms!
try { StdioBridgeHost.Stop(); } catch { }

StdioBridgeHost.Stop() waits up to 2 seconds for the listener task to complete. If the 500ms StopAsync timeout + the subsequent Stop() don't fully clean up before the domain unloads managed state, the bridge restarts in a corrupted state where:

• The OS socket is listening (accepts connections)
• The handshake is sent (new HandleClientAsync tasks run)
• But ProcessCommands (registered on EditorApplication.update) either isn't firing or the command queue isn't being processed

The fact that End Session + Start Session fixes it confirms the issue is stale state from an incomplete stop/restart cycle.

Environment

• Unity 2021.3.45f2 (macOS)
• MCP for Unity v9.4.7-beta.8 (upstream/beta)
• Stdio transport, port 6404
• Claude Code client

Suggested Investigation Areas

1. ProcessCommands registration — is it properly re-registered on EditorApplication.update after reload?
2. processingCommands reentrancy guard — could it get stuck at 1 across a reload?
3. commandQueue state — could stale entries from pre-reload commands block processing?
4. The 500ms timeout in StopAsync().Wait(500) — is this sufficient for clean shutdown?

[dsarno]

Updated findings (2026-02-19)

Root cause narrowed: stdio-specific, NOT general background throttling

Key discovery: The domain reload stall when Unity is backgrounded is stdio-only. HTTP transport handles it fine.

Repro steps:

1. Connect via stdio transport
2. create_script to trigger domain reload
3. Stay in terminal (Unity backgrounded)
4. Any subsequent tool call (read_console, find_gameobjects) times out
5. Switching to Unity → reload completes → bridge restarts → everything works

Same test with HTTP transport: Works perfectly. Domain reload completes, HTTP reload resumes on attempt 1, tool calls respond immediately — all while Unity is backgrounded.

What this tells us

• Unity main loop IS running when backgrounded (HTTP proves it)
• Something specific to StdioBridgeHost or StdioBridgeReloadHandler stop/restart cycle stalls when Unity is backgrounded
• Likely candidate: StdioBridgeHost.Start() has a socket bind retry loop with Thread.Sleep(200ms) that blocks the main thread
• Or: StdioBridgeReloadHandler.OnBeforeAssemblyReload() 500ms timeout for StopAsync().Wait(500) may not complete cleanly when backgrounded

Environment

• macOS 26.3 Tahoe (Darwin 25.3.0) — freshly updated, user reports not seeing this before the update
• NSAppSleepDisabled = 1 (App Nap disabled for Unity)
• Unity 6 LTS, upstream/beta v9.4.7-beta.8

Zombie state fix (separate)

The original zombie state bug (bridge running but not processing commands) is fixed in commit 92b7d96 on fix/stdio-bridge-zombie-785. That fix addresses stale client cleanup, ProcessCommands self-healing, and stale command eviction. But this backgrounding stall is a separate issue that the zombie fix does not address.

Next investigation

• Where exactly do stdio and HTTP reload paths diverge?
• Can stdio reload handler be made more like HTTP?
• What specifically in the stdio path blocks the main thread during backgrounded domain reload?

[dsarno]

Fix submitted in #787.

Root causes identified (multiple contributing factors):

1. ProcessCommands deregistered during domain reload — Stop() removed the EditorApplication.update callback, and all delegates are cleared on reload anyway. This left a gap where commands queued on the TCP thread but ProcessCommands never ran to dispatch them on the main thread.

2. No QueuePlayerLoopUpdate in stdio path — when Unity is backgrounded (not focused), the main loop stops iterating, so even when ProcessCommands was registered, it never fired. HTTP avoids this via TransportCommandDispatcher.RequestMainThreadPump() which calls QueuePlayerLoopUpdate, but stdio had no equivalent.

3. Single-shot reload handler — TryStartBridgeImmediate() attempted one StartAsync and gave up on failure, leaving the bridge permanently dead if the port was temporarily busy during reload.

4. macOS AssetImportWorkers stealing TCP connections — SO_REUSEADDR (the default on macOS) allowed Unity AssetImportWorker child processes to bind the same port as the main editor. These workers loaded the same compiled assemblies and could accept TCP connections, but had no command processing pipeline. Connections were silently routed to workers instead of the main editor, causing the "accepts but never processes" symptom.

5. IsPortAvailable() returned false positives — the port probe in PortManager used a plain TcpListener (which defaults to SO_REUSEADDR), so DiscoverNewPort() reported occupied ports as available and returned the same port, making the fallback useless.

Fixes applied:

• Keep ProcessCommands permanently registered (static guard, never deregistered)
• Add QueuePlayerLoopUpdate() after command enqueue
• Replace single-shot reload handler with async retry loop (6 attempts with backoff)
• Use ExclusiveAddressUse on both the real listener and the port probe to prevent worker port conflicts
• Add PortManager unit tests