feat: add terminal session management with HTTP/WebSocket routes and session history

USAGE.md

@@ -801,7 +801,8 @@ The installed command is `nest --serve`; `python3 -B -m nest --serve` also
 works from the source checkout. Nest uses `UVM_API_TOKEN` and the `UVM_*` host
 settings for its machine-management backend. To launch the standalone UVM API,
 use `./uvm.py --serve` with the same host/port options and configuration. That
-server exposes the management endpoints and `/docs`; Nest serves the dashboard.
+server exposes the UVM management endpoints and `/docs`; Nest serves the
+dashboard and terminal-session endpoints.
 
 The API token is required even for a loopback server. All VM, diagnostics, and
 installation routes require it. The dashboard shell, liveness route, and FastAPI's
@@ -812,6 +813,40 @@ with no whitespace. Use a protected environment file or secret manager rather
 than recording a real token in shell history; do not share tokens or guest
 passwords in reports.
 
+### Use Sessions Inside a MicroVM
+
+1. Open **Machines** and select the microVM.
+2. Start it if it is stopped.
+3. Click **Launch session**, or open its **Sessions** tab and launch there.
+4. Type directly in the embedded terminal. Each session keeps its own shell,
+   current directory, environment, and foreground program.
+5. Use **Session history** to switch between that VM's sessions. Active sessions
+   reconnect to their existing shell; ended sessions replay saved output.
+6. Use **End session** when finished, or run `exit` inside the shell.
+
+Sessions continue while you navigate elsewhere, reload, or sign out of the
+dashboard. VM shutdown/restart or Nest shutdown ends the shell. Session metadata,
+start/end times, exit status, and output survive Nest restarts in
+`$UVM_BASE/nest/sessions.sqlite3`; files are mode `0600` in a mode-`0700` directory.
+Only sessions belonging to the selected exact VM ID are shown. Reusing a VM name
+does not attach another VM's history.
+
+The retained transcript is capped at its latest 8 MiB, and the terminal viewer
+has a 10,000-line scrollback. A truncation note appears when older output is
+discarded. Terminal input supports pastes up to 64 KiB at a time. Guest output
+is saved even while no browser is attached.
+
+For an older VM, stop it, open **Sessions → Guest terminal setup**, click
+**Install / update terminal support**, and start it again. This uses the existing
+stopped-disk agent upgrade endpoint. If the agent is still starting or installing
+Python, wait for it to become ready before launching a session.
+
+The terminal transport uses the guest agent over vsock. It logs in as the VM's
+configured username; `sudo` inside the terminal uses normal guest authentication.
+Nest supports 32 active sessions per server; each guest agent shares eight
+connection slots with its command-execution endpoint. Run one Nest session
+manager per `UVM_BASE` registry. Reverse proxies must forward WebSocket upgrades.
+
 ### Start a TLS Server
 
 Non-loopback binds require a valid TLS certificate and key. The files must be
@@ -876,6 +911,11 @@ curl --cacert /path/to/ca.pem \
 | `POST` | `/vms/{vm_id}/exec` | Execute a guest command/script over vsock, with optional root privileges |
 | `POST` | `/vms/{vm_id}/agent/install` | Install/upgrade the agent on a stopped VM's disk |
 | `GET` | `/vms/{identifier}/logs` | Read a bounded, non-following log tail |
+| `GET` | `/vms/{vm_id}/sessions` | List saved sessions for an exact VM ID (Nest) |
+| `POST` | `/vms/{vm_id}/sessions` | Launch a terminal, with `{}` or optional `rows`/`cols` (Nest) |
+| `GET` | `/vms/{vm_id}/sessions/{session_id}` | Inspect a session (Nest) |
+| `POST` | `/vms/{vm_id}/sessions/{session_id}/close` | End a session and retain its output (Nest) |
+| `WS` | `/vms/{vm_id}/sessions/{session_id}/terminal` | Authenticated live terminal/replay (Nest) |
 
 Individual lifecycle requests do not expose a CLI dry-run flag and do not prompt
 for confirmation. `timeout` is an optional finite, non-negative query parameter