Skip to content

fix(remote-terminal): reattach a healthy remote pane promptly after a worktree switch - #29210

Merged
nwparker merged 2 commits into
mainfrom
OrcaWin/remote-terminal-reconnect-27178
Oct 15, 2026
Merged

nwparker merged 2 commits into
mainfrom
OrcaWin/remote-terminal-reconnect-27178

Conversation

@OrcaWin

@OrcaWin OrcaWin commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator
Files Added Deleted Net
Test 4 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​271 $\color{#cf222e}{\Huge{\mathbf{−}}}$​89 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​182
Prod 2 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​131 $\color{#cf222e}{\Huge{\mathbf{−}}}$​89 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​42

ELI5

A terminal on a remote machine sometimes sat on "Reconnecting to remote runtime" for minutes after you switched to another workspace and back, even though the connection was fine. Clicking Reconnect fixed it instantly. The terminal now reconnects by itself within about a second.

What Changed

Before: after switching back to a remote workspace, the terminal showed the reconnect banner for about 15 seconds. If you switched a few times in a minute, it sat there for about 3 minutes, then said "Automatic retries stopped" until you clicked Reconnect.
After: the terminal reattaches within about a second. Repeated drops slow the retries down instead of stopping them. A connection that is really gone still shows Reconnecting, and after the same ~3 minute window it still offers the Reconnect button.

Older remote hosts (1.4.224 and earlier) end a terminal's output stream when a hidden workspace becomes visible again. The host keeps that terminal running and keeps reporting it as ready. The client handled that end in three slow ways (all in remote-runtime-pty-transport.ts):

  1. It waited the whole 15 s window for a "replacement" terminal, even though the host kept answering that the same one was ready. It now reuses that terminal as soon as the host reports it ready. The exception: if a keystroke sent to it is still unanswered, it keeps waiting, because that send could still come back "stale".
  2. A third drop within 60 s demanded a replacement terminal that never comes. The retry was then parked with no timer, so the banner spun until the ~3 min deadline. Repeated drops now reuse the same terminal after growing delays (1 s, 2 s, 4 s … 30 s). Only a drop within 10 s of reattaching counts as a repeat. Every reattach resets the recovery deadline, so once that ladder is used up (about a minute of nonstop drops) the pane goes back to waiting for a replacement terminal, and the deadline then offers Reconnect. A terminal that drops forever still surfaces Reconnect and does not retry forever. A terminal the host has actually reported stale still waits for a replacement, as before.
  3. "Unknown" answers parked the retry. If the host answered without a ready terminal, or the terminal inventory request failed, the retry waited for a network-online or wake-from-sleep event that never fires on a healthy link. These now retry on the normal backoff ladder until the existing deadline. A retry that is still running when the deadline hits stays revivable by online, resume, or Reconnect.

RemoteRuntimePtyRecoveryState.schedule takes an optional delay so the repeated-drop pacing reuses the existing recovery timer and deadline.

Why

  • These are client-side fixes, so they also work against released hosts that still end streams this way. Clients and hosts update independently. Nothing on the wire changes.
  • The repeated-drop guard from fix(terminal): add replacement policies for repeated same-handle stream #12003 stays. It still rate-limits a terminal that drops right after every reattach, but it no longer gives up on a terminal the host says is alive. Liveness stays honest: an end proves only that we lost the attachment, and the host's "ready" answer is the live evidence.
  • I considered treating "workspace became visible" as a retry trigger. I rejected it because it would only cover the remount path. Scheduling the retries fixes every caller that parked.
  • fix(remote-terminal): stop the reconnect banner after a worktree switch on remote runtimes #27698 (community PR) targets the same issue. This PR takes a smaller route to the same three fixes: no new replacement-policy tier and no extra fence loop on the persisted-pane path.

Linked Issue

Fixes #27178

Also addresses the ~20 s "Reconnect to remote runtime" banner on tab switch in #19647 (same host stream-end + 15 s replacement wait). Not closing it: its second symptom, a frozen pane with no banner while output keeps flowing on the host until a client restart, is a different mechanism this PR does not touch.

Visual Proof

N/A. The visible behavior is how long the reconnect banner stays up. Fake-timer tests pin that timing. I did not run an end-to-end check against a 1.4.224 host (see Testing).

Testing

  • New remote-runtime-pty-transport-healthy-link-reattach.test.ts, red on main (5/6 failing) and green with this change:

    • reattaches within 2 s of a stream end when the host reports the handle ready
    • 5 back-to-back ends keep reattaching and never park
    • a resubscribe whose host answered without a ready handle retries and attaches once ready
    • an attach whose host surface stayed pending past 15 s retries and attaches
    • a resubscribe past repeated inventory failures recovers when the host answers again
    • a host that never produces a handle still latches disconnected with Reconnect available
  • I updated the tests that pinned the old parking behavior. Two-window inventory cap → keeps polling on the ladder until the deadline, then goes quiet. Third flap requires replacement → paced reuse. Pending attach phase recovering → backoff. The prior-ready-evidence test is now fenced by an unanswered send, so it still covers the end-of-window fallback.

  • All terminal-pane/remote-runtime-* suites, plus pty-connection-remote-runtime-attach and terminal-remote-runtime-recovery-ui-state, pass locally (macOS). pnpm tc:web and check:code-quality:changed are clean.

  • Not tested end to end against a real 1.4.224 host.

  • I manually tested these changes locally

  • Automated tests added/updated, or explained why not below

Agent skill upstream boundary

  • Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

  • SSH/remote: renderer-only change to the paired remote terminal transport. No RPC or stream frame changes, so it is safe with mixed client and host versions.
  • Performance: a pane whose liveness is unknown now keeps polling inside the existing ~3 min deadline instead of idling. That is bounded by the backoff ladder, and it stops at the deadline.

Checklist

  • This PR is small and focused
  • I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
  • Before/after screenshots or videos attached for UI changes, or N/A with reason
  • Self-reviewed for correctness, security, and performance
  • Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
  • pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

m4air and others added 2 commits October 15, 2026 12:44
… worktree switch (#27178)

A remote pane whose stream ended while the host still reported its terminal
ready waited the whole 15s inventory window before reusing it, and a third end
within 60s demanded a replacement handle that never comes, parking recovery
with no timer until the ~3 min deadline. Unknown-liveness outcomes on the
attach and resubscribe paths also parked for online/resume events that a
healthy link never fires.

- Reuse a still-ready handle as soon as the host reports it, unless a
  terminal.send to it is unanswered (it may still come back stale).
- Pace repeated ends on the same handle with growing delays instead of
  requiring a replacement; only ends within 10s of a reattach count.
- Schedule unknown-liveness retries on the backoff ladder instead of parking;
  the existing deadline still latches Reconnect for a genuinely lost link.

Co-Authored-By: Claude <noreply@anthropic.com>
…ng ladder is spent

Each paced reattach marked the pane healthy and reset the recovery deadline,
so a handle that ended after every reattach retried forever without ever
offering Reconnect. After the last rung it now falls back to the replacement
wait, whose deadline latches Reconnect.

Co-Authored-By: Claude <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 92878d5b-49d9-4ece-a2b7-4ff19b368b21
📥 Commits

Reviewing files that changed from the base of the PR and between 2c100ef and 1a8fa00.

📒 Files selected for processing: 6
  • src/renderer/src/components/terminal-pane/remote-runtime-pty-recovery-state.ts
  • src/renderer/src/components/terminal-pane/remote-runtime-pty-transport-healthy-link-reattach.test.ts
  • src/renderer/src/components/terminal-pane/remote-runtime-pty-transport-pending-host-surface-attach.test.ts
  • src/renderer/src/components/terminal-pane/remote-runtime-pty-transport-stale-handle-recovery.test.ts
  • src/renderer/src/components/terminal-pane/remote-runtime-pty-transport-sticky-replacement-policy.test.ts
  • src/renderer/src/components/terminal-pane/remote-runtime-pty-transport.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

📝 Walkthrough

The transport now retries unknown host-handle outcomes during the recovery window instead of relying only on external triggers. Repeated same-handle stream ends use a delay ladder and can require a replacement after the ladder is exhausted. The transport tracks in-flight terminal sends by handle and uses that state when deciding whether to reuse a ready handle. Tests cover healthy-link reattachment, pending and unavailable host state, and repeated stream-end recovery.

Priority: ➖ Normal

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 1a8fa

This change makes remote terminal panes reattach sooner after a worktree switch and retry on a schedule when terminal liveness is unknown. No concrete defect was found in the supplied change. Merge-readiness risk is minimal.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 6 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Linked Issues check Passed Issue #27178 requires automatic retries when remote terminal liveness is unknown while the runtime link remains healthy. The transport now schedules retries after unknown attach and resubscribe outcom…
Out of Scope Changes check Passed The changes stay within remote terminal recovery. The optional recovery delay, same-handle flap pacing, in-flight send tracking, transport changes, and related tests support the healthy-link reattachm…
Title check Passed The title clearly and concisely describes the main change: prompt reattachment of a healthy remote terminal after a worktree switch.
Description check Passed The description follows the required template and explains the user impact, implementation, rationale, linked issue, visual-proof exception, testing, compatibility, performance, and checklist status. …
  • Fix all pre-merge checks with AI
✨ Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants