Skip to content

fix(client-runtime): retry a dropped SSH environment promptly - #27

Merged
greaber merged 2 commits into
grant/mainfrom
grant/retry-promptly
Nov 20, 2026
Merged

greaber merged 2 commits into
grant/mainfrom
grant/retry-promptly

Conversation

@greaber

@greaber greaber commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

Problem

After a few failures in a row, the supervisor's exponential backoff (up to 5 minutes) left an SSH environment waiting minutes for its next automatic attempt. Over a flaky link the network was usually back long before that, so pressing Retry now reconnected far sooner.

Change

  • SSH-backed environments (any route is an SshConnectionTarget) get their own retry ladder in supervisor.ts:
    • an attempt that failed after 3 s or more (typically a timeout over a stalled link) is followed by the next attempt at once, with no backoff state, at most 3 times in a row; a persistent slow failure (for example a remote install that keeps failing) then falls back to the fast-failure ladder;
    • a fast failure (offline, refused) waits 1, 2, 4, 8, 16, then 20 s, so an offline laptop does not loop tightly. A connection, foregrounding, a network change, or Retry now resets both counters.
    • Relay, LAN, bearer and primary environments keep the jittered 5-minute ladder: they can have many clients per host and the relay is shared, so the reasoning for SSH (one client per host, each step bounded by the desktop) does not carry over.
  • Errors that need the user never retry automatically. The renderer used to classify only messages containing "cancel" as blocked; everything else from the desktop SSH layer was transient. Unanswered password prompts ("SSH authentication timed out"), refused keys/passwords, agent signing failures (an untouched security key), and host key mismatches are now ConnectionBlockedError (authentication), which waits for Reconnect, foregrounding, or a network change. Without this, the immediate retry would have re-prompted for a password in a loop.
  • Docs: docs/internals/connection-runtime.md and the Desktop-managed SSH section of docs/user/remote-access.md.

Not included: a "link restored" signal from the desktop

The desktop has no existing push signal to the renderer saying an SSH link is healthy again: its SSH layer only runs inside an ensureSshEnvironment call that the client attempt is already waiting on, and its control master emits no "recovered" event. With this ladder, the gaps it would cover are small: a stalled link is always inside an attempt (slow failures retry at once), fast failures wait at most 20 s, and the OS going back online already ends the wait. Building one would mean a new desktop-side probe loop, so it is left out.

Checks

Command SHA Result
vp test run src/connection/supervisor.test.ts (client-runtime) e348388 65 passed; the 3 SSH cases fail without the supervisor change
vp test run src/connection/platform.test.ts (web) e348388 17 passed; the new classification case fails without the platform change
vp run check:changed greaber/grant/main (format, lint, knip, typecheck of 7 packages, tests) e348388 pass
vp test run src/connection/supervisor.test.ts (client-runtime) b9f79e1 66 passed; the slow-failure cap case fails without the cap
vp run check:changed greaber/grant/main b9f79e1 pass

🤖 Generated with Claude Code

An SSH environment that failed a few times in a row waited minutes for its
next automatic attempt, while the link was usually back long before, so
"Retry now" reconnected far sooner.

SSH-backed environments now retry at once after an attempt that failed
slowly (3 seconds or more, typically a timeout), and back off 1, 2, 4 ...
at most 20 seconds after fast failures. SSH failures only the user can fix
(a cancelled or unanswered password prompt, a refused key, an untouched
security key, a changed host key) are now classified as authentication
failures, so they wait for the user instead of prompting again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:M labels Nov 20, 2026
…ilures

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@greaber
greaber merged commit 3931f3e into grant/main Nov 20, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:M vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant