fix: automatically recover Unity servers after stale-port conflicts

[hatayama]

Summary

• Unity automatically retries server recovery after a stale-port conflict while the editor remains open.
• A fallback port is written back to the project settings so the CLI can reconnect to the intended project.

User Impact

• Automatic recovery failures no longer erase the user's intent to keep the server running.
• Intentional stops remain respected and are not undone by the watchdog.

Changes

• Confirmed that background-process and startup-protection early returns, exhausted recovery retries, and unexpected-loop recovery faults previously had no later retry trigger.
• Preserved isServerRunning=true with an empty session ID for automatic recovery failures, while keeping ClearServerSession() for intentional stops.
• Added a throttled editor watchdog with pure decision logic for recovery, settings synchronization, intentional stop, startup protection, and background-process handling.

Verification

• dotnet test tests/ServerStateWatchdog.UnitTests/ServerStateWatchdog.UnitTests.csproj --no-restore — 6 passed.
• node dist/cli.bundle.cjs compile --project-path "$(git rev-parse --show-toplevel)" — Success, 0 errors, 0 warnings.
• Known behavior: if every recovery bind attempt fails, the existing recovery path logs the failure and throws; the watchdog retries after its 30-second backoff.

[coderabbitai]

Warning

Review limit reached

@hatayama, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 51 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6b963138-a0fd-4dc5-a8b2-b6f97a193237

📥 Commits

Reviewing files that changed from the base of the PR and between d345da8 and a3ce2a8.

📒 Files selected for processing (1)

• tests/ServerStateWatchdog.UnitTests/ServerStateWatchdogServiceTests.cs

📝 Walkthrough

Walkthrough

The change adds a Unity editor watchdog that reconciles persisted server intent with actual state, retries failed automatic recovery, synchronizes port settings, and preserves recovery-pending state across recovery failure paths.

Changes

Server recovery watchdog

Layer / File(s)	Summary
Recovery state and watchdog decisions Packages/src/Editor/Config/McpEditorSettings.cs, Packages/src/Editor/Core/ApplicationServices/ServerStateWatchdogService.cs, Packages/src/Editor/Shared/Config/McpConstants.cs, tests/ServerStateWatchdog.UnitTests/*	Adds recovery-pending settings, watchdog observations and actions, retry and suppression rules, the three-second polling interval, and decision-logic tests.
Editor watchdog orchestration Packages/src/Editor/Core/ApplicationServices/ServerStateWatchdog.cs, Packages/src/Editor/Server/McpServerController.cs	Registers periodic editor updates, evaluates server state, starts recovery when needed, logs recovery failures, and synchronizes persisted settings with the running server port.
Recovery failure state integration Packages/src/Editor/Core/ApplicationServices/SessionRecoveryService.cs, Packages/src/Editor/Server/McpServerController.cs	Changes exhausted, faulted, and failed-bind recovery paths to mark recovery pending instead of clearing the server session.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant UnityEditor
  participant ServerStateWatchdog
  participant ServerStateWatchdogService
  participant McpServerController
  participant McpEditorSettings
  UnityEditor->>ServerStateWatchdog: EditorApplication.update
  ServerStateWatchdog->>ServerStateWatchdogService: DecideAction(observation)
  ServerStateWatchdogService-->>ServerStateWatchdog: RecoverServer or RewriteSettings
  ServerStateWatchdog->>McpServerController: StartRecoveryIfNeededAsync()
  McpServerController->>McpEditorSettings: MarkServerRecoveryPending() on failure
  ServerStateWatchdog->>McpServerController: SynchronizeRunningServerSettings()

Loading

Possibly related PRs

• hatayama/unity-cli-loop#871: Changes MCP server recovery behavior after silent server-loop exits.
• hatayama/unity-cli-loop#1552: Updates recovery exhaustion and server session state handling.
• hatayama/unity-cli-loop#1655: Refactors recovery bind-retry behavior and session-state updates.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: automatic Unity server recovery and stale-port conflict handling.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/v2-server-state-watchdog

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}