beta branch: when Claude Code reconnects, Unity session becomes "no session" even though handshake succeeds. This breaks the workflow completely. Logs attached. But Sometimes it works,and the bug only occurs in beta by using http to connect

[whatevertogo]

the python server:

[01/29/26 00:27:10] INFO Starting MCP server 'mcp-for-unity-server' with transport 'http' on server.py:2618
http://localhost:8080/mcp
INFO: Started server process [47480]
INFO: Waiting for application startup.
2026-01-29 00:27:10,235 - docket.worker - INFO - Starting worker 'mylove#47480' with the following tasks:
2026-01-29 00:27:10,235 - docket.worker - INFO - * trace(message: str, ...)
2026-01-29 00:27:10,235 - docket.worker - INFO - * fail(message: str, ...)
2026-01-29 00:27:10,235 - docket.worker - INFO - * sleep(seconds: float, ...)
2026-01-29 00:27:10,236 - mcp.server.streamable_http_manager - INFO - StreamableHTTP session manager started
INFO: Application startup complete.
INFO: Uvicorn running on http://localhost:8080 (Press CTRL+C to quit)
INFO: ('::1', 60557) - "WebSocket /hub/plugin" [accepted]
INFO: connection open
2026-01-29 00:27:20,308 - mcp.server.streamable_http_manager - INFO - Created new transport with session ID: 4cefe6618a6d4f468265163a4df0d52f
INFO: ::1:60562 - "POST /mcp HTTP/1.1" 200 OK
INFO: ::1:60562 - "POST /mcp HTTP/1.1" 202 Accepted
INFO: ::1:60562 - "GET /mcp HTTP/1.1" 200 OK
2026-01-29 00:27:20,319 - asyncio - ERROR - Task exception was never retrieved
future: <Task finished name='Task-38' coro=<IocpProactor.accept..accept_coro() done, defined at C:\Users\18794\AppData\Roaming\uv\python\cpython-3.13.11-windows-x86_64-none\Lib\asyncio\windows_events.py:564> exception=OSError(22, 'The specified network name is no longer available.', None, 64, None)>
Traceback (most recent call last):
File "C:\Users\18794\AppData\Roaming\uv\python\cpython-3.13.11-windows-x86_64-none\Lib\asyncio\windows_events.py", line 567, in accept_coro
await future
File "C:\Users\18794\AppData\Roaming\uv\python\cpython-3.13.11-windows-x86_64-none\Lib\asyncio\windows_events.py", line 804, in _poll
value = callback(transferred, key, ov)
File "C:\Users\18794\AppData\Roaming\uv\python\cpython-3.13.11-windows-x86_64-none\Lib\asyncio\windows_events.py", line 556, in finish_accept
ov.getresult()
~~~~~~~~~~~~^^
OSError: [WinError 64] The specified network name is no longer available.
2026-01-29 00:27:20,321 - asyncio - ERROR - Accept failed on a socket
socket: <asyncio.TransportSocket fd=960, family=2, type=1, proto=0, laddr=('127.0.0.1', 8080)>
Traceback (most recent call last):
File "C:\Users\18794\AppData\Roaming\uv\python\cpython-3.13.11-windows-x86_64-none\Lib\asyncio\proactor_events.py", line 845, in loop
conn, addr = f.result()
~~~~~~~~^^
OSError: [WinError 64] The specified network name is no longer available.
INFO: ::1:60564 - "POST /mcp HTTP/1.1" 200 OK
INFO: ::1:60566 - "POST /mcp HTTP/1.1" 200 OK

the Unity Console:

<color=#2EA3FF>MCP-FOR-UNITY: [WebSocket] Registered with session ID: 61d3bedc-964c-4336-8955-49fadb0a14e8
UnityEngine.Debug:Log (object)
MCPForUnity.Editor.Helpers.McpLog:Info (string,bool) (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Helpers/McpLog.cs:40)
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__41:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:422)
System.Runtime.CompilerServices.AsyncTaskMethodBuilder:Start<MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__41> (MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__41&)
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient:HandleRegisteredAsync (Newtonsoft.Json.Linq.JObject,System.Threading.CancellationToken)
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__39:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:382)
System.Runtime.CompilerServices.AsyncTaskMethodBuilder:Start<MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__39> (MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__39&)
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient:HandleMessageAsync (string,System.Threading.CancellationToken)
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__37:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:293)
System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1:SetResult (string)
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__38:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:359)
System.Threading._ThreadPoolWaitCallback:PerformWaitCallback ()

