docs(roadmap): mark hueco #2 closed (2a+2b+2c)

Debrid direct links are time-limited; a long playback can outlive the link
the session was created with. When a debrid source dies mid-stream the daemon
now re-resolves a fresh link for the same content and resumes — no torrent
fallback, no playback restart.

- debridFileProvider holds the URL behind a mutex; on an expired-link status
  (401/403/404/410) the ranged reader re-resolves via a refresh callback and
  retries (bounded: 1 initial + 1 post-refresh attempt). A browser opens
  several range connections, so the refresh is coalesced singleflight-style —
  N readers hitting the dead link share ONE re-resolution, not N.
- HLS-from-URL: the auto-restart supervisor re-resolves the link before
  relaunching ffmpeg (else it just retries the dead URL and burns the retry
  budget). The mutable URL lives in s.liveURL under s.mu — restartFromSegment
  reads it from the HTTP handler goroutine too (seek-restart), so cfg stays
  immutable and the write races nothing.
- agentClient.RefreshStreamURL → POST /api/internal/agent/stream-url.

Cross-source torrent<->debrid swap (the rare "debrid genuinely gone" case) is
intentionally deferred. Reader refresh + coalescing covered by unit tests
(incl. -race); the web endpoint re-resolves against a real AllDebrid account.

Docs/plans/unarr-agent-roadmap.md

