feat(web): live session feed, so the UI tracks changes made elsewhere

[defangdevs]

Motivation

The tabbed workspace and the settings session list only patched themselves after their own form posts, plus a short burst poll (8 × 2.5 s) that ran only while a session was still starting. Anything that changed sessions from elsewhere was invisible until a manual reload:

• agent-box-session add/rm from a terminal,
• an agent spawning a sibling session for itself (a documented, encouraged workflow),
• a second browser tab or a second device,
• the supervisor bringing a listed session up.

What this does

GET {SESS_BASE}/sessions/events is a Server-Sent Events stream. Each frame carries a 16-hex fingerprint of the session state the pages actually render (name, agent, working directory, live/starting). The page compares it with the state it was rendered from and, on a difference, re-fetches itself and patches #tab-bar / #sessions-list — the same swap its own form posts already perform.

Design points worth reviewing:

• Digest only. Session data (argv, cwd, env, prompts) never crosses the stream; the page re-renders server-side. The fingerprint deliberately excludes the supervisor's bookkeeping fields (hasRun, boxSessionId, cleared initialPrompt) so first-spawn rewrites don't look like a change worth re-rendering for.
• One watcher thread for all streams. A sample forks tmux list-sessions, so sampling per client would scale with open browser tabs. The watcher runs only while ≥ 1 stream is connected and exits when the last one leaves — an idle box spawns nothing.
• Bounded cost. Max 8 concurrent streams (past that: 503, and the client keeps polling). Each stream checks for peer EOF once a second, so a closed tab frees its slot immediately instead of when the next keep-alive write fails. Keep-alive comment every 20 s.
• Connect-gap closed. Pages carry <meta name="agent-box-events" content="…" data-fp="…"> and the daemon replays the current fingerprint on connect, so a change landing between render and connect is not lost.
• Fallbacks. ?poll=1 on the same route returns {"fp": …} as one-shot JSON. The client polls it every 5 s with no EventSource or after a refused stream, and keeps a slow 30 s probe (plus one on tab re-show) even while the stream is up — a stream can die in ways neither end notices, and a workspace that silently stopped updating is the bug this PR exists to fix. Probes pause while the tab is hidden.
• Rate-limited the tmux: OSError log line, now that a background sampler can hit it every second.

User-visible effect

Sessions added or removed anywhere appear/disappear in the tab bar and the settings list within about a second, without a reload. No layout or styling change, so no screenshots — the pages look exactly as before.

Security

• The route sits under the existing session-CRUD prefix, so it is behind the same cookie-or-basic auth gate as everything else on the vhost (asserted: unauthenticated → 401).
• GET-only and read-only, and it discloses nothing but a digest, so no CSRF surface is added.
• No new privileges, sudo rules, units, ports or firewall changes; the daemon still runs as the agent user and only reads.

AWS / cost / migration

None. No template, IAM, networking or state changes; nothing to migrate.

Checks run

• python3 bin/assemble-module.py --check — modules/agent-box.nix regenerated and up to date.
• Real Chromium (nixpkgs Playwright) against a locally-run copy of the daemon: tabs appear and disappear with no navigation, the settings list tracks the same changes, the no-EventSource fallback polls and catches up, a 503'd stream falls back too, and stream slots are released when a page closes.
• Existing browser behaviour unregressed against the same rig: SPA layer: saving and deleting never triggers a full page load, the tab close button arms first and only closes on a second click, ?tab= selects a tab server-side, no root-page href embeds URL userinfo, plus the secret save/edit/delete specs.
• nix-instantiate --parse tests/sessions.nix and a compile of its extracted testScript; playwright test -c tests/e2e --list for the specs.

Not run here: the NixOS VM checks (sessions, settings-page) — this box is aarch64 and the flake's checks are x86_64-only, so CI is their first real run. The new sessions subtest is the important one: it holds a stream open from the client VM through Caddy and requires a frame whose fingerprint differs from the stream's own first frame after a CLI agent-box-session add, so merely receiving a frame cannot pass it.

Note, unrelated to this PR

tests/e2e/root-sessions.spec.ts:90 ("add a session from the tab bar…") is already broken on master: it fills input[name="name"], which the add form dropped when session names became auto-derived. Left alone here.

🤖 Generated with Claude Code

https://claude.ai/code/session_013VoCn5tqBY3hKKwmtCH1kx

[lionello]

Does this remove the polling?