Deploy it, and fix the six things installation found

Both units are installed and running, 10 of 119 channels approved, 251 episodes
live in Jellyfin with verified DirectPlay. 345 tests. Six problems surfaced that no
test could have, and two of them were mine in the deploy scripts.

deploy.sh had a circular dependency with bootstrap.sh: deploy started the units and
told the operator to run bootstrap, but bootstrap refused to run until the state
directory existed, which only deploy creates. The units started against a
non-existent venv, failed 203/EXEC and restart-looped 17 and 21 times. deploy.sh now
creates the directory, calls bootstrap itself through runuser so the venv is not left
root-owned, and refuses to start units when the venv is still missing.

Deno was absent, and `doctor` is the only reason we know. It is mandatory rather than
nice-to-have — without a JS runtime yt-dlp cannot solve the n challenge, which
youtube-automate measured on this machine as 22 formats instead of 29 plus
throttling. Nothing else would have complained; playback would just have quietly
degraded. bootstrap.sh now installs it and asserts yt-dlp reports it.

Episodes had no synopsis at all, because materialise passed plot=None while both
sources hand us descriptions for free. Now plumbed through from RSS
(media:group/media:description) and from videos.list, which carries
snippet.description in the call already being made for durations — so the ~40% of
episodes older than RSS reaches get one too. That needed a schema v2 migration; v1
was left exactly as shipped so a fresh install and a migrated one are identical, and
a test asserts it.

`materialise --all` — the documented recovery from a Jellyfin metadata wipe — was
itself creating duplicates. Episode numbers were re-derived each run, and
next_episode() excludes the row being numbered, so re-materialising a day's videos in
a different order renumbered them and orphaned the old files. One run left 102
orphaned NFOs against 251 episodes. An episode number is now permanent once assigned,
and a video whose rel_path changes has its old files removed first. Running it twice
is now a no-op.

Two Jellyfin behaviours worth having in writing. It ignores <runtime> and
<durationinseconds> for episodes while reading the rest of the NFO happily, so a
.strm shows no duration until first played — not fixable without probing, which is
the one thing this design exists to avoid. And a plain /Library/Refresh does not
reliably re-read a rewritten NFO: after rewriting all 251, fifty kept their old empty
metadata. The fix is metadataRefreshMode=Default with replaceAllMetadata=false, which
took plots from 201 to 251 while the proxy served zero requests. §5's prohibition on
replaceAllMetadata=true still stands — that one probes. Exposed as
`ytstream refresh-metadata` and run automatically after `materialise --all`.

The measurement §5 has been waiting for: a full Jellyfin scan of 251 .strm files
took ~119 s, about 8 minutes per 1,000 episodes, and made zero media probes. That
last number is the fact the whole design rests on, now confirmed at scale on the real
library rather than on seven PoC files.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

deploy/bootstrap.sh

@@ -1,5 +1,9 @@
 #!/bin/bash
-# Everything that does NOT need root. Run as susan, before deploy.sh.
+# Everything that does NOT need root: the venv, yt-dlp, the POT container, the
+# database.
+#
+# Normally invoked for you by deploy.sh, which creates the state directory first.
+# Safe to run directly as susan afterwards — for instance to rebuild the venv:
 #
 #     /opt/ytstream/deploy/bootstrap.sh
 set -euo pipefail
@@ -11,8 +15,12 @@ REPO=/opt/ytstream
 say() { printf '\n\033[1m==> %s\033[0m\n' "$1"; }
 
 if [[ ! -d $STATE ]]; then
-    echo "$STATE does not exist yet — run 'sudo $REPO/deploy/deploy.sh' first," >&2
-    echo "or create it with: sudo install -d -o susan -g automation -m 0770 $STATE" >&2
+    echo "$STATE does not exist. Run 'sudo $REPO/deploy/deploy.sh' — it creates the" >&2
+    echo "directory and then calls this script." >&2
+    exit 1
+fi
+if [[ ! -w $STATE ]]; then
+    echo "$STATE is not writable by $(id -un). Expected mode 0770 susan:automation." >&2
     exit 1
 fi
 
@@ -32,6 +40,40 @@ print("POT plugin:", "MISSING" if missing else "present")
 raise SystemExit(1 if missing else 0)
 PY
 