<color=#2EA3FF>MCP-FOR-UNITY: [WebSocket] Preparing to register 19 tool(s) with the bridge.
UnityEngine.Debug:Log (object)
MCPForUnity.Editor.Helpers.McpLog:Info (string,bool) (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Helpers/McpLog.cs:40)
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__42:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:435)
System.Threading._ThreadPoolWaitCallback:PerformWaitCallback ()

<color=#2EA3FF>MCP-FOR-UNITY: [WebSocket] Sent 19 tools registration
UnityEngine.Debug:Log (object)
MCPForUnity.Editor.Helpers.McpLog:Info (string,bool) (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Helpers/McpLog.cs:40)
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__42:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:475)
System.Runtime.CompilerServices.AsyncTaskMethodBuilder:SetResult ()
MCPForUnity.Editor.Services.Transport.Transports.WebSocketTransportClient/d__47:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:619)
System.Threading._ThreadPoolWaitCallback:PerformWaitCallback ()

<color=#6AA84F>MCP-FOR-UNITY: Connection verification successful: Transport 'websocket' connected [ws://localhost:8080/hub/plugin]
UnityEngine.Debug:Log (object)
MCPForUnity.Editor.Helpers.McpLog:Debug (string) (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Helpers/McpLog.cs:34)
MCPForUnity.Editor.Windows.Components.Connection.McpConnectionSection/d__54:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Windows/Components/Connection/McpConnectionSection.cs:780)
System.Runtime.CompilerServices.AsyncTaskMethodBuilder1<MCPForUnity.Editor.Services.BridgeVerificationResult>:SetResult (MCPForUnity.Editor.Services.BridgeVerificationResult) MCPForUnity.Editor.Services.BridgeControlService/<VerifyAsync>d__15:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/BridgeControlService.cs:136) System.Runtime.CompilerServices.AsyncTaskMethodBuilder1:SetResult (bool)
MCPForUnity.Editor.Services.Transport.TransportManager/d__16:MoveNext () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Services/Transport/TransportManager.cs:120)
UnityEngine.UnitySynchronizationContext:ExecuteTasks ()

<color=#2EA3FF>MCP-FOR-UNITY: Server no longer running; ending orphaned session.
UnityEngine.Debug:Log (object)
MCPForUnity.Editor.Helpers.McpLog:Info (string,bool) (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Helpers/McpLog.cs:40)
MCPForUnity.Editor.Windows.Components.Connection.McpConnectionSection:UpdateConnectionStatus () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Windows/Components/Connection/McpConnectionSection.cs:299)
MCPForUnity.Editor.Windows.MCPForUnityEditorWindow:OnEditorUpdate () (at D:/GitObjectsOwn/unity-mcp/unity-mcp/MCPForUnity/Editor/Windows/MCPForUnityEditorWindow.cs:373)
UnityEditor.EditorApplication:Internal_CallUpdateFunctions ()

[dsarno]

I just pushed a new beta -- can you let me know if it works better for this? Claude Code has been working fine for me and I've been using the new branch for several days. You just have to make sure you press the "register/unregister" button for claude, and possibly exit claude to get the new configuration activated.

Should also have the improved parameter robustness you were talking about. Thanks!

[whatevertogo]

I just pushed a new beta -- can you let me know if it works better for this? Claude Code has been working fine for me and I've been using the new branch for several days. You just have to make sure you press the "register/unregister" button for claude, and possibly exit claude to get the new configuration activated.

Should also have the improved parameter robustness you were talking about. Thanks!

Thank you for your work. After testing, I found two distinct issues:
When Claude Code reconnects to a healthy/running MCP server, it still triggers the "no session" error in the Unity bridge (stdio works normally).
More specifically: repeatedly restarting the MCP server (which appears to be the necessary trigger condition) combined with multiple Claude Code reconnections causes Unity to freeze. Strangely, it occasionally works fine, which is confusing.
This issue only exists in the beta version, not in the stable release.

I'm currently busy with Global Game Jam, but I'll investigate further and provide you with more details once the jam is finished.

Also, I noticed the tool calls are significantly faster. This refactoring was really effective!

[dsarno]

Should be fixed in #656, which is now in beta -- part of upcoming release to main project.