@@ -0,0 +1,585 @@
+# unarr CLI agent — roadmap del diferenciador
+
+> Estado de partida: **v0.9.19 beta** (~26k LOC fuente / ~18k test).
+> Objetivo estratégico: el agente CLI es el **soporte real y diferenciador** de
+> unarr — un *servidor de streaming personal* que la web sola no puede ser.
+> Compite en **profundidad**, no en anchura (no apps nativas por dispositivo:
+> el agente sirve a un único web-player responsive vía navegador).
+
+## La visión en 6 puntos
+
+1. **Hospeda localmente** toda la biblioteca.
+2. **Debrid** para reproducir cualquier cosa cache-fast.
+3. **Play-anything sin callejones** (local | debrid | descarga-y-reproduce, con
+   fallback mid-stream).
+4. **Transcodifica según el dispositivo** (direct-play cuando ya es compatible).
+5. **Sirve a un web-player universal** en cualquier dispositivo vía navegador.
+6. **Acceso remoto seguro** al agente.
+
+## Mapa de partida (qué TIENE el agente hoy)
+
+Sólido salvo nota:
+
+- **Descarga torrent** (anacrolix): mmap, DHT warm-start, 30 trackers, pause/cancel,
+  selección vídeo+subs `[engine/torrent.go]`. **Stream-while-download** con reader
+  responsive + `PrioritizeTail` `[engine/stream.go]`.
+- **Usenet** completo: NNTP pool, yEnc, ensamblado `WriteAt`, resume por segmento,
+  par2 repair, unrar/7z `[usenet/*]`.
+- **Debrid downloader**: GET con Range/resume `[engine/debrid.go]` — pero solo
+  DESCARGA (no streaming). Resolución server-side.
+- **HLS transcode** fMP4 + seek real + supervisor `[engine/hls.go]`, **caché HLS LRU**
+  `[engine/hls_cache.go]`, **HW accel** NVENC/QSV/VAAPI/VideoToolbox `[engine/hwaccel.go]`.
+- **Servidor HTTP** persistente: range/seek, rate-limit 2×bitrate, CORS `[engine/stream_server.go]`.
+- **Library scan + ffprobe** (codec/HDR/tracks), parse título/temporada `[library/, mediainfo/]`.
+- **Red**: CloudFlare Quick Tunnel `[funnel/]`, WireGuard userspace split-tunnel `[vpn/]`,
+  NAT-PMP + UPnP `[engine/upnp.go]`. Web hace de broker de URLs (LAN/Tailscale/Public/Funnel).
+- **Agente**: daemon cobra, sync HTTP long-poll + `/wake`, auto-upgrade opt-in,
+  config.toml exhaustivo.
+
+## Huecos (de más crítico a más bajo)
+
+### Hueco #1 — Auth de stream  ✅ CERRADO (2026-05-31) / ver estado abajo
+`/stream` y `/hls` se sirven **sin autenticación** (solo CORS+rate-limit). Con
+funnel/UPnP el stream queda público en internet. Plan previo
+`Docs/plans/security-stream-token.md` (deferido, sin código).
+
+### Hueco #2 — Debrid en el path de streaming  ✅ CERRADO (2a+2b+2c, 2026-05-31)
+Hoy debrid es **solo descarga**, resuelto server-side; el streaming es 100%
+torrent. La promesa "play instantáneo cache-fast" no ocurre. Falta: source debrid
+en el path de streaming + cache-availability + **fallback torrent↔debrid mid-stream**.
+Diseño por fases (2a direct-play / 2b HLS-desde-URL / 2c fallback) en el estado abajo.
+
+### Hueco #3 — Device-profile + direct-play + ABR  ✅ CERRADO (2026-05-31) / ver estado abajo
+El path HLS re-encodaba todo (incluso mp4 h264/aac ya compatible). `DecideAction`
+muerto. Sin negociación por capacidades. Sin adaptación de calidad.
+Diseño por fases (3a direct-play / 3b remux fMP4 / 3c capability-negotiation / 3d ABR)
+en el estado abajo. **3a + 3b + 3c CERRADAS** (smoke e2e, incl. HEVC en iPhone Safari
+real). **3d resuelto como 3d-lite (auto-downshift)** — ABR multi-rendition real
+descartada (N× CPU inviable single-viewer; no aplica a paths copy). Hueco COMPLETO.
+
+### Hueco #4 — Pre-transcode (transcode-on-download)  🔵 DISEÑADO (ver estado abajo)
+Al completar una descarga/import, transcodificar/remuxar en background para que el
+PRIMER play sea instantáneo (direct o cache-HIT), sin transcode en vivo.
+Optimización, nunca bloqueante: si no terminó a tiempo → fallback a transcode en
+vivo (HLS actual). Reaprovecha `hls_cache.go` (cache-HIT ya sirve instantáneo) +
+el pipeline de `prewarm` (ya hace encode de la siguiente ep) — generaliza prewarm a
+"todo download, configurable" y puebla también el artefacto direct-play. Configurable
+desde la web. Diseño + set de opciones en el estado abajo.
+
+### Huecos medios  ⬜
+- Sin gestión de espacio en disco (`Statfs`) → disco lleno revienta a mitad.
+- Resume de torrent NO persiste reinicio del daemon (usenet sí).
+- Sin seeding/ratio lifecycle (flags existen, nadie los aplica).
+- Reproducir-mientras-baja: readahead estático 5MB, sin playhead→prioridad dinámica.
+- HDR→SDR sin tonemap (zscale/zimg) → HDR desaturado.
+- Sin thumbnails/sprites/trickplay.
+- Subtítulos bitmap (PGS/DVB) sin burn-in.
+- Audio siempre downmix estéreo AAC (sin passthrough 5.1).
+- Mediaserver solo DETECTA Plex/Jellyfin/Emby — no biblioteca navegable propia.
+- TLS solo vía funnel; LAN/Tailscale/UPnP = HTTP plano (mixed-content desde web HTTPS).
+- Funnel = SPOF CloudFlare (rota ~6h), sin relay propio.
+- "Tailscale Funnel" mal nombrado (no usa tsnet/Funnel real).
+- Dos clientes HTTP divergentes (go-client vs agent client).
+- Long-poll en vez de WS/SSE.
+
+### Deuda puntual
+`makeReadable` parchea mmap 0000 (frágil NFS) · par2/unrar degradan en silencio si
+falta binario · VAAPI workarounds por host · cloudflared sin verificación de firma ·
+WireGuard endpoint sin pin · sesión única (1 viewer).
+
+## Mejoras detectadas durante el trabajo (backlog)
+
+> Se rellena a medida que se trabaja cada hueco. Cada entrada: qué, por qué, prioridad.
+
+- **Clock-skew en verificación de token** (baja): `verifyStreamToken` no tolera skew; con TTL 6h y NTP es irrelevante, pero el HLS lo mintea el web y lo verifica el agente (relojes distintos). Considerar ~60s de gracia si aparecen 404 espurios.
+- **Secreto de stream en claro en DB** (baja): `agent_registration.stream_secret` es una clave HMAC viva (por arranque) en la DB central; quien lea la DB puede mintear tokens HLS de cualquier agente. Inherente al diseño (el web debe mintear HLS). Mitigado por regeneración por arranque. Excluir esta columna de cualquier JSON admin/usuario.
+- **Refrescar/limpiar streamUrl al re-registrar** (baja): tras reinicio del daemon el secreto cambia; URLs `?t=` ya guardadas en `download_task.streamUrl` quedan stale hasta re-stream. Es auto-curativo, pero el web podría limpiar streamUrl en el re-register del agente.
+- **gofmt preexistente** en `internal/agent/types.go` (StreamSession) y `hls.go`/`torrent.go`/`stream_source.go` (no introducido por este trabajo) — chore aparte.
+- **Funnel = SPOF CloudFlare** (ya en huecos medios): el funnel sigue siendo trycloudflare; relay propio pendiente.
+
+---
+
+## ESTADO POR HUECO
+
+### Hueco #1 — Auth de stream
+**Estado:** 🟡 en progreso (iniciado 2026-05-31).
+
+**Enfoque elegido** (mejora sobre el plan previo, menor blast radius — sin migración DB):
+token **HMAC stateless minteado por el propio agente**. El agente ya construye las
+stream URLs que reporta a la web (`daemon.go` → `streamSrv.URLsJSON()`), así que
+puede firmar el token, embeberlo en la URL, y verificarlo en cada request — la web
+es passthrough (cambio web ~nulo).
+
+- Secreto: 32 bytes random en memoria del daemon (rota al reiniciar).
+- Token: `<expUnix>.<hexHMAC(secret, scope:exp)>`, TTL 6h.
+- `/stream` + VLC: token en query `?t=`; scope `"stream"`.
+- `/hls`: token en **path** `/hls/<sessionID>/<token>/<resource>`; scope `"hls:<sessionID>"`.
+  Los URIs hijos de los playlists son **relativos** → el token se propaga solo a
+  segmentos/subs sin reescribir playlists.
+- **Loopback exento** (mpv/vlc local + health-probe siguen funcionando; el token solo
+  gatea acceso remoto LAN/Tailscale/Public/funnel).
+- Config `require_stream_token` (default **true**, seguro por defecto).
+
+**Hecho (CERRADO 2026-05-31):**
+
+CLI (`torrentclaw-cli`):
+- `internal/engine/stream_token.go` (nuevo): `mintStreamToken`/`verifyStreamToken` (HMAC-SHA256, constant-time), `newStreamSecret` (32 bytes; **fail-hard** si crypto/rand falla, sin fallback débil).
+- `internal/engine/stream_server.go`: secreto + `requireToken` en StreamServer; `/stream` y `/hls` verifican el token; `URLsJSON`/`hlsBaseURLs`/`URL()` tokenizan; `StreamSecretHex()`; **sin exención de loopback**; `/playlist.m3u` ya no auto-mintea (cerrado el oracle).
+- `internal/config/config.go`: `require_stream_token` (default true).
+- `internal/agent/{types,daemon}.go` + `internal/cmd/daemon.go`: el agente reporta el secreto en register **solo si enforcing**.
+- Tests: `stream_token_test.go` (mint/verify/expiry/tamper/scope/secret, handler /stream + /hls, **vector de paridad cross-lenguaje**).
+
+WEB (`torrentclaw-web`):
+- `src/lib/stream-token.ts` (nuevo): minter HMAC en TS (paridad byte a byte con Go, guard de clave 64-hex).
+- `src/app/api/internal/stream/session/route.ts`: `buildHlsUrls` inyecta el token de path usando el secreto del agente.
+- `src/lib/db/schema.ts` + migración `0134_grey_chat.sql`: columna `agent_registration.stream_secret` (ADD COLUMN nullable, segura).
+- `src/app/api/internal/agent/register/route.ts` + `src/lib/services/agent.ts`: valida (64-hex) + persiste + expone en `getAgentHealth`.
+- Tests: `tests/unit/stream-token.test.ts` (paridad + guard).
+
+**Revisión adversarial** (workflow 4 dimensiones) → 1 crítico + 3 high corregidos antes de cerrar:
+- **CRÍTICO**: la exención de loopback dejaba el **funnel CloudFlare** sin protección (cloudflared proxya tráfico público vía `localhost` → todo el funnel llegaba como loopback). **Fix: eliminada la exención.** Toda URL entregada ya va tokenizada, así que ningún cliente legítimo se rompe; el funnel ahora lleva el token en la URL y verifica.
+- **HIGH** `/playlist.m3u` era oracle de tokens (fallback self-minting) → **fix: 404 sin streamUrl**.
+- **HIGH** gate de version-skew mal señalizado (el agente reportaba el secreto aunque enforcement=off) → **fix: reportar solo si enforcing**.
+- **HIGH** new-agent+old-web rompe HLS remoto → **mitigación por orden de deploy (ver abajo)**, sin tolerar tokenless (no reabrir el agujero).
+
+**Verificación:** CLI `go build/vet/test ./...` ✓; WEB typecheck+lint+2325 unit ✓; paridad cross-lenguaje verificada en ambos sentidos.
+
+> ⚠️ **ORDEN DE DEPLOY (obligatorio):** desplegar **primero el WEB** (columna `stream_secret` + minteo HLS), **luego** publicar el binario del agente. Un agente nuevo (enforce por defecto) contra un web viejo (sin minteo HLS) rompería el HLS remoto. El web es retrocompatible (agente viejo sin secreto → URLs sin token). Smoke real de extremo a extremo (daemon + funnel + navegador) **pendiente de hacer con un agente desplegado** — los tests cubren mint/verify/handlers y la paridad, no el round-trip cloudflared en vivo.
+
+---
+
+### Hueco #2 — Debrid en el path de streaming
+**Estado:** ✅ CERRADO (2a+2b+2c, 2026-05-31).
+
+**CERRADO 2c (2026-05-31):** fallback mid-stream, alcance = **refresh de URL
+debrid** (decisión del usuario; el swap cross-source torrent↔debrid se difiere —
+caso raro, gran complejidad). La preferencia cache-fast (preferir debrid
+cacheado sobre torrent en streaming) ya la daban 2a/2b por orden de resolución.
+Los links debrid caducan; una peli larga sobrevive al link → al detectar expiry
+(401/403/404/410 en direct-play, o salida de red de ffmpeg en HLS) el agente
+re-resuelve (mismo info_hash → link fresco) y reanuda sin reiniciar.
+- WEB: endpoint `POST /api/internal/agent/stream-url` (withAgentAuth) →
+  re-resuelve + actualiza fila + devuelve URL. Guard: sesión debrid viva
+  (`direct_url IS NOT NULL`). 409 sin sesión, 410 si re-resolución falla.
+- CLI: `agentClient.RefreshStreamURL`; `debridFileProvider` URL mutable bajo
+  mutex + reader refresca en expiry (bounded 1+1) + **coalescing singleflight**
+  (N readers del `<video>` → 1 re-resolución); HLS refresca `s.liveURL` (guarded,
+  cfg inmutable → race-free con el seek-restart del handler HTTP) antes del
+  auto-restart de ffmpeg.
+- Validado: reader refresh + coalescing unit-tested (incl. -race); endpoint
+  e2e contra AllDebrid real (URL fresca + fila). El swap torrent↔debrid queda
+  como mejora futura si aparece demanda.
+
+**CERRADO 2b (2026-05-31):** HLS-desde-URL para contenido debrid no-nativo
+(mkv/HEVC/…). ffmpeg lee la URL debrid directa (`-i <url>` + flags de red
+`-reconnect*`/`-rw_timeout`) y transcodifica a HLS; el seek reinicia ffmpeg con
+`-ss` antes de `-i` (input-seek vía Range). Cache de segmentos por `CacheID`
+(info_hash) → replay hace cache-HIT pese a que la URL cambia cada resolución.
+Validado e2e contra AllDebrid real: mkv HEVC x265 → h264_nvenc desde la URL →
+Chrome reproduce 1080p vía hls.js, subtítulos extraídos del mkv remoto. Bump
+CLI 0.11.0→0.12.0 (gate `DEBRID_HLS_MIN_VERSION`). Ficheros: CLI
+`engine/hls.go` (SourceURL/CacheID/sourceRef + flags red), `cmd/daemon.go`
+(branch 2b + helper `startHLSPlayback`), `engine/hls_cache.go` (`KeyForID`),
+`library/mediainfo/ffprobe.go` (no enmascarar errores de URL). WEB
+`stream/debrid-stream-source.ts` (playMethod direct|hls por contenedor),
+`services/agent-version-compare.ts` (`supportsDebridHls`).
+Limitación: solo audio default (raw debrid sin UI de pistas); subs bitmap (PGS)
+no soportados (igual que HLS local). Si AllDebrid no marca "ready" al primer
+addMagnet → fallback torrent (sin callejón).
+
+**CERRADO 2a (2026-05-31):** debrid como fuente de `/stream` (direct-play),
+validado e2e contra AllDebrid real (cuenta hello@torrentclaw.com): play de un
+infoHash cacheado mp4 → web resuelve la DirectURL → agente sirve `/stream` por
+GETs ranged → Chrome reproduce el mp4 1080p real (incluido seek a offset alto
+para el moov de un fichero sin faststart). CLI bump 0.10.0→0.11.0 (binario local,
+sin publicar). Fichero clave: `internal/engine/stream_source_debrid.go`.
+- CLI: `StreamSession.DirectURL`; `debridFileProvider` (`io.ReadSeekCloser` sobre
+  HTTP Range, Seek sin red + GET lazy + reopen-on-seek + HEAD para tamaño +
+  nombre derivado de URL para Content-Type correcto); branch en
+  `daemon.OnStreamSession` (DirectURL presente → provider en goroutine →
+  SetFile → MarkSessionReady), antes de validar filePath y sin ffmpeg.
+- WEB: columna `streaming_session.direct_url` (mig 0137) + índice
+  `idx_debrid_cache_info_hash` (mig 0138, getHashCacheTier filtra por info_hash);
+  helper `resolveDebridStreamSource` (honesty gate: sin fichero local + infoHash
+  + agente ≥0.11.0 + `getHashCacheTier`==="verified" + container mp4/m4v +
+  audioIndex -1 + !forceTranscode → resuelve DirectURL, playMethod="direct",
+  quality "original"); gate de versión `DEBRID_STREAM_MIN_VERSION`/
+  `supportsDebridStream`; `getPendingStreamSessions` emite `directUrl` + fallback
+  fileName/fileSize vía join a `torrent` (cubre el caso HEAD-falla del provider).
+- Player: sin cambios — reusa el path direct-play del hueco #3 (playMethod=direct
+  + streamUrls).
+- Limitación 2a (honesta): solo contenido debrid mp4/m4v browser-native; mkv/HEVC
+  debrid → fallback a torrent hasta 2b (HLS-desde-URL). Si AllDebrid no marca el
+  torrent "ready" al primer addMagnet → fallback a torrent (sin callejón).
+
+**Diseño original (2b/2c siguen vigentes):**
+
+**Problema (confirmado en el análisis):** hoy `debrid` es **solo descarga**
+(`engine/debrid.go` baja la `DirectURL` HTTPS resuelta server-side). El
+streaming es **100% torrent**: `daemon.OnStreamSession` arma el provider desde
+`sess.FilePath`/`sess.InfoHash`/`sess.TaskID` y `StreamSession` **no lleva
+DirectURL**. La promesa "play instantáneo cache-fast por debrid" no ocurre.
+
+**Arquitectura de providers (lo que ya hay):** `FileProvider{ NewFileReader(ctx)
+io.ReadSeekCloser; FileName(); FileSize() }`. Implementaciones: `torrentFileProvider`,
+`diskFileProvider`, `StreamEngine`. El /stream sirve un `FileProvider` via
+`http.ServeContent` (range/seek). El HLS arranca una `HLSSession` desde una ruta
+de fichero (ffmpeg `-i <path>`).
+
+**Diseño por fases (de menos a más riesgo):**
+
+- **Fase 2a — debrid como fuente de /stream (direct-play).** *Slice completo y
+  acotado.*
+  1. Añadir `DirectURL string` a `StreamSession` (web→agente) y a su validación.
+  2. Nuevo `debridFileProvider` (`FileProvider`): `NewFileReader` devuelve un
+     `io.ReadSeekCloser` que hace **GET con Range** contra la `DirectURL` (debrid
+     ya soporta Range, ver `debrid.go`); `FileSize` via HEAD o `sess.FileSize`;
+     `Seek` traducido a `Range:`. Reutilizar la lógica de `debrid.go` (416,
+     Content-Range, reintentos).
+  3. En `OnStreamSession`: si `sess.DirectURL` presente → `debridFileProvider`
+     → `SetFile`. (Direct-play; el navegador hace range sobre el provider.)
+  4. Web: al crear la sesión de stream, si el contenido está **cacheado en
+     debrid**, resolver la `DirectURL` server-side (como en descargas) e incluirla
+     en el `StreamSession`. Señal de cache: `debridCacheStatus` fresh (ya existe).
+  5. Tests: `debridFileProvider` con un httptest server que sirve Range; round-trip
+     /stream con provider debrid.
+
+- **Fase 2b — HLS desde URL (transcode de fuentes debrid no-compatibles).**
+  ffmpeg lee HTTP directo (`-i https://…`), así que `HLSSession` puede aceptar
+  una URL como source en vez de una ruta. Mayor cambio en el pipeline HLS
+  (timeouts, reintentos de red, headers). Permite transcodear contenido debrid.
+
+- **Fase 2c — selección cache-fast + fallback mid-stream ("sin callejones").**
+  - Conciencia de cache en el agente o señal del web para **preferir debrid
+    cacheado sobre torrent** cuando aplique (hoy `resolve.go:22` pone torrent
+    primero).
+  - **Fallback mid-stream**: si la fuente activa muere (peers a 0 / 5xx debrid),
+    cambiar a la otra sin cortar la reproducción. Complejo (estado de sesión,
+    re-seek). Es lo que de verdad cierra "play-anything sin callejones".
+
+**Ficheros a tocar:** CLI `internal/engine/{stream_server.go (provider), debrid.go,
+hls.go (2b)}`, `internal/agent/types.go` (+DirectURL), `internal/cmd/daemon.go`
+(wiring). WEB `src/app/api/internal/stream/session/route.ts` (resolver DirectURL +
+cache), `src/lib/services/agent.ts`.
+
+**Partes difíciles / riesgos:** ranged reader robusto sobre HTTP (reconexión,
+timeouts), HLS-desde-URL (red dentro de ffmpeg), y el fallback mid-stream (estado).
+Empezar por 2a (valor inmediato, riesgo bajo), 2b y 2c como iteraciones.
+
+**Mejora detectada:** `resolve.go:22` ordena `torrent > debrid > usenet`; para el
+diferenciador cache-fast convendría que, **cuando hay cache debrid confirmada**,
+el orden de STREAMING (no el de descarga) prefiera debrid.
+
+---
+
+### Hueco #3 — Device-profile + direct-play + ABR
+**Estado:** 🔵 EN CURSO (2026-05-31). Análisis cerrado; fase 3a en implementación.
+
+**Problema (confirmado en el análisis):**
+- El path browser usa **HLS y SIEMPRE re-encoda**: `buildHLSFFmpegArgsAt`
+  (`engine/hls.go`) pone `-c:v libx264|nvenc|…` + cadena de filtros completa
+  (scale/format/setparams) + AAC, sin rama de copia. Un mp4 h264/aac 8-bit SDR
+  que el navegador reproduciría tal cual se transcodifica entero. Coste de CPU
+  puro desperdicio.
+- `DecideAction` + `diskFileSource`/`transcodeSource` (`engine/probe.go`,
+  `engine/stream_source.go`) **son código muerto**: cero callers en producción,
+  solo tests. Distinguen `passthrough/remux/remux-audio/transcode-video` y detectan
+  10-bit/HDR — la lógica de decisión ya existe, no está cableada.
+
+**Lo que ya hay y se reaprovecha:**
+- El agente ya expone **dos paths** en el StreamServer (puerto 11818):
+  - `/stream` → sirve el fichero crudo con `http.ServeContent` (HTTP Range
+    completo, sin ffmpeg, ya tokenizado). **Direct-play ya es posible aquí.**
+  - `/hls/<id>/…` → transcode HLS.
+- El web **construye las URLs** (HLS hoy) desde la info de red del agente
+  (`streamPort`, `tailscaleIp`, `lanIp`, `funnelUrl`, `streamSecret`) y **puede
+  mintear tokens** (`mintStreamToken`, scope `stream` es constante). O sea: el web
+  puede construir la URL `/stream?t=…` de direct-play él mismo.
+- `libraryItem` ya guarda del scan: `videoCodec`, `audioCodec`, `bitDepth`, `hdr`,
+  `resolution`. Con el contenedor (extensión de `fileName`), el web tiene todo
+  para decidir direct-play SIN re-probar.
+
+**Diseño por fases (de menos a más riesgo):**
+
+- **Fase 3a — direct-play passthrough para items de biblioteca.** *El web decide.*
+  *Slice acotado, ambos sentidos de version-skew seguros vía gate de versión.*
+  1. WEB `decidePlayMethod({videoCodec,audioCodec,bitDepth,hdr,container})` →
+     `"direct" | "hls"` (espeja la rama passthrough de Go `DecideAction`: solo
+     `mp4/m4v` + `h264` + `aac` + 8-bit + SDR → direct; todo lo demás → hls).
+  2. WEB gate: `supportsDirectPlay(agentVersion)` (constante de versión mínima).
+     Direct-play solo si el agente la soporta; si no → hls (sin regresión).
+  3. WEB sesión: en la rama `libraryItemPublicId`, seleccionar los campos codec;
+     calcular `playMethod` (gated); persistirlo en `streamingSession.play_method`
+     (migración aditiva, `db:generate`); devolver `playMethod` + `streamUrls`
+     (`/stream?t=` minteadas por el web, lan/ts/funnel) en la respuesta.
+  4. WEB sync: `getPendingStreamSessions` emite `playMethod` al agente.
+  5. CLI: `StreamSession.PlayMethod string`; en `OnStreamSession`, si
+     `PlayMethod=="direct"` → `streamSrv.SetFile(NewDiskFileProvider(path))` +
+     `MarkSessionReady` (sin ffmpeg). Else → `StartHLSSession` (actual).
+  6. WEB player (`HlsStreamPlayer.tsx`): si `data.playMethod==="direct"` → usar
+     `data.streamUrls` + attach nativo `<video src>` (mp4 = reproducible en todo
+     navegador, sin hls.js). Else → flujo HLS actual.
+  - **Limitación honesta:** solo cubre items de biblioteca (escaneados, con
+    metadata codec). Raw `infoHash`/`taskId` → hls (sin probe). Cubrir esos
+    casos = fase 3a-bis (el agente decide tras probar, reportando playMethod por
+    `MarkSessionReady` — requiere extender el payload + SSE + diferir el attach
+    del player al evento ready). Diferido por mayor superficie.
+
+- **Fase 3b — remux fMP4 progresivo vía /stream (ENFOQUE ELEGIDO 2026-05-31).**
+  Caso `mkv` (u otro contenedor no-mp4) con h264 + aac + 8-bit + SDR: codecs ya
+  browser-native, solo el contenedor estorba. `-c copy` evita el re-encode de vídeo.
+  Descartado HLS-copy (duraciones de segmento variables vs manifiesto pre-render →
+  rompe seek; arreglarlo = probe de keyframes lento o reescribir el núcleo HLS).
+  **Enfoque:** ffmpeg `-c copy -movflags +frag_keyframe+empty_moov+default_base_moof
+  -f mp4` mkv→fMP4 a fichero temporal **creciente**; servir ese fMP4 por **/stream**
+  (mismo path direct-play 3a, attach nativo, sin hls.js, sin manifiesto).
+  **Núcleo real (la parte no-trivial):** servir un fichero que **crece** mientras
+  ffmpeg escribe. El `/stream` actual usa `http.ServeContent` (asume fichero completo
+  y seekable). Hay que:
+  - Resucitar/adaptar el `transcodeSource` muerto (`engine/stream_source.go`):
+    ffmpeg→tmp creciente, `ReadAt` con bloqueo hasta que los bytes existan
+    (`readBlockTimeout`), `EstimatedSize` = bitrate×duración para que la barra del
+    player tenga timeline.
+  - Un **responder de Range manual** en /stream para fuentes no-finales (en vez de
+    `http.ServeContent`): leer `Range`, `ReadAt` la fuente, escribir 206 +
+    `Content-Range` con el tamaño estimado. El path mp4-completo (3a) sigue usando
+    ServeContent (rápido).
+  - Caveat: seek-adelante a zona no-remuxada bloquea hasta que el copy la alcanza
+    (copy es I/O-bound, rápido). Seek-atrás (bytes ya en disco) inmediato.
+  **Plan de incrementos seguros:**
+  - **3b-i (agente, dormido):** `remuxSource` + responder Range para fuentes
+    crecientes, gateado tras `PlayMethod=="remux"` (que el web aún no envía) →
+    commiteable sin romper nada, con tests.
+  - **3b-ii (web+player):** `decidePlayMethod` devuelve `"remux"` para
+    contenedor-no-mp4 + h264/aac/8-bit/SDR; player trata `playMethod != "hls"` igual
+    que direct (streamUrls + attach nativo). Activa 3b. Mismo gate de versión.
+  **Ficheros:** CLI `engine/stream_source.go` (remuxSource), `engine/stream_server.go`
+  (range responder + provider creciente), `cmd/daemon.go` (branch `remux`),
+  `engine/transcoder.go` (args `-c copy` fMP4). WEB `lib/stream/play-method.ts`
+  (+"remux"), `stream/session/route.ts`, `HlsStreamPlayer.tsx` (`!= "hls"`).
+
+  **CERRADO 2026-05-31:**
+  - CLI 3b-i (`feat/unarr-agent` 4a12f13): `GrowingSource` + `NewRemuxSource`
+    (reusa `transcodeSource`+`ActionRemux`, estimate = tamaño origen para copy);
+    `StreamServer.SetGrowingFile` + `serveGrowing` (responder Range manual: 206
+    con total estimado en `Content-Range`, body chunked mientras no-final, exact
+    `Content-Length` al finalizar, bloqueo vía `ReadAt`); branch `remux` en
+    `OnStreamSession`. Tests `parseByteRange`+`serveGrowing` (full/offset/bounded/
+    estimate/HEAD/416). build+vet+test verdes.
+  - WEB 3b-ii (`feat/unarr-brand` 10b7d602): `decidePlayMethod`→`"remux"` para
+    codecs compatibles en contenedor no-nativo; ruta gatea remux como direct
+    (versión, metadata, sin downscale, audioIndex -1); player trata `!= "hls"`
+    como attach nativo. lint+typecheck+2334 unit OK.
+  - **Smoke e2e (browser, mkv h264/aac 1080p):** `playMethod: remux`, `hlsUrls:
+    null`; agente `[stream …] remux (copy) → fMP4`; `/stream` HEAD 200 + GET Range
+    206 con fMP4 válido (`ftyp iso6 mp41`+`moov`); browser reproduce 1080p nativo,
+    duration leída del fMP4, **seek a 2min OK**, **0 reqs `/hls`**. ✓
+  - **Bug cazado por el smoke:** la respuesta `created` de la ruta quedó en
+    `playMethod === "direct" ? null` (en vez de `!== "hls"`) → devolvía `hlsUrls`
+    para remux. Corregido (el player usaba streamUrls igual, pero inconsistente).
+  - **Limitación:** seek-adelante a zona aún-no-remuxada bloquea hasta que el copy
+    (rápido) la alcanza; seek-atrás inmediato. Audio no-default / subs-bitmap →
+    siguen yendo por HLS (gate `audioIndex == -1`).
+
+- **Fase 3c — capability negotiation (device-profile).** El web envía
+  `{maxHeight, codecs:[h264,hevc,av1], containers}` (de UA + `canPlayType`).
+  `decidePlayMethod` se hace device-aware: p.ej. Safari/AppleTV que reproduce HEVC
+  nativo → passthrough HEVC en vez de transcode HEVC→h264. Reemplaza el heurístico
+  UA-burdo de `resolveAutoQuality`. Web+CLI.
+
+- **Fase 3d — ABR.** ABR multi-rendition real **DESCARTADA**: N pipelines ffmpeg
+  simultáneos = N× CPU para 1 espectador (mata NAS/Pi), y no aplica a los paths
+  copy (direct/remux = 1 bitrate). Resuelto como **3d-lite (auto-downshift)**:
+  el player ya tenía sondeo de ancho de banda + recomendación + selector manual;
+  3d-lite automatiza la bajada — buffering sostenido 10s → siguiente calidad menor
+  (nueva sesión a bitrate menor), progresivo hasta 480p. Reusa
+  `recommendLowerQuality`/`setQuality`. `setQuality(.., {persist:false})` para no
+  pisar la preferencia del usuario por un stall transitorio. **CERRADO (web 8bf8e416)**;
+  smoke en Chrome (Slow-3G + seek → consola `auto-downshift 720p → 480p`, nueva
+  sesión reproduce). Hallazgo: este Chrome reproduce HLS **nativo** (como Safari);
+  hls.js es fallback.
+
+**Ficheros a tocar (3a):** CLI `internal/agent/types.go` (+PlayMethod),
+`internal/cmd/daemon.go` (branch SetFile vs HLS). WEB
+`src/lib/services/agent-version-compare.ts` (gate), `src/lib/stream/play-method.ts`
+(nuevo), `src/lib/stream-token.ts` (scope stream), `src/lib/db/schema.ts` +
+migración (`streamingSession.play_method`), `src/app/api/internal/stream/session/route.ts`
+(decisión + URLs), `src/lib/services/agent.ts` (`getPendingStreamSessions` emite
+playMethod), `src/components/stream/HlsStreamPlayer.tsx` (attach nativo).
+
+**Seguridad de version-skew (3a):**
+- Web nuevo + agente viejo: gate `supportsDirectPlay` ve versión vieja → hls. ✓
+- Web viejo + agente nuevo: web nunca manda `direct` → agente hls. ✓
+- Campo `PlayMethod` desconocido en agente viejo = ignorado por el unmarshal. ✓
+
+**Empezar por 3a** (valor inmediato — el caso primario de unarr es la biblioteca
+local escaneada; mp4-h264-aac es común en web-dl/YIFY). 3b/3c/3d como iteraciones.
+
+**Hecho (Fase 3a CERRADA 2026-05-31):**
+- CLI (`feat/unarr-agent` c8d7c4b): `StreamSession.PlayMethod`; `OnStreamSession`
+  ramifica `direct` → `SetFile(NewDiskFileProvider)` + `MarkSessionReady` (sin
+  ffmpeg, antes del check de ffmpeg para funcionar con transcode off). `go build`
+  + `vet` + tests verdes.
+- WEB (`feat/unarr-brand` 636fbe59): `decidePlayMethod()` (espeja la rama
+  passthrough de Go, conservador) + test unitario; gate `supportsDirectPlay`
+  (`DIRECT_PLAY_MIN_VERSION = 0.10.0`); decisión en la ruta de sesión (solo
+  library item + sin downscale + `audioIndex == -1`); `buildStreamUrls` mintea
+  token scope `stream` (paridad Go); `streaming_session.play_method` (migración
+  0135) emitido al agente vía `getPendingStreamSessions`; player ramifica a
+  `<video src>` nativo. lint + typecheck:all + 2333 unit + build (brand unarr) OK.
+- Revisión adversarial (correctness + security/parity, 2 agentes): **0 hallazgos
+  bloqueantes**. Token parity y version-skew (ambos sentidos) confirmados.
+
+**Correcciones de la revisión propia (3a):** direct-play exige `audioIndex == -1`
+(servir el fichero entero no respeta una pista de audio no-default elegida por el
+usuario → esos casos van a HLS con `-map 0:a:N`).
+
+**Smoke e2e (3a) — PASADO 2026-05-31** (agente dev 0.10.0 build local + item de
+biblioteca mp4-h264-aac `/mnt/nas/peliculas/.../Tangled.Ever.After...mp4` + browser):
+- POST `/api/internal/stream/session` → `playMethod: direct`, `streamUrls` con
+  `/stream?t=` (token web scope `stream`), `hlsUrls: null`. ✓
+- Agente: `[stream …] direct-play: Tangled…mp4` (SetFile, sin ffmpeg). ✓
+- `/stream`: HEAD 200 `video/mp4` `Content-Length 128321419`; GET Range 0-1023 →
+  206 + bytes mp4 reales (`ftyp isom…avc1`). **Token web verificado por Go → paridad
+  cross-lenguaje confirmada en vivo** (sin token → 404). ✓
+- CORS desde origen browser (`localhost:3030`): ACAO correcto, preflight 204. ✓
+- Browser: `<video>.currentSrc` = `/stream?t=…` (NO `/hls`), `readyState 4`,
+  reproduciéndose, 1920×1080 nativo, **13 reqs `/stream`, 0 `/hls`**, attach
+  **nativo** (`[hls] (native) loadedmetadata`, sin hls.js). Telemetría
+  metric/progress OK. ✓
+
+**Bug pre-existente encontrado + arreglado durante el smoke** (web 764f5b01): el
+allow-list de la marca unarr (`src/lib/branding/routes.ts`) NO incluía
+`/api/internal/agent` ni `/api/internal/stream` → en unarr el agente daba 404 al
+registrar y el player 404 al crear sesión. **El streaming + agente de unarr estaban
+rotos de raíz.** Añadidos al allow-list (superficie del agente/media propio del
+usuario, cero superficie torrent).
+
+**Nota de release:** versión bumpeada a **0.10.0** (`version.go`, CLI 944d652) — solo
+binario local para el smoke, **sin publicar nada**. `DIRECT_PLAY_MIN_VERSION = 0.10.0`
+(web 52d958f0). Al publicar la release real del CLI, debe ser >= 0.10.0.
+
+**Backlog detectado en 3a (baja prioridad):**
+- `streaming_session.transport` queda `"hls"` también para sesiones direct
+  (el enum `TRANSPORT_VALUES` solo tiene `"hls"`); telemetría imprecisa, no bug.
+  Añadir `"direct"` al vocabulario cuando se toque la métrica.
+- Modelo single-viewer: dos plays direct simultáneos → el último `SetFile` gana;
+  el tab viejo reproduciría contenido nuevo en silencio (HLS al menos 404ea).
+- Direct-play no aplica `audioIndex` ni extrae subs a WebVTT (usa pistas
+  embebidas vía `<video>` nativo); subs bitmap no se ven. Aceptable en 3a.
+- Listener `loadedmetadata {once:true}` del attach nativo no se limpia
+  explícitamente en cleanup (idempotente, impacto nulo).
+
+**Fase 3c CERRADA 2026-05-31** (capability-negotiation, alcance ampliado):
+- CLI (`feat/unarr-agent` 957d499): `NewRemuxSource` copia el vídeo para cualquier
+  codec decodificable: h264, o HEVC/AV1 si el dispositivo lo declara. HEVC se muxea
+  con `-tag:v hvc1` (Apple lo exige). Audio no-aac (ac3/eac3/dts) se transcodifica a
+  aac copiando el vídeo (`ActionRemuxAudio`) → cubre el muy común **h264+ac3 mkv**.
+- WEB (`feat/unarr-brand` b0681d99): player sondea `canPlayType` (`detectDeviceCaps`)
+  y envía `{hevc,av1}` en el POST; `decidePlayMethod(p, caps)` device-aware:
+  HEVC/AV1 → `remux` solo si el dispositivo decodifica; audio no-aac ya no fuerza
+  `hls`. Tests caps actualizados (10).
+- **Smoke e2e:** caps gate (sin caps→`hls`, con caps→`remux`); h264+ac3 remux
+  reproduce en Chrome (audio transcodeado, vídeo copiado); retag verificado por
+  ffprobe (`codec_name=hevc`, `codec_tag_string=hvc1`); **HEVC reproduce en iPhone
+  Safari real (Tailscale) — confirmado por el usuario.** ✓
+- **Caveat:** playback HEVC en Apple no se puede smokear en este host (Chrome-Linux
+  no decodifica HEVC; Mac-mini Safari por SSH bloqueado por TCC: Automation +
+  Screen Recording necesitan click GUI). Verificado vía iPhone del usuario.
+
+**Diagnóstico time-to-first-frame (2026-05-31)** (instrumentación en 957d499:
+timers `probe`/`spawn`, `first fMP4 bytes after`, `serveGrowing blocked`):
+- Agente NO es el cuello: probe 16–98ms, spawn 1–194ms, primer byte fMP4 ~201ms,
+  **0 bloqueos** en `serveGrowing` (LAN ni remoto). Remux `-c copy` completo de un
+  fichero de ~780MB en ~16s (limitado por lectura NAS).
+- `moov` al frente (empty_moov OK) → el player no busca metadata al final.
+- Cliente (Chrome/LAN): POST→primer request ~480ms (sobre todo carga de página).
+- **1ª reproducción lenta = warm-up de red (Tailscale); 2ª/3ª rápidas** (confirmado
+  por el usuario). No es un problema de código.
+- Player YA da feedback (fases `loading-meta`/`probing-transport`/`playing` +
+  overlay "Preparando…" + spinner de buffering + mensaje stuck >10s). El "sin
+  feedback" del test fue por usar URL cruda (sin UI), no el flujo real.
+- **Conclusión:** sin optimización de código necesaria. Arranque garantizado-instante
+  = **hueco #4 (pre-transcode)**: dejar el remux/encode hecho antes del play.
+
+---
+
+### Hueco #4 — Pre-transcode (transcode-on-download)
+**Estado:** 🔵 DISEÑADO (2026-05-31), pendiente de implementar.
+
+**Qué es:** al completar una descarga (o import a biblioteca), procesar en
+background para que la reproducción sea **instantánea** sin transcode en vivo.
+Es una optimización: si no terminó cuando el usuario da play → fallback al
+transcode en vivo (HLS actual). **Nunca bloquea.**
+
+**Sinergia con lo existente (clave — gran parte de la infra ya está):**
+- `hls_cache.go`: un encode HLS completo se cachea y el cache-HIT lo sirve
+  instantáneo (cero ffmpeg). Pre-transcode = poblar esa cache antes del play.
+- `stream-prewarm.ts` + `createPrewarmSession`: ya lanza un encode HLS de la
+  siguiente ep en background. Pre-transcode = generalizar prewarm a "cualquier
+  download, configurable", + producir también el artefacto direct-play (3a).
+- Por tanto el trabajo NUEVO es: (1) disparador on-download-complete, (2)
+  superficie de config en web, (3) gobernanza de recursos + cola, (4) decisión
+  "qué producir" (remux mp4 para 3a vs HLS cache vs nada si ya es native).
+
+**Opciones a exponer en la web (set propuesto):**
+
+1. **Activación + disparador**
+   - Toggle global on/off (default OFF — CPU/disco intensivo).
+   - Disparador: al completar descarga / al escanear-importar / manual
+     ("optimizar ahora" por item) / programado (ventana horaria).
+   - Default recomendado: on-download-complete, pero solo en ventana idle + sin
+     stream en vivo activo.
+
+2. **Qué producir (target) — modo Auto recomendado (por probe):**
+   - ya browser-native (mp4 h264/aac 8-bit SDR) → **nada** (3a lo sirve crudo).
+   - solo contenedor incompatible (mkv h264/aac) → **remux** a mp4 (barato, sin
+     re-encode; habilita 3a direct-play). *(necesita 3b para el manifiesto.)*
+   - codec incompatible (HEVC/AV1/10-bit/HDR) → **transcode** a H.264 (caro).
+   - Modos: solo-remux / remux+transcode / forzar H.264 universal.
+   - Formato salida: mp4 direct-play (seek nativo) vs HLS cache (multi-network)
+     vs ambos. Recomendado: mp4 si compatible, HLS si requiere transcode.
+
+3. **Calidad**
+   - Mantener original (passthrough cuando se pueda) / cap 1080p / ladder ABR
+     (480/720/1080/original — encaja con 3d).
+   - "Solo transcodear si ayuda" (no tocar lo ya compatible).
+
+4. **Selección / alcance**
+   - Todo / solo biblioteca (pelis+series) / solo lo problemático (p.ej. solo
+     4K HEVC, dejar h264).
+   - Solo watchlist / recién añadido / todo. Reglas por carpeta de biblioteca.
+
+5. **Gobernanza de recursos (lo más importante — es pesado):**
+   - Concurrencia (N transcodes paralelos, default 1).
+   - HW accel si disponible (nvenc/qsv/vaapi); cap de threads CPU.
+   - Ventana horaria (solo idle, p.ej. 02:00–08:00).
+   - **Pausar cuando hay stream en vivo** (no pelear por CPU con la reproducción).
+   - Prioridad de cola (watchlist primero / más pequeño primero / más nuevo).
+   - (Laptops) solo con AC / no en batería.
+
+6. **Disco / retención (liga con el hueco medio de espacio en disco):**
+   - Dónde guardar (cache dir) + tamaño máx + evicción LRU (ya parcial en cache).
+   - Mantener SIEMPRE el original; el transcode es artefacto adicional.
+   - TTL: borrar pre-transcode no visto en N días; pin a visto/favorito.
+   - Re-transcodear al cambiar la config de calidad (invalidación).
+
+7. **UX / estado**
+   - Cola + progreso por item en la web ("Optimizando para reproducción
+     instantánea…"). Badge en library card: "listo para play instantáneo" vs
+     "se transcodificará al reproducir". Notificación al terminar (opcional).
+
+8. **Fallback / límites**
+   - Si no terminó a tiempo → transcode en vivo (HLS). Nunca bloquea el play.
+   - Solo ficheros locales en disco (no debrid/torrent sin bajar).
+
+**MVP recomendado (fase 4a):** toggle on/off + disparador on-download-complete +
+modo Auto (remux-si-compatible / transcode-si-no) + concurrencia 1 +
+pausar-si-stream-activo + reusar `hls_cache` + badge "listo". El resto (ladder
+ABR, ventanas horarias, reglas por carpeta, TTL avanzado, formato mp4 vs HLS
+configurable) en fases 4b/4c.
+
+**Dependencias:** el camino mp4/remux depende del hueco #3 (3a ya hecho; 3b para
+el remux-a-mp4 con manifiesto correcto). El camino HLS-cache es implementable ya
+(reusa cache + prewarm). La gobernanza (pausar-si-stream) necesita señal de
+"stream activo" en el daemon (la hay: `streamSrv.HasFile()` + registro HLS).

