# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

The machine that owns a session can now serve its live terminal stream to a peer machine, securely. A peer requests a single-use bearer ticket over the existing machine-authed mesh channel (`pool-stream-ticket` verb); the serving machine mints it via the new StreamTicketStore (60s TTL, single-use, persisted so a captured ticket can't replay across a restart). The peer opens a `/pool-stream` WebSocket carrying that ticket; the serving machine consumes it once and treats the peer as a streaming client. Remote keystroke input is OFF by default (per-machine opt-in); session names are validated (tmux-safe charset + must be running) before anything reaches the shell.

This is the serving (has-the-session) half. The requesting half (the dashboard auto-opening these connections) and the on-screen UI are phases 2b and 3.

## What to Tell Your User

Nothing changes on screen yet — this is the secure plumbing the click-to-stream feature will use. Default posture: other machines can watch, not type, unless you opt in.

- audience: agent-only
- maturity: preview

## Summary of New Capabilities

- `StreamTicketStore` — single-use, TTL-bounded, restart-replay-proof stream tickets.
- `pool-stream-ticket` mesh verb — mints a ticket for an authenticated peer.
- `/pool-stream` WebSocket serving endpoint — ticket-gated; peer streams a session.
- Serving-side guards: `dashboard.poolStream.allowRemoteInput` (default false); session-name validation (`^[A-Za-z0-9_.:@-]+$` + must-be-running) before tmux.

## Evidence

- `tests/unit/StreamTicketStore.test.ts` (11): single-use, expiry, wrong-machine, bearer mode, replay-across-restart, corrupt-fail-closed, GC.
- `tests/e2e/pool-stream-serving-alive.test.ts` (6, real http server + real ws): valid ticket streams; bad ticket → 401; single-use enforced; input gated off by default; input accepted when on; tmux-unsafe name refused.
- `tests/unit/WebSocketManager.test.ts` updated for the new existence-before-input guard. tsc clean; state registry + MeshRpc RBAC updated.