[dsarno]

Thanks for flagging this @whatevertogo !

[dsarno]

@whatevertogo also, if you're interested, here's the bug investigation "report / plan" I used with claude code to track this down. It has the "history" and "hypotheses" we started with. It took a while and a lot of experimenting. But it was useful to have the document to keep me and claude going in the right direction.

Investigation: Issue #654 #643 - Dispatcher Becomes Unreachable After Test Failures

---

🔴 CURRENT STATUS (2026-01-30)

The Problem

After running a full test suite (564 tests), the dispatcher becomes unreachable ("No Unity Editor instances found"), but telemetry falsely reports success.

Root Cause: Unity Domain Reload + Short Reconnection Timeout

1. Tests complete → Unity triggers domain reload (restarts all editor code including MCP bridge)
2. MCP connection drops during domain reload
3. Server tries to reconnect but timeout is too short (2s default, domain reload takes 10-30s)
4. Server gives up → "No Unity Editor instances found"
5. Telemetry still works because it doesn't actually check dispatcher health

Proposed Fix (IMPLEMENTED BUT NOT TESTED)

Increased reconnection timeouts from 2s to 30s in:

• Server/src/transport/plugin_hub.py:427 - UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S
• Server/src/transport/legacy/unity_connection.py:771 - UNITY_MCP_RELOAD_MAX_WAIT_S
• Server/src/transport/legacy/unity_connection.py:421 - Backoff cap when reloading

⚠️ CRITICAL: Fix Not Yet Validated

• Changes are in git but server was NOT restarted
• One test run appeared to work, but that was with OLD code (lucky timing?)
• Concern: 30s default may make ALL commands slow, not just post-reload ones

Next Steps

1. Restart MCP server to apply Python changes
2. Run full test suite and time how long commands take afterward
3. Verify: Commands should be fast when session exists, only wait 30s when no session
4. If commands are slow: Rethink approach - maybe only increase timeout AFTER detecting domain reload, not globally

Open Questions

• Is 30s timeout too aggressive for normal operation?
• Should we detect "domain reload just happened" and only then use longer timeout?
• Why did the test pass once without the fix being active? (Timing luck?)

---

Background: How We Got Here

Initial Hypothesis (WRONG)

"PropertyConversion exceptions are crashing the dispatcher"

Investigation Findings (CORRECT)

1. PropertyConversion exceptions ARE properly caught in try-catch blocks ✅
2. Individual PropertyConversion error tests do NOT crash dispatcher ✅
3. Full test suite DOES crash dispatcher ❌
4. Root cause is domain reload after tests, not PropertyConversion itself

The Real Issue (CONFIRMED)

• Unity Test Framework triggers domain reload after test suite completes
• Domain reload restarts MCP bridge, dropping the connection
• Server's reconnection timeout (2s) is too short for domain reload (10-30s)
• Server gives up and marks instance as unavailable

---

Evidence

Test Results When Full Suite Runs

Failures recorded in test run:

PropertyConversion_ArrayForFloat_Test.SetProperty_ArrayForFloat_ReturnsError
  Message: "Unhandled log message: '[Error] MCP-FOR-UNITY: Error converting token to System.Single...'"

PropertyConversionErrorHandlingTests.ManageComponents_MultipleSetPropertyFailures_DispatcherStaysResponsive
  Message: "Unhandled log message: '[Error] MCP-FOR-UNITY: Error converting token to System.Single...'"

Dispatcher Status After Full Suite

telemetry_ping:  {"success": true}  ← FALSE POSITIVE
manage_scene:    {"error": "No Unity Editor instances found"}  ← REAL STATE

When Same Tests Run Individually

• PropertyConversion_ArrayForFloat_Test.cs alone: ✅ PASSES, dispatcher lives
• PropertyConversionErrorHandlingTests.cs alone: ✅ PASSES, dispatcher lives
• Full suite (564 tests): ❌ CRASHES dispatcher

Clear Pattern

Scenario	Dispatcher Status	Test Runner Status
Individual PropertyConversion tests	✅ Alive	✅ Pass or skip errors
Full suite with error-generating tests	❌ Dead	❌ Reports "unhandled log message" failures
Full suite without PropertyConversion tests	? (untested)	? (untested)

---

Architectural Understanding

How Test Results Flow (Normal Operation)