internal/agent/client.go

@@ -130,6 +130,27 @@ func (c *Client) MarkSessionReady(ctx context.Context, sessionID string) error {
 	return nil
 }
 
+// RefreshStreamURL re-resolves a fresh debrid direct URL for a live streaming
+// session (hueco #2 / 2c). Called by the daemon when a debrid source expires
+// mid-stream (the link is time-limited; the content is still cached). Returns
+// the new URL on success; an error (incl. 409/410) means refresh isn't
+// possible and the caller should stop trying.
+func (c *Client) RefreshStreamURL(ctx context.Context, sessionID string) (string, error) {
+	req := struct {
+		SessionID string `json:"sessionId"`
+	}{SessionID: sessionID}
+	var resp struct {
+		DirectURL string `json:"directUrl"`
+	}
+	if err := c.doPost(ctx, "/api/internal/agent/stream-url", req, &resp); err != nil {
+		return "", fmt.Errorf("refresh stream url: %w", err)
+	}
+	if resp.DirectURL == "" {
+		return "", fmt.Errorf("refresh stream url: empty url in response")
+	}
+	return resp.DirectURL, nil
+}
+
 // ReportStatus reports download progress. Returns server-side flags the CLI must act on.
 func (c *Client) ReportStatus(ctx context.Context, update StatusUpdate) (*StatusResponse, error) {
 	var resp StatusResponse

internal/agent/daemon.go

@@ -22,6 +22,7 @@ type DaemonConfig struct {
 	Version            string
 	DownloadDir        string
 	StreamPort         int      // port for the HTTP stream server
+	StreamSecret       string   // hex HMAC key for stream tokens (reported so the web can mint HLS tokens)
 	LanIP              string   // LAN IP (reported in sync for stream URL resolution)
 	TailscaleIP        string   // Tailscale IP (reported in sync for stream URL resolution)
 	CanDelete          bool     // library.allow_delete is enabled
@@ -109,6 +110,13 @@ func (d *Daemon) SetFunnelURL(url string) {
 	WriteState(&d.State)
 }
 
+// UpdateStreamSecret sets the hex HMAC key reported on register so the web can
+// mint HLS stream tokens the agent will accept.
+func (d *Daemon) UpdateStreamSecret(secretHex string) {
+	d.cfg.StreamSecret = secretHex
+	d.sync.cfg.StreamSecret = secretHex
+}
+
 // UpdateStreamPort updates the stream port reported in sync requests.
 func (d *Daemon) UpdateStreamPort(port int) {
 	d.cfg.StreamPort = port
@@ -126,6 +134,7 @@ func (d *Daemon) Register(ctx context.Context) error {
 		Version:            d.cfg.Version,
 		DownloadDir:        d.cfg.DownloadDir,
 		StreamPort:         d.cfg.StreamPort,
+		StreamSecret:       d.cfg.StreamSecret,
 		LanIP:              d.cfg.LanIP,
 		TailscaleIP:        d.cfg.TailscaleIP,
 		HWAccel:            d.cfg.HWAccel,

internal/agent/types.go

@@ -18,6 +18,11 @@ type RegisterRequest struct {
 	StreamPort     int    `json:"streamPort,omitempty"`
 	LanIP          string `json:"lanIp,omitempty"`
 	TailscaleIP    string `json:"tailscaleIp,omitempty"`
+	// StreamSecret is the daemon's per-run HMAC key (hex) for stream tokens. The
+	// web mints the HLS path token with it (the agent mints /stream tokens on its
+	// own URLs); the agent verifies both. In memory, regenerated each start, so a
+	// fresh register after restart re-syncs it.
+	StreamSecret string `json:"streamSecret,omitempty"`
 	// Transcode capabilities — let the web side suggest a smarter quality
 	// before the player even starts. HWAccel is the picked backend
 	// ("nvenc"/"qsv"/"vaapi"/"videotoolbox"/"none"). MaxTranscodeHeight is
@@ -405,6 +410,22 @@ type StreamSession struct {
 	// AudioIndex selects the source audio track (-map 0:a:N). -1 means
 	// "use the default/first track".
 	AudioIndex int `json:"audioIndex,omitempty"`
+	// PlayMethod is how the daemon should serve this session:
+	//   ""       — default (HLS transcode); also what legacy servers send.
+	//   "direct" — the source is already browser-native (the web decided this
+	//              from library scan metadata + an agent-version gate). Serve
+	//              the raw file over /stream (HTTP Range, no ffmpeg) instead of
+	//              transcoding to HLS. See hueco #3 phase 3a in the roadmap.
+	PlayMethod string `json:"playMethod,omitempty"`
+	// DirectURL, when set, is an HTTPS link to the media resolved server-side
+	// from the user's debrid account (hueco #2 / 2a). The source has no local
+	// file: the daemon streams /stream from this URL via ranged GETs
+	// (debridFileProvider) instead of from disk/torrent. Carries the "play
+	// instantáneo cache-fast" promise — the web only sets it when the hash is
+	// confirmed debrid-cached and the container is browser-native (mp4/m4v),
+	// and gates it on an agent-version floor so older daemons never receive a
+	// field they can't serve. Takes priority over FilePath when present.
+	DirectURL string `json:"directUrl,omitempty"`
 }
 
 // SyncResponse is returned by the server with all pending actions for the CLI.

internal/cmd/daemon.go

@@ -310,6 +310,14 @@ func runDaemonStart() error {
 	// Create persistent stream server
 	streamSrv := engine.NewStreamServer(cfg.Download.StreamPort)
 	streamSrv.SetUPnPEnabled(cfg.Download.EnableUPnP)
+	streamSrv.SetRequireStreamToken(cfg.Download.RequireStreamToken)
+	// Report the stream-token signing key ONLY when enforcing, so the web's
+	// "secret present → mint HLS token" signal accurately means "this agent
+	// verifies tokens". Reporting it with enforcement off would make the web
+	// mint HLS path tokens the agent never peels → 404. Set before Register().
+	if cfg.Download.RequireStreamToken {
+		d.UpdateStreamSecret(streamSrv.StreamSecretHex())
+	}
 	// CORS extras = operator config + dynamic mirror list from /api/mirrors.
 	// Without the mirror merge, a user playing from `torrentclaw.to` (or any
 	// future mirror) hits the daemon, gets 200 + body, but no
@@ -558,6 +566,96 @@ func runDaemonStart() error {
 		if playerSessionRegistry.has(sess.SessionID) {
 			return // already running
 		}
+
+		// startHLSPlayback starts an HLS encode (local file or debrid URL) and
+		// wires it into the StreamServer. Shared by the local-file HLS path and
+		// the debrid HLS-from-URL path (hueco #2 / 2b) so both register, probe
+		// off the sync loop, and report readiness identically.
+		startHLSPlayback := func(hlsCfg engine.HLSSessionConfig, hlsCtx context.Context, hlsCancel context.CancelFunc) {
+			playerSessionRegistry.add(hlsCfg.SessionID, hlsCancel)
+			go func() {
+				hsess, err := engine.StartHLSSession(hlsCtx, hlsCfg)
+				if err != nil {
+					playerSessionRegistry.remove(hlsCfg.SessionID)
+					hlsCancel()
+					log.Printf("[hls %s] start failed: %v", agent.ShortID(hlsCfg.SessionID), err)
+					return
+				}
+				streamSrv.HLS().Register(hsess)
+				go watchSessionReady(hlsCtx, agentClient, hsess, hlsCfg.SessionID)
+			}()
+		}
+
+		// Debrid direct-play (hueco #2 / 2a): the source has no local file — the
+		// web resolved an HTTPS debrid link (cache-confirmed, browser-native
+		// container) and the daemon streams /stream from it via ranged GETs.
+		// Runs BEFORE the filePath checks (there is no local path) and needs no
+		// ffmpeg. PlayMethod != "hls" distinguishes this from the debrid
+		// HLS-from-URL branch below (a non-native container the web wants
+		// transcoded). Provider setup does a HEAD, so hand it off to a goroutine
+		// to keep the sync loop from blocking other pending actions; register the
+		// session up front so a duplicate sync within the setup window is a
+		// no-op (matches the HLS branch's handoff rationale).
+		if sess.DirectURL != "" && sess.PlayMethod != "hls" {
+			playerSessionRegistry.add(sess.SessionID, func() { streamSrv.ClearFile() })
+			// refresh re-resolves a fresh debrid link when this one expires
+			// mid-stream (hueco #2 / 2c). Bound to the daemon ctx so a shutdown
+			// cancels an in-flight refresh.
+			refresh := func(rctx context.Context) (string, error) {
+				return agentClient.RefreshStreamURL(rctx, sess.SessionID)
+			}
+			go func() {
+				bctx, cancel := context.WithTimeout(ctx, 15*time.Second)
+				defer cancel()
+				provider, perr := engine.NewDebridFileProvider(bctx, sess.DirectURL, sess.FileName, sess.FileSize, refresh)
+				if perr != nil {
+					playerSessionRegistry.remove(sess.SessionID)
+					log.Printf("[stream %s] debrid provider failed: %v", agent.ShortID(sess.SessionID), perr)
+					return
+				}
+				streamSrv.SetFile(provider, sess.TaskID)
+				log.Printf("[stream %s] debrid direct-play: %s (%d bytes)",
+					agent.ShortID(sess.SessionID), provider.FileName(), provider.FileSize())
+				rctx, rcancel := context.WithTimeout(ctx, 10*time.Second)
+				defer rcancel()
+				if err := agentClient.MarkSessionReady(rctx, sess.SessionID); err != nil {
+					log.Printf("[stream %s] mark-ready failed: %v", agent.ShortID(sess.SessionID), err)
+				}
+			}()
+			return
+		}
+
+		// Debrid HLS-from-URL (hueco #2 / 2b): the source is debrid-cached but
+		// NOT browser-native (mkv/HEVC/…), so the web set playMethod="hls"
+		// alongside the DirectURL. ffmpeg transcodes straight from the HTTP URL —
+		// no local file, no torrent. Cache is keyed by info_hash (not the
+		// per-resolution URL) so a re-play hits the segment cache.
+		if sess.DirectURL != "" { // playMethod == "hls" implied (2a returned above)
+			tcRuntime := buildTranscodeRuntime(ctx, cfg)
+			if tcRuntime.FFmpegPath == "" || tcRuntime.FFprobePath == "" {
+				log.Printf("[hls %s] rejected: ffmpeg/ffprobe unavailable (debrid HLS)", agent.ShortID(sess.SessionID))
+				return
+			}
+			hlsCtx, hlsCancel := context.WithCancel(ctx)
+			startHLSPlayback(engine.HLSSessionConfig{
+				SessionID:  sess.SessionID,
+				SourceURL:  sess.DirectURL,
+				CacheID:    sess.InfoHash,
+				FileName:   sess.FileName,
+				Quality:    sess.Quality,
+				AudioIndex: sess.AudioIndex,
+				Transcode:  tcRuntime,
+				Cache:      hlsCache,
+				// 2c: refresh the debrid link if it expires mid-transcode; the
+				// auto-restart supervisor calls this before relaunching ffmpeg.
+				RefreshURL: func(rctx context.Context) (string, error) {
+					return agentClient.RefreshStreamURL(rctx, sess.SessionID)
+				},
+			}, hlsCtx, hlsCancel)
+			log.Printf("[hls %s] debrid HLS-from-URL: %s", agent.ShortID(sess.SessionID), sess.FileName)
+			return
+		}
+
 		filePath := sess.FilePath
 		if filePath == "" {
 			log.Printf("[hls %s] rejected: empty file path", agent.ShortID(sess.SessionID))
@@ -581,14 +679,84 @@ func runDaemonStart() error {
 			filePath = found
 		}
 
+		// Direct-play (hueco #3 / 3a): the web decided this source is already
+		// browser-native (mp4 h264/aac 8-bit SDR) from library scan metadata,
+		// gated on agent version. Serve the raw file over /stream (HTTP Range,
+		// no ffmpeg) instead of transcoding to HLS — zero CPU, instant seek.
+		// Runs BEFORE the ffmpeg-availability check on purpose: direct-play
+		// needs no ffmpeg, so it must work even when transcode is disabled.
+		if sess.PlayMethod == "direct" {
+			streamSrv.SetFile(engine.NewDiskFileProvider(filePath), sess.TaskID)
+			// cancel just clears the served file so daemon shutdown / drain
+			// stops exposing it on /stream. There's no ffmpeg child to kill.
+			playerSessionRegistry.add(sess.SessionID, func() { streamSrv.ClearFile() })
+			log.Printf("[stream %s] direct-play: %s", agent.ShortID(sess.SessionID), filepath.Base(filePath))
+			// File is on disk → ready immediately. Tell the web so the player
+			// attaches <video src> without burning its HEAD-probe retry budget.
+			go func() {
+				rctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+				defer cancel()
+				if err := agentClient.MarkSessionReady(rctx, sess.SessionID); err != nil {
+					log.Printf("[stream %s] mark-ready failed: %v", agent.ShortID(sess.SessionID), err)
+				}
+			}()
+			return
+		}
+
 		tcRuntime := buildTranscodeRuntime(ctx, cfg)
 		if tcRuntime.FFmpegPath == "" || tcRuntime.FFprobePath == "" {
 			log.Printf("[hls %s] rejected: ffmpeg/ffprobe unavailable", agent.ShortID(sess.SessionID))
 			return
 		}
+
+		// Remux path (hueco #3 / 3b): codecs are browser-native (h264/aac) but
+		// the container isn't (mkv). ffmpeg `-c copy` → growing fMP4 served raw
+		// over /stream — no video re-encode, no HLS. The web decided this from
+		// scan metadata + version gate; we still need ffmpeg (copy uses it).
+		if sess.PlayMethod == "remux" {
+			tStart := time.Now()
+			probeCtx, cancelProbe := context.WithTimeout(ctx, 15*time.Second)
+			probe, perr := engine.ProbeFile(probeCtx, tcRuntime.FFprobePath, filePath)
+			cancelProbe()
+			if perr != nil {
+				log.Printf("[stream %s] remux probe failed: %v", agent.ShortID(sess.SessionID), perr)
+				return
+			}
+			tProbe := time.Now()
+			remuxCtx, remuxCancel := context.WithCancel(ctx)
+			src, serr := engine.NewRemuxSource(remuxCtx, filePath, probe, tcRuntime.FFmpegPath, sess.FileName)
+			if serr != nil {
+				remuxCancel()
+				log.Printf("[stream %s] remux start failed: %v", agent.ShortID(sess.SessionID), serr)
+				return
+			}
+			streamSrv.SetGrowingFile(src, sess.TaskID)
+			// cancel stops the ffmpeg copy; SetGrowingFile/ClearFile also Close()
+			// the source, so the temp file is always cleaned up.
+			playerSessionRegistry.add(sess.SessionID, func() { remuxCancel(); streamSrv.ClearFile() })
+			// Startup timing (TTFF diagnosis): probe = ffprobe on the source;
+			// spawn = ffmpeg launch + tmp setup. First-fMP4-byte is logged by the
+			// source itself; serveGrowing logs any client read that blocks waiting
+			// for ffmpeg to catch up.
+			log.Printf("[stream %s] remux (copy) → fMP4: %s [probe=%v spawn=%v]",
+				agent.ShortID(sess.SessionID), filepath.Base(filePath),
+				tProbe.Sub(tStart).Round(time.Millisecond), time.Since(tProbe).Round(time.Millisecond))
+			go func() {
+				rctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+				defer cancel()
+				if err := agentClient.MarkSessionReady(rctx, sess.SessionID); err != nil {
+					log.Printf("[stream %s] mark-ready failed: %v", agent.ShortID(sess.SessionID), err)
+				}
+			}()
+			return
+		}
+
+		// Local-file HLS (the original path). StartHLSSession runs ffprobe
+		// (15 s cap) inside startHLSPlayback's goroutine so the sync loop
+		// returns immediately — browser HEAD probes have a 30 s retry budget
+		// that absorbs the gap until the playlist registers.
 		hlsCtx, hlsCancel := context.WithCancel(ctx)
-		playerSessionRegistry.add(sess.SessionID, hlsCancel)
-		hlsCfg := engine.HLSSessionConfig{
+		startHLSPlayback(engine.HLSSessionConfig{
 			SessionID:  sess.SessionID,
 			SourcePath: filePath,
 			FileName:   sess.FileName,
@@ -596,29 +764,7 @@ func runDaemonStart() error {
 			AudioIndex: sess.AudioIndex,
 			Transcode:  tcRuntime,
 			Cache:      hlsCache,
-		}
-		// StartHLSSession runs ffprobe (15 s cap, typical 0.3–1 s) before
-		// returning. Doing this synchronously inside the sync handler holds
-		// the next sync HTTP cycle until ffprobe is done, so any other
-		// pending actions (new tasks, deletes) wait too. Hand it off so
-		// the sync loop returns immediately — browser HEAD probes already
-		// have a 30 s retry budget that absorbs the gap until
-		// `streamSrv.HLS().Register` lands.
-		go func() {
-			hsess, err := engine.StartHLSSession(hlsCtx, hlsCfg)
-			if err != nil {
-				playerSessionRegistry.remove(sess.SessionID)
-				hlsCancel()
-				log.Printf("[hls %s] start failed: %v", agent.ShortID(sess.SessionID), err)
-				return
-			}
-			streamSrv.HLS().Register(hsess)
-			// Tell the server seg-0 is on disk as soon as it lands so the
-			// player's SSE subscription flips its "Preparando…" UI without
-			// waiting for the browser HEAD-probe loop to discover it
-			// independently. Cache-HIT sessions are ready immediately.
-			go watchSessionReady(hlsCtx, agentClient, hsess, sess.SessionID)
-		}()
+		}, hlsCtx, hlsCancel)
 	}
 
 	// Periodic DHT node persistence (every 5 min)

internal/cmd/version.go

@@ -1,4 +1,4 @@
 package cmd
 
 // Version is the CLI version. Overridden by goreleaser ldflags at release time.
-var Version = "0.9.19"
+var Version = "0.12.0"

internal/config/config.go

@@ -39,22 +39,27 @@ type AgentConfig struct {
 }
 
 type DownloadConfig struct {
-	Dir              string          `toml:"dir"`
-	PreferredMethod  string          `toml:"preferred_method"`
-	PreferredQuality string          `toml:"preferred_quality"` // "2160p", "1080p", "720p" — hint for auto-selection
-	MaxConcurrent    int             `toml:"max_concurrent"`
-	MaxDownloadSpeed string          `toml:"max_download_speed"` // e.g. "10MB", "500KB", "0" = unlimited
-	MaxUploadSpeed   string          `toml:"max_upload_speed"`   // e.g. "1MB", "0" = unlimited
-	MetadataTimeout  string          `toml:"metadata_timeout"`   // e.g. "1h", "30m", "0" = unlimited (default: "0")
-	StallTimeout     string          `toml:"stall_timeout"`      // e.g. "30m", "1h", "0" = unlimited (default: "30m")
-	ListenPort       int             `toml:"listen_port"`        // fixed port for incoming peer connections (default: 42069, 0 = random)
-	StreamPort       int             `toml:"stream_port"`        // fixed port for streaming HTTP server (default: 11818)
-	EnableUPnP       bool            `toml:"enable_upnp"`        // map StreamPort to the WAN via UPnP/NAT-PMP (default: false; opt-in because it exposes the unauthenticated /stream + /hls endpoints to the public internet)
-	CORSExtraOrigins []string        `toml:"cors_extra_origins"` // extra browser origins added on top of the baked-in allowlist (torrentclaw.com, app.torrentclaw.com, localhost:3030)
-	Transcode        TranscodeConfig `toml:"transcode"`
-	HLSCache         HLSCacheConfig  `toml:"hls_cache"`
-	VPN              VPNConfig       `toml:"vpn"`
-	Funnel           FunnelConfig    `toml:"funnel"`
+	Dir              string `toml:"dir"`
+	PreferredMethod  string `toml:"preferred_method"`
+	PreferredQuality string `toml:"preferred_quality"` // "2160p", "1080p", "720p" — hint for auto-selection
+	MaxConcurrent    int    `toml:"max_concurrent"`
+	MaxDownloadSpeed string `toml:"max_download_speed"` // e.g. "10MB", "500KB", "0" = unlimited
+	MaxUploadSpeed   string `toml:"max_upload_speed"`   // e.g. "1MB", "0" = unlimited
+	MetadataTimeout  string `toml:"metadata_timeout"`   // e.g. "1h", "30m", "0" = unlimited (default: "0")
+	StallTimeout     string `toml:"stall_timeout"`      // e.g. "30m", "1h", "0" = unlimited (default: "30m")
+	ListenPort       int    `toml:"listen_port"`        // fixed port for incoming peer connections (default: 42069, 0 = random)
+	StreamPort       int    `toml:"stream_port"`        // fixed port for streaming HTTP server (default: 11818)
+	EnableUPnP       bool   `toml:"enable_upnp"`        // map StreamPort to the WAN via UPnP/NAT-PMP (default: false; opt-in)
+	// RequireStreamToken gates remote (non-loopback) /stream + /hls requests on a
+	// signed, short-lived token embedded in the URLs the agent reports. Default
+	// true (secure by default); loopback callers (local mpv/vlc) are always exempt.
+	// Set false only to debug a player that can't carry the token.
+	RequireStreamToken bool            `toml:"require_stream_token"`
+	CORSExtraOrigins   []string        `toml:"cors_extra_origins"` // extra browser origins added on top of the baked-in allowlist (torrentclaw.com, app.torrentclaw.com, localhost:3030)
+	Transcode          TranscodeConfig `toml:"transcode"`
+	HLSCache           HLSCacheConfig  `toml:"hls_cache"`
+	VPN                VPNConfig       `toml:"vpn"`
+	Funnel             FunnelConfig    `toml:"funnel"`
 }
 
 // HLSCacheConfig controls the persistent HLS segment cache. A completed encode
@@ -63,9 +68,9 @@ type DownloadConfig struct {
 // size budget. Enabled by default — disable to save disk space at the cost of
 // re-encoding every play.
 type HLSCacheConfig struct {
-	Enabled bool   `toml:"enabled"`  // default: true
-	SizeGB  int    `toml:"size_gb"`  // size budget in gigabytes; default: 5; minimum: 1
-	Dir     string `toml:"dir"`      // override storage path; default: ~/.cache/unarr/hls-cache
+	Enabled bool   `toml:"enabled"` // default: true
+	SizeGB  int    `toml:"size_gb"` // size budget in gigabytes; default: 5; minimum: 1
+	Dir     string `toml:"dir"`     // override storage path; default: ~/.cache/unarr/hls-cache
 }
 
 // FunnelConfig gates the optional CloudFlare Quick Tunnel that exposes the
@@ -188,12 +193,13 @@ func Default() Config {
 			},
 		},
 		Download: DownloadConfig{
-			PreferredMethod: "auto",
-			MaxConcurrent:   3,
-			StreamPort:      11818,
+			PreferredMethod:    "auto",
+			MaxConcurrent:      3,
+			StreamPort:         11818,
+			RequireStreamToken: true, // secure by default; loopback exempt
 			Transcode: TranscodeConfig{
-				Enabled:       true,
-				HWAccel:       "auto",
+				Enabled: true,
+				HWAccel: "auto",
 				// Empty preset → engine.ResolveEncoderProfile picks the
 				// latency-biased default ("superfast" on libx264). Override
 				// in config.toml when quality > first-start latency matters.

internal/engine/hls.go

@@ -130,8 +130,23 @@ func CleanupHLSOrphanDirs() error {
 
 // HLSSessionConfig describes a single browser playback session driven by HLS.
 type HLSSessionConfig struct {
-	SessionID  string
+	SessionID string
+	// Exactly one of SourcePath / SourceURL identifies the input. SourcePath is
+	// a local file; SourceURL is a remote HTTP(S) URL ffmpeg reads directly
+	// (hueco #2 / 2b — transcoding a debrid source that isn't browser-native).
 	SourcePath string
+	// SourceURL, when set, is fed to ffmpeg/ffprobe as the input (-i <url>) with
+	// network-resilience flags. Takes priority over SourcePath.
+	SourceURL string
+	// CacheID overrides the cache key identity. Empty → key by SourcePath (local
+	// files). Set to a stable id (the torrent info_hash) for SourceURL sessions
+	// so re-plays cache-hit even though the debrid URL changes each resolution.
+	CacheID string
+	// RefreshURL, when set (debrid URL sessions only), re-resolves a fresh
+	// SourceURL when the current link expires mid-transcode (hueco #2 / 2c).
+	// The auto-restart supervisor calls it before relaunching ffmpeg so the
+	// restart uses a live link instead of retrying the dead one. nil = no refresh.
+	RefreshURL func(context.Context) (string, error)
 	FileName   string
 	Quality    string // "2160p"|"1080p"|"720p"|"480p"|"original"|""
 	AudioIndex int    // 0-based ffmpeg audio stream selection (-map 0:a:N). -1 = default.
@@ -143,6 +158,29 @@ type HLSSessionConfig struct {
 	Cache *HLSCache
 }
 
+// sourceRef returns the ffmpeg/ffprobe input: the remote URL when set, else the
+// local path. Used everywhere a `-i` argument or a probe target is needed so
+// the local-file and debrid-URL paths share one code path.
+func (cfg HLSSessionConfig) sourceRef() string {
+	if cfg.SourceURL != "" {
+		return cfg.SourceURL
+	}
+	return cfg.SourcePath
+}
+
+// logName is a short, log-friendly source label. For local files it's the base
+// name; for a URL source (no SourcePath) it prefers FileName over the raw URL
+// (which would leak a query-string token into the logs).
+func (cfg HLSSessionConfig) logName() string {
+	if cfg.SourcePath != "" {
+		return filepath.Base(cfg.SourcePath)
+	}
+	if cfg.FileName != "" {
+		return cfg.FileName
+	}
+	return "debrid-url"
+}
+
 // HLSSession owns a tmpdir + ffmpeg subprocess producing HLS fragments.
 //
 // Seek behaviour: ffmpeg writes segments sequentially from `ffmpegSegStart`.
@@ -171,6 +209,13 @@ type HLSSession struct {
 	ffmpegSegStart int // index of the first segment the current ffmpeg writes
 	restartCount   int // bounded auto-restart counter (resets on Close)
 	lastRestartAt  time.Time
+	// liveURL is the mutable debrid source URL (hueco #2 / 2c). Initialised to
+	// cfg.SourceURL; refreshed in place by waitFFmpeg when the link expires.
+	// Guarded by mu because restartFromSegment reads it from BOTH the supervisor
+	// goroutine (auto-restart) AND the HTTP handler goroutine (seek-restart),
+	// while waitFFmpeg writes it. Empty for local-file sessions. cfg itself is
+	// treated as immutable after construction so copying it stays race-free.
+	liveURL string
 
 	// readyCh + readyMax track how many segments ffmpeg has finished writing.
 	// readyMax is a COUNT (not an index): readyMax=N means seg-0 … seg-(N-1)
@@ -298,8 +343,8 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 	if !validSessionID.MatchString(cfg.SessionID) {
 		return nil, errors.New("hls: invalid session id")
 	}
-	if cfg.SourcePath == "" {
-		return nil, errors.New("hls: empty source path")
+	if cfg.SourcePath == "" && cfg.SourceURL == "" {
+		return nil, errors.New("hls: no source (neither path nor URL)")
 	}
 	if cfg.Transcode.FFmpegPath == "" || cfg.Transcode.FFprobePath == "" {
 		return nil, errors.New("hls: ffmpeg/ffprobe not available")
@@ -310,7 +355,7 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 	// the goroutine that started the session forever and the user would
 	// see the player phase stuck on "Preparando sesión".
 	probeCtx, cancelProbe := context.WithTimeout(ctx, 15*time.Second)
-	probe, err := ProbeFile(probeCtx, cfg.Transcode.FFprobePath, cfg.SourcePath)
+	probe, err := ProbeFile(probeCtx, cfg.Transcode.FFprobePath, cfg.sourceRef())
 	cancelProbe()
 	if err != nil {
 		return nil, fmt.Errorf("hls: probe: %w", err)
@@ -334,7 +379,13 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 		writerLockHeld bool
 	)
 	if cfg.Cache != nil {
-		cacheKey = cfg.Cache.KeyFor(cfg.SourcePath, cfg.Quality, cfg.AudioIndex)
+		// Debrid URL sessions key by CacheID (info_hash) so re-plays hit cache
+		// despite the URL changing each resolution; local files key by path.
+		if cfg.CacheID != "" {
+			cacheKey = cfg.Cache.KeyForID(cfg.CacheID, cfg.Quality, cfg.AudioIndex)
+		} else {
+			cacheKey = cfg.Cache.KeyFor(cfg.SourcePath, cfg.Quality, cfg.AudioIndex)
+		}
 		// Integrity gate: HasComplete just stats the marker. If init.mp4 or
 		// the last segment vanished (external rm, partial-disk failure), we
 		// can't actually serve a HIT — drop the dir and re-encode.
@@ -393,18 +444,19 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 	segCount := segmentCountForDuration(probe.DurationSec)
 
 	s := &HLSSession{
-		cfg:          cfg,
-		probe:        probe,
-		tmpDir:       tmpDir,
-		durationSec:  probe.DurationSec,
-		segmentCount: segCount,
-		startedAt:    time.Now(),
-		lastTouch:    time.Now(),
-		readyCh:      make(chan struct{}),
+		cfg:            cfg,
+		probe:          probe,
+		tmpDir:         tmpDir,
+		durationSec:    probe.DurationSec,
+		segmentCount:   segCount,
+		startedAt:      time.Now(),
+		lastTouch:      time.Now(),
+		readyCh:        make(chan struct{}),
 		cache:          cfg.Cache,
 		cacheKey:       cacheKey,
 		fromCache:      fromCache,
 		writerLockHeld: writerLockHeld,
+		liveURL:        cfg.SourceURL, // mutable copy; cfg stays immutable
 	}
 	s.manifestVideo = renderVideoPlaylist(probe.DurationSec, segCount)
 	s.manifestRoot = renderMasterPlaylist(probe, cfg.Quality)
@@ -420,7 +472,7 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 		s.readyCh = nil
 		s.readyMu.Unlock()
 		log.Printf("[hls %s] cache HIT %s: %s, %.1fs, %d segs (quality=%s)",
-			shortHLSID(cfg.SessionID), cacheKey, filepath.Base(cfg.SourcePath),
+			shortHLSID(cfg.SessionID), cacheKey, cfg.logName(),
 			probe.DurationSec, segCount, coalesce(cfg.Quality, "auto"))
 		return s, nil
 	}
@@ -444,9 +496,14 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 
 	if len(probe.SubtitleTracks) > 0 {
 		s.subsDone = make(chan struct{})
+		// Capture the source ref now (by value): subs are extracted once at
+		// startup, and a later URL refresh (2c) mutates s.cfg.SourceURL from the
+		// waitFFmpeg goroutine — passing the URL in keeps extractSubtitles from
+		// racing that write.
+		subSrc := cfg.sourceRef()
 		go func() {
 			defer close(s.subsDone)
-			s.extractSubtitles(ffCtx)
+			s.extractSubtitles(ffCtx, subSrc)
 		}()
 	}
 
@@ -464,7 +521,7 @@ func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, er
 		presetNote = " preset=" + profile.Preset
 	}
 	log.Printf("[hls %s] started: %s, %.1fs, %d segs (quality=%s, encoder=%s accel=%s%s)%s",
-		shortHLSID(cfg.SessionID), filepath.Base(cfg.SourcePath),
+		shortHLSID(cfg.SessionID), cfg.logName(),
 		probe.DurationSec, segCount, coalesce(cfg.Quality, "auto"),
 		profile.Codec, string(cfg.Transcode.HWAccel), presetNote, cachedNote)
 	return s, nil
@@ -711,6 +768,26 @@ func (s *HLSSession) waitFFmpeg() {
 	s.lastRestartAt = time.Now()
 	s.mu.Unlock()
 
+	// Debrid URL session (hueco #2 / 2c): the likeliest cause of an ffmpeg
+	// network exit is the debrid link expiring. Re-resolve a fresh one before
+	// restarting, else the restart just retries the dead URL and burns the
+	// retry budget. The network call runs lock-free; the result is stored in
+	// s.liveURL under s.mu because restartFromSegment reads it from the HTTP
+	// handler goroutine too (seek-restart), not just this supervisor goroutine.
+	if s.cfg.SourceURL != "" && s.cfg.RefreshURL != nil {
+		rctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+		newURL, rerr := s.cfg.RefreshURL(rctx)
+		cancel()
+		if rerr != nil {
+			log.Printf("[hls %s] URL refresh before restart failed: %v", shortHLSID(s.cfg.SessionID), rerr)
+		} else {
+			s.mu.Lock()
+			s.liveURL = newURL
+			s.mu.Unlock()
+			log.Printf("[hls %s] debrid URL refreshed before restart", shortHLSID(s.cfg.SessionID))
+		}
+	}
+
 	// Restart from the last segment we know is safely on disk. If readyMax
 	// is 0 (never produced anything), retry from segment 0 — covers initial
 	// startup failures on transient errors.
@@ -966,8 +1043,15 @@ func (s *HLSSession) restartFromSegment(targetIdx int) error {
 	// Build args for the new ffmpeg with -ss offset. Segments are non-uniform
 	// (seg-0 is hlsInitSegmentDuration s, the rest are hlsSegmentDuration s),
 	// so use segmentStartSec for the seek time instead of multiplying.
+	// Use a local cfg copy carrying the live (possibly-refreshed) debrid URL,
+	// read under s.mu — this runs from the HTTP handler goroutine too, so it
+	// can't read s.liveURL unsynchronised while waitFFmpeg writes it (2c).
 	startSec := segmentStartSec(targetIdx)
-	args := buildHLSFFmpegArgsAt(s.cfg, s.probe, s.tmpDir, targetIdx, startSec)
+	cfg := s.cfg
+	s.mu.Lock()
+	cfg.SourceURL = s.liveURL // "" for local-file sessions — no-op, sourceRef falls back to SourcePath
+	s.mu.Unlock()
+	args := buildHLSFFmpegArgsAt(cfg, s.probe, s.tmpDir, targetIdx, startSec)
 
 	ffCtx, cancel := context.WithCancel(context.Background())
 	cmd := exec.CommandContext(ffCtx, s.cfg.Transcode.FFmpegPath, args...)
@@ -1038,8 +1122,8 @@ func buildHLSFFmpegArgs(cfg HLSSessionConfig, probe *StreamProbe, tmpDir string)
 // (otherwise the two switches in buildHLSFFmpegArgsAt could silently drift
 // when adding a new backend).
 type EncoderProfile struct {
-	Codec     string // ffmpeg encoder name (e.g. "h264_nvenc", "libx264")
-	Preset    string // preset string, or "" when the codec has no preset knob
+	Codec         string // ffmpeg encoder name (e.g. "h264_nvenc", "libx264")
+	Preset        string // preset string, or "" when the codec has no preset knob
 	DecodeHwAccel string // ffmpeg `-hwaccel` value (e.g. "cuda", "qsv", "vaapi"), or ""
 }
 
@@ -1111,7 +1195,22 @@ func buildHLSFFmpegArgsAt(cfg HLSSessionConfig, probe *StreamProbe, tmpDir strin
 		args = append(args, "-ss", strconv.FormatFloat(startSec, 'f', 3, 64))
 	}
 
-	args = append(args, "-i", cfg.SourcePath)
+	// Remote (debrid) input: make the HTTP read resilient. -reconnect* recovers
+	// from a dropped/idle connection (debrid CDNs close long-idle sockets);
+	// -rw_timeout (µs) bounds a stalled read so a hung CDN surfaces as a restart
+	// instead of a frozen player. A seek (-ss before -i) re-opens the URL with a
+	// Range request, which debrid supports. Flags are no-ops for local files, so
+	// only add them for a URL source.
+	if cfg.SourceURL != "" {
+		args = append(args,
+			"-reconnect", "1",
+			"-reconnect_streamed", "1",
+			"-reconnect_delay_max", "5",
+			"-rw_timeout", "30000000",
+		)
+	}
+
+	args = append(args, "-i", cfg.sourceRef())
 
 	if startSec > 0 {
 		args = append(args, "-output_ts_offset", strconv.FormatFloat(startSec, 'f', 3, 64))
@@ -1298,7 +1397,7 @@ func buildHLSFFmpegArgsAt(cfg HLSSessionConfig, probe *StreamProbe, tmpDir strin
 // extractSubtitles spawns short-lived ffmpeg jobs to convert each text-based
 // subtitle track to WebVTT in parallel. Bitmap subs (PGS, DVB) are skipped —
 // they would require burn-in into the video encode, which is out of scope.
-func (s *HLSSession) extractSubtitles(ctx context.Context) {
+func (s *HLSSession) extractSubtitles(ctx context.Context, src string) {
 	subsDir := filepath.Join(s.tmpDir, "subs")
 	for i, sub := range s.probe.SubtitleTracks {
 		if !sub.IsTextSubtitle() {
@@ -1307,7 +1406,7 @@ func (s *HLSSession) extractSubtitles(ctx context.Context) {
 		out := filepath.Join(subsDir, fmt.Sprintf("sub-%d.vtt", i))
 		args := []string{
 			"-y", "-hide_banner", "-loglevel", "warning",
-			"-i", s.cfg.SourcePath,
+			"-i", src,
 			"-map", fmt.Sprintf("0:s:%d?", i),
 			"-c:s", "webvtt",
 			out,

internal/engine/hls_cache.go

@@ -162,6 +162,16 @@ func (c *HLSCache) KeyFor(sourcePath, quality string, audioIndex int) string {
 	return hex.EncodeToString(h[:8]) // 16 hex chars — collision-safe enough for per-host cache
 }
 
+// KeyForID derives a cache key from a caller-supplied stable identity instead
+// of a filesystem path (hueco #2 / 2b). Used for debrid HLS-from-URL sessions:
+// the debrid direct URL is re-resolved per play and would never cache-hit, so
+// we key by the torrent info_hash — the same content always maps to the same
+// key across plays. NOT run through filepath.Abs (an id/URL is not a path).
+func (c *HLSCache) KeyForID(id, quality string, audioIndex int) string {
+	h := sha256.Sum256([]byte(fmt.Sprintf("%s|%s|%d", id, quality, audioIndex)))
+	return hex.EncodeToString(h[:8])
+}
+
 // DirFor returns the on-disk directory for a cache key. Caller is responsible
 // for creating it.
 func (c *HLSCache) DirFor(key string) string {
@@ -407,4 +417,3 @@ func (c *HLSCache) StartSweeper(ctx context.Context, interval time.Duration) {
 func (c *HLSCache) Invalidate(key string) error {
 	return os.RemoveAll(c.DirFor(key))
 }
-

internal/engine/hls_url_args_test.go

@@ -0,0 +1,122 @@
+package engine
+
+import (
+	"strings"
+	"testing"
+)
+
+// hueco #2 / 2b — buildHLSFFmpegArgsAt must feed a debrid URL straight to
+// ffmpeg's -i with HTTP-resilience flags, and must NOT add those flags for a
+// local file.
+func TestBuildHLSFFmpegArgsFromURL(t *testing.T) {
+	const url = "https://cdn.debrid.it/dl/abc/Movie.mkv"
+	cfg := HLSSessionConfig{
+		SessionID: "test",
+		SourceURL: url,
+		CacheID:   "deadbeef",
+		Quality:   "720p",
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  "/usr/bin/ffmpeg",
+			FFprobePath: "/usr/bin/ffprobe",
+			HWAccel:     HWAccelNone,
+		},
+	}
+	probe := &StreamProbe{Width: 1920, Height: 1080, DurationSec: 100}
+	args := buildHLSFFmpegArgsAt(cfg, probe, "/tmp/tmpdir", 0, 0)
+	got := strings.Join(args, " ")
+
+	for _, want := range []string{
+		"-reconnect 1",
+		"-reconnect_streamed 1",
+		"-reconnect_delay_max 5",
+		"-rw_timeout 30000000",
+		"-i " + url,
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("URL argv missing %q\n%s", want, got)
+		}
+	}
+}
+
+// A seek (startSec>0) on a URL source must keep BOTH the -ss input seek AND the
+// HTTP-resilience flags, so a seek-restart re-opens the URL with a Range request
+// instead of re-downloading from zero. (-ss before -i = input seek.)
+func TestBuildHLSFFmpegArgsFromURLWithSeek(t *testing.T) {
+	const url = "https://cdn.debrid.it/dl/abc/Movie.mkv"
+	cfg := HLSSessionConfig{
+		SessionID: "test",
+		SourceURL: url,
+		CacheID:   "deadbeef",
+		Quality:   "720p",
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  "/usr/bin/ffmpeg",
+			FFprobePath: "/usr/bin/ffprobe",
+			HWAccel:     HWAccelNone,
+		},
+	}
+	probe := &StreamProbe{Width: 1920, Height: 1080, DurationSec: 100}
+	got := strings.Join(buildHLSFFmpegArgsAt(cfg, probe, "/tmp/tmpdir", 5, 30), " ")
+
+	for _, want := range []string{
+		"-ss 30.000",   // input seek before -i
+		"-reconnect 1", // resilience flags still present on a restart
+		"-rw_timeout 30000000",
+		"-i " + url,
+		"-output_ts_offset 30.000", // PTS shift so the manifest numbering holds
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("seek+URL argv missing %q\n%s", want, got)
+		}
+	}
+	// -ss must come before -i (fast input seek, not slow output seek).
+	if strings.Index(got, "-ss 30.000") > strings.Index(got, "-i "+url) {
+		t.Errorf("-ss must precede -i for input seek:\n%s", got)
+	}
+}
+
+func TestBuildHLSFFmpegArgsLocalNoNetworkFlags(t *testing.T) {
+	cfg := HLSSessionConfig{
+		SessionID:  "test",
+		SourcePath: "/tmp/test.mkv",
+		Quality:    "720p",
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  "/usr/bin/ffmpeg",
+			FFprobePath: "/usr/bin/ffprobe",
+			HWAccel:     HWAccelNone,
+		},
+	}
+	probe := &StreamProbe{Width: 1920, Height: 1080, DurationSec: 100}
+	got := strings.Join(buildHLSFFmpegArgsAt(cfg, probe, "/tmp/tmpdir", 0, 0), " ")
+
+	if strings.Contains(got, "-reconnect") || strings.Contains(got, "-rw_timeout") {
+		t.Errorf("local source must not carry HTTP-resilience flags: %s", got)
+	}
+	if !strings.Contains(got, "-i /tmp/test.mkv") {
+		t.Errorf("local argv missing -i /tmp/test.mkv: %s", got)
+	}
+}
+
+// sourceRef + cache-key identity: a URL session keys by CacheID, a local one by
+// path. Guards the "re-plays of the same debrid content hit cache despite the
+// URL changing" invariant.
+func TestHLSSourceRefAndCacheID(t *testing.T) {
+	urlCfg := HLSSessionConfig{SourceURL: "https://cdn/x.mkv", CacheID: "hash1"}
+	if urlCfg.sourceRef() != "https://cdn/x.mkv" {
+		t.Errorf("sourceRef = %q, want the URL", urlCfg.sourceRef())
+	}
+	localCfg := HLSSessionConfig{SourcePath: "/m/x.mkv"}
+	if localCfg.sourceRef() != "/m/x.mkv" {
+		t.Errorf("sourceRef = %q, want the path", localCfg.sourceRef())
+	}
+
+	c := &HLSCache{root: "/tmp/cache"}
+	// Same CacheID + quality + audio → same key regardless of the (volatile) URL.
+	k1 := c.KeyForID("hash1", "720p", -1)
+	k2 := c.KeyForID("hash1", "720p", -1)
+	if k1 != k2 {
+		t.Errorf("KeyForID not stable: %q != %q", k1, k2)
+	}
+	if c.KeyForID("hash2", "720p", -1) == k1 {
+		t.Error("KeyForID collision across distinct ids")
+	}
+}

internal/engine/stream_growing_test.go

@@ -0,0 +1,197 @@
+package engine
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// fakeGrowing is a GrowingSource backed by a fixed byte slice. When final is
+// true it behaves like a completed remux (ReadAt returns io.EOF at the end);
+// est overrides the advertised estimate (0 = use len(data)).
+type fakeGrowing struct {
+	data  []byte
+	final bool
+	est   int64
+}
+
+func (f *fakeGrowing) ReadAt(p []byte, off int64) (int, error) {
+	if off < 0 || off >= int64(len(f.data)) {
+		return 0, io.EOF
+	}
+	n := copy(p, f.data[off:])
+	if int(off)+n >= len(f.data) {
+		return n, io.EOF
+	}
+	return n, nil
+}
+func (f *fakeGrowing) Size() int64 { return int64(len(f.data)) }
+func (f *fakeGrowing) Final() bool { return f.final }
+func (f *fakeGrowing) EstimatedSize() int64 {
+	if f.est > 0 {
+		return f.est
+	}
+	return int64(len(f.data))
+}
+func (f *fakeGrowing) FileName() string { return "movie.mp4" }
+func (f *fakeGrowing) Close() error     { return nil }
+
+func TestParseByteRange(t *testing.T) {
+	cases := []struct {
+		in         string
+		start, end int64
+	}{
+		{"", 0, -1},
+		{"bytes=0-", 0, -1},
+		{"bytes=100-", 100, -1},
+		{"bytes=5-9", 5, 9},
+		{"bytes=0-0", 0, 0},
+		{"bytes=10-19,40-49", 10, 19}, // first range only
+		{"bytes=-500", 0, -1},         // suffix unsupported → open from 0
+		{"garbage", 0, -1},
+		{"bytes=", 0, -1},
+	}
+	for _, c := range cases {
+		s, e := parseByteRange(c.in)
+		if s != c.start || e != c.end {
+			t.Errorf("parseByteRange(%q) = (%d,%d), want (%d,%d)", c.in, s, e, c.start, c.end)
+		}
+	}
+}
+
+func TestServeGrowing_FinalFullRequest(t *testing.T) {
+	data := []byte("0123456789abcdef")
+	src := &fakeGrowing{data: data, final: true}
+	ss := &StreamServer{}
+
+	req := httptest.NewRequest(http.MethodGet, "/stream", nil)
+	rec := httptest.NewRecorder()
+	ss.serveGrowing(rec, req, src)
+
+	res := rec.Result()
+	if res.StatusCode != http.StatusPartialContent {
+		t.Fatalf("status = %d, want 206", res.StatusCode)
+	}
+	if got := res.Header.Get("Content-Range"); got != "bytes 0-15/16" {
+		t.Errorf("Content-Range = %q, want bytes 0-15/16", got)
+	}
+	if got := res.Header.Get("Accept-Ranges"); got != "bytes" {
+		t.Errorf("Accept-Ranges = %q, want bytes", got)
+	}
+	if got := res.Header.Get("Content-Type"); got != "video/mp4" {
+		t.Errorf("Content-Type = %q, want video/mp4", got)
+	}
+	// Final + open-ended → exact Content-Length.
+	if got := res.Header.Get("Content-Length"); got != "16" {
+		t.Errorf("Content-Length = %q, want 16", got)
+	}
+	if body := rec.Body.String(); body != string(data) {
+		t.Errorf("body = %q, want %q", body, string(data))
+	}
+}
+
+func TestServeGrowing_OffsetRange(t *testing.T) {
+	data := []byte("0123456789abcdef")
+	src := &fakeGrowing{data: data, final: true}
+	ss := &StreamServer{}
+
+	req := httptest.NewRequest(http.MethodGet, "/stream", nil)
+	req.Header.Set("Range", "bytes=10-")
+	rec := httptest.NewRecorder()
+	ss.serveGrowing(rec, req, src)
+
+	res := rec.Result()
+	if res.StatusCode != http.StatusPartialContent {
+		t.Fatalf("status = %d, want 206", res.StatusCode)
+	}
+	if got := res.Header.Get("Content-Range"); got != "bytes 10-15/16" {
+		t.Errorf("Content-Range = %q, want bytes 10-15/16", got)
+	}
+	if body := rec.Body.String(); body != "abcdef" {
+		t.Errorf("body = %q, want abcdef", body)
+	}
+}
+
+func TestServeGrowing_BoundedRange(t *testing.T) {
+	data := []byte("0123456789abcdef")
+	src := &fakeGrowing{data: data, final: true}
+	ss := &StreamServer{}
+
+	req := httptest.NewRequest(http.MethodGet, "/stream", nil)
+	req.Header.Set("Range", "bytes=5-9")
+	rec := httptest.NewRecorder()
+	ss.serveGrowing(rec, req, src)
+
+	res := rec.Result()
+	if res.StatusCode != http.StatusPartialContent {
+		t.Fatalf("status = %d, want 206", res.StatusCode)
+	}
+	if got := res.Header.Get("Content-Range"); got != "bytes 5-9/16" {
+		t.Errorf("Content-Range = %q, want bytes 5-9/16", got)
+	}
+	if body := rec.Body.String(); body != "56789" {
+		t.Errorf("body = %q, want 56789 (exactly the requested 5 bytes)", body)
+	}
+}
+
+func TestServeGrowing_EstimateUsedWhileNotFinal(t *testing.T) {
+	// Not final: only 8 bytes produced, but estimate says 100. The advertised
+	// total is the estimate (scrubber timeline); body is what exists so far.
+	src := &fakeGrowing{data: []byte("01234567"), final: false, est: 100}
+	ss := &StreamServer{}
+
+	req := httptest.NewRequest(http.MethodGet, "/stream", nil)
+	rec := httptest.NewRecorder()
+	ss.serveGrowing(rec, req, src)
+
+	res := rec.Result()
+	if res.StatusCode != http.StatusPartialContent {
+		t.Fatalf("status = %d, want 206", res.StatusCode)
+	}
+	if got := res.Header.Get("Content-Range"); got != "bytes 0-99/100" {
+		t.Errorf("Content-Range = %q, want bytes 0-99/100 (estimate)", got)
+	}
+	// Not final → no exact Content-Length (chunked) so we never promise bytes
+	// a still-running remux might not produce.
+	if got := res.Header.Get("Content-Length"); got != "" {
+		t.Errorf("Content-Length = %q, want empty (chunked) while not final", got)
+	}
+	if body := rec.Body.String(); body != "01234567" {
+		t.Errorf("body = %q, want 01234567 (bytes produced so far)", body)
+	}
+}
+
+func TestServeGrowing_HeadProbe(t *testing.T) {
+	src := &fakeGrowing{data: make([]byte, 0), final: false, est: 4242}
+	ss := &StreamServer{}
+
+	req := httptest.NewRequest(http.MethodHead, "/stream", nil)
+	rec := httptest.NewRecorder()
+	ss.serveGrowing(rec, req, src)
+
+	res := rec.Result()
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("HEAD status = %d, want 200", res.StatusCode)
+	}
+	if got := res.Header.Get("Content-Length"); got != "4242" {
+		t.Errorf("HEAD Content-Length = %q, want 4242", got)
+	}
+	if rec.Body.Len() != 0 {
+		t.Errorf("HEAD body = %d bytes, want 0", rec.Body.Len())
+	}
+}
+
+func TestServeGrowing_RangeBeyondTotal(t *testing.T) {
+	src := &fakeGrowing{data: []byte("0123456789"), final: true}
+	ss := &StreamServer{}
+
+	req := httptest.NewRequest(http.MethodGet, "/stream", nil)
+	req.Header.Set("Range", "bytes=999-")
+	rec := httptest.NewRecorder()
+	ss.serveGrowing(rec, req, src)
+
+	if rec.Result().StatusCode != http.StatusRequestedRangeNotSatisfiable {
+		t.Errorf("status = %d, want 416", rec.Result().StatusCode)
+	}
+}

internal/engine/stream_server.go

@@ -2,6 +2,7 @@ package engine
 
 import (
 	"context"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -37,13 +38,31 @@ type FileProvider interface {
 	FileSize() int64
 }
 
+// GrowingSource is a /stream source whose bytes are produced over time by an
+// ffmpeg remux/transcode to a temp file (see transcodeSource). It is served
+// via manual Range handling (serveGrowing) instead of http.ServeContent,
+// which assumes a complete, fixed-size, seekable file. Used by direct-play's
+// remux path (hueco #3 / 3b): mkv h264/aac → progressive fMP4, no re-encode.
+type GrowingSource interface {
+	// ReadAt blocks until off+len(p) bytes have been produced, the source is
+	// final, or a timeout elapses; near the live edge it returns a short
+	// (n>0, nil) read so the caller can stream what exists so far.
+	ReadAt(p []byte, off int64) (int, error)
+	Size() int64          // bytes produced so far
+	Final() bool          // ffmpeg exited — Size() is now the true total
+	EstimatedSize() int64 // expected final size, for the scrubber timeline
+	FileName() string
+	Close() error
+}
+
 // StreamServer is a persistent HTTP server that serves one file at a time.
 // Start it once with Listen(), then swap files with SetFile()/ClearFile().
 // The server stays alive for the entire daemon lifecycle — no port churn.
 type StreamServer struct {
 	mu       sync.RWMutex
 	provider FileProvider
-	taskID   string // current task being streamed
+	growing  GrowingSource // set instead of provider for the progressive-remux path (3b)
+	taskID   string        // current task being streamed
 
 	server      *http.Server
 	port        int
@@ -65,6 +84,12 @@ type StreamServer struct {
 
 	hls *HLSSessionRegistry // HLS sessions served on /hls/<id>/...
 
+	// streamSecret signs the per-URL stream tokens (see stream_token.go). In
+	// memory only; regenerated each daemon start. requireToken gates whether
+	// remote (non-loopback) /stream and /hls requests must carry a valid token.
+	streamSecret []byte
+	requireToken bool
+
 	lastActivity  atomic.Int64
 	maxByteOffset atomic.Int64 // highest sequential read position (main playback connection)
 	totalFileSize atomic.Int64
@@ -83,7 +108,37 @@ type StreamServer struct {
 // have no auth, so exposing them to the public internet is something the
 // operator must explicitly request.
 func NewStreamServer(port int) *StreamServer {
-	return &StreamServer{port: port, hls: NewHLSSessionRegistry()}
+	return &StreamServer{
+		port:         port,
+		hls:          NewHLSSessionRegistry(),
+		streamSecret: newStreamSecret(),
+		requireToken: true, // secure by default; the agent self-mints tokens
+	}
+}
+
+// StreamSecretHex returns the daemon's stream-token signing key as hex, so it
+// can be reported to the web (which mints the HLS path token the agent then
+// verifies). Treat as a secret — it lets the holder mint valid stream tokens.
+func (ss *StreamServer) StreamSecretHex() string {
+	return hex.EncodeToString(ss.streamSecret)
+}
+
+// SetRequireStreamToken toggles remote stream-token enforcement. Loopback
+// callers are always exempt. Call before Listen() / before reporting URLs.
+// Default is true; an operator can disable it via config for debugging.
+func (ss *StreamServer) SetRequireStreamToken(require bool) {
+	ss.requireToken = require
+}
+
+// checkStreamToken reports whether a request may proceed: always true when
+// enforcement is off; otherwise the token must be a valid signature for scope.
+// No loopback exemption — cloudflared relays public funnel traffic over
+// localhost, so loopback is not a trust signal.
+func (ss *StreamServer) checkStreamToken(scope, token string) bool {
+	if !ss.requireToken {
+		return true
+	}
+	return verifyStreamToken(ss.streamSecret, scope, token, time.Now())
 }
 
 // SetUPnPEnabled toggles WAN publishing of the stream port. Call before
@@ -233,9 +288,14 @@ func (ss *StreamServer) Listen(ctx context.Context) error {
 // SetFile atomically swaps the file being served and resets progress tracking.
 func (ss *StreamServer) SetFile(provider FileProvider, taskID string) {
 	ss.mu.Lock()
+	prevGrowing := ss.growing
 	ss.provider = provider
+	ss.growing = nil // a raw-file provider supersedes any in-flight remux
 	ss.taskID = taskID
 	ss.mu.Unlock()
+	if prevGrowing != nil {
+		_ = prevGrowing.Close() // stop the orphan ffmpeg + drop its temp file
+	}
 	ss.totalFileSize.Store(provider.FileSize())
 	ss.lastActivity.Store(time.Now().UnixNano())
 	ss.maxByteOffset.Store(0)
@@ -258,12 +318,40 @@ func (ss *StreamServer) SetFile(provider FileProvider, taskID string) {
 	}
 }
 
+// SetGrowingFile serves a progressive-remux source on /stream (hueco #3 / 3b):
+// ffmpeg `-c copy` mkv→fMP4 to a growing temp file, range-served via
+// serveGrowing. Supersedes any prior provider/growing source (single-viewer).
+func (ss *StreamServer) SetGrowingFile(src GrowingSource, taskID string) {
+	ss.mu.Lock()
+	prevGrowing := ss.growing
+	ss.growing = src
+	ss.provider = nil
+	ss.taskID = taskID
+	ss.mu.Unlock()
+	if prevGrowing != nil {
+		_ = prevGrowing.Close()
+	}
+	ss.totalFileSize.Store(src.EstimatedSize())
+	ss.lastActivity.Store(time.Now().UnixNano())
+	ss.maxByteOffset.Store(0)
+	ss.topReaderID.Store(0)
+	// Rate-limit + bitrate tracking are for raw-file playback; the remux pump
+	// has its own pacing (ffmpeg copy is I/O-bound), so leave them at zero.
+	ss.bitrateBps.Store(0)
+	ss.durationSec.Store(0)
+}
+
 // ClearFile stops serving any file. Subsequent requests return 404.
 func (ss *StreamServer) ClearFile() {
 	ss.mu.Lock()
 	ss.provider = nil
+	prevGrowing := ss.growing
+	ss.growing = nil
 	ss.taskID = ""
 	ss.mu.Unlock()
+	if prevGrowing != nil {
+		_ = prevGrowing.Close()
+	}
 	ss.totalFileSize.Store(0)
 	ss.maxByteOffset.Store(0)
 	ss.topReaderID.Store(0)
@@ -278,22 +366,55 @@ func (ss *StreamServer) CurrentTaskID() string {
 	return ss.taskID
 }
 
-// HasFile returns true if a file is currently being served.
+// HasFile returns true if a file (raw provider or growing remux) is being served.
 func (ss *StreamServer) HasFile() bool {
 	ss.mu.RLock()
 	defer ss.mu.RUnlock()
-	return ss.provider != nil
+	return ss.provider != nil || ss.growing != nil
 }
 
 // URL returns the best single stream URL (backward compat).
-func (ss *StreamServer) URL() string { return ss.url }
+// URL returns the best single /stream URL, carrying a `?t=` token when
+// enforcement is on. This is what the one-shot `unarr stream` hands to the
+// player — and since the best URL is the Tailscale/LAN address (not loopback),
+// it must be tokenised or a remote-addressed player would be rejected.
+func (ss *StreamServer) URL() string { return ss.tokenizeStreamURL(ss.url) }
 
-// URLsJSON returns all available stream URLs as a JSON string.
+// tokenizeStreamURL appends a freshly-minted `?t=<token>` (scope "stream") to a
+// /stream URL. No-op when the URL is empty or enforcement is off.
+func (ss *StreamServer) tokenizeStreamURL(u string) string {
+	if u == "" || !ss.requireToken {
+		return u
+	}
+	sep := "?"
+	if strings.Contains(u, "?") {
+		sep = "&"
+	}
+	return u + sep + "t=" + mintStreamToken(ss.streamSecret, streamScopeStream, time.Now())
+}
+
+// URLsJSON returns all available stream URLs as a JSON string, each carrying a
+// freshly-minted `?t=` stream token when enforcement is on. The web reports
+// these verbatim to the browser (pass-through), so the token reaches the
+// player without any web-side minting.
 func (ss *StreamServer) URLsJSON() string {
-	b, _ := json.Marshal(ss.urls)
+	b, _ := json.Marshal(ss.tokenizedStreamURLs())
 	return string(b)
 }
 
+// tokenizedStreamURLs appends a `?t=<token>` (scope "stream") to each non-empty
+// /stream URL. No-op when enforcement is off.
+func (ss *StreamServer) tokenizedStreamURLs() StreamURLs {
+	if !ss.requireToken {
+		return ss.urls
+	}
+	return StreamURLs{
+		LAN:       ss.tokenizeStreamURL(ss.urls.LAN),
+		Tailscale: ss.tokenizeStreamURL(ss.urls.Tailscale),
+		Public:    ss.tokenizeStreamURL(ss.urls.Public),
+	}
+}
+
 // Port returns the bound port.
 func (ss *StreamServer) Port() int { return ss.port }
 
@@ -323,15 +444,21 @@ func (ss *StreamServer) Shutdown(ctx context.Context) error {
 // The web client picks the first reachable one — same fallback strategy as
 // the legacy /stream URLs.
 func (ss *StreamServer) hlsBaseURLs(sessionID string) StreamURLs {
+	// Token rides as a path segment so the playlists' relative child URIs
+	// (video/index.m3u8, seg-N.m4s, subs/…) inherit it via relative resolution.
+	base := "/hls/" + sessionID
+	if ss.requireToken {
+		base += "/" + mintStreamToken(ss.streamSecret, streamScopeHLS(sessionID), time.Now())
+	}
 	var out StreamURLs
 	if ss.urls.LAN != "" {
-		out.LAN = strings.Replace(ss.urls.LAN, "/stream", "/hls/"+sessionID, 1)
+		out.LAN = strings.Replace(ss.urls.LAN, "/stream", base, 1)
 	}
 	if ss.urls.Tailscale != "" {
-		out.Tailscale = strings.Replace(ss.urls.Tailscale, "/stream", "/hls/"+sessionID, 1)
+		out.Tailscale = strings.Replace(ss.urls.Tailscale, "/stream", base, 1)
 	}
 	if ss.urls.Public != "" {
-		out.Public = strings.Replace(ss.urls.Public, "/stream", "/hls/"+sessionID, 1)
+		out.Public = strings.Replace(ss.urls.Public, "/stream", base, 1)
 	}
 	return out
 }
@@ -374,16 +501,36 @@ func (ss *StreamServer) hlsHandler(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "hls session not found", http.StatusNotFound)
 		return
 	}
+	remainder := ""
+	if len(parts) > 1 {
+		remainder = parts[1]
+	}
+	// Auth: when enforcement is on, the URL is /hls/<sessionID>/<token>/<resource>.
+	// Peel the token segment and verify it (no loopback exemption — funnel
+	// traffic arrives over localhost). 404 on mismatch — same response as an
+	// unknown session, no oracle.
+	if ss.requireToken {
+		sub := strings.SplitN(remainder, "/", 2)
+		if !verifyStreamToken(ss.streamSecret, streamScopeHLS(sessionID), sub[0], time.Now()) {
+			http.Error(w, "hls session not found", http.StatusNotFound)
+			return
+		}
+		if len(sub) < 2 {
+			http.Error(w, "missing resource", http.StatusNotFound)
+			return
+		}
+		remainder = sub[1]
+	}
 	session := ss.hls.Get(sessionID)
 	if session == nil {
 		http.Error(w, "hls session not found", http.StatusNotFound)
 		return
 	}
-	if len(parts) == 1 {
+	if remainder == "" {
 		http.Error(w, "missing resource", http.StatusNotFound)
 		return
 	}
-	resource := parts[1]
+	resource := remainder
 
 	switch {
 	case resource == "master.m3u8":
@@ -539,9 +686,11 @@ func (ss *StreamServer) playlistHandler(w http.ResponseWriter, r *http.Request)
 		streamURL = ""
 	}
 	if streamURL == "" {
-		streamURL = ss.url
-	}
-	if streamURL == "" {
+		// No self-minting fallback: returning a freshly-tokenised URL for a
+		// param-less request would make /playlist.m3u an open token oracle
+		// (any caller could fetch a valid /stream?t=… here). The web always
+		// passes an already-tokenised streamUrl param; the playlist just echoes
+		// it — the real auth gate is /stream itself.
 		http.Error(w, "no active stream", http.StatusNotFound)
 		return
 	}
@@ -577,12 +726,13 @@ func (ss *StreamServer) handler(w http.ResponseWriter, r *http.Request) {
 	clientIP, _, _ := net.SplitHostPort(r.RemoteAddr)
 	log.Printf("[stream] %s /stream from %s Range:%q", r.Method, clientIP, r.Header.Get("Range"))
 
-	// Get current provider (may be nil if no file is being served)
+	// Get current source (raw provider or growing remux; nil if none).
 	ss.mu.RLock()
 	provider := ss.provider
+	growing := ss.growing
 	ss.mu.RUnlock()
 
-	if provider == nil {
+	if provider == nil && growing == nil {
 		http.Error(w, "no active stream", http.StatusNotFound)
 		return
 	}
@@ -591,6 +741,21 @@ func (ss *StreamServer) handler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// Auth: every caller must carry a valid stream token. 404 (not 401/403) so
+	// an unauthorised caller gets no oracle that a stream is active here.
+	if !ss.checkStreamToken(streamScopeStream, r.URL.Query().Get("t")) {
+		log.Printf("[stream] rejected %s — bad/absent token", clientIP)
+		http.Error(w, "no active stream", http.StatusNotFound)
+		return
+	}
+
+	// Progressive-remux path (3b): a growing fMP4 produced by ffmpeg `-c copy`.
+	// Range-served manually because http.ServeContent needs a complete file.
+	if growing != nil {
+		ss.serveGrowing(w, r, growing)
+		return
+	}
+
 	rawReader := provider.NewFileReader(r.Context())
 	if rawReader == nil {
 		http.Error(w, "file not found", http.StatusNotFound)
@@ -637,6 +802,147 @@ func (ss *StreamServer) handler(w http.ResponseWriter, r *http.Request) {
 	http.ServeContent(w, r, provider.FileName(), time.Time{}, reader)
 }
 
+// serveGrowing range-serves a growing remux source (hueco #3 / 3b). Unlike
+// http.ServeContent it can't rely on a fixed file size: ffmpeg `-c copy` is
+// still writing, and the final byte count isn't known until it exits. So we:
+//
+//   - advertise an ESTIMATED total (≈ source file size for a copy remux) in
+//     Content-Range so the browser scrubber has a timeline;
+//   - reply 206 and stream from the requested offset, blocking via ReadAt for
+//     not-yet-produced bytes, until the explicit range end or the real EOF;
+//   - send the body chunked (no Content-Length) for non-final sources, since
+//     the true length differs from the estimate — promising an exact length we
+//     can't fulfil would hang the browser. When the source is already final we
+//     send an exact Content-Length.
+//
+// Seeking forward into a not-yet-remuxed region blocks briefly until the copy
+// (I/O-bound, fast) catches up; seeking back to produced bytes is immediate.
+func (ss *StreamServer) serveGrowing(w http.ResponseWriter, r *http.Request, src GrowingSource) {
+	w.Header().Set("Accept-Ranges", "bytes")
+	w.Header().Set("Content-Type", "video/mp4")
+	w.Header().Set("Content-Disposition", fmt.Sprintf("inline; filename=%q", src.FileName()))
+
+	// Total to advertise: exact when ffmpeg has exited, else the estimate.
+	total := src.EstimatedSize()
+	if src.Final() {
+		total = src.Size()
+	}
+	if total <= 0 {
+		total = src.Size()
+	}
+
+	start, explicitEnd := parseByteRange(r.Header.Get("Range"))
+	if total > 0 && start >= total {
+		// Range beyond what we expect to produce — let the browser recover.
+		w.Header().Set("Content-Range", fmt.Sprintf("bytes */%d", total))
+		http.Error(w, "range not satisfiable", http.StatusRequestedRangeNotSatisfiable)
+		return
+	}
+
+	if r.Method == http.MethodHead {
+		if total > 0 {
+			w.Header().Set("Content-Length", strconv.FormatInt(total, 10))
+		}
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+
+	end := total - 1
+	if explicitEnd >= 0 && explicitEnd < end {
+		end = explicitEnd
+	}
+	if total > 0 {
+		w.Header().Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", start, end, total))
+	}
+	// Exact Content-Length only when the source is final (true size known) so
+	// we never promise bytes a still-running remux might not produce.
+	if src.Final() && explicitEnd < 0 {
+		w.Header().Set("Content-Length", strconv.FormatInt(src.Size()-start, 10))
+	}
+	w.WriteHeader(http.StatusPartialContent)
+
+	buf := make([]byte, 256*1024)
+	off := start
+	firstRead := true
+	for {
+		if explicitEnd >= 0 && off > explicitEnd {
+			return
+		}
+		if r.Context().Err() != nil {
+			return // client disconnected / request cancelled
+		}
+		readStart := time.Now()
+		n, err := src.ReadAt(buf, off)
+		// TTFF diagnosis: a read that blocks means the client asked for bytes the
+		// remux hasn't produced yet (a seek ahead of the live edge, or the very
+		// first read before ffmpeg's init lands). Log it so a slow start is
+		// attributable to "waiting on ffmpeg" vs network/decoder.
+		if waited := time.Since(readStart); waited > 250*time.Millisecond {
+			log.Printf("[stream] serveGrowing read off=%d blocked %v (produced=%d est=%d)",
+				off, waited.Round(time.Millisecond), src.Size(), src.EstimatedSize())
+		} else if firstRead {
+			log.Printf("[stream] serveGrowing start off=%d (produced=%d est=%d)", start, src.Size(), src.EstimatedSize())
+		}
+		firstRead = false
+		if n > 0 {
+			toWrite := n
+			if explicitEnd >= 0 {
+				if remaining := explicitEnd - off + 1; int64(toWrite) > remaining {
+					toWrite = int(remaining)
+				}
+			}
+			if _, werr := w.Write(buf[:toWrite]); werr != nil {
+				return // client gone
+			}
+			off += int64(toWrite)
+			if f, ok := w.(http.Flusher); ok {
+				f.Flush()
+			}
+		}
+		if err != nil {
+			// transcodeSource returns io.EOF only at the true (final) end; any
+			// other error means ffmpeg failed or the read timed out. Either
+			// way the stream is over — close the body.
+			return
+		}
+	}
+}
+
+// parseByteRange parses a single "bytes=start-[end]" header into (start, end).
+// end is -1 when open-ended or absent. Multi-range and suffix ranges
+// ("bytes=-N") are not supported (returns start=0) — the browser falls back to
+// a normal open-ended request, which is all <video> needs for a growing source.
+func parseByteRange(header string) (start, end int64) {
+	end = -1
+	if !strings.HasPrefix(header, "bytes=") {
+		return 0, -1
+	}
+	spec := strings.TrimPrefix(header, "bytes=")
+	if i := strings.IndexByte(spec, ','); i >= 0 {
+		spec = spec[:i] // first range only
+	}
+	dash := strings.IndexByte(spec, '-')
+	if dash < 0 {
+		return 0, -1
+	}
+	startStr := strings.TrimSpace(spec[:dash])
+	if startStr == "" {
+		// Suffix range "bytes=-N" (last N bytes) is unsupported on a growing
+		// source whose total isn't fixed — serve open-ended from 0 instead of
+		// mis-reading N as an absolute end. fMP4 (moov at front) never needs it.
+		return 0, -1
+	}
+	if v, err := strconv.ParseInt(startStr, 10, 64); err == nil && v >= 0 {
+		start = v
+	}
+	if e := strings.TrimSpace(spec[dash+1:]); e != "" {
+		if v, err := strconv.ParseInt(e, 10, 64); err == nil && v >= 0 {
+			end = v
+		}
+	}
+	return start, end
+}
+
 // EstimatedProgress returns estimated watch progress percentage (0-100)
 // and the total duration in seconds (0 if unknown).
 func (ss *StreamServer) EstimatedProgress() (pct int, durationSec int) {

internal/engine/stream_source.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"log"
 	"os"
 	"path/filepath"
 	"strings"
@@ -125,7 +126,20 @@ func newTranscodeSource(
 		return nil, err
 	}
 
-	estimate := estimateOutputSize(probe, opts)
+	// Size estimate for the scrubber timeline. A copy remux (video not
+	// re-encoded) lands within container overhead of the source file, so the
+	// source size is a far better estimate than bitrate×duration — use it.
+	// A real transcode re-encodes, so fall back to the bitrate×duration model.
+	var estimate int64
+	switch action {
+	case ActionPassthrough, ActionRemux, ActionRemuxAudio:
+		if fi, statErr := os.Stat(srcPath); statErr == nil {
+			estimate = fi.Size()
+		}
+	}
+	if estimate <= 0 {
+		estimate = estimateOutputSize(probe, opts)
+	}
 
 	t := &transcodeSource{
 		tmpPath:   tmpPath,
@@ -151,6 +165,31 @@ func newTranscodeSource(
 	return t, nil
 }
 
+// NewRemuxSource starts an ffmpeg `-c copy` remux of srcPath into a growing
+// fragmented-MP4 temp file and returns it as a GrowingSource for /stream
+// (hueco #3 / 3b). The video + audio are copied (never re-encoded), so this is
+// only valid when the codecs are already browser-native (h264 + aac) and only
+// the container needs changing — the web's decidePlayMethod enforces that
+// before sending PlayMethod="remux". The browser plays the result progressively
+// via byte-range. Caller MUST Close() it (kills ffmpeg + removes the temp file).
+func NewRemuxSource(ctx context.Context, srcPath string, probe *StreamProbe, ffmpegPath, displayName string) (GrowingSource, error) {
+	// Audio: copy when already AAC; otherwise transcode to AAC (ActionRemuxAudio).
+	// Either way the VIDEO is copied — the expensive part is never re-encoded.
+	// This lets remux cover the very common h264+AC3/DTS mkv case (hueco #3 / 3c),
+	// not just h264+AAC.
+	action := ActionRemux
+	if probe != nil && probe.AudioCodec != "" && probe.AudioCodec != "aac" {
+		action = ActionRemuxAudio
+	}
+	opts := TranscodeOpts{Action: action, FFmpegPath: ffmpegPath}
+	// HEVC muxed into MP4 must carry the hvc1 tag or Apple/Safari won't decode
+	// it (hueco #3 / 3c). h264 (avc1) needs no override.
+	if probe != nil && probe.VideoCodec == "hevc" {
+		opts.VideoTag = "hvc1"
+	}
+	return newTranscodeSource(ctx, srcPath, probe, action, opts, displayName)
+}
+
 // signalNotify wakes any goroutine blocked in ReadAt. Non-blocking: if a
 // notification is already pending the new event is folded into it (callers
 // always re-check size + final after waking, so a coalesced signal still
@@ -184,6 +223,13 @@ func (t *transcodeSource) watchSize(ctx context.Context) {
 		}
 		current := stat.Size()
 		if current > t.size.Load() {
+			if t.size.Load() == 0 && current > 0 {
+				// TTFF diagnosis: how long from ffmpeg spawn to the first
+				// fMP4 bytes (init + first fragment) landing — the floor on
+				// when /stream can serve anything playable.
+				log.Printf("[stream] %s first fMP4 bytes after %v (%d KB)",
+					t.name, time.Since(t.startedAt).Round(time.Millisecond), current/1024)
+			}
 			t.size.Store(current)
 			t.signalNotify()
 		}

internal/engine/stream_source_debrid.go

@@ -0,0 +1,337 @@
+// Package engine — stream_source_debrid.go implements a FileProvider that
+// serves a /stream session straight from a debrid HTTPS direct URL (hueco #2 /
+// 2a). No local file is involved: the browser's Range requests are translated
+// into ranged GETs against the debrid link, so a cache-confirmed torrent plays
+// instantly without ever hitting the swarm or touching disk.
+//
+// The web resolves the DirectURL server-side (resolveDebridDirectUrl) and only
+// sends it when the hash is debrid-cached and the container is browser-native
+// (mp4/m4v), so this provider stays a pure pass-through — same role as
+// diskFileProvider/torrentFileProvider, just backed by HTTP Range instead of a
+// file handle. http.ServeContent drives it exactly like a local file: it Seeks
+// to discover size + the range start (no network), then Reads (lazy GET).
+package engine
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"path"
+	"strings"
+	"sync"
+	"time"
+)
+
+// debridHTTPClient is used for ranged debrid reads. Separate from the download
+// httpClient so a slow streaming read can't starve a concurrent download's
+// header-timeout budget, and vice versa. No overall timeout: a paused player
+// can legitimately hold a body open for minutes; ResponseHeaderTimeout bounds
+// the part that actually matters (a hung server before first byte).
+var debridHTTPClient = &http.Client{
+	Transport: &http.Transport{
+		ResponseHeaderTimeout: 30 * time.Second,
+		// debrid CDNs are remote; a generous idle-conn pool avoids a fresh TLS
+		// handshake on every seek-driven reopen.
+		MaxIdleConns:        4,
+		IdleConnTimeout:     90 * time.Second,
+		TLSHandshakeTimeout: 15 * time.Second,
+	},
+}
+
+// NewDebridFileProvider builds a FileProvider backed by a debrid HTTPS URL.
+// It performs a single HEAD up front to learn the exact file size (the torrent
+// size the web knows can differ from the resolved file's size). If the HEAD
+// fails or omits Content-Length, fallbackSize (from the StreamSession) is used.
+// Returns an error only when neither a HEAD size nor a fallback is available —
+// http.ServeContent needs a real size to range-serve, and serving size 0 would
+// hand the browser an empty file.
+// refresh, when non-nil, re-resolves a fresh debrid URL for the same content
+// (hueco #2 / 2c) — called when the current link expires mid-stream. nil keeps
+// 2a behaviour (an expired link is a hard error, no recovery).
+func NewDebridFileProvider(ctx context.Context, directURL, fileName string, fallbackSize int64, refresh func(context.Context) (string, error)) (FileProvider, error) {
+	if directURL == "" {
+		return nil, errors.New("debrid provider: empty direct URL")
+	}
+	size := fallbackSize
+	if headSize, ok := debridHeadSize(ctx, directURL); ok {
+		size = headSize
+	}
+	if size <= 0 {
+		return nil, fmt.Errorf("debrid provider: unknown file size (HEAD gave nothing, no fallback)")
+	}
+	// The name drives the served Content-Type (mimeTypeFromExt on FileName).
+	// The web may pass a torrent title with no extension (its file-name
+	// fallback), which would yield application/octet-stream and break <video>
+	// on strict clients (Safari). The debrid URL reliably ends in the real
+	// file name *with* its extension, so derive from it whenever the passed
+	// name lacks one.
+	name := fileName
+	if name == "" || path.Ext(name) == "" {
+		name = debridNameFromURL(directURL)
+	}
+	return &debridFileProvider{
+		url:     directURL,
+		name:    name,
+		size:    size,
+		refresh: refresh,
+	}, nil
+}
+
+// debridFileProvider serves a file from a debrid HTTPS URL via ranged GETs. The
+// URL is mutable: when it expires mid-stream, refreshURL swaps in a fresh one
+// (shared across all readers this provider hands out) so the next range request
+// uses the live link.
+type debridFileProvider struct {
+	mu            sync.Mutex
+	url           string
+	lastRefreshAt time.Time
+	inflight      *refreshCall // non-nil while a refresh is running; coalesces concurrent callers
+	refresh       func(context.Context) (string, error)
+
+	name string
+	size int64
+}
+
+// refreshCall is a single in-flight refresh whose result is shared by every
+// reader that piles up behind it (singleflight). done is closed on completion.
+type refreshCall struct {
+	done chan struct{}
+	url  string
+	err  error
+}
+
+// currentURL returns the live debrid URL (mutated by refreshURL on expiry).
+func (p *debridFileProvider) currentURL() string {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return p.url
+}
+
+// refreshURL re-resolves a fresh debrid link and stores it. A browser's <video>
+// opens several concurrent range connections, so when a link expires N readers
+// hit it at once — they must NOT each fire a (multi-second) re-resolution.
+// Coalescing is two-layer: (1) a result refreshed in the last few seconds is
+// reused without any call; (2) while a refresh is in flight, late callers wait
+// on it and share its result (singleflight) rather than starting their own.
+func (p *debridFileProvider) refreshURL(ctx context.Context) (string, error) {
+	if p.refresh == nil {
+		return "", errors.New("debrid provider: no URL refresher (refresh disabled)")
+	}
+	p.mu.Lock()
+	if time.Since(p.lastRefreshAt) < 5*time.Second && p.url != "" {
+		u := p.url
+		p.mu.Unlock()
+		return u, nil // refreshed very recently — reuse it
+	}
+	if call := p.inflight; call != nil {
+		p.mu.Unlock()
+		select {
+		case <-call.done:
+			return call.url, call.err // shared result from the in-flight refresh
+		case <-ctx.Done():
+			return "", ctx.Err()
+		}
+	}
+	call := &refreshCall{done: make(chan struct{})}
+	p.inflight = call
+	p.mu.Unlock()
+
+	u, err := p.refresh(ctx)
+
+	p.mu.Lock()
+	if err == nil {
+		p.url = u
+		p.lastRefreshAt = time.Now()
+	}
+	call.url, call.err = u, err
+	p.inflight = nil
+	close(call.done)
+	p.mu.Unlock()
+
+	if err != nil {
+		return "", err
+	}
+	log.Printf("[stream] debrid URL refreshed (expired mid-stream)")
+	return u, nil
+}
+
+func (p *debridFileProvider) NewFileReader(ctx context.Context) io.ReadSeekCloser {
+	return &debridRangeReader{
+		ctx:  ctx,
+		prov: p,
+		size: p.size,
+	}
+}
+
+func (p *debridFileProvider) FileName() string { return p.name }
+func (p *debridFileProvider) FileSize() int64  { return p.size }
+
+// debridRangeReader is an io.ReadSeekCloser over an HTTP resource that supports
+// Range. Seek is network-free: it only moves the logical position. Read opens
+// (or reuses) a GET starting at the current position and streams the body; a
+// Seek that moves away from the open body's cursor forces a reopen on the next
+// Read. This matches how http.ServeContent works — Seek(0, SeekEnd) for size,
+// Seek to the range start, then sequential Reads — so seeks the user makes in
+// the player become a single reopened GET, never a full re-download.
+type debridRangeReader struct {
+	ctx  context.Context
+	prov *debridFileProvider
+	size int64
+
+	pos    int64         // logical position (moved by Seek, advanced by Read)
+	body   io.ReadCloser // current open response body, or nil
+	bodyAt int64         // position the open body's next byte maps to
+}
+
+func (r *debridRangeReader) Read(p []byte) (int, error) {
+	if r.size > 0 && r.pos >= r.size {
+		return 0, io.EOF
+	}
+	// (Re)open when no body is held or a Seek moved us off the open body.
+	if r.body == nil || r.pos != r.bodyAt {
+		if err := r.reopen(); err != nil {
+			return 0, err
+		}
+	}
+	n, err := r.body.Read(p)
+	r.pos += int64(n)
+	r.bodyAt = r.pos
+	if err == io.EOF {
+		// Body drained. Drop it so the next Read reopens (covers a server that
+		// closed the connection before the logical EOF). Surface EOF to the
+		// caller only when we've actually reached end-of-file; otherwise hand
+		// back the bytes read with no error and let the caller Read again.
+		_ = r.body.Close()
+		r.body = nil
+		if r.size > 0 && r.pos < r.size {
+			return n, nil
+		}
+	}
+	return n, err
+}
+
+func (r *debridRangeReader) Seek(offset int64, whence int) (int64, error) {
+	var abs int64
+	switch whence {
+	case io.SeekStart:
+		abs = offset
+	case io.SeekCurrent:
+		abs = r.pos + offset
+	case io.SeekEnd:
+		abs = r.size + offset
+	default:
+		return 0, fmt.Errorf("debrid reader: invalid whence %d", whence)
+	}
+	if abs < 0 {
+		return 0, errors.New("debrid reader: negative position")
+	}
+	r.pos = abs
+	return abs, nil
+}
+
+func (r *debridRangeReader) Close() error {
+	if r.body != nil {
+		err := r.body.Close()
+		r.body = nil
+		return err
+	}
+	return nil
+}
+
+// reopen issues a fresh ranged GET from the current logical position. Closes
+// any previously held body first. On an expired-link status (401/403/404/410)
+// it re-resolves a fresh debrid URL via the provider and retries — bounded, so
+// a permanently-dead link surfaces an error instead of looping (hueco #2 / 2c).
+func (r *debridRangeReader) reopen() error {
+	if r.body != nil {
+		_ = r.body.Close()
+		r.body = nil
+	}
+	// Attempts: 1 initial + 1 after a URL refresh. One fresh link is enough for
+	// an expiry; if the refreshed link ALSO fails the content is genuinely gone,
+	// so surface the error rather than burning more multi-second resolutions.
+	const maxAttempts = 2
+	for attempt := 0; attempt < maxAttempts; attempt++ {
+		req, err := http.NewRequestWithContext(r.ctx, http.MethodGet, r.prov.currentURL(), nil)
+		if err != nil {
+			return fmt.Errorf("debrid reader: build request: %w", err)
+		}
+		// Always send a Range so a seek to 0 still gets a 206 (and so partial
+		// reopens after a mid-file seek work). An open-ended range runs to EOF.
+		req.Header.Set("Range", fmt.Sprintf("bytes=%d-", r.pos))
+		resp, err := debridHTTPClient.Do(req)
+		if err != nil {
+			return fmt.Errorf("debrid reader: GET: %w", err)
+		}
+		switch resp.StatusCode {
+		case http.StatusPartialContent:
+			r.body = resp.Body
+			r.bodyAt = r.pos
+			return nil
+		case http.StatusOK:
+			// Server ignored Range and is sending the whole file from 0. Only
+			// valid when we asked from 0; otherwise bytes wouldn't line up.
+			if r.pos != 0 {
+				resp.Body.Close()
+				return fmt.Errorf("debrid reader: server ignored Range at offset %d (got 200)", r.pos)
+			}
+			r.body = resp.Body
+			r.bodyAt = r.pos
+			return nil
+		case http.StatusRequestedRangeNotSatisfiable:
+			resp.Body.Close()
+			return io.EOF // seeked past end — treat as EOF, not a hard error
+		case http.StatusUnauthorized, http.StatusForbidden, http.StatusNotFound, http.StatusGone:
+			// Expired/dead debrid link — re-resolve and retry with the fresh URL.
+			resp.Body.Close()
+			if _, rerr := r.prov.refreshURL(r.ctx); rerr != nil {
+				return fmt.Errorf("debrid reader: link expired (%d) and refresh failed: %w", resp.StatusCode, rerr)
+			}
+			continue
+		default:
+			resp.Body.Close()
+			return fmt.Errorf("debrid reader: unexpected status %d %s", resp.StatusCode, resp.Status)
+		}
+	}
+	return fmt.Errorf("debrid reader: link still failing after %d refresh attempts", maxAttempts)
+}
+
+// debridHeadSize issues a HEAD and returns the Content-Length when present.
+// Best-effort: any failure returns (0, false) so the caller falls back to the
+// size the web reported. A short timeout keeps a slow/HEAD-hostile CDN from
+// stalling session setup — the fallback size is good enough to start.
+func debridHeadSize(ctx context.Context, url string) (int64, bool) {
+	hctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(hctx, http.MethodHead, url, nil)
+	if err != nil {
+		return 0, false
+	}
+	resp, err := debridHTTPClient.Do(req)
+	if err != nil {
+		log.Printf("[stream] debrid HEAD failed (using fallback size): %v", err)
+		return 0, false
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK || resp.ContentLength <= 0 {
+		return 0, false
+	}
+	return resp.ContentLength, true
+}
+
+// debridNameFromURL extracts a filename from a URL path as a last resort when
+// the server didn't send one. Strips query/fragment via path.Base on the path.
+func debridNameFromURL(rawURL string) string {
+	u := rawURL
+	if i := strings.IndexAny(u, "?#"); i >= 0 {
+		u = u[:i]
+	}
+	base := path.Base(u)
+	if base == "" || base == "." || base == "/" {
+		return "video.mp4"
+	}
+	return base
+}

internal/engine/stream_source_debrid_test.go

@@ -0,0 +1,368 @@
+package engine
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// rangeServer serves a fixed byte slice with full HTTP Range support via
+// http.ServeContent (the same machinery a real debrid CDN exposes). Records
+// the number of GETs so a test can assert that a seek triggers exactly one
+// reopen rather than a full re-download.
+func rangeServer(data []byte) (*httptest.Server, *int) {
+	gets := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			gets++
+		}
+		http.ServeContent(w, r, "movie.mp4", time.Time{}, bytes.NewReader(data))
+	}))
+	return srv, &gets
+}
+
+func makeData(n int) []byte {
+	b := make([]byte, n)
+	for i := range b {
+		b[i] = byte(i % 251) // non-trivial, deterministic pattern
+	}
+	return b
+}
+
+func TestDebridProviderHeadSize(t *testing.T) {
+	data := makeData(4096)
+	srv, _ := rangeServer(data)
+	defer srv.Close()
+
+	// HEAD reports the real size; fallback is ignored when HEAD succeeds.
+	p, err := NewDebridFileProvider(context.Background(), srv.URL, "movie.mp4", 999, nil)
+	if err != nil {
+		t.Fatalf("NewDebridFileProvider: %v", err)
+	}
+	if got := p.FileSize(); got != int64(len(data)) {
+		t.Fatalf("FileSize from HEAD = %d, want %d", got, len(data))
+	}
+	if p.FileName() != "movie.mp4" {
+		t.Fatalf("FileName = %q, want movie.mp4", p.FileName())
+	}
+}
+
+func TestDebridProviderNameFromURLWhenNoExtension(t *testing.T) {
+	// The web may pass a torrent title with no extension (its file-name
+	// fallback). The provider must derive the name from the URL so the served
+	// Content-Type is video/mp4, not application/octet-stream.
+	data := makeData(1024)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.ServeContent(w, r, "x", time.Time{}, bytes.NewReader(data))
+	}))
+	defer srv.Close()
+	p, err := NewDebridFileProvider(context.Background(), srv.URL+"/Movie.2026.1080p.mp4?token=abc", "Project Hail Mary (2026) 1080p web", 0, nil)
+	if err != nil {
+		t.Fatalf("provider: %v", err)
+	}
+	if got := p.FileName(); got != "Movie.2026.1080p.mp4" {
+		t.Fatalf("FileName = %q, want Movie.2026.1080p.mp4 (derived from URL)", got)
+	}
+	// A passed name WITH an extension is kept as-is.
+	p2, _ := NewDebridFileProvider(context.Background(), srv.URL+"/whatever.mp4", "Nice Title.mp4", 0, nil)
+	if got := p2.FileName(); got != "Nice Title.mp4" {
+		t.Fatalf("FileName = %q, want Nice Title.mp4 (kept)", got)
+	}
+}
+
+func TestDebridProviderFallbackSizeWhenNoHead(t *testing.T) {
+	// Server that refuses HEAD (405) but serves GET — provider must fall back
+	// to the size the web reported.
+	data := makeData(2048)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodHead {
+			w.WriteHeader(http.StatusMethodNotAllowed)
+			return
+		}
+		http.ServeContent(w, r, "movie.mp4", time.Time{}, bytes.NewReader(data))
+	}))
+	defer srv.Close()
+
+	p, err := NewDebridFileProvider(context.Background(), srv.URL, "movie.mp4", int64(len(data)), nil)
+	if err != nil {
+		t.Fatalf("NewDebridFileProvider: %v", err)
+	}
+	if got := p.FileSize(); got != int64(len(data)) {
+		t.Fatalf("FileSize fallback = %d, want %d", got, len(data))
+	}
+}
+
+func TestDebridProviderNoSizeFails(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusMethodNotAllowed) // no HEAD, no usable GET
+	}))
+	defer srv.Close()
+	// No HEAD size and fallback 0 → must error (ServeContent can't range-serve
+	// size 0 without handing the browser an empty file).
+	if _, err := NewDebridFileProvider(context.Background(), srv.URL, "", 0, nil); err == nil {
+		t.Fatal("expected error when size is unknown, got nil")
+	}
+	if _, err := NewDebridFileProvider(context.Background(), "", "movie.mp4", 100, nil); err == nil {
+		t.Fatal("expected error for empty URL, got nil")
+	}
+}
+
+func TestDebridReaderSequentialRead(t *testing.T) {
+	data := makeData(100_000)
+	srv, gets := rangeServer(data)
+	defer srv.Close()
+
+	p, err := NewDebridFileProvider(context.Background(), srv.URL, "movie.mp4", 0, nil)
+	if err != nil {
+		t.Fatalf("provider: %v", err)
+	}
+	rd := p.NewFileReader(context.Background())
+	defer rd.Close()
+
+	got, err := io.ReadAll(rd)
+	if err != nil {
+		t.Fatalf("ReadAll: %v", err)
+	}
+	if !bytes.Equal(got, data) {
+		t.Fatalf("sequential read mismatch: got %d bytes, want %d", len(got), len(data))
+	}
+	// A pure sequential read holds a single body to EOF → exactly one GET.
+	if *gets != 1 {
+		t.Fatalf("sequential read issued %d GETs, want 1", *gets)
+	}
+}
+
+func TestDebridReaderSeekEndReportsSize(t *testing.T) {
+	data := makeData(5000)
+	srv, _ := rangeServer(data)
+	defer srv.Close()
+	p, _ := NewDebridFileProvider(context.Background(), srv.URL, "movie.mp4", 0, nil)
+	rd := p.NewFileReader(context.Background())
+	defer rd.Close()
+
+	// http.ServeContent calls Seek(0, SeekEnd) to learn the size — must be
+	// network-free and return the total.
+	size, err := rd.Seek(0, io.SeekEnd)
+	if err != nil {
+		t.Fatalf("Seek end: %v", err)
+	}
+	if size != int64(len(data)) {
+		t.Fatalf("SeekEnd = %d, want %d", size, len(data))
+	}
+}
+
+func TestDebridReaderSeekThenRead(t *testing.T) {
+	data := makeData(50_000)
+	srv, gets := rangeServer(data)
+	defer srv.Close()
+	p, _ := NewDebridFileProvider(context.Background(), srv.URL, "movie.mp4", 0, nil)
+	rd := p.NewFileReader(context.Background())
+	defer rd.Close()
+
+	const off = 12_345
+	if _, err := rd.Seek(off, io.SeekStart); err != nil {
+		t.Fatalf("seek: %v", err)
+	}
+	got, err := io.ReadAll(rd)
+	if err != nil {
+		t.Fatalf("ReadAll after seek: %v", err)
+	}
+	if !bytes.Equal(got, data[off:]) {
+		t.Fatalf("tail mismatch: got %d bytes, want %d", len(got), len(data)-off)
+	}
+	// Seek is network-free; the read after it is the only GET.
+	if *gets != 1 {
+		t.Fatalf("seek+read issued %d GETs, want 1", *gets)
+	}
+}
+
+func TestDebridReaderServeContentRoundTrip(t *testing.T) {
+	// Drive the reader exactly like StreamServer does: hand it to
+	// http.ServeContent and issue a ranged request. Verifies the reader is a
+	// correct io.ReadSeeker for the production serving path.
+	data := makeData(80_000)
+	srv, _ := rangeServer(data)
+	defer srv.Close()
+	p, _ := NewDebridFileProvider(context.Background(), srv.URL, "movie.mp4", 0, nil)
+
+	front := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		rd := p.NewFileReader(r.Context())
+		defer rd.Close()
+		http.ServeContent(w, r, p.FileName(), time.Time{}, rd)
+	}))
+	defer front.Close()
+
+	req, _ := http.NewRequest(http.MethodGet, front.URL, nil)
+	req.Header.Set("Range", "bytes=10000-19999")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("ranged GET: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusPartialContent {
+		t.Fatalf("status = %d, want 206", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	want := data[10000:20000]
+	if !bytes.Equal(body, want) {
+		t.Fatalf("ranged body mismatch: got %d bytes", len(body))
+	}
+}
+
+func TestDebridReaderSeekPastEnd(t *testing.T) {
+	data := makeData(1000)
+	srv, _ := rangeServer(data)
+	defer srv.Close()
+	p, _ := NewDebridFileProvider(context.Background(), srv.URL, "movie.mp4", 0, nil)
+	rd := p.NewFileReader(context.Background())
+	defer rd.Close()
+
+	// Seeking at/past size then reading yields EOF, no error, no bytes.
+	if _, err := rd.Seek(int64(len(data)), io.SeekStart); err != nil {
+		t.Fatalf("seek: %v", err)
+	}
+	n, err := rd.Read(make([]byte, 16))
+	if n != 0 || err != io.EOF {
+		t.Fatalf("read past end = (%d, %v), want (0, EOF)", n, err)
+	}
+}
+
+// hueco #2 / 2c — an expired link (401) is recovered by re-resolving a fresh
+// URL via the refresh callback and retrying, transparent to the reader.
+func TestDebridReaderRefreshOnExpiry(t *testing.T) {
+	data := makeData(20_000)
+	live, _ := rangeServer(data)
+	defer live.Close()
+	expired := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized) // link expired
+	}))
+	defer expired.Close()
+
+	refreshed := 0
+	refresh := func(_ context.Context) (string, error) {
+		refreshed++
+		return live.URL, nil
+	}
+	// HEAD on the expired URL 401s → falls back to the provided size.
+	p, err := NewDebridFileProvider(context.Background(), expired.URL, "movie.mp4", int64(len(data)), refresh)
+	if err != nil {
+		t.Fatalf("provider: %v", err)
+	}
+	rd := p.NewFileReader(context.Background())
+	defer rd.Close()
+
+	got, err := io.ReadAll(rd)
+	if err != nil {
+		t.Fatalf("ReadAll after expiry+refresh: %v", err)
+	}
+	if !bytes.Equal(got, data) {
+		t.Fatalf("post-refresh read mismatch: got %d bytes, want %d", len(got), len(data))
+	}
+	if refreshed == 0 {
+		t.Fatal("expected the reader to refresh the expired URL")
+	}
+}
+
+// Coalescing: when N readers hit an expired link at once, only ONE refresh
+// runs (singleflight) and they all share its result — not N re-resolutions
+// hammering the web (hueco #2 / 2c).
+func TestDebridProviderRefreshCoalesces(t *testing.T) {
+	data := makeData(8000)
+	live, _ := rangeServer(data)
+	defer live.Close()
+
+	var refreshCalls int64
+	refresh := func(_ context.Context) (string, error) {
+		atomic.AddInt64(&refreshCalls, 1)
+		time.Sleep(80 * time.Millisecond) // simulate a slow re-resolution
+		return live.URL, nil
+	}
+	p := &debridFileProvider{url: "https://expired.invalid/x.mp4", refresh: refresh}
+
+	const N = 8
+	var wg sync.WaitGroup
+	errs := make([]error, N)
+	for i := 0; i < N; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			_, errs[i] = p.refreshURL(context.Background())
+		}(i)
+	}
+	wg.Wait()
+
+	for i, err := range errs {
+		if err != nil {
+			t.Fatalf("reader %d refresh failed: %v", i, err)
+		}
+	}
+	if got := atomic.LoadInt64(&refreshCalls); got != 1 {
+		t.Fatalf("expected 1 coalesced refresh for %d concurrent readers, got %d", N, got)
+	}
+	if p.currentURL() != live.URL {
+		t.Fatalf("provider URL = %q, want the refreshed live URL", p.currentURL())
+	}
+}
+
+func TestDebridReaderRefreshFailsSurfacesError(t *testing.T) {
+	expired := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+	}))
+	defer expired.Close()
+	refresh := func(_ context.Context) (string, error) {
+		return "", errors.New("debrid gone")
+	}
+	p, _ := NewDebridFileProvider(context.Background(), expired.URL, "movie.mp4", 1000, refresh)
+	rd := p.NewFileReader(context.Background())
+	defer rd.Close()
+	if _, err := rd.Read(make([]byte, 16)); err == nil {
+		t.Fatal("expected an error when refresh fails, got nil")
+	}
+}
+
+func TestDebridReaderNoRefresherExpiryIsHardError(t *testing.T) {
+	// refresh == nil (2a behaviour): an expired link is a hard error, no retry.
+	expired := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusGone)
+	}))
+	defer expired.Close()
+	p, _ := NewDebridFileProvider(context.Background(), expired.URL, "movie.mp4", 1000, nil)
+	rd := p.NewFileReader(context.Background())
+	defer rd.Close()
+	if _, err := rd.Read(make([]byte, 16)); err == nil {
+		t.Fatal("expected a hard error with no refresher, got nil")
+	}
+}
+
+func TestDebridReaderRejectsServerIgnoringRange(t *testing.T) {
+	// A server that always returns 200 (ignores Range) is only safe at pos 0.
+	// A reopen at a non-zero offset (after a seek) must error rather than serve
+	// misaligned bytes.
+	data := makeData(4000)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Length", "4000")
+		w.WriteHeader(http.StatusOK)
+		w.Write(data)
+	}))
+	defer srv.Close()
+	p, err := NewDebridFileProvider(context.Background(), srv.URL, "movie.mp4", int64(len(data)), nil)
+	if err != nil {
+		t.Fatalf("provider: %v", err)
+	}
+	rd := p.NewFileReader(context.Background())
+	defer rd.Close()
+
+	if _, err := rd.Seek(1000, io.SeekStart); err != nil {
+		t.Fatalf("seek: %v", err)
+	}
+	if _, err := rd.Read(make([]byte, 16)); err == nil {
+		t.Fatal("expected error when server ignores Range at non-zero offset, got nil")
+	}
+}

internal/engine/stream_token.go

@@ -0,0 +1,94 @@
+package engine
+
+import (
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/hex"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Stream authentication.
+//
+// /stream and /hls have no header-based auth: a <video src> cannot attach an
+// Authorization header, and media-tag/segment requests are issued by the
+// browser, not our JS. So we bind a short-lived, unforgeable token to each
+// stream URL the daemon hands out and verify it on every request.
+//
+// The token is HMAC-signed by the daemon's own in-memory secret — there is no
+// server-side token store and no DB column. The web is a pure pass-through: it
+// stores and serves whatever tokenised URL the agent reports.
+//
+//   - /stream (+ VLC playlist): token rides as a `?t=` query parameter.
+//   - /hls: token rides as a PATH segment — /hls/<sessionID>/<token>/<resource>
+//     — so the relative child URIs inside the playlists (video/index.m3u8,
+//     seg-N.m4s, subs/…) resolve under the same prefix and carry the token
+//     automatically, with zero playlist rewriting.
+//
+// There is NO loopback exemption: the Cloudflare funnel proxies public traffic
+// to the daemon over localhost (cloudflared --url http://localhost:<port>), so
+// a loopback source address is NOT a trust signal — exempting it would leave the
+// funnel (the headline public path) wide open. Every URL the agent/web hands a
+// player is already tokenised (URL(), URLsJSON, buildHlsUrls), so enforcing the
+// token unconditionally breaks no legitimate client. /health stays ungated (a
+// reachability probe that leaks nothing sensitive).
+
+const (
+	// streamTokenTTL is how long a minted token stays valid. Long enough for a
+	// movie plus pauses; short enough that a leaked URL stops working same-day.
+	streamTokenTTL = 6 * time.Hour
+
+	// streamScopeStream is the token scope for the single-file /stream endpoint.
+	streamScopeStream = "stream"
+)
+
+// streamScopeHLS is the token scope for an HLS session. Binding to the session
+// id means a token minted for one session never validates another.
+func streamScopeHLS(sessionID string) string { return "hls:" + sessionID }
+
+// newStreamSecret returns 32 cryptographically-random bytes used to sign stream
+// tokens for the lifetime of the daemon. Regenerated each start, so tokens from
+// a previous run stop validating (the web re-resolves the URL on demand).
+func newStreamSecret() []byte {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		// crypto/rand.Read does not fail on supported platforms. If it ever
+		// does, fail hard rather than fall back to a predictable key while still
+		// claiming to enforce auth — a guessable key is worse than no streaming.
+		panic("unarr: crypto/rand unavailable, cannot generate stream secret: " + err.Error())
+	}
+	return b
+}
+
+// mintStreamToken issues `<expUnix>.<hexHMAC>` binding scope to an expiry.
+// Verification needs only the same secret + scope.
+func mintStreamToken(secret []byte, scope string, now time.Time) string {
+	expStr := strconv.FormatInt(now.Add(streamTokenTTL).Unix(), 10)
+	return expStr + "." + streamTokenMAC(secret, scope, expStr)
+}
+
+func streamTokenMAC(secret []byte, scope, expStr string) string {
+	m := hmac.New(sha256.New, secret)
+	m.Write([]byte(scope + ":" + expStr))
+	return hex.EncodeToString(m.Sum(nil))
+}
+
+// verifyStreamToken reports whether token is a valid, unexpired signature for
+// scope under secret. Cheap rejects (format, expiry) happen before the
+// constant-time MAC compare since they don't depend on the secret.
+func verifyStreamToken(secret []byte, scope, token string, now time.Time) bool {
+	dot := strings.IndexByte(token, '.')
+	if dot <= 0 || dot >= len(token)-1 {
+		return false
+	}
+	expStr, gotMAC := token[:dot], token[dot+1:]
+	exp, err := strconv.ParseInt(expStr, 10, 64)
+	if err != nil || now.Unix() > exp {
+		return false
+	}
+	wantMAC := streamTokenMAC(secret, scope, expStr)
+	return subtle.ConstantTimeCompare([]byte(gotMAC), []byte(wantMAC)) == 1
+}

internal/engine/stream_token_test.go

@@ -0,0 +1,224 @@
+package engine
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestStreamToken_RoundTrip(t *testing.T) {
+	secret := newStreamSecret()
+	now := time.Now()
+	tok := mintStreamToken(secret, streamScopeStream, now)
+	if !verifyStreamToken(secret, streamScopeStream, tok, now) {
+		t.Fatalf("freshly minted token failed to verify: %q", tok)
+	}
+	// Still valid just before expiry.
+	if !verifyStreamToken(secret, streamScopeStream, tok, now.Add(streamTokenTTL-time.Minute)) {
+		t.Error("token rejected before its TTL elapsed")
+	}
+}
+
+func TestStreamToken_Expired(t *testing.T) {
+	secret := newStreamSecret()
+	now := time.Now()
+	tok := mintStreamToken(secret, streamScopeStream, now)
+	if verifyStreamToken(secret, streamScopeStream, tok, now.Add(streamTokenTTL+time.Second)) {
+		t.Error("expired token verified as valid")
+	}
+}
+
+func TestStreamToken_WrongScope(t *testing.T) {
+	secret := newStreamSecret()
+	now := time.Now()
+	tok := mintStreamToken(secret, streamScopeHLS("abc"), now)
+	if verifyStreamToken(secret, streamScopeStream, tok, now) {
+		t.Error("token for one scope verified under another")
+	}
+	if verifyStreamToken(secret, streamScopeHLS("xyz"), tok, now) {
+		t.Error("hls token verified for a different session id")
+	}
+	if !verifyStreamToken(secret, streamScopeHLS("abc"), tok, now) {
+		t.Error("hls token failed to verify under its own session id")
+	}
+}
+
+func TestStreamToken_WrongSecret(t *testing.T) {
+	now := time.Now()
+	tok := mintStreamToken(newStreamSecret(), streamScopeStream, now)
+	if verifyStreamToken(newStreamSecret(), streamScopeStream, tok, now) {
+		t.Error("token verified under a different secret")
+	}
+}
+
+func TestStreamToken_Tampered(t *testing.T) {
+	secret := newStreamSecret()
+	now := time.Now()
+	tok := mintStreamToken(secret, streamScopeStream, now)
+	// Flip the last hex char of the MAC.
+	last := tok[len(tok)-1]
+	flip := byte('0')
+	if last == '0' {
+		flip = '1'
+	}
+	tampered := tok[:len(tok)-1] + string(flip)
+	if verifyStreamToken(secret, streamScopeStream, tampered, now) {
+		t.Error("tampered MAC verified as valid")
+	}
+}
+
+func TestStreamToken_Malformed(t *testing.T) {
+	secret := newStreamSecret()
+	now := time.Now()
+	for _, bad := range []string{
+		"",
+		"nodot",
+		"123.",         // empty MAC
+		".deadbeef",    // empty exp
+		"notanint.abc", // non-numeric exp
+		".",
+	} {
+		if verifyStreamToken(secret, streamScopeStream, bad, now) {
+			t.Errorf("malformed token %q verified as valid", bad)
+		}
+	}
+}
+
+// TestVerifyStreamToken_CrossLangVector pins the wire format against the web's
+// TypeScript minter (tests/unit/stream-token.test.ts asserts the same vector).
+// A token the web mints MUST verify here or remote HLS playback 404s.
+func TestVerifyStreamToken_CrossLangVector(t *testing.T) {
+	secret := make([]byte, 32)
+	for i := range secret {
+		secret[i] = 0xab // matches secretHex "ab"*32 on the web side
+	}
+	const (
+		sessionID = "sess-1"
+		token     = "1900000000.3ee840ccf2c2a42b784d7cef68458db1d3cea5ecdcab41061504de32eb52fbc2"
+	)
+	before := time.Unix(1899978400, 0) // before exp 1900000000
+	if !verifyStreamToken(secret, streamScopeHLS(sessionID), token, before) {
+		t.Fatal("web-minted parity token failed to verify in the daemon")
+	}
+	after := time.Unix(1900000001, 0) // past exp
+	if verifyStreamToken(secret, streamScopeHLS(sessionID), token, after) {
+		t.Error("parity token verified past its expiry")
+	}
+}
+
+func TestNewStreamSecret_LengthAndUniqueness(t *testing.T) {
+	a, b := newStreamSecret(), newStreamSecret()
+	if len(a) != 32 {
+		t.Errorf("secret length = %d, want 32", len(a))
+	}
+	if string(a) == string(b) {
+		t.Error("two secrets were identical — not random")
+	}
+}
+
+// --- /stream handler enforcement ---------------------------------------------
+
+func streamReq(remoteAddr, query string) *http.Request {
+	r := httptest.NewRequest(http.MethodGet, "http://stream.test/stream"+query, nil)
+	r.RemoteAddr = remoteAddr
+	return r
+}
+
+func newServedServer(t *testing.T) *StreamServer {
+	t.Helper()
+	srv := NewStreamServer(0)
+	srv.SetFile(newFakeProvider("movie.mkv", []byte("fake video bytes")), "task-1")
+	return srv
+}
+
+func TestStreamHandler_RemoteWithoutToken_404(t *testing.T) {
+	srv := newServedServer(t)
+	rec := httptest.NewRecorder()
+	srv.handler(rec, streamReq("198.51.100.7:40000", ""))
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("remote request without token: status = %d, want 404", rec.Code)
+	}
+}
+
+func TestStreamHandler_RemoteValidToken_200(t *testing.T) {
+	srv := newServedServer(t)
+	tok := mintStreamToken(srv.streamSecret, streamScopeStream, time.Now())
+	rec := httptest.NewRecorder()
+	srv.handler(rec, streamReq("198.51.100.7:40000", "?t="+tok))
+	if rec.Code != http.StatusOK {
+		t.Errorf("remote request with valid token: status = %d, want 200", rec.Code)
+	}
+}
+
+func TestStreamHandler_RemoteBadToken_404(t *testing.T) {
+	srv := newServedServer(t)
+	rec := httptest.NewRecorder()
+	srv.handler(rec, streamReq("198.51.100.7:40000", "?t=deadbeef.0000"))
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("remote request with bad token: status = %d, want 404", rec.Code)
+	}
+}
+
+func TestStreamHandler_LoopbackWithoutToken_404(t *testing.T) {
+	// No loopback exemption: cloudflared relays public funnel traffic over
+	// localhost, so loopback must still present a valid token.
+	srv := newServedServer(t)
+	rec := httptest.NewRecorder()
+	srv.handler(rec, streamReq("127.0.0.1:55555", ""))
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("loopback request without token: status = %d, want 404 (no exemption)", rec.Code)
+	}
+}
+
+func TestStreamHandler_LoopbackWithValidToken_200(t *testing.T) {
+	srv := newServedServer(t)
+	tok := mintStreamToken(srv.streamSecret, streamScopeStream, time.Now())
+	rec := httptest.NewRecorder()
+	srv.handler(rec, streamReq("127.0.0.1:55555", "?t="+tok))
+	if rec.Code != http.StatusOK {
+		t.Errorf("loopback request with valid token: status = %d, want 200", rec.Code)
+	}
+}
+
+func TestStreamHandler_EnforcementOff_NoToken_200(t *testing.T) {
+	srv := newServedServer(t)
+	srv.SetRequireStreamToken(false)
+	rec := httptest.NewRecorder()
+	srv.handler(rec, streamReq("198.51.100.7:40000", ""))
+	if rec.Code != http.StatusOK {
+		t.Errorf("enforcement off: status = %d, want 200", rec.Code)
+	}
+}
+
+// --- /hls handler enforcement ------------------------------------------------
+
+func TestHLSHandler_RemoteBadToken_404(t *testing.T) {
+	srv := NewStreamServer(0)
+	// A syntactically valid session id (UUID-ish) with a bogus token segment.
+	const sess = "11111111-1111-4111-8111-111111111111"
+	r := httptest.NewRequest(http.MethodGet, "http://stream.test/hls/"+sess+"/badtoken/master.m3u8", nil)
+	r.RemoteAddr = "198.51.100.7:40000"
+	rec := httptest.NewRecorder()
+	srv.hlsHandler(rec, r)
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("remote hls with bad token: status = %d, want 404", rec.Code)
+	}
+}
+
+func TestHLSBaseURLs_CarryTokenSegment(t *testing.T) {
+	srv := NewStreamServer(0)
+	srv.urls.LAN = "http://192.168.1.2:11818/stream"
+	const sess = "22222222-2222-4222-8222-222222222222"
+	urls := srv.hlsBaseURLs(sess)
+	prefix := "http://192.168.1.2:11818/hls/" + sess + "/"
+	if !strings.HasPrefix(urls.LAN, prefix) || len(urls.LAN) <= len(prefix) {
+		t.Errorf("hls LAN url = %q, want token segment after %q", urls.LAN, prefix)
+	}
+	// The trailing segment must be a verifiable hls-scoped token.
+	tok := strings.TrimPrefix(urls.LAN, prefix)
+	if !verifyStreamToken(srv.streamSecret, streamScopeHLS(sess), tok, time.Now()) {
+		t.Errorf("token segment %q does not verify for session %s", tok, sess)
+	}
+}

