fix(remote): harden runtime liveness and shared-control recovery

[bbingz]

Summary

• make desktop and runtime WebSocket liveness pause-aware so the first timer tick after sleep starts a real probe instead of treating accumulated wall-clock silence as a failed probe
• keep shared-control logical subscriptions alive through recoverable outages with capped exponential backoff while disposing retries when the final subscriber leaves
• reset a shared-control socket after an RPC timeout only when no newer valid inbound frame proves that the connection is still active
• classify authentication and protocol failures once, with callback-safe cleanup

This is PR 1 of a three-PR stack for #8180. It establishes transport recovery foundations without changing terminal stream framing.

Refs #8180

Screenshots

No visual change.

Testing

• pnpm lint
• pnpm typecheck
• focused remote-runtime Vitest suite: 28 files / 820 tests
• pnpm check:max-lines-ratchet
• pnpm build:desktop
• git diff --check origin/main...HEAD
• Added or updated regression tests for pause-aware probing, long-outage retry, stale reconnect timers, timeout activity generations, and fatal close classification
• full repository Vitest suite
• Electron E2E or physical macOS-to-Windows sleep/network interruption test

The commands above are a historical validation record from the origin/main@ff8192a331 rebase; the branch has since been rebased again. The verification host used Node 26.5.0 while the repository declares Node 24; pnpm emitted the engine warning, and all commands above still passed.

AI Review Report

Independent reviews checked the approved #8180 design, retry/cancellation races, callback reentrancy, mixed-version behavior, and compatibility with the renderer/terminal changes in v1.4.136-rc.0. Findings led to fixes for orphan reconnect timers, jitter exceeding the 30-second cap, close-only authentication failures, and throwing/reentrant fatal callbacks. Final verdict: spec PASS and code APPROVED.

Cross-platform review covered macOS sleep/resume, Linux and Windows timer/network behavior, SSH remote runtimes, and Electron boundaries. This layer adds no shortcuts, filesystem assumptions, dependencies, or wire fields.

Security Audit

Reviewed authentication close handling, E2EE close-code normalization, subscription cleanup, request-timeout behavior, callback isolation, and logging. Fatal authentication/protocol errors stop retrying; recoverable network errors do not expose pairing data or credentials.

Notes

Stack order:

1. this PR: transport foundations
2. fix(remote): preserve structured terminal stream failures #8254: structured terminal stream close semantics
3. fix(remote): accelerate terminal recovery on resume/online #8255: negotiated replay and atomic terminal recovery

Merge in this order and roll back in reverse order.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 94601076-d628-4ad9-9c04-6fd336a98f40

📥 Commits

Reviewing files that changed from the base of the PR and between 6b94822 and eb6c9c3.

📒 Files selected for processing (1)

• docs/reference/2026-07-11-remote-runtime-terminal-recovery-design.md

---

📝 Walkthrough

Walkthrough

Adds pause-aware client and server WebSocket liveness with delayed-tick re-baselining and probe-based termination. Refactors shared-control reconnect handling with error classification, jittered backoff, subscription cleanup, stale-timer fencing, fatal-error finalization, and inbound activity tracking. Expands tests for liveness, reconnect behavior, timeout handling, callback isolation, and abnormal socket closure. Adds a design document describing the planned remote terminal recovery architecture, verification procedure, and rollout strategy.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	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 is concise and accurately summarizes the main change: hardening runtime liveness and shared-control recovery.
Description check	✅ Passed	The description follows the template and covers summary, screenshots, testing, AI review, security, and notes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c39a5242-56ea-43bb-93c5-231ea8f5e831

📥 Commits

Reviewing files that changed from the base of the PR and between 2d7080a and 5425aab.

📒 Files selected for processing (18)

