Pivot sessions from 1:1 to 1:N viewers with exclusive input focus (epic)

[FelineStateMachine]

Goal

Move from one host / one client to one host / N enrolled clients connected simultaneously, where every client is a viewer (video + audio per its grants) and at most one client at a time holds input focus (KBM and controller). Focus is transferable and revocable at runtime using the capability machinery we already have.

Why the capability model carries this

The 1:1 restriction is a single hardcoded gate, not a design property. SessionRegistry::claim bails when any ActiveSession exists (crates/sigil-host/src/server.rs:1235-1244 @ 17980ad), but everything around it is already per-peer: invitations enroll a specific peer with an exact InvitationGrants bitfield (view, pointer/keyboard, gamepad; crates/sigil-protocol/src/invitation.rs:23-58), each connection negotiates Capability sets in the hello (crates/sigil-protocol/src/handshake.rs:21-135), and input/audio/feedback are separate claims on the session (input_claimed/audio_claimed/feedback_claimed flags). The pivot is: registry holds N sessions, and the input claim becomes a single transferable focus token instead of a per-session flag.

Terminology (use consistently in all sub-issues)

• Viewer: any connected enrolled client. Receives media/audio per its grants.
• Input focus: the single token authorizing live KBM + gamepad injection. Held by at most one viewer. Grantable, transferable, revocable.
• Input-capable: a viewer whose invitation grants include pointer/keyboard or gamepad; eligibility to request focus, not possession of it.

Explicit call-outs (decided now, not later)

1. P2P meshing is a design constraint of this epic, not a follow-up idea. Multi-viewer fan-out chooses transport shapes now. If media objects are only authenticated by the QUIC connection they arrive on, client-relayed distribution is permanently expensive to add. The fan-out issue must keep content authentication independent of the delivery hop, and the mesh issue in this set decides the extent we commit to. See the dedicated sub-issue below.
2. Phase 2 (multiple simultaneous controller holders, controllers 1-4) is out of scope but must not be precluded. It needs per-controller UX, backend arbitration, and a per-controller input stream. What this epic must do for it: carry a controller-slot identifier in the input protocol from day one (only slot 0 valid in this phase) and keep focus modeled as a token set of size 1 rather than a boolean, so growing to per-slot tokens is additive.
3. Legacy point-to-point media transports (v1/v2/v3 streams) stay 1:1. Multi-viewer service is MoQ-transport-only; a second viewer connecting with only legacy transports gets a clean rejection, not a degraded fan-out reimplemented three times.

Sequencing

Protocol first, then host registry, then fan-out and adaptive control in either order, then authorization/limits, then Portal UX. The mesh design doc can proceed in parallel and must review the fan-out issue's design before it merges. Strongly recommended: land the server.rs split (#70) before the registry work; session.rs is exactly the module this epic rewrites.

Task list is in the first comment / linked issues labeled multi-client.

[FelineStateMachine]

Task list

• 1:N protocol: session roles, transferable input focus, and controller-slot identity #75
• 1:N host registry: N concurrent sessions, focus token, lease rework #76
• 1:N media and audio fan-out over MoQ groups (relay-ready by construction) #77
• 1:N adaptive control: aggregate N feedback streams into one encoder policy #78
• 1:N authorization: max-viewers, viewer-only invitations, per-peer revocation, focus policy #79
• 1:N Portal UX: roster, focus state, request/release/handoff flows #80
• P2P mesh distribution: design decision and spike (explicitly in scope for the 1:N pivot) #81
• 1:N limits, resource bounds, and multi-client test harness #82

Sequencing: protocol, then registry, then fan-out and adaptive in either order, then authorization, then Portal UX, with limits/harness last. The mesh design doc proceeds in parallel and gates the fan-out merge. Recommended pre-work: #70 (server.rs split); #55 folds into the registry issue; #39/#40 fixed before or with the adaptive issue.

[humanlayer]

Riptide is working on this issue.

Artifacts:

• 01 Research Questions Multi Viewer Sessions
• 02 Research Multi Viewer Sessions
• 03 Design Discussion Multi Viewer Sessions
• 04 Structure Outline Multi Viewer Sessions
• Ticket