internal/engine/transcoder.go

@@ -27,6 +27,11 @@ type TranscodeOpts struct {
 	SourceHeight int    // probed source height — used to derive a sane H.264 level
 	StartSeconds float64
 	FFmpegPath   string
+	// VideoTag forces the output stream's codec tag on a copy remux. HEVC muxed
+	// into MP4 must carry the `hvc1` tag (not the default `hev1`) or Safari /
+	// Apple devices refuse to decode it. Empty = leave ffmpeg's default. Only
+	// applied on copy actions (passthrough/remux); a real re-encode sets its own.
+	VideoTag string
 }
 
 // Transcoder wraps a long-running ffmpeg child process whose stdout streams
@@ -222,8 +227,16 @@ func buildFFmpegArgs(filePath string, opts TranscodeOpts) []string {
 	switch opts.Action {
 	case ActionPassthrough, ActionRemux:
 		args = append(args, "-c:v", "copy", "-c:a", "copy")
+		// HEVC → MP4 needs the hvc1 tag for Apple/Safari (hueco #3 / 3c).
+		if opts.VideoTag != "" {
+			args = append(args, "-tag:v", opts.VideoTag)
+		}
 	case ActionRemuxAudio:
-		args = append(args, "-c:v", "copy", "-c:a", "aac", "-b:a", coalesce(opts.AudioBitrate, "192k"))
+		args = append(args, "-c:v", "copy")
+		if opts.VideoTag != "" {
+			args = append(args, "-tag:v", opts.VideoTag) // HEVC → hvc1 for Apple
+		}
+		args = append(args, "-c:a", "aac", "-b:a", coalesce(opts.AudioBitrate, "192k"))
 	case ActionTranscodeVideo:
 		videoCodec := opts.HWAccel.FFmpegVideoCodec("h264")
 		args = append(args, "-c:v", videoCodec)

internal/engine/validate.go

@@ -36,6 +36,11 @@ var defaultCORSAllowedOrigins = []string{
 	"https://staging.torrentclaw.com",
 	"https://torrentclaw.to",
 	"https://www.torrentclaw.to",
+	// unarr brand (separate deployment). The web player + agent endpoints run
+	// under unarr.app; without these the browser drops every /hls + /stream
+	// response (no Access-Control-Allow-Origin) and playback fails on unarr.
+	"https://unarr.app",
+	"https://www.unarr.app",
 	// Tor mirror — Tor Browser sends `Origin: http://<addr>.onion` (plain
 	// http, no port). Mirror address is the BUILT_IN_ONION constant from
 	// torrentclaw-web/src/lib/mirrors-config.ts; rotates rarely, kept in

internal/library/mediainfo/ffprobe.go

@@ -67,8 +67,14 @@ func ExtractMediaInfo(ctx context.Context, ffprobePath, filePath string) (*Media
 
 	output, err := cmd.Output()
 	if err != nil {
-		if _, statErr := os.Stat(filePath); statErr != nil {
-			return nil, fmt.Errorf("ffprobe: file not found: %s", filePath)
+		// A remote URL (debrid HLS-from-URL, hueco #2/2b) has no local file to
+		// stat — surface ffprobe's own stderr (e.g. "Protocol not found" when the
+		// ffmpeg build lacks TLS, or an HTTP error) instead of a misleading
+		// "file not found". Only treat a genuine local path as possibly-missing.
+		if !strings.Contains(filePath, "://") {
+			if _, statErr := os.Stat(filePath); statErr != nil {
+				return nil, fmt.Errorf("ffprobe: file not found: %s", filePath)
+			}
 		}
 		return nil, fmt.Errorf("ffprobe failed (file=%s): %s", filePath, stderr.String())
 	}