feat(stream): pion-based WebRTC byte streamer for browser playback

Replaces the broken anacrolix WebTorrent path with a custom WebRTC peer
that the browser drives directly. Architecture matches plan/clever-
weaving-dove.md (Fase 2 + 3 + 6 of the streaming pivot).

- engine/wire: shared 12-byte binary frame format (Hello / RangeReq /
  RangeData / RangeEnd / Cancel / Ping / Pong / SeekHint). Roundtrip +
  oversized-frame rejection tests.
- agent/signal_client: SSE consumer + POST sender for SDP/ICE relay
  through /api/internal/stream/signal/<id>; auto-reconnects.
- engine/webrtc_stream: pion v4 PeerConnection + DataChannel pump.
  Reads file via os.ReadAt, chunks RangeData at 16 KiB, honours app-
  level backpressure with SetBufferedAmountLowThreshold.
- cmd/daemon dispatcher learns mode webrtc_stream + new
  webrtcSessionRegistry tracks per-session cancel funcs for clean
  shutdown.
- engine/probe + hwaccel + transcoder: foundation for Fase 2.5
  (codec detection, NVENC/QSV/VAAPI/VideoToolbox autodetection,
  ffmpeg pipe wrapper to fragmented MP4). Integration into
  webrtc_stream still pending.
- pion/webrtc/v4 promoted from indirect to direct dep.

End-to-end against unarr-dev confirms a 122 MB 1080p H.264 / AAC MP4
plays in Chrome with the new pipeline.

internal/agent/daemon.go

@@ -35,6 +35,7 @@ type Daemon struct {
 	// Callbacks — set by cmd/daemon.go before calling Run.
 	OnTasksClaimed    func(tasks []Task)
 	OnStreamRequested func(req StreamRequest)
+	OnWebRTCSession   func(sess WebRTCSession)
 	OnControlAction   func(action, taskID string, deleteFiles bool)
 	GetActiveCount    func() int // returns number of active downloads (wired from manager)
 
@@ -169,6 +170,11 @@ func (d *Daemon) Run(ctx context.Context) error {
 			d.OnStreamRequested(req)
 		}
 	}
