docs: record v0.4 multi-device session sharing (relaxes invariant #5)

This commit is contained in:
Yaojia Wang
2026-06-19 10:31:28 +02:00
parent 24b3cbd507
commit 22210fadbc
2 changed files with 4 additions and 3 deletions

View File

@@ -77,8 +77,8 @@ Data flow: `keypress → xterm onData → WS → pty.write() → shell stdin`, a
- `attach(null)` → spawn a new PTY + shell; PTY output goes into a ~2MB **ring buffer** and (if a WS is attached) forwards live.
- `attach(sessionId)` → look up the session, **replay the ring buffer**, then resume the live stream. This is what makes "refresh the page and the Claude session is still there" work.
- WS close → `detach` (mark session unwatched, PTY keeps running), not kill.
- Only one WS attached per session at a time — a new attach kicks the old WS to avoid interleaved input.
- WS close → `detach` one client (PTY keeps running), not kill; the idle clock starts only when the **last** client leaves.
- **Multi-device sharing (v0.4):** a session may have **many concurrent WS clients** — a new attach **JOINS (mirror)**, it does **not** kick. Output/exit/status broadcast to all; any client can type (shared control); the PTY size is the **min cols/rows across clients** (tmux-style). This relaxes the original "one WS per session" invariant (#5). `GET /live-sessions` lists running sessions so any device **auto-shows them as tabs**; `?join=<id>` and the 🔗 share-QR open a specific shared session.
- Orphan reclaim: detached longer than `IDLE_TTL` (default 24h) **with no new output since detach** → reclaim. (node-pty can't reliably detect a foreground child, so liveness is approximated via last-output time — see ARCHITECTURE §3.5 / M3.) On server exit, `pty.kill()` all sessions (no cross-restart persistence in v0.1; tmux backend is a v0.2 idea).
Represent session state as immutable snapshots (id/start-time fixed at creation); hold mutable runtime handles (pty/ws) separately.