fix(stdio): refresh port discovery before reconnect backoff

[SeojunKim-pumisj]

Description

Refresh stdio port discovery immediately after a Unity communication failure. This lets reconnect attempts follow a new port announced in the status registry after a domain reload instead of reusing the cached port until its TTL expires.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Test update

Changes Made

• Force-refresh the stdio instance registry before resolving the reconnect port.
• Add a regression test that primes a stale cached port, changes discovery to a new port, and verifies the new port is selected before retry backoff and used by the next connection attempt.

Compatibility / Package Source

• Unity version(s) tested: Not applicable (Python server-only change)
• Package source used (#beta, #main, tag, branch, or file:): beta
• Resolved commit hash from Packages/packages-lock.json (if using a Git package URL): Not applicable

Testing/Screenshots/Recordings

• Python tests (cd Server && uv run pytest tests/ -v): 1375 passed, 3 skipped
• Unity EditMode tests
• Unity PlayMode tests
• Package import/compile check
• Not applicable (explain why in Additional Notes)

Documentation Updates

• I have added/removed/modified tools or resources
• If yes, I have updated all documentation files using:
  • The LLM prompt at tools/UPDATE_DOCS_PROMPT.md (recommended)
  • Manual review of the generated changes

Related Issues

Fixes #1339

Additional Notes

Unity tests were not run because this change only affects Python stdio reconnection and does not modify the Unity package. The regression test exercises the cache TTL scenario without requiring a Unity Editor.

Summary by CodeRabbit

• Bug Fixes
  • Improved connection recovery when a cached Unity port becomes outdated.
  • Failed connection attempts now refresh available port information before retrying, increasing the likelihood of reconnecting successfully.
  • Connection errors are reported correctly after all retry attempts are exhausted.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 46d91106-dea5-4c95-9f5e-cf9fe942528c

📥 Commits

Reviewing files that changed from the base of the PR and between c21bf49 and 8368342.

📒 Files selected for processing (2)

• Server/src/transport/legacy/unity_connection.py
• Server/tests/integration/test_connection_deadline.py

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The retry path now refreshes the stdio port registry before rediscovering a Unity port. An integration test verifies recovery from a stale cached port and confirms ConnectionError after retries are exhausted.

Changes

Unity port refresh

Layer / File(s)	Summary
Refresh registry before retry Server/src/transport/legacy/unity_connection.py, Server/tests/integration/test_connection_deadline.py	send_command forces a registry refresh before rediscovering the Unity port. The integration test verifies the transition from port 6400 to 6401, retry ordering, and the final ConnectionError.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 83683

This change refreshes port discovery before stdio reconnect retries and adds regression coverage for stale cached ports; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: mertakdut, scriptwonder

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: refreshing stdio port discovery before reconnect backoff.
Description check	✅ Passed	The description follows the repository template. It explains the bug, identifies the code and test changes, records testing results, and links issue #1339.
Linked Issues check	✅ Passed	The implementation satisfies issue #1339 by force-refreshing port discovery after communication failure, before reconnect backoff. The regression test covers stale cached ports and selection of the ne…
Out of Scope Changes check	✅ Passed	The changes are limited to the stdio reconnection fix and its regression test. No unrelated code or documentation changes are present.

Full details: Linked Issues check

Explanation

The implementation satisfies issue #1339 by force-refreshing port discovery after communication failure, before reconnect backoff. The regression test covers stale cached ports and selection of the newly discovered port.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}