Report live view connect failures by stage, without retrying

[robertjamesprior]

Supersedes #403 and #415 — that stack collapsed into one change, since the retry the base PR added is gone. Calibration, reproduction and the hotpatch A/B are in the Linear doc.

Summary

The live view failed silently. onMessage is assigned straight to ws.onmessage, so a throw from createPeer or setRemoteOffer was discarded: no onDisconnected, no parent-frame message, socket still open and healthy. The client could not tell "peer construction failed" from "still connecting."

A single 15s watchdog also covered all three connect stages, so a socket that never opened burned the whole budget and reported only "connection timeout", and a stuck media path was indistinguishable from a stuck socket.

• Route the throw. onMessage wraps the handler, so a rejection reaches onDisconnected and is reported instead of dropped.

• Bound each stage. A connect walks transport (socket open) → signaling (signal/provide + offer) → media (ICE starts). Each arms its own bound and reports its own reason.

  stage	starts	bound
  transport	in connect(), before the socket opens	15s
  signaling	on ws.onopen	3s
  media	after setRemoteOffer, once a peer exists	2s

• Report one terminal event with a machine-readable reason. A bound expiring posts KERNEL_CONNECTION_TIMEOUT; a connect that fails outright posts KERNEL_CONNECTION_FAILED. Both carry reason and the ICE, signaling and socket state at the moment it happened.

  reason	meaning
  transport	the socket never opened, or closed before signaling
  signaling	socket open, no offer inside the bound
  media	peer exists, ICE never reached checking
  peer	peer construction or setRemoteOffer threw
  unsupported	RTCPeerConnection is missing from the browser
  server	the server closed the connect

• No retries. A second attempt against the same peer costs the viewer time the embedder can spend on a new session, and it delays the reason. The client reports the first failure; the embedder decides.

reason replaces the previous prose ("connection timeout", raw error messages) on both events, and attempts is gone with the retry — both are payload changes.

Consequence for embedders

A failed connect now ends within one stage bound instead of a silent 15s wait, with the reason on the parent frame. The neko overlay does not render a terminal state when a connect never succeeded, so an embedder that shows nothing still shows nothing; the parent message is the signal, and it is what lets an embedder choose between remounting and starting a new session.

One result that changes other work: in an injected media-stall (offer stripped, ICE never leaves new), KERNEL_PLAYING still fired while the peer had never connected — the <video> element emits playing without frames flowing. It did not fire in the reproduction (a RTCPeerConnection construction throw). A parent-side gate on playback needs that caveat.

Testing

35 pass, 0 fail in images/chromium-headful/client (bun test tests), including 13 new cases in tests/connect-bound.test.ts covering stage entry, each stage's terminal event, the single-report guarantee, the payload state, and the post-connect disconnect path. tsc --noEmit clean.

The hotpatch A/B numbers in the doc were taken against the stacked build that still retried. Removing the retry changes only the timeout rows, which now post a single event rather than TIMEOUT followed by FAILED. They were not re-run on this revision.

What this does not establish

The affected sessions are a ws close at ~14.9s, which proves the connect watchdog fired and therefore that ICE never reached checking. It does not say why: no peer constructed, a peer that never left new, and signaling that never completed all produce that shape, and no browser-side capture exists from those sessions. The reproduction proves a construction throw produces the shape, not that it is what happened in the field.

The change does not depend on resolving that. reason is what separates the three at the next occurrence, which is the point of the field.

Dependency

The dashboard's live view panel recognises only KERNEL_CONNECTION_TIMEOUT:

if (event.data?.type !== 'KERNEL_CONNECTION_TIMEOUT') return;

so the failures that now report as KERNEL_CONNECTION_FAILED stop showing its failure panel, its Try again button and its GPU failure inspection. kernel/kernel#4421 accepts both and must land first — accepting both is compatible with either image, so the dashboard goes first and nothing has to be released in lockstep.

Not in this PR

Terminal UI with one-click resume, one shared recovery heuristic with the dashboard viewer, a frames-based gate, and awaiting addIceCandidate.

---

Note

Medium Risk
Changes WebRTC connect lifecycle and parent postMessage contract (KERNEL_CONNECTION_FAILED, structured reason); embedders that only handle KERNEL_CONNECTION_TIMEOUT need coordinated updates.

Overview
Replaces the live view client’s single 15s connect watchdog with per-stage timeouts and structured parent-frame failure reporting, so embedders can tell where a connect died instead of waiting on a generic timeout.

The connect path is now transport (15s) → signaling (3s) → media (2s) via armStage, with ICE reaching checking clearing the media bound. Stage expiry posts KERNEL_CONNECTION_TIMEOUT with reason set to the stage; other pre-connect failures post KERNEL_CONNECTION_FAILED with machine-readable reasons (transport, signaling, media, peer, unsupported, server) plus ICE/signaling/socket snapshot—replacing prose reasons and dropping attempts. onMessage is wrapped so throws from peer setup surface through onDisconnected instead of being swallowed. No automatic reconnect after failure (_gaveUp blocks further connect()); server kicks tag _failure = 'server'.

Adds connect-bound.test.ts (13 cases) for stage transitions, single terminal event, and payload shape.

^{Reviewed by Cursor Bugbot for commit 3397bfa. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Sayan-]

• p1: The client and dashboard use different failure events. A peer-construction error sends only KERNEL_CONNECTION_FAILED, but the dashboard listens only for KERNEL_CONNECTION_TIMEOUT. Its failure panel and “Try again” button never appear; the viewer stays on an empty connect overlay.
• p2: The field diagnosis rests on 15-second WebSocket closures, which show the watchdog firing but not why. No browser error was captured to confirm that peer construction threw in the affected sessions. The injected failure verifies the code defect, not the claimed field trigger.

[robertjamesprior]

p1 - accepted - this is a regression, takes priority. checked against browser-session-client.tsx, fixed in kernel/kernel#4421, which accepts both events and is compatible with either image (goes first)

p2 - accepted - no capture from those sessions, softened the claim in the issue and the PR body, and added a "what this does not establish" section listing the three causes the signature can't separate. the fix doesn't depend on resolving it

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 3397bfa. Configure here.}

[cursor]

Media timeout rearmed after ICE checking

High Severity

signal/offer and signal/provide always call armStage('media'), with no check for _everConnected, _gaveUp, or ICE already in checking. That bound is cleared only when ICE enters checking, so a later offer starts a new two-second timer that cannot be cancelled, then posts KERNEL_CONNECTION_TIMEOUT and tears down a live or almost-live peer.

Additional Locations (2)

• images/chromium-headful/client/src/neko/base.ts#L410-L411
• images/chromium-headful/client/src/neko/base.ts#L497-L505

 

^{Reviewed by Cursor Bugbot for commit 3397bfa. Configure here.}

[cursor]

Disconnect leaves onopen handler attached

Medium Severity

connect() now assigns onopen to arm the signaling bound, but disconnect() still only clears onmessage, onerror, and onclose. After a transport timeout, a socket that opens as close() runs can still invoke onopen, re-arm the signaling bound, and post a second KERNEL_CONNECTION_TIMEOUT.

Additional Locations (1)

• images/chromium-headful/client/src/neko/base.ts#L136-L140

 

^{Reviewed by Cursor Bugbot for commit 3397bfa. Configure here.}