Skip to content

[Bug]: Cold-parking unmounts remotely-subscribed terminal panes, making remote-runtime reconnect unrecoverable #11189

Closed

Description

@Fartown

Operating system: macOS
Orca version: 1.4.159 (host), 1.4.159 (client)

Short summary

When Mac A runs an Orca runtime and Mac B connects to it as a remote runtime, terminal tabs on B disconnect repeatedly with the Reconnecting to remote runtime banner, and reconnecting never recovers — it ends at Remote runtime disconnected.

Root cause appears to be that the cold-parking policy on the host only considers local visibility. A tab that a remote client is actively watching is, from the host renderer's point of view, just a hidden tab — so it gets unmounted 30s later, killing the stream. Reconnect re-mounts it, but because hiddenSinceMs is never reset for a background-mounted tab, it is immediately eligible for parking again and gets unmounted within the next render pass. That makes the loop unrecoverable rather than merely flaky.

Steps to reproduce

  1. On host A, open an Orca window with more than TERMINAL_TAB_HOT_RETAIN_LIMIT (12) terminal tabs across several worktrees.
  2. Leave A showing one worktree/tab (the rest are hidden, which is the normal state when nobody is sitting at A).
  3. From client B, pair with A's runtime and open several of A's terminals.
  4. Use the terminals from B only. Do not touch A.

Observed: terminals on B repeatedly show Reconnecting to remote runtime; the Reconnect button does not help. Switching to A and making the tab visible immediately fixes that tab.

Why I think this is what's happening

Remote subscribe asks the host renderer to mount the tab — src/main/runtime/rpc/methods/terminal.ts:

rendererMountRequestedBeforePty = runtime.requestRendererTerminalTabMount(params.terminal)

which lands in useIpcEvents.ts as a background mount (STA-1840). But in TerminalPaneOverlayLayer.tsx, parking takes precedence over that background mount:

.filter((terminalTab) => shouldMountBackgroundWorktreeTab(backgroundMountTabIds, terminalTab.id))
.map((terminalTab) => {
    // ...
    if (parkedTerminalTabIds.has(terminalTab.id)) {
      return null
    }

And neither of the two places that decide parking knows about remote subscribers:

terminal-hidden-view-parking.ts — canParkTerminalTabRenderer exemptions:

if (!args.parkingEnabled || tab.isVisible || tab.hasActivityTerminalPortal || tab.hiddenSinceMs === null) {
  return false
}

use-terminal-tab-cold-parking.ts — the hidden-clock reset:

if (isVisible || hasActivityTerminalPortal || shouldMeasureHiddenWorktree) {
  terminalTabHiddenSinceRef.current.delete(terminalTab.id)
} else if (!terminalTabHiddenSinceRef.current.has(terminalTab.id)) {
  terminalTabHiddenSinceRef.current.set(terminalTab.id, nowMs)
}

The second one is what makes it unrecoverable. After a reconnect the tab is mounted again, but it is still isVisible: false on the host, so hiddenSinceMs keeps its old value (often hours old). nowMs - hiddenSinceMs is far past TERMINAL_TAB_COLD_PARK_DELAY_MS (30s), so the freshly mounted pane is parked again on the next render pass. The client reconnects, the pane is parked, repeat — until the recovery deadline expires and the banner switches to Remote runtime disconnected.

Relevant constants (terminal-hidden-view-parking.ts):

TERMINAL_TAB_COLD_PARK_DELAY_MS = 30_000
TERMINAL_TAB_HOT_RETAIN_MS      = 15 * 60_000
TERMINAL_TAB_HOT_RETAIN_LIMIT   = 12
TERMINAL_WORKTREE_HOT_RETAIN_LIMIT = 8

This is why the frequency scales with tab count. My host had 20 terminals across 8 worktrees, so at least 8 were permanently outside the hot-retain set. Even under the limit, the 15-minute hot-retain window means a long-lived remote terminal eventually gets parked anyway.

Evidence from the host

Host trace log (main.trace.ndjson) shows a repeating pattern that matches the loop — every session-attached is followed 1-2s later by terminal_safe_fit_retry_exhausted (18/18 occurrences), which is the expected "hidden pane is 0x0" symptom of a remount wave:

15:03:33  webgl-atlas-reset
15:03:36  session-attached  (3 sessions within 3s)
15:03:38  terminal_safe_fit_retry_exhausted

Over the afternoon livePanes oscillated between 9 and 15 while nobody was interacting with the host — sidebar_worktree_activate fired only twice on the host in that window, versus 40 times on the client.

Suggested fix

Track whether a tab has an active remote subscriber and treat it like local visibility in both places:

// canParkTerminalTabRenderer
if (!args.parkingEnabled || tab.isVisible || tab.hasActivityTerminalPortal || tab.hasRemoteSubscriber || tab.hiddenSinceMs === null)

// hidden-clock reset
if (isVisible || hasActivityTerminalPortal || hasRemoteSubscriber || shouldMeasureHiddenWorktree)

The subscriber set is already known on the main side (terminal.subscribe / terminal.multiplex connections), so it mainly needs to be surfaced to the renderer alongside backgroundMountTabIds.

Caveat

I could not capture the client-side confirmation directly — the [remote-runtime.shared-control] socket closed warnings go to the Electron process stderr and are not persisted on either machine, and the client trace log contains no remote-runtime entries. So the final link (host park → client banner) is inferred from the code path plus the host-side timing correlation above, not observed end-to-end. Notably the TCP connections to the host stayed ESTABLISHED throughout, which rules out a network-level drop and points at an application-level stream teardown.

Happy to run any instrumentation on both machines if that would help confirm.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions