XERK-278: one WebSocket frame must not be able to kill the hub

[xerhab]

Fixes a remote crash of the hub process reachable with the ordinary operator web login.

Found by the adversarial QA pass on #430's follow-up (XERK-262). The code is pre-existing on main (from XERK-245), so it is fixed here rather than in that PR. Ticket: XERK-278.

The defect

String(x) throws TypeError: Cannot convert object to primitive value for a value with no usable primitive conversion — and pure JSON can express one: {"toString":1,"valueOf":1} gives both hooks as own, non-callable properties.

sanitizeLiveAgents called String() directly on a field parsed out of an /agent/control WebSocket frame. That handler runs inside a socket.on("data") listener with no try/catch above it, and turma/ installs no process.on('uncaughtException'), so the throw exits node.

tunnel connected: victim-host
TypeError: Cannot convert object to primitive value
    at String (<anonymous>)
    at sanitizeLiveAgents (turma/server.js:2278:18)
    at turma/server.js:5126:19
    at Socket.<anonymous> (turma/server.js:3093:7)
Node.js v22.23.1

Why it matters:

• No agent token needed. agentWsAuthorized → agentAuthorized → userAuthorized, so the single-user Basic login opens the socket. Reproduced with TURMA_USER/TURMA_PASSWORD only. That login is reachable through the public Cloudflare tunnel.
• DockerOps runs restart: unless-stopped (compose/turma.yaml:35), so repeating the frame is a sustained outage of the entire control plane — dashboard, tunnels, terminal proxy, archive.
• One packet. No rate limit, no log beyond the crash.

The fix

Two vectors, both closed:

1. sanitizeLiveAgents coerces through a new safeString that cannot throw. Fixed in the function that handles untrusted input, not by wrapping its three callers — a coercion that throws is the bug, and a caller-side guard is one the next caller gets added without. An unconvertible type drops the row (a blank type already did); an unconvertible label blanks the label and keeps the row, so the "an agent is running" signal hasLiveAgents reads is not lost.
2. The frame handler requires the session id to be a string, not merely truthy. liveFanout uses it as a property key, and coercing an object to a key runs the same ToPrimitive. This one only bites once a viewer socket is open on that host (the optional chain short-circuits otherwise), which is why safeString alone does not cover it. Every real id is a string, so this only refuses malformed frames.

Deliberately not fixed with a global uncaughtException handler: that converts the crash into a silent half-state rather than removing it. Worth considering separately.

Verification

• The original one-frame repro now leaves the hub answering (STILL ALIVE, exit 0); before, the listening socket was gone.
• Each half reverted independently reddens the suite — neither is decorative.
• Four new tests in turma/tests/server.test.js: the unit coercions, a real /agent/control socket carrying the poisoned row, a real socket carrying non-string ids with a live viewer attached, and the heartbeat ingest (the third caller — already safe behind the request handler's catch, now pinned so it stays reachable-and-refused rather than becoming a 500 or silently accepted).
• node --test turma/tests/*.test.js agent/tests/*.test.js .github/scripts/tests/*.test.js → 1090 passed, 0 failed.

The control-socket tests run in the same process as the rest of the suite, so a regression does not fail one assertion — it takes the whole run down. That is the intended signal.

Not verified

Not exercised against the deployed hub — the repro is local rigs only, per rules of engagement. The restart: unless-stopped consequence is read from the DockerOps compose file, not observed in production.