Notify the user when connecting as the controlled computer fails

[danielw97]

Link to issue number:

Fixes #19103

Summary of the issue:

When an error occurs while connecting as the controlled computer, NVDA only logs the failure; the user receives no feedback. This is inconsistent with leader connections, where an error dialog is shown.

A previous fix (#19477) was reverted in #20131: its failure handler called disconnectAsFollower(), which stopped the transport's ConnectorThread, so a single failed attempt at startup permanently gave up the connection. This broke users who rely on follower autoconnect as their primary means of accessing a headless or otherwise physically inaccessible machine (#20122).

This PR follows the approach discussed and agreed with @SaschaCowley in #19103: notify without giving up.

Description of user facing changes:

On the first failed attempt of a follower connection that has never succeeded, NVDA now reports in speech and braille: "Unable to connect to the Remote Access server. Retrying".

Connection attempts continue in the background exactly as before (roughly every 5 seconds, indefinitely), so when the server becomes reachable the connection completes and the existing "Connected as controlled computer" cue confirms it. Subsequent failed retries are not announced, to avoid repeating the message every few seconds while the network is down.

Description of developer facing changes:

None.

Description of development approach:

• Registered the transportConnectionFailed handler for the follower transport in connectAsFollower, mirroring the leader flow.
• Added RemoteClient.onConnectAsFollowerFailed, which announces the failure once via ui.delayedMessage, consistent with how _remoteClient/cues.py reports other connection events. A transient spoken/braille message does not demand dismissal and does not imply NVDA has given up, so it works both for the interactive case and for unattended autoconnect.
• The handler deliberately does not touch the reconnector thread — the fix for NVDA Remote should keep retrying connection after startup failures instead of failing immediately #20122 is preserved by construction.
• Announcements are guarded by successfulConnects == 0 (so reconnection attempts of a previously working session are not announced, matching the leader handler) plus a _followerConnectFailures counter reset when a new follower connection is initiated. A counter was used rather than a boolean to leave a hook for possible future escalation (see below).
• The failure is logged once, at warning level rather than error level: NVDA has not given up on the connection, and an error-level log would also play the error sound on test versions of NVDA.
• The leader-side dialog is untouched.

Possible future work, suggested by @SaschaCowley in #19103: after several consecutive failures (e.g. 6 failures / 30 seconds), escalate to a non-modal dialog with an indeterminate progress bar and an option to cancel the connection. Left out of this PR to keep the change minimal; the failure counter provides a natural hook for it.

Testing strategy:

• Four new unit tests in tests/unit/test_remote/test_remoteClient.py:
  • the first failure announces exactly once, and further failures stay silent;
  • failures of a transport that has previously connected (reconnection attempts) are not announced;
  • a late notification after the transport is torn down is a no-op;
  • starting a new follower connection resets the announcement state, so a failure of the new connection is announced again.
• Manual testing on a from-source build with follower autoconnect pointed at a local relay server:
  • With the server off: exactly one spoken announcement shortly after startup, then silent retries (verified over more than a minute in the log — a single Failed to connect message, no repeats).
  • Turning the server on afterwards: NVDA connected automatically within one retry interval and played the "Connected as controlled computer" cue, confirming the NVDA Remote should keep retrying connection after startup failures instead of failing immediately #20122 autoconnect recovery scenario still works.
• The leader connection code path is not modified by this change.
• runlint (ruff + pyright) and the full test_remote unit test suite pass.

Known issues with pull request:

None known.

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

---

Note: I used AI assistance (Claude) while developing this PR. I have reviewed, tested, and understand all changes.