• docs/reference/2026-07-11-remote-runtime-terminal-recovery-design.md
• src/main/runtime/rpc/ws-transport.test.ts
• src/main/runtime/rpc/ws-transport.ts
• src/shared/remote-runtime-client-error-classification.test.ts
• src/shared/remote-runtime-client-error-classification.ts
• src/shared/remote-runtime-shared-control-connection.test.ts
• src/shared/remote-runtime-shared-control-connection.ts
• src/shared/remote-runtime-shared-control-frame-handler.ts
• src/shared/remote-runtime-shared-control-keepalive-refresh.test.ts
• src/shared/remote-runtime-shared-control-open.ts
• src/shared/remote-runtime-shared-control-reconnect-delay.test.ts
• src/shared/remote-runtime-shared-control-reconnect.ts
• src/shared/remote-runtime-shared-control-requests.ts
• src/shared/remote-runtime-shared-control-state.ts
• src/shared/remote-runtime-shared-control-subscription-start.ts
• src/shared/remote-runtime-shared-control-types.ts
• src/shared/remote-runtime-socket-liveness.test.ts
• src/shared/remote-runtime-socket-liveness.ts

✅ Files skipped from review due to trivial changes (1)

• src/shared/remote-runtime-client-error-classification.ts

🚧 Files skipped from review as they are similar to previous changes (15)

• src/shared/remote-runtime-shared-control-frame-handler.ts
• src/shared/remote-runtime-client-error-classification.test.ts
• src/shared/remote-runtime-shared-control-types.ts
• src/shared/remote-runtime-shared-control-reconnect-delay.test.ts
• src/shared/remote-runtime-socket-liveness.test.ts
• src/main/runtime/rpc/ws-transport.test.ts
• src/shared/remote-runtime-shared-control-open.ts
• src/shared/remote-runtime-shared-control-state.ts
• src/main/runtime/rpc/ws-transport.ts
• src/shared/remote-runtime-socket-liveness.ts
• src/shared/remote-runtime-shared-control-keepalive-refresh.test.ts
• src/shared/remote-runtime-shared-control-subscription-start.ts
• src/shared/remote-runtime-shared-control-connection.ts
• src/shared/remote-runtime-shared-control-reconnect.ts
• src/shared/remote-runtime-shared-control-connection.test.ts

[bbingz]

@Jinwoo-H When you have capacity, could you review this entry layer first? #8254 and #8255 form the dependent stack for #8180. The rebased heads are mergeable, focused verification and desktop build passed, and all current CodeRabbit threads have been adjudicated.

[bbingz]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[bbingz]

Rebased onto latest main as a clean 6-commit stack (dropped obsolete merge commits).

Note: skipped 1b9079d107 (scope control timeout resets to silent sockets) because current main already owns connection teardown via socket liveness and deliberately keeps unrelated pending RPCs alive on a single-method timeout. Re-introducing generation-scoped onTimeout → handleSocketClosed would regress that.

[bbingz]

Stack status vs merged #9774

Audited this foundations PR against current main after #9774 (fix(remote-runtime): recover terminals after network loss).

Finding: pause-aware liveness, server heartbeat, shared-control reconnect durability, socket-generation fencing, and “RPC timeout does not thrash the control socket” are already on main via #9774 (parallel architecture, not a line-port of this branch).

Remaining deltas look like polish only (fatal-auth stop-retry, hard-cap jitter under 30s). We are routing a close-as-superseded decision through independent review; will close or open micro follow-ups after that confirms.

Full audit notes: internal /tmp/825x-audit.md (session).

[bbingz]

Closing as superseded by merged #9774 (54c1ec5e — recover terminals after network loss).

Independent review (high confidence) confirmed on current main:

• pause-aware client liveness (remote-runtime-socket-liveness.ts)
• pause-aware server heartbeat (remote-runtime-server-heartbeat.ts)
• shared-control reconnect + socket-generation fencing
• RPC timeout only rejects the request; liveness owns connection teardown

Residual polish (fatal-auth stop-retry, jitter hard-cap ≤30s) can be tiny follow-ups if still desired — not this stack. #8254 / #8255 stay open for narrowed complementary gaps only.