1. Test Runner executes tests, captures results via Unity Test Framework
2. TestJobManager (C#) stores test results, tracks failures
3. TestRunnerService converts results to MCP payload
4. Python run_tests tool returns results via MCP protocol
5. Client receives test status

How Test Results Flow (When Test Failures Occur)

1. Test runner detects "unhandled" error logs → marks test as "Failed"
2. Failure stored in TestJobManager.FailuresSoFar
3. Job status set to TestJobStatus.Failed
4. Results serialized and returned via MCP
5. AT THIS POINT: Something breaks ❌

What We Know About Dispatcher Crash

• Happens AFTER test suite completes (progress shows 564/564)
• Does NOT happen during test execution
• Does NOT happen with individual tests
• ONLY happens when multiple tests report failures due to unhandled logs
• Dispatcher becomes completely unreachable (not just temporarily unavailable)
• Telemetry still responds (proving dispatcher process is alive but instance registry is corrupted)

---

The Mystery: What Actually Breaks?

Three Possibilities

1. Instance Registry Corruption

   • Test failure reporting might corrupt the instance registry
   • When instance registry is cleared/corrupted, "No Unity Editor instances found"
   • Telemetry bypasses instance registry (just returns hardcoded success)
   • Need to investigate: Does test failure reporting interact with instance registry?

2. WebSocket/Stdio Connection Loss

   • Test failure reporting might interrupt the transport connection
   • Dispatcher process still alive, but no active connection
   • Subsequent commands fail because no valid session/connection
   • Need to investigate: Does test failure reporting affect connection state?

3. Dispatcher Command Queue Corruption

   • Multiple unhandled log messages might corrupt the command queue/pending requests
   • Dispatcher gets confused about which commands are active
   • System reaches an invalid state
   • Need to investigate: Does dispatcher track pending commands during test failures?

---

Known Code Paths

Test Failure Reporting (C#)

• File: MCPForUnity/Editor/Services/TestJobManager.cs
• Method: FinalizeCurrentJobFromRunFinished() (lines 357-378)
• Method: OnLeafTestFinished() (lines 425-454)
• Serialization: ToSerializable() (lines 519-557)

Test Result Polling (Python)

• File: Server/src/services/tools/run_tests.py
• Function: get_test_job() (lines 218-317)
• Returns test status and failure details

Instance Registry (Python)

• File: Server/src/transport/plugin_registry.py
• File: Server/src/transport/plugin_hub.py (on_disconnect hook at lines 107-137)
• When dispatcher connection lost, instance is unregistered

Telemetry False Positive (Python)

• File: Server/src/services/tools/manage_editor.py (lines 39-44)
• Returns hardcoded success without checking dispatcher health

---

Questions to Answer

Immediate

1. When test failures are reported, what happens to the instance registry?

   • Does it get cleared?
   • Does on_disconnect() get called?
   • Are session IDs preserved?

2. Does the test failure message/payload corrupt something?

   • Is there a size limit exceeded?
   • Is there a serialization issue?
   • Is there an encoding problem?

3. Why do individual tests not trigger this?

   • What's different between running one test and running 564?
   • Is it cumulative? (i.e., test 1 doesn't break it, test 50 doesn't, but test 564 does)
   • Is it a combination of other test failures + PropertyConversion failures?

Secondary

4. Is the issue in the test framework → dispatcher communication?

   • Does the failure report payload cause an exception in the dispatcher?
   • Does it interrupt the message pump?
   • Does it cause a protocol deserialization error?

5. Could this be a timing/race condition?

   • Domain reloads during testing?
   • Session changes during test execution?
   • Connection state changes while tests are running?

---

Test Files for Reproduction

Created Test Files

• Assets/Tests/EditMode/Tools/PropertyConversion_IntegerForObjectRef_Test.cs - Safe alone
• Assets/Tests/EditMode/Tools/PropertyConversion_ArrayForFloat_Test.cs - Safe alone
• Assets/Tests/EditMode/Tools/PropertyConversion_DirectAPI_Test.cs - Safe alone
• Assets/Tests/EditMode/Tools/PropertyConversionErrorHandlingTests.cs - Safe alone (8 tests)

Reproduction Steps

1. Run individual test files → ✅ Dispatcher lives
2. Run full test suite (564 tests) → ❌ Dispatcher dies

---

Investigation Plan (Data-Driven Approach)

Phase 1: Strategic Instrumentation

Goal: Add logging to determine which mechanism is breaking

Step 1.1: Instance Registry State Tracking

• Location: Server/src/transport/plugin_registry.py and Server/src/transport/plugin_hub.py
• Log instance count before test suite completes
• Log instance count when subsequent commands fail
• Log all calls to on_disconnect() with timestamps and reasons
• Action: Add structured logging around instance registration/deregistration

Step 1.2: Connection State Tracking

• Location: MCPForUnity/Editor/Services/Transport/WebSocketTransportClient.cs
• Log connection state at test suite completion
• Log any disconnection events with stack trace
• Log reconnection attempts
• Action: Add C# Debug.Log statements tracking connection lifecycle

Step 1.3: Dispatcher Command Queue Tracking

• Location: MCPForUnity/Editor/Services/Transport/TransportCommandDispatcher.cs
• Log pending command count before/after test completion
• Log any command queue state changes
• Action: Add logging for pending command lifecycle

Phase 2: Test Run and Data Collection

Goal: Trigger the bug and capture logs from all three instrumentation points

• Run full 564-test suite with instrumentation active
• Capture Python dispatcher logs
• Capture C# editor logs
• Mark exact timestamps when:
  • Last test completes
  • Test failure reported
  • First subsequent command fails ("No instances found")

Phase 3: Root Cause Analysis

Goal: Use collected data to definitively identify which mechanism broke

Expected outcomes (one will be true):

• If Instance Registry is corrupted: We'll see on_disconnect() called unexpectedly, instance count drops to 0
• If Connection is lost: We'll see WebSocket state change to disconnected around test completion time
• If Command Queue is corrupted: We'll see pending command tracking get stuck or confused

Phase 4: Fix Implementation

Once we know what breaks: Fix it appropriately for that mechanism

---

Progress Log

2026-01-30 - Investigation Started

Decision Made: Use data-driven approach

• Will instrument the system to observe behavior rather than speculate
• Focus on instance registry → WebSocket → command queue in priority order
• Track findings in this document as we progress

Findings: ROOT CAUSE IDENTIFIED ✅

The Real Issue: Unity Domain Reload After Tests

This is NOT about test failures crashing the dispatcher. It's about Unity domain reload after test completion.

What Actually Happens:

1. Tests complete (564/564) ✅
2. Unity Test Framework triggers domain reload after tests finish
3. Domain reload restarts ALL editor code, including MCP bridge
4. Legacy stdio connection sees "Connection closed before reading expected bytes"
5. Server tries to reconnect, but Unity isn't ready yet (still in domain reload)
6. Server gets "MCP for Unity requires FRAMING=1, got: ''" - Unity not responding
7. After multiple failed reconnection attempts → "No Unity Editor instances found"

Evidence from Logs:

13:09:11 - get_test_job returned successfully (564/564, 5 failures) ✅
13:09:23 - manage_scene called
13:09:25 - "Connection closed before reading expected bytes" ← CONNECTION LOST
13:09:30 - "MCP for Unity requires FRAMING=1, got: ''" ← Unity in domain reload
13:09:30+ - Multiple reconnection attempts fail

Why Our Debug Logging Didn't Fire:

• No [Issue #654 DEBUG] entries appeared in Python logs
• This means WebSocket/PluginHub transport is NOT being used
• The legacy stdio transport (unity_connection.py) is in use
• Our logging was added to plugin_hub.py (WebSocket), not the legacy transport

The Bug:

• Domain reload is EXPECTED after tests finish
• The bug is that reconnection doesn't handle domain reload gracefully
• Server gives up before Unity finishes domain reload
• Proper fix: Improve reconnection logic to wait for domain reload to complete

---

Reconnection Logic Analysis

Current State: Two Different Systems

1. WebSocket/PluginHub (Python side) - plugin_hub.py:412

• _resolve_session_id() waits only 2 seconds for Unity to reconnect
• Env var: UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S (default 2.0, max 30)
• Unity initiates connection; server passively waits

2. WebSocket (C# side) - WebSocketTransportClient.cs:27

• ReconnectSchedule: 0s, 1s, 3s, 5s, 10s, 30s (6 attempts, ~49s total)
• Unity actively reconnects to server after connection loss

3. Legacy Stdio (Python → Unity) - unity_connection.py:236

• 5+ retry attempts with exponential backoff
• Backoff caps: 0.8s (reloading), 0.25s (fast errors), 3s (other)
• Uses port discovery which returns 0 instances during domain reload
• Checks status file for "reloading" state

Problems Identified

Issue	Location	Impact
Wait too short	plugin_hub.py:426	2s default, domain reload takes 10-30s
Port discovery fails	stdio_port_registry.py	Returns 0 instances during domain reload
Status file not reliable	unity_connection.py:253	May not be written during domain reload
No retry after discovery fails	unity_connection.py:371	Gives up when 0 instances found

Recommendations

Option A: Increase timeouts (quick fix)

• Change UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S default from 2s to 30s
• Increase stdio retry time when instances = 0

Option B: Unify reconnection logic (better long-term)

• Create shared ReconnectionStrategy class
• Domain-reload-aware waiting (detect via status file + heuristics)
• Configurable per-operation timeouts (tests need longer than commands)

Option C: Preserve connection across domain reload

• Have Unity write "reloading" to status file BEFORE domain reload
• Keep last-known port in registry even when instances = 0
• Resume connection after reload without rediscovery

---

Fix Implemented (Option 1)

Changes made:

1. plugin_hub.py:425 - Increased default wait from 2s to 30s

   • UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S default: 2.0 → 30.0
   • Handles domain reload for WebSocket transport

2. unity_connection.py:421 - Increased backoff cap when reloading

   • Backoff cap when status.get('reloading'): 0.8s → 5.0s
   • Allows longer waits between retries during domain reload

3. unity_connection.py:771 - Increased reload wait from 2s to 30s

   • UNITY_MCP_RELOAD_MAX_WAIT_S default: 2.0 → 30.0
   • Handles domain reload for Stdio transport

Debug logging still in place (remove after verification):

• plugin_hub.py - disconnect logging
• unity_connection.py - (none added here)
• WebSocketTransportClient.cs - HandleSocketClosureAsync stack trace
• WebSocketTransportClient.cs - SendJsonAsync payload size
• GetTestJob.cs - job status logging

To test: Restart MCP server, run full test suite, verify dispatcher stays reachable after tests complete.

Follow-up TODO: Unify reconnection logic across WebSocket and Stdio transports (Option 2)

---

Fix Reverted - Back to Data-Driven Investigation

Premature fix was reverted. The diagnosis was based on code inspection without evidence. We need to actually observe what's happening before fixing.

Logging Added for Investigation

C# Side:

1. WebSocketTransportClient.cs - HandleSocketClosureAsync() (line 638):

   • Stack trace capture to identify what triggers disconnection

2. WebSocketTransportClient.cs - SendJsonAsync() (line 611):

   • Logs payload size for all command_result messages
   • Logs any message > 10KB

3. GetTestJob.cs - HandleCommand():

   • Logs job status, completion count, and failure count

Python Side:

1. plugin_hub.py - on_disconnect() (line 107):

   • Close code meaning lookup (1000=Normal, 1006=Abnormal, etc.)
   • Logs pending commands being cancelled
   • Logs registry unregistration

2. plugin_hub.py - _handle_command_result() (line 362):

   • Logs result payload size
   • Warns if payload > 10KB

What to Watch For During Test

In Unity Console:

• [Issue #654 DEBUG] GetTestJob: - Shows test progress and failure counts
• [Issue #654 DEBUG] SendJsonAsync: - Shows payload sizes being sent
• HandleSocketClosureAsync called - Shows stack trace when disconnect happens

In Python Logs:

• [Issue #654 DEBUG] Received command_result: - Shows what's being received
• [Issue #654 DEBUG] Large result payload: - Flags if payload is >10KB
• [Issue #654 DEBUG] on_disconnect called - Shows close code and meaning
• [Issue #654 DEBUG] Cancelling X pending commands - Shows in-flight work
• [Issue #654 DEBUG] Unregistering session - Confirms instance removal

How to Reproduce

1. Restart the MCP server (Python changes need reload)
2. Open Unity with MCPForUnity
3. Connect to the MCP server
4. Run full test suite: run_tests then get_test_job with wait_timeout=300
5. Watch both Unity console and Python logs
6. When "No instances found" error occurs, check logs for timeline

---

Findings: Code Path Analysis

Test Failure Flow (C# → Python):

1. TestJobManager.FinalizeCurrentJobFromRunFinished() (line 357) - marks job as Failed
2. Calls PersistToSessionState(force: true) (line 377) - saves to EditorPrefs (local only)
3. Python get_test_job() (run_tests.py:218) - polls Unity with "get_test_job" command
4. Dispatcher receives response with test failure data

Key Discovery - Instance Unregistration Mechanism:

• File: Server/src/transport/plugin_hub.py (lines 107-136)
• When WebSocket disconnects, on_disconnect() is called
• This triggers _registry.unregister(session_id) (line 134)
• This would produce the symptom: "No Unity Editor instances found"

Critical Finding - Deserialization Vulnerability:

• Location: Server/src/transport/plugin_hub.py (lines 93-105)
• Response handling wraps everything in try-catch that silently logs errors:

  try:
      if message_type == "command_result":
          await self._handle_command_result(CommandResultMessage(**data))
  except Exception as e:
      logger.error(f"Error handling message type {message_type}: {e}")

• If CommandResultMessage(**data) fails, the exception is logged but the future is never resolved
• Then: get_test_job() calls GetTestJobResponse(**response) at line 268
• If response dict has invalid test failure data → Pydantic ValidationError → Could propagate up and crash handler

Hypothesis: Large/complex test failure payloads with deeply nested data cause deserialization to fail, which either:

1. Crashes the message handler (causing WebSocket to disconnect)
2. Corrupts the pending command state
3. Causes the future to never resolve

Test Result Serialization (C#):

• When test job status = Failed, job.Result is set to TestRunResult (line 373)
• But in ToSerializable(), result is only serialized if status == "succeeded" (line 527)
• Failed test details are in progress.failures_so_far which are simple objects with string fields
• This suggests the payload size shouldn't be the issue

Next Actions (Priority Order):

1. Add logging to identify when WebSocket disconnects

   • Add debug logging to plugin_hub.py line 87-105 (on_receive) and line 107-136 (on_disconnect)
   • Log when test failure responses are processed
   • Capture the exact moment the connection closes relative to test completion

2. Reproduce with minimal full test suite

   • Run just the PropertyConversion tests + a few others to see if we can trigger the crash
   • Monitor dispatcher logs during the run
   • Check if it's specific to PropertyConversion or any test failures

3. Check for implicit disconnection

   • Search for any code that might close WebSocket based on response size or content
   • Look for memory limits or buffer overflows
   • Check if exception in response handler could propagate despite try-catch

---

Hypothesis Tracker

Hypothesis	Status	Evidence
PropertyConversion exceptions crash dispatcher	❌ REJECTED	Individual tests with same exceptions don't crash
Test teardown side effects	❌ REJECTED	Combined test file runs fine alone
Domain reload issues	⚠️ UNCERTAIN	May be a factor but not primary cause
Instance registry corruption during failure reporting	⏳ INVESTIGATING	Would explain "No instances found"
Connection loss during test failure	⏳ INVESTIGATING	Would explain subsequent command failures
Test failure payload size/serialization issue	⏳ INVESTIGATING	Could corrupt message pump

---

Summary for Next Investigator

Start here: The dispatcher becomes unreachable specifically when test suites report failures related to unhandled error logs.

The key is to trace: What happens to the instance registry, WebSocket connection, or dispatcher command queue when test failures are reported?

Don't fix: The tests themselves (don't suppress the error logs). Instead, fix why test failure reporting breaks the dispatcher.

Remember: Telemetry false positive is a symptom, not the root cause. The real bug is that test failure reporting somehow corrupts dispatcher state.

---

Investigation Started: 2026-01-30
Last Updated: 2026-01-30
Status: ✅ ROOT CAUSE FOUND AND FIXED (with additional hardening)

---

✅ FINAL FIX (2026-01-30)

Two Issues Found and Fixed

Issue 1: Dispatcher Dies After Test Suite (Original Issue #654)

Root Cause: Unity domain reload after tests complete drops the MCP connection. The reconnection timeout (2s) was too short for domain reloads (10-30s).

Fix: Increased timeouts to handle domain reloads:

File	Change	Purpose
unity_connection.py:421	Backoff cap: 0.8s → 5.0s	Longer waits between retries when reloading
unity_connection.py:771	UNITY_MCP_RELOAD_MAX_WAIT_S: 2.0s → 30.0s	Wait longer for domain reload
plugin_hub.py:427	UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S: 2.0s → 30.0s	Wait longer for session to appear

Issue 2: All Commands Slow (Regression from Issue 1 Fix)

Root Cause: The middleware (unity_instance_middleware.py) called PluginHub._resolve_session_id() on EVERY command regardless of transport mode. For stdio transport, PluginHub would wait the full timeout (now 30s) for a WebSocket session that would never exist, then fall back to stdio.

Evidence from logs:

12:21:06 - Auto-selected sole Unity instance via stdio discovery
12:21:08 - WARNING - No Unity plugin reconnected within 2.00s  ← 2s wait on EVERY command!
12:21:08 - Tool 'read_console' called  ← then stdio works

Fix: Skip PluginHub for stdio transport:

File	Change	Purpose
unity_instance_middleware.py:191	Added _is_http_transport() check	Only call PluginHub for HTTP transport

Validation Status

• Commands are fast for stdio transport
• Full test suite passes and dispatcher survives
• HTTP transport still works

---

Files Changed

1. Server/src/transport/legacy/unity_connection.py

   • Line 421: Backoff cap 0.8s → 5.0s when reloading
   • Line 771: UNITY_MCP_RELOAD_MAX_WAIT_S default 2.0s → 30.0s

2. Server/src/transport/plugin_hub.py

   • Line 427: UNITY_MCP_SESSION_RESOLVE_MAX_WAIT_S default 2.0s → 30.0s
   • Debug logging added (to be removed after validation)

3. Server/src/transport/unity_instance_middleware.py

   • Line 191: Added _is_http_transport() check before calling PluginHub

4. Server/src/transport/unity_transport.py

   • Added timing logging (to be removed after validation)

5. MCPForUnity/Editor/Services/Transport/TransportCommandDispatcher.cs

   • Added timing logging (to be removed after validation)

6. MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs

   • Added timing logging (to be removed after validation)
   • Added session_id to pong messages for server-side tracking

---

Additional Hardening: Server-Side Ping Loop (2026-01-30)

Problem Discovered

During testing, we observed that WebSocket connections could die silently on Windows (OSError 64: "The specified network name is no longer available"). When this happens:

1. The server doesn't know the connection is dead
2. Commands fail with "Unity session not available"
3. The problem persists until Unity detects the dead connection and reconnects

Root Cause

The existing keep-alive mechanism was one-directional:

• Unity sends pong messages every 15s to Python
• Python touches the registry but never actively checks for missing pongs
• If the socket dies silently, Python never discovers it because it never tries to send anything

Solution: Server-Initiated Ping Loop

Added active connection health monitoring from the Python server side:

New Constants in plugin_hub.py:

• PING_INTERVAL = 10 - Send ping every 10 seconds
• PING_TIMEOUT = 20 - Consider connection dead if no pong within 20 seconds

New Mechanism:

1. When a Unity client registers, Python starts a ping loop for that session
2. Every 10 seconds, Python sends a {"type": "ping"} message to Unity
3. Unity responds with {"type": "pong", "session_id": "..."} (was missing session_id before)
4. Python tracks the last pong time per session
5. If no pong received within 20 seconds, Python closes the connection proactively
6. This triggers proper cleanup: pending commands fail-fast, session unregisters

Files Changed:

1. Server/src/transport/models.py - Added PingMessage class
2. Server/src/transport/plugin_hub.py:
   • Added PING_INTERVAL, PING_TIMEOUT constants
   • Added _last_pong, _ping_tasks class variables
   • Added _ping_loop() coroutine
   • Updated _handle_register() to start ping loop
   • Updated _handle_pong() to record last pong time
   • Updated on_disconnect() to stop ping task and cleanup
3. MCPForUnity/Editor/Services/Transport/Transports/WebSocketTransportClient.cs:
   • Updated SendPongAsync() to include session_id in pong messages

Benefits

• Detects dead connections within 20 seconds instead of waiting for next command
• Works on Windows where socket errors may not be reported immediately
• Allows faster recovery: Unity reconnect triggers sooner
• Prevents stale connections from accumulating

Testing Status

• Verify ping/pong works normally when connection is healthy
• Verify dead connections are detected and cleaned up within 20s
• Verify Unity reconnects successfully after forced disconnect

[dsarno]

@whatevertogo can you let me know if this is fixed for you on latest main branch? Version 9.3.0?