+say "Installing the Deno JS runtime"
+# MANDATORY, not optional. Without a JS runtime yt-dlp cannot solve the `n`
+# challenge, and youtube-automate measured the consequence on this machine: 22
+# formats instead of 29, and throttled downloads. yt-dlp finds it by PATH, and the
+# unit pins PATH to this venv's bin, so it has to live here rather than anywhere
+# more natural.
+if [[ -x $VENV/bin/deno ]]; then
+    echo "    already present: $("$VENV/bin/deno" --version | head -1)"
+elif [[ -x /var/lib/youtube-automate/venv/bin/deno ]]; then
+    # Same machine, same architecture, already verified working. Prefer it over a
+    # download while youtube-automate is still installed.
+    install -m 0755 /var/lib/youtube-automate/venv/bin/deno "$VENV/bin/deno"
+    echo "    copied from the youtube-automate venv: $("$VENV/bin/deno" --version | head -1)"
+else
+    tmp=$(mktemp -d)
+    curl -fsSL -o "$tmp/deno.zip" \
+        https://github.com/denoland/deno/releases/latest/download/deno-x86_64-unknown-linux-gnu.zip
+    unzip -q "$tmp/deno.zip" -d "$tmp"
+    install -m 0755 "$tmp/deno" "$VENV/bin/deno"
+    rm -rf "$tmp"
+    echo "    installed $("$VENV/bin/deno" --version | head -1)"
+fi
+
+say "Confirming yt-dlp can solve JS challenges"
+# All three lines must appear, per youtube-automate specs.md §3.
+if "$VENV/bin/yt-dlp" -v --simulate --no-warnings \
+        "https://www.youtube.com/watch?v=dQw4w9WgXcQ" 2>&1 \
+        | grep -q "JS runtimes: deno"; then
+    echo "    yt-dlp reports the deno runtime"
+else
+    echo "    WARNING: yt-dlp did not report a deno JS runtime — playback may be" >&2
+    echo "    throttled or missing formats. Check: ytstream doctor" >&2
+fi
+
 say "Starting the POT provider container if it is not already up"
 if ! curl -sf --max-time 5 http://127.0.0.1:4416/ping >/dev/null 2>&1; then
     docker run -d --name bgutil-provider --restart unless-stopped \
@@ -43,4 +85,4 @@ fi
 say "Initialising the database"
 "$VENV/bin/ytstream" status || true
 
-say "Done — now run 'sudo $REPO/deploy/deploy.sh'"
+say "Virtualenv ready at $VENV"

deploy/deploy.sh

@@ -6,14 +6,21 @@
 #
 #     sudo /opt/ytstream/deploy/deploy.sh
 #
-# Everything that does NOT need root — the venv, the database, the POT provider
-# container, subscriptions, the API key — is handled by `bootstrap.sh` and the
-# application itself. Run bootstrap.sh (as susan) first.
+# This is the only command needed. It creates the state directory, builds the venv
+# by calling bootstrap.sh as the service user, and only then installs and starts
+# the units.
+#
+# That ordering is not cosmetic. An earlier version installed the units first and
+# told the operator to run bootstrap.sh separately — but bootstrap.sh needs the
+# state directory, which only this script can create, so neither could go first.
+# The units started, failed 203/EXEC against a venv that did not exist yet, and
+# restart-looped until the venv appeared.
 set -euo pipefail
 
 REPO=/opt/ytstream
 STATE=/var/lib/ytstream
 VENV=$STATE/venv
+SERVICE_USER=susan
 HOSTNAME_=tube.jihakuz.xyz
 
 if [[ $EUID -ne 0 ]]; then
@@ -26,7 +33,23 @@ say() { printf '\n\033[1m==> %s\033[0m\n' "$1"; }
 say "Creating $STATE"
 # root-owned directory, group-writable by `automation` so susan's cron job and the
 # admin server can both write the database.
-install -d -o susan -g automation -m 0770 "$STATE"
+install -d -o "$SERVICE_USER" -g automation -m 0770 "$STATE"
+
+say "Building the virtualenv"
+if [[ -x $VENV/bin/ytstream ]]; then
+    echo "    already present at $VENV"
+else
+    # As the service user, so the venv is not left root-owned. Absolute path:
+    # runuser lives in /sbin, which is not always on the invoking PATH.
+    /sbin/runuser -u "$SERVICE_USER" -- bash "$REPO/deploy/bootstrap.sh"
+fi
+
+# Refuse to start units that cannot possibly work. Restart=always would otherwise
+# turn a missing venv into a restart loop in the journal.
+if [[ ! -x $VENV/bin/ytstream ]]; then
+    echo "The virtualenv was not built. Fix that, then re-run $0." >&2
+    exit 1
+fi
 
 say "Installing the /usr/local/bin shim"
 cat > /usr/local/bin/ytstream <<EOF