[nwparker]

What

The runtime WebSocket server (orca serve / a paired runtime host) started a 15s heartbeat interval as soon as it began listening and kept it firing forever — even with zero connected clients, sweeping an empty client set every 15s (~0.067 main-process wakeups/sec wasted whenever the server listens with no phone/client attached).

Fix: arm the heartbeat on the first accepted connection (0→1) and stop it after the last one closes (1→0). A heartbeatConnections set tracks accepted sockets; each socket is seeded alive before arming so a fresh first socket survives its initial sweep. Transport shutdown stops the heartbeat and clears the set. The wss.clients sweep authority while armed is unchanged.

ELI5

The host kept doing a 15-second "everyone still there?" roll call even when nobody was connected. Now the roll call only runs while at least one device is actually connected.

Proof of zero regression

• Dead-client detection + keepalive are byte-for-byte unchanged whenever ≥1 client is connected (the sweep still runs over wss.clients).
• Seed-before-arm preserves the "first tick doesn't reap a fresh socket before its first pong" guarantee; every accepted socket is still noteAlive'd at accept.
• Idempotent finalization (each socket's close/error handler removes its own listeners) prevents double-cleanup; a stale finalizer can't stop a re-armed timer while another accepted connection remains; re-arm works when a new client connects after all closed.
• Tests: 30 pass across ws-transport.test.ts + remote-runtime-server-heartbeat.test.ts — zero-client idle (no timer), first-client arm + alive seed, no double-arm on subsequent clients, last-client stop, re-arm after reconnect, error/close race finalization, and unchanged dead-client detection with ≥1 client. typecheck:node clean.

Proof of perf improvement

Removes 0.067 main-process wakeups/sec whenever the runtime server is listening with no client attached (the common orca serve idle state) — the tests assert no interval is armed with zero connections.

Made with Orca 🐋

[coderabbitai]

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: ea33ec74-81fb-45ee-8757-387740f10ba5

📥 Commits

Reviewing files that changed from the base of the PR and between 6413052 and 282938f.

📒 Files selected for processing (4)

• src/main/runtime/rpc/remote-runtime-server-heartbeat.test.ts
• src/main/runtime/rpc/remote-runtime-server-heartbeat.ts
• src/main/runtime/rpc/ws-transport.test.ts
• src/main/runtime/rpc/ws-transport.ts

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

• src/main/runtime/rpc/remote-runtime-server-heartbeat.test.ts
• src/main/runtime/rpc/ws-transport.test.ts
• src/main/runtime/rpc/ws-transport.ts

---

📝 Walkthrough

Walkthrough

WebSocket heartbeat management now tracks active connections and starts monitoring when the first connection arrives. It seeds connection liveness, stops monitoring after the final connection closes, and clears tracking during shutdown. Heartbeat startup performs an immediate probe. Tests cover timer lifecycle, idempotent error and close cleanup, repeated probing, and termination of an unresponsive client.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the summary and testing, but it omits required Screenshots, AI Review Report, Security Audit, and Notes sections.	Add the missing template sections, including Screenshots, AI Review Report with cross-platform checks, Security Audit, and Notes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: the heartbeat now runs only while clients are connected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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