+	d.sync.OnWebRTCSession = func(sess WebRTCSession) {
+		if d.OnWebRTCSession != nil {
+			d.OnWebRTCSession(sess)
+		}
+	}
 	d.sync.OnUpgrade = func(version string) {
 		if version != d.lastNotifiedVersion {
 			d.lastNotifiedVersion = version

internal/agent/signal_client.go

@@ -0,0 +1,233 @@
+package agent
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// SignalRole identifies who produced a signalling message. The opposite role
+// receives it.
+type SignalRole string
+
+const (
+	SignalRoleBrowser SignalRole = "browser"
+	SignalRoleAgent   SignalRole = "agent"
+)
+
+// SignalMessageType matches the server-side z.enum on
+// /api/internal/stream/signal/[sessionId] route.
+type SignalMessageType string
+
+const (
+	SignalMsgOffer        SignalMessageType = "offer"
+	SignalMsgAnswer       SignalMessageType = "answer"
+	SignalMsgCandidate    SignalMessageType = "candidate"
+	SignalMsgCandidateEnd SignalMessageType = "candidate-end"
+	SignalMsgBye          SignalMessageType = "bye"
+)
+
+// SignalMessage mirrors the bus envelope on the web side.
+type SignalMessage struct {
+	From    SignalRole        `json:"from"`
+	Type    SignalMessageType `json:"type"`
+	Payload string            `json:"payload"`
+	TS      int64             `json:"ts"`
+}
+
+// PostSignal enqueues a signalling message produced by this agent. The
+// browser receives it on its next SSE event push.
+func (c *Client) PostSignal(ctx context.Context, sessionID string, msg SignalMessage) error {
+	body := map[string]any{
+		"from":    string(SignalRoleAgent),
+		"type":    string(msg.Type),
+		"payload": msg.Payload,
+	}
+	path := fmt.Sprintf("/api/internal/stream/signal/%s", sessionID)
+	return c.doPost(ctx, path, body, &struct {
+		OK bool `json:"ok"`
+	}{})
+}
+
+// SignalEventStream wraps an open SSE connection. Read messages from Events()
+// until the channel closes (server timeout or context cancel). Always defer
+// Close() to release the underlying response body.
+type SignalEventStream struct {
+	resp   *http.Response
+	cancel context.CancelFunc
+	events chan SignalMessage
+	errs   chan error
+	done   chan struct{}
+}
+
+// Events streams browser-produced messages addressed to the agent.
+// The channel closes when the SSE connection ends; the caller should then
+// call Close() and reopen if it wants to keep listening.
+func (s *SignalEventStream) Events() <-chan SignalMessage { return s.events }
+
+// Err returns the terminating error (if any) once Events() has closed.
+func (s *SignalEventStream) Err() error {
+	select {
+	case err := <-s.errs:
+		return err
+	default:
+		return nil
+	}
+}
+
+// Close cancels the underlying HTTP request and waits for the reader goroutine
+// to drain. Safe to call more than once.
+func (s *SignalEventStream) Close() error {
+	if s.cancel != nil {
+		s.cancel()
+	}
+	if s.resp != nil {
+		s.resp.Body.Close()
+	}
+	<-s.done
+	return nil
+}
+
+// OpenSignalStream opens a long-lived SSE connection to the signal events
+// endpoint. Caller MUST cancel ctx (or call Close()) to free resources.
+//
+// The server caps each response at ~25 s; OpenSignalStream surfaces the
+// disconnect by closing the events channel. Caller should reopen until the
+// session ends.
+func (c *Client) OpenSignalStream(ctx context.Context, sessionID string) (*SignalEventStream, error) {
+	streamCtx, cancel := context.WithCancel(ctx)
+
+	url := fmt.Sprintf("%s/api/internal/stream/signal/%s/events", c.baseURL, sessionID)
+	req, err := http.NewRequestWithContext(streamCtx, http.MethodGet, url, nil)
+	if err != nil {
+		cancel()
+		return nil, fmt.Errorf("open signal stream: %w", err)
+	}
+	req.Header.Set("Accept", "text/event-stream")
+	req.Header.Set("Authorization", "Bearer "+c.apiKey)
+	req.Header.Set("User-Agent", c.userAgent)
+	req.Header.Set("Cache-Control", "no-cache")
+
+	// Use a per-call client with no timeout (SSE connections are long).
+	sseClient := &http.Client{}
+	resp, err := sseClient.Do(req)
+	if err != nil {
+		cancel()
+		return nil, fmt.Errorf("open signal stream: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		resp.Body.Close()
+		cancel()
+		return nil, fmt.Errorf("open signal stream: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+
+	stream := &SignalEventStream{
+		resp:   resp,
+		cancel: cancel,
+		events: make(chan SignalMessage, 8),
+		errs:   make(chan error, 1),
+		done:   make(chan struct{}),
+	}
+
+	go stream.read()
+	return stream, nil
+}
+
+func (s *SignalEventStream) read() {
+	defer close(s.done)
+	defer close(s.events)
+
+	reader := bufio.NewReaderSize(s.resp.Body, 16*1024)
+	var dataBuf bytes.Buffer
+	var eventName string
+
+	for {
+		line, err := reader.ReadString('\n')
+		if err != nil {
+			if err != io.EOF {
+				select {
+				case s.errs <- err:
+				default:
+				}
+			}
+			return
+		}
+		line = strings.TrimRight(line, "\r\n")
+		if line == "" {
+			// End of an event — dispatch if we have data.
+			if dataBuf.Len() == 0 {
+				eventName = ""
+				continue
+			}
+			if eventName == "" || eventName == "signal" {
+				var msg SignalMessage
+				if err := json.Unmarshal(dataBuf.Bytes(), &msg); err == nil {
+					s.events <- msg
+				}
+			}
+			dataBuf.Reset()
+			eventName = ""
+			continue
+		}
+		if strings.HasPrefix(line, ":") {
+			// SSE comment (heartbeat); ignore.
+			continue
+		}
+		if strings.HasPrefix(line, "event:") {
+			eventName = strings.TrimSpace(line[len("event:"):])
+			continue
+		}
+		if strings.HasPrefix(line, "data:") {
+			payload := strings.TrimSpace(line[len("data:"):])
+			if dataBuf.Len() > 0 {
+				dataBuf.WriteByte('\n')
+			}
+			dataBuf.WriteString(payload)
+			continue
+		}
+		// id:, retry:, anything else — ignore for now.
+	}
+}
+
+// SignalLoop runs an SSE consumer that reconnects automatically on disconnect.
+// onMessage is called for every browser-produced message. Returns when ctx is
+// cancelled. Reconnect backoff is fixed at 1 s — the server already paces
+// reconnects with `retry: 1500` headers so churn is bounded.
+func (c *Client) SignalLoop(ctx context.Context, sessionID string, onMessage func(SignalMessage)) error {
+	for ctx.Err() == nil {
+		stream, err := c.OpenSignalStream(ctx, sessionID)
+		if err != nil {
+			select {
+			case <-time.After(time.Second):
+			case <-ctx.Done():
+				return ctx.Err()
+			}
+			continue
+		}
+		for msg := range stream.Events() {
+			onMessage(msg)
+		}
+		streamErr := stream.Err()
+		stream.Close()
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+		// Server closes the SSE every ~25 s; reconnect immediately.
+		// Hard error → small backoff so we don't hammer.
+		if streamErr != nil {
+			select {
+			case <-time.After(time.Second):
+			case <-ctx.Done():
+				return ctx.Err()
+			}
+		}
+	}
+	return ctx.Err()
+}

internal/agent/signal_client_test.go

@@ -0,0 +1,153 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+)
+
+// fakeSSEServer streams a fixed set of SSE events then closes the connection.
+func fakeSSEServer(t *testing.T, msgs []SignalMessage, holdOpenAfter bool) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer test-key" {
+			http.Error(w, "auth", http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		w.Header().Set("Cache-Control", "no-cache")
+		flusher, ok := w.(http.Flusher)
+		if !ok {
+			t.Fatal("server: ResponseWriter is not a Flusher")
+		}
+		fmt.Fprint(w, "retry: 1500\n\n")
+		flusher.Flush()
+		for _, m := range msgs {
+			data, _ := json.Marshal(m)
+			fmt.Fprintf(w, "id: %d\nevent: signal\ndata: %s\n\n", m.TS, data)
+			flusher.Flush()
+		}
+		// Send a heartbeat comment to verify it's ignored.
+		fmt.Fprint(w, ": heartbeat\n\n")
+		flusher.Flush()
+		if holdOpenAfter {
+			// Hold the connection until the client disconnects so the test can
+			// exercise stream.Close().
+			<-r.Context().Done()
+		}
+	}))
+}
+
+func TestSignalStreamReadsMessages(t *testing.T) {
+	want := []SignalMessage{
+		{From: SignalRoleBrowser, Type: SignalMsgOffer, Payload: "{sdp:1}", TS: 1},
+		{From: SignalRoleBrowser, Type: SignalMsgCandidate, Payload: "{cand:1}", TS: 2},
+	}
+	srv := fakeSSEServer(t, want, false)
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "test-ua")
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	stream, err := c.OpenSignalStream(ctx, "session-1")
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	defer stream.Close()
+
+	var got []SignalMessage
+	for m := range stream.Events() {
+		got = append(got, m)
+		if len(got) == len(want) {
+			break
+		}
+	}
+	if len(got) != len(want) {
+		t.Fatalf("got %d messages, want %d", len(got), len(want))
+	}
+	for i, m := range got {
+		if m.From != want[i].From || m.Type != want[i].Type || m.Payload != want[i].Payload {
+			t.Errorf("[%d] mismatch: %+v want %+v", i, m, want[i])
+		}
+	}
+}
+
+func TestSignalStreamPropagatesAuthError(t *testing.T) {
+	srv := fakeSSEServer(t, nil, false)
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "wrong-key", "test-ua")
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+
+	_, err := c.OpenSignalStream(ctx, "session-1")
+	if err == nil {
+		t.Fatal("expected auth error, got nil")
+	}
+}
+
+func TestSignalStreamCloseCancelsRead(t *testing.T) {
+	srv := fakeSSEServer(t, nil, true)
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "test-ua")
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	stream, err := c.OpenSignalStream(ctx, "session-1")
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+
+	// Close on a separate goroutine then make sure the events channel drains.
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		time.Sleep(50 * time.Millisecond)
+		stream.Close()
+	}()
+
+	for range stream.Events() {
+		// drain
+	}
+	wg.Wait()
+}
+
+func TestPostSignalSendsCorrectBody(t *testing.T) {
+	var bodySeen map[string]any
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer test-key" {
+			http.Error(w, "auth", http.StatusUnauthorized)
+			return
+		}
+		_ = json.NewDecoder(r.Body).Decode(&bodySeen)
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprint(w, `{"ok":true}`)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "test-ua")
+	err := c.PostSignal(context.Background(), "sess-x", SignalMessage{
+		Type:    SignalMsgAnswer,
+		Payload: "{sdp:answer}",
+	})
+	if err != nil {
+		t.Fatalf("post: %v", err)
+	}
+	if bodySeen["from"] != string(SignalRoleAgent) {
+		t.Errorf("expected from=agent, got %v", bodySeen["from"])
+	}
+	if bodySeen["type"] != string(SignalMsgAnswer) {
+		t.Errorf("expected type=answer, got %v", bodySeen["type"])
+	}
+	if bodySeen["payload"] != "{sdp:answer}" {
+		t.Errorf("expected payload mismatch, got %v", bodySeen["payload"])
+	}
+}

