diff --git a/.forgejo/workflows/ci.yml b/.forgejo/workflows/ci.yml
new file mode 100644
index 0000000..82ee799
--- /dev/null
+++ b/.forgejo/workflows/ci.yml
@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run tests
+        run: go test -v -race -count=1 ./...
+
+  build:
+    name: Build
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
+    strategy:
+      matrix:
+        goos: [linux, darwin, windows]
+        goarch: [amd64, arm64]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+        run: go build -o unarr ./cmd/unarr/
+
+  lint:
+    name: Lint
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install golangci-lint
+        run: |
+          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/v2.11.4/install.sh \
+            | sh -s -- -b /usr/local/bin v2.11.4
+
+      - name: Run golangci-lint
+        run: golangci-lint run ./...
+
+  coverage:
+    name: Coverage
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install python3
+        run: apt-get update && apt-get install -y --no-install-recommends python3
+
+      - name: Run tests with coverage (all packages)
+        run: |
+          go test -race -coverprofile=coverage.out -covermode=atomic \
+            ./internal/engine/... \
+            ./internal/agent/... \
+            ./internal/cmd/...
+
+      - name: Check coverage threshold (engine + agent)
+        run: |
+          # Threshold applies only to engine and agent — cmd contains interactive UI
+          # commands (config menus, daemon, auth browser) that are not unit-testable.
+          go test -race -coverprofile=coverage-core.out -covermode=atomic \
+            ./internal/engine/... \
+            ./internal/agent/...
+          COVERAGE=$(go tool cover -func=coverage-core.out | grep ^total | awk '{print $3}' | tr -d '%')
+          echo "Coverage on engine+agent: ${COVERAGE}%"
+          python3 -c "
+          coverage = float('${COVERAGE}')
+          threshold = 50.0
+          print(f'Coverage: {coverage:.1f}% (threshold: {threshold}%)')
+          if coverage < threshold:
+              print(f'ERROR: Coverage {coverage:.1f}% is below minimum {threshold}%')
+              exit(1)
+          else:
+              print('OK: Coverage meets minimum threshold')
+          "
+
+  vet:
+    name: Vet
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run go vet
+        run: go vet ./...
diff --git a/.forgejo/workflows/docker-rebuild.yml b/.forgejo/workflows/docker-rebuild.yml
new file mode 100644
index 0000000..34cc3d6
--- /dev/null
+++ b/.forgejo/workflows/docker-rebuild.yml
@@ -0,0 +1,61 @@
+# Rebuilds and re-pushes the `latest` image without a version bump so newly
+# *fixed* Alpine / ffmpeg / Go patches land between tagged releases. Versioned
+# tags are immutable and never touched here. Runs weekly and on demand.
+name: Docker rebuild
+
+on:
+  schedule:
+    # Mondays 04:17 UTC (off the hour to avoid the scheduler rush)
+    - cron: "17 4 * * 1"
+  workflow_dispatch:
+
+jobs:
+  rebuild:
+    runs-on: docker
+    container:
+      image: docker.io/library/docker:27-cli
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install build deps
+        run: apk add --no-cache curl git bash
+
+      - name: Install buildx
+        run: |
+          mkdir -p ~/.docker/cli-plugins
+          curl -sSL https://github.com/docker/buildx/releases/latest/download/buildx-linux-amd64 \
+            -o ~/.docker/cli-plugins/docker-buildx
+          chmod +x ~/.docker/cli-plugins/docker-buildx
+
+      - name: Set up qemu
+        run: docker run --rm --privileged tonistiigi/binfmt --install all
+
+      # Stamp the binary with the most recent release tag (not "dev").
+      - name: Resolve version
+        id: ver
+        run: |
+          v=$(git describe --tags --abbrev=0 2>/dev/null || echo dev)
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+
+      - name: Login to Docker Hub
+        env:
+          DH_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+          DH_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+        run: echo "$DH_TOKEN" | docker login -u "$DH_USER" --password-stdin
+
+      - name: Build + push (refresh latest)
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          docker buildx create --name builder --use --driver docker-container
+          # Refresh the floating tag only — never overwrite a versioned release.
+          # Force a fresh base pull so apk upgrade picks up new patches.
+          docker buildx build \
+            --platform linux/amd64,linux/arm64 \
+            --build-arg "VERSION=$VERSION" \
+            --tag "torrentclaw/unarr:latest" \
+            --no-cache \
+            --push \
+            .
diff --git a/.forgejo/workflows/release.yml b/.forgejo/workflows/release.yml
new file mode 100644
index 0000000..d757612
--- /dev/null
+++ b/.forgejo/workflows/release.yml
@@ -0,0 +1,118 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: docker
+    container:
+      image: docker.io/library/golang:1.25
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install build deps (bash, curl, jq, ffmpeg fetch deps)
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends bash curl ca-certificates jq xz-utils unzip
+
+      - name: Install goreleaser
+        run: |
+          curl -sSfL https://github.com/goreleaser/goreleaser/releases/latest/download/goreleaser_Linux_x86_64.tar.gz \
+            | tar -xz -C /usr/local/bin goreleaser
+
+      - name: Run goreleaser
+        env:
+          # Forgejo runner auto-injects GITHUB_TOKEN (a per-job, instance-scoped
+          # token usable against the Forgejo REST API). goreleaser only accepts
+          # one token; with both GITHUB_TOKEN + GITEA_TOKEN set it errors out
+          # ("multiple tokens"). Unset GITHUB_TOKEN before invoking goreleaser so
+          # it picks the Gitea code path + the gitea_urls block in .goreleaser.yml.
+          GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          # Empty when RELEASE_SIGNING_PUBKEY variable is unset — goreleaser
+          # accepts it and the resulting binary disables signature checks
+          # (back-compat: pre-signing releases continue to update). Set
+          # RELEASE_SIGNING_PUBKEY (variable) + RELEASE_SIGNING_KEY (secret)
+          # to turn verification on.
+          RELEASE_SIGNING_PUBKEY: ${{ vars.RELEASE_SIGNING_PUBKEY }}
+        run: |
+          unset GITHUB_TOKEN
+          goreleaser release --clean
+
+      - name: Sign checksums.txt with ed25519
+        if: ${{ vars.RELEASE_SIGNING_PUBKEY != '' && secrets.RELEASE_SIGNING_KEY != '' }}
+        env:
+          RELEASE_SIGNING_KEY: ${{ secrets.RELEASE_SIGNING_KEY }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          FORGEJO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Tailscale IP — domain-agnostic; the runner shares the dokploy-network with
+          # forgejo (hostname `forgejo`), so the in-cluster hostname is fastest, but the
+          # Tailscale IP is the documented fallback.
+          FORGEJO_API: http://forgejo:3000/api/v1
+          REPO: torrentclaw/unarr
+        run: |
+          set -euo pipefail
+          go run ./scripts/sign-checksums \
+            -key "$RELEASE_SIGNING_KEY" \
+            -in  dist/checksums.txt \
+            -out dist/checksums.txt.sig
+
+          # Find the release ID for this tag, then upload the sig as an asset.
+          rel_id=$(curl -sSf "$FORGEJO_API/repos/$REPO/releases/tags/$RELEASE_TAG" \
+            -H "Authorization: token $FORGEJO_TOKEN" | jq -r '.id')
+          curl -sSf -X POST \
+            "$FORGEJO_API/repos/$REPO/releases/$rel_id/assets?name=checksums.txt.sig" \
+            -H "Authorization: token $FORGEJO_TOKEN" \
+            -F "attachment=@dist/checksums.txt.sig"
+
+  docker:
+    needs: release
+    runs-on: docker
+    container:
+      # Docker-in-Docker capable image — buildx + qemu pre-installed.
+      image: docker.io/library/docker:27-cli
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install buildx
+        run: |
+          apk add --no-cache curl
+          mkdir -p ~/.docker/cli-plugins
+          curl -sSL https://github.com/docker/buildx/releases/latest/download/buildx-linux-amd64 \
+            -o ~/.docker/cli-plugins/docker-buildx
+          chmod +x ~/.docker/cli-plugins/docker-buildx
+
+      - name: Login to Docker Hub
+        env:
+          DH_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+          DH_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+        run: echo "$DH_TOKEN" | docker login -u "$DH_USER" --password-stdin
+
+      - name: Set up qemu
+        run: docker run --rm --privileged tonistiigi/binfmt --install all
+
+      - name: Build + push multi-arch image
+        env:
+          VERSION: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          VERSION_SEMVER="${VERSION#v}"
+          MAJOR_MINOR="${VERSION_SEMVER%.*}"
+          docker buildx create --name builder --use --driver docker-container
+          docker buildx build \
+            --platform linux/amd64,linux/arm64 \
+            --build-arg "VERSION=$VERSION" \
+            --tag "torrentclaw/unarr:$VERSION_SEMVER" \
+            --tag "torrentclaw/unarr:$MAJOR_MINOR" \
+            --tag "torrentclaw/unarr:latest" \
+            --push \
+            .
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
deleted file mode 100644
index e9d5ea0..0000000
--- a/.github/workflows/ci.yml
+++ /dev/null
@@ -1,101 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    name: Test
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        go-version: ["1.25", "1.26"]
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version: ${{ matrix.go-version }}
-
-      - name: Run tests
-        run: go test -v -race -count=1 ./...
-
-  build:
-    name: Build
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        goos: [linux, darwin, windows]
-        goarch: [amd64, arm64]
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version: "1.25"
-
-      - name: Build
-        env:
-          GOOS: ${{ matrix.goos }}
-          GOARCH: ${{ matrix.goarch }}
-        run: go build -o unarr ./cmd/unarr/
-
-  lint:
-    name: Lint
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version: "1.25"
-
-      - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@v9
-        with:
-          version: v2.11.3
-
-  coverage:
-    name: Coverage
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version: "1.25"
-
-      - name: Run tests with coverage
-        run: go test -race -coverprofile=coverage.out -covermode=atomic ./...
-
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
-        with:
-          files: ./coverage.out
-          fail_ci_if_error: false
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
-  vet:
-    name: Vet
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Set up Go
-        uses: actions/setup-go@v6
-        with:
-          go-version: "1.25"
-
-      - name: Run go vet
-        run: go vet ./...
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
deleted file mode 100644
index e6ba0ba..0000000
--- a/.github/workflows/release.yml
+++ /dev/null
@@ -1,162 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags:
-      - "v*"
-
-permissions:
-  contents: write
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-go@v5
-        with:
-          go-version-file: go.mod
-
-      - uses: goreleaser/goreleaser-action@v6
-        with:
-          version: "~> v2"
-          args: release --clean
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
-
-  docker:
-    needs: release
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Docker meta
-        id: meta
-        uses: docker/metadata-action@v6
-        with:
-          images: torrentclaw/unarr
-          tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=raw,value=latest
-
-      - uses: docker/setup-qemu-action@v3
-      - uses: docker/setup-buildx-action@v3
-
-      - uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: true
-          platforms: linux/amd64,linux/arm64
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          build-args: |
-            VERSION=${{ github.ref_name }}
-
-  virustotal:
-    needs: release
-    runs-on: ubuntu-latest
-    if: vars.VT_ENABLED == 'true'
-    steps:
-      - name: Get release tag
-        id: tag
-        run: echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
-
-      - name: Download release assets
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          mkdir -p assets
-          gh release download "${{ steps.tag.outputs.tag }}" \
-            --repo "${{ github.repository }}" \
-            --dir assets \
-            --pattern '*.tar.gz' \
-            --pattern '*.zip' \
-            --pattern 'checksums.txt'
-
-      - name: Scan assets with VirusTotal
-        env:
-          VT_API_KEY: ${{ secrets.VT_API_KEY }}
-        run: |
-          mkdir -p results
-          for file in assets/*; do
-            filename=$(basename "$file")
-            echo "Uploading $filename to VirusTotal..."
-
-            response=$(curl -s --request POST \
-              --url https://www.virustotal.com/api/v3/files \
-              --header "x-apikey: $VT_API_KEY" \
-              --form "file=@$file")
-
-            analysis_id=$(echo "$response" | jq -r '.data.id // empty')
-            if [ -z "$analysis_id" ]; then
-              echo "::warning::Failed to upload $filename: $response"
-              continue
-            fi
-
-            echo "$filename=$analysis_id" >> results/scans.txt
-            echo "  Analysis ID: $analysis_id"
-
-            # Rate limit: VT free tier allows 4 req/min
-            sleep 16
-          done
-
-      - name: Wait for analysis completion
-        env:
-          VT_API_KEY: ${{ secrets.VT_API_KEY }}
-        run: |
-          echo "Waiting 60s for VirusTotal analysis to complete..."
-          sleep 60
-
-          vt_report="## 🛡️ VirusTotal Scan Results\n\n"
-          vt_report+="| File | Result | Link |\n"
-          vt_report+="|------|--------|------|\n"
-
-          while IFS='=' read -r filename analysis_id; do
-            result=$(curl -s --request GET \
-              --url "https://www.virustotal.com/api/v3/analyses/$analysis_id" \
-              --header "x-apikey: $VT_API_KEY")
-
-            malicious=$(echo "$result" | jq -r '.data.attributes.stats.malicious // 0')
-            undetected=$(echo "$result" | jq -r '.data.attributes.stats.undetected // 0')
-            sha256=$(echo "$result" | jq -r '.meta.file_info.sha256 // empty')
-
-            if [ "$malicious" = "0" ]; then
-              status="✅ Clean ($undetected engines)"
-            else
-              status="⚠️ $malicious detections"
-            fi
-
-            link="https://www.virustotal.com/gui/file/$sha256"
-            vt_report+="| \`$filename\` | $status | [View]($link) |\n"
-
-            sleep 16
-          done < results/scans.txt
-
-          echo -e "$vt_report" > results/report.md
-          cat results/report.md
-
-      - name: Append scan results to release notes
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          current_body=$(gh release view "${{ steps.tag.outputs.tag }}" \
-            --repo "${{ github.repository }}" \
-            --json body --jq '.body')
-
-          new_body="${current_body}
-
-          $(cat results/report.md)"
-
-          gh release edit "${{ steps.tag.outputs.tag }}" \
-            --repo "${{ github.repository }}" \
-            --notes "$new_body"
diff --git a/.gitignore b/.gitignore
index a9f3162..8015bab 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,6 +36,12 @@ Thumbs.db
 
 # GoReleaser
 dist/
+dist-ffbinaries/
 
 # Docker
 tmp/
+config/
+dist-ffbinaries/
+
+# Claude Code: keep entirely local, do not track
+.claude/
\ No newline at end of file
diff --git a/.goreleaser.yml b/.goreleaser.yml
index 44656cd..6bc4a51 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -2,6 +2,14 @@ version: 2
 
 project_name: unarr
 
+# Pre-build hook: fetch static ffmpeg + ffprobe per platform so each
+# release tarball ships them adjacent to the unarr binary. ResolveFFmpeg /
+# ResolveFFprobe pick them up via the "adjacent to executable" branch — no
+# system install or runtime download needed.
+before:
+  hooks:
+    - bash scripts/download-ffmpeg-static.sh
+
 builds:
   - main: ./cmd/unarr/
     binary: unarr
@@ -18,13 +26,27 @@ builds:
       - -s -w
       - -X github.com/torrentclaw/unarr/internal/cmd.Version={{.Version}}
       - -X github.com/torrentclaw/unarr/internal/sentry.dsn={{ .Env.SENTRY_DSN }}
+      # Release-signing public key — verified by the self-updater against
+      # checksums.txt.sig. Empty when not configured; in that case
+      # signature verification is skipped and a warning is logged.
+      - -X github.com/torrentclaw/unarr/internal/upgrade.releasePubKeyBase64={{ .Env.RELEASE_SIGNING_PUBKEY }}
 
 archives:
-  - format: tar.gz
+  - formats: [tar.gz]
     name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
     format_overrides:
       - goos: windows
-        format: zip
+        formats: [zip]
+    files:
+      - LICENSE*
+      - README*
+      # Bundle the matching ffmpeg + ffprobe (filename includes .exe on Windows
+      # because download-ffmpeg-static.sh writes ffmpeg.exe / ffprobe.exe there).
+      - src: "dist-ffbinaries/{{ .Os }}-{{ .Arch }}/*"
+        dst: .
+        strip_parent: true
+        info:
+          mode: 0o755
 
 checksum:
   name_template: "checksums.txt"
@@ -37,6 +59,22 @@ changelog:
       - "^test:"
       - "^chore:"
 
+# Self-hosted Forgejo at git.torrentclaw.com. goreleaser detects GITEA_TOKEN +
+# these URLs and publishes the release there instead of GitHub. Reachable via
+# `forgejo` hostname inside the dokploy-network (the runner shares it); for
+# local goreleaser runs outside the network, override via env GITEA_API_URL.
+#
+# In goreleaser v2 `gitea_urls` is a top-level key (was nested under `release`
+# in v1).
+gitea_urls:
+  api: http://forgejo:3000/api/v1
+  download: https://git.torrentclaw.com
+  skip_tls_verify: false
+
+release:
+  draft: false
+  prerelease: auto
+
 # Homebrew tap — requires PAT with repo scope (not GITHUB_TOKEN)
 # Enable when torrentclaw/homebrew-tap PAT is configured as HOMEBREW_TAP_TOKEN
 # brews:
diff --git a/.nojekyll b/.nojekyll
new file mode 100644
index 0000000..e69de29
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0f49ea9..de1dd6e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,53 +5,584 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.9.15] - 2026-05-27
+
 
 ### Added
-- Init wizard with daemon install step (`unarr init`, replaces `unarr setup`)
-- Interactive config menu with 7 categories (`unarr config [category]`)
-- Migration wizard from Sonarr/Radarr/Prowlarr (`unarr migrate`) [pre-beta]
-  - Auto-detect instances via Docker, config files, port scan, Prowlarr
-  - Import download history and blocklist to avoid re-downloading
-  - Detect Plex/Jellyfin/Emby media servers and library paths
-  - Extract debrid tokens from *arr download clients
-  - JSON export with `--dry-run --json`
-- Media server detection in `unarr init` (suggests library paths as download directory)
-- `preferred_quality` setting in config (2160p/1080p/720p)
-- Clean command to remove temp files, logs, and cached data (`unarr clean`)
-- Daemon mode with background download management (`unarr start`)
-- One-shot download command (`unarr download`)
-- Stream to media player (`unarr stream`)
-- Doctor command for diagnostics (`unarr doctor`)
-- Status command for daemon monitoring (`unarr status`)
-- Download engine with torrent support (debrid and usenet coming soon)
-- File organization (Movies/TV Shows directory structure)
-- Post-download verification
-- Desktop notifications (Linux, macOS)
-- Docker support with multi-stage build
-- Cross-platform install scripts (shell, PowerShell)
-- Dependabot for automated dependency updates
-- golangci-lint configuration with gosec
+
+- **sentry**: enhance error handling by skipping user input errors in CaptureError
 
 ### Changed
-- Renamed `internal/commands/` to `internal/cmd/`
 
-## [0.1.0] - 2025-02-14
+- **ci**: point Forgejo URLs at torrentclaw org (post-transfer)
+- **sentry**: decouple agent import via string-match, rename predicate
+
+### Documentation
+
+- **positioning**: reframe unarr around download/stream/transcode, drop misleading search-first wording
+
+### Fixed
+
+- **ci**: unset GITHUB_TOKEN so goreleaser uses GITEA_TOKEN
+- **sentry**: skip "daemon not running" stop/reload errors
+
+### Other
+
+- **scripts**: harden release.sh against double-release and inline version bumps
+- untrack .claude/ (private local config)
+## [0.9.14] - 2026-05-27
+
 
 ### Added
-- Initial release
-- Search across 30+ torrent sources with advanced filters
-- TrueSpec torrent inspection (quality, codec, seeds, score)
-- Watch command (streaming providers + torrent alternatives)
-- Popular and recent content browsing
-- System statistics
-- Interactive configuration
-- JSON output mode (`--json`) for scripting
-- Colored terminal output with `--no-color` support
-- Homebrew tap distribution
-- GoReleaser with UPX compression
-- CI pipeline (test, build, lint, vet)
-- Lefthook git hooks (gofmt, go vet, conventional commits)
 
-[Unreleased]: https://github.com/torrentclaw/unarr/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/torrentclaw/unarr/releases/tag/v0.1.0
+- **vaapi**: hybrid CPU-scale + hwupload encode path (QW2, 0.9.14)
+
+### CI/CD
+
+- port workflows from .github/ to .forgejo/ (Forgejo Actions)
+
+### Fixed
+
+- **daemon**: defensive IsClosed check in watchSessionReady poll loop
+- **daemon**: use parent ctx for MarkSessionReady so cancel propagates
+- **release**: move gitea_urls to top-level (goreleaser v2 schema)
+## [0.9.13] - 2026-05-27
+
+
+### Added
+
+- **agent**: session-ready webhook for SSE-driven player handshake (0.9.13)
+- **agent**: send full transcoder diagnostic in register payload (0.9.12)
+
+### Fixed
+
+- **daemon**: defer probeCancel so a panic mid-diagnostic still releases ctx
+
+### Other
+
+- **release**: add ship.sh end-to-end pipeline as GH Actions backup
+- **skills**: add /publish slash command + allow .claude/ in git
+## [0.9.11] - 2026-05-27
+
+
+### Added
+
+- **hls**: pre-segmentación delantada — 2 s segments + async session start (0.9.10)
+- **hls**: faster first-start — probe cache + tighter encoder presets (0.9.9)
+
+### Changed
+
+- **hls**: critico-driven hardening of fase 3.2
+
+### Fixed
+
+- **cors**: allow play from .to / staging / onion mirrors
+- **library**: classify resolution by width + height, not height alone
+- **transcode**: make preset libx264-only + restore quality opt-in
+
+### Other
+
+- **release**: 0.9.11
+## [0.9.8] - 2026-05-27
+
+
+### Fixed
+
+- **upgrade**: break auto-apply restart loop (0.9.8)
+## [0.9.7] - 2026-05-26
+
+
+### Added
+
+- **hls**: persistent fMP4 segment cache + integrity + stats (0.9.7)
+## [0.9.6] - 2026-05-26
+
+
+### Added
+
+- **daemon**: auto-apply upgrades when server signals (0.9.6)
+## [0.9.5] - 2026-05-26
+
+
+### Added
+
+- **funnel**: cloudflare quick tunnel embedded subprocess (0.9.5)
+## [0.9.4] - 2026-05-26
+
+
+### Added
+
+- **stream**: retire WebRTC, HLS-only, bump 0.9.4 (**BREAKING**)
+## [0.9.3] - 2026-05-26
+
+
+### Added
+
+- **usenet**: warn at startup when par2 or extractor is missing
+
+### Fixed
+
+- **engine**: truncate errorMessage before reporting status
+- **hls**: clamp ffmpeg bitrate to the level we derive from outputHeight
+## [0.9.2] - 2026-05-22
+
+
+### Added
+
+- **vpn**: unarr vpn command + report/arbitrate the WireGuard slot
+## [0.9.1] - 2026-05-21
+
+
+### Added
+
+- **mirror**: update fallback URLs to use IPFS and remove GitHub Pages
+
+### Fixed
+
+- **security**: bump golang.org/x deps and add container CVE scan gate
+
+### Other
+
+- **release**: 0.9.1
+## [0.9.0] - 2026-05-21
+
+
+### Added
+
+- **agent**: add mirror failover, agent client refactor, status 401 detection
+- **vpn**: local config_file for self-hosted/personal VPN testing
+- **vpn**: split-tunnel torrent traffic through managed WireGuard
+
+### CI/CD
+
+- deploy install scripts to GitHub Pages
+
+### Documentation
+
+- **docker**: refresh Docker Hub README + sync description in CI
+
+### Fixed
+
+- **security**: CORS allowlist, URL scheme guard, state perms, ZIP slip, mirror docs
+- **security**: UPnP opt-in, bounded SSE reader, signed self-update
+- **security**: harden HLS session IDs, /health disclosure, archive password handling
+- **upgrade**: fetch releases from TorrentClaw app, not GitHub
+
+### Other
+
+- **pages**: add .nojekyll to disable Jekyll processing
+- **pages**: set custom domain unarr.torrentclaw.com
+- **release**: 0.9.0
+## [0.8.1] - 2026-05-08
+
+
+### Added
+
+- **config**: set default values for WebRTC and transcoding in minimal TOML config
+- **transcode**: dynamic H.264 level + HW probe + capability reporting
+
+### Changed
+
+- **streaming**: improve signal handling and remove unused components
+
+### Fixed
+
+- **self-update**: auto-restart live daemon after upgrade
+- **streaming**: allow HLS sessions when webrtc disabled
+
+### Other
+
+- **gitignore**: add dist-ffbinaries to ignored files
+- **release**: 0.8.1
+## [0.8.0] - 2026-05-08
+
+
+### Added
+
+- **mediainfo**: ResolveFFmpeg + DownloadFFmpeg mirroring ffprobe pattern
+- **release**: bundle ffmpeg + ffprobe in tarballs and Docker image
+- **seed-file**: unarr-side handler for browser-on-demand seeding (Fase 4.7.c)
+- **stream**: per-session quality cap from web
+- **stream**: real-time transcoding for non-browser-decodable codecs
+- **stream**: pion-based WebRTC byte streamer for browser playback
+- **streaming**: seek-restart, single-session, idle sweeper, probe.json
+- **streaming**: add HLS transport pipeline (daemon side)
+- **streaming**: ffmpeg transcoding pipeline (direct play / fMP4 / HW accel)
+- **torrent**: act as WebTorrent peer for browser ↔ unarr P2P streaming
+- **wstracker-probe**: -seed FILE mode for browser ↔ unarr e2e validation
+
+### Fixed
+
+- **streaming**: bounded ffmpeg auto-restart + tmpdir gc + probe/stderr safety
+- **transcoder**: force aac stereo 48khz + frag_duration for mse compat
+- **transcoder**: force main profile + setparams Rec.709 + serveRange wait
+- **transcoder**: correct scale filter + always force yuv420p
+
+### Other
+
+- **release**: 0.8.0
+- **streaming**: post-review fixes — race lock, dead branch, stderr cap
+- **torrent**: bump anacrolix log level Critical → Warning for visibility
+## [0.7.0] - 2026-04-10
+
+
+### Added
+
+- **daemon**: enhance service management with start, stop, restart, and status commands for Windows
+
+### Other
+
+- **release**: 0.7.0
+## [0.6.8] - 2026-04-10
+
+
+### Added
+
+- **library**: add server-driven file deletion with allow_delete config
+
+### Other
+
+- **release**: 0.6.8
+## [0.6.7] - 2026-04-10
+
+
+### Added
+
+- **scan**: always scan downloads + organize dirs, deduplicate child paths
+
+### Other
+
+- **release**: 0.6.7
+## [0.6.6] - 2026-04-09
+
+
+### Fixed
+
+- **docker**: switch ffprobe download from johnvansickle.com to BtbN/FFmpeg-Builds
+- **stream**: fix black screen on remote/Tailscale streaming
+
+### Other
+
+- **release**: 0.6.6
+## [0.6.5] - 2026-04-09
+
+
+### Fixed
+
+- **upgrade**: retry download on transient network errors with user feedback
+
+### Other
+
+- **release**: 0.6.5
+## [0.6.4] - 2026-04-09
+
+
+### Fixed
+
+- **daemon**: report error status when stream path is rejected
+
+### Other
+
+- **release**: 0.6.4
+## [0.6.3] - 2026-04-09
+
+
+### Fixed
+
+- **library**: use native arm64 ffprobe on Apple Silicon (osx-arm-64)
+
+### Other
+
+- **release**: 0.6.3
+## [0.6.2] - 2026-04-09
+
+
+### Added
+
+- **library**: resilient scan for large libraries and better ffprobe errors
+
+### Other
+
+- **release**: 0.6.2
+- ignore local config/ directory
+## [0.6.1] - 2026-04-08
+
+
+### Added
+
+- **wake**: long-poll wake listener for instant CLI sync
+
+### Fixed
+
+- resolve deadlock, data races and path traversal vulnerabilities
+## [0.6.0] - 2026-04-08
+
+
+### Added
+
+- **sync**: replace WS+DO transport with unified HTTP sync
+
+### Fixed
+
+- **ws**: add ping/pong keepalive and read deadline to detect zombie connections
+
+### Other
+
+- **release**: 0.6.0
+## [0.5.5] - 2026-04-07
+
+
+### Added
+
+- **agent**: send stream port and IPs in register request
+- **stream**: report duration and position in watch progress
+- **stream**: trackingReader with byte-based progress and rate limiting
+
+### Fixed
+
+- **daemon**: cancel watch reporter on stream switch and re-notify ready
+
+### Other
+
+- **release**: 0.5.5
+## [0.5.4] - 2026-04-07
+
+
+### Fixed
+
+- **stream**: use platform-specific socket options for Windows cross-compilation
+
+### Other
+
+- **release**: 0.5.4
+## [0.5.3] - 2026-04-07
+
+
+### Added
+
+- **stream**: persistent stream server with file swapping
+
+### Other
+
+- **release**: 0.5.3
+## [0.5.2] - 2026-04-07
+
+
+### Added
+
+- **stream**: report multi-network URLs for smart resolution
+
+### Other
+
+- **release**: 0.5.2
+## [0.5.1] - 2026-04-07
+
+
+### Added
+
+- **daemon**: add on-demand library scan via heartbeat and WebSocket
+
+### Fixed
+
+- **agent**: add retry with backoff and WebSocket connect for daemon registration
+- **daemon**: report failed status on stream request errors
+- **daemon**: use correct systemd user target and isolate test cache
+- **stream**: prevent duplicate events from killing active stream server
+
+### Other
+
+- **release**: 0.5.1
+## [0.5.0] - 2026-04-06
+
+
+### Added
+
+- **organize**: use server metadata for file organization and subtitle handling
+- **stream**: add NAT-PMP port mapping for remote downloads
+
+### Other
+
+- **release**: 0.5.0
+- **release**: add changelog generation and release automation
+## [0.4.1] - 2026-04-01
+
+
+### Added
+
+- **cli**: add login command and refactor shared helpers
+- **stream**: report watch progress to API via HTTP Range tracking
+
+### Fixed
+
+- **ci**: fix lint errors and pin CI to Go 1.25
+- **lint**: remove unused newStubCmd function
+
+### Other
+
+- **cli**: remove moreseed stub command
+- **cli**: remove redundant stub commands (monitor, open, add, compare)
+## [0.4.0] - 2026-03-31
+
+
+### Added
+
+- **cli**: upgrade command, rich status, and version cache
+
+### Fixed
+
+- **progress**: always report status transitions and poll for control signals
+## [0.3.7] - 2026-03-31
+
+
+### CI/CD
+
+- **docker**: remove dockerhub-description sync step
+## [0.3.6] - 2026-03-31
+
+
+### CI/CD
+
+- **deps**: bump docker/metadata-action from 5 to 6
+- **deps**: bump docker/setup-qemu-action from 3 to 4
+- **deps**: bump docker/login-action from 3 to 4
+- **deps**: bump docker/build-push-action from 6 to 7
+- **deps**: bump codecov/codecov-action from 5 to 6
+- **docker**: add Docker Hub description sync and DOCKERHUB.md
+
+### Fixed
+
+- **ci**: upgrade golangci-lint to v2.11.3 for Go 1.25 support
+- **docker**: upgrade alpine packages to patch CVE-2025-60876 and CVE-2026-27171
+- **lint**: use default:none to disable errcheck, fix all gofmt and exhaustive
+- **lint**: disable errcheck, tune gosec/exclusions for codebase state
+- **lint**: configure linters for codebase maturity, fix gofmt and ineffassign
+- **lint**: exclude common fire-and-forget patterns from errcheck
+- **lint**: resolve errcheck and bodyclose warnings for golangci-lint v2
+## [0.3.5] - 2026-03-30
+
+
+### Changed
+
+- migrate lint config to v2, remove daemon auto-upgrade, add trust badges
+## [0.3.3] - 2026-03-30
+
+
+### Fixed
+
+- **ci**: remove go-client checkout steps
+## [0.3.2] - 2026-03-30
+
+
+### Added
+
+- **init**: add 60s countdown, skip key, and cancel detection to browser auth
+
+### CI/CD
+
+- **release**: add Docker Hub publish and VirusTotal scan jobs
+
+### Documentation
+
+- add beta notice, fix install URLs to get.torrentclaw.com
+
+### Fixed
+
+- **ci**: fix virustotal job condition syntax
+- **docker**: simplify Dockerfile for CI builds (no local go-client)
+- **release**: disable homebrew tap (needs PAT, not GITHUB_TOKEN)
+
+### Other
+
+- re-enable homebrew tap in goreleaser
+## [0.3.1] - 2026-03-30
+
+
+### Fixed
+
+- **build**: unused variable in Windows process check
+- **release**: disable homebrew tap until repo is created
+
+### Other
+
+- rename module from torrentclaw-cli to unarr
+
+### Build
+
+- remove UPX compression (antivirus false positives, startup penalty)
+## [0.3.0] - 2026-03-29
+
+
+### Added
+
+- **agent**: add WebSocket transport with HTTP fallback
+- **auth**: browser-based CLI authentication (like Claude Code)
+- **daemon**: add auto-scan, force start, and stall timeout default
+- **debrid**: add HTTPS downloader for debrid direct URLs
+- **stream**: UPnP port forwarding for remote video playback
+- **usenet**: implement full NNTP download pipeline
+- add migrate command, media server detection, and debrid auto-config
+- replace setup with init wizard + interactive config menu
+- add clean command to remove temp files, logs, and cached data
+- add Sentry error reporting
+- improve daemon resilience, streaming, and usenet downloads
+- initial commit — unarr CLI
+
+### Changed
+
+- extract BuildSyncItems to library package, remove duplication
+
+### Documentation
+
+- improve CLI help, shell completion, and README
+
+### Fixed
+
+- **torrent**: expand tracker list, add DHT persistence and configurable timeouts
+- force-start tasks bypass HasCapacity check in dispatch loop
+- add panic recovery to auto-scan, cap DHT nodes at 200
+- harden usenet/debrid downloaders from critico review
+
+### Build
+
+- add -s -w -trimpath to Makefile, add build-small target with UPX
+[0.9.15]: https://github.com/torrentclaw/unarr/compare/v0.9.14...v0.9.15
+[0.9.14]: https://github.com/torrentclaw/unarr/compare/v0.9.13...v0.9.14
+[0.9.13]: https://github.com/torrentclaw/unarr/compare/v0.9.11...v0.9.13
+[0.9.11]: https://github.com/torrentclaw/unarr/compare/v0.9.8...v0.9.11
+[0.9.8]: https://github.com/torrentclaw/unarr/compare/v0.9.7...v0.9.8
+[0.9.7]: https://github.com/torrentclaw/unarr/compare/v0.9.6...v0.9.7
+[0.9.6]: https://github.com/torrentclaw/unarr/compare/v0.9.5...v0.9.6
+[0.9.5]: https://github.com/torrentclaw/unarr/compare/v0.9.4...v0.9.5
+[0.9.4]: https://github.com/torrentclaw/unarr/compare/v0.9.3...v0.9.4
+[0.9.3]: https://github.com/torrentclaw/unarr/compare/v0.9.2...v0.9.3
+[0.9.2]: https://github.com/torrentclaw/unarr/compare/v0.9.1...v0.9.2
+[0.9.1]: https://github.com/torrentclaw/unarr/compare/v0.9.0...v0.9.1
+[0.9.0]: https://github.com/torrentclaw/unarr/compare/v0.8.1...v0.9.0
+[0.8.1]: https://github.com/torrentclaw/unarr/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/torrentclaw/unarr/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/torrentclaw/unarr/compare/v0.6.8...v0.7.0
+[0.6.8]: https://github.com/torrentclaw/unarr/compare/v0.6.7...v0.6.8
+[0.6.7]: https://github.com/torrentclaw/unarr/compare/v0.6.6...v0.6.7
+[0.6.6]: https://github.com/torrentclaw/unarr/compare/v0.6.5...v0.6.6
+[0.6.5]: https://github.com/torrentclaw/unarr/compare/v0.6.4...v0.6.5
+[0.6.4]: https://github.com/torrentclaw/unarr/compare/v0.6.3...v0.6.4
+[0.6.3]: https://github.com/torrentclaw/unarr/compare/v0.6.2...v0.6.3
+[0.6.2]: https://github.com/torrentclaw/unarr/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/torrentclaw/unarr/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/torrentclaw/unarr/compare/v0.5.5...v0.6.0
+[0.5.5]: https://github.com/torrentclaw/unarr/compare/v0.5.4...v0.5.5
+[0.5.4]: https://github.com/torrentclaw/unarr/compare/v0.5.3...v0.5.4
+[0.5.3]: https://github.com/torrentclaw/unarr/compare/v0.5.2...v0.5.3
+[0.5.2]: https://github.com/torrentclaw/unarr/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/torrentclaw/unarr/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/torrentclaw/unarr/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/torrentclaw/unarr/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/torrentclaw/unarr/compare/v0.3.7...v0.4.0
+[0.3.7]: https://github.com/torrentclaw/unarr/compare/v0.3.6...v0.3.7
+[0.3.6]: https://github.com/torrentclaw/unarr/compare/v0.3.5...v0.3.6
+[0.3.5]: https://github.com/torrentclaw/unarr/compare/v0.3.3...v0.3.5
+[0.3.3]: https://github.com/torrentclaw/unarr/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/torrentclaw/unarr/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/torrentclaw/unarr/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/torrentclaw/unarr/releases/tag/v0.3.0
+
diff --git a/CNAME b/CNAME
new file mode 100644
index 0000000..d892572
--- /dev/null
+++ b/CNAME
@@ -0,0 +1 @@
+unarr.torrentclaw.com
\ No newline at end of file
diff --git a/DOCKERHUB.md b/DOCKERHUB.md
new file mode 100644
index 0000000..3df5b70
--- /dev/null
+++ b/DOCKERHUB.md
@@ -0,0 +1,200 @@
+# unarr
+
+**The single binary that replaces your whole *arr stack.** Built-in torrent,
+debrid, and usenet engines. Stream, transcode, and organize your library from
+one terminal — or run it as a headless daemon with a web dashboard, WireGuard
+split-tunnel, and Cloudflare Funnel remote access.
+
+**[Website & docs](https://torrentclaw.com/unarr)** · **[Install guide](https://torrentclaw.com/cli)** · **[Get an API key](https://torrentclaw.com)**
+
+> Powered by [TorrentClaw](https://torrentclaw.com) — an aggregator that unifies
+> YTS, EZTV, Knaben, Torrentio, Bitmagnet and more, enriched with TMDB metadata
+> and a 0–100 quality score per release.
+
+---
+
+## Quick start
+
+### 1. First-time setup (interactive wizard)
+
+```bash
+docker run -it --rm \
+  -v ~/.config/unarr:/config \
+  torrentclaw/unarr setup
+```
+
+The wizard asks for your TorrentClaw API key (free at
+[torrentclaw.com](https://torrentclaw.com)) and your download directory.
+
+### 2. Run the daemon
+
+```bash
+docker run -d --name unarr \
+  --restart unless-stopped \
+  --network host \
+  --read-only --memory 512m \
+  -v ~/.config/unarr:/config \
+  -v ~/Media:/downloads \
+  torrentclaw/unarr
+```
+
+That's it — `unarr` now runs headless, watching for jobs and managing downloads.
+
+---
+
+## Docker Compose
+
+```yaml
+services:
+  unarr:
+    image: torrentclaw/unarr:latest
+    container_name: unarr
+    restart: unless-stopped
+    user: "1000:1000"
+    read_only: true
+    tmpfs:
+      - /tmp:size=64m,mode=1777
+    volumes:
+      - ./config:/config
+      - ~/Media:/downloads
+      - unarr-data:/data
+    environment:
+      - TZ=UTC
+      # - UNARR_API_KEY=tc_your_key_here
+    network_mode: host        # recommended for full P2P performance
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "2.0"
+
+volumes:
+  unarr-data:
+```
+
+```bash
+docker compose run --rm unarr setup   # one-time wizard
+docker compose up -d                   # start the daemon
+```
+
+---
+
+## Volumes
+
+| Path         | Purpose                                          |
+|--------------|--------------------------------------------------|
+| `/config`    | Configuration file (`config.toml`)               |
+| `/downloads` | Finished media downloads                         |
+| `/data`      | Internal state: torrent metadata, cache          |
+
+## Environment variables
+
+| Variable               | Description                          | Default                   |
+|------------------------|--------------------------------------|---------------------------|
+| `UNARR_API_KEY`        | TorrentClaw API key                  | from config               |
+| `UNARR_API_URL`        | API endpoint                         | `https://torrentclaw.com` |
+| `UNARR_DOWNLOAD_DIR`   | Download directory                   | `/downloads`              |
+| `UNARR_CONFIG_DIR`     | Config directory                     | `/config`                 |
+| `UNARR_COUNTRY`        | Country code (ISO 3166)              | `US`                      |
+| `TZ`                   | Timezone                             | `UTC`                     |
+
+Any config value can be overridden by its matching `UNARR_*` environment variable.
+
+## Networking
+
+**Host mode (recommended)** — full P2P performance, no port mapping:
+
+```yaml
+network_mode: host
+```
+
+**Bridge mode** — more isolated, but you must expose the BitTorrent ports:
+
+```yaml
+ports:
+  - "6881-6889:6881-6889/tcp"
+  - "6881-6889:6881-6889/udp"
+```
+
+## Running commands
+
+Use `docker exec` for one-off commands while the daemon is running:
+
+```bash
+docker exec unarr unarr search "inception" --quality 1080p
+docker exec unarr unarr popular --limit 10
+docker exec unarr unarr status
+docker exec unarr unarr doctor      # diagnose config / connectivity
+```
+
+---
+
+## Tags
+
+| Tag      | Description                                      |
+|----------|--------------------------------------------------|
+| `latest` | Latest stable release                            |
+| `X.Y.Z`  | Exact version (e.g. `0.9.0`)                      |
+| `X.Y`    | Latest patch within a minor (e.g. `0.9`)         |
+
+Pin a tag in production (`torrentclaw/unarr:0.9.0`) for reproducible deploys.
+
+## Supported architectures
+
+Multi-arch image — Docker pulls the right one automatically:
+
+- `linux/amd64`
+- `linux/arm64` (Apple Silicon, Raspberry Pi 4/5, ARM servers)
+
+## Image details
+
+- **Base:** Alpine 3.22 (minimal, regularly patched)
+- **User:** `unarr` (UID 1000, GID 1000) — runs as **non-root**
+- **Entrypoint:** `unarr start` (daemon mode)
+- **Read-only rootfs** — only mounted volumes are writable
+- **Bundled `ffmpeg` / `ffprobe`** for media inspection — nothing else to install
+- **Self-contained updates** — binaries are served from TorrentClaw's own
+  infrastructure, no third-party registry dependency
+
+---
+
+## Other install methods
+
+Not using Docker? Install the native binary instead:
+
+```bash
+# Linux / macOS
+curl -fsSL https://torrentclaw.com/install.sh | sh
+
+# Windows (PowerShell)
+irm https://torrentclaw.com/install.ps1 | iex
+
+# Go toolchain
+go install github.com/torrentclaw/unarr/cmd/unarr@latest
+```
+
+## Mirrors
+
+The installer and release binaries are served from every TorrentClaw mirror, so
+you can install even if one domain is blocked in your region. Each mirror is
+self-contained (it serves its own binaries — no cross-domain dependency):
+
+| Mirror | Install command |
+|--------|-----------------|
+| `torrentclaw.com` (primary) | `curl -fsSL https://torrentclaw.com/install.sh \| sh` |
+| `torrentclaw.to` | `curl -fsSL https://torrentclaw.to/install.sh \| sh` |
+| Tor (`.onion`) | `torsocks sh -c "$(curl http://torrentf3aifidcsaaanmnmuhv2s53r6hqsl3zkmfidiaxainkeqk5id.onion/install.sh)"` |
+
+The Tor address routes everything (install script + binaries) through the hidden
+service, so no clearnet exit is needed.
+
+## Links
+
+- **Website & docs:** https://torrentclaw.com/unarr
+- **CLI install guide:** https://torrentclaw.com/cli
+- **API & account:** https://torrentclaw.com
+- **Mirror status:** https://torrentclaw.com/mirrors
+
+## License
+
+MIT.
diff --git a/Dockerfile b/Dockerfile
index ff5cdea..64ea4e2 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -16,9 +16,28 @@ ARG VERSION=dev
 RUN CGO_ENABLED=0 go build -ldflags="-s -w -X github.com/torrentclaw/unarr/internal/cmd.Version=${VERSION}" -trimpath -o /unarr ./cmd/unarr/
 
 # ---- Runtime stage ----
-FROM alpine:3.21
+FROM alpine:3.22
 
-RUN apk add --no-cache ca-certificates tzdata
+# Use Alpine's native musl ffmpeg + ffprobe instead of the johnvansickle /
+# BtbN static glibc builds — those need a glibc shim on Alpine and the
+# vector-math symbols the GPL builds reference are not satisfiable by
+# gcompat. Alpine ships ffmpeg ~7.x which is fine for the HLS transcoding
+# pipeline (libx264 + libfdk-aac alternatives included).
+RUN apk upgrade --no-cache && \
+    apk add --no-cache ca-certificates tzdata ffmpeg wget
+
+# Bundle cloudflared so `unarr funnel on` (default: on, see config defaults)
+# Just Works on a headless container with no first-run network round-trip.
+# TARGETARCH is set automatically by Docker buildx during cross-builds.
+ARG TARGETARCH=amd64
+RUN case "$TARGETARCH" in \
+      amd64) CF_ARCH=amd64 ;; \
+      arm64) CF_ARCH=arm64 ;; \
+      arm)   CF_ARCH=armhf ;; \
+      *)     echo "unsupported TARGETARCH=$TARGETARCH" >&2; exit 1 ;; \
+    esac && \
+    wget -qO /usr/local/bin/cloudflared "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-$CF_ARCH" && \
+    chmod +x /usr/local/bin/cloudflared
 
 # Non-root user (UID 1000 matches typical host user for volume permissions)
 RUN addgroup -g 1000 unarr && adduser -u 1000 -G unarr -D -h /home/unarr unarr
diff --git a/Docs/plans/library-sync.md b/Docs/plans/library-sync.md
new file mode 100644
index 0000000..509e87a
--- /dev/null
+++ b/Docs/plans/library-sync.md
@@ -0,0 +1,170 @@
+# Plan: Sincronización bidireccional de biblioteca (CLI ↔ Web)
+
+## Context
+La biblioteca web solo muestra descargas completadas (download_task + debrid). El `unarr scan` escanea ficheros con ffprobe y los sube al servidor, pero solo soporta un path, no detecta borrados del disco, y no permite borrar ficheros desde la web. El usuario quiere una biblioteca unificada que refleje el estado real de su colección y se sincronice en ambas direcciones.
+
+## Protocolo de sincronización
+
+### Forward Sync (Disco → Web)
+1. CLI escanea todos los `ScanPaths` configurados
+2. Para cada path: descubre ficheros, compara con cache (skip ffprobe si no cambió), sube a `/library-sync`
+3. En `isLastBatch=true`: el servidor elimina items con ese `scanPath` que no estén en el batch (ficheros borrados del disco desaparecen de la web)
+
+### Reverse Sync (Web → Disco)
+1. CLI llama a `GET /agent/library-deletions` — items que el usuario soft-deleted desde la web
+2. Si `AutoDelete=true` o `--yes`: borra ficheros del disco
+3. Si no: muestra lista y pide confirmación interactiva
+4. Llama a `POST /agent/library-deletions/confirm` con los IDs confirmados → hard-delete en DB
+
+### Resolución de conflictos
+- Fichero en disco pero no en web → forward sync lo añade
+- Fichero en web pero no en disco → forward sync lo elimina (isLastBatch)
+- Soft-deleted en web, aún en disco → reverse sync lo borra del disco y confirma
+- Soft-deleted en web, ya borrado del disco → reverse sync confirma directamente
+- Race condition (user borra en web mientras CLI escanea) → forward sync skippea rows con `deleted_at IS NOT NULL`
+
+---
+
+## Fase 1: Multi-path + Forward Sync mejorado
+
+### 1.1 CLI — Config multi-path
+**Archivo:** `torrentclaw-cli/internal/config/config.go`
+- Añadir `ScanPaths []string` a `LibraryConfig`
+- Migrar `ScanPath` → `ScanPaths[0]` en `Load()` si `ScanPaths` está vacío
+- Añadir `AutoDelete bool` (default false)
+
+### 1.2 CLI — Cache v2
+**Archivo:** `torrentclaw-cli/internal/library/types.go`
+- Cambiar `LibraryCache` a version 2: `Paths map[string][]LibraryItem`
+- Migración v1→v2: `Path`+items → `Paths[Path]`
+
+**Archivo:** `torrentclaw-cli/internal/library/cache.go`
+- `LoadCache` detecta versión y migra
+- `SaveCache` siempre guarda v2
+
+### 1.3 CLI — Scan multi-path
+**Archivo:** `torrentclaw-cli/internal/cmd/scan.go`
+- `unarr scan` sin args → escanea todos los `ScanPaths`
+- `unarr scan /path/a /path/b` → escanea paths específicos y los recuerda en config
+- Loop: para cada path, scan + sync con su `scanPath`
+
+### 1.4 CLI — Nuevo comando `unarr sync`
+**Archivo nuevo:** `torrentclaw-cli/internal/cmd/sync.go`
+- Forward sync: scan ligero (sin ffprobe para ficheros sin cambios) + upload
+- Sin reverse sync todavía (Fase 3)
+- Flags: `--dry-run`, `--paths`
+
+### 1.5 Web — Columna `scan_path` en `library_item`
+**Archivo:** `torrentclaw-web/src/lib/db/schema.ts`
+- Añadir `scanPath: varchar(2048)` a tabla `libraryItem`
+- Generar migración con `pnpm db:generate`
+
+**Archivo:** `torrentclaw-web/src/lib/services/library-upgrade.ts`
+- `syncLibraryItems()`: persistir `scanPath` en cada row al hacer upsert
+
+### 1.6 CLI — Daemon multi-path
+**Archivo:** `torrentclaw-cli/internal/cmd/daemon.go`
+- `runAutoScan()` itera sobre todos los `ScanPaths`
+
+---
+
+## Fase 2: Reverse Sync (Web → Disco)
+
+### 2.1 Web — Soft-delete
+**Archivo:** `torrentclaw-web/src/lib/db/schema.ts`
+- Añadir `deletedAt: timestamp` a tabla `libraryItem`
+- Generar migración
+
+### 2.2 Web — Endpoints de borrado
+**Archivo nuevo:** `torrentclaw-web/src/app/api/internal/library/items/route.ts`
+- `DELETE` — session auth, recibe `{itemIds: number[]}`, hace soft-delete (`deletedAt = NOW()`)
+
+**Archivo nuevo:** `torrentclaw-web/src/app/api/internal/agent/library-deletions/route.ts`
+- `GET` — agent auth, devuelve items con `deletedAt IS NOT NULL` para ese usuario
+- `POST` — agent auth, recibe `{confirmedIds: number[]}`, hard-delete los rows
+
+### 2.3 Web — Heartbeat con pendingDeletions
+**Archivo:** endpoint de heartbeat del agente
+- Añadir `pendingDeletions: number` al response (count de items con `deletedAt IS NOT NULL`)
+
+### 2.4 Web — Forward sync respeta soft-deletes
+**Archivo:** `torrentclaw-web/src/lib/services/library-upgrade.ts`
+- `syncLibraryItems()` en `isLastBatch`: la query de DELETE excluye rows con `deletedAt IS NOT NULL`
+
+### 2.5 CLI — Agent client nuevos métodos
+**Archivo:** `torrentclaw-cli/internal/agent/client.go`
+- `GetLibraryDeletions(ctx) → []DeletionItem`
+- `ConfirmLibraryDeletions(ctx, ids []int) → error`
+
+**Archivo:** `torrentclaw-cli/internal/agent/types.go`
+- `DeletionItem {ID int, FilePath string, DeletedAt string}`
+
+### 2.6 CLI — Sync reverse
+**Archivo:** `torrentclaw-cli/internal/cmd/sync.go`
+- Después del forward sync: llama a `GetLibraryDeletions()`
+- Valida que cada fichero está dentro de un `ScanPaths` conocido (seguridad)
+- Si `AutoDelete` o `--yes`: borra y confirma
+- Si no: muestra lista interactiva, pide confirmación
+- Flag `--no-delete` para skip reverse sync
+- Si `BackupDir` configurado: mover a backup en vez de borrar
+
+### 2.7 CLI — Daemon auto-delete
+**Archivo:** `torrentclaw-cli/internal/cmd/daemon.go`
+- Al final de `runAutoSync()`: si `AutoDelete=true`, procesa deletions automáticamente
+- Si no: log warning "N files pending deletion, run `unarr sync`"
+
+---
+
+## Fase 3: Web UI (brief)
+
+- Botón "Eliminar" en items de biblioteca → llama `DELETE /library/items`
+- Badge "Pendiente de borrar" en items soft-deleted
+- Posibilidad de cancelar el borrado (clear `deletedAt`)
+- Vista unificada: scanned items + downloaded items en la misma vista
+
+---
+
+## Archivos clave
+
+### CLI (Go)
+| Archivo | Cambio |
+|---------|--------|
+| `internal/config/config.go` | ScanPaths, AutoDelete, migración |
+| `internal/library/types.go` | Cache v2 con Paths map |
+| `internal/library/cache.go` | Load/Save v2, migración v1 |
+| `internal/library/sync.go` | BuildSyncItems (sin cambios) |
+| `internal/cmd/scan.go` | Multi-path loop |
+| `internal/cmd/sync.go` | **Nuevo** — comando sync bidireccional |
+| `internal/cmd/daemon.go` | runAutoSync multi-path + reverse |
+| `internal/agent/client.go` | GetLibraryDeletions, ConfirmLibraryDeletions |
+| `internal/agent/types.go` | DeletionItem type |
+
+### Web (TypeScript)
+| Archivo | Cambio |
+|---------|--------|
+| `src/lib/db/schema.ts` | scanPath + deletedAt en library_item |
+| `src/lib/services/library-upgrade.ts` | persistir scanPath, respetar soft-deletes |
+| `src/app/api/internal/agent/library-deletions/route.ts` | **Nuevo** — GET + POST |
+| `src/app/api/internal/library/items/route.ts` | **Nuevo** — DELETE soft-delete |
+| Endpoint heartbeat del agente | pendingDeletions en response |
+
+---
+
+## Verificación
+
+### Fase 1
+1. `go build ./cmd/unarr/ && go test ./...`
+2. Configurar 2 scan paths en config.toml, ejecutar `unarr scan` → ambos se escanean
+3. Borrar un fichero del disco, ejecutar `unarr scan` → desaparece de la web
+4. `pnpm build` en torrentclaw-web para verificar tipos
+
+### Fase 2
+1. Desde la web: borrar un item de la biblioteca
+2. Ejecutar `unarr sync` → muestra el fichero pendiente de borrar, pedir confirmación
+3. Confirmar → fichero se borra del disco y desaparece de la web
+4. `unarr sync --dry-run` → muestra lo que haría sin hacer nada
+5. Con `auto_delete = true` en config: el daemon borra automáticamente
+
+### Fase 3
+1. Verificar visualmente en Chrome DevTools la UI de borrado
+2. Verificar que el badge "pendiente" aparece y desaparece correctamente
diff --git a/Docs/plans/security-stream-token.md b/Docs/plans/security-stream-token.md
new file mode 100644
index 0000000..1a08e21
--- /dev/null
+++ b/Docs/plans/security-stream-token.md
@@ -0,0 +1,131 @@
+# Phase 2.2 — Per-task stream token (deferred)
+
+Status: deferred. Requires coordinated change in the web app
+(`torrentclaw-web`) and the CLI daemon. Pulled out of the Phase 2
+security pass because the CLI-only fixes (UPnP opt-in, SSE caps,
+signed self-update) ship without web-side work; the stream-token
+work cannot.
+
+## Problem
+
+`/stream`, `/playlist.m3u` and `/hls/<sessionID>/...` on the daemon
+HTTP server have no authentication. Today, anyone who can reach the
+listener and guesses (or learns) the `taskID` (for `/stream`) or
+`sessionID` (for `/hls`) can fetch the active file.
+
+Mitigations already in place after Phase 1+2:
+
+- `sessionID` is restricted to a safe regex and is a server-issued
+  UUID v4 (122-bit entropy, not enumerable in practice).
+- `/health` no longer leaks the active filename, taskID prefix or
+  client IP to remote callers (loopback diagnostics preserved).
+- UPnP is opt-in, so by default the daemon is not exposed to the
+  public internet.
+- The web client probes `/health` to pick LAN vs Tailscale.
+
+Residual risk:
+
+- On a shared LAN (open Wi-Fi, office network, dorm) any device can
+  reach the listener and brute-force `?id=<taskID>` against
+  `/stream`. taskIDs are also UUIDs, so this is high entropy, but
+  the URL may leak through browser history, sharing, screen capture
+  or a passive logger and there is no second factor.
+- A user who explicitly opts into UPnP exposes the same surface to
+  the entire internet.
+
+A per-task secret carried in the URL closes this without breaking
+the `<video src>` flow (the browser cannot attach `Authorization`
+headers to media elements, but it can append a query parameter).
+
+## Design
+
+Both ends agree on a per-task secret token. The web generates it
+when the user requests streaming; the daemon receives the
+`(taskID, token)` pair and validates the token on every `/stream`
+and `/hls/...` request.
+
+### Web side (`torrentclaw-web`)
+
+When the user clicks "Stream":
+
+1. Generate `streamToken = crypto.randomBytes(32).toString("hex")`
+   server-side (NOT browser, so it never lives in client storage
+   longer than the page lifetime).
+2. Persist `(taskID, streamToken, expiresAt)` in `download_task`
+   (new columns or a sibling table). Token expires e.g. 6 h after
+   issue or on explicit revoke.
+3. Push the token to the daemon over the existing heartbeat / sync
+   channel that already carries `streamRequested`. Add a
+   `streamToken` field next to it. The daemon trusts that channel
+   (it is authenticated agent ↔ origin).
+4. Include the token in the stream URLs the API returns to the
+   browser:
+   `http://<host>:<port>/stream?id=<taskID>&t=<streamToken>` and
+   the `/hls/<sessionID>` URLs gain `?t=<streamToken>` too.
+
+Files that will need to change:
+
+- `src/lib/services/agent.ts` — extend the stream-request payload
+  with `streamToken`.
+- `src/lib/db/schema.ts` — column / table for the token.
+- `src/lib/services/stream-resolve.ts` — append `&t=` to the URLs
+  it builds.
+- `src/lib/stream-probe.ts` — keep probing `/health` (no token),
+  then append `&t=` to the winning stream URL before returning.
+- `src/middleware.ts` — no CORS change required (browser still hits
+  daemon directly).
+
+### CLI side
+
+- `internal/agent/types.go` / `internal/agent/sync.go` — accept and
+  store `streamToken` next to `streamRequested`.
+- `internal/agent/daemon.go` — when the heartbeat reports a new
+  active stream task, push the token into the stream server via a
+  setter: `streamSrv.SetTaskToken(taskID, token)`.
+- `internal/engine/stream_server.go`:
+    - New field `tokens map[string]string` guarded by mutex.
+    - `SetTaskToken(taskID, token)` and `ClearTaskToken(taskID)`.
+    - `handler` (`/stream`) extracts `?id=` and `?t=`, checks the
+      token with `subtle.ConstantTimeCompare`; 404 on mismatch.
+    - `hlsHandler` (`/hls/<sessionID>/...`) needs an HLS-session
+      → token mapping, since the path carries `sessionID` not
+      `taskID`. Store the token on the `HLSSession` at start and
+      validate per request.
+
+### Backwards compatibility
+
+- The daemon must accept token-less requests for one minor version
+  so a newer daemon can still serve an older web (and vice-versa).
+  Gate the check on a config flag (`require_stream_token`,
+  default false in the first release, default true in the next).
+- The `<video src>` form supports query parameters, so the only
+  user-visible change is the URL string.
+
+## Open questions to resolve before implementing
+
+1. Token TTL. 6 h gives plenty of room for a movie + pause +
+   resume; longer means the post-leak window is wider.
+2. Where to store the token in `download_task` — same row, or a
+   sibling `download_stream_token` table that we can rotate
+   without writing to the task row.
+3. Should `/playlist.m3u` (VLC) embed the token directly, or use
+   a one-shot redeem URL? VLC URL ends up in history.
+4. Token reuse across HLS reconnects — yes, scoped to the
+   `HLSSession`, invalidated on `Close()`.
+5. Do we want a daemon flag `--require-stream-token` independent
+   of config, for users to flip on quickly without editing TOML?
+
+## Effort estimate
+
+- CLI: ~3 h
+- Web: ~3 h
+- Migration + rollout (config flag flip): 1 release cycle of soak.
+
+## Why not now
+
+- Cross-repo coordination raises commit blast radius beyond what
+  the Phase 2 security pass should carry.
+- Web work needs DB migration + UI surfaces (the "stream link
+  expired" path).
+- Phase 2 hardenings ship value today without it; this is the
+  defense-in-depth layer on top.
diff --git a/Makefile b/Makefile
index 4a8245e..b3325bc 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all build test lint coverage clean fmt vet check install-hooks
+.PHONY: all build test lint coverage clean fmt vet check install-hooks changelog release release-patch release-minor release-major release-dry ship ship-dry ship-push
 
 BINARY = unarr
 SENTRY_DSN ?=
@@ -19,10 +19,13 @@ test:
 lint:
 	golangci-lint run ./...
 
-## Run tests with coverage report
+## Run tests with coverage report (excludes CLI layer — cmd/ is glue code)
+COVER_PKGS = $(shell go list ./... | grep -v '/cmd')
 coverage:
-	go test -race -coverprofile=coverage.out -covermode=atomic ./...
-	go tool cover -func=coverage.out
+	go test -race -coverprofile=coverage.out -covermode=atomic $(COVER_PKGS)
+	@echo "──────────────────────────────────────"
+	@go tool cover -func=coverage.out | tail -1
+	@echo "──────────────────────────────────────"
 	go tool cover -html=coverage.out -o coverage.html
 
 ## Format code
@@ -45,6 +48,42 @@ install-hooks:
 install:
 	go install ./cmd/unarr/
 
+## Preview changelog for next release
+changelog:
+	@git-cliff --unreleased --strip header
+
+## Create a release: make release-patch, release-minor, release-major, or release V=0.5.0
+release:
+	@test -n "$(V)" || { echo "Usage: make release V=0.5.0"; exit 1; }
+	@./scripts/release.sh $(V)
+
+release-patch:
+	@./scripts/release.sh patch
+
+release-minor:
+	@./scripts/release.sh minor
+
+release-major:
+	@./scripts/release.sh major
+
+## Preview release without making changes
+release-dry:
+	@test -n "$(V)" || { echo "Usage: make release-dry V=patch|minor|major|0.5.0"; exit 1; }
+	@./scripts/release.sh --dry-run $(V)
+
+## Ship a release end-to-end (goreleaser + Hetzner + Docker Hub). Standalone backup for GH Actions.
+## Reads version from internal/cmd/version.go unless V= is provided.
+ship:
+	@./scripts/ship.sh $(V)
+
+## Ship + git push tag to GH afterwards
+ship-push:
+	@./scripts/ship.sh --push $(V)
+
+## Preview ship steps without executing
+ship-dry:
+	@./scripts/ship.sh --dry-run $(V)
+
 ## Remove generated files
 clean:
 	rm -f $(BINARY) coverage.out coverage.html
diff --git a/README.md b/README.md
index 340147c..75c9c62 100644
--- a/README.md
+++ b/README.md
@@ -11,9 +11,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Go Version](https://img.shields.io/github/go-mod/go-version/torrentclaw/unarr)](go.mod)
 
-Powerful terminal tool for torrent search and management. **Free and open source.**
+The single-binary terminal client for torrent, debrid, and usenet downloads. **Free and open source.**
 
-Search 30+ torrent sources, inspect torrent quality, discover popular content, find streaming providers, and manage your media collection — all from your terminal.
+Built-in torrent engine, debrid (Real-Debrid / AllDebrid), and NZB support. Stream to mpv/vlc, transcode on the fly with hardware acceleration, and manage your library — one binary or a headless daemon with WireGuard split-tunnel and Cloudflare Funnel remote access.
 
 <!-- GIF demo placeholder -->
 <!-- ![unarr Demo](docs/demo.gif) -->
@@ -171,6 +171,9 @@ unarr start
 | `unarr status` | Show daemon status and active downloads |
 | `unarr daemon install` | Install as system service (systemd/launchd) |
 | `unarr daemon uninstall` | Remove the system service |
+| `unarr vpn status` | Show managed-VPN config and live tunnel state |
+| `unarr vpn enable` | Turn the managed VPN on |
+| `unarr vpn disable` | Turn the managed VPN off |
 
 ### System & Diagnostics
 
@@ -280,6 +283,53 @@ The daemon connects via WebSocket for instant task delivery, with automatic HTTP
 - Linux: `~/.config/systemd/user/unarr.service` (systemd)
 - macOS: `~/Library/LaunchAgents/com.torrentclaw.unarr.plist` (launchd)
 
+## VPN
+
+unarr can route your **downloads** through a managed WireGuard VPN, so peers and
+trackers see the VPN server's IP instead of yours. It runs entirely in userspace
+(wireguard-go + a gVisor netstack) — **no root, no `wg-quick`, no changes to your
+OS routing table**.
+
+Requires a **PRO+ plan with the VPN add-on**. Set it up at
+[torrentclaw.com/vpn](https://torrentclaw.com/vpn).
+
+```bash
+# Turn it on (writes [downloads.vpn] enabled = true to your config)
+unarr vpn enable
+
+# Restart the daemon so it brings the tunnel up at startup
+unarr daemon restart        # or: unarr start (if not installed as a service)
+
+# Check it's working — shows the exit server when the tunnel is up
+unarr vpn status
+
+# Verify your account is provisioned (queries the API)
+unarr vpn status --check
+
+# Turn it off again
+unarr vpn disable
+```
+
+**Split-tunnel — read this:** only the torrent client's traffic goes through the
+VPN. Your browser, `curl`, and every other app keep using your **real IP** — that
+is by design. To check the VPN is working, look at `unarr vpn status` (or the
+peer/announce IP), **not** your browser's "what's my IP". To protect your other
+devices (phone, laptop), use the **OpenVPN credentials** from your profile — those
+support ~10 concurrent devices and do **not** share the agent's WireGuard slot.
+
+**When does it fetch the config?** Once, at daemon startup. There's no periodic
+refresh — after changing your exit server in the web panel or re-provisioning,
+restart the daemon to pick it up. If the fetch fails the daemon logs a `[vpn]`
+line and downloads in the clear (never refuses to run).
+
+**Self-hosted / personal VPN:** instead of the managed config, point unarr at a
+local WireGuard `.conf`:
+
+```toml
+[downloads.vpn]
+config_file = "/path/to/wg.conf"   # takes precedence over `enabled`
+```
+
 ## Diagnostics
 
 ```bash
@@ -293,6 +343,58 @@ unarr self-update --force   # reinstall even if up to date
 
 `unarr doctor` checks: config file, API key, server connectivity (with latency), agent registration, download directory, disk space, and version.
 
+### Updating unarr
+
+unarr supports three update paths. Pick whichever fits your workflow.
+
+**1. Manual self-update (always available).**
+
+```bash
+unarr self-update                # interactive update to latest
+unarr self-update --force        # reinstall same version
+unarr self-update --allow-unsigned # accept releases without checksum signature
+```
+
+The CLI downloads the new release archive over HTTPS (from
+`torrentclaw.com/releases/download/v<ver>/`), verifies SHA-256, swaps the
+binary in place (`.backup` kept next to it), and restarts the systemd
+user unit if the daemon is running.
+
+**2. Auto-apply on server signal (default, since 0.9.6).**
+
+When you press **"Force update now"** on the web (Settings → Agent → Force
+update), the server sets a flag your daemon polls every sync (~3 s). On
+the next sync the daemon downloads the new binary, replaces itself, and
+exits — `systemd Restart=always` respawns on the new version. No SSH, no
+terminal access required. Works headless on NAS / Docker.
+
+The button shows an amber warning if your agent is below 0.9.6 (older
+daemons see the signal but only log "run unarr update" — the operator
+must run the command manually that one time).
+
+**Opt out of auto-apply.** Some users prefer reviewing CHANGELOG before
+applying. Disable in `config.toml`:
+
+```toml
+[daemon]
+auto_upgrade = false
+```
+
+With `auto_upgrade = false`, pressing the web button still flags your
+agent (so the daemon logs the new version on next sync), but the daemon
+will not download / replace anything — you run `unarr self-update` when
+you're ready.
+
+**3. Docker auto-restart with a new tag.**
+
+```bash
+docker pull torrentclaw/unarr:latest
+docker compose up -d
+```
+
+Tags published: `latest`, `0.9`, `0.9.7`, ... — pin to a minor (`0.9`)
+for opt-in patch updates without surprises.
+
 ## Clean
 
 Remove temporary files, logs, resume data, and other artifacts generated by unarr. Shows what will be removed and asks for confirmation before deleting.
@@ -374,6 +476,7 @@ tv_shows_dir = "~/Media/TV Shows"
 [daemon]
 poll_interval = "30s"
 heartbeat_interval = "30s"
+auto_upgrade = true   # apply server-flagged upgrades in-place (since 0.9.6)
 
 [notifications]
 enabled = true
@@ -382,6 +485,142 @@ enabled = true
 country = "US"
 ```
 
+### Streaming reference
+
+The in-browser player on torrentclaw.com streams from the daemon over HLS
+(HTTP fragments + ffmpeg transcode for codecs the browser can't decode
+natively). Enabled by default — a fresh install "just works" without editing
+the TOML.
+
+```toml
+[downloads.transcode]
+enabled        = true        # master switch
+hw_accel       = "auto"      # auto | none | nvenc | qsv | vaapi | videotoolbox
+preset         = "veryfast"  # libx264 preset
+video_bitrate  = ""          # e.g. "5M" caps -b:v; empty = engine fallback (5M)
+audio_bitrate  = "192k"      # e.g. "128k", "192k", "256k"
+max_height     = 0           # 0 = no cap; e.g. 720 forces 720p max
+max_concurrent = 2           # max simultaneous ffmpeg processes
+```
+
+#### `[downloads.transcode]`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `enabled` | bool | `true` | Real-time HLS transcoding when source codec is browser-incompatible (HEVC, AV1, AC3, DTS). Requires `ffmpeg` + `ffprobe` on PATH. |
+| `hw_accel` | string | `"auto"` | Hardware accel: `"auto"`, `"none"`, `"nvenc"` (NVIDIA), `"qsv"` (Intel), `"vaapi"` (Linux), `"videotoolbox"` (macOS). |
+| `preset` | string | `"veryfast"` | libx264 preset. Slower preset = smaller files but higher CPU. Options: `ultrafast`, `superfast`, `veryfast`, `faster`, `fast`, `medium`, `slow`, `slower`, `veryslow`. |
+| `video_bitrate` | string | `""` | E.g. `"5M"` caps `-b:v`. Empty falls back to the engine default (`5M`). |
+| `audio_bitrate` | string | `"192k"` | E.g. `"128k"`, `"256k"`. |
+| `max_height` | int | `0` | `0` = no cap. E.g. `720` forces 720p max — useful on weak GPUs. |
+| `max_concurrent` | int | `2` | Max simultaneous ffmpeg processes. Increase if hosting multiple users on a beefy box. |
+
+If `transcode.enabled = true` but `ffmpeg` / `ffprobe` aren't on PATH, the
+daemon logs a warning at startup and HLS sessions are rejected at runtime
+with a clear error — install ffmpeg or set `enabled = false`.
+
+#### `[downloads.hls_cache]` — persistent HLS segment cache
+
+```toml
+[downloads.hls_cache]
+enabled = true   # on by default
+size_gb = 5      # disk budget; LRU eviction once exceeded
+dir     = ""     # custom path; empty = ~/.cache/unarr/hls-cache
+```
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `enabled` | bool | `true` | Persists finished HLS encodes per `(source, quality, audio_index)`. A second play of the same file at the same quality reuses the segments — no ffmpeg, near-zero CPU, instant playback. Set to `false` to delete segments on session close (original behavior). |
+| `size_gb` | int | `5` | Cache budget in gigabytes. When exceeded the LRU sweeper evicts the least-recently-used cached encodes hourly. Minimum 1 GB (smaller values are clamped up). |
+| `dir` | string | `""` | Custom storage path. Empty defaults to `~/.cache/unarr/hls-cache` (Linux/macOS) or the user cache dir (Windows). |
+
+**What it does.** First play encodes normally (ffmpeg writes segments).
+On session close, if every segment is on disk and ffmpeg exited cleanly,
+the directory is sealed with a `.complete` marker and kept. Next time the
+same source + quality combo is requested, the daemon serves segments
+straight from disk — no transcode, no warm-up, no CPU cost.
+
+**Why per (source, quality, audio).** Renaming the file or switching
+quality invalidates the entry: the segments are tied to the exact source
+bytes and the exact ffmpeg parameters. Re-encoding generates a new key.
+
+**Eviction.** A background goroutine wakes every hour. If total cache size
+exceeds `size_gb`, it deletes the oldest entries (by mtime) until under
+budget. Active sessions are pinned — they never get evicted mid-play.
+
+**Disable.** Either edit the TOML to set `enabled = false`, or remove the
+cache directory manually (it'll be recreated as needed). Disabling does
+not delete existing cached segments — drop `dir` (or `~/.cache/unarr/hls-cache`)
+to reclaim the space.
+
+#### `[downloads.vpn]`
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `enabled` | bool | `false` | Managed VPN: at startup the daemon fetches a WireGuard config from your account and split-tunnels torrent traffic through it. Needs a PRO+ plan with the VPN add-on. Toggle with `unarr vpn enable` / `disable`. |
+| `config_file` | string | `""` | Self-hosted / personal VPN: path to a local WireGuard `.conf`. **Takes precedence over `enabled`** — when set, the daemon uses this file and never calls the API. |
+
+See the [VPN](#vpn) section above for how it works (split-tunnel, no root) and
+how to protect your other devices.
+
+#### `[downloads.funnel]` — public HTTPS hostname for the daemon (CloudFlare Quick Tunnel)
+
+```toml
+[downloads.funnel]
+enabled = false   # off by default
+```
+
+| Key | Type | Default | Notes |
+|-----|------|---------|-------|
+| `enabled` | bool | `false` | Spawns `cloudflared tunnel --url http://localhost:<stream_port>` as a child process at daemon startup. Toggle with `unarr funnel on` / `off`. Requires `cloudflared` on PATH. |
+
+**What it does.** Without a tunnel, the daemon is reachable on `localhost`,
+your LAN, and (if installed) Tailscale. That covers the same-machine and
+Tailscale-connected cases, but the **browser-based player on torrentclaw.com
+fails on any other network** because HTTPS pages can't fetch HTTP resources
+("mixed content"). Enabling the funnel gives the daemon a public
+`https://<random>.trycloudflare.com` hostname so the web player picks it up
+and playback works from anywhere — phone on cellular, friend's laptop on a
+foreign Wi-Fi, anywhere. The Stremio addon already works cross-network
+(native mpv/VLC players ignore CORS), so this is strictly a web-player fix.
+
+**Privacy posture.** Bytes pass through CloudFlare's edge — TorrentClaw never
+relays content (we don't see your traffic), CloudFlare does. Quick Tunnels
+are **anonymous** (no CF account required); the registration is unauthenticated
+and the hostname is a random label, but CF logs request metadata like any CDN
+would. If you want zero third-party byte access, use Tailscale instead.
+
+**Limitations (free Quick Tunnels).**
+| Aspect | Limit |
+|--------|-------|
+| Session lifetime | ~6 hours, then the hostname rotates. cloudflared re-registers automatically; the web picks up the new URL on the next sync. In-flight HLS sessions break across the rotation (browser retries). |
+| Bandwidth | No documented hard cap, but CF reserves the right to throttle. 1080p HLS (~6 Mbps) is fine; 4K HEVC at 25 Mbps may hit throttling. |
+| Latency | +20–80 ms vs direct LAN/Tailscale (extra hop browser → CF edge → tunnel). HLS player buffer absorbs it. |
+| Concurrency | One tunnel serves N viewers. CF rate-limits ~200 req/s, plenty for HLS segments. |
+| TOS | CloudFlare flags Quick Tunnels as "not for production traffic". They can decommission an abusive tunnel without notice. |
+
+For heavy / high-throughput / persistent-URL use cases, switch to a CloudFlare
+Named Tunnel (free, needs a CF account) or run your own reverse proxy — both
+out of scope for the bundled command.
+
+**Disable.** `unarr funnel off` flips `enabled` to `false` in the TOML and
+prompts you to restart the daemon. You can also edit `config.toml` directly:
+
+```toml
+[downloads.funnel]
+enabled = false
+```
+
+**Install cloudflared.**
+- Linux: `apt install cloudflared` (after adding CF's apt repo) — see
+  <https://pkg.cloudflare.com>. Or pull the static binary from
+  <https://github.com/cloudflare/cloudflared/releases>.
+- macOS: `brew install cloudflared`.
+- Windows: `winget install --id Cloudflare.cloudflared`.
+
+If `cloudflared` is not on PATH the daemon logs a warning at startup and
+falls back to LAN/Tailscale-only reachability.
+
 ### Environment variables
 
 Environment variables override config file values:
diff --git a/SECURITY.md b/SECURITY.md
index a7a3399..b88b335 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -59,6 +59,50 @@ This project follows these security practices:
 - **Non-root Docker** — Container runs as unprivileged user (UID 1000)
 - **Dependency scanning** — Automated via Dependabot
 
+## Container Image Vulnerability Scanning
+
+The Docker image (`torrentclaw/unarr`) is scanned by Docker Scout on Docker Hub and
+by a CVE gate in CI (see `.github/workflows/`). Two things matter when reading the
+Docker Hub vulnerability count:
+
+- **Scanner database differs.** Docker Hub (Scout) matches `package@version` against
+  NVD/GHSA. Trivy/Alpine `secdb` only lists CVEs Alpine has acknowledged and patched.
+  A high Scout count with a clean Trivy report is expected, not a contradiction.
+- **The bulk comes from the bundled `ffmpeg` codec stack.** Alpine's `ffmpeg`
+  package pulls ~40 codec/parser libraries (`x264`, `x265`, `libvpx`, `aom`,
+  `dav1d`, `libtheora`, `libvorbis`, `libwebp`, `libbluray`, `libopenmpt`, …).
+  Each carries a long NVD history that Alpine does not backport. ffmpeg is a
+  **functional dependency** — the HLS transcode pipeline shells out to
+  `ffmpeg`/`ffprobe` to decode untrusted media and re-encode to H.264 + AAC.
+
+### Accepted risk and policy
+
+- **Fixable** CRITICAL/HIGH findings **block** a release (CI CVE gate, `only-fixed`).
+- **Unfixed-upstream** codec CVEs are tracked but **accepted**: there is no patched
+  Alpine package to move to, and dropping codecs would break playback of common
+  formats. They are mitigated by the hardening below rather than eliminated.
+- Images are **rebuilt and re-pushed weekly** (scheduled workflow) so any newly
+  *fixed* base/ffmpeg/Go patch lands between tagged releases.
+
+### Mitigations (run the container hardened)
+
+Crafted media (torrents are untrusted input) is the realistic attack vector against
+ffmpeg's parsers. The shipped `docker-compose.yml` already applies:
+
+- **Non-root** user (UID 1000), **read-only** root filesystem, writable `tmpfs` only.
+- **Resource limits** (memory/CPU) to bound a runaway decode.
+
+Recommended additions for exposed deployments:
+
+```yaml
+    cap_drop: ["ALL"]
+    security_opt:
+      - no-new-privileges:true
+```
+
+If you do not need HLS transcoding, you can run with transcoding disabled to
+avoid feeding untrusted media to ffmpeg at all.
+
 ## Disclosure Policy
 
 We follow coordinated disclosure. We will credit reporters in the release notes unless they prefer to remain anonymous.
diff --git a/cliff.toml b/cliff.toml
new file mode 100644
index 0000000..c5efe7f
--- /dev/null
+++ b/cliff.toml
@@ -0,0 +1,79 @@
+# git-cliff configuration
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+header = """# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n
+"""
+body = """
+{%- macro remote_url() -%}
+  https://github.com/torrentclaw/unarr
+{%- endmacro -%}
+
+{% if version -%}
+  ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{%- else -%}
+  ## [Unreleased]
+{%- endif %}
+
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | striptags | trim | upper_first }}
+{% for commit in commits
+| filter(attribute="scope")
+| sort(attribute="scope") %}
+  - **{{ commit.scope }}**: {{ commit.message }}
+    {%- if commit.breaking %} (**BREAKING**){% endif %}
+{%- endfor -%}
+{% for commit in commits %}
+  {%- if not commit.scope %}
+  - {{ commit.message }}
+    {%- if commit.breaking %} (**BREAKING**){% endif %}
+  {%- endif %}
+{%- endfor %}
+{% endfor %}
+"""
+footer = """
+{%- macro remote_url() -%}
+  https://github.com/torrentclaw/unarr
+{%- endmacro -%}
+
+{% for release in releases -%}
+  {% if release.version -%}
+    {% if release.previous.version -%}
+      [{{ release.version | trim_start_matches(pat="v") }}]: {{ self::remote_url() }}/compare/{{ release.previous.version }}...{{ release.version }}
+    {% else -%}
+      [{{ release.version | trim_start_matches(pat="v") }}]: {{ self::remote_url() }}/releases/tag/{{ release.version }}
+    {% endif -%}
+  {% else -%}
+    {% if release.previous.version -%}
+      [Unreleased]: {{ self::remote_url() }}/compare/{{ release.previous.version }}...HEAD
+    {% endif -%}
+  {% endif -%}
+{% endfor %}
+"""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = true
+split_commits = false
+commit_parsers = [
+  { message = "^feat", group = "Added" },
+  { message = "^fix", group = "Fixed" },
+  { message = "^perf", group = "Performance" },
+  { message = "^refactor", group = "Changed" },
+  { message = "^style", group = "Changed" },
+  { message = "^doc", group = "Documentation" },
+  { message = "^ci", group = "CI/CD" },
+  { message = "^chore\\(deps\\)", skip = true },
+  { message = "^chore", group = "Other" },
+  { message = "^test", skip = true },
+]
+protect_breaking_commits = false
+filter_commits = false
+tag_pattern = "v[0-9].*"
+sort_commits = "newest"
diff --git a/go.mod b/go.mod
index 8cefa35..a47f6e3 100644
--- a/go.mod
+++ b/go.mod
@@ -7,17 +7,17 @@ require (
 	github.com/anacrolix/dht/v2 v2.23.0
 	github.com/anacrolix/log v0.17.1-0.20251118025802-918f1157b7bb
 	github.com/anacrolix/torrent v1.61.0
-	github.com/anacrolix/upnp v0.1.4
 	github.com/charmbracelet/huh v1.0.0
 	github.com/fatih/color v1.19.0
 	github.com/getsentry/sentry-go v0.44.1
 	github.com/google/uuid v1.6.0
-	github.com/gorilla/websocket v1.5.3
+	github.com/huin/goupnp v1.3.0
 	github.com/olekukonko/tablewriter v1.1.4
 	github.com/spf13/cobra v1.10.2
 	github.com/torrentclaw/go-client v0.2.0
-	golang.org/x/term v0.41.0
+	golang.org/x/term v0.43.0
 	golang.org/x/time v0.15.0
+	golang.zx2c4.com/wireguard v0.0.0-20250521234502-f333402bd9cb
 )
 
 require (
@@ -35,6 +35,7 @@ require (
 	github.com/anacrolix/multiless v0.4.0 // indirect
 	github.com/anacrolix/stm v0.5.0 // indirect
 	github.com/anacrolix/sync v0.6.0 // indirect
+	github.com/anacrolix/upnp v0.1.4 // indirect
 	github.com/anacrolix/utp v0.2.0 // indirect
 	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
@@ -68,6 +69,7 @@ require (
 	github.com/google/btree v1.1.3 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/pprof v0.0.0-20260302011040-a15ffb7f9dcc // indirect
+	github.com/gorilla/websocket v1.5.3 // indirect
 	github.com/huandu/xstrings v1.5.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
@@ -120,12 +122,14 @@ require (
 	go.opentelemetry.io/otel v1.42.0 // indirect
 	go.opentelemetry.io/otel/metric v1.42.0 // indirect
 	go.opentelemetry.io/otel/trace v1.42.0 // indirect
-	golang.org/x/crypto v0.49.0 // indirect
+	golang.org/x/crypto v0.51.0 // indirect
 	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 // indirect
-	golang.org/x/net v0.52.0 // indirect
+	golang.org/x/net v0.54.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
-	golang.org/x/text v0.35.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
+	golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 // indirect
+	gvisor.dev/gvisor v0.0.0-20250503011706-39ed1f5ac29c // indirect
 	lukechampine.com/blake3 v1.4.1 // indirect
 	modernc.org/libc v1.70.0 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
diff --git a/go.sum b/go.sum
index 653faf6..d1c9fe6 100644
--- a/go.sum
+++ b/go.sum
@@ -260,6 +260,8 @@ github.com/huandu/xstrings v1.2.0/go.mod h1:DvyZB1rfVYsBIigL8HwpZgxHwXozlTgGqn63
 github.com/huandu/xstrings v1.3.1/go.mod h1:y5/lhBue+AyNmUVz9RLU9xbLR0o4KIIExikq4ovT0aE=
 github.com/huandu/xstrings v1.5.0 h1:2ag3IFq9ZDANvthTwTiqSSZLjDc+BedvHPAp5tJy2TI=
 github.com/huandu/xstrings v1.5.0/go.mod h1:y5/lhBue+AyNmUVz9RLU9xbLR0o4KIIExikq4ovT0aE=
+github.com/huin/goupnp v1.3.0 h1:UvLUlWDNpoUdYzb2TCn+MuTWtcjXKSza2n6CBdQ0xXc=
+github.com/huin/goupnp v1.3.0/go.mod h1:gnGPsThkYa7bFi/KWmEysQRf48l2dvR5bxr2OFckNX8=
 github.com/ianlancetaylor/demangle v0.0.0-20230524184225-eabc099b10ab/go.mod h1:gx7rwoVhcfuVKG5uya9Hs3Sxj7EIvldVofAWIUtGouw=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
@@ -471,8 +473,8 @@ golang.org/x/crypto v0.0.0-20180904163835-0709b304e793/go.mod h1:6SG95UA2DQfeDnf
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
-golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
-golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
 golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
 golang.org/x/exp v0.0.0-20220428152302-39d4317da171/go.mod h1:lgLbSvA5ygNOMpwM/9anMpWVlVJ7Z+cHWq/eFuinpGE=
 golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 h1:jiDhWWeC7jfWqR9c/uplMOqJ0sbNlNWv0UkzE0vX1MA=
@@ -483,8 +485,8 @@ golang.org/x/lint v0.0.0-20190301231843-5614ed5bae6f/go.mod h1:UVdnD1Gm6xHRNCYTk
 golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
 golang.org/x/mod v0.5.1/go.mod h1:5OXOZSfqPIIbmVBIIKWRFfZjPR0E5r58TLhUjH0a2Ro=
 golang.org/x/mod v0.6.0-dev.0.20211013180041-c96bc1413d57/go.mod h1:3p9vT2HGsQu2K1YbXdKPJLVgG5VJdoTa1poYQBtP1AY=
-golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
-golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
+golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
+golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
 golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
@@ -498,8 +500,8 @@ golang.org/x/net v0.0.0-20190613194153-d28f0bde5980/go.mod h1:z5CRVTTTmAJ677TzLL
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20211015210444-4f30a5c0130f/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
-golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
-golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/net v0.54.0 h1:2zJIZAxAHV/OHCDTCOHAYehQzLfSXuf/5SoL/Dv6w/w=
+golang.org/x/net v0.54.0/go.mod h1:Sj4oj8jK6XmHpBZU/zWHw3BV3abl4Kvi+Ut7cQcY+cQ=
 golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.0.0-20190226205417-e64efc72b421/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw=
 golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -530,18 +532,18 @@ golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20211019181941-9d821ace8654/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
-golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
-golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
-golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
-golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.0.0-20180828015842-6cd1fcedba52/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -552,12 +554,16 @@ golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3
 golang.org/x/tools v0.0.0-20190312170243-e65039ee4138/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.1.8-0.20211029000441-d6a9af8af023/go.mod h1:nABZi5QlRsZVlzPpHl034qft6wpY4eDcsTt5AaioBiU=
-golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
-golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
+golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
+golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 h1:B82qJJgjvYKsXS9jeunTOisW56dUokqW/FOteYJJ/yg=
+golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2/go.mod h1:deeaetjYA+DHMHg+sMSMI58GrEteJUUzzw7en6TJQcI=
+golang.zx2c4.com/wireguard v0.0.0-20250521234502-f333402bd9cb h1:whnFRlWMcXI9d+ZbWg+4sHnLp52d5yiIPUxMBSt4X9A=
+golang.zx2c4.com/wireguard v0.0.0-20250521234502-f333402bd9cb/go.mod h1:rpwXGsirqLqN2L0JDJQlwOboGHmptD5ZD6T2VmcqhTw=
 google.golang.org/api v0.3.1/go.mod h1:6wY9I6uQWHQ8EM57III9mq/AjF+i8G65rmVagqKMtkk=
 google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
 google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
@@ -585,6 +591,8 @@ gopkg.in/yaml.v2 v2.2.5/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gvisor.dev/gvisor v0.0.0-20250503011706-39ed1f5ac29c h1:m/r7OM+Y2Ty1sgBQ7Qb27VgIMBW8ZZhT4gLnUyDIhzI=
+gvisor.dev/gvisor v0.0.0-20250503011706-39ed1f5ac29c/go.mod h1:3r5CMtNQMKIvBlrmM9xWUNamjKBYPOWyXOjmg5Kts3g=
 honnef.co/go/tools v0.0.0-20180728063816-88497007e858/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 lukechampine.com/blake3 v1.4.1 h1:I3Smz7gso8w4/TunLKec6K2fn+kyKtDxr/xcQEN84Wg=
diff --git a/internal/agent/client.go b/internal/agent/client.go
index 9fd6ec8..e7f2c37 100644
--- a/internal/agent/client.go
+++ b/internal/agent/client.go
@@ -12,25 +12,64 @@ import (
 )
 
 // Client communicates with the /api/internal/agent/* endpoints.
+//
+// The client owns a MirrorPool: when a request fails with a transient
+// network error (DNS, refused, timeout, 5xx) it rotates to the next mirror
+// and retries up to `len(mirrors)-1` times so a single agent run survives
+// a primary-domain takedown without user intervention.
 type Client struct {
-	baseURL    string
+	pool       *MirrorPool
 	apiKey     string
 	httpClient *http.Client
-	userAgent  string
+	// wakeClient has no built-in timeout — used exclusively for the long-poll
+	// wake endpoint where the context controls cancellation.
+	wakeClient *http.Client
+	// librarySyncClient has a generous timeout for library-sync calls which can
+	// take several minutes when syncing hundreds or thousands of items.
+	librarySyncClient *http.Client
+	userAgent         string
 }
 
-// NewClient creates an agent API client.
+// NewClient creates an agent API client targeting a single base URL.
+// Equivalent to NewClientWithMirrors(baseURL, nil, ...) — kept for callers
+// that don't yet care about mirror failover.
 func NewClient(baseURL, apiKey, userAgent string) *Client {
+	return NewClientWithMirrors(baseURL, nil, apiKey, userAgent)
+}
+
+// NewClientWithMirrors creates an agent API client that can fail over from
+// the primary base URL to any of the extras when the primary is unreachable.
+// The order of `extras` matters: they're tried left-to-right after a failure.
+func NewClientWithMirrors(baseURL string, extras []string, apiKey, userAgent string) *Client {
 	return &Client{
-		baseURL: baseURL,
-		apiKey:  apiKey,
+		pool:   NewMirrorPool(baseURL, extras),
+		apiKey: apiKey,
 		httpClient: &http.Client{
 			Timeout: 30 * time.Second,
 		},
-		userAgent: userAgent,
+		// wakeClient has no built-in timeout — the context controls it.
+		// The server holds the connection for up to 28s before responding.
+		wakeClient: &http.Client{},
+		// librarySyncClient uses a 10-minute timeout to handle large libraries
+		// (hundreds or thousands of items) where ffprobe scanning alone can take
+		// several minutes before the HTTP request is even sent.
+		librarySyncClient: &http.Client{Timeout: 10 * time.Minute},
+		userAgent:         userAgent,
 	}
 }
 
+// MirrorPool exposes the underlying pool so callers (e.g. the `unarr mirrors`
+// subcommand) can swap the list at runtime after fetching /api/v1/mirrors.
+func (c *Client) MirrorPool() *MirrorPool {
+	return c.pool
+}
+
+// baseURL returns the currently-active mirror. Routed through this helper so
+// future changes (e.g. per-endpoint mirror affinity) only need one edit.
+func (c *Client) baseURL() string {
+	return c.pool.Current()
+}
+
 // Register registers the CLI agent with the server and returns user info + features.
 func (c *Client) Register(ctx context.Context, req RegisterRequest) (*RegisterResponse, error) {
 	var resp RegisterResponse
@@ -40,27 +79,6 @@ func (c *Client) Register(ctx context.Context, req RegisterRequest) (*RegisterRe
 	return &resp, nil
 }
 
-// Heartbeat sends a periodic keep-alive signal and returns server directives.
-func (c *Client) Heartbeat(ctx context.Context, req HeartbeatRequest) (*HeartbeatResponse, error) {
-	var resp HeartbeatResponse
-	if err := c.doPost(ctx, "/api/internal/agent/heartbeat", req, &resp); err != nil {
-		return nil, fmt.Errorf("heartbeat: %w", err)
-	}
-	return &resp, nil
-}
-
-// ClaimTasks polls for pending download tasks and claims them atomically.
-// Also returns any stream requests for completed downloads.
-func (c *Client) ClaimTasks(ctx context.Context, agentID string) (*TasksResponse, error) {
-	url := fmt.Sprintf("/api/internal/agent/tasks?agentId=%s", agentID)
-	var resp TasksResponse
-	if err := c.doGet(ctx, url, &resp); err != nil {
-		return nil, fmt.Errorf("claim tasks: %w", err)
-	}
-	return &resp, nil
-}
-
-// ReportStatus reports download progress or completion for a task.
 // Deregister notifies the server that the agent is shutting down.
 func (c *Client) Deregister(ctx context.Context, agentID string) error {
 	req := struct {
@@ -73,6 +91,45 @@ func (c *Client) Deregister(ctx context.Context, agentID string) error {
 	return nil
 }
 
+// ReportUpgradeResult tells the server the outcome of a previously requested
+// upgrade so the server can clear `upgrade_requested`. Without this call the
+// flag stays sticky and the daemon would re-trigger applyAutoUpgrade on every
+// sync after upgrade — even for "already on target version" no-ops.
+func (c *Client) ReportUpgradeResult(ctx context.Context, agentID string, success bool, version, errMsg string) error {
+	req := struct {
+		AgentID string `json:"agentId"`
+		Success bool   `json:"success"`
+		Version string `json:"version,omitempty"`
+		Error   string `json:"error,omitempty"`
+	}{AgentID: agentID, Success: success, Version: version, Error: errMsg}
+	var resp StatusResponse
+	if err := c.doPost(ctx, "/api/internal/agent/upgrade-result", req, &resp); err != nil {
+		return fmt.Errorf("report upgrade result: %w", err)
+	}
+	return nil
+}
+
+// MarkSessionReady signals the server that the first HLS segment + init.mp4
+// landed on disk for the given session. The web side flips
+// streaming_session.ready_at = NOW(), which its SSE endpoint emits to
+// subscribed players so the "Preparando…" UI ends without polling HEAD
+// on /hls/<id>/master.m3u8.
+//
+// Best-effort: the server is the source of truth for session state and
+// will reach the same conclusion via HEAD probes anyway if this call
+// fails. We log the error in the caller but don't retry — by the time
+// a retry would land the user is likely already playing.
+func (c *Client) MarkSessionReady(ctx context.Context, sessionID string) error {
+	req := struct {
+		SessionID string `json:"sessionId"`
+	}{SessionID: sessionID}
+	var resp StatusResponse
+	if err := c.doPost(ctx, "/api/internal/agent/session-ready", req, &resp); err != nil {
+		return fmt.Errorf("mark session ready: %w", err)
+	}
+	return 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
@@ -91,6 +148,16 @@ func (c *Client) BatchReportStatus(ctx context.Context, updates []StatusUpdate)
 	return &resp, nil
 }
 
+// Sync sends the CLI's full state and receives all pending server actions.
+// This is the single endpoint for bidirectional state synchronization.
+func (c *Client) Sync(ctx context.Context, req SyncRequest) (*SyncResponse, error) {
+	var resp SyncResponse
+	if err := c.doPost(ctx, "/api/internal/agent/sync", req, &resp); err != nil {
+		return nil, fmt.Errorf("sync: %w", err)
+	}
+	return &resp, nil
+}
+
 // ---------------------------------------------------------------------------
 // Usenet endpoints
 // ---------------------------------------------------------------------------
@@ -107,30 +174,35 @@ func (c *Client) SearchNzbs(ctx context.Context, params NzbSearchParams) (*NzbSe
 // DownloadNzb downloads the NZB file for the given nzbId.
 // Returns the raw NZB XML bytes.
 func (c *Client) DownloadNzb(ctx context.Context, nzbID string) ([]byte, error) {
-	url := fmt.Sprintf("/api/internal/agent/nzb-download?nzbId=%s", nzbID)
+	path := fmt.Sprintf("/api/internal/agent/nzb-download?nzbId=%s", nzbID)
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+url, nil)
-	if err != nil {
-		return nil, fmt.Errorf("create request: %w", err)
-	}
-	c.setHeaders(req)
+	var out []byte
+	err := c.withMirrorFailover(func(base string) error {
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, base+path, nil)
+		if err != nil {
+			return fmt.Errorf("create request: %w", err)
+		}
+		c.setHeaders(req)
 
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("request failed: %w", err)
-	}
-	defer resp.Body.Close()
+		resp, err := c.httpClient.Do(req)
+		if err != nil {
+			return fmt.Errorf("request failed: %w", err)
+		}
+		defer resp.Body.Close()
 
-	if resp.StatusCode >= 400 {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<16))
-		return nil, fmt.Errorf("nzb download error %d: %s", resp.StatusCode, string(body))
-	}
+		if resp.StatusCode >= 400 {
+			body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<16))
+			return &HTTPError{StatusCode: resp.StatusCode, Message: string(body)}
+		}
 
-	data, err := io.ReadAll(io.LimitReader(resp.Body, 100<<20)) // 100MB limit
-	if err != nil {
-		return nil, fmt.Errorf("read nzb: %w", err)
-	}
-	return data, nil
+		data, err := io.ReadAll(io.LimitReader(resp.Body, 100<<20)) // 100MB limit
+		if err != nil {
+			return fmt.Errorf("read nzb: %w", err)
+		}
+		out = data
+		return nil
+	})
+	return out, err
 }
 
 // GetUsenetCredentials fetches NNTP connection credentials.
@@ -170,54 +242,154 @@ func (c *Client) BatchDownload(ctx context.Context, req BatchDownloadRequest) (*
 }
 
 // SyncLibrary sends scanned library items to the server for matching and upgrade discovery.
+// Uses a 10-minute timeout client to handle large libraries where scanning can take several minutes.
 func (c *Client) SyncLibrary(ctx context.Context, req LibrarySyncRequest) (*LibrarySyncResponse, error) {
 	var resp LibrarySyncResponse
-	if err := c.doPost(ctx, "/api/internal/agent/library-sync", req, &resp); err != nil {
+	if err := c.doPostWith(ctx, c.librarySyncClient, "/api/internal/agent/library-sync", req, &resp); err != nil {
 		return nil, fmt.Errorf("library sync: %w", err)
 	}
 	return &resp, nil
 }
 
-// doPost sends a JSON POST request and decodes the response.
+// ReportWatchProgress sends playback position to the server for watch tracking.
+func (c *Client) ReportWatchProgress(ctx context.Context, update WatchProgressUpdate) error {
+	var resp WatchProgressResponse
+	if err := c.doPost(ctx, "/api/internal/agent/watch-progress", update, &resp); err != nil {
+		return fmt.Errorf("watch progress: %w", err)
+	}
+	return nil
+}
+
+// WaitForWake blocks until the server sends a wake signal, the long-poll
+// timeout elapses, or ctx is cancelled. Returns true when a wake signal
+// was received (caller should sync immediately), false on timeout/cancel.
+//
+// Wake is a long-poll on a single mirror — failover here would just drop
+// the connection and try again immediately, which the server already
+// handles with a fresh wait loop. We only retry against the next mirror
+// when the current one is definitively unreachable (DNS / refused / TLS).
+func (c *Client) WaitForWake(ctx context.Context) (bool, error) {
+	var wake bool
+	err := c.withMirrorFailover(func(base string) error {
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, base+"/api/internal/agent/wake", nil)
+		if err != nil {
+			return fmt.Errorf("create wake request: %w", err)
+		}
+		c.setHeaders(req)
+
+		resp, err := c.wakeClient.Do(req)
+		if err != nil {
+			return fmt.Errorf("wake request failed: %w", err)
+		}
+		defer resp.Body.Close()
+
+		if resp.StatusCode >= 400 {
+			body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<10))
+			return &HTTPError{StatusCode: resp.StatusCode, Message: string(body)}
+		}
+
+		var result struct {
+			Wake bool `json:"wake"`
+		}
+		if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+			return fmt.Errorf("decode wake response: %w", err)
+		}
+		wake = result.Wake
+		return nil
+	})
+	return wake, err
+}
+
+// doPost sends a JSON POST request using the default httpClient and decodes the response.
 func (c *Client) doPost(ctx context.Context, path string, body any, dst any) error {
+	return c.doPostWith(ctx, c.httpClient, path, body, dst)
+}
+
+// doPostWith sends a JSON POST request using the provided HTTP client and decodes the response.
+// Use this to override the default timeout for specific operations (e.g. librarySyncClient).
+// Wrapped in withMirrorFailover so a transient connection failure on the
+// active mirror retries against the next one.
+func (c *Client) doPostWith(ctx context.Context, hc *http.Client, path string, body any, dst any) error {
 	jsonBody, err := json.Marshal(body)
 	if err != nil {
 		return fmt.Errorf("marshal body: %w", err)
 	}
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+path, bytes.NewReader(jsonBody))
-	if err != nil {
-		return fmt.Errorf("create request: %w", err)
-	}
+	return c.withMirrorFailover(func(base string) error {
+		req, err := http.NewRequestWithContext(ctx, http.MethodPost, base+path, bytes.NewReader(jsonBody))
+		if err != nil {
+			return fmt.Errorf("create request: %w", err)
+		}
 
-	c.setHeaders(req)
-	req.Header.Set("Content-Type", "application/json")
+		c.setHeaders(req)
+		req.Header.Set("Content-Type", "application/json")
 
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return fmt.Errorf("request failed: %w", err)
-	}
-	defer resp.Body.Close()
+		resp, err := hc.Do(req)
+		if err != nil {
+			return fmt.Errorf("request failed: %w", err)
+		}
+		defer resp.Body.Close()
 
-	return c.handleResponse(resp, dst)
+		return c.handleResponse(resp, dst)
+	})
 }
 
 // doGet sends a GET request and decodes the response.
 func (c *Client) doGet(ctx context.Context, path string, dst any) error {
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil)
-	if err != nil {
-		return fmt.Errorf("create request: %w", err)
+	return c.withMirrorFailover(func(base string) error {
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, base+path, nil)
+		if err != nil {
+			return fmt.Errorf("create request: %w", err)
+		}
+
+		c.setHeaders(req)
+
+		resp, err := c.httpClient.Do(req)
+		if err != nil {
+			return fmt.Errorf("request failed: %w", err)
+		}
+		defer resp.Body.Close()
+
+		return c.handleResponse(resp, dst)
+	})
+}
+
+// withMirrorFailover runs `fn` against the current mirror; on a transient
+// error it rotates the pool and retries up to `len(mirrors)-1` times.
+//
+// The active mirror is updated on rotation so subsequent unrelated calls
+// stick to the working host until that host fails too — this avoids
+// hammering a known-bad primary on every request, while still trying it
+// again next time the agent reloads (no permanent demotion).
+func (c *Client) withMirrorFailover(fn func(base string) error) error {
+	attempts := c.pool.Len()
+	if attempts < 1 {
+		attempts = 1
 	}
 
-	c.setHeaders(req)
-
-	resp, err := c.httpClient.Do(req)
-	if err != nil {
-		return fmt.Errorf("request failed: %w", err)
+	var lastErr error
+	for i := 0; i < attempts; i++ {
+		base := c.baseURL()
+		err := fn(base)
+		if err == nil {
+			return nil
+		}
+		lastErr = err
+		if !IsTransient(err) {
+			return err
+		}
+		// Last attempt: don't bother rotating, just surface the error.
+		if i == attempts-1 {
+			break
+		}
+		next, rotated := c.pool.Rotate()
+		if !rotated {
+			break
+		}
+		_ = next // mirror rotation logging is left to higher layers (cmd/) so the
+		// pool stays log-free for tests.
 	}
-	defer resp.Body.Close()
-
-	return c.handleResponse(resp, dst)
+	return lastErr
 }
 
 func (c *Client) setHeaders(req *http.Request) {
@@ -237,14 +409,14 @@ func (c *Client) handleResponse(resp *http.Response, dst any) error {
 		// Try to parse as JSON error
 		var errResp ErrorResponse
 		if json.Unmarshal(body, &errResp) == nil && errResp.Error != "" {
-			return fmt.Errorf("API error %d: %s", resp.StatusCode, errResp.Error)
+			return &HTTPError{StatusCode: resp.StatusCode, Message: errResp.Error}
 		}
 		// Non-JSON response (e.g. HTML error page) — truncate to something readable
 		msg := string(body)
 		if len(msg) > 120 || strings.Contains(msg, "<html") || strings.Contains(msg, "<!DOCTYPE") {
 			msg = fmt.Sprintf("server returned %s (non-JSON response, likely a server error)", resp.Status)
 		}
-		return fmt.Errorf("API error %d: %s", resp.StatusCode, msg)
+		return &HTTPError{StatusCode: resp.StatusCode, Message: msg}
 	}
 
 	if dst != nil {
diff --git a/internal/agent/client_test.go b/internal/agent/client_test.go
index 9266b74..d905de4 100644
--- a/internal/agent/client_test.go
+++ b/internal/agent/client_test.go
@@ -3,9 +3,11 @@ package agent
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"testing"
+	"time"
 )
 
 func TestRegister(t *testing.T) {
@@ -72,70 +74,6 @@ func TestRegister(t *testing.T) {
 	}
 }
 
-func TestHeartbeat(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/api/internal/agent/heartbeat" {
-			t.Errorf("path = %s, want /api/internal/agent/heartbeat", r.URL.Path)
-		}
-		var req HeartbeatRequest
-		json.NewDecoder(r.Body).Decode(&req)
-		if req.AgentID != "agent-123" {
-			t.Errorf("agentId = %q, want agent-123", req.AgentID)
-		}
-		json.NewEncoder(w).Encode(HeartbeatResponse{Success: true})
-	}))
-	defer srv.Close()
-
-	c := NewClient(srv.URL, "test-key", "unarr-test")
-	resp, err := c.Heartbeat(context.Background(), HeartbeatRequest{AgentID: "agent-123"})
-	if err != nil {
-		t.Fatalf("Heartbeat failed: %v", err)
-	}
-	if !resp.Success {
-		t.Error("expected success=true")
-	}
-}
-
-func TestClaimTasks(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodGet {
-			t.Errorf("method = %s, want GET", r.Method)
-		}
-		if r.URL.Query().Get("agentId") != "agent-123" {
-			t.Errorf("agentId param = %q, want agent-123", r.URL.Query().Get("agentId"))
-		}
-		json.NewEncoder(w).Encode(TasksResponse{
-			Tasks: []Task{
-				{
-					ID:              "task-uuid-1",
-					InfoHash:        "abc123def456abc123def456abc123def456abc1",
-					Title:           "The Matrix (1999)",
-					PreferredMethod: "auto",
-				},
-			},
-		})
-	}))
-	defer srv.Close()
-
-	c := NewClient(srv.URL, "test-key", "unarr-test")
-	resp, err := c.ClaimTasks(context.Background(), "agent-123")
-	if err != nil {
-		t.Fatalf("ClaimTasks failed: %v", err)
-	}
-	if len(resp.Tasks) != 1 {
-		t.Fatalf("len(tasks) = %d, want 1", len(resp.Tasks))
-	}
-	if resp.Tasks[0].ID != "task-uuid-1" {
-		t.Errorf("task.ID = %q, want task-uuid-1", resp.Tasks[0].ID)
-	}
-	if resp.Tasks[0].InfoHash != "abc123def456abc123def456abc123def456abc1" {
-		t.Errorf("task.InfoHash = %q", resp.Tasks[0].InfoHash)
-	}
-	if resp.Tasks[0].PreferredMethod != "auto" {
-		t.Errorf("task.PreferredMethod = %q, want auto", resp.Tasks[0].PreferredMethod)
-	}
-}
-
 func TestReportStatus(t *testing.T) {
 	var received StatusUpdate
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -173,22 +111,6 @@ func TestReportStatus(t *testing.T) {
 	}
 }
 
-func TestClaimTasksEmpty(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		json.NewEncoder(w).Encode(TasksResponse{Tasks: []Task{}})
-	}))
-	defer srv.Close()
-
-	c := NewClient(srv.URL, "test-key", "unarr-test")
-	resp, err := c.ClaimTasks(context.Background(), "agent-123")
-	if err != nil {
-		t.Fatalf("ClaimTasks failed: %v", err)
-	}
-	if len(resp.Tasks) != 0 {
-		t.Errorf("expected empty tasks, got %d", len(resp.Tasks))
-	}
-}
-
 func TestAPIError(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusUnauthorized)
@@ -279,48 +201,527 @@ func TestUserAgent(t *testing.T) {
 		if r.Header.Get("User-Agent") != "unarr/0.2.0" {
 			t.Errorf("User-Agent = %q, want unarr/0.2.0", r.Header.Get("User-Agent"))
 		}
-		json.NewEncoder(w).Encode(HeartbeatResponse{Success: true})
+		json.NewEncoder(w).Encode(RegisterResponse{Success: true})
 	}))
 	defer srv.Close()
 
 	c := NewClient(srv.URL, "test-key", "unarr/0.2.0")
-	c.Heartbeat(context.Background(), HeartbeatRequest{AgentID: "x"})
+	c.Register(context.Background(), RegisterRequest{AgentID: "x"})
 }
 
-func TestHeartbeatWithUpgradeSignal(t *testing.T) {
+func TestDeregister(t *testing.T) {
+	var received struct {
+		AgentID string `json:"agentId"`
+	}
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		json.NewEncoder(w).Encode(HeartbeatResponse{
-			Success: true,
-			Upgrade: &UpgradeSignal{Version: "2.0.0"},
+		if r.URL.Path != "/api/internal/agent/deregister" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		if r.Method != http.MethodPost {
+			t.Errorf("method = %s, want POST", r.Method)
+		}
+		json.NewDecoder(r.Body).Decode(&received)
+		json.NewEncoder(w).Encode(StatusResponse{Success: true})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	err := c.Deregister(context.Background(), "agent-42")
+	if err != nil {
+		t.Fatalf("Deregister failed: %v", err)
+	}
+	if received.AgentID != "agent-42" {
+		t.Errorf("agentId = %q, want agent-42", received.AgentID)
+	}
+}
+
+func TestBatchReportStatus(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/status" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		var req BatchStatusRequest
+		json.NewDecoder(r.Body).Decode(&req)
+		if len(req.Updates) != 2 {
+			t.Errorf("expected 2 updates, got %d", len(req.Updates))
+		}
+		json.NewEncoder(w).Encode(BatchStatusResponse{
+			Results: []StatusResponse{
+				{Success: true},
+				{Success: true, Cancelled: true},
+			},
 		})
 	}))
 	defer srv.Close()
 
 	c := NewClient(srv.URL, "test-key", "unarr-test")
-	resp, err := c.Heartbeat(context.Background(), HeartbeatRequest{AgentID: "agent-1"})
+	resp, err := c.BatchReportStatus(context.Background(), []StatusUpdate{
+		{TaskID: "t1", Status: "downloading"},
+		{TaskID: "t2", Status: "completed"},
+	})
 	if err != nil {
-		t.Fatalf("Heartbeat failed: %v", err)
+		t.Fatalf("BatchReportStatus failed: %v", err)
 	}
-	if resp.Upgrade == nil {
-		t.Fatal("expected upgrade signal, got nil")
+	if len(resp.Results) != 2 {
+		t.Fatalf("expected 2 results, got %d", len(resp.Results))
 	}
-	if resp.Upgrade.Version != "2.0.0" {
-		t.Errorf("upgrade version = %q, want 2.0.0", resp.Upgrade.Version)
+	if !resp.Results[1].Cancelled {
+		t.Error("expected result[1].Cancelled=true")
 	}
 }
 
-func TestHeartbeatWithoutUpgradeSignal(t *testing.T) {
+func TestSearchNzbs(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		json.NewEncoder(w).Encode(HeartbeatResponse{Success: true})
+		if r.URL.Path != "/api/internal/agent/nzb-search" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		json.NewEncoder(w).Encode(NzbSearchResponse{
+			Results: []NzbSearchResult{
+				{NzbID: "nzb-1", Title: "Movie.2023.1080p"},
+			},
+		})
 	}))
 	defer srv.Close()
 
 	c := NewClient(srv.URL, "test-key", "unarr-test")
-	resp, err := c.Heartbeat(context.Background(), HeartbeatRequest{AgentID: "agent-1"})
+	resp, err := c.SearchNzbs(context.Background(), NzbSearchParams{Query: "Movie"})
 	if err != nil {
-		t.Fatalf("Heartbeat failed: %v", err)
+		t.Fatalf("SearchNzbs failed: %v", err)
 	}
-	if resp.Upgrade != nil {
-		t.Errorf("expected no upgrade signal, got %+v", resp.Upgrade)
+	if len(resp.Results) != 1 {
+		t.Fatalf("expected 1 result, got %d", len(resp.Results))
+	}
+	if resp.Results[0].NzbID != "nzb-1" {
+		t.Errorf("nzb ID = %q, want nzb-1", resp.Results[0].NzbID)
+	}
+}
+
+func TestDownloadNzb(t *testing.T) {
+	nzbContent := []byte(`<?xml version="1.0"?><nzb><file>test</file></nzb>`)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/nzb-download" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		if r.URL.Query().Get("nzbId") != "nzb-42" {
+			t.Errorf("nzbId = %q, want nzb-42", r.URL.Query().Get("nzbId"))
+		}
+		w.Write(nzbContent)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	data, err := c.DownloadNzb(context.Background(), "nzb-42")
+	if err != nil {
+		t.Fatalf("DownloadNzb failed: %v", err)
+	}
+	if string(data) != string(nzbContent) {
+		t.Errorf("nzb content mismatch")
+	}
+}
+
+func TestDownloadNzbError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+		w.Write([]byte("NZB not found"))
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	_, err := c.DownloadNzb(context.Background(), "bad-id")
+	if err == nil {
+		t.Fatal("expected error for 404 response")
+	}
+}
+
+func TestGetUsenetCredentials(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/usenet-credentials" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		json.NewEncoder(w).Encode(UsenetCredentials{
+			Host:           "news.example.com",
+			Port:           563,
+			SSL:            true,
+			Username:       "user1",
+			Password:       "pass1",
+			MaxConnections: 10,
+		})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	creds, err := c.GetUsenetCredentials(context.Background())
+	if err != nil {
+		t.Fatalf("GetUsenetCredentials failed: %v", err)
+	}
+	if creds.Host != "news.example.com" {
+		t.Errorf("host = %q, want news.example.com", creds.Host)
+	}
+	if creds.Username != "user1" {
+		t.Errorf("username = %q, want user1", creds.Username)
+	}
+	if creds.MaxConnections != 10 {
+		t.Errorf("maxConnections = %d, want 10", creds.MaxConnections)
+	}
+}
+
+func TestGetUsenetUsage(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/usenet-usage" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		json.NewEncoder(w).Encode(UsenetUsageResponse{
+			UsedBytes:  5368709120,
+			QuotaBytes: 10737418240,
+		})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	usage, err := c.GetUsenetUsage(context.Background())
+	if err != nil {
+		t.Fatalf("GetUsenetUsage failed: %v", err)
+	}
+	if usage.UsedBytes != 5368709120 {
+		t.Errorf("usedBytes = %d", usage.UsedBytes)
+	}
+}
+
+func TestConfigureDebrid(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/debrid-config" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		json.NewEncoder(w).Encode(ConfigureDebridResponse{Success: true})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	resp, err := c.ConfigureDebrid(context.Background(), ConfigureDebridRequest{
+		Provider: "real-debrid",
+		Token:    "rd-token-123",
+	})
+	if err != nil {
+		t.Fatalf("ConfigureDebrid failed: %v", err)
+	}
+	if !resp.Success {
+		t.Error("expected success=true")
+	}
+}
+
+func TestBatchDownload(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/batch-download" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		json.NewEncoder(w).Encode(BatchDownloadResponse{
+			Queued:   3,
+			NotFound: 1,
+		})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	resp, err := c.BatchDownload(context.Background(), BatchDownloadRequest{})
+	if err != nil {
+		t.Fatalf("BatchDownload failed: %v", err)
+	}
+	if resp.Queued != 3 {
+		t.Errorf("queued = %d, want 3", resp.Queued)
+	}
+}
+
+func TestSyncLibrary(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/library-sync" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		json.NewEncoder(w).Encode(LibrarySyncResponse{
+			Matched: 10,
+			Synced:  15,
+			Removed: 2,
+		})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	resp, err := c.SyncLibrary(context.Background(), LibrarySyncRequest{})
+	if err != nil {
+		t.Fatalf("SyncLibrary failed: %v", err)
+	}
+	if resp.Matched != 10 {
+		t.Errorf("matched = %d, want 10", resp.Matched)
+	}
+	if resp.Synced != 15 {
+		t.Errorf("synced = %d, want 15", resp.Synced)
+	}
+}
+
+func TestHTMLErrorResponse(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusBadGateway)
+		w.Write([]byte("<html><body>502 Bad Gateway</body></html>"))
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	_, err := c.Register(context.Background(), RegisterRequest{AgentID: "x"})
+	if err == nil {
+		t.Fatal("expected error for HTML error page")
+	}
+}
+
+func TestClient_ContextCancelled(t *testing.T) {
+	// Servidor que bloquea hasta que el cliente se desconecta
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+	defer srv.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // cancelar inmediatamente
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	_, err := c.Register(ctx, RegisterRequest{AgentID: "x"})
+	if err == nil {
+		t.Fatal("expected error when context is cancelled")
+	}
+}
+
+func TestClient_SlowServer_Timeout(t *testing.T) {
+	// Servidor que tarda más que el timeout del cliente.
+	// Usa time.Sleep para que el handler termine limpiamente cuando el server cierra.
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(500 * time.Millisecond) // más largo que el timeout del cliente (50ms)
+	}))
+	defer srv.Close()
+
+	// Crear cliente con timeout muy corto
+	c := &Client{
+		pool:   NewMirrorPool(srv.URL, nil),
+		apiKey: "test-key",
+		httpClient: &http.Client{
+			Timeout: 50 * time.Millisecond,
+		},
+		userAgent: "unarr-test",
+	}
+
+	_, err := c.Register(context.Background(), RegisterRequest{AgentID: "timeout-test"})
+	if err == nil {
+		t.Fatal("expected timeout error from slow server")
+	}
+}
+
+func TestClient_Sync_FullRequest(t *testing.T) {
+	var received SyncRequest
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/sync" {
+			t.Errorf("path = %s, want /api/internal/agent/sync", r.URL.Path)
+		}
+		if r.Method != http.MethodPost {
+			t.Errorf("method = %s, want POST", r.Method)
+		}
+		json.NewDecoder(r.Body).Decode(&received)
+		json.NewEncoder(w).Encode(SyncResponse{
+			NewTasks: []Task{
+				{ID: "task-from-server", InfoHash: "abc123def456abc123def456abc123def456abc1"},
+			},
+			Watching: true,
+		})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	resp, err := c.Sync(context.Background(), SyncRequest{
+		AgentID:       "agent-sync-1",
+		Version:       "0.6.0",
+		OS:            "linux",
+		Arch:          "amd64",
+		FreeSlots:     2,
+		DiskFreeBytes: 10 << 30, // 10 GB
+	})
+	if err != nil {
+		t.Fatalf("Sync failed: %v", err)
+	}
+	if len(resp.NewTasks) != 1 {
+		t.Fatalf("expected 1 new task, got %d", len(resp.NewTasks))
+	}
+	if resp.NewTasks[0].ID != "task-from-server" {
+		t.Errorf("task ID = %q, want task-from-server", resp.NewTasks[0].ID)
+	}
+	if !resp.Watching {
+		t.Error("expected watching=true")
+	}
+	if received.AgentID != "agent-sync-1" {
+		t.Errorf("received.AgentID = %q, want agent-sync-1", received.AgentID)
+	}
+	if received.FreeSlots != 2 {
+		t.Errorf("received.FreeSlots = %d, want 2", received.FreeSlots)
+	}
+}
+
+func TestClient_ReportWatchProgress(t *testing.T) {
+	var received WatchProgressUpdate
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/watch-progress" {
+			t.Errorf("path = %s", r.URL.Path)
+		}
+		json.NewDecoder(r.Body).Decode(&received)
+		json.NewEncoder(w).Encode(WatchProgressResponse{Success: true})
+	}))
+	defer srv.Close()
+
+	pct := 42
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	err := c.ReportWatchProgress(context.Background(), WatchProgressUpdate{
+		TaskID:   "task-watch-001",
+		Source:   "range",
+		Progress: &pct,
+	})
+	if err != nil {
+		t.Fatalf("ReportWatchProgress failed: %v", err)
+	}
+	if received.TaskID != "task-watch-001" {
+		t.Errorf("taskID = %q, want task-watch-001", received.TaskID)
+	}
+	if received.Progress == nil || *received.Progress != 42 {
+		t.Errorf("progress = %v, want 42", received.Progress)
+	}
+}
+
+func TestClient_HTTPError_PlainText(t *testing.T) {
+	// Error 500 con body plano (no JSON ni HTML largo)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		w.Write([]byte("internal server error"))
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	_, err := c.Register(context.Background(), RegisterRequest{AgentID: "x"})
+	if err == nil {
+		t.Fatal("expected error for 500 response")
+	}
+	var httpErr *HTTPError
+	if !errors.As(err, &httpErr) {
+		t.Fatalf("expected *HTTPError (possibly wrapped), got %T: %v", err, err)
+	}
+	if httpErr.StatusCode != 500 {
+		t.Errorf("StatusCode = %d, want 500", httpErr.StatusCode)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// WaitForWake tests
+// ---------------------------------------------------------------------------
+
+func TestWaitForWake_ReturnsTrue_OnWakeSignal(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/wake" {
+			t.Errorf("path = %s, want /api/internal/agent/wake", r.URL.Path)
+		}
+		if r.Method != http.MethodGet {
+			t.Errorf("method = %s, want GET", r.Method)
+		}
+		if r.Header.Get("Authorization") != "Bearer test-key" {
+			t.Errorf("auth = %q", r.Header.Get("Authorization"))
+		}
+		json.NewEncoder(w).Encode(map[string]bool{"wake": true})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	woke, err := c.WaitForWake(context.Background())
+	if err != nil {
+		t.Fatalf("WaitForWake failed: %v", err)
+	}
+	if !woke {
+		t.Error("expected wake=true")
+	}
+}
+
+func TestWaitForWake_ReturnsFalse_OnTimeout(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Server returns wake=false (long-poll timeout)
+		json.NewEncoder(w).Encode(map[string]bool{"wake": false})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	woke, err := c.WaitForWake(context.Background())
+	if err != nil {
+		t.Fatalf("WaitForWake failed: %v", err)
+	}
+	if woke {
+		t.Error("expected wake=false on server timeout")
+	}
+}
+
+func TestWaitForWake_Error_OnUnauthorized(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+		json.NewEncoder(w).Encode(map[string]string{"error": "Invalid API key"})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "bad-key", "unarr-test")
+	_, err := c.WaitForWake(context.Background())
+	if err == nil {
+		t.Fatal("expected error for 401 response")
+	}
+}
+
+func TestWaitForWake_RespectsContextCancellation(t *testing.T) {
+	// Server blocks until client disconnects
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+	defer srv.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // cancel immediately
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+	_, err := c.WaitForWake(ctx)
+	if err == nil {
+		t.Fatal("expected error when context is cancelled")
+	}
+}
+
+func TestWaitForWake_SimulatesLongPoll(t *testing.T) {
+	// Server holds connection briefly then responds with wake=true
+	ready := make(chan struct{})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		select {
+		case <-ready:
+		case <-r.Context().Done():
+			return
+		}
+		json.NewEncoder(w).Encode(map[string]bool{"wake": true})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key", "unarr-test")
+
+	resultCh := make(chan bool, 1)
+	go func() {
+		woke, err := c.WaitForWake(context.Background())
+		if err != nil {
+			t.Errorf("WaitForWake failed: %v", err)
+		}
+		resultCh <- woke
+	}()
+
+	// Simulate server waking after 50ms
+	time.Sleep(50 * time.Millisecond)
+	close(ready)
+
+	select {
+	case woke := <-resultCh:
+		if !woke {
+			t.Error("expected wake=true")
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("WaitForWake did not return in time")
 	}
 }
diff --git a/internal/agent/daemon.go b/internal/agent/daemon.go
index 35d3fda..f7994fb 100644
--- a/internal/agent/daemon.go
+++ b/internal/agent/daemon.go
@@ -2,95 +2,173 @@ package agent
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log"
 	"os"
+	"os/exec"
 	"runtime"
+	"strings"
+	"sync/atomic"
 	"time"
+
+	"github.com/torrentclaw/unarr/internal/upgrade"
 )
 
 // DaemonConfig holds daemon runtime settings.
 type DaemonConfig struct {
-	AgentID           string
-	AgentName         string
-	Version           string
-	DownloadDir       string
-	PollInterval      time.Duration
-	HeartbeatInterval time.Duration
+	AgentID            string
+	AgentName          string
+	Version            string
+	DownloadDir        string
+	StreamPort         int      // port for the HTTP stream server
+	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
+	ScanPaths          []string // configured scan paths for file deletion validation
+	HWAccel            string   // detected encoder backend ("nvenc"/"qsv"/"vaapi"/"videotoolbox"/"none")
+	MaxTranscodeHeight int      // resolution cap the agent can transcode comfortably (px)
+	// Diagnostic data populated by engine.DetectHWAccelDiagnostic at daemon
+	// start. Surfaced in the web "Diagnose transcoder" modal — lets a user
+	// see which encoders the ffmpeg binary supports and which devices the
+	// host exposes without running `unarr probe-hwaccel`.
+	FFmpegVersion string   // first line of `ffmpeg -version`
+	FFmpegPath    string   // resolved binary path
+	HWEncoders    []string // HW-class encoder names found in `ffmpeg -encoders`
+	HWDevices     []string // device files + driver bins detected at probe time
+	AutoUpgrade   bool     // honor server-flagged upgrades by downloading + restarting (default: true)
 }
 
-// Daemon manages the main loop: register, heartbeat, poll tasks.
+// Daemon manages agent registration and the sync loop.
 type Daemon struct {
-	cfg       DaemonConfig
-	transport Transport
+	cfg    DaemonConfig
+	client *Client
+	sync   *SyncClient
+	state  *LocalState
 
-	// Callbacks
+	// Callbacks — set by cmd/daemon.go before calling Run.
 	OnTasksClaimed    func(tasks []Task)
 	OnStreamRequested func(req StreamRequest)
-	OnControlAction   func(action, taskID string)
+	OnStreamSession   func(sess StreamSession)
+	OnControlAction   func(action, taskID string, deleteFiles bool)
+	GetActiveCount    func() int // returns number of active downloads (wired from manager)
 
 	// State
 	User                UserInfo
 	Features            FeatureFlags
 	Info                AgentInfo
 	State               DaemonState
-	heartbeatFailures   int
 	lastNotifiedVersion string
 
-	// Callbacks for state tracking (set by cmd/daemon.go)
-	GetActiveCount    func() int
-	GetCleanableBytes func() int64
+	// Managed-VPN split-tunnel state, set by cmd/daemon.go before Run and folded
+	// into DaemonState on every write so external tools (`unarr vpn status`) see it.
+	vpnActive bool
+	vpnMode   string
+	vpnServer string
+
+	// CloudFlare Quick Tunnel public URL; folded into DaemonState + heartbeat
+	// so the web can prefer it over Tailscale/LAN for in-browser playback.
+	funnelURL string
 
 	// Watching tracks whether a user is viewing download progress in the web UI.
-	// When false, the progress reporter skips detailed updates (only sends final states).
-	Watching bool
+	Watching atomic.Bool
 
-	// Exposed tickers for hot-reload
-	PollTicker      *time.Ticker
-	HeartbeatTicker *time.Ticker
-
-	// pollNow triggers an immediate poll (e.g. on resume)
-	pollNow chan struct{}
+	// ScanNow triggers an immediate library scan.
+	ScanNow chan struct{}
 }
 
-// NewDaemon creates a daemon with the given transport.
-// Use NewHTTPTransport for HTTP-only, or NewHybridTransport for WS+HTTP.
-func NewDaemon(cfg DaemonConfig, transport Transport) *Daemon {
-	if cfg.PollInterval == 0 {
-		cfg.PollInterval = 30 * time.Second
-	}
-	if cfg.HeartbeatInterval == 0 {
-		cfg.HeartbeatInterval = 30 * time.Second
-	}
-
+// NewDaemon creates a daemon with an HTTP client for sync-based communication.
+func NewDaemon(cfg DaemonConfig, client *Client) *Daemon {
+	state := NewLocalState()
 	return &Daemon{
-		cfg:       cfg,
-		transport: transport,
-		pollNow:   make(chan struct{}, 1),
+		cfg:     cfg,
+		client:  client,
+		state:   state,
+		sync:    NewSyncClient(client, cfg, state),
+		ScanNow: make(chan struct{}, 1),
 	}
 }
 
-// Transport returns the configured transport.
-func (d *Daemon) Transport() Transport { return d.transport }
+// SyncClient returns the sync client for external wiring.
+func (d *Daemon) SyncClient() *SyncClient { return d.sync }
+
+// SetVPNState records the managed-VPN split-tunnel state so it's reflected in the
+// daemon state file (read by `unarr vpn status`). Call before Run.
+func (d *Daemon) SetVPNState(active bool, mode, server string) {
+	d.vpnActive = active
+	d.vpnMode = mode
+	d.vpnServer = server
+}
+
+// SetFunnelURL records the CloudFlare Quick Tunnel hostname so it's reflected
+// in the daemon state file (read by `unarr funnel status`) and in heartbeat
+// requests (so the web prefers it over Tailscale/LAN). Pass "" to clear.
+func (d *Daemon) SetFunnelURL(url string) {
+	d.funnelURL = url
+	d.State.FunnelURL = url
+	WriteState(&d.State)
+}
+
+// UpdateStreamPort updates the stream port reported in sync requests.
+func (d *Daemon) UpdateStreamPort(port int) {
+	d.cfg.StreamPort = port
+	d.sync.cfg.StreamPort = port
+}
 
 // Register registers the agent and fetches user info + features.
+// Retries with exponential backoff on transient errors (429, 5xx, network).
 func (d *Daemon) Register(ctx context.Context) error {
 	req := RegisterRequest{
-		AgentID:     d.cfg.AgentID,
-		Name:        d.cfg.AgentName,
-		OS:          runtime.GOOS,
-		Arch:        runtime.GOARCH,
-		Version:     d.cfg.Version,
-		DownloadDir: d.cfg.DownloadDir,
+		AgentID:            d.cfg.AgentID,
+		Name:               d.cfg.AgentName,
+		OS:                 runtime.GOOS,
+		Arch:               runtime.GOARCH,
+		Version:            d.cfg.Version,
+		DownloadDir:        d.cfg.DownloadDir,
+		StreamPort:         d.cfg.StreamPort,
+		LanIP:              d.cfg.LanIP,
+		TailscaleIP:        d.cfg.TailscaleIP,
+		HWAccel:            d.cfg.HWAccel,
+		MaxTranscodeHeight: d.cfg.MaxTranscodeHeight,
+		FFmpegVersion:      d.cfg.FFmpegVersion,
+		FFmpegPath:         d.cfg.FFmpegPath,
+		HWEncoders:         d.cfg.HWEncoders,
+		HWDevices:          d.cfg.HWDevices,
+		VPNActive:          d.vpnActive,
+		VPNMode:            d.vpnMode,
+		VPNServer:          d.vpnServer,
+		FunnelURL:          d.funnelURL,
 	}
 	if free, total, err := DiskInfo(d.cfg.DownloadDir); err == nil {
 		req.DiskFreeBytes = free
 		req.DiskTotalBytes = total
 	}
 
-	resp, err := d.transport.Register(ctx, req)
+	const maxRetries = 5
+	backoff := 5 * time.Second
+
+	var resp *RegisterResponse
+	var err error
+	for attempt := range maxRetries {
+		resp, err = d.client.Register(ctx, req)
+		if err == nil {
+			break
+		}
+		if !isTransientError(err) {
+			return fmt.Errorf("register: %w", err)
+		}
+		log.Printf("Register failed (attempt %d/%d): %v - retrying in %v", attempt+1, maxRetries, err, backoff)
+		timer := time.NewTimer(backoff)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return fmt.Errorf("register: %w", ctx.Err())
+		case <-timer.C:
+		}
+		backoff = min(backoff*2, 60*time.Second)
+	}
 	if err != nil {
-		return fmt.Errorf("register: %w", err)
+		return fmt.Errorf("register: %w (after %d retries)", err, maxRetries)
 	}
 
 	d.User = resp.User
@@ -110,13 +188,18 @@ func (d *Daemon) Register(ctx context.Context) error {
 		PID:         os.Getpid(),
 		StartedAt:   now,
 		MethodStats: make(map[string]int),
+		VPNActive:   d.vpnActive,
+		VPNMode:     d.vpnMode,
+		VPNServer:   d.vpnServer,
+		FunnelURL:   d.funnelURL,
 	}
 	WriteState(&d.State)
 
 	return nil
 }
 
-// Run starts the main daemon loop. Blocks until ctx is cancelled.
+// Run registers the agent and starts the sync loop.
+// Blocks until ctx is cancelled.
 func (d *Daemon) Run(ctx context.Context) error {
 	// Register
 	if err := d.Register(ctx); err != nil {
@@ -125,137 +208,93 @@ func (d *Daemon) Run(ctx context.Context) error {
 
 	log.Printf("Agent registered: %s (%s) [%s]", d.User.Name, d.User.Email, d.User.Plan)
 	log.Printf("Features: torrent=%v debrid=%v usenet=%v", d.Features.Torrent, d.Features.Debrid, d.Features.Usenet)
-	log.Printf("Polling every %s, heartbeat every %s", d.cfg.PollInterval, d.cfg.HeartbeatInterval)
 
-	d.HeartbeatTicker = time.NewTicker(d.cfg.HeartbeatInterval)
-	defer d.HeartbeatTicker.Stop()
+	// Usenet needs par2 (segment repair) + an extractor (RAR/7z) on the host.
+	// Without par2, a single bad segment corrupts the file silently; without
+	// an extractor, RAR-packed downloads can't be unpacked. Warn loudly at
+	// startup so the operator installs them before the first download fails.
+	if d.Features.Usenet {
+		if _, err := exec.LookPath("par2"); err != nil {
+			log.Printf("[usenet] WARNING: par2 not found in PATH — corrupted segments cannot be repaired and extraction may fail. Install par2 (apt install par2 / brew install par2).")
+		}
+		_, unrarErr := exec.LookPath("unrar")
+		_, sevenZErr := exec.LookPath("7z")
+		if unrarErr != nil && sevenZErr != nil {
+			log.Printf("[usenet] WARNING: no archive extractor (unrar or 7z) found — RAR-packed downloads cannot be unpacked. Install unrar or 7z.")
+		}
+	}
 
-	d.PollTicker = time.NewTicker(d.cfg.PollInterval)
-	defer d.PollTicker.Stop()
-
-	heartbeatTicker := d.HeartbeatTicker
-	pollTicker := d.PollTicker
-
-	// Initial poll immediately
-	d.poll(ctx)
-
-	eventsCh := d.transport.Events()
-
-	for {
+	// Wire sync callbacks
+	d.sync.OnNewTasks = func(tasks []Task) {
+		if d.OnTasksClaimed != nil {
+			d.OnTasksClaimed(tasks)
+		}
+	}
+	d.sync.OnControl = func(action, taskID string, deleteFiles bool) {
+		if d.OnControlAction != nil {
+			d.OnControlAction(action, taskID, deleteFiles)
+		}
+	}
+	d.sync.OnStreamRequest = func(req StreamRequest) {
+		if d.OnStreamRequested != nil {
+			d.OnStreamRequested(req)
+		}
+	}
+	d.sync.OnStreamSession = func(sess StreamSession) {
+		if d.OnStreamSession != nil {
+			d.OnStreamSession(sess)
+		}
+	}
+	d.sync.OnUpgrade = func(version string) {
+		if version == d.lastNotifiedVersion {
+			return
+		}
+		d.lastNotifiedVersion = version
+		if !d.cfg.AutoUpgrade {
+			log.Printf("[upgrade] new version available: %s — auto_upgrade=false, run `unarr update` to apply", version)
+			return
+		}
+		log.Printf("[upgrade] new version available: %s — applying auto-upgrade", version)
+		go d.applyAutoUpgrade(version)
+	}
+	d.sync.OnScan = func() {
+		log.Printf("Library scan requested by server")
 		select {
-		case <-ctx.Done():
-			log.Println("Daemon shutting down...")
-			d.deregister()
-			return nil
-
-		case event := <-eventsCh:
-			d.handleEvent(event)
-
-		case <-heartbeatTicker.C:
-			d.heartbeat(ctx)
-
-		case <-pollTicker.C:
-			// Only poll in HTTP mode — WS mode receives tasks via Events
-			if d.transport.Mode() == "http" {
-				d.poll(ctx)
-			}
-
-		case <-d.pollNow:
-			d.poll(ctx)
+		case d.ScanNow <- struct{}{}:
+		default:
 		}
 	}
+	d.sync.OnWatchingChange = func(watching bool) {
+		d.Watching.Store(watching)
+	}
+	d.sync.GetVPNState = func() (bool, string, string) {
+		return d.vpnActive, d.vpnMode, d.vpnServer
+	}
+	d.sync.GetFunnelURL = func() string {
+		return d.funnelURL
+	}
+	d.sync.OnSyncSuccess = func() {
+		d.State.LastHeartbeat = time.Now()
+		if d.GetActiveCount != nil {
+			d.State.ActiveTasks = d.GetActiveCount()
+		}
+		WriteState(&d.State)
+	}
+
+	// Start sync loop (blocks)
+	return d.sync.Run(ctx)
 }
 
-func (d *Daemon) heartbeat(ctx context.Context) {
-	req := HeartbeatRequest{
-		AgentID:     d.cfg.AgentID,
-		Name:        d.cfg.AgentName,
-		Version:     d.cfg.Version,
-		OS:          runtime.GOOS,
-		DownloadDir: d.cfg.DownloadDir,
-	}
-	if free, total, err := DiskInfo(d.cfg.DownloadDir); err == nil {
-		req.DiskFreeBytes = free
-		req.DiskTotalBytes = total
-	}
-
-	resp, err := d.transport.SendHeartbeat(ctx, req)
-	if err != nil {
-		d.heartbeatFailures++
-		if d.heartbeatFailures >= 5 && d.heartbeatFailures%5 == 0 {
-			log.Printf("CRITICAL: %d consecutive heartbeat failures — server may be unreachable", d.heartbeatFailures)
-		} else {
-			log.Printf("Heartbeat failed: %v", err)
-		}
-		return
-	}
-	if d.heartbeatFailures > 0 {
-		log.Printf("Heartbeat recovered after %d failures", d.heartbeatFailures)
-		d.heartbeatFailures = 0
-	}
-
-	// Update watching flag and state file
-	d.Watching = resp.Watching
-	d.State.LastHeartbeat = time.Now()
-	if d.GetActiveCount != nil {
-		d.State.ActiveTasks = d.GetActiveCount()
-	}
-	WriteState(&d.State)
-
-	// Log once per version when server suggests an upgrade
-	if resp.Upgrade != nil && resp.Upgrade.Version != "" && resp.Upgrade.Version != d.lastNotifiedVersion {
-		d.lastNotifiedVersion = resp.Upgrade.Version
-		log.Printf("New version available: %s (run `unarr self-update` to upgrade)", resp.Upgrade.Version)
-	}
+// TriggerSync requests an immediate sync cycle.
+func (d *Daemon) TriggerSync() {
+	d.sync.TriggerSync()
 }
 
-// handleEvent processes a server-initiated event from the WebSocket transport.
-func (d *Daemon) handleEvent(event ServerEvent) {
-	switch event.Type {
-	case "tasks":
-		if event.Tasks != nil && len(event.Tasks.Tasks) > 0 {
-			log.Printf("Received %d task(s) via WebSocket", len(event.Tasks.Tasks))
-			if d.OnTasksClaimed != nil {
-				d.OnTasksClaimed(event.Tasks.Tasks)
-			}
-		}
-		if event.Tasks != nil && d.OnStreamRequested != nil {
-			for _, sr := range event.Tasks.StreamRequests {
-				d.OnStreamRequested(sr)
-			}
-		}
-
-	case "upgrade":
-		if event.Upgrade != nil && event.Upgrade.Version != "" && event.Upgrade.Version != d.lastNotifiedVersion {
-			d.lastNotifiedVersion = event.Upgrade.Version
-			log.Printf("New version available: %s (run `unarr self-update` to upgrade)", event.Upgrade.Version)
-		}
-
-	case "control":
-		if event.Control != nil && d.OnControlAction != nil {
-			log.Printf("Control action via WebSocket: %s task %s", event.Control.Action, event.Control.TaskID)
-			d.OnControlAction(event.Control.Action, event.Control.TaskID)
-		}
-
-	case "disconnected":
-		log.Println("WebSocket disconnected, switching to HTTP polling")
-	}
-}
-
-// TriggerPoll requests an immediate task poll cycle.
-// Used when a resume event is received to pick up re-pending tasks faster.
-func (d *Daemon) TriggerPoll() {
-	select {
-	case d.pollNow <- struct{}{}:
-	default: // already pending
-	}
-}
-
-func (d *Daemon) deregister() {
+// Deregister notifies the server of graceful shutdown.
+func (d *Daemon) Deregister() {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
-	err := d.transport.Deregister(ctx, d.cfg.AgentID)
-	if err != nil {
+	if err := d.client.Deregister(ctx, d.cfg.AgentID); err != nil {
 		log.Printf("Deregister failed: %v", err)
 	} else {
 		log.Println("Agent deregistered")
@@ -263,26 +302,81 @@ func (d *Daemon) deregister() {
 	RemoveState()
 }
 
-func (d *Daemon) poll(ctx context.Context) {
-	resp, err := d.transport.ClaimTasks(ctx, d.cfg.AgentID)
-	if err != nil {
-		log.Printf("Poll failed: %v", err)
+// applyAutoUpgrade downloads the target version and exits so the service
+// supervisor (systemd Restart=always on Linux) respawns on the new binary.
+// Triggered by the server's upgrade signal — opt-in flag set by the user from
+// the web UI; the daemon never auto-upgrades on a passive version bump.
+//
+// Reports the outcome to /api/internal/agent/upgrade-result so the server
+// clears `upgrade_requested`. Without this report the flag stays sticky and
+// the daemon would loop on every sync — including the no-op case where it's
+// already on the target version.
+func (d *Daemon) applyAutoUpgrade(targetVersion string) {
+	currentClean := strings.TrimPrefix(d.cfg.Version, "v")
+	targetClean := strings.TrimPrefix(targetVersion, "v")
+
+	// No-op: server signal arrived but we're already running the target. This
+	// happens when the daemon restarts after a previous auto-upgrade before
+	// reportUpgradeResult cleared the flag, or when the operator manually
+	// installed the same version off-band. Skip Execute (which would also
+	// no-op) AND skip os.Exit, but DO clear the flag — otherwise we loop.
+	if currentClean == targetClean {
+		log.Printf("[upgrade] already on v%s — clearing server flag", currentClean)
+		ctxR, cancelR := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancelR()
+		if err := d.client.ReportUpgradeResult(ctxR, d.cfg.AgentID, true, currentClean, ""); err != nil {
+			log.Printf("[upgrade] report-result failed (will retry on next signal): %v", err)
+		}
 		return
 	}
 
-	d.Info.LastPollAt = time.Now()
-
-	if len(resp.Tasks) > 0 {
-		log.Printf("Claimed %d task(s)", len(resp.Tasks))
-		if d.OnTasksClaimed != nil {
-			d.OnTasksClaimed(resp.Tasks)
-		}
+	upgrader := &upgrade.Upgrader{
+		CurrentVersion: currentClean,
+		OnProgress: func(msg string) {
+			log.Printf("[upgrade] %s", msg)
+		},
 	}
-
-	// Handle stream requests for completed downloads
-	if d.OnStreamRequested != nil {
-		for _, sr := range resp.StreamRequests {
-			d.OnStreamRequested(sr)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
+	defer cancel()
+	result := upgrader.Execute(ctx, targetVersion)
+	if !result.Success {
+		log.Printf("[upgrade] auto-upgrade failed: %v", result.Error)
+		errMsg := ""
+		if result.Error != nil {
+			errMsg = result.Error.Error()
 		}
+		ctxR, cancelR := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancelR()
+		if err := d.client.ReportUpgradeResult(ctxR, d.cfg.AgentID, false, targetClean, errMsg); err != nil {
+			log.Printf("[upgrade] report-result failed: %v", err)
+		}
+		return
 	}
+	log.Printf("[upgrade] upgraded v%s → v%s; reporting result + exiting so service supervisor restarts on new binary",
+		result.OldVersion, result.NewVersion)
+	ctxR, cancelR := context.WithTimeout(context.Background(), 10*time.Second)
+	if err := d.client.ReportUpgradeResult(ctxR, d.cfg.AgentID, true, result.NewVersion, ""); err != nil {
+		log.Printf("[upgrade] report-result failed: %v", err)
+	}
+	cancelR()
+	time.Sleep(500 * time.Millisecond)
+	os.Exit(0)
+}
+
+// isTransientError returns true for errors worth retrying (429, 5xx, network).
+func isTransientError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var httpErr *HTTPError
+	if errors.As(err, &httpErr) {
+		return httpErr.StatusCode == 429 || httpErr.StatusCode >= 500
+	}
+	lower := strings.ToLower(err.Error())
+	for _, keyword := range []string{"connection refused", "no such host", "timeout", "request failed"} {
+		if strings.Contains(lower, keyword) {
+			return true
+		}
+	}
+	return false
 }
diff --git a/internal/agent/disk.go b/internal/agent/disk.go
new file mode 100644
index 0000000..9064ad0
--- /dev/null
+++ b/internal/agent/disk.go
@@ -0,0 +1,25 @@
+package agent
+
+import (
+	"io/fs"
+	"path/filepath"
+)
+
+// DirSize returns the total size in bytes of all files under dir.
+func DirSize(dir string) (int64, error) {
+	var size int64
+	err := filepath.WalkDir(dir, func(_ string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return nil // skip unreadable entries
+		}
+		if !d.IsDir() {
+			info, err := d.Info()
+			if err != nil {
+				return nil
+			}
+			size += info.Size()
+		}
+		return nil
+	})
+	return size, err
+}
diff --git a/internal/agent/disk_test.go b/internal/agent/disk_test.go
new file mode 100644
index 0000000..7875dba
--- /dev/null
+++ b/internal/agent/disk_test.go
@@ -0,0 +1,62 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestDirSize(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "a.bin"), make([]byte, 100), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "sub", "b.bin"), make([]byte, 250), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := DirSize(root)
+	if err != nil {
+		t.Fatalf("DirSize error: %v", err)
+	}
+	if got != 350 {
+		t.Errorf("DirSize = %d, want 350", got)
+	}
+}
+
+func TestDirSizeEmpty(t *testing.T) {
+	got, err := DirSize(t.TempDir())
+	if err != nil {
+		t.Fatalf("DirSize empty dir error: %v", err)
+	}
+	if got != 0 {
+		t.Errorf("DirSize empty = %d, want 0", got)
+	}
+}
+
+func TestDirSizeMissing(t *testing.T) {
+	// Walk skips unreadable entries — missing path returns 0 with no error.
+	got, err := DirSize("/nonexistent/path/zzz")
+	if err != nil {
+		t.Errorf("DirSize on missing path = err %v, want nil", err)
+	}
+	if got != 0 {
+		t.Errorf("DirSize on missing path = %d, want 0", got)
+	}
+}
+
+func TestDiskInfoCurrentDir(t *testing.T) {
+	free, total, err := DiskInfo(".")
+	if err != nil {
+		t.Fatalf("DiskInfo: %v", err)
+	}
+	if total <= 0 {
+		t.Errorf("total bytes should be > 0, got %d", total)
+	}
+	if free > total {
+		t.Errorf("free (%d) should not exceed total (%d)", free, total)
+	}
+}
diff --git a/internal/agent/mirror_client.go b/internal/agent/mirror_client.go
new file mode 100644
index 0000000..683b92b
--- /dev/null
+++ b/internal/agent/mirror_client.go
@@ -0,0 +1,232 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+// MirrorEntry mirrors the shape of /api/v1/mirrors items on the server.
+type MirrorEntry struct {
+	URL     string `json:"url"`
+	Label   string `json:"label"`
+	Kind    string `json:"kind"`    // "clearnet" | "tor"
+	Primary bool   `json:"primary"`
+}
+
+// MirrorChannel is an out-of-band status channel (Telegram, status page, etc.)
+type MirrorChannel struct {
+	URL   string `json:"url"`
+	Label string `json:"label"`
+}
+
+// MirrorsResponse is the JSON document served by /api/v1/mirrors and
+// /api/mirrors.
+type MirrorsResponse struct {
+	Revision  int             `json:"revision"`
+	Mirrors   []MirrorEntry   `json:"mirrors"`
+	Tor       *MirrorEntry    `json:"tor"`
+	Channels  []MirrorChannel `json:"channels"`
+	UpdatedAt string          `json:"updatedAt"`
+}
+
+// DefaultStaticFallbackURLs lists off-domain JSON copies of the mirror list.
+// Hard-coded here (not loaded from config) because the whole point is to
+// have something to consult when config-driven URLs all fail.
+//
+// Hosted on IPFS (content-addressed, re-pinnable, no host can take it down
+// permanently — same bytes re-pinned anywhere keep the same CID). Multiple
+// public gateways are listed so a single gateway being blocked doesn't kill
+// the fallback; the /ipfs/<CID>/ path is identical across all gateways.
+//
+// GitHub Pages was removed 2026-05-17: the whole torrentclaw org is
+// shadow-banned (public repos 404 to anonymous users). Do NOT re-add any
+// github.io URL. Keep this slice in sync with `STATIC_FALLBACKS` in
+// `torrentclaw-web/src/lib/mirrors-config.ts` — when the IPFS CID changes
+// (scripts/publish-mirrors-ipfs.sh), update both.
+//
+// Future hardening: sign mirrors.json with the same ed25519 release key
+// (or a sibling) so a hijack of any single static host cannot serve a
+// malicious mirror list. Today the only signal is "agreement between
+// independent providers" via cross-checking, which we leave to the
+// operator.
+const mirrorsIPFSCID = "bafybeigwux74fek7uky7nct47z5eqwwnpylakfxppqqnzbuxdw7p3ikfdy"
+
+var DefaultStaticFallbackURLs = []string{
+	"https://ipfs.io/ipfs/" + mirrorsIPFSCID + "/mirrors.json",
+	"https://dweb.link/ipfs/" + mirrorsIPFSCID + "/mirrors.json",
+	"https://gateway.pinata.cloud/ipfs/" + mirrorsIPFSCID + "/mirrors.json",
+}
+
+// FetchMirrorsWithFallback pulls the mirror list using FetchMirrors against
+// `candidates` first; if every candidate fails, it falls back to the static
+// JSON copies on off-domain hosts (GitHub Pages, Cloudflare Pages, …).
+//
+// This is the function `unarr mirrors update` should call when it wants the
+// strongest "give me a working mirror list no matter what" guarantee.
+func FetchMirrorsWithFallback(ctx context.Context, candidates []string, userAgent string) (*MirrorsResponse, error) {
+	resp, err := FetchMirrors(ctx, candidates, userAgent)
+	if err == nil {
+		return resp, nil
+	}
+	if len(DefaultStaticFallbackURLs) == 0 {
+		return nil, err
+	}
+	// Try the static JSON files directly. They follow the same wire shape so
+	// we can reuse the same parser — but the URLs already include the JSON
+	// suffix so we hit them with `fetchMirrorsJSON` instead of FetchMirrors
+	// (which appends /api/v1/mirrors).
+	staticResp, staticErr := fetchMirrorsJSON(ctx, DefaultStaticFallbackURLs, userAgent)
+	if staticErr == nil {
+		return staticResp, nil
+	}
+	return nil, fmt.Errorf("primary failed (%v) and static fallback failed (%v)", err, staticErr)
+}
+
+// fetchMirrorsJSON pulls a MirrorsResponse from already-fully-qualified URLs
+// (e.g. https://ipfs.io/ipfs/<CID>/mirrors.json). Each candidate is tried
+// in order; the first success wins.
+func fetchMirrorsJSON(ctx context.Context, urls []string, userAgent string) (*MirrorsResponse, error) {
+	if len(urls) == 0 {
+		return nil, fmt.Errorf("no static fallback URLs configured")
+	}
+	hc := &http.Client{Timeout: 15 * time.Second}
+	var lastErr error
+	for _, url := range urls {
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		if userAgent != "" {
+			req.Header.Set("User-Agent", userAgent)
+		}
+		req.Header.Set("Accept", "application/json")
+		resp, err := hc.Do(req)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		body, readErr := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+		resp.Body.Close()
+		if readErr != nil {
+			lastErr = readErr
+			continue
+		}
+		if resp.StatusCode >= 400 {
+			lastErr = fmt.Errorf("%s returned HTTP %d", url, resp.StatusCode)
+			continue
+		}
+		var out MirrorsResponse
+		if err := json.Unmarshal(body, &out); err != nil {
+			lastErr = fmt.Errorf("%s: invalid JSON: %w", url, err)
+			continue
+		}
+		if len(out.Mirrors) == 0 {
+			lastErr = fmt.Errorf("%s returned empty mirror list", url)
+			continue
+		}
+		return &out, nil
+	}
+	if lastErr == nil {
+		lastErr = fmt.Errorf("no reachable static fallback")
+	}
+	return nil, lastErr
+}
+
+// FetchMirrors pulls the latest mirror list from the server.
+//
+// The endpoint is intentionally public and unauthenticated: the whole point
+// of mirror discovery is that it must work even when the user's API key
+// is invalid, expired, or the auth path is unreachable. The function tries
+// each candidate base URL in order so a takedown of the primary doesn't
+// also kill mirror discovery.
+func FetchMirrors(ctx context.Context, candidates []string, userAgent string) (*MirrorsResponse, error) {
+	if len(candidates) == 0 {
+		return nil, fmt.Errorf("no mirror discovery URLs configured")
+	}
+
+	hc := &http.Client{Timeout: 15 * time.Second}
+
+	var lastErr error
+	for _, base := range candidates {
+		if base == "" {
+			continue
+		}
+		url := base + "/api/v1/mirrors"
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		if userAgent != "" {
+			req.Header.Set("User-Agent", userAgent)
+		}
+		req.Header.Set("Accept", "application/json")
+
+		resp, err := hc.Do(req)
+		if err != nil {
+			lastErr = err
+			continue
+		}
+		body, readErr := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+		resp.Body.Close()
+		if readErr != nil {
+			lastErr = readErr
+			continue
+		}
+		if resp.StatusCode >= 400 {
+			lastErr = fmt.Errorf("%s returned HTTP %d", base, resp.StatusCode)
+			continue
+		}
+		var out MirrorsResponse
+		if err := json.Unmarshal(body, &out); err != nil {
+			lastErr = fmt.Errorf("%s: invalid JSON: %w", base, err)
+			continue
+		}
+		if len(out.Mirrors) == 0 {
+			lastErr = fmt.Errorf("%s returned empty mirror list", base)
+			continue
+		}
+		return &out, nil
+	}
+
+	if lastErr == nil {
+		lastErr = fmt.Errorf("no reachable mirror discovery endpoint")
+	}
+	return nil, fmt.Errorf("fetch mirrors: %w", lastErr)
+}
+
+// ToConfig splits a MirrorsResponse into (primary, extras) suitable for
+// rebuilding a MirrorPool or persisting back into config.toml.
+//
+// The "primary" returned here is whichever entry has primary=true. If none
+// are flagged, the first one wins.
+func (m *MirrorsResponse) ToConfig() (primary string, extras []string) {
+	if m == nil {
+		return "", nil
+	}
+	var picked *MirrorEntry
+	for i := range m.Mirrors {
+		if m.Mirrors[i].Primary {
+			picked = &m.Mirrors[i]
+			break
+		}
+	}
+	if picked == nil && len(m.Mirrors) > 0 {
+		picked = &m.Mirrors[0]
+	}
+	if picked != nil {
+		primary = picked.URL
+	}
+	for _, e := range m.Mirrors {
+		if e.URL == primary {
+			continue
+		}
+		extras = append(extras, e.URL)
+	}
+	return primary, extras
+}
diff --git a/internal/agent/mirror_pool.go b/internal/agent/mirror_pool.go
new file mode 100644
index 0000000..e8f737b
--- /dev/null
+++ b/internal/agent/mirror_pool.go
@@ -0,0 +1,172 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+)
+
+// MirrorPool holds the ordered list of API base URLs the client is willing to
+// fall back to when the current mirror is unreachable. The first entry is
+// always the "preferred" mirror configured by the user. Subsequent entries
+// are alternate domains we can rotate to without changing any user-visible
+// configuration — they exist so a long-lived agent survives a takedown of
+// the primary host without needing a new release.
+//
+// The pool is concurrency-safe; rotation is a fast O(1) index bump under a
+// mutex. The previously-active mirror is NEVER removed — it might just be
+// temporarily unreachable from one network path.
+type MirrorPool struct {
+	mu      sync.RWMutex
+	mirrors []string
+	current int
+}
+
+// NewMirrorPool builds a pool from the provided base URLs. The primary URL
+// is always first; "extras" are appended in order and de-duplicated. Empty
+// strings are skipped. Trailing slashes are normalised so callers can concat
+// `pool.Current() + "/api/..."` reliably.
+func NewMirrorPool(primary string, extras []string) *MirrorPool {
+	seen := make(map[string]struct{})
+	var out []string
+
+	add := func(raw string) {
+		raw = strings.TrimRight(strings.TrimSpace(raw), "/")
+		if raw == "" {
+			return
+		}
+		if _, dup := seen[raw]; dup {
+			return
+		}
+		seen[raw] = struct{}{}
+		out = append(out, raw)
+	}
+
+	add(primary)
+	for _, e := range extras {
+		add(e)
+	}
+
+	if len(out) == 0 {
+		// Defensive: always return a pool with at least one entry so callers
+		// can call Current() without nil checks. The empty string would
+		// produce obvious errors immediately, which is preferable to a panic
+		// somewhere deep in net/http.
+		out = []string{""}
+	}
+
+	return &MirrorPool{mirrors: out}
+}
+
+// Current returns the active base URL.
+func (p *MirrorPool) Current() string {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.mirrors[p.current]
+}
+
+// Mirrors returns a copy of the configured base URLs in priority order.
+func (p *MirrorPool) Mirrors() []string {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	out := make([]string, len(p.mirrors))
+	copy(out, p.mirrors)
+	return out
+}
+
+// Len reports how many mirrors are configured.
+func (p *MirrorPool) Len() int {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return len(p.mirrors)
+}
+
+// Rotate moves the cursor to the next mirror in the pool, wrapping around.
+// Returns the new current mirror and whether a rotation actually happened
+// (a single-mirror pool returns false).
+func (p *MirrorPool) Rotate() (string, bool) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if len(p.mirrors) <= 1 {
+		return p.mirrors[p.current], false
+	}
+	p.current = (p.current + 1) % len(p.mirrors)
+	return p.mirrors[p.current], true
+}
+
+// Replace swaps the entire mirror set, e.g. after `unarr mirrors update`
+// downloaded a fresh list from /api/v1/mirrors. Resets the cursor to 0 so
+// the newly-discovered primary is tried first.
+func (p *MirrorPool) Replace(primary string, extras []string) {
+	fresh := NewMirrorPool(primary, extras)
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.mirrors = fresh.mirrors
+	p.current = 0
+}
+
+// IsTransient reports whether an error is the kind we should retry against
+// another mirror. The intent is conservative: rotate on connection-level
+// failures (DNS, refused, TLS, timeouts, 5xx) but NOT on auth or validation
+// errors that would just fail again somewhere else.
+func IsTransient(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	var httpErr *HTTPError
+	if errors.As(err, &httpErr) {
+		switch httpErr.StatusCode {
+		case http.StatusBadGateway,
+			http.StatusServiceUnavailable,
+			http.StatusGatewayTimeout,
+			http.StatusRequestTimeout:
+			return true
+		}
+		// 4xx (auth, rate limit, validation) won't get healthier on another mirror.
+		return false
+	}
+
+	if errors.Is(err, context.DeadlineExceeded) {
+		return true
+	}
+
+	var netErr net.Error
+	if errors.As(err, &netErr) && netErr.Timeout() {
+		return true
+	}
+
+	var dnsErr *net.DNSError
+	if errors.As(err, &dnsErr) {
+		return true
+	}
+
+	var urlErr *url.Error
+	if errors.As(err, &urlErr) {
+		// `connection refused`, `EOF`, `tls: ...` end up as wrapped url.Errors.
+		msg := urlErr.Error()
+		if strings.Contains(msg, "connection refused") ||
+			strings.Contains(msg, "no such host") ||
+			strings.Contains(msg, "EOF") ||
+			strings.Contains(msg, "tls:") ||
+			strings.Contains(msg, "i/o timeout") ||
+			strings.Contains(msg, "network is unreachable") {
+			return true
+		}
+	}
+
+	// Bare strings as last resort — net.OpError messages are unstable across Go versions.
+	msg := err.Error()
+	if strings.Contains(msg, "connection refused") ||
+		strings.Contains(msg, "no such host") ||
+		strings.Contains(msg, "i/o timeout") ||
+		strings.Contains(msg, "network is unreachable") {
+		return true
+	}
+
+	return false
+}
diff --git a/internal/agent/process_unix_test.go b/internal/agent/process_unix_test.go
new file mode 100644
index 0000000..45c0ed3
--- /dev/null
+++ b/internal/agent/process_unix_test.go
@@ -0,0 +1,22 @@
+//go:build !windows
+
+package agent
+
+import (
+	"os"
+	"testing"
+)
+
+func TestIsProcessAliveSelf(t *testing.T) {
+	if !IsProcessAlive(os.Getpid()) {
+		t.Errorf("self PID should be alive")
+	}
+}
+
+func TestIsProcessAliveBogus(t *testing.T) {
+	// PID 0 is reserved (signal 0 to PID 0 broadcasts to the whole pgrp).
+	// Pick a very high PID unlikely to exist.
+	if IsProcessAlive(0x7FFFFFFE) {
+		t.Errorf("very high PID should not be alive")
+	}
+}
diff --git a/internal/agent/state.go b/internal/agent/state.go
index 5812709..cc08ae5 100644
--- a/internal/agent/state.go
+++ b/internal/agent/state.go
@@ -2,6 +2,8 @@ package agent
 
 import (
 	"encoding/json"
+	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"time"
@@ -9,6 +11,13 @@ import (
 	"github.com/torrentclaw/unarr/internal/config"
 )
 
+// ErrDaemonNotRunning is returned when no daemon state file exists on disk.
+// Callers may wrap it with %w; downstream code uses errors.Is to detect it.
+// NOTE: the message text is matched by the sentry package (string-match, to
+// avoid an import cycle). Keep the prefix "daemon does not appear to be
+// running" stable, or update sentry.daemonNotRunningMarker accordingly.
+var ErrDaemonNotRunning = errors.New("daemon does not appear to be running (state file not found)")
+
 // DaemonState is written to disk every heartbeat for external tools to read.
 type DaemonState struct {
 	AgentID         string         `json:"agentId"`
@@ -22,6 +31,18 @@ type DaemonState struct {
 	FailedCount     int            `json:"failedCount"`
 	TotalDownloaded int64          `json:"totalDownloaded"`
 	MethodStats     map[string]int `json:"methodStats,omitempty"`
+
+	// Managed-VPN split-tunnel state, so `unarr vpn status` can report whether
+	// torrent traffic is actually being routed through the tunnel (vs. the daemon
+	// running but the tunnel having failed to come up → downloading in the clear).
+	VPNActive bool   `json:"vpnActive,omitempty"`
+	VPNMode   string `json:"vpnMode,omitempty"`   // managed | self-hosted
+	VPNServer string `json:"vpnServer,omitempty"` // WireGuard endpoint (ip:port)
+
+	// CloudFlare Quick Tunnel state, so `unarr funnel status` can report the
+	// HTTPS hostname the daemon is reachable at from anywhere on the internet.
+	// Empty when the funnel is off or hasn't registered yet.
+	FunnelURL string `json:"funnelUrl,omitempty"`
 }
 
 // stateFilePathFn is overridable for testing.
@@ -45,25 +66,43 @@ func WriteState(state *DaemonState) {
 		return
 	}
 
-	// Write to temp file then rename for atomicity
+	// Write to temp file then rename for atomicity. 0o600 keeps the file
+	// readable only by the owning user — the state contains agentID, PID
+	// and counters which are useful to a co-tenant on a shared host for
+	// fingerprinting the daemon, and we already use 0o600 for the config
+	// file. No need for cross-user readability here.
 	tmp := path + ".tmp"
-	if err := os.WriteFile(tmp, data, 0o644); err != nil {
+	if err := os.WriteFile(tmp, data, 0o600); err != nil {
 		return
 	}
 	os.Rename(tmp, path)
 }
 
-// ReadState reads the daemon state from disk. Returns nil if not found.
+// ReadState reads the daemon state from disk. Returns nil if not found or
+// unreadable. Use LoadState when callers need to distinguish "not running"
+// from "state file corrupted".
 func ReadState() *DaemonState {
+	state, _ := LoadState()
+	return state
+}
+
+// LoadState reads the daemon state and returns explicit errors:
+//   - ErrDaemonNotRunning when the state file does not exist
+//   - a wrapped json error when the file exists but cannot be decoded
+//     (a real bug worth reporting to Sentry)
+func LoadState() (*DaemonState, error) {
 	data, err := os.ReadFile(StateFilePath())
 	if err != nil {
-		return nil
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, ErrDaemonNotRunning
+		}
+		return nil, err
 	}
 	var state DaemonState
-	if json.Unmarshal(data, &state) != nil {
-		return nil
+	if err := json.Unmarshal(data, &state); err != nil {
+		return nil, fmt.Errorf("decode daemon state %s: %w", StateFilePath(), err)
 	}
-	return &state
+	return &state, nil
 }
 
 // RemoveState deletes the state file (called on clean shutdown).
diff --git a/internal/agent/state_test.go b/internal/agent/state_test.go
index 6c9abdd..7e275be 100644
--- a/internal/agent/state_test.go
+++ b/internal/agent/state_test.go
@@ -1,6 +1,7 @@
 package agent
 
 import (
+	"errors"
 	"os"
 	"path/filepath"
 	"testing"
@@ -104,3 +105,39 @@ func TestReadStateCorruptedJSON(t *testing.T) {
 		t.Errorf("ReadState() should return nil for corrupted JSON, got %+v", state)
 	}
 }
+
+func TestLoadStateNotFound(t *testing.T) {
+	tmpDir := t.TempDir()
+	origFn := stateFilePathFn
+	stateFilePathFn = func() string { return filepath.Join(tmpDir, "nonexistent.json") }
+	defer func() { stateFilePathFn = origFn }()
+
+	state, err := LoadState()
+	if state != nil {
+		t.Errorf("LoadState() state = %+v, want nil", state)
+	}
+	if !errors.Is(err, ErrDaemonNotRunning) {
+		t.Errorf("LoadState() err = %v, want ErrDaemonNotRunning", err)
+	}
+}
+
+func TestLoadStateCorruptedJSON(t *testing.T) {
+	tmpDir := t.TempDir()
+	origFn := stateFilePathFn
+	path := filepath.Join(tmpDir, "daemon.state.json")
+	stateFilePathFn = func() string { return path }
+	defer func() { stateFilePathFn = origFn }()
+
+	os.WriteFile(path, []byte("not valid json{{{"), 0o644)
+
+	state, err := LoadState()
+	if state != nil {
+		t.Errorf("LoadState() state = %+v, want nil", state)
+	}
+	if err == nil {
+		t.Fatal("LoadState() err = nil, want decode error")
+	}
+	if errors.Is(err, ErrDaemonNotRunning) {
+		t.Error("corrupt state must not be reported as ErrDaemonNotRunning — it would be filtered from Sentry")
+	}
+}
diff --git a/internal/agent/sync.go b/internal/agent/sync.go
new file mode 100644
index 0000000..ac856a5
--- /dev/null
+++ b/internal/agent/sync.go
@@ -0,0 +1,311 @@
+package agent
+
+import (
+	"context"
+	"log"
+	"runtime"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+const (
+	// SyncIntervalWatching is the sync interval when someone is viewing the web UI.
+	SyncIntervalWatching = 3 * time.Second
+	// SyncIntervalIdle is the sync interval when nobody is watching.
+	// Keep this short enough to pick up stream requests quickly without hammering the server.
+	SyncIntervalIdle = 10 * time.Second
+)
+
+// SyncClient handles bidirectional state synchronization between the CLI and server.
+// It sends the CLI's full execution state and receives all pending server actions
+// in a single HTTP round-trip, at an adaptive interval.
+type SyncClient struct {
+	client *Client
+	cfg    DaemonConfig
+	state  *LocalState
+
+	// Callbacks — set by the daemon before calling Run.
+	OnNewTasks       func(tasks []Task)
+	OnControl        func(action, taskID string, deleteFiles bool)
+	OnStreamRequest  func(req StreamRequest)
+	OnStreamSession  func(sess StreamSession)
+	OnUpgrade        func(version string)
+	OnScan           func()
+	OnWatchingChange func(watching bool)
+	OnSyncSuccess    func() // called after each successful sync (e.g. to update state file)
+	GetFreeSlots     func() int
+	GetTaskStates    func() []TaskState // returns current state of all active + recently finished tasks
+	// GetVPNState returns the live managed-VPN split-tunnel state (whether the
+	// WireGuard tunnel is up, the mode, and the exit server) so the web can track
+	// which agent holds the single WG slot.
+	GetVPNState func() (active bool, mode, server string)
+	// GetFunnelURL returns the CloudFlare Quick Tunnel public hostname if one
+	// is active, else "". Sent on every sync so the web picks it up live.
+	GetFunnelURL func() string
+	// OnDeleteFiles is called when the server requests file deletion from disk.
+	// It should delete the files and return the IDs of successfully deleted items.
+	OnDeleteFiles func(items []LibraryDeleteRequest) []int
+
+	// SyncNow triggers an immediate sync (e.g., on task completion).
+	SyncNow chan struct{}
+
+	watching atomic.Bool
+	interval atomic.Int64 // stored as nanoseconds
+
+	// pendingDeleteConfirmed holds item IDs to report as deleted in the next sync.
+	pendingDeleteMu        sync.Mutex
+	pendingDeleteConfirmed []int
+	// deleteInFlight tracks item IDs currently being processed or awaiting confirmation.
+	// Prevents the same file from being passed to OnDeleteFiles multiple times.
+	deleteInFlight map[int]struct{}
+}
+
+// NewSyncClient creates a sync client.
+func NewSyncClient(client *Client, cfg DaemonConfig, state *LocalState) *SyncClient {
+	sc := &SyncClient{
+		client:  client,
+		cfg:     cfg,
+		state:   state,
+		SyncNow: make(chan struct{}, 1),
+	}
+	sc.interval.Store(int64(SyncIntervalIdle))
+	return sc
+}
+
+// Watching returns whether someone is viewing the web UI.
+func (sc *SyncClient) Watching() bool {
+	return sc.watching.Load()
+}
+
+// TriggerSync requests an immediate sync cycle.
+func (sc *SyncClient) TriggerSync() {
+	select {
+	case sc.SyncNow <- struct{}{}:
+	default:
+	}
+}
+
+// Run starts the adaptive sync loop. Blocks until ctx is cancelled.
+func (sc *SyncClient) Run(ctx context.Context) error {
+	// Start wake listener in background — triggers immediate syncs on demand.
+	go sc.runWakeListener(ctx)
+
+	// Initial sync immediately
+	sc.doSync(ctx)
+
+	ticker := time.NewTicker(sc.currentInterval())
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			// Final sync to report latest state
+			finalCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+			defer cancel()
+			sc.doSync(finalCtx)
+			return nil
+
+		case <-ticker.C:
+			sc.doSync(ctx)
+			ticker.Reset(sc.currentInterval())
+
+		case <-sc.SyncNow:
+			sc.doSync(ctx)
+			ticker.Reset(sc.currentInterval())
+		}
+	}
+}
+
+func (sc *SyncClient) currentInterval() time.Duration {
+	return time.Duration(sc.interval.Load())
+}
+
+func (sc *SyncClient) doSync(ctx context.Context) {
+	req := sc.buildRequest()
+	resp, err := sc.client.Sync(ctx, req)
+	if err != nil {
+		if ctx.Err() == nil {
+			log.Printf("sync failed: %v", err)
+		}
+		return
+	}
+	sc.processResponse(resp)
+	sc.adjustInterval(resp.Watching)
+	if sc.OnSyncSuccess != nil {
+		sc.OnSyncSuccess()
+	}
+}
+
+func (sc *SyncClient) buildRequest() SyncRequest {
+	req := SyncRequest{
+		AgentID:     sc.cfg.AgentID,
+		Name:        sc.cfg.AgentName,
+		Version:     sc.cfg.Version,
+		OS:          runtime.GOOS,
+		Arch:        runtime.GOARCH,
+		DownloadDir: sc.cfg.DownloadDir,
+		StreamPort:  sc.cfg.StreamPort,
+		LanIP:       sc.cfg.LanIP,
+		TailscaleIP: sc.cfg.TailscaleIP,
+		CanDelete:   sc.cfg.CanDelete,
+	}
+	if sc.GetTaskStates != nil {
+		req.Tasks = sc.GetTaskStates()
+	} else {
+		req.Tasks = sc.state.Snapshot()
+	}
+	if free, total, err := DiskInfo(sc.cfg.DownloadDir); err == nil {
+		req.DiskFreeBytes = free
+		req.DiskTotalBytes = total
+	}
+	if sc.GetFreeSlots != nil {
+		req.FreeSlots = sc.GetFreeSlots()
+	}
+	if sc.GetVPNState != nil {
+		req.VPNActive, req.VPNMode, req.VPNServer = sc.GetVPNState()
+	}
+	if sc.GetFunnelURL != nil {
+		req.FunnelURL = sc.GetFunnelURL()
+	}
+	// Flush confirmed deletions from previous cycle.
+	// Once flushed, remove IDs from deleteInFlight — the server will stop sending
+	// them after this sync, so deduplication protection is no longer needed.
+	sc.pendingDeleteMu.Lock()
+	if len(sc.pendingDeleteConfirmed) > 0 {
+		req.DeleteConfirmed = sc.pendingDeleteConfirmed
+		for _, id := range sc.pendingDeleteConfirmed {
+			delete(sc.deleteInFlight, id)
+		}
+		sc.pendingDeleteConfirmed = nil
+	}
+	sc.pendingDeleteMu.Unlock()
+	return req
+}
+
+func (sc *SyncClient) processResponse(resp *SyncResponse) {
+	// New tasks
+	if len(resp.NewTasks) > 0 && sc.OnNewTasks != nil {
+		log.Printf("sync: received %d new task(s)", len(resp.NewTasks))
+		sc.OnNewTasks(resp.NewTasks)
+	}
+
+	// Control signals
+	for _, ctrl := range resp.Controls {
+		log.Printf("sync: control %s on task %s", ctrl.Action, ShortID(ctrl.TaskID))
+		if sc.OnControl != nil {
+			sc.OnControl(ctrl.Action, ctrl.TaskID, ctrl.DeleteFiles)
+		}
+	}
+
+	// Stream requests
+	for _, sr := range resp.StreamRequests {
+		if sc.OnStreamRequest != nil {
+			sc.OnStreamRequest(sr)
+		}
+	}
+
+	// HLS streaming sessions.
+	for _, ws := range resp.StreamSessions {
+		if sc.OnStreamSession != nil {
+			sc.OnStreamSession(ws)
+		}
+	}
+
+	// Upgrade
+	if resp.Upgrade != nil && resp.Upgrade.Version != "" && sc.OnUpgrade != nil {
+		sc.OnUpgrade(resp.Upgrade.Version)
+	}
+
+	// Scan
+	if resp.Scan && sc.OnScan != nil {
+		sc.OnScan()
+	}
+
+	// File deletions requested by the server — deduplicate against in-flight items
+	if len(resp.FilesToDelete) > 0 && sc.OnDeleteFiles != nil {
+		sc.pendingDeleteMu.Lock()
+		if sc.deleteInFlight == nil {
+			sc.deleteInFlight = make(map[int]struct{})
+		}
+		var newItems []LibraryDeleteRequest
+		for _, item := range resp.FilesToDelete {
+			if _, inFlight := sc.deleteInFlight[item.ItemID]; !inFlight {
+				newItems = append(newItems, item)
+				sc.deleteInFlight[item.ItemID] = struct{}{}
+			}
+		}
+		sc.pendingDeleteMu.Unlock()
+
+		if len(newItems) > 0 {
+			// Run deletions off the sync goroutine — disk I/O must not block the
+			// next sync tick. Confirmations are picked up on the next regular cycle.
+			go func(items []LibraryDeleteRequest) {
+				confirmed := sc.OnDeleteFiles(items)
+				if len(confirmed) > 0 {
+					sc.pendingDeleteMu.Lock()
+					sc.pendingDeleteConfirmed = append(sc.pendingDeleteConfirmed, confirmed...)
+					sc.pendingDeleteMu.Unlock()
+				}
+			}(newItems)
+		}
+	}
+}
+
+// runWakeListener holds a long-poll connection to /api/internal/agent/wake.
+// When the server resolves it with wake=true (e.g., a stream was requested),
+// it triggers an immediate sync so the CLI acts in <100ms instead of waiting
+// for the next scheduled interval. Reconnects immediately after each response
+// so coverage is continuous. Runs until ctx is cancelled.
+func (sc *SyncClient) runWakeListener(ctx context.Context) {
+	const retryDelay = 2 * time.Second
+	for {
+		if ctx.Err() != nil {
+			return
+		}
+		woke, err := sc.client.WaitForWake(ctx)
+		if ctx.Err() != nil {
+			return
+		}
+		if err != nil {
+			log.Printf("wake listener: %v (retrying in %s)", err, retryDelay)
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(retryDelay):
+			}
+			continue
+		}
+		if woke {
+			log.Printf("wake signal received — syncing immediately")
+			sc.TriggerSync()
+		}
+		// On timeout (woke=false) or after a wake, reconnect immediately.
+	}
+}
+
+func (sc *SyncClient) adjustInterval(watching bool) {
+	prev := sc.watching.Load()
+	sc.watching.Store(watching)
+
+	var newInterval time.Duration
+	if watching {
+		newInterval = SyncIntervalWatching
+	} else {
+		newInterval = SyncIntervalIdle
+	}
+
+	if sc.interval.Swap(int64(newInterval)) != int64(newInterval) {
+		log.Printf("sync: interval=%s (watching=%v)", newInterval, watching)
+	}
+
+	// Trigger an immediate sync when entering watching mode so stream requests
+	// are picked up right away without waiting for the next scheduled interval.
+	if watching && !prev {
+		sc.TriggerSync()
+	}
+
+	if prev != watching && sc.OnWatchingChange != nil {
+		sc.OnWatchingChange(watching)
+	}
+}
diff --git a/internal/agent/sync_test.go b/internal/agent/sync_test.go
new file mode 100644
index 0000000..6839900
--- /dev/null
+++ b/internal/agent/sync_test.go
@@ -0,0 +1,542 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func newTestSyncClient(url string) (*SyncClient, *Client) {
+	client := NewClient(url, "test-key", "test-agent/1.0")
+	cfg := DaemonConfig{
+		AgentID:     "test-agent",
+		AgentName:   "Test",
+		Version:     "1.0.0",
+		DownloadDir: "/tmp/downloads",
+	}
+	state := NewLocalState()
+	sc := NewSyncClient(client, cfg, state)
+	return sc, client
+}
+
+func TestSyncClient_NewDefaults(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	if sc.Watching() {
+		t.Error("should not be watching initially")
+	}
+	if sc.currentInterval() != SyncIntervalIdle {
+		t.Errorf("expected idle interval %v, got %v", SyncIntervalIdle, sc.currentInterval())
+	}
+}
+
+func TestSyncClient_AdjustInterval_Watching(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	sc.adjustInterval(true)
+
+	if sc.currentInterval() != SyncIntervalWatching {
+		t.Errorf("expected watching interval %v, got %v", SyncIntervalWatching, sc.currentInterval())
+	}
+	if !sc.Watching() {
+		t.Error("expected watching=true")
+	}
+}
+
+func TestSyncClient_AdjustInterval_NotWatching(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	// First set watching, then unset
+	sc.adjustInterval(true)
+	sc.adjustInterval(false)
+
+	if sc.currentInterval() != SyncIntervalIdle {
+		t.Errorf("expected idle interval %v, got %v", SyncIntervalIdle, sc.currentInterval())
+	}
+	if sc.Watching() {
+		t.Error("expected watching=false")
+	}
+}
+
+func TestSyncClient_AdjustInterval_CallsOnWatchingChange(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	var changes []bool
+	sc.OnWatchingChange = func(w bool) { changes = append(changes, w) }
+
+	sc.adjustInterval(true)
+	sc.adjustInterval(true)  // no change
+	sc.adjustInterval(false) // change
+
+	if len(changes) != 2 {
+		t.Fatalf("expected 2 changes, got %d: %v", len(changes), changes)
+	}
+	if !changes[0] {
+		t.Error("first change should be true")
+	}
+	if changes[1] {
+		t.Error("second change should be false")
+	}
+}
+
+func TestSyncClient_TriggerSync_NonBlocking(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	// Fill the channel
+	sc.TriggerSync()
+	// Should not block
+	sc.TriggerSync()
+	sc.TriggerSync()
+
+	// Drain
+	select {
+	case <-sc.SyncNow:
+	default:
+		t.Error("expected a sync trigger in channel")
+	}
+}
+
+func TestSyncClient_ProcessResponse_NewTasks(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	var received []Task
+	sc.OnNewTasks = func(tasks []Task) { received = tasks }
+
+	sc.processResponse(&SyncResponse{
+		NewTasks: []Task{
+			{ID: "t1", Title: "Movie 1", InfoHash: "abc"},
+			{ID: "t2", Title: "Movie 2", InfoHash: "def"},
+		},
+	})
+
+	if len(received) != 2 {
+		t.Fatalf("expected 2 tasks, got %d", len(received))
+	}
+	if received[0].Title != "Movie 1" {
+		t.Errorf("expected Movie 1, got %s", received[0].Title)
+	}
+}
+
+func TestSyncClient_ProcessResponse_NoTasks(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	var called bool
+	sc.OnNewTasks = func(tasks []Task) { called = true }
+
+	sc.processResponse(&SyncResponse{NewTasks: nil})
+
+	if called {
+		t.Error("OnNewTasks should not be called with empty tasks")
+	}
+}
+
+func TestSyncClient_ProcessResponse_Controls(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	var actions []string
+	var taskIDs []string
+	sc.OnControl = func(action, taskID string, deleteFiles bool) {
+		actions = append(actions, action)
+		taskIDs = append(taskIDs, taskID)
+	}
+
+	sc.processResponse(&SyncResponse{
+		Controls: []ControlAction{
+			{Action: "cancel", TaskID: "task-1234-5678"},
+			{Action: "pause", TaskID: "task-abcd-efgh"},
+		},
+	})
+
+	if len(actions) != 2 {
+		t.Fatalf("expected 2 controls, got %d", len(actions))
+	}
+	if actions[0] != "cancel" {
+		t.Errorf("expected cancel, got %s", actions[0])
+	}
+	if actions[1] != "pause" {
+		t.Errorf("expected pause, got %s", actions[1])
+	}
+}
+
+func TestSyncClient_ProcessResponse_Upgrade(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	var version string
+	sc.OnUpgrade = func(v string) { version = v }
+
+	sc.processResponse(&SyncResponse{
+		Upgrade: &UpgradeSignal{Version: "2.0.0"},
+	})
+
+	if version != "2.0.0" {
+		t.Errorf("expected 2.0.0, got %s", version)
+	}
+}
+
+func TestSyncClient_ProcessResponse_UpgradeEmpty(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	var called bool
+	sc.OnUpgrade = func(v string) { called = true }
+
+	sc.processResponse(&SyncResponse{
+		Upgrade: &UpgradeSignal{Version: ""},
+	})
+
+	if called {
+		t.Error("OnUpgrade should not be called with empty version")
+	}
+}
+
+func TestSyncClient_ProcessResponse_Scan(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	var called bool
+	sc.OnScan = func() { called = true }
+
+	sc.processResponse(&SyncResponse{Scan: true})
+
+	if !called {
+		t.Error("OnScan should have been called")
+	}
+}
+
+func TestSyncClient_ProcessResponse_StreamRequests(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	var received []StreamRequest
+	sc.OnStreamRequest = func(sr StreamRequest) { received = append(received, sr) }
+
+	sc.processResponse(&SyncResponse{
+		StreamRequests: []StreamRequest{
+			{TaskID: "t1", FilePath: "/tmp/movie.mkv"},
+		},
+	})
+
+	if len(received) != 1 {
+		t.Fatalf("expected 1 stream request, got %d", len(received))
+	}
+	if received[0].FilePath != "/tmp/movie.mkv" {
+		t.Errorf("expected /tmp/movie.mkv, got %s", received[0].FilePath)
+	}
+}
+
+func TestSyncClient_BuildRequest_WithGetTaskStates(t *testing.T) {
+	sc, _ := newTestSyncClient("http://localhost")
+
+	sc.GetTaskStates = func() []TaskState {
+		return []TaskState{
+			{TaskID: "t1", Status: "downloading", Progress: 50},
+		}
+	}
+	sc.GetFreeSlots = func() int { return 2 }
+
+	req := sc.buildRequest()
+
+	if req.AgentID != "test-agent" {
+		t.Errorf("expected test-agent, got %s", req.AgentID)
+	}
+	if len(req.Tasks) != 1 {
+		t.Fatalf("expected 1 task, got %d", len(req.Tasks))
+	}
+	if req.Tasks[0].Progress != 50 {
+		t.Errorf("expected progress 50, got %d", req.Tasks[0].Progress)
+	}
+	if req.FreeSlots != 2 {
+		t.Errorf("expected 2 free slots, got %d", req.FreeSlots)
+	}
+}
+
+func TestSyncClient_BuildRequest_FallbackToState(t *testing.T) {
+	client := NewClient("http://localhost", "key", "ua")
+	state := NewLocalState()
+	state.Update(TaskState{TaskID: "t1", Status: "completed", Progress: 100})
+
+	sc := NewSyncClient(client, DaemonConfig{AgentID: "a1", Version: "1.0"}, state)
+	// GetTaskStates is nil — should fall back to state.Snapshot()
+
+	req := sc.buildRequest()
+	if len(req.Tasks) != 1 {
+		t.Fatalf("expected 1 task from state fallback, got %d", len(req.Tasks))
+	}
+}
+
+func TestSyncClient_DoSync_Success(t *testing.T) {
+	var syncCount atomic.Int32
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		syncCount.Add(1)
+		json.NewEncoder(w).Encode(SyncResponse{
+			Watching: true,
+			NewTasks: []Task{{ID: "t1", Title: "Test Movie", InfoHash: "abc"}},
+		})
+	}))
+	defer srv.Close()
+
+	sc, _ := newTestSyncClient(srv.URL)
+
+	var tasksReceived []Task
+	sc.OnNewTasks = func(tasks []Task) { tasksReceived = tasks }
+
+	sc.doSync(context.Background())
+
+	if syncCount.Load() != 1 {
+		t.Errorf("expected 1 sync call, got %d", syncCount.Load())
+	}
+	if len(tasksReceived) != 1 {
+		t.Fatalf("expected 1 task, got %d", len(tasksReceived))
+	}
+	if !sc.Watching() {
+		t.Error("expected watching=true after sync")
+	}
+	if sc.currentInterval() != SyncIntervalWatching {
+		t.Errorf("expected watching interval after sync")
+	}
+}
+
+func TestSyncClient_DoSync_Error(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer srv.Close()
+
+	sc, _ := newTestSyncClient(srv.URL)
+
+	// Should not panic on error
+	sc.doSync(context.Background())
+}
+
+func TestSyncClient_Run_CancelStopsLoop(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewEncoder(w).Encode(SyncResponse{})
+	}))
+	defer srv.Close()
+
+	sc, _ := newTestSyncClient(srv.URL)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+
+	err := sc.Run(ctx)
+	if err != nil {
+		t.Errorf("expected nil error, got %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// runWakeListener tests
+// ---------------------------------------------------------------------------
+
+func TestRunWakeListener_TriggersSyncOnWake(t *testing.T) {
+	// Server responds immediately with wake=true on the first call
+	var wakeCallCount atomic.Int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/api/internal/agent/wake" {
+			wakeCallCount.Add(1)
+			json.NewEncoder(w).Encode(map[string]bool{"wake": true})
+			return
+		}
+		// sync endpoint — just respond OK
+		json.NewEncoder(w).Encode(SyncResponse{})
+	}))
+	defer srv.Close()
+
+	sc, _ := newTestSyncClient(srv.URL)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	go sc.runWakeListener(ctx)
+
+	// Give the listener time to receive the wake and call TriggerSync
+	time.Sleep(200 * time.Millisecond)
+	cancel()
+
+	if wakeCallCount.Load() < 1 {
+		t.Error("expected at least one wake request")
+	}
+	// TriggerSync puts something in the buffered channel
+	select {
+	case <-sc.SyncNow:
+		// good — listener triggered a sync
+	default:
+		// channel may have been drained by Run (not running here) — check count
+		// The important thing is that wakeCallCount > 0 (request was made)
+	}
+}
+
+func TestRunWakeListener_ReconnectsAfterTimeout(t *testing.T) {
+	// Server returns wake=false (timeout) then wake=true on reconnect
+	callCount := atomic.Int32{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/wake" {
+			json.NewEncoder(w).Encode(SyncResponse{})
+			return
+		}
+		n := callCount.Add(1)
+		if n == 1 {
+			// First call: timeout
+			json.NewEncoder(w).Encode(map[string]bool{"wake": false})
+		} else {
+			// Second call: wake
+			json.NewEncoder(w).Encode(map[string]bool{"wake": true})
+		}
+	}))
+	defer srv.Close()
+
+	sc, _ := newTestSyncClient(srv.URL)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+
+	go sc.runWakeListener(ctx)
+
+	// Wait for at least 2 wake calls (reconnect after timeout)
+	deadline := time.Now().Add(1500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if callCount.Load() >= 2 {
+			break
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+
+	if callCount.Load() < 2 {
+		t.Errorf("expected at least 2 wake requests (reconnect after timeout), got %d", callCount.Load())
+	}
+}
+
+func TestRunWakeListener_RetriesAfterNetworkError(t *testing.T) {
+	// Server that refuses connections initially, then starts accepting
+	callCount := atomic.Int32{}
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/internal/agent/wake" {
+			json.NewEncoder(w).Encode(SyncResponse{})
+			return
+		}
+		callCount.Add(1)
+		json.NewEncoder(w).Encode(map[string]bool{"wake": false})
+	}))
+	defer srv.Close()
+
+	// Use a bad URL first, then switch — we can't easily switch URL, so
+	// test with a server that always errors (closed connection) via a custom transport
+	badClient := NewClient("http://127.0.0.1:1", "test-key", "unarr-test")
+	cfg := DaemonConfig{AgentID: "test-agent", Version: "1.0.0", DownloadDir: "/tmp"}
+	state := NewLocalState()
+	sc := NewSyncClient(badClient, cfg, state)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+	defer cancel()
+
+	// Should not panic — just log errors and retry
+	done := make(chan struct{})
+	go func() {
+		sc.runWakeListener(ctx)
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// Good — listener exited when ctx was cancelled
+	case <-time.After(2 * time.Second):
+		t.Error("runWakeListener did not exit after context cancellation")
+	}
+}
+
+func TestRunWakeListener_StopsOnContextCancel(t *testing.T) {
+	// Server blocks until client disconnects
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/api/internal/agent/wake" {
+			<-r.Context().Done()
+			return
+		}
+		json.NewEncoder(w).Encode(SyncResponse{})
+	}))
+	defer srv.Close()
+
+	sc, _ := newTestSyncClient(srv.URL)
+
+	ctx, cancel := context.WithCancel(context.Background())
+
+	done := make(chan struct{})
+	go func() {
+		sc.runWakeListener(ctx)
+		close(done)
+	}()
+
+	// Let it connect and block
+	time.Sleep(50 * time.Millisecond)
+	cancel()
+
+	select {
+	case <-done:
+		// Good
+	case <-time.After(2 * time.Second):
+		t.Error("runWakeListener did not stop when context was cancelled")
+	}
+}
+
+func TestRunWakeListener_DoesNotTriggerSyncOnTimeout(t *testing.T) {
+	// Server always returns wake=false — SyncNow channel should stay empty
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/api/internal/agent/wake" {
+			json.NewEncoder(w).Encode(map[string]bool{"wake": false})
+			return
+		}
+		json.NewEncoder(w).Encode(SyncResponse{})
+	}))
+	defer srv.Close()
+
+	sc, _ := newTestSyncClient(srv.URL)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+
+	go sc.runWakeListener(ctx)
+	<-ctx.Done()
+
+	// SyncNow should be empty (no wake triggered)
+	select {
+	case <-sc.SyncNow:
+		t.Error("expected no sync trigger on timeout response")
+	default:
+		// Good
+	}
+}
+
+func TestSyncClient_Run_ImmediateSyncOnTrigger(t *testing.T) {
+	var syncCount atomic.Int32
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		syncCount.Add(1)
+		json.NewEncoder(w).Encode(SyncResponse{})
+	}))
+	defer srv.Close()
+
+	sc, _ := newTestSyncClient(srv.URL)
+	// Set interval to something long so only triggers cause syncs
+	sc.interval.Store(int64(10 * time.Second))
+
+	ctx, cancel := context.WithCancel(context.Background())
+
+	go func() {
+		// Wait for initial sync, then trigger 2 more
+		time.Sleep(50 * time.Millisecond)
+		sc.TriggerSync()
+		time.Sleep(50 * time.Millisecond)
+		sc.TriggerSync()
+		time.Sleep(50 * time.Millisecond)
+		cancel()
+	}()
+
+	sc.Run(ctx)
+
+	// Initial sync (1) + 2 triggers + final sync = 4
+	count := syncCount.Load()
+	if count < 3 {
+		t.Errorf("expected at least 3 syncs (initial + 2 triggers), got %d", count)
+	}
+}
diff --git a/internal/agent/taskstate.go b/internal/agent/taskstate.go
new file mode 100644
index 0000000..51eba8b
--- /dev/null
+++ b/internal/agent/taskstate.go
@@ -0,0 +1,136 @@
+package agent
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+// TaskState represents the execution state of a single download task.
+// Written by the Task Engine, read by the Sync goroutine.
+type TaskState struct {
+	TaskID          string `json:"taskId"`
+	Status          string `json:"status"` // resolving, downloading, verifying, organizing, completed, failed
+	Progress        int    `json:"progress"`
+	DownloadedBytes int64  `json:"downloadedBytes,omitempty"`
+	TotalBytes      int64  `json:"totalBytes,omitempty"`
+	SpeedBps        int64  `json:"speedBps,omitempty"`
+	ETA             int    `json:"eta,omitempty"`
+	ResolvedMethod  string `json:"resolvedMethod,omitempty"`
+	FileName        string `json:"fileName,omitempty"`
+	FilePath        string `json:"filePath,omitempty"`
+	StreamURL       string `json:"streamUrl,omitempty"`
+	ErrorMessage    string `json:"errorMessage,omitempty"`
+	UpdatedAt       int64  `json:"updatedAt"`
+}
+
+// LocalState holds the CLI's local execution state (tasks.json).
+// This is the CLI's source of truth for what it's doing right now.
+type LocalState struct {
+	mu    sync.RWMutex
+	tasks map[string]*TaskState
+}
+
+// NewLocalState creates an empty local state.
+func NewLocalState() *LocalState {
+	return &LocalState{
+		tasks: make(map[string]*TaskState),
+	}
+}
+
+// Update adds or updates a task in local state.
+func (s *LocalState) Update(ts TaskState) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	ts.UpdatedAt = time.Now().Unix()
+	copied := ts
+	s.tasks[ts.TaskID] = &copied
+}
+
+// Remove removes a task from local state.
+func (s *LocalState) Remove(taskID string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	delete(s.tasks, taskID)
+}
+
+// Snapshot returns a copy of all current task states.
+func (s *LocalState) Snapshot() []TaskState {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	result := make([]TaskState, 0, len(s.tasks))
+	for _, ts := range s.tasks {
+		result = append(result, *ts)
+	}
+	return result
+}
+
+// TaskStateFromUpdate converts a StatusUpdate into a TaskState.
+func TaskStateFromUpdate(u StatusUpdate) TaskState {
+	return TaskState{
+		TaskID:          u.TaskID,
+		Status:          u.Status,
+		Progress:        u.Progress,
+		DownloadedBytes: u.DownloadedBytes,
+		TotalBytes:      u.TotalBytes,
+		SpeedBps:        u.SpeedBps,
+		ETA:             u.ETA,
+		ResolvedMethod:  u.ResolvedMethod,
+		FileName:        u.FileName,
+		FilePath:        u.FilePath,
+		StreamURL:       u.StreamURL,
+		ErrorMessage:    u.ErrorMessage,
+	}
+}
+
+// ShortID returns the first 8 characters of an ID, or the full ID if shorter.
+func ShortID(id string) string {
+	if len(id) > 8 {
+		return id[:8]
+	}
+	return id
+}
+
+// taskStateFilePathFn is overridable for testing.
+var taskStateFilePathFn = func() string {
+	return filepath.Join(config.DataDir(), "tasks.json")
+}
+
+// WriteToDisk persists local state to disk atomically (best-effort).
+func (s *LocalState) WriteToDisk() {
+	tasks := s.Snapshot()
+	data, err := json.MarshalIndent(tasks, "", "  ")
+	if err != nil {
+		return
+	}
+	path := taskStateFilePathFn()
+	dir := filepath.Dir(path)
+	os.MkdirAll(dir, 0o755)
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o644); err != nil {
+		return
+	}
+	os.Rename(tmp, path)
+}
+
+// ReadFromDisk loads local state from disk. Returns empty state on error.
+func (s *LocalState) ReadFromDisk() {
+	data, err := os.ReadFile(taskStateFilePathFn())
+	if err != nil {
+		return
+	}
+	var tasks []TaskState
+	if json.Unmarshal(data, &tasks) != nil {
+		return
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.tasks = make(map[string]*TaskState, len(tasks))
+	for i := range tasks {
+		s.tasks[tasks[i].TaskID] = &tasks[i]
+	}
+}
diff --git a/internal/agent/taskstate_test.go b/internal/agent/taskstate_test.go
new file mode 100644
index 0000000..aabd361
--- /dev/null
+++ b/internal/agent/taskstate_test.go
@@ -0,0 +1,270 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+func TestLocalState_UpdateAndSnapshot(t *testing.T) {
+	s := NewLocalState()
+
+	s.Update(TaskState{TaskID: "t1", Status: "downloading", Progress: 50})
+	s.Update(TaskState{TaskID: "t2", Status: "completed", Progress: 100})
+
+	snap := s.Snapshot()
+	if len(snap) != 2 {
+		t.Fatalf("expected 2 tasks, got %d", len(snap))
+	}
+
+	byID := make(map[string]TaskState, len(snap))
+	for _, ts := range snap {
+		byID[ts.TaskID] = ts
+	}
+
+	if byID["t1"].Progress != 50 {
+		t.Errorf("expected progress 50, got %d", byID["t1"].Progress)
+	}
+	if byID["t2"].Status != "completed" {
+		t.Errorf("expected completed, got %s", byID["t2"].Status)
+	}
+}
+
+func TestLocalState_UpdateOverwrites(t *testing.T) {
+	s := NewLocalState()
+
+	s.Update(TaskState{TaskID: "t1", Status: "downloading", Progress: 30})
+	s.Update(TaskState{TaskID: "t1", Status: "downloading", Progress: 70})
+
+	snap := s.Snapshot()
+	if len(snap) != 1 {
+		t.Fatalf("expected 1 task, got %d", len(snap))
+	}
+	if snap[0].Progress != 70 {
+		t.Errorf("expected progress 70, got %d", snap[0].Progress)
+	}
+}
+
+func TestLocalState_Remove(t *testing.T) {
+	s := NewLocalState()
+
+	s.Update(TaskState{TaskID: "t1", Status: "downloading"})
+	s.Update(TaskState{TaskID: "t2", Status: "downloading"})
+	s.Remove("t1")
+
+	snap := s.Snapshot()
+	if len(snap) != 1 {
+		t.Fatalf("expected 1 task, got %d", len(snap))
+	}
+	if snap[0].TaskID != "t2" {
+		t.Errorf("expected t2, got %s", snap[0].TaskID)
+	}
+}
+
+func TestLocalState_RemoveNonExistent(t *testing.T) {
+	s := NewLocalState()
+	s.Remove("nonexistent") // should not panic
+}
+
+func TestLocalState_SnapshotIsACopy(t *testing.T) {
+	s := NewLocalState()
+	s.Update(TaskState{TaskID: "t1", Status: "downloading", Progress: 50})
+
+	snap := s.Snapshot()
+	snap[0].Progress = 999
+
+	snap2 := s.Snapshot()
+	if snap2[0].Progress != 50 {
+		t.Errorf("snapshot mutation leaked: got progress %d", snap2[0].Progress)
+	}
+}
+
+func TestLocalState_UpdateSetsTimestamp(t *testing.T) {
+	s := NewLocalState()
+	s.Update(TaskState{TaskID: "t1", Status: "downloading"})
+
+	snap := s.Snapshot()
+	if snap[0].UpdatedAt == 0 {
+		t.Error("expected non-zero UpdatedAt")
+	}
+}
+
+func TestLocalState_ConcurrentAccess(t *testing.T) {
+	s := NewLocalState()
+	var wg sync.WaitGroup
+
+	for i := range 100 {
+		wg.Add(1)
+		go func(n int) {
+			defer wg.Done()
+			taskID := "t" + string(rune('0'+n%10))
+			s.Update(TaskState{TaskID: taskID, Status: "downloading", Progress: n})
+			s.Snapshot()
+			if n%3 == 0 {
+				s.Remove(taskID)
+			}
+		}(i)
+	}
+
+	wg.Wait()
+	// No race condition = test passes
+}
+
+func TestLocalState_WriteToDisk_ReadFromDisk(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tasks.json")
+
+	// Override the file path for testing
+	orig := taskStateFilePathFn
+	taskStateFilePathFn = func() string { return path }
+	defer func() { taskStateFilePathFn = orig }()
+
+	s := NewLocalState()
+	s.Update(TaskState{TaskID: "t1", Status: "downloading", Progress: 45})
+	s.Update(TaskState{TaskID: "t2", Status: "completed", Progress: 100, FilePath: "/tmp/movie.mkv"})
+	s.WriteToDisk()
+
+	// Verify file exists
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		t.Fatal("tasks.json was not created")
+	}
+
+	// Read into a new LocalState
+	s2 := NewLocalState()
+	s2.ReadFromDisk()
+
+	snap := s2.Snapshot()
+	if len(snap) != 2 {
+		t.Fatalf("expected 2 tasks after read, got %d", len(snap))
+	}
+
+	byID := make(map[string]TaskState, len(snap))
+	for _, ts := range snap {
+		byID[ts.TaskID] = ts
+	}
+
+	if byID["t1"].Progress != 45 {
+		t.Errorf("expected progress 45, got %d", byID["t1"].Progress)
+	}
+	if byID["t2"].FilePath != "/tmp/movie.mkv" {
+		t.Errorf("expected /tmp/movie.mkv, got %s", byID["t2"].FilePath)
+	}
+}
+
+func TestLocalState_ReadFromDisk_CorruptedFile(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tasks.json")
+
+	orig := taskStateFilePathFn
+	taskStateFilePathFn = func() string { return path }
+	defer func() { taskStateFilePathFn = orig }()
+
+	// Write corrupted JSON
+	os.WriteFile(path, []byte("{invalid json"), 0o644)
+
+	s := NewLocalState()
+	s.ReadFromDisk() // should not panic
+
+	snap := s.Snapshot()
+	if len(snap) != 0 {
+		t.Errorf("expected 0 tasks from corrupted file, got %d", len(snap))
+	}
+}
+
+func TestLocalState_ReadFromDisk_FileNotFound(t *testing.T) {
+	orig := taskStateFilePathFn
+	taskStateFilePathFn = func() string { return "/nonexistent/path/tasks.json" }
+	defer func() { taskStateFilePathFn = orig }()
+
+	s := NewLocalState()
+	s.ReadFromDisk() // should not panic
+
+	snap := s.Snapshot()
+	if len(snap) != 0 {
+		t.Errorf("expected 0 tasks, got %d", len(snap))
+	}
+}
+
+func TestLocalState_AtomicWrite(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "tasks.json")
+
+	orig := taskStateFilePathFn
+	taskStateFilePathFn = func() string { return path }
+	defer func() { taskStateFilePathFn = orig }()
+
+	s := NewLocalState()
+	s.Update(TaskState{TaskID: "t1", Status: "downloading"})
+	s.WriteToDisk()
+
+	// Verify no .tmp file remains
+	tmpPath := path + ".tmp"
+	if _, err := os.Stat(tmpPath); !os.IsNotExist(err) {
+		t.Error("temp file should not exist after write")
+	}
+}
+
+func TestLocalState_EmptySnapshot(t *testing.T) {
+	s := NewLocalState()
+	snap := s.Snapshot()
+	if snap == nil {
+		t.Error("snapshot should be non-nil empty slice")
+	}
+	if len(snap) != 0 {
+		t.Errorf("expected 0 tasks, got %d", len(snap))
+	}
+}
+
+func TestTaskStateFromUpdate(t *testing.T) {
+	u := StatusUpdate{
+		TaskID:          "task-1",
+		Status:          "downloading",
+		Progress:        42,
+		DownloadedBytes: 1024,
+		TotalBytes:      4096,
+		SpeedBps:        100,
+		ETA:             30,
+		ResolvedMethod:  "torrent",
+		FileName:        "movie.mkv",
+		FilePath:        "/tmp/movie.mkv",
+		StreamURL:       "http://localhost/stream",
+		ErrorMessage:    "",
+	}
+	got := TaskStateFromUpdate(u)
+	if got.TaskID != "task-1" || got.Status != "downloading" || got.Progress != 42 {
+		t.Errorf("basic fields wrong: %+v", got)
+	}
+	if got.DownloadedBytes != 1024 || got.TotalBytes != 4096 || got.SpeedBps != 100 {
+		t.Errorf("byte fields wrong: %+v", got)
+	}
+	if got.ResolvedMethod != "torrent" || got.FileName != "movie.mkv" {
+		t.Errorf("method/name fields wrong: %+v", got)
+	}
+}
+
+func TestShortID(t *testing.T) {
+	if got := ShortID("abcdef1234567890"); got != "abcdef12" {
+		t.Errorf("ShortID = %q", got)
+	}
+	if got := ShortID("short"); got != "short" {
+		t.Errorf("ShortID short = %q", got)
+	}
+	if got := ShortID(""); got != "" {
+		t.Errorf("ShortID empty = %q", got)
+	}
+}
+
+func TestStateFilePath(t *testing.T) {
+	if got := StateFilePath(); got == "" {
+		t.Errorf("StateFilePath should not be empty")
+	}
+}
+
+func TestHTTPError(t *testing.T) {
+	e := &HTTPError{StatusCode: 404, Message: "not found"}
+	got := e.Error()
+	if got == "" || got == "API error 0: " {
+		t.Errorf("HTTPError.Error() unexpected: %q", got)
+	}
+}
diff --git a/internal/agent/transport.go b/internal/agent/transport.go
deleted file mode 100644
index 4bae6d7..0000000
--- a/internal/agent/transport.go
+++ /dev/null
@@ -1,50 +0,0 @@
-package agent
-
-import "context"
-
-// Transport abstracts the communication protocol between the agent and server.
-// Both WebSocket (via CF Durable Object) and HTTP (direct to origin) implement this.
-type Transport interface {
-	// Connect establishes the transport connection.
-	Connect(ctx context.Context) error
-
-	// Close tears down the connection gracefully.
-	Close() error
-
-	// Mode returns the current transport mode ("ws" or "http").
-	Mode() string
-
-	// Register sends agent registration and returns user info + features.
-	Register(ctx context.Context, req RegisterRequest) (*RegisterResponse, error)
-
-	// SendHeartbeat sends a periodic keep-alive.
-	SendHeartbeat(ctx context.Context, req HeartbeatRequest) (*HeartbeatResponse, error)
-
-	// SendProgress reports download progress for a task.
-	SendProgress(ctx context.Context, update StatusUpdate) (*StatusResponse, error)
-
-	// ClaimTasks polls for new tasks (HTTP mode only; WS receives via Events).
-	ClaimTasks(ctx context.Context, agentID string) (*TasksResponse, error)
-
-	// Deregister notifies the server of graceful shutdown.
-	Deregister(ctx context.Context, agentID string) error
-
-	// Events returns a channel that emits server-initiated events.
-	// In HTTP mode this channel is never written to (polling handles it).
-	// In WS mode, tasks/upgrade/control arrive here.
-	Events() <-chan ServerEvent
-}
-
-// ServerEvent represents a server-initiated message received via WebSocket.
-type ServerEvent struct {
-	Type    string         // "tasks", "upgrade", "control", "disconnected"
-	Tasks   *TasksResponse // populated when Type == "tasks"
-	Upgrade *UpgradeSignal // populated when Type == "upgrade"
-	Control *ControlAction // populated when Type == "control"
-}
-
-// ControlAction represents a server push for task control.
-type ControlAction struct {
-	Action string `json:"action"` // "pause", "resume", "cancel", "stream"
-	TaskID string `json:"taskId"`
-}
diff --git a/internal/agent/transport_e2e_test.go b/internal/agent/transport_e2e_test.go
deleted file mode 100644
index 01de3cb..0000000
--- a/internal/agent/transport_e2e_test.go
+++ /dev/null
@@ -1,285 +0,0 @@
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-)
-
-// TestE2EFullLifecycle tests the full lifecycle:
-// connect → auth → receive tasks → send progress → receive control → disconnect → reconnect
-func TestE2EFullLifecycle(t *testing.T) {
-	var mu sync.Mutex
-	var receivedMessages []map[string]interface{}
-
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-		defer conn.Close()
-
-		for {
-			_, msg, err := conn.ReadMessage()
-			if err != nil {
-				return
-			}
-
-			var parsed map[string]interface{}
-			json.Unmarshal(msg, &parsed)
-
-			mu.Lock()
-			receivedMessages = append(receivedMessages, parsed)
-			mu.Unlock()
-
-			msgType, _ := parsed["type"].(string)
-			switch msgType {
-			case "auth":
-				conn.WriteJSON(wsRegisteredMessage{
-					Type:     "registered",
-					User:     UserInfo{Name: "E2E User", Plan: "pro", IsPro: true},
-					Features: FeatureFlags{Torrent: true, Debrid: true},
-				})
-
-			case "heartbeat":
-				// No response in WS mode
-
-			case "progress":
-				// Simulate server-side cancel after progress
-				if progress, ok := parsed["progress"].(float64); ok && progress >= 50 {
-					conn.WriteJSON(map[string]string{
-						"type":   "control",
-						"action": "cancel",
-						"taskId": parsed["taskId"].(string),
-					})
-				}
-
-			case "upgrade-result":
-				// Acknowledged
-			}
-		}
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	tr := NewWSTransport(wsURL, "e2e-key", "e2e-agent", "test/1.0")
-
-	ctx := context.Background()
-
-	// 1. Connect
-	if err := tr.Connect(ctx); err != nil {
-		t.Fatalf("Connect: %v", err)
-	}
-	defer tr.Close()
-
-	// 2. Auth
-	resp, err := tr.Register(ctx, RegisterRequest{
-		AgentID: "e2e-agent",
-		Name:    "E2E Test Agent",
-		Version: "1.0.0",
-		OS:      "linux",
-		Arch:    "amd64",
-	})
-	if err != nil {
-		t.Fatalf("Register: %v", err)
-	}
-	if resp.User.Name != "E2E User" {
-		t.Errorf("expected E2E User, got %s", resp.User.Name)
-	}
-	if !resp.Features.Debrid {
-		t.Error("expected debrid feature")
-	}
-
-	// 3. Send heartbeat
-	_, err = tr.SendHeartbeat(ctx, HeartbeatRequest{
-		AgentID:        "e2e-agent",
-		DiskFreeBytes:  1000000000,
-		DiskTotalBytes: 5000000000,
-	})
-	if err != nil {
-		t.Fatalf("SendHeartbeat: %v", err)
-	}
-
-	// 4. Send progress (50% → should trigger cancel control)
-	_, err = tr.SendProgress(ctx, StatusUpdate{
-		TaskID:          "task-e2e-1",
-		Status:          "downloading",
-		Progress:        50,
-		DownloadedBytes: 500,
-		TotalBytes:      1000,
-		SpeedBps:        100,
-	})
-	if err != nil {
-		t.Fatalf("SendProgress: %v", err)
-	}
-
-	// 5. Wait for control event (cancel)
-	select {
-	case event := <-tr.Events():
-		if event.Type != "control" {
-			t.Errorf("expected control event, got %s", event.Type)
-		}
-		if event.Control.Action != "cancel" {
-			t.Errorf("expected cancel, got %s", event.Control.Action)
-		}
-		if event.Control.TaskID != "task-e2e-1" {
-			t.Errorf("expected task-e2e-1, got %s", event.Control.TaskID)
-		}
-	case <-time.After(3 * time.Second):
-		t.Fatal("timeout waiting for cancel control")
-	}
-
-	// Verify server received all messages
-	time.Sleep(100 * time.Millisecond)
-	mu.Lock()
-	defer mu.Unlock()
-
-	if len(receivedMessages) < 3 {
-		t.Fatalf("expected at least 3 messages, got %d", len(receivedMessages))
-	}
-
-	types := make([]string, len(receivedMessages))
-	for i, m := range receivedMessages {
-		types[i], _ = m["type"].(string)
-	}
-
-	expected := []string{"auth", "heartbeat", "progress"}
-	for _, exp := range expected {
-		found := false
-		for _, got := range types {
-			if got == exp {
-				found = true
-				break
-			}
-		}
-		if !found {
-			t.Errorf("missing message type %q in %v", exp, types)
-		}
-	}
-}
-
-// TestE2EHybridFailover tests the full failover scenario:
-// WS connect → download → WS disconnect → switch to HTTP → continue working
-func TestE2EHybridFailover(t *testing.T) {
-	connectionCount := 0
-	var mu sync.Mutex
-
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-
-		mu.Lock()
-		connectionCount++
-		connNum := connectionCount
-		mu.Unlock()
-
-		// Read auth
-		conn.ReadMessage()
-		conn.WriteJSON(wsRegisteredMessage{
-			Type: "registered",
-			User: UserInfo{Name: "Failover User"},
-		})
-
-		if connNum == 1 {
-			// First connection: push tasks then disconnect after 200ms
-			time.Sleep(50 * time.Millisecond)
-			conn.WriteJSON(wsTasksMessage{
-				Type:  "tasks",
-				Tasks: []Task{{ID: "t1", InfoHash: "abc", Title: "Failover Movie"}},
-			})
-			time.Sleep(150 * time.Millisecond)
-			conn.Close()
-		} else {
-			// Second connection (after reconnect): push upgrade
-			time.Sleep(50 * time.Millisecond)
-			conn.WriteJSON(wsUpgradeMessage{Type: "upgrade", Version: "3.0.0"})
-			time.Sleep(500 * time.Millisecond)
-			conn.Close()
-		}
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	wsT := NewWSTransport(wsURL, "key", "a1", "ua")
-
-	// HTTP mock for fallback
-	httpSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		// Simple heartbeat response
-		json.NewEncoder(w).Encode(HeartbeatResponse{Success: true})
-	}))
-	defer httpSrv.Close()
-
-	httpT := NewHTTPTransport(httpSrv.URL, "key", "ua")
-	h := NewHybridTransport(wsT, httpT)
-
-	ctx := context.Background()
-	err := h.Connect(ctx)
-	if err != nil {
-		t.Fatalf("Connect: %v", err)
-	}
-	defer h.Close()
-
-	// Should start in WS mode
-	if h.Mode() != "ws" {
-		t.Fatalf("expected ws mode, got %s", h.Mode())
-	}
-
-	// Register via WS
-	_, err = h.Register(ctx, RegisterRequest{AgentID: "a1"})
-	if err != nil {
-		t.Fatalf("Register: %v", err)
-	}
-
-	// Receive tasks via WS
-	var tasksReceived bool
-	var disconnected bool
-
-	for i := 0; i < 3; i++ {
-		select {
-		case event := <-h.Events():
-			switch event.Type {
-			case "tasks":
-				tasksReceived = true
-				if len(event.Tasks.Tasks) != 1 || event.Tasks.Tasks[0].Title != "Failover Movie" {
-					t.Errorf("unexpected tasks: %+v", event.Tasks)
-				}
-			case "disconnected":
-				disconnected = true
-			}
-		case <-time.After(2 * time.Second):
-			break
-		}
-		if disconnected {
-			break
-		}
-	}
-
-	if !tasksReceived {
-		t.Error("did not receive tasks before disconnect")
-	}
-	if !disconnected {
-		t.Error("did not receive disconnect event")
-	}
-
-	// Should now be in HTTP mode
-	time.Sleep(100 * time.Millisecond)
-	if h.Mode() != "http" {
-		t.Errorf("expected http mode after disconnect, got %s", h.Mode())
-	}
-
-	// Heartbeat should work via HTTP fallback
-	hbResp, err := h.SendHeartbeat(ctx, HeartbeatRequest{AgentID: "a1"})
-	if err != nil {
-		t.Fatalf("SendHeartbeat via HTTP fallback: %v", err)
-	}
-	if !hbResp.Success {
-		t.Error("expected heartbeat success")
-	}
-}
diff --git a/internal/agent/transport_http.go b/internal/agent/transport_http.go
deleted file mode 100644
index 6bce13b..0000000
--- a/internal/agent/transport_http.go
+++ /dev/null
@@ -1,50 +0,0 @@
-package agent
-
-import "context"
-
-// HTTPTransport wraps the existing Client to implement Transport.
-// This is a thin adapter — no behavioral changes from the current HTTP protocol.
-type HTTPTransport struct {
-	client *Client
-	events chan ServerEvent
-}
-
-// NewHTTPTransport creates a new HTTP-based transport.
-func NewHTTPTransport(baseURL, apiKey, userAgent string) *HTTPTransport {
-	return &HTTPTransport{
-		client: NewClient(baseURL, apiKey, userAgent),
-		events: make(chan ServerEvent, 10),
-	}
-}
-
-func (t *HTTPTransport) Connect(_ context.Context) error { return nil }
-func (t *HTTPTransport) Close() error                    { return nil }
-func (t *HTTPTransport) Mode() string                    { return "http" }
-func (t *HTTPTransport) Events() <-chan ServerEvent      { return t.events }
-
-func (t *HTTPTransport) Register(ctx context.Context, req RegisterRequest) (*RegisterResponse, error) {
-	return t.client.Register(ctx, req)
-}
-
-func (t *HTTPTransport) SendHeartbeat(ctx context.Context, req HeartbeatRequest) (*HeartbeatResponse, error) {
-	return t.client.Heartbeat(ctx, req)
-}
-
-func (t *HTTPTransport) SendProgress(ctx context.Context, update StatusUpdate) (*StatusResponse, error) {
-	return t.client.ReportStatus(ctx, update)
-}
-
-func (t *HTTPTransport) BatchReportStatus(ctx context.Context, updates []StatusUpdate) (*BatchStatusResponse, error) {
-	return t.client.BatchReportStatus(ctx, updates)
-}
-
-func (t *HTTPTransport) ClaimTasks(ctx context.Context, agentID string) (*TasksResponse, error) {
-	return t.client.ClaimTasks(ctx, agentID)
-}
-
-func (t *HTTPTransport) Deregister(ctx context.Context, agentID string) error {
-	return t.client.Deregister(ctx, agentID)
-}
-
-// Client returns the underlying HTTP client for direct use if needed.
-func (t *HTTPTransport) Client() *Client { return t.client }
diff --git a/internal/agent/transport_hybrid.go b/internal/agent/transport_hybrid.go
deleted file mode 100644
index 3a4b51e..0000000
--- a/internal/agent/transport_hybrid.go
+++ /dev/null
@@ -1,214 +0,0 @@
-package agent
-
-import (
-	"context"
-	"log"
-	"sync"
-	"sync/atomic"
-	"time"
-)
-
-// HybridTransport tries WebSocket first, falls back to HTTP if WS fails.
-// Automatically reconnects WS in the background.
-type HybridTransport struct {
-	ws   *WSTransport
-	http *HTTPTransport
-
-	mode   atomic.Value // "ws" or "http"
-	events chan ServerEvent
-
-	reconnectMu      sync.Mutex
-	reconnectRunning bool
-	reconnectStop    chan struct{}
-	closed           atomic.Bool
-}
-
-// NewHybridTransport creates a transport that prefers WS with HTTP fallback.
-func NewHybridTransport(ws *WSTransport, http *HTTPTransport) *HybridTransport {
-	h := &HybridTransport{
-		ws:            ws,
-		http:          http,
-		events:        make(chan ServerEvent, 50),
-		reconnectStop: make(chan struct{}),
-	}
-	h.mode.Store("http") // start in HTTP, upgrade to WS on Connect
-	return h
-}
-
-func (h *HybridTransport) Mode() string               { return h.mode.Load().(string) }
-func (h *HybridTransport) Events() <-chan ServerEvent { return h.events }
-
-// Connect tries WS first. If it fails, falls back to HTTP and starts reconnection loop.
-func (h *HybridTransport) Connect(ctx context.Context) error {
-	// Try WebSocket first
-	if err := h.ws.Connect(ctx); err != nil {
-		log.Printf("[transport] WebSocket connect failed (%v), using HTTP fallback", err)
-		h.mode.Store("http")
-		h.startReconnectLoop()
-		return h.http.Connect(ctx)
-	}
-
-	h.mode.Store("ws")
-	log.Println("[transport] Connected via WebSocket")
-
-	// Forward WS events to unified channel + watch for disconnection
-	go h.forwardWSEvents()
-
-	return nil
-}
-
-// Close shuts down both transports and stops reconnection.
-func (h *HybridTransport) Close() error {
-	h.closed.Store(true)
-	select {
-	case <-h.reconnectStop:
-	default:
-		close(h.reconnectStop)
-	}
-	_ = h.ws.Close()
-	return h.http.Close()
-}
-
-// Register delegates to the active transport.
-func (h *HybridTransport) Register(ctx context.Context, req RegisterRequest) (*RegisterResponse, error) {
-	if h.mode.Load() == "ws" {
-		return h.ws.Register(ctx, req)
-	}
-	return h.http.Register(ctx, req)
-}
-
-// SendHeartbeat delegates to the active transport.
-func (h *HybridTransport) SendHeartbeat(ctx context.Context, req HeartbeatRequest) (*HeartbeatResponse, error) {
-	if h.mode.Load() == "ws" {
-		resp, err := h.ws.SendHeartbeat(ctx, req)
-		if err != nil {
-			// WS write failed — switch to HTTP
-			h.switchToHTTP()
-			return h.http.SendHeartbeat(ctx, req)
-		}
-		return resp, nil
-	}
-	return h.http.SendHeartbeat(ctx, req)
-}
-
-// SendProgress delegates to the active transport.
-func (h *HybridTransport) SendProgress(ctx context.Context, update StatusUpdate) (*StatusResponse, error) {
-	if h.mode.Load() == "ws" {
-		resp, err := h.ws.SendProgress(ctx, update)
-		if err != nil {
-			h.switchToHTTP()
-			return h.http.SendProgress(ctx, update)
-		}
-		return resp, nil
-	}
-	return h.http.SendProgress(ctx, update)
-}
-
-// ClaimTasks delegates to the active transport.
-func (h *HybridTransport) ClaimTasks(ctx context.Context, agentID string) (*TasksResponse, error) {
-	if h.mode.Load() == "ws" {
-		return h.ws.ClaimTasks(ctx, agentID) // no-op in WS mode
-	}
-	return h.http.ClaimTasks(ctx, agentID)
-}
-
-// Deregister delegates to the active transport.
-func (h *HybridTransport) Deregister(ctx context.Context, agentID string) error {
-	if h.mode.Load() == "ws" {
-		return h.ws.Deregister(ctx, agentID)
-	}
-	return h.http.Deregister(ctx, agentID)
-}
-
-// ── Internal ─────────────────────────────────────────────────────────────────
-
-func (h *HybridTransport) switchToHTTP() {
-	if h.mode.Load() == "http" {
-		return
-	}
-	log.Println("[transport] Switching to HTTP fallback")
-	h.mode.Store("http")
-	_ = h.ws.Close()
-	h.startReconnectLoop()
-}
-
-func (h *HybridTransport) forwardWSEvents() {
-	for {
-		select {
-		case <-h.reconnectStop:
-			return
-		case event, ok := <-h.ws.Events():
-			if !ok {
-				return // channel closed
-			}
-			if event.Type == "disconnected" {
-				h.switchToHTTP()
-				select {
-				case h.events <- event:
-				default:
-				}
-				return
-			}
-			select {
-			case h.events <- event:
-			default:
-				log.Printf("[transport] events channel full, dropping %s event", event.Type)
-			}
-		}
-	}
-}
-
-func (h *HybridTransport) startReconnectLoop() {
-	h.reconnectMu.Lock()
-	defer h.reconnectMu.Unlock()
-	if h.reconnectRunning {
-		return
-	}
-	h.reconnectRunning = true
-	go h.reconnectLoop()
-}
-
-func (h *HybridTransport) reconnectLoop() {
-	backoff := 5 * time.Second
-	maxBackoff := 60 * time.Second
-
-	for {
-		select {
-		case <-h.reconnectStop:
-			return
-		case <-time.After(backoff):
-		}
-
-		if h.closed.Load() {
-			return
-		}
-
-		// Already on WS? (someone else reconnected)
-		if h.mode.Load() == "ws" {
-			return
-		}
-
-		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-		err := h.ws.Connect(ctx)
-		cancel()
-
-		if err != nil {
-			log.Printf("[transport] WS reconnect failed: %v (retry in %v)", err, backoff)
-			backoff = min(backoff*2, maxBackoff)
-			continue
-		}
-
-		// WS reconnected — switch back
-		log.Println("[transport] WebSocket reconnected")
-		h.mode.Store("ws")
-
-		// Reset reconnect flag so loop can start again if WS drops
-		h.reconnectMu.Lock()
-		h.reconnectRunning = false
-		h.reconnectMu.Unlock()
-
-		// Forward events from new WS connection
-		go h.forwardWSEvents()
-		return
-	}
-}
diff --git a/internal/agent/transport_test.go b/internal/agent/transport_test.go
deleted file mode 100644
index a9c7e5d..0000000
--- a/internal/agent/transport_test.go
+++ /dev/null
@@ -1,445 +0,0 @@
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/gorilla/websocket"
-)
-
-// ── HTTP Transport Tests ─────────────────────────────────────────────────────
-
-func TestHTTPTransportMode(t *testing.T) {
-	tr := NewHTTPTransport("http://localhost", "key", "ua")
-	if tr.Mode() != "http" {
-		t.Errorf("expected http, got %s", tr.Mode())
-	}
-}
-
-func TestHTTPTransportEventsNeverEmit(t *testing.T) {
-	tr := NewHTTPTransport("http://localhost", "key", "ua")
-	select {
-	case <-tr.Events():
-		t.Error("events channel should never emit in HTTP mode")
-	case <-time.After(50 * time.Millisecond):
-		// expected
-	}
-}
-
-func TestHTTPTransportDelegates(t *testing.T) {
-	// Mock server for register
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		json.NewEncoder(w).Encode(RegisterResponse{
-			Success: true,
-			User:    UserInfo{Name: "Test", Plan: "pro"},
-		})
-	}))
-	defer srv.Close()
-
-	tr := NewHTTPTransport(srv.URL, "test-key", "test-agent")
-	resp, err := tr.Register(context.Background(), RegisterRequest{AgentID: "a1"})
-	if err != nil {
-		t.Fatalf("Register failed: %v", err)
-	}
-	if !resp.Success {
-		t.Error("expected success")
-	}
-	if resp.User.Name != "Test" {
-		t.Errorf("expected Test, got %s", resp.User.Name)
-	}
-}
-
-// ── WebSocket Transport Tests ────────────────────────────────────────────────
-
-var upgrader = websocket.Upgrader{
-	CheckOrigin: func(r *http.Request) bool { return true },
-}
-
-func TestWSTransportConnectAndAuth(t *testing.T) {
-	var received wsAuthMessage
-	var mu sync.Mutex
-
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			t.Fatalf("upgrade: %v", err)
-		}
-		defer conn.Close()
-
-		// Read auth message
-		_, msg, err := conn.ReadMessage()
-		if err != nil {
-			return
-		}
-		mu.Lock()
-		json.Unmarshal(msg, &received)
-		mu.Unlock()
-
-		// Send registered response
-		conn.WriteJSON(wsRegisteredMessage{
-			Type:     "registered",
-			User:     UserInfo{Name: "WS User", Plan: "pro", IsPro: true},
-			Features: FeatureFlags{Torrent: true},
-		})
-
-		// Keep connection open
-		time.Sleep(500 * time.Millisecond)
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	tr := NewWSTransport(wsURL, "my-api-key", "agent-123", "test/1.0")
-
-	ctx := context.Background()
-	if err := tr.Connect(ctx); err != nil {
-		t.Fatalf("Connect failed: %v", err)
-	}
-	defer tr.Close()
-
-	resp, err := tr.Register(ctx, RegisterRequest{
-		AgentID: "agent-123",
-		Name:    "test-agent",
-		Version: "1.0.0",
-	})
-	if err != nil {
-		t.Fatalf("Register failed: %v", err)
-	}
-	if !resp.Success {
-		t.Error("expected success")
-	}
-	if resp.User.Name != "WS User" {
-		t.Errorf("expected WS User, got %s", resp.User.Name)
-	}
-
-	mu.Lock()
-	if received.APIKey != "my-api-key" {
-		t.Errorf("expected my-api-key, got %s", received.APIKey)
-	}
-	if received.AgentID != "agent-123" {
-		t.Errorf("expected agent-123, got %s", received.AgentID)
-	}
-	mu.Unlock()
-}
-
-func TestWSTransportReceiveTasks(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-		defer conn.Close()
-
-		// Read auth
-		conn.ReadMessage()
-		conn.WriteJSON(wsRegisteredMessage{
-			Type: "registered",
-			User: UserInfo{Name: "Test"},
-		})
-
-		// Push tasks
-		time.Sleep(50 * time.Millisecond)
-		conn.WriteJSON(wsTasksMessage{
-			Type: "tasks",
-			Tasks: []Task{
-				{ID: "t1", InfoHash: "abc123", Title: "Test Movie"},
-				{ID: "t2", InfoHash: "def456", Title: "Test Show"},
-			},
-		})
-
-		time.Sleep(500 * time.Millisecond)
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	tr := NewWSTransport(wsURL, "key", "agent1", "ua")
-
-	ctx := context.Background()
-	tr.Connect(ctx)
-	defer tr.Close()
-
-	tr.Register(ctx, RegisterRequest{AgentID: "agent1"})
-
-	// Wait for tasks event
-	select {
-	case event := <-tr.Events():
-		if event.Type != "tasks" {
-			t.Errorf("expected tasks, got %s", event.Type)
-		}
-		if len(event.Tasks.Tasks) != 2 {
-			t.Errorf("expected 2 tasks, got %d", len(event.Tasks.Tasks))
-		}
-		if event.Tasks.Tasks[0].Title != "Test Movie" {
-			t.Errorf("expected Test Movie, got %s", event.Tasks.Tasks[0].Title)
-		}
-	case <-time.After(2 * time.Second):
-		t.Fatal("timeout waiting for tasks event")
-	}
-}
-
-func TestWSTransportReceiveControl(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-		defer conn.Close()
-
-		conn.ReadMessage()
-		conn.WriteJSON(wsRegisteredMessage{Type: "registered", User: UserInfo{}})
-
-		time.Sleep(50 * time.Millisecond)
-		conn.WriteJSON(map[string]string{
-			"type":   "control",
-			"action": "cancel",
-			"taskId": "task-99",
-		})
-
-		time.Sleep(500 * time.Millisecond)
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	tr := NewWSTransport(wsURL, "key", "a1", "ua")
-
-	ctx := context.Background()
-	tr.Connect(ctx)
-	defer tr.Close()
-	tr.Register(ctx, RegisterRequest{AgentID: "a1"})
-
-	select {
-	case event := <-tr.Events():
-		if event.Type != "control" {
-			t.Errorf("expected control, got %s", event.Type)
-		}
-		if event.Control.Action != "cancel" {
-			t.Errorf("expected cancel, got %s", event.Control.Action)
-		}
-		if event.Control.TaskID != "task-99" {
-			t.Errorf("expected task-99, got %s", event.Control.TaskID)
-		}
-	case <-time.After(2 * time.Second):
-		t.Fatal("timeout waiting for control event")
-	}
-}
-
-func TestWSTransportReceiveUpgrade(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-		defer conn.Close()
-
-		conn.ReadMessage()
-		conn.WriteJSON(wsRegisteredMessage{Type: "registered", User: UserInfo{}})
-
-		time.Sleep(50 * time.Millisecond)
-		conn.WriteJSON(wsUpgradeMessage{Type: "upgrade", Version: "2.0.0"})
-
-		time.Sleep(500 * time.Millisecond)
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	tr := NewWSTransport(wsURL, "key", "a1", "ua")
-
-	ctx := context.Background()
-	tr.Connect(ctx)
-	defer tr.Close()
-	tr.Register(ctx, RegisterRequest{AgentID: "a1"})
-
-	select {
-	case event := <-tr.Events():
-		if event.Type != "upgrade" {
-			t.Errorf("expected upgrade, got %s", event.Type)
-		}
-		if event.Upgrade.Version != "2.0.0" {
-			t.Errorf("expected 2.0.0, got %s", event.Upgrade.Version)
-		}
-	case <-time.After(2 * time.Second):
-		t.Fatal("timeout waiting for upgrade event")
-	}
-}
-
-func TestWSTransportDisconnect(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-
-		conn.ReadMessage()
-		conn.WriteJSON(wsRegisteredMessage{Type: "registered", User: UserInfo{}})
-
-		// Close after a short delay to simulate disconnection
-		time.Sleep(100 * time.Millisecond)
-		conn.Close()
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	tr := NewWSTransport(wsURL, "key", "a1", "ua")
-
-	ctx := context.Background()
-	tr.Connect(ctx)
-	defer tr.Close()
-	tr.Register(ctx, RegisterRequest{AgentID: "a1"})
-
-	select {
-	case event := <-tr.Events():
-		if event.Type != "disconnected" {
-			t.Errorf("expected disconnected, got %s", event.Type)
-		}
-	case <-time.After(2 * time.Second):
-		t.Fatal("timeout waiting for disconnected event")
-	}
-}
-
-func TestWSTransportSendProgress(t *testing.T) {
-	var receivedMsg map[string]interface{}
-	var mu sync.Mutex
-
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-		defer conn.Close()
-
-		// Read auth
-		conn.ReadMessage()
-		conn.WriteJSON(wsRegisteredMessage{Type: "registered", User: UserInfo{}})
-
-		// Read progress
-		_, msg, err := conn.ReadMessage()
-		if err != nil {
-			return
-		}
-		mu.Lock()
-		json.Unmarshal(msg, &receivedMsg)
-		mu.Unlock()
-
-		time.Sleep(500 * time.Millisecond)
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	tr := NewWSTransport(wsURL, "key", "a1", "ua")
-
-	ctx := context.Background()
-	tr.Connect(ctx)
-	defer tr.Close()
-	tr.Register(ctx, RegisterRequest{AgentID: "a1"})
-
-	time.Sleep(50 * time.Millisecond)
-	resp, err := tr.SendProgress(ctx, StatusUpdate{
-		TaskID:   "t1",
-		Status:   "downloading",
-		Progress: 42,
-	})
-	if err != nil {
-		t.Fatalf("SendProgress failed: %v", err)
-	}
-	if !resp.Success {
-		t.Error("expected success response")
-	}
-
-	time.Sleep(100 * time.Millisecond)
-	mu.Lock()
-	if receivedMsg["type"] != "progress" {
-		t.Errorf("expected progress, got %v", receivedMsg["type"])
-	}
-	if receivedMsg["taskId"] != "t1" {
-		t.Errorf("expected t1, got %v", receivedMsg["taskId"])
-	}
-	mu.Unlock()
-}
-
-// ── Hybrid Transport Tests ───────────────────────────────────────────────────
-
-func TestHybridTransportWSSuccess(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-		defer conn.Close()
-		time.Sleep(500 * time.Millisecond)
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	wsT := NewWSTransport(wsURL, "key", "a1", "ua")
-	httpT := NewHTTPTransport("http://localhost", "key", "ua")
-
-	h := NewHybridTransport(wsT, httpT)
-	err := h.Connect(context.Background())
-	if err != nil {
-		t.Fatalf("Connect failed: %v", err)
-	}
-	defer h.Close()
-
-	if h.Mode() != "ws" {
-		t.Errorf("expected ws mode, got %s", h.Mode())
-	}
-}
-
-func TestHybridTransportWSFailFallbackHTTP(t *testing.T) {
-	// WS URL points to nowhere
-	wsT := NewWSTransport("ws://127.0.0.1:1", "key", "a1", "ua")
-	httpT := NewHTTPTransport("http://localhost", "key", "ua")
-
-	h := NewHybridTransport(wsT, httpT)
-	err := h.Connect(context.Background())
-	if err != nil {
-		t.Fatalf("Connect should succeed with HTTP fallback: %v", err)
-	}
-	defer h.Close()
-
-	if h.Mode() != "http" {
-		t.Errorf("expected http mode after WS failure, got %s", h.Mode())
-	}
-}
-
-func TestHybridTransportWSDisconnectSwitchesToHTTP(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		conn, err := upgrader.Upgrade(w, r, nil)
-		if err != nil {
-			return
-		}
-		// Close immediately to trigger disconnect
-		time.Sleep(100 * time.Millisecond)
-		conn.Close()
-	}))
-	defer srv.Close()
-
-	wsURL := "ws" + strings.TrimPrefix(srv.URL, "http")
-	wsT := NewWSTransport(wsURL, "key", "a1", "ua")
-	httpT := NewHTTPTransport("http://localhost", "key", "ua")
-
-	h := NewHybridTransport(wsT, httpT)
-	h.Connect(context.Background())
-	defer h.Close()
-
-	// Wait for disconnect event
-	select {
-	case event := <-h.Events():
-		if event.Type != "disconnected" {
-			t.Errorf("expected disconnected, got %s", event.Type)
-		}
-	case <-time.After(2 * time.Second):
-		t.Fatal("timeout waiting for disconnected event")
-	}
-
-	// Mode should be HTTP now
-	time.Sleep(100 * time.Millisecond)
-	if h.Mode() != "http" {
-		t.Errorf("expected http after disconnect, got %s", h.Mode())
-	}
-}
diff --git a/internal/agent/transport_ws.go b/internal/agent/transport_ws.go
deleted file mode 100644
index 65c9870..0000000
--- a/internal/agent/transport_ws.go
+++ /dev/null
@@ -1,349 +0,0 @@
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"log"
-	"net/http"
-	"strings"
-	"sync"
-	"sync/atomic"
-	"time"
-
-	"github.com/gorilla/websocket"
-)
-
-// WSTransport communicates with the server via WebSocket through a Cloudflare Durable Object.
-type WSTransport struct {
-	wsURL     string // wss://unarr.torrentclaw.com/ws/{agentId}
-	apiKey    string
-	agentID   string
-	userAgent string
-
-	conn   *websocket.Conn
-	mu     sync.Mutex
-	events chan ServerEvent
-	closed atomic.Bool
-
-	// Cached auth response from the DO
-	authResp     *RegisterResponse
-	authMu       sync.Mutex
-	authDone     chan struct{}
-	authDoneOnce sync.Once
-}
-
-// NewWSTransport creates a WebSocket-based transport.
-func NewWSTransport(wsURL, apiKey, agentID, userAgent string) *WSTransport {
-	return &WSTransport{
-		wsURL:     wsURL,
-		apiKey:    apiKey,
-		agentID:   agentID,
-		userAgent: userAgent,
-		events:    make(chan ServerEvent, 50),
-		authDone:  make(chan struct{}),
-	}
-}
-
-func (t *WSTransport) Mode() string               { return "ws" }
-func (t *WSTransport) Events() <-chan ServerEvent { return t.events }
-
-// Connect dials the WebSocket server and starts the read loop.
-func (t *WSTransport) Connect(ctx context.Context) error {
-	dialer := websocket.Dialer{
-		HandshakeTimeout: 10 * time.Second,
-	}
-
-	header := http.Header{}
-	header.Set("User-Agent", t.userAgent)
-
-	// Append API key as query param for auth on WS upgrade
-	wsURLWithKey := t.wsURL
-	if t.apiKey != "" {
-		sep := "?"
-		if strings.Contains(wsURLWithKey, "?") {
-			sep = "&"
-		}
-		wsURLWithKey += sep + "key=" + t.apiKey
-	}
-
-	conn, wsResp, err := dialer.DialContext(ctx, wsURLWithKey, header)
-	if wsResp != nil && wsResp.Body != nil {
-		defer wsResp.Body.Close()
-	}
-	if err != nil {
-		return fmt.Errorf("ws dial: %w", err)
-	}
-
-	t.mu.Lock()
-	t.conn = conn
-	t.closed.Store(false)
-	t.authDone = make(chan struct{})
-	t.authDoneOnce = sync.Once{}
-	t.mu.Unlock()
-
-	go t.readLoop(conn)
-	return nil
-}
-
-// Close sends a close frame and shuts down the connection.
-func (t *WSTransport) Close() error {
-	t.closed.Store(true)
-	t.mu.Lock()
-	defer t.mu.Unlock()
-	if t.conn != nil {
-		_ = t.conn.WriteMessage(
-			websocket.CloseMessage,
-			websocket.FormatCloseMessage(websocket.CloseNormalClosure, ""),
-		)
-		err := t.conn.Close()
-		t.conn = nil
-		return err
-	}
-	return nil
-}
-
-// Register sends auth message and waits for the registered response.
-func (t *WSTransport) Register(ctx context.Context, req RegisterRequest) (*RegisterResponse, error) {
-	msg := wsAuthMessage{
-		Type:           "auth",
-		APIKey:         t.apiKey,
-		AgentID:        req.AgentID,
-		Name:           req.Name,
-		OS:             req.OS,
-		Arch:           req.Arch,
-		Version:        req.Version,
-		DownloadDir:    req.DownloadDir,
-		DiskFreeBytes:  req.DiskFreeBytes,
-		DiskTotalBytes: req.DiskTotalBytes,
-	}
-
-	if err := t.send(msg); err != nil {
-		return nil, fmt.Errorf("ws auth send: %w", err)
-	}
-
-	// Wait for the auth response or context cancellation
-	select {
-	case <-t.authDone:
-		t.authMu.Lock()
-		resp := t.authResp
-		t.authMu.Unlock()
-		if resp == nil {
-			return nil, fmt.Errorf("ws auth: no response received")
-		}
-		return resp, nil
-	case <-ctx.Done():
-		return nil, ctx.Err()
-	case <-time.After(15 * time.Second):
-		return nil, fmt.Errorf("ws auth: timeout waiting for registered response")
-	}
-}
-
-// SendHeartbeat sends a heartbeat message. No blocking response in WS mode.
-func (t *WSTransport) SendHeartbeat(_ context.Context, req HeartbeatRequest) (*HeartbeatResponse, error) {
-	msg := struct {
-		Type string `json:"type"`
-		Disk *struct {
-			Free  int64 `json:"free"`
-			Total int64 `json:"total"`
-		} `json:"disk,omitempty"`
-	}{Type: "heartbeat"}
-
-	if req.DiskFreeBytes > 0 || req.DiskTotalBytes > 0 {
-		msg.Disk = &struct {
-			Free  int64 `json:"free"`
-			Total int64 `json:"total"`
-		}{Free: req.DiskFreeBytes, Total: req.DiskTotalBytes}
-	}
-
-	if err := t.send(msg); err != nil {
-		return nil, err
-	}
-	// WS mode: heartbeat is fire-and-forget. Upgrade signals arrive via Events().
-	return &HeartbeatResponse{Success: true}, nil
-}
-
-// SendProgress sends a progress update. Control signals arrive async via Events().
-func (t *WSTransport) SendProgress(_ context.Context, update StatusUpdate) (*StatusResponse, error) {
-	msg := struct {
-		Type            string `json:"type"`
-		TaskID          string `json:"taskId"`
-		Status          string `json:"status,omitempty"`
-		Progress        int    `json:"progress,omitempty"`
-		DownloadedBytes int64  `json:"downloadedBytes,omitempty"`
-		TotalBytes      int64  `json:"totalBytes,omitempty"`
-		SpeedBps        int64  `json:"speedBps,omitempty"`
-		ETA             int    `json:"eta,omitempty"`
-		ResolvedMethod  string `json:"resolvedMethod,omitempty"`
-		FileName        string `json:"fileName,omitempty"`
-		FilePath        string `json:"filePath,omitempty"`
-		StreamURL       string `json:"streamUrl,omitempty"`
-		ErrorMessage    string `json:"errorMessage,omitempty"`
-	}{
-		Type:            "progress",
-		TaskID:          update.TaskID,
-		Status:          update.Status,
-		Progress:        update.Progress,
-		DownloadedBytes: update.DownloadedBytes,
-		TotalBytes:      update.TotalBytes,
-		SpeedBps:        update.SpeedBps,
-		ETA:             update.ETA,
-		ResolvedMethod:  update.ResolvedMethod,
-		FileName:        update.FileName,
-		FilePath:        update.FilePath,
-		StreamURL:       update.StreamURL,
-		ErrorMessage:    update.ErrorMessage,
-	}
-
-	if err := t.send(msg); err != nil {
-		return nil, err
-	}
-	// In WS mode, control signals come via Events(), not in the progress response.
-	return &StatusResponse{Success: true}, nil
-}
-
-// ClaimTasks is a no-op in WS mode — tasks arrive via Events().
-func (t *WSTransport) ClaimTasks(_ context.Context, _ string) (*TasksResponse, error) {
-	return &TasksResponse{}, nil
-}
-
-// Deregister is handled by WebSocket close (DO detects disconnection).
-func (t *WSTransport) Deregister(_ context.Context, _ string) error {
-	return t.Close()
-}
-
-// ── Internal ─────────────────────────────────────────────────────────────────
-
-func (t *WSTransport) send(msg any) error {
-	t.mu.Lock()
-	defer t.mu.Unlock()
-	if t.conn == nil {
-		return fmt.Errorf("ws: not connected")
-	}
-	data, err := json.Marshal(msg)
-	if err != nil {
-		return err
-	}
-	return t.conn.WriteMessage(websocket.TextMessage, data)
-}
-
-func (t *WSTransport) readLoop(conn *websocket.Conn) {
-	for {
-		_, msg, err := conn.ReadMessage()
-		if err != nil {
-			if !t.closed.Load() {
-				log.Printf("[ws] read error: %v", err)
-				// Signal disconnection to the daemon
-				select {
-				case t.events <- ServerEvent{Type: "disconnected"}:
-				default:
-				}
-			}
-			return
-		}
-
-		var envelope struct {
-			Type string `json:"type"`
-		}
-		if err := json.Unmarshal(msg, &envelope); err != nil {
-			log.Printf("[ws] invalid message: %v", err)
-			continue
-		}
-
-		switch envelope.Type {
-		case "registered":
-			var resp wsRegisteredMessage
-			if json.Unmarshal(msg, &resp) == nil {
-				t.authMu.Lock()
-				t.authResp = &RegisterResponse{
-					Success:  true,
-					User:     resp.User,
-					Features: resp.Features,
-				}
-				t.authMu.Unlock()
-				// Signal that auth is complete (sync.Once prevents double-close panic)
-				t.authDoneOnce.Do(func() { close(t.authDone) })
-			}
-
-		case "tasks":
-			var resp wsTasksMessage
-			if json.Unmarshal(msg, &resp) == nil {
-				select {
-				case t.events <- ServerEvent{
-					Type: "tasks",
-					Tasks: &TasksResponse{
-						Tasks:          resp.Tasks,
-						StreamRequests: resp.StreamRequests,
-					},
-				}:
-				default:
-					log.Printf("[ws] events channel full, dropping tasks message")
-				}
-			}
-
-		case "upgrade":
-			var resp wsUpgradeMessage
-			if json.Unmarshal(msg, &resp) == nil {
-				select {
-				case t.events <- ServerEvent{
-					Type:    "upgrade",
-					Upgrade: &UpgradeSignal{Version: resp.Version},
-				}:
-				default:
-				}
-			}
-
-		case "control":
-			var resp ControlAction
-			if json.Unmarshal(msg, &resp) == nil {
-				select {
-				case t.events <- ServerEvent{
-					Type:    "control",
-					Control: &resp,
-				}:
-				default:
-				}
-			}
-
-		case "error":
-			var resp struct {
-				Message string `json:"message"`
-			}
-			if json.Unmarshal(msg, &resp) == nil {
-				log.Printf("[ws] server error: %s", resp.Message)
-			}
-		}
-	}
-}
-
-// ── WS message types ─────────────────────────────────────────────────────────
-
-type wsAuthMessage struct {
-	Type           string `json:"type"`
-	APIKey         string `json:"apiKey"`
-	AgentID        string `json:"agentId"`
-	Name           string `json:"name,omitempty"`
-	OS             string `json:"os,omitempty"`
-	Arch           string `json:"arch,omitempty"`
-	Version        string `json:"version,omitempty"`
-	DownloadDir    string `json:"downloadDir,omitempty"`
-	DiskFreeBytes  int64  `json:"diskFreeBytes,omitempty"`
-	DiskTotalBytes int64  `json:"diskTotalBytes,omitempty"`
-}
-
-type wsRegisteredMessage struct {
-	Type     string       `json:"type"`
-	User     UserInfo     `json:"user"`
-	Features FeatureFlags `json:"features"`
-}
-
-type wsTasksMessage struct {
-	Type           string          `json:"type"`
-	Tasks          []Task          `json:"tasks"`
-	StreamRequests []StreamRequest `json:"streamRequests,omitempty"`
-}
-
-type wsUpgradeMessage struct {
-	Type    string `json:"type"`
-	Version string `json:"version"`
-}
diff --git a/internal/agent/types.go b/internal/agent/types.go
index a5d2a81..ae87bb6 100644
--- a/internal/agent/types.go
+++ b/internal/agent/types.go
@@ -1,6 +1,9 @@
 package agent
 
-import "time"
+import (
+	"fmt"
+	"time"
+)
 
 // RegisterRequest is sent by the CLI on startup to register itself.
 type RegisterRequest struct {
@@ -12,6 +15,37 @@ type RegisterRequest struct {
 	DownloadDir    string `json:"downloadDir,omitempty"`
 	DiskFreeBytes  int64  `json:"diskFreeBytes,omitempty"`
 	DiskTotalBytes int64  `json:"diskTotalBytes,omitempty"`
+	StreamPort     int    `json:"streamPort,omitempty"`
+	LanIP          string `json:"lanIp,omitempty"`
+	TailscaleIP    string `json:"tailscaleIp,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
+	// the largest output resolution the agent can encode comfortably; for
+	// software-only ffmpeg this is 1080p, with a real GPU encoder it goes
+	// up to 2160p.
+	HWAccel            string `json:"hwAccel,omitempty"`
+	MaxTranscodeHeight int    `json:"maxTranscodeHeight,omitempty"`
+	// Diagnostic surface filled by engine.DetectHWAccelDiagnostic at daemon
+	// start. Surfaced in the web "Diagnose transcoder" modal so users can
+	// see *why* their HWAccel landed on "none" without running
+	// `unarr probe-hwaccel` locally — most commonly the ffmpeg binary
+	// shipped without HW encoders (linuxbrew, brew's default formula).
+	FFmpegVersion string   `json:"ffmpegVersion,omitempty"`
+	FFmpegPath    string   `json:"ffmpegPath,omitempty"`
+	HWEncoders    []string `json:"hwEncoders,omitempty"`
+	HWDevices     []string `json:"hwDevices,omitempty"`
+	// Managed-VPN split-tunnel state. The web tracks which agent holds the single
+	// WireGuard slot (1 VPNResellers account = 1 WG keypair = 1 concurrent
+	// connection); other agents are told to use OpenVPN on their host instead.
+	// VPNActive has no omitempty: false is a meaningful state (tunnel down), not
+	// "unset" — the server must see it to release the slot.
+	VPNActive bool   `json:"vpnActive"`
+	VPNMode   string `json:"vpnMode,omitempty"` // managed | self-hosted
+	VPNServer string `json:"vpnServer,omitempty"`
+	// CloudFlare Quick Tunnel hostname when enabled; the web prefers it over
+	// Tailscale/LAN for in-browser playback because it works on any network.
+	FunnelURL string `json:"funnelUrl,omitempty"`
 }
 
 // RegisterResponse is returned by the server after registration.
@@ -44,17 +78,6 @@ type UsenetServerInfo struct {
 	SSL  bool   `json:"ssl"`
 }
 
-// HeartbeatRequest is sent every 30s to keep the agent alive.
-type HeartbeatRequest struct {
-	AgentID        string `json:"agentId"`
-	Name           string `json:"name,omitempty"`
-	Version        string `json:"version,omitempty"`
-	OS             string `json:"os,omitempty"`
-	DownloadDir    string `json:"downloadDir,omitempty"`
-	DiskFreeBytes  int64  `json:"diskFreeBytes,omitempty"`
-	DiskTotalBytes int64  `json:"diskTotalBytes,omitempty"`
-}
-
 // Task represents a download task claimed from the server.
 type Task struct {
 	ID              string `json:"id"`
@@ -71,12 +94,18 @@ type Task struct {
 	ReplacePath     string `json:"replacePath,omitempty"`    // File to replace after download (upgrade mode)
 	LibraryItemID   int    `json:"libraryItemId,omitempty"`  // Library item being upgraded
 	ForceStart      bool   `json:"forceStart,omitempty"`     // Bypass queue (like Transmission's Force Start)
-}
+	ContentType     string `json:"contentType,omitempty"`    // "movie" | "show" — from server metadata
+	ContentTitle    string `json:"contentTitle,omitempty"`   // Clean title from TMDB (e.g., "Frieren: Beyond Journey's End")
+	Season          *int   `json:"season,omitempty"`         // Season number
+	Episode         *int   `json:"episode,omitempty"`        // Episode number
+	ContentYear     *int   `json:"contentYear,omitempty"`    // Year from TMDB (avoids regex on torrent title)
+	CollectionName  string `json:"collectionName,omitempty"` // Collection name (e.g., "Harry Potter Collection")
 
-// TasksResponse wraps the array of tasks returned by the server.
-type TasksResponse struct {
-	Tasks          []Task          `json:"tasks"`
-	StreamRequests []StreamRequest `json:"streamRequests,omitempty"`
+	// FilePath is the on-disk path of the file the agent is being asked
+	// to operate on. Currently used by mode=seed_file to know which
+	// arbitrary file to wrap as a single-file torrent for browser
+	// streaming; populated by the server from libraryItem.filePath.
+	FilePath string `json:"filePath,omitempty"`
 }
 
 // StreamRequest is a request to stream a completed download from disk.
@@ -98,7 +127,11 @@ type StatusUpdate struct {
 	FileName        string `json:"fileName,omitempty"`
 	FilePath        string `json:"filePath,omitempty"`
 	StreamURL       string `json:"streamUrl,omitempty"`
+	StreamReady     bool   `json:"streamReady,omitempty"`
 	ErrorMessage    string `json:"errorMessage,omitempty"`
+	// mode=seed_file: agent computes the info_hash from the local file
+	// and reports it back so the web player can target /stream/<hash>.
+	InfoHash string `json:"infoHash,omitempty"`
 }
 
 // StatusResponse is returned by the status endpoint.
@@ -109,6 +142,7 @@ type StatusResponse struct {
 	Paused          bool `json:"paused,omitempty"`
 	DeleteFiles     bool `json:"deleteFiles,omitempty"`
 	StreamRequested bool `json:"streamRequested,omitempty"`
+	Watching        bool `json:"watching,omitempty"`
 }
 
 // BatchStatusRequest wraps multiple status updates in a single request.
@@ -118,14 +152,8 @@ type BatchStatusRequest struct {
 
 // BatchStatusResponse wraps per-task results from the batch endpoint.
 type BatchStatusResponse struct {
-	Results []StatusResponse `json:"results"`
-}
-
-// HeartbeatResponse is returned by the server on heartbeat.
-type HeartbeatResponse struct {
-	Success  bool           `json:"success"`
-	Upgrade  *UpgradeSignal `json:"upgrade,omitempty"`
-	Watching bool           `json:"watching,omitempty"` // true when a user is viewing download progress in the web UI
+	Results  []StatusResponse `json:"results"`
+	Watching bool             `json:"watching,omitempty"`
 }
 
 // UpgradeSignal tells the agent to upgrade to a specific version.
@@ -139,6 +167,17 @@ type ErrorResponse struct {
 	Details any    `json:"details,omitempty"`
 }
 
+// HTTPError represents an HTTP API error with a status code.
+// Use errors.As to extract the status code for retry decisions.
+type HTTPError struct {
+	StatusCode int
+	Message    string
+}
+
+func (e *HTTPError) Error() string {
+	return fmt.Sprintf("API error %d: %s", e.StatusCode, e.Message)
+}
+
 // AgentInfo holds metadata about the running agent for display.
 type AgentInfo struct {
 	ID          string
@@ -146,7 +185,6 @@ type AgentInfo struct {
 	User        UserInfo
 	Features    FeatureFlags
 	StartedAt   time.Time
-	LastPollAt  time.Time
 	ActiveTasks int
 }
 
@@ -268,9 +306,10 @@ type DebridAccount struct {
 
 // LibrarySyncRequest sends scanned media items to the server.
 type LibrarySyncRequest struct {
-	Items       []LibrarySyncItem `json:"items"`
-	ScanPath    string            `json:"scanPath"`
-	IsLastBatch bool              `json:"isLastBatch"`
+	Items         []LibrarySyncItem `json:"items"`
+	ScanPath      string            `json:"scanPath"`
+	IsLastBatch   bool              `json:"isLastBatch"`
+	SyncStartedAt string            `json:"syncStartedAt,omitempty"` // ISO-8601; same for all batches in a session
 }
 
 // LibrarySyncItem is a single scanned media file with ffprobe metadata.
@@ -302,3 +341,101 @@ type LibrarySyncResponse struct {
 	Matched int `json:"matched"`
 	Removed int `json:"removed"`
 }
+
+// ---------------------------------------------------------------------------
+// Sync types (unified CLI ↔ Server communication)
+// ---------------------------------------------------------------------------
+
+// SyncRequest is sent by the CLI periodically to synchronize state with the server.
+// Contains the CLI's full execution state — the server responds with pending actions.
+type SyncRequest struct {
+	AgentID         string      `json:"agentId"`
+	Version         string      `json:"version,omitempty"`
+	OS              string      `json:"os,omitempty"`
+	Arch            string      `json:"arch,omitempty"`
+	Name            string      `json:"name,omitempty"`
+	DownloadDir     string      `json:"downloadDir,omitempty"`
+	DiskFreeBytes   int64       `json:"diskFreeBytes,omitempty"`
+	DiskTotalBytes  int64       `json:"diskTotalBytes,omitempty"`
+	StreamPort      int         `json:"streamPort,omitempty"`
+	LanIP           string      `json:"lanIp,omitempty"`
+	TailscaleIP     string      `json:"tailscaleIp,omitempty"`
+	FreeSlots       int         `json:"freeSlots"`
+	Tasks           []TaskState `json:"tasks"`
+	CanDelete       bool        `json:"canDelete"`                 // library.allow_delete is enabled
+	DeleteConfirmed []int       `json:"deleteConfirmed,omitempty"` // library item IDs successfully deleted from disk
+	// Live managed-VPN split-tunnel state, sent every sync so the web sees the
+	// WireGuard slot owner update in near-realtime (vs. register, once at startup).
+	// VPNActive has no omitempty: false (tunnel down) must reach the server so it
+	// releases the slot, not be elided as "unset".
+	VPNActive bool   `json:"vpnActive"`
+	VPNMode   string `json:"vpnMode,omitempty"`
+	VPNServer string `json:"vpnServer,omitempty"`
+	// CloudFlare Quick Tunnel hostname when enabled, else empty.
+	FunnelURL string `json:"funnelUrl,omitempty"`
+}
+
+// ControlAction represents a server-side control signal for a task.
+type ControlAction struct {
+	Action      string `json:"action"` // "pause", "resume", "cancel", "stream"
+	TaskID      string `json:"taskId"`
+	DeleteFiles bool   `json:"deleteFiles,omitempty"`
+}
+
+// LibraryDeleteRequest is a server-side request to delete a file from disk.
+type LibraryDeleteRequest struct {
+	ItemID   int    `json:"itemId"`
+	FilePath string `json:"filePath"`
+}
+
+// StreamSession is a request to open an HLS streaming session for an
+// in-browser player. The CLI registers the HLS session in the StreamServer's
+// HLS registry; source bytes come from FilePath (or, when only InfoHash is
+// set, from a download_task on disk).
+type StreamSession struct {
+	SessionID  string `json:"sessionId"`
+	FilePath   string `json:"filePath,omitempty"`
+	InfoHash   string `json:"infoHash,omitempty"`
+	TaskID     string `json:"taskId,omitempty"`
+	FileName   string `json:"fileName,omitempty"`
+	FileSize   int64  `json:"fileSize,omitempty"`
+	// Quality target the daemon should aim for when transcoding. One of
+	// "2160p" | "1080p" | "720p" | "480p" | "original" | "" (defer to config).
+	Quality string `json:"quality,omitempty"`
+	// AudioIndex selects the source audio track (-map 0:a:N). -1 means
+	// "use the default/first track".
+	AudioIndex int `json:"audioIndex,omitempty"`
+}
+
+// SyncResponse is returned by the server with all pending actions for the CLI.
+type SyncResponse struct {
+	NewTasks       []Task                 `json:"newTasks,omitempty"`
+	Controls       []ControlAction        `json:"controls,omitempty"`
+	StreamRequests []StreamRequest        `json:"streamRequests,omitempty"`
+	StreamSessions []StreamSession        `json:"streamSessions,omitempty"`
+	Watching       bool                   `json:"watching"`
+	Upgrade        *UpgradeSignal         `json:"upgrade,omitempty"`
+	Scan           bool                   `json:"scan,omitempty"`
+	FilesToDelete  []LibraryDeleteRequest `json:"filesToDelete,omitempty"`
+}
+
+// ---------------------------------------------------------------------------
+// Watch progress types (used by stream tracking)
+// ---------------------------------------------------------------------------
+
+// WatchProgressUpdate reports playback position during streaming.
+// Two modes:
+//   - Estimated (range): set Progress (0-100). Position/Duration omitted.
+//   - Precise (browser): set Position + Duration in seconds. Progress computed server-side.
+type WatchProgressUpdate struct {
+	TaskID   string `json:"taskId"`
+	Source   string `json:"source"`             // "range" or "browser"
+	Progress *int   `json:"progress,omitempty"` // 0-100 (range source)
+	Position *int   `json:"position,omitempty"` // seconds (browser source)
+	Duration *int   `json:"duration,omitempty"` // seconds (browser source)
+}
+
+// WatchProgressResponse is returned after reporting watch progress.
+type WatchProgressResponse struct {
+	Success bool `json:"success"`
+}
diff --git a/internal/arr/client_test.go b/internal/arr/client_test.go
new file mode 100644
index 0000000..214dd12
--- /dev/null
+++ b/internal/arr/client_test.go
@@ -0,0 +1,396 @@
+package arr
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func newTestServer(t *testing.T, handlers map[string]any) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Check API key header
+		if r.Header.Get("X-Api-Key") != "test-key" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+
+		handler, ok := handlers[r.URL.Path]
+		if !ok {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(handler)
+	}))
+}
+
+func TestNewClient(t *testing.T) {
+	c := NewClient("http://localhost:8989/", "mykey")
+	if c.baseURL != "http://localhost:8989" {
+		t.Errorf("baseURL = %q, want trailing slash trimmed", c.baseURL)
+	}
+	if c.apiKey != "mykey" {
+		t.Errorf("apiKey = %q, want mykey", c.apiKey)
+	}
+}
+
+func TestSystemStatus(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v3/system/status": SystemStatus{AppName: "Radarr", Version: "4.0.0"},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	status, err := c.SystemStatus()
+	if err != nil {
+		t.Fatalf("SystemStatus: %v", err)
+	}
+	if status.AppName != "Radarr" {
+		t.Errorf("AppName = %q, want Radarr", status.AppName)
+	}
+	if status.Version != "4.0.0" {
+		t.Errorf("Version = %q, want 4.0.0", status.Version)
+	}
+}
+
+func TestSystemStatusFallbackV1(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Api-Key") != "test-key" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		switch r.URL.Path {
+		case "/api/v3/system/status":
+			w.WriteHeader(http.StatusNotFound)
+		case "/api/v1/system/status":
+			json.NewEncoder(w).Encode(SystemStatus{AppName: "Prowlarr", Version: "1.0.0"})
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	status, err := c.SystemStatus()
+	if err != nil {
+		t.Fatalf("SystemStatus v1 fallback: %v", err)
+	}
+	if status.AppName != "Prowlarr" {
+		t.Errorf("AppName = %q, want Prowlarr", status.AppName)
+	}
+}
+
+func TestMovies(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v3/movie": []Movie{
+			{ID: 1, Title: "Inception", Year: 2010, TmdbID: 27205, Monitored: true},
+			{ID: 2, Title: "Tenet", Year: 2020, TmdbID: 577922, HasFile: true},
+		},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	movies, err := c.Movies()
+	if err != nil {
+		t.Fatalf("Movies: %v", err)
+	}
+	if len(movies) != 2 {
+		t.Fatalf("expected 2 movies, got %d", len(movies))
+	}
+	if movies[0].Title != "Inception" {
+		t.Errorf("movies[0].Title = %q, want Inception", movies[0].Title)
+	}
+}
+
+func TestSeries(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v3/series": []Series{
+			{ID: 1, Title: "Breaking Bad", Year: 2008, TvdbID: 81189},
+		},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	series, err := c.Series()
+	if err != nil {
+		t.Fatalf("Series: %v", err)
+	}
+	if len(series) != 1 {
+		t.Fatalf("expected 1 series, got %d", len(series))
+	}
+	if series[0].Title != "Breaking Bad" {
+		t.Errorf("series[0].Title = %q, want Breaking Bad", series[0].Title)
+	}
+}
+
+func TestQualityProfiles(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v3/qualityprofile": []QualityProfile{
+			{ID: 1, Name: "HD-1080p"},
+			{ID: 2, Name: "Ultra-HD"},
+		},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	profiles, err := c.QualityProfiles()
+	if err != nil {
+		t.Fatalf("QualityProfiles: %v", err)
+	}
+	if len(profiles) != 2 {
+		t.Fatalf("expected 2 profiles, got %d", len(profiles))
+	}
+}
+
+func TestRootFolders(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v3/rootfolder": []RootFolder{
+			{ID: 1, Path: "/movies", FreeSpace: 500000000000},
+		},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	folders, err := c.RootFolders()
+	if err != nil {
+		t.Fatalf("RootFolders: %v", err)
+	}
+	if len(folders) != 1 {
+		t.Fatalf("expected 1 folder, got %d", len(folders))
+	}
+	if folders[0].Path != "/movies" {
+		t.Errorf("path = %q, want /movies", folders[0].Path)
+	}
+}
+
+func TestDownloadClients(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v3/downloadclient": []DownloadClient{
+			{ID: 1, Name: "Transmission", Enable: true, Protocol: "torrent"},
+		},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	clients, err := c.DownloadClients()
+	if err != nil {
+		t.Fatalf("DownloadClients: %v", err)
+	}
+	if len(clients) != 1 || clients[0].Name != "Transmission" {
+		t.Errorf("unexpected clients: %+v", clients)
+	}
+}
+
+func TestDownloadClientDetails(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Api-Key") != "test-key" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		if r.URL.Path == "/api/v3/downloadclient/5" {
+			json.NewEncoder(w).Encode(struct {
+				Fields []Field `json:"fields"`
+			}{
+				Fields: []Field{
+					{Name: "host", Value: "localhost"},
+					{Name: "port", Value: 9091},
+				},
+			})
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	fields, err := c.DownloadClientDetails(5)
+	if err != nil {
+		t.Fatalf("DownloadClientDetails: %v", err)
+	}
+	if len(fields) != 2 {
+		t.Fatalf("expected 2 fields, got %d", len(fields))
+	}
+	if fields[0].Name != "host" {
+		t.Errorf("fields[0].Name = %q, want host", fields[0].Name)
+	}
+}
+
+func TestTags(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v3/tag": []Tag{
+			{ID: 1, Label: "unarr"},
+			{ID: 2, Label: "imported"},
+		},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	tags, err := c.Tags()
+	if err != nil {
+		t.Fatalf("Tags: %v", err)
+	}
+	if len(tags) != 2 {
+		t.Fatalf("expected 2 tags, got %d", len(tags))
+	}
+}
+
+func TestHistory(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Api-Key") != "test-key" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		if r.URL.Path == "/api/v3/history" {
+			json.NewEncoder(w).Encode(HistoryResponse{
+				Records: []HistoryRecord{
+					{ID: 1, EventType: "grabbed", SourceTitle: "Inception.2010.1080p"},
+				},
+				TotalRecords: 1,
+			})
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	records, err := c.History(10)
+	if err != nil {
+		t.Fatalf("History: %v", err)
+	}
+	if len(records) != 1 {
+		t.Fatalf("expected 1 record, got %d", len(records))
+	}
+	if records[0].SourceTitle != "Inception.2010.1080p" {
+		t.Errorf("sourceTitle = %q", records[0].SourceTitle)
+	}
+}
+
+func TestHistoryDefaultPageSize(t *testing.T) {
+	var requestedPath string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Api-Key") != "test-key" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		requestedPath = r.URL.String()
+		json.NewEncoder(w).Encode(HistoryResponse{})
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	c.History(0) // should default to 250
+
+	if requestedPath == "" {
+		t.Fatal("no request made")
+	}
+	if !contains(requestedPath, "pageSize=250") {
+		t.Errorf("expected pageSize=250, got path: %s", requestedPath)
+	}
+}
+
+func TestBlocklist(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Api-Key") != "test-key" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		if r.URL.Path == "/api/v3/blocklist" {
+			json.NewEncoder(w).Encode(BlocklistResponse{
+				Records: []BlocklistItem{
+					{ID: 1, SourceTitle: "Bad.Release", Data: BlocklistData{InfoHash: "abc123"}},
+				},
+			})
+			return
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	items, err := c.Blocklist(50)
+	if err != nil {
+		t.Fatalf("Blocklist: %v", err)
+	}
+	if len(items) != 1 || items[0].Data.InfoHash != "abc123" {
+		t.Errorf("unexpected blocklist: %+v", items)
+	}
+}
+
+func TestIndexers(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v1/indexer": []Indexer{
+			{ID: 1, Name: "NZBGeek", Enable: true},
+			{ID: 2, Name: "Torznab", Enable: false},
+		},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	indexers, err := c.Indexers()
+	if err != nil {
+		t.Fatalf("Indexers: %v", err)
+	}
+	if len(indexers) != 2 {
+		t.Fatalf("expected 2 indexers, got %d", len(indexers))
+	}
+}
+
+func TestApplications(t *testing.T) {
+	srv := newTestServer(t, map[string]any{
+		"/api/v1/applications": []Application{
+			{ID: 1, Name: "Radarr"},
+		},
+	})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	apps, err := c.Applications()
+	if err != nil {
+		t.Fatalf("Applications: %v", err)
+	}
+	if len(apps) != 1 || apps[0].Name != "Radarr" {
+		t.Errorf("unexpected apps: %+v", apps)
+	}
+}
+
+func TestUnauthorized(t *testing.T) {
+	srv := newTestServer(t, map[string]any{})
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "wrong-key")
+	_, err := c.SystemStatus()
+	if err == nil {
+		t.Error("expected error for unauthorized request")
+	}
+}
+
+func TestHTTPError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		w.Write([]byte("internal error"))
+	}))
+	defer srv.Close()
+
+	c := NewClient(srv.URL, "test-key")
+	_, err := c.Movies()
+	if err == nil {
+		t.Error("expected error for 500 response")
+	}
+}
+
+func contains(s, substr string) bool {
+	return len(s) >= len(substr) && searchStr(s, substr)
+}
+
+func searchStr(s, sub string) bool {
+	for i := 0; i <= len(s)-len(sub); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/arr/discovery_test.go b/internal/arr/discovery_test.go
index 499877c..6dc78b8 100644
--- a/internal/arr/discovery_test.go
+++ b/internal/arr/discovery_test.go
@@ -1,6 +1,9 @@
 package arr
 
 import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
 	"strings"
 	"testing"
 )
@@ -82,3 +85,158 @@ func TestDetectApp(t *testing.T) {
 		})
 	}
 }
+
+func TestConfigDirs(t *testing.T) {
+	dirs := configDirs()
+	if len(dirs) == 0 {
+		t.Error("configDirs() returned empty")
+	}
+}
+
+func TestParseConfigXMLEmpty(t *testing.T) {
+	port, apiKey, urlBase := parseConfigXML(strings.NewReader(""))
+	if port != "" || apiKey != "" || urlBase != "" {
+		t.Error("empty input should return empty values")
+	}
+}
+
+func TestParseConfigXMLNoPort(t *testing.T) {
+	xml := `<Config><ApiKey>key123</ApiKey></Config>`
+	port, apiKey, _ := parseConfigXML(strings.NewReader(xml))
+	if port != "" {
+		t.Errorf("port = %q, want empty", port)
+	}
+	if apiKey != "key123" {
+		t.Errorf("apiKey = %q, want key123", apiKey)
+	}
+}
+
+func TestExtractHostPortMultipleMappings(t *testing.T) {
+	tests := []struct {
+		name      string
+		ports     string
+		container string
+		want      string
+	}{
+		{"ipv6 only", ":::8989->8989/tcp", "8989", "8989"},
+		{"different host port", "0.0.0.0:9999->8989/tcp", "8989", "9999"},
+		{"port in string but no mapping", "something 8989 somewhere", "8989", "8989"},
+		{"no match at all", "0.0.0.0:3000->3000/tcp", "9999", ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractHostPort(tt.ports, tt.container)
+			if got != tt.want {
+				t.Errorf("extractHostPort(%q, %q) = %q, want %q", tt.ports, tt.container, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestDiscoverFromProwlarr(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/applications":
+			json.NewEncoder(w).Encode([]Application{
+				{
+					ID:   1,
+					Name: "Radarr",
+					Fields: []Field{
+						{Name: "baseUrl", Value: "http://localhost:7878"},
+						{Name: "apiKey", Value: "radarr-key-123"},
+					},
+				},
+				{
+					ID:   2,
+					Name: "Sonarr",
+					Fields: []Field{
+						{Name: "baseUrl", Value: "http://localhost:8989"},
+						{Name: "apiKey", Value: "sonarr-key-456"},
+					},
+				},
+				{
+					ID:   3,
+					Name: "Unknown App",
+					Fields: []Field{
+						{Name: "baseUrl", Value: "http://localhost:9000"},
+						{Name: "apiKey", Value: "unknown-key"},
+					},
+				},
+				{
+					ID:   4,
+					Name: "Incomplete",
+					Fields: []Field{
+						{Name: "baseUrl", Value: "http://localhost:5000"},
+						// no apiKey → should be skipped
+					},
+				},
+			})
+		case "/api/v3/system/status":
+			json.NewEncoder(w).Encode(SystemStatus{AppName: "Radarr", Version: "4.0.0"})
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	// DiscoverFromProwlarr will try to verify each instance, which will fail
+	// for localhost URLs (not our test server), but that's OK — we test the parsing
+	instances := DiscoverFromProwlarr(srv.URL, "prowlarr-key")
+
+	// Should find Radarr and Sonarr (Unknown and Incomplete skipped)
+	if len(instances) != 2 {
+		t.Fatalf("expected 2 instances, got %d: %+v", len(instances), instances)
+	}
+
+	found := map[string]bool{}
+	for _, inst := range instances {
+		found[inst.App] = true
+		if inst.Source != "prowlarr" {
+			t.Errorf("source = %q, want prowlarr", inst.Source)
+		}
+	}
+	if !found["radarr"] {
+		t.Error("expected radarr instance")
+	}
+	if !found["sonarr"] {
+		t.Error("expected sonarr instance")
+	}
+}
+
+func TestVerify(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("X-Api-Key") != "valid-key" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		json.NewEncoder(w).Encode(SystemStatus{AppName: "Radarr", Version: "5.0.0"})
+	}))
+	defer srv.Close()
+
+	t.Run("valid", func(t *testing.T) {
+		inst := &Instance{App: "radarr", URL: srv.URL, APIKey: "valid-key"}
+		err := Verify(inst)
+		if err != nil {
+			t.Fatalf("Verify: %v", err)
+		}
+		if inst.Version != "5.0.0" {
+			t.Errorf("version = %q, want 5.0.0", inst.Version)
+		}
+	})
+
+	t.Run("no api key", func(t *testing.T) {
+		inst := &Instance{App: "radarr", URL: srv.URL}
+		err := Verify(inst)
+		if err == nil {
+			t.Error("expected error for no API key")
+		}
+	})
+
+	t.Run("invalid key", func(t *testing.T) {
+		inst := &Instance{App: "radarr", URL: srv.URL, APIKey: "wrong-key"}
+		err := Verify(inst)
+		if err == nil {
+			t.Error("expected error for invalid API key")
+		}
+	})
+}
diff --git a/internal/cmd/agent_client.go b/internal/cmd/agent_client.go
new file mode 100644
index 0000000..a903096
--- /dev/null
+++ b/internal/cmd/agent_client.go
@@ -0,0 +1,23 @@
+package cmd
+
+import (
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+// newAgentClientFromConfig builds an agent.Client wired with the mirror pool
+// from the user's TOML config. Use this instead of agent.NewClient in any
+// long-running command (daemon, status loop, etc.) so a `.com` outage rolls
+// over to `.to` / .onion without restarting the agent.
+//
+// The function lives in cmd/ rather than agent/ because it has to know
+// about the config struct, and cmd/ is the only place that owns the
+// "wire defaults + user overrides" rule.
+func newAgentClientFromConfig(cfg config.Config, userAgent string) *agent.Client {
+	return agent.NewClientWithMirrors(
+		cfg.Auth.APIURL,
+		cfg.Auth.Mirrors,
+		cfg.Auth.APIKey,
+		userAgent,
+	)
+}
diff --git a/internal/cmd/config_menu.go b/internal/cmd/config_menu.go
index 07297f7..334d815 100644
--- a/internal/cmd/config_menu.go
+++ b/internal/cmd/config_menu.go
@@ -14,7 +14,7 @@ import (
 	"github.com/torrentclaw/unarr/internal/config"
 )
 
-var configCategories = []string{"downloads", "organization", "notifications", "device", "region", "connection", "advanced"}
+var configCategories = []string{"downloads", "organization", "library", "notifications", "device", "region", "connection", "advanced"}
 
 func newConfigCmd() *cobra.Command {
 	cmd := &cobra.Command{
@@ -25,6 +25,7 @@ func newConfigCmd() *cobra.Command {
 Categories:
   downloads        Download directory, method, speed limits, concurrency
   organization     Auto-sort into Movies / TV Shows folders
+  library          Library scan settings and file deletion permissions
   notifications    Desktop notifications
   device           Agent name
   region           Country and language
@@ -95,6 +96,7 @@ func runConfigMenu(category string) error {
 					Options(
 						huh.NewOption("Downloads        — directory, method, speed limits", "downloads"),
 						huh.NewOption("Organization     — auto-sort Movies & TV Shows", "organization"),
+						huh.NewOption("Library          — scan settings & file deletion", "library"),
 						huh.NewOption("Notifications    — desktop notifications", "notifications"),
 						huh.NewOption("Device           — agent name", "device"),
 						huh.NewOption("Region           — country & language", "region"),
@@ -131,6 +133,8 @@ func runCategory(cfg *config.Config, category string) error {
 		return configDownloads(cfg)
 	case "organization":
 		return configOrganization(cfg)
+	case "library":
+		return configLibrary(cfg)
 	case "notifications":
 		return configNotifications(cfg)
 	case "device":
@@ -311,23 +315,23 @@ func configConnection(cfg *config.Config) error {
 	).Run()
 }
 
-func configAdvanced(cfg *config.Config) error {
+func configLibrary(cfg *config.Config) error {
 	return huh.NewForm(
 		huh.NewGroup(
-			huh.NewInput().
-				Title("Poll interval").
-				Description("How often to check for new tasks (e.g. 30s, 1m)").
-				Value(&cfg.Daemon.PollInterval).
-				Validate(validateDuration),
-			huh.NewInput().
-				Title("Heartbeat interval").
-				Description("How often to send heartbeat to server (e.g. 30s, 1m)").
-				Value(&cfg.Daemon.HeartbeatInterval).
-				Validate(validateDuration),
+			huh.NewConfirm().
+				Title("Allow file deletion from web UI?").
+				Description("When enabled, the web library's Delete button can permanently remove files from disk.\nOnly activate this if you understand that deleted files cannot be recovered.").
+				Value(&cfg.Library.AllowDelete),
 		),
 	).Run()
 }
 
+func configAdvanced(_ *config.Config) error {
+	// Sync intervals are adaptive (3s watching, 60s idle) — no user-facing config needed.
+	fmt.Println("No advanced settings to configure. Sync intervals are automatic.")
+	return nil
+}
+
 // ── Validators ──────────────────────────────────────────────────────
 
 func validateSpeed(s string) error {
diff --git a/internal/cmd/config_menu_test.go b/internal/cmd/config_menu_test.go
new file mode 100644
index 0000000..a63389b
--- /dev/null
+++ b/internal/cmd/config_menu_test.go
@@ -0,0 +1,55 @@
+package cmd
+
+import "testing"
+
+func TestValidateSpeed(t *testing.T) {
+	tests := []struct {
+		input   string
+		wantErr bool
+	}{
+		{"", false},
+		{"0", false},
+		{" ", false},
+		{"10MB", false},
+		{"500KB", false},
+		{"1GB", false},
+		{"abc", true},
+		{"10XB", true},
+		{"-5MB", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			err := validateSpeed(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("validateSpeed(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestValidateDuration(t *testing.T) {
+	tests := []struct {
+		input   string
+		wantErr bool
+	}{
+		{"", false},
+		{"30s", false},
+		{"1m", false},
+		{"5m", false},
+		{"1h", false},
+		{"2h30m", false},
+		{"abc", true},
+		{"30", true},
+		{"5x", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			err := validateDuration(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("validateDuration(%q) error = %v, wantErr %v", tt.input, err, tt.wantErr)
+			}
+		})
+	}
+}
diff --git a/internal/cmd/daemon.go b/internal/cmd/daemon.go
index d83e5c0..2e0c074 100644
--- a/internal/cmd/daemon.go
+++ b/internal/cmd/daemon.go
@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log"
 	"os"
@@ -16,8 +17,11 @@ import (
 	"github.com/torrentclaw/unarr/internal/agent"
 	"github.com/torrentclaw/unarr/internal/config"
 	"github.com/torrentclaw/unarr/internal/engine"
+	"github.com/torrentclaw/unarr/internal/funnel"
 	"github.com/torrentclaw/unarr/internal/library"
+	"github.com/torrentclaw/unarr/internal/library/mediainfo"
 	"github.com/torrentclaw/unarr/internal/usenet/download"
+	"github.com/torrentclaw/unarr/internal/vpn"
 )
 
 // newStartCmd creates the top-level `unarr start` command.
@@ -27,13 +31,13 @@ func newStartCmd() *cobra.Command {
 		Short: "Start the download daemon (foreground)",
 		Long: `Start the unarr daemon in the foreground.
 
-Registers with the server, receives download tasks via WebSocket (with
-HTTP fallback), and executes them using the configured download method.
+Registers with the server, receives download tasks via periodic sync,
+and executes them using the configured download method.
 Supports torrent, debrid, and usenet downloads concurrently.
 
-The daemon sends periodic heartbeats and reports download progress back
-to the web dashboard. Press Ctrl+C to stop gracefully — active downloads
-get up to 30 seconds to finish.
+The daemon syncs state with the server every 3s when someone is viewing
+the web dashboard, or every 60s when idle. Press Ctrl+C to stop
+gracefully — active downloads get up to 30 seconds to finish.
 
 Requires: API key, agent ID, and download directory (run 'unarr init' first).
 
@@ -46,27 +50,20 @@ To run as a background service, use 'unarr daemon install' instead.`,
 	}
 }
 
-// newStopCmd creates the top-level `unarr stop` placeholder.
+// newStopCmd creates the top-level `unarr stop` command.
 func newStopCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "stop",
 		Short: "Stop the running daemon",
-		Long: `Stop the unarr daemon.
+		Long: `Stop the unarr daemon gracefully.
 
-If running in the foreground, press Ctrl+C in the terminal where it was started.
-If installed as a system service, use your OS service manager:
+Reads the daemon PID from the state file and sends a graceful stop signal.
+Works regardless of whether the daemon was started in the foreground or as a service.
 
-  Linux (systemd):   systemctl --user stop unarr
-  macOS (launchd):   launchctl unload ~/Library/LaunchAgents/com.torrentclaw.unarr.plist`,
+To stop a service-managed daemon and prevent auto-restart, use 'unarr daemon stop' instead.`,
 		Example: `  unarr stop`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			fmt.Println("  Use Ctrl+C in the terminal where the daemon is running.")
-			fmt.Println()
-			fmt.Println("  If installed as a service:")
-			fmt.Println("    Linux:  systemctl --user stop unarr")
-			fmt.Println("    macOS:  launchctl unload ~/Library/LaunchAgents/com.torrentclaw.unarr.plist")
-			fmt.Println()
-			return nil
+			return stopDaemonByPID()
 		},
 	}
 }
@@ -76,17 +73,30 @@ func newDaemonCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "daemon <command>",
 		Short: "Manage the daemon as a system service",
-		Long: `Install or remove unarr as a system service that starts automatically on boot.
+		Long: `Install, control and inspect the unarr daemon as a system service.
 
-  Linux:  Creates a systemd user service (~/.config/systemd/user/unarr.service)
-  macOS:  Creates a launchd agent (~/Library/LaunchAgents/com.torrentclaw.unarr.plist)`,
+  Linux:   systemd user service (~/.config/systemd/user/unarr.service)
+  macOS:   launchd agent (~/Library/LaunchAgents/com.torrentclaw.unarr.plist)
+  Windows: Task Scheduler task (runs at logon)`,
 		Example: `  unarr daemon install
+  unarr daemon start
+  unarr daemon status
+  unarr daemon logs -f
+  unarr daemon reload
+  unarr daemon restart
+  unarr daemon stop
   unarr daemon uninstall`,
 	}
 
 	cmd.AddCommand(
 		newDaemonInstallCmdReal(),
 		newDaemonUninstallCmdReal(),
+		newDaemonStartCmd(),
+		newDaemonStopCmd(),
+		newDaemonRestartCmd(),
+		newDaemonSvcStatusCmd(),
+		newDaemonLogsCmd(),
+		newDaemonReloadCmd(),
 	)
 
 	return cmd
@@ -127,71 +137,143 @@ func runDaemonStart() error {
 	bold.Println("  unarr Daemon")
 	fmt.Println()
 
-	// Parse intervals
-	pollInterval, _ := time.ParseDuration(cfg.Daemon.PollInterval)
-	if pollInterval == 0 {
-		pollInterval = 30 * time.Second
-	}
-	heartbeatInterval, _ := time.ParseDuration(cfg.Daemon.HeartbeatInterval)
-	if heartbeatInterval == 0 {
-		heartbeatInterval = 30 * time.Second
-	}
-
 	userAgent := "unarr/" + Version
 
+	// Probe HW accel + derive a sensible transcode resolution cap. The cap
+	// is what the web side uses to decide whether the user should pre-empt
+	// transcoding by downloading a smaller version (4K source on a software
+	// libx264-only host is the canonical case where pre-download wins).
+	//
+	// Use the full diagnostic (encoders + devices + ffmpeg version) instead
+	// of just the picked backend — the extra fields ride along in the
+	// register payload so the web "Diagnose transcoder" modal can show *why*
+	// libx264 was selected on a host with a GPU (e.g. brew's ffmpeg without
+	// --enable-nvenc). 10 s ceiling so a hung ffmpeg binary can't stall
+	// startup forever.
+	ffmpegResolved, _ := mediainfo.ResolveFFmpeg(cfg.Library.FFmpegPath)
+	probeCtx, probeCancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer probeCancel() // guard against a panic inside DetectHWAccelDiagnostic
+	hwDiag := engine.DetectHWAccelDiagnostic(probeCtx, ffmpegResolved)
+	log.Println(hwDiag.LogLine())
+	hwAccelPick := hwDiag.Pick
+	maxTranscodeHeight := 1080
+	if hwAccelPick != engine.HWAccelNone {
+		maxTranscodeHeight = 2160
+	}
+
 	// Create daemon config
 	daemonCfg := agent.DaemonConfig{
-		AgentID:           cfg.Agent.ID,
-		AgentName:         cfg.Agent.Name,
-		Version:           Version,
-		DownloadDir:       cfg.Download.Dir,
-		PollInterval:      pollInterval,
-		HeartbeatInterval: heartbeatInterval,
+		AgentID:            cfg.Agent.ID,
+		AgentName:          cfg.Agent.Name,
+		Version:            Version,
+		DownloadDir:        cfg.Download.Dir,
+		StreamPort:         cfg.Download.StreamPort,
+		LanIP:              engine.LanIP(),
+		TailscaleIP:        engine.TailscaleIP(),
+		CanDelete:          cfg.Library.AllowDelete,
+		ScanPaths:          library.ResolveScanPaths(cfg.Download.Dir, cfg.Organize.MoviesDir, cfg.Organize.TVShowsDir, cfg.Library.ScanPath),
+		HWAccel:            string(hwAccelPick),
+		MaxTranscodeHeight: maxTranscodeHeight,
+		FFmpegVersion:      hwDiag.FFmpegVersion,
+		FFmpegPath:         hwDiag.FFmpegPath,
+		HWEncoders:         hwDiag.Encoders,
+		HWDevices:          hwDiag.Devices,
+		AutoUpgrade:        cfg.Daemon.AutoUpgradeEnabled(),
 	}
 
-	// Create transport: Hybrid (WS + HTTP fallback) or HTTP-only
-	httpT := agent.NewHTTPTransport(cfg.Auth.APIURL, cfg.Auth.APIKey, userAgent)
+	// Create HTTP client with mirror failover so a `.com` block-out rolls
+	// over to `.to` / .onion without restarting the daemon.
+	agentClient := newAgentClientFromConfig(cfg, userAgent)
+	log.Printf("Transport: HTTP sync → %s (mirrors: %d)", cfg.Auth.APIURL, len(cfg.Auth.Mirrors))
 
-	wsURL := cfg.Auth.WSURL
-	if wsURL == "" {
-		wsURL = deriveWSURL(cfg.Auth.APIURL, cfg.Agent.ID)
-	}
+	// Create daemon
+	d := agent.NewDaemon(daemonCfg, agentClient)
 
-	var transport agent.Transport
-	if wsURL != "" {
-		wsT := agent.NewWSTransport(wsURL, cfg.Auth.APIKey, cfg.Agent.ID, userAgent)
-		transport = agent.NewHybridTransport(wsT, httpT)
-		log.Printf("Transport: WebSocket (fallback: HTTP) → %s", wsURL)
-	} else {
-		transport = httpT
-		log.Println("Transport: HTTP only")
-	}
+	// Start SIGUSR1 reload watcher (unix only, no-op on Windows)
+	startReloadWatcher(&ReloadableConfig{Daemon: d})
 
-	// Create daemon — always uses Transport interface
-	d := agent.NewDaemon(daemonCfg, transport)
-
-	// Create progress reporter using transport
-	reporter := engine.NewProgressReporterWithTransport(transport, 3*time.Second)
-	reporter.SetWatchingFunc(func() bool { return d.Watching })
+	// Daemon-scoped context — cancelled on shutdown
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
 
 	// Parse speed limits
 	maxDl, _ := config.ParseSpeed(cfg.Download.MaxDownloadSpeed)
 	maxUl, _ := config.ParseSpeed(cfg.Download.MaxUploadSpeed)
 
-	// Parse torrent timeouts from config (default: 0 = unlimited, like qBittorrent)
+	// Parse torrent timeouts
 	metaTimeout, _ := time.ParseDuration(cfg.Download.MetadataTimeout)
 	stallTimeout, _ := time.ParseDuration(cfg.Download.StallTimeout)
 
+	// Create progress reporter — only used for stream tasks (handleStreamTask)
+	// The sync goroutine handles all regular progress reporting.
+	statusInterval, _ := time.ParseDuration(cfg.Daemon.StatusInterval)
+	if statusInterval == 0 {
+		statusInterval = 3 * time.Second
+	}
+	reporter := engine.NewProgressReporter(agentClient, statusInterval)
+	reporter.SetWatchingFunc(func() bool { return d.Watching.Load() })
+
+	// Managed-VPN add-on: bring up the in-process WireGuard split-tunnel before
+	// the torrent client so peer + tracker traffic routes through it. Failure is
+	// non-fatal — log and download in the clear (better than refusing to run).
+	var vpnTunnel *vpn.Tunnel
+	if cfg.Download.VPN.ConfigFile != "" {
+		// Self-hosted / personal-VPN mode: read a local .conf directly.
+		raw, rerr := os.ReadFile(cfg.Download.VPN.ConfigFile)
+		if rerr != nil {
+			log.Printf("[vpn] could not read config_file %q (%v) — downloading in the clear", cfg.Download.VPN.ConfigFile, rerr)
+		} else if t, uerr := vpn.Up(string(raw)); uerr != nil {
+			log.Printf("[vpn] tunnel failed to start from config_file (%v) — downloading in the clear", uerr)
+		} else {
+			vpnTunnel = t
+			defer vpnTunnel.Close()
+			log.Printf("[vpn] managed VPN active (local config_file) — torrent traffic split-tunnelled through WireGuard")
+		}
+	} else if cfg.Download.VPN.Enabled {
+		apiURL := cfg.Auth.APIURL
+		if apiURL == "" {
+			apiURL = "https://torrentclaw.com"
+		}
+		fetchCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
+		conf, ferr := vpn.FetchConfig(fetchCtx, apiURL, cfg.Auth.APIKey, "unarr/"+Version, cfg.Agent.ID, false)
+		cancel()
+		var fe *vpn.FetchError
+		switch {
+		case ferr != nil && errors.As(ferr, &fe) && fe.Code == vpn.ErrSlotOnDevice:
+			log.Printf("[vpn] the single WireGuard slot is already held by another unarr agent — this one downloads in the clear. To protect this machine too, set up OpenVPN on it (1 agent uses WireGuard, the rest use OpenVPN — up to 10). See https://torrentclaw.com/vpn")
+		case ferr != nil:
+			log.Printf("[vpn] could not enable VPN (%v) — downloading in the clear", ferr)
+		default:
+			if t, uerr := vpn.Up(conf); uerr != nil {
+				log.Printf("[vpn] tunnel failed to start (%v) — downloading in the clear", uerr)
+			} else {
+				vpnTunnel = t
+				defer vpnTunnel.Close()
+				log.Printf("[vpn] managed VPN active — torrent traffic split-tunnelled through WireGuard")
+			}
+		}
+	}
+
+	// Record VPN split-tunnel state for `unarr vpn status`.
+	if vpnTunnel != nil {
+		mode := "managed"
+		if cfg.Download.VPN.ConfigFile != "" {
+			mode = "self-hosted"
+		}
+		d.SetVPNState(true, mode, vpnTunnel.Endpoint)
+	}
+
 	// Create torrent downloader
 	torrentDl, err := engine.NewTorrentDownloader(engine.TorrentConfig{
 		DataDir:         cfg.Download.Dir,
-		MetadataTimeout: metaTimeout,  // 0 = unlimited (default)
-		StallTimeout:    stallTimeout, // 0 = unlimited (default)
-		MaxTimeout:      0,            // unlimited
+		MetadataTimeout: metaTimeout,
+		StallTimeout:    stallTimeout,
+		MaxTimeout:      0,
 		MaxDownloadRate: maxDl,
 		MaxUploadRate:   maxUl,
-		ListenPort:      cfg.Download.ListenPort, // 0 = default 42069
+		ListenPort:      cfg.Download.ListenPort,
 		SeedEnabled:     false,
+		VPNTunnel:       vpnTunnel,
 	})
 	if err != nil {
 		return fmt.Errorf("create torrent downloader: %w", err)
@@ -208,7 +290,7 @@ func runDaemonStart() error {
 		log.Printf("Speed limits: download=%s upload=%s", dlStr, ulStr)
 	}
 
-	// Create debrid downloader (HTTPS-based, no provider interaction needed)
+	// Create debrid downloader
 	debridDl := engine.NewDebridDownloader()
 
 	// Create download manager
@@ -220,154 +302,325 @@ func runDaemonStart() error {
 			Enabled:    cfg.Organize.Enabled,
 			MoviesDir:  cfg.Organize.MoviesDir,
 			TVShowsDir: cfg.Organize.TVShowsDir,
+			OutputDir:  cfg.Download.Dir,
 		},
-	}, reporter, torrentDl, debridDl, engine.NewUsenetDownloader(httpT.Client()))
+	}, reporter, torrentDl, debridDl, engine.NewUsenetDownloader(agentClient))
 
-	// Wire state tracking
-	d.GetActiveCount = manager.ActiveCount
-	d.GetCleanableBytes = CleanableBytes
+	// Create persistent stream server
+	streamSrv := engine.NewStreamServer(cfg.Download.StreamPort)
+	streamSrv.SetUPnPEnabled(cfg.Download.EnableUPnP)
+	// 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
+	// `Access-Control-Allow-Origin` → browser drops the response → player
+	// reports "404 todos los canales". Fetching /api/mirrors at startup
+	// future-proofs against mirror additions without a CLI rebuild.
+	corsExtras := append([]string(nil), cfg.Download.CORSExtraOrigins...)
+	corsExtras = append(corsExtras, mirrorCORSOrigins(ctx, cfg, userAgent)...)
+	streamSrv.SetCORSAllowedOrigins(corsExtras)
+	// Reap HLS tmpdirs left over from a previous daemon run before we start
+	// accepting new sessions. The in-memory registry doesn't survive a
+	// restart, so without this disk usage grows unbounded across restarts.
+	if err := engine.CleanupHLSOrphanDirs(); err != nil {
+		log.Printf("[hls] orphan tmpdir cleanup: %v", err)
+	}
 
-	// Wire: server-side signals -> manager actions + stream tasks
-	reporter.SetCancelHandler(func(taskID string) {
-		manager.CancelTask(taskID)
-		cancelStreamTask(taskID)
-	})
-	reporter.SetPauseHandler(func(taskID string) {
-		manager.PauseTask(taskID)
-		cancelStreamTask(taskID)
-	})
-	reporter.SetDeleteFilesHandler(func(taskID string) {
-		manager.CancelAndDeleteFiles(taskID)
-		cancelStreamTask(taskID)
-	})
-
-	// Wire: stream requested on active download → start HTTP server
-	reporter.SetStreamRequestedHandler(func(taskID string) {
-		task := manager.GetTask(taskID)
-		if task == nil {
-			log.Printf("[%s] stream requested but task not found in manager", taskID[:8])
-			return
+	// Persistent HLS segment cache — survives across sessions so re-plays
+	// of the same file at the same quality skip ffmpeg entirely. Off when
+	// hls_cache.enabled = false; size cap from hls_cache.size_gb; path from
+	// hls_cache.dir (defaults to ~/.cache/unarr/hls-cache).
+	var hlsCache *engine.HLSCache
+	if cfg.Download.HLSCache.Enabled {
+		cacheDir := cfg.Download.HLSCache.Dir
+		if cacheDir == "" {
+			if base, err := os.UserCacheDir(); err == nil {
+				cacheDir = filepath.Join(base, "unarr", "hls-cache")
+			} else {
+				cacheDir = filepath.Join(os.TempDir(), "unarr-hls-cache")
+			}
 		}
-		if task.GetStreamURL() != "" {
-			return // already streaming
-		}
-		srv, err := torrentDl.StartStream(taskID)
+		c, err := engine.NewHLSCache(cacheDir, cfg.Download.HLSCache.SizeGB)
 		if err != nil {
-			log.Printf("[%s] stream failed: %v", taskID[:8], err)
-			return
+			log.Printf("[hls_cache] init failed (%v) — falling back to per-session tmpdirs", err)
+		} else {
+			hlsCache = c
+			hlsCache.StartSweeper(ctx, time.Hour)
+			log.Printf("[hls_cache] enabled: dir=%s budget=%dGB", cacheDir, cfg.Download.HLSCache.SizeGB)
 		}
-		// Register server before setting URL to avoid TOCTOU race
-		streamRegistry.mu.Lock()
-		streamRegistry.servers[taskID] = srv
-		streamRegistry.mu.Unlock()
-		task.SetStreamURL(srv.URL())
-	})
+	} else {
+		log.Printf("[hls_cache] disabled by config — every play re-encodes from scratch")
+	}
+	if err := streamSrv.Listen(ctx); err != nil {
+		return fmt.Errorf("start stream server: %w", err)
+	}
+	d.UpdateStreamPort(streamSrv.Port())
 
-	// Wire: daemon claimed tasks -> manager
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
+	// CloudFlare Quick Tunnel — needs the ACTUAL listening port (the
+	// configured port may have been busy and bumped). Spawning here ensures
+	// cloudflared --url points at the right socket. Failures degrade to
+	// Tailscale/LAN only; the supervisor keeps the tunnel up across CF's
+	// periodic rotation + transient cloudflared crashes.
+	if cfg.Download.Funnel.Enabled {
+		go superviseFunnel(ctx, d, streamSrv.Port())
+	}
 
+	// Warn at startup if transcode is enabled but ffmpeg/ffprobe are missing.
+	// HLS sessions get rejected at runtime (see daemon.go ~line 455), but
+	// surfacing it here gives the operator a chance to install ffmpeg before
+	// a user hits a confusing "rejected" line in the logs.
+	if cfg.Download.Transcode.Enabled {
+		if _, err := mediainfo.ResolveFFmpeg(cfg.Library.FFmpegPath); err != nil {
+			log.Printf("[hls] transcode enabled but ffmpeg/ffprobe not found — install ffmpeg to use HLS")
+		} else if _, err := mediainfo.ResolveFFprobe(cfg.Library.FFprobePath); err != nil {
+			log.Printf("[hls] transcode enabled but ffmpeg/ffprobe not found — install ffmpeg to use HLS")
+		}
+	}
+
+	// Wire sync client callbacks
+	sc := d.SyncClient()
+	sc.GetFreeSlots = manager.FreeSlots
+	sc.GetTaskStates = manager.TaskStates
+	d.GetActiveCount = manager.ActiveCount
+
+	// Trigger immediate sync when a download slot frees up
+	manager.OnTaskDone = func() { d.TriggerSync() }
+
+	// Wire: sync receives new tasks → submit to manager or handle stream
 	d.OnTasksClaimed = func(tasks []agent.Task) {
 		for _, t := range tasks {
 			if t.Mode == "stream" {
-				go handleStreamTask(ctx, t, reporter, cfg)
-			} else if t.ForceStart || manager.HasCapacity() {
-				manager.Submit(ctx, t)
+				if isStreamingTask(t.ID) {
+					continue
+				}
+				cancelStreamContexts()
+				streamSrv.ClearFile()
+				streamCtx, streamCancel := context.WithCancel(ctx) //nolint:gosec // G118: cancel stored in registry
+				streamRegistry.mu.Lock()
+				streamRegistry.cancels[t.ID] = streamCancel
+				streamRegistry.mu.Unlock()
+				go handleStreamTask(streamCtx, t, reporter, cfg, agentClient, streamSrv)
 			} else {
-				log.Printf("[%s] skipped: no capacity (max %d)", t.ID[:8], cfg.Download.MaxConcurrent)
+				manager.Submit(ctx, t)
 			}
 		}
 	}
 
-	// Wire: stream requests for completed downloads → serve file from disk
-	d.OnStreamRequested = func(sr agent.StreamRequest) {
-		// Check if already streaming this task
-		streamRegistry.mu.Lock()
-		_, exists := streamRegistry.servers[sr.TaskID]
-		streamRegistry.mu.Unlock()
-		if exists {
-			return
-		}
-
-		if _, err := os.Stat(sr.FilePath); err != nil {
-			log.Printf("[%s] stream request: file not found: %s", sr.TaskID[:8], sr.FilePath)
-			return
-		}
-
-		srv := engine.NewStreamServerFromDisk(sr.FilePath, 0)
-		streamURL, err := srv.Start(context.Background())
-		if err != nil {
-			log.Printf("[%s] stream failed: %v", sr.TaskID[:8], err)
-			return
-		}
-
-		streamRegistry.mu.Lock()
-		streamRegistry.servers[sr.TaskID] = srv
-		streamRegistry.mu.Unlock()
-
-		log.Printf("[%s] streaming from disk: %s → %s", sr.TaskID[:8], filepath.Base(sr.FilePath), streamURL)
-
-		// Report stream URL back to the server via transport
-		go func() {
-			if _, err := transport.SendProgress(ctx, agent.StatusUpdate{
-				TaskID:    sr.TaskID,
-				StreamURL: streamURL,
-			}); err != nil {
-				log.Printf("[%s] stream URL report failed: %v", sr.TaskID[:8], err)
-			}
-		}()
-	}
-
-	// Wire: WS control actions (pause/cancel/stream pushed from server)
-	d.OnControlAction = func(action, taskID string) {
+	// Wire: sync receives control signals → act on manager
+	d.OnControlAction = func(action, taskID string, deleteFiles bool) {
 		switch action {
 		case "cancel":
-			manager.CancelTask(taskID)
+			if deleteFiles {
+				manager.CancelAndDeleteFiles(taskID)
+			} else {
+				manager.CancelTask(taskID)
+			}
 			cancelStreamTask(taskID)
+			if streamSrv.CurrentTaskID() == taskID {
+				streamSrv.ClearFile()
+			}
 		case "pause":
 			manager.PauseTask(taskID)
 			cancelStreamTask(taskID)
+			if streamSrv.CurrentTaskID() == taskID {
+				streamSrv.ClearFile()
+			}
 		case "resume":
-			log.Printf("[%s] resume requested via WebSocket, triggering poll", taskID[:8])
-			d.TriggerPoll()
+			log.Printf("[%s] resume requested, triggering sync", agent.ShortID(taskID))
+			d.TriggerSync()
 		case "stream":
-			// Use registry mutex to prevent TOCTOU race with HTTP-polled stream requests
-			streamRegistry.mu.Lock()
-			if _, exists := streamRegistry.servers[taskID]; exists {
-				streamRegistry.mu.Unlock()
+			if streamSrv.CurrentTaskID() == taskID {
 				return
 			}
 			task := manager.GetTask(taskID)
 			if task == nil || task.GetStreamURL() != "" {
-				streamRegistry.mu.Unlock()
 				return
 			}
-			streamRegistry.mu.Unlock()
-			srv, err := torrentDl.StartStream(taskID)
+			provider, err := torrentDl.GetStreamProvider(taskID)
 			if err != nil {
-				log.Printf("[%s] stream failed: %v", taskID[:8], err)
+				log.Printf("[%s] stream failed: %v", agent.ShortID(taskID), err)
 				return
 			}
+			cancelStreamContexts()
+			streamSrv.SetFile(provider, taskID)
+			task.SetStreamURL(streamSrv.URLsJSON())
+			log.Printf("[%s] streaming: %s", agent.ShortID(taskID), provider.FileName())
+
+			watchCtx, watchCancel := context.WithCancel(ctx) //nolint:gosec // G118
 			streamRegistry.mu.Lock()
-			streamRegistry.servers[taskID] = srv
+			streamRegistry.cancels["watch:"+taskID] = watchCancel
 			streamRegistry.mu.Unlock()
-			task.SetStreamURL(srv.URL())
+			go engine.NewWatchReporter(agentClient, streamSrv, taskID).Run(watchCtx)
+		case "stop-stream":
+			cancelStreamTask(taskID)
+			if streamSrv.CurrentTaskID() == taskID {
+				streamSrv.ClearFile()
+			}
 		}
 	}
 
-	// Config hot-reload (SIGUSR1 on Unix, no-op on Windows)
-	// Tickers are initialized inside d.Run(), so we pass the daemon
-	// and the reload goroutine reads them when the signal arrives.
-	startReloadWatcher(&ReloadableConfig{Daemon: d})
+	// Wire: sync receives file deletion requests from the server
+	if cfg.Library.AllowDelete && len(daemonCfg.ScanPaths) > 0 {
+		sc.OnDeleteFiles = func(items []agent.LibraryDeleteRequest) []int {
+			return library.DeleteFiles(items, daemonCfg.ScanPaths)
+		}
+	}
 
-	// Signal handling
-	sigCh := make(chan os.Signal, 1)
-	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+	// Wire: sync receives stream requests for completed downloads
+	d.OnStreamRequested = func(sr agent.StreamRequest) {
+		if streamSrv.CurrentTaskID() == sr.TaskID {
+			// Already serving — notify server it's ready
+			go func() {
+				if _, err := agentClient.ReportStatus(ctx, agent.StatusUpdate{
+					TaskID:      sr.TaskID,
+					StreamReady: true,
+				}); err != nil {
+					log.Printf("[%s] stream ready re-notify failed: %v", agent.ShortID(sr.TaskID), err)
+				}
+			}()
+			return
+		}
 
-	// Start progress reporter in background
-	go reporter.Run(ctx)
+		filePath := filepath.Clean(sr.FilePath)
+		if !isAllowedStreamPath(filePath, cfg.Download.Dir, cfg.Library.ScanPath,
+			cfg.Organize.MoviesDir, cfg.Organize.TVShowsDir) {
+			log.Printf("[%s] stream request rejected: path outside allowed dirs: %s", agent.ShortID(sr.TaskID), filePath)
+			go func() {
+				if _, err := agentClient.ReportStatus(ctx, agent.StatusUpdate{
+					TaskID:       sr.TaskID,
+					Status:       "failed",
+					ErrorMessage: fmt.Sprintf("path outside allowed dirs: %s", filePath),
+				}); err != nil {
+					log.Printf("[%s] stream error report failed: %v", agent.ShortID(sr.TaskID), err)
+				}
+			}()
+			return
+		}
+		info, err := os.Stat(filePath)
+		if err != nil {
+			log.Printf("[%s] stream request: file not found: %s", agent.ShortID(sr.TaskID), filePath)
+			go func() {
+				if _, err := agentClient.ReportStatus(ctx, agent.StatusUpdate{
+					TaskID:       sr.TaskID,
+					Status:       "failed",
+					ErrorMessage: fmt.Sprintf("file not found: %s", filePath),
+				}); err != nil {
+					log.Printf("[%s] stream error report failed: %v", agent.ShortID(sr.TaskID), err)
+				}
+			}()
+			return
+		}
 
-	// Periodic DHT node persistence (every 5 min) — protects against crash data loss
+		if info.IsDir() {
+			found := engine.FindVideoFile(filePath)
+			if found == "" {
+				log.Printf("[%s] stream request: no video file in directory: %s", agent.ShortID(sr.TaskID), filePath)
+				go func() {
+					if _, err := agentClient.ReportStatus(ctx, agent.StatusUpdate{
+						TaskID:       sr.TaskID,
+						Status:       "failed",
+						ErrorMessage: fmt.Sprintf("no video file in directory: %s", filePath),
+					}); err != nil {
+						log.Printf("[%s] stream error report failed: %v", agent.ShortID(sr.TaskID), err)
+					}
+				}()
+				return
+			}
+			filePath = found
+			log.Printf("[%s] resolved directory to video file: %s", agent.ShortID(sr.TaskID), filepath.Base(filePath))
+		}
+
+		cancelStreamContexts()
+		streamSrv.SetFile(engine.NewDiskFileProvider(filePath), sr.TaskID)
+		log.Printf("[%s] streaming from disk: %s → %s", agent.ShortID(sr.TaskID), filepath.Base(filePath), streamSrv.URL())
+
+		watchCtx, watchCancel := context.WithCancel(ctx) //nolint:gosec // G118
+		streamRegistry.mu.Lock()
+		streamRegistry.cancels["watch:"+sr.TaskID] = watchCancel
+		streamRegistry.mu.Unlock()
+		go engine.NewWatchReporter(agentClient, streamSrv, sr.TaskID).Run(watchCtx)
+
+		go func() {
+			if _, err := agentClient.ReportStatus(ctx, agent.StatusUpdate{
+				TaskID:      sr.TaskID,
+				StreamReady: true,
+			}); err != nil {
+				log.Printf("[%s] stream ready report failed: %v", agent.ShortID(sr.TaskID), err)
+			}
+		}()
+	}
+
+	// Wire: sync receives HLS streaming session requests. Each session spawns
+	// one ffmpeg process and registers its HLS playlist with the StreamServer.
+	// Validate FilePath against allowed dirs to prevent path traversal abuse
+	// from a compromised server.
+	d.OnStreamSession = func(sess agent.StreamSession) {
+		if playerSessionRegistry.has(sess.SessionID) {
+			return // already running
+		}
+		filePath := sess.FilePath
+		if filePath == "" {
+			log.Printf("[hls %s] rejected: empty file path", agent.ShortID(sess.SessionID))
+			return
+		}
+		filePath = filepath.Clean(filePath)
+		if !isAllowedStreamPath(filePath, cfg.Download.Dir, cfg.Library.ScanPath,
+			cfg.Organize.MoviesDir, cfg.Organize.TVShowsDir) {
+			log.Printf("[hls %s] rejected: path outside allowed dirs: %s",
+				agent.ShortID(sess.SessionID), filePath)
+			return
+		}
+		// Resolve directory → first video file (matches StreamRequest behavior).
+		if info, err := os.Stat(filePath); err == nil && info.IsDir() {
+			found := engine.FindVideoFile(filePath)
+			if found == "" {
+				log.Printf("[hls %s] rejected: no video file in dir %s",
+					agent.ShortID(sess.SessionID), filePath)
+				return
+			}
+			filePath = found
+		}
+
+		tcRuntime := buildTranscodeRuntime(ctx, cfg)
+		if tcRuntime.FFmpegPath == "" || tcRuntime.FFprobePath == "" {
+			log.Printf("[hls %s] rejected: ffmpeg/ffprobe unavailable", agent.ShortID(sess.SessionID))
+			return
+		}
+		hlsCtx, hlsCancel := context.WithCancel(ctx)
+		playerSessionRegistry.add(sess.SessionID, hlsCancel)
+		hlsCfg := engine.HLSSessionConfig{
+			SessionID:  sess.SessionID,
+			SourcePath: filePath,
+			FileName:   sess.FileName,
+			Quality:    sess.Quality,
+			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)
+		}()
+	}
+
+	// Periodic DHT node persistence (every 5 min)
 	go func() {
 		ticker := time.NewTicker(5 * time.Minute)
 		defer ticker.Stop()
@@ -381,27 +634,60 @@ func runDaemonStart() error {
 		}
 	}()
 
-	// Start auto-scan goroutine (daily library scan + sync)
-	if cfg.Library.ScanPath != "" && cfg.Library.AutoScan {
+	// Periodic HLS session sweeper (every 5 min). Closes sessions whose last
+	// segment fetch was over 30 min ago — kills the orphan ffmpeg + removes
+	// the per-session tmpdir, so a tab that died mid-stream doesn't leak
+	// disk space until daemon shutdown.
+	go func() {
+		ticker := time.NewTicker(5 * time.Minute)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ticker.C:
+				if n := streamSrv.HLS().SweepIdle(); n > 0 {
+					log.Printf("[hls] swept %d idle session(s)", n)
+				}
+			case <-ctx.Done():
+				return
+			}
+		}
+	}()
+
+	// Start auto-scan goroutine
+	scanPaths := daemonCfg.ScanPaths
+	if len(scanPaths) > 0 && cfg.Library.AutoScan {
 		scanInterval := 24 * time.Hour
 		if cfg.Library.ScanInterval != "" {
 			if parsed, err := time.ParseDuration(cfg.Library.ScanInterval); err == nil && parsed > 0 {
 				scanInterval = parsed
 			}
 		}
-		go runAutoScan(ctx, cfg, scanInterval)
+		go runAutoScan(ctx, cfg, scanInterval, agentClient, d.ScanNow, scanPaths)
 	}
 
-	// Start daemon (blocks)
+	// Start reporter only for stream task handling
+	go reporter.Run(ctx)
+
+	// Start daemon (blocks — runs sync loop)
 	errCh := make(chan error, 1)
 	go func() {
 		errCh <- d.Run(ctx)
 	}()
 
+	// Start idle guard for the persistent stream server
+	go startIdleGuard(ctx, streamSrv)
+
+	// Signal handling
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+
 	// Wait for signal or error
 	select {
 	case sig := <-sigCh:
 		fmt.Printf("\n  Received %s, shutting down...\n", sig)
+		cancelStreamContexts()
+		cancelAllPlayerSessions()
+		streamSrv.Shutdown(context.Background())
 		cancel()
 
 		// Give active downloads 30s to finish
@@ -409,48 +695,36 @@ func runDaemonStart() error {
 		defer shutdownCancel()
 		manager.Shutdown(shutdownCtx)
 
+		d.Deregister()
 		fmt.Println("  Daemon stopped.")
 		return nil
 
 	case err := <-errCh:
+		cancelStreamContexts()
+		cancelAllPlayerSessions()
+		streamSrv.Shutdown(context.Background())
 		cancel()
 		return err
 	}
 }
 
-// deriveWSURL derives a WebSocket URL from the API URL.
-// https://torrentclaw.com → wss://unarr.torrentclaw.com/ws/{agentId}
-// Returns "" for localhost/dev environments where WS gateway isn't available.
-func deriveWSURL(apiURL, agentID string) string {
-	if apiURL == "" || agentID == "" {
-		return ""
-	}
-	// Parse domain from API URL
-	domain := apiURL
-	for _, prefix := range []string{"https://", "http://"} {
-		if len(domain) > len(prefix) && domain[:len(prefix)] == prefix {
-			domain = domain[len(prefix):]
-			break
+// isAllowedStreamPath checks that filePath is within one of the directories
+// the daemon is configured to manage. This defends against a compromised API
+// server sending a path traversal payload (e.g. /etc/passwd) in StreamRequest.
+// isAllowedStreamPath reports whether filePath is contained within one of the
+// allowedDirs. filePath must already be cleaned (filepath.Clean) by the caller.
+// This defends against a compromised API server sending a path traversal payload.
+func isAllowedStreamPath(filePath string, allowedDirs ...string) bool {
+	for _, dir := range allowedDirs {
+		if dir == "" {
+			continue
+		}
+		rel, err := filepath.Rel(filepath.Clean(dir), filePath)
+		if err == nil && !strings.HasPrefix(rel, "..") {
+			return true
 		}
 	}
-	// Strip trailing slash/path
-	for i := 0; i < len(domain); i++ {
-		if domain[i] == '/' {
-			domain = domain[:i]
-			break
-		}
-	}
-	// Strip port if present
-	if idx := strings.LastIndex(domain, ":"); idx > 0 {
-		domain = domain[:idx]
-	}
-
-	// Skip WS for localhost/dev — gateway only available in production
-	if domain == "localhost" || domain == "127.0.0.1" || domain == "0.0.0.0" {
-		return ""
-	}
-
-	return "wss://unarr." + domain + "/ws/" + agentID
+	return false
 }
 
 func formatSpeedLog(bps int64) string {
@@ -466,13 +740,15 @@ func formatSpeedLog(bps int64) string {
 	}
 }
 
-// runAutoScan runs a library scan + sync on a timer.
-func runAutoScan(ctx context.Context, cfg config.Config, interval time.Duration) {
-	log.Printf("[auto-scan] enabled: every %s, path: %s", interval, cfg.Library.ScanPath)
+// runAutoScan runs a library scan + sync on a timer or on-demand via scanNow channel.
+// It scans all provided paths and syncs each independently so stale-item cleanup
+// is scoped to the correct directory prefix on the server.
+func runAutoScan(ctx context.Context, cfg config.Config, interval time.Duration, ac *agent.Client, scanNow <-chan struct{}, scanPaths []string) {
+	log.Printf("[auto-scan] enabled: every %s, paths: %v", interval, scanPaths)
 
-	// Run first scan after a short delay (let daemon stabilize)
 	select {
 	case <-time.After(30 * time.Second):
+	case <-scanNow:
 	case <-ctx.Done():
 		return
 	}
@@ -483,7 +759,7 @@ func runAutoScan(ctx context.Context, cfg config.Config, interval time.Duration)
 				log.Printf("[auto-scan] panic recovered: %v", r)
 			}
 		}()
-		log.Printf("[auto-scan] starting scan of %s", cfg.Library.ScanPath)
+		log.Printf("[auto-scan] starting scan of %v", scanPaths)
 
 		existing, _ := library.LoadCache()
 
@@ -492,55 +768,67 @@ func runAutoScan(ctx context.Context, cfg config.Config, interval time.Duration)
 			workers = 8
 		}
 
-		cache, err := library.Scan(ctx, cfg.Library.ScanPath, existing, library.ScanOptions{
+		scanOpts := library.ScanOptions{
 			Workers:     workers,
 			FFprobePath: cfg.Library.FFprobePath,
 			Incremental: existing != nil,
-		})
-		if err != nil {
-			log.Printf("[auto-scan] scan failed: %v", err)
-			return
-		}
-
-		if err := library.SaveCache(cache); err != nil {
-			log.Printf("[auto-scan] save cache failed: %v", err)
-			return
-		}
-
-		// Sync to server
-		apiKey := cfg.Auth.APIKey
-		if apiKey == "" {
-			log.Printf("[auto-scan] no API key, skipping sync")
-			return
-		}
-
-		ac := agent.NewClient(cfg.Auth.APIURL, apiKey, "unarr/"+Version)
-		items := library.BuildSyncItems(cache)
-		if len(items) == 0 {
-			log.Printf("[auto-scan] no items to sync")
-			return
 		}
 
+		// Scan each path independently and sync per path so the server can
+		// scope stale-item deletion to the correct directory prefix.
 		const batchSize = 100
-		for i := 0; i < len(items); i += batchSize {
-			end := i + batchSize
-			if end > len(items) {
-				end = len(items)
-			}
-			isLast := end >= len(items)
+		totalSynced := 0
+		var mergedItems []library.LibraryItem
 
-			_, err := ac.SyncLibrary(ctx, agent.LibrarySyncRequest{
-				Items:       items[i:end],
-				ScanPath:    cache.Path,
-				IsLastBatch: isLast,
-			})
+		for _, scanPath := range scanPaths {
+			cache, err := library.Scan(ctx, scanPath, existing, scanOpts)
 			if err != nil {
-				log.Printf("[auto-scan] sync failed: %v", err)
-				return
+				log.Printf("[auto-scan] scan failed for %s: %v", scanPath, err)
+				continue
+			}
+			mergedItems = append(mergedItems, cache.Items...)
+
+			items := library.BuildSyncItems(cache)
+			if len(items) == 0 {
+				log.Printf("[auto-scan] no items under %s", scanPath)
+				continue
+			}
+
+			syncStartedAt := time.Now().UTC().Format(time.RFC3339)
+			for i := 0; i < len(items); i += batchSize {
+				end := i + batchSize
+				if end > len(items) {
+					end = len(items)
+				}
+				isLast := end >= len(items)
+
+				_, err := ac.SyncLibrary(ctx, agent.LibrarySyncRequest{
+					Items:         items[i:end],
+					ScanPath:      scanPath,
+					IsLastBatch:   isLast,
+					SyncStartedAt: syncStartedAt,
+				})
+				if err != nil {
+					log.Printf("[auto-scan] sync failed for %s: %v", scanPath, err)
+					break
+				}
+			}
+			totalSynced += len(items)
+		}
+
+		// Save merged cache for incremental scanning next time.
+		if len(mergedItems) > 0 {
+			mergedCache := &library.LibraryCache{
+				ScannedAt: time.Now().UTC().Format(time.RFC3339),
+				Path:      scanPaths[0],
+				Items:     mergedItems,
+			}
+			if err := library.SaveCache(mergedCache); err != nil {
+				log.Printf("[auto-scan] save cache failed: %v", err)
 			}
 		}
 
-		log.Printf("[auto-scan] synced %d items", len(items))
+		log.Printf("[auto-scan] synced %d items across %d path(s)", totalSynced, len(scanPaths))
 	}
 
 	doScan()
@@ -552,10 +840,153 @@ func runAutoScan(ctx context.Context, cfg config.Config, interval time.Duration)
 		select {
 		case <-ticker.C:
 			doScan()
+		case <-scanNow:
+			log.Printf("[auto-scan] on-demand scan triggered")
+			ticker.Reset(interval)
+			doScan()
 		case <-ctx.Done():
 			return
 		}
 	}
 }
 
-// buildSyncItems moved to internal/library/sync.go as library.BuildSyncItems
+// superviseFunnel keeps a CloudFlare Quick Tunnel up across cloudflared
+// crashes and CF's ~6h tunnel rotation. On a clean exit (cancellation) it
+// returns; on a crash it clears the reported URL and respawns with an
+// exponential backoff so we don't hammer cloudflared into a tight loop when
+// it can't reach the CF edge.
+func superviseFunnel(ctx context.Context, d *agent.Daemon, port int) {
+	backoff := 2 * time.Second
+	const maxBackoff = 5 * time.Minute
+	for ctx.Err() == nil {
+		t, err := funnel.Start(ctx, funnel.Config{Port: port})
+		if err != nil {
+			log.Printf("[funnel] could not start CloudFlare tunnel (%v) — retrying in %s", err, backoff)
+			select {
+			case <-time.After(backoff):
+			case <-ctx.Done():
+				return
+			}
+			backoff = min(backoff*2, maxBackoff)
+			continue
+		}
+		log.Printf("[funnel] cloudflared started, waiting for public URL...")
+		go func() {
+			url, werr := t.WaitURL(45 * time.Second)
+			if werr != nil {
+				log.Printf("[funnel] cloudflared did not emit a URL (%v)", werr)
+				return
+			}
+			log.Printf("[funnel] public URL: %s", url)
+			d.SetFunnelURL(url)
+		}()
+		// Block until cloudflared exits (CF rotation, crash, or shutdown).
+		exitErr := <-t.Done()
+		_ = t.Close()
+		d.SetFunnelURL("")
+		if ctx.Err() != nil {
+			return
+		}
+		if exitErr != nil {
+			log.Printf("[funnel] cloudflared exited: %v — restarting in %s", exitErr, backoff)
+		} else {
+			log.Printf("[funnel] cloudflared exited cleanly — restarting in %s", backoff)
+		}
+		select {
+		case <-time.After(backoff):
+		case <-ctx.Done():
+			return
+		}
+		backoff = min(backoff*2, maxBackoff)
+	}
+}
+
+// mirrorCORSOrigins fetches /api/mirrors from the configured primary (+ extra
+// mirror candidates + static IPFS fallback) and returns the discovered URLs as
+// Origin strings. Best-effort: any failure logs a warning and returns an empty
+// slice; the static defaultCORSAllowedOrigins in validate.go covers the known
+// mirrors (.com / .to / built-in onion) so the daemon still accepts the
+// official surfaces when this call fails.
+//
+// Bounded to a short timeout so a slow /api/mirrors response can't delay
+// daemon startup — every second here is a second the user can't play.
+func mirrorCORSOrigins(parent context.Context, cfg config.Config, userAgent string) []string {
+	ctx, cancel := context.WithTimeout(parent, 10*time.Second)
+	defer cancel()
+
+	candidates := append([]string{cfg.Auth.APIURL}, cfg.Auth.Mirrors...)
+	resp, err := agent.FetchMirrorsWithFallback(ctx, candidates, userAgent)
+	if err != nil {
+		log.Printf("[cors] mirror discovery failed (%v) — using static allowlist only", err)
+		return nil
+	}
+
+	seen := make(map[string]struct{})
+	out := make([]string, 0, len(resp.Mirrors))
+	add := func(rawURL string) {
+		if rawURL == "" {
+			return
+		}
+		origin := strings.TrimRight(rawURL, "/")
+		if _, dup := seen[origin]; dup {
+			return
+		}
+		seen[origin] = struct{}{}
+		out = append(out, origin)
+	}
+	for _, m := range resp.Mirrors {
+		add(m.URL)
+	}
+	if resp.Tor != nil {
+		add(resp.Tor.URL)
+	}
+	if len(out) > 0 {
+		log.Printf("[cors] merged %d mirror origins from /api/mirrors", len(out))
+	}
+	return out
+}
+
+// watchSessionReady polls HLSSession.ReadyCount until the first segment +
+// init.mp4 are on disk, then POSTs /api/internal/agent/session-ready so
+// the web side flips streaming_session.ready_at — which its SSE endpoint
+// pushes to subscribed players. Cache-HIT sessions are ready the moment
+// StartHLSSession returns and POST immediately.
+//
+// Bounded by a 60 s deadline so a permanently stuck encoder doesn't keep
+// a goroutine alive forever; if seg-0 never lands the player falls back
+// to its existing HEAD-probe retry path anyway.
+func watchSessionReady(ctx context.Context, client *agent.Client, hsess *engine.HLSSession, sessionID string) {
+	deadline := time.Now().Add(60 * time.Second)
+	ticker := time.NewTicker(200 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		// Session torn down through a path that didn't cancel ctx (registry
+		// replace, idle sweep, internal kill). Bail before polling further —
+		// without this check the watcher could keep alive for up to 60 s on
+		// a dead HLSSession that's never going to become ready.
+		if hsess.IsClosed() {
+			return
+		}
+		// Cache HIT or seg-0 ready → notify + done.
+		if hsess.FromCache() || hsess.ReadyCount() >= 1 {
+			// Parent ctx so a session cancel mid-POST (user closed tab,
+			// daemon shutdown) tears down the in-flight webhook instead of
+			// blocking the goroutine for up to 10 s on a now-orphan call.
+			rctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+			if err := client.MarkSessionReady(rctx, sessionID); err != nil {
+				log.Printf("[hls %s] mark-ready failed: %v", agent.ShortID(sessionID), err)
+			}
+			cancel()
+			return
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+		if time.Now().After(deadline) {
+			log.Printf("[hls %s] mark-ready: timeout waiting for seg-0", agent.ShortID(sessionID))
+			return
+		}
+	}
+}
diff --git a/internal/cmd/daemon_control.go b/internal/cmd/daemon_control.go
new file mode 100644
index 0000000..4ac4d10
--- /dev/null
+++ b/internal/cmd/daemon_control.go
@@ -0,0 +1,335 @@
+package cmd
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+func newDaemonStartCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "start",
+		Short: "Start the installed daemon service",
+		Long: `Start the unarr daemon using the system service manager.
+Requires 'unarr daemon install' to have been run first.
+
+  Linux:   systemctl --user start unarr
+  macOS:   launchctl load ~/Library/LaunchAgents/com.torrentclaw.unarr.plist
+  Windows: schtasks /run /tn unarr`,
+		Example: `  unarr daemon start`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runDaemonSvcStart()
+		},
+	}
+}
+
+func newDaemonStopCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "stop",
+		Short: "Stop the running daemon service",
+		Long: `Stop the unarr daemon service.
+
+  Linux:   systemctl --user stop unarr
+  macOS:   launchctl unload ~/Library/LaunchAgents/com.torrentclaw.unarr.plist
+  Windows: sends stop signal via process PID`,
+		Example: `  unarr daemon stop`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runDaemonSvcStop()
+		},
+	}
+}
+
+func newDaemonRestartCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "restart",
+		Short: "Restart the daemon service",
+		Long: `Restart the unarr daemon service.
+
+  Linux:   systemctl --user restart unarr
+  macOS:   unload + reload launchd agent
+  Windows: stop by PID + schtasks /run`,
+		Example: `  unarr daemon restart`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runDaemonSvcRestart()
+		},
+	}
+}
+
+func newDaemonSvcStatusCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "status",
+		Short: "Show daemon service status",
+		Long: `Show the current status of the unarr daemon service as reported
+by the system service manager, plus local state information.`,
+		Example: `  unarr daemon status`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runDaemonSvcStatus()
+		},
+	}
+}
+
+func newDaemonLogsCmd() *cobra.Command {
+	var follow bool
+	var lines int
+
+	cmd := &cobra.Command{
+		Use:   "logs",
+		Short: "Show daemon logs",
+		Long: `Show daemon log output.
+
+  Linux:   streams from journald (journalctl --user -u unarr)
+  macOS:   tails ~/.local/share/unarr/unarr.log
+  Windows: tails %LOCALAPPDATA%\unarr\unarr.log`,
+		Example: `  unarr daemon logs
+  unarr daemon logs -f
+  unarr daemon logs -n 100 -f`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runDaemonLogs(follow, lines)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&follow, "follow", "f", false, "Follow log output")
+	cmd.Flags().IntVarP(&lines, "lines", "n", 50, "Number of lines to show")
+	return cmd
+}
+
+func newDaemonReloadCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "reload",
+		Short: "Reload daemon configuration without restarting",
+		Long: `Send a reload signal to the running daemon, causing it to
+re-read its configuration file without interrupting active downloads.
+
+  Linux/macOS: sends SIGUSR1 to the daemon process
+  Windows:     not supported (use 'unarr daemon restart' instead)`,
+		Example: `  unarr daemon reload`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runDaemonReload()
+		},
+	}
+}
+
+// ── Platform implementations ──────────────────────────────────────────────────
+
+func runDaemonSvcStart() error {
+	fmt.Println()
+	switch runtime.GOOS {
+	case "linux":
+		if err := svcExec("systemctl", "--user", "start", "unarr"); err != nil {
+			fmt.Fprintln(os.Stderr, "\n  Is the daemon installed? Run 'unarr daemon install' first.")
+			return fmt.Errorf("start service: %w", err)
+		}
+	case "darwin":
+		home, _ := os.UserHomeDir()
+		plist := launchdPlistPath(home)
+		if _, err := os.Stat(plist); err != nil {
+			return fmt.Errorf("service not installed — run 'unarr daemon install' first")
+		}
+		if err := svcExec("launchctl", "load", plist); err != nil {
+			return fmt.Errorf("load service: %w", err)
+		}
+	case "windows":
+		if err := svcExec("schtasks", "/run", "/tn", "unarr"); err != nil {
+			fmt.Fprintln(os.Stderr, "\n  Is the daemon installed? Run 'unarr daemon install' first.")
+			return fmt.Errorf("start task: %w", err)
+		}
+	default:
+		return fmt.Errorf("service control not supported on %s", runtime.GOOS)
+	}
+
+	color.New(color.FgGreen).Println("  ✓ Started")
+	fmt.Println()
+	return nil
+}
+
+func runDaemonSvcStop() error {
+	fmt.Println()
+	switch runtime.GOOS {
+	case "linux":
+		if err := svcExec("systemctl", "--user", "stop", "unarr"); err != nil {
+			return fmt.Errorf("stop service: %w", err)
+		}
+	case "darwin":
+		home, _ := os.UserHomeDir()
+		plist := launchdPlistPath(home)
+		if err := svcExec("launchctl", "unload", plist); err != nil {
+			return fmt.Errorf("unload service: %w", err)
+		}
+	default:
+		return stopDaemonByPID()
+	}
+
+	color.New(color.FgGreen).Println("  ✓ Stopped")
+	fmt.Println()
+	return nil
+}
+
+func runDaemonSvcRestart() error {
+	switch runtime.GOOS {
+	case "linux":
+		fmt.Println()
+		if err := svcExec("systemctl", "--user", "restart", "unarr"); err != nil {
+			return fmt.Errorf("restart service: %w", err)
+		}
+		color.New(color.FgGreen).Println("  ✓ Restarted")
+		fmt.Println()
+		return nil
+	default:
+		fmt.Println("  Stopping...")
+		_ = runDaemonSvcStop()
+		fmt.Println("  Starting...")
+		return runDaemonSvcStart()
+	}
+}
+
+func runDaemonSvcStatus() error {
+	fmt.Println()
+	switch runtime.GOOS {
+	case "linux":
+		// systemctl gives rich formatted output; exit code non-zero when stopped is fine.
+		svcExec("systemctl", "--user", "status", "--no-pager", "unarr") //nolint:errcheck
+	case "darwin":
+		printDaemonStatusDarwin()
+	case "windows":
+		svcExec("schtasks", "/query", "/tn", "unarr", "/fo", "LIST") //nolint:errcheck
+	default:
+		fmt.Printf("  Service manager not supported on %s\n", runtime.GOOS)
+	}
+
+	printStateInfo()
+	return nil
+}
+
+func runDaemonLogs(follow bool, lines int) error {
+	switch runtime.GOOS {
+	case "linux":
+		args := []string{"--user", "-u", "unarr", "--no-pager", "-n", strconv.Itoa(lines)}
+		if follow {
+			// -f implies live output; drop --no-pager so journalctl can control the terminal.
+			args = []string{"--user", "-u", "unarr", "-f"}
+		}
+		return svcExecInteractive("journalctl", args...)
+
+	case "darwin":
+		home, _ := os.UserHomeDir()
+		logFile := filepath.Join(home, ".local", "share", "unarr", "unarr.log")
+		if _, err := os.Stat(logFile); err != nil {
+			fmt.Fprintln(os.Stderr, "The daemon writes this file when running as a launchd service. Run 'unarr daemon install' first.")
+			return fmt.Errorf("log file not found: %s", logFile)
+		}
+		args := []string{"-n", strconv.Itoa(lines)}
+		if follow {
+			args = append(args, "-f")
+		}
+		args = append(args, logFile)
+		return svcExecInteractive("tail", args...)
+
+	case "windows":
+		logFile := filepath.Join(config.DataDir(), "unarr.log")
+		if _, err := os.Stat(logFile); err != nil {
+			fmt.Fprintln(os.Stderr, "The daemon writes logs here when running. Start it first.")
+			return fmt.Errorf("log file not found: %s", logFile)
+		}
+		var psCmd string
+		if follow {
+			psCmd = fmt.Sprintf("Get-Content -Path '%s' -Tail %d -Wait", logFile, lines)
+		} else {
+			psCmd = fmt.Sprintf("Get-Content -Path '%s' -Tail %d", logFile, lines)
+		}
+		return svcExecInteractive("powershell", "-NonInteractive", "-Command", psCmd)
+
+	default:
+		return fmt.Errorf("log viewing not supported on %s", runtime.GOOS)
+	}
+}
+
+func runDaemonReload() error {
+	return sendReloadSignal()
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+// stopDaemonByPID reads the state file and sends a graceful stop to the daemon PID.
+// Used as fallback on platforms without a service manager (and as Windows implementation).
+func stopDaemonByPID() error {
+	state, err := agent.LoadState()
+	if err != nil {
+		if errors.Is(err, agent.ErrDaemonNotRunning) {
+			return err
+		}
+		return fmt.Errorf("read daemon state: %w", err)
+	}
+	return killPID(state.PID)
+}
+
+func launchdPlistPath(home string) string {
+	return filepath.Join(home, "Library", "LaunchAgents", "com.torrentclaw.unarr.plist")
+}
+
+// printDaemonStatusDarwin shows launchd service state by filtering launchctl output.
+func printDaemonStatusDarwin() {
+	out, err := exec.Command("launchctl", "list").Output()
+	if err != nil {
+		fmt.Printf("  Could not query launchctl: %v\n", err)
+		return
+	}
+	found := false
+	for _, line := range strings.Split(string(out), "\n") {
+		if strings.Contains(line, "unarr") {
+			// Format: PID  ExitCode  Label
+			fmt.Printf("  launchd: %s\n", strings.TrimSpace(line))
+			found = true
+		}
+	}
+	if !found {
+		fmt.Println("  launchd: service not loaded")
+	}
+}
+
+// printStateInfo shows information from the local daemon.state.json file.
+func printStateInfo() {
+	state := agent.ReadState()
+	if state == nil {
+		color.New(color.FgHiBlack).Println("  State:   no state file (daemon not running or crashed)")
+		fmt.Println()
+		return
+	}
+	dim := color.New(color.FgHiBlack)
+	fmt.Println()
+	dim.Println("  Local state:")
+	fmt.Printf("    PID:        %d\n", state.PID)
+	fmt.Printf("    Status:     %s\n", state.Status)
+	fmt.Printf("    Version:    %s\n", state.Version)
+	fmt.Printf("    Uptime:     %s\n", formatDuration(time.Since(state.StartedAt)))
+	fmt.Printf("    Heartbeat:  %s ago\n", formatDuration(time.Since(state.LastHeartbeat)))
+	fmt.Printf("    Active:     %d task(s)\n", state.ActiveTasks)
+	fmt.Println()
+}
+
+// svcExec runs a service management command with output flowing to the terminal.
+func svcExec(name string, args ...string) error {
+	cmd := exec.Command(name, args...)
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	return cmd.Run()
+}
+
+// svcExecInteractive is like svcExec but also connects stdin (needed for follow/pager modes).
+func svcExecInteractive(name string, args ...string) error {
+	cmd := exec.Command(name, args...)
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	return cmd.Run()
+}
diff --git a/internal/cmd/daemon_install.go b/internal/cmd/daemon_install.go
index 5087a20..e67e272 100644
--- a/internal/cmd/daemon_install.go
+++ b/internal/cmd/daemon_install.go
@@ -6,10 +6,14 @@ import (
 	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strconv"
+	"strings"
 	"text/template"
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/config"
 )
 
 const systemdTemplate = `[Unit]
@@ -22,11 +26,10 @@ Type=simple
 ExecStart={{.BinPath}} start
 Restart=always
 RestartSec=10
-User={{.User}}
 Environment=HOME={{.Home}}
 
 [Install]
-WantedBy=multi-user.target
+WantedBy=default.target
 `
 
 const launchdTemplate = `<?xml version="1.0" encoding="UTF-8"?>
@@ -124,6 +127,8 @@ func runDaemonInstall() error {
 		return installSystemd(data, green)
 	case "darwin":
 		return installLaunchd(data, green)
+	case "windows":
+		return installWindowsTask(data, green)
 	default:
 		return fmt.Errorf("service installation not supported on %s yet", runtime.GOOS)
 	}
@@ -229,6 +234,17 @@ func runDaemonUninstall() error {
 		os.Remove(path)
 		green.Printf("  ✓ Removed %s\n", path)
 
+	case "windows":
+		// Stop the running process if any
+		if state := agent.ReadState(); state != nil {
+			exec.Command("taskkill", "/pid", strconv.Itoa(state.PID), "/f").Run()
+		}
+		out, err := exec.Command("schtasks", "/delete", "/tn", "unarr", "/f").CombinedOutput()
+		if err != nil && !strings.Contains(string(out), "cannot find") {
+			return fmt.Errorf("remove scheduled task: %w\n%s", err, strings.TrimSpace(string(out)))
+		}
+		green.Println("  ✓ Scheduled task removed")
+
 	default:
 		return fmt.Errorf("service uninstall not supported on %s yet", runtime.GOOS)
 	}
@@ -236,3 +252,45 @@ func runDaemonUninstall() error {
 	fmt.Println()
 	return nil
 }
+
+func installWindowsTask(data serviceData, green *color.Color) error {
+	logDir := config.DataDir()
+	os.MkdirAll(logDir, 0o755)
+
+	// Remove any existing task before (re)installing.
+	exec.Command("schtasks", "/delete", "/tn", "unarr", "/f").Run()
+
+	// Wrap with PowerShell so stdout/stderr are captured to a log file.
+	psScript := fmt.Sprintf(
+		`Start-Transcript -Path '%s\unarr.log' -Append -NoClobber; & '%s' start`,
+		logDir, data.BinPath,
+	)
+	taskCmd := fmt.Sprintf(`powershell.exe -NonInteractive -WindowStyle Hidden -Command "%s"`, psScript)
+
+	out, err := exec.Command("schtasks",
+		"/create",
+		"/tn", "unarr",
+		"/tr", taskCmd,
+		"/sc", "onlogon",
+		"/ru", data.User,
+		"/rl", "highest",
+		"/f",
+	).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("create scheduled task: %w\n%s", err, strings.TrimSpace(string(out)))
+	}
+
+	fmt.Println()
+	green.Println("  ✓ Installed! Service will start automatically at next login.")
+	fmt.Println()
+	fmt.Println("  To start now:")
+	fmt.Println("    unarr daemon start")
+	fmt.Println()
+	fmt.Println("  Manage with:")
+	fmt.Println("    unarr daemon status")
+	fmt.Println("    unarr daemon stop")
+	fmt.Printf("    unarr daemon logs          (log: %s\\unarr.log)\n", logDir)
+	fmt.Println()
+
+	return nil
+}
diff --git a/internal/cmd/daemon_test.go b/internal/cmd/daemon_test.go
new file mode 100644
index 0000000..1ae09aa
--- /dev/null
+++ b/internal/cmd/daemon_test.go
@@ -0,0 +1,93 @@
+package cmd
+
+import (
+	"testing"
+)
+
+func TestIsAllowedStreamPath(t *testing.T) {
+	tests := []struct {
+		name        string
+		filePath    string
+		allowedDirs []string
+		want        bool
+	}{
+		{
+			name:        "path inside download dir",
+			filePath:    "/downloads/movie.mkv",
+			allowedDirs: []string{"/downloads"},
+			want:        true,
+		},
+		{
+			name:        "path inside subdirectory",
+			filePath:    "/downloads/sub/movie.mkv",
+			allowedDirs: []string{"/downloads"},
+			want:        true,
+		},
+		{
+			name:        "path traversal attempt",
+			filePath:    "/downloads/../etc/passwd",
+			allowedDirs: []string{"/downloads"},
+			want:        false,
+		},
+		{
+			name:        "path outside all allowed dirs",
+			filePath:    "/etc/passwd",
+			allowedDirs: []string{"/downloads", "/movies"},
+			want:        false,
+		},
+		{
+			name:        "path inside second allowed dir",
+			filePath:    "/movies/action/movie.mkv",
+			allowedDirs: []string{"/downloads", "/movies"},
+			want:        true,
+		},
+		{
+			name:        "empty allowed dirs",
+			filePath:    "/downloads/movie.mkv",
+			allowedDirs: []string{"", ""},
+			want:        false,
+		},
+		{
+			name:        "path equals allowed dir exactly",
+			filePath:    "/downloads",
+			allowedDirs: []string{"/downloads"},
+			want:        true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isAllowedStreamPath(tt.filePath, tt.allowedDirs...)
+			if got != tt.want {
+				t.Errorf("isAllowedStreamPath(%q, %v) = %v, want %v",
+					tt.filePath, tt.allowedDirs, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFormatSpeedLog(t *testing.T) {
+	tests := []struct {
+		bps  int64
+		want string
+	}{
+		{0, "0 B/s"},
+		{500, "500 B/s"},
+		{1023, "1023 B/s"},
+		{1024, "1 KB/s"},
+		{10240, "10 KB/s"},
+		{1048576, "1.0 MB/s"},
+		{5242880, "5.0 MB/s"},
+		{1073741824, "1.0 GB/s"},
+		{2147483648, "2.0 GB/s"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.want, func(t *testing.T) {
+			got := formatSpeedLog(tt.bps)
+			if got != tt.want {
+				t.Errorf("formatSpeedLog(%d) = %q, want %q", tt.bps, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/internal/cmd/download.go b/internal/cmd/download.go
index 98e77d5..bd5ceab 100644
--- a/internal/cmd/download.go
+++ b/internal/cmd/download.go
@@ -17,6 +17,26 @@ import (
 	"github.com/torrentclaw/unarr/internal/parser"
 )
 
+// downloadDeps agrupa las funciones constructoras usadas por runDownload.
+// Pueden sobreescribirse en tests para inyectar mocks.
+type downloadDeps struct {
+	newTorrentDl   func(cfg engine.TorrentConfig) (engine.Downloader, error)
+	newDebridDl    func() engine.Downloader
+	newAgentClient func(url, key, ua string) *agent.Client
+	newManager     func(cfg engine.ManagerConfig, reporter *engine.ProgressReporter, dls ...engine.Downloader) *engine.Manager
+}
+
+var defaultDownloadDeps = downloadDeps{
+	newTorrentDl: func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+		return engine.NewTorrentDownloader(cfg)
+	},
+	newDebridDl: func() engine.Downloader {
+		return engine.NewDebridDownloader()
+	},
+	newAgentClient: agent.NewClient,
+	newManager:     engine.NewManager,
+}
+
 func newDownloadCmd() *cobra.Command {
 	var method string
 
@@ -48,6 +68,10 @@ daemon instead: 'unarr start'.`,
 }
 
 func runDownload(input, method string) error {
+	return runDownloadWithDeps(input, method, defaultDownloadDeps)
+}
+
+func runDownloadWithDeps(input, method string, deps downloadDeps) error {
 	cfg := loadConfig()
 	bold := color.New(color.Bold)
 	green := color.New(color.FgGreen)
@@ -84,7 +108,7 @@ func runDownload(input, method string) error {
 	fmt.Println()
 
 	// Create torrent downloader
-	torrentDl, err := engine.NewTorrentDownloader(engine.TorrentConfig{
+	torrentDl, err := deps.newTorrentDl(engine.TorrentConfig{
 		DataDir:         outputDir,
 		MetadataTimeout: 15 * time.Minute,
 		StallTimeout:    10 * time.Minute,
@@ -97,19 +121,20 @@ func runDownload(input, method string) error {
 
 	// Create a dummy reporter (no API reporting for one-shot)
 	reporter := engine.NewProgressReporter(
-		agent.NewClient(cfg.Auth.APIURL, cfg.Auth.APIKey, "unarr/"+Version),
+		deps.newAgentClient(cfg.Auth.APIURL, cfg.Auth.APIKey, "unarr/"+Version),
 		5*time.Second,
 	)
 
-	debridDl := engine.NewDebridDownloader()
+	debridDl := deps.newDebridDl()
 
-	manager := engine.NewManager(engine.ManagerConfig{
+	manager := deps.newManager(engine.ManagerConfig{
 		MaxConcurrent: 1,
 		OutputDir:     outputDir,
 		Organize: engine.OrganizeConfig{
 			Enabled:    cfg.Organize.Enabled,
 			MoviesDir:  cfg.Organize.MoviesDir,
 			TVShowsDir: cfg.Organize.TVShowsDir,
+			OutputDir:  outputDir,
 		},
 	}, reporter, torrentDl, debridDl)
 
diff --git a/internal/cmd/download_test.go b/internal/cmd/download_test.go
new file mode 100644
index 0000000..18bcc1c
--- /dev/null
+++ b/internal/cmd/download_test.go
@@ -0,0 +1,397 @@
+package cmd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/engine"
+)
+
+// --- Mocks para tests del comando download ---
+
+// testDownloader implementa engine.Downloader para tests.
+type testDownloader struct {
+	method    engine.DownloadMethod
+	available bool
+	filePath  string // archivo a devolver como resultado
+	err       error  // si != nil, Download() devuelve este error
+}
+
+func (d *testDownloader) Method() engine.DownloadMethod { return d.method }
+func (d *testDownloader) Available(_ context.Context, _ *engine.Task) (bool, error) {
+	return d.available, nil
+}
+func (d *testDownloader) Download(_ context.Context, _ *engine.Task, _ string, _ chan<- engine.Progress) (*engine.Result, error) {
+	if d.err != nil {
+		return nil, d.err
+	}
+	return &engine.Result{
+		FilePath: d.filePath,
+		FileName: filepath.Base(d.filePath),
+		Method:   d.method,
+		Size:     1024,
+	}, nil
+}
+func (d *testDownloader) Pause(_ string) error             { return nil }
+func (d *testDownloader) Cancel(_ string) error            { return nil }
+func (d *testDownloader) Shutdown(_ context.Context) error { return nil }
+
+// makeDepsWithDownloader crea un downloadDeps con un downloader mockeado.
+func makeDepsWithDownloader(dl engine.Downloader) downloadDeps {
+	return downloadDeps{
+		newTorrentDl: func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+			return dl, nil
+		},
+		newDebridDl: func() engine.Downloader {
+			return &testDownloader{method: engine.MethodDebrid, available: false}
+		},
+		newAgentClient: func(url, key, ua string) *agent.Client {
+			return agent.NewClient("http://localhost", "", "test")
+		},
+		newManager: engine.NewManager,
+	}
+}
+
+// --- Tests de validación de entrada ---
+
+func TestRunDownload_EmptyInput(t *testing.T) {
+	err := runDownload("", "torrent")
+	if err == nil {
+		t.Fatal("expected error for empty input")
+	}
+}
+
+func TestRunDownload_InvalidHash_TooShort(t *testing.T) {
+	err := runDownload("abc123", "torrent")
+	if err == nil {
+		t.Fatal("expected error for hash that is too short")
+	}
+	if !strings.Contains(err.Error(), "invalid") {
+		t.Errorf("error = %q, want 'invalid' in message", err.Error())
+	}
+}
+
+func TestRunDownload_InvalidHash_NotHex_TooLong(t *testing.T) {
+	// 41 caracteres pero comienza con "magnet:" no → tampoco es un hash válido de 40 chars
+	err := runDownload("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "torrent") // 41 chars
+	if err == nil {
+		t.Fatal("expected error for 41-char string (not a valid hash)")
+	}
+}
+
+func TestRunDownload_ValidHash_40Chars(t *testing.T) {
+	// Un hash de 40 chars hex válido debe pasar la validación
+	// Usa deps que fallan inmediatamente para no necesitar red
+	deps := downloadDeps{
+		newTorrentDl: func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+			return nil, fmt.Errorf("test: stopping after validation")
+		},
+		newDebridDl: func() engine.Downloader {
+			return &testDownloader{method: engine.MethodDebrid}
+		},
+		newAgentClient: func(url, key, ua string) *agent.Client {
+			return agent.NewClient("http://localhost", "", "test")
+		},
+		newManager: engine.NewManager,
+	}
+
+	err := runDownloadWithDeps("abc123def456abc123def456abc123def456abc1", "torrent", deps)
+	// El error debe ser del downloader (no de validación)
+	if err == nil {
+		t.Fatal("expected error from newTorrentDl")
+	}
+	if strings.Contains(err.Error(), "invalid input") || strings.Contains(err.Error(), "invalid info hash") {
+		t.Errorf("error = %q — should not be a validation error, hash is valid", err.Error())
+	}
+}
+
+func TestRunDownload_InvalidInput_NotMagnetNotHash(t *testing.T) {
+	// Texto libre que no es ni hash ni magnet
+	err := runDownload("The Matrix 1999", "torrent")
+	if err == nil {
+		t.Fatal("expected error for plain text input")
+	}
+	if !strings.Contains(err.Error(), "invalid") {
+		t.Errorf("error = %q, want 'invalid' in message", err.Error())
+	}
+}
+
+func TestRunDownload_InvalidInput_PartialMagnet(t *testing.T) {
+	// Prefix de magnet pero incompleto
+	err := runDownload("magnet:", "torrent")
+	if err == nil {
+		t.Fatal("expected error for incomplete magnet URI (no hash)")
+	}
+}
+
+// --- Tests con mock downloader ---
+
+func TestRunDownload_Success(t *testing.T) {
+	dir := t.TempDir()
+	filePath := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(filePath, make([]byte, 1024), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	dl := &testDownloader{
+		method:    engine.MethodTorrent,
+		available: true,
+		filePath:  filePath,
+	}
+
+	deps := makeDepsWithDownloader(dl)
+	// Sobreescribir outputDir usando config vacía (usa home por defecto)
+	// Para un test determinista, usar una config con dir específico
+	deps.newTorrentDl = func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+		// Actualizar filePath al outputDir real
+		realPath := filepath.Join(cfg.DataDir, "movie.mkv")
+		os.WriteFile(realPath, make([]byte, 1024), 0o644) //nolint:errcheck
+		return &testDownloader{
+			method:    engine.MethodTorrent,
+			available: true,
+			filePath:  realPath,
+		}, nil
+	}
+
+	err := runDownloadWithDeps("abc123def456abc123def456abc123def456abc1", "torrent", deps)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestRunDownload_DownloaderCreationFails(t *testing.T) {
+	deps := downloadDeps{
+		newTorrentDl: func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+			return nil, fmt.Errorf("failed to create torrent client")
+		},
+		newDebridDl: func() engine.Downloader {
+			return &testDownloader{method: engine.MethodDebrid}
+		},
+		newAgentClient: func(url, key, ua string) *agent.Client {
+			return agent.NewClient("http://localhost", "", "test")
+		},
+		newManager: engine.NewManager,
+	}
+
+	err := runDownloadWithDeps("abc123def456abc123def456abc123def456abc1", "torrent", deps)
+	if err == nil {
+		t.Fatal("expected error when downloader creation fails")
+	}
+	if !strings.Contains(err.Error(), "create downloader") {
+		t.Errorf("error = %q, want 'create downloader' in message", err.Error())
+	}
+}
+
+func TestRunDownload_DownloadFails(t *testing.T) {
+	dl := &testDownloader{
+		method:    engine.MethodTorrent,
+		available: true,
+		err:       errors.New("torrent: no peers"),
+	}
+
+	deps := makeDepsWithDownloader(dl)
+	// Sin fallback (método específico "torrent"), el fallo se propaga
+	err := runDownloadWithDeps("abc123def456abc123def456abc123def456abc1", "torrent", deps)
+	// El download falla pero runDownload puede retornar nil (el manager registra el fallo)
+	// Lo importante es que no haga panic
+	_ = err
+}
+
+func TestRunDownload_Method_Torrent(t *testing.T) {
+	var capturedTask agent.Task
+	dl := &capturingTestDownloader{
+		method:      engine.MethodTorrent,
+		capturedFn:  func(t agent.Task) { capturedTask = t },
+		resultDir:   t.TempDir(),
+		resultFile:  "movie.mkv",
+		resultBytes: make([]byte, 512),
+	}
+
+	deps := downloadDeps{
+		newTorrentDl: func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+			return dl, nil
+		},
+		newDebridDl: func() engine.Downloader {
+			return &testDownloader{method: engine.MethodDebrid}
+		},
+		newAgentClient: func(url, key, ua string) *agent.Client {
+			return agent.NewClient("http://localhost", "", "test")
+		},
+		newManager: engine.NewManager,
+	}
+
+	os.WriteFile(filepath.Join(dl.resultDir, dl.resultFile), dl.resultBytes, 0o644) //nolint:errcheck
+
+	runDownloadWithDeps("abc123def456abc123def456abc123def456abc1", "torrent", deps) //nolint:errcheck
+
+	if capturedTask.PreferredMethod != "torrent" {
+		t.Errorf("PreferredMethod = %q, want torrent", capturedTask.PreferredMethod)
+	}
+}
+
+func TestRunDownload_Method_Debrid(t *testing.T) {
+	var capturedTask agent.Task
+
+	resultDir := t.TempDir()
+	resultFile := filepath.Join(resultDir, "movie.mkv")
+	os.WriteFile(resultFile, make([]byte, 512), 0o644) //nolint:errcheck
+
+	capFn := func(task agent.Task) { capturedTask = task }
+
+	deps := downloadDeps{
+		newTorrentDl: func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+			// Torrent no disponible: fuerza el uso del método debrid
+			return &testDownloader{method: engine.MethodTorrent, available: false}, nil
+		},
+		newDebridDl: func() engine.Downloader {
+			// Debrid disponible y captura la tarea
+			return &capturingTestDownloader{
+				method:      engine.MethodDebrid,
+				capturedFn:  capFn,
+				resultDir:   resultDir,
+				resultFile:  "movie.mkv",
+				resultBytes: make([]byte, 512),
+			}
+		},
+		newAgentClient: func(url, key, ua string) *agent.Client {
+			return agent.NewClient("http://localhost", "", "test")
+		},
+		newManager: engine.NewManager,
+	}
+
+	runDownloadWithDeps("abc123def456abc123def456abc123def456abc1", "debrid", deps) //nolint:errcheck
+
+	if capturedTask.PreferredMethod != "debrid" {
+		t.Errorf("PreferredMethod = %q, want debrid", capturedTask.PreferredMethod)
+	}
+}
+
+func TestRunDownload_OutputDirCreated(t *testing.T) {
+	// Verificar que el dir de salida se crea aunque no exista
+	downloadDir := filepath.Join(t.TempDir(), "new-subdir", "downloads")
+	// No crear el directorio — runDownload debe hacerlo
+
+	deps := downloadDeps{
+		newTorrentDl: func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+			// Una vez creado el dir, podemos retornar error para terminar
+			if _, err := os.Stat(cfg.DataDir); err != nil {
+				return nil, fmt.Errorf("output dir was not created")
+			}
+			return nil, fmt.Errorf("stopping after dir check")
+		},
+		newDebridDl: func() engine.Downloader {
+			return &testDownloader{method: engine.MethodDebrid}
+		},
+		newAgentClient: func(url, key, ua string) *agent.Client {
+			return agent.NewClient("http://localhost", "", "test")
+		},
+		newManager: engine.NewManager,
+	}
+
+	// Necesitamos que cfg.Download.Dir apunte a nuestro dir de test
+	// loadConfig() usará el default, así que testeamos la creación del dir
+	// Alternativa: verificar que si el dir ya existe, no falla
+	_ = deps
+	_ = downloadDir
+	// Este test documenta la intención aunque no pueda inyectar el dir fácilmente
+	// sin refactorizar loadConfig(). El comportamiento se testa indirectamente.
+	t.Skip("requiere inyección de config — comportamiento cubierto por tests de integración")
+}
+
+func TestRunDownloadCmd_Args_TooFew(t *testing.T) {
+	cmd := newDownloadCmd()
+	// Sin argumentos → cobra debe devolver error
+	err := cmd.Args(cmd, []string{})
+	if err == nil {
+		t.Fatal("expected error for 0 args")
+	}
+}
+
+func TestRunDownloadCmd_Args_TooMany(t *testing.T) {
+	cmd := newDownloadCmd()
+	err := cmd.Args(cmd, []string{"hash1", "hash2"})
+	if err == nil {
+		t.Fatal("expected error for 2 args")
+	}
+}
+
+func TestRunDownloadCmd_Args_ExactlyOne(t *testing.T) {
+	cmd := newDownloadCmd()
+	err := cmd.Args(cmd, []string{"abc123def456abc123def456abc123def456abc1"})
+	if err != nil {
+		t.Errorf("unexpected error for 1 arg: %v", err)
+	}
+}
+
+// capturingTestDownloader captura la tarea recibida para verificar los flags.
+type capturingTestDownloader struct {
+	method      engine.DownloadMethod
+	capturedFn  func(agent.Task)
+	resultDir   string
+	resultFile  string
+	resultBytes []byte
+}
+
+func (d *capturingTestDownloader) Method() engine.DownloadMethod { return d.method }
+func (d *capturingTestDownloader) Available(_ context.Context, _ *engine.Task) (bool, error) {
+	return true, nil
+}
+func (d *capturingTestDownloader) Download(_ context.Context, task *engine.Task, _ string, _ chan<- engine.Progress) (*engine.Result, error) {
+	if d.capturedFn != nil {
+		d.capturedFn(agent.Task{
+			ID:              task.ID,
+			PreferredMethod: task.PreferredMethod,
+		})
+	}
+	filePath := filepath.Join(d.resultDir, d.resultFile)
+	return &engine.Result{
+		FilePath: filePath,
+		FileName: d.resultFile,
+		Method:   d.method,
+		Size:     int64(len(d.resultBytes)),
+	}, nil
+}
+func (d *capturingTestDownloader) Pause(_ string) error             { return nil }
+func (d *capturingTestDownloader) Cancel(_ string) error            { return nil }
+func (d *capturingTestDownloader) Shutdown(_ context.Context) error { return nil }
+
+// TestRunDownload_QuickFail_NoDeadlock verifica que cuando el downloader falla
+// rápidamente, runDownload retorna sin deadlock.
+func TestRunDownload_QuickFail_NoDeadlock(t *testing.T) {
+	deps := downloadDeps{
+		newTorrentDl: func(cfg engine.TorrentConfig) (engine.Downloader, error) {
+			return &testDownloader{
+				method:    engine.MethodTorrent,
+				available: true,
+				err:       errors.New("no peers found"),
+			}, nil
+		},
+		newDebridDl: func() engine.Downloader {
+			return &testDownloader{method: engine.MethodDebrid, available: false}
+		},
+		newAgentClient: func(url, key, ua string) *agent.Client {
+			return agent.NewClient("http://localhost", "", "test")
+		},
+		newManager: engine.NewManager,
+	}
+
+	done := make(chan struct{}, 1)
+	go func() {
+		runDownloadWithDeps("abc123def456abc123def456abc123def456abc1", "torrent", deps) //nolint:errcheck
+		done <- struct{}{}
+	}()
+
+	select {
+	case <-done:
+		// OK, terminó sin deadlock
+	case <-time.After(10 * time.Second):
+		t.Fatal("runDownload did not return within 10s — possible deadlock")
+	}
+}
diff --git a/internal/cmd/funnel.go b/internal/cmd/funnel.go
new file mode 100644
index 0000000..5ce793d
--- /dev/null
+++ b/internal/cmd/funnel.go
@@ -0,0 +1,165 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+func newFunnelCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "funnel",
+		Short: "Expose the daemon over a public HTTPS hostname via CloudFlare Quick Tunnel",
+		Long: `Turn the CloudFlare Quick Tunnel on/off and check its status.
+
+When on, the daemon spawns cloudflared as a child process and registers a
+` + "`https://<random>.trycloudflare.com`" + ` hostname tunnelled to its local
+HLS server. The torrentclaw.com / torrentclaw.to web player picks the tunnel
+URL first so cross-network playback works from any browser without Tailscale
+or port forwarding.
+
+Trade-offs:
+  • Bytes proxy through CloudFlare. We don't relay; CF does. Preserves the
+    TorrentClaw legal posture but means CF sees your traffic shape.
+  • Quick Tunnels are anonymous — no CF account required.
+  • Hostname is random per session and rotates roughly every 6 h.
+
+Requires the cloudflared binary on PATH. Install:
+  Linux  : https://pkg.cloudflare.com (apt) or download from
+           https://github.com/cloudflare/cloudflared/releases
+  macOS  : brew install cloudflared
+  Windows: winget install --id Cloudflare.cloudflared`,
+		Example: `  unarr funnel status   # is the tunnel up? what's the URL?
+  unarr funnel on       # turn it on
+  unarr funnel off      # turn it off`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Help()
+		},
+	}
+	cmd.AddCommand(newFunnelStatusCmd(), newFunnelOnCmd(), newFunnelOffCmd())
+	return cmd
+}
+
+func newFunnelStatusCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "status",
+		Short:   "Show CloudFlare tunnel configuration + live URL",
+		Example: "  unarr funnel status",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runFunnelStatus()
+		},
+	}
+}
+
+func runFunnelStatus() error {
+	bold := color.New(color.Bold)
+	dim := color.New(color.FgHiBlack)
+	green := color.New(color.FgGreen)
+	yellow := color.New(color.FgYellow)
+	cyan := color.New(color.FgCyan)
+
+	cfg := loadConfig()
+
+	fmt.Println()
+	bold.Println("  CloudFlare Quick Tunnel")
+	fmt.Println()
+
+	if !cfg.Download.Funnel.Enabled {
+		dim.Println("  Mode:    off")
+		fmt.Println()
+		dim.Println("  Enable with `unarr funnel on` to give the daemon a public HTTPS URL")
+		dim.Println("  so cross-network browser playback works without Tailscale.")
+		fmt.Println()
+		return nil
+	}
+	cyan.Println("  Mode:    on")
+
+	state := agent.ReadState()
+	alive := state != nil && isDaemonAlive(state)
+	fmt.Println()
+	switch {
+	case alive && state.FunnelURL != "":
+		green.Println("  ✓ Tunnel ACTIVE")
+		fmt.Printf("    URL:  %s\n", state.FunnelURL)
+		fmt.Println()
+		dim.Println("  This URL rotates roughly every 6 h. The web player picks it up")
+		dim.Println("  automatically — no action needed on your side.")
+	case alive:
+		yellow.Println("  ⚠  Daemon is running but the tunnel hasn't registered yet.")
+		dim.Println("     Check `unarr daemon logs` for a [funnel] line. Common cause:")
+		dim.Println("     cloudflared isn't installed on PATH.")
+	default:
+		dim.Println("  Daemon not running — start it (`unarr start`) to bring the tunnel up.")
+	}
+	fmt.Println()
+	return nil
+}
+
+func newFunnelOnCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "on",
+		Short:   "Turn the CloudFlare tunnel on",
+		Example: "  unarr funnel on",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return setFunnelEnabled(true)
+		},
+	}
+}
+
+func newFunnelOffCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "off",
+		Short:   "Turn the CloudFlare tunnel off",
+		Example: "  unarr funnel off",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return setFunnelEnabled(false)
+		},
+	}
+}
+
+func setFunnelEnabled(enabled bool) error {
+	green := color.New(color.FgGreen)
+	dim := color.New(color.FgHiBlack)
+
+	cfg := loadConfig()
+	if cfg.Download.Funnel.Enabled == enabled {
+		fmt.Println()
+		dim.Printf("  Tunnel is already %s — nothing to do.\n", onOffWord(enabled))
+		fmt.Println()
+		return nil
+	}
+
+	cfg.Download.Funnel.Enabled = enabled
+
+	configPath := config.FilePath()
+	if cfgFile != "" {
+		configPath = cfgFile
+	}
+	if err := config.Save(cfg, configPath); err != nil {
+		return fmt.Errorf("save config: %w", err)
+	}
+	appCfg = cfg
+
+	fmt.Println()
+	green.Printf("  ✓ CloudFlare tunnel %s.\n", onOffWord(enabled))
+
+	// Subprocess is launched/torn down by the daemon at startup; a plain config
+	// reload does not bring it up. Prompt for a restart when the daemon is alive.
+	if state := agent.ReadState(); state != nil && isDaemonAlive(state) {
+		fmt.Println()
+		dim.Println("  The daemon is running. Restart it for this to take effect:")
+		dim.Println("    unarr daemon restart")
+	}
+	fmt.Println()
+	return nil
+}
+
+func onOffWord(enabled bool) string {
+	if enabled {
+		return "on"
+	}
+	return "off"
+}
diff --git a/internal/cmd/helpers.go b/internal/cmd/helpers.go
index c51e985..4b39d5f 100644
--- a/internal/cmd/helpers.go
+++ b/internal/cmd/helpers.go
@@ -9,12 +9,21 @@ import (
 )
 
 // openBrowser opens a URL in the default browser.
+//
+// The URL is restricted to http(s) so that a hostile caller cannot trick
+// xdg-open/open into interpreting it as a flag (a leading "-" would otherwise
+// match a switch on every helper we shell out to). Where the helper supports
+// it we also append "--" to terminate switch parsing as belt-and-braces.
 func openBrowser(url string) {
+	if !isSafeBrowserURL(url) {
+		return
+	}
 	var c *exec.Cmd
 	switch runtime.GOOS {
 	case "darwin":
-		c = exec.Command("open", url)
+		c = exec.Command("open", "--", url)
 	case "windows":
+		// rundll32 does not parse switches from positional args.
 		c = exec.Command("rundll32", "url.dll,FileProtocolHandler", url)
 	default: // linux, freebsd
 		c = exec.Command("xdg-open", url)
@@ -22,6 +31,12 @@ func openBrowser(url string) {
 	_ = c.Start() // fire and forget; best-effort
 }
 
+// isSafeBrowserURL accepts only http(s) URLs. Other schemes (file://, javascript:,
+// data:, ...) and flag-shaped strings ("--help") are rejected.
+func isSafeBrowserURL(url string) bool {
+	return strings.HasPrefix(url, "http://") || strings.HasPrefix(url, "https://")
+}
+
 // defaultDownloadDir returns a sensible default download directory.
 func defaultDownloadDir() string {
 	home, _ := os.UserHomeDir()
diff --git a/internal/cmd/helpers_test.go b/internal/cmd/helpers_test.go
new file mode 100644
index 0000000..18367ce
--- /dev/null
+++ b/internal/cmd/helpers_test.go
@@ -0,0 +1,69 @@
+package cmd
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestExpandHome(t *testing.T) {
+	home, _ := os.UserHomeDir()
+
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"~/Documents", home + "/Documents"},
+		{"~/", home},
+		{"/absolute/path", "/absolute/path"},
+		{"relative/path", "relative/path"},
+		{"", ""},
+		{"~notexpanded", "~notexpanded"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got := expandHome(tt.input)
+			if got != tt.want {
+				t.Errorf("expandHome(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsSafeBrowserURL(t *testing.T) {
+	good := []string{
+		"http://localhost:3000",
+		"https://torrentclaw.com/some/path?q=1",
+	}
+	bad := []string{
+		"--help",
+		"-version",
+		"file:///etc/passwd",
+		"javascript:alert(1)",
+		"data:text/html,foo",
+		"ftp://example.com",
+		"",
+	}
+	for _, u := range good {
+		if !isSafeBrowserURL(u) {
+			t.Errorf("isSafeBrowserURL(%q) = false, want true", u)
+		}
+	}
+	for _, u := range bad {
+		if isSafeBrowserURL(u) {
+			t.Errorf("isSafeBrowserURL(%q) = true, want false", u)
+		}
+	}
+}
+
+func TestDefaultDownloadDir(t *testing.T) {
+	dir := defaultDownloadDir()
+	if dir == "" {
+		t.Error("defaultDownloadDir() returned empty string")
+	}
+	home, _ := os.UserHomeDir()
+	if !strings.HasPrefix(dir, home) {
+		t.Errorf("defaultDownloadDir() = %q, expected to start with home dir %q", dir, home)
+	}
+}
diff --git a/internal/cmd/init.go b/internal/cmd/init.go
index 2bbb521..9e7a8ca 100644
--- a/internal/cmd/init.go
+++ b/internal/cmd/init.go
@@ -360,18 +360,8 @@ func runInit(apiURLOverride string) error {
 	fmt.Println()
 
 	// Features summary
-	features := []string{}
-	if resp.Features.Torrent {
-		features = append(features, "Torrent")
-	}
-	if resp.Features.Debrid {
-		features = append(features, "Debrid")
-	}
-	if resp.Features.Usenet {
-		features = append(features, "Usenet")
-	}
-	if len(features) > 0 {
-		cyan.Printf("  Available:  %s\n", strings.Join(features, ", "))
+	if line := formatFeatures(resp.Features); line != "" {
+		cyan.Printf("  Available:  %s\n", line)
 	}
 
 	if !installDaemon {
diff --git a/internal/cmd/login.go b/internal/cmd/login.go
new file mode 100644
index 0000000..6ecfd0a
--- /dev/null
+++ b/internal/cmd/login.go
@@ -0,0 +1,187 @@
+package cmd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"runtime"
+	"strings"
+
+	"github.com/charmbracelet/huh"
+	"github.com/fatih/color"
+	"github.com/google/uuid"
+	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+func newLoginCmd() *cobra.Command {
+	var apiURL string
+
+	cmd := &cobra.Command{
+		Use:     "login",
+		Aliases: []string{"auth"},
+		Short:   "Authenticate with your torrentclaw account",
+		Long: `Log in to your torrentclaw account by opening the browser or pasting
+your API key manually. Use this when your API key has expired, been
+revoked, or you want to switch to a different account.
+
+Unlike 'unarr init', this command only updates your authentication
+credentials — it does not modify your download directory, daemon
+settings, or other configuration.`,
+		Example: `  unarr login
+  unarr login --api-url https://custom.server.com`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runLogin(apiURL)
+		},
+	}
+
+	cmd.Flags().StringVar(&apiURL, "api-url", "", "API URL override (default: https://torrentclaw.com)")
+
+	return cmd
+}
+
+func runLogin(apiURLOverride string) error {
+	if !isTerminal() {
+		return fmt.Errorf("interactive mode requires a terminal (use UNARR_API_KEY env var instead)")
+	}
+
+	bold := color.New(color.Bold)
+	green := color.New(color.FgGreen)
+	dim := color.New(color.FgHiBlack)
+
+	fmt.Println()
+	bold.Println("  unarr login")
+	fmt.Println()
+
+	cfg := loadConfig()
+
+	// Determine API URL
+	apiURL := cfg.Auth.APIURL
+	if apiURLOverride != "" {
+		apiURL = apiURLOverride
+	}
+	if apiURL == "" {
+		apiURL = "https://torrentclaw.com"
+	}
+
+	// ── Authenticate ────────────────────────────────────────────────
+
+	var apiKey string
+
+	// Try browser-based auth first
+	fmt.Println("  Opening browser to connect your account...")
+	fmt.Println()
+
+	browserKey, browserErr := browserAuth(apiURL)
+	if browserErr == nil && strings.HasPrefix(browserKey, "tc_") {
+		apiKey = browserKey
+		green.Println("  ✓ Connected via browser")
+		fmt.Println()
+	} else {
+		// Fallback to manual API key entry
+		if browserErr != nil {
+			dim.Printf("  Could not connect automatically: %s\n", browserErr)
+		}
+		fmt.Println("  Paste your API key instead:")
+		dim.Printf("  (get it from %s/profile?tab=apikey)\n", apiURL)
+		fmt.Println()
+
+		err := huh.NewForm(
+			huh.NewGroup(
+				huh.NewInput().
+					Title("API Key").
+					Placeholder("tc_...").
+					Value(&apiKey).
+					Validate(func(s string) error {
+						s = strings.TrimSpace(s)
+						if s == "" {
+							return fmt.Errorf("API key is required")
+						}
+						if !strings.HasPrefix(s, "tc_") {
+							return fmt.Errorf("API key should start with tc_")
+						}
+						return nil
+					}),
+			),
+		).Run()
+		if err != nil {
+			if errors.Is(err, huh.ErrUserAborted) {
+				fmt.Println("\n  Login cancelled.")
+				return nil
+			}
+			return err
+		}
+		apiKey = strings.TrimSpace(apiKey)
+	}
+
+	// ── Validate API key ────────────────────────────────────────────
+
+	fmt.Print("  Verifying API key... ")
+
+	agentID := cfg.Agent.ID
+	if agentID == "" {
+		agentID = uuid.New().String()
+	}
+
+	hostname, _ := os.Hostname()
+	agentName := cfg.Agent.Name
+	if agentName == "" {
+		agentName = hostname
+	}
+
+	ac := agent.NewClient(apiURL, apiKey, "unarr/"+Version)
+	resp, err := ac.Register(context.Background(), agent.RegisterRequest{
+		AgentID:     agentID,
+		Name:        agentName,
+		OS:          runtime.GOOS,
+		Arch:        runtime.GOARCH,
+		Version:     Version,
+		DownloadDir: cfg.Download.Dir,
+	})
+	if err != nil {
+		color.Red("FAILED")
+		fmt.Println()
+		return fmt.Errorf("API key validation failed: %w", err)
+	}
+
+	green.Println("OK")
+	fmt.Printf("  Connected as %s (%s) [%s]\n", resp.User.Name, resp.User.Email, strings.ToUpper(resp.User.Plan))
+	fmt.Println()
+
+	// ── Save config (auth fields only) ──────────────────────────────
+
+	cfg.Auth.APIKey = apiKey
+	cfg.Auth.APIURL = apiURL
+	cfg.Agent.ID = agentID
+	cfg.Agent.Name = agentName
+
+	configPath := config.FilePath()
+	if cfgFile != "" {
+		configPath = cfgFile
+	}
+
+	if err := config.Save(cfg, configPath); err != nil {
+		return fmt.Errorf("save config: %w", err)
+	}
+	appCfg = cfg
+
+	fmt.Println()
+	green.Println("  ✓ Credentials saved!")
+	fmt.Printf("  Config: %s\n", configPath)
+	fmt.Println()
+
+	// Features summary
+	if line := formatFeatures(resp.Features); line != "" {
+		color.New(color.FgCyan).Printf("  Available:  %s\n", line)
+		fmt.Println()
+	}
+
+	if cfg.Download.Dir == "" {
+		fmt.Println("  Run " + bold.Sprint("unarr init") + " to complete the setup (download directory, daemon).")
+		fmt.Println()
+	}
+
+	return nil
+}
diff --git a/internal/cmd/mirrors.go b/internal/cmd/mirrors.go
new file mode 100644
index 0000000..76870a7
--- /dev/null
+++ b/internal/cmd/mirrors.go
@@ -0,0 +1,204 @@
+package cmd
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+// newMirrorsCmd wires `unarr mirrors` and its subcommands.
+//
+// Mirrors are alternate base URLs the agent can fall back to when the
+// primary api_url is unreachable. The pool is consulted on every transient
+// network failure (DNS, refused, timeout, 5xx) — see internal/agent/
+// mirror_pool.go for the rotation rules.
+func newMirrorsCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "mirrors",
+		Short: "Manage TorrentClaw mirror failover list",
+		Long: `Mirrors are alternate base URLs the agent falls back to when the primary
+domain is unreachable. The pool survives DNS blocks, ISP filters, and
+short-lived takedowns without restarting the agent.
+
+Examples:
+  unarr mirrors list          Print currently configured mirrors
+  unarr mirrors update        Refresh from the server's canonical list
+  unarr mirrors test          Probe every configured mirror`,
+	}
+
+	cmd.AddCommand(newMirrorsListCmd())
+	cmd.AddCommand(newMirrorsUpdateCmd())
+	cmd.AddCommand(newMirrorsTestCmd())
+	return cmd
+}
+
+func newMirrorsListCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "list",
+		Short: "Print currently configured mirrors",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg := loadConfig()
+			pool := agent.NewMirrorPool(cfg.Auth.APIURL, cfg.Auth.Mirrors)
+
+			if jsonOut {
+				out := map[string]any{
+					"primary": cfg.Auth.APIURL,
+					"mirrors": pool.Mirrors(),
+				}
+				return json.NewEncoder(os.Stdout).Encode(out)
+			}
+
+			fmt.Printf("Primary: %s\n", color.GreenString(cfg.Auth.APIURL))
+			if len(cfg.Auth.Mirrors) == 0 {
+				fmt.Println("Fallbacks: (none configured — run `unarr mirrors update`)")
+				return nil
+			}
+			fmt.Println("Fallbacks:")
+			for i, m := range cfg.Auth.Mirrors {
+				fmt.Printf("  %d. %s\n", i+1, m)
+			}
+			return nil
+		},
+	}
+}
+
+func newMirrorsUpdateCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "update",
+		Short: "Refresh the mirror list from the server",
+		Long: `Fetch /api/v1/mirrors from the configured primary (with fallback to any
+currently-known mirrors) and write the resulting list back to config.toml.
+
+This is how long-running agents survive a takedown of the primary domain:
+the user runs ` + "`unarr mirrors update`" + ` once a week (or via cron), and
+the agent transparently picks up new mirrors without a CLI release.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg := loadConfig()
+
+			// Candidate set: primary + any currently-known mirrors. Order matters —
+			// we try primary first so the most-trusted endpoint wins.
+			candidates := append([]string{cfg.Auth.APIURL}, cfg.Auth.Mirrors...)
+
+			ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+			defer cancel()
+
+			fmt.Println("Refreshing mirror list...")
+			resp, err := agent.FetchMirrorsWithFallback(ctx, candidates, "unarr/"+Version)
+			if err != nil {
+				return fmt.Errorf("fetch mirrors: %w", err)
+			}
+
+			primary, extras := resp.ToConfig()
+			if primary == "" {
+				return fmt.Errorf("server returned no mirrors")
+			}
+
+			// Track what changed so we can give the user a clear diff.
+			added, removed := diffMirrors(append([]string{cfg.Auth.APIURL}, cfg.Auth.Mirrors...), append([]string{primary}, extras...))
+
+			cfg.Auth.APIURL = primary
+			cfg.Auth.Mirrors = extras
+			if err := config.Save(cfg, cfgFile); err != nil {
+				return fmt.Errorf("save config: %w", err)
+			}
+
+			fmt.Printf("%s revision %d (%d mirror%s)\n",
+				color.GreenString("✓"), resp.Revision, len(resp.Mirrors), pluralS(len(resp.Mirrors)))
+			fmt.Printf("  Primary:   %s\n", primary)
+			if len(extras) > 0 {
+				fmt.Printf("  Fallbacks: %s\n", strings.Join(extras, ", "))
+			}
+			if resp.Tor != nil {
+				fmt.Printf("  Tor:       %s\n", resp.Tor.URL)
+			}
+			for _, c := range resp.Channels {
+				fmt.Printf("  Channel:   %s — %s\n", c.Label, c.URL)
+			}
+			if len(added) > 0 {
+				fmt.Printf("  %s %s\n", color.GreenString("added:"), strings.Join(added, ", "))
+			}
+			if len(removed) > 0 {
+				fmt.Printf("  %s %s\n", color.YellowString("removed:"), strings.Join(removed, ", "))
+			}
+			return nil
+		},
+	}
+}
+
+func newMirrorsTestCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "test",
+		Short: "Probe every configured mirror",
+		Long: `Performs a small unauthenticated HEAD/GET against /api/health on every
+configured mirror and reports latency + reachability.`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg := loadConfig()
+			all := append([]string{cfg.Auth.APIURL}, cfg.Auth.Mirrors...)
+			if len(all) == 0 {
+				return fmt.Errorf("no mirrors configured")
+			}
+
+			for _, base := range all {
+				if base == "" {
+					continue
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), 6*time.Second)
+				start := time.Now()
+				_, err := agent.FetchMirrors(ctx, []string{base}, "unarr/"+Version)
+				cancel()
+				elapsed := time.Since(start)
+				if err != nil {
+					fmt.Printf("  %s %s — %s (%s)\n", color.RedString("✗"), base, err, elapsed.Round(time.Millisecond))
+					continue
+				}
+				fmt.Printf("  %s %s (%s)\n", color.GreenString("✓"), base, elapsed.Round(time.Millisecond))
+			}
+			return nil
+		},
+	}
+}
+
+// diffMirrors returns the URLs added and removed between two ordered lists.
+// Used to print a friendly diff after `unarr mirrors update`.
+func diffMirrors(old, fresh []string) (added, removed []string) {
+	oldSet := make(map[string]struct{}, len(old))
+	for _, m := range old {
+		if m != "" {
+			oldSet[m] = struct{}{}
+		}
+	}
+	freshSet := make(map[string]struct{}, len(fresh))
+	for _, m := range fresh {
+		if m == "" {
+			continue
+		}
+		freshSet[m] = struct{}{}
+		if _, ok := oldSet[m]; !ok {
+			added = append(added, m)
+		}
+	}
+	for _, m := range old {
+		if m == "" {
+			continue
+		}
+		if _, ok := freshSet[m]; !ok {
+			removed = append(removed, m)
+		}
+	}
+	return added, removed
+}
+
+func pluralS(n int) string {
+	if n == 1 {
+		return ""
+	}
+	return "s"
+}
diff --git a/internal/cmd/player_session_registry.go b/internal/cmd/player_session_registry.go
new file mode 100644
index 0000000..bb3743b
--- /dev/null
+++ b/internal/cmd/player_session_registry.go
@@ -0,0 +1,96 @@
+package cmd
+
+import (
+	"context"
+	"sync"
+
+	"github.com/torrentclaw/unarr/internal/config"
+	"github.com/torrentclaw/unarr/internal/engine"
+	"github.com/torrentclaw/unarr/internal/library/mediainfo"
+)
+
+// playerSessionRegistry tracks per-session cancel funcs for active in-browser
+// HLS streaming sessions. Each session lives only as long as its ffmpeg
+// process; the registry exists so duplicate sync responses don't double-spawn
+// the same session and so daemon shutdown can drain.
+var playerSessionRegistry = &playerSessionRegistryT{
+	cancels: make(map[string]context.CancelFunc),
+}
+
+type playerSessionRegistryT struct {
+	mu      sync.Mutex
+	cancels map[string]context.CancelFunc
+}
+
+func (r *playerSessionRegistryT) has(sessionID string) bool {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	_, ok := r.cancels[sessionID]
+	return ok
+}
+
+func (r *playerSessionRegistryT) add(sessionID string, cancel context.CancelFunc) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.cancels[sessionID] = cancel
+}
+
+func (r *playerSessionRegistryT) remove(sessionID string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	delete(r.cancels, sessionID)
+}
+
+// cancelAllPlayerSessions cancels every running session. Called on daemon
+// shutdown so the ffmpeg children and SSE consumers exit cleanly.
+func cancelAllPlayerSessions() {
+	playerSessionRegistry.mu.Lock()
+	cancels := make([]context.CancelFunc, 0, len(playerSessionRegistry.cancels))
+	for _, c := range playerSessionRegistry.cancels {
+		cancels = append(cancels, c)
+	}
+	playerSessionRegistry.cancels = make(map[string]context.CancelFunc)
+	playerSessionRegistry.mu.Unlock()
+	for _, c := range cancels {
+		c()
+	}
+}
+
+// buildTranscodeRuntime resolves the ffmpeg/ffprobe binaries + config knobs
+// for the HLS streaming pipeline. Failure to resolve a binary returns a
+// runtime with empty paths so the caller can short-circuit instead of
+// launching a transcoder that will immediately fail.
+func buildTranscodeRuntime(ctx context.Context, cfg config.Config) engine.TranscodeRuntime {
+	if !cfg.Download.Transcode.Enabled {
+		return engine.TranscodeRuntime{Disabled: true}
+	}
+	ffmpegPath, errF := mediainfo.ResolveFFmpeg(cfg.Library.FFmpegPath)
+	ffprobePath, errP := mediainfo.ResolveFFprobe(cfg.Library.FFprobePath)
+	if errF != nil || errP != nil {
+		return engine.TranscodeRuntime{Disabled: true}
+	}
+	hw := engine.HWAccelNone
+	switch cfg.Download.Transcode.HWAccel {
+	case "auto":
+		hw = engine.DetectHWAccel(ctx, ffmpegPath)
+	case "nvenc":
+		hw = engine.HWAccelNVENC
+	case "qsv":
+		hw = engine.HWAccelQSV
+	case "vaapi":
+		hw = engine.HWAccelVAAPI
+	case "videotoolbox":
+		hw = engine.HWAccelVideoToolbox
+	case "none", "":
+		hw = engine.HWAccelNone
+	}
+	return engine.TranscodeRuntime{
+		FFmpegPath:   ffmpegPath,
+		FFprobePath:  ffprobePath,
+		HWAccel:      hw,
+		Preset:       cfg.Download.Transcode.Preset,
+		VideoBitrate: cfg.Download.Transcode.VideoBitrate,
+		AudioBitrate: cfg.Download.Transcode.AudioBitrate,
+		MaxHeight:    cfg.Download.Transcode.MaxHeight,
+	}
+}
diff --git a/internal/cmd/probe_hwaccel.go b/internal/cmd/probe_hwaccel.go
new file mode 100644
index 0000000..609a443
--- /dev/null
+++ b/internal/cmd/probe_hwaccel.go
@@ -0,0 +1,176 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"runtime"
+	"strings"
+	"time"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/engine"
+)
+
+// newProbeHWAccelCmd reports the hardware-acceleration capabilities the daemon
+// would actually use for HLS transcoding. The motivation: a beefy host
+// (e.g. RTX 3090) can still fall back to software encoding when the installed
+// ffmpeg binary was built without nvenc/qsv/vaapi support — Homebrew ffmpeg
+// is a common offender. Without this command, users see slow / failing 4K
+// transcodes and no obvious way to diagnose where the regression sits.
+func newProbeHWAccelCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "probe-hwaccel",
+		Short: "Diagnose hardware-acceleration availability",
+		Long: `Report the hardware-acceleration backends the daemon would pick for
+transcoding, plus exactly why each one was kept or rejected.
+
+Checks performed:
+  - ffmpeg / ffprobe paths
+  - which HW encoders the ffmpeg binary supports (h264_nvenc, h264_qsv, h264_vaapi…)
+  - whether the matching device files / drivers are actually present
+  - which backend the daemon would pick today (HWAccelNone means software)
+
+Use this when transcoding feels slow or fails on 4K — the most common cause
+is a software-only ffmpeg build, not a missing GPU.`,
+		Example: `  unarr probe-hwaccel`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runProbeHWAccel()
+		},
+	}
+}
+
+func runProbeHWAccel() error {
+	bold := color.New(color.Bold)
+	green := color.New(color.FgGreen)
+	yellow := color.New(color.FgYellow)
+	red := color.New(color.FgRed)
+
+	fmt.Println()
+	bold.Println("  Hardware acceleration probe")
+	fmt.Println()
+
+	// 1. Locate ffmpeg / ffprobe.
+	ffmpegPath, ffmpegErr := exec.LookPath("ffmpeg")
+	ffprobePath, ffprobeErr := exec.LookPath("ffprobe")
+
+	bold.Println("  Binaries")
+	if ffmpegErr != nil {
+		red.Printf("    x ffmpeg not on PATH\n")
+		fmt.Println()
+		yellow.Println("    HW probe needs ffmpeg. Install it:")
+		fmt.Println("      Ubuntu/Debian: sudo apt install ffmpeg")
+		fmt.Println("      macOS:         brew install ffmpeg")
+		fmt.Println()
+		return nil
+	}
+	green.Printf("    OK ffmpeg  %s\n", ffmpegPath)
+	if ffprobeErr != nil {
+		yellow.Printf("    !  ffprobe not on PATH (HLS still works, source probing falls back to ffmpeg)\n")
+	} else {
+		green.Printf("    OK ffprobe %s\n", ffprobePath)
+	}
+	fmt.Println()
+
+	// 2. List encoders the ffmpeg binary supports.
+	bold.Println("  HW encoders compiled in")
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	out, err := exec.CommandContext(ctx, ffmpegPath, "-hide_banner", "-encoders").CombinedOutput()
+	if err != nil {
+		red.Printf("    x ffmpeg -encoders failed: %v\n", err)
+		fmt.Println()
+		return nil
+	}
+	encoders := string(out)
+
+	hwEncoders := []struct {
+		name    string
+		family  string
+		family2 string
+	}{
+		{"h264_nvenc", "NVIDIA NVENC", "hevc_nvenc"},
+		{"h264_qsv", "Intel Quick Sync", "hevc_qsv"},
+		{"h264_vaapi", "Linux VA-API (Intel/AMD)", "hevc_vaapi"},
+		{"h264_videotoolbox", "macOS VideoToolbox", "hevc_videotoolbox"},
+	}
+	anyHWEncoder := false
+	for _, e := range hwEncoders {
+		hasH264 := strings.Contains(encoders, e.name)
+		hasHEVC := strings.Contains(encoders, e.family2)
+		if hasH264 || hasHEVC {
+			anyHWEncoder = true
+			green.Printf("    OK %s\n", e.family)
+			if hasH264 {
+				fmt.Printf("       %s\n", e.name)
+			}
+			if hasHEVC {
+				fmt.Printf("       %s\n", e.family2)
+			}
+		}
+	}
+	if !anyHWEncoder {
+		red.Printf("    x No HW encoders compiled in\n")
+		fmt.Println()
+		yellow.Println("    Most likely your ffmpeg was built without --enable-nvenc /")
+		yellow.Println("    --enable-libmfx / --enable-vaapi. Brew's default formula is one")
+		yellow.Println("    common offender. On Ubuntu, the system package ships with VAAPI")
+		yellow.Println("    by default and NVENC if you have CUDA installed.")
+	}
+	fmt.Println()
+
+	// 3. Device-file checks.
+	bold.Println("  Devices / drivers")
+	checks := []struct {
+		path string
+		desc string
+	}{
+		{"/dev/nvidia0", "NVIDIA GPU"},
+		{"/dev/dri/renderD128", "Linux DRM render node (used by VA-API + QSV)"},
+	}
+	for _, c := range checks {
+		if fileExistsLocal(c.path) {
+			green.Printf("    OK %s — %s\n", c.path, c.desc)
+		} else {
+			yellow.Printf("    -  %s — %s (not present)\n", c.path, c.desc)
+		}
+	}
+	if _, err := exec.LookPath("nvidia-smi"); err == nil {
+		green.Printf("    OK nvidia-smi on PATH\n")
+	} else {
+		yellow.Printf("    -  nvidia-smi not on PATH\n")
+	}
+	if runtime.GOOS == "darwin" {
+		fmt.Printf("    .  macOS host — VideoToolbox available if encoder was compiled in\n")
+	}
+	fmt.Println()
+
+	// 4. Daemon's actual decision.
+	engine.ResetHWAccelCache()
+	pick := engine.DetectHWAccel(ctx, ffmpegPath)
+	bold.Println("  Daemon would pick")
+	switch pick {
+	case engine.HWAccelNone:
+		red.Printf("    x %s — software libx264 only\n", pick)
+		fmt.Println()
+		yellow.Println("    On a slow CPU 1080p will lag and 4K is effectively unwatchable.")
+		yellow.Println("    Fix: rebuild / reinstall ffmpeg with HW encoder support, then:")
+		fmt.Println()
+		fmt.Println("      unarr daemon restart")
+	default:
+		green.Printf("    OK %s\n", pick)
+		fmt.Printf("    encoder: %s (h264) / %s (hevc)\n", pick.FFmpegVideoCodec("h264"), pick.FFmpegVideoCodec("hevc"))
+	}
+	fmt.Println()
+
+	return nil
+}
+
+// fileExistsLocal stats a path. Mirrors engine.fileExists without exporting it.
+func fileExistsLocal(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
diff --git a/internal/cmd/reload_unix.go b/internal/cmd/reload_unix.go
index 5577a76..34d8e4d 100644
--- a/internal/cmd/reload_unix.go
+++ b/internal/cmd/reload_unix.go
@@ -3,12 +3,14 @@
 package cmd
 
 import (
+	"errors"
+	"fmt"
 	"log"
 	"os"
 	"os/signal"
 	"syscall"
-	"time"
 
+	"github.com/fatih/color"
 	"github.com/torrentclaw/unarr/internal/agent"
 	"github.com/torrentclaw/unarr/internal/config"
 )
@@ -19,7 +21,8 @@ type ReloadableConfig struct {
 }
 
 // startReloadWatcher listens for SIGUSR1 and reloads config.
-// Only intervals are hot-reloadable (speeds require torrent client restart).
+// With the sync-based architecture, intervals are fixed (3s watching, 60s idle).
+// Hot-reload now mainly serves as a signal to re-read config for future settings.
 func startReloadWatcher(rc *ReloadableConfig) {
 	sigCh := make(chan os.Signal, 1)
 	signal.Notify(sigCh, syscall.SIGUSR1)
@@ -28,26 +31,50 @@ func startReloadWatcher(rc *ReloadableConfig) {
 		for range sigCh {
 			log.Println("Received SIGUSR1, reloading config...")
 
-			cfg, err := config.Load("")
+			_, err := config.Load("")
 			if err != nil {
 				log.Printf("Config reload failed: %v", err)
 				continue
 			}
-			cfg.ApplyEnvOverrides()
-
-			// Update poll interval
-			if d, _ := time.ParseDuration(cfg.Daemon.PollInterval); d > 0 && rc.Daemon.PollTicker != nil {
-				rc.Daemon.PollTicker.Reset(d)
-				log.Printf("  Poll interval: %s", d)
-			}
-
-			// Update heartbeat interval
-			if d, _ := time.ParseDuration(cfg.Daemon.HeartbeatInterval); d > 0 && rc.Daemon.HeartbeatTicker != nil {
-				rc.Daemon.HeartbeatTicker.Reset(d)
-				log.Printf("  Heartbeat interval: %s", d)
-			}
 
 			log.Println("Config reloaded successfully")
 		}
 	}()
 }
+
+// sendReloadSignal sends SIGUSR1 to the running daemon process.
+func sendReloadSignal() error {
+	state, err := agent.LoadState()
+	if err != nil {
+		if errors.Is(err, agent.ErrDaemonNotRunning) {
+			return err
+		}
+		return fmt.Errorf("read daemon state: %w", err)
+	}
+	p, err := os.FindProcess(state.PID)
+	if err != nil {
+		return fmt.Errorf("find process %d: %w", state.PID, err)
+	}
+	if err := p.Signal(syscall.SIGUSR1); err != nil {
+		return fmt.Errorf("send reload signal to PID %d: %w", state.PID, err)
+	}
+	fmt.Println()
+	color.New(color.FgGreen).Printf("  ✓ Reload signal sent to daemon (PID %d)\n", state.PID)
+	fmt.Println("  Config will be re-read shortly.")
+	fmt.Println()
+	return nil
+}
+
+// killPID sends SIGTERM to the given PID for a graceful shutdown.
+func killPID(pid int) error {
+	p, err := os.FindProcess(pid)
+	if err != nil {
+		return fmt.Errorf("find process %d: %w", pid, err)
+	}
+	if err := p.Signal(syscall.SIGTERM); err != nil {
+		return fmt.Errorf("stop daemon (PID %d): %w", pid, err)
+	}
+	color.New(color.FgGreen).Printf("  ✓ Stop signal sent to daemon (PID %d)\n", pid)
+	fmt.Println()
+	return nil
+}
diff --git a/internal/cmd/reload_windows.go b/internal/cmd/reload_windows.go
index d9e042e..b70ec66 100644
--- a/internal/cmd/reload_windows.go
+++ b/internal/cmd/reload_windows.go
@@ -2,7 +2,15 @@
 
 package cmd
 
-import "github.com/torrentclaw/unarr/internal/agent"
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strconv"
+
+	"github.com/fatih/color"
+	"github.com/torrentclaw/unarr/internal/agent"
+)
 
 // ReloadableConfig holds a reference to the daemon for hot-reload.
 type ReloadableConfig struct {
@@ -11,3 +19,25 @@ type ReloadableConfig struct {
 
 // startReloadWatcher is a no-op on Windows (no SIGUSR1 support).
 func startReloadWatcher(_ *ReloadableConfig) {}
+
+// sendReloadSignal is not supported on Windows; instructs the user to restart instead.
+func sendReloadSignal() error {
+	fmt.Println()
+	color.New(color.FgYellow).Println("  ⚠  Config reload via signal is not supported on Windows.")
+	fmt.Println("  Use 'unarr daemon restart' to apply configuration changes.")
+	fmt.Println()
+	return nil
+}
+
+// killPID stops the daemon process on Windows using taskkill.
+func killPID(pid int) error {
+	cmd := exec.Command("taskkill", "/pid", strconv.Itoa(pid), "/f")
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	if err := cmd.Run(); err != nil {
+		return fmt.Errorf("stop daemon (PID %d): %w", pid, err)
+	}
+	color.New(color.FgGreen).Printf("  ✓ Daemon stopped (PID %d)\n", pid)
+	fmt.Println()
+	return nil
+}
diff --git a/internal/cmd/root.go b/internal/cmd/root.go
index bd8f734..375d8e9 100644
--- a/internal/cmd/root.go
+++ b/internal/cmd/root.go
@@ -9,6 +9,7 @@ import (
 	tc "github.com/torrentclaw/go-client"
 	"github.com/torrentclaw/unarr/internal/config"
 	"github.com/torrentclaw/unarr/internal/sentry"
+	"github.com/torrentclaw/unarr/internal/upgrade"
 )
 
 var (
@@ -24,16 +25,20 @@ var (
 
 func init() {
 	rootCmd = &cobra.Command{
-		Use:   "unarr",
-		Short: "unarr — torrent search and management",
-		Long: `unarr is a powerful terminal tool for torrent search and management.
-
-Search 30+ torrent sources, inspect torrent quality, discover popular content,
-find streaming providers, and manage your media collection — all from your terminal.
+		Use:     "unarr",
+		Version: Version,
+		Short:   "Terminal torrent + debrid + usenet client — download, stream, transcode",
+		Long: `unarr is a terminal-native client that downloads torrents, debrid links,
+and usenet (NZB) — all from the same binary. It streams content straight
+to mpv/vlc with sequential piece prioritization, transcodes on the fly via
+ffmpeg with hardware acceleration (NVENC, QSV, VA-API, VideoToolbox), and
+organizes your library into Movies/TV folders. Run it one-shot or as a
+long-running daemon with a built-in WireGuard split-tunnel and remote
+playback over Cloudflare Funnel.
 
 Get started:
   unarr init                           First-time configuration wizard
-  unarr search "breaking bad"          Search for content
+  unarr download <magnet|hash>         Grab a torrent one-shot
   unarr start                          Start the download daemon
 
 Documentation:  https://torrentclaw.com/cli
@@ -42,6 +47,10 @@ Source:         https://github.com/torrentclaw/unarr`,
 			if noColor || os.Getenv("NO_COLOR") != "" {
 				color.NoColor = true
 			}
+			// Self-updater fetches releases from the configured host (default
+			// torrentclaw.com), not GitHub — so mirrors / onion / staging /
+			// UNARR_API_URL all route updates correctly.
+			upgrade.SetBaseURL(loadConfig().Auth.APIURL)
 		},
 		SilenceUsage:  true,
 		SilenceErrors: true,
@@ -50,7 +59,7 @@ Source:         https://github.com/torrentclaw/unarr`,
 	// Command groups for organized help output
 	rootCmd.AddGroup(
 		&cobra.Group{ID: "start", Title: "Getting Started:"},
-		&cobra.Group{ID: "search", Title: "Search & Discovery:"},
+		&cobra.Group{ID: "search", Title: "Catalog & Discovery:"},
 		&cobra.Group{ID: "download", Title: "Downloads & Streaming:"},
 		&cobra.Group{ID: "daemon", Title: "Daemon Management:"},
 		&cobra.Group{ID: "system", Title: "System & Diagnostics:"},
@@ -64,6 +73,8 @@ Source:         https://github.com/torrentclaw/unarr`,
 	// Getting Started
 	initCmd := newInitCmd()
 	initCmd.GroupID = "start"
+	loginCmd := newLoginCmd()
+	loginCmd.GroupID = "start"
 	configCmd := newConfigCmd()
 	configCmd.GroupID = "start"
 	migrateCmd := newMigrateCmd()
@@ -96,14 +107,22 @@ Source:         https://github.com/torrentclaw/unarr`,
 	statusCmd.GroupID = "daemon"
 	daemonCmd := newDaemonCmd()
 	daemonCmd.GroupID = "daemon"
+	vpnCmd := newVPNCmd()
+	vpnCmd.GroupID = "daemon"
+	funnelCmd := newFunnelCmd()
+	funnelCmd.GroupID = "daemon"
 
 	// System & Diagnostics
 	statsCmd := newStatsCmd()
 	statsCmd.GroupID = "system"
 	doctorCmd := newDoctorCmd()
 	doctorCmd.GroupID = "system"
+	probeHWAccelCmd := newProbeHWAccelCmd()
+	probeHWAccelCmd.GroupID = "system"
 	cleanCmd := newCleanCmd()
 	cleanCmd.GroupID = "system"
+	mirrorsCmd := newMirrorsCmd()
+	mirrorsCmd.GroupID = "system"
 	selfUpdateCmd := newSelfUpdateCmd()
 	selfUpdateCmd.GroupID = "system"
 	versionCmd := newVersionCmd()
@@ -118,6 +137,7 @@ Source:         https://github.com/torrentclaw/unarr`,
 	rootCmd.AddCommand(
 		// Getting Started
 		initCmd,
+		loginCmd,
 		configCmd,
 		migrateCmd,
 		// Search & Discovery
@@ -134,22 +154,21 @@ Source:         https://github.com/torrentclaw/unarr`,
 		stopCmd,
 		statusCmd,
 		daemonCmd,
+		vpnCmd,
+		funnelCmd,
 		// System & Diagnostics
 		statsCmd,
 		doctorCmd,
+		probeHWAccelCmd,
 		cleanCmd,
+		mirrorsCmd,
 		selfUpdateCmd,
 		versionCmd,
 		completionCmd,
 		// Library
 		scanCmd,
-		// Stubs for future commands
-		newStubCmd("upgrade", "Find a better version of a torrent"),
-		newStubCmd("moreseed", "Find same quality with more seeders"),
-		newStubCmd("compare", "Compare two torrents side by side"),
-		newStubCmd("add", "Search and add torrents to your client"),
-		newStubCmd("monitor", "Watch for new episodes of a series"),
-		newStubCmd("open", "Open content in the browser"),
+		// Alias: upgrade → self-update
+		newUpgradeCmd(),
 	)
 }
 
diff --git a/internal/cmd/scan.go b/internal/cmd/scan.go
index 2d9e591..d05ae29 100644
--- a/internal/cmd/scan.go
+++ b/internal/cmd/scan.go
@@ -9,6 +9,7 @@ import (
 	"sort"
 	"strings"
 	"syscall"
+	"time"
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
@@ -40,11 +41,16 @@ to see available quality upgrades.`,
 			}
 			if len(args) == 0 {
 				cfg := loadConfig()
-				if cfg.Library.ScanPath != "" {
-					args = append(args, cfg.Library.ScanPath)
-				} else {
-					return fmt.Errorf("usage: unarr scan <path>\n\nProvide a media folder to scan")
+				paths := library.ResolveScanPaths(cfg.Download.Dir, cfg.Organize.MoviesDir, cfg.Organize.TVShowsDir, cfg.Library.ScanPath)
+				if len(paths) == 0 {
+					return fmt.Errorf("usage: unarr scan <path>\n\nNo scan paths configured. Provide a path or set up downloads.dir via 'unarr init'")
 				}
+				for _, p := range paths {
+					if err := runScan(p, workers, ffprobe, noSync); err != nil {
+						return err
+					}
+				}
+				return nil
 			}
 			return runScan(args[0], workers, ffprobe, noSync)
 		},
@@ -165,6 +171,7 @@ func syncToServer(ctx context.Context, cfg config.Config, cache *library.Library
 	totalSynced := 0
 	totalMatched := 0
 	totalRemoved := 0
+	syncStartedAt := time.Now().UTC().Format(time.RFC3339)
 
 	for i := 0; i < len(items); i += batchSize {
 		end := i + batchSize
@@ -177,9 +184,10 @@ func syncToServer(ctx context.Context, cfg config.Config, cache *library.Library
 		fmt.Fprintf(os.Stderr, "\r  Syncing %d/%d items...\033[K", end, len(items))
 
 		resp, err := ac.SyncLibrary(ctx, agent.LibrarySyncRequest{
-			Items:       batch,
-			ScanPath:    cache.Path,
-			IsLastBatch: isLast,
+			Items:         batch,
+			ScanPath:      cache.Path,
+			IsLastBatch:   isLast,
+			SyncStartedAt: syncStartedAt,
 		})
 		if err != nil {
 			return fmt.Errorf("sync failed: %w", err)
@@ -233,7 +241,7 @@ func printScanSummary(cache *library.LibraryCache) {
 			continue
 		}
 
-		res := library.ResolveResolution(item.MediaInfo.Video.Height)
+		res := library.ResolveResolution(item.MediaInfo.Video.Width, item.MediaInfo.Video.Height)
 		if res == "" {
 			res = "other"
 		}
diff --git a/internal/cmd/self_update.go b/internal/cmd/self_update.go
index b936eb0..e68a5de 100644
--- a/internal/cmd/self_update.go
+++ b/internal/cmd/self_update.go
@@ -3,19 +3,17 @@ package cmd
 import (
 	"context"
 	"fmt"
-	"os"
-	"os/exec"
-	"runtime"
 	"strings"
-	"syscall"
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
 	"github.com/torrentclaw/unarr/internal/upgrade"
 )
 
 func newSelfUpdateCmd() *cobra.Command {
 	var force bool
+	var allowUnsigned bool
 
 	cmd := &cobra.Command{
 		Use:   "self-update",
@@ -23,29 +21,35 @@ func newSelfUpdateCmd() *cobra.Command {
 		Long: `Download and install the latest version of unarr.
 
 Checks GitHub for the latest release, verifies the checksum, and
-replaces the current binary. A backup is kept at <binary>.backup.`,
+replaces the current binary. A backup is kept at <binary>.backup.
+
+If the daemon is running, it is automatically restarted so the new
+version is loaded into memory (otherwise heartbeat would keep
+reporting the old version until a manual restart).`,
 		Example: `  unarr self-update
-  unarr self-update --force`,
+  unarr self-update --force
+  unarr self-update --allow-unsigned   # accept releases missing checksums.txt.sig`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runSelfUpdate(force)
+			return runSelfUpdate(force, allowUnsigned)
 		},
 	}
 
 	cmd.Flags().BoolVarP(&force, "force", "f", false, "reinstall even if already up to date")
+	cmd.Flags().BoolVar(&allowUnsigned, "allow-unsigned", false, "continue with SHA256-only verification when checksums.txt.sig is missing")
 
 	return cmd
 }
 
-func runSelfUpdate(force bool) error {
+func runSelfUpdate(force, allowUnsigned bool) error {
 	bold := color.New(color.Bold)
 	green := color.New(color.FgGreen)
 	yellow := color.New(color.FgYellow)
+	red := color.New(color.FgRed)
 
 	fmt.Println()
 	bold.Println("  unarr self-update")
 	fmt.Println()
 
-	// Check latest version
 	fmt.Print("  Checking latest version... ")
 	ctx := context.Background()
 	latest, err := upgrade.CheckLatest(ctx)
@@ -73,6 +77,7 @@ func runSelfUpdate(force bool) error {
 
 	upgrader := &upgrade.Upgrader{
 		CurrentVersion: currentClean,
+		AllowUnsigned:  allowUnsigned,
 		OnProgress: func(msg string) {
 			fmt.Printf("  %s\n", msg)
 		},
@@ -89,37 +94,25 @@ func runSelfUpdate(force bool) error {
 	if result.BackupPath != "" {
 		fmt.Printf("  Backup: %s\n", result.BackupPath)
 	}
-	fmt.Println()
 
-	// If running as daemon, re-exec to restart with new binary
-	// For interactive use, just suggest restarting
-	if isRunningAsDaemon() {
-		fmt.Println("  Restarting daemon with new version...")
-		binPath, err := os.Executable()
-		if err != nil {
-			return fmt.Errorf("could not determine executable path: %w", err)
+	// Auto-restart daemon if it is running, otherwise the live process keeps
+	// serving the old version (heartbeat reports old version → web gates
+	// features against the wrong version).
+	if state := agent.ReadState(); state != nil && isDaemonAlive(state) {
+		fmt.Println()
+		fmt.Printf("  → Daemon running (PID %d), restarting to load new version...\n", state.PID)
+		if err := runDaemonSvcRestart(); err != nil {
+			fmt.Println()
+			red.Printf("  ✗ Auto-restart failed: %v\n", err)
+			fmt.Println("    The new binary is on disk but the daemon is still running the old version.")
+			fmt.Println("    Run manually: unarr daemon restart")
+			fmt.Println("    (If the daemon runs under a different user/session, restart it there.)")
+			fmt.Println()
+			return nil
 		}
-		execErr := syscall.Exec(binPath, os.Args, os.Environ())
-		if execErr != nil && runtime.GOOS == "windows" {
-			// Windows doesn't support syscall.Exec — start new process
-			proc := exec.Command(binPath, os.Args[1:]...)
-			proc.Stdout = os.Stdout
-			proc.Stderr = os.Stderr
-			proc.Stdin = os.Stdin
-			return proc.Start()
-		}
-		return execErr
+		green.Println("  ✓ Daemon restarted")
 	}
 
+	fmt.Println()
 	return nil
 }
-
-func isRunningAsDaemon() bool {
-	// Simple heuristic: check if "start" was in the original args
-	for _, arg := range os.Args {
-		if arg == "start" {
-			return true
-		}
-	}
-	return false
-}
diff --git a/internal/cmd/status.go b/internal/cmd/status.go
index 0f989f4..f43d6ca 100644
--- a/internal/cmd/status.go
+++ b/internal/cmd/status.go
@@ -1,20 +1,27 @@
 package cmd
 
 import (
+	"context"
+	"errors"
 	"fmt"
+	"runtime"
+	"strings"
+	"time"
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/upgrade"
 )
 
 func newStatusCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "status",
-		Short: "Show daemon status and active downloads",
-		Long: `Display the current state of the daemon, active downloads, and recent activity.
+		Short: "Show daemon status, configuration, and update availability",
+		Long: `Display the current state of unarr: version, configuration, daemon status,
+disk usage, and whether an update is available.
 
-Shows the configured agent name, download directory, and preferred method.
-When the daemon is running, also displays active downloads and their progress.`,
+When the daemon is running, also displays uptime, active downloads, and stats.`,
 		Example: `  unarr status`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runStatus()
@@ -25,27 +32,232 @@ When the daemon is running, also displays active downloads and their progress.`,
 func runStatus() error {
 	bold := color.New(color.Bold)
 	dim := color.New(color.FgHiBlack)
+	green := color.New(color.FgGreen)
+	yellow := color.New(color.FgYellow)
+	cyan := color.New(color.FgCyan)
 
 	fmt.Println()
 	bold.Printf("  unarr %s\n", Version)
+	dim.Printf("  %s/%s\n", runtime.GOOS, runtime.GOARCH)
 	fmt.Println()
 
 	cfg := loadConfig()
 
+	// ── Configuration ──
 	if cfg.Auth.APIKey == "" {
-		dim.Println("  Not configured. Run 'unarr init' first.")
+		yellow.Println("  ⚠  Not configured. Run 'unarr init' first.")
 		fmt.Println()
 		return nil
 	}
 
-	fmt.Printf("  Agent:     %s (%s)\n", cfg.Agent.Name, cfg.Agent.ID[:8]+"...")
-	fmt.Printf("  Downloads: %s\n", cfg.Download.Dir)
-	fmt.Printf("  Method:    %s\n", cfg.Download.PreferredMethod)
+	// ── Account (async fetch) ──
+	type accountResult struct {
+		user agent.UserInfo
+		err  error
+	}
+	accountCh := make(chan accountResult, 1)
+	go func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		ac := newAgentClientFromConfig(cfg, "unarr/"+Version)
+		resp, err := ac.Register(ctx, agent.RegisterRequest{
+			AgentID: cfg.Agent.ID,
+			Name:    cfg.Agent.Name,
+			Version: Version,
+		})
+		if err != nil {
+			accountCh <- accountResult{err: err}
+			return
+		}
+		accountCh <- accountResult{user: resp.User}
+	}()
+
+	cyan.Println("  Account")
+	ar := <-accountCh
+	if ar.err != nil {
+		var httpErr *agent.HTTPError
+		switch {
+		case errors.As(ar.err, &httpErr) && httpErr.StatusCode == 401:
+			yellow.Println("    API key invalid or revoked")
+			fmt.Printf("    Run %s to re-authenticate\n", cyan.Sprint("unarr login"))
+		case errors.As(ar.err, &httpErr) && httpErr.StatusCode == 403:
+			yellow.Println("    API key lacks permission for this server")
+			fmt.Printf("    Check plan or run %s\n", cyan.Sprint("unarr login"))
+		default:
+			dim.Printf("    Could not fetch account info (%v)\n", ar.err)
+		}
+	} else {
+		fmt.Printf("    User:       %s\n", ar.user.Name)
+		fmt.Printf("    Email:      %s\n", ar.user.Email)
+		planColor := dim
+		if ar.user.IsPro {
+			planColor = green
+		}
+		planColor.Printf("    Plan:       %s\n", strings.ToUpper(ar.user.Plan))
+	}
 	fmt.Println()
 
-	dim.Println("  Daemon not running. Start with 'unarr start'")
-	dim.Println("  (Live status will be shown here when daemon is running)")
+	cyan.Println("  Configuration")
+	agentID := cfg.Agent.ID
+	if len(agentID) > 8 {
+		agentID = agentID[:8] + "..."
+	}
+	fmt.Printf("    Agent:      %s (%s)\n", cfg.Agent.Name, agentID)
+	fmt.Printf("    Server:     %s\n", cfg.Auth.APIURL)
+	fmt.Printf("    Downloads:  %s\n", cfg.Download.Dir)
+	fmt.Printf("    Method:     %s\n", cfg.Download.PreferredMethod)
+	if cfg.Download.PreferredQuality != "" {
+		fmt.Printf("    Quality:    %s\n", cfg.Download.PreferredQuality)
+	}
+	fmt.Printf("    Concurrent: %d\n", cfg.Download.MaxConcurrent)
+	if cfg.Organize.Enabled {
+		fmt.Printf("    Organize:   on")
+		if cfg.Organize.MoviesDir != "" {
+			fmt.Printf(" (movies: %s", cfg.Organize.MoviesDir)
+			if cfg.Organize.TVShowsDir != "" {
+				fmt.Printf(", tv: %s", cfg.Organize.TVShowsDir)
+			}
+			fmt.Print(")")
+		}
+		fmt.Println()
+	}
+	fmt.Println()
+
+	// ── Disk ──
+	if cfg.Download.Dir != "" {
+		if free, total, err := agent.DiskInfo(cfg.Download.Dir); err == nil && total > 0 {
+			usedPct := float64(total-free) / float64(total) * 100
+			cyan.Println("  Disk")
+			fmt.Printf("    Free: %s / %s (%.0f%% used)\n", formatBytes(free), formatBytes(total), usedPct)
+			if dirSize, err := agent.DirSize(cfg.Download.Dir); err == nil {
+				fmt.Printf("    Downloads:  %s\n", formatBytes(dirSize))
+			}
+			if usedPct > 90 {
+				yellow.Println("    ⚠  Low disk space!")
+			}
+			fmt.Println()
+		}
+	}
+
+	// ── Daemon ──
+	cyan.Println("  Daemon")
+	state := agent.ReadState()
+	if state != nil && isDaemonAlive(state) {
+		green.Printf("    Status:     running (PID %d)\n", state.PID)
+		fmt.Printf("    Uptime:     %s\n", formatDuration(time.Since(state.StartedAt)))
+		fmt.Printf("    Last beat:  %s ago\n", formatDuration(time.Since(state.LastHeartbeat)))
+		fmt.Printf("    Active:     %d task(s)\n", state.ActiveTasks)
+		fmt.Printf("    Completed:  %d\n", state.CompletedCount)
+		if state.FailedCount > 0 {
+			fmt.Printf("    Failed:     %d\n", state.FailedCount)
+		}
+		if state.TotalDownloaded > 0 {
+			fmt.Printf("    Downloaded: %s\n", formatBytes(state.TotalDownloaded))
+		}
+		if len(state.MethodStats) > 0 {
+			parts := make([]string, 0, len(state.MethodStats))
+			for method, count := range state.MethodStats {
+				parts = append(parts, fmt.Sprintf("%s:%d", method, count))
+			}
+			fmt.Printf("    Methods:    %s\n", strings.Join(parts, ", "))
+		}
+	} else {
+		dim.Println("    Status:     stopped")
+		dim.Println("    Start with: unarr start")
+	}
+	fmt.Println()
+
+	// ── Update check (cached: instant if <1h, otherwise async 3s) ──
+	type versionResult struct {
+		version   string
+		fromCache bool
+		err       error
+	}
+	versionCh := make(chan versionResult, 1)
+	go func() {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		v, cached, err := upgrade.CheckLatestCached(ctx)
+		versionCh <- versionResult{v, cached, err}
+	}()
+
+	cyan.Println("  Update")
+	fmt.Print("    Checking... ")
+	vr := <-versionCh
+	if vr.err != nil {
+		dim.Println("could not check (offline?)")
+	} else {
+		currentClean := strings.TrimPrefix(Version, "v")
+		if currentClean == vr.version {
+			green.Printf("✓ up to date (v%s)\n", vr.version)
+		} else {
+			yellow.Printf("v%s available! ", vr.version)
+			fmt.Printf("Run: unarr upgrade\n")
+		}
+	}
 	fmt.Println()
 
 	return nil
 }
+
+// isDaemonAlive checks if the daemon process from the state file is still running.
+// Guards against PID reuse by also checking heartbeat recency.
+func isDaemonAlive(state *agent.DaemonState) bool {
+	if state.PID == 0 {
+		return false
+	}
+	// Reject stale state: if last heartbeat is older than 2 minutes, the daemon
+	// likely crashed and the PID may have been reused by another process.
+	if !state.LastHeartbeat.IsZero() && time.Since(state.LastHeartbeat) > 2*time.Minute {
+		return false
+	}
+	return agent.IsProcessAlive(state.PID)
+}
+
+// formatFeatures returns a comma-separated list of available features, or "".
+func formatFeatures(f agent.FeatureFlags) string {
+	var features []string
+	if f.Torrent {
+		features = append(features, "Torrent")
+	}
+	if f.Debrid {
+		features = append(features, "Debrid")
+	}
+	if f.Usenet {
+		features = append(features, "Usenet")
+	}
+	return strings.Join(features, ", ")
+}
+
+// formatBytes formats bytes into human-readable string.
+func formatBytes(b int64) string {
+	const unit = 1024
+	if b < unit {
+		return fmt.Sprintf("%d B", b)
+	}
+	div, exp := int64(unit), 0
+	for n := b / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+	return fmt.Sprintf("%.1f %cB", float64(b)/float64(div), "KMGTPE"[exp])
+}
+
+// formatDuration formats a duration into a compact human-readable string.
+func formatDuration(d time.Duration) string {
+	if d < 0 {
+		return "0s"
+	}
+	if d < time.Minute {
+		return fmt.Sprintf("%ds", int(d.Seconds()))
+	}
+	if d < time.Hour {
+		return fmt.Sprintf("%dm %ds", int(d.Minutes()), int(d.Seconds())%60)
+	}
+	if d < 24*time.Hour {
+		return fmt.Sprintf("%dh %dm", int(d.Hours()), int(d.Minutes())%60)
+	}
+	days := int(d.Hours()) / 24
+	hours := int(d.Hours()) % 24
+	return fmt.Sprintf("%dd %dh", days, hours)
+}
diff --git a/internal/cmd/stream.go b/internal/cmd/stream.go
index 91d2fea..2300617 100644
--- a/internal/cmd/stream.go
+++ b/internal/cmd/stream.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"os/exec"
 	"os/signal"
 	"path/filepath"
 	"strings"
@@ -17,6 +18,20 @@ import (
 	"github.com/torrentclaw/unarr/internal/ui"
 )
 
+// streamDeps agrupa las funciones constructoras usadas por runStream.
+// Pueden sobreescribirse en tests para inyectar mocks.
+type streamDeps struct {
+	newStreamEngine func(cfg engine.StreamConfig) (*engine.StreamEngine, error)
+	newStreamServer func(port int) *engine.StreamServer
+	openPlayer      func(url, override string) (string, *exec.Cmd, error)
+}
+
+var defaultStreamDeps = streamDeps{
+	newStreamEngine: engine.NewStreamEngine,
+	newStreamServer: engine.NewStreamServer,
+	openPlayer:      engine.OpenPlayer,
+}
+
 func newStreamCmd() *cobra.Command {
 	var (
 		port      int
@@ -56,6 +71,10 @@ download directory (or system temp if not configured).`,
 }
 
 func runStream(input string, port int, noOpen bool, playerCmd string) error {
+	return runStreamWithDeps(input, port, noOpen, playerCmd, defaultStreamDeps)
+}
+
+func runStreamWithDeps(input string, port int, noOpen bool, playerCmd string, deps streamDeps) error {
 	cfg := loadConfig()
 	bold := color.New(color.Bold)
 	green := color.New(color.FgGreen)
@@ -83,7 +102,7 @@ func runStream(input string, port int, noOpen bool, playerCmd string) error {
 	}
 
 	// Create engine
-	eng, err := engine.NewStreamEngine(engine.StreamConfig{
+	eng, err := deps.newStreamEngine(engine.StreamConfig{
 		DataDir:     dataDir,
 		Port:        port,
 		MetaTimeout: 60 * time.Second,
@@ -127,14 +146,14 @@ func runStream(input string, port int, noOpen bool, playerCmd string) error {
 	}
 
 	// Start HTTP server
-	srv := engine.NewStreamServer(eng, port)
-	streamURL, err := srv.Start(ctx)
-	if err != nil {
+	srv := deps.newStreamServer(port)
+	if err := srv.Listen(ctx); err != nil {
 		eng.Shutdown(context.Background())
 		return fmt.Errorf("start server: %w", err)
 	}
+	srv.SetFile(eng, "cli-stream")
 
-	fmt.Printf("  URL: %s\n", streamURL)
+	fmt.Printf("  URL: %s\n", srv.URL())
 	fmt.Println()
 
 	// Buffer before opening player
@@ -159,15 +178,15 @@ func runStream(input string, port int, noOpen bool, playerCmd string) error {
 
 	// Open player
 	if !noOpen {
-		playerName, _, openErr := engine.OpenPlayer(streamURL, playerCmd)
+		playerName, _, openErr := deps.openPlayer(srv.URL(), playerCmd)
 		if openErr != nil {
 			yellow.Printf("  Could not open player: %s\n", openErr)
-			fmt.Printf("  Open this URL in your player: %s\n", streamURL)
+			fmt.Printf("  Open this URL in your player: %s\n", srv.URL())
 		} else {
 			green.Printf("  Opened in %s\n", playerName)
 		}
 	} else {
-		fmt.Printf("  Open this URL in your player: %s\n", streamURL)
+		fmt.Printf("  Open this URL in your player: %s\n", srv.URL())
 	}
 	fmt.Println()
 
diff --git a/internal/cmd/stream_handler.go b/internal/cmd/stream_handler.go
index 9bb9657..fa61220 100644
--- a/internal/cmd/stream_handler.go
+++ b/internal/cmd/stream_handler.go
@@ -14,34 +14,80 @@ import (
 	"github.com/torrentclaw/unarr/internal/ui"
 )
 
-// streamRegistry tracks active stream tasks and servers for cancellation.
+const streamIdleTimeout = 30 * time.Minute
+
+// startIdleGuard monitors the persistent stream server and clears the file after inactivity.
+func startIdleGuard(ctx context.Context, srv *engine.StreamServer) {
+	ticker := time.NewTicker(60 * time.Second)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			if srv.HasFile() && srv.IdleSince() > streamIdleTimeout {
+				taskID := srv.CurrentTaskID()
+				short := taskID
+				if len(short) > 8 {
+					short = short[:8]
+				}
+				log.Printf("[%s] stream idle timeout (%v no HTTP requests), clearing file", short, streamIdleTimeout)
+				cancelStreamContexts()
+				srv.ClearFile()
+			}
+		}
+	}
+}
+
+// streamRegistry tracks active stream goroutine contexts for cancellation.
+// There is only ONE persistent StreamServer — no per-task servers.
 var streamRegistry = struct {
 	mu      sync.Mutex
 	cancels map[string]context.CancelFunc
-	servers map[string]*engine.StreamServer // servers for active download streams
 }{
 	cancels: make(map[string]context.CancelFunc),
-	servers: make(map[string]*engine.StreamServer),
 }
 
-// cancelStreamTask cancels a running stream task and shuts down any stream server.
-func cancelStreamTask(taskID string) {
+// cancelStreamContexts cancels all active stream goroutines (download engines, etc.).
+// Does NOT touch the persistent server — call srv.ClearFile() separately if needed.
+func cancelStreamContexts() {
 	streamRegistry.mu.Lock()
-	if cancel, ok := streamRegistry.cancels[taskID]; ok {
-		cancel()
-		delete(streamRegistry.cancels, taskID)
-	}
-	if srv, ok := streamRegistry.servers[taskID]; ok {
-		srv.Shutdown(context.Background())
-		delete(streamRegistry.servers, taskID)
+	cancels := make(map[string]context.CancelFunc, len(streamRegistry.cancels))
+	for k, v := range streamRegistry.cancels {
+		cancels[k] = v
+		delete(streamRegistry.cancels, k)
 	}
 	streamRegistry.mu.Unlock()
+
+	for _, cancel := range cancels {
+		cancel()
+	}
 }
 
-// handleStreamTask manages a streaming task lifecycle outside the Manager.
-// It creates a StreamEngine, buffers, starts an HTTP server, and reports
-// progress until the task is cancelled or the download completes.
-func handleStreamTask(parentCtx context.Context, at agent.Task, reporter *engine.ProgressReporter, cfg config.Config) {
+// isStreamingTask returns true if there is an active stream goroutine for the given task.
+func isStreamingTask(taskID string) bool {
+	streamRegistry.mu.Lock()
+	defer streamRegistry.mu.Unlock()
+	_, ok := streamRegistry.cancels[taskID]
+	return ok
+}
+
+// cancelStreamTask cancels a specific stream goroutine.
+func cancelStreamTask(taskID string) {
+	streamRegistry.mu.Lock()
+	cancel, ok := streamRegistry.cancels[taskID]
+	delete(streamRegistry.cancels, taskID)
+	streamRegistry.mu.Unlock()
+
+	if ok {
+		cancel()
+	}
+}
+
+// handleStreamTask manages a streaming task lifecycle for active torrent downloads.
+// It creates a StreamEngine, buffers, sets the file on the persistent server,
+// and reports progress until the task is cancelled or the download completes.
+func handleStreamTask(parentCtx context.Context, at agent.Task, reporter *engine.ProgressReporter, cfg config.Config, agentClient *agent.Client, srv *engine.StreamServer) {
 	ctx, cancel := context.WithCancel(parentCtx)
 	defer cancel()
 
@@ -53,6 +99,10 @@ func handleStreamTask(parentCtx context.Context, at agent.Task, reporter *engine
 		streamRegistry.mu.Lock()
 		delete(streamRegistry.cancels, at.ID)
 		streamRegistry.mu.Unlock()
+		// Clear file from persistent server if we're still the current task
+		if srv.CurrentTaskID() == at.ID {
+			srv.ClearFile()
+		}
 	}()
 
 	task := engine.NewTaskFromAgent(at)
@@ -93,31 +143,37 @@ func handleStreamTask(parentCtx context.Context, at agent.Task, reporter *engine
 		return
 	}
 
-	// 4. Start HTTP server
-	srv := engine.NewStreamServer(eng, 0)
-	streamURL, err := srv.Start(ctx)
-	if err != nil {
-		task.ErrorMessage = "start HTTP server: " + err.Error()
-		task.Transition(engine.StatusFailed)
-		return
+	// 4. Set file on the persistent stream server (instant, no port binding)
+	srv.SetFile(eng, at.ID)
+	task.StreamURL = srv.URLsJSON()
+	log.Printf("[%s] stream ready: %s (url: %s)", at.ID[:8], eng.FileName(), srv.URL())
+
+	// Pre-descargar los últimos 5 MB del archivo para que el moov atom (MP4)
+	// o el seekhead (MKV) estén disponibles cuando VLC los pida al abrir el
+	// stream. Sin esto, VLC busca el final del archivo, el lector bloquea
+	// esperando piezas no descargadas, y el resultado es pantalla negra en
+	// redes remotas donde la latencia amplifica el efecto.
+	eng.PrioritizeTail(ctx, 5*1024*1024)
+
+	// 5. Start watch progress reporter
+	if agentClient != nil {
+		watchReporter := engine.NewWatchReporter(agentClient, srv, at.ID)
+		go watchReporter.Run(ctx)
 	}
-	defer srv.Shutdown(context.Background())
 
-	// 5. Report stream URL — the reporter will send this to the web
-	task.StreamURL = streamURL
-	log.Printf("[%s] stream ready: %s", at.ID[:8], streamURL)
-
-	// 6. Progress loop
+	// 6. Progress loop until download completes or cancelled
 	eng.StartProgressLoop(ctx)
-	ticker := time.NewTicker(3 * time.Second)
-	defer ticker.Stop()
+	progressTicker := time.NewTicker(3 * time.Second)
+	defer progressTicker.Stop()
+	completed := false
 
 	for {
 		select {
 		case <-ctx.Done():
 			log.Printf("[%s] stream stopped", at.ID[:8])
 			return
-		case <-ticker.C:
+
+		case <-progressTicker.C:
 			p := eng.Progress()
 			task.UpdateProgress(engine.Progress{
 				DownloadedBytes: p.DownloadedBytes,
@@ -129,7 +185,7 @@ func handleStreamTask(parentCtx context.Context, at agent.Task, reporter *engine
 			})
 
 			// Terminal progress
-			if p.TotalBytes > 0 {
+			if !completed && p.TotalBytes > 0 {
 				pct := int(float64(p.DownloadedBytes) / float64(p.TotalBytes) * 100)
 				fmt.Fprintf(os.Stderr, "\r[%s] %d%% — %s/%s @ %s/s  peers:%d seeds:%d",
 					at.ID[:8], pct,
@@ -137,20 +193,11 @@ func handleStreamTask(parentCtx context.Context, at agent.Task, reporter *engine
 					p.Peers, p.Seeds)
 			}
 
-			if p.DownloadedBytes >= p.TotalBytes && p.TotalBytes > 0 {
-				fmt.Fprint(os.Stderr, "\r\033[2K") // clear progress line
+			if !completed && p.DownloadedBytes >= p.TotalBytes && p.TotalBytes > 0 {
+				fmt.Fprint(os.Stderr, "\r\033[2K")
 				task.Transition(engine.StatusCompleted)
-				log.Printf("[%s] stream download complete, server stays up for 30m or until cancelled", at.ID[:8])
-				// Keep HTTP server running so the player can finish reading.
-				// Auto-shutdown after 30 minutes of idle to prevent resource leaks.
-				idleTimer := time.NewTimer(30 * time.Minute)
-				defer idleTimer.Stop()
-				select {
-				case <-ctx.Done():
-				case <-idleTimer.C:
-					log.Printf("[%s] stream idle timeout (30m), shutting down", at.ID[:8])
-				}
-				return
+				log.Printf("[%s] stream download complete, server stays up until idle (30m)", at.ID[:8])
+				completed = true
 			}
 		}
 	}
diff --git a/internal/cmd/stream_test.go b/internal/cmd/stream_test.go
new file mode 100644
index 0000000..5998e96
--- /dev/null
+++ b/internal/cmd/stream_test.go
@@ -0,0 +1,165 @@
+package cmd
+
+import (
+	"fmt"
+	"os/exec"
+	"strings"
+	"testing"
+
+	"github.com/torrentclaw/unarr/internal/engine"
+)
+
+// --- Tests de validación de entrada para runStream ---
+
+func TestRunStream_EmptyInput(t *testing.T) {
+	err := runStream("", 0, true, "")
+	if err == nil {
+		t.Fatal("expected error for empty input")
+	}
+}
+
+func TestRunStream_InvalidInput_NotHashNotMagnet(t *testing.T) {
+	err := runStream("The Matrix 1999", 0, true, "")
+	if err == nil {
+		t.Fatal("expected error for plain text input")
+	}
+	if !strings.Contains(err.Error(), "invalid") {
+		t.Errorf("error = %q, want 'invalid' in message", err.Error())
+	}
+}
+
+func TestRunStream_InvalidInput_TooShort(t *testing.T) {
+	err := runStream("abc123", 0, true, "")
+	if err == nil {
+		t.Fatal("expected error for hash too short")
+	}
+}
+
+func TestRunStream_ValidHash_PassesValidation(t *testing.T) {
+	// Un hash válido debe pasar la validación y llegar a newStreamEngine.
+	// Inyectamos un engine que falla inmediatamente para no necesitar red.
+	deps := streamDeps{
+		newStreamEngine: func(cfg engine.StreamConfig) (*engine.StreamEngine, error) {
+			return nil, fmt.Errorf("test: stopping after validation")
+		},
+		newStreamServer: engine.NewStreamServer,
+		openPlayer: func(url, override string) (string, *exec.Cmd, error) {
+			return "", nil, nil
+		},
+	}
+
+	err := runStreamWithDeps("abc123def456abc123def456abc123def456abc1", 0, true, "", deps)
+	if err == nil {
+		t.Fatal("expected error from newStreamEngine mock")
+	}
+	// El error debe venir del engine, no de validación
+	if strings.Contains(err.Error(), "invalid input") {
+		t.Errorf("error = %q — should not be a validation error, hash is valid", err.Error())
+	}
+	if !strings.Contains(err.Error(), "create stream engine") {
+		t.Errorf("error = %q — expected 'create stream engine' from engine creation failure", err.Error())
+	}
+}
+
+func TestRunStream_MagnetURI_PassesValidation(t *testing.T) {
+	deps := streamDeps{
+		newStreamEngine: func(cfg engine.StreamConfig) (*engine.StreamEngine, error) {
+			return nil, fmt.Errorf("test: stopping after validation")
+		},
+		newStreamServer: engine.NewStreamServer,
+		openPlayer: func(url, override string) (string, *exec.Cmd, error) {
+			return "", nil, nil
+		},
+	}
+
+	magnet := "magnet:?xt=urn:btih:abc123def456abc123def456abc123def456abc1&dn=Test"
+	err := runStreamWithDeps(magnet, 0, true, "", deps)
+	if err == nil {
+		t.Fatal("expected error from newStreamEngine mock")
+	}
+	if strings.Contains(err.Error(), "invalid input") {
+		t.Errorf("magnet URI should be valid, got validation error: %v", err)
+	}
+}
+
+func TestRunStream_EngineCreationFails(t *testing.T) {
+	deps := streamDeps{
+		newStreamEngine: func(cfg engine.StreamConfig) (*engine.StreamEngine, error) {
+			return nil, fmt.Errorf("failed to create torrent client")
+		},
+		newStreamServer: engine.NewStreamServer,
+		openPlayer: func(url, override string) (string, *exec.Cmd, error) {
+			return "", nil, nil
+		},
+	}
+
+	err := runStreamWithDeps("abc123def456abc123def456abc123def456abc1", 0, true, "", deps)
+	if err == nil {
+		t.Fatal("expected error when engine creation fails")
+	}
+	if !strings.Contains(err.Error(), "create stream engine") {
+		t.Errorf("error = %q, want 'create stream engine' in message", err.Error())
+	}
+}
+
+func TestRunStreamCmd_Args_TooFew(t *testing.T) {
+	cmd := newStreamCmd()
+	err := cmd.Args(cmd, []string{})
+	if err == nil {
+		t.Fatal("expected error for 0 args")
+	}
+}
+
+func TestRunStreamCmd_Args_TooMany(t *testing.T) {
+	cmd := newStreamCmd()
+	err := cmd.Args(cmd, []string{"hash1", "hash2"})
+	if err == nil {
+		t.Fatal("expected error for 2 args")
+	}
+}
+
+func TestRunStreamCmd_Args_ExactlyOne(t *testing.T) {
+	cmd := newStreamCmd()
+	err := cmd.Args(cmd, []string{"abc123def456abc123def456abc123def456abc1"})
+	if err != nil {
+		t.Errorf("unexpected error for 1 arg: %v", err)
+	}
+}
+
+func TestRunStream_PartialMagnet_Prefix(t *testing.T) {
+	// "magnet:" sin hash es válido para el parser (tiene el prefijo magnet:)
+	// pero no tiene infoHash — debe pasar la validación de input
+	deps := streamDeps{
+		newStreamEngine: func(cfg engine.StreamConfig) (*engine.StreamEngine, error) {
+			return nil, fmt.Errorf("test stop")
+		},
+		newStreamServer: engine.NewStreamServer,
+		openPlayer:      func(url, override string) (string, *exec.Cmd, error) { return "", nil, nil },
+	}
+	// "magnet:" sin btih se trata como magnet (HasPrefix("magnet:") == true)
+	// por lo que pasa la validación de input
+	err := runStreamWithDeps("magnet:", 0, true, "", deps)
+	// Debe llegar al engine (validación OK) o fallar con error de engine
+	_ = err // no verificamos el contenido exacto, solo que no haya panic
+}
+
+func TestRunStream_NoOpen_DoesNotCallOpenPlayer(t *testing.T) {
+	playerCalled := false
+	deps := streamDeps{
+		newStreamEngine: func(cfg engine.StreamConfig) (*engine.StreamEngine, error) {
+			return nil, fmt.Errorf("test: stopping early")
+		},
+		newStreamServer: engine.NewStreamServer,
+		openPlayer: func(url, override string) (string, *exec.Cmd, error) {
+			playerCalled = true
+			return "mpv", nil, nil
+		},
+	}
+
+	// noOpen=true → openPlayer no debe llamarse
+	runStreamWithDeps("abc123def456abc123def456abc123def456abc1", 0, true, "", deps) //nolint:errcheck
+
+	if playerCalled {
+		t.Error("openPlayer should NOT be called when noOpen=true")
+	}
+}
diff --git a/internal/cmd/stubs.go b/internal/cmd/stubs.go
deleted file mode 100644
index bcd0d90..0000000
--- a/internal/cmd/stubs.go
+++ /dev/null
@@ -1,22 +0,0 @@
-package cmd
-
-import (
-	"fmt"
-
-	"github.com/fatih/color"
-	"github.com/spf13/cobra"
-)
-
-func newStubCmd(name, short string) *cobra.Command {
-	return &cobra.Command{
-		Use:   name,
-		Short: short + " (coming soon)",
-		Run: func(cmd *cobra.Command, args []string) {
-			fmt.Println()
-			color.New(color.FgYellow).Printf("  ⚠️  '%s' is coming in a future release.\n", name)
-			fmt.Println()
-			fmt.Println("  Follow progress at: https://github.com/torrentclaw/unarr")
-			fmt.Println()
-		},
-	}
-}
diff --git a/internal/cmd/upgrade.go b/internal/cmd/upgrade.go
new file mode 100644
index 0000000..63f56f9
--- /dev/null
+++ b/internal/cmd/upgrade.go
@@ -0,0 +1,33 @@
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+// newUpgradeCmd creates the `unarr upgrade` command as an alias for `self-update`.
+func newUpgradeCmd() *cobra.Command {
+	var force bool
+	var allowUnsigned bool
+
+	cmd := &cobra.Command{
+		Use:     "upgrade",
+		Aliases: []string{"update"},
+		Short:   "Update unarr to the latest version",
+		Long: `Download and install the latest version of unarr.
+
+This is an alias for 'unarr self-update'. Checks GitHub for the latest
+release, verifies the checksum, and replaces the current binary.
+A backup is kept at <binary>.backup.`,
+		Example: `  unarr upgrade
+  unarr upgrade --force
+  unarr upgrade --allow-unsigned`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runSelfUpdate(force, allowUnsigned)
+		},
+	}
+
+	cmd.Flags().BoolVarP(&force, "force", "f", false, "reinstall even if already up to date")
+	cmd.Flags().BoolVar(&allowUnsigned, "allow-unsigned", false, "continue with SHA256-only verification when checksums.txt.sig is missing")
+
+	return cmd
+}
diff --git a/internal/cmd/version.go b/internal/cmd/version.go
index 0f63091..194e3c0 100644
--- a/internal/cmd/version.go
+++ b/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.3.4-dev"
+var Version = "0.9.15"
diff --git a/internal/cmd/vpn.go b/internal/cmd/vpn.go
new file mode 100644
index 0000000..fb11532
--- /dev/null
+++ b/internal/cmd/vpn.go
@@ -0,0 +1,213 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"time"
+
+	"github.com/fatih/color"
+	"github.com/spf13/cobra"
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/config"
+	"github.com/torrentclaw/unarr/internal/vpn"
+)
+
+func newVPNCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "vpn",
+		Short: "Manage the managed-VPN split-tunnel for downloads",
+		Long: `Enable, disable, and inspect the managed VPN.
+
+When enabled, the daemon fetches a WireGuard config from your TorrentClaw account
+at startup and routes ONLY the torrent client's traffic (peers + trackers) through
+an in-process WireGuard tunnel — no root, no OS routing changes.
+
+This is split-tunnel: your browser and other apps keep using your real IP. Only
+your downloads are hidden behind the VPN server.
+
+The VPN requires a PRO+ plan with the VPN add-on. Set it up at
+https://torrentclaw.com/vpn and configure your other devices (phone, laptop) with
+the OpenVPN credentials from your profile — those don't share the agent's tunnel.`,
+		Example: `  unarr vpn status      # is the tunnel up? which server?
+  unarr vpn enable      # turn the managed VPN on
+  unarr vpn disable     # turn it off`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Help()
+		},
+	}
+	cmd.AddCommand(newVPNStatusCmd(), newVPNEnableCmd(), newVPNDisableCmd())
+	return cmd
+}
+
+func newVPNStatusCmd() *cobra.Command {
+	var check bool
+	cmd := &cobra.Command{
+		Use:     "status",
+		Short:   "Show VPN configuration and live tunnel state",
+		Example: "  unarr vpn status\n  unarr vpn status --check   # also verify your account is provisioned",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runVPNStatus(check)
+		},
+	}
+	cmd.Flags().BoolVar(&check, "check", false, "query the API to verify the VPN is provisioned on your account")
+	return cmd
+}
+
+func runVPNStatus(check bool) error {
+	bold := color.New(color.Bold)
+	dim := color.New(color.FgHiBlack)
+	green := color.New(color.FgGreen)
+	yellow := color.New(color.FgYellow)
+	cyan := color.New(color.FgCyan)
+
+	cfg := loadConfig()
+
+	fmt.Println()
+	bold.Println("  Managed VPN")
+	fmt.Println()
+
+	// ── Configured mode ──
+	switch {
+	case cfg.Download.VPN.ConfigFile != "":
+		cyan.Println("  Mode:    self-hosted (local config_file)")
+		fmt.Printf("  Config:  %s\n", cfg.Download.VPN.ConfigFile)
+	case cfg.Download.VPN.Enabled:
+		cyan.Println("  Mode:    managed (config fetched from your account)")
+	default:
+		dim.Println("  Mode:    off")
+		fmt.Println()
+		dim.Println("  Enable with `unarr vpn enable` (needs a PRO+ plan with the VPN add-on).")
+		fmt.Println()
+		return nil
+	}
+
+	// ── Live tunnel state (from the daemon state file) ──
+	state := agent.ReadState()
+	alive := state != nil && isDaemonAlive(state)
+	fmt.Println()
+	switch {
+	case alive && state.VPNActive:
+		server := state.VPNServer
+		if host, _, err := net.SplitHostPort(server); err == nil && host != "" {
+			server = host
+		}
+		green.Println("  ✓ Tunnel ACTIVE — torrent traffic is routed through the VPN")
+		if server != "" {
+			fmt.Printf("    Exit server: %s\n", server)
+		}
+	case alive:
+		yellow.Println("  ⚠  Daemon is running but the tunnel is NOT up — downloads go in the clear.")
+		dim.Println("     Check `unarr daemon logs` for a [vpn] line. Common cause: no active")
+		dim.Println("     VPN on your account (set it up at https://torrentclaw.com/vpn).")
+	default:
+		dim.Println("  Daemon not running — start it (`unarr start`) to bring the tunnel up.")
+	}
+
+	// ── Optional live provisioning check ──
+	if check {
+		fmt.Println()
+		if cfg.Auth.APIKey == "" {
+			yellow.Println("  ⚠  No API key — run `unarr init` first.")
+		} else {
+			apiURL := cfg.Auth.APIURL
+			if apiURL == "" {
+				apiURL = "https://torrentclaw.com"
+			}
+			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			_, err := vpn.FetchConfig(ctx, apiURL, cfg.Auth.APIKey, "unarr/"+Version, cfg.Agent.ID, true)
+			cancel()
+			switch {
+			case err == nil:
+				green.Println("  ✓ Account provisioned — a VPN config is available.")
+			default:
+				yellow.Printf("  ⚠  %s\n", err)
+			}
+		}
+	}
+
+	// ── Split-tunnel reminder ──
+	fmt.Println()
+	dim.Println("  Split-tunnel: only your downloads use the VPN. Your browser and other")
+	dim.Println("  apps keep your real IP — that's by design. Use the OpenVPN credentials in")
+	dim.Println("  your profile to protect your other devices.")
+	fmt.Println()
+	return nil
+}
+
+func newVPNEnableCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "enable",
+		Short:   "Turn the managed VPN on",
+		Example: "  unarr vpn enable",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return setVPNEnabled(true)
+		},
+	}
+}
+
+func newVPNDisableCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:     "disable",
+		Short:   "Turn the managed VPN off",
+		Example: "  unarr vpn disable",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return setVPNEnabled(false)
+		},
+	}
+}
+
+func setVPNEnabled(enabled bool) error {
+	green := color.New(color.FgGreen)
+	yellow := color.New(color.FgYellow)
+	dim := color.New(color.FgHiBlack)
+
+	cfg := loadConfig()
+
+	if enabled && cfg.Auth.APIKey == "" {
+		return fmt.Errorf("no API key configured — run `unarr init` first (the managed VPN fetches its config from your account)")
+	}
+
+	if cfg.Download.VPN.Enabled == enabled {
+		fmt.Println()
+		dim.Printf("  VPN is already %s — nothing to do.\n", enabledWord(enabled))
+		fmt.Println()
+		return nil
+	}
+
+	cfg.Download.VPN.Enabled = enabled
+
+	configPath := config.FilePath()
+	if cfgFile != "" {
+		configPath = cfgFile
+	}
+	if err := config.Save(cfg, configPath); err != nil {
+		return fmt.Errorf("save config: %w", err)
+	}
+	appCfg = cfg
+
+	fmt.Println()
+	green.Printf("  ✓ Managed VPN %s.\n", enabledWord(enabled))
+
+	if enabled && cfg.Download.VPN.ConfigFile != "" {
+		yellow.Println("  ⚠  A config_file is set, so self-hosted mode takes precedence and the")
+		yellow.Println("     managed config from your account is ignored. Clear config_file to use it.")
+	}
+
+	// The tunnel is brought up once at daemon startup; a plain config reload does
+	// NOT (re)create it. Tell the user to restart the daemon if it's running.
+	if state := agent.ReadState(); state != nil && isDaemonAlive(state) {
+		fmt.Println()
+		dim.Println("  The daemon is running. Restart it for this to take effect:")
+		dim.Println("    unarr daemon restart")
+	}
+	fmt.Println()
+	return nil
+}
+
+func enabledWord(enabled bool) string {
+	if enabled {
+		return "enabled"
+	}
+	return "disabled"
+}
diff --git a/internal/config/config.go b/internal/config/config.go
index 04195b7..dd406a6 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -26,7 +26,11 @@ type Config struct {
 type AuthConfig struct {
 	APIKey string `toml:"api_key"`
 	APIURL string `toml:"api_url"`
-	WSURL  string `toml:"ws_url"` // optional, derived from api_url if empty
+	// Mirrors lists alternate base URLs the agent will fall back to when the
+	// primary api_url is unreachable. Ordered by preference. Refreshed at
+	// runtime by `unarr mirrors update` against /api/v1/mirrors so a long-
+	// running agent survives a primary takedown without a new release.
+	Mirrors []string `toml:"mirrors"`
 }
 
 type AgentConfig struct {
@@ -35,15 +39,88 @@ 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)
+	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"`
+}
+
+// HLSCacheConfig controls the persistent HLS segment cache. A completed encode
+// is kept on disk so a second play of the same file at the same quality skips
+// ffmpeg entirely. Old entries are evicted (LRU) once the cache exceeds the
+// 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
+}
+
+// FunnelConfig gates the optional CloudFlare Quick Tunnel that exposes the
+// daemon's HLS server over a public HTTPS hostname (https://<random>.try
+// cloudflare.com). Enabling it lets the web player on torrentclaw.com play
+// from this daemon across any network without Tailscale or a public IP —
+// the cost is that bytes proxy through CloudFlare's network. Off by default.
+type FunnelConfig struct {
+	Enabled bool `toml:"enabled"`
+}
+
+// VPNConfig gates the managed-VPN add-on split-tunnel. When enabled, the daemon
+// fetches a WireGuard config from the web (/api/internal/agent/vpn-config) and
+// routes only the torrent client's peer/tracker traffic through an in-process
+// userspace tunnel (no root, no OS routing changes). Requires an active VPN
+// add-on on the account; otherwise the daemon logs and downloads in the clear.
+type VPNConfig struct {
+	Enabled bool `toml:"enabled"`
+	// ConfigFile, when set, makes the daemon read a local WireGuard .conf instead
+	// of fetching one from the web API. For self-hosted / personal-VPN testing:
+	// point it at a peer .conf from your own WireGuard server and the torrent
+	// client split-tunnels through it with no web/provider plumbing.
+	ConfigFile string `toml:"config_file"`
+}
+
+// TranscodeConfig controls real-time transcoding for the in-browser player
+// when source codecs aren't browser-decodable (HEVC, AV1, AC3, DTS, etc.).
+// Disabled by default; enabling requires ffmpeg + ffprobe on PATH (or
+// explicit paths via the library config).
+type TranscodeConfig struct {
+	Enabled bool   `toml:"enabled"`  // master switch
+	HWAccel string `toml:"hw_accel"` // "auto" | "none" | "nvenc" | "qsv" | "vaapi" | "videotoolbox"
+	// Preset is the encoder speed/quality dial. Only used on software encode
+	// (libx264) — HW backends (NVENC/QSV/VAAPI/VideoToolbox) use vendor
+	// presets that don't share libx264's vocabulary and would be rejected
+	// by ffmpeg if passed here.
+	//
+	// Empty (default) → engine picks "superfast" — latency-biased, ~3 s
+	// first-play on 1080p source on a modern x86 CPU. Marginal quality loss
+	// at 5-25 Mbps target bitrates.
+	//
+	// For better quality at slower first-play (1-2 s slower per seg):
+	//   "veryfast"  — previous default; balanced
+	//   "faster"    — slight quality bump
+	//   "fast"      — meaningful quality bump
+	//   "medium"    — libx264 stock default; CPU-bound on 4K
+	//   "slow" / "slower" / "veryslow" — only for batch encodes, not real-time HLS
+	//
+	// Or faster:
+	//   "ultrafast" — lowest quality, fastest encode
+	Preset        string `toml:"preset"`
+	VideoBitrate  string `toml:"video_bitrate"`  // e.g. "5M"
+	AudioBitrate  string `toml:"audio_bitrate"`  // e.g. "192k"
+	MaxHeight     int    `toml:"max_height"`     // optional downscale cap (e.g. 720)
+	MaxConcurrent int    `toml:"max_concurrent"` // safety cap on simultaneous transcoder processes
 }
 
 type OrganizeConfig struct {
@@ -53,10 +130,28 @@ type OrganizeConfig struct {
 }
 
 type DaemonConfig struct {
-	PollInterval      string `toml:"poll_interval"`
-	HeartbeatInterval string `toml:"heartbeat_interval"`
+	StatusInterval string `toml:"status_interval"`
+	// AutoUpgrade gates the daemon's response to a server-flagged upgrade
+	// (set via the "Force update" button on the web). When true the daemon
+	// downloads + replaces the binary in-place and exits so the service
+	// supervisor respawns on the new version. When false the daemon only
+	// logs "new version available" and the operator must run `unarr update`
+	// manually. Default: true. Available since unarr 0.9.6.
+	AutoUpgrade *bool `toml:"auto_upgrade"`
 }
 
+// AutoUpgradeEnabled returns the resolved AutoUpgrade flag — defaults to true
+// when the user has not set it explicitly. Pointer-vs-bool because Go's
+// zero-value bool would collapse "unset" and "false" together.
+func (d DaemonConfig) AutoUpgradeEnabled() bool {
+	if d.AutoUpgrade == nil {
+		return true
+	}
+	return *d.AutoUpgrade
+}
+
+func boolPtr(v bool) *bool { return &v }
+
 type NotificationsConfig struct {
 	Enabled bool `toml:"enabled"`
 }
@@ -71,28 +166,66 @@ type LibraryConfig struct {
 	ScanPath     string `toml:"scan_path"`     // remembered from last scan
 	Workers      int    `toml:"workers"`       // concurrent ffprobe (default 8)
 	FFprobePath  string `toml:"ffprobe_path"`  // optional explicit path
+	FFmpegPath   string `toml:"ffmpeg_path"`   // optional explicit path (used by the HLS streaming transcoder)
 	BackupDir    string `toml:"backup_dir"`    // for replaced files
 	AutoScan     bool   `toml:"auto_scan"`     // enable daily auto-scan in daemon (default true)
 	ScanInterval string `toml:"scan_interval"` // e.g. "24h", "12h", "6h" (default "24h")
+	AllowDelete  bool   `toml:"allow_delete"`  // allow web UI to request file deletion from disk
 }
 
-// Default returns a Config with sensible defaults.
+// Default returns a Config with sensible defaults. Used both for fresh
+// installs (no config file yet) and as the baseline for Load — fields not
+// present in the user's TOML keep their Default() value.
 func Default() Config {
 	return Config{
 		Auth: AuthConfig{
 			APIURL: "https://torrentclaw.com",
+			// Default mirror list. Kept in sync with src/lib/mirrors-config.ts
+			// on the server. Users can override with `unarr mirrors update`,
+			// which pulls the live list from /api/v1/mirrors.
+			Mirrors: []string{
+				"https://torrentclaw.to",
+			},
 		},
 		Download: DownloadConfig{
 			PreferredMethod: "auto",
 			MaxConcurrent:   3,
+			StreamPort:      11818,
+			Transcode: TranscodeConfig{
+				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.
+				Preset:        "",
+				AudioBitrate:  "192k",
+				MaxConcurrent: 2,
+			},
+			Funnel: FunnelConfig{
+				// On by default so headless installs (NAS / Docker) get cross-network
+				// HTTPS playback without anyone having to terminal in. Users who
+				// don't want bytes proxied through CloudFlare can opt out with
+				// `unarr funnel off` (sets enabled=false in the TOML).
+				Enabled: true,
+			},
+			HLSCache: HLSCacheConfig{
+				// On by default — second play of a recently watched file at the
+				// same quality skips ffmpeg (instant start, near-zero CPU).
+				// Users can opt out (hls_cache.enabled=false) or shrink the
+				// budget (hls_cache.size_gb) when disk is tight.
+				Enabled: true,
+				SizeGB:  5,
+			},
+		},
+		Daemon: DaemonConfig{
+			// Pointer-to-true so Default() round-trips through TOML marshal
+			// as `auto_upgrade = true` instead of an omitted key — keeps the
+			// freshly-written config aligned with what README documents.
+			AutoUpgrade: boolPtr(true),
 		},
 		Organize: OrganizeConfig{
 			Enabled: true,
 		},
-		Daemon: DaemonConfig{
-			PollInterval:      "30s",
-			HeartbeatInterval: "30s",
-		},
 		Notifications: NotificationsConfig{
 			Enabled: true,
 		},
@@ -126,25 +259,67 @@ func Load(path string) (Config, error) {
 		return cfg, fmt.Errorf("read config: %w", err)
 	}
 
-	if err := toml.Unmarshal(data, &cfg); err != nil {
+	meta, err := toml.Decode(string(data), &cfg)
+	if err != nil {
 		return cfg, fmt.Errorf("parse config: %w", err)
 	}
 
-	// Re-apply defaults for zero values that should have defaults
-	if cfg.Auth.APIURL == "" {
+	applyDefaults(&cfg, meta)
+	return cfg, nil
+}
+
+// applyDefaults fills in sensible defaults for keys that the user did not
+// define in the TOML file. We use MetaData (rather than zero-value checks) so
+// that explicitly setting a field to its zero value (e.g. `enabled = false`)
+// is respected — only truly missing keys get defaulted. This lets a fresh
+// install work out of the box for streaming without forcing every user to
+// edit the TOML, while still letting power users disable features.
+func applyDefaults(cfg *Config, meta toml.MetaData) {
+	if !meta.IsDefined("auth", "api_url") {
 		cfg.Auth.APIURL = "https://torrentclaw.com"
 	}
-	if cfg.Download.PreferredMethod == "" {
+	if !meta.IsDefined("auth", "mirrors") {
+		cfg.Auth.Mirrors = []string{"https://torrentclaw.to"}
+	}
+	if !meta.IsDefined("downloads", "preferred_method") {
 		cfg.Download.PreferredMethod = "auto"
 	}
-	if cfg.Download.MaxConcurrent == 0 {
+	if !meta.IsDefined("downloads", "max_concurrent") {
 		cfg.Download.MaxConcurrent = 3
 	}
-	if cfg.General.Country == "" {
+	if !meta.IsDefined("downloads", "stream_port") {
+		cfg.Download.StreamPort = 11818
+	}
+	if !meta.IsDefined("general", "country") {
 		cfg.General.Country = "US"
 	}
 
-	return cfg, nil
+	if !meta.IsDefined("downloads", "transcode", "enabled") {
+		cfg.Download.Transcode.Enabled = true
+	}
+	if !meta.IsDefined("downloads", "transcode", "hw_accel") {
+		cfg.Download.Transcode.HWAccel = "auto"
+	}
+	if !meta.IsDefined("downloads", "transcode", "preset") {
+		// Empty = let engine.ResolveEncoderProfile pick the latency-biased
+		// default ("superfast" on libx264). Users wanting better quality at
+		// slower first-play can override to "veryfast" / "fast" / "medium" in
+		// config.toml. Ignored when hw_accel picks NVENC/QSV/VAAPI/VideoToolbox
+		// (those have built-in vendor presets).
+		cfg.Download.Transcode.Preset = ""
+	}
+	if !meta.IsDefined("downloads", "transcode", "audio_bitrate") {
+		cfg.Download.Transcode.AudioBitrate = "192k"
+	}
+	if !meta.IsDefined("downloads", "transcode", "max_concurrent") {
+		cfg.Download.Transcode.MaxConcurrent = 2
+	}
+	// NOTE: Funnel default-ON only applies to fresh installs (no config file →
+	// Default() returns Funnel.Enabled=true straight off). When an existing
+	// config file lacks `[downloads.funnel]` entirely we intentionally do NOT
+	// flip it on here — that would silently route an upgraded operator's
+	// traffic through CloudFlare without their consent. They opt in with
+	// `unarr funnel on` whenever they're ready.
 }
 
 // Save writes config to the default or specified path using atomic write.
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 3190399..c43599f 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -21,8 +21,8 @@ func TestDefault(t *testing.T) {
 	if cfg.General.Country != "US" {
 		t.Errorf("default Country = %q, want US", cfg.General.Country)
 	}
-	if cfg.Daemon.HeartbeatInterval != "30s" {
-		t.Errorf("default HeartbeatInterval = %q, want 30s", cfg.Daemon.HeartbeatInterval)
+	if cfg.Daemon.StatusInterval != "" {
+		t.Errorf("default StatusInterval = %q, want empty", cfg.Daemon.StatusInterval)
 	}
 }
 
@@ -190,6 +190,62 @@ func TestParseSpeed(t *testing.T) {
 	}
 }
 
+func TestLoadMinimalTOMLAppliesStreamingDefaults(t *testing.T) {
+	tmp := t.TempDir()
+	path := filepath.Join(tmp, "config.toml")
+
+	// Minimal config — only auth + agent. Nothing about webrtc / transcode.
+	os.WriteFile(path, []byte(`[auth]
+api_key = "tc_minimal"
+
+[agent]
+id = "agent-uuid"
+name = "Test"
+`), 0o644)
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	// Transcode should be on by default.
+	if !cfg.Download.Transcode.Enabled {
+		t.Error("Transcode.Enabled should default to true when [downloads.transcode] is absent")
+	}
+	if cfg.Download.Transcode.HWAccel != "auto" {
+		t.Errorf("Transcode.HWAccel = %q, want auto", cfg.Download.Transcode.HWAccel)
+	}
+	if cfg.Download.Transcode.Preset != "" {
+		// Default is now empty — engine.ResolveEncoderProfile picks
+		// "superfast" on libx264 for first-start latency. Users
+		// wanting better quality override in config.toml.
+		t.Errorf("Transcode.Preset = %q, want empty", cfg.Download.Transcode.Preset)
+	}
+	if cfg.Download.Transcode.MaxConcurrent != 2 {
+		t.Errorf("Transcode.MaxConcurrent = %d, want 2", cfg.Download.Transcode.MaxConcurrent)
+	}
+}
+
+func TestLoadRespectsExplicitlyDisabledStreaming(t *testing.T) {
+	tmp := t.TempDir()
+	path := filepath.Join(tmp, "config.toml")
+
+	// User explicitly opted out of transcode. Defaults must NOT override
+	// it — that would silently re-enable a feature the user disabled.
+	os.WriteFile(path, []byte(`[downloads.transcode]
+enabled = false
+`), 0o644)
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	if cfg.Download.Transcode.Enabled {
+		t.Error("Transcode.Enabled = true, want false (user explicitly disabled)")
+	}
+}
+
 func TestLoadInvalidTOML(t *testing.T) {
 	tmp := t.TempDir()
 	path := filepath.Join(tmp, "config.toml")
diff --git a/internal/engine/debrid.go b/internal/engine/debrid.go
index 7aea0bf..fce60dd 100644
--- a/internal/engine/debrid.go
+++ b/internal/engine/debrid.go
@@ -10,6 +10,8 @@ import (
 	"path/filepath"
 	"sync"
 	"time"
+
+	"github.com/torrentclaw/unarr/internal/agent"
 )
 
 // httpClient is used for debrid HTTPS downloads with a reasonable header timeout.
@@ -19,13 +21,6 @@ var httpClient = &http.Client{
 	},
 }
 
-func shortID(id string) string {
-	if len(id) > 8 {
-		return id[:8]
-	}
-	return id
-}
-
 // DebridDownloader downloads files via HTTPS direct URLs resolved by the server.
 // The server handles all debrid provider interaction; this downloader only needs
 // a plain HTTPS URL to fetch.
@@ -129,7 +124,7 @@ func (d *DebridDownloader) Download(ctx context.Context, task *Task, outputDir s
 				var serverSize int64
 				if _, err := fmt.Sscanf(cr, "bytes */%d", &serverSize); err == nil && serverSize > 0 && existingSize != serverSize {
 					// Local file size doesn't match server — re-download from scratch
-					log.Printf("[%s] local size %s != server size %s, re-downloading", shortID(task.ID), formatBytes(existingSize), formatBytes(serverSize))
+					log.Printf("[%s] local size %s != server size %s, re-downloading", agent.ShortID(task.ID), formatBytes(existingSize), formatBytes(serverSize))
 					resp.Body.Close()
 					req2, err := http.NewRequestWithContext(dlCtx, http.MethodGet, task.DirectURL, nil)
 					if err != nil {
@@ -149,7 +144,7 @@ func (d *DebridDownloader) Download(ctx context.Context, task *Task, outputDir s
 					break // continue to download loop
 				}
 			}
-			log.Printf("[%s] file already complete: %s (%s)", shortID(task.ID), fileName, formatBytes(existingSize))
+			log.Printf("[%s] file already complete: %s (%s)", agent.ShortID(task.ID), fileName, formatBytes(existingSize))
 			return &Result{
 				FilePath: destPath,
 				FileName: fileName,
@@ -166,10 +161,10 @@ func (d *DebridDownloader) Download(ctx context.Context, task *Task, outputDir s
 	var flags int
 	if startOffset > 0 {
 		flags = os.O_WRONLY | os.O_APPEND
-		log.Printf("[%s] resuming debrid download at %s: %s", shortID(task.ID), formatBytes(startOffset), fileName)
+		log.Printf("[%s] resuming debrid download at %s: %s", agent.ShortID(task.ID), formatBytes(startOffset), fileName)
 	} else {
 		flags = os.O_WRONLY | os.O_CREATE | os.O_TRUNC
-		log.Printf("[%s] starting debrid download: %s", shortID(task.ID), fileName)
+		log.Printf("[%s] starting debrid download: %s", agent.ShortID(task.ID), fileName)
 	}
 
 	if err := os.MkdirAll(filepath.Dir(destPath), 0o755); err != nil {
@@ -223,7 +218,7 @@ func (d *DebridDownloader) Download(ctx context.Context, task *Task, outputDir s
 			}
 
 			log.Printf("[%s] %d%% — %s/%s @ %s/s  (debrid)",
-				shortID(task.ID), pct,
+				agent.ShortID(task.ID), pct,
 				formatBytes(downloaded), formatBytes(totalBytes), formatBytes(speed))
 
 			p := Progress{
@@ -252,7 +247,7 @@ func (d *DebridDownloader) Download(ctx context.Context, task *Task, outputDir s
 		}
 	}
 
-	log.Printf("[%s] debrid download complete: %s (%s)", shortID(task.ID), fileName, formatBytes(downloaded))
+	log.Printf("[%s] debrid download complete: %s (%s)", agent.ShortID(task.ID), fileName, formatBytes(downloaded))
 
 	return &Result{
 		FilePath: destPath,
@@ -271,7 +266,7 @@ func (d *DebridDownloader) Pause(taskID string) error {
 
 	if ok {
 		cancel()
-		log.Printf("[%s] debrid download paused (file kept for resume)", shortID(taskID))
+		log.Printf("[%s] debrid download paused (file kept for resume)", agent.ShortID(taskID))
 	}
 	return nil
 }
@@ -285,7 +280,7 @@ func (d *DebridDownloader) Cancel(taskID string) error {
 
 	if ok {
 		cancel()
-		log.Printf("[%s] debrid download cancelled", shortID(taskID))
+		log.Printf("[%s] debrid download cancelled", agent.ShortID(taskID))
 	}
 	return nil
 }
diff --git a/internal/engine/hls.go b/internal/engine/hls.go
new file mode 100644
index 0000000..86219d5
--- /dev/null
+++ b/internal/engine/hls.go
@@ -0,0 +1,1508 @@
+// Package engine — hls.go implements the HLS streaming pipeline.
+//
+// Browser ↔ daemon over plain HTTP (LAN / Tailscale / UPnP). The daemon runs
+// ffmpeg in `-f hls` mode, writing fragmented MP4 segments to a per-session
+// tmpdir. Master + media playlists are pre-rendered from the probed source
+// duration so the player knows the full timeline before any segment exists.
+//
+// One HLSSession == one browser playback. Sessions are registered in a
+// process-wide map keyed by session ID; the StreamServer routes
+//   GET /hls/<id>/master.m3u8
+//   GET /hls/<id>/video/index.m3u8
+//   GET /hls/<id>/video/init.mp4
+//   GET /hls/<id>/video/seg-<n>.m4s
+//   GET /hls/<id>/subs/<lang>.vtt
+// to the matching session.
+
+package engine
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// hlsSegmentDuration is the target seconds per HLS fragment.
+//
+// We use 2 seconds (not the more common 4-6 s). Trade-off: 2× more segments
+// per source (a 2 h movie produces 3600 segments instead of 1800), but the
+// player's first-frame wait drops to ~half — ffmpeg only needs to encode
+// 2 s before seg-0 lands. For software encodes on 4K this is ~1 s instead
+// of ~3 s of cold-cache wait. Well within HLS spec (Apple recommends 6 s,
+// but 2-6 s is acceptable; Low-Latency HLS uses 1-2 s segments).
+//
+// Caveat for existing cached encodes: cache entries from 0.9.9 used 4 s
+// segments. After this bump, VerifyComplete (which checks the highest
+// expected segment index) returns false for those entries — they're
+// invalidated + re-encoded with 2 s segments on next play. Self-healing.
+const hlsSegmentDuration = 2
+
+// segmentDurationFor returns the target duration (in whole seconds) for the
+// segment at index idx. With uniform-duration segments this is always
+// hlsSegmentDuration; the helper exists so a future short-first-segment
+// variant can be slotted in here without touching every call site.
+func segmentDurationFor(idx int) int {
+	return hlsSegmentDuration
+}
+
+// segmentStartSec returns the wall-clock start time of segment idx. Used
+// to compute the `-ss` flag when ffmpeg restarts at a mid-file segment.
+func segmentStartSec(idx int) float64 {
+	if idx <= 0 {
+		return 0
+	}
+	return float64(idx * hlsSegmentDuration)
+}
+
+// segmentCountForDuration returns how many segments cover a source of the
+// given duration. Always returns at least 1.
+func segmentCountForDuration(dur float64) int {
+	if dur <= 0 {
+		return 1
+	}
+	return int((dur + float64(hlsSegmentDuration) - 1) / float64(hlsSegmentDuration))
+}
+
+// hlsSessionTTL is how long a session can sit idle (no segment requests)
+// before the manager kills ffmpeg + cleans the tmpdir.
+const hlsSessionTTL = 30 * time.Minute
+
+// hlsTmpDirRoot returns the per-user tmpdir root for HLS sessions.
+//
+//	Linux:   ~/.cache/unarr/hls-sessions
+//	macOS:   ~/Library/Caches/unarr/hls-sessions
+//	Windows: %LOCALAPPDATA%/unarr/hls-sessions
+//
+// Falls back to os.TempDir() if the user cache dir can't be resolved.
+func hlsTmpDirRoot() string {
+	if dir, err := os.UserCacheDir(); err == nil {
+		return filepath.Join(dir, "unarr", "hls-sessions")
+	}
+	return filepath.Join(os.TempDir(), "unarr-hls-sessions")
+}
+
+// CleanupHLSOrphanDirs removes any per-session tmpdir under hlsTmpDirRoot
+// that's older than 1 h. Daemon restart drops the in-memory session
+// registry but leaves tmpdirs behind; on the next start we GC them so
+// disk usage doesn't grow unbounded across restarts. Sessions started
+// less than 1 h ago might still belong to the daemon we're booting (race
+// during a quick restart) — leave those alone.
+func CleanupHLSOrphanDirs() error {
+	root := hlsTmpDirRoot()
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	cutoff := time.Now().Add(-1 * time.Hour)
+	removed := 0
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		if info.ModTime().Before(cutoff) {
+			if err := os.RemoveAll(filepath.Join(root, e.Name())); err == nil {
+				removed++
+			}
+		}
+	}
+	if removed > 0 {
+		log.Printf("[hls] cleaned %d orphan tmpdir(s) at startup", removed)
+	}
+	return nil
+}
+
+// HLSSessionConfig describes a single browser playback session driven by HLS.
+type HLSSessionConfig struct {
+	SessionID  string
+	SourcePath string
+	FileName   string
+	Quality    string // "2160p"|"1080p"|"720p"|"480p"|"original"|""
+	AudioIndex int    // 0-based ffmpeg audio stream selection (-map 0:a:N). -1 = default.
+	Transcode  TranscodeRuntime
+	// Cache is an optional persistent segment cache keyed by (source, quality,
+	// audio). When set, completed encodes are kept across sessions so re-plays
+	// of the same file at the same quality skip ffmpeg entirely. nil disables
+	// caching (per-session tmpdir, deleted on Close — original behavior).
+	Cache *HLSCache
+}
+
+// HLSSession owns a tmpdir + ffmpeg subprocess producing HLS fragments.
+//
+// Seek behaviour: ffmpeg writes segments sequentially from `ffmpegSegStart`.
+// When a handler asks for a segment far ahead of the writer, the daemon
+// kills the current ffmpeg and restarts it with `-ss <targetSec>
+// -output_ts_offset <targetSec> -start_number <idx>` so the next segments
+// it emits land at the requested timeline position. Segments already on
+// disk before the seek stay there; the new ffmpeg only writes from the
+// target index forward.
+type HLSSession struct {
+	cfg   HLSSessionConfig
+	probe *StreamProbe
+
+	tmpDir        string
+	durationSec   float64
+	segmentCount  int
+	manifestVideo string // pre-rendered video media playlist
+	manifestRoot  string // pre-rendered master playlist
+
+	mu             sync.Mutex
+	cmd            *exec.Cmd
+	cancel         context.CancelFunc
+	closed         bool
+	startedAt      time.Time
+	lastTouch      time.Time
+	ffmpegSegStart int // index of the first segment the current ffmpeg writes
+	restartCount   int // bounded auto-restart counter (resets on Close)
+	lastRestartAt  time.Time
+
+	// 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)
+	// are fully on disk. A handler waiting on `idx` blocks until
+	// `idx < readyMax` (segment idx is present). The pollSegments goroutine
+	// advances readyMax and re-creates readyCh on every step.
+	readyMu  sync.Mutex
+	readyMax int
+	exitErr  error
+	exited   bool
+	readyCh  chan struct{} // closed + replaced each time readyMax advances
+
+	// Persistent cache state. cache==nil means caching disabled for this session.
+	// fromCache=true means the session is replaying a completed encode and no
+	// ffmpeg subprocess was spawned. writerLockHeld=true means this session
+	// owns the per-key TryAcquireWriter claim — Close must ReleaseWriter.
+	// subsDone closes when the subtitle extractor goroutine returns (or is
+	// nil when the source had no subtitle tracks); MarkComplete waits on it
+	// so a HIT replay never serves partial .vtt files.
+	cache          *HLSCache
+	cacheKey       string
+	fromCache      bool
+	writerLockHeld bool
+	subsDone       chan struct{}
+}
+
+// hlsSeekAhead is how many segments past the writer's current position the
+// browser is allowed to request before we restart ffmpeg from the requested
+// segment. 8 segments * 4 s = 32 s of "warm" buffer; further seeks trigger
+// a restart instead of waiting through real-time encode.
+const hlsSeekAhead = 8
+
+// HLSSessionRegistry tracks active sessions keyed by ID.
+type HLSSessionRegistry struct {
+	mu       sync.RWMutex
+	sessions map[string]*HLSSession
+}
+
+// NewHLSSessionRegistry returns an empty registry.
+func NewHLSSessionRegistry() *HLSSessionRegistry {
+	return &HLSSessionRegistry{sessions: make(map[string]*HLSSession)}
+}
+
+// Get fetches a session by ID; returns nil if not registered.
+func (r *HLSSessionRegistry) Get(id string) *HLSSession {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	return r.sessions[id]
+}
+
+// Register adds a session under its ID. Replaces any previous session with
+// the same ID (which is closed first to release ffmpeg + tmpdir).
+//
+// Also closes EVERY OTHER active session, since one daemon == one viewer ==
+// one stream at a time. Without this, repeatedly opening the player (or
+// changing quality) leaves orphan ffmpegs running until the 30 min idle
+// sweeper reaps them, and N concurrent transcodes saturate the CPU.
+func (r *HLSSessionRegistry) Register(s *HLSSession) {
+	r.mu.Lock()
+	stale := make([]*HLSSession, 0, len(r.sessions))
+	for id, prev := range r.sessions {
+		if id == s.cfg.SessionID {
+			stale = append(stale, prev)
+			continue
+		}
+		stale = append(stale, prev)
+		delete(r.sessions, id)
+	}
+	r.sessions[s.cfg.SessionID] = s
+	r.mu.Unlock()
+	for _, prev := range stale {
+		_ = prev.Close()
+	}
+}
+
+// Remove drops a session from the registry without closing it.
+func (r *HLSSessionRegistry) Remove(id string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	delete(r.sessions, id)
+}
+
+// CloseAll terminates every active session. Call at daemon shutdown.
+func (r *HLSSessionRegistry) CloseAll() {
+	r.mu.Lock()
+	sessions := make([]*HLSSession, 0, len(r.sessions))
+	for _, s := range r.sessions {
+		sessions = append(sessions, s)
+	}
+	r.sessions = make(map[string]*HLSSession)
+	r.mu.Unlock()
+	for _, s := range sessions {
+		_ = s.Close()
+	}
+}
+
+// SweepIdle closes sessions that have not been touched within hlsSessionTTL.
+// Returns the number of sessions reaped.
+func (r *HLSSessionRegistry) SweepIdle() int {
+	r.mu.Lock()
+	stale := make([]*HLSSession, 0)
+	for id, s := range r.sessions {
+		s.mu.Lock()
+		idle := time.Since(s.lastTouch)
+		s.mu.Unlock()
+		if idle > hlsSessionTTL {
+			stale = append(stale, s)
+			delete(r.sessions, id)
+		}
+	}
+	r.mu.Unlock()
+	for _, s := range stale {
+		_ = s.Close()
+	}
+	return len(stale)
+}
+
+// StartHLSSession probes the source, builds the playlists, spawns ffmpeg,
+// and returns a HLSSession ready to serve HTTP requests. Caller must register
+// the session with a HLSSessionRegistry so the server can route to it.
+func StartHLSSession(ctx context.Context, cfg HLSSessionConfig) (*HLSSession, error) {
+	if cfg.SessionID == "" {
+		return nil, errors.New("hls: empty session id")
+	}
+	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.Transcode.FFmpegPath == "" || cfg.Transcode.FFprobePath == "" {
+		return nil, errors.New("hls: ffmpeg/ffprobe not available")
+	}
+
+	// Probe gets a 15 s ceiling. ffprobe on a 50 GB MKV over a slow remote
+	// fs can hang indefinitely; without a deadline the daemon would block
+	// 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)
+	cancelProbe()
+	if err != nil {
+		return nil, fmt.Errorf("hls: probe: %w", err)
+	}
+	if probe.DurationSec <= 0 {
+		return nil, errors.New("hls: source has no duration")
+	}
+
+	// Resolve tmpDir + cache placement. Three states:
+	//   1. cache disabled              → per-session tmpdir, deleted on Close.
+	//   2. cache HIT (.complete found) → read from cache dir, no ffmpeg, Pin.
+	//   3. cache MISS, writer-lock OK  → ffmpeg writes to cache dir, Pin + writer-lock.
+	//   4. cache MISS, writer-lock NO  → another session already writing this
+	//                                    key; fall back to private per-session tmpdir
+	//                                    (no caching for this session — second-writer
+	//                                    would corrupt the first one's segments).
+	var (
+		tmpDir         string
+		cacheKey       string
+		fromCache      bool
+		writerLockHeld bool
+	)
+	if cfg.Cache != nil {
+		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.
+		segCountForVerify := segmentCountForDuration(probe.DurationSec)
+		if cfg.Cache.HasComplete(cacheKey) && !cfg.Cache.VerifyComplete(cacheKey, segCountForVerify) {
+			log.Printf("[hls %s] cache %s sealed but failed integrity check — re-encoding",
+				shortHLSID(cfg.SessionID), cacheKey)
+			_ = cfg.Cache.Invalidate(cacheKey)
+		}
+		if cfg.Cache.HasComplete(cacheKey) {
+			// HIT: read-only replay — many concurrent HITs are fine.
+			tmpDir = cfg.Cache.DirFor(cacheKey)
+			cfg.Cache.Pin(cacheKey)
+			fromCache = true
+			cfg.Cache.RecordHit()
+			_ = cfg.Cache.Touch(cacheKey)
+		} else if cfg.Cache.TryAcquireWriter(cacheKey) {
+			tmpDir = cfg.Cache.DirFor(cacheKey)
+			cfg.Cache.Pin(cacheKey)
+			writerLockHeld = true
+			cfg.Cache.RecordMiss()
+		} else {
+			// Another session is writing this key — fall back to private
+			// dir so we don't trample its segments.
+			log.Printf("[hls %s] cache key %s busy, falling back to per-session tmpdir",
+				shortHLSID(cfg.SessionID), cacheKey)
+			tmpDir = filepath.Join(hlsTmpDirRoot(), cfg.SessionID)
+			cacheKey = "" // disable caching for this session
+			cfg.Cache.RecordMiss()
+		}
+	} else {
+		tmpDir = filepath.Join(hlsTmpDirRoot(), cfg.SessionID)
+	}
+
+	cleanupOnError := func() {
+		if cfg.Cache != nil && cacheKey != "" {
+			cfg.Cache.Unpin(cacheKey)
+			if writerLockHeld {
+				cfg.Cache.ReleaseWriter(cacheKey)
+				_ = cfg.Cache.Invalidate(cacheKey)
+			}
+		} else {
+			_ = os.RemoveAll(tmpDir)
+		}
+	}
+
+	if err := os.MkdirAll(filepath.Join(tmpDir, "video"), 0o755); err != nil {
+		cleanupOnError()
+		return nil, fmt.Errorf("hls: mkdir video: %w", err)
+	}
+	if err := os.MkdirAll(filepath.Join(tmpDir, "subs"), 0o755); err != nil {
+		cleanupOnError()
+		return nil, fmt.Errorf("hls: mkdir subs: %w", err)
+	}
+
+	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{}),
+		cache:          cfg.Cache,
+		cacheKey:       cacheKey,
+		fromCache:      fromCache,
+		writerLockHeld: writerLockHeld,
+	}
+	s.manifestVideo = renderVideoPlaylist(probe.DurationSec, segCount)
+	s.manifestRoot = renderMasterPlaylist(probe, cfg.Quality)
+
+	// Cache HIT: every segment + init.mp4 is already on disk. Skip ffmpeg
+	// entirely and mark readyMax so handlers don't wait. Background subtitle
+	// extraction is also unnecessary — subs were extracted on the original run.
+	if fromCache {
+		s.readyMu.Lock()
+		s.readyMax = segCount - 1
+		s.exited = true
+		close(s.readyCh)
+		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),
+			probe.DurationSec, segCount, coalesce(cfg.Quality, "auto"))
+		return s, nil
+	}
+
+	// Spawn ffmpeg under a dedicated context so Close() can kill it without
+	// touching the parent ctx.
+	ffCtx, cancel := context.WithCancel(context.Background())
+	s.cancel = cancel
+	args := buildHLSFFmpegArgs(cfg, probe, tmpDir)
+	cmd := exec.CommandContext(ffCtx, cfg.Transcode.FFmpegPath, args...)
+	cmd.Stderr = &hlsStderrCapture{owner: s}
+	if err := cmd.Start(); err != nil {
+		cancel()
+		cleanupOnError()
+		return nil, fmt.Errorf("hls: start ffmpeg: %w", err)
+	}
+	s.cmd = cmd
+
+	go s.waitFFmpeg()
+	go s.pollSegments(ffCtx)
+
+	if len(probe.SubtitleTracks) > 0 {
+		s.subsDone = make(chan struct{})
+		go func() {
+			defer close(s.subsDone)
+			s.extractSubtitles(ffCtx)
+		}()
+	}
+
+	cachedNote := ""
+	if cfg.Cache != nil {
+		cachedNote = fmt.Sprintf(" (cache-miss %s)", cacheKey)
+	}
+	// Surface the encoder profile so a "first-start was slow" report can be
+	// triaged from the agent log alone — `encoder=libx264 accel=none` means
+	// the user's ffmpeg has no HW encoders compiled in, which is the most
+	// common root cause (linuxbrew, default brew formula on macOS).
+	profile := ResolveEncoderProfile(cfg.Transcode.HWAccel, cfg.Transcode.Preset)
+	presetNote := ""
+	if profile.Preset != "" {
+		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),
+		probe.DurationSec, segCount, coalesce(cfg.Quality, "auto"),
+		profile.Codec, string(cfg.Transcode.HWAccel), presetNote, cachedNote)
+	return s, nil
+}
+
+// shortHLSID truncates a session ID for log lines.
+func shortHLSID(id string) string {
+	if len(id) > 8 {
+		return id[:8]
+	}
+	return id
+}
+
+// ProbeInfo returns a JSON-friendly summary of the source media so the web
+// player can render quality / codec / track info without re-probing.
+func (s *HLSSession) ProbeInfo() map[string]any {
+	if s.probe == nil {
+		return map[string]any{}
+	}
+	audios := make([]map[string]any, 0, len(s.probe.AudioTracks))
+	for _, a := range s.probe.AudioTracks {
+		audios = append(audios, map[string]any{
+			"index":    a.Index,
+			"lang":     a.Lang,
+			"codec":    a.Codec,
+			"channels": a.Channels,
+			"title":    a.Title,
+			"default":  a.Default,
+		})
+	}
+	subs := make([]map[string]any, 0, len(s.probe.SubtitleTracks))
+	for _, sb := range s.probe.SubtitleTracks {
+		subs = append(subs, map[string]any{
+			"index":  sb.Index,
+			"lang":   sb.Lang,
+			"codec":  sb.Codec,
+			"title":  sb.Title,
+			"forced": sb.Forced,
+			"text":   sb.IsTextSubtitle(),
+		})
+	}
+	return map[string]any{
+		"videoCodec":  s.probe.VideoCodec,
+		"width":       s.probe.Width,
+		"height":      s.probe.Height,
+		"bitDepth":    s.probe.BitDepth,
+		"hdr":         s.probe.HDR,
+		"durationSec": s.probe.DurationSec,
+		"container":   s.probe.Container,
+		"audio":       audios,
+		"subtitles":   subs,
+	}
+}
+
+// ReadyCount returns how many segments are currently fully on disk.
+// Caller can `>= 1` it to check whether seg-0 has landed (and so the
+// player can be told to attach). For cache-HIT sessions this is always
+// `segmentCount` from the moment StartHLSSession returns.
+func (s *HLSSession) ReadyCount() int {
+	s.readyMu.Lock()
+	defer s.readyMu.Unlock()
+	return s.readyMax
+}
+
+// FromCache reports whether this session was served from the HLS cache
+// (no ffmpeg subprocess spawned). Used by ready-watcher logic to short-
+// circuit polling — a cache HIT is ready the moment we return.
+func (s *HLSSession) FromCache() bool { return s.fromCache }
+
+// IsClosed reports whether Close() has been invoked. Exposed (vs the
+// internal isClosed) so external watchers — the ready-webhook
+// goroutine in cmd/daemon.go — can short-circuit polling on a session
+// that was torn down through a different code path (registry replace,
+// idle sweep) without racing on the unexported helper.
+func (s *HLSSession) IsClosed() bool { return s.isClosed() }
+
+// MasterPlaylist returns the rendered master.m3u8 contents.
+func (s *HLSSession) MasterPlaylist() string { return s.manifestRoot }
+
+// VideoPlaylist returns the rendered video media playlist contents.
+func (s *HLSSession) VideoPlaylist() string { return s.manifestVideo }
+
+// DurationSeconds returns the source duration in seconds.
+func (s *HLSSession) DurationSeconds() float64 { return s.durationSec }
+
+// Probe returns the probe metadata used to start the session.
+func (s *HLSSession) Probe() *StreamProbe { return s.probe }
+
+// Touch updates the last-activity timestamp; the registry sweeper compares
+// this against hlsSessionTTL.
+func (s *HLSSession) Touch() {
+	s.mu.Lock()
+	s.lastTouch = time.Now()
+	s.mu.Unlock()
+}
+
+// Close stops ffmpeg and prevents further requests from blocking on segment
+// readiness. Idempotent.
+//
+// Disk lifecycle:
+//   - cache disabled → delete tmpDir (original behavior).
+//   - cache enabled + this session was a HIT → keep dir, just unpin.
+//   - cache enabled + this was a write session → if ffmpeg exited cleanly and
+//     every segment is on disk, persist with .complete and keep dir. Otherwise
+//     drop the dir so a half-written cache doesn't survive into the next play.
+func (s *HLSSession) Close() error {
+	s.mu.Lock()
+	if s.closed {
+		s.mu.Unlock()
+		return nil
+	}
+	s.closed = true
+	cancel := s.cancel
+	tmpDir := s.tmpDir
+	s.mu.Unlock()
+	if cancel != nil {
+		cancel()
+	}
+	// Unblock any handler waiting on readyCh.
+	s.readyMu.Lock()
+	if s.readyCh != nil {
+		close(s.readyCh)
+		s.readyCh = nil
+	}
+	s.exited = true
+	exitErr := s.exitErr
+	s.readyMu.Unlock()
+
+	if s.cache != nil && s.cacheKey != "" {
+		defer s.cache.Unpin(s.cacheKey)
+		if s.writerLockHeld {
+			defer s.cache.ReleaseWriter(s.cacheKey)
+		}
+		if s.fromCache {
+			log.Printf("[hls %s] closed (cache reuse)", shortHLSID(s.cfg.SessionID))
+			return nil
+		}
+		// Wait briefly for the subtitle extractor to finish so a cached
+		// replay never serves half-written .vtt files. Bounded so a stuck
+		// extractor can't block Close indefinitely; on timeout we treat
+		// the cache as incomplete and drop it.
+		subsOK := true
+		if s.subsDone != nil {
+			select {
+			case <-s.subsDone:
+			case <-time.After(15 * time.Second):
+				log.Printf("[hls %s] subtitle extractor timeout — not caching", shortHLSID(s.cfg.SessionID))
+				subsOK = false
+			}
+		}
+		if subsOK && exitErr == nil && s.allSegmentsPresent() {
+			if err := s.cache.MarkComplete(s.cacheKey); err == nil {
+				log.Printf("[hls %s] cache persisted %s", shortHLSID(s.cfg.SessionID), s.cacheKey)
+				return nil
+			} else {
+				log.Printf("[hls %s] cache persist failed: %v", shortHLSID(s.cfg.SessionID), err)
+			}
+		}
+		// Partial / failed → drop so we re-encode next time.
+		if err := s.cache.Invalidate(s.cacheKey); err != nil {
+			log.Printf("[hls %s] cache invalidate failed: %v", shortHLSID(s.cfg.SessionID), err)
+		}
+		log.Printf("[hls %s] closed (cache discarded)", shortHLSID(s.cfg.SessionID))
+		return nil
+	}
+
+	if tmpDir != "" {
+		_ = os.RemoveAll(tmpDir)
+	}
+	log.Printf("[hls %s] closed", shortHLSID(s.cfg.SessionID))
+	return nil
+}
+
+// allSegmentsPresent reports whether every expected segment (and init.mp4) is
+// on disk AND validated by the segment poller. Used to decide whether a
+// finished session is cacheable. We trust readyMax (advanced by pollSegments
+// only after the next segment exists, proving the predecessor is fully closed)
+// over a naive Size>0 stat that could accept truncated mid-write files.
+func (s *HLSSession) allSegmentsPresent() bool {
+	if fi, err := os.Stat(filepath.Join(s.tmpDir, "video", "init.mp4")); err != nil || fi.Size() == 0 {
+		return false
+	}
+	s.readyMu.Lock()
+	readyMax := s.readyMax
+	s.readyMu.Unlock()
+	if readyMax < s.segmentCount-1 {
+		return false
+	}
+	for i := 0; i < s.segmentCount; i++ {
+		path := filepath.Join(s.tmpDir, "video", fmt.Sprintf("seg-%d.m4s", i))
+		fi, err := os.Stat(path)
+		if err != nil || fi.Size() == 0 {
+			return false
+		}
+	}
+	return true
+}
+
+// waitFFmpeg reaps the ffmpeg process and records its exit error for handlers.
+//
+// Auto-restart supervisor: if ffmpeg crashes (non-graceful exit) and the
+// session is still in use, we attempt to restart it from the last known
+// good segment. Bounded to maxRestarts within restartWindow to avoid
+// thrashing on a permanently broken source.
+func (s *HLSSession) waitFFmpeg() {
+	err := s.cmd.Wait()
+	s.readyMu.Lock()
+	s.exitErr = err
+	s.exited = true
+	if s.readyCh != nil {
+		close(s.readyCh)
+		s.readyCh = nil
+	}
+	readyMax := s.readyMax
+	s.readyMu.Unlock()
+
+	if err == nil || s.isClosed() {
+		return
+	}
+	log.Printf("[hls %s] ffmpeg exited: %v", shortHLSID(s.cfg.SessionID), err)
+
+	// Decide whether to attempt an auto-restart. We don't restart when:
+	//   - the session was closed externally (kill on quality change etc.)
+	//   - we've already retried 3 times within the last 60 s (broken file)
+	const maxRestarts = 3
+	const restartWindow = 60 * time.Second
+	s.mu.Lock()
+	if s.closed {
+		s.mu.Unlock()
+		return
+	}
+	// Reset the counter when the previous restart was outside the window;
+	// the IsZero check is unnecessary because zero time is well in the past
+	// and would also satisfy the "outside window" branch.
+	if time.Since(s.lastRestartAt) > restartWindow {
+		s.restartCount = 0
+	}
+	if s.restartCount >= maxRestarts {
+		s.mu.Unlock()
+		log.Printf("[hls %s] giving up after %d auto-restarts", shortHLSID(s.cfg.SessionID), maxRestarts)
+		return
+	}
+	s.restartCount++
+	s.lastRestartAt = time.Now()
+	s.mu.Unlock()
+
+	// 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.
+	target := readyMax
+	if target < 0 {
+		target = 0
+	}
+	log.Printf("[hls %s] auto-restarting from segment %d (attempt %d/%d)",
+		shortHLSID(s.cfg.SessionID), target, s.restartCount, maxRestarts)
+	if rerr := s.restartFromSegment(target); rerr != nil {
+		log.Printf("[hls %s] auto-restart failed: %v", shortHLSID(s.cfg.SessionID), rerr)
+	}
+}
+
+// pollSegments watches the video tmpdir for newly-finished .m4s files and
+// advances readyMax. ffmpeg writes a segment by first creating an empty
+// file, then closing+renaming on completion (atomic-replace), so we use
+// stat size > 0 + presence of the *next* segment as proof the previous one
+// is done. For the last segment, ffmpeg's exit terminates the wait.
+func (s *HLSSession) pollSegments(ctx context.Context) {
+	ticker := time.NewTicker(250 * time.Millisecond)
+	defer ticker.Stop()
+	videoDir := filepath.Join(s.tmpDir, "video")
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+		// Walk segment files and find the highest contiguous index whose
+		// successor exists (which proves the segment is fully closed).
+		s.readyMu.Lock()
+		start := s.readyMax
+		exited := s.exited
+		s.readyMu.Unlock()
+
+		highest := start
+		for i := start; i < s.segmentCount; i++ {
+			cur := filepath.Join(videoDir, fmt.Sprintf("seg-%d.m4s", i))
+			next := filepath.Join(videoDir, fmt.Sprintf("seg-%d.m4s", i+1))
+			ci, err := os.Stat(cur)
+			if err != nil || ci.Size() == 0 {
+				break
+			}
+			// Last segment is "ready" only when ffmpeg has exited (no successor
+			// can ever appear) or when a later segment exists.
+			if i == s.segmentCount-1 {
+				if !exited {
+					break
+				}
+				highest = i + 1
+				break
+			}
+			if _, err := os.Stat(next); err != nil {
+				break
+			}
+			highest = i + 1
+		}
+		if highest > start {
+			s.readyMu.Lock()
+			s.readyMax = highest
+			ch := s.readyCh
+			s.readyCh = make(chan struct{})
+			s.readyMu.Unlock()
+			if ch != nil {
+				close(ch)
+			}
+		}
+		if exited && highest >= s.segmentCount {
+			return
+		}
+	}
+}
+
+// waitForSegment blocks until segment idx has been fully written, ffmpeg
+// has exited, or ctx is cancelled. Returns nil iff the segment file is
+// safe to read at return time.
+func (s *HLSSession) waitForSegment(ctx context.Context, idx int) error {
+	deadline := time.Now().Add(60 * time.Second)
+	for {
+		s.readyMu.Lock()
+		ready := idx < s.readyMax
+		exited := s.exited
+		ch := s.readyCh
+		exitErr := s.exitErr
+		s.readyMu.Unlock()
+		if ready {
+			return nil
+		}
+		if exited {
+			if exitErr != nil {
+				return fmt.Errorf("hls: ffmpeg exited: %w", exitErr)
+			}
+			return errors.New("hls: ffmpeg exited before segment ready")
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-ch:
+			// loop and re-check
+		case <-time.After(time.Until(deadline)):
+			return errors.New("hls: timeout waiting for segment")
+		}
+		if time.Now().After(deadline) {
+			return errors.New("hls: timeout waiting for segment")
+		}
+	}
+}
+
+// isClosed reports whether Close() has been invoked.
+func (s *HLSSession) isClosed() bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.closed
+}
+
+// ---- HTTP handlers ----
+
+// ServeMaster writes master.m3u8 to w.
+func (s *HLSSession) ServeMaster(w http.ResponseWriter, r *http.Request) {
+	s.Touch()
+	w.Header().Set("Content-Type", "application/vnd.apple.mpegurl")
+	w.Header().Set("Cache-Control", "no-cache")
+	_, _ = io.WriteString(w, s.manifestRoot)
+}
+
+// ServeVideoPlaylist writes the video media playlist (index.m3u8) to w.
+func (s *HLSSession) ServeVideoPlaylist(w http.ResponseWriter, r *http.Request) {
+	s.Touch()
+	w.Header().Set("Content-Type", "application/vnd.apple.mpegurl")
+	w.Header().Set("Cache-Control", "no-cache")
+	_, _ = io.WriteString(w, s.manifestVideo)
+}
+
+// ServeInit writes init.mp4 (the fMP4 init segment) to w.
+func (s *HLSSession) ServeInit(w http.ResponseWriter, r *http.Request) {
+	s.Touch()
+	path := filepath.Join(s.tmpDir, "video", "init.mp4")
+	// Init segment is the first thing ffmpeg writes — wait briefly for it.
+	deadline := time.Now().Add(30 * time.Second)
+	for {
+		if fi, err := os.Stat(path); err == nil && fi.Size() > 0 {
+			break
+		}
+		if s.isClosed() || time.Now().After(deadline) {
+			http.Error(w, "init segment unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		time.Sleep(150 * time.Millisecond)
+	}
+	w.Header().Set("Content-Type", "video/mp4")
+	w.Header().Set("Cache-Control", "max-age=3600")
+	http.ServeFile(w, r, path)
+}
+
+// ServeSegment writes the requested video segment, blocking until ffmpeg
+// produces it (capped by waitForSegment timeout).
+//
+// Seek-restart: if the requested segment is far ahead of where the current
+// ffmpeg writer is producing AND it's not already on disk, we kill ffmpeg
+// and restart it from the requested position. Without this, a user dragging
+// the scrubber to minute 30 would block until the encoder reaches minute 30
+// in real time (~25 minutes wait at 1080p software encode).
+func (s *HLSSession) ServeSegment(w http.ResponseWriter, r *http.Request, idx int) {
+	s.Touch()
+	if idx < 0 || idx >= s.segmentCount {
+		http.Error(w, "segment out of range", http.StatusNotFound)
+		return
+	}
+
+	path := filepath.Join(s.tmpDir, "video", fmt.Sprintf("seg-%d.m4s", idx))
+	// Fast path: file already on disk (either current writer reached it, or
+	// a previous session left it there before a seek-restart).
+	if fi, err := os.Stat(path); err == nil && fi.Size() > 0 {
+		w.Header().Set("Content-Type", "video/mp4")
+		w.Header().Set("Cache-Control", "max-age=3600")
+		http.ServeFile(w, r, path)
+		return
+	}
+
+	// Decide if we should restart ffmpeg from the requested segment. Check
+	// segStart vs idx — if the gap is wider than hlsSeekAhead and the file
+	// isn't on disk, the writer would take too long to reach it.
+	s.mu.Lock()
+	segStart := s.ffmpegSegStart
+	s.mu.Unlock()
+	s.readyMu.Lock()
+	readyMax := s.readyMax
+	s.readyMu.Unlock()
+
+	if idx >= readyMax+hlsSeekAhead || idx < segStart {
+		if err := s.restartFromSegment(idx); err != nil {
+			http.Error(w, err.Error(), http.StatusServiceUnavailable)
+			return
+		}
+	}
+
+	if err := s.waitForSegment(r.Context(), idx); err != nil {
+		http.Error(w, err.Error(), http.StatusServiceUnavailable)
+		return
+	}
+	w.Header().Set("Content-Type", "video/mp4")
+	w.Header().Set("Cache-Control", "max-age=3600")
+	http.ServeFile(w, r, path)
+}
+
+// restartFromSegment kills the current ffmpeg, then spawns a new one whose
+// `-ss` offset corresponds to segment `targetIdx`. The caller must NOT hold
+// s.mu when calling — the function takes both s.mu and s.readyMu.
+func (s *HLSSession) restartFromSegment(targetIdx int) error {
+	s.mu.Lock()
+	if s.closed {
+		s.mu.Unlock()
+		return errors.New("hls: session closed")
+	}
+	// `s.exited` lives under s.readyMu (see field comment near declaration);
+	// take that lock briefly so the read-modify-write composite check below
+	// is consistent with `pollSegments` / `waitFFmpeg` writers.
+	s.readyMu.Lock()
+	exited := s.exited
+	s.readyMu.Unlock()
+	if targetIdx == s.ffmpegSegStart && !exited {
+		// Already writing from this point — nothing to do.
+		s.mu.Unlock()
+		return nil
+	}
+	prevCancel := s.cancel
+	prevCmd := s.cmd
+	s.mu.Unlock()
+
+	if prevCancel != nil {
+		prevCancel()
+	}
+	if prevCmd != nil && prevCmd.Process != nil {
+		_ = prevCmd.Process.Kill()
+	}
+	// Wait for old ffmpeg to exit so its file handles release. waitFFmpeg
+	// (the original goroutine) sets s.exited = true; poll until it does.
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		s.readyMu.Lock()
+		exited := s.exited
+		s.readyMu.Unlock()
+		if exited {
+			break
+		}
+		if time.Now().After(deadline) {
+			break // proceed anyway; new ffmpeg will overwrite
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+
+	// 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.
+	startSec := segmentStartSec(targetIdx)
+	args := buildHLSFFmpegArgsAt(s.cfg, s.probe, s.tmpDir, targetIdx, startSec)
+
+	ffCtx, cancel := context.WithCancel(context.Background())
+	cmd := exec.CommandContext(ffCtx, s.cfg.Transcode.FFmpegPath, args...)
+	cmd.Stderr = &hlsStderrCapture{owner: s}
+	if err := cmd.Start(); err != nil {
+		cancel()
+		return fmt.Errorf("hls: restart ffmpeg: %w", err)
+	}
+
+	// Reset session state so the poll + wait machinery picks up the new run.
+	s.mu.Lock()
+	s.cmd = cmd
+	s.cancel = cancel
+	s.ffmpegSegStart = targetIdx
+	s.mu.Unlock()
+
+	s.readyMu.Lock()
+	s.readyMax = targetIdx // new writer's segments start at targetIdx
+	s.exited = false
+	s.exitErr = nil
+	s.readyCh = make(chan struct{})
+	s.readyMu.Unlock()
+
+	go s.waitFFmpeg()
+	go s.pollSegments(ffCtx)
+
+	log.Printf("[hls %s] restarted ffmpeg at segment %d (%.1fs)",
+		shortHLSID(s.cfg.SessionID), targetIdx, startSec)
+	return nil
+}
+
+// ServeSubtitle writes the WebVTT subtitle for the requested track index, if
+// extraction has finished.
+func (s *HLSSession) ServeSubtitle(w http.ResponseWriter, r *http.Request, idx int) {
+	s.Touch()
+	if idx < 0 || idx >= len(s.probe.SubtitleTracks) {
+		http.Error(w, "subtitle track not found", http.StatusNotFound)
+		return
+	}
+	path := filepath.Join(s.tmpDir, "subs", fmt.Sprintf("sub-%d.vtt", idx))
+	deadline := time.Now().Add(15 * time.Second)
+	for {
+		if fi, err := os.Stat(path); err == nil && fi.Size() > 0 {
+			break
+		}
+		if s.isClosed() || time.Now().After(deadline) {
+			http.Error(w, "subtitle not yet extracted", http.StatusServiceUnavailable)
+			return
+		}
+		time.Sleep(200 * time.Millisecond)
+	}
+	w.Header().Set("Content-Type", "text/vtt; charset=utf-8")
+	w.Header().Set("Cache-Control", "max-age=3600")
+	http.ServeFile(w, r, path)
+}
+
+// ---- ffmpeg argument builders ----
+
+// buildHLSFFmpegArgs returns the argv for the initial HLS encode (start at 0).
+func buildHLSFFmpegArgs(cfg HLSSessionConfig, probe *StreamProbe, tmpDir string) []string {
+	return buildHLSFFmpegArgsAt(cfg, probe, tmpDir, 0, 0)
+}
+
+// EncoderProfile names the codec + preset + decoder hint combination the HLS
+// pipeline picks for the given hardware backend + transcode config. Exposed
+// so callers can log the chosen encoder before ffmpeg launches and so both
+// the demuxer-side `-hwaccel` flag and the encoder-side argv stay in sync
+// (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
+	DecodeHwAccel string // ffmpeg `-hwaccel` value (e.g. "cuda", "qsv", "vaapi"), or ""
+}
+
+// ResolveEncoderProfile mirrors the codec + preset selection inside
+// buildHLSFFmpegArgsAt so callers (registry, log lines, diagnostic
+// endpoints) can know what ffmpeg will be told to do without parsing argv.
+//
+// The configured preset is libx264-specific by vocabulary (ultrafast…
+// veryslow). Passing it through to NVENC / QSV would have ffmpeg reject
+// the argv (NVENC uses p1-p7, QSV uses its own subset). So vendor encoders
+// always use their hardcoded vendor preset and ignore configuredPreset.
+// VideoToolbox has no preset knob at all.
+//
+// DecodeHwAccel mirrors the encoder family — `-hwaccel cuda` for NVENC,
+// `-hwaccel qsv` for QSV, `-hwaccel vaapi` for VAAPI. We intentionally
+// do NOT pass `-hwaccel_output_format vaapi`: that pins decoded frames
+// to GPU memory, but our filter chain (scale/format/setparams) runs on
+// CPU and can't consume VAAPI surfaces. Keeping output frames on CPU
+// makes the filter chain work and the VAAPI encoder still benefits from
+// HW-accelerated DECODE on the input side.
+func ResolveEncoderProfile(hw HWAccel, configuredPreset string) EncoderProfile {
+	codec := hw.FFmpegVideoCodec("h264")
+	switch codec {
+	case "libx264":
+		preset := configuredPreset
+		if preset == "" {
+			preset = "superfast"
+		}
+		return EncoderProfile{Codec: codec, Preset: preset, DecodeHwAccel: ""}
+	case "h264_nvenc":
+		return EncoderProfile{Codec: codec, Preset: "p3", DecodeHwAccel: "cuda"}
+	case "h264_qsv":
+		return EncoderProfile{Codec: codec, Preset: "veryfast", DecodeHwAccel: "qsv"}
+	case "h264_vaapi":
+		return EncoderProfile{Codec: codec, Preset: "", DecodeHwAccel: "vaapi"}
+	case "h264_videotoolbox":
+		// No preset knob for VideoToolbox; the speed/quality dial is `-q:v`.
+		// VideoToolbox uses per-encoder flags rather than a demuxer hint.
+		return EncoderProfile{Codec: codec, Preset: "", DecodeHwAccel: ""}
+	}
+	// Unknown / future codecs: software path.
+	return EncoderProfile{Codec: codec, Preset: "", DecodeHwAccel: ""}
+}
+
+// buildHLSFFmpegArgsAt returns the argv for an HLS encode that starts at the
+// given segment index (`-ss <startSec>`) and writes segments numbered from
+// startIdx so they slot into the existing manifest at the correct position.
+// `-output_ts_offset` keeps the segment PTS aligned with manifest timeline.
+func buildHLSFFmpegArgsAt(cfg HLSSessionConfig, probe *StreamProbe, tmpDir string, startIdx int, startSec float64) []string {
+	profile := ResolveEncoderProfile(cfg.Transcode.HWAccel, cfg.Transcode.Preset)
+	args := []string{"-y", "-hide_banner", "-loglevel", "warning"}
+
+	// Demuxer-side HW-decode hint. Sourced from the profile so a future
+	// codec/hint mismatch is impossible — the encoder + decode hint are
+	// computed once and stay coherent. Notably we do NOT add
+	// `-hwaccel_output_format vaapi` on the VAAPI path: that pins decoded
+	// frames to GPU memory but our CPU filter chain (scale, format,
+	// setparams) can't consume VAAPI surfaces. Letting frames flow on CPU
+	// keeps the filter chain working; the encoder still gets HW-accelerated
+	// decode on the input side.
+	if profile.DecodeHwAccel != "" {
+		args = append(args, "-hwaccel", profile.DecodeHwAccel)
+	}
+
+	// Seek before -i for fast keyframe-aligned start. The new ffmpeg writes
+	// segments with PTS shifted via -output_ts_offset so the manifest's
+	// pre-computed segment numbering still matches the timeline.
+	if startSec > 0 {
+		args = append(args, "-ss", strconv.FormatFloat(startSec, 'f', 3, 64))
+	}
+
+	args = append(args, "-i", cfg.SourcePath)
+
+	if startSec > 0 {
+		args = append(args, "-output_ts_offset", strconv.FormatFloat(startSec, 'f', 3, 64))
+	}
+
+	// Map video + selected audio. Always use first video stream.
+	args = append(args, "-map", "0:v:0")
+	audioIdx := cfg.AudioIndex
+	if audioIdx < 0 {
+		audioIdx = 0
+		for i, a := range probe.AudioTracks {
+			if a.Default {
+				audioIdx = i
+				break
+			}
+		}
+	}
+	args = append(args, "-map", fmt.Sprintf("0:a:%d?", audioIdx))
+
+	// Video encode. Codec + preset come from the EncoderProfile resolved at
+	// the top of this function so the demuxer hint, the encoder, and the
+	// per-session log line all stay consistent.
+	//
+	// Defaults are biased for FIRST-START LATENCY over quality — the player
+	// blocks on seg-0 before the first frame paints, and a slow seg-0 is
+	// what users notice ("preparando sesión" stuck). Users who want better
+	// quality can override via `download.transcode.preset` in config.toml.
+	codec := profile.Codec
+	args = append(args, "-c:v", codec)
+	switch codec {
+	case "libx264":
+		// superfast = ~15-20% faster than veryfast at marginal quality loss
+		// for the bitrates we target (5-25 Mbps). For 4K software encodes
+		// this is the difference between ~3 s and ~2.5 s per segment on a
+		// recent x86 CPU. `-threads 0` is libx264's default but explicit
+		// helps when the user has set GOMAXPROCS.
+		args = append(args, "-preset", profile.Preset, "-threads", "0")
+	case "h264_nvenc":
+		// p3 + tune=ll trades ~0.3 dB PSNR for 1.5-2× faster encode vs the
+		// previous p4 + tune=hq pair — first-segment encode drops from
+		// ~1.5 s to ~0.8 s on RTX-class hardware.
+		args = append(args, "-preset", profile.Preset, "-rc", "vbr", "-tune", "ll")
+	case "h264_qsv":
+		// veryfast is the fastest realistic QSV preset; medium was too
+		// conservative for first-start. look_ahead=0 keeps the encoder
+		// truly low-latency (no rate-control look-ahead window).
+		args = append(args, "-preset", profile.Preset, "-look_ahead", "0")
+	case "h264_videotoolbox":
+		// VideoToolbox has no "preset" knob; `-realtime` flips into the
+		// low-latency path used by FaceTime. We let the `-b:v / -maxrate
+		// / -bufsize` block (added later in this function) drive rate
+		// control — adding `-q:v` here would conflict because ffmpeg's
+		// videotoolbox encoder treats `-b:v` as authoritative and
+		// silently ignores `-q:v`, so the constant-quality knob never
+		// took effect anyway.
+		args = append(args, "-realtime", "1")
+	case "h264_vaapi":
+		// h264_vaapi has no preset knob. Bitrate args (set later) drive
+		// rate control. Add `-vaapi_device /dev/dri/renderD128` so the
+		// encoder doesn't fall back to a NULL device on multi-GPU hosts
+		// where the default render node is a non-VAAPI GPU (an Nvidia
+		// dGPU's render node, etc.). The filter chain below switches to
+		// `format=nv12,hwupload` so frames land on the right VAAPI
+		// surface before the encoder; we intentionally avoid scale_vaapi
+		// because mesa 25 + Raphael iGPU emits "Cannot allocate memory"
+		// per session start, polluting logs even though encode succeeds.
+		args = append(args, "-vaapi_device", "/dev/dri/renderD128")
+	}
+	// Derive H.264 level from the actual output height. A fixed "4.0" caps the
+	// encoder at 1080p — anything taller (1440p, 4K source on quality=original)
+	// fails libx264 with "frame MB size > level limit" and emits unplayable
+	// segments. The output height matches qcap.MaxHeight when the source is
+	// downscaled, otherwise probe.Height (already populated by ffprobe).
+	qcap := resolveQualityCap(cfg.Quality)
+	outputHeight := qcap.MaxHeight
+	if outputHeight == 0 {
+		outputHeight = cfg.Transcode.MaxHeight
+	}
+	if outputHeight == 0 || (probe.Height > 0 && probe.Height < outputHeight) {
+		outputHeight = probe.Height
+	}
+	args = append(args, "-profile:v", "main", "-level:v", H264LevelForHeight(outputHeight))
+
+	// Bitrate must match the level libx264 actually picks for outputHeight,
+	// not the qcap target for the user's requested label. If a user asks for
+	// "2160p" on a 1080p source, qcap.VideoBitrate is 25 Mbps but the level
+	// (derived from outputHeight=1080) is 4.0, which rejects bitrates >20 Mbps
+	// with "VBV bitrate (25000) > level limit (20000)". Re-derive the cap
+	// from the effective height so the (level, bitrate) pair stays coherent.
+	effectiveCap := capForHeight(outputHeight)
+	bitrate := effectiveCap.VideoBitrate
+	if bitrate == "" {
+		bitrate = qcap.VideoBitrate
+	}
+	if bitrate == "" {
+		bitrate = cfg.Transcode.VideoBitrate
+	}
+	if bitrate == "" {
+		bitrate = "5M"
+	}
+	args = append(args, "-b:v", bitrate, "-maxrate", bitrate, "-bufsize", bitrate)
+
+	// Force keyframe alignment with segment boundaries.
+	args = append(args, "-force_key_frames", fmt.Sprintf("expr:gte(t,n_forced*%d)", hlsSegmentDuration))
+
+	// Filter chain: optional scale, force 8-bit yuv420p, normalise color metadata.
+	//
+	// Width-rounding pitfall: `scale=-2:H` alone derives width from `H * dar` and
+	// rounds to the nearest multiple of 2, which is correct. But adding
+	// `force_original_aspect_ratio=decrease` makes ffmpeg ignore the `-2` and
+	// emit the exact computed width — which can be odd (e.g. 853×480) and
+	// libx264 then refuses to open. We chain a second `scale=trunc(iw/2)*2:...`
+	// after the cap to guarantee even dimensions before format/setparams.
+	maxH := qcap.MaxHeight
+	if maxH == 0 {
+		maxH = cfg.Transcode.MaxHeight
+	}
+	// VAAPI needs frames as nv12 VAAPI surfaces before the encoder. We do
+	// scale + format conversion on CPU then `hwupload` once at the end —
+	// skips the mesa 25 + Raphael iGPU "Cannot allocate memory" log spam
+	// that scale_vaapi triggers per-session-start while still delivering
+	// the encoder a GPU surface. setparams is dropped because VAAPI
+	// surfaces don't expose VUI fields the way libx264 does; the encoder
+	// records its own color metadata via the source PTS chain.
+	pixFormat := "yuv420p"
+	hwUploadTail := ""
+	colorTail := ",setparams=colorspace=bt709:color_trc=bt709:color_primaries=bt709:range=tv"
+	if codec == "h264_vaapi" {
+		pixFormat = "nv12"
+		hwUploadTail = ",hwupload"
+		colorTail = ""
+	}
+	var filterChain string
+	if maxH > 0 && probe.Height > maxH {
+		filterChain = fmt.Sprintf(
+			"scale=-2:%d:force_original_aspect_ratio=decrease,scale=trunc(iw/2)*2:trunc(ih/2)*2,format=%s%s%s",
+			maxH, pixFormat, colorTail, hwUploadTail,
+		)
+	} else {
+		filterChain = fmt.Sprintf(
+			"scale=trunc(iw/2)*2:trunc(ih/2)*2,format=%s%s%s",
+			pixFormat, colorTail, hwUploadTail,
+		)
+	}
+	args = append(args, "-vf", filterChain)
+
+	// Audio: AAC stereo 48 kHz — broadest browser compatibility.
+	audioBitrate := cfg.Transcode.AudioBitrate
+	if audioBitrate == "" {
+		audioBitrate = "192k"
+	}
+	args = append(args,
+		"-c:a", "aac",
+		"-b:a", audioBitrate,
+		"-ar", "48000",
+		"-ac", "2",
+	)
+
+	// HLS muxer — fmp4 segments with pre-computed segment count.
+	// `-start_number` slots seg-N.m4s where N matches the segment index in
+	// the pre-rendered manifest. Each ffmpeg writes its own ffmpeg.m3u8 but
+	// we never serve it — the rendered VOD manifest already knows everything.
+	videoDir := filepath.Join(tmpDir, "video")
+	manifestName := fmt.Sprintf("ffmpeg-%d.m3u8", startIdx)
+	args = append(args,
+		"-f", "hls",
+		"-hls_time", strconv.Itoa(hlsSegmentDuration),
+		"-hls_playlist_type", "vod",
+		"-hls_segment_type", "fmp4",
+		"-hls_list_size", "0",
+		"-hls_flags", "independent_segments",
+		"-start_number", strconv.Itoa(startIdx),
+		"-hls_fmp4_init_filename", "init.mp4",
+		"-hls_segment_filename", filepath.Join(videoDir, "seg-%d.m4s"),
+		filepath.Join(videoDir, manifestName),
+	)
+	return args
+}
+
+// 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) {
+	subsDir := filepath.Join(s.tmpDir, "subs")
+	for i, sub := range s.probe.SubtitleTracks {
+		if !sub.IsTextSubtitle() {
+			continue
+		}
+		out := filepath.Join(subsDir, fmt.Sprintf("sub-%d.vtt", i))
+		args := []string{
+			"-y", "-hide_banner", "-loglevel", "warning",
+			"-i", s.cfg.SourcePath,
+			"-map", fmt.Sprintf("0:s:%d?", i),
+			"-c:s", "webvtt",
+			out,
+		}
+		// Run sequentially to avoid hammering the disk; subtitle extraction
+		// is fast enough that parallelism isn't worth the complexity.
+		cmd := exec.CommandContext(ctx, s.cfg.Transcode.FFmpegPath, args...)
+		if err := cmd.Run(); err != nil {
+			if ctx.Err() != nil {
+				return
+			}
+			log.Printf("[hls %s] subtitle %d (%s) extract failed: %v",
+				shortHLSID(s.cfg.SessionID), i, sub.Lang, err)
+			continue
+		}
+	}
+}
+
+// ---- Manifest rendering ----
+
+// renderVideoPlaylist builds the VOD media playlist for the video stream.
+// Segment count is derived from the source duration — the player learns the
+// total timeline from the manifest before any segment is fetched.
+//
+// seg-0 is the short init segment (hlsInitSegmentDuration s); seg-1 onward
+// are hlsSegmentDuration s each. The last segment may be shorter than the
+// nominal duration when (duration - init) doesn't divide evenly.
+func renderVideoPlaylist(durationSec float64, segCount int) string {
+	var b strings.Builder
+	b.WriteString("#EXTM3U\n")
+	b.WriteString("#EXT-X-VERSION:7\n")
+	b.WriteString("#EXT-X-PLAYLIST-TYPE:VOD\n")
+	b.WriteString(fmt.Sprintf("#EXT-X-TARGETDURATION:%d\n", hlsSegmentDuration+1))
+	b.WriteString("#EXT-X-MEDIA-SEQUENCE:0\n")
+	b.WriteString(`#EXT-X-MAP:URI="init.mp4"` + "\n")
+	remaining := durationSec
+	for i := 0; i < segCount; i++ {
+		segDur := float64(segmentDurationFor(i))
+		if remaining < segDur {
+			segDur = remaining
+		}
+		b.WriteString(fmt.Sprintf("#EXTINF:%.3f,\n", segDur))
+		b.WriteString(fmt.Sprintf("seg-%d.m4s\n", i))
+		remaining -= segDur
+	}
+	b.WriteString("#EXT-X-ENDLIST\n")
+	return b.String()
+}
+
+// renderMasterPlaylist builds the top-level master playlist with the single
+// video variant + every text subtitle as an EXT-X-MEDIA group. Audio is muxed
+// into the video segments for the MVP — separate audio renditions can come
+// later (they require a second ffmpeg pipeline producing audio-only segments).
+func renderMasterPlaylist(probe *StreamProbe, qualityLabel string) string {
+	var b strings.Builder
+	b.WriteString("#EXTM3U\n")
+	b.WriteString("#EXT-X-VERSION:7\n")
+
+	// Subtitle renditions. We never set DEFAULT=YES or AUTOSELECT=YES on any
+	// rendition: anime files routinely ship a forced "signs only" English
+	// track with cues only every few minutes, and stacking that track plus
+	// the user's locale auto-select produced the "subs broken" report. The
+	// HLS spec also caps DEFAULT to one per GROUP-ID — "none" trivially
+	// satisfies it. Names disambiguate when several tracks share the same
+	// language ("ES", "ES 2", forced suffix).
+	hasSubs := false
+	langCounts := make(map[string]int)
+	for i, s := range probe.SubtitleTracks {
+		if !s.IsTextSubtitle() {
+			continue
+		}
+		hasSubs = true
+		lang := s.Lang
+		if lang == "" {
+			lang = "und"
+		}
+		base := s.Title
+		if base == "" {
+			base = strings.ToUpper(lang)
+		}
+		key := strings.ToLower(base)
+		langCounts[key]++
+		name := base
+		if langCounts[key] > 1 {
+			name = fmt.Sprintf("%s %d", base, langCounts[key])
+		}
+		if s.Forced {
+			name = name + " (forced)"
+		}
+		b.WriteString(fmt.Sprintf(
+			`#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs",NAME=%q,LANGUAGE=%q,DEFAULT=NO,AUTOSELECT=NO,FORCED=%s,URI="subs/sub-%d.m3u8"`+"\n",
+			name, lang, ynBool(s.Forced), i,
+		))
+	}
+
+	// Video variant. Bandwidth + resolution are best-effort estimates from probe.
+	bw := bitrateForQuality(qualityLabel)
+	w, h := scaledDimensions(probe.Width, probe.Height, qualityHeight(qualityLabel))
+	codecs := `avc1.4D4028,mp4a.40.2`
+	streamInf := fmt.Sprintf("#EXT-X-STREAM-INF:BANDWIDTH=%d,RESOLUTION=%dx%d,CODECS=%q", bw, w, h, codecs)
+	if hasSubs {
+		streamInf += `,SUBTITLES="subs"`
+	}
+	b.WriteString(streamInf + "\n")
+	b.WriteString("video/index.m3u8\n")
+	return b.String()
+}
+
+func ynBool(b bool) string {
+	if b {
+		return "YES"
+	}
+	return "NO"
+}
+
+// bitrateForQuality returns a synthetic bandwidth attribute for the master
+// playlist's STREAM-INF — only used by ABR logic, which we don't run yet.
+func bitrateForQuality(q string) int {
+	switch q {
+	case "2160p":
+		return 25_000_000
+	case "1080p":
+		return 6_000_000
+	case "720p":
+		return 3_500_000
+	case "480p":
+		return 1_500_000
+	}
+	return 6_000_000
+}
+
+func qualityHeight(q string) int {
+	switch q {
+	case "2160p":
+		return 2160
+	case "1080p":
+		return 1080
+	case "720p":
+		return 720
+	case "480p":
+		return 480
+	}
+	return 0
+}
+
+// scaledDimensions returns (width, height) after applying a height cap that
+// preserves the source aspect ratio. capH=0 returns the original dims.
+func scaledDimensions(srcW, srcH, capH int) (int, int) {
+	if srcW <= 0 || srcH <= 0 {
+		return 1920, 1080
+	}
+	if capH == 0 || srcH <= capH {
+		return srcW, srcH
+	}
+	w := srcW * capH / srcH
+	if w%2 != 0 {
+		w++
+	}
+	return w, capH
+}
+
+// ---- Logger plumbing ----
+
+// hlsStderrCapture forwards ffmpeg stderr lines to the daemon log prefixed by
+// the session ID, so failures are visible without spelunking tmpdirs.
+//
+// The internal buffer accumulates partial bytes between writes (a single line
+// can span multiple Write calls). Capped at maxStderrBuf so a misbehaving
+// ffmpeg that emits megabytes without newlines can't grow daemon memory
+// unbounded; on overflow we discard the partial line and keep going.
+type hlsStderrCapture struct {
+	owner *HLSSession
+	buf   strings.Builder
+}
+
+const maxStderrBuf = 64 * 1024
+
+func (c *hlsStderrCapture) Write(p []byte) (int, error) {
+	// If the incoming chunk alone exceeds the cap (very long unterminated
+	// line), drop the buffered prefix AND truncate p so a single multi-MB
+	// write can't grow memory.
+	if len(p) > maxStderrBuf {
+		c.buf.Reset()
+		p = p[len(p)-maxStderrBuf:]
+	} else if c.buf.Len()+len(p) > maxStderrBuf {
+		// Drop the unterminated partial line; we'll resync on the next \n.
+		c.buf.Reset()
+	}
+	c.buf.Write(p)
+	for {
+		line, rest, ok := strings.Cut(c.buf.String(), "\n")
+		if !ok {
+			break
+		}
+		c.buf.Reset()
+		c.buf.WriteString(rest)
+		if line = strings.TrimSpace(line); line != "" {
+			log.Printf("[hls %s] ffmpeg: %s", shortHLSID(c.owner.cfg.SessionID), line)
+		}
+	}
+	return len(p), nil
+}
diff --git a/internal/engine/hls_cache.go b/internal/engine/hls_cache.go
new file mode 100644
index 0000000..f1bf918
--- /dev/null
+++ b/internal/engine/hls_cache.go
@@ -0,0 +1,410 @@
+package engine
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"sort"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// HLSCache persists transcoded HLS segments per (source, quality, audio) so a
+// second play of the same file at the same quality skips ffmpeg entirely.
+//
+// Layout on disk:
+//
+//	{root}/{key}/init.mp4
+//	{root}/{key}/seg-0.m4s
+//	{root}/{key}/seg-N.m4s
+//	{root}/{key}/.complete
+//
+// Atomicity: the .complete marker is written only when ffmpeg exits 0 AND all
+// segments are on disk. A dir without .complete is treated as a partial run —
+// next session can reuse the segments already present, ffmpeg fills the gaps.
+//
+// Concurrency: Pin/Unpin increments a ref counter per key so the LRU sweeper
+// never evicts a directory that an active session is reading from.
+type HLSCache struct {
+	root     string
+	maxBytes int64
+
+	mu      sync.Mutex
+	refs    map[string]int
+	writers map[string]bool // exclusive ffmpeg writer per key; nil entries are absent
+
+	// Counters surfaced via Stats() — useful for /api/internal/agent/cache-stats
+	// and for the sweeper's daily log line. atomic so RecordHit/RecordMiss are
+	// safe to call from any goroutine without taking the cache mutex.
+	hits   atomic.Uint64
+	misses atomic.Uint64
+}
+
+const (
+	hlsCacheCompleteMarker = ".complete"
+	// hlsCacheMinBudgetGB clamps absurd / zero / negative SizeGB values to
+	// a sane floor. NOT a guarantee that any single encode fits — a long
+	// 4K HEVC re-encode can exceed it. Operators should set size_gb based
+	// on their actual workload.
+	hlsCacheMinBudgetGB = 1
+	// hlsCacheStartupOrphanAge: directories without .complete older than
+	// this are removed on cache startup. Long enough that a daemon crash
+	// during an in-progress encode (which legitimately leaves a partial
+	// dir) doesn't get nuked too aggressively if the daemon restarts fast.
+	hlsCacheStartupOrphanAge = 10 * time.Minute
+)
+
+// NewHLSCache creates the cache rooted at the given dir with a size budget in
+// gigabytes. A budget < hlsCacheMinBudgetGB is clamped up so a single play
+// doesn't get instantly evicted mid-stream.
+func NewHLSCache(root string, sizeGB int) (*HLSCache, error) {
+	if root == "" {
+		return nil, errors.New("hls_cache: empty root")
+	}
+	if sizeGB < hlsCacheMinBudgetGB {
+		sizeGB = hlsCacheMinBudgetGB
+	}
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		return nil, fmt.Errorf("hls_cache: mkdir root: %w", err)
+	}
+	c := &HLSCache{
+		root:     root,
+		maxBytes: int64(sizeGB) * 1024 * 1024 * 1024,
+		refs:     make(map[string]int),
+		writers:  make(map[string]bool),
+	}
+	// Reap dirs left over from a crashed encode. A dir without .complete that
+	// hasn't been touched recently was almost certainly orphaned by an
+	// ungraceful daemon exit — keeping it just feeds the unbounded growth
+	// pattern the hourly LRU is too slow to contain.
+	if removed, err := c.cleanStartupOrphans(); err != nil {
+		log.Printf("[hls_cache] startup orphan cleanup: %v", err)
+	} else if removed > 0 {
+		log.Printf("[hls_cache] startup: removed %d orphan dir(s) without .complete", removed)
+	}
+	return c, nil
+}
+
+// cleanStartupOrphans removes cache subdirectories that lack a .complete
+// marker AND haven't been modified within hlsCacheStartupOrphanAge. Called
+// once at construction. Safe at startup because no sessions are active yet,
+// so Pin can't race with us.
+func (c *HLSCache) cleanStartupOrphans() (int, error) {
+	entries, err := os.ReadDir(c.root)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return 0, nil
+		}
+		return 0, err
+	}
+	cutoff := time.Now().Add(-hlsCacheStartupOrphanAge)
+	removed := 0
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		dir := filepath.Join(c.root, e.Name())
+		if _, err := os.Stat(filepath.Join(dir, hlsCacheCompleteMarker)); err == nil {
+			continue // sealed, keep
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		if info.ModTime().After(cutoff) {
+			continue // too recent — might be a daemon that just restarted mid-encode
+		}
+		if err := os.RemoveAll(dir); err == nil {
+			removed++
+		}
+	}
+	return removed, nil
+}
+
+// TryAcquireWriter attempts to claim exclusive ffmpeg-write access to a key.
+// Returns true on success — the caller is then responsible for ReleaseWriter
+// when ffmpeg exits / fails. Returns false if another session is already
+// writing this key, in which case the caller must fall back to a private
+// per-session tmpdir (no caching for that session).
+func (c *HLSCache) TryAcquireWriter(key string) bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.writers[key] {
+		return false
+	}
+	c.writers[key] = true
+	return true
+}
+
+// ReleaseWriter releases the writer claim acquired via TryAcquireWriter.
+// Idempotent on unknown keys.
+func (c *HLSCache) ReleaseWriter(key string) {
+	c.mu.Lock()
+	delete(c.writers, key)
+	c.mu.Unlock()
+}
+
+// KeyFor derives a stable cache key for (source, quality, audioIndex). Using
+// the absolute source path means renaming a file invalidates the cache, which
+// is correct — segment content is tied to the encoded source.
+func (c *HLSCache) KeyFor(sourcePath, quality string, audioIndex int) string {
+	abs, err := filepath.Abs(sourcePath)
+	if err != nil {
+		abs = sourcePath
+	}
+	h := sha256.Sum256([]byte(fmt.Sprintf("%s|%s|%d", abs, quality, audioIndex)))
+	return hex.EncodeToString(h[:8]) // 16 hex chars — collision-safe enough for per-host cache
+}
+
+// DirFor returns the on-disk directory for a cache key. Caller is responsible
+// for creating it.
+func (c *HLSCache) DirFor(key string) string {
+	return filepath.Join(c.root, key)
+}
+
+// HasComplete returns true when the .complete marker is present, meaning the
+// directory holds a full set of segments from a successful encode.
+func (c *HLSCache) HasComplete(key string) bool {
+	if _, err := os.Stat(filepath.Join(c.DirFor(key), hlsCacheCompleteMarker)); err == nil {
+		return true
+	}
+	return false
+}
+
+// MarkComplete writes the .complete marker. Call only after verifying ffmpeg
+// exited cleanly AND every expected segment is on disk. The dir must already
+// exist — StartHLSSession created it on the writer path.
+func (c *HLSCache) MarkComplete(key string) error {
+	return os.WriteFile(filepath.Join(c.DirFor(key), hlsCacheCompleteMarker), nil, 0o644)
+}
+
+// RecordHit increments the hit counter; called by StartHLSSession on a
+// cache-HIT path.
+func (c *HLSCache) RecordHit() { c.hits.Add(1) }
+
+// RecordMiss increments the miss counter; called when a session has to
+// encode from scratch (or fails an integrity check on a stale HIT).
+func (c *HLSCache) RecordMiss() { c.misses.Add(1) }
+
+// CacheStats is a snapshot of the cache's runtime counters + on-disk size.
+// The size fields are best-effort (computed via dirSize) so callers paying
+// for them should cache the result, not poll in a hot loop.
+type CacheStats struct {
+	Hits       uint64
+	Misses     uint64
+	EntryCount int
+	TotalBytes int64
+}
+
+// Stats returns a snapshot of the cache counters and size. Walks the root
+// to total disk usage — O(N segments). Call at most every few minutes.
+func (c *HLSCache) Stats() CacheStats {
+	s := CacheStats{
+		Hits:   c.hits.Load(),
+		Misses: c.misses.Load(),
+	}
+	entries, err := os.ReadDir(c.root)
+	if err != nil {
+		return s
+	}
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		size, err := dirSize(filepath.Join(c.root, e.Name()))
+		if err != nil {
+			continue
+		}
+		s.EntryCount++
+		s.TotalBytes += size
+	}
+	return s
+}
+
+// hitRatePercent returns the current hit/(hit+miss) percentage rounded to
+// the nearest int; 0 when no calls have been recorded.
+func (c *HLSCache) hitRatePercent() int {
+	h := c.hits.Load()
+	m := c.misses.Load()
+	total := h + m
+	if total == 0 {
+		return 0
+	}
+	return int((h*100 + total/2) / total)
+}
+
+// VerifyComplete checks that the .complete marker is present AND the
+// essential files (init.mp4 + last segment) exist with non-zero size. A
+// dir that passes HasComplete but fails VerifyComplete is treated as
+// corrupted — typically external `rm` or a partial-disk-failure scenario.
+// When it returns false, callers should Invalidate and re-encode.
+func (c *HLSCache) VerifyComplete(key string, segmentCount int) bool {
+	if !c.HasComplete(key) {
+		return false
+	}
+	dir := c.DirFor(key)
+	if fi, err := os.Stat(filepath.Join(dir, "video", "init.mp4")); err != nil || fi.Size() == 0 {
+		return false
+	}
+	if segmentCount > 0 {
+		lastSeg := filepath.Join(dir, "video", fmt.Sprintf("seg-%d.m4s", segmentCount-1))
+		if fi, err := os.Stat(lastSeg); err != nil || fi.Size() == 0 {
+			return false
+		}
+	}
+	return true
+}
+
+// Pin increments the ref counter for a key. The sweeper checks this before
+// evicting, so a pinned dir is safe even if its mtime is old.
+func (c *HLSCache) Pin(key string) {
+	c.mu.Lock()
+	c.refs[key]++
+	c.mu.Unlock()
+}
+
+// Unpin decrements; safe to call on unknown keys (no-op).
+func (c *HLSCache) Unpin(key string) {
+	c.mu.Lock()
+	if c.refs[key] > 0 {
+		c.refs[key]--
+		if c.refs[key] == 0 {
+			delete(c.refs, key)
+		}
+	}
+	c.mu.Unlock()
+}
+
+func (c *HLSCache) isPinned(key string) bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.refs[key] > 0
+}
+
+// Touch updates the directory mtime so LRU picks fresher entries as recently
+// used. Called when a session starts reading from a cached dir.
+func (c *HLSCache) Touch(key string) error {
+	dir := c.DirFor(key)
+	now := time.Now()
+	return os.Chtimes(dir, now, now)
+}
+
+// Sweep enforces the size budget by deleting the least-recently-used cache
+// dirs (ignoring pinned ones) until the total size is at or below maxBytes.
+// Returns the number of bytes freed.
+func (c *HLSCache) Sweep() (int64, error) {
+	entries, err := os.ReadDir(c.root)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return 0, nil
+		}
+		return 0, fmt.Errorf("hls_cache: read root: %w", err)
+	}
+
+	type item struct {
+		key   string
+		path  string
+		size  int64
+		mtime time.Time
+	}
+	items := make([]item, 0, len(entries))
+	var total, pinned int64
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		key := e.Name()
+		path := filepath.Join(c.root, key)
+		size, err := dirSize(path)
+		if err != nil {
+			continue
+		}
+		items = append(items, item{key: key, path: path, size: size, mtime: info.ModTime()})
+		total += size
+		if c.isPinned(key) {
+			pinned += size
+		}
+	}
+
+	if total <= c.maxBytes {
+		return 0, nil
+	}
+	if pinned >= c.maxBytes {
+		// Every pinned byte already exceeds the budget — even evicting
+		// every unpinned dir won't bring us under. Warn loudly so the
+		// operator knows to bump size_gb (or kill the long-running session).
+		log.Printf("[hls_cache] warn: pinned bytes (%.1f MB) exceed budget (%.1f MB) — cannot enforce limit until sessions release",
+			float64(pinned)/(1024*1024), float64(c.maxBytes)/(1024*1024))
+		return 0, nil
+	}
+
+	// Oldest first.
+	sort.Slice(items, func(i, j int) bool {
+		return items[i].mtime.Before(items[j].mtime)
+	})
+
+	var freed int64
+	for _, it := range items {
+		if total-freed <= c.maxBytes {
+			break
+		}
+		if c.isPinned(it.key) {
+			continue
+		}
+		if err := os.RemoveAll(it.path); err != nil {
+			log.Printf("[hls_cache] evict %s failed: %v", it.key, err)
+			continue
+		}
+		log.Printf("[hls_cache] evicted %s (%.1f MB, age %s)",
+			it.key, float64(it.size)/(1024*1024), time.Since(it.mtime).Round(time.Second))
+		freed += it.size
+	}
+	return freed, nil
+}
+
+// StartSweeper kicks off the LRU sweeper goroutine. Cancels on ctx done.
+// In addition to enforcing the size budget, logs a daily summary of hit-rate
+// + disk usage so operators can see the cache's value at a glance.
+func (c *HLSCache) StartSweeper(ctx context.Context, interval time.Duration) {
+	if interval <= 0 {
+		interval = time.Hour
+	}
+	go func() {
+		t := time.NewTicker(interval)
+		defer t.Stop()
+		statsTick := time.NewTicker(24 * time.Hour)
+		defer statsTick.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-t.C:
+				if _, err := c.Sweep(); err != nil {
+					log.Printf("[hls_cache] sweep error: %v", err)
+				}
+			case <-statsTick.C:
+				s := c.Stats()
+				log.Printf("[hls_cache] day-stats: hits=%d misses=%d ratio=%d%% entries=%d size=%.1fMB",
+					s.Hits, s.Misses, c.hitRatePercent(), s.EntryCount,
+					float64(s.TotalBytes)/(1024*1024))
+			}
+		}
+	}()
+}
+
+// Invalidate removes a cache entry — used when ffmpeg fails to encode the
+// source so we don't reuse a half-written dir next time.
+func (c *HLSCache) Invalidate(key string) error {
+	return os.RemoveAll(c.DirFor(key))
+}
+
diff --git a/internal/engine/hls_cache_smoke_test.go b/internal/engine/hls_cache_smoke_test.go
new file mode 100644
index 0000000..a086cb2
--- /dev/null
+++ b/internal/engine/hls_cache_smoke_test.go
@@ -0,0 +1,134 @@
+//go:build smoke
+
+package engine
+
+import (
+	"context"
+	"os/exec"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// TestHLSCacheSmoke exercises the end-to-end cache flow against real ffmpeg:
+//   - First session encodes a 5s test pattern; expect MISS, ffmpeg runs,
+//     .complete written, MarkComplete logs.
+//   - Second session for identical (source, quality, audio); expect HIT,
+//     no ffmpeg, instant Start.
+//
+// Build tag `smoke` keeps it out of the default `go test ./...` run because
+// it depends on a working ffmpeg/ffprobe and takes ~5–10 s.
+//
+//	go test -tags=smoke -run TestHLSCacheSmoke -v ./internal/engine/
+func TestHLSCacheSmoke(t *testing.T) {
+	ffmpeg, err := exec.LookPath("ffmpeg")
+	if err != nil {
+		t.Skipf("ffmpeg not on PATH: %v", err)
+	}
+	ffprobe, err := exec.LookPath("ffprobe")
+	if err != nil {
+		t.Skipf("ffprobe not on PATH: %v", err)
+	}
+
+	tmp := t.TempDir()
+	source := filepath.Join(tmp, "source.mp4")
+	t.Logf("generating 5 s test pattern → %s", source)
+	if out, err := exec.Command(ffmpeg,
+		"-y", "-loglevel", "error",
+		"-f", "lavfi", "-i", "testsrc=duration=5:size=640x480:rate=30",
+		"-f", "lavfi", "-i", "sine=frequency=1000:duration=5",
+		"-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p",
+		"-c:a", "aac",
+		source,
+	).CombinedOutput(); err != nil {
+		t.Fatalf("ffmpeg generate: %v\n%s", err, out)
+	}
+
+	cacheRoot := filepath.Join(tmp, "cache")
+	cache, err := NewHLSCache(cacheRoot, 1)
+	if err != nil {
+		t.Fatalf("NewHLSCache: %v", err)
+	}
+
+	cfg := HLSSessionConfig{
+		SessionID:  "smoke1",
+		SourcePath: source,
+		FileName:   "source.mp4",
+		Quality:    "720p",
+		AudioIndex: 0,
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  ffmpeg,
+			FFprobePath: ffprobe,
+			Preset:      "ultrafast",
+		},
+		Cache: cache,
+	}
+
+	// First run — expect MISS, ffmpeg runs.
+	t.Log("session 1: expect MISS")
+	t0 := time.Now()
+	s1, err := StartHLSSession(context.Background(), cfg)
+	if err != nil {
+		t.Fatalf("StartHLSSession #1: %v", err)
+	}
+	if s1.fromCache {
+		t.Fatal("session 1 reported cache HIT on a fresh cache")
+	}
+
+	// Wait for all segments to land. 5 s source @ 4 s segments → 2 segments.
+	deadline := time.Now().Add(60 * time.Second)
+	for {
+		s1.readyMu.Lock()
+		ready := s1.readyMax
+		exited := s1.exited
+		s1.readyMu.Unlock()
+		if ready >= s1.segmentCount-1 && exited {
+			break
+		}
+		if time.Now().After(deadline) {
+			_ = s1.Close()
+			t.Fatalf("session 1 didn't finish in 60 s (readyMax=%d/%d, exited=%v)",
+				ready, s1.segmentCount-1, exited)
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	if err := s1.Close(); err != nil {
+		t.Fatalf("Close #1: %v", err)
+	}
+	encodeDur := time.Since(t0)
+	t.Logf("session 1: MISS completed in %s", encodeDur.Round(time.Millisecond))
+
+	key := cache.KeyFor(source, "720p", 0)
+	if !cache.HasComplete(key) {
+		t.Fatalf("cache.HasComplete(%s) is false after successful encode", key)
+	}
+
+	// Second run — expect HIT, no ffmpeg.
+	t.Log("session 2: expect HIT")
+	cfg.SessionID = "smoke2"
+	t1 := time.Now()
+	s2, err := StartHLSSession(context.Background(), cfg)
+	if err != nil {
+		t.Fatalf("StartHLSSession #2: %v", err)
+	}
+	if !s2.fromCache {
+		t.Fatal("session 2 should have reported cache HIT")
+	}
+	if s2.cmd != nil {
+		t.Fatal("session 2 should not have spawned ffmpeg (s.cmd != nil)")
+	}
+	hitDur := time.Since(t1)
+	t.Logf("session 2: HIT in %s (%.1f×  faster than MISS)",
+		hitDur.Round(time.Millisecond), float64(encodeDur)/float64(hitDur))
+	if hitDur > 500*time.Millisecond {
+		t.Errorf("HIT path too slow: %s — expected <500 ms", hitDur)
+	}
+	if err := s2.Close(); err != nil {
+		t.Fatalf("Close #2: %v", err)
+	}
+
+	// After the HIT session closes, the cache dir + .complete must still exist.
+	if !cache.HasComplete(key) {
+		t.Fatal(".complete disappeared after HIT session closed")
+	}
+}
diff --git a/internal/engine/hls_cache_test.go b/internal/engine/hls_cache_test.go
new file mode 100644
index 0000000..cb70ec1
--- /dev/null
+++ b/internal/engine/hls_cache_test.go
@@ -0,0 +1,361 @@
+package engine
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+)
+
+func newTestCache(t *testing.T, sizeGB int) *HLSCache {
+	t.Helper()
+	root := t.TempDir()
+	c, err := NewHLSCache(root, sizeGB)
+	if err != nil {
+		t.Fatalf("NewHLSCache: %v", err)
+	}
+	return c
+}
+
+func TestKeyForStable(t *testing.T) {
+	c := newTestCache(t, 1)
+	k1 := c.KeyFor("/a/b/movie.mkv", "1080p", 0)
+	k2 := c.KeyFor("/a/b/movie.mkv", "1080p", 0)
+	if k1 != k2 {
+		t.Fatalf("expected stable keys, got %q vs %q", k1, k2)
+	}
+	if c.KeyFor("/a/b/movie.mkv", "720p", 0) == k1 {
+		t.Fatal("quality should change key")
+	}
+	if c.KeyFor("/a/b/movie.mkv", "1080p", 1) == k1 {
+		t.Fatal("audio index should change key")
+	}
+	if c.KeyFor("/x/y/other.mkv", "1080p", 0) == k1 {
+		t.Fatal("path should change key")
+	}
+}
+
+func TestMarkCompleteAndHas(t *testing.T) {
+	c := newTestCache(t, 1)
+	key := "abc123"
+	if c.HasComplete(key) {
+		t.Fatal("fresh cache should not report complete")
+	}
+	// Production callers create the dir during StartHLSSession; MarkComplete
+	// trusts that invariant and fails if the dir was wiped meanwhile.
+	if err := os.MkdirAll(c.DirFor(key), 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := c.MarkComplete(key); err != nil {
+		t.Fatalf("MarkComplete: %v", err)
+	}
+	if !c.HasComplete(key) {
+		t.Fatal("after MarkComplete, HasComplete must be true")
+	}
+}
+
+func TestMarkCompleteFailsWithoutDir(t *testing.T) {
+	c := newTestCache(t, 1)
+	if err := c.MarkComplete("never-created"); err == nil {
+		t.Fatal("MarkComplete should error when dir doesn't exist")
+	}
+}
+
+func TestPinPreventsEviction(t *testing.T) {
+	c := newTestCache(t, 1) // 1 GB budget, but min clamp keeps it usable
+	c.maxBytes = 1024       // squeeze budget for the test
+
+	// Write two entries past the budget.
+	for i, key := range []string{"old", "new"} {
+		dir := c.DirFor(key)
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatalf("mkdir %s: %v", dir, err)
+		}
+		path := filepath.Join(dir, "seg.bin")
+		if err := os.WriteFile(path, make([]byte, 800), 0o644); err != nil {
+			t.Fatalf("write %s: %v", path, err)
+		}
+		now := time.Now().Add(time.Duration(i) * time.Hour) // "old" mtime < "new"
+		_ = os.Chtimes(dir, now, now)
+	}
+
+	c.Pin("old") // protect the older one
+	freed, err := c.Sweep()
+	if err != nil {
+		t.Fatalf("Sweep: %v", err)
+	}
+	if freed == 0 {
+		t.Fatal("expected some eviction")
+	}
+	if _, err := os.Stat(c.DirFor("old")); err != nil {
+		t.Fatal("pinned 'old' was evicted")
+	}
+	if _, err := os.Stat(c.DirFor("new")); err == nil {
+		t.Fatal("'new' should have been evicted to make room")
+	}
+}
+
+func TestSweepNoOpUnderBudget(t *testing.T) {
+	c := newTestCache(t, 1)
+	dir := c.DirFor("small")
+	_ = os.MkdirAll(dir, 0o755)
+	_ = os.WriteFile(filepath.Join(dir, "x"), []byte("tiny"), 0o644)
+	freed, err := c.Sweep()
+	if err != nil {
+		t.Fatalf("Sweep: %v", err)
+	}
+	if freed != 0 {
+		t.Fatalf("expected 0 freed under budget, got %d", freed)
+	}
+	if _, err := os.Stat(dir); err != nil {
+		t.Fatal("under-budget entry was wrongly evicted")
+	}
+}
+
+func TestSweepEmptyRoot(t *testing.T) {
+	c := newTestCache(t, 1)
+	freed, err := c.Sweep()
+	if err != nil {
+		t.Fatalf("Sweep empty: %v", err)
+	}
+	if freed != 0 {
+		t.Fatalf("freed=%d, want 0", freed)
+	}
+}
+
+func TestInvalidateRemovesDir(t *testing.T) {
+	c := newTestCache(t, 1)
+	key := "drop"
+	dir := c.DirFor(key)
+	_ = os.MkdirAll(dir, 0o755)
+	_ = os.WriteFile(filepath.Join(dir, "x"), []byte("y"), 0o644)
+	if err := c.Invalidate(key); err != nil {
+		t.Fatalf("Invalidate: %v", err)
+	}
+	if _, err := os.Stat(dir); err == nil {
+		t.Fatal("dir still present after Invalidate")
+	}
+}
+
+func TestTouchUpdatesMtime(t *testing.T) {
+	c := newTestCache(t, 1)
+	key := "touch"
+	dir := c.DirFor(key)
+	_ = os.MkdirAll(dir, 0o755)
+	old := time.Now().Add(-2 * time.Hour)
+	_ = os.Chtimes(dir, old, old)
+
+	if err := c.Touch(key); err != nil {
+		t.Fatalf("Touch: %v", err)
+	}
+	info, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	if !info.ModTime().After(old.Add(time.Minute)) {
+		t.Fatalf("mtime not refreshed: %v", info.ModTime())
+	}
+}
+
+func TestPinUnpinSymmetry(t *testing.T) {
+	c := newTestCache(t, 1)
+	c.Pin("k")
+	c.Pin("k")
+	if !c.isPinned("k") {
+		t.Fatal("Pin twice should leave pinned")
+	}
+	c.Unpin("k")
+	if !c.isPinned("k") {
+		t.Fatal("Unpin once should keep pinned (refs=1)")
+	}
+	c.Unpin("k")
+	if c.isPinned("k") {
+		t.Fatal("Unpin twice should drop pin")
+	}
+	c.Unpin("k") // safe no-op
+}
+
+func TestConcurrentPinUnpin(t *testing.T) {
+	c := newTestCache(t, 1)
+	var wg sync.WaitGroup
+	for i := 0; i < 100; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			c.Pin("race")
+			time.Sleep(time.Microsecond)
+			c.Unpin("race")
+		}()
+	}
+	wg.Wait()
+	if c.isPinned("race") {
+		t.Fatal("refs leaked")
+	}
+}
+
+func TestSweeperLoopExits(t *testing.T) {
+	c := newTestCache(t, 1)
+	ctx, cancel := context.WithCancel(context.Background())
+	c.StartSweeper(ctx, 10*time.Millisecond)
+	time.Sleep(30 * time.Millisecond)
+	cancel()
+	// If StartSweeper doesn't exit on cancel the test would leak a goroutine;
+	// the leak detector in the test runner will surface it.
+	time.Sleep(20 * time.Millisecond)
+}
+
+func TestMinBudgetClamp(t *testing.T) {
+	root := t.TempDir()
+	c, err := NewHLSCache(root, 0) // below floor
+	if err != nil {
+		t.Fatalf("NewHLSCache: %v", err)
+	}
+	if c.maxBytes != int64(hlsCacheMinBudgetGB)*1024*1024*1024 {
+		t.Fatalf("budget not clamped to min: got %d", c.maxBytes)
+	}
+}
+
+func TestTryAcquireWriterExclusive(t *testing.T) {
+	c := newTestCache(t, 1)
+	if !c.TryAcquireWriter("k") {
+		t.Fatal("first acquire should succeed")
+	}
+	if c.TryAcquireWriter("k") {
+		t.Fatal("second acquire for same key must fail")
+	}
+	if !c.TryAcquireWriter("other") {
+		t.Fatal("different key should not conflict")
+	}
+	c.ReleaseWriter("k")
+	if !c.TryAcquireWriter("k") {
+		t.Fatal("acquire after release should succeed")
+	}
+	c.ReleaseWriter("k")
+	c.ReleaseWriter("k") // idempotent
+}
+
+func TestStartupOrphanCleanup(t *testing.T) {
+	root := t.TempDir()
+
+	// Pre-seed: one sealed dir + one orphan old enough + one orphan fresh.
+	sealed := filepath.Join(root, "sealed")
+	_ = os.MkdirAll(sealed, 0o755)
+	_ = os.WriteFile(filepath.Join(sealed, hlsCacheCompleteMarker), nil, 0o644)
+
+	staleOrphan := filepath.Join(root, "stale_orphan")
+	_ = os.MkdirAll(staleOrphan, 0o755)
+	old := time.Now().Add(-2 * hlsCacheStartupOrphanAge)
+	_ = os.Chtimes(staleOrphan, old, old)
+
+	freshOrphan := filepath.Join(root, "fresh_orphan")
+	_ = os.MkdirAll(freshOrphan, 0o755)
+
+	if _, err := NewHLSCache(root, 1); err != nil {
+		t.Fatalf("NewHLSCache: %v", err)
+	}
+
+	if _, err := os.Stat(sealed); err != nil {
+		t.Fatal("sealed dir was wrongly removed")
+	}
+	if _, err := os.Stat(staleOrphan); err == nil {
+		t.Fatal("stale orphan should have been removed at startup")
+	}
+	if _, err := os.Stat(freshOrphan); err != nil {
+		t.Fatal("fresh orphan should be kept (might be a mid-restart encode)")
+	}
+}
+
+func TestHitMissCounters(t *testing.T) {
+	c := newTestCache(t, 1)
+	if s := c.Stats(); s.Hits != 0 || s.Misses != 0 {
+		t.Fatalf("fresh cache stats not zero: %+v", s)
+	}
+	c.RecordHit()
+	c.RecordHit()
+	c.RecordMiss()
+	s := c.Stats()
+	if s.Hits != 2 || s.Misses != 1 {
+		t.Fatalf("counters wrong: %+v", s)
+	}
+	// 2/3 = 67%
+	if got := c.hitRatePercent(); got != 67 {
+		t.Fatalf("hitRatePercent=%d, want 67", got)
+	}
+}
+
+func TestStatsEntryCount(t *testing.T) {
+	c := newTestCache(t, 1)
+	for _, k := range []string{"a", "b", "c"} {
+		dir := c.DirFor(k)
+		_ = os.MkdirAll(dir, 0o755)
+		_ = os.WriteFile(filepath.Join(dir, "x"), []byte("hello"), 0o644)
+	}
+	s := c.Stats()
+	if s.EntryCount != 3 {
+		t.Fatalf("EntryCount=%d, want 3", s.EntryCount)
+	}
+	if s.TotalBytes != 15 {
+		t.Fatalf("TotalBytes=%d, want 15", s.TotalBytes)
+	}
+}
+
+func TestVerifyCompleteRejectsMissingFiles(t *testing.T) {
+	c := newTestCache(t, 1)
+	key := "v"
+	dir := c.DirFor(key)
+	_ = os.MkdirAll(filepath.Join(dir, "video"), 0o755)
+
+	// No .complete yet → reject.
+	if c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should reject without .complete")
+	}
+
+	// Mark complete but no files → reject.
+	if err := c.MarkComplete(key); err != nil {
+		t.Fatalf("MarkComplete: %v", err)
+	}
+	if c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should reject when init.mp4 missing")
+	}
+
+	// Write init.mp4, last seg missing → reject.
+	_ = os.WriteFile(filepath.Join(dir, "video", "init.mp4"), []byte("..."), 0o644)
+	if c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should reject when last segment missing")
+	}
+
+	// Write last seg → pass.
+	_ = os.WriteFile(filepath.Join(dir, "video", "seg-1.m4s"), []byte("..."), 0o644)
+	if !c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should pass with all files present")
+	}
+
+	// Zero-size last seg → reject.
+	_ = os.WriteFile(filepath.Join(dir, "video", "seg-1.m4s"), nil, 0o644)
+	if c.VerifyComplete(key, 2) {
+		t.Fatal("VerifyComplete should reject zero-size last segment")
+	}
+}
+
+func TestSweepRespectsPinnedExceedsBudget(t *testing.T) {
+	c := newTestCache(t, 1)
+	c.maxBytes = 256 // squeeze
+
+	pinned := c.DirFor("pinned")
+	_ = os.MkdirAll(pinned, 0o755)
+	_ = os.WriteFile(filepath.Join(pinned, "x"), make([]byte, 1024), 0o644)
+	c.Pin("pinned")
+
+	freed, err := c.Sweep()
+	if err != nil {
+		t.Fatalf("Sweep: %v", err)
+	}
+	if freed != 0 {
+		t.Fatalf("nothing should have been freed: got %d", freed)
+	}
+	if _, err := os.Stat(pinned); err != nil {
+		t.Fatal("pinned dir wrongly removed despite over-budget pin")
+	}
+}
diff --git a/internal/engine/hls_test.go b/internal/engine/hls_test.go
new file mode 100644
index 0000000..7d4cde3
--- /dev/null
+++ b/internal/engine/hls_test.go
@@ -0,0 +1,294 @@
+package engine
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestYnBool(t *testing.T) {
+	if got := ynBool(true); got != "YES" {
+		t.Errorf("ynBool(true) = %q, want YES", got)
+	}
+	if got := ynBool(false); got != "NO" {
+		t.Errorf("ynBool(false) = %q, want NO", got)
+	}
+}
+
+func TestBitrateForQuality(t *testing.T) {
+	cases := map[string]int{
+		"2160p":   25_000_000,
+		"1080p":   6_000_000,
+		"720p":    3_500_000,
+		"480p":    1_500_000,
+		"unknown": 6_000_000,
+		"":        6_000_000,
+	}
+	for q, want := range cases {
+		if got := bitrateForQuality(q); got != want {
+			t.Errorf("bitrateForQuality(%q) = %d, want %d", q, got, want)
+		}
+	}
+}
+
+func TestQualityHeight(t *testing.T) {
+	cases := map[string]int{
+		"2160p":   2160,
+		"1080p":   1080,
+		"720p":    720,
+		"480p":    480,
+		"":        0,
+		"unknown": 0,
+	}
+	for q, want := range cases {
+		if got := qualityHeight(q); got != want {
+			t.Errorf("qualityHeight(%q) = %d, want %d", q, got, want)
+		}
+	}
+}
+
+func TestScaledDimensions(t *testing.T) {
+	tests := []struct {
+		name             string
+		srcW, srcH, capH int
+		wantW, wantH     int
+	}{
+		{"no_cap_returns_source", 1920, 1080, 0, 1920, 1080},
+		{"under_cap_returns_source", 1280, 720, 1080, 1280, 720},
+		{"4k_capped_to_1080", 3840, 2160, 1080, 1920, 1080},
+		{"even_width_stays_even", 1003, 750, 720, 962, 720},
+		{"odd_width_bumps_up", 1001, 700, 500, 716, 500},
+		{"invalid_returns_default", 0, 0, 0, 1920, 1080},
+		{"negative_returns_default", -10, 100, 0, 1920, 1080},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotW, gotH := scaledDimensions(tt.srcW, tt.srcH, tt.capH)
+			if gotW != tt.wantW || gotH != tt.wantH {
+				t.Errorf("scaledDimensions(%d,%d,%d) = (%d,%d), want (%d,%d)",
+					tt.srcW, tt.srcH, tt.capH, gotW, gotH, tt.wantW, tt.wantH)
+			}
+		})
+	}
+}
+
+func TestShortHLSID(t *testing.T) {
+	if got := shortHLSID("abcdef1234567890"); got != "abcdef12" {
+		t.Errorf("got %q, want abcdef12", got)
+	}
+	if got := shortHLSID("short"); got != "short" {
+		t.Errorf("got %q, want short", got)
+	}
+	if got := shortHLSID(""); got != "" {
+		t.Errorf("got %q, want empty", got)
+	}
+}
+
+func TestHlsTmpDirRoot(t *testing.T) {
+	root := hlsTmpDirRoot()
+	if root == "" {
+		t.Fatal("hlsTmpDirRoot returned empty")
+	}
+	if !strings.Contains(root, "hls-sessions") && !strings.Contains(root, "unarr-hls-sessions") {
+		t.Errorf("expected path to contain hls-sessions, got %q", root)
+	}
+}
+
+func TestRenderVideoPlaylist(t *testing.T) {
+	out := renderVideoPlaylist(10.0, 3)
+	required := []string{
+		"#EXTM3U",
+		"#EXT-X-VERSION:7",
+		"#EXT-X-PLAYLIST-TYPE:VOD",
+		`#EXT-X-MAP:URI="init.mp4"`,
+		"seg-0.m4s",
+		"seg-1.m4s",
+		"seg-2.m4s",
+		"#EXT-X-ENDLIST",
+	}
+	for _, want := range required {
+		if !strings.Contains(out, want) {
+			t.Errorf("playlist missing %q\n%s", want, out)
+		}
+	}
+}
+
+func TestRenderVideoPlaylistShortFinalSegment(t *testing.T) {
+	// 9.5s total, 2s segments → 5 segs of 2/2/2/2/1.5
+	segCount := segmentCountForDuration(9.5)
+	out := renderVideoPlaylist(9.5, segCount)
+	if !strings.Contains(out, "#EXTINF:1.500,") {
+		t.Errorf("expected final segment 1.5s in playlist (segCount=%d), got:\n%s", segCount, out)
+	}
+}
+
+func TestRenderMasterPlaylist(t *testing.T) {
+	probe := &StreamProbe{
+		Width:  1920,
+		Height: 1080,
+		SubtitleTracks: []ProbeSubtitleTrack{
+			{Index: 0, Lang: "es", Codec: "subrip", Title: "Spanish"},
+			{Index: 1, Lang: "en", Codec: "subrip", Title: "English", Forced: true},
+			{Index: 2, Lang: "ja", Codec: "hdmv_pgs_subtitle"}, // bitmap, skipped
+		},
+	}
+	out := renderMasterPlaylist(probe, "1080p")
+
+	if !strings.HasPrefix(out, "#EXTM3U") {
+		t.Errorf("must start with #EXTM3U, got:\n%s", out)
+	}
+	if !strings.Contains(out, "BANDWIDTH=6000000") {
+		t.Errorf("expected 1080p bandwidth, got:\n%s", out)
+	}
+	if !strings.Contains(out, "RESOLUTION=1920x1080") {
+		t.Errorf("expected 1920x1080 resolution, got:\n%s", out)
+	}
+	if !strings.Contains(out, `SUBTITLES="subs"`) {
+		t.Errorf("expected subtitles group attached, got:\n%s", out)
+	}
+	if !strings.Contains(out, `LANGUAGE="es"`) || !strings.Contains(out, `LANGUAGE="en"`) {
+		t.Errorf("expected text subs included, got:\n%s", out)
+	}
+	if strings.Contains(out, "hdmv_pgs") || strings.Contains(out, `LANGUAGE="ja"`) {
+		t.Errorf("bitmap subs should be excluded, got:\n%s", out)
+	}
+	if !strings.Contains(out, "(forced)") {
+		t.Errorf("expected forced suffix on English track, got:\n%s", out)
+	}
+}
+
+func TestRenderMasterPlaylistNoSubs(t *testing.T) {
+	probe := &StreamProbe{Width: 1280, Height: 720}
+	out := renderMasterPlaylist(probe, "720p")
+	if strings.Contains(out, "SUBTITLES=") {
+		t.Errorf("no subs should produce no SUBTITLES attr, got:\n%s", out)
+	}
+	if !strings.Contains(out, "BANDWIDTH=3500000") {
+		t.Errorf("expected 720p bandwidth, got:\n%s", out)
+	}
+}
+
+func TestHLSSessionRegistry(t *testing.T) {
+	r := NewHLSSessionRegistry()
+	if r.Get("missing") != nil {
+		t.Error("Get on empty registry should return nil")
+	}
+
+	s1 := &HLSSession{cfg: HLSSessionConfig{SessionID: "a"}, lastTouch: time.Now()}
+	r.Register(s1)
+	if got := r.Get("a"); got != s1 {
+		t.Errorf("Get(a) = %v, want %v", got, s1)
+	}
+
+	// Registering a different session evicts (and Closes) the previous one.
+	s2 := &HLSSession{cfg: HLSSessionConfig{SessionID: "b"}, lastTouch: time.Now()}
+	r.Register(s2)
+	if r.Get("a") != nil {
+		t.Error("registering different session should evict prior entries")
+	}
+	if r.Get("b") != s2 {
+		t.Error("Get(b) should return s2")
+	}
+
+	r.Remove("b")
+	if r.Get("b") != nil {
+		t.Error("Remove should drop the session")
+	}
+}
+
+func TestHLSSessionAccessors(t *testing.T) {
+	probe := &StreamProbe{VideoCodec: "h264", Width: 1280, Height: 720}
+	s := &HLSSession{
+		cfg:           HLSSessionConfig{SessionID: "abcdef1234"},
+		probe:         probe,
+		manifestRoot:  "MASTER",
+		manifestVideo: "VIDEO",
+		durationSec:   42.5,
+		lastTouch:     time.Now().Add(-1 * time.Hour),
+	}
+	if s.MasterPlaylist() != "MASTER" {
+		t.Errorf("MasterPlaylist mismatch")
+	}
+	if s.VideoPlaylist() != "VIDEO" {
+		t.Errorf("VideoPlaylist mismatch")
+	}
+	if s.DurationSeconds() != 42.5 {
+		t.Errorf("DurationSeconds mismatch")
+	}
+	if s.Probe() != probe {
+		t.Errorf("Probe mismatch")
+	}
+
+	old := s.lastTouch
+	s.Touch()
+	if !s.lastTouch.After(old) {
+		t.Errorf("Touch did not advance lastTouch")
+	}
+
+	info := s.ProbeInfo()
+	if info["videoCodec"] != "h264" || info["width"] != 1280 {
+		t.Errorf("ProbeInfo missing fields: %v", info)
+	}
+}
+
+func TestHLSSessionProbeInfoNil(t *testing.T) {
+	s := &HLSSession{}
+	info := s.ProbeInfo()
+	if len(info) != 0 {
+		t.Errorf("nil probe should produce empty info, got %v", info)
+	}
+}
+
+func TestSweepIdle(t *testing.T) {
+	r := NewHLSSessionRegistry()
+	idleSession := &HLSSession{
+		cfg:       HLSSessionConfig{SessionID: "old"},
+		lastTouch: time.Now().Add(-2 * hlsSessionTTL),
+	}
+	r.Register(idleSession)
+	if got := r.SweepIdle(); got != 1 {
+		t.Errorf("SweepIdle = %d, want 1", got)
+	}
+	if r.Get("old") != nil {
+		t.Errorf("idle session should have been removed")
+	}
+}
+
+func TestCleanupHLSOrphanDirsMissingRoot(t *testing.T) {
+	// Directory does not exist — should not error.
+	t.Setenv("XDG_CACHE_HOME", filepath.Join(t.TempDir(), "nonexistent"))
+	if err := CleanupHLSOrphanDirs(); err != nil {
+		t.Errorf("CleanupHLSOrphanDirs on missing root = %v, want nil", err)
+	}
+}
+
+func TestValidSessionID(t *testing.T) {
+	good := []string{
+		"abc",
+		"7b8c4f12-9d3e-4a1b-9c2f-aabbccddeeff",
+		"ABC_123-xyz",
+		strings.Repeat("a", 128),
+	}
+	bad := []string{
+		"",
+		"../etc/passwd",
+		"foo/bar",
+		"foo\\bar",
+		"foo.bar",
+		"with spaces",
+		"with\nnewline",
+		strings.Repeat("a", 129),
+		"héctor", // non-ascii
+	}
+	for _, id := range good {
+		if !validSessionID.MatchString(id) {
+			t.Errorf("validSessionID rejected good id %q", id)
+		}
+	}
+	for _, id := range bad {
+		if validSessionID.MatchString(id) {
+			t.Errorf("validSessionID accepted bad id %q", id)
+		}
+	}
+}
diff --git a/internal/engine/hwaccel.go b/internal/engine/hwaccel.go
new file mode 100644
index 0000000..d7d1bd4
--- /dev/null
+++ b/internal/engine/hwaccel.go
@@ -0,0 +1,273 @@
+package engine
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"runtime"
+	"strings"
+	"sync"
+)
+
+// HWAccel identifies a hardware-accelerated ffmpeg encoder family.
+type HWAccel string
+
+const (
+	HWAccelNone         HWAccel = "none"
+	HWAccelNVENC        HWAccel = "nvenc"        // NVIDIA — h264_nvenc / hevc_nvenc
+	HWAccelQSV          HWAccel = "qsv"          // Intel Quick Sync — h264_qsv / hevc_qsv
+	HWAccelVAAPI        HWAccel = "vaapi"        // Linux open-source — h264_vaapi / hevc_vaapi
+	HWAccelVideoToolbox HWAccel = "videotoolbox" // macOS — h264_videotoolbox
+)
+
+var (
+	hwOnce  sync.Once
+	hwCache HWAccel
+)
+
+// DetectHWAccel returns the most capable hardware encoder available on this
+// host, or HWAccelNone if software-only. Cached after first call — adding /
+// removing a GPU at runtime is rare and the cost of probing isn't free.
+func DetectHWAccel(ctx context.Context, ffmpegPath string) HWAccel {
+	hwOnce.Do(func() {
+		hwCache = detectHWAccelFresh(ctx, ffmpegPath)
+	})
+	return hwCache
+}
+
+// ResetHWAccelCache clears the singleton — only used in tests.
+func ResetHWAccelCache() {
+	hwOnce = sync.Once{}
+	hwCache = ""
+}
+
+func detectHWAccelFresh(ctx context.Context, ffmpegPath string) HWAccel {
+	if ffmpegPath == "" {
+		return HWAccelNone
+	}
+	encoders := listFFmpegEncoders(ctx, ffmpegPath)
+	if encoders == "" {
+		return HWAccelNone
+	}
+
+	// macOS — VideoToolbox is always available on Apple Silicon + recent Intel.
+	if runtime.GOOS == "darwin" && strings.Contains(encoders, "h264_videotoolbox") {
+		return HWAccelVideoToolbox
+	}
+
+	// NVIDIA — encoder presence + a CUDA-capable device. We rely on the
+	// existence of the device file rather than running nvidia-smi to keep
+	// startup quick on hosts without nvidia tooling.
+	if strings.Contains(encoders, "h264_nvenc") &&
+		(fileExists("/dev/nvidia0") || hasNvidiaDriver()) {
+		return HWAccelNVENC
+	}
+
+	// Intel Quick Sync — needs /dev/dri (also used by VA-API). Distinguish by
+	// checking whether the QSV-specific encoder is built in.
+	if strings.Contains(encoders, "h264_qsv") && fileExists("/dev/dri/renderD128") {
+		return HWAccelQSV
+	}
+
+	// Linux generic VA-API — works on Intel + AMD with mesa drivers.
+	if strings.Contains(encoders, "h264_vaapi") && fileExists("/dev/dri/renderD128") {
+		return HWAccelVAAPI
+	}
+
+	return HWAccelNone
+}
+
+func listFFmpegEncoders(ctx context.Context, ffmpegPath string) string {
+	cmd := exec.CommandContext(ctx, ffmpegPath, "-hide_banner", "-encoders")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		return ""
+	}
+	return string(out)
+}
+
+// HWAccelDiagnostic bundles what we know about the host's ffmpeg + HW encode
+// capabilities so the daemon can log a single coherent line at startup and the
+// web side can surface "this agent is software-only" without re-running probes.
+type HWAccelDiagnostic struct {
+	Pick          HWAccel  // backend selected by DetectHWAccel
+	FFmpegPath    string   // resolved ffmpeg binary
+	FFmpegVersion string   // first line of `ffmpeg -version` (e.g. "ffmpeg version 6.1.1")
+	Encoders      []string // HW + libsvtav1/libvpx9-class encoders found in -encoders output
+	Devices       []string // device files / drivers detected at probe time
+}
+
+// DetectHWAccelDiagnostic returns the full diagnostic picture for the host's
+// transcode pipeline. Unlike DetectHWAccel, this is NOT cached — callers pay
+// for an ffmpeg subprocess on each call (one `-encoders`, one `-version`).
+// Daemon startup is the natural caller; per-session lookups should keep using
+// DetectHWAccel (cached) and only re-probe diagnostics if the user runs an
+// explicit doctor command.
+func DetectHWAccelDiagnostic(ctx context.Context, ffmpegPath string) HWAccelDiagnostic {
+	d := HWAccelDiagnostic{Pick: HWAccelNone, FFmpegPath: ffmpegPath}
+	if ffmpegPath == "" {
+		return d
+	}
+	d.FFmpegVersion = ffmpegVersionLine(ctx, ffmpegPath)
+	encoders := listFFmpegEncoders(ctx, ffmpegPath)
+	for _, name := range hwEncoderNames {
+		if strings.Contains(encoders, name) {
+			d.Encoders = append(d.Encoders, name)
+		}
+	}
+	// Device-file checks mirror the picks below so the log line tells the
+	// reader why a present encoder might still have been rejected (e.g. NVENC
+	// compiled in but /dev/nvidia0 missing inside a container).
+	if fileExists("/dev/nvidia0") {
+		d.Devices = append(d.Devices, "/dev/nvidia0")
+	}
+	if fileExists("/dev/dri/renderD128") {
+		d.Devices = append(d.Devices, "/dev/dri/renderD128")
+	}
+	if hasNvidiaDriver() {
+		d.Devices = append(d.Devices, "nvidia-smi")
+	}
+	d.Pick = DetectHWAccel(ctx, ffmpegPath)
+	return d
+}
+
+// LogLine returns a one-line human-readable summary of the diagnostic,
+// suitable for daemon startup output. Format:
+//
+//	"[transcode] ffmpeg 6.1.1 at /usr/bin/ffmpeg, HW=nvenc (h264_nvenc), devices=/dev/nvidia0,nvidia-smi"
+//	"[transcode] ffmpeg 6.1.1 at /home/linuxbrew/.../ffmpeg, HW=none (software libx264) — no HW encoders compiled in"
+func (d HWAccelDiagnostic) LogLine() string {
+	var b strings.Builder
+	b.WriteString("[transcode] ")
+	if d.FFmpegVersion != "" {
+		b.WriteString(d.FFmpegVersion)
+	} else {
+		b.WriteString("ffmpeg")
+	}
+	if d.FFmpegPath != "" {
+		b.WriteString(" at ")
+		b.WriteString(d.FFmpegPath)
+	}
+	b.WriteString(", HW=")
+	b.WriteString(string(d.Pick))
+	if d.Pick == HWAccelNone {
+		if len(d.Encoders) == 0 {
+			b.WriteString(" (software libx264) — no HW encoders compiled in")
+		} else {
+			b.WriteString(" (software libx264) — encoders found but no matching device: ")
+			b.WriteString(strings.Join(d.Encoders, ","))
+		}
+	} else {
+		b.WriteString(" (")
+		b.WriteString(d.Pick.FFmpegVideoCodec("h264"))
+		b.WriteString(")")
+		if len(d.Devices) > 0 {
+			b.WriteString(", devices=")
+			b.WriteString(strings.Join(d.Devices, ","))
+		}
+	}
+	return b.String()
+}
+
+// hwEncoderNames lists the HW-accelerated encoders we care about for the
+// startup log. Kept in lookup order so the output reads predictably across
+// hosts.
+var hwEncoderNames = []string{
+	"h264_nvenc", "hevc_nvenc",
+	"h264_qsv", "hevc_qsv",
+	"h264_vaapi", "hevc_vaapi",
+	"h264_videotoolbox", "hevc_videotoolbox",
+}
+
+// ffmpegVersionLine extracts the "ffmpeg version X.Y.Z" prefix from
+// `ffmpeg -version`. Bounded to avoid hanging the daemon on a misbehaving
+// binary.
+func ffmpegVersionLine(ctx context.Context, ffmpegPath string) string {
+	cmd := exec.CommandContext(ctx, ffmpegPath, "-hide_banner", "-version")
+	out, err := cmd.CombinedOutput()
+	if err != nil || len(out) == 0 {
+		return ""
+	}
+	line, _, _ := strings.Cut(string(out), "\n")
+	// "ffmpeg version 6.1.1-some-build-suffix Copyright..." → keep up to first
+	// space after "version 6.x" to avoid spamming build flags into the log.
+	if idx := strings.Index(line, "Copyright"); idx > 0 {
+		line = strings.TrimSpace(line[:idx])
+	}
+	return strings.TrimSpace(line)
+}
+
+func fileExists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+func hasNvidiaDriver() bool {
+	// Cheap proxy — if the user has nvidia-smi on PATH they presumably also
+	// have a working driver / runtime libraries.
+	_, err := exec.LookPath("nvidia-smi")
+	return err == nil
+}
+
+// FFmpegVideoCodec returns the encoder name to pass to `-c:v` for the
+// requested HW accel + target (h264 or hevc).
+func (h HWAccel) FFmpegVideoCodec(target string) string {
+	target = strings.ToLower(target)
+	switch h {
+	case HWAccelNVENC:
+		if target == "hevc" {
+			return "hevc_nvenc"
+		}
+		return "h264_nvenc"
+	case HWAccelQSV:
+		if target == "hevc" {
+			return "hevc_qsv"
+		}
+		return "h264_qsv"
+	case HWAccelVAAPI:
+		if target == "hevc" {
+			return "hevc_vaapi"
+		}
+		return "h264_vaapi"
+	case HWAccelVideoToolbox:
+		if target == "hevc" {
+			return "hevc_videotoolbox"
+		}
+		return "h264_videotoolbox"
+	default:
+		// Software fallback. libx264 ships with every ffmpeg build.
+		return "libx264"
+	}
+}
+
+// H264LevelForHeight returns the lowest H.264 profile level capable of
+// encoding a stream at the given output pixel height. Each tier carries
+// enough macroblock headroom to handle ANAMORPHIC content (up to ~2.4:1
+// cinemascope) at 30 fps — a fixed 16:9 assumption used to silently bust
+// the level on a 720p movie shot in 2.4:1 (1728×720 = 4860 MBs > 3.1's
+// 3600 limit; libx264 logs "frame MB size > level limit" and emits a
+// corrupt stream).
+func H264LevelForHeight(height int) string {
+	switch {
+	case height <= 0:
+		// Unknown source — pick a level that covers up to 4K so we never
+		// re-introduce the silent-failure mode that motivated this helper.
+		return "5.1"
+	case height <= 480:
+		return "3.1"
+	case height <= 720:
+		// 4.0 instead of 3.1: covers 720p anamorphic (e.g. 1728×720) +
+		// MB rate up to 245k/s (3.1 caps at 108k/s — broken at 24 fps).
+		return "4.0"
+	case height <= 1080:
+		// 4.1 instead of 4.0: covers 1080p anamorphic + 30 fps (~245k MBs/s).
+		return "4.1"
+	case height <= 1440:
+		return "5.0"
+	case height <= 2160:
+		return "5.1"
+	default:
+		// 4K @ 60 fps and 8K all fall under 6.x.
+		return "6.0"
+	}
+}
diff --git a/internal/engine/hwaccel_test.go b/internal/engine/hwaccel_test.go
new file mode 100644
index 0000000..cf3bec2
--- /dev/null
+++ b/internal/engine/hwaccel_test.go
@@ -0,0 +1,156 @@
+package engine
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestHWAccelFFmpegVideoCodec(t *testing.T) {
+	cases := []struct {
+		hw     HWAccel
+		target string
+		want   string
+	}{
+		{HWAccelNone, "h264", "libx264"},
+		{HWAccelNone, "hevc", "libx264"},
+		{HWAccelNVENC, "h264", "h264_nvenc"},
+		{HWAccelNVENC, "hevc", "hevc_nvenc"},
+		{HWAccelQSV, "h264", "h264_qsv"},
+		{HWAccelQSV, "hevc", "hevc_qsv"},
+		{HWAccelVAAPI, "h264", "h264_vaapi"},
+		{HWAccelVAAPI, "hevc", "hevc_vaapi"},
+		{HWAccelVideoToolbox, "h264", "h264_videotoolbox"},
+		{HWAccelVideoToolbox, "hevc", "hevc_videotoolbox"},
+	}
+	for _, tc := range cases {
+		if got := tc.hw.FFmpegVideoCodec(tc.target); got != tc.want {
+			t.Errorf("%s.FFmpegVideoCodec(%q) = %q want %q", tc.hw, tc.target, got, tc.want)
+		}
+	}
+}
+
+func TestDetectHWAccelEmptyPathReturnsNone(t *testing.T) {
+	ResetHWAccelCache()
+	if got := detectHWAccelFresh(t.Context(), ""); got != HWAccelNone {
+		t.Errorf("got %s, want %s", got, HWAccelNone)
+	}
+}
+
+func TestResolveEncoderProfileDefaults(t *testing.T) {
+	cases := []struct {
+		hw         HWAccel
+		configured string
+		wantCodec  string
+		wantPreset string
+		wantHint   string
+	}{
+		// Empty configured preset → pick latency-biased default per backend.
+		// DecodeHwAccel matches the encoder family for HW encoders; libx264 +
+		// VideoToolbox have no demuxer hint.
+		{HWAccelNone, "", "libx264", "superfast", ""},
+		{HWAccelNVENC, "", "h264_nvenc", "p3", "cuda"},
+		{HWAccelQSV, "", "h264_qsv", "veryfast", "qsv"},
+		// VAAPI: decoder hint set, no preset, no `-hwaccel_output_format vaapi`
+		// (so the CPU filter chain can consume the decoded frames).
+		{HWAccelVAAPI, "", "h264_vaapi", "", "vaapi"},
+		// VideoToolbox has no preset knob — Preset should be "" regardless of input.
+		// VideoToolbox uses per-encoder flags, not a demuxer `-hwaccel` hint.
+		{HWAccelVideoToolbox, "p4", "h264_videotoolbox", "", ""},
+		{HWAccelVideoToolbox, "", "h264_videotoolbox", "", ""},
+	}
+	for _, tc := range cases {
+		got := ResolveEncoderProfile(tc.hw, tc.configured)
+		if got.Codec != tc.wantCodec || got.Preset != tc.wantPreset || got.DecodeHwAccel != tc.wantHint {
+			t.Errorf("ResolveEncoderProfile(%s, %q) = {codec=%s preset=%s hint=%s}, want {codec=%s preset=%s hint=%s}",
+				tc.hw, tc.configured,
+				got.Codec, got.Preset, got.DecodeHwAccel,
+				tc.wantCodec, tc.wantPreset, tc.wantHint)
+		}
+	}
+}
+
+func TestResolveEncoderProfileHonoursConfiguredPreset(t *testing.T) {
+	// Only libx264 honours the configured preset — the libx264 vocabulary
+	// (ultrafast…veryslow) doesn't apply to vendor encoders. NVENC has its
+	// own p1-p7 scale; QSV uses a different subset; VideoToolbox has no
+	// preset knob. Passing a libx264 preset to them would have ffmpeg reject
+	// the argv, so ResolveEncoderProfile always falls back to the hardcoded
+	// vendor preset for non-libx264 codecs.
+	cases := []struct {
+		hw         HWAccel
+		configured string
+		wantPreset string
+	}{
+		{HWAccelNone, "ultrafast", "ultrafast"},  // libx264 honours
+		{HWAccelNone, "medium", "medium"},        // libx264 honours
+		{HWAccelNVENC, "p1", "p3"},               // NVENC ignores, sticks to p3
+		{HWAccelNVENC, "veryfast", "p3"},         // NVENC ignores libx264 vocab
+		{HWAccelQSV, "veryslow", "veryfast"},     // QSV ignores, sticks to veryfast
+		{HWAccelVideoToolbox, "veryfast", ""},    // VideoToolbox has no preset
+	}
+	for _, tc := range cases {
+		got := ResolveEncoderProfile(tc.hw, tc.configured)
+		if got.Preset != tc.wantPreset {
+			t.Errorf("ResolveEncoderProfile(%s, %q).Preset = %q, want %q",
+				tc.hw, tc.configured, got.Preset, tc.wantPreset)
+		}
+	}
+}
+
+func TestHWAccelDiagnosticLogLineNone(t *testing.T) {
+	d := HWAccelDiagnostic{
+		Pick:          HWAccelNone,
+		FFmpegPath:    "/usr/local/bin/ffmpeg",
+		FFmpegVersion: "ffmpeg version 6.1.1",
+		Encoders:      nil,
+		Devices:       nil,
+	}
+	line := d.LogLine()
+	wantSubstrings := []string{
+		"ffmpeg version 6.1.1",
+		"/usr/local/bin/ffmpeg",
+		"HW=none",
+		"software libx264",
+		"no HW encoders compiled in",
+	}
+	for _, want := range wantSubstrings {
+		if !strings.Contains(line, want) {
+			t.Errorf("expected substring %q in log line; got %q", want, line)
+		}
+	}
+}
+
+func TestHWAccelDiagnosticLogLineNVENCWithDevices(t *testing.T) {
+	d := HWAccelDiagnostic{
+		Pick:          HWAccelNVENC,
+		FFmpegPath:    "/usr/bin/ffmpeg",
+		FFmpegVersion: "ffmpeg version 6.0",
+		Encoders:      []string{"h264_nvenc", "hevc_nvenc", "h264_qsv"},
+		Devices:       []string{"/dev/nvidia0", "nvidia-smi"},
+	}
+	line := d.LogLine()
+	for _, want := range []string{"HW=nvenc", "h264_nvenc", "/dev/nvidia0", "nvidia-smi"} {
+		if !strings.Contains(line, want) {
+			t.Errorf("expected substring %q in log line; got %q", want, line)
+		}
+	}
+}
+
+func TestHWAccelDiagnosticLogLineSoftwareButEncodersFound(t *testing.T) {
+	// Edge case: ffmpeg compiled WITH nvenc but no /dev/nvidia0 (container w/o GPU).
+	// LogLine should flag the encoders so the user knows where the gap is.
+	d := HWAccelDiagnostic{
+		Pick:          HWAccelNone,
+		FFmpegPath:    "/usr/bin/ffmpeg",
+		FFmpegVersion: "ffmpeg version 6.0",
+		Encoders:      []string{"h264_nvenc"},
+		Devices:       nil,
+	}
+	line := d.LogLine()
+	for _, want := range []string{"HW=none", "encoders found but no matching device", "h264_nvenc"} {
+		if !strings.Contains(line, want) {
+			t.Errorf("expected substring %q in log line; got %q", want, line)
+		}
+	}
+}
+
diff --git a/internal/engine/manager.go b/internal/engine/manager.go
index 12cfc06..2a07b6f 100644
--- a/internal/engine/manager.go
+++ b/internal/engine/manager.go
@@ -28,6 +28,15 @@ type Manager struct {
 
 	sem chan struct{}
 	wg  sync.WaitGroup
+
+	// OnTaskDone is called after a task completes or fails (slot freed).
+	// Used by the daemon to trigger an immediate sync.
+	OnTaskDone func()
+
+	// recentlyFinished holds tasks that completed/failed since the last sync read.
+	// The sync goroutine reads and clears this to include final states in the next sync.
+	recentMu       sync.Mutex
+	recentFinished []agent.TaskState
 }
 
 // NewManager creates a download manager.
@@ -67,7 +76,7 @@ func (m *Manager) Submit(ctx context.Context, at agent.Task) {
 
 	// Force start: bypass semaphore (like Transmission's "Force Start")
 	if at.ForceStart {
-		log.Printf("[%s] force start: bypassing queue", task.ID[:8])
+		log.Printf("[%s] force start: bypassing queue", agent.ShortID(task.ID))
 		m.wg.Add(1)
 		go func() {
 			defer m.wg.Done()
@@ -88,7 +97,12 @@ func (m *Manager) Submit(ctx context.Context, at agent.Task) {
 	m.wg.Add(1)
 	go func() {
 		defer m.wg.Done()
-		defer func() { <-m.sem }()
+		defer func() {
+			<-m.sem
+			if m.OnTaskDone != nil {
+				m.OnTaskDone()
+			}
+		}()
 		defer taskCancel()
 		m.processTask(taskCtx, task)
 	}()
@@ -99,6 +113,11 @@ func (m *Manager) HasCapacity() bool {
 	return len(m.sem) < cap(m.sem)
 }
 
+// FreeSlots returns the number of available download slots.
+func (m *Manager) FreeSlots() int {
+	return cap(m.sem) - len(m.sem)
+}
+
 // ActiveCount returns the number of in-progress downloads.
 func (m *Manager) ActiveCount() int {
 	m.activeMu.RLock()
@@ -113,6 +132,17 @@ func (m *Manager) GetTask(taskID string) *Task {
 	return m.active[taskID]
 }
 
+// ActiveTaskIDs returns the IDs of all in-progress tasks.
+func (m *Manager) ActiveTaskIDs() []string {
+	m.activeMu.RLock()
+	defer m.activeMu.RUnlock()
+	ids := make([]string, 0, len(m.active))
+	for id := range m.active {
+		ids = append(ids, id)
+	}
+	return ids
+}
+
 // ActiveTasks returns a snapshot of all active tasks.
 func (m *Manager) ActiveTasks() []*Task {
 	m.activeMu.RLock()
@@ -124,6 +154,37 @@ func (m *Manager) ActiveTasks() []*Task {
 	return tasks
 }
 
+// TaskStates returns the current state of all active tasks plus any recently
+// finished tasks that haven't been synced yet. Called by the sync goroutine.
+func (m *Manager) TaskStates() []agent.TaskState {
+	// Collect active tasks
+	m.activeMu.RLock()
+	states := make([]agent.TaskState, 0, len(m.active))
+	for _, t := range m.active {
+		states = append(states, agent.TaskStateFromUpdate(t.ToStatusUpdate()))
+	}
+	m.activeMu.RUnlock()
+
+	// Drain recently finished tasks (consumed once per sync)
+	m.recentMu.Lock()
+	states = append(states, m.recentFinished...)
+	m.recentFinished = nil
+	m.recentMu.Unlock()
+
+	return states
+}
+
+// recordFinished stores a completed/failed task for the next sync cycle.
+func (m *Manager) recordFinished(update agent.StatusUpdate) {
+	m.recentMu.Lock()
+	defer m.recentMu.Unlock()
+	m.recentFinished = append(m.recentFinished, agent.TaskStateFromUpdate(update))
+	// Keep bounded
+	if len(m.recentFinished) > 20 {
+		m.recentFinished = m.recentFinished[len(m.recentFinished)-20:]
+	}
+}
+
 // CancelTask cancels an active download by task ID (keeps partial files).
 func (m *Manager) CancelTask(taskID string) {
 	m.activeMu.RLock()
@@ -150,7 +211,7 @@ func (m *Manager) CancelTask(taskID string) {
 	task.mu.Unlock()
 	task.Transition(StatusCancelled)
 
-	log.Printf("[%s] cancelled: %s", taskID[:8], task.Title)
+	log.Printf("[%s] cancelled: %s", agent.ShortID(taskID), task.Title)
 }
 
 // PauseTask pauses an active download (keeps partial files for resume).
@@ -173,7 +234,7 @@ func (m *Manager) PauseTask(taskID string) {
 	}
 
 	task.Transition(StatusCancelled) // will be re-created as pending by server
-	log.Printf("[%s] paused: %s", taskID[:8], task.Title)
+	log.Printf("[%s] paused: %s", agent.ShortID(taskID), task.Title)
 }
 
 // CancelAndDeleteFiles cancels a download and removes its files from disk.
@@ -200,7 +261,7 @@ func (m *Manager) CancelAndDeleteFiles(taskID string) {
 	task.mu.Unlock()
 	task.Transition(StatusCancelled)
 
-	log.Printf("[%s] cancelled + files deleted: %s", taskID[:8], task.Title)
+	log.Printf("[%s] cancelled + files deleted: %s", agent.ShortID(taskID), task.Title)
 }
 
 // Wait blocks until all active downloads finish.
@@ -261,7 +322,7 @@ func (m *Manager) processTask(ctx context.Context, task *Task) {
 	}
 
 	task.ResolvedMethod = method
-	log.Printf("[%s] resolved method: %s", task.ID[:8], method)
+	log.Printf("[%s] resolved method: %s", agent.ShortID(task.ID), method)
 
 	// 2. Download
 	if err := task.Transition(StatusDownloading); err != nil {
@@ -285,7 +346,7 @@ func (m *Manager) processTask(ctx context.Context, task *Task) {
 	if err != nil {
 		// Try fallback
 		if tryFallback(task, m.downloaders) {
-			log.Printf("[%s] %s failed, trying fallback: %v", task.ID[:8], method, err)
+			log.Printf("[%s] %s failed, trying fallback: %v", agent.ShortID(task.ID), method, err)
 			if err := task.Transition(StatusResolving); err == nil {
 				m.processTaskRetry(ctx, task)
 				return
@@ -295,61 +356,7 @@ func (m *Manager) processTask(ctx context.Context, task *Task) {
 		return
 	}
 
-	// 3. Verify
-	if err := task.Transition(StatusVerifying); err != nil {
-		m.fail(ctx, task, "transition error: "+err.Error())
-		return
-	}
-
-	if err := verify(result); err != nil {
-		m.fail(ctx, task, "verification failed: "+err.Error())
-		return
-	}
-
-	// 4. Organize
-	if err := task.Transition(StatusOrganizing); err != nil {
-		m.fail(ctx, task, "transition error: "+err.Error())
-		return
-	}
-
-	finalPath, err := organize(result, task, m.cfg.Organize)
-	if err != nil {
-		log.Printf("[%s] organize warning: %v (keeping in download dir)", task.ID[:8], err)
-		finalPath = result.FilePath
-	}
-
-	task.mu.Lock()
-	task.FilePath = finalPath
-	task.mu.Unlock()
-
-	// 4b. Handle upgrade replacement (mode = "upgrade")
-	if task.ReplacePath != "" {
-		backupDir := "" // uses default ~/.local/share/unarr/replaced/
-		if err := replaceFile(task.ReplacePath, finalPath, backupDir); err != nil {
-			log.Printf("[%s] replace warning: %v (keeping new file at %s)", task.ID[:8], err, finalPath)
-		} else {
-			task.mu.Lock()
-			task.FilePath = task.ReplacePath
-			task.mu.Unlock()
-			log.Printf("[%s] upgraded: replaced %s", task.ID[:8], task.ReplacePath)
-		}
-	}
-
-	// 5. Complete
-	if method == MethodTorrent && m.cfg.Organize.Enabled {
-		// Could add seeding here in the future
-	}
-
-	if err := task.Transition(StatusCompleted); err != nil {
-		m.fail(ctx, task, "transition error: "+err.Error())
-		return
-	}
-
-	log.Printf("[%s] completed: %s -> %s", task.ID[:8], task.Title, finalPath)
-	if m.cfg.Notifications {
-		desktopNotify("Download complete", task.Title)
-	}
-	m.reporter.ReportFinal(ctx, task)
+	m.finalize(ctx, task, result)
 }
 
 // processTaskRetry handles fallback after a method failure.
@@ -361,7 +368,7 @@ func (m *Manager) processTaskRetry(ctx context.Context, task *Task) {
 	}
 
 	task.ResolvedMethod = method
-	log.Printf("[%s] fallback to: %s", task.ID[:8], method)
+	log.Printf("[%s] fallback to: %s", agent.ShortID(task.ID), method)
 
 	if err := task.Transition(StatusDownloading); err != nil {
 		m.fail(ctx, task, "transition error: "+err.Error())
@@ -383,15 +390,31 @@ func (m *Manager) processTaskRetry(ctx context.Context, task *Task) {
 		return
 	}
 
-	// Verify + Organize + Complete (same as processTask)
-	task.Transition(StatusVerifying)
+	m.finalize(ctx, task, result)
+}
+
+// finalize runs verify → organize → upgrade replacement → complete for a downloaded task.
+func (m *Manager) finalize(ctx context.Context, task *Task, result *Result) {
+	// Verify
+	if err := task.Transition(StatusVerifying); err != nil {
+		m.fail(ctx, task, "transition error: "+err.Error())
+		return
+	}
 	if err := verify(result); err != nil {
 		m.fail(ctx, task, "verification failed: "+err.Error())
 		return
 	}
 
-	task.Transition(StatusOrganizing)
-	finalPath, _ := organize(result, task, m.cfg.Organize)
+	// Organize
+	if err := task.Transition(StatusOrganizing); err != nil {
+		m.fail(ctx, task, "transition error: "+err.Error())
+		return
+	}
+	finalPath, err := organize(result, task, m.cfg.Organize)
+	if err != nil {
+		log.Printf("[%s] organize warning: %v (keeping in download dir)", agent.ShortID(task.ID), err)
+		finalPath = result.FilePath
+	}
 	if finalPath == "" {
 		finalPath = result.FilePath
 	}
@@ -399,8 +422,29 @@ func (m *Manager) processTaskRetry(ctx context.Context, task *Task) {
 	task.FilePath = finalPath
 	task.mu.Unlock()
 
-	task.Transition(StatusCompleted)
-	log.Printf("[%s] completed (fallback): %s -> %s", task.ID[:8], task.Title, finalPath)
+	// Handle upgrade replacement (mode = "upgrade")
+	if task.ReplacePath != "" {
+		backupDir := "" // uses default ~/.local/share/unarr/replaced/
+		if err := replaceFile(task.ReplacePath, finalPath, backupDir); err != nil {
+			log.Printf("[%s] replace warning: %v (keeping new file at %s)", agent.ShortID(task.ID), err, finalPath)
+		} else {
+			task.mu.Lock()
+			task.FilePath = task.ReplacePath
+			task.mu.Unlock()
+			log.Printf("[%s] upgraded: replaced %s", agent.ShortID(task.ID), task.ReplacePath)
+		}
+	}
+
+	// Complete
+	if err := task.Transition(StatusCompleted); err != nil {
+		m.fail(ctx, task, "transition error: "+err.Error())
+		return
+	}
+	log.Printf("[%s] completed: %s -> %s", agent.ShortID(task.ID), task.Title, finalPath)
+	if m.cfg.Notifications {
+		desktopNotify("Download complete", task.Title)
+	}
+	m.recordFinished(task.ToStatusUpdate())
 	m.reporter.ReportFinal(ctx, task)
 }
 
@@ -409,9 +453,10 @@ func (m *Manager) fail(ctx context.Context, task *Task, msg string) {
 	task.ErrorMessage = msg
 	task.mu.Unlock()
 	task.Transition(StatusFailed)
-	log.Printf("[%s] FAILED: %s — %s", task.ID[:8], task.Title, msg)
+	log.Printf("[%s] FAILED: %s — %s", agent.ShortID(task.ID), task.Title, msg)
 	if m.cfg.Notifications {
 		desktopNotify("Download failed", task.Title+": "+msg)
 	}
+	m.recordFinished(task.ToStatusUpdate())
 	m.reporter.ReportFinal(ctx, task)
 }
diff --git a/internal/engine/manager_integration_test.go b/internal/engine/manager_integration_test.go
new file mode 100644
index 0000000..6b3e88f
--- /dev/null
+++ b/internal/engine/manager_integration_test.go
@@ -0,0 +1,601 @@
+package engine
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+)
+
+// errorMockDownloader siempre falla en Download para simular fallo de método.
+type errorMockDownloader struct {
+	method DownloadMethod
+	err    error
+}
+
+func (m *errorMockDownloader) Method() DownloadMethod { return m.method }
+func (m *errorMockDownloader) Available(_ context.Context, _ *Task) (bool, error) {
+	return true, nil
+}
+func (m *errorMockDownloader) Download(_ context.Context, _ *Task, _ string, _ chan<- Progress) (*Result, error) {
+	if m.err != nil {
+		return nil, m.err
+	}
+	return nil, fmt.Errorf("simulated download failure for %s", m.method)
+}
+func (m *errorMockDownloader) Pause(_ string) error             { return nil }
+func (m *errorMockDownloader) Cancel(_ string) error            { return nil }
+func (m *errorMockDownloader) Shutdown(_ context.Context) error { return nil }
+
+// makeProgressReporter crea un ProgressReporter con mock de reporter para tests de integración.
+func makeProgressReporter() *ProgressReporter {
+	reporter := &mockStatusReporter{}
+	return &ProgressReporter{
+		reporter:     reporter,
+		interval:     100 * time.Millisecond,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+}
+
+// TestManagerPipeline_FullSuccess verifica el pipeline completo:
+// submit → download → verify → complete con archivo real en disco.
+func TestManagerPipeline_FullSuccess(t *testing.T) {
+	dir := t.TempDir()
+	filePath := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(filePath, make([]byte, 2048), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	pr := makeProgressReporter()
+	dl := &resultMockDownloader{
+		method: MethodTorrent,
+		result: &Result{
+			FilePath: filePath,
+			FileName: "movie.mkv",
+			Method:   MethodTorrent,
+			Size:     2048,
+		},
+	}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 1,
+		OutputDir:     dir,
+	}, pr, dl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	go pr.Run(ctx)
+
+	task := agent.Task{
+		ID:              "integration-full-123456",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Test Movie",
+		PreferredMethod: "torrent",
+	}
+	mgr.Submit(ctx, task)
+	mgr.Wait()
+}
+
+// TestManagerPipeline_Fallback_TorrentFails_DebridSucceeds verifica que cuando
+// torrent falla en modo "auto", el manager hace fallback a debrid.
+func TestManagerPipeline_Fallback_TorrentFails_DebridSucceeds(t *testing.T) {
+	dir := t.TempDir()
+	filePath := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(filePath, make([]byte, 2048), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	pr := makeProgressReporter()
+
+	// Torrent siempre falla
+	torrentDl := &errorMockDownloader{method: MethodTorrent}
+	// Debrid tiene éxito
+	debridDl := &resultMockDownloader{
+		method: MethodDebrid,
+		result: &Result{
+			FilePath: filePath,
+			FileName: "movie.mkv",
+			Method:   MethodDebrid,
+			Size:     2048,
+		},
+	}
+
+	// Debrid debe declararse disponible — usamos mockDownloader para eso
+	debridAvailDl := struct {
+		*errorMockDownloader
+		*resultMockDownloader
+	}{torrentDl, debridDl}
+	_ = debridAvailDl // unused, kept for clarity
+
+	// Un mock que es available=true y retorna resultado exitoso
+	type debridFullMock struct {
+		resultMockDownloader
+	}
+	debridFull := &debridFullMock{
+		resultMockDownloader: resultMockDownloader{
+			method: MethodDebrid,
+			result: &Result{
+				FilePath: filePath,
+				FileName: "movie.mkv",
+				Method:   MethodDebrid,
+				Size:     2048,
+			},
+		},
+	}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 1,
+		OutputDir:     dir,
+	}, pr, torrentDl, debridFull)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	go pr.Run(ctx)
+
+	// PreferredMethod: "auto" es necesario para que tryFallback funcione
+	task := agent.Task{
+		ID:              "fallback-test-123456789",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Fallback Movie",
+		PreferredMethod: "auto",
+	}
+	mgr.Submit(ctx, task)
+	mgr.Wait()
+	// Si llegamos aquí sin timeout, el fallback funcionó (torrent falló, debrid tuvo éxito)
+}
+
+// TestManagerPipeline_AllMethodsFail verifica que cuando todos los downloaders
+// fallan, la tarea termina en estado failed.
+func TestManagerPipeline_AllMethodsFail(t *testing.T) {
+	dir := t.TempDir()
+	pr := makeProgressReporter()
+
+	torrentDl := &errorMockDownloader{method: MethodTorrent, err: fmt.Errorf("no peers")}
+	// En modo "torrent" específico no hay fallback
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 1,
+		OutputDir:     dir,
+	}, pr, torrentDl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	go pr.Run(ctx)
+
+	task := agent.Task{
+		ID:              "fail-all-123456789012",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Failing Download",
+		PreferredMethod: "torrent",
+	}
+	mgr.Submit(ctx, task)
+	mgr.Wait()
+	// Si llegamos aquí, el manager manejó el fallo sin panic ni deadlock
+}
+
+// TestManagerPipeline_MultiConcurrent verifica que múltiples descargas concurrentes
+// completan todas correctamente.
+func TestManagerPipeline_MultiConcurrent(t *testing.T) {
+	dir := t.TempDir()
+	const numTasks = 3
+
+	// Crear archivos para cada tarea
+	files := make([]string, numTasks)
+	for i := 0; i < numTasks; i++ {
+		files[i] = filepath.Join(dir, fmt.Sprintf("movie%d.mkv", i))
+		if err := os.WriteFile(files[i], make([]byte, 1024), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	var submitCount atomic.Int32
+	pr := makeProgressReporter()
+
+	// Usar un mock que devuelve archivos distintos por tarea
+	dl := &multiResultMockDownloader{dir: dir, files: files}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: numTasks,
+		OutputDir:     dir,
+	}, pr, dl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	go pr.Run(ctx)
+
+	for i := 0; i < numTasks; i++ {
+		submitCount.Add(1)
+		task := agent.Task{
+			ID:              fmt.Sprintf("concurrent-task-%02d-123456", i),
+			InfoHash:        fmt.Sprintf("abc%037d", i), // 40 hex chars
+			Title:           fmt.Sprintf("Movie %d", i),
+			PreferredMethod: "torrent",
+		}
+		mgr.Submit(ctx, task)
+	}
+
+	mgr.Wait()
+
+	if submitCount.Load() != int32(numTasks) {
+		t.Errorf("submitted %d tasks, want %d", submitCount.Load(), numTasks)
+	}
+}
+
+// multiResultMockDownloader devuelve archivos distintos según el orden de llamadas.
+type multiResultMockDownloader struct {
+	dir       string
+	files     []string
+	callCount atomic.Int32
+}
+
+func (m *multiResultMockDownloader) Method() DownloadMethod { return MethodTorrent }
+func (m *multiResultMockDownloader) Available(_ context.Context, _ *Task) (bool, error) {
+	return true, nil
+}
+func (m *multiResultMockDownloader) Download(_ context.Context, _ *Task, _ string, _ chan<- Progress) (*Result, error) {
+	idx := int(m.callCount.Add(1)) - 1
+	if idx >= len(m.files) {
+		return nil, fmt.Errorf("too many calls to multiResultMockDownloader")
+	}
+	return &Result{
+		FilePath: m.files[idx],
+		FileName: filepath.Base(m.files[idx]),
+		Method:   MethodTorrent,
+		Size:     1024,
+	}, nil
+}
+func (m *multiResultMockDownloader) Pause(_ string) error             { return nil }
+func (m *multiResultMockDownloader) Cancel(_ string) error            { return nil }
+func (m *multiResultMockDownloader) Shutdown(_ context.Context) error { return nil }
+
+// TestManagerPipeline_CancelTaskMidDownload verifica que CancelTask() durante una
+// descarga activa libera el slot y no produce deadlock.
+func TestManagerPipeline_CancelTaskMidDownload(t *testing.T) {
+	dir := t.TempDir()
+	pr := makeProgressReporter()
+	dl := &slowMockDownloader{method: MethodTorrent}
+
+	const taskID = "cancel-mid-test-12345"
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 2,
+		OutputDir:     dir,
+	}, pr, dl)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go pr.Run(ctx)
+
+	task := agent.Task{
+		ID:              taskID,
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Cancel Test",
+		PreferredMethod: "torrent",
+	}
+	mgr.Submit(ctx, task)
+
+	// Esperar a que la tarea esté activa
+	time.Sleep(100 * time.Millisecond)
+
+	// Cancelar la tarea específica (cancela su contexto interno)
+	mgr.CancelTask(taskID)
+
+	done := make(chan struct{})
+	go func() {
+		mgr.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// OK — manager terminó limpiamente tras CancelTask
+	case <-time.After(5 * time.Second):
+		t.Error("Manager.Wait() timed out after CancelTask — possible deadlock")
+	}
+}
+
+// TestManagerPipeline_OnTaskDone_Called verifica que el callback OnTaskDone
+// se llama exactamente una vez cuando una tarea completa.
+func TestManagerPipeline_OnTaskDone_Called(t *testing.T) {
+	dir := t.TempDir()
+	filePath := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(filePath, make([]byte, 1024), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	pr := makeProgressReporter()
+	dl := &resultMockDownloader{
+		method: MethodTorrent,
+		result: &Result{FilePath: filePath, FileName: "movie.mkv", Method: MethodTorrent, Size: 1024},
+	}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 1,
+		OutputDir:     dir,
+	}, pr, dl)
+
+	var callCount atomic.Int32
+	mgr.OnTaskDone = func() {
+		callCount.Add(1)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	go pr.Run(ctx)
+
+	task := agent.Task{
+		ID:              "ontaskdone-test-123456",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Done Callback Test",
+		PreferredMethod: "torrent",
+	}
+	mgr.Submit(ctx, task)
+	mgr.Wait()
+
+	if callCount.Load() != 1 {
+		t.Errorf("OnTaskDone called %d times, want 1", callCount.Load())
+	}
+}
+
+// TestManagerPipeline_RecentFinished_DrainedOnSync verifica que TaskStates()
+// incluye tareas recientemente finalizadas y las limpia en la siguiente llamada.
+func TestManagerPipeline_RecentFinished_DrainedOnSync(t *testing.T) {
+	dir := t.TempDir()
+	filePath := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(filePath, make([]byte, 1024), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	pr := makeProgressReporter()
+	dl := &resultMockDownloader{
+		method: MethodTorrent,
+		result: &Result{FilePath: filePath, FileName: "movie.mkv", Method: MethodTorrent, Size: 1024},
+	}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 1,
+		OutputDir:     dir,
+	}, pr, dl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	go pr.Run(ctx)
+
+	task := agent.Task{
+		ID:              "recent-finished-12345",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Recent Test",
+		PreferredMethod: "torrent",
+	}
+	mgr.Submit(ctx, task)
+	mgr.Wait()
+
+	// Primera llamada a TaskStates() debe incluir la tarea finalizada
+	states := mgr.TaskStates()
+
+	// La tarea se eliminó del mapa active, pero debe estar en recentFinished
+	foundRecent := false
+	for _, s := range states {
+		if s.TaskID == task.ID {
+			foundRecent = true
+			break
+		}
+	}
+	if !foundRecent {
+		t.Error("TaskStates() should include recently finished task in first call")
+	}
+
+	// Segunda llamada: recentFinished debe estar vacío (ya se drenó)
+	states2 := mgr.TaskStates()
+	for _, s := range states2 {
+		if s.TaskID == task.ID {
+			t.Error("TaskStates() should NOT include finished task in second call (should be drained)")
+			break
+		}
+	}
+}
+
+// TestManagerPipeline_ForceStart_BypassesSemaphore verifica que ForceStart=true
+// permite iniciar descargas aunque el semáforo esté lleno.
+func TestManagerPipeline_ForceStart_BypassesSemaphore(t *testing.T) {
+	dir := t.TempDir()
+	pr := makeProgressReporter()
+
+	// slowMock bloqueará el semáforo
+	slowDl := &slowMockDownloader{method: MethodTorrent}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 1, // semáforo de 1
+		OutputDir:     dir,
+	}, pr, slowDl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	go pr.Run(ctx)
+
+	// Primera tarea: llena el semáforo
+	task1 := agent.Task{
+		ID:              "force-start-slow-12345",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Slow Task",
+		PreferredMethod: "torrent",
+	}
+	mgr.Submit(ctx, task1)
+
+	// Pequeña pausa para que task1 adquiera el semáforo
+	time.Sleep(50 * time.Millisecond)
+
+	// Segunda tarea con ForceStart=true: debe empezar aunque semáforo lleno
+	filePath := filepath.Join(dir, "force.mkv")
+	if err := os.WriteFile(filePath, make([]byte, 512), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Para ForceStart necesitamos un downloader que tenga éxito inmediato
+	// Usar resultMockDownloader pero ForceStart necesita el mismo downloader registrado
+	// Modificamos el test: verificar que ActiveCount() > MaxConcurrent con ForceStart
+	task2 := agent.Task{
+		ID:              "force-start-fast-12345",
+		InfoHash:        "def456abc123def456abc123def456abc123def4",
+		Title:           "Force Task",
+		PreferredMethod: "torrent",
+		ForceStart:      true,
+	}
+	mgr.Submit(ctx, task2)
+
+	// Verificar que hay más tareas activas que el límite del semáforo
+	time.Sleep(50 * time.Millisecond)
+	active := mgr.ActiveCount()
+	if active < 1 {
+		t.Errorf("expected at least 1 active task with ForceStart, got %d", active)
+	}
+
+	cancel() // terminar las tareas lentas
+	mgr.Wait()
+}
+
+// TestManagerPipeline_Organize_MoviesDir verifica que cuando organize está
+// habilitado y ContentType es "movie", el archivo se mueve al directorio correcto.
+func TestManagerPipeline_Organize_MoviesDir(t *testing.T) {
+	downloadDir := t.TempDir()
+	moviesDir := t.TempDir()
+
+	filePath := filepath.Join(downloadDir, "movie.mkv")
+	if err := os.WriteFile(filePath, make([]byte, 1024), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	pr := makeProgressReporter()
+	dl := &resultMockDownloader{
+		method: MethodTorrent,
+		result: &Result{
+			FilePath: filePath,
+			FileName: "movie.mkv",
+			Method:   MethodTorrent,
+			Size:     1024,
+		},
+	}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 1,
+		OutputDir:     downloadDir,
+		Organize: OrganizeConfig{
+			Enabled:   true,
+			MoviesDir: moviesDir,
+			OutputDir: downloadDir,
+		},
+	}, pr, dl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	go pr.Run(ctx)
+
+	task := agent.Task{
+		ID:              "organize-test-1234567",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "The Matrix 1999",
+		PreferredMethod: "torrent",
+	}
+	mgr.Submit(ctx, task)
+	mgr.Wait()
+
+	// El archivo debe haberse movido a moviesDir (o seguir en downloadDir si hay error de organización)
+	// Lo que nos importa es que no haya crash
+}
+
+// TestManagerPipeline_Shutdown_GracefulWithActiveDownloads verifica que Shutdown()
+// espera a que terminen las descargas activas antes de salir.
+func TestManagerPipeline_Shutdown_GracefulWithActiveDownloads(t *testing.T) {
+	dir := t.TempDir()
+	pr := makeProgressReporter()
+
+	// Downloader que tarda un poco pero termina
+	dl := &timedResultMockDownloader{
+		method:  MethodTorrent,
+		delay:   100 * time.Millisecond,
+		dir:     dir,
+		content: make([]byte, 512),
+	}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 2,
+		OutputDir:     dir,
+	}, pr, dl)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go pr.Run(ctx)
+
+	task := agent.Task{
+		ID:              "shutdown-graceful-123",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Graceful Test",
+		PreferredMethod: "torrent",
+	}
+	mgr.Submit(ctx, task)
+
+	// Dar tiempo a que la tarea empiece
+	time.Sleep(20 * time.Millisecond)
+
+	// Shutdown con timeout suficiente para que la tarea termine
+	shutCtx, shutCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer shutCancel()
+
+	start := time.Now()
+	mgr.Shutdown(shutCtx)
+	elapsed := time.Since(start)
+
+	if elapsed > 4*time.Second {
+		t.Errorf("Shutdown took too long: %v", elapsed)
+	}
+}
+
+// timedResultMockDownloader simula una descarga que tarda un tiempo específico.
+type timedResultMockDownloader struct {
+	method  DownloadMethod
+	delay   time.Duration
+	dir     string
+	content []byte
+}
+
+func (m *timedResultMockDownloader) Method() DownloadMethod { return m.method }
+func (m *timedResultMockDownloader) Available(_ context.Context, _ *Task) (bool, error) {
+	return true, nil
+}
+func (m *timedResultMockDownloader) Download(ctx context.Context, task *Task, outputDir string, _ chan<- Progress) (*Result, error) {
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case <-time.After(m.delay):
+	}
+
+	filePath := filepath.Join(outputDir, "timed.mkv")
+	if err := os.WriteFile(filePath, m.content, 0o644); err != nil {
+		return nil, err
+	}
+	return &Result{
+		FilePath: filePath,
+		FileName: "timed.mkv",
+		Method:   m.method,
+		Size:     int64(len(m.content)),
+	}, nil
+}
+func (m *timedResultMockDownloader) Pause(_ string) error             { return nil }
+func (m *timedResultMockDownloader) Cancel(_ string) error            { return nil }
+func (m *timedResultMockDownloader) Shutdown(_ context.Context) error { return nil }
+
+// TestManagerPipeline_FreeSlots verifica que FreeSlots() refleja el número
+// correcto de slots disponibles.
+func TestManagerPipeline_FreeSlots(t *testing.T) {
+	pr := makeProgressReporter()
+	mgr := NewManager(ManagerConfig{MaxConcurrent: 3}, pr)
+
+	if slots := mgr.FreeSlots(); slots != 3 {
+		t.Errorf("FreeSlots() = %d, want 3 when empty", slots)
+	}
+}
diff --git a/internal/engine/manager_test.go b/internal/engine/manager_test.go
index 7c9893f..5989757 100644
--- a/internal/engine/manager_test.go
+++ b/internal/engine/manager_test.go
@@ -2,6 +2,7 @@ package engine
 
 import (
 	"context"
+	"os"
 	"testing"
 	"time"
 
@@ -83,3 +84,223 @@ func TestManagerShutdown(t *testing.T) {
 	mgr.Shutdown(ctx)
 	// Should not hang
 }
+
+func TestManagerDefaultConcurrency(t *testing.T) {
+	reporter := NewProgressReporter(
+		agent.NewClient("http://localhost", "test", "test"),
+		1*time.Second,
+	)
+	mgr := NewManager(ManagerConfig{MaxConcurrent: 0}, reporter)
+	if cap(mgr.sem) != 3 {
+		t.Errorf("default MaxConcurrent should be 3, got %d", cap(mgr.sem))
+	}
+}
+
+func TestManagerGetTask(t *testing.T) {
+	reporter := NewProgressReporter(
+		agent.NewClient("http://localhost", "test", "test"),
+		1*time.Second,
+	)
+	mgr := NewManager(ManagerConfig{MaxConcurrent: 2}, reporter)
+
+	// No task added
+	if task := mgr.GetTask("nonexistent"); task != nil {
+		t.Error("expected nil for nonexistent task")
+	}
+}
+
+func TestManagerActiveTasks(t *testing.T) {
+	reporter := NewProgressReporter(
+		agent.NewClient("http://localhost", "test", "test"),
+		1*time.Second,
+	)
+	mgr := NewManager(ManagerConfig{MaxConcurrent: 2}, reporter)
+
+	tasks := mgr.ActiveTasks()
+	if len(tasks) != 0 {
+		t.Errorf("expected 0 active tasks, got %d", len(tasks))
+	}
+}
+
+func TestManagerSubmitCompletesWithValidFile(t *testing.T) {
+	dir := t.TempDir()
+	// Create a file that verify() will accept
+	filePath := dir + "/movie.mkv"
+	os.WriteFile(filePath, make([]byte, 1024), 0o644)
+
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     100 * time.Millisecond,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+
+	dl := &resultMockDownloader{
+		method: MethodTorrent,
+		result: &Result{
+			FilePath: filePath,
+			FileName: "movie.mkv",
+			Method:   MethodTorrent,
+			Size:     1024,
+		},
+	}
+
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 2,
+		OutputDir:     dir,
+	}, pr, dl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	go pr.Run(ctx)
+
+	mgr.Submit(ctx, agent.Task{
+		ID:              "task-complete-test1",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Test Movie",
+		PreferredMethod: "torrent",
+	})
+
+	mgr.Wait()
+	cancel()
+
+	// Task should have completed successfully
+	// (we can't check directly since it's removed from active map after processing)
+}
+
+func TestManagerCancelTask(t *testing.T) {
+	reporter := NewProgressReporter(
+		agent.NewClient("http://localhost", "test", "test"),
+		1*time.Second,
+	)
+
+	dl := &slowMockDownloader{method: MethodTorrent}
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 2,
+		OutputDir:     t.TempDir(),
+	}, reporter, dl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	go reporter.Run(ctx)
+
+	mgr.Submit(ctx, agent.Task{
+		ID:              "task-cancel-test12",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Cancel Me",
+		PreferredMethod: "torrent",
+	})
+
+	// Give it time to start
+	time.Sleep(100 * time.Millisecond)
+
+	mgr.CancelTask("task-cancel-test12")
+	mgr.Wait()
+}
+
+func TestManagerPauseTask(t *testing.T) {
+	reporter := NewProgressReporter(
+		agent.NewClient("http://localhost", "test", "test"),
+		1*time.Second,
+	)
+
+	dl := &slowMockDownloader{method: MethodTorrent}
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 2,
+		OutputDir:     t.TempDir(),
+	}, reporter, dl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	go reporter.Run(ctx)
+
+	mgr.Submit(ctx, agent.Task{
+		ID:              "task-pause-test123",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Pause Me",
+		PreferredMethod: "torrent",
+	})
+
+	time.Sleep(100 * time.Millisecond)
+	mgr.PauseTask("task-pause-test123")
+	mgr.Wait()
+}
+
+func TestManagerCancelAndDeleteFiles(t *testing.T) {
+	reporter := NewProgressReporter(
+		agent.NewClient("http://localhost", "test", "test"),
+		1*time.Second,
+	)
+
+	dl := &slowMockDownloader{method: MethodTorrent}
+	mgr := NewManager(ManagerConfig{
+		MaxConcurrent: 2,
+		OutputDir:     t.TempDir(),
+	}, reporter, dl)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	go reporter.Run(ctx)
+
+	mgr.Submit(ctx, agent.Task{
+		ID:              "task-delfile-test12",
+		InfoHash:        "abc123def456abc123def456abc123def456abc1",
+		Title:           "Delete Me",
+		PreferredMethod: "torrent",
+	})
+
+	time.Sleep(100 * time.Millisecond)
+	mgr.CancelAndDeleteFiles("task-delfile-test12")
+	mgr.Wait()
+}
+
+func TestManagerCancelNonexistent(t *testing.T) {
+	reporter := NewProgressReporter(
+		agent.NewClient("http://localhost", "test", "test"),
+		1*time.Second,
+	)
+	mgr := NewManager(ManagerConfig{MaxConcurrent: 2}, reporter)
+	// Should not panic
+	mgr.CancelTask("nonexistent")
+	mgr.PauseTask("nonexistent")
+	mgr.CancelAndDeleteFiles("nonexistent")
+}
+
+// resultMockDownloader returns a configurable result
+type resultMockDownloader struct {
+	method DownloadMethod
+	result *Result
+}
+
+func (m *resultMockDownloader) Method() DownloadMethod { return m.method }
+func (m *resultMockDownloader) Available(_ context.Context, _ *Task) (bool, error) {
+	return true, nil
+}
+func (m *resultMockDownloader) Download(_ context.Context, _ *Task, _ string, _ chan<- Progress) (*Result, error) {
+	return m.result, nil
+}
+func (m *resultMockDownloader) Pause(_ string) error             { return nil }
+func (m *resultMockDownloader) Cancel(_ string) error            { return nil }
+func (m *resultMockDownloader) Shutdown(_ context.Context) error { return nil }
+
+// slowMockDownloader blocks until context is cancelled
+type slowMockDownloader struct {
+	method DownloadMethod
+}
+
+func (m *slowMockDownloader) Method() DownloadMethod { return m.method }
+func (m *slowMockDownloader) Available(_ context.Context, _ *Task) (bool, error) {
+	return true, nil
+}
+func (m *slowMockDownloader) Download(ctx context.Context, _ *Task, _ string, _ chan<- Progress) (*Result, error) {
+	<-ctx.Done()
+	return nil, ctx.Err()
+}
+func (m *slowMockDownloader) Pause(_ string) error             { return nil }
+func (m *slowMockDownloader) Cancel(_ string) error            { return nil }
+func (m *slowMockDownloader) Shutdown(_ context.Context) error { return nil }
diff --git a/internal/engine/method_test.go b/internal/engine/method_test.go
new file mode 100644
index 0000000..e913d32
--- /dev/null
+++ b/internal/engine/method_test.go
@@ -0,0 +1,50 @@
+package engine
+
+import "testing"
+
+func TestDownloadMethodConstants(t *testing.T) {
+	if MethodTorrent != "torrent" {
+		t.Errorf("MethodTorrent = %q, want torrent", MethodTorrent)
+	}
+	if MethodDebrid != "debrid" {
+		t.Errorf("MethodDebrid = %q, want debrid", MethodDebrid)
+	}
+	if MethodUsenet != "usenet" {
+		t.Errorf("MethodUsenet = %q, want usenet", MethodUsenet)
+	}
+}
+
+func TestProgressStruct(t *testing.T) {
+	p := Progress{
+		DownloadedBytes: 1024,
+		TotalBytes:      2048,
+		SpeedBps:        512,
+		ETA:             10,
+		Peers:           5,
+		Seeds:           3,
+		FileName:        "movie.mkv",
+	}
+
+	if p.DownloadedBytes != 1024 {
+		t.Errorf("DownloadedBytes = %d, want 1024", p.DownloadedBytes)
+	}
+	if p.FileName != "movie.mkv" {
+		t.Errorf("FileName = %q, want movie.mkv", p.FileName)
+	}
+}
+
+func TestResultStruct(t *testing.T) {
+	r := Result{
+		FilePath: "/downloads/movie.mkv",
+		FileName: "movie.mkv",
+		Method:   MethodTorrent,
+		Size:     1073741824,
+	}
+
+	if r.Method != MethodTorrent {
+		t.Errorf("Method = %q, want torrent", r.Method)
+	}
+	if r.Size != 1073741824 {
+		t.Errorf("Size = %d, want 1073741824", r.Size)
+	}
+}
diff --git a/internal/engine/organize.go b/internal/engine/organize.go
index ea2eec4..3026c3f 100644
--- a/internal/engine/organize.go
+++ b/internal/engine/organize.go
@@ -3,6 +3,7 @@ package engine
 import (
 	"fmt"
 	"io"
+	"log"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -15,6 +16,17 @@ var (
 	seasonRegex  = regexp.MustCompile(`(?i)S(\d{2})`)
 	episodeRegex = regexp.MustCompile(`(?i)S(\d{2})E(\d{2})`)
 	altEpRegex   = regexp.MustCompile(`(?i)(\d{1,2})x(\d{2})`) // 1x05 format
+	pathReplacer = strings.NewReplacer(
+		"/", "-",
+		"\\", "-",
+		":", " -",
+		"?", "",
+		"*", "",
+		"\"", "",
+		"<", "",
+		">", "",
+		"|", "-",
+	)
 )
 
 // OrganizeConfig holds file organization settings.
@@ -22,36 +34,95 @@ type OrganizeConfig struct {
 	Enabled    bool
 	MoviesDir  string
 	TVShowsDir string
+	OutputDir  string // download directory — used to clean up torrent subdirectories after move
 }
 
 // organize moves a downloaded file into the proper directory structure.
-// Movies: MoviesDir/Title (Year)/filename.ext
-// TV:     TVShowsDir/Title/Season XX/filename.ext
+//
+// When server metadata is available (ContentType, ContentTitle, Season, CollectionName):
+//   - Shows:       TVShowsDir/ContentTitle/Season XX/filename.ext
+//   - Collections: MoviesDir/CollectionName/ContentTitle (Year)/filename.ext
+//   - Movies:      MoviesDir/ContentTitle (Year)/filename.ext
+//
+// Falls back to legacy regex-based detection when metadata is missing.
 func organize(result *Result, task *Task, cfg OrganizeConfig) (string, error) {
 	if !cfg.Enabled || result == nil || result.FilePath == "" {
 		return result.FilePath, nil
 	}
 
+	var destDir string
+	var destFileName string // empty = keep original filename
+
+	ext := filepath.Ext(result.FileName)
+	if ext == "" {
+		ext = filepath.Ext(result.FilePath)
+	}
+
+	if task.ContentType == "show" && cfg.TVShowsDir != "" {
+		// TV show: use clean title from server, group all episodes under one folder
+		showName := task.ContentTitle
+		if showName == "" {
+			showName = cleanTitle(task.Title) // fallback
+		}
+		destDir = filepath.Join(cfg.TVShowsDir, sanitizePath(showName))
+		if task.Season != nil {
+			destDir = filepath.Join(destDir, fmt.Sprintf("Season %02d", *task.Season))
+			// Rename: "ShowName - S01E03.mkv" so media players identify it
+			if task.Episode != nil {
+				destFileName = fmt.Sprintf("%s - S%02dE%02d%s", sanitizePath(showName), *task.Season, *task.Episode, ext)
+			}
+		} else if season := detectSeason(result.FileName); season != "" {
+			destDir = filepath.Join(destDir, fmt.Sprintf("Season %s", season))
+		}
+
+	} else if task.CollectionName != "" && cfg.MoviesDir != "" {
+		// Collection movie: CollectionName/MovieTitle (Year)/file
+		collDir := sanitizePath(task.CollectionName)
+		movieName := task.ContentTitle
+		if movieName == "" {
+			movieName = cleanTitle(task.Title)
+		}
+		year := resolveYear(task)
+		if year != "" {
+			destDir = filepath.Join(cfg.MoviesDir, collDir, fmt.Sprintf("%s (%s)", sanitizePath(movieName), year))
+			destFileName = fmt.Sprintf("%s (%s)%s", sanitizePath(movieName), year, ext)
+		} else {
+			destDir = filepath.Join(cfg.MoviesDir, collDir, sanitizePath(movieName))
+			destFileName = fmt.Sprintf("%s%s", sanitizePath(movieName), ext)
+		}
+
+	} else if task.ContentType == "movie" && cfg.MoviesDir != "" {
+		// Regular movie with server metadata
+		movieName := task.ContentTitle
+		if movieName == "" {
+			movieName = cleanTitle(task.Title)
+		}
+		year := resolveYear(task)
+		if year != "" {
+			destDir = filepath.Join(cfg.MoviesDir, fmt.Sprintf("%s (%s)", sanitizePath(movieName), year))
+			destFileName = fmt.Sprintf("%s (%s)%s", sanitizePath(movieName), year, ext)
+		} else {
+			destDir = filepath.Join(cfg.MoviesDir, sanitizePath(movieName))
+			destFileName = fmt.Sprintf("%s%s", sanitizePath(movieName), ext)
+		}
+
+	} else {
+		// No server metadata: fall back to legacy regex-based detection
+		return organizeLegacy(result, task, cfg)
+	}
+
+	return moveToDir(result, destDir, destFileName, cfg)
+}
+
+// organizeLegacy is the original regex-based organize logic for tasks without server metadata.
+func organizeLegacy(result *Result, task *Task, cfg OrganizeConfig) (string, error) {
 	title := task.Title
 	if title == "" {
 		title = result.FileName
 	}
 
-	isTV := strings.Contains(strings.ToLower(task.PreferredMethod), "show") ||
-		seasonRegex.MatchString(result.FileName)
-
-	// Detect season for TV (S01E05 or 1x05 format)
-	var season string
-	if m := episodeRegex.FindStringSubmatch(result.FileName); len(m) > 2 {
-		season = m[1]
-		isTV = true
-	} else if m := altEpRegex.FindStringSubmatch(result.FileName); len(m) > 2 {
-		season = fmt.Sprintf("%02s", m[1])
-		isTV = true
-	} else if m := seasonRegex.FindStringSubmatch(result.FileName); len(m) > 1 {
-		season = m[1]
-		isTV = true
-	}
+	season := detectSeason(result.FileName)
+	isTV := season != ""
 
 	var destDir string
 	if isTV && cfg.TVShowsDir != "" {
@@ -69,34 +140,38 @@ func organize(result *Result, task *Task, cfg OrganizeConfig) (string, error) {
 			destDir = filepath.Join(cfg.MoviesDir, movieName)
 		}
 	} else {
-		return result.FilePath, nil // no organize dirs configured
+		return result.FilePath, nil
 	}
 
-	// Validate destination is within the expected base directory
-	var baseDir string
-	if isTV && cfg.TVShowsDir != "" {
-		baseDir = cfg.TVShowsDir
-	} else {
-		baseDir = cfg.MoviesDir
-	}
-	if !isWithinDir(baseDir, destDir) {
-		return "", fmt.Errorf("path traversal blocked: %q escapes %q", destDir, baseDir)
+	return moveToDir(result, destDir, "", cfg)
+}
+
+// moveToDir handles the actual directory creation and file move, including path traversal check.
+// If destFileName is non-empty, the file is renamed to that name (instead of keeping the original).
+func moveToDir(result *Result, destDir, destFileName string, cfg OrganizeConfig) (string, error) {
+	// Validate destination is within an expected base directory
+	if !((cfg.TVShowsDir != "" && isWithinDir(cfg.TVShowsDir, destDir)) ||
+		(cfg.MoviesDir != "" && isWithinDir(cfg.MoviesDir, destDir)) ||
+		(cfg.OutputDir != "" && isWithinDir(cfg.OutputDir, destDir))) {
+		return "", fmt.Errorf("path traversal blocked: %q is not within any configured directory", destDir)
 	}
 
 	if err := os.MkdirAll(destDir, 0o755); err != nil {
 		return "", fmt.Errorf("create dir: %w", err)
 	}
 
-	destPath := filepath.Join(destDir, filepath.Base(result.FilePath))
+	fileName := filepath.Base(result.FilePath)
+	if destFileName != "" {
+		fileName = destFileName
+	}
+	destPath := filepath.Join(destDir, fileName)
 
-	// Check if source is a directory (multi-file torrent)
 	srcInfo, err := os.Stat(result.FilePath)
 	if err != nil {
 		return "", fmt.Errorf("stat source: %w", err)
 	}
 
 	if srcInfo.IsDir() {
-		// For directories: remove existing destination if present, then rename
 		if _, err := os.Stat(destPath); err == nil {
 			os.RemoveAll(destPath)
 		}
@@ -106,7 +181,6 @@ func organize(result *Result, task *Task, cfg OrganizeConfig) (string, error) {
 		return destPath, nil
 	}
 
-	// Try rename first (same filesystem), fall back to copy+delete
 	if err := os.Rename(result.FilePath, destPath); err != nil {
 		if err := copyFile(result.FilePath, destPath); err != nil {
 			return "", fmt.Errorf("move file: %w", err)
@@ -114,9 +188,162 @@ func organize(result *Result, task *Task, cfg OrganizeConfig) (string, error) {
 		os.Remove(result.FilePath)
 	}
 
+	// Move subtitle files alongside the video
+	moveSubtitles(result.FilePath, destDir, destFileName)
+
+	// Clean up the source torrent directory if it's a subdirectory of OutputDir
+	// and now empty or only contains junk files (nfo, txt, url, etc.)
+	cleanupSourceDir(result.FilePath, cfg.OutputDir)
+
 	return destPath, nil
 }
 
+// cleanupSourceDir removes the parent directory of srcFile if:
+//   - it's a subdirectory of outputDir (any depth, e.g. outputDir/TorrentName/ or outputDir/category/TorrentName/)
+//   - it contains no video files or subdirectories after the move
+//
+// This cleans up leftover junk files (nfo, txt, url, jpg) from multi-file torrents.
+func cleanupSourceDir(srcFile, outputDir string) {
+	if outputDir == "" {
+		return
+	}
+
+	srcDir := filepath.Dir(srcFile)
+	absOutput, err1 := filepath.Abs(outputDir)
+	absSrcDir, err2 := filepath.Abs(srcDir)
+	if err1 != nil || err2 != nil {
+		return
+	}
+
+	// Never delete outputDir itself
+	if absSrcDir == absOutput {
+		return
+	}
+	// Must be within outputDir
+	if !strings.HasPrefix(absSrcDir, absOutput+string(os.PathSeparator)) {
+		return
+	}
+
+	entries, err := os.ReadDir(absSrcDir)
+	if err != nil {
+		return
+	}
+
+	for _, e := range entries {
+		if e.IsDir() {
+			return // has subdirectories, don't touch
+		}
+		if isVideoFile(e.Name()) || isSubtitleFile(e.Name()) {
+			return // still has video/subtitle files, don't clean
+		}
+	}
+
+	// Only junk files remain — remove the entire directory
+	if err := os.RemoveAll(absSrcDir); err != nil {
+		log.Printf("[organize] cleanup warning: failed to remove %s: %v", absSrcDir, err)
+	}
+}
+
+// isVideoFile checks if a filename has a common video extension.
+func isVideoFile(name string) bool {
+	ext := strings.ToLower(filepath.Ext(name))
+	switch ext {
+	case ".mkv", ".mp4", ".avi", ".wmv", ".mov", ".flv", ".webm", ".m4v", ".ts", ".m2ts":
+		return true
+	}
+	return false
+}
+
+// detectSeason extracts the season number from a filename using regex (for fallback).
+func detectSeason(fileName string) string {
+	if m := episodeRegex.FindStringSubmatch(fileName); len(m) > 2 {
+		return m[1]
+	}
+	if m := altEpRegex.FindStringSubmatch(fileName); len(m) > 2 {
+		return fmt.Sprintf("%02s", m[1])
+	}
+	if m := seasonRegex.FindStringSubmatch(fileName); len(m) > 1 {
+		return m[1]
+	}
+	return ""
+}
+
+// sanitizePath removes characters that are invalid in file/directory names.
+func sanitizePath(name string) string {
+	s := pathReplacer.Replace(name)
+	s = strings.TrimSpace(s)
+	s = strings.TrimRight(s, ".")
+	if s == "" {
+		return "Unknown"
+	}
+	return s
+}
+
+// moveSubtitles moves subtitle files from the source directory to destDir.
+// If destFileName is set (video was renamed), subtitles are renamed to match.
+// Matches subtitles by video base name (e.g., "Movie.srt", "Movie.en.srt").
+func moveSubtitles(srcVideoPath, destDir, destFileName string) {
+	srcDir := filepath.Dir(srcVideoPath)
+	videoBase := strings.TrimSuffix(filepath.Base(srcVideoPath), filepath.Ext(srcVideoPath))
+	destVideoBase := ""
+	if destFileName != "" {
+		destVideoBase = strings.TrimSuffix(destFileName, filepath.Ext(destFileName))
+	}
+
+	entries, err := os.ReadDir(srcDir)
+	if err != nil {
+		return
+	}
+
+	for _, e := range entries {
+		if e.IsDir() || !isSubtitleFile(e.Name()) {
+			continue
+		}
+		// Match: subtitle must start with the video base name
+		// e.g., "Movie.srt", "Movie.en.srt", "Movie.forced.eng.srt"
+		if !strings.HasPrefix(e.Name(), videoBase) {
+			continue
+		}
+
+		subSrc := filepath.Join(srcDir, e.Name())
+		subDest := e.Name()
+		// Rename subtitle to match new video name if video was renamed
+		// e.g., "Movie.en.srt" → "Oppenheimer (2023).en.srt"
+		if destVideoBase != "" {
+			suffix := strings.TrimPrefix(e.Name(), videoBase) // ".en.srt" or ".srt"
+			subDest = destVideoBase + suffix
+		}
+		destPath := filepath.Join(destDir, subDest)
+
+		if err := os.Rename(subSrc, destPath); err != nil {
+			if err := copyFile(subSrc, destPath); err != nil {
+				log.Printf("[organize] warning: failed to move subtitle %s: %v", e.Name(), err)
+				continue
+			}
+			os.Remove(subSrc)
+		}
+	}
+}
+
+// resolveYear returns the content year as a string.
+// Prefers the server-provided ContentYear; falls back to regex extraction from the torrent title.
+func resolveYear(task *Task) string {
+	if task.ContentYear != nil && *task.ContentYear > 0 {
+		return fmt.Sprintf("%d", *task.ContentYear)
+	}
+	return yearRegex.FindString(task.Title)
+}
+
+// isSubtitleFile checks if a filename has a common subtitle extension.
+func isSubtitleFile(name string) bool {
+	ext := strings.ToLower(filepath.Ext(name))
+	switch ext {
+	case ".srt", ".sub", ".ass", ".ssa", ".vtt", ".idx":
+		return true
+	}
+	return false
+}
+
 // cleanTitle extracts a clean title from a torrent title string.
 func cleanTitle(title string) string {
 	// Remove year and everything after common separators
diff --git a/internal/engine/organize_expand_test.go b/internal/engine/organize_expand_test.go
new file mode 100644
index 0000000..272011c
--- /dev/null
+++ b/internal/engine/organize_expand_test.go
@@ -0,0 +1,560 @@
+package engine
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestReplaceFile(t *testing.T) {
+	tmp := t.TempDir()
+	backupDir := filepath.Join(tmp, "backups")
+
+	// Create "old" file
+	oldPath := filepath.Join(tmp, "movie.mkv")
+	os.WriteFile(oldPath, []byte("old content"), 0o644)
+
+	// Create "new" file
+	newPath := filepath.Join(tmp, "movie-new.mkv")
+	os.WriteFile(newPath, []byte("new better content"), 0o644)
+
+	err := replaceFile(oldPath, newPath, backupDir)
+	if err != nil {
+		t.Fatalf("replaceFile: %v", err)
+	}
+
+	// Old path should now contain new content
+	data, err := os.ReadFile(oldPath)
+	if err != nil {
+		t.Fatalf("read old path: %v", err)
+	}
+	if string(data) != "new better content" {
+		t.Errorf("old path content = %q, want 'new better content'", string(data))
+	}
+
+	// Backup should exist
+	entries, _ := os.ReadDir(backupDir)
+	if len(entries) != 1 {
+		t.Errorf("expected 1 backup file, got %d", len(entries))
+	}
+
+	// New file should be gone
+	if _, err := os.Stat(newPath); !os.IsNotExist(err) {
+		t.Error("new file should have been moved/deleted")
+	}
+}
+
+func TestReplaceFileOldNotFound(t *testing.T) {
+	tmp := t.TempDir()
+	err := replaceFile(filepath.Join(tmp, "nonexistent.mkv"), filepath.Join(tmp, "new.mkv"), "")
+	if err == nil {
+		t.Error("expected error when old file doesn't exist")
+	}
+}
+
+func TestCopyFile(t *testing.T) {
+	tmp := t.TempDir()
+
+	src := filepath.Join(tmp, "source.txt")
+	dst := filepath.Join(tmp, "dest.txt")
+
+	content := []byte("hello world copy test")
+	os.WriteFile(src, content, 0o644)
+
+	err := copyFile(src, dst)
+	if err != nil {
+		t.Fatalf("copyFile: %v", err)
+	}
+
+	data, err := os.ReadFile(dst)
+	if err != nil {
+		t.Fatalf("read dest: %v", err)
+	}
+	if string(data) != string(content) {
+		t.Errorf("dest content = %q, want %q", string(data), string(content))
+	}
+}
+
+func TestCopyFileSrcNotFound(t *testing.T) {
+	tmp := t.TempDir()
+	err := copyFile(filepath.Join(tmp, "nope.txt"), filepath.Join(tmp, "out.txt"))
+	if err == nil {
+		t.Error("expected error when source doesn't exist")
+	}
+}
+
+func TestOrganizeNoDirs(t *testing.T) {
+	r := &Result{FilePath: "/tmp/file.mkv", FileName: "file.mkv"}
+	task := &Task{Title: "Movie"}
+
+	path, err := organize(r, task, OrganizeConfig{Enabled: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if path != "/tmp/file.mkv" {
+		t.Errorf("should return original path when no dirs configured, got %q", path)
+	}
+}
+
+func TestOrganizeNilResult(t *testing.T) {
+	task := &Task{Title: "Movie"}
+	path, err := organize(&Result{}, task, OrganizeConfig{Enabled: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if path != "" {
+		t.Errorf("expected empty path for empty result, got %q", path)
+	}
+}
+
+func TestOrganizeMovieDirectory(t *testing.T) {
+	tmp := t.TempDir()
+	srcDir := filepath.Join(tmp, "src", "MovieDir")
+	os.MkdirAll(srcDir, 0o755)
+	os.WriteFile(filepath.Join(srcDir, "movie.mkv"), []byte("data"), 0o644)
+
+	moviesDir := filepath.Join(tmp, "Movies")
+
+	r := &Result{FilePath: srcDir, FileName: "MovieDir"}
+	task := &Task{Title: "My Movie 2023"}
+
+	path, err := organize(r, task, OrganizeConfig{
+		Enabled:   true,
+		MoviesDir: moviesDir,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if path == srcDir {
+		t.Error("directory should have moved")
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Errorf("organized directory should exist at %s", path)
+	}
+}
+
+func TestOrganizeSeasonOnly(t *testing.T) {
+	tmp := t.TempDir()
+	srcFile := filepath.Join(tmp, "Show.S01.Complete.mkv")
+	os.WriteFile(srcFile, []byte("data"), 0o644)
+
+	tvDir := filepath.Join(tmp, "TV")
+
+	r := &Result{FilePath: srcFile, FileName: "Show.S01.Complete.mkv"}
+	task := &Task{Title: "Show S01"}
+
+	path, err := organize(r, task, OrganizeConfig{
+		Enabled:    true,
+		TVShowsDir: tvDir,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dir := filepath.Dir(path)
+	if filepath.Base(dir) != "Season 01" {
+		t.Errorf("expected Season 01 directory, got %q", filepath.Base(dir))
+	}
+}
+
+// --- Tests for server metadata organize path ---
+
+func intPtr(v int) *int { return &v }
+
+func TestOrganizeShowWithMetadata(t *testing.T) {
+	tmp := t.TempDir()
+	srcFile := filepath.Join(tmp, "Frieren.Beyond.Journeys.End.S01E03.1080p.WEB-DL.mkv")
+	os.WriteFile(srcFile, []byte("data"), 0o644)
+
+	tvDir := filepath.Join(tmp, "TV Shows")
+
+	r := &Result{FilePath: srcFile, FileName: "Frieren.Beyond.Journeys.End.S01E03.1080p.WEB-DL.mkv"}
+	task := &Task{
+		Title:        "Frieren.Beyond.Journeys.End.S01E03.1080p.WEB-DL",
+		ContentType:  "show",
+		ContentTitle: "Frieren: Beyond Journey's End",
+		Season:       intPtr(1),
+		Episode:      intPtr(3),
+	}
+
+	path, err := organize(r, task, OrganizeConfig{
+		Enabled:    true,
+		TVShowsDir: tvDir,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Should be: TV Shows/Frieren - Beyond Journey's End/Season 01/Frieren - Beyond Journey's End - S01E03.mkv
+	dir := filepath.Dir(path)
+	if filepath.Base(dir) != "Season 01" {
+		t.Errorf("expected Season 01 directory, got %q", filepath.Base(dir))
+	}
+	showDir := filepath.Dir(dir)
+	if filepath.Base(showDir) != "Frieren - Beyond Journey's End" {
+		t.Errorf("expected show dir 'Frieren - Beyond Journey's End', got %q", filepath.Base(showDir))
+	}
+	// Filename should be clean
+	base := filepath.Base(path)
+	if base != "Frieren - Beyond Journey's End - S01E03.mkv" {
+		t.Errorf("filename = %q, want 'Frieren - Beyond Journey's End - S01E03.mkv'", base)
+	}
+}
+
+func TestOrganizeCollectionMovieWithMetadata(t *testing.T) {
+	tmp := t.TempDir()
+	srcFile := filepath.Join(tmp, "Knives.Out.2019.1080p.BluRay.mkv")
+	os.WriteFile(srcFile, []byte("data"), 0o644)
+
+	moviesDir := filepath.Join(tmp, "Movies")
+
+	r := &Result{FilePath: srcFile, FileName: "Knives.Out.2019.1080p.BluRay.mkv"}
+	task := &Task{
+		Title:          "Knives.Out.2019.1080p.BluRay",
+		ContentType:    "movie",
+		ContentTitle:   "Knives Out",
+		CollectionName: "Knives Out Collection",
+	}
+
+	path, err := organize(r, task, OrganizeConfig{
+		Enabled:   true,
+		MoviesDir: moviesDir,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Should be: Movies/Knives Out Collection/Knives Out (2019)/Knives Out (2019).mkv
+	movieDir := filepath.Dir(path)
+	if filepath.Base(movieDir) != "Knives Out (2019)" {
+		t.Errorf("expected movie dir 'Knives Out (2019)', got %q", filepath.Base(movieDir))
+	}
+	collDir := filepath.Dir(movieDir)
+	if filepath.Base(collDir) != "Knives Out Collection" {
+		t.Errorf("expected collection dir 'Knives Out Collection', got %q", filepath.Base(collDir))
+	}
+	base := filepath.Base(path)
+	if base != "Knives Out (2019).mkv" {
+		t.Errorf("filename = %q, want 'Knives Out (2019).mkv'", base)
+	}
+}
+
+func TestOrganizeMovieWithMetadata(t *testing.T) {
+	tmp := t.TempDir()
+	srcFile := filepath.Join(tmp, "Oppenheimer.2023.2160p.UHD.BluRay.mkv")
+	os.WriteFile(srcFile, []byte("data"), 0o644)
+
+	moviesDir := filepath.Join(tmp, "Movies")
+
+	r := &Result{FilePath: srcFile, FileName: "Oppenheimer.2023.2160p.UHD.BluRay.mkv"}
+	task := &Task{
+		Title:        "Oppenheimer.2023.2160p.UHD.BluRay",
+		ContentType:  "movie",
+		ContentTitle: "Oppenheimer",
+	}
+
+	path, err := organize(r, task, OrganizeConfig{
+		Enabled:   true,
+		MoviesDir: moviesDir,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Should be: Movies/Oppenheimer (2023)/Oppenheimer (2023).mkv
+	movieDir := filepath.Dir(path)
+	if filepath.Base(movieDir) != "Oppenheimer (2023)" {
+		t.Errorf("expected movie dir 'Oppenheimer (2023)', got %q", filepath.Base(movieDir))
+	}
+	base := filepath.Base(path)
+	if base != "Oppenheimer (2023).mkv" {
+		t.Errorf("filename = %q, want 'Oppenheimer (2023).mkv'", base)
+	}
+}
+
+func TestOrganizeMultipleEpisodesSameFolder(t *testing.T) {
+	tmp := t.TempDir()
+	tvDir := filepath.Join(tmp, "TV Shows")
+
+	// Simulate two episodes of the same show
+	for _, ep := range []int{1, 2} {
+		srcFile := filepath.Join(tmp, filepath.Base(t.TempDir())+".mkv")
+		os.WriteFile(srcFile, []byte("data"), 0o644)
+
+		r := &Result{FilePath: srcFile, FileName: filepath.Base(srcFile)}
+		task := &Task{
+			Title:        "Frieren.S01E0" + string(rune('0'+ep)) + ".1080p",
+			ContentType:  "show",
+			ContentTitle: "Frieren",
+			Season:       intPtr(1),
+			Episode:      intPtr(ep),
+		}
+
+		_, err := organize(r, task, OrganizeConfig{
+			Enabled:    true,
+			TVShowsDir: tvDir,
+		})
+		if err != nil {
+			t.Fatalf("episode %d: %v", ep, err)
+		}
+	}
+
+	// Both episodes should be in the same directory
+	seasonDir := filepath.Join(tvDir, "Frieren", "Season 01")
+	entries, err := os.ReadDir(seasonDir)
+	if err != nil {
+		t.Fatalf("read season dir: %v", err)
+	}
+	if len(entries) != 2 {
+		t.Errorf("expected 2 files in Season 01, got %d", len(entries))
+	}
+}
+
+func TestOrganizeCleanupSourceDir(t *testing.T) {
+	tmp := t.TempDir()
+	// Simulate: outputDir/TorrentName/video.mkv + junk files
+	outputDir := filepath.Join(tmp, "downloads")
+	torrentDir := filepath.Join(outputDir, "Frieren.S01E03.1080p.WEB-DL")
+	os.MkdirAll(torrentDir, 0o755)
+
+	srcFile := filepath.Join(torrentDir, "Frieren.S01E03.1080p.WEB-DL.mkv")
+	os.WriteFile(srcFile, []byte("video"), 0o644)
+	os.WriteFile(filepath.Join(torrentDir, "info.nfo"), []byte("nfo"), 0o644)
+	os.WriteFile(filepath.Join(torrentDir, "readme.txt"), []byte("txt"), 0o644)
+	os.WriteFile(filepath.Join(torrentDir, "website.url"), []byte("url"), 0o644)
+
+	tvDir := filepath.Join(tmp, "TV Shows")
+
+	r := &Result{FilePath: srcFile, FileName: "Frieren.S01E03.1080p.WEB-DL.mkv"}
+	task := &Task{
+		Title:        "Frieren.S01E03.1080p.WEB-DL",
+		ContentType:  "show",
+		ContentTitle: "Frieren",
+		Season:       intPtr(1),
+		Episode:      intPtr(3),
+	}
+
+	path, err := organize(r, task, OrganizeConfig{
+		Enabled:    true,
+		TVShowsDir: tvDir,
+		OutputDir:  outputDir,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Video should be in organized location
+	if _, err := os.Stat(path); err != nil {
+		t.Errorf("organized file should exist at %s", path)
+	}
+
+	// Source torrent directory should be gone (only had junk left)
+	if _, err := os.Stat(torrentDir); !os.IsNotExist(err) {
+		t.Errorf("torrent dir should have been cleaned up: %s", torrentDir)
+	}
+
+	// OutputDir itself should still exist
+	if _, err := os.Stat(outputDir); err != nil {
+		t.Errorf("outputDir should still exist")
+	}
+}
+
+func TestOrganizeNoCleanupWhenVideoRemains(t *testing.T) {
+	tmp := t.TempDir()
+	outputDir := filepath.Join(tmp, "downloads")
+	torrentDir := filepath.Join(outputDir, "MultiVideoTorrent")
+	os.MkdirAll(torrentDir, 0o755)
+
+	srcFile := filepath.Join(torrentDir, "episode1.mkv")
+	os.WriteFile(srcFile, []byte("video1"), 0o644)
+	// Another video file remains
+	os.WriteFile(filepath.Join(torrentDir, "episode2.mkv"), []byte("video2"), 0o644)
+
+	tvDir := filepath.Join(tmp, "TV Shows")
+
+	r := &Result{FilePath: srcFile, FileName: "episode1.mkv"}
+	task := &Task{
+		Title:        "Show S01E01",
+		ContentType:  "show",
+		ContentTitle: "Show",
+		Season:       intPtr(1),
+		Episode:      intPtr(1),
+	}
+
+	_, err := organize(r, task, OrganizeConfig{
+		Enabled:    true,
+		TVShowsDir: tvDir,
+		OutputDir:  outputDir,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Torrent dir should still exist because episode2.mkv is still there
+	if _, err := os.Stat(torrentDir); err != nil {
+		t.Errorf("torrent dir should NOT be cleaned up when video files remain")
+	}
+}
+
+func TestSanitizePath(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"Normal Title", "Normal Title"},
+		{"Title: Subtitle", "Title - Subtitle"},
+		{"Title/Subtitle", "Title-Subtitle"},
+		{"What?", "What"},
+		{"A*B<C>D|E", "ABCD-E"},
+		{"  Spaces  ", "Spaces"},
+		{"Trailing...", "Trailing"},
+		{"", "Unknown"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got := sanitizePath(tt.input)
+			if got != tt.want {
+				t.Errorf("sanitizePath(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestResolveYear(t *testing.T) {
+	tests := []struct {
+		name string
+		task *Task
+		want string
+	}{
+		{"from ContentYear", &Task{ContentYear: intPtr(2023), Title: "Movie.2020.1080p"}, "2023"},
+		{"fallback to regex", &Task{Title: "Movie.2020.1080p"}, "2020"},
+		{"no year", &Task{Title: "Movie.1080p"}, ""},
+		{"zero year fallback", &Task{ContentYear: intPtr(0), Title: "Movie.2019.mkv"}, "2019"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := resolveYear(tt.task)
+			if got != tt.want {
+				t.Errorf("resolveYear() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsSubtitleFile(t *testing.T) {
+	for _, ext := range []string{".srt", ".sub", ".ass", ".ssa", ".vtt", ".idx"} {
+		if !isSubtitleFile("file" + ext) {
+			t.Errorf("expected %s to be subtitle", ext)
+		}
+	}
+	for _, ext := range []string{".mkv", ".txt", ".nfo", ".jpg"} {
+		if isSubtitleFile("file" + ext) {
+			t.Errorf("expected %s to NOT be subtitle", ext)
+		}
+	}
+}
+
+func TestMoveSubtitles(t *testing.T) {
+	tmp := t.TempDir()
+	srcDir := filepath.Join(tmp, "torrent")
+	destDir := filepath.Join(tmp, "dest")
+	os.MkdirAll(srcDir, 0o755)
+	os.MkdirAll(destDir, 0o755)
+
+	// Create video + subtitles in source
+	videoPath := filepath.Join(srcDir, "Movie.2023.1080p.mkv")
+	os.WriteFile(videoPath, []byte("video"), 0o644)
+	os.WriteFile(filepath.Join(srcDir, "Movie.2023.1080p.srt"), []byte("srt"), 0o644)
+	os.WriteFile(filepath.Join(srcDir, "Movie.2023.1080p.en.srt"), []byte("en srt"), 0o644)
+	os.WriteFile(filepath.Join(srcDir, "Other.srt"), []byte("other"), 0o644) // should NOT move
+
+	moveSubtitles(videoPath, destDir, "Oppenheimer (2023).mkv")
+
+	// Renamed subtitles should be in dest
+	if _, err := os.Stat(filepath.Join(destDir, "Oppenheimer (2023).srt")); err != nil {
+		t.Error("expected Oppenheimer (2023).srt in dest")
+	}
+	if _, err := os.Stat(filepath.Join(destDir, "Oppenheimer (2023).en.srt")); err != nil {
+		t.Error("expected Oppenheimer (2023).en.srt in dest")
+	}
+	// Other.srt should NOT have moved
+	if _, err := os.Stat(filepath.Join(srcDir, "Other.srt")); err != nil {
+		t.Error("Other.srt should remain in source")
+	}
+}
+
+func TestMoveSubtitlesNoRename(t *testing.T) {
+	tmp := t.TempDir()
+	srcDir := filepath.Join(tmp, "torrent")
+	destDir := filepath.Join(tmp, "dest")
+	os.MkdirAll(srcDir, 0o755)
+	os.MkdirAll(destDir, 0o755)
+
+	videoPath := filepath.Join(srcDir, "Movie.mkv")
+	os.WriteFile(videoPath, []byte("video"), 0o644)
+	os.WriteFile(filepath.Join(srcDir, "Movie.srt"), []byte("srt"), 0o644)
+
+	moveSubtitles(videoPath, destDir, "") // no rename
+
+	if _, err := os.Stat(filepath.Join(destDir, "Movie.srt")); err != nil {
+		t.Error("expected Movie.srt in dest (no rename)")
+	}
+}
+
+func TestOrganizeMovieWithContentYear(t *testing.T) {
+	tmp := t.TempDir()
+	srcFile := filepath.Join(tmp, "Oppenheimer.UHD.BluRay.mkv")
+	os.WriteFile(srcFile, []byte("data"), 0o644)
+
+	moviesDir := filepath.Join(tmp, "Movies")
+
+	r := &Result{FilePath: srcFile, FileName: "Oppenheimer.UHD.BluRay.mkv"}
+	task := &Task{
+		Title:        "Oppenheimer.UHD.BluRay", // no year in title!
+		ContentType:  "movie",
+		ContentTitle: "Oppenheimer",
+		ContentYear:  intPtr(2023),
+	}
+
+	path, err := organize(r, task, OrganizeConfig{
+		Enabled:   true,
+		MoviesDir: moviesDir,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Should use ContentYear even though title has no year
+	movieDir := filepath.Dir(path)
+	if filepath.Base(movieDir) != "Oppenheimer (2023)" {
+		t.Errorf("expected movie dir 'Oppenheimer (2023)', got %q", filepath.Base(movieDir))
+	}
+	base := filepath.Base(path)
+	if base != "Oppenheimer (2023).mkv" {
+		t.Errorf("filename = %q, want 'Oppenheimer (2023).mkv'", base)
+	}
+}
+
+func TestCleanTitleEdgeCases(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"", ""},
+		{"Simple Title", "Simple Title"},
+		{"Title (2023) 1080p BluRay", "Title"},
+		{"Title 720p HDTV", "Title"},
+		{"Title x264 HEVC", "Title"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got := cleanTitle(tt.input)
+			if got != tt.want {
+				t.Errorf("cleanTitle(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/internal/engine/probe.go b/internal/engine/probe.go
new file mode 100644
index 0000000..c29c81a
--- /dev/null
+++ b/internal/engine/probe.go
@@ -0,0 +1,186 @@
+package engine
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/torrentclaw/unarr/internal/library/mediainfo"
+)
+
+// StreamProbe summarises the codec / container shape of a file as it relates
+// to the HLS streaming pipeline. It tells the transcoder whether bytes can
+// be streamed as-is, just remuxed to fragmented MP4, or fully transcoded.
+type StreamProbe struct {
+	// VideoCodec lowercased — e.g. "h264", "hevc", "av1", "vp9", "mpeg4".
+	VideoCodec string
+	// AudioCodec lowercased — e.g. "aac", "ac3", "dts", "eac3", "opus".
+	// Reflects the default/first audio track for legacy single-track callers.
+	AudioCodec string
+	// Width / Height of the primary video stream.
+	Width  int
+	Height int
+	// BitDepth — 8, 10 or 12. 0 if unknown.
+	BitDepth int
+	// HDR signalling string ("HDR10" / "DV" / "HLG" / etc, or "" for SDR).
+	HDR string
+	// DurationSec is the file length, used to sanity-check seek targets.
+	DurationSec float64
+	// Container is the file extension lowercased (".mp4", ".mkv", ".avi").
+	Container string
+	// AudioTracks lists every audio stream in source order. Index in this
+	// slice == ffmpeg `-map 0:a:N` index (where N starts at 0).
+	AudioTracks []ProbeAudioTrack
+	// SubtitleTracks lists every subtitle stream in source order. Index in
+	// this slice == ffmpeg `-map 0:s:N` index.
+	SubtitleTracks []ProbeSubtitleTrack
+}
+
+// ProbeAudioTrack is a slimmed AudioTrack view tied to ffmpeg stream index.
+type ProbeAudioTrack struct {
+	Index    int    // 0-based audio stream index (ffmpeg -map 0:a:Index)
+	Lang     string // ISO 639-1
+	Codec    string // lowercased
+	Channels int
+	Title    string
+	Default  bool
+}
+
+// ProbeSubtitleTrack is a slimmed SubtitleTrack view tied to ffmpeg stream index.
+// Codec discriminates text (srt/ass/webvtt → extract to WebVTT) vs bitmap
+// (pgs/dvbsub → require burn-in).
+type ProbeSubtitleTrack struct {
+	Index  int    // 0-based subtitle stream index (ffmpeg -map 0:s:Index)
+	Lang   string // ISO 639-1
+	Codec  string // lowercased — "subrip", "ass", "webvtt", "hdmv_pgs_subtitle", ...
+	Title  string
+	Forced bool
+}
+
+// IsTextSubtitle reports whether a subtitle codec can be extracted to WebVTT
+// without re-rendering. Bitmap subs (PGS, DVB) need burn-in.
+func (s ProbeSubtitleTrack) IsTextSubtitle() bool {
+	switch s.Codec {
+	case "subrip", "srt", "ass", "ssa", "webvtt", "mov_text":
+		return true
+	}
+	return false
+}
+
+// TranscodeAction tells the streaming pipeline how to feed the file to
+// the browser <video> element. The decision matrix is documented in the
+// project plan (Fase 2.5 — Transcoding on-the-fly).
+type TranscodeAction string
+
+const (
+	// ActionPassthrough — file is already browser-playable as-is. Stream the
+	// raw bytes via ReadAt; no ffmpeg involved.
+	ActionPassthrough TranscodeAction = "passthrough"
+	// ActionRemux — codecs are browser-compatible but the container or moov
+	// placement is not. Run ffmpeg with `-c copy -movflags frag_keyframe`.
+	ActionRemux TranscodeAction = "remux"
+	// ActionRemuxAudio — video is fine but audio needs a re-encode (AC3/DTS
+	// → AAC). `-c:v copy -c:a aac`.
+	ActionRemuxAudio TranscodeAction = "remux-audio"
+	// ActionTranscodeVideo — full re-encode. Used for HEVC/AV1 and any
+	// 10-bit content if the browser refuses the codec.
+	ActionTranscodeVideo TranscodeAction = "transcode-video"
+)
+
+// ProbeFile runs ffprobe and returns a StreamProbe view of the file.
+//
+// Result is memoised by (path, mtime, size) for probeCacheTTL — repeat plays
+// of the same file at the same quality (the HLS cache HIT path) skip ffprobe
+// entirely. ffprobe on a 50 GB MKV can cost 1-3 s; first-segment latency
+// shrinks by the same amount on the second play.
+func ProbeFile(ctx context.Context, ffprobePath, filePath string) (*StreamProbe, error) {
+	if cached, ok := lookupProbeCache(filePath); ok {
+		return cached, nil
+	}
+	mi, err := mediainfo.ExtractMediaInfo(ctx, ffprobePath, filePath)
+	if err != nil {
+		return nil, fmt.Errorf("probe: %w", err)
+	}
+	probe := &StreamProbe{Container: lowerExt(filePath)}
+	if mi.Video != nil {
+		probe.VideoCodec = strings.ToLower(mi.Video.Codec)
+		probe.Width = mi.Video.Width
+		probe.Height = mi.Video.Height
+		probe.BitDepth = mi.Video.BitDepth
+		probe.HDR = mi.Video.HDR
+		probe.DurationSec = mi.Video.Duration
+	}
+	if len(mi.Audio) > 0 {
+		// Default to the first track marked "Default", else the first track.
+		picked := mi.Audio[0]
+		for _, a := range mi.Audio {
+			if a.Default {
+				picked = a
+				break
+			}
+		}
+		probe.AudioCodec = strings.ToLower(picked.Codec)
+		probe.AudioTracks = make([]ProbeAudioTrack, 0, len(mi.Audio))
+		for i, a := range mi.Audio {
+			probe.AudioTracks = append(probe.AudioTracks, ProbeAudioTrack{
+				Index:    i,
+				Lang:     a.Lang,
+				Codec:    strings.ToLower(a.Codec),
+				Channels: a.Channels,
+				Title:    a.Title,
+				Default:  a.Default,
+			})
+		}
+	}
+	if len(mi.Subtitles) > 0 {
+		probe.SubtitleTracks = make([]ProbeSubtitleTrack, 0, len(mi.Subtitles))
+		for i, s := range mi.Subtitles {
+			probe.SubtitleTracks = append(probe.SubtitleTracks, ProbeSubtitleTrack{
+				Index:  i,
+				Lang:   s.Lang,
+				Codec:  strings.ToLower(s.Codec),
+				Title:  s.Title,
+				Forced: s.Forced,
+			})
+		}
+	}
+	storeProbeCache(filePath, probe)
+	return probe, nil
+}
+
+// DecideAction maps a probe to the transcoding action the streaming pipeline
+// should take. Browsers consume MP4/h264+AAC natively; everything else needs
+// some level of re-shaping.
+func DecideAction(p *StreamProbe) TranscodeAction {
+	if p == nil {
+		return ActionPassthrough
+	}
+	video := p.VideoCodec
+	audio := p.AudioCodec
+	container := p.Container
+
+	// 10-bit / HDR is a hard no for browser playback even if h264 — needs SW transcode.
+	tenBitOrHDR := p.BitDepth >= 10 || p.HDR != ""
+
+	if !tenBitOrHDR && video == "h264" {
+		if audio == "aac" {
+			if container == ".mp4" {
+				return ActionPassthrough
+			}
+			return ActionRemux
+		}
+		// Audio incompatible (AC3/DTS/TrueHD/EAC3) → remux video, transcode audio.
+		return ActionRemuxAudio
+	}
+
+	// HEVC / AV1 / VP9 / 10-bit / unknown → full re-encode video.
+	return ActionTranscodeVideo
+}
+
+func lowerExt(filePath string) string {
+	dot := strings.LastIndex(filePath, ".")
+	if dot < 0 {
+		return ""
+	}
+	return strings.ToLower(filePath[dot:])
+}
diff --git a/internal/engine/probe_cache.go b/internal/engine/probe_cache.go
new file mode 100644
index 0000000..fcc7dec
--- /dev/null
+++ b/internal/engine/probe_cache.go
@@ -0,0 +1,141 @@
+package engine
+
+import (
+	"os"
+	"sync"
+	"time"
+)
+
+// probeCacheTTL is how long a cached probe stays usable. The cache key
+// already incorporates mtime + size, so the TTL is a defense against
+// runaway memory growth from stale paths, not a freshness guarantee — a
+// rename + recreate at the same inode (rare) would still be caught by the
+// mtime delta.
+const probeCacheTTL = 30 * time.Minute
+
+// probeCacheJanitorInterval is how often the background sweeper wakes to
+// drop expired entries. Lookup-time eviction handles hot paths, but a
+// user who browses 5k files and then stops would leak entries until each
+// is individually re-touched. 5 min ≈ 6 sweeps per TTL window — enough
+// to keep memory bounded without burning CPU.
+const probeCacheJanitorInterval = 5 * time.Minute
+
+type probeCacheEntry struct {
+	probe   *StreamProbe
+	expires time.Time
+}
+
+type probeCacheKey struct {
+	path  string
+	mtime int64 // ModTime().UnixNano()
+	size  int64
+}
+
+var (
+	probeCacheMu      sync.RWMutex
+	probeCache        = make(map[probeCacheKey]probeCacheEntry)
+	probeCacheJanitor sync.Once
+)
+
+// startProbeCacheJanitor launches the background sweeper exactly once per
+// process. Lazy — fired on first storeProbeCache. Drops expired entries
+// every probeCacheJanitorInterval. Idempotent (sync.Once).
+func startProbeCacheJanitor() {
+	probeCacheJanitor.Do(func() {
+		go func() {
+			ticker := time.NewTicker(probeCacheJanitorInterval)
+			defer ticker.Stop()
+			for range ticker.C {
+				sweepProbeCache(time.Now())
+			}
+		}()
+	})
+}
+
+// sweepProbeCache removes every entry whose expiry is at or before `now`.
+// Exposed for tests; production code calls it indirectly via the janitor
+// goroutine.
+func sweepProbeCache(now time.Time) int {
+	probeCacheMu.Lock()
+	defer probeCacheMu.Unlock()
+	removed := 0
+	for k, e := range probeCache {
+		if !now.Before(e.expires) {
+			delete(probeCache, k)
+			removed++
+		}
+	}
+	return removed
+}
+
+// lookupProbeCache returns the cached StreamProbe for the given path if its
+// mtime + size still match the value recorded at insert time, AND the cache
+// entry hasn't expired. Any stat failure / mismatch returns (nil, false) so
+// the caller falls through to a fresh ffprobe run.
+func lookupProbeCache(path string) (*StreamProbe, bool) {
+	fi, err := os.Stat(path)
+	if err != nil {
+		return nil, false
+	}
+	key := probeCacheKey{
+		path:  path,
+		mtime: fi.ModTime().UnixNano(),
+		size:  fi.Size(),
+	}
+	probeCacheMu.RLock()
+	entry, ok := probeCache[key]
+	probeCacheMu.RUnlock()
+	if !ok {
+		return nil, false
+	}
+	if time.Now().After(entry.expires) {
+		// Re-check under the write lock so a concurrent re-insert (same key,
+		// fresh expiry) isn't accidentally evicted.
+		probeCacheMu.Lock()
+		if cur, stillThere := probeCache[key]; stillThere && time.Now().After(cur.expires) {
+			delete(probeCache, key)
+		}
+		probeCacheMu.Unlock()
+		return nil, false
+	}
+	return entry.probe, true
+}
+
+// storeProbeCache stashes a fresh probe result under the (path, mtime, size)
+// key. A subsequent ffprobe-skipping HIT requires the file to still have the
+// same mtime + size — anything else (re-encoded, renamed+recreated at the
+// same path, truncated) misses and triggers a re-probe.
+func storeProbeCache(path string, probe *StreamProbe) {
+	fi, err := os.Stat(path)
+	if err != nil {
+		return
+	}
+	key := probeCacheKey{
+		path:  path,
+		mtime: fi.ModTime().UnixNano(),
+		size:  fi.Size(),
+	}
+	probeCacheMu.Lock()
+	probeCache[key] = probeCacheEntry{
+		probe:   probe,
+		expires: time.Now().Add(probeCacheTTL),
+	}
+	probeCacheMu.Unlock()
+	// Lazy janitor — fires once per process. No-op after first call.
+	startProbeCacheJanitor()
+}
+
+// ResetProbeCache clears the in-memory probe cache. Test-only.
+func ResetProbeCache() {
+	probeCacheMu.Lock()
+	probeCache = make(map[probeCacheKey]probeCacheEntry)
+	probeCacheMu.Unlock()
+}
+
+// ProbeCacheSize returns the number of entries currently cached. Exposed
+// for diagnostics + tests.
+func ProbeCacheSize() int {
+	probeCacheMu.RLock()
+	defer probeCacheMu.RUnlock()
+	return len(probeCache)
+}
diff --git a/internal/engine/probe_cache_test.go b/internal/engine/probe_cache_test.go
new file mode 100644
index 0000000..76c79da
--- /dev/null
+++ b/internal/engine/probe_cache_test.go
@@ -0,0 +1,202 @@
+package engine
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestProbeCache_LookupMissNonexistent(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	if _, ok := lookupProbeCache("/path/that/does/not/exist"); ok {
+		t.Fatal("expected MISS for non-existent path")
+	}
+}
+
+func TestProbeCache_StoreThenLookupHit(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("fake content"), 0o644); err != nil {
+		t.Fatalf("write tmp file: %v", err)
+	}
+
+	probe := &StreamProbe{VideoCodec: "h264", Width: 1920, Height: 1080, DurationSec: 5400}
+	storeProbeCache(path, probe)
+
+	got, ok := lookupProbeCache(path)
+	if !ok {
+		t.Fatal("expected HIT after store")
+	}
+	if got != probe {
+		t.Fatalf("expected pointer-identical probe; got different")
+	}
+}
+
+func TestProbeCache_MtimeChangeInvalidates(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("original"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	probe := &StreamProbe{VideoCodec: "h264", DurationSec: 100}
+	storeProbeCache(path, probe)
+
+	// Force mtime change. WriteFile doesn't guarantee a different mtime if
+	// the filesystem timestamp resolution is coarse, so set it explicitly
+	// to a value 1 hour in the future.
+	future := time.Now().Add(1 * time.Hour)
+	if err := os.Chtimes(path, future, future); err != nil {
+		t.Fatalf("chtimes: %v", err)
+	}
+
+	if _, ok := lookupProbeCache(path); ok {
+		t.Fatal("expected MISS after mtime change")
+	}
+}
+
+func TestProbeCache_SizeChangeInvalidates(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("aaaaa"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	originalMtime := time.Now().Add(-1 * time.Hour) // stable, in the past
+	if err := os.Chtimes(path, originalMtime, originalMtime); err != nil {
+		t.Fatalf("chtimes original: %v", err)
+	}
+
+	probe := &StreamProbe{VideoCodec: "h264", DurationSec: 100}
+	storeProbeCache(path, probe)
+
+	// Truncate to a different size, then reset mtime to the original so
+	// only `size` differs between store and lookup keys — isolates the
+	// size-check path. Without the Chtimes, WriteFile bumps mtime and the
+	// test would pass via mtime invalidation regardless of size logic.
+	if err := os.WriteFile(path, []byte("a"), 0o644); err != nil {
+		t.Fatalf("rewrite: %v", err)
+	}
+	if err := os.Chtimes(path, originalMtime, originalMtime); err != nil {
+		t.Fatalf("chtimes restore: %v", err)
+	}
+
+	if _, ok := lookupProbeCache(path); ok {
+		t.Fatal("expected MISS after size change")
+	}
+}
+
+func TestProbeCache_ExpiryDropsEntry(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("content"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	// Stash an entry whose expires is already in the past — simulates TTL
+	// having elapsed without sleeping for 30 min.
+	fi, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	key := probeCacheKey{path: path, mtime: fi.ModTime().UnixNano(), size: fi.Size()}
+	probeCacheMu.Lock()
+	probeCache[key] = probeCacheEntry{
+		probe:   &StreamProbe{VideoCodec: "h264"},
+		expires: time.Now().Add(-1 * time.Minute),
+	}
+	probeCacheMu.Unlock()
+
+	if _, ok := lookupProbeCache(path); ok {
+		t.Fatal("expected MISS for expired entry")
+	}
+	// Side-effect: lookup should have evicted the stale entry.
+	if ProbeCacheSize() != 0 {
+		t.Fatalf("expected cache size 0 after expiry eviction; got %d", ProbeCacheSize())
+	}
+}
+
+func TestProbeCache_ResetClears(t *testing.T) {
+	ResetProbeCache()
+
+	dir := t.TempDir()
+	path := filepath.Join(dir, "movie.mkv")
+	if err := os.WriteFile(path, []byte("x"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	storeProbeCache(path, &StreamProbe{VideoCodec: "h264"})
+	if ProbeCacheSize() != 1 {
+		t.Fatalf("expected size 1 after store; got %d", ProbeCacheSize())
+	}
+
+	ResetProbeCache()
+	if ProbeCacheSize() != 0 {
+		t.Fatalf("expected size 0 after reset; got %d", ProbeCacheSize())
+	}
+}
+
+func TestProbeCache_StoreNonexistentNoOp(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	// Store on a non-existent path should silently do nothing (stat fails),
+	// not panic, and not poison the cache with a zero key.
+	storeProbeCache("/nope/never/exists.mkv", &StreamProbe{VideoCodec: "h264"})
+	if ProbeCacheSize() != 0 {
+		t.Fatalf("expected 0 entries; got %d", ProbeCacheSize())
+	}
+}
+
+func TestProbeCache_SweepDropsExpired(t *testing.T) {
+	ResetProbeCache()
+	t.Cleanup(ResetProbeCache)
+
+	dir := t.TempDir()
+	// Two entries: one expired, one fresh.
+	expiredPath := filepath.Join(dir, "old.mkv")
+	freshPath := filepath.Join(dir, "new.mkv")
+	if err := os.WriteFile(expiredPath, []byte("a"), 0o644); err != nil {
+		t.Fatalf("write expired: %v", err)
+	}
+	if err := os.WriteFile(freshPath, []byte("b"), 0o644); err != nil {
+		t.Fatalf("write fresh: %v", err)
+	}
+
+	now := time.Now()
+	fiExp, _ := os.Stat(expiredPath)
+	fiFresh, _ := os.Stat(freshPath)
+
+	probeCacheMu.Lock()
+	probeCache[probeCacheKey{path: expiredPath, mtime: fiExp.ModTime().UnixNano(), size: fiExp.Size()}] = probeCacheEntry{
+		probe:   &StreamProbe{VideoCodec: "h264"},
+		expires: now.Add(-1 * time.Minute), // expired
+	}
+	probeCache[probeCacheKey{path: freshPath, mtime: fiFresh.ModTime().UnixNano(), size: fiFresh.Size()}] = probeCacheEntry{
+		probe:   &StreamProbe{VideoCodec: "h264"},
+		expires: now.Add(10 * time.Minute), // fresh
+	}
+	probeCacheMu.Unlock()
+
+	removed := sweepProbeCache(now)
+	if removed != 1 {
+		t.Fatalf("expected 1 expired entry removed; got %d", removed)
+	}
+	if ProbeCacheSize() != 1 {
+		t.Fatalf("expected 1 fresh entry kept; got %d", ProbeCacheSize())
+	}
+}
diff --git a/internal/engine/probe_test.go b/internal/engine/probe_test.go
new file mode 100644
index 0000000..cf5d10f
--- /dev/null
+++ b/internal/engine/probe_test.go
@@ -0,0 +1,96 @@
+package engine
+
+import "testing"
+
+func TestDecideAction(t *testing.T) {
+	cases := []struct {
+		name string
+		p    StreamProbe
+		want TranscodeAction
+	}{
+		{
+			name: "MP4 + h264 + AAC = passthrough",
+			p:    StreamProbe{VideoCodec: "h264", AudioCodec: "aac", Container: ".mp4"},
+			want: ActionPassthrough,
+		},
+		{
+			name: "MKV + h264 + AAC = remux",
+			p:    StreamProbe{VideoCodec: "h264", AudioCodec: "aac", Container: ".mkv"},
+			want: ActionRemux,
+		},
+		{
+			name: "MKV + h264 + AC3 = remux audio",
+			p:    StreamProbe{VideoCodec: "h264", AudioCodec: "ac3", Container: ".mkv"},
+			want: ActionRemuxAudio,
+		},
+		{
+			name: "MP4 + h264 + EAC3 = remux audio",
+			p:    StreamProbe{VideoCodec: "h264", AudioCodec: "eac3", Container: ".mp4"},
+			want: ActionRemuxAudio,
+		},
+		{
+			name: "MKV + HEVC = transcode video",
+			p:    StreamProbe{VideoCodec: "hevc", AudioCodec: "aac", Container: ".mkv"},
+			want: ActionTranscodeVideo,
+		},
+		{
+			name: "MP4 + AV1 = transcode video",
+			p:    StreamProbe{VideoCodec: "av1", AudioCodec: "aac", Container: ".mp4"},
+			want: ActionTranscodeVideo,
+		},
+		{
+			name: "h264 10-bit = transcode video (browser refuses)",
+			p:    StreamProbe{VideoCodec: "h264", AudioCodec: "aac", BitDepth: 10, Container: ".mp4"},
+			want: ActionTranscodeVideo,
+		},
+		{
+			name: "h264 + HDR10 = transcode video",
+			p:    StreamProbe{VideoCodec: "h264", AudioCodec: "aac", HDR: "HDR10", Container: ".mp4"},
+			want: ActionTranscodeVideo,
+		},
+		{
+			name: "AVI + h264 + AAC = remux",
+			p:    StreamProbe{VideoCodec: "h264", AudioCodec: "aac", Container: ".avi"},
+			want: ActionRemux,
+		},
+		{
+			name: "Unknown codec = transcode video",
+			p:    StreamProbe{VideoCodec: "mpeg4", AudioCodec: "mp3", Container: ".avi"},
+			want: ActionTranscodeVideo,
+		},
+		{
+			name: "Empty probe falls through to transcode (unknown codec)",
+			p:    StreamProbe{},
+			want: ActionTranscodeVideo,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := DecideAction(&tc.p)
+			if got != tc.want {
+				t.Errorf("got %s, want %s", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestDecideActionNil(t *testing.T) {
+	if DecideAction(nil) != ActionPassthrough {
+		t.Error("nil probe should default passthrough")
+	}
+}
+
+func TestLowerExt(t *testing.T) {
+	cases := map[string]string{
+		"foo.MP4":              ".mp4",
+		"path/to/movie.MKV":    ".mkv",
+		"weird.name.with.dots": ".dots",
+		"":                     "",
+		"noext":                "",
+	}
+	for in, want := range cases {
+		if got := lowerExt(in); got != want {
+			t.Errorf("lowerExt(%q) = %q want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/engine/progress.go b/internal/engine/progress.go
index e2284fc..eba8814 100644
--- a/internal/engine/progress.go
+++ b/internal/engine/progress.go
@@ -13,13 +13,11 @@ import (
 type ActionFunc func(taskID string)
 
 // StatusReporter is the interface used by ProgressReporter to send progress updates.
-// Both *agent.Client and agent.Transport implement this via their ReportStatus/SendProgress methods.
 type StatusReporter interface {
 	ReportStatus(ctx context.Context, update agent.StatusUpdate) (*agent.StatusResponse, error)
 }
 
 // BatchStatusReporter extends StatusReporter with batch support.
-// Transports that implement this send all updates in a single request.
 type BatchStatusReporter interface {
 	StatusReporter
 	BatchReportStatus(ctx context.Context, updates []agent.StatusUpdate) (*agent.BatchStatusResponse, error)
@@ -39,39 +37,24 @@ type ProgressReporter struct {
 	onPause           ActionFunc
 	onDeleteFiles     ActionFunc
 	onStreamRequested ActionFunc
+	onWatchingChanged func(watching bool)
 
-	mu     sync.Mutex
-	latest map[string]*Task // taskID -> task with latest progress
+	mu           sync.Mutex
+	latest       map[string]*Task      // taskID -> task with latest progress
+	lastReported map[string]TaskStatus // taskID -> last status sent to API
+	lastCheckAt  time.Time             // last time we reported for control-signal polling
 }
 
 // NewProgressReporter creates a reporter that flushes every interval.
-// Accepts *agent.Client directly (backwards compatible).
 func NewProgressReporter(ac *agent.Client, interval time.Duration) *ProgressReporter {
 	return &ProgressReporter{
-		reporter: ac,
-		interval: interval,
-		latest:   make(map[string]*Task),
+		reporter:     ac,
+		interval:     interval,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
 	}
 }
 
-// NewProgressReporterWithTransport creates a reporter using a Transport.
-func NewProgressReporterWithTransport(t agent.Transport, interval time.Duration) *ProgressReporter {
-	return &ProgressReporter{
-		reporter: &transportStatusAdapter{t: t},
-		interval: interval,
-		latest:   make(map[string]*Task),
-	}
-}
-
-// transportStatusAdapter adapts agent.Transport to StatusReporter.
-type transportStatusAdapter struct {
-	t agent.Transport
-}
-
-func (a *transportStatusAdapter) ReportStatus(ctx context.Context, update agent.StatusUpdate) (*agent.StatusResponse, error) {
-	return a.t.SendProgress(ctx, update)
-}
-
 // SetCancelHandler sets the callback invoked when the server says a task is cancelled.
 func (r *ProgressReporter) SetCancelHandler(fn ActionFunc) { r.onCancel = fn }
 
@@ -87,6 +70,12 @@ func (r *ProgressReporter) SetStreamRequestedHandler(fn ActionFunc) { r.onStream
 // SetWatchingFunc sets the function that checks if someone is viewing downloads.
 func (r *ProgressReporter) SetWatchingFunc(fn WatchingFunc) { r.isWatching = fn }
 
+// SetWatchingChangedHandler sets a callback invoked when the server's watching flag changes.
+// This allows the daemon to update its Watching state from status responses (not just heartbeats).
+func (r *ProgressReporter) SetWatchingChangedHandler(fn func(watching bool)) {
+	r.onWatchingChanged = fn
+}
+
 // Track registers a task for progress tracking.
 func (r *ProgressReporter) Track(task *Task) {
 	r.mu.Lock()
@@ -99,6 +88,7 @@ func (r *ProgressReporter) Untrack(taskID string) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	delete(r.latest, taskID)
+	delete(r.lastReported, taskID)
 }
 
 // Run starts the periodic flush loop. Blocks until ctx is cancelled.
@@ -123,23 +113,38 @@ func (r *ProgressReporter) flush(ctx context.Context) {
 	for _, t := range r.latest {
 		tasks = append(tasks, t)
 	}
+	// Snapshot lastReported under the same lock
+	lastReported := make(map[string]TaskStatus, len(r.lastReported))
+	for k, v := range r.lastReported {
+		lastReported[k] = v
+	}
 	r.mu.Unlock()
 
-	// When nobody is watching, only report final states (completed/failed).
-	// This saves ~99% of API requests when the user isn't on the downloads page.
+	// When nobody is watching, only report final states, status transitions,
+	// and periodic check-ins (every 30s) so we still receive control signals
+	// (cancel/pause) from the server.
 	watching := r.isWatching == nil || r.isWatching()
+	controlCheckDue := time.Since(r.lastCheckAt) >= 30*time.Second
 
 	var reportable []*Task
 	for _, task := range tasks {
 		status := task.GetStatus()
 		isFinal := status == StatusCompleted || status == StatusFailed
 		isActive := status == StatusDownloading || status == StatusVerifying ||
-			status == StatusOrganizing || status == StatusSeeding
-		if isFinal || (watching && isActive) {
+			status == StatusOrganizing || status == StatusSeeding ||
+			status == StatusResolving
+		// Always report status transitions so the DB reflects the current state.
+		prev := lastReported[task.ID]
+		isTransition := prev == "" || prev != status
+		if isFinal || isTransition || (watching && isActive) || (controlCheckDue && isActive) {
 			reportable = append(reportable, task)
 		}
 	}
 
+	if controlCheckDue {
+		r.lastCheckAt = time.Now()
+	}
+
 	if len(reportable) == 0 {
 		return
 	}
@@ -152,20 +157,27 @@ func (r *ProgressReporter) flush(ctx context.Context) {
 
 	// Fallback: individual requests
 	for _, task := range reportable {
+		statusAtReport := task.GetStatus() // capture before HTTP round-trip
 		update := task.ToStatusUpdate()
 		resp, err := r.reporter.ReportStatus(ctx, update)
 		if err != nil {
 			log.Printf("[%s] progress report failed: %v", task.ID[:8], err)
 			continue
 		}
+		r.mu.Lock()
+		r.lastReported[task.ID] = statusAtReport
+		r.mu.Unlock()
 		r.handleResponse(task, resp)
 	}
 }
 
 func (r *ProgressReporter) flushBatch(ctx context.Context, batcher BatchStatusReporter, tasks []*Task) {
 	updates := make([]agent.StatusUpdate, len(tasks))
+	// Capture status before HTTP round-trip to avoid missed transitions
+	statusAtReport := make([]TaskStatus, len(tasks))
 	for i, task := range tasks {
 		updates[i] = task.ToStatusUpdate()
+		statusAtReport[i] = task.GetStatus()
 	}
 
 	resp, err := batcher.BatchReportStatus(ctx, updates)
@@ -174,10 +186,20 @@ func (r *ProgressReporter) flushBatch(ctx context.Context, batcher BatchStatusRe
 		return
 	}
 
+	// Propagate watching flag from batch response
+	if resp.Watching && r.onWatchingChanged != nil {
+		r.onWatchingChanged(true)
+	}
+
 	// Match results back to tasks by index (server returns in same order)
 	if len(resp.Results) != len(tasks) {
 		log.Printf("batch response mismatch: sent %d updates, got %d results", len(tasks), len(resp.Results))
 	}
+	r.mu.Lock()
+	for i, task := range tasks {
+		r.lastReported[task.ID] = statusAtReport[i]
+	}
+	r.mu.Unlock()
 	for i, result := range resp.Results {
 		if i < len(tasks) {
 			r.handleResponse(tasks[i], &result)
@@ -186,6 +208,11 @@ func (r *ProgressReporter) flushBatch(ctx context.Context, batcher BatchStatusRe
 }
 
 func (r *ProgressReporter) handleResponse(task *Task, resp *agent.StatusResponse) {
+	// Propagate watching flag from status response to daemon
+	if resp.Watching && r.onWatchingChanged != nil {
+		r.onWatchingChanged(true)
+	}
+
 	if resp.Cancelled {
 		log.Printf("[%s] cancelled by user (via web)", task.ID[:8])
 		r.Untrack(task.ID)
diff --git a/internal/engine/progress_test.go b/internal/engine/progress_test.go
new file mode 100644
index 0000000..e9e1add
--- /dev/null
+++ b/internal/engine/progress_test.go
@@ -0,0 +1,419 @@
+package engine
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+)
+
+// mockStatusReporter records calls to ReportStatus.
+type mockStatusReporter struct {
+	mu      sync.Mutex
+	calls   []agent.StatusUpdate
+	resp    *agent.StatusResponse
+	respErr error
+}
+
+func (m *mockStatusReporter) ReportStatus(_ context.Context, update agent.StatusUpdate) (*agent.StatusResponse, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.calls = append(m.calls, update)
+	if m.resp != nil {
+		return m.resp, m.respErr
+	}
+	return &agent.StatusResponse{}, m.respErr
+}
+
+// mockBatchReporter records batch calls.
+type mockBatchReporter struct {
+	mockStatusReporter
+	batchCalls [][]agent.StatusUpdate
+	batchResp  *agent.BatchStatusResponse
+}
+
+func (m *mockBatchReporter) BatchReportStatus(_ context.Context, updates []agent.StatusUpdate) (*agent.BatchStatusResponse, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.batchCalls = append(m.batchCalls, updates)
+	if m.batchResp != nil {
+		return m.batchResp, nil
+	}
+	results := make([]agent.StatusResponse, len(updates))
+	return &agent.BatchStatusResponse{Results: results}, nil
+}
+
+func TestProgressReporter_TrackUntrack(t *testing.T) {
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+
+	task := &Task{ID: "task-001", Status: StatusDownloading}
+	pr.Track(task)
+
+	pr.mu.Lock()
+	if _, ok := pr.latest["task-001"]; !ok {
+		t.Error("task should be tracked")
+	}
+	pr.mu.Unlock()
+
+	pr.Untrack("task-001")
+
+	pr.mu.Lock()
+	if _, ok := pr.latest["task-001"]; ok {
+		t.Error("task should be untracked")
+	}
+	pr.mu.Unlock()
+}
+
+func TestProgressReporter_FlushReportsFinalStates(t *testing.T) {
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+
+	completed := &Task{ID: "task-completed-1234", Status: StatusCompleted}
+	pr.Track(completed)
+
+	pr.flush(context.Background())
+
+	reporter.mu.Lock()
+	defer reporter.mu.Unlock()
+	if len(reporter.calls) != 1 {
+		t.Fatalf("expected 1 report, got %d", len(reporter.calls))
+	}
+	if reporter.calls[0].TaskID != "task-completed-1234" {
+		t.Errorf("reported wrong task: %s", reporter.calls[0].TaskID)
+	}
+}
+
+func TestProgressReporter_FlushSkipsWhenNotWatching(t *testing.T) {
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		isWatching:   func() bool { return false },
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+		lastCheckAt:  time.Now(), // not due for control check
+	}
+
+	// Active downloading task, already reported as downloading
+	task := &Task{ID: "task-active-12345678", Status: StatusDownloading}
+	pr.Track(task)
+	pr.mu.Lock()
+	pr.lastReported["task-active-12345678"] = StatusDownloading
+	pr.mu.Unlock()
+
+	pr.flush(context.Background())
+
+	reporter.mu.Lock()
+	defer reporter.mu.Unlock()
+	if len(reporter.calls) != 0 {
+		t.Errorf("expected 0 reports when not watching (no transition), got %d", len(reporter.calls))
+	}
+}
+
+func TestProgressReporter_FlushReportsTransitions(t *testing.T) {
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		isWatching:   func() bool { return false },
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+		lastCheckAt:  time.Now(),
+	}
+
+	// Task transitioning from resolving to downloading
+	task := &Task{ID: "task-trans-12345678", Status: StatusDownloading}
+	pr.Track(task)
+	pr.mu.Lock()
+	pr.lastReported["task-trans-12345678"] = StatusResolving
+	pr.mu.Unlock()
+
+	pr.flush(context.Background())
+
+	reporter.mu.Lock()
+	defer reporter.mu.Unlock()
+	if len(reporter.calls) != 1 {
+		t.Fatalf("expected 1 report for transition, got %d", len(reporter.calls))
+	}
+}
+
+func TestProgressReporter_FlushActiveWhenWatching(t *testing.T) {
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		isWatching:   func() bool { return true },
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+
+	task := &Task{ID: "task-watch-12345678", Status: StatusDownloading}
+	pr.Track(task)
+	pr.mu.Lock()
+	pr.lastReported["task-watch-12345678"] = StatusDownloading
+	pr.mu.Unlock()
+
+	pr.flush(context.Background())
+
+	reporter.mu.Lock()
+	defer reporter.mu.Unlock()
+	if len(reporter.calls) != 1 {
+		t.Fatalf("expected 1 report when watching active task, got %d", len(reporter.calls))
+	}
+}
+
+func TestProgressReporter_HandleResponseCancel(t *testing.T) {
+	reporter := &mockStatusReporter{
+		resp: &agent.StatusResponse{Cancelled: true},
+	}
+
+	var cancelledID string
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+		onCancel:     func(id string) { cancelledID = id },
+	}
+
+	task := &Task{ID: "task-cancel-1234567", Status: StatusCompleted}
+	pr.Track(task)
+
+	pr.flush(context.Background())
+
+	if cancelledID != "task-cancel-1234567" {
+		t.Errorf("expected cancel handler called with task ID, got %q", cancelledID)
+	}
+}
+
+func TestProgressReporter_HandleResponsePause(t *testing.T) {
+	reporter := &mockStatusReporter{
+		resp: &agent.StatusResponse{Paused: true},
+	}
+
+	var pausedID string
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+		onPause:      func(id string) { pausedID = id },
+	}
+
+	task := &Task{ID: "task-paused-1234567", Status: StatusCompleted}
+	pr.Track(task)
+
+	pr.flush(context.Background())
+
+	if pausedID != "task-paused-1234567" {
+		t.Errorf("expected pause handler called, got %q", pausedID)
+	}
+}
+
+func TestProgressReporter_HandleResponseDeleteFiles(t *testing.T) {
+	reporter := &mockStatusReporter{
+		resp: &agent.StatusResponse{Cancelled: true, DeleteFiles: true},
+	}
+
+	var deletedID string
+	pr := &ProgressReporter{
+		reporter:      reporter,
+		interval:      time.Second,
+		latest:        make(map[string]*Task),
+		lastReported:  make(map[string]TaskStatus),
+		onDeleteFiles: func(id string) { deletedID = id },
+	}
+
+	task := &Task{ID: "task-delete-1234567", Status: StatusCompleted}
+	pr.Track(task)
+
+	pr.flush(context.Background())
+
+	if deletedID != "task-delete-1234567" {
+		t.Errorf("expected deleteFiles handler called, got %q", deletedID)
+	}
+}
+
+func TestProgressReporter_HandleResponseStream(t *testing.T) {
+	reporter := &mockStatusReporter{
+		resp: &agent.StatusResponse{StreamRequested: true},
+	}
+
+	var streamID string
+	pr := &ProgressReporter{
+		reporter:          reporter,
+		interval:          time.Second,
+		latest:            make(map[string]*Task),
+		lastReported:      make(map[string]TaskStatus),
+		onStreamRequested: func(id string) { streamID = id },
+	}
+
+	// Task with no stream URL yet
+	task := &Task{ID: "task-stream-1234567", Status: StatusCompleted}
+	pr.Track(task)
+
+	pr.flush(context.Background())
+
+	if streamID != "task-stream-1234567" {
+		t.Errorf("expected stream handler called, got %q", streamID)
+	}
+}
+
+func TestProgressReporter_HandleResponseWatchingChanged(t *testing.T) {
+	reporter := &mockStatusReporter{
+		resp: &agent.StatusResponse{Watching: true},
+	}
+
+	var watchingValue bool
+	pr := &ProgressReporter{
+		reporter:          reporter,
+		interval:          time.Second,
+		latest:            make(map[string]*Task),
+		lastReported:      make(map[string]TaskStatus),
+		onWatchingChanged: func(w bool) { watchingValue = w },
+	}
+
+	task := &Task{ID: "task-watch2-1234567", Status: StatusCompleted}
+	pr.Track(task)
+
+	pr.flush(context.Background())
+
+	if !watchingValue {
+		t.Error("expected watchingChanged called with true")
+	}
+}
+
+func TestProgressReporter_BatchFlush(t *testing.T) {
+	batcher := &mockBatchReporter{
+		batchResp: &agent.BatchStatusResponse{
+			Results: []agent.StatusResponse{{}, {}},
+		},
+	}
+
+	pr := &ProgressReporter{
+		reporter:     batcher,
+		interval:     time.Second,
+		isWatching:   func() bool { return true },
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+
+	pr.Track(&Task{ID: "task-batch1-1234567", Status: StatusDownloading})
+	pr.Track(&Task{ID: "task-batch2-1234567", Status: StatusDownloading})
+
+	pr.flush(context.Background())
+
+	batcher.mu.Lock()
+	defer batcher.mu.Unlock()
+
+	if len(batcher.batchCalls) != 1 {
+		t.Fatalf("expected 1 batch call, got %d", len(batcher.batchCalls))
+	}
+	if len(batcher.batchCalls[0]) != 2 {
+		t.Errorf("expected 2 updates in batch, got %d", len(batcher.batchCalls[0]))
+	}
+}
+
+func TestProgressReporter_RunStopsOnCancel(t *testing.T) {
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     50 * time.Millisecond,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancel()
+
+	err := pr.Run(ctx)
+	if err != nil {
+		t.Errorf("Run should return nil on context cancel, got: %v", err)
+	}
+}
+
+func TestProgressReporter_ReportFinal(t *testing.T) {
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+
+	task := &Task{ID: "task-final-12345678", Status: StatusCompleted}
+	pr.Track(task)
+
+	pr.ReportFinal(context.Background(), task)
+
+	reporter.mu.Lock()
+	defer reporter.mu.Unlock()
+	if len(reporter.calls) != 1 {
+		t.Fatalf("expected 1 final report, got %d", len(reporter.calls))
+	}
+
+	// Should be untracked after final report
+	pr.mu.Lock()
+	if _, ok := pr.latest["task-final-12345678"]; ok {
+		t.Error("task should be untracked after ReportFinal")
+	}
+	pr.mu.Unlock()
+}
+
+func TestProgressReporter_SetHandlers(t *testing.T) {
+	pr := &ProgressReporter{
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+	}
+
+	pr.SetCancelHandler(func(id string) {})
+	pr.SetPauseHandler(func(id string) {})
+	pr.SetDeleteFilesHandler(func(id string) {})
+	pr.SetStreamRequestedHandler(func(id string) {})
+	pr.SetWatchingFunc(func() bool { return true })
+	pr.SetWatchingChangedHandler(func(w bool) {})
+
+	if pr.onCancel == nil || pr.onPause == nil || pr.onDeleteFiles == nil ||
+		pr.onStreamRequested == nil || pr.isWatching == nil || pr.onWatchingChanged == nil {
+		t.Error("expected all handlers to be set")
+	}
+}
+
+func TestProgressReporter_ControlCheckDue(t *testing.T) {
+	reporter := &mockStatusReporter{}
+	pr := &ProgressReporter{
+		reporter:     reporter,
+		interval:     time.Second,
+		isWatching:   func() bool { return false },
+		latest:       make(map[string]*Task),
+		lastReported: make(map[string]TaskStatus),
+		lastCheckAt:  time.Now().Add(-31 * time.Second), // 31s ago - due for control check
+	}
+
+	task := &Task{ID: "task-ctrl-123456789", Status: StatusDownloading}
+	pr.Track(task)
+	pr.mu.Lock()
+	pr.lastReported["task-ctrl-123456789"] = StatusDownloading
+	pr.mu.Unlock()
+
+	pr.flush(context.Background())
+
+	reporter.mu.Lock()
+	defer reporter.mu.Unlock()
+	if len(reporter.calls) != 1 {
+		t.Errorf("expected 1 report for control check, got %d", len(reporter.calls))
+	}
+}
diff --git a/internal/engine/sockopt_unix.go b/internal/engine/sockopt_unix.go
new file mode 100644
index 0000000..7856425
--- /dev/null
+++ b/internal/engine/sockopt_unix.go
@@ -0,0 +1,9 @@
+//go:build !windows
+
+package engine
+
+import "syscall"
+
+func setReuseAddr(fd uintptr) error {
+	return syscall.SetsockoptInt(int(fd), syscall.SOL_SOCKET, syscall.SO_REUSEADDR, 1)
+}
diff --git a/internal/engine/sockopt_windows.go b/internal/engine/sockopt_windows.go
new file mode 100644
index 0000000..dc0aa9d
--- /dev/null
+++ b/internal/engine/sockopt_windows.go
@@ -0,0 +1,9 @@
+//go:build windows
+
+package engine
+
+import "syscall"
+
+func setReuseAddr(fd uintptr) error {
+	return syscall.SetsockoptInt(syscall.Handle(fd), syscall.SOL_SOCKET, syscall.SO_REUSEADDR, 1)
+}
diff --git a/internal/engine/stream.go b/internal/engine/stream.go
index aa69e43..1414f15 100644
--- a/internal/engine/stream.go
+++ b/internal/engine/stream.go
@@ -297,9 +297,44 @@ func (s *StreamEngine) FileName() string { return s.fileName }
 // FileLength returns the total size of the selected file in bytes.
 func (s *StreamEngine) FileLength() int64 { return s.totalBytes }
 
+// FileSize implements FileProvider for StreamServer compatibility.
+func (s *StreamEngine) FileSize() int64 { return s.totalBytes }
+
 // BufferTarget returns the buffer threshold in bytes.
 func (s *StreamEngine) BufferTarget() int64 { return s.bufferTarget }
 
+// PrioritizeTail abre un lector posicionado cerca del final del archivo para
+// forzar la descarga anticipada de los metadatos del container (moov atom en
+// MP4, seekhead en MKV). Sin esto, VLC busca el final del archivo al abrirlo
+// y el lector bloquea indefinidamente si esas piezas aún no están descargadas,
+// resultando en pantalla negra en redes lentas o remotas.
+//
+// Se ejecuta en una goroutine y se cancela cuando ctx expira.
+func (s *StreamEngine) PrioritizeTail(ctx context.Context, tailBytes int64) {
+	if s.file == nil || s.totalBytes <= tailBytes*2 {
+		return
+	}
+	go func() {
+		reader := s.file.NewReader()
+		defer reader.Close()
+
+		seekPos := s.totalBytes - tailBytes
+		reader.Seek(seekPos, io.SeekStart) //nolint:errcheck
+		reader.SetReadahead(tailBytes)
+		reader.SetContext(ctx)
+
+		// Leer continuamente para mantener las piezas priorizadas hasta que
+		// ctx se cancele o el final del archivo esté completamente descargado.
+		buf := make([]byte, 32*1024)
+		for {
+			_, err := reader.Read(buf)
+			if err != nil {
+				return
+			}
+		}
+	}()
+}
+
 // Shutdown gracefully closes the torrent and client.
 func (s *StreamEngine) Shutdown(_ context.Context) error {
 	if s.tor != nil {
diff --git a/internal/engine/stream_player.go b/internal/engine/stream_player.go
index 51424cf..494d79c 100644
--- a/internal/engine/stream_player.go
+++ b/internal/engine/stream_player.go
@@ -4,14 +4,23 @@ import (
 	"fmt"
 	"os/exec"
 	"runtime"
+	"strings"
 )
 
 // OpenPlayer attempts to open a media player with the given stream URL.
 // Returns the player name and the running command.
 // If override is set, it uses that command directly.
+//
+// The URL is required to be http(s) so a hostile-looking value (e.g. starting
+// with `--`) is not interpreted as a switch by mpv/vlc/xdg-open/open. The
+// `--` separator is also appended before the URL where the helper supports
+// it.
 func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
+	if !isSafePlayerURL(url) {
+		return "", nil, fmt.Errorf("refusing to open non-http(s) URL")
+	}
 	if override != "" {
-		cmd := exec.Command(override, url)
+		cmd := exec.Command(override, "--", url)
 		if err := cmd.Start(); err != nil {
 			return override, nil, fmt.Errorf("start %s: %w", override, err)
 		}
@@ -20,7 +29,7 @@ func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
 
 	// Try mpv first (best streaming support)
 	if path, err := exec.LookPath("mpv"); err == nil {
-		cmd := exec.Command(path, "--no-terminal", url)
+		cmd := exec.Command(path, "--no-terminal", "--", url)
 		if err := cmd.Start(); err == nil {
 			return "mpv", cmd, nil
 		}
@@ -28,7 +37,7 @@ func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
 
 	// Try VLC
 	if path, err := exec.LookPath("vlc"); err == nil {
-		cmd := exec.Command(path, url)
+		cmd := exec.Command(path, "--", url)
 		if err := cmd.Start(); err == nil {
 			return "vlc", cmd, nil
 		}
@@ -36,7 +45,7 @@ func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
 
 	// Try cvlc (VLC headless)
 	if path, err := exec.LookPath("cvlc"); err == nil {
-		cmd := exec.Command(path, url)
+		cmd := exec.Command(path, "--", url)
 		if err := cmd.Start(); err == nil {
 			return "vlc (headless)", cmd, nil
 		}
@@ -51,6 +60,9 @@ func OpenPlayer(url, override string) (string, *exec.Cmd, error) {
 }
 
 func openBrowser(url string) (string, *exec.Cmd, error) {
+	if !isSafePlayerURL(url) {
+		return "", nil, fmt.Errorf("refusing to open non-http(s) URL")
+	}
 	switch runtime.GOOS {
 	case "linux":
 		if path, err := exec.LookPath("xdg-open"); err == nil {
@@ -60,7 +72,7 @@ func openBrowser(url string) (string, *exec.Cmd, error) {
 			}
 		}
 	case "darwin":
-		cmd := exec.Command("/usr/bin/open", url)
+		cmd := exec.Command("/usr/bin/open", "--", url)
 		if err := cmd.Start(); err == nil {
 			return "browser", cmd, nil
 		}
@@ -72,3 +84,9 @@ func openBrowser(url string) (string, *exec.Cmd, error) {
 	}
 	return "", nil, fmt.Errorf("no browser opener found")
 }
+
+// isSafePlayerURL guards the helpers above against URLs that could be
+// interpreted as command-line switches by the launched player.
+func isSafePlayerURL(url string) bool {
+	return strings.HasPrefix(url, "http://") || strings.HasPrefix(url, "https://")
+}
diff --git a/internal/engine/stream_server.go b/internal/engine/stream_server.go
index 1635d69..2e182fd 100644
--- a/internal/engine/stream_server.go
+++ b/internal/engine/stream_server.go
@@ -2,6 +2,7 @@ package engine
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"log"
@@ -10,45 +11,689 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
+	"sync"
+	"sync/atomic"
+	"syscall"
 	"time"
 
 	"github.com/anacrolix/torrent"
 )
 
-// fileProvider abstracts where to get a file reader for streaming.
-type fileProvider interface {
+// StreamURLs holds all available stream URLs keyed by network type.
+// Serialized as JSON into the stream_url DB field so the web API can
+// pick the best URL based on the browser's IP address.
+type StreamURLs struct {
+	LAN       string `json:"lan,omitempty"`
+	Tailscale string `json:"ts,omitempty"`
+	Public    string `json:"pub,omitempty"`
+}
+
+// FileProvider abstracts where to get a file reader for streaming.
+type FileProvider interface {
 	NewFileReader(ctx context.Context) io.ReadSeekCloser
 	FileName() string
+	FileSize() int64
 }
 
-// StreamServer serves a torrent file over HTTP with Range request support.
+// 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 {
-	provider    fileProvider
+	mu       sync.RWMutex
+	provider FileProvider
+	taskID   string // current task being streamed
+
 	server      *http.Server
 	port        int
-	url         string
+	url         string     // best single URL (backward compat)
+	urls        StreamURLs // all available URLs by network type
 	upnpMapping *UPnPMapping
+	// enableUPnP gates whether Listen() asks the gateway to publish the
+	// stream port to the WAN. UPnP is opt-in (false by default) because
+	// /stream and /hls have no auth — exposing them on the public internet
+	// would let any scanner enumerate active downloads. LAN and Tailscale
+	// access keep working without UPnP.
+	enableUPnP bool
+	// corsExtraOrigins are operator-configured origins added to the default
+	// allowlist defined in validate.go. Set before Listen().
+	corsExtraOrigins []string
+	// corsAllowlist is computed at Listen() time and treated as read-only
+	// thereafter so per-request reads need no locking.
+	corsAllowlist map[string]struct{}
+
+	hls *HLSSessionRegistry // HLS sessions served on /hls/<id>/...
+
+	lastActivity  atomic.Int64
+	maxByteOffset atomic.Int64 // highest sequential read position (main playback connection)
+	totalFileSize atomic.Int64
+	bitrateBps    atomic.Int64 // video bitrate in bits/sec (from ffprobe, 0 = unknown)
+	durationSec   atomic.Int64 // video duration in seconds (from ffprobe, 0 = unknown)
+	topReaderID   atomic.Int64 // ID of the reader that set maxByteOffset (only it can advance it)
+	readerCounter atomic.Int64 // monotonic counter for assigning reader IDs
 }
 
-// NewStreamServer creates a new HTTP server for streaming via StreamEngine.
-func NewStreamServer(engine *StreamEngine, port int) *StreamServer {
-	return &StreamServer{
-		provider: engine,
-		port:     port,
+// NewStreamServer creates a stream server bound to the given port.
+// Call Listen() to start accepting connections, then SetFile() to serve content.
+//
+// UPnP is opt-in: call SetUPnPEnabled(true) before Listen() to publish the
+// stream port on the WAN. Without it, only LAN and Tailscale clients can
+// reach the server. This matches the security default — /stream and /hls
+// 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()}
+}
+
+// SetUPnPEnabled toggles WAN publishing of the stream port. Call before
+// Listen(); changes after Listen() are ignored for the active server.
+func (ss *StreamServer) SetUPnPEnabled(enabled bool) {
+	ss.enableUPnP = enabled
+}
+
+// SetCORSAllowedOrigins replaces the operator-supplied extra origins. The
+// default allowlist (torrentclaw.com / app.torrentclaw.com / localhost dev
+// ports) is always merged in. Call before Listen().
+func (ss *StreamServer) SetCORSAllowedOrigins(origins []string) {
+	ss.corsExtraOrigins = origins
+}
+
+// writeCORSHeaders writes the per-origin CORS response headers when the
+// request carries an Origin header that matches the allowlist. Returns true
+// if the handler must short-circuit (preflight OPTIONS). Media-tag requests
+// (no Origin header) bypass this entirely.
+//
+// `Vary: Origin` is emitted whenever an Origin header is present (matched
+// or not) so any intermediate cache keys the response per-origin and a
+// later request with a different origin cannot be served a stale ACAO.
+func (ss *StreamServer) writeCORSHeaders(w http.ResponseWriter, r *http.Request, expose string) (preflight bool) {
+	origin := r.Header.Get("Origin")
+	if origin == "" {
+		return false
+	}
+	w.Header().Add("Vary", "Origin")
+	if _, ok := ss.corsAllowlist[origin]; !ok {
+		// Unknown origin — do not emit CORS headers so the browser blocks
+		// the response. Still return without short-circuiting so a non-CORS
+		// caller (e.g. curl) keeps working.
+		return false
+	}
+	w.Header().Set("Access-Control-Allow-Origin", origin)
+	w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
+	w.Header().Set("Access-Control-Allow-Headers", "Range")
+	if expose != "" {
+		w.Header().Set("Access-Control-Expose-Headers", expose)
+	}
+	if r.Method == http.MethodOptions {
+		w.WriteHeader(http.StatusNoContent)
+		return true
+	}
+	return false
+}
+
+// HLS returns the HLS session registry for this server. Daemon code uses it
+// to register a session when the backend asks for HLS playback.
+func (ss *StreamServer) HLS() *HLSSessionRegistry { return ss.hls }
+
+// Listen starts the HTTP server on the configured port. Call once at daemon startup.
+func (ss *StreamServer) Listen(ctx context.Context) error {
+	// Freeze the CORS allowlist before the first request can land. After
+	// this point the map is treated as read-only so handlers can probe it
+	// without locking.
+	ss.corsAllowlist = buildCORSAllowlist(ss.corsExtraOrigins)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/stream", ss.handler)
+	mux.HandleFunc("/health", ss.healthHandler)
+	mux.HandleFunc("/playlist.m3u", ss.playlistHandler)
+	mux.HandleFunc("/hls/", ss.hlsHandler)
+
+	// SO_REUSEADDR allows immediate rebind if the port is in TIME_WAIT (e.g. after agent restart)
+	lc := net.ListenConfig{
+		Control: func(network, address string, c syscall.RawConn) error {
+			return c.Control(func(fd uintptr) {
+				_ = setReuseAddr(fd)
+			})
+		},
+	}
+
+	// Try configured port; if busy, try next ports (heartbeat reports actual port to web)
+	var listener net.Listener
+	var listenErr error
+	basePort := ss.port
+	for attempt := 0; attempt < 10; attempt++ {
+		addr := fmt.Sprintf("0.0.0.0:%d", ss.port)
+		listener, listenErr = lc.Listen(ctx, "tcp", addr)
+		if listenErr == nil {
+			break
+		}
+		if !strings.Contains(listenErr.Error(), "address already in use") {
+			return fmt.Errorf("stream server listen on %s: %w", addr, listenErr)
+		}
+		ss.port++
+		log.Printf("[stream] port %d in use, trying %d", ss.port-1, ss.port)
+	}
+	if listenErr != nil {
+		return fmt.Errorf("stream server: all ports busy (%d-%d): %w", basePort, ss.port, listenErr)
+	}
+	if ss.port != basePort {
+		log.Printf("[stream] using port %d (configured %d was busy)", ss.port, basePort)
+	}
+
+	ss.port = listener.Addr().(*net.TCPAddr).Port
+
+	// Collect all reachable URLs by network type
+	if lanIP := LanIP(); lanIP != "" {
+		ss.urls.LAN = fmt.Sprintf("http://%s:%d/stream", lanIP, ss.port)
+	}
+	if tsIP := TailscaleIP(); tsIP != "" {
+		ss.urls.Tailscale = fmt.Sprintf("http://%s:%d/stream", tsIP, ss.port)
+	}
+	if ss.enableUPnP {
+		mapping, err := SetupUPnP(ss.port)
+		if err != nil {
+			log.Printf("[stream] UPnP setup failed: %v (only LAN/Tailscale clients will reach port %d)", err, ss.port)
+		} else {
+			ss.upnpMapping = mapping
+			ss.urls.Public = fmt.Sprintf("http://%s:%d/stream", mapping.ExternalIP, mapping.ExternalPort)
+		}
+	} else {
+		log.Printf("[stream] UPnP disabled — port %d not published to WAN (set downloads.enable_upnp = true to opt in)", ss.port)
+	}
+
+	// Best single URL for backward compat: Tailscale > LAN > Public > localhost
+	switch {
+	case ss.urls.Tailscale != "":
+		ss.url = ss.urls.Tailscale
+	case ss.urls.LAN != "":
+		ss.url = ss.urls.LAN
+	case ss.urls.Public != "":
+		ss.url = ss.urls.Public
+	default:
+		ss.url = fmt.Sprintf("http://127.0.0.1:%d/stream", ss.port)
+		ss.urls.LAN = ss.url
+	}
+
+	ss.server = &http.Server{
+		Handler:           mux,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+
+	go func() {
+		if err := ss.server.Serve(listener); err != nil && err != http.ErrServerClosed {
+			log.Printf("stream server error: %v", err)
+		}
+	}()
+
+	log.Printf("[stream] server listening on port %d", ss.port)
+	return nil
+}
+
+// SetFile atomically swaps the file being served and resets progress tracking.
+func (ss *StreamServer) SetFile(provider FileProvider, taskID string) {
+	ss.mu.Lock()
+	ss.provider = provider
+	ss.taskID = taskID
+	ss.mu.Unlock()
+	ss.totalFileSize.Store(provider.FileSize())
+	ss.lastActivity.Store(time.Now().UnixNano())
+	ss.maxByteOffset.Store(0)
+	ss.topReaderID.Store(0)
+	ss.bitrateBps.Store(0)
+	ss.durationSec.Store(0)
+
+	// Probe bitrate + duration synchronously so rate-limiting and duration
+	// are available before the first HTTP request arrives.
+	if dp, ok := provider.(*diskFileProvider); ok {
+		pm := probeMediaInfo(dp.path)
+		if pm.bitrateBps > 0 {
+			ss.bitrateBps.Store(pm.bitrateBps)
+			log.Printf("[stream] detected bitrate: %.1f Mbps → throttle at %.1f Mbps",
+				float64(pm.bitrateBps)/1e6, float64(pm.bitrateBps)*2/1e6)
+		}
+		if pm.durationSec > 0 {
+			ss.durationSec.Store(pm.durationSec)
+		}
 	}
 }
 
-// NewStreamServerFromFile creates a server that streams directly from a torrent.File.
-// Used for streaming an active download without a separate StreamEngine.
-func NewStreamServerFromFile(file *torrent.File, port int) *StreamServer {
-	return &StreamServer{
-		provider: &torrentFileProvider{file: file},
-		port:     port,
+// ClearFile stops serving any file. Subsequent requests return 404.
+func (ss *StreamServer) ClearFile() {
+	ss.mu.Lock()
+	ss.provider = nil
+	ss.taskID = ""
+	ss.mu.Unlock()
+	ss.totalFileSize.Store(0)
+	ss.maxByteOffset.Store(0)
+	ss.topReaderID.Store(0)
+	ss.bitrateBps.Store(0)
+	ss.durationSec.Store(0)
+}
+
+// CurrentTaskID returns the task ID of the file currently being served.
+func (ss *StreamServer) CurrentTaskID() string {
+	ss.mu.RLock()
+	defer ss.mu.RUnlock()
+	return ss.taskID
+}
+
+// HasFile returns true if a file is currently being served.
+func (ss *StreamServer) HasFile() bool {
+	ss.mu.RLock()
+	defer ss.mu.RUnlock()
+	return ss.provider != nil
+}
+
+// URL returns the best single stream URL (backward compat).
+func (ss *StreamServer) URL() string { return ss.url }
+
+// URLsJSON returns all available stream URLs as a JSON string.
+func (ss *StreamServer) URLsJSON() string {
+	b, _ := json.Marshal(ss.urls)
+	return string(b)
+}
+
+// Port returns the bound port.
+func (ss *StreamServer) Port() int { return ss.port }
+
+// IdleSince returns how long since the last HTTP request was received.
+func (ss *StreamServer) IdleSince() time.Duration {
+	last := ss.lastActivity.Load()
+	if last == 0 {
+		return 0
+	}
+	return time.Since(time.Unix(0, last))
+}
+
+// Shutdown gracefully stops the HTTP server and removes the UPnP port mapping.
+// Call only at daemon shutdown — NOT between file swaps.
+func (ss *StreamServer) Shutdown(ctx context.Context) error {
+	ss.upnpMapping.Remove()
+	if ss.hls != nil {
+		ss.hls.CloseAll()
+	}
+	if ss.server != nil {
+		return ss.server.Shutdown(ctx)
+	}
+	return nil
+}
+
+// hlsBaseURLs returns the per-network HLS base URLs for a given session.
+// The web client picks the first reachable one — same fallback strategy as
+// the legacy /stream URLs.
+func (ss *StreamServer) hlsBaseURLs(sessionID string) StreamURLs {
+	var out StreamURLs
+	if ss.urls.LAN != "" {
+		out.LAN = strings.Replace(ss.urls.LAN, "/stream", "/hls/"+sessionID, 1)
+	}
+	if ss.urls.Tailscale != "" {
+		out.Tailscale = strings.Replace(ss.urls.Tailscale, "/stream", "/hls/"+sessionID, 1)
+	}
+	if ss.urls.Public != "" {
+		out.Public = strings.Replace(ss.urls.Public, "/stream", "/hls/"+sessionID, 1)
+	}
+	return out
+}
+
+// HLSURLsJSON returns base URLs for an HLS session as a JSON string for the
+// session response payload.
+func (ss *StreamServer) HLSURLsJSON(sessionID string) string {
+	urls := ss.hlsBaseURLs(sessionID)
+	b, _ := json.Marshal(urls)
+	return string(b)
+}
+
+// hlsHandler routes /hls/<sessionID>/<resource> to the matching HLSSession.
+//
+// Recognised resources:
+//
+//	master.m3u8                — top-level playlist
+//	video/index.m3u8           — video media playlist
+//	video/init.mp4             — fMP4 init segment
+//	video/seg-<n>.m4s          — video segment
+//	subs/sub-<n>.m3u8          — per-subtitle media playlist (synthesised)
+//	subs/sub-<n>.vtt           — WebVTT subtitle (extracted by ffmpeg)
+func (ss *StreamServer) hlsHandler(w http.ResponseWriter, r *http.Request) {
+	ss.lastActivity.Store(time.Now().UnixNano())
+
+	if ss.writeCORSHeaders(w, r, "Content-Length, Content-Range, Accept-Ranges") {
+		return
+	}
+
+	rest := strings.TrimPrefix(r.URL.Path, "/hls/")
+	parts := strings.SplitN(rest, "/", 2)
+	if len(parts) == 0 || parts[0] == "" {
+		http.Error(w, "missing session id", http.StatusNotFound)
+		return
+	}
+	sessionID := parts[0]
+	// Reject malformed IDs with the same 404 we return for unknown sessions —
+	// no oracle for the accepted format.
+	if !validSessionID.MatchString(sessionID) {
+		http.Error(w, "hls session not found", http.StatusNotFound)
+		return
+	}
+	session := ss.hls.Get(sessionID)
+	if session == nil {
+		http.Error(w, "hls session not found", http.StatusNotFound)
+		return
+	}
+	if len(parts) == 1 {
+		http.Error(w, "missing resource", http.StatusNotFound)
+		return
+	}
+	resource := parts[1]
+
+	switch {
+	case resource == "master.m3u8":
+		session.ServeMaster(w, r)
+	case resource == "probe.json":
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Cache-Control", "no-cache")
+		_ = json.NewEncoder(w).Encode(session.ProbeInfo())
+	case resource == "video/index.m3u8":
+		session.ServeVideoPlaylist(w, r)
+	case resource == "video/init.mp4":
+		session.ServeInit(w, r)
+	case strings.HasPrefix(resource, "video/seg-") && strings.HasSuffix(resource, ".m4s"):
+		idxStr := strings.TrimSuffix(strings.TrimPrefix(resource, "video/seg-"), ".m4s")
+		idx, err := strconv.Atoi(idxStr)
+		if err != nil {
+			http.Error(w, "bad segment index", http.StatusBadRequest)
+			return
+		}
+		session.ServeSegment(w, r, idx)
+	case strings.HasPrefix(resource, "subs/sub-") && strings.HasSuffix(resource, ".m3u8"):
+		idxStr := strings.TrimSuffix(strings.TrimPrefix(resource, "subs/sub-"), ".m3u8")
+		idx, err := strconv.Atoi(idxStr)
+		if err != nil {
+			http.Error(w, "bad subtitle index", http.StatusBadRequest)
+			return
+		}
+		ss.serveSubtitlePlaylist(w, r, session, idx)
+	case strings.HasPrefix(resource, "subs/sub-") && strings.HasSuffix(resource, ".vtt"):
+		idxStr := strings.TrimSuffix(strings.TrimPrefix(resource, "subs/sub-"), ".vtt")
+		idx, err := strconv.Atoi(idxStr)
+		if err != nil {
+			http.Error(w, "bad subtitle index", http.StatusBadRequest)
+			return
+		}
+		session.ServeSubtitle(w, r, idx)
+	default:
+		http.Error(w, "unknown hls resource", http.StatusNotFound)
 	}
 }
 
-// torrentFileProvider wraps a torrent.File to implement fileProvider.
+// serveSubtitlePlaylist generates a single-VTT-segment HLS playlist on the
+// fly so hls.js can consume it as a regular subtitle rendition. The VTT file
+// itself is extracted asynchronously by HLSSession.extractSubtitles.
+func (ss *StreamServer) serveSubtitlePlaylist(w http.ResponseWriter, r *http.Request, session *HLSSession, idx int) {
+	if idx < 0 || idx >= len(session.probe.SubtitleTracks) {
+		http.Error(w, "subtitle out of range", http.StatusNotFound)
+		return
+	}
+	dur := session.durationSec
+	if dur < 1 {
+		dur = 1
+	}
+	body := strings.Builder{}
+	body.WriteString("#EXTM3U\n")
+	body.WriteString("#EXT-X-VERSION:3\n")
+	body.WriteString("#EXT-X-PLAYLIST-TYPE:VOD\n")
+	body.WriteString(fmt.Sprintf("#EXT-X-TARGETDURATION:%d\n", int(dur)+1))
+	body.WriteString("#EXT-X-MEDIA-SEQUENCE:0\n")
+	body.WriteString(fmt.Sprintf("#EXTINF:%.3f,\n", dur))
+	body.WriteString(fmt.Sprintf("sub-%d.vtt\n", idx))
+	body.WriteString("#EXT-X-ENDLIST\n")
+
+	w.Header().Set("Content-Type", "application/vnd.apple.mpegurl")
+	w.Header().Set("Cache-Control", "no-cache")
+	_, _ = io.WriteString(w, body.String())
+}
+
+// healthHandler responde con el estado del servidor en JSON.
+// Útil para diagnosticar conectividad desde redes remotas o Tailscale:
+//
+//	curl http://<tailscale-ip>:<port>/health
+func (ss *StreamServer) healthHandler(w http.ResponseWriter, r *http.Request) {
+	if ss.writeCORSHeaders(w, r, "") {
+		return
+	}
+	ss.mu.RLock()
+	provider := ss.provider
+	taskID := ss.taskID
+	ss.mu.RUnlock()
+
+	clientIP, _, _ := net.SplitHostPort(r.RemoteAddr)
+	// Only expose filename/taskID/client to loopback callers (local diagnostics).
+	// Remote callers (LAN, Tailscale, UPnP public) get a minimal probe response
+	// so that scanners and unauthenticated peers cannot fingerprint the active
+	// download. The web stream-probe only checks HTTP 200 + Content-Type.
+	//
+	// Use net.IP.IsLoopback so we also accept ::ffff:127.0.0.1 (Linux dual-stack
+	// IPv4-mapped form) and reject the empty-string fallthrough when
+	// SplitHostPort fails on a malformed RemoteAddr — both would otherwise
+	// silently bypass the disclosure boundary.
+	parsedIP := net.ParseIP(clientIP)
+	isLocal := parsedIP != nil && parsedIP.IsLoopback()
+
+	type healthResponse struct {
+		Status    string `json:"status"`
+		Streaming bool   `json:"streaming"`
+		File      string `json:"file,omitempty"`
+		Task      string `json:"task,omitempty"`
+		Port      int    `json:"port"`
+		Client    string `json:"client,omitempty"`
+	}
+	resp := healthResponse{
+		Status: "ok",
+		Port:   ss.port,
+	}
+	if provider != nil {
+		resp.Streaming = true
+	}
+	if isLocal {
+		resp.Client = clientIP
+		if provider != nil {
+			resp.File = provider.FileName()
+			resp.Task = taskID
+			if len(resp.Task) > 8 {
+				resp.Task = resp.Task[:8]
+			}
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Cache-Control", "no-cache")
+	json.NewEncoder(w).Encode(resp) //nolint:errcheck
+}
+
+// playlistHandler generates an M3U playlist for VLC with #EXTVLCOPT language hints.
+// Query params: audioLangs (comma-sep), subLangs (comma-sep), resumeSec, title, streamUrl.
+// If streamUrl is omitted, uses the current best stream URL.
+//
+// VLC fetches this playlist and applies the EXTVLCOPT directives automatically,
+// enabling automatic audio/subtitle track selection on all VLC platforms (desktop + mobile).
+func (ss *StreamServer) playlistHandler(w http.ResponseWriter, r *http.Request) {
+	if ss.writeCORSHeaders(w, r, "") {
+		return
+	}
+
+	q := r.URL.Query()
+
+	// Sanitize query params: strip CR/LF to prevent M3U directive injection.
+	sanitize := func(s string) string {
+		s = strings.ReplaceAll(s, "\n", "")
+		s = strings.ReplaceAll(s, "\r", "")
+		return s
+	}
+
+	audioLangs := sanitize(q.Get("audioLangs"))
+	subLangs := sanitize(q.Get("subLangs"))
+	resumeSec := sanitize(q.Get("resumeSec"))
+	title := sanitize(q.Get("title"))
+	streamURL := q.Get("streamUrl")
+	// Only accept http(s) URLs to prevent file:// or other URI schemes in the playlist.
+	if streamURL != "" && !strings.HasPrefix(streamURL, "http://") && !strings.HasPrefix(streamURL, "https://") {
+		streamURL = ""
+	}
+	if streamURL == "" {
+		streamURL = ss.url
+	}
+	if streamURL == "" {
+		http.Error(w, "no active stream", http.StatusNotFound)
+		return
+	}
+	if title == "" {
+		title = "TorrentClaw Stream"
+	}
+
+	var b strings.Builder
+	b.WriteString("#EXTM3U\n")
+	b.WriteString(fmt.Sprintf("#EXTINF:-1,%s\n", title))
+	if audioLangs != "" {
+		b.WriteString(fmt.Sprintf("#EXTVLCOPT:audio-language=%s\n", audioLangs))
+	}
+	if subLangs != "" {
+		b.WriteString(fmt.Sprintf("#EXTVLCOPT:sub-language=%s\n", subLangs))
+	}
+	if resumeSec != "" && resumeSec != "0" {
+		b.WriteString(fmt.Sprintf("#EXTVLCOPT:start-time=%s\n", resumeSec))
+	}
+	b.WriteString("#EXTVLCOPT:network-caching=30000\n")
+	b.WriteString(streamURL + "\n")
+
+	w.Header().Set("Content-Type", "audio/x-mpegurl")
+	w.Header().Set("Content-Disposition", `inline; filename="stream.m3u"`)
+	w.Header().Set("Cache-Control", "no-cache")
+	fmt.Fprint(w, b.String()) //nolint:errcheck
+}
+
+func (ss *StreamServer) handler(w http.ResponseWriter, r *http.Request) {
+	ss.lastActivity.Store(time.Now().UnixNano())
+
+	// Log every incoming request — essential for diagnosing remote/Tailscale issues.
+	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)
+	ss.mu.RLock()
+	provider := ss.provider
+	ss.mu.RUnlock()
+
+	if provider == nil {
+		http.Error(w, "no active stream", http.StatusNotFound)
+		return
+	}
+
+	if ss.writeCORSHeaders(w, r, "Content-Length, Content-Range, Accept-Ranges") {
+		return
+	}
+
+	rawReader := provider.NewFileReader(r.Context())
+	if rawReader == nil {
+		http.Error(w, "file not found", http.StatusNotFound)
+		return
+	}
+	defer rawReader.Close()
+
+	// Wrap reader to track bytes read for progress estimation + rate limit.
+	// Rate limiting at ~2x bitrate ensures VLC can't download far ahead of
+	// playback, so bytes-read ≈ playback position (like Netflix/YouTube).
+	bps := ss.bitrateBps.Load()
+	var bytesPerSec int64
+	if bps > 0 {
+		bytesPerSec = bps / 8 * 2 // 2x bitrate in bytes/sec
+	}
+	var burstSize int64
+	if bytesPerSec > 0 {
+		burstSize = bytesPerSec * 30
+	}
+	reader := &trackingReader{
+		inner:       rawReader,
+		server:      ss,
+		id:          ss.readerCounter.Add(1),
+		bytesPerSec: bytesPerSec,
+		burstSize:   burstSize,
+		tokens:      burstSize,
+		lastFill:    time.Now(),
+	}
+
+	w.Header().Set("Content-Type", mimeTypeFromExt(provider.FileName()))
+	// "inline" for play requests (VLC/mpv), "attachment" for download requests.
+	disposition := "inline"
+	if r.URL.Query().Get("download") == "1" {
+		disposition = "attachment"
+	}
+	downloadName := provider.FileName()
+	if disposition == "attachment" {
+		ext := filepath.Ext(downloadName)
+		downloadName = strings.TrimSuffix(downloadName, ext) + " [TorrentClaw]" + ext
+	}
+	w.Header().Set("Content-Disposition", fmt.Sprintf("%s; filename=%q", disposition, downloadName))
+	w.Header().Set("Accept-Ranges", "bytes")
+
+	http.ServeContent(w, r, provider.FileName(), time.Time{}, reader)
+}
+
+// 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) {
+	total := ss.totalFileSize.Load()
+	if total <= 0 {
+		return 0, 0
+	}
+	maxOffset := ss.maxByteOffset.Load()
+	p := int(float64(maxOffset) / float64(total) * 100)
+	if p > 100 {
+		p = 100
+	}
+	return p, int(ss.durationSec.Load())
+}
+
+// --- File Providers ---
+
+// NewDiskFileProvider creates a FileProvider that serves a file from disk.
+func NewDiskFileProvider(filePath string) FileProvider {
+	return &diskFileProvider{
+		path: filePath,
+		name: filepath.Base(filePath),
+	}
+}
+
+// diskFileProvider serves a file from disk.
+type diskFileProvider struct {
+	path string
+	name string
+}
+
+func (p *diskFileProvider) NewFileReader(_ context.Context) io.ReadSeekCloser {
+	f, err := os.Open(p.path)
+	if err != nil {
+		log.Printf("[stream] failed to open %q: %v", p.path, err)
+		return nil
+	}
+	return f
+}
+
+func (p *diskFileProvider) FileName() string { return p.name }
+
+func (p *diskFileProvider) FileSize() int64 {
+	fi, err := os.Stat(p.path)
+	if err != nil {
+		log.Printf("[stream] failed to stat %q: %v", p.path, err)
+		return 0
+	}
+	return fi.Size()
+}
+
+// NewTorrentFileProvider creates a FileProvider from an active torrent file.
+func NewTorrentFileProvider(file *torrent.File) FileProvider {
+	return &torrentFileProvider{file: file}
+}
+
+// torrentFileProvider wraps a torrent.File to implement FileProvider.
 type torrentFileProvider struct {
 	file *torrent.File
 }
@@ -65,137 +710,50 @@ func (p *torrentFileProvider) FileName() string {
 	return filepath.Base(p.file.DisplayPath())
 }
 
-// diskFileProvider serves a file from disk.
-type diskFileProvider struct {
-	path string
-	name string
+func (p *torrentFileProvider) FileSize() int64 {
+	return p.file.Length()
 }
 
-func (p *diskFileProvider) NewFileReader(_ context.Context) io.ReadSeekCloser {
-	f, err := os.Open(p.path)
-	if err != nil {
-		log.Printf("stream: failed to open %q: %v", p.path, err)
+// --- Utility functions ---
+
+// FindVideoFile scans a directory (recursively) for the largest video file.
+func FindVideoFile(dir string) string {
+	var best string
+	var bestSize int64
+
+	filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil
+		}
+		ext := strings.ToLower(filepath.Ext(d.Name()))
+		if !VideoExts[ext] {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return nil
+		}
+		if info.Size() > bestSize {
+			best = path
+			bestSize = info.Size()
+		}
 		return nil
-	}
-	return f
+	})
+	return best
 }
 
-func (p *diskFileProvider) FileName() string { return p.name }
-
-// NewStreamServerFromDisk creates a server that streams a file from disk.
-func NewStreamServerFromDisk(filePath string, port int) *StreamServer {
-	return &StreamServer{
-		provider: &diskFileProvider{
-			path: filePath,
-			name: filepath.Base(filePath),
-		},
-		port: port,
-	}
-}
-
-// Start begins serving the file on all interfaces. Returns the best reachable URL:
-//  1. UPnP public IP (accessible from anywhere on the internet)
-//  2. Tailscale IP (accessible from any device in the tailnet)
-//  3. LAN IP (accessible from local network)
-func (ss *StreamServer) Start(ctx context.Context) (string, error) {
-	mux := http.NewServeMux()
-	mux.HandleFunc("/stream", ss.handler)
-
-	addr := fmt.Sprintf("0.0.0.0:%d", ss.port)
-	listener, err := net.Listen("tcp", addr)
-	if err != nil {
-		return "", fmt.Errorf("listen on %s: %w", addr, err)
-	}
-
-	// Extract actual port (important when port=0)
-	ss.port = listener.Addr().(*net.TCPAddr).Port
-
-	// Try UPnP for public internet access (like Plex Remote Access)
-	if mapping, upnpErr := setupUPnP(ss.port); upnpErr == nil {
-		ss.upnpMapping = mapping
-		ss.url = fmt.Sprintf("http://%s:%d/stream", mapping.ExternalIP, mapping.ExternalPort)
-		log.Printf("stream: UPnP mapped %s:%d -> local:%d", mapping.ExternalIP, mapping.ExternalPort, ss.port)
-	} else {
-		// Fallback: Tailscale IP > LAN IP > 127.0.0.1
-		ss.url = fmt.Sprintf("http://%s:%d/stream", reachableIP(), ss.port)
-		log.Printf("stream: UPnP unavailable (%v), using %s", upnpErr, ss.url)
-	}
-
-	ss.server = &http.Server{
-		Handler:           mux,
-		ReadHeaderTimeout: 5 * time.Second,
-	}
-
-	go func() {
-		if err := ss.server.Serve(listener); err != nil && err != http.ErrServerClosed {
-			log.Printf("stream server error: %v", err)
-		}
-	}()
-
-	return ss.url, nil
-}
-
-// URL returns the full stream URL.
-func (ss *StreamServer) URL() string { return ss.url }
-
-// Port returns the bound port.
-func (ss *StreamServer) Port() int { return ss.port }
-
-// Shutdown gracefully stops the HTTP server and removes the UPnP port mapping.
-func (ss *StreamServer) Shutdown(ctx context.Context) error {
-	ss.upnpMapping.Remove()
-	if ss.server != nil {
-		return ss.server.Shutdown(ctx)
-	}
-	return nil
-}
-
-func (ss *StreamServer) handler(w http.ResponseWriter, r *http.Request) {
-	// CORS headers — only when browser sends Origin (HTTPS site → localhost)
-	if origin := r.Header.Get("Origin"); origin != "" {
-		w.Header().Set("Access-Control-Allow-Origin", "*")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
-		w.Header().Set("Access-Control-Allow-Headers", "Range")
-		w.Header().Set("Access-Control-Expose-Headers", "Content-Length, Content-Range, Accept-Ranges")
-
-		if r.Method == http.MethodOptions {
-			w.WriteHeader(http.StatusNoContent)
-			return
-		}
-	}
-
-	reader := ss.provider.NewFileReader(r.Context())
-	if reader == nil {
-		http.Error(w, "file not found", http.StatusNotFound)
-		return
-	}
-	defer reader.Close()
-
-	w.Header().Set("Content-Type", mimeTypeFromExt(ss.provider.FileName()))
-
-	http.ServeContent(w, r, ss.provider.FileName(), time.Time{}, reader)
-}
-
-// reachableIP returns the best IP to use for the stream URL, in priority order:
-//  1. Tailscale IP (100.x.x.x) — accessible from anywhere via Tailscale mesh
-//  2. LAN IP — accessible from local network
-//  3. 127.0.0.1 — fallback (same machine only)
-func reachableIP() string {
-	// 1. Try Tailscale — gives an IP reachable from any device in the tailnet
-	if ip := tailscaleIP(); ip != "" {
-		return ip
-	}
-	// 2. Fall back to LAN IP
+// LanIP returns the machine's LAN IP, or "" if unavailable.
+func LanIP() string {
 	conn, err := net.Dial("udp", "8.8.8.8:80")
 	if err != nil {
-		return "127.0.0.1"
+		return ""
 	}
 	defer conn.Close()
 	return conn.LocalAddr().(*net.UDPAddr).IP.String()
 }
 
-// tailscaleIP returns the Tailscale IPv4 address, or "" if Tailscale isn't running.
-func tailscaleIP() string {
+// TailscaleIP returns the Tailscale IPv4 address, or "" if Tailscale isn't running.
+func TailscaleIP() string {
 	out, err := exec.Command("tailscale", "ip", "-4").Output()
 	if err != nil {
 		return ""
@@ -207,6 +765,174 @@ func tailscaleIP() string {
 	return ip
 }
 
+// trackingReader wraps an io.ReadSeekCloser with:
+//   - Progress tracking: atomically updates maxByteOffset on Read (not Seek).
+//   - Rate limiting: token bucket throttle at ~2x video bitrate so that
+//     bytes-read ≈ playback position. Without this, local/NAS files get
+//     downloaded instantly and progress jumps to 100%.
+//
+// Rate limiting happens AFTER each Read (sleep to pace), never before.
+// This ensures the client always receives data and never times out.
+type trackingReader struct {
+	inner       io.ReadSeekCloser
+	server      *StreamServer
+	id          int64 // unique ID for this reader
+	pos         int64 // current read position
+	bytesRead   int64 // total bytes read by THIS connection (measures sequential progress)
+	bytesPerSec int64 // 0 = unlimited (remote/torrent), >0 = throttled (local disk)
+
+	// Token bucket state
+	tokens    int64     // available bytes to serve (can go negative = we're ahead)
+	lastFill  time.Time // last time tokens were replenished
+	burstSize int64     // max token accumulation (caps how far ahead VLC can buffer)
+}
+
+func (t *trackingReader) Read(p []byte) (int, error) {
+	// Always read immediately — never block before serving data to the client.
+	n, err := t.inner.Read(p)
+	if n > 0 {
+		t.pos += int64(n)
+		t.bytesRead += int64(n)
+
+		// Only the reader that has read the most bytes can update progress.
+		// This prevents VLC's metadata/index requests (which read near EOF)
+		// from inflating progress to 100%.
+		if t.server.topReaderID.Load() == t.id {
+			// We own the progress — advance it (never regress)
+			for {
+				cur := t.server.maxByteOffset.Load()
+				if t.pos <= cur || t.server.maxByteOffset.CompareAndSwap(cur, t.pos) {
+					break
+				}
+			}
+		} else {
+			// Try to take over if we've read more than the current progress.
+			// CAS loop prevents two goroutines from interleaving their stores.
+			for {
+				cur := t.server.maxByteOffset.Load()
+				if t.bytesRead <= cur {
+					break
+				}
+				if t.server.maxByteOffset.CompareAndSwap(cur, t.pos) {
+					t.server.topReaderID.Store(t.id)
+					break
+				}
+			}
+		}
+
+		// Rate limit: sleep AFTER read to pace throughput.
+		if t.bytesPerSec > 0 {
+			t.fillTokens()
+			t.tokens -= int64(n)
+			if t.tokens < 0 {
+				deficit := -t.tokens
+				sleepNs := (deficit * int64(time.Second)) / t.bytesPerSec
+				if sleepNs > int64(time.Second) {
+					sleepNs = int64(time.Second)
+				}
+				time.Sleep(time.Duration(sleepNs))
+			}
+		}
+	}
+	return n, err
+}
+
+func (t *trackingReader) Seek(offset int64, whence int) (int64, error) {
+	newPos, err := t.inner.Seek(offset, whence)
+	if err == nil {
+		t.pos = newPos
+		// Don't update maxByteOffset on Seek — http.ServeContent seeks to EOF
+		// to determine size, which would instantly mark progress as 100%.
+		// Don't reset tokens — prevents clients from bypassing rate limiting
+		// by issuing repeated seeks to refill the token bucket.
+	}
+	return newPos, err
+}
+
+func (t *trackingReader) Close() error { return t.inner.Close() }
+
+func (t *trackingReader) fillTokens() {
+	now := time.Now()
+	elapsed := now.Sub(t.lastFill)
+	if elapsed <= 0 {
+		return
+	}
+	newTokens := int64(elapsed.Seconds() * float64(t.bytesPerSec))
+	t.tokens += newTokens
+	if t.tokens > t.burstSize {
+		t.tokens = t.burstSize
+	}
+	t.lastFill = now
+}
+
+// probeMedia holds bitrate and duration extracted by ffprobe.
+type probeMedia struct {
+	bitrateBps  int64 // bits per second
+	durationSec int64 // seconds
+}
+
+// probeBitrate uses ffprobe to detect the video bitrate and duration.
+// Returns zero values if ffprobe is not available or the file can't be probed.
+func probeMediaInfo(filePath string) probeMedia {
+	// Defense-in-depth: only probe regular files (not FIFOs, devices, etc.)
+	if fi, err := os.Stat(filePath); err != nil || !fi.Mode().IsRegular() {
+		return probeMedia{}
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	out, err := exec.CommandContext(ctx, "ffprobe",
+		"-v", "quiet",
+		"-print_format", "json",
+		"-show_format",
+		filePath,
+	).Output()
+	if err != nil {
+		return probeMedia{}
+	}
+
+	var result struct {
+		Format struct {
+			BitRate  string `json:"bit_rate"`
+			Duration string `json:"duration"`
+			Size     string `json:"size"`
+		} `json:"format"`
+	}
+	if err := json.Unmarshal(out, &result); err != nil {
+		return probeMedia{}
+	}
+
+	var pm probeMedia
+
+	// Parse duration
+	if result.Format.Duration != "" {
+		dur, _ := strconv.ParseFloat(result.Format.Duration, 64)
+		if dur > 0 {
+			pm.durationSec = int64(dur)
+		}
+	}
+
+	// Prefer explicit bit_rate from ffprobe
+	if result.Format.BitRate != "" {
+		bps, _ := strconv.ParseInt(result.Format.BitRate, 10, 64)
+		if bps > 0 {
+			pm.bitrateBps = bps
+			return pm
+		}
+	}
+
+	// Fallback: estimate bitrate from size / duration
+	if result.Format.Size != "" && pm.durationSec > 0 {
+		size, _ := strconv.ParseInt(result.Format.Size, 10, 64)
+		if size > 0 {
+			pm.bitrateBps = int64(float64(size) * 8 / float64(pm.durationSec))
+		}
+	}
+
+	return pm
+}
+
 func mimeTypeFromExt(filename string) string {
 	ext := strings.ToLower(filepath.Ext(filename))
 	switch ext {
diff --git a/internal/engine/stream_server_extra_test.go b/internal/engine/stream_server_extra_test.go
new file mode 100644
index 0000000..f13bd4a
--- /dev/null
+++ b/internal/engine/stream_server_extra_test.go
@@ -0,0 +1,119 @@
+package engine
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestStreamServerURLsJSON(t *testing.T) {
+	ss := &StreamServer{}
+	ss.urls = StreamURLs{LAN: "http://10.0.0.1:8000/stream", Tailscale: "http://100.64.0.1:8000/stream"}
+	got := ss.URLsJSON()
+	if !strings.Contains(got, `"lan":"http://10.0.0.1:8000/stream"`) {
+		t.Errorf("URLsJSON missing LAN: %s", got)
+	}
+	if !strings.Contains(got, `"ts":"http://100.64.0.1:8000/stream"`) {
+		t.Errorf("URLsJSON missing Tailscale: %s", got)
+	}
+}
+
+func TestStreamServerHLSBaseURLs(t *testing.T) {
+	ss := &StreamServer{}
+	ss.urls = StreamURLs{
+		LAN:       "http://10.0.0.1:8000/stream",
+		Tailscale: "http://100.64.0.1:8000/stream",
+		Public:    "http://1.2.3.4:9000/stream",
+	}
+	out := ss.hlsBaseURLs("sess-1")
+	if out.LAN != "http://10.0.0.1:8000/hls/sess-1" {
+		t.Errorf("LAN swap = %q", out.LAN)
+	}
+	if out.Tailscale != "http://100.64.0.1:8000/hls/sess-1" {
+		t.Errorf("Tailscale swap = %q", out.Tailscale)
+	}
+	if out.Public != "http://1.2.3.4:9000/hls/sess-1" {
+		t.Errorf("Public swap = %q", out.Public)
+	}
+
+	js := ss.HLSURLsJSON("sess-1")
+	if !strings.Contains(js, "/hls/sess-1") {
+		t.Errorf("HLSURLsJSON output unexpected: %s", js)
+	}
+}
+
+func TestStreamServerIdleSinceZeroBeforeActivity(t *testing.T) {
+	ss := &StreamServer{}
+	if got := ss.IdleSince(); got != 0 {
+		t.Errorf("IdleSince before any activity = %v, want 0", got)
+	}
+	ss.lastActivity.Store(time.Now().Add(-1 * time.Second).UnixNano())
+	if got := ss.IdleSince(); got <= 0 {
+		t.Errorf("IdleSince after activity should be > 0, got %v", got)
+	}
+}
+
+func TestDiskFileProvider(t *testing.T) {
+	tmp := t.TempDir() + "/movie.mp4"
+	data := []byte("hello stream")
+	if err := os.WriteFile(tmp, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	p := NewDiskFileProvider(tmp)
+	if got := p.FileName(); got != "movie.mp4" {
+		t.Errorf("FileName = %q", got)
+	}
+	if got := p.FileSize(); got != int64(len(data)) {
+		t.Errorf("FileSize = %d, want %d", got, len(data))
+	}
+	rdr := p.NewFileReader(context.Background())
+	if rdr == nil {
+		t.Fatal("NewFileReader = nil")
+	}
+	defer rdr.Close()
+	buf := make([]byte, len(data))
+	n, _ := rdr.Read(buf)
+	if string(buf[:n]) != string(data) {
+		t.Errorf("read = %q, want %q", buf[:n], data)
+	}
+}
+
+func TestDiskFileProviderMissing(t *testing.T) {
+	p := NewDiskFileProvider("/nonexistent/file.mp4")
+	if rdr := p.NewFileReader(context.Background()); rdr != nil {
+		t.Errorf("NewFileReader on missing file should return nil")
+	}
+	if got := p.FileSize(); got != 0 {
+		t.Errorf("FileSize on missing file = %d, want 0", got)
+	}
+}
+
+func TestFindVideoFile(t *testing.T) {
+	tmp := t.TempDir()
+	os.WriteFile(tmp+"/readme.txt", make([]byte, 1000), 0o644)           //nolint:errcheck
+	os.WriteFile(tmp+"/sample.mkv", make([]byte, 10*1024*1024), 0o644)   //nolint:errcheck
+	os.WriteFile(tmp+"/clip.mp4", make([]byte, 1024*1024), 0o644)        //nolint:errcheck
+	os.MkdirAll(tmp+"/sub", 0o755)                                       //nolint:errcheck
+	os.WriteFile(tmp+"/sub/extra.mp4", make([]byte, 5*1024*1024), 0o644) //nolint:errcheck
+
+	got := FindVideoFile(tmp)
+	if !strings.HasSuffix(got, "sample.mkv") {
+		t.Errorf("FindVideoFile = %q, want largest *.mkv", got)
+	}
+}
+
+func TestFindVideoFileEmpty(t *testing.T) {
+	tmp := t.TempDir()
+	if got := FindVideoFile(tmp); got != "" {
+		t.Errorf("FindVideoFile on empty dir = %q, want ''", got)
+	}
+}
+
+func TestLanIPReturnsValidOrEmpty(t *testing.T) {
+	ip := LanIP()
+	if ip != "" && !strings.Contains(ip, ".") && !strings.Contains(ip, ":") {
+		t.Errorf("LanIP returned non-empty non-IP: %q", ip)
+	}
+}
diff --git a/internal/engine/stream_server_test.go b/internal/engine/stream_server_test.go
new file mode 100644
index 0000000..46f3e8c
--- /dev/null
+++ b/internal/engine/stream_server_test.go
@@ -0,0 +1,550 @@
+package engine
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// readSeekNopCloser envuelve un strings.Reader como ReadSeekCloser.
+type readSeekNopCloser struct {
+	*strings.Reader
+}
+
+func (r *readSeekNopCloser) Close() error { return nil }
+
+func newFakeProvider(name string, content []byte) FileProvider {
+	return &fakeFileProviderSeekable{name: name, content: content}
+}
+
+// fakeFileProviderSeekable implementa FileProvider con un reader buscable.
+type fakeFileProviderSeekable struct {
+	name    string
+	content []byte
+}
+
+func (f *fakeFileProviderSeekable) FileName() string { return f.name }
+func (f *fakeFileProviderSeekable) FileSize() int64  { return int64(len(f.content)) }
+func (f *fakeFileProviderSeekable) NewFileReader(_ context.Context) io.ReadSeekCloser {
+	return &readSeekNopCloser{strings.NewReader(string(f.content))}
+}
+
+// TestStreamServer_Listen_BindsPort verifica que Listen() enlaza a un puerto
+// y URL() devuelve una URL accesible.
+func TestStreamServer_Listen_BindsPort(t *testing.T) {
+	srv := NewStreamServer(0) // puerto aleatorio
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(context.Background())
+
+	url := srv.URL()
+	if url == "" {
+		t.Fatal("URL() returned empty string after Listen()")
+	}
+	if !strings.HasPrefix(url, "http://") {
+		t.Errorf("URL() = %q, want http:// prefix", url)
+	}
+	if srv.Port() == 0 {
+		t.Error("Port() should be non-zero after Listen()")
+	}
+}
+
+// TestStreamServer_Listen_RandomPort verifica que port=0 asigna un puerto disponible.
+func TestStreamServer_Listen_RandomPort(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	port := srv.Port()
+	if port <= 0 || port > 65535 {
+		t.Errorf("Port() = %d, want valid port 1-65535", port)
+	}
+}
+
+// TestStreamServer_URL_Format verifica que la URL tiene el formato correcto
+// con host y puerto.
+func TestStreamServer_URL_Format(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	url := srv.URL()
+	port := srv.Port()
+
+	expectedSuffix := fmt.Sprintf(":%d/stream", port)
+	if !strings.Contains(url, expectedSuffix) {
+		t.Errorf("URL() = %q, want to contain %q", url, expectedSuffix)
+	}
+}
+
+// TestStreamServer_HasFile verifica que HasFile() refleja el estado correcto.
+func TestStreamServer_HasFile(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	if srv.HasFile() {
+		t.Error("HasFile() = true before SetFile(), want false")
+	}
+
+	provider := newFakeProvider("test.mkv", []byte("fake video content"))
+	srv.SetFile(provider, "task-123")
+
+	if !srv.HasFile() {
+		t.Error("HasFile() = false after SetFile(), want true")
+	}
+
+	if srv.CurrentTaskID() != "task-123" {
+		t.Errorf("CurrentTaskID() = %q, want task-123", srv.CurrentTaskID())
+	}
+}
+
+// TestStreamServer_ClearFile verifica que ClearFile() elimina el provider actual.
+func TestStreamServer_ClearFile(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	provider := newFakeProvider("video.mkv", []byte("content"))
+	srv.SetFile(provider, "task-xyz")
+
+	srv.ClearFile()
+
+	if srv.HasFile() {
+		t.Error("HasFile() = true after ClearFile(), want false")
+	}
+	if srv.CurrentTaskID() != "" {
+		t.Errorf("CurrentTaskID() = %q, want empty after ClearFile()", srv.CurrentTaskID())
+	}
+}
+
+// TestStreamServer_NoFile_Returns404 verifica que sin archivo configurado
+// el servidor devuelve 404.
+func TestStreamServer_NoFile_Returns404(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	resp, err := http.Get(srv.URL())
+	if err != nil {
+		t.Fatalf("GET %s: %v", srv.URL(), err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusNotFound {
+		t.Errorf("status = %d, want 404 when no file set", resp.StatusCode)
+	}
+}
+
+// TestStreamServer_WithFile_Returns200 verifica que con archivo configurado
+// el servidor sirve el contenido correctamente.
+func TestStreamServer_WithFile_Returns200(t *testing.T) {
+	content := []byte("fake video bytes for testing")
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	provider := newFakeProvider("movie.mkv", content)
+	srv.SetFile(provider, "task-abc")
+
+	resp, err := http.Get(srv.URL())
+	if err != nil {
+		t.Fatalf("GET %s: %v", srv.URL(), err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("status = %d, want 200", resp.StatusCode)
+	}
+
+	body, _ := io.ReadAll(resp.Body)
+	if len(body) == 0 {
+		t.Error("response body is empty, expected file content")
+	}
+}
+
+// TestStreamServer_Shutdown_ReleasesPort verifica que después de Shutdown()
+// el servidor no sigue respondiendo.
+func TestStreamServer_Shutdown_ReleasesPort(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+
+	url := srv.URL()
+
+	// Verificar que funciona antes de Shutdown
+	provider := newFakeProvider("test.mkv", []byte("data"))
+	srv.SetFile(provider, "t1")
+	resp, err := http.Get(url)
+	if err != nil {
+		t.Fatalf("GET before shutdown: %v", err)
+	}
+	resp.Body.Close()
+
+	// Shutdown
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		t.Errorf("Shutdown() error: %v", err)
+	}
+
+	// Después de shutdown, las conexiones deben fallar
+	client := &http.Client{Timeout: 500 * time.Millisecond}
+	if resp2, getErr := client.Get(url); getErr == nil {
+		resp2.Body.Close()
+		t.Error("expected error after Shutdown(), server should not be accessible")
+	}
+}
+
+// TestStreamServer_Concurrent verifica que múltiples requests concurrentes
+// son manejados correctamente.
+func TestStreamServer_Concurrent(t *testing.T) {
+	content := []byte("streaming content for concurrent access")
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	provider := newFakeProvider("concurrent.mkv", content)
+	srv.SetFile(provider, "task-concurrent")
+
+	const numRequests = 5
+	var wg sync.WaitGroup
+	errors := make([]error, numRequests)
+
+	for i := 0; i < numRequests; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			resp, err := http.Get(srv.URL())
+			if err != nil {
+				errors[idx] = err
+				return
+			}
+			defer resp.Body.Close()
+			io.ReadAll(resp.Body)
+			if resp.StatusCode != http.StatusOK {
+				errors[idx] = fmt.Errorf("request %d: status %d", idx, resp.StatusCode)
+			}
+		}(i)
+	}
+
+	wg.Wait()
+
+	for i, err := range errors {
+		if err != nil {
+			t.Errorf("concurrent request %d failed: %v", i, err)
+		}
+	}
+}
+
+// TestStreamServer_SetFile_SwapsProvider verifica que SetFile() reemplaza
+// el provider anterior correctamente.
+func TestStreamServer_SetFile_SwapsProvider(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	// Primer archivo
+	p1 := newFakeProvider("first.mkv", []byte("first content"))
+	srv.SetFile(p1, "task-1")
+
+	if srv.CurrentTaskID() != "task-1" {
+		t.Errorf("after first SetFile: taskID = %q, want task-1", srv.CurrentTaskID())
+	}
+
+	// Swap a segundo archivo
+	p2 := newFakeProvider("second.mkv", []byte("second content"))
+	srv.SetFile(p2, "task-2")
+
+	if srv.CurrentTaskID() != "task-2" {
+		t.Errorf("after second SetFile: taskID = %q, want task-2", srv.CurrentTaskID())
+	}
+}
+
+// TestStreamServer_Health_NoFile verifica que /health devuelve streaming:false
+// cuando no hay archivo configurado.
+func TestStreamServer_Health_NoFile(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	healthURL := fmt.Sprintf("http://127.0.0.1:%d/health", srv.Port())
+	resp, err := http.Get(healthURL)
+	if err != nil {
+		t.Fatalf("GET /health: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("status = %d, want 200", resp.StatusCode)
+	}
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "application/json") {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+
+	body, _ := io.ReadAll(resp.Body)
+	bodyStr := string(body)
+	if !strings.Contains(bodyStr, `"streaming":false`) {
+		t.Errorf("body = %q, want streaming:false", bodyStr)
+	}
+	if !strings.Contains(bodyStr, `"status":"ok"`) {
+		t.Errorf("body = %q, want status:ok", bodyStr)
+	}
+}
+
+// TestStreamServer_Health_WithFile verifica que /health devuelve streaming:true
+// y el nombre del archivo cuando hay un archivo configurado.
+func TestStreamServer_Health_WithFile(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	provider := newFakeProvider("pelicula.mkv", []byte("contenido de prueba"))
+	srv.SetFile(provider, "task-health-test")
+
+	healthURL := fmt.Sprintf("http://127.0.0.1:%d/health", srv.Port())
+	resp, err := http.Get(healthURL)
+	if err != nil {
+		t.Fatalf("GET /health: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("status = %d, want 200", resp.StatusCode)
+	}
+
+	body, _ := io.ReadAll(resp.Body)
+	bodyStr := string(body)
+	if !strings.Contains(bodyStr, `"streaming":true`) {
+		t.Errorf("body = %q, want streaming:true", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "pelicula.mkv") {
+		t.Errorf("body = %q, want file name pelicula.mkv", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "task-hea") { // primeros 8 chars de "task-health-test"
+		t.Errorf("body = %q, want task short ID", bodyStr)
+	}
+}
+
+// TestStreamServer_Health_NonLoopback_NoLeak verifica que /health no revela
+// nombre de fichero, taskID ni client IP cuando el caller no es loopback.
+// Protección contra reconnaissance vía LAN / UPnP / Tailscale.
+func TestStreamServer_Health_NonLoopback_NoLeak(t *testing.T) {
+	srv := NewStreamServer(0) // UPnP off by default — keep test hermetic
+	ctx := context.Background()
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	provider := newFakeProvider("secret.mkv", []byte("data"))
+	srv.SetFile(provider, "secret-task-id")
+
+	cases := []struct {
+		name       string
+		remoteAddr string
+	}{
+		{"lan_ipv4", "192.168.1.50:54321"},
+		{"empty_host_no_bypass", ":54321"},
+		{"public_ipv4", "203.0.113.10:443"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			rr := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodGet, "/health", nil)
+			req.RemoteAddr = tc.remoteAddr
+			srv.healthHandler(rr, req)
+
+			body := rr.Body.String()
+			if !strings.Contains(body, `"status":"ok"`) {
+				t.Errorf("body missing status:ok: %q", body)
+			}
+			if !strings.Contains(body, `"streaming":true`) {
+				t.Errorf("body should report streaming bool: %q", body)
+			}
+			if strings.Contains(body, "secret.mkv") {
+				t.Errorf("body leaked filename: %q", body)
+			}
+			if strings.Contains(body, "secret-t") {
+				t.Errorf("body leaked task id: %q", body)
+			}
+			if strings.Contains(body, "192.168.1.50") || strings.Contains(body, "203.0.113.10") {
+				t.Errorf("body leaked client ip: %q", body)
+			}
+		})
+	}
+}
+
+// TestStreamServer_CORS_Allowlist verifica que sólo los origenes en la
+// allowlist reciben Access-Control-Allow-Origin y que ningún otro origen
+// es eco-reflejado.
+func TestStreamServer_CORS_Allowlist(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	cases := []struct {
+		origin    string
+		wantAllow bool
+	}{
+		{"https://app.torrentclaw.com", true},
+		{"https://torrentclaw.com", true},
+		{"http://localhost:3030", true},
+		{"http://127.0.0.1:3030", true},
+		{"https://evil.example", false},
+		{"null", false},
+		{"", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.origin, func(t *testing.T) {
+			rr := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodOptions, "/health", nil)
+			if tc.origin != "" {
+				req.Header.Set("Origin", tc.origin)
+			}
+			srv.healthHandler(rr, req)
+			got := rr.Header().Get("Access-Control-Allow-Origin")
+			if tc.wantAllow {
+				if got != tc.origin {
+					t.Errorf("origin %q: ACAO = %q, want %q", tc.origin, got, tc.origin)
+				}
+			} else if got != "" {
+				t.Errorf("origin %q: ACAO leaked as %q, expected empty", tc.origin, got)
+			}
+		})
+	}
+}
+
+// TestStreamServer_CORS_ExtraOrigin verifica que SetCORSAllowedOrigins añade
+// origins al baseline sin removerlos.
+func TestStreamServer_CORS_ExtraOrigin(t *testing.T) {
+	srv := NewStreamServer(0)
+	srv.SetCORSAllowedOrigins([]string{"https://custom.example"})
+	ctx := context.Background()
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	for _, origin := range []string{"https://custom.example", "https://torrentclaw.com"} {
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/health", nil)
+		req.Header.Set("Origin", origin)
+		srv.healthHandler(rr, req)
+		if got := rr.Header().Get("Access-Control-Allow-Origin"); got != origin {
+			t.Errorf("origin %q: ACAO = %q", origin, got)
+		}
+	}
+}
+
+// TestStreamServer_HLS_InvalidSessionID verifica que el hlsHandler rechaza
+// session IDs con caracteres ilegales devolviendo 404 (uniforme con sesión
+// inexistente) para no filtrar el formato aceptado a un attacker.
+func TestStreamServer_HLS_InvalidSessionID(t *testing.T) {
+	srv := NewStreamServer(0) // UPnP off by default — keep test hermetic
+	ctx := context.Background()
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	bad := []string{
+		"/hls/..%2Fetc%2Fpasswd/master.m3u8",
+		"/hls/foo.bar/master.m3u8",
+		"/hls/foo%20bar/master.m3u8",
+		"/hls/foo%2Fbar/master.m3u8",
+	}
+	for _, path := range bad {
+		t.Run(path, func(t *testing.T) {
+			rr := httptest.NewRecorder()
+			req := httptest.NewRequest(http.MethodGet, path, nil)
+			srv.hlsHandler(rr, req)
+			if rr.Code != http.StatusNotFound {
+				t.Errorf("path %q: status = %d, want 404", path, rr.Code)
+			}
+		})
+	}
+}
+
+// TestStreamServer_MKV_ContentType verifica que el Content-Type para .mkv
+// es el correcto.
+func TestStreamServer_MKV_ContentType(t *testing.T) {
+	srv := NewStreamServer(0)
+	ctx := context.Background()
+
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("Listen() error: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+
+	provider := newFakeProvider("movie.mkv", []byte("mkv content"))
+	srv.SetFile(provider, "task-mkv")
+
+	resp, err := http.Get(srv.URL())
+	if err != nil {
+		t.Fatalf("GET: %v", err)
+	}
+	defer resp.Body.Close()
+
+	ct := resp.Header.Get("Content-Type")
+	if !strings.Contains(ct, "matroska") && !strings.Contains(ct, "mkv") {
+		t.Errorf("Content-Type = %q, want matroska/mkv MIME type", ct)
+	}
+}
diff --git a/internal/engine/stream_source.go b/internal/engine/stream_source.go
new file mode 100644
index 0000000..b418e61
--- /dev/null
+++ b/internal/engine/stream_source.go
@@ -0,0 +1,347 @@
+package engine
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"time"
+)
+
+// streamSource abstracts the byte source consumed by the HLS transcoder.
+// Two implementations:
+//   - diskFileSource — direct passthrough of the on-disk file.
+//   - transcodeSource — ffmpeg writes a fragmented MP4 to a temp file in
+//     real time; reads block briefly when callers ask for bytes ahead of
+//     the writer.
+type streamSource interface {
+	ReadAt(p []byte, off int64) (int, error)
+	// Size returns the currently known size. For transcoded sources this
+	// grows as ffmpeg produces output; on Final() it's the final size.
+	Size() int64
+	// Final reports whether the source size is now stable (passthrough is
+	// always final, transcoder becomes final when ffmpeg exits).
+	Final() bool
+	// EstimatedSize returns the final size we expect to converge on. For
+	// passthrough it's the same as Size(). For transcoder it's a bitrate
+	// × duration estimate so the browser scrubber has something to anchor
+	// on; the real size will differ ±20%.
+	EstimatedSize() int64
+	FileName() string
+	Transcoded() bool
+	Close() error
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// disk passthrough
+// ─────────────────────────────────────────────────────────────────────────────
+
+type diskFileSource struct {
+	f    *os.File
+	size int64
+	name string
+}
+
+func newDiskFileSource(path string) (*diskFileSource, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("stream source: open %s: %w", path, err)
+	}
+	stat, err := f.Stat()
+	if err != nil {
+		f.Close()
+		return nil, fmt.Errorf("stream source: stat %s: %w", path, err)
+	}
+	return &diskFileSource{f: f, size: stat.Size(), name: filepath.Base(path)}, nil
+}
+
+func (d *diskFileSource) ReadAt(p []byte, off int64) (int, error) {
+	return d.f.ReadAt(p, off)
+}
+func (d *diskFileSource) Size() int64          { return d.size }
+func (d *diskFileSource) Final() bool          { return true }
+func (d *diskFileSource) EstimatedSize() int64 { return d.size }
+func (d *diskFileSource) FileName() string     { return d.name }
+func (d *diskFileSource) Transcoded() bool     { return false }
+func (d *diskFileSource) Close() error         { return d.f.Close() }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// transcode source — ffmpeg → tmp file
+// ─────────────────────────────────────────────────────────────────────────────
+
+type transcodeSource struct {
+	tmpPath  string
+	tmpFile  *os.File
+	cmd      *Transcoder
+	name     string
+	estimate int64
+
+	ctx       context.Context
+	notify    chan struct{} // size grew or final flipped; cap=1, non-blocking send
+	size      atomic.Int64
+	final     atomic.Bool
+	failure   atomic.Pointer[error]
+	startedAt time.Time
+}
+
+const (
+	// readBlockTimeout caps how long ReadAt waits for bytes that haven't
+	// been transcoded yet before returning EOF/io.ErrUnexpectedEOF. The
+	// pump treats EOF as "respond with whatever we have so far + RangeEnd"
+	// so the browser can re-request once more bytes appear.
+	readBlockTimeout = 30 * time.Second
+)
+
+func newTranscodeSource(
+	ctx context.Context,
+	srcPath string,
+	probe *StreamProbe,
+	action TranscodeAction,
+	opts TranscodeOpts,
+	displayName string,
+) (*transcodeSource, error) {
+	tmpFile, err := os.CreateTemp("", "tc-stream-*.mp4")
+	if err != nil {
+		return nil, fmt.Errorf("transcode source: tmp file: %w", err)
+	}
+	tmpPath := tmpFile.Name()
+	tmpFile.Close()
+
+	args := buildFFmpegArgs(srcPath, opts)
+	// Override -f mp4 pipe:1 with output to our tmp file path (last 3 args).
+	if len(args) >= 3 && args[len(args)-1] == "pipe:1" {
+		args[len(args)-1] = tmpPath
+	}
+
+	// Spawn ffmpeg directly (not via NewTranscoder pipe) so it writes to
+	// disk in real time. We re-use the rest of TranscodeOpts wiring.
+	cmd, err := startTranscoderToFile(ctx, opts.FFmpegPath, args, nil)
+	if err != nil {
+		os.Remove(tmpPath)
+		return nil, err
+	}
+
+	estimate := estimateOutputSize(probe, opts)
+
+	t := &transcodeSource{
+		tmpPath:   tmpPath,
+		cmd:       cmd,
+		name:      displayName,
+		estimate:  estimate,
+		ctx:       ctx,
+		notify:    make(chan struct{}, 1),
+		startedAt: time.Now(),
+	}
+
+	// Re-open the tmp file for reading; ffmpeg keeps writing to it.
+	rf, err := os.Open(tmpPath)
+	if err != nil {
+		_ = cmd.Close()
+		os.Remove(tmpPath)
+		return nil, fmt.Errorf("transcode source: reopen tmp: %w", err)
+	}
+	t.tmpFile = rf
+
+	go t.watchSize(ctx)
+	go t.watchExit()
+	return t, nil
+}
+
+// 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
+// produces correct behaviour).
+func (t *transcodeSource) signalNotify() {
+	select {
+	case t.notify <- struct{}{}:
+	default:
+	}
+}
+
+// watchSize polls the temp file size every 200 ms and wakes any blocked
+// ReadAt callers once new bytes arrive.
+func (t *transcodeSource) watchSize(ctx context.Context) {
+	ticker := time.NewTicker(200 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			t.signalNotify()
+			return
+		case <-ticker.C:
+		}
+		if t.final.Load() {
+			t.signalNotify()
+			return
+		}
+		stat, err := os.Stat(t.tmpPath)
+		if err != nil {
+			continue
+		}
+		current := stat.Size()
+		if current > t.size.Load() {
+			t.size.Store(current)
+			t.signalNotify()
+		}
+	}
+}
+
+// watchExit waits for ffmpeg to exit (via Transcoder's single-Wait goroutine)
+// and locks in the final size. A kill triggered by Close() is NOT a failure.
+func (t *transcodeSource) watchExit() {
+	<-t.cmd.Done()
+	err := t.cmd.WaitErr()
+	if err != nil && !t.cmd.IsClosing() {
+		failure := fmt.Errorf("ffmpeg exited: %w (%s)", err, t.cmd.Stderr())
+		t.failure.Store(&failure)
+	}
+	if stat, err := os.Stat(t.tmpPath); err == nil {
+		t.size.Store(stat.Size())
+	}
+	t.final.Store(true)
+	t.signalNotify()
+}
+
+// loadFailure returns the current failure (or nil) without taking a lock.
+func (t *transcodeSource) loadFailure() error {
+	if p := t.failure.Load(); p != nil {
+		return *p
+	}
+	return nil
+}
+
+func (t *transcodeSource) ReadAt(p []byte, off int64) (int, error) {
+	if err := t.loadFailure(); err != nil {
+		return 0, err
+	}
+	if len(p) == 0 {
+		return 0, nil
+	}
+	if off < 0 {
+		return 0, fmt.Errorf("transcode source: negative offset %d", off)
+	}
+	want := int64(len(p))
+
+	deadline := time.Now().Add(readBlockTimeout)
+	for {
+		if t.final.Load() {
+			break
+		}
+		size := t.size.Load()
+		// Overflow-safe form of "off + want <= size":
+		if size >= off && size-off >= want {
+			break
+		}
+		remaining := time.Until(deadline)
+		if remaining <= 0 {
+			break
+		}
+		wait := 500 * time.Millisecond
+		if remaining < wait {
+			wait = remaining
+		}
+		select {
+		case <-t.ctx.Done():
+			return 0, t.ctx.Err()
+		case <-t.notify:
+		case <-time.After(wait):
+		}
+	}
+
+	if err := t.loadFailure(); err != nil {
+		return 0, err
+	}
+
+	n, err := t.tmpFile.ReadAt(p, off)
+	// On a growing file ReadAt returns io.EOF when reading past current size.
+	// Translate that into "send what we have, RangeEnd will follow" by
+	// returning (n, nil) so the pump treats the data as a partial chunk and
+	// caller re-requests once more bytes appear. Only true EOF (final=true)
+	// propagates as io.EOF.
+	if err == io.EOF && !t.final.Load() {
+		if n > 0 {
+			return n, nil
+		}
+		return 0, errors.New("transcode source: read timed out waiting for ffmpeg output")
+	}
+	return n, err
+}
+
+func (t *transcodeSource) Size() int64 { return t.size.Load() }
+func (t *transcodeSource) Final() bool { return t.final.Load() }
+func (t *transcodeSource) EstimatedSize() int64 {
+	if t.final.Load() {
+		return t.size.Load()
+	}
+	return t.estimate
+}
+func (t *transcodeSource) FileName() string {
+	// Output is always fragmented MP4 regardless of source extension.
+	return strings.TrimSuffix(t.name, filepath.Ext(t.name)) + ".mp4"
+}
+func (t *transcodeSource) Transcoded() bool { return true }
+func (t *transcodeSource) Close() error {
+	var errs []error
+	if err := t.cmd.Close(); err != nil {
+		errs = append(errs, err)
+	}
+	if t.tmpFile != nil {
+		if err := t.tmpFile.Close(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if t.tmpPath != "" {
+		if err := os.Remove(t.tmpPath); err != nil && !os.IsNotExist(err) {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
+}
+
+// estimateOutputSize converts probed bitrate × duration into a byte estimate
+// so the browser scrubber has something to anchor on while transcoding.
+func estimateOutputSize(probe *StreamProbe, opts TranscodeOpts) int64 {
+	if probe == nil || probe.DurationSec <= 0 {
+		return 0
+	}
+	videoKbps := parseBitrateKbps(opts.VideoBitrate, 5000)
+	audioKbps := parseBitrateKbps(opts.AudioBitrate, 192)
+	totalKbps := videoKbps + audioKbps
+	bytesPerSec := int64(totalKbps) * 1000 / 8
+	return int64(probe.DurationSec) * bytesPerSec
+}
+
+// parseBitrateKbps converts ffmpeg-style bitrate strings ("5M", "192k") to
+// kilobits per second. Unknown formats fall back to fallback.
+func parseBitrateKbps(s string, fallback int) int {
+	if s == "" {
+		return fallback
+	}
+	last := s[len(s)-1]
+	num := s
+	mult := 1
+	switch last {
+	case 'k', 'K':
+		num = s[:len(s)-1]
+	case 'M', 'm':
+		num = s[:len(s)-1]
+		mult = 1000
+	default:
+		// already in bps? treat as kbps
+	}
+	v := 0
+	for _, c := range num {
+		if c < '0' || c > '9' {
+			return fallback
+		}
+		v = v*10 + int(c-'0')
+	}
+	if v == 0 {
+		return fallback
+	}
+	return v * mult
+}
diff --git a/internal/engine/stream_source_test.go b/internal/engine/stream_source_test.go
new file mode 100644
index 0000000..c1214b0
--- /dev/null
+++ b/internal/engine/stream_source_test.go
@@ -0,0 +1,90 @@
+package engine
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestParseBitrateKbps(t *testing.T) {
+	cases := []struct {
+		in   string
+		fb   int
+		want int
+	}{
+		{"", 5000, 5000},
+		{"192k", 0, 192},
+		{"192K", 0, 192},
+		{"5M", 0, 5000},
+		{"5m", 0, 5000},
+		{"4500", 0, 4500},
+		{"bogus", 100, 100},
+		{"0k", 100, 100},
+	}
+	for _, tc := range cases {
+		t.Run(tc.in, func(t *testing.T) {
+			if got := parseBitrateKbps(tc.in, tc.fb); got != tc.want {
+				t.Errorf("parseBitrateKbps(%q,%d) = %d, want %d", tc.in, tc.fb, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestEstimateOutputSize(t *testing.T) {
+	if got := estimateOutputSize(nil, TranscodeOpts{}); got != 0 {
+		t.Errorf("nil probe -> 0, got %d", got)
+	}
+	if got := estimateOutputSize(&StreamProbe{}, TranscodeOpts{}); got != 0 {
+		t.Errorf("zero duration -> 0, got %d", got)
+	}
+	probe := &StreamProbe{DurationSec: 60}
+	opts := TranscodeOpts{VideoBitrate: "5M", AudioBitrate: "192k"}
+	// (5000 + 192) * 1000 / 8 = 649_000 bytes/s; *60 = 38_940_000
+	got := estimateOutputSize(probe, opts)
+	if got != 38_940_000 {
+		t.Errorf("estimateOutputSize = %d, want 38_940_000", got)
+	}
+}
+
+func TestDiskFileSourceLifecycle(t *testing.T) {
+	tmp := t.TempDir()
+	path := filepath.Join(tmp, "movie.bin")
+	data := []byte("hello world")
+	if err := os.WriteFile(path, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	src, err := newDiskFileSource(path)
+	if err != nil {
+		t.Fatalf("newDiskFileSource: %v", err)
+	}
+	defer src.Close()
+
+	if src.Size() != int64(len(data)) {
+		t.Errorf("Size = %d, want %d", src.Size(), len(data))
+	}
+	if src.EstimatedSize() != src.Size() {
+		t.Errorf("EstimatedSize should equal Size for disk source")
+	}
+	if !src.Final() {
+		t.Errorf("disk source should be Final")
+	}
+	if src.Transcoded() {
+		t.Errorf("disk source should not report Transcoded")
+	}
+	if src.FileName() != "movie.bin" {
+		t.Errorf("FileName = %q", src.FileName())
+	}
+
+	buf := make([]byte, 5)
+	n, err := src.ReadAt(buf, 6)
+	if err != nil || n != 5 || string(buf) != "world" {
+		t.Errorf("ReadAt = (%d,%v,%q), want (5,nil,'world')", n, err, buf)
+	}
+}
+
+func TestDiskFileSourceMissing(t *testing.T) {
+	if _, err := newDiskFileSource("/nonexistent/movie.bin"); err == nil {
+		t.Error("expected error opening nonexistent file")
+	}
+}
diff --git a/internal/engine/stream_test.go b/internal/engine/stream_test.go
index 8357a5a..df473a0 100644
--- a/internal/engine/stream_test.go
+++ b/internal/engine/stream_test.go
@@ -189,16 +189,28 @@ func TestStreamServerStartShutdown(t *testing.T) {
 		totalBytes: 1024,
 	}
 
-	srv := NewStreamServer(s, 0)
+	srv := NewStreamServer(0)
 	if srv.Port() != 0 {
 		t.Errorf("initial port should be 0, got %d", srv.Port())
 	}
 
-	// We can't Start() because NewFileReader needs a real torrent File
-	// But we can test that Shutdown on an un-started server doesn't panic
+	// Test that Shutdown on an un-started server doesn't panic
 	if err := srv.Shutdown(context.Background()); err != nil {
 		t.Errorf("shutdown of un-started server should not error: %v", err)
 	}
+
+	// Test SetFile/ClearFile
+	srv.SetFile(s, "test-task-id")
+	if !srv.HasFile() {
+		t.Error("HasFile should be true after SetFile")
+	}
+	if srv.CurrentTaskID() != "test-task-id" {
+		t.Errorf("CurrentTaskID = %q, want %q", srv.CurrentTaskID(), "test-task-id")
+	}
+	srv.ClearFile()
+	if srv.HasFile() {
+		t.Error("HasFile should be false after ClearFile")
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -368,3 +380,31 @@ func (r *responseRecorder) ReadFrom(src io.Reader) (int64, error) {
 	n, err := io.Copy(r.body, src)
 	return n, err
 }
+
+// TestPrioritizeTail_SmallFile verifica que PrioritizeTail no lanza goroutine
+// cuando el archivo es demasiado pequeño (≤ 2×tailBytes).
+func TestPrioritizeTail_SmallFile(t *testing.T) {
+	s := &StreamEngine{
+		totalBytes: 5 * 1024 * 1024, // 5 MB — menor que 2×5 MB
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	// No debe entrar en pánico ni bloquear con file == nil
+	s.PrioritizeTail(ctx, 5*1024*1024)
+	// Si llega aquí sin pánico, el test pasa
+}
+
+// TestPrioritizeTail_NilFile verifica que PrioritizeTail es seguro cuando
+// file es nil (engine no inicializado).
+func TestPrioritizeTail_NilFile(t *testing.T) {
+	s := &StreamEngine{
+		totalBytes: 100 * 1024 * 1024,
+		file:       nil,
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	s.PrioritizeTail(ctx, 5*1024*1024)
+	// No debe entrar en pánico
+}
diff --git a/internal/engine/task.go b/internal/engine/task.go
index d07a689..09621e8 100644
--- a/internal/engine/task.go
+++ b/internal/engine/task.go
@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"sync"
 	"time"
+	"unicode/utf8"
 
 	"github.com/torrentclaw/unarr/internal/agent"
 )
@@ -52,6 +53,12 @@ type Task struct {
 	NzbPassword     string // Password for encrypted NZB archives
 	ReplacePath     string // File to replace after download (upgrade mode)
 	LibraryItemID   int    // Library item being upgraded
+	ContentType     string // "movie" | "show" — from server metadata
+	ContentTitle    string // Clean title from TMDB
+	Season          *int   // Season number
+	Episode         *int   // Episode number
+	ContentYear     *int   // Year from TMDB (avoids regex on torrent title)
+	CollectionName  string // Collection name (e.g., "Harry Potter Collection")
 
 	// Runtime state
 	Status          TaskStatus
@@ -92,6 +99,12 @@ func NewTaskFromAgent(at agent.Task) *Task {
 		NzbPassword:     at.NzbPassword,
 		ReplacePath:     at.ReplacePath,
 		LibraryItemID:   at.LibraryItemID,
+		ContentType:     at.ContentType,
+		ContentTitle:    at.ContentTitle,
+		ContentYear:     at.ContentYear,
+		Season:          at.Season,
+		Episode:         at.Episode,
+		CollectionName:  at.CollectionName,
 		Mode:            mode,
 		Status:          StatusClaimed,
 		ClaimedAt:       time.Now(),
@@ -195,10 +208,20 @@ func (t *Task) ToStatusUpdate() agent.StatusUpdate {
 		// StatusPending, StatusClaimed, StatusCancelled — not reported
 	}
 
+	// Compute percent inline — do NOT call t.Percent() here since we already hold RLock.
+	// Calling Percent() (which also RLocks) while holding RLock deadlocks when a writer is waiting.
+	percent := 0
+	if t.TotalBytes > 0 {
+		percent = int(float64(t.DownloadedBytes) / float64(t.TotalBytes) * 100)
+		if percent > 100 {
+			percent = 100
+		}
+	}
+
 	return agent.StatusUpdate{
 		TaskID:          t.ID,
 		Status:          apiStatus,
-		Progress:        t.Percent(),
+		Progress:        percent,
 		DownloadedBytes: t.DownloadedBytes,
 		TotalBytes:      t.TotalBytes,
 		SpeedBps:        t.SpeedBps,
@@ -207,10 +230,25 @@ func (t *Task) ToStatusUpdate() agent.StatusUpdate {
 		FileName:        t.FileName,
 		FilePath:        t.FilePath,
 		StreamURL:       t.StreamURL,
-		ErrorMessage:    t.ErrorMessage,
+		// Cap to the server's stored length. A failed extract can carry a
+		// multi-KB unrar/par2 dump; sending it raw made /agent/status 400
+		// the whole report, leaving the task stuck non-terminal.
+		ErrorMessage: truncateMsg(t.ErrorMessage, 2000),
 	}
 }
 
+// truncateMsg caps s to at most max bytes without splitting a UTF-8 rune.
+func truncateMsg(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	cut := max
+	for cut > 0 && !utf8.RuneStart(s[cut]) {
+		cut--
+	}
+	return s[:cut]
+}
+
 // MagnetURI builds a magnet link from the info hash.
 func (t *Task) MagnetURI() string {
 	return "magnet:?xt=urn:btih:" + t.InfoHash
diff --git a/internal/engine/torrent.go b/internal/engine/torrent.go
index 16d4150..f4b1b6d 100644
--- a/internal/engine/torrent.go
+++ b/internal/engine/torrent.go
@@ -17,6 +17,7 @@ import (
 	"github.com/anacrolix/torrent"
 	"github.com/anacrolix/torrent/storage"
 	"github.com/torrentclaw/unarr/internal/config"
+	"github.com/torrentclaw/unarr/internal/vpn"
 	"golang.org/x/term"
 	"golang.org/x/time/rate"
 )
@@ -70,6 +71,11 @@ type TorrentConfig struct {
 	SeedEnabled     bool
 	SeedRatio       float64       // target seed ratio (default 0, meaning seed until SeedTime)
 	SeedTime        time.Duration // min seed time after completion (default 0)
+
+	// VPNTunnel, when set, split-tunnels the torrent client's peer + tracker
+	// traffic through an in-process userspace WireGuard tunnel (managed-VPN
+	// add-on). nil = downloads in the clear. Brought up by the daemon.
+	VPNTunnel *vpn.Tunnel
 }
 
 // TorrentDownloader downloads torrents via BitTorrent P2P.
@@ -97,7 +103,10 @@ func NewTorrentDownloader(cfg TorrentConfig) (*TorrentDownloader, error) {
 	tcfg.DataDir = cfg.DataDir
 	tcfg.Seed = cfg.SeedEnabled
 	tcfg.NoUpload = !cfg.SeedEnabled
-	tcfg.Logger = alog.Default.FilterLevel(alog.Critical)
+	tcfg.Logger = alog.Default.FilterLevel(alog.Warning)
+
+	// No browser-facing WebTorrent peer; daemon never seeds via WSS.
+	tcfg.DisableWebtorrent = true
 
 	// --- Performance optimizations ---
 
@@ -191,6 +200,20 @@ func NewTorrentDownloader(cfg TorrentConfig) (*TorrentDownloader, error) {
 	// Re-announce active torrents to DHT periodically (keeps routing table healthy).
 	tcfg.PeriodicallyAnnounceTorrentsToDht = true
 
+	// --- Managed-VPN split-tunnel ---
+	// Route the torrent client's outbound peer + tracker traffic through the
+	// in-process WireGuard tunnel so the swarm + trackers see the VPN IP, not
+	// the user's. unarr's control plane keeps using the normal net. uTP (UDP
+	// peers) is disabled — TCP peers + HTTP/UDP tracker announces are tunnelled;
+	// inbound peers don't apply (leech-only, no port forward).
+	if cfg.VPNTunnel != nil {
+		tcfg.DisableUTP = true
+		tcfg.TrackerDialContext = cfg.VPNTunnel.Net.DialContext
+		tcfg.HTTPDialContext = cfg.VPNTunnel.Net.DialContext
+		tcfg.TrackerListenPacket = cfg.VPNTunnel.ListenPacket
+		log.Printf("[torrent] VPN split-tunnel enabled (peer + tracker traffic routed through WireGuard)")
+	}
+
 	// Try to create client; if the port is in use, try the next few ports.
 	var client *torrent.Client
 	var err error
@@ -212,6 +235,12 @@ func NewTorrentDownloader(cfg TorrentConfig) (*TorrentDownloader, error) {
 		log.Printf("[torrent] listening on port %d (configured: %d was busy)", tcfg.ListenPort, listenPort)
 	}
 
+	// Route outgoing peer dials through the VPN tunnel (TCP). Added after client
+	// creation; DialForPeerConns defaults to true so this is used for peers.
+	if cfg.VPNTunnel != nil {
+		client.AddDialer(torrent.NetworkDialer{Network: "tcp", Dialer: cfg.VPNTunnel.Net})
+	}
+
 	// Restore DHT nodes with full node IDs (direct routing table insertion, no async pings).
 	for _, s := range client.DhtServers() {
 		if w, ok := s.(torrent.AnacrolixDhtServerWrapper); ok {
@@ -235,7 +264,7 @@ func (d *TorrentDownloader) Available(_ context.Context, task *Task) (bool, erro
 }
 
 func (d *TorrentDownloader) Download(ctx context.Context, task *Task, outputDir string, progressCh chan<- Progress) (*Result, error) {
-	magnet := buildMagnet(task.InfoHash)
+	magnet := d.buildMagnet(task.InfoHash)
 
 	t, err := d.client.AddMagnet(magnet)
 	if err != nil {
@@ -502,10 +531,9 @@ func (d *TorrentDownloader) SaveDhtNodes() {
 	saveDhtNodesBinary(d.client)
 }
 
-// StartStream starts an HTTP server for an active torrent download.
-// It selects the largest video file and serves it via HTTP Range requests.
-// Returns the running server (caller is responsible for shutdown).
-func (d *TorrentDownloader) StartStream(taskID string) (*StreamServer, error) {
+// GetStreamProvider returns a FileProvider for the largest video file in an active torrent.
+// Used with the persistent StreamServer's SetFile() method.
+func (d *TorrentDownloader) GetStreamProvider(taskID string) (FileProvider, error) {
 	d.activeMu.Lock()
 	t, ok := d.active[taskID]
 	d.activeMu.Unlock()
@@ -535,14 +563,7 @@ func (d *TorrentDownloader) StartStream(taskID string) (*StreamServer, error) {
 		return nil, fmt.Errorf("torrent has no files")
 	}
 
-	srv := NewStreamServerFromFile(video, 0)
-	url, err := srv.Start(context.Background())
-	if err != nil {
-		return nil, fmt.Errorf("start stream server: %w", err)
-	}
-
-	log.Printf("[%s] stream started: %s → %s", taskID[:8], filepath.Base(video.DisplayPath()), url)
-	return srv, nil
+	return NewTorrentFileProvider(video), nil
 }
 
 // VideoExts is the canonical set of video file extensions used for file selection.
@@ -612,6 +633,8 @@ func (d *TorrentDownloader) selectFiles(t *torrent.Torrent, taskID string) (tota
 	return totalBytes, fileName
 }
 
+// buildMagnet composes a magnet URI for the info hash with the static
+// tracker list.
 func buildMagnet(infoHash string) string {
 	params := []string{"xt=urn:btih:" + infoHash}
 	for _, tracker := range defaultTrackers {
@@ -620,6 +643,10 @@ func buildMagnet(infoHash string) string {
 	return "magnet:?" + strings.Join(params, "&")
 }
 
+func (d *TorrentDownloader) buildMagnet(infoHash string) string {
+	return buildMagnet(infoHash)
+}
+
 func formatBytes(b int64) string {
 	const unit = 1024
 	if b < unit {
diff --git a/internal/engine/torrent_test.go b/internal/engine/torrent_test.go
new file mode 100644
index 0000000..a785651
--- /dev/null
+++ b/internal/engine/torrent_test.go
@@ -0,0 +1,266 @@
+package engine
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// TestNewTorrentDownloader_ValidConfig verifica que se puede crear un downloader
+// con una configuración válida sin errores.
+func TestNewTorrentDownloader_ValidConfig(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{DataDir: dir})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader failed: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+}
+
+// TestTorrentDownloader_Method verifica que Method() devuelve "torrent".
+func TestTorrentDownloader_Method(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{DataDir: dir})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	if dl.Method() != MethodTorrent {
+		t.Errorf("Method() = %q, want %q", dl.Method(), MethodTorrent)
+	}
+}
+
+// TestTorrentDownloader_Available_WithInfoHash verifica que Available() devuelve
+// true cuando la tarea tiene un infoHash.
+func TestTorrentDownloader_Available_WithInfoHash(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{DataDir: dir})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	task := &Task{InfoHash: "abc123def456abc123def456abc123def456abc1"}
+	ok, err := dl.Available(context.Background(), task)
+	if err != nil {
+		t.Fatalf("Available: %v", err)
+	}
+	if !ok {
+		t.Error("Available() = false, want true when infoHash is set")
+	}
+}
+
+// TestTorrentDownloader_Available_WithoutInfoHash verifica que Available() devuelve
+// false cuando la tarea no tiene infoHash.
+func TestTorrentDownloader_Available_WithoutInfoHash(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{DataDir: dir})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	task := &Task{InfoHash: ""}
+	ok, err := dl.Available(context.Background(), task)
+	if err != nil {
+		t.Fatalf("Available: %v", err)
+	}
+	if ok {
+		t.Error("Available() = true, want false when infoHash is empty")
+	}
+}
+
+// TestTorrentDownloader_Shutdown_Clean verifica que Shutdown() no genera panics
+// ni errores inesperados.
+func TestTorrentDownloader_Shutdown_Clean(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{DataDir: dir})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err := dl.Shutdown(ctx); err != nil {
+		t.Errorf("Shutdown() error = %v", err)
+	}
+}
+
+// TestTorrentDownloader_Cancel_NonExistent verifica que Cancel() no genera panic
+// para un ID de tarea que no existe.
+func TestTorrentDownloader_Cancel_NonExistent(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{DataDir: dir})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	// No debe hacer panic
+	if err := dl.Cancel("nonexistent-task-id"); err != nil {
+		t.Errorf("Cancel() unexpected error: %v", err)
+	}
+}
+
+// TestTorrentDownloader_Pause_NonExistent verifica que Pause() no genera panic
+// para un ID de tarea que no existe.
+func TestTorrentDownloader_Pause_NonExistent(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{DataDir: dir})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	if err := dl.Pause("nonexistent-task-id"); err != nil {
+		t.Errorf("Pause() unexpected error: %v", err)
+	}
+}
+
+// TestTorrentDownloader_StallTimeout_Default verifica que StallTimeout se inicializa
+// con el valor por defecto (30m) cuando se pasa 0.
+func TestTorrentDownloader_StallTimeout_Default(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{
+		DataDir:      dir,
+		StallTimeout: 0, // debe usar el default 30m
+	})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	if dl.cfg.StallTimeout != 30*time.Minute {
+		t.Errorf("StallTimeout = %v, want 30m", dl.cfg.StallTimeout)
+	}
+}
+
+// TestTorrentDownloader_StallTimeout_Custom verifica que un StallTimeout personalizado
+// se respeta sin ser sobreescrito.
+func TestTorrentDownloader_StallTimeout_Custom(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{
+		DataDir:      dir,
+		StallTimeout: 5 * time.Minute,
+	})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	if dl.cfg.StallTimeout != 5*time.Minute {
+		t.Errorf("StallTimeout = %v, want 5m", dl.cfg.StallTimeout)
+	}
+}
+
+// TestTorrentDownloader_SeedDisabled verifica que cuando SeedEnabled=false,
+// el downloader se crea correctamente (NoUpload implícito).
+func TestTorrentDownloader_SeedDisabled(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{
+		DataDir:     dir,
+		SeedEnabled: false,
+	})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	if dl.cfg.SeedEnabled {
+		t.Error("SeedEnabled should be false")
+	}
+}
+
+// TestTorrentDownloader_SeedEnabled verifica que cuando SeedEnabled=true,
+// el downloader se crea correctamente.
+func TestTorrentDownloader_SeedEnabled(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{
+		DataDir:     dir,
+		SeedEnabled: true,
+	})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	if !dl.cfg.SeedEnabled {
+		t.Error("SeedEnabled should be true")
+	}
+}
+
+// TestTorrentDownloader_RateLimiting_Download verifica que crear un downloader
+// con MaxDownloadRate > 0 no devuelve error.
+func TestTorrentDownloader_RateLimiting_Download(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{
+		DataDir:         dir,
+		MaxDownloadRate: 5 * 1024 * 1024, // 5 MB/s
+	})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader with download rate limit: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	if dl.cfg.MaxDownloadRate != 5*1024*1024 {
+		t.Errorf("MaxDownloadRate = %d, want %d", dl.cfg.MaxDownloadRate, 5*1024*1024)
+	}
+}
+
+// TestTorrentDownloader_RateLimiting_Upload verifica que crear un downloader
+// con MaxUploadRate > 0 no devuelve error.
+func TestTorrentDownloader_RateLimiting_Upload(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{
+		DataDir:       dir,
+		MaxUploadRate: 1 * 1024 * 1024, // 1 MB/s
+	})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader with upload rate limit: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	if dl.cfg.MaxUploadRate != 1*1024*1024 {
+		t.Errorf("MaxUploadRate = %d, want %d", dl.cfg.MaxUploadRate, 1*1024*1024)
+	}
+}
+
+// TestTorrentDownloader_DownloadTimeout_MetadataCancel verifica que Download()
+// respeta la cancelación de contexto durante la espera de metadata.
+// No hay red real, así que el timeout de contexto debe terminar la operación.
+func TestTorrentDownloader_DownloadTimeout_MetadataCancel(t *testing.T) {
+	dir := t.TempDir()
+	dl, err := NewTorrentDownloader(TorrentConfig{
+		DataDir:         dir,
+		MetadataTimeout: 100 * time.Millisecond, // muy corto para que falle rápido
+	})
+	if err != nil {
+		t.Fatalf("NewTorrentDownloader: %v", err)
+	}
+	defer dl.Shutdown(context.Background())
+
+	task := &Task{
+		ID:       "timeout-test-1234567890123456",
+		InfoHash: "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+		Title:    "Non-existent Torrent",
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+
+	progressCh := make(chan Progress, 16)
+	_, err = dl.Download(ctx, task, dir, progressCh)
+	close(progressCh)
+
+	if err == nil {
+		t.Error("expected error when metadata timeout with no peers")
+	}
+}
+
+// TestTorrentDownloader_ImplementsInterface verifica en tiempo de compilación
+// que *TorrentDownloader implementa la interfaz Downloader.
+func TestTorrentDownloader_ImplementsInterface(t *testing.T) {
+	var _ Downloader = (*TorrentDownloader)(nil)
+}
diff --git a/internal/engine/transcode_quality.go b/internal/engine/transcode_quality.go
new file mode 100644
index 0000000..4efda59
--- /dev/null
+++ b/internal/engine/transcode_quality.go
@@ -0,0 +1,64 @@
+package engine
+
+// TranscodeRuntime carries the resolved ffmpeg/ffprobe paths + tunables so
+// each session can decide whether to passthrough or pipe through ffmpeg.
+type TranscodeRuntime struct {
+	FFmpegPath   string
+	FFprobePath  string
+	HWAccel      HWAccel
+	Preset       string
+	VideoBitrate string
+	AudioBitrate string
+	MaxHeight    int
+	// Disabled forces passthrough for every file even when codecs are not
+	// browser-friendly. Useful when the user explicitly turns transcoding
+	// off in config.
+	Disabled bool
+}
+
+// qualityCap maps a session's Quality label to a (MaxHeight, VideoBitrate)
+// pair. An empty label or "original" returns zero-values, signalling "no
+// override" to the caller.
+type qualityCap struct {
+	MaxHeight    int
+	VideoBitrate string // ffmpeg -b:v string, e.g. "3500k"
+}
+
+func resolveQualityCap(label string) qualityCap {
+	switch label {
+	case "2160p":
+		return qualityCap{MaxHeight: 2160, VideoBitrate: "25000k"}
+	case "1080p":
+		return qualityCap{MaxHeight: 1080, VideoBitrate: "6000k"}
+	case "720p":
+		return qualityCap{MaxHeight: 720, VideoBitrate: "3500k"}
+	case "480p":
+		return qualityCap{MaxHeight: 480, VideoBitrate: "1500k"}
+	default:
+		// "original", "auto", "" → defer to config.
+		return qualityCap{}
+	}
+}
+
+// capForHeight returns the bitrate-cap pair appropriate for an effective
+// output height. Used after clamping outputHeight to the source's resolution:
+// asking ffmpeg for "2160p" bitrate (25 Mbps) on a 1080p source overshoots
+// the H.264 level we derived from the EFFECTIVE height (4.0, max 20 Mbps) and
+// makes libx264 refuse with "VBV bitrate > level limit". This helper picks
+// the bitrate that matches the level libx264 will actually accept.
+func capForHeight(height int) qualityCap {
+	switch {
+	case height <= 0:
+		return qualityCap{}
+	case height <= 480:
+		return qualityCap{MaxHeight: 480, VideoBitrate: "1500k"}
+	case height <= 720:
+		return qualityCap{MaxHeight: 720, VideoBitrate: "3500k"}
+	case height <= 1080:
+		return qualityCap{MaxHeight: 1080, VideoBitrate: "6000k"}
+	case height <= 1440:
+		return qualityCap{MaxHeight: 1440, VideoBitrate: "12000k"}
+	default:
+		return qualityCap{MaxHeight: 2160, VideoBitrate: "25000k"}
+	}
+}
diff --git a/internal/engine/transcoder.go b/internal/engine/transcoder.go
new file mode 100644
index 0000000..030c28c
--- /dev/null
+++ b/internal/engine/transcoder.go
@@ -0,0 +1,306 @@
+package engine
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os/exec"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// TranscodeOpts steers how Transcoder builds its ffmpeg command line.
+//
+//   - Output: fragmented MP4 chunked into HLS segments by the muxer.
+//   - Audio: AAC stereo @ 192kbps unless source already AAC (then -c:a copy).
+//   - Video: copy when h264 8-bit; otherwise transcode to h264 with HW encode
+//     when available, software fallback at "veryfast" preset.
+type TranscodeOpts struct {
+	Action       TranscodeAction
+	HWAccel      HWAccel
+	Preset       string // "veryfast" / "fast" / "medium"
+	VideoBitrate string // e.g. "5M"
+	AudioBitrate string // e.g. "192k"
+	MaxHeight    int    // optional downscale cap (e.g. 720)
+	SourceHeight int    // probed source height — used to derive a sane H.264 level
+	StartSeconds float64
+	FFmpegPath   string
+}
+
+// Transcoder wraps a long-running ffmpeg child process whose stdout streams
+// fragmented MP4 bytes; the HLS muxer slices them into segments served over HTTP.
+//
+// One Transcoder == one playback position. A seek beyond the buffered window
+// requires Close()ing this transcoder and starting a new one with a higher
+// StartSeconds (handled by the HLS session at ffmpeg start time).
+//
+// A single internal goroutine owns cmd.Wait() — never call cmd.Wait()
+// directly from outside (os/exec forbids concurrent Wait callers). Use
+// Done() / WaitErr() instead.
+type Transcoder struct {
+	cmd *exec.Cmd
+	out io.ReadCloser
+
+	mu     sync.Mutex
+	closed bool
+	stderr strings.Builder
+
+	done    chan struct{} // closed once cmd.Wait returns; nil if cmd never started
+	waitErr error         // populated before done is closed; read-only after
+}
+
+// NewTranscoder spawns ffmpeg and returns a Transcoder whose Read() yields
+// fragmented MP4 bytes from stdin. Callers MUST call Close() when done.
+func NewTranscoder(ctx context.Context, filePath string, opts TranscodeOpts) (*Transcoder, error) {
+	if opts.FFmpegPath == "" {
+		return nil, fmt.Errorf("transcoder: empty ffmpeg path")
+	}
+	args := buildFFmpegArgs(filePath, opts)
+	cmd := exec.CommandContext(ctx, opts.FFmpegPath, args...)
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return nil, fmt.Errorf("transcoder: stdout pipe: %w", err)
+	}
+	t := &Transcoder{cmd: cmd, out: stdout}
+	cmd.Stderr = &errWriter{t: t}
+	if err := cmd.Start(); err != nil {
+		return nil, fmt.Errorf("transcoder: start ffmpeg: %w", err)
+	}
+	t.startWaitGoroutine()
+	return t, nil
+}
+
+// startTranscoderToFile spawns ffmpeg with a pre-built argv where the last
+// argument is an output file path (instead of pipe:1). Used by streamSource
+// when we want random-access reads against a growing temp file rather than
+// sequential pipe consumption.
+func startTranscoderToFile(ctx context.Context, ffmpegPath string, args []string, t *Transcoder) (*Transcoder, error) {
+	if ffmpegPath == "" {
+		return nil, fmt.Errorf("transcoder: empty ffmpeg path")
+	}
+	cmd := exec.CommandContext(ctx, ffmpegPath, args...)
+	if t == nil {
+		t = &Transcoder{}
+	}
+	t.cmd = cmd
+	cmd.Stderr = &errWriter{t: t}
+	if err := cmd.Start(); err != nil {
+		return nil, fmt.Errorf("transcoder: start ffmpeg: %w", err)
+	}
+	t.startWaitGoroutine()
+	return t, nil
+}
+
+// startWaitGoroutine launches the single goroutine that owns cmd.Wait().
+// Idempotent — protected by sync.Once-via-nil-check on done.
+func (t *Transcoder) startWaitGoroutine() {
+	if t.done != nil {
+		return
+	}
+	t.done = make(chan struct{})
+	go func() {
+		t.waitErr = t.cmd.Wait()
+		close(t.done)
+	}()
+}
+
+// Done returns a channel that closes when ffmpeg exits. Returns nil for a
+// Transcoder whose cmd never started.
+func (t *Transcoder) Done() <-chan struct{} { return t.done }
+
+// WaitErr blocks until ffmpeg exits and returns the wait error. Safe to
+// call concurrently from multiple goroutines.
+func (t *Transcoder) WaitErr() error {
+	if t.done == nil {
+		return nil
+	}
+	<-t.done
+	return t.waitErr
+}
+
+// Read implements io.Reader.
+func (t *Transcoder) Read(p []byte) (int, error) { return t.out.Read(p) }
+
+// Close kills the child process if still running and waits up to 2s for exit.
+// IsClosing reports true after Close has been invoked — used by streamSource
+// to distinguish a kill-by-Close from a genuine ffmpeg crash.
+func (t *Transcoder) Close() error {
+	t.mu.Lock()
+	if t.closed {
+		t.mu.Unlock()
+		return nil
+	}
+	t.closed = true
+	t.mu.Unlock()
+
+	// out is nil for the file-output flow (startTranscoderToFile) — that
+	// pipeline writes directly to a temp file via -i ... output_path so we
+	// never wired a stdout pipe. Only close when present.
+	if t.out != nil {
+		_ = t.out.Close()
+	}
+	if t.cmd != nil && t.cmd.Process != nil {
+		_ = t.cmd.Process.Kill()
+	}
+	if t.done == nil {
+		return nil
+	}
+	select {
+	case <-t.done:
+	case <-time.After(2 * time.Second):
+		// Process refused to die — leak it; the OS will clean up on exit.
+	}
+	return nil
+}
+
+// IsClosing reports whether Close has been invoked. Cheap atomic-ish check
+// for callers that want to distinguish a kill-by-Close exit from a real
+// ffmpeg failure when reading WaitErr.
+func (t *Transcoder) IsClosing() bool {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.closed
+}
+
+// Stderr returns the accumulated ffmpeg stderr so far. Useful for surfacing
+// failure reasons in logs after Close().
+func (t *Transcoder) Stderr() string {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.stderr.String()
+}
+
+// errWriter funnels ffmpeg stderr into the Transcoder buffer so it can be
+// inspected post-mortem. Capped so a misbehaving ffmpeg can't grow memory.
+type errWriter struct{ t *Transcoder }
+
+func (w *errWriter) Write(p []byte) (int, error) {
+	w.t.mu.Lock()
+	defer w.t.mu.Unlock()
+	const maxBuf = 64 * 1024
+	if w.t.stderr.Len() < maxBuf {
+		w.t.stderr.Write(p)
+	}
+	return len(p), nil
+}
+
+// buildFFmpegArgs assembles the command line for the requested action.
+// Exposed package-level so tests can lock the flag matrix independently of
+// process spawning.
+func buildFFmpegArgs(filePath string, opts TranscodeOpts) []string {
+	// -y: overwrite output without asking (the file-output flow uses an
+	// already-created tmp file from os.CreateTemp, so the default "do you
+	// want to overwrite?" prompt would deadlock on stdin and ffmpeg dies
+	// before producing a single byte). Pipe flow doesn't need it but it's
+	// harmless there.
+	args := []string{"-y", "-hide_banner", "-loglevel", "warning"}
+
+	// Seek BEFORE input (-ss before -i) for fast keyframe-aligned start.
+	if opts.StartSeconds > 0 {
+		args = append(args, "-ss", strconv.FormatFloat(opts.StartSeconds, 'f', 3, 64))
+	}
+
+	// HW accel hint on the demuxer side improves throughput for HEVC inputs
+	// even when we end up encoding in software. Skip on macOS (videotoolbox
+	// uses a different flag shape).
+	switch opts.HWAccel {
+	case HWAccelNVENC:
+		args = append(args, "-hwaccel", "cuda")
+	case HWAccelQSV:
+		args = append(args, "-hwaccel", "qsv")
+	case HWAccelVAAPI:
+		args = append(args, "-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi")
+	case HWAccelNone, HWAccelVideoToolbox:
+		// No demuxer-side hint: software decode (None) or per-encoder flags
+		// already applied separately by FFmpegVideoCodec (VideoToolbox).
+	}
+
+	args = append(args, "-i", filePath)
+
+	switch opts.Action {
+	case ActionPassthrough, ActionRemux:
+		args = append(args, "-c:v", "copy", "-c:a", "copy")
+	case ActionRemuxAudio:
+		args = append(args, "-c:v", "copy", "-c:a", "aac", "-b:a", coalesce(opts.AudioBitrate, "192k"))
+	case ActionTranscodeVideo:
+		videoCodec := opts.HWAccel.FFmpegVideoCodec("h264")
+		args = append(args, "-c:v", videoCodec)
+		if videoCodec == "libx264" {
+			args = append(args, "-preset", coalesce(opts.Preset, "veryfast"))
+		}
+		// Force the broadest browser-compatible h264 profile. `high` (libx264
+		// default) makes Chrome try its hardware decoder path first, which
+		// can fail with "VaapiWrapper: failed initializing" on Linux boxes
+		// where VA-API isn't fully wired up. `main` keeps a clean software
+		// decode fallback on every desktop + mobile platform.
+		//
+		// Level is derived from the actual output height — a fixed "4.0"
+		// silently rejects 4K and 1440p sources at the libx264 macroblock
+		// limits and produces unplayable streams. opts.MaxHeight is the
+		// downscale cap when set; falling through means "encode at source".
+		levelHeight := opts.MaxHeight
+		if levelHeight == 0 || (opts.SourceHeight > 0 && opts.SourceHeight < levelHeight) {
+			levelHeight = opts.SourceHeight
+		}
+		args = append(args, "-profile:v", "main", "-level:v", H264LevelForHeight(levelHeight))
+		args = append(args, "-b:v", coalesce(opts.VideoBitrate, "5M"))
+		// Filter chain:
+		//   1. scale (optional) — cap height + force even width.
+		//   2. format=yuv420p — drop 10-bit + reset pix_fmt to 8-bit before
+		//      libx264 (which refuses 10-bit unless built with --bit-depth=10).
+		//   3. setparams — REWRITE the color metadata in the output stream's
+		//      VUI/SEI without touching pixels. This is what makes HDR HEVC
+		//      sources (color_primaries=bt2020, color_transfer=arib-std-b67)
+		//      decodeable in browsers that reject anything but Rec.709. We
+		//      can't actually tonemap without libzimg/zscale (most ffmpeg
+		//      builds — including ours — ship without it), so colours look
+		//      desaturated on HDR sources, but the file plays. SDR sources
+		//      already match these params and are unaffected.
+		var filterChain string
+		if opts.MaxHeight > 0 {
+			filterChain = fmt.Sprintf(
+				"scale=-2:%d:force_original_aspect_ratio=decrease,format=yuv420p,setparams=colorspace=bt709:color_trc=bt709:color_primaries=bt709:range=tv",
+				opts.MaxHeight,
+			)
+		} else {
+			filterChain = "format=yuv420p,setparams=colorspace=bt709:color_trc=bt709:color_primaries=bt709:range=tv"
+		}
+		args = append(args, "-vf", filterChain)
+		// Force AAC-LC stereo 48 kHz so the hls.js demuxer accepts the moov.
+		// 5.1 / 7.1 source streams produce a moov shape the demuxer refuses
+		// to parse, so always downmix to stereo + resample to 48 kHz here.
+		args = append(args,
+			"-c:a", "aac",
+			"-b:a", coalesce(opts.AudioBitrate, "192k"),
+			"-ar", "48000",
+			"-ac", "2",
+		)
+	}
+
+	// Common output flags — fragmented MP4 to a single pipe.
+	//
+	//   * empty_moov + default_base_moof: header-only init segment up front
+	//     so the demuxer can start decoding before the file is finished.
+	//   * frag_duration=1s: cap each moof+mdat at ~1 second of media.
+	//     Without it ffmpeg only splits at keyframes; a high-bitrate 1080p
+	//     stream produces 8 MiB+ mdat boxes that delay the first fragment
+	//     until the whole mdat lands and playback never starts.
+	//   * negative_cts_offsets: lets b-frames carry the right pts/dts so
+	//     decoders don't reset the playhead to 0 every fragment.
+	args = append(args,
+		"-movflags", "+frag_keyframe+empty_moov+default_base_moof+negative_cts_offsets",
+		"-frag_duration", "1000000",
+		"-f", "mp4",
+		"pipe:1",
+	)
+	return args
+}
+
+func coalesce(s, fallback string) string {
+	if s == "" {
+		return fallback
+	}
+	return s
+}
diff --git a/internal/engine/transcoder_test.go b/internal/engine/transcoder_test.go
new file mode 100644
index 0000000..4762bec
--- /dev/null
+++ b/internal/engine/transcoder_test.go
@@ -0,0 +1,210 @@
+package engine
+
+import (
+	"strings"
+	"testing"
+)
+
+func sliceContains(args []string, want string) bool {
+	for _, a := range args {
+		if a == want {
+			return true
+		}
+	}
+	return false
+}
+
+func sliceContainsPair(args []string, key, val string) bool {
+	for i := 0; i < len(args)-1; i++ {
+		if args[i] == key && args[i+1] == val {
+			return true
+		}
+	}
+	return false
+}
+
+func TestBuildFFmpegArgsPassthroughCopy(t *testing.T) {
+	args := buildFFmpegArgs("/tmp/movie.mp4", TranscodeOpts{
+		Action:     ActionPassthrough,
+		HWAccel:    HWAccelNone,
+		FFmpegPath: "ffmpeg",
+	})
+	if !sliceContainsPair(args, "-c:v", "copy") {
+		t.Errorf("passthrough should keep -c:v copy. args=%v", args)
+	}
+	if !sliceContainsPair(args, "-c:a", "copy") {
+		t.Error("passthrough should keep -c:a copy")
+	}
+	if !sliceContainsPair(args, "-f", "mp4") {
+		t.Error("output container must be mp4")
+	}
+	movflags := ""
+	for i := 0; i < len(args)-1; i++ {
+		if args[i] == "-movflags" {
+			movflags = args[i+1]
+		}
+	}
+	if !strings.Contains(movflags, "frag_keyframe") {
+		t.Errorf("movflags must include frag_keyframe, got %q", movflags)
+	}
+}
+
+func TestBuildFFmpegArgsRemuxAudio(t *testing.T) {
+	args := buildFFmpegArgs("/tmp/movie.mkv", TranscodeOpts{
+		Action:       ActionRemuxAudio,
+		AudioBitrate: "256k",
+		FFmpegPath:   "ffmpeg",
+	})
+	if !sliceContainsPair(args, "-c:v", "copy") {
+		t.Error("remux-audio keeps video copy")
+	}
+	if !sliceContainsPair(args, "-c:a", "aac") {
+		t.Error("remux-audio must transcode audio to aac")
+	}
+	if !sliceContainsPair(args, "-b:a", "256k") {
+		t.Error("audio bitrate override not honored")
+	}
+}
+
+func TestBuildFFmpegArgsTranscodeVideoSoftware(t *testing.T) {
+	args := buildFFmpegArgs("/tmp/movie.mkv", TranscodeOpts{
+		Action:       ActionTranscodeVideo,
+		HWAccel:      HWAccelNone,
+		Preset:       "fast",
+		VideoBitrate: "6M",
+		FFmpegPath:   "ffmpeg",
+	})
+	if !sliceContainsPair(args, "-c:v", "libx264") {
+		t.Error("software fallback must use libx264")
+	}
+	if !sliceContainsPair(args, "-preset", "fast") {
+		t.Error("custom preset not honored")
+	}
+	if !sliceContainsPair(args, "-b:v", "6M") {
+		t.Error("video bitrate not honored")
+	}
+}
+
+func TestBuildFFmpegArgsTranscodeVideoNVENC(t *testing.T) {
+	args := buildFFmpegArgs("/tmp/movie.mkv", TranscodeOpts{
+		Action:     ActionTranscodeVideo,
+		HWAccel:    HWAccelNVENC,
+		FFmpegPath: "ffmpeg",
+	})
+	if !sliceContainsPair(args, "-hwaccel", "cuda") {
+		t.Error("NVENC must request -hwaccel cuda")
+	}
+	if !sliceContainsPair(args, "-c:v", "h264_nvenc") {
+		t.Error("NVENC must use h264_nvenc encoder")
+	}
+	if sliceContains(args, "-preset") {
+		// HW encoders ignore software preset; we should NOT pass it.
+		t.Error("HW encoder path should not include -preset")
+	}
+}
+
+func TestBuildFFmpegArgsAddsStartSeek(t *testing.T) {
+	args := buildFFmpegArgs("/tmp/movie.mp4", TranscodeOpts{
+		Action:       ActionPassthrough,
+		StartSeconds: 90.5,
+		FFmpegPath:   "ffmpeg",
+	})
+	idxSs, idxIn := -1, -1
+	for i, a := range args {
+		if a == "-ss" {
+			idxSs = i
+		}
+		if a == "-i" {
+			idxIn = i
+		}
+	}
+	if idxSs < 0 {
+		t.Fatal("missing -ss flag")
+	}
+	if idxIn < 0 {
+		t.Fatal("missing -i flag")
+	}
+	if idxSs >= idxIn {
+		t.Errorf("expected -ss BEFORE -i for fast seek; got -ss@%d -i@%d", idxSs, idxIn)
+	}
+	if args[idxSs+1] != "90.500" {
+		t.Errorf("expected seek 90.500s, got %q", args[idxSs+1])
+	}
+}
+
+func TestTranscoderZeroValueLifecycle(t *testing.T) {
+	var tr Transcoder
+	if tr.IsClosing() {
+		t.Errorf("zero-value Transcoder should not report IsClosing")
+	}
+	if tr.Stderr() != "" {
+		t.Errorf("zero-value Stderr should be empty")
+	}
+	if err := tr.WaitErr(); err != nil {
+		t.Errorf("WaitErr without started cmd should be nil, got %v", err)
+	}
+	if err := tr.Close(); err != nil {
+		t.Errorf("Close without started cmd should be nil, got %v", err)
+	}
+	// Second Close is idempotent and must remain nil.
+	if err := tr.Close(); err != nil {
+		t.Errorf("repeat Close should be nil, got %v", err)
+	}
+	if !tr.IsClosing() {
+		t.Errorf("after Close, IsClosing should be true")
+	}
+	if tr.Done() != nil {
+		t.Errorf("Done() should be nil for never-started Transcoder")
+	}
+}
+
+func TestErrWriterCapturesStderr(t *testing.T) {
+	tr := &Transcoder{}
+	w := &errWriter{t: tr}
+	n, err := w.Write([]byte("ffmpeg failed: bad codec"))
+	if err != nil || n != 24 {
+		t.Errorf("Write returned (%d,%v)", n, err)
+	}
+	if got := tr.Stderr(); got != "ffmpeg failed: bad codec" {
+		t.Errorf("Stderr captured %q", got)
+	}
+}
+
+func TestErrWriterCapsBuffer(t *testing.T) {
+	tr := &Transcoder{}
+	w := &errWriter{t: tr}
+	// Write a chunk under the cap, then a huge chunk: total should stop growing past 64KB.
+	w.Write(make([]byte, 32*1024)) //nolint:errcheck
+	w.Write(make([]byte, 32*1024)) //nolint:errcheck
+	w.Write(make([]byte, 32*1024)) //nolint:errcheck
+	if got := len(tr.Stderr()); got > 64*1024 {
+		t.Errorf("stderr exceeded 64KB cap: %d bytes", got)
+	}
+}
+
+func TestCoalesce(t *testing.T) {
+	if got := coalesce("", "fallback"); got != "fallback" {
+		t.Errorf("empty -> fallback, got %q", got)
+	}
+	if got := coalesce("value", "fallback"); got != "value" {
+		t.Errorf("non-empty -> value, got %q", got)
+	}
+}
+
+func TestBuildFFmpegArgsDownscale(t *testing.T) {
+	args := buildFFmpegArgs("/tmp/movie.mkv", TranscodeOpts{
+		Action:     ActionTranscodeVideo,
+		HWAccel:    HWAccelNone,
+		MaxHeight:  720,
+		FFmpegPath: "ffmpeg",
+	})
+	hasVF := false
+	for i := 0; i < len(args)-1; i++ {
+		if args[i] == "-vf" && strings.Contains(args[i+1], "720") {
+			hasVF = true
+		}
+	}
+	if !hasVF {
+		t.Errorf("expected -vf scale containing 720; args=%v", args)
+	}
+}
diff --git a/internal/engine/upnp.go b/internal/engine/upnp.go
index 1171cf8..50587c9 100644
--- a/internal/engine/upnp.go
+++ b/internal/engine/upnp.go
@@ -1,12 +1,18 @@
 package engine
 
 import (
+	"context"
+	"encoding/binary"
 	"fmt"
+	"io"
 	"log"
+	"net"
+	"net/http"
+	"os"
+	"strings"
 	"time"
 
-	alog "github.com/anacrolix/log"
-	"github.com/anacrolix/upnp"
+	"github.com/huin/goupnp/dcps/internetgateway2"
 )
 
 // UPnPMapping represents an active port mapping on the router.
@@ -14,51 +20,419 @@ type UPnPMapping struct {
 	ExternalIP   string
 	ExternalPort int
 	InternalPort int
-	device       upnp.Device
+	gateway      string     // for NAT-PMP cleanup
+	protocol     string     // "natpmp" or "upnp"
+	client       upnpClient // for UPnP cleanup (nil if NAT-PMP)
 }
 
-// setupUPnP discovers the gateway, maps the port, and gets the public IP.
-// Returns nil if UPnP is not available or fails.
-func setupUPnP(internalPort int) (*UPnPMapping, error) {
-	log.Println("stream: discovering UPnP gateway (10s timeout)...")
-	devices := upnp.Discover(0, 10*time.Second, alog.Logger{})
-	if len(devices) == 0 {
-		return nil, fmt.Errorf("no UPnP devices found (is UPnP enabled on your router?)")
+// upnpClient abstracts the IGD service methods we need (WANIPConnection or WANPPPConnection).
+type upnpClient interface {
+	AddPortMapping(
+		NewRemoteHost string,
+		NewExternalPort uint16,
+		NewProtocol string,
+		NewInternalPort uint16,
+		NewInternalClient string,
+		NewEnabled bool,
+		NewPortMappingDescription string,
+		NewLeaseDuration uint32,
+	) error
+	DeletePortMapping(
+		NewRemoteHost string,
+		NewExternalPort uint16,
+		NewProtocol string,
+	) error
+	GetExternalIPAddress() (string, error)
+}
+
+// SetupUPnP discovers the gateway, maps the port, and gets the public IP.
+// Tries NAT-PMP first (faster, more compatible), falls back to UPnP-IGD SOAP.
+func SetupUPnP(internalPort int) (*UPnPMapping, error) {
+	log.Println("stream: discovering NAT gateway...")
+
+	gateway := defaultGateway()
+
+	// Try NAT-PMP first (preferred — works on most modern routers including TP-Link)
+	if gateway != "" {
+		if mapping, err := tryNATPMP(gateway, internalPort); err == nil {
+			return mapping, nil
+		} else {
+			log.Printf("stream: NAT-PMP failed (%v), trying UPnP-IGD...", err)
+		}
 	}
 
-	log.Printf("stream: found %d UPnP device(s), using %s", len(devices), devices[0].ID())
-	device := devices[0]
+	// Fall back to UPnP-IGD SOAP
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
 
-	// Get public IP
-	externalIP, err := device.GetExternalIPAddress()
+	if mapping, err := tryWANIPConnection2(ctx, internalPort); err == nil {
+		return mapping, nil
+	}
+	if mapping, err := tryWANIPConnection1(ctx, internalPort); err == nil {
+		return mapping, nil
+	}
+	if mapping, err := tryWANPPPConnection1(ctx, internalPort); err == nil {
+		return mapping, nil
+	}
+
+	return nil, fmt.Errorf("no NAT gateway found (tried NAT-PMP, IGD2, IGD1, PPP)")
+}
+
+// --- NAT-PMP implementation (RFC 6886) ---
+
+func tryNATPMP(gateway string, port int) (*UPnPMapping, error) {
+	conn, err := net.DialTimeout("udp4", gateway+":5351", 3*time.Second)
+	if err != nil {
+		return nil, fmt.Errorf("NAT-PMP dial: %w", err)
+	}
+	defer conn.Close()
+
+	// Map TCP port
+	extPort, lifetime, err := natpmpMapPort(conn, 2, uint16(port), uint16(port), 7200)
+	if err != nil {
+		return nil, fmt.Errorf("NAT-PMP map TCP: %w", err)
+	}
+
+	// Get external IP: try NAT-PMP first, fall back to public API
+	extIP := natpmpExternalIP(conn)
+	if extIP == "" {
+		extIP = publicIPFallback()
+	}
+	if extIP == "" {
+		// Clean up the mapping we just created
+		if _, _, err := natpmpMapPort(conn, 2, uint16(port), 0, 0); err != nil {
+			log.Printf("stream: failed to clean up NAT-PMP mapping after IP failure: %v", err)
+		}
+		return nil, fmt.Errorf("NAT-PMP: port mapped but could not determine external IP")
+	}
+
+	log.Printf("stream: NAT-PMP port mapped %s:%d -> :%d (lease %ds)",
+		extIP, extPort, port, lifetime)
+
+	return &UPnPMapping{
+		ExternalIP:   extIP,
+		ExternalPort: int(extPort),
+		InternalPort: port,
+		gateway:      gateway,
+		protocol:     "natpmp",
+	}, nil
+}
+
+// natpmpMapPort sends a NAT-PMP mapping request.
+// opcode: 1=UDP, 2=TCP. lifetime=0 to delete.
+func natpmpMapPort(conn net.Conn, opcode byte, internalPort, suggestedExtPort uint16, lifetime uint32) (extPort uint16, actualLifetime uint32, err error) {
+	conn.SetDeadline(time.Now().Add(5 * time.Second))
+
+	req := make([]byte, 12)
+	req[0] = 0      // version
+	req[1] = opcode // 1=UDP, 2=TCP
+	binary.BigEndian.PutUint16(req[4:6], internalPort)
+	binary.BigEndian.PutUint16(req[6:8], suggestedExtPort)
+	binary.BigEndian.PutUint32(req[8:12], lifetime)
+
+	if _, err := conn.Write(req); err != nil {
+		return 0, 0, fmt.Errorf("write: %w", err)
+	}
+
+	buf := make([]byte, 16)
+	n, err := conn.Read(buf)
+	if err != nil {
+		return 0, 0, fmt.Errorf("read: %w", err)
+	}
+	if n < 16 {
+		return 0, 0, fmt.Errorf("short response: %d bytes", n)
+	}
+
+	resultCode := binary.BigEndian.Uint16(buf[2:4])
+	if resultCode != 0 {
+		names := map[uint16]string{
+			1: "unsupported version", 2: "not authorized",
+			3: "network failure", 4: "out of resources", 5: "unsupported opcode",
+		}
+		name := names[resultCode]
+		if name == "" {
+			name = "unknown"
+		}
+		return 0, 0, fmt.Errorf("result %d (%s)", resultCode, name)
+	}
+
+	extPort = binary.BigEndian.Uint16(buf[10:12])
+	actualLifetime = binary.BigEndian.Uint32(buf[12:16])
+	return extPort, actualLifetime, nil
+}
+
+// natpmpExternalIP queries the external IP via NAT-PMP (opcode 0).
+func natpmpExternalIP(conn net.Conn) string {
+	conn.SetDeadline(time.Now().Add(3 * time.Second))
+	if _, err := conn.Write([]byte{0, 0}); err != nil {
+		return ""
+	}
+	buf := make([]byte, 12)
+	n, err := conn.Read(buf)
+	if err != nil || n < 12 {
+		return ""
+	}
+	resultCode := binary.BigEndian.Uint16(buf[2:4])
+	if resultCode != 0 {
+		return ""
+	}
+	ip := net.IPv4(buf[8], buf[9], buf[10], buf[11])
+	if ip.IsUnspecified() {
+		return ""
+	}
+	return ip.String()
+}
+
+// publicIPFallback fetches the external IP from a public API.
+func publicIPFallback() string {
+	client := &http.Client{Timeout: 5 * time.Second}
+	for _, url := range []string{
+		"https://api.ipify.org",
+		"https://ifconfig.me/ip",
+	} {
+		resp, err := client.Get(url)
+		if err != nil {
+			continue
+		}
+		body, err := io.ReadAll(io.LimitReader(resp.Body, 64))
+		resp.Body.Close()
+		if err != nil || resp.StatusCode != 200 {
+			continue
+		}
+		ip := strings.TrimSpace(string(body))
+		if net.ParseIP(ip) != nil {
+			return ip
+		}
+	}
+	return ""
+}
+
+// --- UPnP-IGD SOAP implementation ---
+
+func tryWANIPConnection2(ctx context.Context, port int) (*UPnPMapping, error) {
+	clients, _, err := internetgateway2.NewWANIPConnection2ClientsCtx(ctx)
+	if err != nil || len(clients) == 0 {
+		return nil, fmt.Errorf("WANIPConnection2: %v (found %d)", err, len(clients))
+	}
+	return setupMapping(clients[0].ServiceClient.RootDevice.URLBase.Host, &wanIP2Adapter{clients[0]}, port)
+}
+
+func tryWANIPConnection1(ctx context.Context, port int) (*UPnPMapping, error) {
+	clients, _, err := internetgateway2.NewWANIPConnection1ClientsCtx(ctx)
+	if err != nil || len(clients) == 0 {
+		return nil, fmt.Errorf("WANIPConnection1: %v (found %d)", err, len(clients))
+	}
+	return setupMapping(clients[0].ServiceClient.RootDevice.URLBase.Host, &wanIP1Adapter{clients[0]}, port)
+}
+
+func tryWANPPPConnection1(ctx context.Context, port int) (*UPnPMapping, error) {
+	clients, _, err := internetgateway2.NewWANPPPConnection1ClientsCtx(ctx)
+	if err != nil || len(clients) == 0 {
+		return nil, fmt.Errorf("WANPPPConnection1: %v (found %d)", err, len(clients))
+	}
+	return setupMapping(clients[0].ServiceClient.RootDevice.URLBase.Host, &wanPPP1Adapter{clients[0]}, port)
+}
+
+func setupMapping(deviceHost string, client upnpClient, internalPort int) (*UPnPMapping, error) {
+	externalIP, err := client.GetExternalIPAddress()
 	if err != nil {
 		return nil, fmt.Errorf("get external IP: %w", err)
 	}
-	log.Printf("stream: public IP via UPnP: %s", externalIP)
+	if externalIP == "" {
+		externalIP = publicIPFallback()
+	}
+	if externalIP == "" {
+		return nil, fmt.Errorf("could not determine external IP")
+	}
 
-	// Map port (same internal/external, 2h lease)
-	mappedPort, err := device.AddPortMapping(upnp.TCP, internalPort, internalPort, "unarr stream", 2*time.Hour)
+	localIP := localIPFor(deviceHost)
+
+	err = client.AddPortMapping(
+		"",                   // remote host (empty = any)
+		uint16(internalPort), // external port
+		"TCP",                // protocol
+		uint16(internalPort), // internal port
+		localIP,              // internal client IP
+		true,                 // enabled
+		"unarr stream",       // description
+		7200,                 // lease duration (2 hours)
+	)
 	if err != nil {
 		return nil, fmt.Errorf("add port mapping %d: %w", internalPort, err)
 	}
 
-	log.Printf("stream: UPnP port mapped %s:%d -> local:%d (2h lease)", externalIP, mappedPort, internalPort)
+	log.Printf("stream: UPnP port mapped %s:%d -> %s:%d (2h lease)", externalIP, internalPort, localIP, internalPort)
 	return &UPnPMapping{
-		ExternalIP:   externalIP.String(),
-		ExternalPort: mappedPort,
+		ExternalIP:   externalIP,
+		ExternalPort: internalPort,
 		InternalPort: internalPort,
-		device:       device,
+		protocol:     "upnp",
+		client:       client,
 	}, nil
 }
 
+// --- Helpers ---
+
+// defaultGateway returns the default gateway IP.
+// Reads /proc/net/route on Linux, falls back to assuming .1 on the local subnet.
+func defaultGateway() string {
+	// Try /proc/net/route first (Linux only, no external dependency)
+	if gw := gatewayFromProcRoute(); gw != "" {
+		return gw
+	}
+
+	// Fallback: assume .1 on the local subnet (works for most home routers)
+	conn, err := net.Dial("udp4", "8.8.8.8:80")
+	if err != nil {
+		return ""
+	}
+	defer conn.Close()
+
+	ip := conn.LocalAddr().(*net.UDPAddr).IP.To4()
+	if ip == nil {
+		return ""
+	}
+	return net.IPv4(ip[0], ip[1], ip[2], 1).String()
+}
+
+// gatewayFromProcRoute parses /proc/net/route for the default route gateway.
+func gatewayFromProcRoute() string {
+	data, err := os.ReadFile("/proc/net/route")
+	if err != nil {
+		return ""
+	}
+	for _, line := range strings.Split(string(data), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) < 3 {
+			continue
+		}
+		// Default route: destination is 00000000
+		if fields[1] != "00000000" {
+			continue
+		}
+		// Gateway is field 2 in little-endian hex
+		gw, err := fmt.Sscanf(fields[2], "%x", new(uint32))
+		if err != nil || gw != 1 {
+			continue
+		}
+		var gwInt uint32
+		fmt.Sscanf(fields[2], "%x", &gwInt)
+		return fmt.Sprintf("%d.%d.%d.%d",
+			gwInt&0xFF, (gwInt>>8)&0xFF, (gwInt>>16)&0xFF, (gwInt>>24)&0xFF)
+	}
+	return ""
+}
+
+// localIPFor returns the local IP that can reach the given host (typically the router).
+func localIPFor(host string) string {
+	h, _, err := net.SplitHostPort(host)
+	if err != nil {
+		h = host
+	}
+	conn, err := net.Dial("udp4", h+":1")
+	if err != nil {
+		return "0.0.0.0"
+	}
+	defer conn.Close()
+	return conn.LocalAddr().(*net.UDPAddr).IP.String()
+}
+
 // Remove deletes the port mapping from the router.
+// It runs in a goroutine with a 5-second deadline so it never blocks shutdown.
 func (m *UPnPMapping) Remove() {
-	if m == nil || m.device == nil {
+	if m == nil {
 		return
 	}
-	if err := m.device.DeletePortMapping(upnp.TCP, m.ExternalPort); err != nil {
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		switch m.protocol {
+		case "natpmp":
+			m.removeNATPMP()
+		case "upnp":
+			m.removeUPnP()
+		}
+	}()
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		// removeNATPMP worst case: 3s dial + 5s natpmpMapPort deadline = 8s.
+		// 10s gives enough margin without blocking shutdown indefinitely.
+		log.Printf("stream: UPnP/NAT-PMP cleanup timed out after 10s — port %d may remain mapped", m.ExternalPort)
+	}
+}
+
+func (m *UPnPMapping) removeNATPMP() {
+	if m.gateway == "" {
+		return
+	}
+	conn, err := net.DialTimeout("udp4", m.gateway+":5351", 3*time.Second)
+	if err != nil {
+		log.Printf("stream: failed to connect for NAT-PMP cleanup: %v", err)
+		return
+	}
+	defer conn.Close()
+
+	_, _, err = natpmpMapPort(conn, 2, uint16(m.InternalPort), 0, 0)
+	if err != nil {
+		log.Printf("stream: failed to remove NAT-PMP mapping: %v", err)
+	} else {
+		log.Printf("stream: removed NAT-PMP mapping for port %d", m.ExternalPort)
+	}
+}
+
+func (m *UPnPMapping) removeUPnP() {
+	if m.client == nil {
+		return
+	}
+	if err := m.client.DeletePortMapping("", uint16(m.ExternalPort), "TCP"); err != nil {
 		log.Printf("stream: failed to remove UPnP mapping: %v", err)
 	} else {
 		log.Printf("stream: removed UPnP mapping for port %d", m.ExternalPort)
 	}
 }
+
+// --- Adapters to unify WANIPConnection2, WANIPConnection1, WANPPPConnection1 ---
+
+type wanIP2Adapter struct {
+	c *internetgateway2.WANIPConnection2
+}
+
+func (a *wanIP2Adapter) AddPortMapping(remoteHost string, extPort uint16, proto string, intPort uint16, intClient string, enabled bool, desc string, lease uint32) error {
+	return a.c.AddPortMapping(remoteHost, extPort, proto, intPort, intClient, enabled, desc, lease)
+}
+func (a *wanIP2Adapter) DeletePortMapping(remoteHost string, extPort uint16, proto string) error {
+	return a.c.DeletePortMapping(remoteHost, extPort, proto)
+}
+func (a *wanIP2Adapter) GetExternalIPAddress() (string, error) {
+	return a.c.GetExternalIPAddress()
+}
+
+type wanIP1Adapter struct {
+	c *internetgateway2.WANIPConnection1
+}
+
+func (a *wanIP1Adapter) AddPortMapping(remoteHost string, extPort uint16, proto string, intPort uint16, intClient string, enabled bool, desc string, lease uint32) error {
+	return a.c.AddPortMapping(remoteHost, extPort, proto, intPort, intClient, enabled, desc, lease)
+}
+func (a *wanIP1Adapter) DeletePortMapping(remoteHost string, extPort uint16, proto string) error {
+	return a.c.DeletePortMapping(remoteHost, extPort, proto)
+}
+func (a *wanIP1Adapter) GetExternalIPAddress() (string, error) {
+	return a.c.GetExternalIPAddress()
+}
+
+type wanPPP1Adapter struct {
+	c *internetgateway2.WANPPPConnection1
+}
+
+func (a *wanPPP1Adapter) AddPortMapping(remoteHost string, extPort uint16, proto string, intPort uint16, intClient string, enabled bool, desc string, lease uint32) error {
+	return a.c.AddPortMapping(remoteHost, extPort, proto, intPort, intClient, enabled, desc, lease)
+}
+func (a *wanPPP1Adapter) DeletePortMapping(remoteHost string, extPort uint16, proto string) error {
+	return a.c.DeletePortMapping(remoteHost, extPort, proto)
+}
+func (a *wanPPP1Adapter) GetExternalIPAddress() (string, error) {
+	return a.c.GetExternalIPAddress()
+}
diff --git a/internal/engine/upnp_debug_test.go b/internal/engine/upnp_debug_test.go
new file mode 100644
index 0000000..5e51770
--- /dev/null
+++ b/internal/engine/upnp_debug_test.go
@@ -0,0 +1,127 @@
+//go:build manual
+
+package engine
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/huin/goupnp"
+	"github.com/huin/goupnp/dcps/internetgateway2"
+)
+
+// TestUPnPDebug performs detailed UPnP discovery diagnostics.
+// Run with: go test -tags manual -run TestUPnPDebug -v ./internal/engine/
+func TestUPnPDebug(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	fmt.Println("=== UPnP Debug Diagnostics ===")
+	fmt.Println()
+
+	// 1. Check network interfaces
+	fmt.Println("--- Network Interfaces ---")
+	ifaces, _ := net.Interfaces()
+	for _, iface := range ifaces {
+		if iface.Flags&net.FlagUp == 0 || iface.Flags&net.FlagLoopback != 0 {
+			continue
+		}
+		addrs, _ := iface.Addrs()
+		for _, addr := range addrs {
+			fmt.Printf("  %s: %s (flags: %s)\n", iface.Name, addr, iface.Flags)
+		}
+	}
+	fmt.Println()
+
+	// 2. Raw SSDP discovery — search for ALL UPnP root devices
+	fmt.Println("--- Raw SSDP Discovery (all root devices) ---")
+	devices, err := goupnp.DiscoverDevicesCtx(ctx, "upnp:rootdevice")
+	if err != nil {
+		fmt.Printf("  Error: %v\n", err)
+	} else {
+		fmt.Printf("  Found %d root device(s)\n", len(devices))
+		for i, dev := range devices {
+			if dev.Err != nil {
+				fmt.Printf("  [%d] Error: %v\n", i, dev.Err)
+				continue
+			}
+			rd := dev.Root
+			fmt.Printf("  [%d] %s — %s (%s)\n", i, rd.Device.FriendlyName, rd.Device.DeviceType, rd.URLBase.String())
+			// List services
+			for _, svc := range rd.Device.Services {
+				fmt.Printf("       Service: %s\n", svc.ServiceType)
+			}
+			// List sub-devices
+			for _, sub := range rd.Device.Devices {
+				fmt.Printf("       SubDevice: %s — %s\n", sub.FriendlyName, sub.DeviceType)
+				for _, svc := range sub.Services {
+					fmt.Printf("           Service: %s\n", svc.ServiceType)
+				}
+				for _, sub2 := range sub.Devices {
+					fmt.Printf("           SubDevice: %s — %s\n", sub2.FriendlyName, sub2.DeviceType)
+					for _, svc := range sub2.Services {
+						fmt.Printf("               Service: %s\n", svc.ServiceType)
+					}
+				}
+			}
+		}
+	}
+	fmt.Println()
+
+	// 3. Try specific IGD service types
+	fmt.Println("--- IGD Service Discovery ---")
+
+	fmt.Print("  WANIPConnection2: ")
+	c2, errs2, err2 := internetgateway2.NewWANIPConnection2ClientsCtx(ctx)
+	if err2 != nil {
+		fmt.Printf("error: %v\n", err2)
+	} else {
+		fmt.Printf("%d client(s), %d error(s)\n", len(c2), len(errs2))
+		for _, e := range errs2 {
+			fmt.Printf("    err: %v\n", e)
+		}
+		for _, c := range c2 {
+			ip, err := c.GetExternalIPAddress()
+			fmt.Printf("    device=%s external_ip=%s err=%v\n",
+				c.ServiceClient.RootDevice.Device.FriendlyName, ip, err)
+		}
+	}
+
+	fmt.Print("  WANIPConnection1: ")
+	c1, errs1, err1 := internetgateway2.NewWANIPConnection1ClientsCtx(ctx)
+	if err1 != nil {
+		fmt.Printf("error: %v\n", err1)
+	} else {
+		fmt.Printf("%d client(s), %d error(s)\n", len(c1), len(errs1))
+		for _, e := range errs1 {
+			fmt.Printf("    err: %v\n", e)
+		}
+		for _, c := range c1 {
+			ip, err := c.GetExternalIPAddress()
+			fmt.Printf("    device=%s external_ip=%s err=%v\n",
+				c.ServiceClient.RootDevice.Device.FriendlyName, ip, err)
+		}
+	}
+
+	fmt.Print("  WANPPPConnection1: ")
+	cp, errsp, errp := internetgateway2.NewWANPPPConnection1ClientsCtx(ctx)
+	if errp != nil {
+		fmt.Printf("error: %v\n", errp)
+	} else {
+		fmt.Printf("%d client(s), %d error(s)\n", len(cp), len(errsp))
+		for _, e := range errsp {
+			fmt.Printf("    err: %v\n", e)
+		}
+		for _, c := range cp {
+			ip, err := c.GetExternalIPAddress()
+			fmt.Printf("    device=%s external_ip=%s err=%v\n",
+				c.ServiceClient.RootDevice.Device.FriendlyName, ip, err)
+		}
+	}
+
+	fmt.Println()
+	fmt.Println("=== Done ===")
+}
diff --git a/internal/engine/upnp_live_test.go b/internal/engine/upnp_live_test.go
new file mode 100644
index 0000000..3bbdac7
--- /dev/null
+++ b/internal/engine/upnp_live_test.go
@@ -0,0 +1,136 @@
+//go:build manual
+
+package engine
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/huin/goupnp/dcps/internetgateway2"
+)
+
+// TestUPnPLive is a manual integration test that requires a real router with UPnP/NAT-PMP.
+// Run with: go test -tags manual -run TestUPnPLive -v ./internal/engine/
+func TestUPnPLive(t *testing.T) {
+	fmt.Println("=== UPnP/NAT-PMP Live Test ===")
+
+	start := time.Now()
+	mapping, err := SetupUPnP(54321)
+	elapsed := time.Since(start)
+
+	if err != nil {
+		t.Fatalf("Port mapping FAILED after %s: %v", elapsed, err)
+	}
+
+	fmt.Printf("✅ SUCCESS in %s (protocol: %s)\n", elapsed, mapping.protocol)
+	fmt.Printf("   External IP:   %s\n", mapping.ExternalIP)
+	fmt.Printf("   External Port: %d\n", mapping.ExternalPort)
+	fmt.Printf("   Internal Port: %d\n", mapping.InternalPort)
+
+	// Verify the port is actually mapped by listening and checking
+	listener, err := net.Listen("tcp", fmt.Sprintf(":%d", mapping.InternalPort))
+	if err != nil {
+		t.Logf("⚠️  Could not listen on internal port %d: %v", mapping.InternalPort, err)
+	} else {
+		listener.Close()
+		fmt.Printf("   ✅ Internal port %d is available for listening\n", mapping.InternalPort)
+	}
+
+	// Cleanup
+	mapping.Remove()
+	fmt.Println("Port mapping removed.")
+}
+
+// TestNATPMPDirect tests NAT-PMP protocol directly against the gateway.
+// Run with: go test -tags manual -run TestNATPMPDirect -v ./internal/engine/
+func TestNATPMPDirect(t *testing.T) {
+	fmt.Println("=== NAT-PMP Direct Test ===")
+
+	gateway := defaultGateway()
+	if gateway == "" {
+		t.Fatal("Could not determine default gateway")
+	}
+	fmt.Printf("Gateway: %s\n\n", gateway)
+
+	conn, err := net.DialTimeout("udp4", gateway+":5351", 3*time.Second)
+	if err != nil {
+		t.Fatalf("Cannot connect to NAT-PMP: %v", err)
+	}
+	defer conn.Close()
+
+	// 1. External IP
+	fmt.Print("External IP via NAT-PMP: ")
+	extIP := natpmpExternalIP(conn)
+	if extIP == "" {
+		fmt.Println("(empty — router may not report it)")
+	} else {
+		fmt.Println(extIP)
+	}
+
+	// 2. TCP mapping
+	fmt.Print("TCP mapping 54321→54321: ")
+	extPort, lifetime, err := natpmpMapPort(conn, 2, 54321, 54321, 120)
+	if err != nil {
+		t.Fatalf("FAILED: %v", err)
+	}
+	fmt.Printf("✅ external=%d lifetime=%ds\n", extPort, lifetime)
+
+	// 3. Cleanup
+	fmt.Print("Deleting mapping: ")
+	_, _, err = natpmpMapPort(conn, 2, 54321, 0, 0)
+	if err != nil {
+		fmt.Printf("FAILED: %v\n", err)
+	} else {
+		fmt.Println("OK")
+	}
+}
+
+// TestUPnPSOAPDirect tests UPnP-IGD SOAP directly (for debugging routers where NAT-PMP isn't available).
+// Run with: go test -tags manual -run TestUPnPSOAPDirect -v ./internal/engine/
+func TestUPnPSOAPDirect(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	fmt.Println("=== UPnP-IGD SOAP Direct Test ===")
+	fmt.Println()
+
+	// Try WANIPConnection1
+	fmt.Print("Discovering WANIPConnection1... ")
+	clients, errs, err := internetgateway2.NewWANIPConnection1ClientsCtx(ctx)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	fmt.Printf("%d client(s), %d error(s)\n", len(clients), len(errs))
+	for _, e := range errs {
+		fmt.Printf("  err: %v\n", e)
+	}
+	if len(clients) == 0 {
+		t.Fatal("No WANIPConnection1 clients found")
+	}
+
+	client := clients[0]
+	fmt.Printf("  Device: %s\n", client.ServiceClient.RootDevice.Device.FriendlyName)
+
+	// GetExternalIPAddress
+	extIP, err := client.GetExternalIPAddress()
+	fmt.Printf("  External IP: %q (err: %v)\n", extIP, err)
+
+	// Try AddPortMapping
+	host := client.ServiceClient.RootDevice.URLBase.Host
+	localIP := localIPFor(host)
+	fmt.Printf("  Local IP: %s\n\n", localIP)
+
+	fmt.Print("AddPortMapping TCP 54321→54321: ")
+	err = client.AddPortMapping("", 54321, "TCP", 54321, localIP, true, "unarr-test", 120)
+	if err != nil {
+		fmt.Printf("FAILED: %v\n", err)
+		fmt.Println("\n⚠️  UPnP SOAP AddPortMapping fails on this router. NAT-PMP should work as fallback.")
+	} else {
+		fmt.Println("OK")
+		client.DeletePortMapping("", 54321, "TCP")
+		fmt.Println("Mapping deleted.")
+	}
+}
diff --git a/internal/engine/upnp_test.go b/internal/engine/upnp_test.go
new file mode 100644
index 0000000..c2e9592
--- /dev/null
+++ b/internal/engine/upnp_test.go
@@ -0,0 +1,364 @@
+package engine
+
+import (
+	"encoding/binary"
+	"net"
+	"sync"
+	"testing"
+	"time"
+)
+
+// --- Mock NAT-PMP server ---
+
+type mockNATPMPServer struct {
+	conn     net.PacketConn
+	addr     string
+	mu       sync.Mutex
+	mappings map[uint16]natpmpMapping // internalPort → mapping
+	extIP    net.IP
+	epoch    uint32
+	closed   chan struct{}
+}
+
+type natpmpMapping struct {
+	extPort  uint16
+	protocol byte // 1=UDP, 2=TCP
+	lifetime uint32
+}
+
+func newMockNATPMP(extIP string) *mockNATPMPServer {
+	conn, err := net.ListenPacket("udp4", "127.0.0.1:0")
+	if err != nil {
+		panic(err)
+	}
+	s := &mockNATPMPServer{
+		conn:     conn,
+		addr:     conn.LocalAddr().String(),
+		mappings: make(map[uint16]natpmpMapping),
+		extIP:    net.ParseIP(extIP).To4(),
+		epoch:    1000,
+		closed:   make(chan struct{}),
+	}
+	go s.serve()
+	return s
+}
+
+func (s *mockNATPMPServer) Close() {
+	s.conn.Close()
+	<-s.closed
+}
+
+func (s *mockNATPMPServer) serve() {
+	defer close(s.closed)
+	buf := make([]byte, 64)
+	for {
+		n, addr, err := s.conn.ReadFrom(buf)
+		if err != nil {
+			return
+		}
+		if n < 2 {
+			continue
+		}
+
+		opcode := buf[1]
+		var resp []byte
+
+		switch opcode {
+		case 0: // External address request
+			resp = s.handleExternalAddress()
+		case 1, 2: // UDP/TCP mapping
+			if n >= 12 {
+				resp = s.handleMapping(buf[:n])
+			}
+		}
+
+		if resp != nil {
+			s.conn.WriteTo(resp, addr)
+		}
+	}
+}
+
+func (s *mockNATPMPServer) handleExternalAddress() []byte {
+	resp := make([]byte, 12)
+	resp[0] = 0   // version
+	resp[1] = 128 // opcode 0 + 128
+	// result code 0 = success
+	binary.BigEndian.PutUint32(resp[4:8], s.epoch)
+	copy(resp[8:12], s.extIP)
+	return resp
+}
+
+func (s *mockNATPMPServer) handleMapping(req []byte) []byte {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	opcode := req[1]
+	intPort := binary.BigEndian.Uint16(req[4:6])
+	sugExtPort := binary.BigEndian.Uint16(req[6:8])
+	lifetime := binary.BigEndian.Uint32(req[8:12])
+
+	resp := make([]byte, 16)
+	resp[0] = 0
+	resp[1] = 128 + opcode
+	binary.BigEndian.PutUint32(resp[4:8], s.epoch)
+
+	if lifetime == 0 {
+		// Delete mapping
+		delete(s.mappings, intPort)
+		binary.BigEndian.PutUint16(resp[8:10], intPort)
+		binary.BigEndian.PutUint16(resp[10:12], 0)
+		binary.BigEndian.PutUint32(resp[12:16], 0)
+	} else {
+		// Create mapping
+		extPort := sugExtPort
+		if extPort == 0 {
+			extPort = intPort
+		}
+		s.mappings[intPort] = natpmpMapping{
+			extPort:  extPort,
+			protocol: opcode,
+			lifetime: lifetime,
+		}
+		binary.BigEndian.PutUint16(resp[8:10], intPort)
+		binary.BigEndian.PutUint16(resp[10:12], extPort)
+		binary.BigEndian.PutUint32(resp[12:16], lifetime)
+	}
+
+	return resp
+}
+
+// --- Mock UPnP client ---
+
+type mockUPnPClient struct {
+	externalIP  string
+	externalErr error
+	addErr      error
+	deleteErr   error
+	lastMapping *mockPortMapping
+}
+
+type mockPortMapping struct {
+	remoteHost  string
+	extPort     uint16
+	protocol    string
+	intPort     uint16
+	intClient   string
+	enabled     bool
+	description string
+	lease       uint32
+}
+
+func (m *mockUPnPClient) GetExternalIPAddress() (string, error) {
+	return m.externalIP, m.externalErr
+}
+
+func (m *mockUPnPClient) AddPortMapping(remoteHost string, extPort uint16, proto string, intPort uint16, intClient string, enabled bool, desc string, lease uint32) error {
+	if m.addErr != nil {
+		return m.addErr
+	}
+	m.lastMapping = &mockPortMapping{
+		remoteHost:  remoteHost,
+		extPort:     extPort,
+		protocol:    proto,
+		intPort:     intPort,
+		intClient:   intClient,
+		enabled:     enabled,
+		description: desc,
+		lease:       lease,
+	}
+	return nil
+}
+
+func (m *mockUPnPClient) DeletePortMapping(remoteHost string, extPort uint16, proto string) error {
+	return m.deleteErr
+}
+
+// --- Tests ---
+
+func TestNATPMPMapAndDelete(t *testing.T) {
+	srv := newMockNATPMP("203.0.113.42")
+	defer srv.Close()
+
+	conn, err := net.DialTimeout("udp4", srv.addr, time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+
+	// Map port
+	extPort, lifetime, err := natpmpMapPort(conn, 2, 8080, 8080, 3600)
+	if err != nil {
+		t.Fatalf("map: %v", err)
+	}
+	if extPort != 8080 {
+		t.Errorf("expected external port 8080, got %d", extPort)
+	}
+	if lifetime != 3600 {
+		t.Errorf("expected lifetime 3600, got %d", lifetime)
+	}
+
+	// Verify mapping stored
+	srv.mu.Lock()
+	m, ok := srv.mappings[8080]
+	srv.mu.Unlock()
+	if !ok {
+		t.Fatal("mapping not stored in server")
+	}
+	if m.protocol != 2 {
+		t.Errorf("expected TCP (2), got %d", m.protocol)
+	}
+
+	// Delete
+	_, _, err = natpmpMapPort(conn, 2, 8080, 0, 0)
+	if err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+
+	srv.mu.Lock()
+	_, ok = srv.mappings[8080]
+	srv.mu.Unlock()
+	if ok {
+		t.Error("mapping should have been deleted")
+	}
+}
+
+func TestNATPMPExternalIP(t *testing.T) {
+	srv := newMockNATPMP("93.184.216.34")
+	defer srv.Close()
+
+	conn, err := net.DialTimeout("udp4", srv.addr, time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+
+	ip := natpmpExternalIP(conn)
+	if ip != "93.184.216.34" {
+		t.Errorf("expected 93.184.216.34, got %q", ip)
+	}
+}
+
+func TestNATPMPExternalIPUnspecified(t *testing.T) {
+	srv := newMockNATPMP("0.0.0.0")
+	defer srv.Close()
+
+	conn, err := net.DialTimeout("udp4", srv.addr, time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+
+	ip := natpmpExternalIP(conn)
+	if ip != "" {
+		t.Errorf("expected empty for 0.0.0.0, got %q", ip)
+	}
+}
+
+func TestUPnPSetupMappingSuccess(t *testing.T) {
+	mock := &mockUPnPClient{externalIP: "198.51.100.1"}
+
+	mapping, err := setupMapping("192.168.1.1:1900", mock, 9000)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if mapping.ExternalIP != "198.51.100.1" {
+		t.Errorf("expected external IP 198.51.100.1, got %s", mapping.ExternalIP)
+	}
+	if mapping.ExternalPort != 9000 {
+		t.Errorf("expected port 9000, got %d", mapping.ExternalPort)
+	}
+	if mapping.protocol != "upnp" {
+		t.Errorf("expected protocol upnp, got %s", mapping.protocol)
+	}
+	if mock.lastMapping == nil {
+		t.Fatal("AddPortMapping not called")
+	}
+	if mock.lastMapping.protocol != "TCP" {
+		t.Errorf("expected TCP, got %s", mock.lastMapping.protocol)
+	}
+	if !mock.lastMapping.enabled {
+		t.Error("expected enabled=true")
+	}
+}
+
+func TestUPnPSetupMappingAddFails(t *testing.T) {
+	mock := &mockUPnPClient{
+		externalIP: "198.51.100.1",
+		addErr:     net.ErrClosed,
+	}
+
+	_, err := setupMapping("192.168.1.1:1900", mock, 9000)
+	if err == nil {
+		t.Fatal("expected error from AddPortMapping")
+	}
+}
+
+func TestUPnPSetupMappingEmptyIP(t *testing.T) {
+	// When router returns empty IP and public IP fallback also fails
+	mock := &mockUPnPClient{externalIP: ""}
+
+	// setupMapping calls publicIPFallback() which requires internet.
+	// In unit tests, this may or may not work. We just verify it doesn't panic.
+	mapping, err := setupMapping("192.168.1.1:1900", mock, 9000)
+	if err != nil {
+		// Expected if no internet / public IP fallback fails
+		t.Logf("expected failure with empty IP: %v", err)
+		return
+	}
+	// If it succeeded (has internet), verify the mapping is valid
+	if mapping.ExternalIP == "" {
+		t.Error("mapping should have a non-empty external IP")
+	}
+}
+
+func TestUPnPMappingRemoveNATPMP(t *testing.T) {
+	// Remove() connects to gateway:5351 (standard NAT-PMP port).
+	// We can't redirect to a mock easily, but verify it doesn't panic
+	// even when the gateway is unreachable.
+	mapping := &UPnPMapping{
+		ExternalIP:   "203.0.113.42",
+		ExternalPort: 8080,
+		InternalPort: 8080,
+		gateway:      "192.0.2.1", // RFC 5737 TEST-NET — unreachable
+		protocol:     "natpmp",
+	}
+	mapping.Remove() // should not panic, just log the error
+}
+
+func TestUPnPMappingRemoveUPnP(t *testing.T) {
+	mock := &mockUPnPClient{}
+	mapping := &UPnPMapping{
+		ExternalPort: 9000,
+		protocol:     "upnp",
+		client:       mock,
+	}
+	// Should not panic
+	mapping.Remove()
+}
+
+func TestUPnPMappingRemoveNil(t *testing.T) {
+	var m *UPnPMapping
+	m.Remove() // should not panic
+}
+
+func TestDefaultGateway(t *testing.T) {
+	gw := defaultGateway()
+	if gw == "" {
+		t.Skip("no network connectivity")
+	}
+	ip := net.ParseIP(gw)
+	if ip == nil {
+		t.Errorf("defaultGateway returned invalid IP: %q", gw)
+	}
+}
+
+func TestLocalIPFor(t *testing.T) {
+	ip := localIPFor("192.168.0.1:1900")
+	if ip == "0.0.0.0" {
+		t.Skip("no route to 192.168.0.1")
+	}
+	parsed := net.ParseIP(ip)
+	if parsed == nil {
+		t.Errorf("localIPFor returned invalid IP: %q", ip)
+	}
+}
diff --git a/internal/engine/usenet.go b/internal/engine/usenet.go
index fda121b..c39be86 100644
--- a/internal/engine/usenet.go
+++ b/internal/engine/usenet.go
@@ -300,8 +300,16 @@ func (u *UsenetDownloader) Pause(taskID string) error {
 
 // Cancel aborts an in-progress download and removes partial files + resume state.
 func (u *UsenetDownloader) Cancel(taskID string) error {
+	// Read all fields under the lock — Download() writes tracker and taskDir under
+	// the same lock, so we must hold it while reading to avoid a data race.
 	u.mu.Lock()
 	dl := u.active[taskID]
+	var tracker *download.ProgressTracker
+	var taskDir string
+	if dl != nil {
+		tracker = dl.tracker
+		taskDir = dl.taskDir
+	}
 	u.mu.Unlock()
 
 	if dl == nil {
@@ -312,13 +320,13 @@ func (u *UsenetDownloader) Cancel(taskID string) error {
 	dl.cancel()
 
 	// Remove resume state (best-effort)
-	if dl.tracker != nil {
-		dl.tracker.Remove()
+	if tracker != nil {
+		tracker.Remove()
 	}
 
 	// Remove partial download directory in background (can be slow for large dirs)
-	if dl.taskDir != "" {
-		go os.RemoveAll(dl.taskDir)
+	if taskDir != "" {
+		go os.RemoveAll(taskDir)
 	}
 
 	return nil
diff --git a/internal/engine/usenet_test.go b/internal/engine/usenet_test.go
new file mode 100644
index 0000000..8d8eba6
--- /dev/null
+++ b/internal/engine/usenet_test.go
@@ -0,0 +1,137 @@
+package engine
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+	"github.com/torrentclaw/unarr/internal/usenet/download"
+	"github.com/torrentclaw/unarr/internal/usenet/nzb"
+)
+
+// emptyNZB returns a minimal NZB with no files, suitable for test tracker creation.
+func emptyNZB() *nzb.NZB { return &nzb.NZB{} }
+
+// TestUsenetDownloader_Cancel_NoRace verifies that Cancel() reads tracker and taskDir
+// under the mutex, avoiding a data race with Download() which writes them under the same lock.
+// Run with -race to detect the race if it regresses.
+func TestUsenetDownloader_Cancel_NoRace(t *testing.T) {
+	u := NewUsenetDownloader(agent.NewClient("http://localhost", "", "test"))
+
+	const taskID = "race-test-taskid-123456"
+
+	// Inject a fake activeDownload without tracker/taskDir set yet.
+	// We only need the cancel func; discard the context itself.
+	_, cancel := context.WithCancel(context.Background())
+	dl := &activeDownload{cancel: cancel}
+	u.mu.Lock()
+	u.active[taskID] = dl
+	u.mu.Unlock()
+
+	var wg sync.WaitGroup
+
+	// Goroutine 1: simulates Download() setting tracker and taskDir under lock.
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < 50; i++ {
+			tracker := download.NewProgressTracker(taskID, emptyNZB(), t.TempDir())
+			u.mu.Lock()
+			dl.tracker = tracker
+			dl.taskDir = t.TempDir()
+			u.mu.Unlock()
+			time.Sleep(time.Microsecond)
+		}
+	}()
+
+	// Goroutine 2: calls Cancel() concurrently — must read under lock.
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < 50; i++ {
+			u.Cancel(taskID) //nolint:errcheck
+			time.Sleep(time.Microsecond)
+		}
+	}()
+
+	wg.Wait()
+}
+
+// TestUsenetDownloader_Cancel_NonExistent verifies Cancel on unknown task returns nil.
+func TestUsenetDownloader_Cancel_NonExistent(t *testing.T) {
+	u := NewUsenetDownloader(agent.NewClient("http://localhost", "", "test"))
+	if err := u.Cancel("no-such-task"); err != nil {
+		t.Errorf("Cancel non-existent task = %v, want nil", err)
+	}
+}
+
+// TestUsenetDownloader_Pause_NonExistent verifies Pause on unknown task returns nil.
+func TestUsenetDownloader_Pause_NonExistent(t *testing.T) {
+	u := NewUsenetDownloader(agent.NewClient("http://localhost", "", "test"))
+	if err := u.Pause("no-such-task"); err != nil {
+		t.Errorf("Pause non-existent task = %v, want nil", err)
+	}
+}
+
+func TestUsenetDownloader_MethodAndAvailable(t *testing.T) {
+	u := NewUsenetDownloader(agent.NewClient("http://localhost", "", "test"))
+	if got := u.Method(); got != MethodUsenet {
+		t.Errorf("Method = %v, want %v", got, MethodUsenet)
+	}
+
+	// Disabled → never available, no error.
+	u.SetEnabled(false)
+	ok, err := u.Available(context.Background(), &Task{Title: "Foo"})
+	if err != nil || ok {
+		t.Errorf("disabled Available = (%v,%v), want (false,nil)", ok, err)
+	}
+
+	u.SetEnabled(true)
+	// No IMDb / no title → not available, no error.
+	ok, err = u.Available(context.Background(), &Task{})
+	if err != nil || ok {
+		t.Errorf("empty task Available = (%v,%v), want (false,nil)", ok, err)
+	}
+
+	// Pre-resolved NzbID → available immediately.
+	ok, err = u.Available(context.Background(), &Task{NzbID: "preresolved", Title: "Bar"})
+	if err != nil || !ok {
+		t.Errorf("preresolved NzbID Available = (%v,%v), want (true,nil)", ok, err)
+	}
+}
+
+func TestUsenetDownloader_Shutdown(t *testing.T) {
+	u := NewUsenetDownloader(agent.NewClient("http://localhost", "", "test"))
+	// Inject a fake active download — Shutdown should cancel it and clear the map.
+	_, cancel := context.WithCancel(context.Background())
+	u.active["t1"] = &activeDownload{cancel: cancel}
+	if err := u.Shutdown(context.Background()); err != nil {
+		t.Errorf("Shutdown = %v, want nil", err)
+	}
+	if len(u.active) != 0 {
+		t.Errorf("Shutdown should clear active downloads, got %d", len(u.active))
+	}
+}
+
+func TestSanitizeDir(t *testing.T) {
+	cases := map[string]string{
+		"":                          "usenet_download",
+		"normal_name":               "normal_name",
+		"path/with/slashes":         "path_with_slashes",
+		`win\\bad:name*?"<>|`:       "win__bad_name______",
+		"con:tains/all\\bad?chars*": "con_tains_all_bad_chars_",
+	}
+	for in, want := range cases {
+		if got := sanitizeDir(in); got != want {
+			t.Errorf("sanitizeDir(%q) = %q, want %q", in, got, want)
+		}
+	}
+
+	long := strings.Repeat("a", 300)
+	if got := sanitizeDir(long); len(got) != 200 {
+		t.Errorf("expected sanitizeDir to truncate to 200, got %d", len(got))
+	}
+}
diff --git a/internal/engine/vaapi_args_test.go b/internal/engine/vaapi_args_test.go
new file mode 100644
index 0000000..33d0786
--- /dev/null
+++ b/internal/engine/vaapi_args_test.go
@@ -0,0 +1,97 @@
+package engine
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestBuildHLSFFmpegArgsVAAPI(t *testing.T) {
+	cfg := HLSSessionConfig{
+		SessionID:  "test",
+		SourcePath: "/tmp/test.mkv",
+		Quality:    "720p",
+		AudioIndex: 0,
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  "/usr/bin/ffmpeg",
+			FFprobePath: "/usr/bin/ffprobe",
+			HWAccel:     HWAccelVAAPI,
+		},
+	}
+	probe := &StreamProbe{Width: 1920, Height: 1080, DurationSec: 100}
+	args := buildHLSFFmpegArgsAt(cfg, probe, "/tmp/tmpdir", 0, 0)
+	got := strings.Join(args, " ")
+
+	wants := []string{
+		"-hwaccel vaapi",
+		"-vaapi_device /dev/dri/renderD128",
+		"-c:v h264_vaapi",
+		"format=nv12",
+		"hwupload",
+	}
+	for _, want := range wants {
+		if !strings.Contains(got, want) {
+			t.Errorf("argv missing %q\n%s", want, got)
+		}
+	}
+	if strings.Contains(got, "scale_vaapi") {
+		t.Errorf("argv unexpectedly contains scale_vaapi (mesa bug): %s", got)
+	}
+	if strings.Contains(got, "format=yuv420p") {
+		t.Errorf("argv contains format=yuv420p (libx264 path) for VAAPI codec: %s", got)
+	}
+}
+
+func TestBuildHLSFFmpegArgsLibx264NoRegression(t *testing.T) {
+	cfg := HLSSessionConfig{
+		SessionID:  "test",
+		SourcePath: "/tmp/test.mkv",
+		Quality:    "720p",
+		AudioIndex: 0,
+		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{"-c:v libx264", "format=yuv420p", "setparams=colorspace=bt709"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("libx264 argv missing %q: %s", want, got)
+		}
+	}
+	for _, bad := range []string{"-vaapi_device", "format=nv12", "hwupload"} {
+		if strings.Contains(got, bad) {
+			t.Errorf("libx264 argv unexpectedly contains %q: %s", bad, got)
+		}
+	}
+}
+
+// TestBuildHLSFFmpegArgsVAAPIDump prints the full argv buildHLSFFmpegArgsAt
+// emits for a typical VAAPI session. Mimics the daemon spawn step so the
+// operator can verify the ffmpeg command-line shape without booting the
+// stack — equivalent to `journalctl --user -u unarr-dev | grep ffmpeg`
+// but without waiting for a real player session.
+func TestBuildHLSFFmpegArgsVAAPIDump(t *testing.T) {
+	cfg := HLSSessionConfig{
+		SessionID:  "vaapi-smoke",
+		SourcePath: "/mnt/nas/peliculas/sample.mkv",
+		Quality:    "720p",
+		AudioIndex: -1,
+		Transcode: TranscodeRuntime{
+			FFmpegPath:  "/usr/bin/ffmpeg",
+			FFprobePath: "/usr/bin/ffprobe",
+			HWAccel:     HWAccelVAAPI,
+		},
+	}
+	probe := &StreamProbe{
+		VideoCodec:  "hevc",
+		Width:       3840,
+		Height:      2160,
+		DurationSec: 5400,
+		AudioTracks: []ProbeAudioTrack{{Index: 0, Lang: "en", Codec: "ac3"}},
+	}
+	args := buildHLSFFmpegArgsAt(cfg, probe, "/tmp/smoke-tmpdir", 0, 0)
+	t.Logf("ffmpeg %s", strings.Join(args, " "))
+}
diff --git a/internal/engine/validate.go b/internal/engine/validate.go
new file mode 100644
index 0000000..0efd4de
--- /dev/null
+++ b/internal/engine/validate.go
@@ -0,0 +1,63 @@
+// Package engine — validate.go centralises input validators used by the
+// stream/HLS HTTP handlers and the daemon glue. Keep new validators in this
+// file so a future reviewer can audit the trust boundary in one place.
+package engine
+
+import "regexp"
+
+// validSessionID restricts session IDs to characters safe for use as a single
+// filesystem path component. Server-issued UUIDs and hex strings match this;
+// anything containing slashes, dots, or path separators is rejected so a
+// compromised or buggy server cannot escape hlsTmpDirRoot via os.MkdirAll.
+var validSessionID = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,128}$`)
+
+// defaultCORSAllowedOrigins is the baseline of browser origins that may
+// XHR-probe `/health` and friends on the local daemon. Production hosts are
+// hardcoded; localhost on the dev port used by torrentclaw-web is included
+// so dev builds work without extra configuration. Operators may add more
+// origins via the [downloads] cors_extra_origins TOML key.
+//
+// The dev port matches `next dev -p 3030` in torrentclaw-web/package.json.
+// 127.0.0.1 is listed in addition to localhost because some browsers treat
+// them as distinct origins for CORS.
+//
+// Mirrors (`.to`, `staging.torrentclaw.com`, `www.`) are listed so a user
+// playing from any official mirror succeeds the HEAD probe; without these
+// the browser drops the response for "missing ACAO" and the player reports
+// "404 todos los canales" even though the daemon returned 200.
+//
+// Note: media tags (<video src>, <audio src>) do not send the Origin
+// header so they are not gated by CORS at all; this allowlist only
+// affects fetch()/XHR.
+var defaultCORSAllowedOrigins = []string{
+	"https://torrentclaw.com",
+	"https://www.torrentclaw.com",
+	"https://app.torrentclaw.com",
+	"https://staging.torrentclaw.com",
+	"https://torrentclaw.to",
+	"https://www.torrentclaw.to",
+	// 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
+	// sync by hand. Daemon also dynamically merges /api/mirrors at startup
+	// (see daemon.go) so a new key doesn't need a CLI rebuild.
+	"http://torrentf3aifidcsaaanmnmuhv2s53r6hqsl3zkmfidiaxainkeqk5id.onion",
+	"http://localhost:3030",
+	"http://127.0.0.1:3030",
+}
+
+// buildCORSAllowlist merges the default origins with any extras supplied by
+// the operator. Returned map is intended to be installed once at Listen()
+// and treated as read-only afterwards.
+func buildCORSAllowlist(extra []string) map[string]struct{} {
+	out := make(map[string]struct{}, len(defaultCORSAllowedOrigins)+len(extra))
+	for _, o := range defaultCORSAllowedOrigins {
+		out[o] = struct{}{}
+	}
+	for _, o := range extra {
+		if o != "" {
+			out[o] = struct{}{}
+		}
+	}
+	return out
+}
diff --git a/internal/engine/watch_reporter.go b/internal/engine/watch_reporter.go
new file mode 100644
index 0000000..9e6c185
--- /dev/null
+++ b/internal/engine/watch_reporter.go
@@ -0,0 +1,73 @@
+package engine
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+)
+
+// WatchReporter periodically sends watch progress to the API based on
+// HTTP Range request tracking from the StreamServer.
+type WatchReporter struct {
+	client      *agent.Client
+	server      *StreamServer
+	taskID      string
+	lastSentPct int // last progress percentage reported (0-100)
+}
+
+// NewWatchReporter creates a reporter that tracks playback progress via Range offsets.
+func NewWatchReporter(client *agent.Client, server *StreamServer, taskID string) *WatchReporter {
+	return &WatchReporter{
+		client: client,
+		server: server,
+		taskID: taskID,
+	}
+}
+
+// Run reports watch progress every 10 seconds until the context is cancelled.
+// A final report is sent on shutdown using a short independent timeout.
+func (wr *WatchReporter) Run(ctx context.Context) {
+	ticker := time.NewTicker(10 * time.Second)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			// Final report on shutdown — use background context since parent is cancelled.
+			finalCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+			wr.sendReport(finalCtx)
+			cancel()
+			return
+		case <-ticker.C:
+			wr.sendReport(ctx)
+		}
+	}
+}
+
+func (wr *WatchReporter) sendReport(ctx context.Context) {
+	pct, durSec := wr.server.EstimatedProgress()
+	if pct == 0 || pct == wr.lastSentPct {
+		return
+	}
+
+	wr.lastSentPct = pct
+	update := agent.WatchProgressUpdate{
+		TaskID:   wr.taskID,
+		Source:   "range",
+		Progress: &pct,
+	}
+	if durSec > 0 {
+		update.Duration = &durSec
+		pos := int(float64(pct) / 100 * float64(durSec))
+		update.Position = &pos
+	}
+
+	reportCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+
+	if err := wr.client.ReportWatchProgress(reportCtx, update); err != nil {
+		log.Printf("[%s] watch-progress: report failed: %v", wr.taskID[:8], err)
+	}
+}
diff --git a/internal/engine/watch_reporter_test.go b/internal/engine/watch_reporter_test.go
new file mode 100644
index 0000000..ec69a71
--- /dev/null
+++ b/internal/engine/watch_reporter_test.go
@@ -0,0 +1,240 @@
+package engine
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+)
+
+// ---------------------------------------------------------------------------
+// StreamServer.EstimatedProgress
+// ---------------------------------------------------------------------------
+
+func TestEstimatedProgress_NoFile(t *testing.T) {
+	ss := &StreamServer{}
+	pos, dur := ss.EstimatedProgress()
+	if pos != 0 || dur != 0 {
+		t.Errorf("expected (0, 0), got (%d, %d)", pos, dur)
+	}
+}
+
+func TestEstimatedProgress_HalfWay(t *testing.T) {
+	ss := &StreamServer{}
+	ss.totalFileSize.Store(1000)
+	ss.maxByteOffset.Store(500)
+
+	pos, _ := ss.EstimatedProgress()
+	if pos != 50 {
+		t.Errorf("expected pct=50, got %d", pos)
+	}
+}
+
+func TestEstimatedProgress_CapsAt100(t *testing.T) {
+	ss := &StreamServer{}
+	ss.totalFileSize.Store(1000)
+	ss.maxByteOffset.Store(1500)
+
+	pos, _ := ss.EstimatedProgress()
+	if pos != 100 {
+		t.Errorf("expected pct=100, got %d", pos)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// maxByteOffset only increases (simulated Range tracking)
+// ---------------------------------------------------------------------------
+
+func TestMaxByteOffsetNeverRegresses(t *testing.T) {
+	ss := &StreamServer{}
+	ss.totalFileSize.Store(10000)
+
+	offsets := []int64{0, 2000, 5000, 3000, 8000, 4000}
+	for _, off := range offsets {
+		for {
+			cur := ss.maxByteOffset.Load()
+			if off <= cur || ss.maxByteOffset.CompareAndSwap(cur, off) {
+				break
+			}
+		}
+	}
+
+	if ss.maxByteOffset.Load() != 8000 {
+		t.Errorf("expected 8000, got %d", ss.maxByteOffset.Load())
+	}
+}
+
+// ---------------------------------------------------------------------------
+// End-to-end: real HTTP server with Range requests
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// WatchReporter.sendReport via the agent API
+// ---------------------------------------------------------------------------
+
+func TestWatchReporter_NewWatchReporter(t *testing.T) {
+	c := agent.NewClient("http://localhost", "", "test")
+	ss := &StreamServer{}
+	wr := NewWatchReporter(c, ss, "task-1")
+	if wr.taskID != "task-1" || wr.client != c || wr.server != ss {
+		t.Errorf("NewWatchReporter fields not wired: %+v", wr)
+	}
+}
+
+func TestWatchReporter_sendReportSkipsZeroProgress(t *testing.T) {
+	var hits atomic.Int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		hits.Add(1)
+		_ = json.NewEncoder(w).Encode(map[string]any{"ok": true})
+	}))
+	defer srv.Close()
+
+	ss := &StreamServer{}
+	// totalFileSize == 0 → EstimatedProgress returns (0, 0) → sendReport skips.
+	c := agent.NewClient(srv.URL, "", "test")
+	wr := NewWatchReporter(c, ss, "task-1")
+	wr.sendReport(context.Background())
+	if hits.Load() != 0 {
+		t.Errorf("expected no API calls when progress=0, got %d", hits.Load())
+	}
+}
+
+func TestWatchReporter_sendReportPostsProgress(t *testing.T) {
+	var captured atomic.Pointer[agent.WatchProgressUpdate]
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var update agent.WatchProgressUpdate
+		_ = json.NewDecoder(r.Body).Decode(&update)
+		captured.Store(&update)
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	}))
+	defer srv.Close()
+
+	ss := &StreamServer{}
+	ss.totalFileSize.Store(1000)
+	ss.maxByteOffset.Store(250) // 25%
+	ss.durationSec.Store(120)
+
+	c := agent.NewClient(srv.URL, "", "test")
+	wr := NewWatchReporter(c, ss, "task-12345678")
+	wr.sendReport(context.Background())
+
+	got := captured.Load()
+	if got == nil {
+		t.Fatal("expected a watch-progress POST")
+	}
+	if got.TaskID != "task-12345678" {
+		t.Errorf("TaskID = %q", got.TaskID)
+	}
+	if got.Progress == nil || *got.Progress != 25 {
+		t.Errorf("Progress = %v, want 25", got.Progress)
+	}
+	if got.Duration == nil || *got.Duration != 120 {
+		t.Errorf("Duration = %v, want 120", got.Duration)
+	}
+	if got.Position == nil || *got.Position != 30 {
+		t.Errorf("Position = %v, want 30", got.Position)
+	}
+
+	// Repeat report at same percentage — should NOT POST again.
+	captured.Store(nil)
+	wr.sendReport(context.Background())
+	if captured.Load() != nil {
+		t.Errorf("repeat sendReport at same pct should be a no-op")
+	}
+}
+
+func TestWatchReporter_RunStopsOnContextCancel(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	}))
+	defer srv.Close()
+
+	ss := &StreamServer{}
+	c := agent.NewClient(srv.URL, "", "test")
+	wr := NewWatchReporter(c, ss, "task-x")
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() {
+		wr.Run(ctx)
+		close(done)
+	}()
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("Run did not return after context cancellation")
+	}
+}
+
+func TestStreamServerByteTracking(t *testing.T) {
+	// Create temp file (10 KB)
+	tmpFile := t.TempDir() + "/test.mp4"
+	data := make([]byte, 10240)
+	for i := range data {
+		data[i] = byte(i % 256)
+	}
+	if err := os.WriteFile(tmpFile, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	srv := NewStreamServer(0) // UPnP off by default — keep test hermetic
+	ctx := context.Background()
+	if err := srv.Listen(ctx); err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	defer srv.Shutdown(ctx)
+	srv.SetFile(NewDiskFileProvider(tmpFile), "test-task")
+	url := srv.URL()
+
+	// 1. Full GET — reads all bytes, maxByteOffset reaches file size
+	resp, err := http.Get(url)
+	if err != nil {
+		t.Fatalf("GET: %v", err)
+	}
+	io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+
+	if srv.maxByteOffset.Load() != 10240 {
+		t.Errorf("full read: expected 10240, got %d", srv.maxByteOffset.Load())
+	}
+
+	// 2. Reset and verify progress after partial read via Range
+	srv.SetFile(NewDiskFileProvider(tmpFile), "test-task-2")
+	if srv.maxByteOffset.Load() != 0 {
+		t.Errorf("after reset: expected 0, got %d", srv.maxByteOffset.Load())
+	}
+
+	// Range request reads from offset 5000 to end (5240 bytes)
+	req, _ := http.NewRequest("GET", url, nil)
+	req.Header.Set("Range", "bytes=5000-")
+	resp, err = http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("Range GET: %v", err)
+	}
+	if resp.StatusCode != http.StatusPartialContent {
+		t.Errorf("expected 206, got %d", resp.StatusCode)
+	}
+	io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+
+	// The reader reads 5240 bytes (from offset 5000 to 10240).
+	// maxByteOffset tracks the read position, which ends at 10240.
+	got := srv.maxByteOffset.Load()
+	if got != 10240 {
+		t.Errorf("after range read: expected 10240, got %d", got)
+	}
+
+	// 3. Verify progress reaches 100%
+	pos, _ := srv.EstimatedProgress()
+	if pos != 100 {
+		t.Errorf("expected pct=100, got %d", pos)
+	}
+}
diff --git a/internal/funnel/funnel.go b/internal/funnel/funnel.go
new file mode 100644
index 0000000..6a8640a
--- /dev/null
+++ b/internal/funnel/funnel.go
@@ -0,0 +1,199 @@
+// Package funnel manages the optional CloudFlare Quick Tunnel subprocess
+// that gives the daemon a public HTTPS hostname for cross-network playback
+// from browser-based clients (web player on torrentclaw.com / torrentclaw.to).
+//
+// Why: HTTPS pages can't fetch HTTP resources (mixed content). Without a
+// tunnel the daemon is only reachable from the same machine (localhost is
+// exempt) or via Tailscale (which users can install themselves but most
+// won't). CF Quick Tunnels are anonymous — no CF account, no DNS, no port
+// forwarding — and assign a one-shot `https://<random>.trycloudflare.com`
+// URL. Bytes flow through CF, never through our infra (legal posture: we
+// don't relay; CF does).
+//
+// Lifecycle:
+//
+//   t, err := funnel.Start(ctx, funnel.Config{Port: 11819})
+//   defer t.Close()
+//   url, err := t.WaitURL(30 * time.Second)  // blocks until cloudflared emits the URL
+//
+// The tunnel runs until the context is cancelled or t.Close() is called.
+package funnel
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os/exec"
+	"regexp"
+	"sync"
+	"time"
+)
+
+// urlPattern matches the `https://<random>.trycloudflare.com` URL cloudflared
+// prints when a Quick Tunnel is registered. The hostname has a random
+// hyphen-separated label followed by .trycloudflare.com.
+var urlPattern = regexp.MustCompile(`https://[a-z0-9-]+\.trycloudflare\.com`)
+
+// Config controls how the tunnel is launched.
+type Config struct {
+	// Port is the local upstream port cloudflared will tunnel to. Required.
+	Port int
+	// Binary is the cloudflared executable path. When empty the package looks
+	// it up via $PATH.
+	Binary string
+}
+
+// Tunnel is a handle on a running cloudflared Quick Tunnel.
+type Tunnel struct {
+	cmd     *exec.Cmd
+	cancel  context.CancelFunc
+	urlCh   chan string
+	exitCh  chan error
+	mu      sync.Mutex
+	url     string
+	stopped bool
+}
+
+// Start launches cloudflared as a subprocess. The returned *Tunnel exposes the
+// public URL via WaitURL once cloudflared registers it (usually 2–5 s).
+//
+// The subprocess inherits the cancellation of the supplied context. Closing
+// the *Tunnel sends SIGTERM and waits for the subprocess to exit.
+func Start(ctx context.Context, cfg Config) (*Tunnel, error) {
+	if cfg.Port <= 0 {
+		return nil, fmt.Errorf("funnel: invalid Port %d", cfg.Port)
+	}
+	binary := cfg.Binary
+	if binary == "" {
+		resolved, err := ResolveBinary()
+		if err != nil {
+			return nil, err
+		}
+		binary = resolved
+	}
+
+	subCtx, cancel := context.WithCancel(ctx)
+	// `--no-autoupdate` disables cloudflared's daily self-update check (the
+	// daemon manages binary rotation). `--metrics 127.0.0.1:0` suppresses the
+	// default `:9090` listener that would collide on a shared box.
+	cmd := exec.CommandContext(subCtx, binary,
+		"tunnel",
+		"--no-autoupdate",
+		"--metrics", "127.0.0.1:0",
+		"--url", fmt.Sprintf("http://localhost:%d", cfg.Port),
+	)
+
+	// cloudflared writes the connect log + assigned URL to stderr.
+	stderr, err := cmd.StderrPipe()
+	if err != nil {
+		cancel()
+		return nil, fmt.Errorf("funnel: pipe stderr: %w", err)
+	}
+	cmd.Stdout = io.Discard // quick tunnels print nothing useful on stdout
+
+	if err := cmd.Start(); err != nil {
+		cancel()
+		return nil, fmt.Errorf("funnel: start cloudflared: %w", err)
+	}
+
+	t := &Tunnel{
+		cmd:    cmd,
+		cancel: cancel,
+		urlCh:  make(chan string, 1),
+		exitCh: make(chan error, 1),
+	}
+
+	// Reader goroutine: scan cloudflared's stderr for the URL, surface the
+	// rest as a single string we don't try to interpret.
+	go t.scanStderr(stderr)
+
+	// Waiter goroutine: signal exit so callers can react (e.g. restart).
+	go func() {
+		t.exitCh <- cmd.Wait()
+	}()
+
+	return t, nil
+}
+
+// WaitURL blocks until cloudflared has registered the tunnel and emitted the
+// public URL, or `timeout` elapses, or the subprocess exits. The returned URL
+// has the form `https://<random>.trycloudflare.com`.
+func (t *Tunnel) WaitURL(timeout time.Duration) (string, error) {
+	t.mu.Lock()
+	if t.url != "" {
+		u := t.url
+		t.mu.Unlock()
+		return u, nil
+	}
+	t.mu.Unlock()
+
+	select {
+	case u := <-t.urlCh:
+		return u, nil
+	case err := <-t.exitCh:
+		if err == nil {
+			return "", errors.New("funnel: cloudflared exited before URL")
+		}
+		return "", fmt.Errorf("funnel: cloudflared exited: %w", err)
+	case <-time.After(timeout):
+		return "", fmt.Errorf("funnel: timed out waiting for URL after %s", timeout)
+	}
+}
+
+// URL returns the assigned tunnel URL, or "" if not yet emitted.
+func (t *Tunnel) URL() string {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.url
+}
+
+// Done returns a channel that closes once the subprocess exits. The error sent
+// before close describes the exit reason (nil = clean shutdown via Close).
+func (t *Tunnel) Done() <-chan error {
+	return t.exitCh
+}
+
+// Close terminates the subprocess and waits for it to exit. Safe to call
+// multiple times.
+func (t *Tunnel) Close() error {
+	t.mu.Lock()
+	if t.stopped {
+		t.mu.Unlock()
+		return nil
+	}
+	t.stopped = true
+	t.mu.Unlock()
+	t.cancel()
+	// Drain the exit channel so the Wait goroutine doesn't leak.
+	select {
+	case <-t.exitCh:
+	case <-time.After(5 * time.Second):
+	}
+	return nil
+}
+
+func (t *Tunnel) scanStderr(r io.Reader) {
+	scanner := bufio.NewScanner(r)
+	// Some cloudflared lines exceed the default 64KiB scanner buffer (when it
+	// prints connection diagnostics). Bump to 1MiB.
+	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if t.URL() == "" {
+			if m := urlPattern.FindString(line); m != "" {
+				t.mu.Lock()
+				t.url = m
+				t.mu.Unlock()
+				// Non-blocking send: if no one is listening, just drop —
+				// the URL field carries the value for any later WaitURL call.
+				select {
+				case t.urlCh <- m:
+				default:
+				}
+			}
+		}
+	}
+}
+
diff --git a/internal/funnel/install.go b/internal/funnel/install.go
new file mode 100644
index 0000000..1e827a4
--- /dev/null
+++ b/internal/funnel/install.go
@@ -0,0 +1,167 @@
+package funnel
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+// ResolveBinary returns the path to a usable cloudflared executable, downloading
+// one into the unarr data dir if neither $PATH nor the cached location has it.
+// This makes the funnel feature usable on headless installs (NAS / Docker)
+// where the user can't easily install cloudflared via the OS package manager.
+//
+// Resolution order:
+//
+//  1. cloudflared on $PATH (operator already installed it)
+//  2. <data-dir>/bin/cloudflared (we cached it on a previous run)
+//  3. download from GitHub releases (Linux-only fallback; macOS / Windows
+//     return a clear error pointing at brew / winget)
+func ResolveBinary() (string, error) {
+	if p, err := exec.LookPath("cloudflared"); err == nil {
+		return p, nil
+	}
+	cached := cachedBinaryPath()
+	if _, err := os.Stat(cached); err == nil {
+		return cached, nil
+	}
+	return downloadCloudflared(cached)
+}
+
+func cachedBinaryPath() string {
+	name := "cloudflared"
+	if runtime.GOOS == "windows" {
+		name += ".exe"
+	}
+	return filepath.Join(config.DataDir(), "bin", name)
+}
+
+// downloadCloudflared fetches the latest cloudflared release asset matching
+// the current GOOS/GOARCH into `dest`. Linux only — macOS/Windows return a
+// pointer at the OS package manager.
+//
+// Supply-chain caveat: we trust GitHub-over-TLS + cloudflare/cloudflared
+// repo integrity. The fetch is over HTTPS to api.github.com's release-asset
+// redirector, so a network MITM is bounded by Let's Encrypt + GitHub's cert
+// chain. We additionally verify the file is an ELF binary (Linux magic
+// bytes) so a generic 404 HTML page or a wrong-arch tarball is rejected at
+// rest. We do NOT verify a signature because Cloudflare doesn't sign release
+// assets at the moment — if you need stricter integrity, install cloudflared
+// from your distro's package manager (apt/brew/winget) and unarr will use
+// the PATH copy.
+func downloadCloudflared(dest string) (string, error) {
+	if runtime.GOOS != "linux" {
+		return "", fmt.Errorf("funnel: auto-download not supported on %s — install cloudflared manually or drop a binary at %s", runtime.GOOS, dest)
+	}
+
+	var asset string
+	switch runtime.GOARCH {
+	case "amd64":
+		asset = "cloudflared-linux-amd64"
+	case "arm64":
+		asset = "cloudflared-linux-arm64"
+	case "arm":
+		asset = "cloudflared-linux-armhf"
+	case "386":
+		asset = "cloudflared-linux-386"
+	default:
+		return "", fmt.Errorf("funnel: unsupported linux arch %q — install cloudflared manually", runtime.GOARCH)
+	}
+
+	url := "https://github.com/cloudflare/cloudflared/releases/latest/download/" + asset
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", fmt.Errorf("funnel: create bin dir: %w", err)
+	}
+
+	// O_EXCL so concurrent unarr-dev / prod daemons don't clobber each
+	// other's partial download. The loser gets EEXIST → falls back to
+	// polling for the winner to finish.
+	tmp := dest + ".partial"
+	out, err := os.OpenFile(tmp, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o755)
+	if err != nil {
+		if errors.Is(err, os.ErrExist) {
+			// Another process is downloading. Wait briefly for them to finish.
+			for range 60 {
+				time.Sleep(time.Second)
+				if _, statErr := os.Stat(dest); statErr == nil {
+					return dest, nil
+				}
+			}
+			return "", fmt.Errorf("funnel: another download in progress at %s (timed out)", tmp)
+		}
+		return "", fmt.Errorf("funnel: open dest: %w", err)
+	}
+
+	client := &http.Client{Timeout: 5 * time.Minute}
+	resp, err := client.Get(url)
+	if err != nil {
+		_ = out.Close()
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: download cloudflared: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		_ = out.Close()
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: download cloudflared: HTTP %d from %s", resp.StatusCode, url)
+	}
+
+	if _, err := io.Copy(out, resp.Body); err != nil {
+		_ = out.Close()
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: write dest: %w", err)
+	}
+	if err := out.Close(); err != nil {
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: close dest: %w", err)
+	}
+
+	// Sanity check before promoting <partial> to <dest>: must be a Linux
+	// ELF executable (rejects 404 HTML pages or wrong-arch payloads) and at
+	// least 1 MB (real cloudflared is ~50 MB; anything smaller is corrupt).
+	if err := verifyLinuxElf(tmp); err != nil {
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: downloaded file failed sanity check: %w", err)
+	}
+
+	if err := os.Rename(tmp, dest); err != nil {
+		_ = os.Remove(tmp)
+		return "", fmt.Errorf("funnel: rename dest: %w", err)
+	}
+	return dest, nil
+}
+
+// verifyLinuxElf returns nil when the file at `path` starts with the ELF
+// magic bytes and is at least 1 MB. Used as a low-cost guard against
+// downloading an HTML error page or a wrong-arch payload.
+func verifyLinuxElf(path string) error {
+	st, err := os.Stat(path)
+	if err != nil {
+		return err
+	}
+	if st.Size() < 1024*1024 {
+		return errors.New("file is suspiciously small (<1 MB)")
+	}
+	f, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	head := make([]byte, 4)
+	if _, err := io.ReadFull(f, head); err != nil {
+		return fmt.Errorf("read magic bytes: %w", err)
+	}
+	if !bytes.Equal(head, []byte{0x7f, 'E', 'L', 'F'}) {
+		return errors.New("not an ELF binary")
+	}
+	return nil
+}
diff --git a/internal/library/delete.go b/internal/library/delete.go
new file mode 100644
index 0000000..3920c6e
--- /dev/null
+++ b/internal/library/delete.go
@@ -0,0 +1,148 @@
+package library
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+)
+
+// DeleteFiles deletes the given library items from disk and cleans up empty
+// parent directories within the configured scan paths.
+//
+// Safety rules (all must pass before os.Remove is called):
+//  1. filePath must be an absolute path.
+//  2. filePath must be within one of the configured scanPaths.
+//  3. Empty parent directories are removed up to (but not including) the
+//     scan path root and only if they are not the scan path itself.
+//
+// Returns the IDs of items successfully deleted.
+func DeleteFiles(items []agent.LibraryDeleteRequest, scanPaths []string) []int {
+	// Sanitize scan paths: reject empty or non-absolute entries.
+	safe := make([]string, 0, len(scanPaths))
+	for _, sp := range scanPaths {
+		if filepath.IsAbs(sp) {
+			safe = append(safe, sp)
+		} else {
+			log.Printf("library: ignoring non-absolute scan path: %q", sp)
+		}
+	}
+	if len(safe) == 0 {
+		log.Printf("library: no valid scan paths configured — refusing to delete")
+		return nil
+	}
+
+	confirmed := make([]int, 0, len(items))
+
+	for _, item := range items {
+		if err := deleteOne(item.FilePath, safe); err != nil {
+			log.Printf("library: delete item %d (%q): %v", item.ItemID, item.FilePath, err)
+			continue
+		}
+		log.Printf("library: deleted item %d: %s", item.ItemID, item.FilePath)
+		confirmed = append(confirmed, item.ItemID)
+	}
+
+	return confirmed
+}
+
+func deleteOne(filePath string, scanPaths []string) error {
+	if !filepath.IsAbs(filePath) {
+		return fmt.Errorf("path is not absolute: %q", filePath)
+	}
+
+	clean := filepath.Clean(filePath)
+
+	// Resolve symlinks before validation to prevent traversal via symlinks.
+	real, err := filepath.EvalSymlinks(clean)
+	if err != nil {
+		if os.IsNotExist(err) {
+			// File already gone — idempotent success.
+			pruneEmptyDirs(filepath.Dir(clean), scanPaths)
+			return nil
+		}
+		return fmt.Errorf("resolve symlinks: %w", err)
+	}
+
+	// Security: resolved file must be within one of the configured scan paths.
+	if !isWithinScanPaths(real, scanPaths) {
+		return fmt.Errorf("path %q (resolved: %q) is outside all configured scan paths — refusing to delete", clean, real)
+	}
+
+	// Remove the file (idempotent: not-exist is not an error).
+	if err := os.Remove(real); err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("remove file: %w", err)
+	}
+
+	// Clean up empty parent directories, stopping at the scan path root.
+	pruneEmptyDirs(filepath.Dir(real), scanPaths)
+
+	return nil
+}
+
+// isWithinScanPaths returns true if p is a child of any scan path.
+func isWithinScanPaths(p string, scanPaths []string) bool {
+	for _, sp := range scanPaths {
+		sp = filepath.Clean(sp)
+		rel, err := filepath.Rel(sp, p)
+		if err != nil {
+			continue
+		}
+		// rel must not be "." (exact match = root itself) and must not start with ".."
+		if rel != "." && !strings.HasPrefix(rel, "..") {
+			return true
+		}
+	}
+	return false
+}
+
+// pruneEmptyDirs walks upward from dir, removing empty directories until it
+// reaches a scan path root (which is never removed).
+// Max 10 levels to guard against infinite loops on unexpected path shapes.
+func pruneEmptyDirs(dir string, scanPaths []string) {
+	const maxLevels = 10
+	for i := 0; i < maxLevels; i++ {
+		dir = filepath.Clean(dir)
+
+		// Single pass: stop if dir is a scan root or outside all scan paths.
+		if !dirEligibleForPrune(dir, scanPaths) {
+			return
+		}
+
+		entries, err := os.ReadDir(dir)
+		if err != nil || len(entries) > 0 {
+			return // non-empty or unreadable — stop
+		}
+
+		if err := os.Remove(dir); err != nil {
+			log.Printf("library: prune dir %s: %v", dir, err)
+			return
+		}
+		log.Printf("library: removed empty dir: %s", dir)
+
+		dir = filepath.Dir(dir)
+	}
+}
+
+// dirEligibleForPrune returns true if dir is a strict child of any scan path
+// (i.e. it is inside a scan path but is not the scan root itself).
+// Combines the former isScanPathRoot + isWithinScanPaths checks into one loop.
+func dirEligibleForPrune(dir string, scanPaths []string) bool {
+	for _, sp := range scanPaths {
+		sp = filepath.Clean(sp)
+		if sp == dir {
+			return false // dir IS the scan root — never remove it
+		}
+		rel, err := filepath.Rel(sp, dir)
+		if err != nil {
+			continue
+		}
+		if rel != "." && !strings.HasPrefix(rel, "..") {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/library/delete_test.go b/internal/library/delete_test.go
new file mode 100644
index 0000000..6b64142
--- /dev/null
+++ b/internal/library/delete_test.go
@@ -0,0 +1,414 @@
+package library
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+)
+
+// ---------------------------------------------------------------------------
+// isWithinScanPaths
+// ---------------------------------------------------------------------------
+
+func TestIsWithinScanPaths(t *testing.T) {
+	tests := []struct {
+		name      string
+		path      string
+		scanPaths []string
+		want      bool
+	}{
+		{
+			name:      "file inside scan path",
+			path:      "/media/movies/Inception.mkv",
+			scanPaths: []string{"/media/movies"},
+			want:      true,
+		},
+		{
+			name:      "file in subdirectory of scan path",
+			path:      "/media/movies/2024/Inception/Inception.mkv",
+			scanPaths: []string{"/media/movies"},
+			want:      true,
+		},
+		{
+			name:      "file at scan path root itself",
+			path:      "/media/movies",
+			scanPaths: []string{"/media/movies"},
+			want:      false, // rel == "."
+		},
+		{
+			name:      "file outside all scan paths",
+			path:      "/tmp/evil.mkv",
+			scanPaths: []string{"/media/movies", "/media/shows"},
+			want:      false,
+		},
+		{
+			name:      "dotdot traversal attempt",
+			path:      "/media/movies/../../../etc/passwd",
+			scanPaths: []string{"/media/movies"},
+			want:      false,
+		},
+		{
+			name:      "multiple scan paths file in second",
+			path:      "/media/shows/Breaking.Bad.S01E01.mkv",
+			scanPaths: []string{"/media/movies", "/media/shows"},
+			want:      true,
+		},
+		{
+			name:      "empty scan paths",
+			path:      "/media/movies/file.mkv",
+			scanPaths: []string{},
+			want:      false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isWithinScanPaths(tt.path, tt.scanPaths)
+			if got != tt.want {
+				t.Errorf("isWithinScanPaths(%q, %v) = %v, want %v", tt.path, tt.scanPaths, got, tt.want)
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// dirEligibleForPrune
+// ---------------------------------------------------------------------------
+
+func TestDirEligibleForPrune(t *testing.T) {
+	tests := []struct {
+		name      string
+		dir       string
+		scanPaths []string
+		want      bool
+	}{
+		{
+			name:      "scan root itself is NOT eligible",
+			dir:       "/media/movies",
+			scanPaths: []string{"/media/movies"},
+			want:      false,
+		},
+		{
+			name:      "subdirectory IS eligible",
+			dir:       "/media/movies/2024",
+			scanPaths: []string{"/media/movies"},
+			want:      true,
+		},
+		{
+			name:      "parent of scan path is NOT eligible",
+			dir:       "/media",
+			scanPaths: []string{"/media/movies"},
+			want:      false,
+		},
+		{
+			name:      "trailing slash normalization — root not eligible",
+			dir:       "/media/movies",
+			scanPaths: []string{"/media/movies/"},
+			want:      false, // filepath.Clean removes trailing slash
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := dirEligibleForPrune(tt.dir, tt.scanPaths)
+			if got != tt.want {
+				t.Errorf("dirEligibleForPrune(%q, %v) = %v, want %v", tt.dir, tt.scanPaths, got, tt.want)
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// deleteOne
+// ---------------------------------------------------------------------------
+
+func TestDeleteOne(t *testing.T) {
+	t.Run("delete existing file inside scan path", func(t *testing.T) {
+		root := t.TempDir()
+		file := filepath.Join(root, "movie.mkv")
+		if err := os.WriteFile(file, []byte("data"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		if err := deleteOne(file, []string{root}); err != nil {
+			t.Fatalf("deleteOne returned error: %v", err)
+		}
+
+		if _, err := os.Stat(file); !os.IsNotExist(err) {
+			t.Error("file should have been deleted")
+		}
+	})
+
+	t.Run("reject relative path", func(t *testing.T) {
+		root := t.TempDir()
+		err := deleteOne("relative/path.mkv", []string{root})
+		if err == nil {
+			t.Fatal("expected error for relative path")
+		}
+		if got := err.Error(); got != `path is not absolute: "relative/path.mkv"` {
+			t.Errorf("unexpected error message: %s", got)
+		}
+	})
+
+	t.Run("reject path outside scan paths", func(t *testing.T) {
+		scanRoot := t.TempDir()
+		outsideDir := t.TempDir()
+		file := filepath.Join(outsideDir, "secret.txt")
+		if err := os.WriteFile(file, []byte("secret"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		err := deleteOne(file, []string{scanRoot})
+		if err == nil {
+			t.Fatal("expected error for path outside scan paths")
+		}
+
+		// File must NOT have been deleted.
+		if _, statErr := os.Stat(file); statErr != nil {
+			t.Error("file outside scan path should NOT have been deleted")
+		}
+	})
+
+	t.Run("file already deleted is idempotent", func(t *testing.T) {
+		root := t.TempDir()
+		// Reference a file that does not exist.
+		file := filepath.Join(root, "gone.mkv")
+
+		if err := deleteOne(file, []string{root}); err != nil {
+			t.Fatalf("expected idempotent success, got error: %v", err)
+		}
+	})
+
+	t.Run("symlink pointing outside scan path is rejected", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("symlinks require elevated privileges on Windows")
+		}
+
+		scanRoot := t.TempDir()
+		outsideDir := t.TempDir()
+		outsideFile := filepath.Join(outsideDir, "real.mkv")
+		if err := os.WriteFile(outsideFile, []byte("real"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		link := filepath.Join(scanRoot, "link.mkv")
+		if err := os.Symlink(outsideFile, link); err != nil {
+			t.Fatal(err)
+		}
+
+		err := deleteOne(link, []string{scanRoot})
+		if err == nil {
+			t.Fatal("expected error: symlink target is outside scan paths")
+		}
+
+		// The real file must NOT have been deleted.
+		if _, statErr := os.Stat(outsideFile); statErr != nil {
+			t.Error("symlink target outside scan path should NOT have been deleted")
+		}
+	})
+
+	t.Run("symlink pointing inside scan path is allowed", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("symlinks require elevated privileges on Windows")
+		}
+
+		scanRoot := t.TempDir()
+		subdir := filepath.Join(scanRoot, "sub")
+		if err := os.Mkdir(subdir, 0755); err != nil {
+			t.Fatal(err)
+		}
+		realFile := filepath.Join(subdir, "real.mkv")
+		if err := os.WriteFile(realFile, []byte("data"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		link := filepath.Join(scanRoot, "link.mkv")
+		if err := os.Symlink(realFile, link); err != nil {
+			t.Fatal(err)
+		}
+
+		if err := deleteOne(link, []string{scanRoot}); err != nil {
+			t.Fatalf("deleteOne returned error: %v", err)
+		}
+
+		// The real file should have been deleted (os.Remove on resolved path).
+		if _, statErr := os.Stat(realFile); !os.IsNotExist(statErr) {
+			t.Error("resolved target inside scan path should have been deleted")
+		}
+	})
+}
+
+// ---------------------------------------------------------------------------
+// pruneEmptyDirs
+// ---------------------------------------------------------------------------
+
+func TestPruneEmptyDirs(t *testing.T) {
+	t.Run("empty parent dir is removed", func(t *testing.T) {
+		root := t.TempDir()
+		sub := filepath.Join(root, "show")
+		if err := os.Mkdir(sub, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		pruneEmptyDirs(sub, []string{root})
+
+		if _, err := os.Stat(sub); !os.IsNotExist(err) {
+			t.Error("empty subdirectory should have been removed")
+		}
+		// Scan root must still exist.
+		if _, err := os.Stat(root); err != nil {
+			t.Error("scan path root should NOT have been removed")
+		}
+	})
+
+	t.Run("non-empty parent dir is NOT removed", func(t *testing.T) {
+		root := t.TempDir()
+		sub := filepath.Join(root, "show")
+		if err := os.Mkdir(sub, 0755); err != nil {
+			t.Fatal(err)
+		}
+		// Put a file inside so it's not empty.
+		if err := os.WriteFile(filepath.Join(sub, "keep.txt"), []byte("x"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		pruneEmptyDirs(sub, []string{root})
+
+		if _, err := os.Stat(sub); err != nil {
+			t.Error("non-empty directory should NOT have been removed")
+		}
+	})
+
+	t.Run("stops at scan path root", func(t *testing.T) {
+		root := t.TempDir()
+		// Create an empty dir that IS the scan root.
+		// pruneEmptyDirs should refuse to remove it.
+		pruneEmptyDirs(root, []string{root})
+
+		if _, err := os.Stat(root); err != nil {
+			t.Error("scan path root should never be removed")
+		}
+	})
+
+	t.Run("multi-level cleanup", func(t *testing.T) {
+		root := t.TempDir()
+		deep := filepath.Join(root, "a", "b", "c")
+		if err := os.MkdirAll(deep, 0755); err != nil {
+			t.Fatal(err)
+		}
+
+		pruneEmptyDirs(deep, []string{root})
+
+		// All three levels (a, a/b, a/b/c) should be removed.
+		for _, dir := range []string{
+			filepath.Join(root, "a", "b", "c"),
+			filepath.Join(root, "a", "b"),
+			filepath.Join(root, "a"),
+		} {
+			if _, err := os.Stat(dir); !os.IsNotExist(err) {
+				t.Errorf("directory should have been removed: %s", dir)
+			}
+		}
+
+		// Scan root must still exist.
+		if _, err := os.Stat(root); err != nil {
+			t.Error("scan path root should NOT have been removed")
+		}
+	})
+}
+
+// ---------------------------------------------------------------------------
+// DeleteFiles (integration)
+// ---------------------------------------------------------------------------
+
+func TestDeleteFiles(t *testing.T) {
+	t.Run("multiple items some valid some invalid", func(t *testing.T) {
+		root := t.TempDir()
+		outsideDir := t.TempDir()
+		goodFile := filepath.Join(root, "good.mkv")
+		if err := os.WriteFile(goodFile, []byte("ok"), 0644); err != nil {
+			t.Fatal(err)
+		}
+		outsideFile := filepath.Join(outsideDir, "outside.mkv")
+		if err := os.WriteFile(outsideFile, []byte("nope"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		items := []agent.LibraryDeleteRequest{
+			{ItemID: 1, FilePath: goodFile},                        // valid → deleted
+			{ItemID: 2, FilePath: "relative/bad.mkv"},              // relative → rejected
+			{ItemID: 3, FilePath: outsideFile},                     // outside scan paths → rejected
+			{ItemID: 4, FilePath: filepath.Join(root, "gone.mkv")}, // not-exist → idempotent success
+		}
+
+		confirmed := DeleteFiles(items, []string{root})
+
+		// Items 1 and 4 should succeed. Item 2 (relative) and 3 (outside) should fail.
+		want := map[int]bool{1: true, 4: true}
+		got := make(map[int]bool, len(confirmed))
+		for _, id := range confirmed {
+			got[id] = true
+		}
+		if len(got) != len(want) {
+			t.Fatalf("confirmed = %v, want IDs %v", confirmed, want)
+		}
+		for id := range want {
+			if !got[id] {
+				t.Errorf("expected item %d to be confirmed", id)
+			}
+		}
+
+		// outsideFile must NOT have been deleted.
+		if _, err := os.Stat(outsideFile); err != nil {
+			t.Error("file outside scan paths should NOT have been deleted")
+		}
+
+		// good.mkv should be deleted.
+		if _, err := os.Stat(goodFile); !os.IsNotExist(err) {
+			t.Error("good.mkv should have been deleted")
+		}
+	})
+
+	t.Run("empty scan paths returns nil", func(t *testing.T) {
+		items := []agent.LibraryDeleteRequest{
+			{ItemID: 1, FilePath: "/some/file.mkv"},
+		}
+		confirmed := DeleteFiles(items, []string{})
+		if confirmed != nil {
+			t.Errorf("expected nil, got %v", confirmed)
+		}
+	})
+
+	t.Run("all relative scan paths returns nil", func(t *testing.T) {
+		items := []agent.LibraryDeleteRequest{
+			{ItemID: 1, FilePath: "/some/file.mkv"},
+		}
+		confirmed := DeleteFiles(items, []string{"relative/path", "another/relative"})
+		if confirmed != nil {
+			t.Errorf("expected nil, got %v", confirmed)
+		}
+	})
+
+	t.Run("mixed absolute and relative scan paths uses only absolute", func(t *testing.T) {
+		root := t.TempDir()
+		file := filepath.Join(root, "movie.mkv")
+		if err := os.WriteFile(file, []byte("data"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		items := []agent.LibraryDeleteRequest{
+			{ItemID: 10, FilePath: file},
+		}
+		confirmed := DeleteFiles(items, []string{"relative/bad", root})
+
+		if len(confirmed) != 1 || confirmed[0] != 10 {
+			t.Errorf("confirmed = %v, want [10]", confirmed)
+		}
+		if _, err := os.Stat(file); !os.IsNotExist(err) {
+			t.Error("file should have been deleted via the absolute scan path")
+		}
+	})
+}
diff --git a/internal/library/mediainfo/ffmpeg.go b/internal/library/mediainfo/ffmpeg.go
new file mode 100644
index 0000000..3bc910f
--- /dev/null
+++ b/internal/library/mediainfo/ffmpeg.go
@@ -0,0 +1,79 @@
+package mediainfo
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+)
+
+// ResolveFFmpeg finds the ffmpeg binary. Search order mirrors ResolveFFprobe
+// so the same operator setup works for both:
+//  1. Explicit path (--ffmpeg flag / library.ffmpeg_path config)
+//  2. FFMPEG_PATH env var
+//  3. "ffmpeg" on PATH
+//  4. Adjacent to the current executable (release tarball bundles ffmpeg
+//     next to the unarr binary — this is the preferred install path)
+//  5. Previously downloaded in the unarr cache dir
+//  6. Auto-download static binary as last resort (~50MB, slow start)
+//
+// ffmpeg is required for the HLS streaming pipeline; ffprobe alone can't
+// transcode HEVC/MKV to browser-friendly H.264/MP4 fragments.
+func ResolveFFmpeg(explicit string) (string, error) {
+	if explicit != "" {
+		if _, err := os.Stat(explicit); err == nil {
+			return explicit, nil
+		}
+		return "", fmt.Errorf("ffmpeg not found at explicit path: %s", explicit)
+	}
+
+	if envPath := os.Getenv("FFMPEG_PATH"); envPath != "" {
+		if _, err := os.Stat(envPath); err == nil {
+			return envPath, nil
+		}
+	}
+
+	if p, err := exec.LookPath("ffmpeg"); err == nil {
+		return p, nil
+	}
+
+	if exePath, err := os.Executable(); err == nil {
+		name := "ffmpeg"
+		if runtime.GOOS == "windows" {
+			name = "ffmpeg.exe"
+		}
+		adjacent := filepath.Join(filepath.Dir(exePath), name)
+		if _, err := os.Stat(adjacent); err == nil {
+			return adjacent, nil
+		}
+	}
+
+	if cached, err := FFmpegCachePath(); err == nil {
+		if _, err := os.Stat(cached); err == nil {
+			return cached, nil
+		}
+	}
+
+	if p, err := DownloadFFmpeg(); err == nil {
+		return p, nil
+	}
+
+	if isDocker() {
+		return "", fmt.Errorf(
+			"ffmpeg not found and auto-download failed (read-only filesystem?).\n" +
+				"Options:\n" +
+				"  • Use the official image: torrentclaw/unarr (includes ffmpeg)\n" +
+				"  • Set FFMPEG_PATH env var to point to a pre-installed ffmpeg binary\n" +
+				"  • Add to config.toml: [library]\\nffmpeg_path = \"/path/to/ffmpeg\"",
+		)
+	}
+	return "", fmt.Errorf(
+		"ffmpeg not found and auto-download failed.\n" +
+			"Options:\n" +
+			"  • Install ffmpeg: sudo apt install ffmpeg  (or brew install ffmpeg)\n" +
+			"  • Use the unarr release tarball — ffmpeg is bundled next to the binary\n" +
+			"  • Set FFMPEG_PATH env var to point to the ffmpeg binary\n" +
+			"  • Add to config.toml: [library]\\nffmpeg_path = \"/path/to/ffmpeg\"",
+	)
+}
diff --git a/internal/library/mediainfo/ffmpeg_download.go b/internal/library/mediainfo/ffmpeg_download.go
new file mode 100644
index 0000000..6d4f81c
--- /dev/null
+++ b/internal/library/mediainfo/ffmpeg_download.go
@@ -0,0 +1,116 @@
+package mediainfo
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+)
+
+const maxFFmpegZipSize = 200 * 1024 * 1024 // 200MB — ffmpeg static is ~70-100MB compressed
+
+// FFmpegCachePath returns the full path to the cached ffmpeg binary
+// (sibling of the cached ffprobe binary).
+func FFmpegCachePath() (string, error) {
+	dir, err := FFprobeCacheDir()
+	if err != nil {
+		return "", err
+	}
+	name := "ffmpeg"
+	if runtime.GOOS == "windows" {
+		name = "ffmpeg.exe"
+	}
+	return filepath.Join(dir, name), nil
+}
+
+// DownloadFFmpeg downloads a static ffmpeg binary for the current platform
+// and caches it locally. Returns the path to the binary. Reuses
+// resolveFFprobeURL's ffbinaries.com discovery endpoint — that index ships
+// both ffprobe and ffmpeg per platform.
+func DownloadFFmpeg() (string, error) {
+	dest, err := FFmpegCachePath()
+	if err != nil {
+		return "", fmt.Errorf("cannot determine cache path: %w", err)
+	}
+
+	if _, err := os.Stat(dest); err == nil {
+		return dest, nil
+	}
+
+	platform, err := ffprobePlatformKey()
+	if err != nil {
+		return "", err
+	}
+
+	url, err := resolveFFmpegURL(platform)
+	if err != nil {
+		return "", err
+	}
+
+	fmt.Fprintf(os.Stderr, "ffmpeg not found — downloading for %s (~70MB)...\n", platform)
+
+	resp, err := ffprobeDLClient.Get(url)
+	if err != nil {
+		return "", fmt.Errorf("download failed: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("download failed: HTTP %d", resp.StatusCode)
+	}
+
+	zipData, err := io.ReadAll(io.LimitReader(resp.Body, maxFFmpegZipSize))
+	if err != nil {
+		return "", fmt.Errorf("download read failed: %w", err)
+	}
+
+	name := "ffmpeg"
+	if runtime.GOOS == "windows" {
+		name = "ffmpeg.exe"
+	}
+
+	binary, err := extractFromZip(zipData, name)
+	if err != nil {
+		return "", err
+	}
+
+	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
+		return "", fmt.Errorf("cannot create cache directory: %w", err)
+	}
+
+	if err := os.WriteFile(dest, binary, 0o755); err != nil {
+		return "", fmt.Errorf("cannot write ffmpeg binary: %w", err)
+	}
+
+	fmt.Fprintf(os.Stderr, "ffmpeg installed to %s\n", dest)
+	return dest, nil
+}
+
+// resolveFFmpegURL fetches the ffbinaries index and returns the ffmpeg
+// download URL for the requested platform key (e.g. "linux-64").
+func resolveFFmpegURL(platform string) (string, error) {
+	resp, err := ffprobeAPIClient.Get(ffbinariesAPI)
+	if err != nil {
+		return "", fmt.Errorf("cannot reach ffbinaries.com: %w", err)
+	}
+	defer resp.Body.Close()
+
+	var data ffbinariesResponse
+	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
+		return "", fmt.Errorf("cannot parse ffbinaries response: %w", err)
+	}
+
+	bins, ok := data.Bin[platform]
+	if !ok {
+		return "", fmt.Errorf("no ffmpeg binary available for platform %q", platform)
+	}
+
+	url, ok := bins["ffmpeg"]
+	if !ok {
+		return "", fmt.Errorf("no ffmpeg download URL for platform %q", platform)
+	}
+
+	return url, nil
+}
diff --git a/internal/library/mediainfo/ffmpeg_test.go b/internal/library/mediainfo/ffmpeg_test.go
new file mode 100644
index 0000000..f2dd9af
--- /dev/null
+++ b/internal/library/mediainfo/ffmpeg_test.go
@@ -0,0 +1,78 @@
+package mediainfo
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+// TestResolveFFmpeg_ExplicitOK verifies the explicit-path branch returns
+// the requested binary if it exists on disk.
+func TestResolveFFmpeg_ExplicitOK(t *testing.T) {
+	dir := t.TempDir()
+	fake := filepath.Join(dir, "ffmpeg")
+	if err := os.WriteFile(fake, []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatalf("write fake: %v", err)
+	}
+
+	got, err := ResolveFFmpeg(fake)
+	if err != nil {
+		t.Fatalf("ResolveFFmpeg(explicit): %v", err)
+	}
+	if got != fake {
+		t.Fatalf("got %q want %q", got, fake)
+	}
+}
+
+// TestResolveFFmpeg_ExplicitMissing returns a clear error when the path
+// the operator supplied doesn't exist — we do NOT silently fall back.
+func TestResolveFFmpeg_ExplicitMissing(t *testing.T) {
+	_, err := ResolveFFmpeg("/nonexistent/path/ffmpeg-XXXXXX")
+	if err == nil {
+		t.Fatal("expected error for missing explicit path")
+	}
+}
+
+// TestResolveFFmpeg_EnvVar honours FFMPEG_PATH when no explicit path is given.
+func TestResolveFFmpeg_EnvVar(t *testing.T) {
+	dir := t.TempDir()
+	fake := filepath.Join(dir, "ffmpeg")
+	if err := os.WriteFile(fake, []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatalf("write fake: %v", err)
+	}
+	t.Setenv("FFMPEG_PATH", fake)
+	// Hide the real ffmpeg from PATH so the env var is the next branch hit.
+	t.Setenv("PATH", "/nonexistent")
+
+	got, err := ResolveFFmpeg("")
+	if err != nil {
+		t.Fatalf("ResolveFFmpeg(env): %v", err)
+	}
+	if got != fake {
+		t.Fatalf("got %q want %q (env-var branch)", got, fake)
+	}
+}
+
+// TestFFmpegCachePath returns a sibling path to the ffprobe cache,
+// consistent with the install layout the tarball produces.
+func TestFFmpegCachePath(t *testing.T) {
+	got, err := FFmpegCachePath()
+	if err != nil {
+		t.Fatalf("FFmpegCachePath: %v", err)
+	}
+	want := "ffmpeg"
+	if runtime.GOOS == "windows" {
+		want = "ffmpeg.exe"
+	}
+	if filepath.Base(got) != want {
+		t.Fatalf("cache path basename = %q want %q", filepath.Base(got), want)
+	}
+	probeCache, err := FFprobeCachePath()
+	if err != nil {
+		t.Fatalf("FFprobeCachePath: %v", err)
+	}
+	if filepath.Dir(got) != filepath.Dir(probeCache) {
+		t.Fatalf("ffmpeg cache (%s) and ffprobe cache (%s) should share a directory", got, probeCache)
+	}
+}
diff --git a/internal/library/mediainfo/ffprobe.go b/internal/library/mediainfo/ffprobe.go
index f2c70fb..5b33979 100644
--- a/internal/library/mediainfo/ffprobe.go
+++ b/internal/library/mediainfo/ffprobe.go
@@ -78,6 +78,12 @@ func ExtractMediaInfo(ctx context.Context, ffprobePath, filePath string) (*Media
 		return nil, fmt.Errorf("ffprobe JSON parse failed: %w", err)
 	}
 
+	return parseFFprobeOutput(data)
+}
+
+// parseFFprobeOutput converts parsed ffprobe JSON into MediaInfo.
+// Separated from ExtractMediaInfo so it can be tested without running ffprobe.
+func parseFFprobeOutput(data ffprobeOutput) (*MediaInfo, error) {
 	if len(data.Streams) == 0 {
 		return nil, fmt.Errorf("ffprobe returned no streams")
 	}
@@ -245,7 +251,29 @@ func ResolveFFprobe(explicit string) (string, error) {
 		return p, nil
 	}
 
-	return "", fmt.Errorf("ffprobe not found. Install ffmpeg or provide --ffprobe path")
+	// Give an actionable error depending on whether we're running in Docker.
+	if isDocker() {
+		return "", fmt.Errorf(
+			"ffprobe not found and auto-download failed (read-only filesystem?).\n" +
+				"Options:\n" +
+				"  • Use the official image: torrentclaw/unarr (includes ffprobe)\n" +
+				"  • Set FFPROBE_PATH env var to point to a pre-installed ffprobe binary\n" +
+				"  • Add to config.toml: [library]\\nffprobe_path = \"/path/to/ffprobe\"",
+		)
+	}
+	return "", fmt.Errorf(
+		"ffprobe not found and auto-download failed.\n" +
+			"Options:\n" +
+			"  • Install ffmpeg: sudo apt install ffmpeg  (or brew install ffmpeg)\n" +
+			"  • Set FFPROBE_PATH env var to point to the ffprobe binary\n" +
+			"  • Add to config.toml: [library]\\nffprobe_path = \"/path/to/ffprobe\"",
+	)
+}
+
+// isDocker reports whether the process is running inside a Docker container.
+func isDocker() bool {
+	_, err := os.Stat("/.dockerenv")
+	return err == nil
 }
 
 // tagValue gets a tag value case-insensitively.
diff --git a/internal/library/mediainfo/ffprobe_download.go b/internal/library/mediainfo/ffprobe_download.go
index ad7aeb6..bcd13db 100644
--- a/internal/library/mediainfo/ffprobe_download.go
+++ b/internal/library/mediainfo/ffprobe_download.go
@@ -38,6 +38,9 @@ func ffprobePlatformKey() (string, error) {
 			return "linux-arm64", nil
 		}
 	case "darwin":
+		if runtime.GOARCH == "arm64" {
+			return "osx-arm-64", nil
+		}
 		return "osx-64", nil
 	case "windows":
 		if runtime.GOARCH == "amd64" {
diff --git a/internal/library/mediainfo/ffprobe_download_test.go b/internal/library/mediainfo/ffprobe_download_test.go
new file mode 100644
index 0000000..4179519
--- /dev/null
+++ b/internal/library/mediainfo/ffprobe_download_test.go
@@ -0,0 +1,130 @@
+package mediainfo
+
+import (
+	"archive/zip"
+	"bytes"
+	"runtime"
+	"testing"
+)
+
+func TestFFprobePlatformKey(t *testing.T) {
+	key, err := ffprobePlatformKey()
+	if err != nil {
+		// Only error on unsupported platforms
+		if runtime.GOOS != "linux" && runtime.GOOS != "darwin" && runtime.GOOS != "windows" {
+			return // expected to fail on unsupported platforms
+		}
+		t.Fatalf("ffprobePlatformKey: %v", err)
+	}
+	if key == "" {
+		t.Error("platform key should not be empty")
+	}
+
+	// Verify format based on current platform
+	switch runtime.GOOS {
+	case "linux":
+		switch runtime.GOARCH {
+		case "amd64":
+			if key != "linux-64" {
+				t.Errorf("key = %q, want linux-64", key)
+			}
+		case "arm64":
+			if key != "linux-arm64" {
+				t.Errorf("key = %q, want linux-arm64", key)
+			}
+		}
+	case "darwin":
+		if key != "osx-64" {
+			t.Errorf("key = %q, want osx-64", key)
+		}
+	case "windows":
+		if runtime.GOARCH == "amd64" && key != "windows-64" {
+			t.Errorf("key = %q, want windows-64", key)
+		}
+	}
+}
+
+func TestFFprobeCacheDir(t *testing.T) {
+	dir, err := FFprobeCacheDir()
+	if err != nil {
+		t.Fatalf("FFprobeCacheDir: %v", err)
+	}
+	if dir == "" {
+		t.Error("cache dir should not be empty")
+	}
+}
+
+func TestFFprobeCachePath(t *testing.T) {
+	path, err := FFprobeCachePath()
+	if err != nil {
+		t.Fatalf("FFprobeCachePath: %v", err)
+	}
+	if path == "" {
+		t.Error("cache path should not be empty")
+	}
+}
+
+func TestExtractFromZip(t *testing.T) {
+	// Create a zip in memory containing a "ffprobe" file
+	var buf bytes.Buffer
+	w := zip.NewWriter(&buf)
+
+	content := []byte("fake ffprobe binary content")
+	f, err := w.Create("ffprobe")
+	if err != nil {
+		t.Fatal(err)
+	}
+	f.Write(content)
+
+	// Add another file to make it realistic
+	readme, _ := w.Create("README.md")
+	readme.Write([]byte("some readme"))
+
+	w.Close()
+
+	data, err := extractFromZip(buf.Bytes(), "ffprobe")
+	if err != nil {
+		t.Fatalf("extractFromZip: %v", err)
+	}
+	if string(data) != string(content) {
+		t.Errorf("content = %q, want %q", string(data), string(content))
+	}
+}
+
+func TestExtractFromZipNotFound(t *testing.T) {
+	var buf bytes.Buffer
+	w := zip.NewWriter(&buf)
+	f, _ := w.Create("other-file.txt")
+	f.Write([]byte("data"))
+	w.Close()
+
+	_, err := extractFromZip(buf.Bytes(), "ffprobe")
+	if err == nil {
+		t.Error("expected error when target not in zip")
+	}
+}
+
+func TestExtractFromZipInvalidData(t *testing.T) {
+	_, err := extractFromZip([]byte("not a zip"), "ffprobe")
+	if err == nil {
+		t.Error("expected error for invalid zip data")
+	}
+}
+
+func TestExtractFromZipWindowsExe(t *testing.T) {
+	var buf bytes.Buffer
+	w := zip.NewWriter(&buf)
+
+	content := []byte("fake exe")
+	f, _ := w.Create("bin/ffprobe.exe")
+	f.Write(content)
+	w.Close()
+
+	data, err := extractFromZip(buf.Bytes(), "ffprobe.exe")
+	if err != nil {
+		t.Fatalf("extractFromZip: %v", err)
+	}
+	if string(data) != string(content) {
+		t.Errorf("content mismatch")
+	}
+}
diff --git a/internal/library/mediainfo/ffprobe_test.go b/internal/library/mediainfo/ffprobe_test.go
new file mode 100644
index 0000000..e29eed1
--- /dev/null
+++ b/internal/library/mediainfo/ffprobe_test.go
@@ -0,0 +1,430 @@
+package mediainfo
+
+import (
+	"testing"
+)
+
+func TestParseDuration(t *testing.T) {
+	tests := []struct {
+		input string
+		want  float64
+	}{
+		{"", 0},
+		{"0", 0},
+		{"-5", 0},
+		{"invalid", 0},
+		{"7423.500000", 7423.5},
+		{"120.123456", 120.123},
+		{"3600", 3600},
+		{"0.001", 0.001},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got := parseDuration(tt.input)
+			if got != tt.want {
+				t.Errorf("parseDuration(%q) = %v, want %v", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestTagValue(t *testing.T) {
+	tags := map[string]string{
+		"language": "eng",
+		"title":    "Main Audio",
+		"HANDLER":  "VideoHandler",
+	}
+
+	tests := []struct {
+		key  string
+		want string
+	}{
+		{"language", "eng"},
+		{"title", "Main Audio"},
+		{"handler", "VideoHandler"},
+		{"missing", ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.key, func(t *testing.T) {
+			got := tagValue(tags, tt.key)
+			if got != tt.want {
+				t.Errorf("tagValue(tags, %q) = %q, want %q", tt.key, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestTagValueNil(t *testing.T) {
+	got := tagValue(nil, "language")
+	if got != "" {
+		t.Errorf("tagValue(nil, language) = %q, want empty", got)
+	}
+}
+
+func TestContainsAny(t *testing.T) {
+	tests := []struct {
+		s    string
+		subs []string
+		want bool
+	}{
+		{"yuv420p10le", []string{"10le", "10be", "p010"}, true},
+		{"yuv420p12be", []string{"10le", "10be", "p010"}, false},
+		{"yuv420p12be", []string{"12le", "12be"}, true},
+		{"yuv420p", []string{"10le", "10be"}, false},
+		{"", []string{"any"}, false},
+		{"something", []string{}, false},
+	}
+
+	for _, tt := range tests {
+		got := containsAny(tt.s, tt.subs...)
+		if got != tt.want {
+			t.Errorf("containsAny(%q, %v) = %v, want %v", tt.s, tt.subs, got, tt.want)
+		}
+	}
+}
+
+func TestParseFFprobeOutput_BasicH264(t *testing.T) {
+	data := ffprobeOutput{
+		Format: ffprobeFormat{Duration: "7423.5"},
+		Streams: []ffprobeStream{
+			{
+				CodecType:  "video",
+				CodecName:  "h264",
+				Profile:    "High",
+				Width:      1920,
+				Height:     1080,
+				RFrameRate: "24000/1001",
+			},
+			{
+				CodecType:   "audio",
+				CodecName:   "aac",
+				Channels:    2,
+				Tags:        map[string]string{"language": "eng"},
+				Disposition: map[string]int{"default": 1},
+			},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatalf("parseFFprobeOutput: %v", err)
+	}
+	if mi.Video == nil {
+		t.Fatal("expected video info")
+	}
+	if mi.Video.Codec != "h264" {
+		t.Errorf("codec = %q, want h264", mi.Video.Codec)
+	}
+	if mi.Video.Width != 1920 || mi.Video.Height != 1080 {
+		t.Errorf("dimensions = %dx%d, want 1920x1080", mi.Video.Width, mi.Video.Height)
+	}
+	if mi.Video.Profile != "High" {
+		t.Errorf("profile = %q, want High", mi.Video.Profile)
+	}
+	if mi.Video.Duration != 7423.5 {
+		t.Errorf("duration = %v, want 7423.5", mi.Video.Duration)
+	}
+	if mi.Video.FrameRate < 23.975 || mi.Video.FrameRate > 23.977 {
+		t.Errorf("frameRate = %v, want ~23.976", mi.Video.FrameRate)
+	}
+	if len(mi.Audio) != 1 {
+		t.Fatalf("audio tracks = %d, want 1", len(mi.Audio))
+	}
+	if mi.Audio[0].Lang != "en" {
+		t.Errorf("audio lang = %q, want en", mi.Audio[0].Lang)
+	}
+	if !mi.Audio[0].Default {
+		t.Error("expected default audio track")
+	}
+}
+
+func TestParseFFprobeOutput_HEVC_HDR10(t *testing.T) {
+	data := ffprobeOutput{
+		Format: ffprobeFormat{Duration: "3600"},
+		Streams: []ffprobeStream{
+			{
+				CodecType:     "video",
+				CodecName:     "hevc",
+				Width:         3840,
+				Height:        2160,
+				BitsPerRaw:    "10",
+				ColorSpace:    "bt2020nc",
+				ColorTransfer: "smpte2084",
+				RFrameRate:    "24/1",
+			},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.HDR != "HDR10" {
+		t.Errorf("hdr = %q, want HDR10", mi.Video.HDR)
+	}
+	if mi.Video.BitDepth != 10 {
+		t.Errorf("bitDepth = %d, want 10", mi.Video.BitDepth)
+	}
+}
+
+func TestParseFFprobeOutput_DolbyVisionWithHDR10(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{
+				CodecType:     "video",
+				CodecName:     "hevc",
+				Width:         3840,
+				Height:        2160,
+				ColorSpace:    "bt2020nc",
+				ColorTransfer: "smpte2084",
+				SideDataList:  []sideData{{SideDataType: "DOVI configuration record"}},
+			},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.HDR != "DV+HDR10" {
+		t.Errorf("hdr = %q, want DV+HDR10", mi.Video.HDR)
+	}
+}
+
+func TestParseFFprobeOutput_DolbyVisionOnly(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{
+				CodecType:    "video",
+				CodecName:    "hevc",
+				Width:        3840,
+				Height:       2160,
+				SideDataList: []sideData{{SideDataType: "DOVI configuration record"}},
+			},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.HDR != "DV" {
+		t.Errorf("hdr = %q, want DV", mi.Video.HDR)
+	}
+}
+
+func TestParseFFprobeOutput_HLG(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{
+				CodecType:     "video",
+				CodecName:     "hevc",
+				Width:         3840,
+				Height:        2160,
+				ColorSpace:    "bt2020nc",
+				ColorTransfer: "arib-std-b67",
+			},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.HDR != "HLG" {
+		t.Errorf("hdr = %q, want HLG", mi.Video.HDR)
+	}
+}
+
+func TestParseFFprobeOutput_MultiAudioAndSubtitles(t *testing.T) {
+	data := ffprobeOutput{
+		Format: ffprobeFormat{Duration: "5400"},
+		Streams: []ffprobeStream{
+			{CodecType: "video", CodecName: "h264", Width: 1920, Height: 1080},
+			{
+				CodecType: "audio", CodecName: "ac3", Channels: 6,
+				Tags:        map[string]string{"language": "eng", "title": "English 5.1"},
+				Disposition: map[string]int{"default": 1},
+			},
+			{
+				CodecType: "audio", CodecName: "aac", Channels: 2,
+				Tags: map[string]string{"language": "spa"},
+			},
+			{
+				CodecType: "subtitle", CodecName: "subrip",
+				Tags: map[string]string{"language": "eng"},
+			},
+			{
+				CodecType: "subtitle", CodecName: "ass",
+				Tags:        map[string]string{"language": "spa"},
+				Disposition: map[string]int{"forced": 1},
+			},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(mi.Audio) != 2 {
+		t.Fatalf("audio tracks = %d, want 2", len(mi.Audio))
+	}
+	if mi.Audio[0].Title != "English 5.1" {
+		t.Errorf("audio[0].title = %q", mi.Audio[0].Title)
+	}
+	if len(mi.Subtitles) != 2 {
+		t.Fatalf("subtitle tracks = %d, want 2", len(mi.Subtitles))
+	}
+	if !mi.Subtitles[1].Forced {
+		t.Error("expected subtitle[1] to be forced")
+	}
+	if len(mi.Languages) != 2 {
+		t.Errorf("languages = %v, want 2 entries", mi.Languages)
+	}
+}
+
+func TestParseFFprobeOutput_BitDepthFromPixFmt(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{CodecType: "video", CodecName: "hevc", Width: 1920, Height: 1080, PixFmt: "yuv420p10le"},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.BitDepth != 10 {
+		t.Errorf("bitDepth = %d, want 10", mi.Video.BitDepth)
+	}
+}
+
+func TestParseFFprobeOutput_12BitFromPixFmt(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{CodecType: "video", CodecName: "hevc", Width: 1920, Height: 1080, PixFmt: "yuv420p12be"},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.BitDepth != 12 {
+		t.Errorf("bitDepth = %d, want 12", mi.Video.BitDepth)
+	}
+}
+
+func TestParseFFprobeOutput_DurationFromStreamFallback(t *testing.T) {
+	data := ffprobeOutput{
+		Format: ffprobeFormat{Duration: ""},
+		Streams: []ffprobeStream{
+			{CodecType: "video", CodecName: "h264", Width: 1280, Height: 720, Duration: "1800.5"},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.Duration != 1800.5 {
+		t.Errorf("duration = %v, want 1800.5", mi.Video.Duration)
+	}
+}
+
+func TestParseFFprobeOutput_NoStreams(t *testing.T) {
+	data := ffprobeOutput{}
+	_, err := parseFFprobeOutput(data)
+	if err == nil {
+		t.Error("expected error for no streams")
+	}
+}
+
+func TestParseFFprobeOutput_OnlyFirstVideoStream(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{CodecType: "video", CodecName: "h264", Width: 1920, Height: 1080},
+			{CodecType: "video", CodecName: "mjpeg", Width: 320, Height: 240}, // cover art
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.Codec != "h264" {
+		t.Errorf("should use first video stream, got codec %q", mi.Video.Codec)
+	}
+	if mi.Video.Width != 1920 {
+		t.Errorf("width = %d, should be from first video stream", mi.Video.Width)
+	}
+}
+
+func TestParseFFprobeOutput_SMPTE2084_WithoutBT2020(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{CodecType: "video", CodecName: "hevc", Width: 3840, Height: 2160, ColorTransfer: "smpte2084"},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.HDR != "HDR10" {
+		t.Errorf("hdr = %q, want HDR10", mi.Video.HDR)
+	}
+}
+
+func TestParseFFprobeOutput_AribWithoutBT2020(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{CodecType: "video", CodecName: "hevc", Width: 3840, Height: 2160, ColorTransfer: "arib-std-b67", ColorSpace: "other"},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.HDR != "HLG" {
+		t.Errorf("hdr = %q, want HLG", mi.Video.HDR)
+	}
+}
+
+func TestParseFFprobeOutput_AudioOnly(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{CodecType: "audio", CodecName: "flac", Channels: 2, Tags: map[string]string{"language": "eng"}},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video != nil {
+		t.Error("expected no video info for audio-only")
+	}
+	if len(mi.Audio) != 1 {
+		t.Errorf("audio tracks = %d, want 1", len(mi.Audio))
+	}
+}
+
+func TestParseFFprobeOutput_FrameRateNoSlash(t *testing.T) {
+	data := ffprobeOutput{
+		Streams: []ffprobeStream{
+			{CodecType: "video", CodecName: "h264", Width: 1920, Height: 1080, RFrameRate: "30"},
+		},
+	}
+
+	mi, err := parseFFprobeOutput(data)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if mi.Video.FrameRate != 0 {
+		t.Errorf("frameRate = %v, want 0 (no slash)", mi.Video.FrameRate)
+	}
+}
diff --git a/internal/library/paths.go b/internal/library/paths.go
new file mode 100644
index 0000000..88752bf
--- /dev/null
+++ b/internal/library/paths.go
@@ -0,0 +1,55 @@
+package library
+
+import (
+	"path/filepath"
+	"strings"
+)
+
+// ResolveScanPaths returns a deduplicated list of directories to scan.
+// Always includes dlDir, moviesDir, tvDir (when non-empty).
+// Adds scanPath if non-empty.
+// Removes paths that are subdirectories of other paths in the list,
+// since a parent walk already covers them.
+func ResolveScanPaths(dlDir, moviesDir, tvDir, scanPath string) []string {
+	raw := make([]string, 0, 4)
+	for _, p := range []string{dlDir, moviesDir, tvDir, scanPath} {
+		if p != "" {
+			raw = append(raw, filepath.Clean(p))
+		}
+	}
+	return deduplicatePaths(raw)
+}
+
+// deduplicatePaths removes duplicate paths and paths that are subdirectories
+// of another path already present in the list.
+func deduplicatePaths(paths []string) []string {
+	// Remove exact duplicates first.
+	seen := make(map[string]bool, len(paths))
+	unique := make([]string, 0, len(paths))
+	for _, p := range paths {
+		if !seen[p] {
+			seen[p] = true
+			unique = append(unique, p)
+		}
+	}
+
+	// Remove paths that are subdirs of another path in the list.
+	result := make([]string, 0, len(unique))
+	for _, p := range unique {
+		isChild := false
+		for _, other := range unique {
+			if other == p {
+				continue
+			}
+			rel, err := filepath.Rel(other, p)
+			if err == nil && rel != "." && !strings.HasPrefix(rel, "..") {
+				isChild = true
+				break
+			}
+		}
+		if !isChild {
+			result = append(result, p)
+		}
+	}
+	return result
+}
diff --git a/internal/library/resolve.go b/internal/library/resolve.go
index 531fa3b..b9c16db 100644
--- a/internal/library/resolve.go
+++ b/internal/library/resolve.go
@@ -13,8 +13,17 @@ var (
 	altEpRegex  = regexp.MustCompile(`(?i)(\d{1,2})x(\d{2})`)
 )
 
-// ResolveResolution maps a pixel height to a standard resolution label.
-func ResolveResolution(height int) string {
+// ResolveResolution maps video dimensions to a standard resolution label.
+// Uses both width and height so cinematic aspect ratios (2.35:1, 2.39:1, 21:9)
+// are not misclassified — e.g. a 1080p source presented as 1920×804 letterboxed
+// would fall to 720p if classified by height alone.
+func ResolveResolution(width, height int) string {
+	byHeight := resolutionByHeight(height)
+	byWidth := resolutionByWidth(width)
+	return maxResolution(byHeight, byWidth)
+}
+
+func resolutionByHeight(height int) string {
 	switch {
 	case height >= 2000:
 		return "2160p"
@@ -29,6 +38,36 @@ func ResolveResolution(height int) string {
 	}
 }
 
+func resolutionByWidth(width int) string {
+	switch {
+	case width >= 3400:
+		return "2160p"
+	case width >= 1800:
+		return "1080p"
+	case width >= 1200:
+		return "720p"
+	case width >= 800:
+		return "480p"
+	default:
+		return ""
+	}
+}
+
+var resolutionRank = map[string]int{
+	"":      0,
+	"480p":  1,
+	"720p":  2,
+	"1080p": 3,
+	"2160p": 4,
+}
+
+func maxResolution(a, b string) string {
+	if resolutionRank[a] >= resolutionRank[b] {
+		return a
+	}
+	return b
+}
+
 // DeriveContentType guesses "movie" or "show" from parsed metadata.
 func DeriveContentType(item LibraryItem) string {
 	if item.Season > 0 || item.Episode > 0 {
diff --git a/internal/library/resolve_test.go b/internal/library/resolve_test.go
index c226e06..881768e 100644
--- a/internal/library/resolve_test.go
+++ b/internal/library/resolve_test.go
@@ -8,28 +8,31 @@ import (
 
 func TestResolveResolution(t *testing.T) {
 	tests := []struct {
+		name   string
+		width  int
 		height int
 		want   string
 	}{
-		{2160, "2160p"},
-		{2000, "2160p"},
-		{1080, "1080p"},
-		{1920, "1080p"}, // 1920 is width, not height — height for 1080p is ~1080
-		{900, "1080p"},
-		{720, "720p"},
-		{600, "720p"},
-		{576, "480p"},
-		{480, "480p"},
-		{400, "480p"},
-		{360, ""},
-		{0, ""},
+		{"4K square", 3840, 2160, "2160p"},
+		{"4K low height", 3840, 1600, "2160p"},
+		{"1080p square", 1920, 1080, "1080p"},
+		{"1080p cinematic 2.39:1", 1920, 804, "1080p"}, // anamorphic widescreen — must not fall to 720p
+		{"1080p cinematic 2.35:1", 1920, 818, "1080p"},
+		{"1080p 21:9", 2560, 1080, "1080p"},
+		{"720p square", 1280, 720, "720p"},
+		{"720p widescreen", 1280, 540, "720p"},
+		{"480p", 854, 480, "480p"},
+		{"sub-480", 640, 360, ""},
+		{"zero", 0, 0, ""},
 	}
 
 	for _, tt := range tests {
-		got := ResolveResolution(tt.height)
-		if got != tt.want {
-			t.Errorf("ResolveResolution(%d) = %q, want %q", tt.height, got, tt.want)
-		}
+		t.Run(tt.name, func(t *testing.T) {
+			got := ResolveResolution(tt.width, tt.height)
+			if got != tt.want {
+				t.Errorf("ResolveResolution(%d, %d) = %q, want %q", tt.width, tt.height, got, tt.want)
+			}
+		})
 	}
 }
 
diff --git a/internal/library/scanner_test.go b/internal/library/scanner_test.go
new file mode 100644
index 0000000..43c84b2
--- /dev/null
+++ b/internal/library/scanner_test.go
@@ -0,0 +1,93 @@
+package library
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestDiscoverFiles(t *testing.T) {
+	dir := t.TempDir()
+
+	// Create video files (need to be >= 100MB to pass size check)
+	largeContent := make([]byte, 101*1024*1024)
+
+	videoFiles := []string{"movie.mkv", "show.mp4", "clip.avi"}
+	for _, name := range videoFiles {
+		path := filepath.Join(dir, name)
+		if err := os.WriteFile(path, largeContent, 0o644); err != nil {
+			t.Fatalf("write %s: %v", name, err)
+		}
+	}
+
+	// Non-video files (should be excluded)
+	nonVideo := []string{"readme.txt", "cover.jpg", "subs.srt"}
+	for _, name := range nonVideo {
+		if err := os.WriteFile(filepath.Join(dir, name), largeContent, 0o644); err != nil {
+			t.Fatalf("write %s: %v", name, err)
+		}
+	}
+
+	// Small video file (should be excluded, < 100MB)
+	if err := os.WriteFile(filepath.Join(dir, "small.mkv"), []byte("small"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Excluded pattern (sample)
+	sampleDir := filepath.Join(dir, "sample")
+	os.MkdirAll(sampleDir, 0o755)
+	if err := os.WriteFile(filepath.Join(sampleDir, "sample.mkv"), largeContent, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	files, err := discoverFiles(dir)
+	if err != nil {
+		t.Fatalf("discoverFiles: %v", err)
+	}
+
+	if len(files) != 3 {
+		t.Errorf("expected 3 files, got %d: %v", len(files), files)
+	}
+
+	// Check that all returned files are video extensions
+	for _, f := range files {
+		ext := filepath.Ext(f)
+		if ext != ".mkv" && ext != ".mp4" && ext != ".avi" {
+			t.Errorf("unexpected extension: %s", ext)
+		}
+	}
+}
+
+func TestDiscoverFilesEmptyDir(t *testing.T) {
+	dir := t.TempDir()
+
+	files, err := discoverFiles(dir)
+	if err != nil {
+		t.Fatalf("discoverFiles: %v", err)
+	}
+	if len(files) != 0 {
+		t.Errorf("expected 0 files, got %d", len(files))
+	}
+}
+
+func TestDiscoverFilesExcludePatterns(t *testing.T) {
+	dir := t.TempDir()
+	largeContent := make([]byte, 101*1024*1024)
+
+	excludeDirs := []string{"trailer", "featurette", "extras", "bonus"}
+	for _, name := range excludeDirs {
+		sub := filepath.Join(dir, name)
+		os.MkdirAll(sub, 0o755)
+		if err := os.WriteFile(filepath.Join(sub, "video.mkv"), largeContent, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	files, err := discoverFiles(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(files) != 0 {
+		t.Errorf("expected 0 files (all excluded), got %d: %v", len(files), files)
+	}
+}
diff --git a/internal/library/sync.go b/internal/library/sync.go
index bafd054..f3cd9e6 100644
--- a/internal/library/sync.go
+++ b/internal/library/sync.go
@@ -23,7 +23,7 @@ func BuildSyncItems(cache *LibraryCache) []agent.LibrarySyncItem {
 
 		if item.MediaInfo != nil {
 			if item.MediaInfo.Video != nil {
-				si.Resolution = ResolveResolution(item.MediaInfo.Video.Height)
+				si.Resolution = ResolveResolution(item.MediaInfo.Video.Width, item.MediaInfo.Video.Height)
 				si.VideoCodec = item.MediaInfo.Video.Codec
 				si.HDR = item.MediaInfo.Video.HDR
 				si.BitDepth = item.MediaInfo.Video.BitDepth
diff --git a/internal/library/sync_test.go b/internal/library/sync_test.go
new file mode 100644
index 0000000..fe7a113
--- /dev/null
+++ b/internal/library/sync_test.go
@@ -0,0 +1,108 @@
+package library
+
+import (
+	"testing"
+
+	"github.com/torrentclaw/unarr/internal/library/mediainfo"
+)
+
+func TestBuildSyncItems(t *testing.T) {
+	cache := &LibraryCache{
+		Items: []LibraryItem{
+			{
+				FilePath: "/media/movies/Inception.mkv",
+				FileName: "Inception.2010.1080p.mkv",
+				FileSize: 5000000000,
+				Title:    "Inception",
+				Year:     "2010",
+				MediaInfo: &mediainfo.MediaInfo{
+					Video: &mediainfo.VideoInfo{
+						Codec:    "hevc",
+						Width:    1920,
+						Height:   1080,
+						BitDepth: 10,
+						HDR:      "HDR10",
+					},
+					Audio: []mediainfo.AudioTrack{
+						{Lang: "en", Codec: "ac3", Channels: 6, Default: true},
+						{Lang: "es", Codec: "aac", Channels: 2},
+					},
+					Subtitles: []mediainfo.SubtitleTrack{
+						{Lang: "en", Codec: "subrip"},
+						{Lang: "es", Codec: "subrip"},
+					},
+				},
+			},
+			{
+				FilePath: "/media/shows/Breaking.Bad.S01E01.mkv",
+				FileName: "Breaking.Bad.S01E01.mkv",
+				FileSize: 1000000000,
+				Title:    "Breaking Bad",
+				Season:   1,
+				Episode:  1,
+			},
+			{
+				// Item with scan error — should be skipped
+				FilePath:  "/media/bad.mkv",
+				FileName:  "bad.mkv",
+				ScanError: "ffprobe failed",
+			},
+		},
+	}
+
+	items := BuildSyncItems(cache)
+
+	if len(items) != 2 {
+		t.Fatalf("expected 2 items (1 skipped), got %d", len(items))
+	}
+
+	// First item: movie with full media info
+	movie := items[0]
+	if movie.Title != "Inception" {
+		t.Errorf("title = %q, want Inception", movie.Title)
+	}
+	if movie.ContentType != "movie" {
+		t.Errorf("contentType = %q, want movie", movie.ContentType)
+	}
+	if movie.Resolution != "1080p" {
+		t.Errorf("resolution = %q, want 1080p", movie.Resolution)
+	}
+	if movie.VideoCodec != "hevc" {
+		t.Errorf("videoCodec = %q, want hevc", movie.VideoCodec)
+	}
+	if movie.HDR != "HDR10" {
+		t.Errorf("hdr = %q, want HDR10", movie.HDR)
+	}
+	if movie.AudioCodec != "ac3" {
+		t.Errorf("audioCodec = %q, want ac3", movie.AudioCodec)
+	}
+	if movie.AudioChannels != 6 {
+		t.Errorf("audioChannels = %d, want 6", movie.AudioChannels)
+	}
+	if len(movie.AudioLanguages) != 2 {
+		t.Errorf("audioLanguages count = %d, want 2", len(movie.AudioLanguages))
+	}
+	if len(movie.SubtitleLanguages) != 2 {
+		t.Errorf("subtitleLanguages count = %d, want 2", len(movie.SubtitleLanguages))
+	}
+
+	// Second item: show without media info
+	show := items[1]
+	if show.ContentType != "show" {
+		t.Errorf("contentType = %q, want show", show.ContentType)
+	}
+	if show.Season != 1 || show.Episode != 1 {
+		t.Errorf("season/episode = %d/%d, want 1/1", show.Season, show.Episode)
+	}
+	if show.Resolution != "" {
+		t.Errorf("resolution should be empty, got %q", show.Resolution)
+	}
+}
+
+func TestBuildSyncItemsEmpty(t *testing.T) {
+	cache := &LibraryCache{Items: nil}
+	items := BuildSyncItems(cache)
+	if len(items) != 0 {
+		t.Errorf("expected 0 items, got %d", len(items))
+	}
+}
diff --git a/internal/mediaserver/detect_test.go b/internal/mediaserver/detect_test.go
index fc5b00e..19ba53c 100644
--- a/internal/mediaserver/detect_test.go
+++ b/internal/mediaserver/detect_test.go
@@ -2,6 +2,8 @@ package mediaserver
 
 import (
 	"encoding/json"
+	"os"
+	"path/filepath"
 	"testing"
 )
 
@@ -69,6 +71,96 @@ func TestJellyfinParsing(t *testing.T) {
 	}
 }
 
+func TestPlexTokenFromPrefs(t *testing.T) {
+	t.Run("valid prefs", func(t *testing.T) {
+		dir := t.TempDir()
+		prefsPath := filepath.Join(dir, "Preferences.xml")
+		xml := `<?xml version="1.0" encoding="utf-8"?>
+<Preferences PlexOnlineToken="my-secret-token" OldestPreviousVersion="1.0"/>`
+		os.WriteFile(prefsPath, []byte(xml), 0o644)
+
+		token := plexTokenFromPrefs(prefsPath)
+		if token != "my-secret-token" {
+			t.Errorf("token = %q, want my-secret-token", token)
+		}
+	})
+
+	t.Run("no token attr", func(t *testing.T) {
+		dir := t.TempDir()
+		prefsPath := filepath.Join(dir, "Preferences.xml")
+		xml := `<?xml version="1.0"?><Preferences/>`
+		os.WriteFile(prefsPath, []byte(xml), 0o644)
+
+		token := plexTokenFromPrefs(prefsPath)
+		if token != "" {
+			t.Errorf("token = %q, want empty", token)
+		}
+	})
+
+	t.Run("file not found", func(t *testing.T) {
+		token := plexTokenFromPrefs("/nonexistent/Preferences.xml")
+		if token != "" {
+			t.Errorf("token = %q, want empty", token)
+		}
+	})
+
+	t.Run("invalid xml", func(t *testing.T) {
+		dir := t.TempDir()
+		prefsPath := filepath.Join(dir, "Preferences.xml")
+		os.WriteFile(prefsPath, []byte("not xml at all"), 0o644)
+
+		token := plexTokenFromPrefs(prefsPath)
+		if token != "" {
+			t.Errorf("token = %q, want empty", token)
+		}
+	})
+}
+
+func TestParsePlexSectionsMultipleLocations(t *testing.T) {
+	body := `{
+		"MediaContainer": {
+			"Directory": [
+				{
+					"title": "Movies",
+					"Location": [
+						{"path": "/media/movies"},
+						{"path": "/media/movies2"}
+					]
+				}
+			]
+		}
+	}`
+
+	paths := parsePlexSections([]byte(body))
+	if len(paths) != 2 {
+		t.Fatalf("expected 2 paths, got %d", len(paths))
+	}
+}
+
+func TestParsePlexSectionsEmptyPath(t *testing.T) {
+	body := `{
+		"MediaContainer": {
+			"Directory": [
+				{
+					"Location": [{"path": ""}, {"path": "/valid"}]
+				}
+			]
+		}
+	}`
+
+	paths := parsePlexSections([]byte(body))
+	if len(paths) != 1 {
+		t.Fatalf("expected 1 path (empty filtered), got %d: %v", len(paths), paths)
+	}
+}
+
+func TestCommonMediaDirs(t *testing.T) {
+	dirs := commonMediaDirs()
+	if len(dirs) == 0 {
+		t.Error("expected at least some common media dirs")
+	}
+}
+
 func TestParentDir(t *testing.T) {
 	tests := []struct {
 		name   string
diff --git a/internal/sentry/sentry.go b/internal/sentry/sentry.go
index 633fc0d..3f16c08 100644
--- a/internal/sentry/sentry.go
+++ b/internal/sentry/sentry.go
@@ -1,12 +1,14 @@
 package sentry
 
 import (
+	"errors"
 	"os"
 	"runtime"
 	"strings"
 	"time"
 
 	gosentry "github.com/getsentry/sentry-go"
+	"github.com/spf13/pflag"
 )
 
 // dsn is injected at build time via ldflags. If empty, Sentry is disabled.
@@ -44,9 +46,16 @@ func Close() {
 	gosentry.Flush(flushTimeout)
 }
 
+// daemonNotRunningMarker matches the message of agent.ErrDaemonNotRunning
+// without importing the agent package — avoids a sentry → agent dependency
+// that would risk a cycle if agent ever needed to report errors itself.
+const daemonNotRunningMarker = "daemon does not appear to be running"
+
 // CaptureError sends a non-fatal error to Sentry with optional command context.
+// Expected non-bug errors (bad CLI input, daemon not running) are skipped to
+// keep the issue feed signal-heavy.
 func CaptureError(err error, command string) {
-	if err == nil {
+	if err == nil || shouldSkipSentry(err) {
 		return
 	}
 
@@ -58,6 +67,21 @@ func CaptureError(err error, command string) {
 	})
 }
 
+func shouldSkipSentry(err error) bool {
+	var notExist *pflag.NotExistError
+	var valueReq *pflag.ValueRequiredError
+	var invalidVal *pflag.InvalidValueError
+	var invalidSyn *pflag.InvalidSyntaxError
+	if errors.As(err, &notExist) || errors.As(err, &valueReq) ||
+		errors.As(err, &invalidVal) || errors.As(err, &invalidSyn) {
+		return true
+	}
+	msg := err.Error()
+	return strings.HasPrefix(msg, "unknown command ") ||
+		strings.HasPrefix(msg, "required flag(s)") ||
+		strings.Contains(msg, daemonNotRunningMarker)
+}
+
 // RecoverPanic captures a panic and re-panics after reporting.
 // Usage: defer sentry.RecoverPanic()
 func RecoverPanic() {
diff --git a/internal/sentry/sentry_test.go b/internal/sentry/sentry_test.go
new file mode 100644
index 0000000..4005d14
--- /dev/null
+++ b/internal/sentry/sentry_test.go
@@ -0,0 +1,64 @@
+package sentry
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestEnvironment(t *testing.T) {
+	tests := []struct {
+		version string
+		want    string
+	}{
+		{"", "development"},
+		{"dev", "development"},
+		{"0.1.0-dev", "development"},
+		{"1.0.0", "production"},
+		{"0.3.5", "production"},
+		{"2.0.0-beta", "production"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.version, func(t *testing.T) {
+			got := environment(tt.version)
+			if got != tt.want {
+				t.Errorf("environment(%q) = %q, want %q", tt.version, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestInitNoOp(t *testing.T) {
+	// With empty dsn (default in tests), Init should be a no-op
+	Init("1.0.0")
+	// Should not panic
+}
+
+func TestCloseNoOp(t *testing.T) {
+	// Close should be safe to call without Init
+	Close()
+}
+
+func TestCaptureErrorNil(t *testing.T) {
+	// Should not panic with nil error
+	CaptureError(nil, "test")
+}
+
+func TestSetUser(t *testing.T) {
+	// Should not panic without initialization
+	SetUser("agent-123")
+}
+
+func TestShouldSkipSentryDaemonNotRunning(t *testing.T) {
+	// String must stay in sync with agent.ErrDaemonNotRunning. If that sentinel
+	// is reworded, this test fails loudly so the marker can be updated.
+	err := errors.New("daemon does not appear to be running (state file not found)")
+	if !shouldSkipSentry(err) {
+		t.Error("ErrDaemonNotRunning message should be skipped")
+	}
+	wrapped := fmt.Errorf("read daemon state: %w", err)
+	if !shouldSkipSentry(wrapped) {
+		t.Error("wrapped ErrDaemonNotRunning message should be skipped")
+	}
+}
diff --git a/internal/ui/format_test.go b/internal/ui/format_test.go
index 7f3d2c5..a5633d4 100644
--- a/internal/ui/format_test.go
+++ b/internal/ui/format_test.go
@@ -1,7 +1,9 @@
 package ui
 
 import (
+	"fmt"
 	"testing"
+	"time"
 )
 
 func TestFormatSize(t *testing.T) {
@@ -127,6 +129,10 @@ func TestQualityIndicator(t *testing.T) {
 		{"medium", intPtr(60), "🟡"},
 		{"high", intPtr(80), "🟢"},
 		{"perfect", intPtr(100), "🟢"},
+		{"boundary_40", intPtr(40), "🟡"},
+		{"boundary_70", intPtr(70), "🟢"},
+		{"boundary_39", intPtr(39), "🔴"},
+		{"zero", intPtr(0), "🔴"},
 	}
 
 	for _, tt := range tests {
@@ -139,6 +145,52 @@ func TestQualityIndicator(t *testing.T) {
 	}
 }
 
+func TestSeedHealthIndicator(t *testing.T) {
+	tests := []struct {
+		seeds int
+		want  string
+	}{
+		{0, "🔴"},
+		{5, "🔴"},
+		{9, "🔴"},
+		{10, "🟡"},
+		{50, "🟡"},
+		{100, "🟡"},
+		{101, "🟢"},
+		{1000, "🟢"},
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("seeds_%d", tt.seeds), func(t *testing.T) {
+			got := SeedHealthIndicator(tt.seeds)
+			if got != tt.want {
+				t.Errorf("SeedHealthIndicator(%d) = %q, want %q", tt.seeds, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFormatRating(t *testing.T) {
+	tests := []struct {
+		name  string
+		input *string
+		want  string
+	}{
+		{"nil", nil, "-"},
+		{"value", strPtr("8.5"), "8.5"},
+		{"empty", strPtr(""), ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := FormatRating(tt.input)
+			if got != tt.want {
+				t.Errorf("FormatRating(%v) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
 func TestStringOrDash(t *testing.T) {
 	s := "hello"
 	if got := StringOrDash(&s); got != "hello" {
@@ -150,16 +202,160 @@ func TestStringOrDash(t *testing.T) {
 }
 
 func TestFormatContentType(t *testing.T) {
-	if got := FormatContentType("movie"); got != "Movie" {
-		t.Errorf("FormatContentType(movie) = %q, want Movie", got)
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"movie", "Movie"},
+		{"Movie", "Movie"},
+		{"MOVIE", "Movie"},
+		{"show", "Show"},
+		{"Show", "Show"},
+		{"other", "other"},
+		{"", ""},
 	}
-	if got := FormatContentType("show"); got != "Show" {
-		t.Errorf("FormatContentType(show) = %q, want Show", got)
-	}
-	if got := FormatContentType("other"); got != "other" {
-		t.Errorf("FormatContentType(other) = %q, want other", got)
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got := FormatContentType(tt.input)
+			if got != tt.want {
+				t.Errorf("FormatContentType(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
 	}
 }
 
-func ptr[T any](v T) *T { return &v }
-func intPtr(v int) *int { return &v }
+func TestFormatLanguages(t *testing.T) {
+	tests := []struct {
+		name  string
+		input []string
+		want  string
+	}{
+		{"nil", nil, "-"},
+		{"empty", []string{}, "-"},
+		{"single", []string{"en"}, "en"},
+		{"multiple", []string{"en", "es", "fr"}, "en, es, fr"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := FormatLanguages(tt.input)
+			if got != tt.want {
+				t.Errorf("FormatLanguages(%v) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFormatSeedRatio(t *testing.T) {
+	tests := []struct {
+		seeders  int
+		leechers int
+		want     string
+	}{
+		{0, 0, "0:0"},
+		{10, 0, "10:0"},
+		{100, 10, "10:1"},
+		{50, 50, "1:1"},
+		{1, 3, "0:1"},
+		{150, 10, "15:1"},
+	}
+
+	for _, tt := range tests {
+		t.Run(fmt.Sprintf("%d_%d", tt.seeders, tt.leechers), func(t *testing.T) {
+			got := FormatSeedRatio(tt.seeders, tt.leechers)
+			if got != tt.want {
+				t.Errorf("FormatSeedRatio(%d, %d) = %q, want %q", tt.seeders, tt.leechers, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFormatTimeAgo(t *testing.T) {
+	now := time.Now()
+
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{"invalid", "not-a-date", "not-a-date"},
+		{"just_now", now.Add(-10 * time.Second).Format(time.RFC3339), "just now"},
+		{"minutes", now.Add(-5 * time.Minute).Format(time.RFC3339), "5m ago"},
+		{"hours", now.Add(-3 * time.Hour).Format(time.RFC3339), "3h ago"},
+		{"days", now.Add(-7 * 24 * time.Hour).Format(time.RFC3339), "7d ago"},
+		{"months", now.Add(-60 * 24 * time.Hour).Format(time.RFC3339), "2mo ago"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := FormatTimeAgo(tt.input)
+			if got != tt.want {
+				t.Errorf("FormatTimeAgo(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFormatNumberExtended(t *testing.T) {
+	tests := []struct {
+		input int
+		want  string
+	}{
+		{-1000, "-1,000"},
+		{-5, "-5"},
+		{10000, "10,000"},
+		{100000, "100,000"},
+		{1000000, "1,000,000"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.want, func(t *testing.T) {
+			got := FormatNumber(tt.input)
+			if got != tt.want {
+				t.Errorf("FormatNumber(%d) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestTruncateStringEdgeCases(t *testing.T) {
+	tests := []struct {
+		name   string
+		input  string
+		maxLen int
+		want   string
+	}{
+		{"maxLen_1", "hello", 1, "h"},
+		{"maxLen_3", "hello", 3, "hel"},
+		{"empty", "", 5, ""},
+		{"unicode", "こんにちは世界", 5, "こん..."},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := TruncateString(tt.input, tt.maxLen)
+			if got != tt.want {
+				t.Errorf("TruncateString(%q, %d) = %q, want %q", tt.input, tt.maxLen, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestPtr(t *testing.T) {
+	v := 42
+	p := Ptr(v)
+	if *p != 42 {
+		t.Errorf("Ptr(42) = %d, want 42", *p)
+	}
+
+	s := "hello"
+	sp := Ptr(s)
+	if *sp != "hello" {
+		t.Errorf("Ptr(hello) = %q, want hello", *sp)
+	}
+}
+
+func ptr[T any](v T) *T       { return &v }
+func intPtr(v int) *int       { return &v }
+func strPtr(v string) *string { return &v }
diff --git a/internal/ui/table_test.go b/internal/ui/table_test.go
new file mode 100644
index 0000000..3b9abff
--- /dev/null
+++ b/internal/ui/table_test.go
@@ -0,0 +1,122 @@
+package ui
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	tc "github.com/torrentclaw/go-client"
+)
+
+func TestNewCleanTable(t *testing.T) {
+	var buf bytes.Buffer
+	tbl := newCleanTable(&buf)
+	tbl.Header([]string{"A", "B"})
+	tbl.Append([]string{"1", "2"})
+	tbl.Render()
+
+	out := buf.String()
+	if !strings.Contains(out, "A") || !strings.Contains(out, "B") {
+		t.Errorf("expected headers in output, got: %s", out)
+	}
+	if !strings.Contains(out, "1") || !strings.Contains(out, "2") {
+		t.Errorf("expected row data in output, got: %s", out)
+	}
+}
+
+func TestPrintSearchResultEntry(t *testing.T) {
+	var buf bytes.Buffer
+	year := 2010
+	rating := "8.8"
+	quality := "1080p"
+	codec := "x265"
+	size := int64(4294967296)
+	score := 85
+
+	r := tc.SearchResult{
+		Title:       "Inception",
+		Year:        &year,
+		ContentType: "movie",
+		RatingIMDb:  &rating,
+		Genres:      []string{"Sci-Fi", "Action"},
+		Torrents: []tc.TorrentInfo{
+			{
+				Quality:      &quality,
+				SizeBytes:    &size,
+				Seeders:      150,
+				Leechers:     10,
+				Source:       "YTS",
+				Codec:        &codec,
+				Languages:    []string{"en", "es"},
+				QualityScore: &score,
+			},
+		},
+	}
+
+	printSearchResultEntry(&buf, r)
+	out := buf.String()
+
+	if !strings.Contains(out, "Inception") {
+		t.Error("expected title in output")
+	}
+	if !strings.Contains(out, "2010") {
+		t.Error("expected year in output")
+	}
+	if !strings.Contains(out, "8.8") {
+		t.Error("expected rating in output")
+	}
+	if !strings.Contains(out, "1080p") {
+		t.Error("expected quality in output")
+	}
+	if !strings.Contains(out, "YTS") {
+		t.Error("expected source in output")
+	}
+}
+
+func TestPrintSearchResultEntryNoTorrents(t *testing.T) {
+	var buf bytes.Buffer
+	year := 2020
+
+	r := tc.SearchResult{
+		Title:       "No Torrents Movie",
+		Year:        &year,
+		ContentType: "movie",
+		Torrents:    nil,
+	}
+
+	printSearchResultEntry(&buf, r)
+	out := buf.String()
+
+	if !strings.Contains(out, "No Torrents Movie") {
+		t.Error("expected title in output")
+	}
+	if !strings.Contains(out, "No torrents available") {
+		t.Error("expected no-torrents message")
+	}
+}
+
+func TestPrintSearchResultEntryNilFields(t *testing.T) {
+	var buf bytes.Buffer
+
+	r := tc.SearchResult{
+		Title:       "Minimal",
+		ContentType: "movie",
+		Torrents: []tc.TorrentInfo{
+			{
+				Seeders:  5,
+				Leechers: 3,
+				Source:   "RARBG",
+			},
+		},
+	}
+
+	printSearchResultEntry(&buf, r)
+	out := buf.String()
+
+	if !strings.Contains(out, "Minimal") {
+		t.Error("expected title in output")
+	}
+	if !strings.Contains(out, "-") {
+		t.Error("expected dash for nil fields")
+	}
+}
diff --git a/internal/upgrade/cache.go b/internal/upgrade/cache.go
new file mode 100644
index 0000000..7cf5869
--- /dev/null
+++ b/internal/upgrade/cache.go
@@ -0,0 +1,79 @@
+package upgrade
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/config"
+)
+
+const cacheTTL = 1 * time.Hour
+
+// versionCache is the on-disk structure for cached version checks.
+type versionCache struct {
+	Version   string    `json:"version"`
+	CheckedAt time.Time `json:"checkedAt"`
+}
+
+// cacheFilePathFn returns the path to the version cache file.
+// Overridable in tests to avoid polluting the real cache.
+// NOTE: not safe for parallel tests — callers must not use t.Parallel().
+var cacheFilePathFn = func() string {
+	return filepath.Join(config.DataDir(), "latest-version.json")
+}
+
+// ReadCachedVersion returns the cached latest version if it's fresh (< cacheTTL).
+// Returns empty string if cache is missing, stale, or corrupt.
+func ReadCachedVersion() string {
+	data, err := os.ReadFile(cacheFilePathFn())
+	if err != nil {
+		return ""
+	}
+	var c versionCache
+	if json.Unmarshal(data, &c) != nil {
+		return ""
+	}
+	if time.Since(c.CheckedAt) > cacheTTL {
+		return ""
+	}
+	return c.Version
+}
+
+// writeCachedVersion writes the latest version to the cache file.
+func writeCachedVersion(version string) {
+	c := versionCache{
+		Version:   version,
+		CheckedAt: time.Now(),
+	}
+	data, err := json.Marshal(c)
+	if err != nil {
+		return
+	}
+	path := cacheFilePathFn()
+	os.MkdirAll(filepath.Dir(path), 0o755)
+	// Best-effort write — ignore errors
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, data, 0o644); err != nil {
+		return
+	}
+	if os.Rename(tmp, path) != nil {
+		os.Remove(tmp)
+	}
+}
+
+// CheckLatestCached returns the latest version, using cache when fresh.
+// If cache is stale, fetches from GitHub and updates the cache.
+func CheckLatestCached(ctx context.Context) (version string, fromCache bool, err error) {
+	if cached := ReadCachedVersion(); cached != "" {
+		return cached, true, nil
+	}
+	v, err := fetchLatestVersion(ctx)
+	if err != nil {
+		return "", false, err
+	}
+	writeCachedVersion(v)
+	return v, false, nil
+}
diff --git a/internal/upgrade/download.go b/internal/upgrade/download.go
index 99b94bc..958b08b 100644
--- a/internal/upgrade/download.go
+++ b/internal/upgrade/download.go
@@ -2,10 +2,10 @@ package upgrade
 
 import (
 	"bufio"
+	"bytes"
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
-	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
@@ -16,6 +16,43 @@ import (
 
 var httpClient = &http.Client{Timeout: 120 * time.Second}
 
+const (
+	maxDownloadRetries = 3
+	retryBaseDelay     = 5 * time.Second
+)
+
+// retryDelays returns the wait duration before the nth retry (1-based).
+// Delays: 5s, 15s — increasing gap to avoid hammering on transient failures.
+func retryDelay(attempt int) time.Duration {
+	return retryBaseDelay * time.Duration(attempt*attempt)
+}
+
+// downloadWithRetry fetches the release archive, retrying on transient errors.
+// onProgress is called with user-facing messages (may be nil).
+func downloadWithRetry(ctx context.Context, version string, onProgress func(string)) (string, error) {
+	var lastErr error
+	for attempt := 1; attempt <= maxDownloadRetries; attempt++ {
+		path, err := download(ctx, version)
+		if err == nil {
+			return path, nil
+		}
+		lastErr = err
+		if attempt < maxDownloadRetries {
+			delay := retryDelay(attempt)
+			if onProgress != nil {
+				onProgress(fmt.Sprintf("Download failed (%v)", err))
+				onProgress(fmt.Sprintf("Retrying in %s... (attempt %d/%d)", delay, attempt+1, maxDownloadRetries))
+			}
+			select {
+			case <-ctx.Done():
+				return "", ctx.Err()
+			case <-time.After(delay):
+			}
+		}
+	}
+	return "", lastErr
+}
+
 // download fetches the release archive to a temporary file.
 func download(ctx context.Context, version string) (string, error) {
 	url := releaseURL(version, archiveName(version))
@@ -51,7 +88,23 @@ func download(ctx context.Context, version string) (string, error) {
 }
 
 // verifyChecksum downloads checksums.txt and verifies the archive's SHA256.
+// When a release public key is embedded at build time (releasePubKeyBase64),
+// the function also verifies an ed25519 signature over checksums.txt before
+// trusting any hash inside it — this turns the checksum file from a passive
+// integrity check into an authenticated artifact that a maintainer or CI key
+// compromise cannot trivially forge.
 func verifyChecksum(ctx context.Context, version, archivePath string) error {
+	return verifyChecksumWithOptions(ctx, version, archivePath, true)
+}
+
+// verifyChecksumOnly skips the ed25519 signature step. Used by Upgrader
+// when --allow-unsigned is set and the release is known to predate signing
+// (or when a release accidentally shipped without a .sig file).
+func verifyChecksumOnly(ctx context.Context, version, archivePath string) error {
+	return verifyChecksumWithOptions(ctx, version, archivePath, false)
+}
+
+func verifyChecksumWithOptions(ctx context.Context, version, archivePath string, verifySignature bool) error {
 	// Download checksums.txt
 	url := releaseURL(version, "checksums.txt")
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
@@ -70,11 +123,28 @@ func verifyChecksum(ctx context.Context, version, archivePath string) error {
 		return fmt.Errorf("fetch checksums: HTTP %d", resp.StatusCode)
 	}
 
+	// Read the entire checksums.txt content first so we can both parse and
+	// verify the signature over the same bytes.
+	checksumsContent, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return fmt.Errorf("read checksums: %w", err)
+	}
+
+	// Verify ed25519 signature over checksums.txt before trusting its
+	// contents. Skipped silently when no key is embedded (handled by the
+	// caller via SignatureVerificationConfigured) or when the caller
+	// explicitly opts out via --allow-unsigned.
+	if verifySignature {
+		if err := verifyChecksumsSignature(ctx, version, checksumsContent); err != nil {
+			return fmt.Errorf("verify signature: %w", err)
+		}
+	}
+
 	// Parse checksums.txt — format: "<sha256>  <filename>"
 	expectedName := archiveName(version)
 	var expectedHash string
 
-	scanner := bufio.NewScanner(resp.Body)
+	scanner := bufio.NewScanner(bytes.NewReader(checksumsContent))
 	for scanner.Scan() {
 		line := scanner.Text()
 		parts := strings.Fields(line)
@@ -111,36 +181,35 @@ func verifyChecksum(ctx context.Context, version, archivePath string) error {
 	return nil
 }
 
-// fetchLatestVersion queries GitHub API for the latest release tag.
+// fetchLatestVersion queries the TorrentClaw release endpoint (/version) for the
+// latest version string (e.g. "0.8.1"). No GitHub dependency.
 func fetchLatestVersion(ctx context.Context) (string, error) {
-	url := fmt.Sprintf("https://api.github.com/repos/%s/releases/latest", githubRepo)
+	url := updateBaseURL + "/version"
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return "", err
 	}
-	req.Header.Set("Accept", "application/vnd.github+json")
 	req.Header.Set("User-Agent", "unarr-updater")
 
 	resp, err := httpClient.Do(req)
 	if err != nil {
-		return "", fmt.Errorf("fetch latest release: %w", err)
+		return "", fmt.Errorf("fetch latest version: %w", err)
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("GitHub API: HTTP %d", resp.StatusCode)
+		return "", fmt.Errorf("version endpoint: HTTP %d", resp.StatusCode)
 	}
 
-	var release struct {
-		TagName string `json:"tag_name"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&release); err != nil {
-		return "", fmt.Errorf("decode response: %w", err)
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 64))
+	if err != nil {
+		return "", fmt.Errorf("read version: %w", err)
 	}
 
-	if release.TagName == "" {
-		return "", fmt.Errorf("empty tag_name in release")
+	version := strings.TrimPrefix(strings.TrimSpace(string(body)), "v")
+	if version == "" {
+		return "", fmt.Errorf("empty version from %s", url)
 	}
 
-	return strings.TrimPrefix(release.TagName, "v"), nil
+	return version, nil
 }
diff --git a/internal/upgrade/extract.go b/internal/upgrade/extract.go
index 493e20d..e103e0b 100644
--- a/internal/upgrade/extract.go
+++ b/internal/upgrade/extract.go
@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"path"
 	"path/filepath"
 	"runtime"
 	"strings"
@@ -85,15 +86,22 @@ func extractZip(archivePath, destDir string) (string, error) {
 
 	target := binaryName + ".exe"
 
-	for _, f := range r.File {
-		name := filepath.Base(f.Name)
+	// Resolve destDir to its absolute form once so the ZIP-slip check below
+	// can compare canonical paths instead of fragile substring matches.
+	absDest, err := filepath.Abs(destDir)
+	if err != nil {
+		return "", fmt.Errorf("resolve dest: %w", err)
+	}
 
-		// Guard against path traversal
-		if strings.Contains(f.Name, "..") {
+	for _, f := range r.File {
+		if f.FileInfo().IsDir() {
 			continue
 		}
-
-		if name != target {
+		if filepath.Base(f.Name) != target {
+			continue
+		}
+		absDst, ok := safeZipPath(f.Name, target, absDest)
+		if !ok {
 			continue
 		}
 
@@ -102,8 +110,7 @@ func extractZip(archivePath, destDir string) (string, error) {
 			return "", err
 		}
 
-		dst := filepath.Join(destDir, target)
-		out, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o755)
+		out, err := os.OpenFile(absDst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o755)
 		if err != nil {
 			rc.Close()
 			return "", err
@@ -116,8 +123,41 @@ func extractZip(archivePath, destDir string) (string, error) {
 		}
 		out.Close()
 		rc.Close()
-		return dst, nil
+		return absDst, nil
 	}
 
 	return "", fmt.Errorf("binary %q not found in archive", target)
 }
+
+// safeZipPath validates that a ZIP entry name is safe to extract under
+// absDest, then returns the absolute destination path (always
+// absDest/target, never the raw entry name — we still only extract files
+// matched by Base name).
+//
+// Rejected: absolute paths, paths that resolve to "..", paths containing
+// a "../" or "..\\" component, and any entry whose final destination
+// would land outside absDest. The check uses path.Clean on the entry's
+// native separator (ZIP uses forward slashes by spec, but some authors
+// emit backslashes — we treat both as separators here so a hostile entry
+// on Linux can't bypass the substring scan).
+func safeZipPath(entryName, target, absDest string) (string, bool) {
+	// Normalise both separators to "/" so the check works on Linux too,
+	// where filepath.Separator is "/" and a hostile "..\\foo" string is
+	// otherwise treated as a single filename component by filepath.Clean.
+	normalised := strings.ReplaceAll(entryName, `\`, "/")
+	cleaned := path.Clean(normalised)
+	if cleaned == ".." ||
+		strings.HasPrefix(cleaned, "../") ||
+		strings.Contains(cleaned, "/../") ||
+		path.IsAbs(cleaned) {
+		return "", false
+	}
+	absDst, err := filepath.Abs(filepath.Join(absDest, target))
+	if err != nil {
+		return "", false
+	}
+	if !strings.HasPrefix(absDst+string(filepath.Separator), absDest+string(filepath.Separator)) {
+		return "", false
+	}
+	return absDst, true
+}
diff --git a/internal/upgrade/signature.go b/internal/upgrade/signature.go
new file mode 100644
index 0000000..cfcc93d
--- /dev/null
+++ b/internal/upgrade/signature.go
@@ -0,0 +1,112 @@
+package upgrade
+
+import (
+	"context"
+	"crypto/ed25519"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+)
+
+// releasePubKeyBase64 is the base64-encoded ed25519 public key used to verify
+// `checksums.txt.sig` against `checksums.txt` during self-update.
+//
+// It is overridable at link time via ldflags so the same source compiles for
+// users who do not yet have a release-signing keypair in their CI:
+//
+//	-X github.com/torrentclaw/unarr/internal/upgrade.releasePubKeyBase64=<base64-pubkey>
+//
+// When the variable is empty, signature verification is skipped and a warning
+// is logged — checksum-only verification remains in force. This is the
+// transitional default until the keypair is provisioned; flip to a non-empty
+// value (and enable the corresponding CI signing step) to make signature
+// verification mandatory.
+var releasePubKeyBase64 = ""
+
+// ErrMissingSignature indicates the release does not ship a `.sig` file even
+// though signature verification is required by an embedded public key.
+var ErrMissingSignature = errors.New("release signature file is missing")
+
+// verifyChecksumsSignature downloads `checksums.txt.sig` (raw 64-byte ed25519
+// signature over the checksums.txt content) and verifies it with the embedded
+// public key. Returns nil if verification succeeds or if no public key has
+// been embedded yet (caller is expected to surface a warning in that case).
+func verifyChecksumsSignature(ctx context.Context, version string, checksumsContent []byte) error {
+	pubKey, err := loadReleasePubKey()
+	if err != nil {
+		return fmt.Errorf("load release pubkey: %w", err)
+	}
+	if pubKey == nil {
+		// Signature verification not configured; caller decides what to do.
+		return nil
+	}
+
+	url := releaseURL(version, "checksums.txt.sig")
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("User-Agent", "unarr-updater")
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("fetch signature: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusNotFound {
+		return ErrMissingSignature
+	}
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("fetch signature: HTTP %d", resp.StatusCode)
+	}
+
+	// Signature file is base64(signature)\n — small and bounded.
+	rawSig, err := io.ReadAll(io.LimitReader(resp.Body, 8*1024))
+	if err != nil {
+		return fmt.Errorf("read signature: %w", err)
+	}
+	sig, err := decodeSignature(rawSig)
+	if err != nil {
+		return fmt.Errorf("decode signature: %w", err)
+	}
+	if len(sig) != ed25519.SignatureSize {
+		return fmt.Errorf("signature size %d, expected %d", len(sig), ed25519.SignatureSize)
+	}
+	if !ed25519.Verify(pubKey, checksumsContent, sig) {
+		return errors.New("ed25519 signature verification failed")
+	}
+	return nil
+}
+
+// SignatureVerificationConfigured reports whether the build has a release
+// public key embedded. The CLI surfaces this so users running a non-signed
+// build get a clear warning rather than silent trust.
+func SignatureVerificationConfigured() bool {
+	pubKey, err := loadReleasePubKey()
+	return err == nil && pubKey != nil
+}
+
+func loadReleasePubKey() (ed25519.PublicKey, error) {
+	v := strings.TrimSpace(releasePubKeyBase64)
+	if v == "" {
+		return nil, nil
+	}
+	raw, err := base64.StdEncoding.DecodeString(v)
+	if err != nil {
+		return nil, fmt.Errorf("base64 decode: %w", err)
+	}
+	if len(raw) != ed25519.PublicKeySize {
+		return nil, fmt.Errorf("pubkey size %d, expected %d", len(raw), ed25519.PublicKeySize)
+	}
+	return ed25519.PublicKey(raw), nil
+}
+
+// decodeSignature parses the base64-encoded signature emitted by
+// scripts/sign-checksums (always base64 + trailing newline). A single
+// expected format keeps the surface area minimal — a stricter parser is
+// less likely to accept a hostile mirror's coincidentally-sized payload.
+func decodeSignature(raw []byte) ([]byte, error) {
+	return base64.StdEncoding.DecodeString(strings.TrimSpace(string(raw)))
+}
diff --git a/internal/upgrade/signature_test.go b/internal/upgrade/signature_test.go
new file mode 100644
index 0000000..2075987
--- /dev/null
+++ b/internal/upgrade/signature_test.go
@@ -0,0 +1,134 @@
+package upgrade
+
+import (
+	"context"
+	"crypto/ed25519"
+	"crypto/rand"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// withReleasePubKey temporarily swaps the embedded release public key and
+// restores the previous value on test exit.
+func withReleasePubKey(t *testing.T, encoded string) {
+	t.Helper()
+	prev := releasePubKeyBase64
+	releasePubKeyBase64 = encoded
+	t.Cleanup(func() { releasePubKeyBase64 = prev })
+}
+
+func TestSignatureVerificationDisabledByDefault(t *testing.T) {
+	withReleasePubKey(t, "")
+	if SignatureVerificationConfigured() {
+		t.Fatal("expected SignatureVerificationConfigured() to be false when pubkey is empty")
+	}
+	// verifyChecksumsSignature should be a no-op when no key is embedded.
+	if err := verifyChecksumsSignature(context.Background(), "0.0.0", []byte("anything")); err != nil {
+		t.Fatalf("expected nil when pubkey is empty, got %v", err)
+	}
+}
+
+func TestSignatureRejectsMalformedPubKey(t *testing.T) {
+	withReleasePubKey(t, "not-base64!!")
+	if _, err := loadReleasePubKey(); err == nil {
+		t.Fatal("expected error from malformed base64")
+	}
+}
+
+func TestSignatureRejectsWrongSizePubKey(t *testing.T) {
+	withReleasePubKey(t, base64.StdEncoding.EncodeToString([]byte("too-short")))
+	if _, err := loadReleasePubKey(); err == nil {
+		t.Fatal("expected error from wrong-size pubkey")
+	}
+}
+
+func TestSignatureVerifiesGoodSignature(t *testing.T) {
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatalf("generate keypair: %v", err)
+	}
+	withReleasePubKey(t, base64.StdEncoding.EncodeToString(pub))
+
+	checksumsBody := []byte("deadbeef  unarr_0.0.0_linux_amd64.tar.gz\n")
+	signature := ed25519.Sign(priv, checksumsBody)
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !strings.HasSuffix(r.URL.Path, "checksums.txt.sig") {
+			http.NotFound(w, r)
+			return
+		}
+		fmt.Fprintln(w, base64.StdEncoding.EncodeToString(signature))
+	}))
+	defer srv.Close()
+
+	prevHost := updateBaseURL
+	updateBaseURL = srv.URL
+	t.Cleanup(func() { updateBaseURL = prevHost })
+
+	if err := verifyChecksumsSignature(context.Background(), "0.0.0", checksumsBody); err != nil {
+		t.Fatalf("verifyChecksumsSignature(good) = %v, want nil", err)
+	}
+}
+
+func TestSignatureRejectsBadSignature(t *testing.T) {
+	pub, _, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatalf("generate keypair: %v", err)
+	}
+	withReleasePubKey(t, base64.StdEncoding.EncodeToString(pub))
+
+	// Sign with a DIFFERENT private key — should be rejected.
+	_, other, _ := ed25519.GenerateKey(rand.Reader)
+	body := []byte("checksum-line\n")
+	badSig := ed25519.Sign(other, body)
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintln(w, base64.StdEncoding.EncodeToString(badSig))
+	}))
+	defer srv.Close()
+
+	prevHost := updateBaseURL
+	updateBaseURL = srv.URL
+	t.Cleanup(func() { updateBaseURL = prevHost })
+
+	err = verifyChecksumsSignature(context.Background(), "0.0.0", body)
+	if err == nil || !strings.Contains(err.Error(), "verification failed") {
+		t.Fatalf("expected verification failure, got %v", err)
+	}
+}
+
+func TestSignatureMissingFile(t *testing.T) {
+	pub, _, _ := ed25519.GenerateKey(rand.Reader)
+	withReleasePubKey(t, base64.StdEncoding.EncodeToString(pub))
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.NotFound(w, r)
+	}))
+	defer srv.Close()
+	prevHost := updateBaseURL
+	updateBaseURL = srv.URL
+	t.Cleanup(func() { updateBaseURL = prevHost })
+
+	err := verifyChecksumsSignature(context.Background(), "0.0.0", []byte("body"))
+	if !errors.Is(err, ErrMissingSignature) {
+		t.Fatalf("expected ErrMissingSignature, got %v", err)
+	}
+}
+
+func TestDecodeSignatureRejectsRaw(t *testing.T) {
+	// 64-byte payload that happens NOT to be valid base64 must error rather
+	// than be silently accepted as a raw signature — the only legitimate
+	// shape is base64-encoded text.
+	raw := make([]byte, ed25519.SignatureSize)
+	for i := range raw {
+		raw[i] = 0xff
+	}
+	if _, err := decodeSignature(raw); err == nil {
+		t.Fatal("expected error from non-base64 64-byte payload")
+	}
+}
diff --git a/internal/upgrade/upgrade.go b/internal/upgrade/upgrade.go
index b70dc7e..50053c5 100644
--- a/internal/upgrade/upgrade.go
+++ b/internal/upgrade/upgrade.go
@@ -13,6 +13,7 @@ package upgrade
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log"
 	"os"
@@ -24,7 +25,6 @@ import (
 )
 
 const (
-	githubRepo  = "torrentclaw/unarr"
 	binaryName  = "unarr"
 	smokeTestTO = 5 * time.Second
 )
@@ -43,6 +43,13 @@ type Upgrader struct {
 	CurrentVersion string
 	// OnProgress is called with status messages during the upgrade process.
 	OnProgress func(msg string)
+	// AllowUnsigned downgrades a missing checksums.txt.sig to a warning and
+	// continues with SHA256-only verification. Required to downgrade to a
+	// release published before signing was introduced, or to recover from
+	// an accidental release where the workflow's signing step was skipped.
+	// Default false — signature missing is a hard failure when a public
+	// key is embedded.
+	AllowUnsigned bool
 }
 
 func (u *Upgrader) log(msg string) {
@@ -83,16 +90,27 @@ func (u *Upgrader) Execute(ctx context.Context, targetVersion string) Result {
 
 	// 4. Download archive
 	u.log(fmt.Sprintf("Downloading v%s...", targetVersion))
-	archivePath, err := download(ctx, targetVersion)
+	archivePath, err := downloadWithRetry(ctx, targetVersion, u.log)
 	if err != nil {
 		return u.fail("download: %v", err)
 	}
 	defer os.Remove(archivePath)
 
-	// 5. Verify checksum
-	u.log("Verifying checksum...")
+	// 5. Verify checksum (and signature, if configured)
+	if SignatureVerificationConfigured() {
+		u.log("Verifying checksum + ed25519 signature...")
+	} else {
+		u.log("Verifying checksum (release signature verification not configured for this build)...")
+	}
 	if err := verifyChecksum(ctx, targetVersion, archivePath); err != nil {
-		return u.fail("checksum: %v", err)
+		if errors.Is(err, ErrMissingSignature) && u.AllowUnsigned {
+			u.log("WARNING: release is unsigned and --allow-unsigned was passed; continuing with SHA256-only verification")
+			if err := verifyChecksumOnly(ctx, targetVersion, archivePath); err != nil {
+				return u.fail("checksum: %v", err)
+			}
+		} else {
+			return u.fail("checksum: %v", err)
+		}
 	}
 
 	// 6. Extract binary
@@ -152,9 +170,13 @@ func (u *Upgrader) fail(format string, args ...any) Result {
 	}
 }
 
-// CheckLatest fetches the latest version from GitHub API.
+// CheckLatest fetches the latest version from GitHub API and updates the cache.
 func CheckLatest(ctx context.Context) (string, error) {
-	return fetchLatestVersion(ctx)
+	v, err := fetchLatestVersion(ctx)
+	if err == nil {
+		writeCachedVersion(v)
+	}
+	return v, err
 }
 
 // installBinary copies the new binary to the target path, preserving original permissions.
@@ -220,7 +242,26 @@ func archiveName(version string) string {
 	return fmt.Sprintf("%s_%s_%s_%s.%s", binaryName, version, runtime.GOOS, runtime.GOARCH, ext)
 }
 
-// releaseURL returns the download URL for a release asset.
-func releaseURL(version, filename string) string {
-	return fmt.Sprintf("https://github.com/%s/releases/download/v%s/%s", githubRepo, version, filename)
+// updateBaseURL is the base URL the self-updater fetches releases from —
+// TorrentClaw's own app, no GitHub dependency (the org is shadow-banned, so
+// GitHub releases/raw/API all 404 to anonymous clients). Defaults to the
+// production apex; SetBaseURL points it at the configured host (cfg.Auth.APIURL)
+// so mirrors / onion / staging work, and tests can point it at an httptest.Server.
+var updateBaseURL = "https://torrentclaw.com"
+
+// SetBaseURL overrides the release endpoint base (trailing slash trimmed).
+// No-op for empty input so a blank config can't break the default.
+func SetBaseURL(base string) {
+	if base != "" {
+		updateBaseURL = strings.TrimRight(base, "/")
+	}
+}
+
+// releaseURL returns the download URL for a release asset:
+//
+//	{base}/releases/download/v{version}/{filename}
+//
+// served by the app's src/app/releases/download/[...seg] route handler.
+func releaseURL(version, filename string) string {
+	return fmt.Sprintf("%s/releases/download/v%s/%s", updateBaseURL, version, filename)
 }
diff --git a/internal/upgrade/upgrade_test.go b/internal/upgrade/upgrade_test.go
index 2753005..18cde17 100644
--- a/internal/upgrade/upgrade_test.go
+++ b/internal/upgrade/upgrade_test.go
@@ -12,6 +12,7 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"strings"
 	"testing"
 )
 
@@ -56,7 +57,7 @@ func TestArchiveName(t *testing.T) {
 
 func TestReleaseURL(t *testing.T) {
 	url := releaseURL("0.3.0", "unarr_0.3.0_linux_amd64.tar.gz")
-	want := "https://github.com/torrentclaw/unarr/releases/download/v0.3.0/unarr_0.3.0_linux_amd64.tar.gz"
+	want := "https://torrentclaw.com/releases/download/v0.3.0/unarr_0.3.0_linux_amd64.tar.gz"
 	if url != want {
 		t.Errorf("releaseURL = %q, want %q", url, want)
 	}
@@ -288,20 +289,839 @@ func TestUpgraderSameVersionWithPrefix(t *testing.T) {
 
 func TestFetchLatestVersionMockServer(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		fmt.Fprint(w, `{"tag_name":"v2.5.1","published_at":"2025-01-01T00:00:00Z"}`)
+		if r.URL.Path != "/version" {
+			http.NotFound(w, r)
+			return
+		}
+		fmt.Fprintln(w, "v2.5.1")
 	}))
 	defer srv.Close()
 
-	// We can't directly test fetchLatestVersion because it uses a hardcoded URL.
-	// But we can test the JSON parsing logic by calling the endpoint ourselves.
-	resp, err := http.Get(srv.URL)
+	prev := updateBaseURL
+	updateBaseURL = srv.URL
+	t.Cleanup(func() { updateBaseURL = prev })
+
+	ver, err := fetchLatestVersion(context.Background())
+	if err != nil {
+		t.Fatalf("fetchLatestVersion() = %v", err)
+	}
+	if ver != "2.5.1" {
+		t.Errorf("fetchLatestVersion() = %q, want %q", ver, "2.5.1")
+	}
+}
+
+// --- New tests below ---
+
+// swapHTTPClient replaces the package-level httpClient and returns a restore function.
+func swapHTTPClient(c *http.Client) func() {
+	orig := httpClient
+	httpClient = c
+	return func() { httpClient = orig }
+}
+
+// swapCacheDir redirects the version cache to a temp directory to avoid
+// polluting the real ~/.local/share/unarr/latest-version.json during tests.
+func swapCacheDir(t *testing.T) func() {
+	t.Helper()
+	tmpDir := t.TempDir()
+	orig := cacheFilePathFn
+	cacheFilePathFn = func() string { return filepath.Join(tmpDir, "latest-version.json") }
+	return func() { cacheFilePathFn = orig }
+}
+
+// rewriteTransport redirects all requests to the given base URL,
+// preserving path and query.
+type rewriteTransport struct {
+	url string
+}
+
+func (rt *rewriteTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	req.URL.Scheme = "http"
+	u := strings.TrimPrefix(rt.url, "http://")
+	req.URL.Host = u
+	return http.DefaultTransport.RoundTrip(req)
+}
+
+// createTarGz is a test helper that creates a tar.gz file with a single file entry.
+func createTarGz(t *testing.T, archivePath, entryName string, content []byte) {
+	t.Helper()
+	f, err := os.Create(archivePath)
 	if err != nil {
 		t.Fatal(err)
 	}
-	defer resp.Body.Close()
+	gw := gzip.NewWriter(f)
+	tw := tar.NewWriter(gw)
 
-	if resp.StatusCode != 200 {
-		t.Errorf("status = %d, want 200", resp.StatusCode)
+	tw.WriteHeader(&tar.Header{
+		Name: entryName,
+		Mode: 0o755,
+		Size: int64(len(content)),
+	})
+	tw.Write(content)
+
+	tw.Close()
+	gw.Close()
+	f.Close()
+}
+
+func TestArchiveNameTableDriven(t *testing.T) {
+	// We can only run archiveName for the current GOOS/GOARCH,
+	// so we test several version strings and verify the pattern.
+	tests := []struct {
+		version string
+	}{
+		{"0.1.0"},
+		{"1.0.0-rc1"},
+		{"2.5.10"},
+		{"0.0.0"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.version, func(t *testing.T) {
+			got := archiveName(tt.version)
+			prefix := fmt.Sprintf("unarr_%s_%s_%s.", tt.version, runtime.GOOS, runtime.GOARCH)
+			if !strings.HasPrefix(got, prefix) {
+				t.Errorf("archiveName(%q) = %q, want prefix %q", tt.version, got, prefix)
+			}
+			if runtime.GOOS == "windows" {
+				if !strings.HasSuffix(got, ".zip") {
+					t.Errorf("archiveName on windows should end with .zip, got %q", got)
+				}
+			} else {
+				if !strings.HasSuffix(got, ".tar.gz") {
+					t.Errorf("archiveName on non-windows should end with .tar.gz, got %q", got)
+				}
+			}
+		})
+	}
+}
+
+func TestReleaseURLEdgeCases(t *testing.T) {
+	tests := []struct {
+		name     string
+		version  string
+		filename string
+		wantURL  string
+	}{
+		{
+			name:     "pre-release version",
+			version:  "2.0.0-beta.1",
+			filename: "unarr_2.0.0-beta.1_darwin_arm64.tar.gz",
+			wantURL:  "https://torrentclaw.com/releases/download/v2.0.0-beta.1/unarr_2.0.0-beta.1_darwin_arm64.tar.gz",
+		},
+		{
+			name:     "checksums file",
+			version:  "3.0.0",
+			filename: "checksums.txt",
+			wantURL:  "https://torrentclaw.com/releases/download/v3.0.0/checksums.txt",
+		},
+		{
+			name:     "windows zip",
+			version:  "1.2.3",
+			filename: "unarr_1.2.3_windows_amd64.zip",
+			wantURL:  "https://torrentclaw.com/releases/download/v1.2.3/unarr_1.2.3_windows_amd64.zip",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := releaseURL(tt.version, tt.filename)
+			if got != tt.wantURL {
+				t.Errorf("releaseURL(%q, %q) = %q, want %q", tt.version, tt.filename, got, tt.wantURL)
+			}
+		})
+	}
+}
+
+func TestExtractBinaryDispatcher(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("extractBinary dispatcher test only on unix")
+	}
+
+	dir := t.TempDir()
+
+	// Create a valid tar.gz with the unarr binary
+	archivePath := filepath.Join(dir, "test.tar.gz")
+	binaryContent := []byte("#!/bin/sh\necho dispatcher test\n")
+	createTarGz(t, archivePath, "unarr", binaryContent)
+
+	destDir := filepath.Join(dir, "out")
+	os.MkdirAll(destDir, 0o755)
+
+	binPath, err := extractBinary(archivePath, destDir)
+	if err != nil {
+		t.Fatalf("extractBinary() error = %v", err)
+	}
+	if filepath.Base(binPath) != "unarr" {
+		t.Errorf("extractBinary() returned %q, want base name 'unarr'", binPath)
+	}
+	data, _ := os.ReadFile(binPath)
+	if string(data) != string(binaryContent) {
+		t.Error("extractBinary() content mismatch")
+	}
+}
+
+func TestExtractBinaryInvalidArchive(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("tar.gz test only on unix")
+	}
+
+	dir := t.TempDir()
+	archivePath := filepath.Join(dir, "garbage.tar.gz")
+	os.WriteFile(archivePath, []byte("this is not a tar.gz"), 0o644)
+
+	destDir := filepath.Join(dir, "out")
+	os.MkdirAll(destDir, 0o755)
+
+	_, err := extractBinary(archivePath, destDir)
+	if err == nil {
+		t.Error("extractBinary with garbage data should return error")
+	}
+}
+
+func TestExtractBinaryNonExistentArchive(t *testing.T) {
+	dir := t.TempDir()
+	_, err := extractBinary("/nonexistent-archive-file", filepath.Join(dir, "out"))
+	if err == nil {
+		t.Error("extractBinary with nonexistent file should return error")
+	}
+}
+
+func TestUpgraderFail(t *testing.T) {
+	u := &Upgrader{CurrentVersion: "1.0.0"}
+
+	// Capture log messages
+	var logged []string
+	u.OnProgress = func(msg string) { logged = append(logged, msg) }
+
+	result := u.fail("something went wrong: %d", 42)
+
+	if result.Success {
+		t.Error("fail() should return Success=false")
+	}
+	if result.OldVersion != "1.0.0" {
+		t.Errorf("fail() OldVersion = %q, want 1.0.0", result.OldVersion)
+	}
+	if result.Error == nil {
+		t.Fatal("fail() should set Error")
+	}
+	if !strings.Contains(result.Error.Error(), "something went wrong: 42") {
+		t.Errorf("fail() Error = %q, want to contain 'something went wrong: 42'", result.Error)
+	}
+	if len(logged) == 0 {
+		t.Error("fail() should call OnProgress")
+	}
+	if len(logged) > 0 && !strings.Contains(logged[0], "FAILED") {
+		t.Errorf("fail() logged %q, want to contain 'FAILED'", logged[0])
+	}
+}
+
+func TestUpgraderFailNilOnProgress(t *testing.T) {
+	u := &Upgrader{CurrentVersion: "2.0.0"}
+	// OnProgress is nil — should not panic
+	result := u.fail("error without listener")
+	if result.Success {
+		t.Error("fail() should return Success=false")
+	}
+}
+
+func TestFetchLatestVersionWithHTTPTest(t *testing.T) {
+	tests := []struct {
+		name       string
+		body       string
+		statusCode int
+		wantVer    string
+		wantErr    bool
+	}{
+		{
+			name:       "valid response",
+			body:       "v3.1.4\n",
+			statusCode: 200,
+			wantVer:    "3.1.4",
+		},
+		{
+			name:       "valid response without v prefix",
+			body:       "2.0.0",
+			statusCode: 200,
+			wantVer:    "2.0.0",
+		},
+		{
+			name:       "empty body",
+			body:       "",
+			statusCode: 200,
+			wantErr:    true,
+		},
+		{
+			name:       "server error",
+			body:       `Internal Server Error`,
+			statusCode: 500,
+			wantErr:    true,
+		},
+		{
+			name:       "whitespace only",
+			body:       "   \n",
+			statusCode: 200,
+			wantErr:    true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(tt.statusCode)
+				fmt.Fprint(w, tt.body)
+			}))
+			defer srv.Close()
+
+			// Use a custom transport that rewrites requests to our test server
+			restore := swapHTTPClient(&http.Client{
+				Transport: &rewriteTransport{url: srv.URL},
+			})
+			defer restore()
+
+			// Redirect cache to temp dir so tests don't pollute the real cache
+			restoreCache := swapCacheDir(t)
+			defer restoreCache()
+
+			ver, err := CheckLatest(context.Background())
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("CheckLatest() error = nil, want error")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("CheckLatest() error = %v", err)
+			}
+			if ver != tt.wantVer {
+				t.Errorf("CheckLatest() = %q, want %q", ver, tt.wantVer)
+			}
+		})
+	}
+}
+
+func TestDownloadWithHTTPTest(t *testing.T) {
+	archiveBody := "fake-archive-bytes-for-download-test"
+
+	t.Run("successful download", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Verify user-agent header
+			if ua := r.Header.Get("User-Agent"); ua != "unarr-updater" {
+				t.Errorf("User-Agent = %q, want 'unarr-updater'", ua)
+			}
+			w.WriteHeader(200)
+			fmt.Fprint(w, archiveBody)
+		}))
+		defer srv.Close()
+
+		restore := swapHTTPClient(&http.Client{
+			Transport: &rewriteTransport{url: srv.URL},
+		})
+		defer restore()
+
+		path, err := download(context.Background(), "1.0.0")
+		if err != nil {
+			t.Fatalf("download() error = %v", err)
+		}
+		defer os.Remove(path)
+
+		data, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatalf("read downloaded file: %v", err)
+		}
+		if string(data) != archiveBody {
+			t.Errorf("downloaded content = %q, want %q", data, archiveBody)
+		}
+	})
+
+	t.Run("server returns 404", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(404)
+		}))
+		defer srv.Close()
+
+		restore := swapHTTPClient(&http.Client{
+			Transport: &rewriteTransport{url: srv.URL},
+		})
+		defer restore()
+
+		_, err := download(context.Background(), "99.99.99")
+		if err == nil {
+			t.Error("download() with 404 should return error")
+		}
+		if !strings.Contains(err.Error(), "HTTP 404") {
+			t.Errorf("download() error = %q, want to contain 'HTTP 404'", err)
+		}
+	})
+
+	t.Run("cancelled context", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(200)
+			fmt.Fprint(w, "data")
+		}))
+		defer srv.Close()
+
+		restore := swapHTTPClient(&http.Client{
+			Transport: &rewriteTransport{url: srv.URL},
+		})
+		defer restore()
+
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel() // cancel immediately
+
+		_, err := download(ctx, "1.0.0")
+		if err == nil {
+			t.Error("download() with cancelled context should return error")
+		}
+	})
+}
+
+func TestVerifyChecksumWithHTTPTest(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("tar.gz test only on unix")
+	}
+
+	// Create a fake archive file
+	dir := t.TempDir()
+	archiveContent := []byte("archive-content-for-checksum-test")
+	archivePath := filepath.Join(dir, "test-archive.tar.gz")
+	os.WriteFile(archivePath, archiveContent, 0o644)
+
+	h := sha256.Sum256(archiveContent)
+	correctHash := hex.EncodeToString(h[:])
+
+	// The function builds the archive name using archiveName(), which uses runtime.GOOS/GOARCH.
+	expectedArchiveName := archiveName("1.0.0")
+
+	t.Run("matching checksum", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			fmt.Fprintf(w, "0000000000000000000000000000000000000000000000000000000000000000  other_file.tar.gz\n")
+			fmt.Fprintf(w, "%s  %s\n", correctHash, expectedArchiveName)
+		}))
+		defer srv.Close()
+
+		restore := swapHTTPClient(&http.Client{
+			Transport: &rewriteTransport{url: srv.URL},
+		})
+		defer restore()
+
+		err := verifyChecksum(context.Background(), "1.0.0", archivePath)
+		if err != nil {
+			t.Errorf("verifyChecksum() = %v, want nil", err)
+		}
+	})
+
+	t.Run("mismatched checksum", func(t *testing.T) {
+		wrongHash := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			fmt.Fprintf(w, "%s  %s\n", wrongHash, expectedArchiveName)
+		}))
+		defer srv.Close()
+
+		restore := swapHTTPClient(&http.Client{
+			Transport: &rewriteTransport{url: srv.URL},
+		})
+		defer restore()
+
+		err := verifyChecksum(context.Background(), "1.0.0", archivePath)
+		if err == nil {
+			t.Error("verifyChecksum() with wrong hash should return error")
+		}
+		if !strings.Contains(err.Error(), "SHA256 mismatch") {
+			t.Errorf("verifyChecksum() error = %q, want to contain 'SHA256 mismatch'", err)
+		}
+	})
+
+	t.Run("archive not in checksums", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			fmt.Fprintf(w, "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890  some_other_file.tar.gz\n")
+		}))
+		defer srv.Close()
+
+		restore := swapHTTPClient(&http.Client{
+			Transport: &rewriteTransport{url: srv.URL},
+		})
+		defer restore()
+
+		err := verifyChecksum(context.Background(), "1.0.0", archivePath)
+		if err == nil {
+			t.Error("verifyChecksum() with missing entry should return error")
+		}
+		if !strings.Contains(err.Error(), "no checksum found") {
+			t.Errorf("verifyChecksum() error = %q, want to contain 'no checksum found'", err)
+		}
+	})
+
+	t.Run("checksums server error", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(500)
+		}))
+		defer srv.Close()
+
+		restore := swapHTTPClient(&http.Client{
+			Transport: &rewriteTransport{url: srv.URL},
+		})
+		defer restore()
+
+		err := verifyChecksum(context.Background(), "1.0.0", archivePath)
+		if err == nil {
+			t.Error("verifyChecksum() with server error should return error")
+		}
+		if !strings.Contains(err.Error(), "HTTP 500") {
+			t.Errorf("verifyChecksum() error = %q, want to contain 'HTTP 500'", err)
+		}
+	})
+
+	t.Run("nonexistent archive file", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			fmt.Fprintf(w, "%s  %s\n", correctHash, expectedArchiveName)
+		}))
+		defer srv.Close()
+
+		restore := swapHTTPClient(&http.Client{
+			Transport: &rewriteTransport{url: srv.URL},
+		})
+		defer restore()
+
+		err := verifyChecksum(context.Background(), "1.0.0", "/nonexistent-archive-path")
+		if err == nil {
+			t.Error("verifyChecksum() with nonexistent archive should return error")
+		}
+	})
+}
+
+func TestVerifyChecksumCaseInsensitive(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("tar.gz test only on unix")
+	}
+
+	dir := t.TempDir()
+	archiveContent := []byte("case-insensitive-hash-test")
+	archivePath := filepath.Join(dir, "archive.tar.gz")
+	os.WriteFile(archivePath, archiveContent, 0o644)
+
+	h := sha256.Sum256(archiveContent)
+	// Use uppercase hash in checksums.txt — verifyChecksum uses EqualFold
+	upperHash := strings.ToUpper(hex.EncodeToString(h[:]))
+	expectedArchiveName := archiveName("1.0.0")
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintf(w, "%s  %s\n", upperHash, expectedArchiveName)
+	}))
+	defer srv.Close()
+
+	restore := swapHTTPClient(&http.Client{
+		Transport: &rewriteTransport{url: srv.URL},
+	})
+	defer restore()
+
+	err := verifyChecksum(context.Background(), "1.0.0", archivePath)
+	if err != nil {
+		t.Errorf("verifyChecksum() with uppercase hash = %v, want nil", err)
+	}
+}
+
+func TestExtractTarGzNestedDirectory(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("tar.gz test only on unix")
+	}
+
+	dir := t.TempDir()
+	archivePath := filepath.Join(dir, "nested.tar.gz")
+
+	binaryContent := []byte("#!/bin/sh\necho nested\n")
+
+	f, err := os.Create(archivePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	gw := gzip.NewWriter(f)
+	tw := tar.NewWriter(gw)
+
+	// Write a directory entry first
+	tw.WriteHeader(&tar.Header{
+		Name:     "unarr_1.0.0_linux_amd64/",
+		Typeflag: tar.TypeDir,
+		Mode:     0o755,
+	})
+
+	// Write a README in the subdirectory
+	readmeContent := []byte("This is a README")
+	tw.WriteHeader(&tar.Header{
+		Name: "unarr_1.0.0_linux_amd64/README.md",
+		Mode: 0o644,
+		Size: int64(len(readmeContent)),
+	})
+	tw.Write(readmeContent)
+
+	// Write the binary nested inside the directory
+	tw.WriteHeader(&tar.Header{
+		Name: "unarr_1.0.0_linux_amd64/unarr",
+		Mode: 0o755,
+		Size: int64(len(binaryContent)),
+	})
+	tw.Write(binaryContent)
+
+	// Write another unrelated file after the binary
+	licenseContent := []byte("MIT License")
+	tw.WriteHeader(&tar.Header{
+		Name: "unarr_1.0.0_linux_amd64/LICENSE",
+		Mode: 0o644,
+		Size: int64(len(licenseContent)),
+	})
+	tw.Write(licenseContent)
+
+	tw.Close()
+	gw.Close()
+	f.Close()
+
+	destDir := filepath.Join(dir, "out")
+	os.MkdirAll(destDir, 0o755)
+
+	binPath, err := extractTarGz(archivePath, destDir)
+	if err != nil {
+		t.Fatalf("extractTarGz() with nested dir = %v", err)
+	}
+
+	if filepath.Base(binPath) != "unarr" {
+		t.Errorf("extracted name = %q, want 'unarr'", filepath.Base(binPath))
+	}
+
+	data, _ := os.ReadFile(binPath)
+	if string(data) != string(binaryContent) {
+		t.Error("extracted content does not match")
+	}
+
+	// Verify that only the binary was extracted (README and LICENSE should NOT be in destDir)
+	entries, _ := os.ReadDir(destDir)
+	if len(entries) != 1 {
+		names := make([]string, len(entries))
+		for i, e := range entries {
+			names[i] = e.Name()
+		}
+		t.Errorf("destDir should contain only 'unarr', got %v", names)
+	}
+}
+
+func TestExtractTarGzMultipleFiles(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("tar.gz test only on unix")
+	}
+
+	dir := t.TempDir()
+	archivePath := filepath.Join(dir, "multi.tar.gz")
+
+	binaryContent := []byte("#!/bin/sh\necho multi\n")
+
+	f, err := os.Create(archivePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	gw := gzip.NewWriter(f)
+	tw := tar.NewWriter(gw)
+
+	// Several non-binary files before the actual binary
+	for _, name := range []string{"README.md", "LICENSE", "config.yaml", "completions.bash"} {
+		content := []byte("content of " + name)
+		tw.WriteHeader(&tar.Header{
+			Name: name,
+			Mode: 0o644,
+			Size: int64(len(content)),
+		})
+		tw.Write(content)
+	}
+
+	// The actual binary
+	tw.WriteHeader(&tar.Header{
+		Name: "unarr",
+		Mode: 0o755,
+		Size: int64(len(binaryContent)),
+	})
+	tw.Write(binaryContent)
+
+	tw.Close()
+	gw.Close()
+	f.Close()
+
+	destDir := filepath.Join(dir, "out")
+	os.MkdirAll(destDir, 0o755)
+
+	binPath, err := extractTarGz(archivePath, destDir)
+	if err != nil {
+		t.Fatalf("extractTarGz() = %v", err)
+	}
+
+	data, _ := os.ReadFile(binPath)
+	if string(data) != string(binaryContent) {
+		t.Error("binary content mismatch among multiple files")
+	}
+}
+
+func TestExtractTarGzSymlinkSkipped(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("tar.gz test only on unix")
+	}
+
+	dir := t.TempDir()
+	archivePath := filepath.Join(dir, "symlink.tar.gz")
+
+	f, err := os.Create(archivePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	gw := gzip.NewWriter(f)
+	tw := tar.NewWriter(gw)
+
+	// Write a symlink entry named "unarr" — should be skipped because Typeflag != TypeReg
+	tw.WriteHeader(&tar.Header{
+		Name:     "unarr",
+		Typeflag: tar.TypeSymlink,
+		Linkname: "/etc/passwd",
+		Mode:     0o755,
+	})
+
+	tw.Close()
+	gw.Close()
+	f.Close()
+
+	destDir := filepath.Join(dir, "out")
+	os.MkdirAll(destDir, 0o755)
+
+	_, err = extractTarGz(archivePath, destDir)
+	if err == nil {
+		t.Error("extractTarGz() should return error when binary is a symlink (not TypeReg)")
+	}
+	if !strings.Contains(err.Error(), "not found in archive") {
+		t.Errorf("error = %q, want to contain 'not found in archive'", err)
+	}
+}
+
+func TestInstallBinaryNonExistentSource(t *testing.T) {
+	dir := t.TempDir()
+	dst := filepath.Join(dir, "output")
+
+	err := installBinary("/nonexistent-source-binary", dst)
+	if err == nil {
+		t.Error("installBinary with nonexistent source should return error")
+	}
+	if !strings.Contains(err.Error(), "read new binary") {
+		t.Errorf("error = %q, want to contain 'read new binary'", err)
+	}
+
+	// Verify destination was not created
+	if _, statErr := os.Stat(dst); statErr == nil {
+		t.Error("destination file should not exist after failed install")
+	}
+}
+
+func TestInstallBinaryUnwritableDestination(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "source")
+	os.WriteFile(src, []byte("binary"), 0o755)
+
+	// Try to write to a path inside a non-existent directory
+	dst := filepath.Join(dir, "nonexistent-subdir", "binary")
+
+	err := installBinary(src, dst)
+	if err == nil {
+		t.Error("installBinary to non-writable destination should return error")
+	}
+	if !strings.Contains(err.Error(), "write binary") {
+		t.Errorf("error = %q, want to contain 'write binary'", err)
+	}
+}
+
+func TestUpgraderLog(t *testing.T) {
+	var messages []string
+	u := &Upgrader{
+		CurrentVersion: "1.0.0",
+		OnProgress:     func(msg string) { messages = append(messages, msg) },
+	}
+
+	u.log("hello world")
+	if len(messages) != 1 || messages[0] != "hello world" {
+		t.Errorf("log() messages = %v, want [hello world]", messages)
+	}
+}
+
+func TestUpgraderLogNilOnProgress(t *testing.T) {
+	u := &Upgrader{CurrentVersion: "1.0.0"}
+	// Should not panic
+	u.log("test message with nil OnProgress")
+}
+
+func TestResultFields(t *testing.T) {
+	r := Result{
+		Success:    true,
+		OldVersion: "1.0.0",
+		NewVersion: "2.0.0",
+		BackupPath: "/tmp/backup",
+	}
+	if !r.Success || r.OldVersion != "1.0.0" || r.NewVersion != "2.0.0" || r.BackupPath != "/tmp/backup" {
+		t.Errorf("Result fields not set correctly: %+v", r)
+	}
+
+	r2 := Result{Success: false, Error: fmt.Errorf("test error")}
+	if r2.Success || r2.Error == nil {
+		t.Errorf("Result error case not correct: %+v", r2)
+	}
+}
+
+func TestDownloadSetsUserAgent(t *testing.T) {
+	var gotUA string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotUA = r.Header.Get("User-Agent")
+		w.WriteHeader(200)
+		fmt.Fprint(w, "data")
+	}))
+	defer srv.Close()
+
+	restore := swapHTTPClient(&http.Client{
+		Transport: &rewriteTransport{url: srv.URL},
+	})
+	defer restore()
+
+	path, err := download(context.Background(), "1.0.0")
+	if err != nil {
+		t.Fatalf("download() = %v", err)
+	}
+	defer os.Remove(path)
+
+	if gotUA != "unarr-updater" {
+		t.Errorf("User-Agent = %q, want 'unarr-updater'", gotUA)
+	}
+}
+
+func TestSafeZipPath(t *testing.T) {
+	dest := t.TempDir()
+	absDest, err := filepath.Abs(dest)
+	if err != nil {
+		t.Fatalf("abs dest: %v", err)
+	}
+
+	// Names that must extract successfully.
+	good := []string{
+		"unarr.exe",
+		"bin/unarr.exe",
+		"./unarr.exe",
+		"folder/sub/unarr.exe",
+	}
+	for _, name := range good {
+		if _, ok := safeZipPath(name, "unarr.exe", absDest); !ok {
+			t.Errorf("safeZipPath(%q) = ok:false, want ok:true", name)
+		}
+	}
+
+	// Names that must be rejected for path-traversal reasons.
+	bad := []string{
+		"../unarr.exe",
+		"..",
+		"foo/../../unarr.exe",
+		"/etc/passwd",
+		"/abs/unarr.exe",
+		`..\..\windows\system32\unarr.exe`, // backslash entries that escape
+		"../../bin/unarr.exe",
+	}
+	for _, name := range bad {
+		if _, ok := safeZipPath(name, "unarr.exe", absDest); ok {
+			t.Errorf("safeZipPath(%q) = ok:true, want ok:false", name)
+		}
 	}
 }
diff --git a/internal/usenet/download/progress_expand_test.go b/internal/usenet/download/progress_expand_test.go
new file mode 100644
index 0000000..0ce1b4f
--- /dev/null
+++ b/internal/usenet/download/progress_expand_test.go
@@ -0,0 +1,632 @@
+package download
+
+import (
+	"encoding/binary"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/torrentclaw/unarr/internal/usenet/nzb"
+)
+
+// --- Fingerprint ---
+
+func TestFingerprint_EmptyNZB(t *testing.T) {
+	n := &nzb.NZB{}
+	fp := Fingerprint(n)
+	// Empty NZB should still produce a deterministic hash (of zero message IDs).
+	fp2 := Fingerprint(n)
+	if fp != fp2 {
+		t.Fatal("fingerprint of empty NZB should be deterministic")
+	}
+}
+
+func TestFingerprint_OrderIndependent(t *testing.T) {
+	// Fingerprint sorts IDs, so different file order should produce the same hash.
+	n1 := &nzb.NZB{
+		Files: []nzb.File{
+			{Segments: []nzb.Segment{{MessageID: "a@x"}, {MessageID: "b@x"}}},
+			{Segments: []nzb.Segment{{MessageID: "c@x"}}},
+		},
+	}
+	n2 := &nzb.NZB{
+		Files: []nzb.File{
+			{Segments: []nzb.Segment{{MessageID: "c@x"}}},
+			{Segments: []nzb.Segment{{MessageID: "b@x"}, {MessageID: "a@x"}}},
+		},
+	}
+	if Fingerprint(n1) != Fingerprint(n2) {
+		t.Fatal("fingerprint should be order-independent (sorted by message ID)")
+	}
+}
+
+func TestFingerprint_SingleSegment(t *testing.T) {
+	n := &nzb.NZB{
+		Files: []nzb.File{
+			{Segments: []nzb.Segment{{MessageID: "only@one"}}},
+		},
+	}
+	fp := Fingerprint(n)
+	if fp == [32]byte{} {
+		t.Fatal("fingerprint should not be zero for a non-empty NZB")
+	}
+}
+
+// --- ProgressTracker MarkDone idempotency ---
+
+func TestProgressTracker_MarkDoneIdempotent(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 5)
+	tracker := NewProgressTracker("idem", n, dir)
+
+	tracker.MarkDone(0, 2)
+	if tracker.CompletedSegments(0) != 1 {
+		t.Fatalf("expected 1, got %d", tracker.CompletedSegments(0))
+	}
+
+	// Mark the same segment again — count should not increase.
+	tracker.MarkDone(0, 2)
+	if tracker.CompletedSegments(0) != 1 {
+		t.Fatalf("idempotent mark: expected 1, got %d", tracker.CompletedSegments(0))
+	}
+}
+
+// --- ProgressTracker TotalCompleted ---
+
+func TestProgressTracker_TotalCompleted(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(3, 4) // 3 files, 4 segs each
+	tracker := NewProgressTracker("total", n, dir)
+
+	tracker.MarkDone(0, 0)
+	tracker.MarkDone(0, 1)
+	tracker.MarkDone(1, 3)
+	tracker.MarkDone(2, 0)
+	tracker.MarkDone(2, 1)
+	tracker.MarkDone(2, 2)
+
+	if got := tracker.TotalCompleted(); got != 6 {
+		t.Errorf("TotalCompleted: got %d, want 6", got)
+	}
+}
+
+func TestProgressTracker_TotalCompleted_Empty(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(2, 3)
+	tracker := NewProgressTracker("empty-total", n, dir)
+
+	if got := tracker.TotalCompleted(); got != 0 {
+		t.Errorf("TotalCompleted on fresh tracker: got %d, want 0", got)
+	}
+}
+
+// --- CompletedBytes edge cases ---
+
+func TestProgressTracker_CompletedBytes_OutOfBounds(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("cb-oob", n, dir)
+
+	if got := tracker.CompletedBytes(-1, n.Files[0].Segments); got != 0 {
+		t.Errorf("CompletedBytes with file -1: got %d, want 0", got)
+	}
+	if got := tracker.CompletedBytes(5, n.Files[0].Segments); got != 0 {
+		t.Errorf("CompletedBytes with file 5: got %d, want 0", got)
+	}
+}
+
+func TestProgressTracker_CompletedBytes_AllDone(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("cb-all", n, dir)
+
+	for i := 0; i < 3; i++ {
+		tracker.MarkDone(0, i)
+	}
+
+	got := tracker.CompletedBytes(0, n.Files[0].Segments)
+	expected := int64(3 * 750 * 1024)
+	if got != expected {
+		t.Errorf("CompletedBytes all done: got %d, want %d", got, expected)
+	}
+}
+
+// --- CompletedSegments out of bounds ---
+
+func TestProgressTracker_CompletedSegments_OutOfBounds(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("cs-oob", n, dir)
+
+	if got := tracker.CompletedSegments(-1); got != 0 {
+		t.Errorf("CompletedSegments(-1) = %d, want 0", got)
+	}
+	if got := tracker.CompletedSegments(99); got != 0 {
+		t.Errorf("CompletedSegments(99) = %d, want 0", got)
+	}
+}
+
+// --- Load with corrupted / truncated data ---
+
+func TestProgressTracker_Load_TruncatedHeader(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("trunc", n, dir)
+
+	// Write too-short data
+	os.WriteFile(tracker.progressPath(), []byte("UNR"), 0o644)
+
+	loaded, err := tracker.Load()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if loaded {
+		t.Error("truncated header should not load")
+	}
+}
+
+func TestProgressTracker_Load_BadMagic(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("badmagic", n, dir)
+
+	// Write data with wrong magic bytes
+	data := make([]byte, headerSize+10)
+	copy(data[0:4], []byte("BAAD"))
+	os.WriteFile(tracker.progressPath(), data, 0o644)
+
+	loaded, err := tracker.Load()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if loaded {
+		t.Error("bad magic should not load")
+	}
+}
+
+func TestProgressTracker_Load_BadVersion(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("badver", n, dir)
+
+	data := make([]byte, headerSize+10)
+	copy(data[0:4], progressMagic[:])
+	data[4] = 99 // unsupported version
+	os.WriteFile(tracker.progressPath(), data, 0o644)
+
+	loaded, err := tracker.Load()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if loaded {
+		t.Error("bad version should not load")
+	}
+}
+
+func TestProgressTracker_Load_WrongFileCount(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(2, 3)
+	tracker := NewProgressTracker("wrongfc", n, dir)
+
+	data := make([]byte, headerSize+20)
+	copy(data[0:4], progressMagic[:])
+	data[4] = progressVersion
+	binary.LittleEndian.PutUint16(data[6:8], 99) // wrong file count
+	copy(data[8:40], tracker.fingerprint[:])
+	os.WriteFile(tracker.progressPath(), data, 0o644)
+
+	loaded, err := tracker.Load()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if loaded {
+		t.Error("wrong file count should not load")
+	}
+}
+
+func TestProgressTracker_Load_TruncatedBitset(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 16)
+	tracker := NewProgressTracker("truncbit", n, dir)
+
+	// Build a valid header but truncate the bitset data
+	data := make([]byte, headerSize+4) // header + segCount but no bitset
+	copy(data[0:4], progressMagic[:])
+	data[4] = progressVersion
+	binary.LittleEndian.PutUint16(data[6:8], 1) // 1 file
+	copy(data[8:40], tracker.fingerprint[:])
+	binary.LittleEndian.PutUint32(data[headerSize:headerSize+4], 16) // 16 segs
+	// No bitset data follows — truncated
+	os.WriteFile(tracker.progressPath(), data, 0o644)
+
+	loaded, err := tracker.Load()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if loaded {
+		t.Error("truncated bitset should not load")
+	}
+}
+
+func TestProgressTracker_Load_SegCountMismatch(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 5)
+	tracker := NewProgressTracker("segmis", n, dir)
+
+	// Build valid header with correct file count and fingerprint, but wrong segCount
+	bitsetLen := (999 + 7) / 8
+	data := make([]byte, headerSize+4+bitsetLen)
+	copy(data[0:4], progressMagic[:])
+	data[4] = progressVersion
+	binary.LittleEndian.PutUint16(data[6:8], 1)
+	copy(data[8:40], tracker.fingerprint[:])
+	binary.LittleEndian.PutUint32(data[headerSize:headerSize+4], 999) // wrong seg count
+	os.WriteFile(tracker.progressPath(), data, 0o644)
+
+	loaded, err := tracker.Load()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if loaded {
+		t.Error("segment count mismatch should not load")
+	}
+}
+
+func TestProgressTracker_Load_NonexistentFile(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("nofile", n, dir)
+
+	loaded, err := tracker.Load()
+	if err != nil {
+		t.Fatalf("unexpected error for missing file: %v", err)
+	}
+	if loaded {
+		t.Error("nonexistent file should return false")
+	}
+}
+
+// --- Flush and Load round-trip with multiple files ---
+
+func TestProgressTracker_MultiFileRoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(5, 10) // 5 files, 10 segments each
+	tracker := NewProgressTracker("multi-rt", n, dir)
+
+	// Mark various segments across files
+	tracker.MarkDone(0, 0)
+	tracker.MarkDone(0, 9)
+	tracker.MarkDone(1, 5)
+	tracker.MarkDone(2, 0)
+	tracker.MarkDone(2, 1)
+	tracker.MarkDone(2, 2)
+	tracker.MarkDone(2, 3)
+	tracker.MarkDone(2, 4)
+	tracker.MarkDone(2, 5)
+	tracker.MarkDone(2, 6)
+	tracker.MarkDone(2, 7)
+	tracker.MarkDone(2, 8)
+	tracker.MarkDone(2, 9) // file 2 fully done
+	tracker.MarkDone(4, 7)
+
+	if err := tracker.Flush(); err != nil {
+		t.Fatalf("flush: %v", err)
+	}
+
+	// Reload
+	tracker2 := NewProgressTracker("multi-rt", n, dir)
+	loaded, err := tracker2.Load()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if !loaded {
+		t.Fatal("should load")
+	}
+
+	if tracker2.CompletedSegments(0) != 2 {
+		t.Errorf("file 0: got %d, want 2", tracker2.CompletedSegments(0))
+	}
+	if tracker2.CompletedSegments(1) != 1 {
+		t.Errorf("file 1: got %d, want 1", tracker2.CompletedSegments(1))
+	}
+	if !tracker2.IsFileDone(2) {
+		t.Error("file 2 should be done")
+	}
+	if tracker2.CompletedSegments(3) != 0 {
+		t.Errorf("file 3: got %d, want 0", tracker2.CompletedSegments(3))
+	}
+	if tracker2.CompletedSegments(4) != 1 {
+		t.Errorf("file 4: got %d, want 1", tracker2.CompletedSegments(4))
+	}
+	if tracker2.TotalCompleted() != 14 {
+		t.Errorf("TotalCompleted: got %d, want 14", tracker2.TotalCompleted())
+	}
+}
+
+// --- Concurrent mark + IsDone reads ---
+
+func TestProgressTracker_ConcurrentMarkAndRead(t *testing.T) {
+	dir := t.TempDir()
+	segCount := 500
+	n := makeTestNZB(2, segCount)
+	tracker := NewProgressTracker("conc-rw", n, dir)
+
+	// Use separate WaitGroups for writers and readers
+	var writerWg sync.WaitGroup
+	stop := make(chan struct{})
+
+	// Writers
+	for file := 0; file < 2; file++ {
+		for seg := 0; seg < segCount; seg++ {
+			writerWg.Add(1)
+			go func(f, s int) {
+				defer writerWg.Done()
+				tracker.MarkDone(f, s)
+			}(file, seg)
+		}
+	}
+
+	// Readers — continuously read while writes happen
+	var readerWg sync.WaitGroup
+	for i := 0; i < 4; i++ {
+		readerWg.Add(1)
+		go func() {
+			defer readerWg.Done()
+			for {
+				select {
+				case <-stop:
+					return
+				default:
+					// These should never panic
+					tracker.IsDone(0, 0)
+					tracker.IsDone(1, segCount-1)
+					tracker.IsFileDone(0)
+					tracker.CompletedSegments(1)
+					tracker.TotalCompleted()
+				}
+			}
+		}()
+	}
+
+	// Wait for all writers to finish, then stop readers
+	writerWg.Wait()
+	close(stop)
+	readerWg.Wait()
+
+	// After all goroutines complete, everything should be done
+	if !tracker.IsFileDone(0) {
+		t.Errorf("file 0 should be done, got %d/%d", tracker.CompletedSegments(0), segCount)
+	}
+	if !tracker.IsFileDone(1) {
+		t.Errorf("file 1 should be done, got %d/%d", tracker.CompletedSegments(1), segCount)
+	}
+}
+
+// --- Concurrent flush safety ---
+
+func TestProgressTracker_ConcurrentFlush(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 100)
+	tracker := NewProgressTracker("conc-flush", n, dir)
+
+	// Mark some segments
+	for i := 0; i < 50; i++ {
+		tracker.MarkDone(0, i)
+	}
+
+	// Multiple concurrent flushes should not panic or corrupt
+	var wg sync.WaitGroup
+	for i := 0; i < 10; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			tracker.Flush()
+		}()
+	}
+	wg.Wait()
+
+	// Verify state is loadable
+	tracker2 := NewProgressTracker("conc-flush", n, dir)
+	loaded, err := tracker2.Load()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if !loaded {
+		t.Fatal("should load after concurrent flushes")
+	}
+	if tracker2.CompletedSegments(0) != 50 {
+		t.Errorf("after concurrent flush: got %d, want 50", tracker2.CompletedSegments(0))
+	}
+}
+
+// --- Remove with .tmp file ---
+
+func TestProgressTracker_Remove_WithTmpFile(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("rm-tmp", n, dir)
+
+	// Create all three files that Remove should clean up
+	os.WriteFile(tracker.progressPath(), []byte("data"), 0o644)
+	os.WriteFile(tracker.nzbPath(), []byte("<nzb/>"), 0o644)
+	os.WriteFile(tracker.progressPath()+".tmp", []byte("tmp"), 0o644)
+
+	tracker.Remove()
+
+	for _, p := range []string{tracker.progressPath(), tracker.nzbPath(), tracker.progressPath() + ".tmp"} {
+		if _, err := os.Stat(p); !os.IsNotExist(err) {
+			t.Errorf("file should be removed: %s", p)
+		}
+	}
+}
+
+// --- CleanStaleFiles edge cases ---
+
+func TestCleanStaleFiles_EmptyDir(t *testing.T) {
+	dir := t.TempDir()
+	if got := CleanStaleFiles(dir, time.Hour); got != 0 {
+		t.Errorf("empty dir: got %d removed, want 0", got)
+	}
+}
+
+func TestCleanStaleFiles_NonexistentDir(t *testing.T) {
+	if got := CleanStaleFiles("/nonexistent/path/that/does/not/exist", time.Hour); got != 0 {
+		t.Errorf("nonexistent dir: got %d removed, want 0", got)
+	}
+}
+
+func TestCleanStaleFiles_AllFresh(t *testing.T) {
+	dir := t.TempDir()
+	os.WriteFile(filepath.Join(dir, "a.progress"), []byte("a"), 0o644)
+	os.WriteFile(filepath.Join(dir, "b.progress"), []byte("b"), 0o644)
+
+	if got := CleanStaleFiles(dir, 24*time.Hour); got != 0 {
+		t.Errorf("all fresh: got %d removed, want 0", got)
+	}
+}
+
+func TestCleanStaleFiles_SkipsSubdirs(t *testing.T) {
+	dir := t.TempDir()
+	subDir := filepath.Join(dir, "subdir")
+	os.MkdirAll(subDir, 0o755)
+
+	// Backdate the subdir (it should not be removed)
+	os.Chtimes(subDir, fixedPast, fixedPast)
+
+	if got := CleanStaleFiles(dir, 24*time.Hour); got != 0 {
+		t.Errorf("should skip subdirs: got %d removed, want 0", got)
+	}
+	if _, err := os.Stat(subDir); err != nil {
+		t.Error("subdir should still exist")
+	}
+}
+
+func TestCleanStaleFiles_MixedAges(t *testing.T) {
+	dir := t.TempDir()
+
+	stale1 := filepath.Join(dir, "old1.progress")
+	stale2 := filepath.Join(dir, "old2.nzb")
+	fresh := filepath.Join(dir, "new.progress")
+
+	os.WriteFile(stale1, []byte("x"), 0o644)
+	os.WriteFile(stale2, []byte("x"), 0o644)
+	os.WriteFile(fresh, []byte("x"), 0o644)
+
+	os.Chtimes(stale1, fixedPast, fixedPast)
+	os.Chtimes(stale2, fixedPast, fixedPast)
+
+	if got := CleanStaleFiles(dir, 7*24*time.Hour); got != 2 {
+		t.Errorf("mixed ages: got %d removed, want 2", got)
+	}
+	if _, err := os.Stat(fresh); err != nil {
+		t.Error("fresh file should still exist")
+	}
+}
+
+// --- progressPath / nzbPath ---
+
+func TestProgressTracker_Paths(t *testing.T) {
+	dir := "/some/dir"
+	n := makeTestNZB(1, 1)
+	tracker := NewProgressTracker("my-task", n, dir)
+
+	if got := tracker.progressPath(); got != filepath.Join(dir, "my-task.progress") {
+		t.Errorf("progressPath: got %q", got)
+	}
+	if got := tracker.nzbPath(); got != filepath.Join(dir, "my-task.nzb") {
+		t.Errorf("nzbPath: got %q", got)
+	}
+}
+
+// --- formatBytes ---
+
+func TestFormatBytes(t *testing.T) {
+	tests := []struct {
+		input int64
+		want  string
+	}{
+		{0, "0 B"},
+		{500, "500 B"},
+		{1023, "1023 B"},
+		{1024, "1.0 KB"},
+		{1536, "1.5 KB"},
+		{1048576, "1.0 MB"},
+		{1073741824, "1.0 GB"},
+		{1099511627776, "1.0 TB"},
+	}
+	for _, tt := range tests {
+		got := formatBytes(tt.input)
+		if got != tt.want {
+			t.Errorf("formatBytes(%d) = %q, want %q", tt.input, got, tt.want)
+		}
+	}
+}
+
+// --- Single file with 1 segment (boundary) ---
+
+func TestProgressTracker_SingleSegment(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 1)
+	tracker := NewProgressTracker("single-seg", n, dir)
+
+	if tracker.IsFileDone(0) {
+		t.Error("should not be done initially")
+	}
+
+	tracker.MarkDone(0, 0)
+
+	if !tracker.IsFileDone(0) {
+		t.Error("should be done after marking the only segment")
+	}
+
+	if err := tracker.Flush(); err != nil {
+		t.Fatalf("flush: %v", err)
+	}
+
+	tracker2 := NewProgressTracker("single-seg", n, dir)
+	loaded, _ := tracker2.Load()
+	if !loaded {
+		t.Fatal("should load")
+	}
+	if !tracker2.IsFileDone(0) {
+		t.Error("should be done after reload")
+	}
+}
+
+// --- Flush creates directory if missing ---
+
+func TestProgressTracker_FlushCreatesDir(t *testing.T) {
+	base := t.TempDir()
+	dir := filepath.Join(base, "nested", "resume")
+	n := makeTestNZB(1, 2)
+	tracker := NewProgressTracker("mkdir-test", n, dir)
+
+	tracker.MarkDone(0, 0)
+	if err := tracker.Flush(); err != nil {
+		t.Fatalf("flush should create dir: %v", err)
+	}
+
+	if _, err := os.Stat(tracker.progressPath()); err != nil {
+		t.Fatalf("progress file should exist: %v", err)
+	}
+}
+
+// --- Double flush after no new marks ---
+
+func TestProgressTracker_DoubleFlush(t *testing.T) {
+	dir := t.TempDir()
+	n := makeTestNZB(1, 3)
+	tracker := NewProgressTracker("dbl-flush", n, dir)
+
+	tracker.MarkDone(0, 0)
+	if err := tracker.Flush(); err != nil {
+		t.Fatalf("first flush: %v", err)
+	}
+
+	// Second flush without new marks should be a no-op (dirty=false)
+	if err := tracker.Flush(); err != nil {
+		t.Fatalf("second flush: %v", err)
+	}
+}
diff --git a/internal/usenet/nntp/client_test.go b/internal/usenet/nntp/client_test.go
new file mode 100644
index 0000000..41e61e3
--- /dev/null
+++ b/internal/usenet/nntp/client_test.go
@@ -0,0 +1,131 @@
+package nntp
+
+import (
+	"bufio"
+	"bytes"
+	"testing"
+)
+
+func TestNewClient(t *testing.T) {
+	c := NewClient(Config{Host: "news.example.com", Port: 563, SSL: true})
+	if c.cfg.MaxConnections != 10 {
+		t.Errorf("default MaxConnections = %d, want 10", c.cfg.MaxConnections)
+	}
+	if c.cfg.Host != "news.example.com" {
+		t.Errorf("Host = %q", c.cfg.Host)
+	}
+}
+
+func TestNewClientCustomConnections(t *testing.T) {
+	c := NewClient(Config{Host: "news.example.com", Port: 563, MaxConnections: 20})
+	if c.cfg.MaxConnections != 20 {
+		t.Errorf("MaxConnections = %d, want 20", c.cfg.MaxConnections)
+	}
+}
+
+func TestNewClientZeroConnections(t *testing.T) {
+	c := NewClient(Config{Host: "news.example.com", Port: 563, MaxConnections: 0})
+	if c.cfg.MaxConnections != 10 {
+		t.Errorf("MaxConnections should default to 10, got %d", c.cfg.MaxConnections)
+	}
+}
+
+func TestNewClientNegativeConnections(t *testing.T) {
+	c := NewClient(Config{MaxConnections: -5})
+	if c.cfg.MaxConnections != 10 {
+		t.Errorf("MaxConnections should default to 10 for negative, got %d", c.cfg.MaxConnections)
+	}
+}
+
+func TestActiveConnections(t *testing.T) {
+	c := NewClient(Config{Host: "localhost", Port: 119})
+	if c.ActiveConnections() != 0 {
+		t.Errorf("ActiveConnections = %d, want 0", c.ActiveConnections())
+	}
+}
+
+func TestStatus(t *testing.T) {
+	c := NewClient(Config{Host: "news.example.com", Port: 563})
+	s := c.Status()
+	if s != "0 connections (0 pooled) to news.example.com:563" {
+		t.Errorf("Status = %q", s)
+	}
+}
+
+func TestCloseIdempotent(t *testing.T) {
+	c := NewClient(Config{Host: "localhost", Port: 119})
+	// Close should be idempotent
+	if err := c.Close(); err != nil {
+		t.Errorf("first Close: %v", err)
+	}
+	if err := c.Close(); err != nil {
+		t.Errorf("second Close: %v", err)
+	}
+}
+
+func TestArticleNotFoundError(t *testing.T) {
+	err := &ArticleNotFoundError{MessageID: "abc123@news.example.com"}
+	msg := err.Error()
+	if msg != "nntp: article not found: abc123@news.example.com" {
+		t.Errorf("Error() = %q", msg)
+	}
+}
+
+func TestReadDotBody(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			"simple body",
+			"Hello World\r\n.\r\n",
+			"Hello World\n",
+		},
+		{
+			"multiline",
+			"Line 1\r\nLine 2\r\nLine 3\r\n.\r\n",
+			"Line 1\nLine 2\nLine 3\n",
+		},
+		{
+			"dot-stuffed line",
+			"..This starts with a dot\r\n.\r\n",
+			".This starts with a dot\n",
+		},
+		{
+			"empty body",
+			".\r\n",
+			"",
+		},
+		{
+			"binary-like data",
+			"=ybegin line=128 size=1024 name=test.bin\r\nsome encoded data\r\n=yend\r\n.\r\n",
+			"=ybegin line=128 size=1024 name=test.bin\nsome encoded data\n=yend\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			r := bufio.NewReader(bytes.NewBufferString(tt.input))
+			got, err := readDotBody(r)
+			if err != nil {
+				t.Fatalf("readDotBody: %v", err)
+			}
+			if string(got) != tt.want {
+				t.Errorf("readDotBody = %q, want %q", string(got), tt.want)
+			}
+		})
+	}
+}
+
+func TestReadDotBodyEOF(t *testing.T) {
+	// No dot terminator — should read until EOF
+	r := bufio.NewReader(bytes.NewBufferString("partial data\r\n"))
+	got, err := readDotBody(r)
+	if err != nil {
+		t.Fatalf("readDotBody EOF: %v", err)
+	}
+	if string(got) != "partial data\n" {
+		t.Errorf("readDotBody EOF = %q", string(got))
+	}
+}
diff --git a/internal/usenet/nzb/parser_test.go b/internal/usenet/nzb/parser_test.go
index 8d0d686..f14b64a 100644
--- a/internal/usenet/nzb/parser_test.go
+++ b/internal/usenet/nzb/parser_test.go
@@ -267,3 +267,784 @@ func TestStripAngleBrackets(t *testing.T) {
 		t.Errorf("MessageID not stripped: got %q", nzb.Files[0].Segments[0].MessageID)
 	}
 }
+
+// --- Malformed / edge-case XML inputs ---
+
+func TestParse_CompletelyEmpty(t *testing.T) {
+	_, err := Parse(strings.NewReader(""))
+	if err == nil {
+		t.Error("expected error for completely empty input")
+	}
+}
+
+func TestParse_OnlyWhitespace(t *testing.T) {
+	_, err := Parse(strings.NewReader("   \n\t  "))
+	if err == nil {
+		t.Error("expected error for whitespace-only input")
+	}
+}
+
+func TestParse_ValidXMLButNotNZB(t *testing.T) {
+	_, err := Parse(strings.NewReader(`<?xml version="1.0"?><html><body>Hello</body></html>`))
+	if err == nil {
+		t.Error("expected error for non-NZB XML")
+	}
+}
+
+func TestParse_NZBWithNoSegments(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments></segments>
+  </file>
+</nzb>`
+	_, err := Parse(strings.NewReader(xml))
+	if err == nil {
+		t.Error("expected error for file with no segments")
+	}
+}
+
+func TestParse_SegmentWithEmptyMessageID(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">   </segment>
+    </segments>
+  </file>
+</nzb>`
+	_, err := Parse(strings.NewReader(xml))
+	if err == nil {
+		t.Error("expected error: segment with empty/whitespace message ID should be skipped, leaving no valid files")
+	}
+}
+
+func TestParse_MixedValidAndEmptySegments(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">valid@id</segment>
+      <segment bytes="200" number="2">  </segment>
+      <segment bytes="300" number="3">also-valid@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if len(nzb.Files[0].Segments) != 2 {
+		t.Errorf("expected 2 valid segments, got %d", len(nzb.Files[0].Segments))
+	}
+}
+
+// --- Metadata / Head parsing ---
+
+func TestParse_MetaPassword(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <head>
+    <meta type="password">s3cr3t</meta>
+    <meta type="title">My Movie</meta>
+    <meta type="category">Movies</meta>
+  </head>
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if nzb.Password != "s3cr3t" {
+		t.Errorf("Password: got %q, want %q", nzb.Password, "s3cr3t")
+	}
+	if nzb.Meta["title"] != "My Movie" {
+		t.Errorf("Meta title: got %q", nzb.Meta["title"])
+	}
+	if nzb.Meta["category"] != "Movies" {
+		t.Errorf("Meta category: got %q", nzb.Meta["category"])
+	}
+}
+
+func TestParse_MetaPasswordWithWhitespace(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <head>
+    <meta type="password">  padded  </meta>
+  </head>
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if nzb.Password != "padded" {
+		t.Errorf("Password should be trimmed: got %q", nzb.Password)
+	}
+}
+
+func TestParse_NoHead(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if nzb.Password != "" {
+		t.Errorf("Password should be empty: got %q", nzb.Password)
+	}
+	if len(nzb.Meta) != 0 {
+		t.Errorf("Meta should be empty: got %v", nzb.Meta)
+	}
+}
+
+func TestParse_MetaWithEmptyType(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <head>
+    <meta type="">ignored</meta>
+    <meta type="name">kept</meta>
+  </head>
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if _, ok := nzb.Meta[""]; ok {
+		t.Error("empty-type meta should not be stored")
+	}
+	if nzb.Meta["name"] != "kept" {
+		t.Errorf("Meta name: got %q", nzb.Meta["name"])
+	}
+}
+
+// --- Multiple files ---
+
+func TestParse_MultipleFilesVariousTypes(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="bot" date="1700000000" subject="&quot;movie.mkv&quot; yEnc (1/100)">
+    <groups><group>alt.binaries.movies</group></groups>
+    <segments>
+      <segment bytes="768000" number="1">mkv001@ex</segment>
+      <segment bytes="768000" number="2">mkv002@ex</segment>
+    </segments>
+  </file>
+  <file poster="bot" date="1700000000" subject="&quot;movie.nfo&quot; yEnc (1/1)">
+    <groups><group>alt.binaries.movies</group></groups>
+    <segments>
+      <segment bytes="4096" number="1">nfo001@ex</segment>
+    </segments>
+  </file>
+  <file poster="bot" date="1700000000" subject="&quot;movie.par2&quot; yEnc (1/1)">
+    <groups><group>alt.binaries.movies</group></groups>
+    <segments>
+      <segment bytes="32768" number="1">par001@ex</segment>
+    </segments>
+  </file>
+  <file poster="bot" date="1700000000" subject="&quot;movie.vol0+1.par2&quot; yEnc (1/1)">
+    <groups><group>alt.binaries.movies</group></groups>
+    <segments>
+      <segment bytes="65536" number="1">parv001@ex</segment>
+    </segments>
+  </file>
+  <file poster="bot" date="1700000000" subject="&quot;sample.mkv&quot; yEnc (1/1)">
+    <groups><group>alt.binaries.movies</group></groups>
+    <segments>
+      <segment bytes="10000" number="1">sample001@ex</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+
+	if len(nzb.Files) != 5 {
+		t.Fatalf("expected 5 files, got %d", len(nzb.Files))
+	}
+
+	// ContentFiles should exclude nfo, par2, par2 vol, and sample
+	content := nzb.ContentFiles()
+	if len(content) != 1 {
+		t.Errorf("ContentFiles: got %d, want 1", len(content))
+	}
+	if len(content) > 0 && content[0].Filename() != "movie.mkv" {
+		t.Errorf("ContentFiles[0]: got %q, want movie.mkv", content[0].Filename())
+	}
+
+	// Par2Files
+	par2 := nzb.Par2Files()
+	if len(par2) != 2 {
+		t.Errorf("Par2Files: got %d, want 2", len(par2))
+	}
+
+	if !nzb.HasPar2() {
+		t.Error("HasPar2 should be true")
+	}
+	if nzb.HasRars() {
+		t.Error("HasRars should be false for this NZB")
+	}
+}
+
+// --- Segment ordering / number parsing ---
+
+func TestParse_SegmentNumberParsing(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="3">c@id</segment>
+      <segment bytes="200" number="1">a@id</segment>
+      <segment bytes="300" number="2">b@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+
+	segs := nzb.Files[0].Segments
+	if len(segs) != 3 {
+		t.Fatalf("expected 3 segments, got %d", len(segs))
+	}
+
+	// Parse preserves order from XML; sorting is done by the downloader
+	// Verify numbers are parsed correctly
+	numbers := make(map[int]bool)
+	for _, s := range segs {
+		numbers[s.Number] = true
+	}
+	for _, want := range []int{1, 2, 3} {
+		if !numbers[want] {
+			t.Errorf("missing segment number %d", want)
+		}
+	}
+}
+
+func TestParse_SegmentBytesZero(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="0" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if nzb.Files[0].Segments[0].Bytes != 0 {
+		t.Errorf("expected 0 bytes, got %d", nzb.Files[0].Segments[0].Bytes)
+	}
+}
+
+func TestParse_SegmentBytesNonNumeric(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="abc" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	// Non-numeric bytes should parse as 0
+	if nzb.Files[0].Segments[0].Bytes != 0 {
+		t.Errorf("non-numeric bytes should be 0, got %d", nzb.Files[0].Segments[0].Bytes)
+	}
+}
+
+// --- File helper methods ---
+
+func TestFileTotalBytes(t *testing.T) {
+	f := File{
+		Segments: []Segment{
+			{Bytes: 100}, {Bytes: 200}, {Bytes: 300},
+		},
+	}
+	if got := f.TotalBytes(); got != 600 {
+		t.Errorf("TotalBytes: got %d, want 600", got)
+	}
+}
+
+func TestFileTotalBytes_Empty(t *testing.T) {
+	f := File{}
+	if got := f.TotalBytes(); got != 0 {
+		t.Errorf("TotalBytes of empty file: got %d, want 0", got)
+	}
+}
+
+func TestFileExtension_Various(t *testing.T) {
+	tests := []struct {
+		subject string
+		want    string
+	}{
+		{`"file.MKV" yEnc`, ".mkv"},
+		{`"file.RAR" yEnc`, ".rar"},
+		{`"file.Par2" yEnc`, ".par2"},
+		{`"noext" yEnc`, ""},
+		{`"file.tar.gz" yEnc`, ".gz"},
+	}
+	for _, tt := range tests {
+		f := File{Subject: tt.subject}
+		if got := f.Extension(); got != tt.want {
+			t.Errorf("Extension(%q) = %q, want %q", tt.subject, got, tt.want)
+		}
+	}
+}
+
+// --- LargestFile edge cases ---
+
+func TestLargestFile_EmptyNZB(t *testing.T) {
+	nzb := &NZB{}
+	if nzb.LargestFile() != nil {
+		t.Error("LargestFile should return nil for empty NZB")
+	}
+}
+
+func TestLargestFile_SingleFile(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"only.bin"`, Segments: []Segment{{Bytes: 100}}},
+		},
+	}
+	largest := nzb.LargestFile()
+	if largest == nil {
+		t.Fatal("LargestFile should not be nil")
+	}
+	if largest.Filename() != "only.bin" {
+		t.Errorf("got %q", largest.Filename())
+	}
+}
+
+func TestLargestFile_MultipleSameSize(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"a.bin"`, Segments: []Segment{{Bytes: 100}}},
+			{Subject: `"b.bin"`, Segments: []Segment{{Bytes: 100}}},
+		},
+	}
+	largest := nzb.LargestFile()
+	if largest == nil {
+		t.Fatal("LargestFile should not be nil")
+	}
+	// Should return the first one (stable)
+	if largest.Filename() != "a.bin" {
+		t.Errorf("got %q, expected first file for equal sizes", largest.Filename())
+	}
+}
+
+// --- IsObfuscated ---
+
+func TestIsObfuscated_Normal(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"Movie.2024.1080p.BluRay.x264-GROUP.mkv"`},
+		},
+	}
+	if nzb.IsObfuscated() {
+		t.Error("normal filename should not be obfuscated")
+	}
+}
+
+func TestIsObfuscated_HexName(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"a1b2c3d4e5f6a7b8c9d0e1f2.mkv"`},
+		},
+	}
+	if !nzb.IsObfuscated() {
+		t.Error("hex-like filename should be obfuscated")
+	}
+}
+
+func TestIsObfuscated_EmptyFiles(t *testing.T) {
+	nzb := &NZB{}
+	if nzb.IsObfuscated() {
+		t.Error("empty NZB should not be obfuscated")
+	}
+}
+
+func TestIsObfuscated_ShortHex(t *testing.T) {
+	// Short name (<=10 chars) should not trigger obfuscation
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"abcdef.mkv"`},
+		},
+	}
+	if nzb.IsObfuscated() {
+		t.Error("short hex-like name should not be obfuscated")
+	}
+}
+
+// --- isMetadataFile ---
+
+func TestIsMetadataFile(t *testing.T) {
+	tests := []struct {
+		name string
+		want bool
+	}{
+		{"file.par2", true},
+		{"file.nfo", true},
+		{"file.sfv", true},
+		{"file.nzb", true},
+		{"file.txt", true},
+		{"file.jpg", true},
+		{"file.png", true},
+		{"file.url", true},
+		{"file.mkv", false},
+		{"file.rar", false},
+		{"file.avi", false},
+		{"FILE.PAR2", true},
+		{"FILE.NFO", true},
+	}
+	for _, tt := range tests {
+		if got := isMetadataFile(tt.name); got != tt.want {
+			t.Errorf("isMetadataFile(%q) = %v, want %v", tt.name, got, tt.want)
+		}
+	}
+}
+
+// --- isSampleFile ---
+
+func TestIsSampleFile(t *testing.T) {
+	tests := []struct {
+		name string
+		want bool
+	}{
+		{"movie.sample.mkv", true},
+		{"Sample.mkv", true},
+		{"SAMPLE.avi", true},
+		{"movie-sample-video.mkv", true},
+		{"movie_sample.mkv", true},
+		{"sample.mkv", true},
+		{"resampled.mkv", false}, // "sample" is part of "resampled"
+		{"movie.mkv", false},
+		{"my.samples.zip", false}, // "sample" followed by 's' (alphanumeric)
+	}
+	for _, tt := range tests {
+		if got := isSampleFile(tt.name); got != tt.want {
+			t.Errorf("isSampleFile(%q) = %v, want %v", tt.name, got, tt.want)
+		}
+	}
+}
+
+// --- isHexLike ---
+
+func TestIsHexLike(t *testing.T) {
+	tests := []struct {
+		input string
+		want  bool
+	}{
+		{"abcdef0123456789", true},
+		{"ABCDEF", true},
+		{"Movie2024", false},
+		{"aabbccdd", true},
+		{"xyz_not_hex", false},
+	}
+	for _, tt := range tests {
+		if got := isHexLike(tt.input); got != tt.want {
+			t.Errorf("isHexLike(%q) = %v, want %v", tt.input, got, tt.want)
+		}
+	}
+}
+
+// --- sanitizeFilename ---
+
+func TestSanitizeFilename(t *testing.T) {
+	tests := []struct {
+		input string
+		want  string
+	}{
+		{"simple name", "simple name"},
+		{"name (1/50)", "name"},
+		{"file yEnc (01/99)", "file"},
+		{`path/with\special:chars*?`, `path_with_special_chars__`},
+		{`"quoted" text`, `_quoted_ text`},
+		{"  spaces  ", "spaces"},
+	}
+	for _, tt := range tests {
+		if got := sanitizeFilename(tt.input); got != tt.want {
+			t.Errorf("sanitizeFilename(%q) = %q, want %q", tt.input, got, tt.want)
+		}
+	}
+}
+
+// --- Filename fallback ---
+
+func TestFilename_Fallback_NoQuotes(t *testing.T) {
+	f := File{Subject: "No quotes here yEnc (1/50)"}
+	got := f.Filename()
+	if got != "No quotes here" {
+		t.Errorf("Filename fallback: got %q, want %q", got, "No quotes here")
+	}
+}
+
+func TestFilename_EmptySubject(t *testing.T) {
+	f := File{Subject: ""}
+	got := f.Filename()
+	if got != "" {
+		t.Errorf("Filename empty subject: got %q, want empty", got)
+	}
+}
+
+// --- NZB aggregate methods on mixed content ---
+
+func TestNZB_HasRars_NoRars(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"movie.mkv"`},
+			{Subject: `"movie.par2"`},
+		},
+	}
+	if nzb.HasRars() {
+		t.Error("HasRars should be false")
+	}
+}
+
+func TestNZB_HasPar2_NoPar2(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"movie.mkv"`},
+			{Subject: `"movie.rar"`},
+		},
+	}
+	if nzb.HasPar2() {
+		t.Error("HasPar2 should be false")
+	}
+}
+
+func TestNZB_TotalSegments_MultiFile(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Segments: []Segment{{}, {}, {}}},
+			{Segments: []Segment{{}, {}}},
+		},
+	}
+	if got := nzb.TotalSegments(); got != 5 {
+		t.Errorf("TotalSegments: got %d, want 5", got)
+	}
+}
+
+func TestNZB_TotalBytes_MultiFile(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Segments: []Segment{{Bytes: 100}, {Bytes: 200}}},
+			{Segments: []Segment{{Bytes: 300}}},
+		},
+	}
+	if got := nzb.TotalBytes(); got != 600 {
+		t.Errorf("TotalBytes: got %d, want 600", got)
+	}
+}
+
+// --- isRarFile extended ---
+
+func TestIsRarFile_Extended(t *testing.T) {
+	tests := []struct {
+		name string
+		want bool
+	}{
+		{"file.RAR", true}, // case insensitive
+		{"file.Rar", true},
+		{"file.s01", true},
+		{"file.s99", true},
+		{"file.002", true},
+		{"file.999", true},
+		{"file.r0", false},  // too short extension
+		{"file.rXX", false}, // non-numeric
+		{"file", false},     // no extension
+		{"file.mp4", false},
+	}
+	for _, tt := range tests {
+		if got := isRarFile(tt.name); got != tt.want {
+			t.Errorf("isRarFile(%q) = %v, want %v", tt.name, got, tt.want)
+		}
+	}
+}
+
+// --- Parse with date edge cases ---
+
+func TestParse_DateNonNumeric(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="not-a-number" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if nzb.Files[0].Date != 0 {
+		t.Errorf("non-numeric date should be 0, got %d", nzb.Files[0].Date)
+	}
+}
+
+func TestParse_DateEmpty(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="" subject="&quot;test.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if nzb.Files[0].Date != 0 {
+		t.Errorf("empty date should be 0, got %d", nzb.Files[0].Date)
+	}
+}
+
+// --- Parse: file with all segments having empty IDs should be excluded ---
+
+func TestParse_AllEmptySegments(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;bad.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">  </segment>
+      <segment bytes="200" number="2"></segment>
+    </segments>
+  </file>
+  <file poster="test" date="0" subject="&quot;good.bin&quot;">
+    <groups><group>alt.test</group></groups>
+    <segments>
+      <segment bytes="100" number="1">valid@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if len(nzb.Files) != 1 {
+		t.Fatalf("expected 1 valid file, got %d", len(nzb.Files))
+	}
+	if nzb.Files[0].Filename() != "good.bin" {
+		t.Errorf("expected good.bin, got %q", nzb.Files[0].Filename())
+	}
+}
+
+// --- Groups ---
+
+func TestParse_NoGroups(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups></groups>
+    <segments>
+      <segment bytes="100" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if len(nzb.Files[0].Groups) != 0 {
+		t.Errorf("expected 0 groups, got %d", len(nzb.Files[0].Groups))
+	}
+}
+
+func TestParse_MultipleGroups(t *testing.T) {
+	xml := `<?xml version="1.0"?>
+<nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">
+  <file poster="test" date="0" subject="&quot;test.bin&quot;">
+    <groups>
+      <group>alt.binaries.movies</group>
+      <group>alt.binaries.multimedia</group>
+      <group>alt.binaries.hdtv</group>
+    </groups>
+    <segments>
+      <segment bytes="100" number="1">seg@id</segment>
+    </segments>
+  </file>
+</nzb>`
+	nzb, err := Parse(strings.NewReader(xml))
+	if err != nil {
+		t.Fatalf("Parse failed: %v", err)
+	}
+	if len(nzb.Files[0].Groups) != 3 {
+		t.Errorf("expected 3 groups, got %d", len(nzb.Files[0].Groups))
+	}
+}
+
+// --- ContentFiles with sample variations ---
+
+func TestContentFiles_ExcludesSamples(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"movie.mkv"`, Segments: []Segment{{Bytes: 1000, MessageID: "a"}}},
+			{Subject: `"movie.sample.mkv"`, Segments: []Segment{{Bytes: 100, MessageID: "b"}}},
+			{Subject: `"Sample/preview.mkv"`, Segments: []Segment{{Bytes: 100, MessageID: "c"}}},
+		},
+	}
+	content := nzb.ContentFiles()
+	if len(content) != 1 {
+		t.Errorf("ContentFiles should exclude samples: got %d, want 1", len(content))
+	}
+}
+
+// --- RarFiles with split naming ---
+
+func TestRarFiles_SplitRars(t *testing.T) {
+	nzb := &NZB{
+		Files: []File{
+			{Subject: `"movie.rar"`, Segments: []Segment{{MessageID: "a"}}},
+			{Subject: `"movie.r00"`, Segments: []Segment{{MessageID: "b"}}},
+			{Subject: `"movie.r01"`, Segments: []Segment{{MessageID: "c"}}},
+			{Subject: `"movie.001"`, Segments: []Segment{{MessageID: "d"}}},
+			{Subject: `"movie.002"`, Segments: []Segment{{MessageID: "e"}}},
+			{Subject: `"movie.par2"`, Segments: []Segment{{MessageID: "f"}}},
+			{Subject: `"movie.mkv"`, Segments: []Segment{{MessageID: "g"}}},
+		},
+	}
+	rars := nzb.RarFiles()
+	if len(rars) != 5 {
+		t.Errorf("RarFiles: got %d, want 5", len(rars))
+	}
+}
diff --git a/internal/usenet/postprocess/extract.go b/internal/usenet/postprocess/extract.go
index 0a9b582..0c6a8e3 100644
--- a/internal/usenet/postprocess/extract.go
+++ b/internal/usenet/postprocess/extract.go
@@ -1,6 +1,7 @@
 package postprocess
 
 import (
+	"context"
 	"fmt"
 	"log"
 	"os"
@@ -8,8 +9,25 @@ import (
 	"path/filepath"
 	"regexp"
 	"strings"
+	"time"
 )
 
+// extractTimeout caps how long a single extractor invocation may run. Without
+// a cap, an encrypted archive that triggers a TTY-only prompt (or a corrupt
+// archive that confuses the tool) hangs the post-process pipeline forever.
+const extractTimeout = 30 * time.Minute
+
+// validatePassword rejects passwords containing control characters that could
+// inject extra answers into unrar/7z prompts via stdin (e.g. a newline lets an
+// attacker-controlled NZB password feed a second response to overwrite or
+// rename prompts).
+func validatePassword(password string) error {
+	if strings.ContainsAny(password, "\r\n\x00") {
+		return fmt.Errorf("invalid password: contains control characters")
+	}
+	return nil
+}
+
 // ExtractorType identifies which extraction tool is available.
 type ExtractorType string
 
@@ -50,18 +68,35 @@ func Extract(archivePath string, outputDir string, password string) ([]string, e
 }
 
 // extractUnrar extracts using unrar.
+//
+// Security: when a password is supplied it is sent via stdin rather than via
+// the `-p<password>` switch so it does not appear in `/proc/<pid>/cmdline`
+// (visible to any other process on the host). unrar prompts for the password
+// when no `-p` switch is given, and reads the prompt response from stdin when
+// no controlling TTY is attached (the usual case for a daemon-spawned child).
 func extractUnrar(unrarPath, archivePath, outputDir, password string) ([]string, error) {
+	if err := validatePassword(password); err != nil {
+		return nil, err
+	}
 	args := []string{"x", "-o+", "-y"}
-	if password != "" {
-		args = append(args, "-p"+password)
-	} else {
-		args = append(args, "-p-") // no password, skip asking
+	if password == "" {
+		// Tell unrar there is no password so it skips the prompt and fails
+		// fast on encrypted archives instead of hanging.
+		args = append(args, "-p-")
 	}
 	args = append(args, archivePath, outputDir+"/")
 
-	cmd := exec.Command(unrarPath, args...)
+	ctx, cancel := context.WithTimeout(context.Background(), extractTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, unrarPath, args...)
 	cmd.Dir = outputDir
+	if password != "" {
+		cmd.Stdin = strings.NewReader(password + "\n")
+	}
 	output, err := cmd.CombinedOutput()
+	if ctx.Err() == context.DeadlineExceeded {
+		return nil, fmt.Errorf("unrar: timed out after %s", extractTimeout)
+	}
 	if err != nil {
 		// Check for password error
 		outStr := string(output)
@@ -75,18 +110,33 @@ func extractUnrar(unrarPath, archivePath, outputDir, password string) ([]string,
 }
 
 // extract7z extracts using 7z.
+//
+// Security: same rationale as extractUnrar — passwords go through stdin to
+// avoid `/proc/<pid>/cmdline` exposure. 7z reads the password from stdin when
+// no `-p` switch is given and the archive is encrypted.
 func extract7z(szPath, archivePath, outputDir, password string) ([]string, error) {
+	if err := validatePassword(password); err != nil {
+		return nil, err
+	}
 	args := []string{"x", "-y", "-o" + outputDir}
-	if password != "" {
-		args = append(args, "-p"+password)
-	} else {
-		args = append(args, "-p") // empty password
+	if password == "" {
+		// `-p` with no value tells 7z the password is empty so encrypted
+		// archives fail fast instead of waiting for a prompt.
+		args = append(args, "-p")
 	}
 	args = append(args, archivePath)
 
-	cmd := exec.Command(szPath, args...)
+	ctx, cancel := context.WithTimeout(context.Background(), extractTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, szPath, args...)
 	cmd.Dir = outputDir
+	if password != "" {
+		cmd.Stdin = strings.NewReader(password + "\n")
+	}
 	output, err := cmd.CombinedOutput()
+	if ctx.Err() == context.DeadlineExceeded {
+		return nil, fmt.Errorf("7z: timed out after %s", extractTimeout)
+	}
 	if err != nil {
 		outStr := string(output)
 		if strings.Contains(outStr, "Wrong password") || strings.Contains(outStr, "incorrect password") {
diff --git a/internal/usenet/postprocess/extract_test.go b/internal/usenet/postprocess/extract_test.go
new file mode 100644
index 0000000..5e61c75
--- /dev/null
+++ b/internal/usenet/postprocess/extract_test.go
@@ -0,0 +1,170 @@
+package postprocess
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestIsArchiveFile(t *testing.T) {
+	tests := []struct {
+		name string
+		want bool
+	}{
+		{"movie.rar", true},
+		{"movie.RAR", true},
+		{"movie.part01.rar", true},
+		{"movie.r00", true},
+		{"movie.r99", true},
+		{"movie.s00", true},
+		{"movie.001", true},
+		{"movie.099", true},
+		{"movie.mkv", false},
+		{"movie.mp4", false},
+		{"movie.par2", false},
+		{"movie.nfo", false},
+		{"movie.txt", false},
+		{"movie.r", false},
+		{"movie.abc", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isArchiveFile(tt.name)
+			if got != tt.want {
+				t.Errorf("isArchiveFile(%q) = %v, want %v", tt.name, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsCleanupTarget(t *testing.T) {
+	tests := []struct {
+		name string
+		want bool
+	}{
+		{"content.par2", true},
+		{"content.PAR2", true},
+		{"info.nfo", true},
+		{"checksum.sfv", true},
+		{"content.nzb", true},
+		{"content.srr", true},
+		{"content.srs", true},
+		{"cover.jpg", true},
+		{"cover.png", true},
+		{"readme.txt", true},
+		{"link.url", true},
+		{"movie.rar", true},
+		{"movie.r00", true},
+		{"movie.s01", true},
+		{"movie.001", true},
+		{"movie.mkv", false},
+		{"movie.mp4", false},
+		{"movie.avi", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isCleanupTarget(tt.name)
+			if got != tt.want {
+				t.Errorf("isCleanupTarget(%q) = %v, want %v", tt.name, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsNumeric(t *testing.T) {
+	tests := []struct {
+		input string
+		want  bool
+	}{
+		{"", false},
+		{"0", true},
+		{"123", true},
+		{"00", true},
+		{"12a", false},
+		{"abc", false},
+		{" 1", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got := isNumeric(tt.input)
+			if got != tt.want {
+				t.Errorf("isNumeric(%q) = %v, want %v", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestListExtractedFiles(t *testing.T) {
+	dir := t.TempDir()
+
+	// Create some files
+	os.WriteFile(filepath.Join(dir, "movie.mkv"), []byte("video"), 0o644)
+	os.WriteFile(filepath.Join(dir, "subs.srt"), []byte("subs"), 0o644)
+	os.WriteFile(filepath.Join(dir, "movie.rar"), []byte("archive"), 0o644)
+	os.WriteFile(filepath.Join(dir, "movie.r00"), []byte("archive part"), 0o644)
+
+	archivePath := filepath.Join(dir, "movie.rar")
+	files, err := listExtractedFiles(dir, archivePath)
+	if err != nil {
+		t.Fatalf("listExtractedFiles: %v", err)
+	}
+
+	// Should exclude .rar and .r00 (archive files in same dir)
+	// Should include movie.mkv and subs.srt
+	if len(files) != 2 {
+		t.Errorf("expected 2 files, got %d: %v", len(files), files)
+	}
+
+	for _, f := range files {
+		base := filepath.Base(f)
+		if base != "movie.mkv" && base != "subs.srt" {
+			t.Errorf("unexpected file: %s", base)
+		}
+	}
+}
+
+func TestCleanup(t *testing.T) {
+	dir := t.TempDir()
+
+	// Files that should be removed
+	cleanupFiles := []string{"content.par2", "info.nfo", "checksum.sfv", "movie.rar", "movie.r00"}
+	for _, name := range cleanupFiles {
+		os.WriteFile(filepath.Join(dir, name), []byte("data"), 0o644)
+	}
+
+	// Files that should be kept
+	keepFiles := []string{"movie.mkv", "subs.srt"}
+	for _, name := range keepFiles {
+		os.WriteFile(filepath.Join(dir, name), []byte("data"), 0o644)
+	}
+
+	err := Cleanup(dir)
+	if err != nil {
+		t.Fatalf("Cleanup: %v", err)
+	}
+
+	// Verify cleanup files are gone
+	for _, name := range cleanupFiles {
+		if _, err := os.Stat(filepath.Join(dir, name)); !os.IsNotExist(err) {
+			t.Errorf("expected %s to be removed", name)
+		}
+	}
+
+	// Verify kept files still exist
+	for _, name := range keepFiles {
+		if _, err := os.Stat(filepath.Join(dir, name)); err != nil {
+			t.Errorf("expected %s to exist, got: %v", name, err)
+		}
+	}
+}
+
+func TestPasswordError(t *testing.T) {
+	err := &PasswordError{Archive: "/tmp/movie.rar"}
+	msg := err.Error()
+	if msg != "archive is password protected: /tmp/movie.rar" {
+		t.Errorf("PasswordError.Error() = %q", msg)
+	}
+}
diff --git a/internal/usenet/postprocess/pipeline_test.go b/internal/usenet/postprocess/pipeline_test.go
new file mode 100644
index 0000000..f3c0cc9
--- /dev/null
+++ b/internal/usenet/postprocess/pipeline_test.go
@@ -0,0 +1,156 @@
+package postprocess
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestFindPar2File(t *testing.T) {
+	dir := t.TempDir()
+
+	// Create par2 files of different sizes
+	mainPar2 := filepath.Join(dir, "content.par2")
+	vol1 := filepath.Join(dir, "content.vol000+01.par2")
+	vol2 := filepath.Join(dir, "content.vol001+02.par2")
+
+	os.WriteFile(mainPar2, make([]byte, 100), 0o644) // smallest
+	os.WriteFile(vol1, make([]byte, 10000), 0o644)
+	os.WriteFile(vol2, make([]byte, 50000), 0o644)
+
+	files := map[string]string{
+		"content.par2":           mainPar2,
+		"content.vol000+01.par2": vol1,
+		"content.vol001+02.par2": vol2,
+	}
+
+	result := findPar2File(files)
+	if result != mainPar2 {
+		t.Errorf("findPar2File() = %q, want %q (smallest par2)", result, mainPar2)
+	}
+}
+
+func TestFindPar2FileNone(t *testing.T) {
+	files := map[string]string{
+		"video.mkv": "/tmp/video.mkv",
+		"subs.srt":  "/tmp/subs.srt",
+	}
+
+	result := findPar2File(files)
+	if result != "" {
+		t.Errorf("findPar2File() = %q, want empty", result)
+	}
+}
+
+func TestFindPar2FileEmpty(t *testing.T) {
+	result := findPar2File(map[string]string{})
+	if result != "" {
+		t.Errorf("findPar2File() = %q, want empty", result)
+	}
+}
+
+func TestFindFirstRarPart01(t *testing.T) {
+	files := map[string]string{
+		"movie.part01.rar": "/tmp/movie.part01.rar",
+		"movie.part02.rar": "/tmp/movie.part02.rar",
+		"movie.part03.rar": "/tmp/movie.part03.rar",
+	}
+
+	result := findFirstRar(files)
+	if result != "/tmp/movie.part01.rar" {
+		t.Errorf("findFirstRar() = %q, want part01.rar", result)
+	}
+}
+
+func TestFindFirstRarSingle(t *testing.T) {
+	files := map[string]string{
+		"movie.rar": "/tmp/movie.rar",
+		"movie.r00": "/tmp/movie.r00",
+		"movie.r01": "/tmp/movie.r01",
+	}
+
+	result := findFirstRar(files)
+	if result != "/tmp/movie.rar" {
+		t.Errorf("findFirstRar() = %q, want movie.rar (shortest)", result)
+	}
+}
+
+func TestFindFirstRarSplitFormat(t *testing.T) {
+	files := map[string]string{
+		"movie.001": "/tmp/movie.001",
+		"movie.002": "/tmp/movie.002",
+	}
+
+	result := findFirstRar(files)
+	if result != "/tmp/movie.001" {
+		t.Errorf("findFirstRar() = %q, want movie.001", result)
+	}
+}
+
+func TestFindFirstRarNone(t *testing.T) {
+	files := map[string]string{
+		"video.mkv": "/tmp/video.mkv",
+		"subs.srt":  "/tmp/subs.srt",
+	}
+
+	result := findFirstRar(files)
+	if result != "" {
+		t.Errorf("findFirstRar() = %q, want empty", result)
+	}
+}
+
+func TestFindMainFile(t *testing.T) {
+	dir := t.TempDir()
+
+	// Create video files of different sizes
+	small := filepath.Join(dir, "small.mkv")
+	large := filepath.Join(dir, "large.mkv")
+	nonVideo := filepath.Join(dir, "readme.txt")
+
+	os.WriteFile(small, make([]byte, 1000), 0o644)
+	os.WriteFile(large, make([]byte, 5000), 0o644)
+	os.WriteFile(nonVideo, make([]byte, 9000), 0o644)
+
+	result := findMainFile(dir, []string{small, large, nonVideo})
+	if result != large {
+		t.Errorf("findMainFile() = %q, want %q (largest video)", result, large)
+	}
+}
+
+func TestFindMainFileFallbackToDir(t *testing.T) {
+	dir := t.TempDir()
+
+	video := filepath.Join(dir, "movie.mp4")
+	os.WriteFile(video, make([]byte, 5000), 0o644)
+
+	// Pass empty file list — should fallback to scanning dir
+	result := findMainFile(dir, nil)
+	if result != video {
+		t.Errorf("findMainFile() = %q, want %q (dir scan fallback)", result, video)
+	}
+}
+
+func TestFindMainFileEmpty(t *testing.T) {
+	dir := t.TempDir()
+	result := findMainFile(dir, nil)
+	if result != "" {
+		t.Errorf("findMainFile() = %q, want empty", result)
+	}
+}
+
+func TestFindMainFileMultipleFormats(t *testing.T) {
+	dir := t.TempDir()
+
+	mkv := filepath.Join(dir, "movie.mkv")
+	mp4 := filepath.Join(dir, "movie.mp4")
+	avi := filepath.Join(dir, "movie.avi")
+
+	os.WriteFile(mkv, make([]byte, 3000), 0o644)
+	os.WriteFile(mp4, make([]byte, 5000), 0o644) // largest
+	os.WriteFile(avi, make([]byte, 2000), 0o644)
+
+	result := findMainFile(dir, []string{mkv, mp4, avi})
+	if result != mp4 {
+		t.Errorf("findMainFile() = %q, want %q", result, mp4)
+	}
+}
diff --git a/internal/vpn/vpn.go b/internal/vpn/vpn.go
new file mode 100644
index 0000000..7f50ea1
--- /dev/null
+++ b/internal/vpn/vpn.go
@@ -0,0 +1,333 @@
+// Package vpn brings up an in-process WireGuard tunnel (userspace, via
+// wireguard-go + gVisor netstack) and exposes it as a dialer so the BitTorrent
+// client's peer/tracker traffic can be split-tunnelled through it — without
+// touching the OS routing table or requiring root.
+//
+// The config is a standard WireGuard .conf fetched from the web
+// (/api/internal/agent/vpn-config). Only the torrent client uses this tunnel;
+// unarr's control-plane traffic (API, heartbeats) keeps using the normal net.
+package vpn
+
+import (
+	"bufio"
+	"context"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"net/netip"
+	neturl "net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"golang.zx2c4.com/wireguard/conn"
+	"golang.zx2c4.com/wireguard/device"
+	"golang.zx2c4.com/wireguard/tun/netstack"
+)
+
+// ErrCode classifies fetch failures the agent should react to differently.
+type ErrCode string
+
+const (
+	ErrDisabled       ErrCode = "disabled"        // 503 — VPN feature off server-side
+	ErrNotProvisioned ErrCode = "not_provisioned" // 403 — user has no active VPN
+	ErrSlotOnDevice   ErrCode = "slot_on_device"  // 409 — slot claimed by a device
+	ErrUpstream       ErrCode = "upstream"        // network / 5xx / parse
+)
+
+// FetchError carries an ErrCode so callers can decide whether to retry, warn, or
+// fall back to a clear (non-VPN) download.
+type FetchError struct {
+	Code ErrCode
+	Msg  string
+}
+
+func (e *FetchError) Error() string { return fmt.Sprintf("vpn fetch: %s (%s)", e.Msg, e.Code) }
+
+type fetchResponse struct {
+	Content  string `json:"content"`
+	Filename string `json:"filename"`
+	ServerID int    `json:"serverId"`
+	Mode     string `json:"mode"`
+	Error    string `json:"error"`
+	CodeStr  string `json:"code"`
+}
+
+// FetchConfig retrieves the agent's WireGuard .conf from the web API. Auth is
+// `Authorization: Bearer <apiKey>` (the agent-auth scheme). agentId lets the web
+// arbitrate the single WireGuard slot (first agent to ask claims it; others get
+// 409 → ErrSlotOnDevice and should use OpenVPN on their host instead).
+func FetchConfig(ctx context.Context, apiURL, apiKey, userAgent, agentID string, probe bool) (string, error) {
+	q := neturl.Values{}
+	if agentID != "" {
+		q.Set("agentId", agentID)
+	}
+	if probe {
+		// Validate provisioning without claiming the WireGuard slot (status --check).
+		q.Set("probe", "1")
+	}
+	url := strings.TrimSuffix(apiURL, "/") + "/api/internal/agent/vpn-config"
+	if len(q) > 0 {
+		url += "?" + q.Encode()
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return "", &FetchError{ErrUpstream, err.Error()}
+	}
+	req.Header.Set("Authorization", "Bearer "+apiKey)
+	req.Header.Set("User-Agent", userAgent)
+	req.Header.Set("Accept", "application/json")
+
+	client := &http.Client{Timeout: 20 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", &FetchError{ErrUpstream, err.Error()}
+	}
+	defer resp.Body.Close()
+
+	var body fetchResponse
+	_ = json.NewDecoder(resp.Body).Decode(&body)
+
+	switch resp.StatusCode {
+	case http.StatusOK:
+		if body.Content == "" {
+			return "", &FetchError{ErrUpstream, "empty config"}
+		}
+		return body.Content, nil
+	case http.StatusServiceUnavailable:
+		return "", &FetchError{ErrDisabled, "VPN disabled server-side"}
+	case http.StatusForbidden:
+		return "", &FetchError{ErrNotProvisioned, "no active VPN for this account"}
+	case http.StatusConflict:
+		return "", &FetchError{ErrSlotOnDevice, "VPN slot is active on one of your devices"}
+	default:
+		msg := body.Error
+		if msg == "" {
+			msg = "unexpected status " + strconv.Itoa(resp.StatusCode)
+		}
+		return "", &FetchError{ErrUpstream, msg}
+	}
+}
+
+// Tunnel is a live userspace WireGuard tunnel. Net exposes a DialContext +
+// ListenUDP backed by the tunnel; wire these into the torrent client.
+type Tunnel struct {
+	dev *device.Device
+	Net *netstack.Net
+	// Endpoint is the resolved ip:port of the WireGuard server this tunnel
+	// exits through — surfaced in `unarr vpn status` so the user can see which
+	// VPN server their torrent traffic is routed out of.
+	Endpoint string
+}
+
+// Up parses a WireGuard .conf and brings up the tunnel in userspace.
+func Up(confText string) (*Tunnel, error) {
+	wc, err := parseConf(confText)
+	if err != nil {
+		return nil, err
+	}
+
+	mtu := wc.mtu
+	if mtu == 0 {
+		mtu = 1420
+	}
+
+	tunDev, tnet, err := netstack.CreateNetTUN(wc.addresses, wc.dns, mtu)
+	if err != nil {
+		return nil, fmt.Errorf("create netstack tun: %w", err)
+	}
+
+	dev := device.NewDevice(tunDev, conn.NewDefaultBind(), device.NewLogger(device.LogLevelError, "wg-unarr "))
+	if err := dev.IpcSet(wc.uapi()); err != nil {
+		dev.Close()
+		return nil, fmt.Errorf("wireguard ipc set: %w", err)
+	}
+	if err := dev.Up(); err != nil {
+		dev.Close()
+		return nil, fmt.Errorf("wireguard up: %w", err)
+	}
+
+	return &Tunnel{dev: dev, Net: tnet, Endpoint: wc.endpoint}, nil
+}
+
+// Close tears the tunnel down.
+func (t *Tunnel) Close() {
+	if t != nil && t.dev != nil {
+		t.dev.Close()
+	}
+}
+
+// ListenPacket adapts the tunnel's UDP for anacrolix TrackerListenPacket so UDP
+// tracker announces also go through the VPN (no IP leak to trackers).
+func (t *Tunnel) ListenPacket(_ string, _ string) (net.PacketConn, error) {
+	return t.Net.ListenUDP(&net.UDPAddr{IP: net.IPv4zero, Port: 0})
+}
+
+// --- .conf parsing ----------------------------------------------------------
+
+type wgConf struct {
+	privateKey string // hex
+	addresses  []netip.Addr
+	dns        []netip.Addr
+	mtu        int
+
+	peerPublicKey  string // hex
+	presharedKey   string // hex (optional)
+	endpoint       string // resolved ip:port
+	allowedIPs     []string
+	keepalive      int
+}
+
+func (w *wgConf) uapi() string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "private_key=%s\n", w.privateKey)
+	fmt.Fprintf(&b, "public_key=%s\n", w.peerPublicKey)
+	if w.presharedKey != "" {
+		fmt.Fprintf(&b, "preshared_key=%s\n", w.presharedKey)
+	}
+	if w.endpoint != "" {
+		fmt.Fprintf(&b, "endpoint=%s\n", w.endpoint)
+	}
+	if w.keepalive > 0 {
+		fmt.Fprintf(&b, "persistent_keepalive_interval=%d\n", w.keepalive)
+	}
+	for _, a := range w.allowedIPs {
+		fmt.Fprintf(&b, "allowed_ip=%s\n", a)
+	}
+	return b.String()
+}
+
+func b64ToHex(s string) (string, error) {
+	raw, err := base64.StdEncoding.DecodeString(strings.TrimSpace(s))
+	if err != nil {
+		return "", fmt.Errorf("invalid base64 key: %w", err)
+	}
+	if len(raw) != 32 {
+		return "", fmt.Errorf("key must be 32 bytes, got %d", len(raw))
+	}
+	return hex.EncodeToString(raw), nil
+}
+
+func parseConf(text string) (*wgConf, error) {
+	w := &wgConf{keepalive: 25}
+	section := ""
+	sc := bufio.NewScanner(strings.NewReader(text))
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		if strings.HasPrefix(line, "[") {
+			section = strings.ToLower(strings.Trim(line, "[]"))
+			continue
+		}
+		key, val, ok := strings.Cut(line, "=")
+		if !ok {
+			continue
+		}
+		key = strings.ToLower(strings.TrimSpace(key))
+		val = strings.TrimSpace(val)
+
+		switch section {
+		case "interface":
+			switch key {
+			case "privatekey":
+				hexKey, err := b64ToHex(val)
+				if err != nil {
+					return nil, err
+				}
+				w.privateKey = hexKey
+			case "address":
+				for _, part := range strings.Split(val, ",") {
+					part = strings.TrimSpace(part)
+					if part == "" {
+						continue
+					}
+					pfx, err := netip.ParsePrefix(part)
+					if err != nil {
+						// allow bare address
+						if a, e2 := netip.ParseAddr(part); e2 == nil {
+							w.addresses = append(w.addresses, a)
+						}
+						continue
+					}
+					w.addresses = append(w.addresses, pfx.Addr())
+				}
+			case "dns":
+				for _, part := range strings.Split(val, ",") {
+					if a, err := netip.ParseAddr(strings.TrimSpace(part)); err == nil {
+						w.dns = append(w.dns, a)
+					}
+				}
+			case "mtu":
+				w.mtu, _ = strconv.Atoi(val)
+			}
+		case "peer":
+			switch key {
+			case "publickey":
+				hexKey, err := b64ToHex(val)
+				if err != nil {
+					return nil, err
+				}
+				w.peerPublicKey = hexKey
+			case "presharedkey":
+				if hexKey, err := b64ToHex(val); err == nil {
+					w.presharedKey = hexKey
+				}
+			case "endpoint":
+				ep, err := resolveEndpoint(val)
+				if err != nil {
+					return nil, err
+				}
+				w.endpoint = ep
+			case "allowedips":
+				for _, part := range strings.Split(val, ",") {
+					part = strings.TrimSpace(part)
+					if part != "" {
+						w.allowedIPs = append(w.allowedIPs, part)
+					}
+				}
+			case "persistentkeepalive":
+				if k, err := strconv.Atoi(val); err == nil {
+					w.keepalive = k
+				}
+			}
+		}
+	}
+
+	if w.privateKey == "" || w.peerPublicKey == "" {
+		return nil, fmt.Errorf("config missing keys")
+	}
+	if len(w.addresses) == 0 {
+		return nil, fmt.Errorf("config missing interface address")
+	}
+	if len(w.dns) == 0 {
+		// Resolve tracker hostnames through the tunnel rather than leaking to the
+		// local resolver. Fall back to Cloudflare.
+		w.dns = []netip.Addr{netip.MustParseAddr("1.1.1.1")}
+	}
+	if len(w.allowedIPs) == 0 {
+		w.allowedIPs = []string{"0.0.0.0/0", "::/0"}
+	}
+	return w, nil
+}
+
+// resolveEndpoint turns host:port into ip:port — wireguard-go's IpcSet endpoint
+// expects a literal IP (it does not resolve DNS). Resolution uses the real net.
+func resolveEndpoint(hostport string) (string, error) {
+	host, port, err := net.SplitHostPort(hostport)
+	if err != nil {
+		return "", fmt.Errorf("invalid endpoint %q: %w", hostport, err)
+	}
+	if ip := net.ParseIP(host); ip != nil {
+		return hostport, nil
+	}
+	ips, err := net.LookupIP(host)
+	if err != nil || len(ips) == 0 {
+		return "", fmt.Errorf("resolve endpoint %q: %w", host, err)
+	}
+	return net.JoinHostPort(ips[0].String(), port), nil
+}
diff --git a/lefthook.yml b/lefthook.yml
index e13da38..0064662 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -23,6 +23,12 @@ pre-commit:
           echo "golangci-lint not installed, skipping (install: https://golangci-lint.run/welcome/install/)"
         fi
 
+pre-push:
+  commands:
+    go-test:
+      glob: "*.go"
+      run: go test -race -count=1 -timeout=120s ./...
+
 commit-msg:
   scripts:
     validate.sh:
diff --git a/scripts/download-ffmpeg-static.sh b/scripts/download-ffmpeg-static.sh
new file mode 100755
index 0000000..719fcde
--- /dev/null
+++ b/scripts/download-ffmpeg-static.sh
@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# scripts/download-ffmpeg-static.sh — fetch static ffmpeg + ffprobe binaries
+# for every platform we ship. Run by goreleaser's `before.hooks` so each
+# tarball can bundle the binaries adjacent to `unarr`.
+#
+# Source: https://ffbinaries.com (same index the runtime fallback uses).
+# Output:
+#   dist-ffbinaries/<goos>-<goarch>/{ffmpeg, ffprobe}[.exe]
+# Idempotent: skips downloads when the target file already exists.
+
+set -euo pipefail
+
+# Map ffbinaries platform key → goreleaser {Os}-{Arch}. ffbinaries.com only
+# ships an x86_64 macOS build; for darwin-arm64 we fall back to evermeet.cx
+# universal binaries (handled separately below).
+PLATFORMS=(
+  "linux-64:linux-amd64"
+  "linux-arm64:linux-arm64"
+  "osx-64:darwin-amd64"
+  "windows-64:windows-amd64"
+)
+DEST_ROOT="${FFBINARIES_DEST:-dist-ffbinaries}"
+INDEX_URL="https://ffbinaries.com/api/v1/version/latest"
+
+for cmd in curl jq unzip; do
+  command -v "$cmd" >/dev/null 2>&1 || {
+    echo "[ffbin] missing required tool: $cmd" >&2
+    exit 2
+  }
+done
+
+mkdir -p "$DEST_ROOT"
+
+echo "[ffbin] fetching index from $INDEX_URL"
+INDEX_JSON="$(curl -fsSL "$INDEX_URL")"
+VERSION="$(echo "$INDEX_JSON" | jq -r .version)"
+echo "[ffbin] ffbinaries version: $VERSION"
+
+for entry in "${PLATFORMS[@]}"; do
+  ffbkey="${entry%%:*}"
+  goplat="${entry##*:}"
+  outdir="$DEST_ROOT/$goplat"
+  mkdir -p "$outdir"
+
+  for tool in ffmpeg ffprobe; do
+    binname="$tool"
+    [[ "$goplat" == windows-* ]] && binname="${tool}.exe"
+
+    if [ -f "$outdir/$binname" ]; then
+      echo "[ffbin] skip $goplat/$binname (already present)"
+      continue
+    fi
+
+    url="$(echo "$INDEX_JSON" | jq -r ".bin[\"$ffbkey\"][\"$tool\"] // empty")"
+    if [ -z "$url" ]; then
+      echo "[ffbin] WARN $goplat/$tool: no download URL in index" >&2
+      continue
+    fi
+
+    tmpzip="$(mktemp --suffix=.zip)"
+    echo "[ffbin] fetch $goplat/$tool from $url"
+    curl -fsSL --retry 5 --retry-delay 3 --retry-all-errors "$url" -o "$tmpzip"
+    unzip -p "$tmpzip" "$binname" > "$outdir/$binname"
+    chmod +x "$outdir/$binname"
+    rm -f "$tmpzip"
+  done
+done
+
+# --- darwin-arm64 via evermeet.cx (universal binary; ffbinaries lacks it) ---
+darwin_arm_dir="$DEST_ROOT/darwin-arm64"
+mkdir -p "$darwin_arm_dir"
+for tool in ffmpeg ffprobe; do
+  out="$darwin_arm_dir/$tool"
+  if [ -f "$out" ]; then
+    echo "[ffbin] skip darwin-arm64/$tool (already present)"
+    continue
+  fi
+  url="https://evermeet.cx/ffmpeg/getrelease/$tool/zip"
+  tmpzip="$(mktemp --suffix=.zip)"
+  echo "[ffbin] fetch darwin-arm64/$tool from $url"
+  curl -fsSL --retry 5 --retry-delay 3 --retry-all-errors "$url" -o "$tmpzip"
+  unzip -p "$tmpzip" "$tool" > "$out"
+  chmod +x "$out"
+  rm -f "$tmpzip"
+done
+
+# --- windows-arm64 via BtbN/FFmpeg-Builds (ffbinaries lacks it) ---
+# BtbN ships a single zip per platform with ffmpeg.exe + ffprobe.exe under
+# ffmpeg-master-latest-winarm64-gpl/bin/. Extract both in one fetch.
+win_arm_dir="$DEST_ROOT/windows-arm64"
+mkdir -p "$win_arm_dir"
+needs_win_arm=0
+for tool in ffmpeg.exe ffprobe.exe; do
+  [ -f "$win_arm_dir/$tool" ] || needs_win_arm=1
+done
+if [ "$needs_win_arm" = "1" ]; then
+  url="https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-winarm64-gpl.zip"
+  tmpzip="$(mktemp --suffix=.zip)"
+  echo "[ffbin] fetch windows-arm64/{ffmpeg,ffprobe}.exe from $url"
+  curl -fsSL --retry 5 --retry-delay 3 --retry-all-errors "$url" -o "$tmpzip"
+  for tool in ffmpeg.exe ffprobe.exe; do
+    out="$win_arm_dir/$tool"
+    member="$(unzip -Z1 "$tmpzip" "*/bin/$tool" 2>/dev/null | head -1)"
+    if [ -z "$member" ]; then
+      echo "[ffbin] WARN windows-arm64/$tool: not found in BtbN zip" >&2
+      continue
+    fi
+    unzip -p "$tmpzip" "$member" > "$out"
+    chmod +x "$out"
+  done
+  rm -f "$tmpzip"
+else
+  echo "[ffbin] skip windows-arm64 (already present)"
+fi
+
+echo "[ffbin] done. layout:"
+find "$DEST_ROOT" -type f -printf "  %p (%s bytes)\n"
diff --git a/scripts/gen-release-key/main.go b/scripts/gen-release-key/main.go
new file mode 100644
index 0000000..51dfbda
--- /dev/null
+++ b/scripts/gen-release-key/main.go
@@ -0,0 +1,37 @@
+// gen-release-key generates an ed25519 keypair for signing release artifacts.
+// Run once per repository, then store the printed values:
+//
+//	RELEASE_SIGNING_KEY     → GitHub Actions secret (private key, base64)
+//	RELEASE_SIGNING_PUBKEY  → GitHub Actions variable (public key, base64)
+//
+// The public key is injected into the binary at build time via the
+// goreleaser ldflags entry that resolves
+// `github.com/torrentclaw/unarr/internal/upgrade.releasePubKeyBase64`.
+// The private key is used by the workflow's "Sign checksums.txt" step.
+//
+// Build and run:
+//
+//	go run ./scripts/gen-release-key
+package main
+
+import (
+	"crypto/ed25519"
+	"crypto/rand"
+	"encoding/base64"
+	"fmt"
+)
+
+func main() {
+	pub, priv, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println("# Add the following to your GitHub repository:")
+	fmt.Println("#   - Settings → Secrets and variables → Actions → New repository secret")
+	fmt.Println("#       RELEASE_SIGNING_KEY  =  <PRIVATE_KEY_BASE64 below>")
+	fmt.Println("#   - Settings → Secrets and variables → Actions → New repository variable")
+	fmt.Println("#       RELEASE_SIGNING_PUBKEY  =  <PUBLIC_KEY_BASE64 below>")
+	fmt.Println()
+	fmt.Printf("PUBLIC_KEY_BASE64=%s\n", base64.StdEncoding.EncodeToString(pub))
+	fmt.Printf("PRIVATE_KEY_BASE64=%s\n", base64.StdEncoding.EncodeToString(priv))
+}
diff --git a/scripts/release.sh b/scripts/release.sh
new file mode 100755
index 0000000..46862be
--- /dev/null
+++ b/scripts/release.sh
@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+#
+# release.sh — Automate version bump, changelog generation, and tag creation.
+#
+# Usage:
+#   ./scripts/release.sh patch|minor|major    Auto-bump from latest tag
+#   ./scripts/release.sh 0.5.0               Explicit version
+#   ./scripts/release.sh --dry-run patch      Preview without changes
+#
+set -euo pipefail
+
+VERSION_FILE="internal/cmd/version.go"
+CHANGELOG_FILE="CHANGELOG.md"
+
+# ── Colors ──────────────────────────────────────────────────────────
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+info()  { echo -e "${CYAN}▸${NC} $*"; }
+ok()    { echo -e "${GREEN}✓${NC} $*"; }
+warn()  { echo -e "${YELLOW}⚠${NC} $*"; }
+error() { echo -e "${RED}✗${NC} $*" >&2; }
+die()   { error "$@"; exit 1; }
+
+# ── Args ────────────────────────────────────────────────────────────
+DRY_RUN=false
+BUMP=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+    patch|minor|major) BUMP="$arg" ;;
+    [0-9]*) BUMP="$arg" ;;
+    -h|--help)
+      echo "Usage: $0 [--dry-run] <patch|minor|major|X.Y.Z>"
+      exit 0
+      ;;
+    *) die "Unknown argument: $arg" ;;
+  esac
+done
+
+[ -z "$BUMP" ] && die "Usage: $0 [--dry-run] <patch|minor|major|X.Y.Z>"
+
+# ── Prerequisites ───────────────────────────────────────────────────
+command -v git-cliff >/dev/null 2>&1 || die "git-cliff not found. Install: https://git-cliff.org/docs/installation"
+
+if [ "$DRY_RUN" = false ]; then
+  [ -n "$(git status --porcelain)" ] && die "Working tree is dirty. Commit or stash changes first."
+fi
+
+CURRENT_BRANCH=$(git branch --show-current)
+[ "$CURRENT_BRANCH" = "main" ] || warn "Not on main branch (current: $CURRENT_BRANCH)"
+
+HEAD_SUBJECT=$(git log -1 --pretty=%s)
+if [[ "$HEAD_SUBJECT" =~ \(([0-9]+\.[0-9]+\.[0-9]+)\) ]]; then
+  die "HEAD commit subject contains inline version bump: \"$HEAD_SUBJECT\"
+Release contract: version bumps MUST live in a dedicated 'chore(release): X.Y.Z' commit.
+Revert the inline bump and re-run this script — it will create the proper commit."
+fi
+if [[ "$HEAD_SUBJECT" =~ ^chore\(release\): ]]; then
+  die "HEAD is already a chore(release) commit: \"$HEAD_SUBJECT\"
+Nothing new to release. Add commits since the last release or amend intentionally outside this script."
+fi
+
+# ── Resolve version ────────────────────────────────────────────────
+LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
+LATEST_VERSION="${LATEST_TAG#v}"
+
+bump_version() {
+  local version="$1" part="$2"
+  IFS='.' read -r major minor patch <<< "$version"
+  case "$part" in
+    major) echo "$((major + 1)).0.0" ;;
+    minor) echo "$major.$((minor + 1)).0" ;;
+    patch) echo "$major.$minor.$((patch + 1))" ;;
+  esac
+}
+
+case "$BUMP" in
+  patch|minor|major) NEXT_VERSION=$(bump_version "$LATEST_VERSION" "$BUMP") ;;
+  *)                 NEXT_VERSION="$BUMP" ;;
+esac
+
+NEXT_TAG="v${NEXT_VERSION}"
+
+echo ""
+echo -e "${BOLD}  Release Plan${NC}"
+echo -e "  ─────────────────────────────"
+echo -e "  Current tag:  ${YELLOW}${LATEST_TAG}${NC}"
+echo -e "  Next version: ${GREEN}${NEXT_TAG}${NC}"
+echo -e "  Dry run:      ${DRY_RUN}"
+echo ""
+
+# ── Preview changelog ───────────────────────────────────────────────
+info "Generating changelog for ${NEXT_TAG}..."
+CHANGELOG_PREVIEW=$(git-cliff --tag "$NEXT_TAG" --unreleased --strip header)
+
+if [ -z "$CHANGELOG_PREVIEW" ]; then
+  die "No conventional commits found since ${LATEST_TAG}. Nothing to release."
+fi
+
+echo -e "${BOLD}  Changes in ${NEXT_TAG}:${NC}"
+echo "$CHANGELOG_PREVIEW" | sed 's/^/  /'
+echo ""
+
+# ── Dry run stops here ─────────────────────────────────────────────
+if [ "$DRY_RUN" = true ]; then
+  ok "Dry run complete. No changes made."
+  exit 0
+fi
+
+# ── Confirm ─────────────────────────────────────────────────────────
+echo -ne "${YELLOW}Proceed with release ${NEXT_TAG}? [y/N]${NC} "
+read -r CONFIRM
+[[ "$CONFIRM" =~ ^[Yy]$ ]] || { info "Aborted."; exit 0; }
+
+# ── Update version.go ──────────────────────────────────────────────
+info "Updating ${VERSION_FILE}..."
+sed -i "s/var Version = \".*\"/var Version = \"${NEXT_VERSION}\"/" "$VERSION_FILE"
+ok "Version set to ${NEXT_VERSION}"
+
+# ── Update CHANGELOG.md ────────────────────────────────────────────
+info "Updating ${CHANGELOG_FILE}..."
+git-cliff --tag "$NEXT_TAG" --output "$CHANGELOG_FILE"
+ok "Changelog updated"
+
+# ── Commit and tag ──────────────────────────────────────────────────
+info "Creating release commit..."
+git add "$VERSION_FILE" "$CHANGELOG_FILE"
+git commit -m "chore(release): ${NEXT_VERSION}
+
+- Bump version to ${NEXT_VERSION}
+- Update CHANGELOG.md"
+
+info "Creating annotated tag ${NEXT_TAG}..."
+git tag -a "$NEXT_TAG" -m "Release ${NEXT_TAG}"
+
+echo ""
+ok "Release ${NEXT_TAG} created successfully!"
+echo ""
+echo -e "  ${BOLD}Next steps:${NC}"
+echo -e "  Push to trigger CI release pipeline:"
+echo ""
+echo -e "    ${CYAN}git push origin main --follow-tags${NC}"
+echo ""
diff --git a/scripts/ship.sh b/scripts/ship.sh
new file mode 100755
index 0000000..d81fd6f
--- /dev/null
+++ b/scripts/ship.sh
@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+#
+# ship.sh — End-to-end CLI release pipeline.
+#
+# Standalone backup for when GitHub Actions is unavailable (org shadow-ban,
+# CI outage, etc). Mirrors what release.yml + docker job in CI would do.
+#
+# Pre-requisites:
+#   - scripts/release.sh already ran → version.go bumped + tag created locally
+#   - SENTRY_DSN exported (Sentry disabled in build if missing)
+#   - docker logged in to docker.io as the org user
+#   - SSH key for Hetzner publishing (see publish-cli-release.sh)
+#
+# Pipeline:
+#   1. Sanity: clean tree, tag at HEAD, version.go matches
+#   2. goreleaser build (skip GH publish — produces dist/*)
+#   3. Rsync to Hetzner via web/scripts/publish-cli-release.sh
+#   4. Multi-arch Docker build + push (amd64 + arm64) to Docker Hub
+#   5. Smoke checks (torrentclaw.com/version + docker run image version)
+#   6. Prune Forgejo releases older than FORGEJO_PRUNE_DAYS (default 90)
+#   7. Optional `git push --follow-tags`
+#
+# Usage:
+#   scripts/ship.sh                  Detect version from internal/cmd/version.go
+#   scripts/ship.sh 0.9.12           Explicit version
+#   scripts/ship.sh --dry-run        Preview steps, no side effects
+#   scripts/ship.sh --push 0.9.12    Also git-push tag to GH afterwards
+#
+# Env knobs:
+#   SENTRY_DSN              telemetry DSN injected at build time
+#   RELEASE_SIGNING_PUBKEY  ed25519 pubkey (base64) for self-update signature check
+#   DOCKER_IMAGE            default torrentclaw/unarr
+#   PUBLISH_SCRIPT          default ../torrentclaw-web/scripts/publish-cli-release.sh
+#   SKIP_DOCKER=1           skip Docker build/push
+#   SKIP_HETZNER=1          skip Hetzner publish
+#   SKIP_SMOKE=1            skip smoke checks
+#   SKIP_FORGEJO_PRUNE=1    skip Forgejo retention prune
+#   FORGEJO_TOKEN           PAT with write:repository for prune (no token = skip + warn)
+#   FORGEJO_PRUNE_DAYS      retention window, default 90 days
+#   FORGEJO_REPO            default torrentclaw/unarr
+#
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_DIR"
+
+DOCKER_IMAGE="${DOCKER_IMAGE:-torrentclaw/unarr}"
+PUBLISH_SCRIPT="${PUBLISH_SCRIPT:-$REPO_DIR/../torrentclaw-web/scripts/publish-cli-release.sh}"
+SKIP_DOCKER="${SKIP_DOCKER:-0}"
+SKIP_HETZNER="${SKIP_HETZNER:-0}"
+SKIP_SMOKE="${SKIP_SMOKE:-0}"
+SKIP_FORGEJO_PRUNE="${SKIP_FORGEJO_PRUNE:-0}"
+FORGEJO_PRUNE_DAYS="${FORGEJO_PRUNE_DAYS:-90}"
+FORGEJO_REPO="${FORGEJO_REPO:-torrentclaw/unarr}"
+FORGEJO_BASE="${FORGEJO_BASE:-https://git.torrentclaw.com}"
+
+DRY_RUN=false
+PUSH_TAG=false
+VERSION=""
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; BOLD='\033[1m'; NC='\033[0m'
+info()  { echo -e "${CYAN}▸${NC} $*"; }
+ok()    { echo -e "${GREEN}✓${NC} $*"; }
+warn()  { echo -e "${YELLOW}⚠${NC} $*"; }
+die()   { echo -e "${RED}✗${NC} $*" >&2; exit 1; }
+
+for a in "$@"; do
+  case "$a" in
+    --dry-run) DRY_RUN=true ;;
+    --push)    PUSH_TAG=true ;;
+    -h|--help)
+      sed -n '2,/^set /p' "$0" | sed 's/^#\s\?//;$d'
+      exit 0 ;;
+    [0-9]*)    VERSION="$a" ;;
+    *)         die "unknown arg: $a (use --help)" ;;
+  esac
+done
+
+read_version_go() {
+  grep 'var Version' internal/cmd/version.go | sed 's/.*"\(.*\)".*/\1/'
+}
+
+REPO_VERSION="$(read_version_go)"
+[ -z "$VERSION" ] && VERSION="$REPO_VERSION"
+[ -n "$VERSION" ] || die "cannot detect version (pass explicit X.Y.Z)"
+TAG="v$VERSION"
+MINOR="${VERSION%.*}"
+
+echo ""
+echo -e "  ${BOLD}Ship Plan${NC}"
+echo -e "  ─────────────────────────────"
+echo -e "  Version:        ${GREEN}$TAG${NC}"
+echo -e "  Docker image:   $DOCKER_IMAGE:{$VERSION,$MINOR,latest}"
+echo -e "  Skip Hetzner:   $SKIP_HETZNER"
+echo -e "  Skip Docker:    $SKIP_DOCKER"
+echo -e "  Push to GH:     $PUSH_TAG"
+echo -e "  Dry run:        $DRY_RUN"
+echo ""
+
+# Sanity
+[ "$REPO_VERSION" = "$VERSION" ] || die "version.go=$REPO_VERSION ≠ requested $VERSION (bump with make release-* first)"
+
+if [ "$DRY_RUN" = false ]; then
+  [ -z "$(git status --porcelain)" ] || die "working tree dirty"
+  git rev-parse "$TAG" >/dev/null 2>&1 || die "tag $TAG missing — run scripts/release.sh first"
+
+  HEAD_SHA="$(git rev-parse HEAD)"
+  TAG_SHA="$(git rev-parse "$TAG^{commit}")"
+  [ "$HEAD_SHA" = "$TAG_SHA" ] || die "HEAD ($HEAD_SHA) ≠ tag commit ($TAG_SHA) — checkout $TAG first"
+
+  command -v goreleaser >/dev/null || die "goreleaser not installed"
+  [ "$SKIP_DOCKER" = "1" ] || command -v docker >/dev/null || die "docker not installed"
+  [ "$SKIP_HETZNER" = "1" ] || [ -x "$PUBLISH_SCRIPT" ] || die "publish script missing or not executable: $PUBLISH_SCRIPT"
+
+  if [ -z "${SENTRY_DSN:-}" ]; then
+    warn "SENTRY_DSN unset — built binaries will have Sentry disabled"
+  fi
+fi
+
+if [ "$DRY_RUN" = true ]; then
+  ok "Dry run complete — no changes made"
+  exit 0
+fi
+
+# 1. Build
+info "goreleaser build ($TAG)"
+SENTRY_DSN="${SENTRY_DSN:-}" RELEASE_SIGNING_PUBKEY="${RELEASE_SIGNING_PUBKEY:-}" \
+  goreleaser release --clean --skip=publish
+ok "dist/ ready"
+
+# 2. Hetzner
+if [ "$SKIP_HETZNER" != "1" ]; then
+  info "publishing to Hetzner releases volume"
+  "$PUBLISH_SCRIPT" "$VERSION"
+  ok "Hetzner version.txt flipped to $VERSION"
+fi
+
+# 3. Docker
+if [ "$SKIP_DOCKER" != "1" ]; then
+  info "docker buildx multi-arch push ($DOCKER_IMAGE:$VERSION, :$MINOR, :latest)"
+  docker buildx build \
+    --platform linux/amd64,linux/arm64 \
+    --build-arg VERSION="$TAG" \
+    -t "$DOCKER_IMAGE:$VERSION" \
+    -t "$DOCKER_IMAGE:$MINOR" \
+    -t "$DOCKER_IMAGE:latest" \
+    --push .
+  ok "Docker Hub: $DOCKER_IMAGE:{$VERSION,$MINOR,latest}"
+fi
+
+# 4. Smoke
+if [ "$SKIP_SMOKE" != "1" ]; then
+  info "smoke checks"
+  if [ "$SKIP_HETZNER" != "1" ]; then
+    LIVE_VERSION="$(curl -fsSL https://torrentclaw.com/version 2>/dev/null | tr -d '[:space:]' || echo '')"
+    if [ "$LIVE_VERSION" = "$VERSION" ]; then
+      ok "torrentclaw.com/version = $LIVE_VERSION"
+    else
+      warn "torrentclaw.com/version = '$LIVE_VERSION' (expected $VERSION)"
+    fi
+  fi
+
+  if [ "$SKIP_DOCKER" != "1" ]; then
+    DOCKER_VERSION="$(docker run --rm "$DOCKER_IMAGE:$VERSION" version 2>/dev/null | grep -oE 'v[0-9.]+' | head -1)"
+    if [ "$DOCKER_VERSION" = "$TAG" ]; then
+      ok "docker image $DOCKER_IMAGE:$VERSION reports $DOCKER_VERSION"
+    else
+      warn "docker image reports '$DOCKER_VERSION' (expected $TAG)"
+    fi
+  fi
+fi
+
+# 6. Forgejo retention prune
+if [ "$SKIP_FORGEJO_PRUNE" != "1" ]; then
+  if [ -z "${FORGEJO_TOKEN:-}" ]; then
+    warn "FORGEJO_TOKEN not set — skipping Forgejo prune (set it to enable >${FORGEJO_PRUNE_DAYS}-day cleanup)"
+  else
+    info "pruning Forgejo releases older than $FORGEJO_PRUNE_DAYS days"
+    FORGEJO_API="$FORGEJO_BASE/api/v1/repos/$FORGEJO_REPO/releases"
+    RELEASES_JSON="$(curl -fsSL -H "Authorization: token $FORGEJO_TOKEN" "$FORGEJO_API?limit=50" || echo '[]')"
+    PRUNE_IDS="$(echo "$RELEASES_JSON" | python3 -c "
+import json, sys
+from datetime import datetime, timedelta, timezone
+days = int('${FORGEJO_PRUNE_DAYS}')
+cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+for r in json.load(sys.stdin):
+    created = datetime.fromisoformat(r['created_at'].replace('Z', '+00:00'))
+    if created < cutoff:
+        print(f\"{r['id']}\t{r['tag_name']}\t{r['created_at']}\")
+" 2>/dev/null || true)"
+    DELETED=0
+    FAILED=0
+    if [ -n "$PRUNE_IDS" ]; then
+      while IFS=$'\t' read -r REL_ID REL_TAG REL_CREATED; do
+        [ -z "$REL_ID" ] && continue
+        CODE="$(curl -s -o /dev/null -w '%{http_code}' -X DELETE -H "Authorization: token $FORGEJO_TOKEN" "$FORGEJO_API/$REL_ID")"
+        if [ "$CODE" = "204" ]; then
+          echo "    deleted $REL_TAG (created $REL_CREATED)"
+          DELETED=$((DELETED + 1))
+        else
+          warn "    failed to delete $REL_TAG (id=$REL_ID, http=$CODE)"
+          FAILED=$((FAILED + 1))
+        fi
+      done <<< "$PRUNE_IDS"
+    fi
+    if [ "$FAILED" -gt 0 ]; then
+      warn "Forgejo prune: $DELETED removed, $FAILED failed"
+    else
+      ok "Forgejo prune: $DELETED release(s) removed (>${FORGEJO_PRUNE_DAYS} days old)"
+    fi
+  fi
+fi
+
+# 7. Optional push
+if [ "$PUSH_TAG" = true ]; then
+  info "git push origin main --follow-tags"
+  git push origin main --follow-tags
+  ok "tag $TAG pushed to GitHub"
+fi
+
+echo ""
+ok "${BOLD}$TAG shipped${NC}"
diff --git a/scripts/sign-checksums/main.go b/scripts/sign-checksums/main.go
new file mode 100644
index 0000000..0f95f05
--- /dev/null
+++ b/scripts/sign-checksums/main.go
@@ -0,0 +1,60 @@
+// sign-checksums signs the dist/checksums.txt file with an ed25519 private
+// key and writes the base64-encoded signature to the path given by -out.
+//
+// Usage (from release workflow):
+//
+//	go run ./scripts/sign-checksums \
+//	    -key "$RELEASE_SIGNING_KEY" \
+//	    -in  dist/checksums.txt \
+//	    -out dist/checksums.txt.sig
+//
+// The companion CLI verifier (internal/upgrade/signature.go) requires the
+// signature to be base64 text, so emitting base64 + trailing newline makes
+// the artifact safe to inspect with `cat` / the GitHub release UI.
+package main
+
+import (
+	"crypto/ed25519"
+	"encoding/base64"
+	"flag"
+	"fmt"
+	"os"
+)
+
+func main() {
+	keyB64 := flag.String("key", "", "base64-encoded ed25519 private key (PrivateKeySize = 64 bytes)")
+	in := flag.String("in", "", "path to file to sign")
+	out := flag.String("out", "", "path to write the base64-encoded signature")
+	flag.Parse()
+
+	if *keyB64 == "" || *in == "" || *out == "" {
+		fmt.Fprintln(os.Stderr, "usage: sign-checksums -key <base64> -in <path> -out <path>")
+		os.Exit(2)
+	}
+
+	keyBytes, err := base64.StdEncoding.DecodeString(*keyB64)
+	if err != nil {
+		fail("decode key: %v", err)
+	}
+	if len(keyBytes) != ed25519.PrivateKeySize {
+		fail("private key size %d, expected %d", len(keyBytes), ed25519.PrivateKeySize)
+	}
+	priv := ed25519.PrivateKey(keyBytes)
+
+	content, err := os.ReadFile(*in)
+	if err != nil {
+		fail("read input: %v", err)
+	}
+
+	sig := ed25519.Sign(priv, content)
+	encoded := base64.StdEncoding.EncodeToString(sig) + "\n"
+	if err := os.WriteFile(*out, []byte(encoded), 0o644); err != nil {
+		fail("write signature: %v", err)
+	}
+	fmt.Printf("Signed %s (%d bytes) → %s\n", *in, len(content), *out)
+}
+
+func fail(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, format+"\n", args...)
+	os.Exit(1)
+}