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, parent postMessage payload contract, and failure semantics for all live-view embedders; misaligned dashboard handling could hide failure UI until kernel#4421 lands.

Overview
Replaces the live-view client’s single 15s connect watchdog with per-stage timeouts (transport 15s, signaling 3s, media 2s) and reports one terminal parent-frame event per failed connect—no in-client retry after give-up.

WebSocket handler errors are no longer swallowed: onMessage wraps the async handler so peer construction / setRemoteOffer failures reach onDisconnected and embedders get KERNEL_CONNECTION_FAILED with a machine-readable reason (transport, signaling, media, peer, unsupported, server) plus ICE/signaling/socket snapshot. Stage expiry posts KERNEL_CONNECTION_TIMEOUT with the same reason shape (replacing prose "connection timeout" and dropping attempts). Pre-connect failures always notify the parent; post-connect drops use the normal disconnect path. Server kicks set _failure = 'server' in index.ts.

Adds connect-bound.test.ts covering stage transitions, single-report guarantees, ICE checking clearing the media timer, and give-up blocking further connect() calls.

Embedder note: consumers that only handle KERNEL_CONNECTION_TIMEOUT will miss new KERNEL_CONNECTION_FAILED cases until updated (per PR dependency on kernel#4421).

^{Reviewed by Cursor Bugbot for commit 9c222e9. 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.}

[Sayan-]

• p2: A later signal/offer rearms the two-second media timeout even after the peer has connected. If ICE stays connected without another state-change event, the timer reports a timeout and disconnects. The server can send an offer on renegotiation, but I could not establish that routine operations trigger one. I reproduced the client path with a simulated peer, not a live browser.

[robertjamesprior]

p2 — fixed, and it was a real one. The media bound is now armed only while the first connect is still in flight: a later signal/offer on a connected (or checking) peer no longer starts the two-second timer, so a renegotiation can't report a timeout and tear down a live session. connect() also resets the per-attempt connected flag, so a second login on the same client still gets its media bound.

While I was in there I took the two Bugbot findings on the same path, since they're the same class of stale-bound problem:

• disconnect() now clears the socket's onopen handler too. It was left attached, so a socket that opened as close() ran could re-arm the signaling bound and post a second failure for a connect that had already given up.
• A renegotiation signal/offer while the connect is still in flight stays bounded — the guard only skips the arm once ICE has reached checking or the peer is connected.

Three tests added in connect-bound.test.ts; reverting the source change fails two of them. bun test tests 38 pass / 0 fail, tsc --noEmit clean.

The p1 (dashboard recognising both events) is kernel/kernel#4421, unchanged and still the one that goes first.

[robertjamesprior]

Stacked a fix for the one stretch the bounds missed: #427.

oniceconnectionstatechange cleared the bound on checking, but onConnected and KERNEL_CONNECTED wait for connected. A peer that reached checking and then stalled had no timer watching and reported nothing — the silent frame this PR is about, in the only part of the connect still unbounded. Leaving it armed costs nothing healthy: connected follows checking by tens of milliseconds, inside the same 2s budget. reason stays media.

Not included: a stall that begins after playback. That needs a frame-progress signal, and the peer path has no access to the media element, so it lands in the video layer as a separate change.