internal/agent/sync.go

@@ -29,6 +29,7 @@ type SyncClient struct {
 	OnNewTasks       func(tasks []Task)
 	OnControl        func(action, taskID string, deleteFiles bool)
 	OnStreamRequest  func(req StreamRequest)
+	OnWebRTCSession  func(sess WebRTCSession)
 	OnUpgrade        func(version string)
 	OnScan           func()
 	OnWatchingChange func(watching bool)
@@ -191,6 +192,13 @@ func (sc *SyncClient) processResponse(resp *SyncResponse) {
 		}
 	}
 
+	// WebRTC streaming sessions
+	for _, ws := range resp.WebRTCSessions {
+		if sc.OnWebRTCSession != nil {
+			sc.OnWebRTCSession(ws)
+		}
+	}
+
 	// Upgrade
 	if resp.Upgrade != nil && resp.Upgrade.Version != "" && sc.OnUpgrade != nil {
 		sc.OnUpgrade(resp.Upgrade.Version)

internal/agent/types.go

@@ -351,11 +351,25 @@ type LibraryDeleteRequest struct {
 	FilePath string `json:"filePath"`
 }
 
+// WebRTCSession is a request to open a custom WebRTC DataChannel byte-stream
+// to a browser player. The CLI must POST an SDP answer to
+// /api/internal/stream/signal/<sessionId> and serve bytes from FilePath
+// (or, when only InfoHash is set, from a download_task on disk).
+type WebRTCSession struct {
+	SessionID string `json:"sessionId"`
+	FilePath  string `json:"filePath,omitempty"`
+	InfoHash  string `json:"infoHash,omitempty"`
+	TaskID    string `json:"taskId,omitempty"`
+	FileName  string `json:"fileName,omitempty"`
+	FileSize  int64  `json:"fileSize,omitempty"`
+}
+
 // SyncResponse is returned by the server with all pending actions for the CLI.
 type SyncResponse struct {
 	NewTasks       []Task                 `json:"newTasks,omitempty"`
 	Controls       []ControlAction        `json:"controls,omitempty"`
 	StreamRequests []StreamRequest        `json:"streamRequests,omitempty"`
+	WebRTCSessions []WebRTCSession        `json:"webrtcSessions,omitempty"`
 	Watching       bool                   `json:"watching"`
 	Upgrade        *UpgradeSignal         `json:"upgrade,omitempty"`
 	Scan           bool                   `json:"scan,omitempty"`