docs(jellyfin): record player-owned playback verdict

Record the isolated Jellyfin 12 live evidence and the server-plugin-only no-go. Remove the discovery snapshot invalidated by Jellyfin's actual playback call path, scope the guide cache to connection settings, and fail closed for dangling mirror sources. Refs #357 Co-Authored-By: OpenAI Codex <codex@openai.com>
fix(jellyfin): harden player-owned playback probe
2026-07-15 20:15:35 +02:00 · 2026-07-15 19:07:55 +02:00 · 2026-07-14 21:44:07 +02:00 · 2026-07-14 21:37:35 +02:00 · 2026-07-14 19:00:01 +00:00 · 2026-07-14 20:51:59 +02:00
711 changed files with 26569 additions and 40781 deletions
@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# ersatztv#303 H9 — docs/decisions.md is append-only. This blocks a commit / PR that DELETES or
+# MODIFIES an existing line of that file; pure INSERTIONS anywhere are always allowed (adding a new
+# entry inserts a TOC line near the top AND appends a block at the bottom — both are insertions, so
+# numstat reports 0 deleted lines). A genuine factual fix to a past entry is the one legitimate edit:
+# put the literal token [decisions-edit] in the commit message to override.
+#
+# Fail-open: any tooling trouble (unknown mode, non-numeric numstat, missing refs) -> allow. The point
+# is to catch the accidental rewrite-history case, never to wedge a legitimate commit.
+#
+# Assumes decisions.md ends with a trailing newline (it does; .editorconfig enforces it). If that final
+# newline were ever dropped, git would render the next append as a modify of the last line (deleted=1)
+# and this would false-block the append until the author adds [decisions-edit] — cheap and self-correcting.
+#
+# Modes:
+#   staged <msgfile>       pre-commit/commit-msg — staged diff vs HEAD; trailer read from <msgfile>
+#   range  <base> <head>   CI (PR) — merge-base diff base...head; trailer scanned across base..head msgs
+set -euo pipefail
+
+FILE="docs/decisions.md"
+mode="${1:-}"
+
+case "$mode" in
+  staged)
+    deleted=$(git diff --cached --numstat -- "$FILE" 2>/dev/null | awk '{print $2}' | head -1)
+    msg=$(cat "${2:-/dev/null}" 2>/dev/null || true)
+    ;;
+  range)
+    base="${2:-}"; head="${3:-}"
+    [ -n "$base" ] && [ -n "$head" ] || exit 0          # missing refs -> fail-open
+    deleted=$(git diff --numstat "$base...$head" -- "$FILE" 2>/dev/null | awk '{print $2}' | head -1)
+    msg=$(git log --format='%B' "$base..$head" 2>/dev/null || true)
+    ;;
+  *)
+    exit 0                                              # unknown mode -> fail-open
+    ;;
+esac
+
+# Empty (no change to the file) or '-' (binary) -> treat as 0 (fail-open / nothing to guard).
+deleted="${deleted:-0}"
+case "$deleted" in ''|*[!0-9]*) deleted=0 ;; esac
+[ "$deleted" -gt 0 ] || exit 0                          # pure insertion / no change -> allow
+
+# Explicit override for a documented factual fix.
+if printf '%s' "$msg" | grep -qiF '[decisions-edit]'; then
+  exit 0
+fi
+
+{
+  echo "decisions-guard (ersatztv#303 H9): docs/decisions.md is append-only — this change deletes/modifies ${deleted} existing line(s)."
+  echo "  Append new entries at the bottom (plus a TOC line in the Index); do not rewrite settled entries."
+  echo "  To fix a genuine factual error in a past entry, add the token [decisions-edit] to the commit message."
+} >&2
+exit 1
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# PostToolUse / Bash — after a successful `git worktree add`, stamp the new worktree with
+# this session's id (.claude-worktree-owner) so pretooluse-worktree-guard.sh (H7) can tell
+# a sibling worktree another session created apart from this session's own.
+# Fail-safe: any parse trouble → do nothing (the guard stays fail-open without a marker).
+set -euo pipefail
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null || true)
+cwd=$(printf '%s' "$input" | jq -r '.cwd // ""' 2>/dev/null || true)
+me=$(printf '%s' "$input" | jq -r '.session_id // ""' 2>/dev/null || true)
+
+printf '%s' "$cmd" | grep -qE 'git[[:space:]]+worktree[[:space:]]+add\b' || exit 0
+[ -z "$me" ] && exit 0
+[ -z "$cwd" ] && cwd="$PWD"
+
+# Extract the <path> arg of `git worktree add [flags] <path> [<commit-ish>]`.
+# Skip flags; skip the values of the value-taking flags (-b/-B/--reason). Worktree paths
+# in this repo have no spaces, so whitespace tokenization is safe.
+add_args=$(printf '%s' "$cmd" | sed -E 's/.*git[[:space:]]+worktree[[:space:]]+add[[:space:]]+//')
+path=""
+skip=0
+for tok in $add_args; do
+  if [ "$skip" = 1 ]; then skip=0; continue; fi
+  case "$tok" in
+    -b|-B|--reason) skip=1; continue ;;
+    --) continue ;;
+    -*) continue ;;
+    *) path=$(printf '%s' "$tok" | tr -d '"'"'"''); break ;;
+  esac
+done
+[ -z "$path" ] && exit 0
+case "$path" in /*) abs="$path" ;; *) abs="$cwd/$path" ;; esac
+[ -d "$abs" ] || exit 0
+# Don't clobber a marker a different session already planted.
+[ -f "$abs/.claude-worktree-owner" ] && exit 0
+printf '%s\n' "$me" > "$abs/.claude-worktree-owner" 2>/dev/null || true
+exit 0
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Husky pre-push backstop for ersatztv#303 H6 — the fast-forward-to-main path the Claude merge
+# hook (pretooluse-merge-consent.sh) can't see. Reads git's pre-push ref lines on stdin; for a push
+# to main it scans the pushed commits for a Gitea close-keyword (`fixes #N`), and if the linked
+# issue's "## Done-when" checklist still has unticked boxes it BLOCKS the push.
+#
+# A git hook has no interactive "ask", so this is deliberately fail-OPEN: it only blocks when it can
+# positively prove an unticked box (creds present, issue fetched, non-docs change). No creds, Gitea
+# unreachable, docs-only diff, or no linked issue -> allow (a loud warning at most). The authoritative
+# gate is the merge hook; this just catches a direct `git push origin main`.
+#
+# Auth (never committed): ETV_GITEA_TOKEN or ETV_GITEA_BASICAUTH; ETV_GITEA_URL overrides the base.
+set -euo pipefail
+
+# git passes "<localref> <localsha> <remoteref> <remotesha>" lines on stdin.
+refs=$(cat || true)
+printf '%s\n' "$refs" | grep -q 'refs/heads/main' || exit 0   # only gate pushes to main
+
+base_url="${ETV_GITEA_URL:-http://192.168.1.95:3000}/api/v1"
+if [ -z "${ETV_GITEA_TOKEN:-}" ] && [ -z "${ETV_GITEA_BASICAUTH:-}" ]; then
+  exit 0   # can't verify -> fail-open (the merge hook is the real gate)
+fi
+gq() {
+  if [ -n "${ETV_GITEA_TOKEN:-}" ]; then
+    curl -sf -H "Authorization: token $ETV_GITEA_TOKEN" "$base_url/$1" 2>/dev/null || true
+  else
+    curl -sf -u "$ETV_GITEA_BASICAUTH" "$base_url/$1" 2>/dev/null || true
+  fi
+}
+
+zero=0000000000000000000000000000000000000000
+blocked=""
+while read -r localref localsha remoteref remotesha; do
+  [ "$remoteref" = "refs/heads/main" ] || continue
+  [ "$localsha" = "$zero" ] && continue   # branch deletion
+  # Commit range being pushed. New branch (remotesha all-zero) -> just the tip, don't rescan history.
+  if [ "$remotesha" = "$zero" ]; then range="$localsha -1"; else range="$remotesha..$localsha"; fi
+  msgs=$(git log --format='%B' $range 2>/dev/null || true)
+  issues=$(printf '%s' "$msgs" | grep -ioE '(close[sd]?|fix(e[sd])?|resolve[sd]?) +#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+  [ -n "$issues" ] || continue
+
+  # Docs-only exemption over the pushed range.
+  changed=$(git diff --name-only $range 2>/dev/null || true)
+  if [ -n "$changed" ] && ! printf '%s\n' "$changed" | grep -qvE '^(docs/|\.claude/|\.husky/|\.gitea/|.*\.md$)'; then
+    continue
+  fi
+
+  for n in $issues; do
+    ibody=$(gq "repos/timothy/ersatztv/issues/$n" | jq -r '.body // ""' 2>/dev/null || true)
+    [ -n "$ibody" ] || continue   # can't fetch -> fail-open
+    unchecked=$(printf '%s\n' "$ibody" | awk '
+      /^##[[:space:]]+[Dd]one-when/ {grab=1; next}
+      grab && /^##[[:space:]]/ {grab=0}
+      grab {print}' | grep -cE '^[[:space:]]*[-*][[:space:]]+\[[[:space:]]\]' || true)
+    if [ "${unchecked:-0}" -gt 0 ]; then
+      blocked="${blocked}  - issue #$n has $unchecked unticked ## Done-when box(es)\n"
+    fi
+  done
+done <<EOF
+$refs
+EOF
+
+if [ -n "$blocked" ]; then
+  printf 'husky - H6 merge-consent (ersatztv#303): push to main BLOCKED\n' >&2
+  printf '%b' "$blocked" >&2
+  printf 'Finish/tick every Done-when criterion (incl. adversarial review) first, or push a docs-only change.\n' >&2
+  exit 1
+fi
+exit 0
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# H11 (ersatztv#311) — refuse to push a branch that is BEHIND origin/main: rebase first, do NOT
+# merge main in. A merge commit drags in files you never touched (e.g. the ~2500 legacy-BOM .cs),
+# which then trips the pre-commit `dotnet format` hook on code that isn't yours (the #309 session).
+# Rebasing keeps your diff to exactly what you changed.
+#
+# Fail-OPEN on anything we can't decide (a git pre-push hook has no "ask"): not a git repo,
+# offline / fetch fails, no origin/main, HEAD unresolved -> allow the push. The only hard block is
+# a positively-proven "behind origin/main". Deliberate exception: ETV_SKIP_REBASE_CHECK=1.
+set -uo pipefail
+
+[ "${ETV_SKIP_REBASE_CHECK:-}" = "1" ] && exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+# Best-effort fetch of the latest main; offline / no network -> don't block.
+git fetch origin main --quiet 2>/dev/null || exit 0
+git rev-parse --verify --quiet origin/main >/dev/null 2>&1 || exit 0
+
+# Pushing main itself, or a branch already rebased on top of it, means origin/main is an ANCESTOR
+# of HEAD -> nothing to rebase, allow.
+if git merge-base --is-ancestor origin/main HEAD 2>/dev/null; then
+  exit 0
+fi
+
+behind=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo '?')
+branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo HEAD)
+echo "husky - push blocked (H11): '$branch' is behind origin/main by $behind commit(s)."
+echo "  Rebase before pushing — do NOT merge main in (a merge drags in files you didn't touch,"
+echo "  e.g. legacy-BOM .cs, and trips the format hook on code that isn't yours):"
+echo "    git fetch origin main && git rebase origin/main"
+echo "  Deliberate exception: ETV_SKIP_REBASE_CHECK=1 git push"
+exit 1
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# PreToolUse / Agent (subagent spawn) — RAM-gate the fan-out.
+# The historic 8-9-way crash was RAM starvation, not CPU load; gate on FREE RAM.
+# Fail-open: if memory_pressure is unavailable/unparsable → allow.
+set -euo pipefail
+free=$(memory_pressure -Q 2>/dev/null | grep -oE 'free percentage: [0-9]+' | grep -oE '[0-9]+' || true)
+[ -z "${free:-}" ] && exit 0
+
+if [ "$free" -lt 10 ]; then
+  jq -n --arg f "$free" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:("Free RAM \($f)% (<10%): do NOT spawn more agents — the historic crash was RAM starvation from an 8-9-way fan-out. Wait for memory_pressure -Q to recover, then retry.")}}'
+elif [ "$free" -lt 20 ]; then
+  jq -n --arg f "$free" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"ask",permissionDecisionReason:("Free RAM \($f)% (<20%): near the fan-out ceiling. Confirm before adding another build/implementer agent (read-only recon agents are cheap).")}}'
+fi
+exit 0
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# PreToolUse / Bash — deny commands that violate a HARD RULE.
+# Fail-open: any parse trouble → allow (exit 0 with no output).
+set -euo pipefail
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null || true)
+
+# Match an actual env ASSIGNMENT in COMMAND POSITION — line start or right after a shell
+# separator (; && || | ( ), optionally `export`. This deliberately does NOT match the name
+# when it sits inside a quoted string (echo, git commit -m, jq test payloads), where the
+# preceding char is a quote/word, not a separator — so mentions of the rule never false-trip.
+if printf '%s' "$cmd" | grep -qE '(^|[;&|(]|&&|\|\|)[[:space:]]*(export[[:space:]]+)?ETV_UPDATE_GOLDENS='; then
+  jq -n '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:"Blocked: ETV_UPDATE_GOLDENS regenerates golden-test baselines — HARD RULE (docs/handoffs lore); never set it in a session. Update a golden deliberately and reviewed, not via a guarded run."}}'
+fi
+exit 0
@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# PreToolUse / mcp__gitea__pull_request_write — derive merge consent from STATE instead of
+# trusting the agent's judgment (ersatztv#303 H6 + H10). A PR merge is the one irreversible op; allow it
+# only when ALL are true:
+#   (a) the PR's CI combined status is green, AND
+#   (b) every checkbox in the linked issue's "## Done-when" section is ticked, AND
+#   (c) a review-verdict comment on the PR references the CURRENT head sha (H10) — proving the
+#       LATEST commit was reviewed, not a stale earlier diff (the ersatztv#242 failure mode:
+#       "re-review the fix commit, not just the initial PR diff").
+# The "## Done-when" issue-body checklist is the convention (docs/decisions.md, CLAUDE.md Task
+# Completion Protocol). One box is "adversarial review passed"; the others are per-issue.
+# The H10 review-verdict convention: after reviewing a PR (or its latest fix commit), post a PR
+# comment carrying a line `Review-verdict: <MERGEABLE|APPROVED|BLOCKED|NOT-MERGEABLE> @ <head-sha>`.
+#
+# Decision policy — a CONSENT gate, so it does NOT fail silently open:
+#   - state derivable and satisfied                -> grant (auto-approve: permissionDecision "allow",
+#                                                            so NO redundant permission prompt fires —
+#                                                            the derived state IS the consent, ersatztv#314)
+#   - state derivable and NOT satisfied            -> deny  (actionable reason)
+#   - state NOT derivable (no creds, Gitea down,
+#     no linked issue, no Done-when section)       -> ask   (surface to a human/session judgment)
+# Only a real merge is gated; every other pull_request_write method is passed through UNTOUCHED
+# (bare exit 0 → normal permissioning still applies), NOT auto-granted.
+#
+# WHY "grant" (not a bare exit 0) on the satisfied path (ersatztv#314 root cause): a PreToolUse hook
+# that exits 0 with no JSON does NOT auto-approve — it only declines to block, so control falls through
+# to the normal permission system and the raw MCP prompt still fires. The gate therefore only ever
+# ADDED a deny/ask net; it never REMOVED the baseline prompt on the happy path, so a satisfied merge
+# was confirmed twice (conversationally + a redundant mechanical prompt). Emitting permissionDecision
+# "allow" is what actually suppresses the prompt — "derive consent from state" made real.
+#
+# Gitea auth from env (never committed): ETV_GITEA_TOKEN (a token) OR ETV_GITEA_BASICAUTH (user:pass).
+# ETV_GITEA_URL overrides the base (default: the LAN instance; a LAN address, not a secret).
+set -euo pipefail
+input=$(cat)
+
+decide() { # $1=grant|allow|deny|ask  $2=reason
+  case "$1" in
+    # grant = the gate is SATISFIED → auto-approve so no redundant permission prompt fires.
+    grant) jq -n --arg r "$2" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"allow",permissionDecisionReason:$r}}'; exit 0 ;;
+    # allow = not our concern (non-merge method) → pass through untouched; normal permissioning applies.
+    allow) exit 0 ;;
+    deny)  jq -n --arg r "$2" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}'; exit 0 ;;
+    ask)   jq -n --arg r "$2" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"ask",permissionDecisionReason:$r}}'; exit 0 ;;
+  esac
+}
+
+method=$(printf '%s' "$input" | jq -r '.tool_input.method // ""' 2>/dev/null || true)
+[ "$method" = "merge" ] || decide allow ""
+
+owner=$(printf '%s' "$input" | jq -r '.tool_input.owner // ""' 2>/dev/null || true)
+repo=$(printf '%s'  "$input" | jq -r '.tool_input.repo  // ""' 2>/dev/null || true)
+pr=$(printf '%s'    "$input" | jq -r '.tool_input.pull_number // ""' 2>/dev/null || true)
+mwcs=$(printf '%s'  "$input" | jq -r '.tool_input.merge_when_checks_succeed // false' 2>/dev/null || true)
+[ -n "$owner" ] && [ -n "$repo" ] && [ -n "$pr" ] || decide ask "H6 merge gate: could not read owner/repo/pull_number from the merge call; confirm manually that CI is green and the issue's Done-when boxes are ticked."
+
+base_url="${ETV_GITEA_URL:-http://192.168.1.95:3000}/api/v1"
+# curl wrapper carrying whichever auth is configured; empty output on any failure.
+gq() {
+  local path="$1"
+  if [ -n "${ETV_GITEA_TOKEN:-}" ]; then
+    curl -sf -H "Authorization: token $ETV_GITEA_TOKEN" "$base_url/$path" 2>/dev/null || true
+  elif [ -n "${ETV_GITEA_BASICAUTH:-}" ]; then
+    curl -sf -u "$ETV_GITEA_BASICAUTH" "$base_url/$path" 2>/dev/null || true
+  else
+    return 1
+  fi
+}
+if [ -z "${ETV_GITEA_TOKEN:-}" ] && [ -z "${ETV_GITEA_BASICAUTH:-}" ]; then
+  decide ask "H6 merge gate: no Gitea credentials in env (ETV_GITEA_TOKEN or ETV_GITEA_BASICAUTH), so CI/Done-when state can't be verified. Confirm manually that CI is green and the linked issue's Done-when boxes are all ticked, then approve."
+fi
+
+prjson=$(gq "repos/$owner/$repo/pulls/$pr")
+[ -n "$prjson" ] || decide ask "H6 merge gate: could not fetch PR #$pr from Gitea (unreachable or auth rejected). Verify CI-green + Done-when manually before merging."
+
+sha=$(printf '%s' "$prjson" | jq -r '.head.sha // ""' 2>/dev/null || true)
+body=$(printf '%s' "$prjson" | jq -r '.body // ""' 2>/dev/null || true)
+
+# --- Docs-only exemption: if every changed file is docs/process, skip the gate. ---
+files=$(gq "repos/$owner/$repo/pulls/$pr/files?limit=100" | jq -r '.[].filename // empty' 2>/dev/null || true)
+if [ -n "$files" ] && ! printf '%s\n' "$files" | grep -qvE '^(docs/|\.claude/|\.husky/|\.gitea/|.*\.md$)'; then
+  # Docs/process-only PR: the Done-when + review-verdict gate doesn't apply — but this exemption is a
+  # file-TYPE bypass, NOT the a+b+c "provably reviewed & ready" proof, so it does NOT auto-grant. It
+  # passes through to normal permissioning (one prompt). This deliberately keeps a human in the loop for
+  # process-control files (.claude/ / .gitea/ / .husky/ — the gate, CI, and git hooks themselves): a PR
+  # that weakens the gate must not silently self-merge (ersatztv#317 review nit). Only the satisfied
+  # merge path below auto-grants.
+  decide allow ""   # passthrough (exit 0 → normal prompt), NOT grant
+fi
+
+# --- Linked issue: Gitea auto-close keywords in the PR body. ---
+issues=$(printf '%s' "$body" | grep -ioE '(close[sd]?|fix(e[sd])?|resolve[sd]?) +#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+[ -n "$issues" ] || decide ask "H6 merge gate: PR #$pr has no linked issue (no 'fixes #N' / 'closes #N' in its body), so there is no Done-when checklist to derive consent from. Confirm the work is complete + reviewed, then approve."
+
+# --- (b) Done-when checkboxes: every linked issue must have an all-ticked section. ---
+for n in $issues; do
+  ibody=$(gq "repos/$owner/$repo/issues/$n" | jq -r '.body // ""' 2>/dev/null || true)
+  [ -n "$ibody" ] || decide ask "H6 merge gate: could not fetch linked issue #$n. Verify its Done-when checklist manually before merging."
+  # Slice the "## Done-when" section: from that header to the next "## " (or EOF).
+  section=$(printf '%s\n' "$ibody" | awk '
+    /^##[[:space:]]+[Dd]one-when/ {grab=1; next}
+    grab && /^##[[:space:]]/ {grab=0}
+    grab {print}')
+  if [ -z "$(printf '%s' "$section" | tr -d '[:space:]')" ]; then
+    decide ask "H6 merge gate: linked issue #$n has no '## Done-when' checklist section (the merge-consent convention — see CLAUDE.md Task Completion Protocol). Add one, or confirm completion manually and approve."
+  fi
+  unchecked=$(printf '%s\n' "$section" | grep -cE '^[[:space:]]*[-*][[:space:]]+\[[[:space:]]\]' || true)
+  if [ "${unchecked:-0}" -gt 0 ]; then
+    decide deny "H6 merge gate: BLOCKED — linked issue #$n has $unchecked unticked box(es) in its ## Done-when checklist. Finish (or explicitly tick) every completion criterion — including the adversarial-review box — before merging PR #$pr."
+  fi
+done
+
+# --- (a) CI combined status must be green (unless deferring to Gitea's own check-gate). ---
+if [ "$mwcs" != "true" ]; then
+  [ -n "$sha" ] || decide ask "H6 merge gate: could not resolve PR #$pr head sha to check CI. Verify CI is green before merging."
+  state=$(gq "repos/$owner/$repo/commits/$sha/status" | jq -r '.state // ""' 2>/dev/null || true)
+  case "$state" in
+    success) : ;;
+    "")      decide ask "H6 merge gate: could not read CI status for PR #$pr ($sha). Verify CI is green before merging." ;;
+    *)       decide deny "H6 merge gate: BLOCKED — PR #$pr CI status is '$state', not 'success'. Wait for a green build (or pass merge_when_checks_succeed to let Gitea gate it) before merging." ;;
+  esac
+fi
+
+# --- (c) Review-verdict freshness (ersatztv#303 H10): a review-verdict comment must reference the
+#     CURRENT head sha, so the latest commit is proven-reviewed (ersatztv#242: re-review the fix
+#     commit, not just the initial diff). Graceful adoption mirrors (b): a verdict comment that
+#     references head must be positive -> allow; one that exists only for an OLDER commit -> deny
+#     (the stale-review failure mode); NO verdict comment at all -> ask (convention not yet used).
+[ -n "$sha" ] || decide ask "H10 merge gate: could not resolve PR #$pr head sha to verify a review verdict. Confirm the review covered the latest commit before merging."
+short=${sha:0:7}
+comments=$(gq "repos/$owner/$repo/issues/$pr/comments?limit=100")
+if [ -z "$comments" ]; then
+  decide ask "H10 merge gate: could not fetch PR #$pr comments to verify a head-referencing review verdict ($short). Confirm the adversarial/Codex review covered the latest commit before merging."
+fi
+# Verdict lines across all comment bodies: a real verdict line STARTS with the marker (after optional
+# leading whitespace). Anchoring to line-start is deliberate — it rejects a comment that merely QUOTES
+# the positive template mid-sentence (an instruction "please post: Review-verdict: MERGEABLE @ <sha>",
+# or the gate's own suggestion text echoed back), which would otherwise self-approve the merge.
+verdicts=$(printf '%s' "$comments" | jq -r '.[].body // empty' 2>/dev/null | grep -iE '^[[:space:]]*review-verdict:' || true)
+if [ -z "$verdicts" ]; then
+  decide ask "H10 merge gate: no 'Review-verdict:' comment found on PR #$pr referencing head $short. Post the adversarial/Codex verdict (e.g. 'Review-verdict: MERGEABLE @ $short'), or confirm the review covered the latest commit and approve."
+fi
+# Classify each verdict line by the sha it references (its "@ <sha>" field) and its verdict word.
+# A line references the CURRENT head iff head BEGINS WITH that sha token AND the token is >=7 chars
+# (git short-sha prefix semantics) — NOT a loose substring test: an older sha that merely contains
+# the head prefix, or the head prefix appearing in an unrelated URL on the line, must NOT count
+# (adversarial false-opens). The verdict token must sit right after the marker on the same line.
+head_pos=0; head_neg=0; stale=0
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  # The sha the line references: the hex token in its "@ <sha>" field (>=7 chars), lowercased.
+  ref=$(printf '%s' "$line" | grep -ioE '@[[:space:]]*[0-9a-f]{7,40}' | head -1 \
+        | grep -oiE '[0-9a-f]{7,40}' | tr 'A-F' 'a-f' || true)
+  is_pos=0
+  # Positive iff the line's OWN leading verdict word (right after the line-start marker) is positive —
+  # anchored so a second, later `review-verdict: mergeable` substring on a BLOCKED line can't flip it.
+  if printf '%s' "$line" | grep -iqE '^[[:space:]]*review-verdict:[[:space:]]*(mergeable|approved|lgtm)'; then is_pos=1; fi
+  [ -z "$ref" ] && continue   # marker present but no @<sha> -> falls through to the final ask
+  case "$sha" in
+    "$ref"*) if [ "$is_pos" = 1 ]; then head_pos=1; else head_neg=1; fi ;;
+    *)       stale=1 ;;
+  esac
+done <<VERDICTS
+$verdicts
+VERDICTS
+
+# A negative verdict on head wins over a positive one (a later BLOCKED retracts an earlier MERGEABLE
+# on the SAME head; and if the head were fixed the sha would change, so this can't wrongly block).
+if [ "$head_neg" = 1 ]; then
+  decide deny "H10 merge gate: BLOCKED — a review verdict for the current head ($short) is negative (BLOCKED/NOT-MERGEABLE). Resolve the findings and post a fresh 'Review-verdict: MERGEABLE @ $short' before merging PR #$pr."
+fi
+if [ "$head_pos" = 1 ]; then
+  # (a) CI green + (b) all Done-when ticked + (c) positive verdict @ current head -> SATISFIED. Auto-grant.
+  decide grant "H6/H10 merge gate: satisfied — CI green, all Done-when boxes ticked, and a positive Review-verdict references the current head ($short). Auto-granted (no separate confirmation needed)."
+fi
+if [ "$stale" = 1 ]; then
+  decide deny "H10 merge gate: BLOCKED — a review-verdict comment references an older commit, not the current head ($short). The latest commit(s) are unreviewed (ersatztv#242: re-review the fix commit, not just the initial diff). Re-review the head and post 'Review-verdict: MERGEABLE @ $short'."
+fi
+# Marker(s) exist but reference no sha at all -> ask (don't mislabel as a stale older-commit review).
+decide ask "H10 merge gate: a 'Review-verdict:' comment on PR #$pr references no commit sha. Post one referencing the current head ($short) — e.g. 'Review-verdict: MERGEABLE @ $short' — or confirm the review covered the latest commit and approve."
+
+# All derivable and satisfied -> auto-grant (defensive: the head_pos branch above already exits here).
+decide grant "H6/H10 merge gate: satisfied — auto-granted."
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# PreToolUse / browser-navigate — deny opening download/stream endpoints in a tab
+# (they hang the MCP session; curl them instead). Fail-open on parse trouble.
+set -euo pipefail
+input=$(cat)
+url=$(printf '%s' "$input" | jq -r '.tool_input.url // ""' 2>/dev/null || true)
+
+if printf '%s' "$url" | grep -qE '/iptv/|\.m3u8|/artwork/|playback\.m3u8'; then
+  jq -n '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:"Blocked: do not open download/stream endpoints (/iptv, .m3u8, /artwork, playback.m3u8) in a browser tab — they stall the MCP session. curl them instead (docs/handoffs lore)."}}'
+fi
+exit 0
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# PreToolUse / Bash — deny `git commit`/`git merge` inside a sibling worktree that
+# a DIFFERENT session created (burned us twice — #289 path-leak, the plumbing-merge
+# workaround exists precisely because of this). Ownership is a `.claude-worktree-owner`
+# marker (session id) written at `git worktree add` time by posttooluse-worktree-marker.sh.
+#
+# Fail-open by design: no marker, unparsable input, or marker == this session → allow.
+# So the main tree (never marked) and pre-convention worktrees (no marker) are unaffected;
+# only a commit/merge into another session's marked worktree is blocked.
+set -euo pipefail
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null || true)
+cwd=$(printf '%s' "$input" | jq -r '.cwd // ""' 2>/dev/null || true)
+me=$(printf '%s' "$input" | jq -r '.session_id // ""' 2>/dev/null || true)
+
+# Only guard the state-mutating ops. Match `git commit`/`git merge` in command position
+# (line start or after a shell separator) so a quoted mention never false-trips.
+printf '%s' "$cmd" | grep -qE '(^|[;&|(]|&&|\|\|)[[:space:]]*git[[:space:]]+(-C[[:space:]]+[^[:space:]]+[[:space:]]+)?(commit|merge)\b' || exit 0
+
+[ -z "$cwd" ] && cwd="$PWD"
+
+# Determine the effective directory the git op runs in. Two common redirections in the
+# lore's usage move it off the session cwd: `git -C <path>` and a leading `cd <path> &&`.
+effdir="$cwd"
+cpath=$(printf '%s' "$cmd" | grep -oE 'git[[:space:]]+-C[[:space:]]+[^[:space:]&|;]+' | head -1 | sed -E 's/^git[[:space:]]+-C[[:space:]]+//' | tr -d '"'"'"'' || true)
+cdpath=$(printf '%s' "$cmd" | grep -oE '^[[:space:]]*cd[[:space:]]+[^[:space:]&|;]+' | head -1 | sed -E 's/^[[:space:]]*cd[[:space:]]+//' | tr -d '"'"'"'' || true)
+if [ -n "${cpath:-}" ]; then
+  effdir="$cpath"
+elif [ -n "${cdpath:-}" ]; then
+  effdir="$cdpath"
+fi
+# Resolve a relative effective dir against the session cwd.
+case "$effdir" in /*) : ;; *) effdir="$cwd/$effdir" ;; esac
+
+root=$(git -C "$effdir" rev-parse --show-toplevel 2>/dev/null || true)
+[ -z "$root" ] && exit 0
+marker="$root/.claude-worktree-owner"
+[ -f "$marker" ] || exit 0
+owner=$(tr -d '[:space:]' < "$marker" 2>/dev/null || true)
+[ -z "$owner" ] && exit 0
+[ "$owner" = "$me" ] && exit 0
+
+# Marker names a DIFFERENT session → deny.
+jq -n --arg o "$owner" --arg r "$root" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:("Blocked: worktree \($r) is owned by session \($o), not this one. Never commit/merge inside a sibling worktree another session created (#289 path-leak, plumbing-merge workaround). Commit from your own tree; if you genuinely own this worktree now, overwrite its .claude-worktree-owner marker with your session id.")}}'
+exit 0
@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/pretooluse-bash-guard.sh\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/pretooluse-worktree-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__plugin_playwright_playwright__browser_navigate|mcp__claude-in-chrome__navigate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/pretooluse-nav-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/pretooluse-agent-ram.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__gitea__pull_request_write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/pretooluse-merge-consent.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/posttooluse-worktree-marker.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -169,7 +169,12 @@ jobs:
      # service container above. MySql__ConnectionString maps to config key "MySql:ConnectionString".
      - name: MySql — model drift + apply all migrations to a fresh DB
        env:
-          MySql__ConnectionString: "Server=mysql;Port=3306;Database=ersatztv_migrations;Uid=root;Pwd=ersatztv;"
+          # DefaultCommandTimeout is raised from MySqlConnector's 30s default: replaying every
+          # migration to a fresh DB issues DDL commands that can exceed 30s when two migration jobs
+          # share a runner host (each spins its own mysql:8.4 service) and starve each other. That
+          # contention produced both "Command Timeout expired" and mid-replay connection drops
+          # (MySqlEndOfStreamException) — neither is a model problem. See #13 / #236.
+          MySql__ConnectionString: "Server=mysql;Port=3306;Database=ersatztv_migrations;Uid=root;Pwd=ersatztv;DefaultCommandTimeout=300;"
        run: |
          set -euo pipefail
          export PATH="$PATH:$HOME/.dotnet/tools"
@@ -178,8 +183,23 @@ jobs:
            --context TvContext --startup-project ErsatzTV --project ErsatzTV.Infrastructure.MySql -- --provider MySql
          echo "::endgroup::"
          echo "::group::MySql apply all migrations to a fresh DB"
-          dotnet ef database update --no-build --configuration Release \
-            --context TvContext --startup-project ErsatzTV --project ErsatzTV.Infrastructure.MySql -- --provider MySql
+          # Retry the apply: under concurrent-runner MySQL contention the server can drop the
+          # connection mid-replay. Each attempt resumes from __EFMigrationsHistory (EF wraps each
+          # migration in its own transaction, so an interrupted migration rolls back cleanly and the
+          # retry continues from the last committed one) — so this only papers over infra flakiness,
+          # never a real migration failure, which fails deterministically on every attempt.
+          attempt=1
+          max=3
+          until dotnet ef database update --no-build --configuration Release \
+            --context TvContext --startup-project ErsatzTV --project ErsatzTV.Infrastructure.MySql -- --provider MySql; do
+            if [ "$attempt" -ge "$max" ]; then
+              echo "MySql apply failed after ${max} attempts" >&2
+              exit 1
+            fi
+            echo "MySql apply attempt ${attempt} failed (likely runner MySQL contention); retrying in 15s..." >&2
+            attempt=$((attempt + 1))
+            sleep 15
+          done
          echo "::endgroup::"

  build:
@@ -341,3 +361,181 @@ jobs:
          else
            echo "Parity-doc reminder: nothing to flag."
          fi
+
+  # BLOCKING (ersatztv#303 H9): docs/decisions.md is an append-only log. Fails a PR that deletes or
+  # rewrites a settled entry (numstat reports >0 deleted lines) unless a commit in the range carries
+  # the [decisions-edit] override token for a documented factual fix. Same script the Husky commit-msg
+  # hook calls, so local and CI enforcement can't drift. Seconds-long git diff -> keep it off the build runners.
+  decisions-guard:
+    name: decisions.md append-only
+    runs-on: small
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Enforce append-only
+        run: |
+          base_ref="${{ github.base_ref }}"
+          git fetch --no-tags --depth=200 origin "$base_ref" || true
+          ./.claude/hooks/decisions-guard.sh range "origin/${base_ref}" HEAD
+      - name: Consolidation-floor reminder (non-blocking)
+        run: |
+          # Consolidation is primarily a release step; this is the between-releases floor. The metric is
+          # the file's LINE COUNT — the context an agent actually burns reading the log — not entry count.
+          # Floor 1800 keeps the whole log inside one default 2000-line Read (headroom for the reader's
+          # own overhead). Nudge (never fail) past it so append-only can't grow past what agents can read.
+          n=$(wc -l < docs/decisions.md | tr -d ' ')
+          echo "docs/decisions.md is ${n} lines (consolidation floor: 1800; one Read caps at 2000)."
+          if [ "${n:-0}" -gt 1800 ]; then
+            echo "::warning::docs/decisions.md is ${n} lines (>1800) — larger than agents can comfortably read in one pass. Do a consolidation pass (prune/merge superseded entries with [decisions-edit]); don't wait for the next release. See the decisions.md header."
+          fi
+
+  # BLOCKING (unlike docs-reminder): the mechanizable half of the "docs-update in the
+  # same PR" rule for the API contract (ersatztv#303 H4/H5). If a PR touches the API
+  # surface (ErsatzTV/Controllers/Api/** or ErsatzTV.Core/Api/**), the generated
+  # artifacts — v1.json (OpenAPI spec), v1.d.ts (SPA client), endpoint-index.md — MUST
+  # already be regenerated in the diff. We rebuild them from source and fail on any drift.
+  # Also covers the "regenerate artifacts after merging main into a PR branch" lore bullet.
+  #
+  # Path-gated INSIDE the job (not via top-level `if:`) so the check always reports a
+  # status on every PR and can be a required check without stalling API-free PRs: when no
+  # API path changed, the expensive steps skip and the job passes trivially.
+  api-docs:
+    name: API docs in sync (OpenAPI + endpoint index)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect API-surface changes
+        id: detect
+        run: |
+          base_ref="${{ github.base_ref }}"
+          git fetch --no-tags --depth=100 origin "$base_ref" || true
+          changed="$(git diff --name-only "origin/${base_ref}...HEAD" 2>/dev/null || true)"
+          echo "Changed files in this PR:"; printf '%s\n' "$changed"
+          if printf '%s\n' "$changed" | grep -Eq '^ErsatzTV/Controllers/Api/|^ErsatzTV\.Core/Api/'; then
+            echo "api_changed=true" >> "$GITHUB_OUTPUT"
+            echo "API surface changed -> will verify generated artifacts are in sync."
+          else
+            echo "api_changed=false" >> "$GITHUB_OUTPUT"
+            echo "No API-surface change -> skipping regeneration (job passes)."
+          fi
+
+      - name: Setup .NET
+        if: steps.detect.outputs.api_changed == 'true'
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Cache NuGet packages
+        if: steps.detect.outputs.api_changed == 'true'
+        uses: actions/cache@v4
+        with:
+          path: ~/.nuget/packages
+          key: nuget-${{ runner.os }}-${{ hashFiles('Directory.Packages.props', 'global.json') }}
+          restore-keys: nuget-${{ runner.os }}-
+
+      - name: Restore
+        if: steps.detect.outputs.api_changed == 'true'
+        run: dotnet restore
+
+      - name: Setup Node
+        if: steps.detect.outputs.api_changed == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install SPA dependencies
+        if: steps.detect.outputs.api_changed == 'true'
+        working-directory: web
+        run: npm ci
+
+      - name: Regenerate OpenAPI spec + endpoint index
+        if: steps.detect.outputs.api_changed == 'true'
+        run: ./scripts/update-openapi.sh
+
+      - name: Regenerate SPA API client types
+        if: steps.detect.outputs.api_changed == 'true'
+        working-directory: web
+        run: npm run generate:api
+
+      - name: Fail on stale generated artifacts
+        if: steps.detect.outputs.api_changed == 'true'
+        run: |
+          if ! git diff --exit-code -- \
+              ErsatzTV/wwwroot/openapi/v1.json \
+              web/src/api/generated/v1.d.ts \
+              docs/endpoint-index.md; then
+            echo "::error::This PR changes the API surface but its generated artifacts are stale. Run './scripts/update-openapi.sh && (cd web && npm run generate:api)' and commit v1.json / v1.d.ts / endpoint-index.md in THIS PR (CLAUDE.md → Conventions; ersatztv#303 H4/H5)."
+            exit 1
+          fi
+          echo "Generated API artifacts are in sync."
+
+  # Formatting-as-you-touch gate (ersatztv#311): verify the .cs files THIS PR changed conform to
+  # .editorconfig (style + charset=utf-8, i.e. no UTF-8 BOM). Scoped to changed files so it enforces
+  # "normalize a legacy file when you touch it" WITHOUT a big-bang reformat of the ~2500 pre-existing
+  # BOM files. A PR that touches no .cs skips the expensive steps and passes trivially (always reports
+  # a status, so it is safe as a required check).
+  format:
+    name: Formatting (changed .cs conform to .editorconfig)
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect changed C# files
+        id: detect
+        run: |
+          base_ref="${{ github.base_ref }}"
+          git fetch --no-tags --depth=100 origin "$base_ref" || true
+          changed="$(git diff --name-only --diff-filter=ACM "origin/${base_ref}...HEAD" -- '*.cs' 2>/dev/null || true)"
+          echo "Changed .cs files in this PR:"; printf '%s\n' "$changed"
+          if [ -n "$changed" ]; then
+            printf '%s\n' "$changed" > /tmp/changed-cs.txt
+            echo "cs_changed=true" >> "$GITHUB_OUTPUT"
+            echo "-> will verify these files conform to .editorconfig."
+          else
+            echo "cs_changed=false" >> "$GITHUB_OUTPUT"
+            echo "No .cs change -> skipping format verify (job passes)."
+          fi
+
+      - name: Setup .NET
+        if: steps.detect.outputs.cs_changed == 'true'
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Cache NuGet packages
+        if: steps.detect.outputs.cs_changed == 'true'
+        uses: actions/cache@v4
+        with:
+          path: ~/.nuget/packages
+          key: nuget-${{ runner.os }}-${{ hashFiles('Directory.Packages.props', 'global.json') }}
+          restore-keys: nuget-${{ runner.os }}-
+
+      - name: Restore
+        if: steps.detect.outputs.cs_changed == 'true'
+        run: dotnet restore
+
+      - name: Verify formatting of changed .cs files
+        if: steps.detect.outputs.cs_changed == 'true'
+        shell: bash
+        run: |
+          mapfile -t files < /tmp/changed-cs.txt
+          echo "Verifying ${#files[@]} changed .cs file(s) against .editorconfig..."
+          if ! dotnet format ErsatzTV.sln --no-restore --verify-no-changes --include "${files[@]}"; then
+            echo "::error::One or more .cs files this PR touches don't conform to .editorconfig (formatting or a UTF-8 BOM). Run 'dotnet format ErsatzTV.sln --include <files>' and commit the result in THIS PR — the fix-as-you-touch convention (docs/contributing.md §7; ersatztv#311). Legacy files you did NOT touch are unaffected."
+            exit 1
+          fi
+          echo "All changed .cs files conform to .editorconfig."
@@ -54,4 +54,11 @@ docker-compose.override.yml
 ErsatzTV/wwwroot/v2/
 ErsatzTV/wwwroot/app/
 web/dist/
-web/node_modules/
+web/node_modules
+
+# E2E / screenshot scratch (from Playwright/live-E2E runs) — never committed
+/*.png
+.playwright-mcp/
+
+# Per-session worktree-ownership marker (H7, ersatztv#303) — local, never committed
+.claude-worktree-owner
@@ -8,3 +8,8 @@ grep -q '^Co-Authored-By:' "$1" || {
  echo 'husky - commit message missing Co-Authored-By trailer'
  exit 1
 }
+
+# H9 (ersatztv#303) — docs/decisions.md is append-only. Block a commit that rewrites a settled
+# entry unless the message carries [decisions-edit]. commit-msg runs after the index is final, so
+# the staged diff is what's being committed; the message file ($1) supplies the override token.
+./.claude/hooks/decisions-guard.sh staged "$1" || exit 1
@@ -1,6 +1,16 @@
 cd web && npx lint-staged || exit 1
 cd ..

+# H3 (ersatztv#303) — never commit a screenshot dropped at the repo root. Belt-and-suspenders with
+# .gitignore (catches a forced `git add -f`). Root-level *.png only; nested paths are legit assets.
+root_png=$(git diff --cached --name-only --diff-filter=ACM | grep -iE '^[^/]+\.png$' || true)
+if [ -n "$root_png" ]; then
+  echo "husky - refusing to commit root-level screenshot(s):"
+  printf '  %s\n' $root_png
+  echo "  Move it out of the repo root or drop it (root *.png are review/debug artifacts; see .gitignore)."
+  exit 1
+fi
+
 # dotnet format on staged .cs files (repo root). Scoped to the staged files so we
 # don't pay the full-tree cost; skip entirely when no .cs is staged (avoids the
 # ~20-40s sln load for web-only commits).
@@ -1,9 +1,20 @@
+# H6 merge-consent backstop (ersatztv#303): gate a direct push to main on the linked issue's
+# ## Done-when checklist. Read git's pre-push ref lines FIRST (before the web checks below, which
+# may consume stdin) and forward them. Fail-open: no creds / not main / docs-only -> allow.
+_prepush_refs="$(cat)"
+printf '%s\n' "$_prepush_refs" | ./.claude/hooks/prepush-donewhen.sh || exit 1
+
 # Git exports GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE while running hooks. In a worktree
 # (or any subdir), an explicit GIT_DIR makes nested `git` commands mislocate the working
 # tree — notably `check:api`'s `git diff --exit-code` (run from web/) silently reports "no
 # diff" and lets drift through. Unset them so nested git rediscovers the repo normally.
 unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE

+# H11 (ersatztv#311): refuse to push a branch that is BEHIND origin/main — rebase, don't merge
+# main in (a merge drags in files you never touched, e.g. legacy-BOM .cs, and trips the format
+# hook on code that isn't yours). Fail-open; escape with ETV_SKIP_REBASE_CHECK=1.
+./.claude/hooks/prepush-rebase-check.sh || exit 1
+
 # CI-parity checks: catch "green locally, red in CI" before the push leaves the machine.
 # check:api guards the generated OpenAPI types (v1.json / v1.d.ts drift); the full
 # lint/typecheck/build catch a staged change that breaks an UNstaged file (lint-staged
@@ -5,7 +5,7 @@ Custom IPTV channel server for Jellyfin. Forked from [ErsatzTV/ErsatzTV](https:/
 ## Architecture

 - **Language**: C# / .NET 10
- **UI**: ChicoryTV React SPA (`web/`, Vite, served at `/app`) over the REST API — the default UI; root `/` and migrated legacy routes 302 there (`ErsatzTV/LegacyUiRedirects.cs`). The legacy Blazor Server UI (MudBlazor) still serves the remaining un-migrated admin screens — playback troubleshooting, multi/rerun collections, and playlist editing depth; Blazor home = `/system/health`, reachable via the Settings → System "Classic UI" link. Media detail pages + image folder browser landed in the SPA via #141 (PR #183); its removal is #91 phase (b), gated on #145 (playback troubleshooting) and API gaps #151/#152/#153/#155 (scheduling parity #144/#162 DONE 2026-07-07: blocks/templates/decos/deco-templates/playout editors all in the SPA; #141/#158/#161/#180 also DONE)
+- **UI**: ChicoryTV React SPA (`web/`, Vite, served at `/app`) over the REST API — the ONLY UI. The legacy Blazor Server UI (MudBlazor) was removed in #91 phase (b); root `/` and every legacy route now 302 to `/app`, either via an explicit redirect in `ErsatzTV/LegacyUiRedirects.cs` or the Startup catch-all fallback (any unmatched non-`/api`/`/artwork`/`/docs`/`/openapi` path → `/app`). Historical parity work: media detail pages + image folder browser landed via #141 (PR #183); scheduling parity #144/#162, #141/#158/#161/#180, #145, #151/#152/#153/#155, and the media-source write API/SPA #202 are all DONE.
 - **Pattern**: CQRS via MediatR — queries/commands in `ErsatzTV.Application/`
 - **Database**: EF Core (SQLite default, MySQL optional) — context in `ErsatzTV.Infrastructure/Data/TvContext.cs`
 - **Media**: FFmpeg via CliWrap, SkiaSharp for logo generation
@@ -15,7 +15,7 @@ Custom IPTV channel server for Jellyfin. Forked from [ErsatzTV/ErsatzTV](https:/

 | Project | Role |
 |---------|------|
-| `ErsatzTV/` | ASP.NET Core host, API controllers, SPA static hosting, legacy Blazor pages, DI setup |
+| `ErsatzTV/` | ASP.NET Core host, API controllers, SPA static hosting, DI setup |
 | `web/` | ChicoryTV React SPA (Vite + TypeScript; builds into `ErsatzTV/wwwroot/app`) |
 | `ErsatzTV.Application/` | MediatR handlers (business logic) |
 | `ErsatzTV.Core/` | Domain entities, interfaces, no infrastructure deps |
@@ -35,10 +35,10 @@ Custom IPTV channel server for Jellyfin. Forked from [ErsatzTV/ErsatzTV](https:/

 ## Deployment

- **Docker host**: jazz (192.168.1.99), container `ersatztv`, port 8409
- **Config volume**: `~/downloadswarm/ersatztv/` on jazz → `/config` in container
+- **Docker host**: bumblebee (192.168.1.99), container `ersatztv`, port 8409
+- **Config volume**: `~/downloadswarm/ersatztv/` on bumblebee → `/config` in container
 - **SQLite DB**: `/config/ersatztv.sqlite3` (WAL mode, root-owned)
- **Images** (our fork, built by `.gitea/workflows/docker-build.yml` → `192.168.1.95:3000/timothy/ersatztv`): push to `main` → `:latest` + `:<sha>` (test image); push `v*` tag → `:prod` + `:<version>` + `:<sha>`. Prod deploys via **Komodo GitOps**: the `media-servers` compose in `timothy/server-management` (`docker/bumblebee/stacks/media-servers/compose.yaml`) pins the version tag (currently `26.5.0`, deployed 2026-07-07); releasing = tag here, wait for the image build, bump that pin and push (the Komodo pre-deploy hook backs up before recreating). Test container tracks `:latest`. Pipeline details: `docs/ci-cd.md`.
+- **Images** (our fork, built by `.gitea/workflows/docker-build.yml` → `192.168.1.95:3000/timothy/ersatztv`): push to `main` → `:latest` + `:<sha>` (test image); push `v*` tag → `:prod` + `:<version>` + `:<sha>`. Prod's **Komodo GitOps** `media-servers` stack follows floating `:prod`; after the immutable `:<version>` candidate passes the release scans, manually deploy the stack (Global Auto Update is the daily fallback). Both paths run the fail-closed pre-deploy backup and prod-copy migration smoke before recreation. Test tracks `:latest`. Pipeline details: `docs/ci-cd.md`.

 ## Development

@@ -55,7 +55,7 @@ docker build -f docker/Dockerfile -t ersatztv:dev .

 ## Conventions

- **Read [`docs/contributing.md`](docs/contributing.md)** before non-trivial changes — it documents the established patterns (layering, CQRS handlers, LanguageExt, Blazor/MudBlazor, EF Core + dual-provider migrations, the FFmpeg pipeline, analyzers, testing) and the **deviation policy**: match the established style; diverge only with a concrete, stated reason.
+- **Read [`docs/contributing.md`](docs/contributing.md)** before non-trivial changes — it documents the established patterns (layering, CQRS handlers, LanguageExt, the ChicoryTV SPA, EF Core + dual-provider migrations, the FFmpeg pipeline, analyzers, testing) and the **deviation policy**: match the established style; diverge only with a concrete, stated reason.
 - **Docs-first is a HARD RULE — read before you explore**: before ANY API / SPA / E2E / parity / scheduling work, read `docs/README.md` (index) → the convention docs (`api-conventions`, `spa-conventions`, `e2e-local`, `domain-model`, `blazor-route-parity`, `decisions`). **Do NOT reverse-engineer conventions from source (Grep/Read) before reading these** — they exist precisely so you don't. Only recon the task-specific delta the docs deliberately don't freeze (a merged endpoint's exact DTO, a Blazor page's field list). **This applies to delegated subagents too**: tell each agent which doc section to read; never let one re-derive conventions from code.
 - **Docs-update is part of "done" — same PR, never a follow-up**: any PR that changes a convention, adds/migrates/redirects a route, adds/changes a `/api/*` endpoint, or reverses a decision MUST update the relevant doc in that same PR:

@@ -70,7 +70,7 @@ docker build -f docker/Dockerfile -t ersatztv:dev .
  The `docs-reminder` CI job flags a screen/route change that skips `blazor-route-parity.md`, but it's a **non-blocking** nudge — the rule is on you, not the check.
 - Follow existing MediatR CQRS pattern for new features
 - Domain logic in `ErsatzTV.Core`, infrastructure in `ErsatzTV.Infrastructure`
- Keep UI thin: the SPA talks to `/api/*` only; legacy Blazor pages delegate to MediatR handlers. New screens go in the SPA (`web/`), never in Blazor
+- Keep UI thin: the SPA talks to `/api/*` only; controllers delegate to MediatR handlers. All UI is in the SPA (`web/`)
 - Test with **NUnit** + Shouldly + NSubstitute (the existing `*.Tests` projects); xUnit is **not** used here
 - **Dependencies use Central Package Management**: versions live in the repo-root `Directory.Packages.props`; csproj reference packages by name only. Add/upgrade by editing the central `<PackageVersion>` — never put `Version=` back on a `<PackageReference>` (trips `NU1008`). See `docs/ci-cd.md` → Dependency management.
 - **DB migrations target BOTH providers**: a `TvContext` model change needs a migration in `ErsatzTV.Infrastructure.Sqlite` **and** `ErsatzTV.Infrastructure.MySql` — run `scripts/add-migration.sh <Name>` (does both). CI's `migrations` job enforces model-drift + apply-to-fresh-DB per provider. See `docs/ci-cd.md` → Migration integrity.
@@ -82,6 +82,12 @@ docker build -f docker/Dockerfile -t ersatztv:dev .

 Every task that closes a Gitea issue MUST complete ALL of these before it is considered done. Use `/done <issue>` to run through this automatically.

+**Merge-consent is derived from state, not asserted (`## Done-when` convention — ersatztv#303 H6 + H10).** Any issue whose PR will merge to `main` should carry a `## Done-when` section in its **issue body** — a checklist of completion criteria (always include an "adversarial review passed" box; add per-issue criteria like tests-green, docs-updated, live-E2E). Two hooks derive merge-consent from it so a premature merge is blocked *by construction*, not by memory:
+- `pretooluse-merge-consent.sh` (Claude PreToolUse on the Gitea merge tool) — **auto-grants** a merge (emits `permissionDecision: allow`, so **no** redundant mechanical prompt fires) only when the PR's CI is green **and** every `## Done-when` box on the linked issue (`fixes #N`) is ticked **and** a `Review-verdict:` comment references the PR's *current head sha* (**H10**); **denies** on an unticked box, red CI, or a stale/negative review verdict; **asks** (falls back to a human prompt) when it can't derive state (no linked issue, no `## Done-when` section, no `Review-verdict:` comment yet, no creds, Gitea down). On the auto-grant (satisfied) path the derived state **is** the consent — do not also ask conversationally to merge; a separate human confirmation is warranted only when the gate **asks** (ersatztv#314). **The H10 review-verdict convention**: after an adversarial/Codex review of a PR (or its latest fix commit), post a PR comment with a line `Review-verdict: <MERGEABLE|APPROVED|BLOCKED> @ <head-sha>` — this proves the *latest* commit was reviewed, not a stale earlier diff (ersatztv#242).
+- `.husky/pre-push` → `prepush-donewhen.sh` — a fail-open backstop that blocks a direct `git push origin main` whose commits `fix #N` an issue with unticked boxes.
+
+Both need Gitea read creds in the env to enforce (**`ETV_GITEA_BASICAUTH=user:pass`** or `ETV_GITEA_TOKEN`; `ETV_GITEA_URL` overrides the base). Without them the merge hook asks and the push backstop is a no-op — the gate degrades to today's manual confirmation, never a silent pass. Docs-only PRs/pushes are exempt.
+
 1. **Root cause** (bug fixes / incidents only): Document WHY the problem existed, not just what was changed. If root cause is unknown, say so explicitly and open a follow-up investigation issue. Fixing symptoms without understanding causes creates recurring problems.
 2. **Comment on issues** as you work — what you found, what approach you're taking, any deviations from the suggested fix.
 3. **Push changes**: `git push` all commits before closing. Use `fixes #N` in commit messages to auto-close where appropriate.
@@ -5,10 +5,7 @@

  <ItemGroup>
    <PackageVersion Include="AsyncFixer" Version="2.1.0" />
-    <PackageVersion Include="Blazored.FluentValidation" Version="2.2.0" />
-    <PackageVersion Include="BlazorSortable" Version="6.0.2" />
    <PackageVersion Include="Blurhash.SkiaSharp" Version="2.0.0" />
-    <PackageVersion Include="Chronic.Core" Version="0.4.0" />
    <PackageVersion Include="CliWrap" Version="3.10.2" />
    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
    <PackageVersion Include="Dapper" Version="2.1.79" />
@@ -22,8 +19,6 @@
    <PackageVersion Include="FluentValidation.AspNetCore" Version="11.3.1" />
    <PackageVersion Include="Flurl" Version="4.0.0" />
    <PackageVersion Include="Hardware.Info" Version="101.1.1.1" />
-    <PackageVersion Include="Heron.MudCalendar" Version="3.4.0" />
-    <PackageVersion Include="HtmlSanitizer" Version="9.0.892" />
    <PackageVersion Include="Humanizer.Core" Version="3.0.1" />
    <PackageVersion Include="Jint" Version="4.5.0" />
    <PackageVersion Include="JsonSchema.Net" Version="9.0.0" />
@@ -33,14 +28,17 @@
    <PackageVersion Include="Lucene.Net" Version="4.8.0-beta00017" />
    <PackageVersion Include="Lucene.Net.Analysis.Common" Version="4.8.0-beta00017" />
    <PackageVersion Include="Lucene.Net.QueryParser" Version="4.8.0-beta00017" />
-    <PackageVersion Include="Markdig" Version="0.44.0" />
    <PackageVersion Include="MediatR" Version="[12.5.0]" />
-    <PackageVersion Include="MediatR.Courier.DependencyInjection" Version="5.0.0" />
    <PackageVersion Include="Meziantou.Analyzer" Version="3.0.115" />
    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.2" />
    <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.2" />
+    <PackageVersion Include="Microsoft.Extensions.Identity.Core" Version="10.0.2" />
    <PackageVersion Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="10.0.2" />
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.2" />
+    <!-- Direct-pin over the 2.0.0 transitive (from Microsoft.AspNetCore.OpenApi + Scalar.AspNetCore):
+         2.0.0 is GHSA-v5pm-xwqc-g5wc (High — stack overflow parsing a circular $ref). Fixed in 2.7.5.
+         Referenced directly in ErsatzTV.csproj so the override actually resolves (CPM). See ersatztv#314/#8. -->
+    <PackageVersion Include="Microsoft.OpenApi" Version="2.7.5" />
    <PackageVersion Include="Microsoft.AspNetCore.SpaServices.Extensions" Version="10.0.2" />
    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="[9.0.12,10)" />
    <PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="[9.0.12,10)" />
@@ -61,8 +59,6 @@
    <PackageVersion Include="Microsoft.IO.RecyclableMemoryStream" Version="3.0.1" />
    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
    <PackageVersion Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.14.15" />
-    <PackageVersion Include="MudBlazor" Version="8.15.0" />
-    <PackageVersion Include="NaturalSort.Extension" Version="4.4.1" />
    <PackageVersion Include="NCalcSync" Version="6.3.2" />
    <PackageVersion Include="NetArchTest.eNhancedEdition" Version="1.4.5" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
@@ -1,5 +1,5 @@
-using System.Net;
 using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Images;

 namespace ErsatzTV.Application.Artworks;

@@ -11,7 +11,14 @@ public record ArtworkContentTypeModel(string Path, string ContentType)

    public bool HasContentType => !string.IsNullOrWhiteSpace(ContentType);

-    public string UrlWithContentType => string.IsNullOrWhiteSpace(ContentType)
-        ? Path
-        : $"{Path}?contentType={WebUtility.UrlEncode(ContentType)}";
+    // The artwork serve routes now sniff the content type from the stored file and no longer honor a
+    // client-supplied ?contentType= (issue #283 — that reflection was the stored-XSS sink), so the
+    // directly-usable URL is just the path.
+    public string UrlWithContentType => Path;
+
+    // Defense-in-depth: never persist a content type outside the image allow-list, so a value that
+    // slipped in via the {path, contentType} JSON DTOs can't later be reflected anywhere. The serve
+    // path derives the type from the file regardless; this only keeps stored metadata honest.
+    public ArtworkContentTypeModel Sanitized() =>
+        ImageContentTypes.IsAccepted(ContentType) ? this : this with { ContentType = string.Empty };
 }
@@ -9,5 +9,5 @@ namespace ErsatzTV.Application.Artworks;
 ///     landing it in the same on-disk cache the Blazor UI uses (via <c>IImageCache</c>),
 ///     so the returned path is equivalent to a Blazor-uploaded image.
 /// </summary>
-public record UploadArtwork(Stream Stream, string ContentType, ArtworkKind ArtworkKind)
+public record UploadArtwork(Stream Stream, ArtworkKind ArtworkKind)
    : IRequest<Either<BaseError, ArtworkUploadResponseModel>>;
@@ -1,22 +1,13 @@
 using ErsatzTV.Core;
 using ErsatzTV.Core.Api.Artwork;
 using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Images;
 using ErsatzTV.Core.Interfaces.Images;

 namespace ErsatzTV.Application.Artworks;

 public class UploadArtworkHandler : IRequestHandler<UploadArtwork, Either<BaseError, ArtworkUploadResponseModel>>
 {
-    // png/jpeg/gif/webp are all decoded by SkiaSharp and read by FFmpeg, matching the
-    // formats the Blazor logo/watermark upload already accepts. Format expansion is ersatztv#66.
-    private static readonly System.Collections.Generic.HashSet<string> AcceptedContentTypes = new(StringComparer.OrdinalIgnoreCase)
-    {
-        "image/png",
-        "image/jpeg",
-        "image/gif",
-        "image/webp"
-    };
-
    private readonly IImageCache _imageCache;

    public UploadArtworkHandler(IImageCache imageCache) => _imageCache = imageCache;
@@ -25,15 +16,31 @@ public class UploadArtworkHandler : IRequestHandler<UploadArtwork, Either<BaseEr
        UploadArtwork request,
        CancellationToken cancellationToken)
    {
-        string contentType = (request.ContentType ?? string.Empty).Trim();
-        if (!AcceptedContentTypes.Contains(contentType))
+        // Buffer the upload so we can sniff its true format before storing it. The request body is
+        // already bounded by the Kestrel MaxRequestBodySize / the controller's size check, so this
+        // is a bounded read.
+        byte[] bytes;
+        await using (var buffer = new MemoryStream())
        {
-            return BaseError.New(
-                $"Unsupported image content type '{contentType}'; supported types are: {string.Join(", ", AcceptedContentTypes)}");
+            await request.Stream.CopyToAsync(buffer, cancellationToken);
+            bytes = buffer.ToArray();
        }

+        // Derive the content type from the actual bytes, never from the client-declared value
+        // (issue #283 — a spoofed image/png header let a <script> payload be stored and later served
+        // as HTML). A payload that isn't a supported raster image is rejected here.
+        Option<string> maybeContentType = ImageContentTypes.DetectContentType(bytes);
+        if (maybeContentType.IsNone)
+        {
+            return BaseError.New(
+                $"Uploaded file is not a supported image; supported types are: {string.Join(", ", ImageContentTypes.Accepted)}");
+        }
+
+        string contentType = maybeContentType.IfNone(string.Empty);
+
+        using var toCache = new MemoryStream(bytes, writable: false);
        Either<BaseError, string> maybeFileName = await _imageCache.SaveArtworkToCache(
-            request.Stream,
+            toCache,
            request.ArtworkKind);

        return maybeFileName.Map(fileName => new ArtworkUploadResponseModel(
@@ -0,0 +1,28 @@
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     Shared constants for the browser-SPA session authentication (issue #295): the cookie scheme name,
+///     the custom claim types the local-login path stamps onto the principal, and the auth-method marker
+///     values. The web host (cookie <c>OnValidatePrincipal</c>, <c>AuthController</c>) and the Application
+///     handlers both reference these so the claim contract has a single definition.
+/// </summary>
+public static class AuthConstants
+{
+    /// <summary>The cookie authentication scheme name shared by local login and the OIDC callback.</summary>
+    public const string CookieScheme = "cookie";
+
+    /// <summary>The OIDC challenge scheme name.</summary>
+    public const string OidcScheme = "oidc";
+
+    /// <summary>Claim type recording how the principal signed in (<see cref="MethodLocal" /> / <see cref="MethodOidc" />).</summary>
+    public const string AuthMethodClaim = "etv:auth_method";
+
+    /// <summary>Claim type carrying the local admin's security stamp (checked on every request to revoke sessions).</summary>
+    public const string SecurityStampClaim = "etv:security_stamp";
+
+    public const string MethodLocal = "local";
+    public const string MethodOidc = "oidc";
+
+    /// <summary>Minimum length for a local admin password.</summary>
+    public const int MinPasswordLength = 8;
+}
@@ -0,0 +1,10 @@
+using ErsatzTV.Core;
+
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     Changes the local admin password after verifying the current one. Rotates the security stamp so all
+///     other sessions are revoked. <see cref="Username" /> is the signed-in principal's name.
+/// </summary>
+public record ChangeLocalAdminPassword(string Username, string CurrentPassword, string NewPassword)
+    : IRequest<Either<BaseError, LocalAdminPrincipal>>;
@@ -0,0 +1,68 @@
+using ErsatzTV.Core;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace ErsatzTV.Application.Auth;
+
+public class ChangeLocalAdminPasswordHandler(
+    IDbContextFactory<TvContext> dbContextFactory,
+    ILocalPasswordHasher passwordHasher)
+    : IRequestHandler<ChangeLocalAdminPassword, Either<BaseError, LocalAdminPrincipal>>
+{
+    public async Task<Either<BaseError, LocalAdminPrincipal>> Handle(
+        ChangeLocalAdminPassword request,
+        CancellationToken cancellationToken)
+    {
+        foreach (BaseError error in LocalAdminHelpers.ValidatePassword(request.NewPassword))
+        {
+            return error;
+        }
+
+        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
+
+        List<ConfigElement> rows = await dbContext.ConfigElements
+            .Where(c => c.Key == ConfigElementKey.AuthLocalAdminUsername.Key
+                        || c.Key == ConfigElementKey.AuthLocalAdminPasswordHash.Key
+                        || c.Key == ConfigElementKey.AuthSecurityStamp.Key)
+            .ToListAsync(cancellationToken);
+
+        ConfigElement userRow = rows.Find(r => r.Key == ConfigElementKey.AuthLocalAdminUsername.Key);
+        ConfigElement hashRow = rows.Find(r => r.Key == ConfigElementKey.AuthLocalAdminPasswordHash.Key);
+        ConfigElement stampRow = rows.Find(r => r.Key == ConfigElementKey.AuthSecurityStamp.Key);
+
+        if (hashRow is null)
+        {
+            return BaseError.New("No local administrator is configured");
+        }
+
+        string username = (request.Username ?? string.Empty).Trim();
+        bool userMatches = userRow is not null
+                           && string.Equals(userRow.Value, username, StringComparison.OrdinalIgnoreCase);
+
+        LocalPasswordVerification result =
+            passwordHasher.Verify(hashRow.Value, request.CurrentPassword ?? string.Empty);
+
+        if (!userMatches || result == LocalPasswordVerification.Failed)
+        {
+            return BaseError.New("Current password is incorrect");
+        }
+
+        // Atomic: the new hash and rotated stamp commit together, so a crash can't leave the new password
+        // active with the old stamp still authorizing revoked sessions.
+        string stamp = LocalAdminHelpers.NewSecurityStamp();
+        hashRow.Value = passwordHasher.Hash(request.NewPassword);
+        if (stampRow is null)
+        {
+            dbContext.ConfigElements.Add(new ConfigElement { Key = ConfigElementKey.AuthSecurityStamp.Key, Value = stamp });
+        }
+        else
+        {
+            stampRow.Value = stamp;
+        }
+
+        await dbContext.SaveChangesAsync(cancellationToken);
+
+        return new LocalAdminPrincipal(userRow.Value, stamp);
+    }
+}
@@ -0,0 +1,9 @@
+using ErsatzTV.Core;
+
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     First-run setup-claim: creates the single local administrator. Fails if one already exists
+///     (first-claim-wins), so a later anonymous call cannot take over the account.
+/// </summary>
+public record ClaimLocalAdmin(string Username, string Password) : IRequest<Either<BaseError, LocalAdminPrincipal>>;
@@ -0,0 +1,68 @@
+using ErsatzTV.Core;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace ErsatzTV.Application.Auth;
+
+public class ClaimLocalAdminHandler(IDbContextFactory<TvContext> dbContextFactory, ILocalPasswordHasher passwordHasher)
+    : IRequestHandler<ClaimLocalAdmin, Either<BaseError, LocalAdminPrincipal>>
+{
+    public async Task<Either<BaseError, LocalAdminPrincipal>> Handle(
+        ClaimLocalAdmin request,
+        CancellationToken cancellationToken)
+    {
+        foreach (BaseError error in LocalAdminHelpers.ValidateNewCredentials(request.Username, request.Password))
+        {
+            return error;
+        }
+
+        string username = request.Username.Trim();
+
+        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
+
+        // Fast path for the common already-configured case (clean 409). The real first-claim-wins guard is
+        // the unique index on ConfigElement.Key + the single atomic SaveChanges below: two concurrent claims
+        // both pass this check, but only one INSERT of the three credential rows commits — the loser's
+        // SaveChanges violates the unique Key index and rolls back wholesale (no mixed-state credential).
+        bool alreadyConfigured = await dbContext.ConfigElements
+            .AnyAsync(c => c.Key == ConfigElementKey.AuthLocalAdminPasswordHash.Key, cancellationToken);
+        if (alreadyConfigured)
+        {
+            return BaseError.New("A local administrator has already been configured");
+        }
+
+        string stamp = LocalAdminHelpers.NewSecurityStamp();
+        dbContext.ConfigElements.AddRange(
+            new ConfigElement { Key = ConfigElementKey.AuthLocalAdminUsername.Key, Value = username },
+            new ConfigElement
+            {
+                Key = ConfigElementKey.AuthLocalAdminPasswordHash.Key,
+                Value = passwordHasher.Hash(request.Password)
+            },
+            new ConfigElement { Key = ConfigElementKey.AuthSecurityStamp.Key, Value = stamp });
+
+        try
+        {
+            await dbContext.SaveChangesAsync(cancellationToken);
+        }
+        catch (DbUpdateException)
+        {
+            // A write conflict here is (almost always) a lost first-claim race — a concurrent claim inserted
+            // these keys first (unique Key index). Confirm the row now exists on a fresh context before
+            // reporting "already configured"; otherwise this was a genuine/transient DB error → rethrow rather
+            // than mask it.
+            await using TvContext verifyContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
+            bool nowConfigured = await verifyContext.ConfigElements
+                .AnyAsync(c => c.Key == ConfigElementKey.AuthLocalAdminPasswordHash.Key, cancellationToken);
+            if (nowConfigured)
+            {
+                return BaseError.New("A local administrator has already been configured");
+            }
+
+            throw;
+        }
+
+        return new LocalAdminPrincipal(username, stamp);
+    }
+}
@@ -0,0 +1,8 @@
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     The current local-admin security stamp, or <c>None</c> if no local admin is configured. The cookie
+///     <c>OnValidatePrincipal</c> compares this to the principal's stamp claim on every request; a mismatch
+///     (i.e. the password was changed) rejects the session.
+/// </summary>
+public record GetLocalAdminSecurityStamp : IRequest<Option<string>>;
@@ -0,0 +1,11 @@
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Interfaces.Repositories;
+
+namespace ErsatzTV.Application.Auth;
+
+public class GetLocalAdminSecurityStampHandler(IConfigElementRepository configElementRepository)
+    : IRequestHandler<GetLocalAdminSecurityStamp, Option<string>>
+{
+    public async Task<Option<string>> Handle(GetLocalAdminSecurityStamp request, CancellationToken cancellationToken) =>
+        await configElementRepository.GetValue<string>(ConfigElementKey.AuthSecurityStamp, cancellationToken);
+}
@@ -0,0 +1,27 @@
+namespace ErsatzTV.Application.Auth;
+
+public enum LocalPasswordVerification
+{
+    Failed,
+    Success,
+    SuccessRehashNeeded
+}
+
+/// <summary>
+///     Wraps ASP.NET Core Identity's <c>PasswordHasher</c> (PBKDF2) behind a minimal, framework-agnostic
+///     surface so the Auth handlers don't depend on Identity types directly.
+/// </summary>
+public interface ILocalPasswordHasher
+{
+    /// <summary>Hashes a password for storage (random per-hash salt embedded in the returned string).</summary>
+    string Hash(string password);
+
+    /// <summary>Verifies a password against a stored hash in constant time (delegated to Identity).</summary>
+    LocalPasswordVerification Verify(string hash, string password);
+
+    /// <summary>
+    ///     A stable, valid hash of a throwaway password. Verify against this when no real credential exists
+    ///     so an unknown-username / unconfigured login costs the same as a real one (no user enumeration).
+    /// </summary>
+    string DummyHash { get; }
+}
@@ -0,0 +1,4 @@
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>True once a local administrator credential has been set (first-run setup is complete).</summary>
+public record IsLocalAdminConfigured : IRequest<bool>;
@@ -0,0 +1,15 @@
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Interfaces.Repositories;
+
+namespace ErsatzTV.Application.Auth;
+
+public class IsLocalAdminConfiguredHandler(IConfigElementRepository configElementRepository)
+    : IRequestHandler<IsLocalAdminConfigured, bool>
+{
+    public async Task<bool> Handle(IsLocalAdminConfigured request, CancellationToken cancellationToken)
+    {
+        Option<ConfigElement> hash =
+            await configElementRepository.GetConfigElement(ConfigElementKey.AuthLocalAdminPasswordHash, cancellationToken);
+        return hash.IsSome;
+    }
+}
@@ -0,0 +1,49 @@
+using System.Security.Cryptography;
+using ErsatzTV.Core;
+
+namespace ErsatzTV.Application.Auth;
+
+internal static class LocalAdminHelpers
+{
+    public const int MaxUsernameLength = 256;
+
+    // Upper bound so an absurdly long password can't burn CPU in PBKDF2 (the request body is also capped
+    // by Kestrel, #283; this is defense-in-depth on the field itself).
+    public const int MaxPasswordLength = 1024;
+
+    /// <summary>128 bits of random, lowercase hex. Rotated on every password change to revoke sessions.</summary>
+    public static string NewSecurityStamp() =>
+        Convert.ToHexString(RandomNumberGenerator.GetBytes(16)).ToLowerInvariant();
+
+    /// <summary>Validates a new username + password. Returns the error, or None if valid.</summary>
+    public static Option<BaseError> ValidateNewCredentials(string username, string password)
+    {
+        string trimmed = (username ?? string.Empty).Trim();
+        if (trimmed.Length == 0)
+        {
+            return BaseError.New("Username is required");
+        }
+
+        if (trimmed.Length > MaxUsernameLength)
+        {
+            return BaseError.New("Username is too long");
+        }
+
+        return ValidatePassword(password);
+    }
+
+    public static Option<BaseError> ValidatePassword(string password)
+    {
+        if (string.IsNullOrEmpty(password) || password.Length < AuthConstants.MinPasswordLength)
+        {
+            return BaseError.New($"Password must be at least {AuthConstants.MinPasswordLength} characters");
+        }
+
+        if (password.Length > MaxPasswordLength)
+        {
+            return BaseError.New($"Password must be at most {MaxPasswordLength} characters");
+        }
+
+        return Option<BaseError>.None;
+    }
+}
@@ -0,0 +1,9 @@
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     The identity of the single local administrator, as returned by a successful claim / login / password
+///     change. The web host turns this into a cookie principal: <see cref="Username" /> becomes the name claim
+///     and <see cref="SecurityStamp" /> is stamped as <see cref="AuthConstants.SecurityStampClaim" /> so a later
+///     password change (which rotates the stamp) revokes the session.
+/// </summary>
+public record LocalAdminPrincipal(string Username, string SecurityStamp);
@@ -0,0 +1,33 @@
+using Microsoft.AspNetCore.Identity;
+
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     <see cref="ILocalPasswordHasher" /> backed by ASP.NET Core Identity's <see cref="PasswordHasher{TUser}" />
+///     (PBKDF2-HMAC-SHA512, per-hash random salt, format-versioned so a future work-factor bump is a
+///     transparent rehash-on-verify). Stateless and thread-safe → registered as a singleton.
+/// </summary>
+public sealed class LocalPasswordHasher : ILocalPasswordHasher
+{
+    // The generic user parameter is unused by the hasher (it takes no per-user data), so a shared sentinel
+    // is fine.
+    private static readonly object Sentinel = new();
+
+    private readonly PasswordHasher<object> _hasher = new();
+    private readonly Lazy<string> _dummyHash;
+
+    public LocalPasswordHasher() =>
+        _dummyHash = new Lazy<string>(() => _hasher.HashPassword(Sentinel, "not-a-real-password"));
+
+    public string DummyHash => _dummyHash.Value;
+
+    public string Hash(string password) => _hasher.HashPassword(Sentinel, password);
+
+    public LocalPasswordVerification Verify(string hash, string password) =>
+        _hasher.VerifyHashedPassword(Sentinel, hash, password) switch
+        {
+            PasswordVerificationResult.Success => LocalPasswordVerification.Success,
+            PasswordVerificationResult.SuccessRehashNeeded => LocalPasswordVerification.SuccessRehashNeeded,
+            _ => LocalPasswordVerification.Failed
+        };
+}
@@ -0,0 +1,9 @@
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     Rotates the local admin security stamp, revoking every outstanding local session server-side (their
+///     cookies carry the old stamp and fail <c>OnValidatePrincipal</c> on their next request). Used by logout
+///     so signing out actually ends the session server-side, not just client-side. A no-op when no local
+///     admin is configured. OIDC sessions are unaffected (they carry no stamp).
+/// </summary>
+public record RotateLocalAdminSecurityStamp : IRequest<Unit>;
@@ -0,0 +1,28 @@
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace ErsatzTV.Application.Auth;
+
+public class RotateLocalAdminSecurityStampHandler(IDbContextFactory<TvContext> dbContextFactory)
+    : IRequestHandler<RotateLocalAdminSecurityStamp, Unit>
+{
+    public async Task<Unit> Handle(RotateLocalAdminSecurityStamp request, CancellationToken cancellationToken)
+    {
+        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
+
+        ConfigElement stampRow = await dbContext.ConfigElements
+            .FirstOrDefaultAsync(c => c.Key == ConfigElementKey.AuthSecurityStamp.Key, cancellationToken);
+
+        // No local admin configured → nothing to revoke.
+        if (stampRow is null)
+        {
+            return Unit.Default;
+        }
+
+        stampRow.Value = LocalAdminHelpers.NewSecurityStamp();
+        await dbContext.SaveChangesAsync(cancellationToken);
+
+        return Unit.Default;
+    }
+}
@@ -0,0 +1,11 @@
+using ErsatzTV.Core;
+
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     Recovery/bootstrap path: (re)sets the local admin from configuration (env
+///     <c>Auth:LocalAdmin:Username</c>/<c>Password</c>). Overwrites any existing credential and rotates the
+///     stamp (revoking sessions), so an operator who is locked out can reset by setting the env and
+///     restarting. Runs at startup only when a password is configured.
+/// </summary>
+public record SeedLocalAdminFromEnvironment(string Username, string Password) : IRequest<Either<BaseError, Unit>>;
@@ -0,0 +1,63 @@
+using ErsatzTV.Core;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace ErsatzTV.Application.Auth;
+
+public class SeedLocalAdminFromEnvironmentHandler(
+    IDbContextFactory<TvContext> dbContextFactory,
+    ILocalPasswordHasher passwordHasher)
+    : IRequestHandler<SeedLocalAdminFromEnvironment, Either<BaseError, Unit>>
+{
+    public async Task<Either<BaseError, Unit>> Handle(
+        SeedLocalAdminFromEnvironment request,
+        CancellationToken cancellationToken)
+    {
+        string username = (request.Username ?? string.Empty).Trim();
+        if (username.Length == 0)
+        {
+            username = "admin";
+        }
+
+        if (username.Length > LocalAdminHelpers.MaxUsernameLength)
+        {
+            return BaseError.New("Seed username is too long");
+        }
+
+        foreach (BaseError error in LocalAdminHelpers.ValidatePassword(request.Password))
+        {
+            return error;
+        }
+
+        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
+
+        List<ConfigElement> rows = await dbContext.ConfigElements
+            .Where(c => c.Key == ConfigElementKey.AuthLocalAdminUsername.Key
+                        || c.Key == ConfigElementKey.AuthLocalAdminPasswordHash.Key
+                        || c.Key == ConfigElementKey.AuthSecurityStamp.Key)
+            .ToListAsync(cancellationToken);
+
+        // Overwrite (recovery/bootstrap) atomically: username + new hash + rotated stamp commit together.
+        Upsert(dbContext, rows, ConfigElementKey.AuthLocalAdminUsername.Key, username);
+        Upsert(dbContext, rows, ConfigElementKey.AuthLocalAdminPasswordHash.Key, passwordHasher.Hash(request.Password));
+        Upsert(dbContext, rows, ConfigElementKey.AuthSecurityStamp.Key, LocalAdminHelpers.NewSecurityStamp());
+
+        await dbContext.SaveChangesAsync(cancellationToken);
+
+        return Unit.Default;
+    }
+
+    private static void Upsert(TvContext dbContext, List<ConfigElement> existing, string key, string value)
+    {
+        ConfigElement row = existing.Find(r => r.Key == key);
+        if (row is null)
+        {
+            dbContext.ConfigElements.Add(new ConfigElement { Key = key, Value = value });
+        }
+        else
+        {
+            row.Value = value;
+        }
+    }
+}
@@ -0,0 +1,9 @@
+using ErsatzTV.Core;
+
+namespace ErsatzTV.Application.Auth;
+
+/// <summary>
+///     Verifies a local-login username/password. On success returns the principal (username + current
+///     security stamp) to sign into a cookie. A generic error (no username enumeration) on any failure.
+/// </summary>
+public record VerifyLocalAdminLogin(string Username, string Password) : IRequest<Either<BaseError, LocalAdminPrincipal>>;
@@ -0,0 +1,53 @@
+using ErsatzTV.Core;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace ErsatzTV.Application.Auth;
+
+public class VerifyLocalAdminLoginHandler(
+    IDbContextFactory<TvContext> dbContextFactory,
+    ILocalPasswordHasher passwordHasher)
+    : IRequestHandler<VerifyLocalAdminLogin, Either<BaseError, LocalAdminPrincipal>>
+{
+    private static readonly BaseError InvalidCredentials = BaseError.New("Invalid username or password");
+
+    public async Task<Either<BaseError, LocalAdminPrincipal>> Handle(
+        VerifyLocalAdminLogin request,
+        CancellationToken cancellationToken)
+    {
+        string username = (request.Username ?? string.Empty).Trim();
+
+        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
+
+        // Read the hash and stamp in ONE snapshot so they are consistent (issue: a login racing a password
+        // change must not return a stamp newer than the hash it verified). A concurrent change is then either
+        // wholly before this read (the old password fails to verify) or wholly after it (we return the
+        // pre-change stamp, so the cookie AuthController issues is revoked on its very next request by
+        // CookieSecurityStampValidator). No writes happen here, so there is nothing to clobber.
+        Dictionary<string, string> config = await dbContext.ConfigElements
+            .Where(c => c.Key == ConfigElementKey.AuthLocalAdminUsername.Key
+                        || c.Key == ConfigElementKey.AuthLocalAdminPasswordHash.Key
+                        || c.Key == ConfigElementKey.AuthSecurityStamp.Key)
+            .ToDictionaryAsync(c => c.Key, c => c.Value, cancellationToken);
+
+        config.TryGetValue(ConfigElementKey.AuthLocalAdminUsername.Key, out string storedUser);
+        config.TryGetValue(ConfigElementKey.AuthLocalAdminPasswordHash.Key, out string storedHash);
+        config.TryGetValue(ConfigElementKey.AuthSecurityStamp.Key, out string stamp);
+
+        // Always run exactly one PBKDF2 verify — against a dummy hash when unconfigured/unknown — so response
+        // timing does not reveal whether the account exists (no user enumeration).
+        string candidateHash = storedHash ?? passwordHasher.DummyHash;
+        LocalPasswordVerification result = passwordHasher.Verify(candidateHash, request.Password ?? string.Empty);
+
+        bool userMatches = storedUser is not null
+                           && string.Equals(storedUser, username, StringComparison.OrdinalIgnoreCase);
+
+        if (storedHash is null || !userMatches || result == LocalPasswordVerification.Failed)
+        {
+            return InvalidCredentials;
+        }
+
+        return new LocalAdminPrincipal(storedUser, stamp ?? string.Empty);
+    }
+}
@@ -38,6 +38,41 @@ internal static class Mapper
            channel.IsEnabled,
            channel.ShowInEpg);

+    internal static ChannelDetailResponseModel ProjectToDetailResponseModel(Channel channel, int playoutCount)
+    {
+        ArtworkContentTypeModel logo = GetLogo(channel);
+        return new ChannelDetailResponseModel(
+            channel.Id,
+            channel.Number,
+            channel.Name,
+            channel.Group,
+            channel.Categories,
+            channel.FFmpegProfileId,
+            channel.SlugSeconds,
+            new ChannelLogoResponseModel(logo.Path, logo.ContentType),
+            channel.StreamSelectorMode,
+            channel.StreamSelector,
+            channel.PreferredAudioLanguageCode,
+            channel.PreferredAudioTitle,
+            channel.PlayoutSource,
+            channel.PlayoutMode,
+            channel.MirrorSourceChannelId,
+            channel.PlayoutOffset,
+            channel.StreamingMode,
+            channel.WatermarkId,
+            channel.FallbackFillerId,
+            playoutCount,
+            channel.PreferredSubtitleLanguageCode,
+            channel.SubtitleMode,
+            channel.MusicVideoCreditsMode,
+            channel.MusicVideoCreditsTemplate,
+            channel.SongVideoMode,
+            channel.TranscodeMode,
+            channel.IdleBehavior,
+            channel.IsEnabled,
+            channel.ShowInEpg);
+    }
+
    internal static ChannelResponseModel ProjectToResponseModel(Channel channel) =>
        new(
            channel.Id,
@@ -0,0 +1,5 @@
+using ErsatzTV.Core.Api.Channels;
+
+namespace ErsatzTV.Application.Channels;
+
+public record GetChannelByIdForApi(int Id) : IRequest<Option<ChannelDetailResponseModel>>;
@@ -0,0 +1,15 @@
+using ErsatzTV.Core.Api.Channels;
+using ErsatzTV.Core.Interfaces.Repositories;
+using static ErsatzTV.Application.Channels.Mapper;
+
+namespace ErsatzTV.Application.Channels;
+
+public class GetChannelByIdForApiHandler(IChannelRepository channelRepository)
+    : IRequestHandler<GetChannelByIdForApi, Option<ChannelDetailResponseModel>>
+{
+    public Task<Option<ChannelDetailResponseModel>> Handle(
+        GetChannelByIdForApi request,
+        CancellationToken cancellationToken) =>
+        channelRepository.GetChannel(request.Id)
+            .MapT(channel => ProjectToDetailResponseModel(channel, channel.Playouts?.Count ?? 0));
+}
@@ -119,6 +119,7 @@ public class GetChannelGuideDataHandler(

            responseChannels.Add(
                new ChannelGuideChannelResponseModel(
+                    channel.Id,
                    channel.Number,
                    channel.Name,
                    programmes.OrderBy(p => p.Start).ToList()));
@@ -0,0 +1,6 @@
+using ErsatzTV.Core.Api.Channels;
+
+namespace ErsatzTV.Application.Channels;
+
+public record GetChannelPlaybackSource(int ChannelId, DateTimeOffset At)
+    : IRequest<Option<ChannelPlaybackSourceResponseModel>>;
@@ -0,0 +1,171 @@
+#nullable enable
+using ErsatzTV.Core.Api.Channels;
+using ErsatzTV.Core.Domain;
+using ErsatzTV.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace ErsatzTV.Application.Channels;
+
+/// <summary>
+/// Resolves the physical playout item at a point in time without invoking the streaming or FFmpeg pipeline.
+/// Guide projection is deliberately not used here: guide entries may merge filler or split a block differently
+/// from the actual media-item boundaries a player must follow.
+/// </summary>
+public class GetChannelPlaybackSourceHandler(IDbContextFactory<TvContext> dbContextFactory)
+    : IRequestHandler<GetChannelPlaybackSource, Option<ChannelPlaybackSourceResponseModel>>
+{
+    public async Task<Option<ChannelPlaybackSourceResponseModel>> Handle(
+        GetChannelPlaybackSource request,
+        CancellationToken cancellationToken)
+    {
+        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
+
+        Channel? channel = await dbContext.Channels
+            .AsNoTracking()
+            .SingleOrDefaultAsync(c => c.Id == request.ChannelId, cancellationToken);
+
+        if (channel is null)
+        {
+            return None;
+        }
+
+        // Deleting a mirror's source sets this nullable FK to null. Do not self-resolve to a stale
+        // playout that may remain attached to the mirror channel.
+        if (channel.PlayoutSource == ChannelPlayoutSource.Mirror && channel.MirrorSourceChannelId is null)
+        {
+            return None;
+        }
+
+        int sourceChannelId = channel.PlayoutSource == ChannelPlayoutSource.Mirror
+            ? channel.MirrorSourceChannelId!.Value
+            : channel.Id;
+        TimeSpan playoutOffset = channel.PlayoutSource == ChannelPlayoutSource.Mirror
+            ? channel.PlayoutOffset ?? TimeSpan.Zero
+            : TimeSpan.Zero;
+        DateTime sourceAtUtc = request.At.UtcDateTime - playoutOffset;
+
+        PlayoutItem? active = await ActiveItems(dbContext, sourceChannelId, sourceAtUtc)
+            .OrderBy(pi => pi.Start)
+            .FirstOrDefaultAsync(cancellationToken);
+
+        DateTime? nextSourceTransition = active?.Finish;
+        if (nextSourceTransition is null)
+        {
+            nextSourceTransition = await dbContext.PlayoutItems
+                .AsNoTracking()
+                .Where(pi => pi.Playout.ChannelId == sourceChannelId && pi.Start > sourceAtUtc)
+                .OrderBy(pi => pi.Start)
+                .Select(pi => (DateTime?)pi.Start)
+                .FirstOrDefaultAsync(cancellationToken);
+        }
+
+        DateTimeOffset resolvedAt = request.At.ToUniversalTime();
+        DateTimeOffset sourceAt = new(sourceAtUtc, TimeSpan.Zero);
+        DateTimeOffset? nextTransitionAt = nextSourceTransition.HasValue
+            ? new DateTimeOffset(nextSourceTransition.Value + playoutOffset, TimeSpan.Zero)
+            : null;
+
+        ChannelPlaybackItemResponseModel? playbackItem = active is null
+            ? null
+            : ToPlaybackItem(active, sourceAtUtc, playoutOffset);
+
+        return new ChannelPlaybackSourceResponseModel(
+            channel.Id,
+            sourceChannelId,
+            resolvedAt,
+            sourceAt,
+            nextTransitionAt,
+            playbackItem);
+    }
+
+    private static IQueryable<PlayoutItem> ActiveItems(TvContext dbContext, int sourceChannelId, DateTime sourceAtUtc) =>
+        dbContext.PlayoutItems
+            .AsNoTracking()
+            .Where(pi => pi.Playout.ChannelId == sourceChannelId)
+            .Where(pi => pi.Start <= sourceAtUtc && pi.Finish > sourceAtUtc)
+            .Include(pi => pi.MediaItem)
+            .ThenInclude(mi => (mi as Movie)!.MediaVersions)
+            .ThenInclude(mv => mv.MediaFiles)
+            .Include(pi => pi.MediaItem)
+            .ThenInclude(mi => (mi as Episode)!.MediaVersions)
+            .ThenInclude(mv => mv.MediaFiles)
+            .Include(pi => pi.MediaItem)
+            .ThenInclude(mi => (mi as MusicVideo)!.MediaVersions)
+            .ThenInclude(mv => mv.MediaFiles)
+            .Include(pi => pi.MediaItem)
+            .ThenInclude(mi => (mi as OtherVideo)!.MediaVersions)
+            .ThenInclude(mv => mv.MediaFiles)
+            .Include(pi => pi.MediaItem)
+            .ThenInclude(mi => (mi as Song)!.MediaVersions)
+            .ThenInclude(mv => mv.MediaFiles)
+            .Include(pi => pi.MediaItem)
+            .ThenInclude(mi => (mi as Image)!.MediaVersions)
+            .ThenInclude(mv => mv.MediaFiles)
+            .Include(pi => pi.MediaItem)
+            .ThenInclude(mi => (mi as RemoteStream)!.MediaVersions)
+            .ThenInclude(mv => mv.MediaFiles)
+            .AsSplitQuery();
+
+    private static ChannelPlaybackItemResponseModel ToPlaybackItem(
+        PlayoutItem item,
+        DateTime sourceAtUtc,
+        TimeSpan playoutOffset)
+    {
+        TimeSpan currentOffset = item.InPoint + (sourceAtUtc - item.Start);
+        if (currentOffset < item.InPoint)
+        {
+            currentOffset = item.InPoint;
+        }
+
+        if (item.OutPoint > item.InPoint && currentOffset > item.OutPoint)
+        {
+            currentOffset = item.OutPoint;
+        }
+
+        return new ChannelPlaybackItemResponseModel(
+            item.Id,
+            item.MediaItemId,
+            new DateTimeOffset(item.Start + playoutOffset, TimeSpan.Zero),
+            new DateTimeOffset(item.Finish + playoutOffset, TimeSpan.Zero),
+            item.InPoint.Ticks,
+            currentOffset.Ticks,
+            item.OutPoint.Ticks,
+            item.FillerKind,
+            GetSourceReference(item.MediaItem));
+    }
+
+    private static ChannelPlaybackSourceReferenceResponseModel GetSourceReference(MediaItem mediaItem) =>
+        mediaItem switch
+        {
+            JellyfinMovie movie => Reference(ChannelPlaybackSourceKind.JellyfinItem, itemId: movie.ItemId),
+            JellyfinEpisode episode => Reference(ChannelPlaybackSourceKind.JellyfinItem, itemId: episode.ItemId),
+            PlexMovie movie => Reference(ChannelPlaybackSourceKind.PlexItem, itemId: movie.Key),
+            PlexEpisode episode => Reference(ChannelPlaybackSourceKind.PlexItem, itemId: episode.Key),
+            PlexOtherVideo video => Reference(ChannelPlaybackSourceKind.PlexItem, itemId: video.Key),
+            EmbyMovie movie => Reference(ChannelPlaybackSourceKind.EmbyItem, itemId: movie.ItemId),
+            EmbyEpisode episode => Reference(ChannelPlaybackSourceKind.EmbyItem, itemId: episode.ItemId),
+            RemoteStream stream => Reference(ChannelPlaybackSourceKind.RemoteUrl, isLive: stream.IsLive),
+            Movie movie => LocalFile(movie.MediaVersions),
+            Episode episode => LocalFile(episode.MediaVersions),
+            MusicVideo video => LocalFile(video.MediaVersions),
+            OtherVideo video => LocalFile(video.MediaVersions),
+            Song song => LocalFile(song.MediaVersions),
+            Image image => LocalFile(image.MediaVersions),
+            _ => Reference(ChannelPlaybackSourceKind.Unsupported)
+        };
+
+    private static ChannelPlaybackSourceReferenceResponseModel LocalFile(IEnumerable<MediaVersion> versions)
+    {
+        string? path = versions.FirstOrDefault()?.MediaFiles.FirstOrDefault()?.Path;
+        return string.IsNullOrWhiteSpace(path)
+            ? Reference(ChannelPlaybackSourceKind.Unsupported)
+            : Reference(ChannelPlaybackSourceKind.LocalFile, path: path);
+    }
+
+    private static ChannelPlaybackSourceReferenceResponseModel Reference(
+        ChannelPlaybackSourceKind kind,
+        string? itemId = null,
+        string? path = null,
+        bool isLive = false) =>
+        new(kind, itemId, path, isLive);
+}
@@ -15,9 +15,10 @@ public static class ConcurrencyExtensions
    ///     UPDATE of that row with <c>WHERE Version=@orig</c>, so a concurrent bump from a replace-all
    ///     editor would otherwise surface as an unhandled <see cref="DbUpdateConcurrencyException" /> →
    ///     500 (issue #253 / #269). Phase-1 semantics for a missing <c>If-Match</c> is <b>force-write</b>,
-    ///     so on a concurrency failure we adopt the stored token as both original (the retry's WHERE then
-    ///     matches) and current (so we don't revert the concurrent bump) and retry — a client-wins merge
-    ///     scoped to the token; our own modified scalars still win. Bounded to avoid a livelock; if the row
+    ///     so on a concurrency failure we rebase onto the stored token: original becomes the stored value
+    ///     (the retry's WHERE then matches) and current becomes stored + our pending delta (a bumper's ++
+    ///     still advances the ETag past the concurrent writer's value — #269 rotation; a non-bumper adopts
+    ///     it unchanged) and retry; our own modified scalars still win. Bounded to avoid a livelock; if the row
    ///     was deleted out from under us, that's a genuine conflict and rethrows.
    /// </summary>
    public static async Task<int> SaveChangesForcingVersion(
@@ -48,9 +49,16 @@ public static class ConcurrencyExtensions
                    }

                    PropertyEntry version = entry.Property(nameof(IVersionedAggregate.Version));
-                    object currentVersion = databaseValues[nameof(IVersionedAggregate.Version)]!;
-                    version.OriginalValue = currentVersion;
-                    version.CurrentValue = currentVersion;
+                    int dbVersion = (int)databaseValues[nameof(IVersionedAggregate.Version)]!;
+
+                    // Rebase our pending delta on top of the stored token instead of adopting it verbatim:
+                    // a Version-bumping sibling (pending current = original + 1) must still advance the
+                    // ETag PAST the concurrent writer's value, or an editor holding that writer's ETag is
+                    // never invalidated by our change (#269 rotation silently lost under race). Non-bumpers
+                    // (delta 0, e.g. ErasePlayoutHistory) still adopt the stored token unchanged.
+                    int pendingDelta = (int)version.CurrentValue! - (int)version.OriginalValue!;
+                    version.OriginalValue = dbVersion;
+                    version.CurrentValue = dbVersion + pendingDelta;
                    resolvedAny = true;
                }

@@ -15,6 +15,7 @@
        <PackageReference Include="MediatR" />
        <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" />
        <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
+        <PackageReference Include="Microsoft.Extensions.Identity.Core" />
        <PackageReference Include="Newtonsoft.Json" />
        <PackageReference Include="Serilog.Formatting.Compact.Reader" />
        <PackageReference Include="WebMarkupMin.Core" />
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Core.Errors;
 using ErsatzTV.Core.FFmpeg;
@@ -139,7 +139,7 @@ public class UpdateFFmpegProfileHandler(IDbContextFactory<TvContext> dbContextFa
        TvContext dbContext,
        UpdateFFmpegProfile updateFFmpegProfile)
    {
-        if (updateFFmpegProfile.Name.Length > 50)
+        if (string.IsNullOrWhiteSpace(updateFFmpegProfile.Name) || updateFFmpegProfile.Name.Length > 50)
        {
            return BaseError.New($"FFmpeg profile name \"{updateFFmpegProfile.Name}\" is invalid");
        }
@@ -3,6 +3,6 @@ using ErsatzTV.Core.Domain;

 namespace ErsatzTV.Application.Images;

-public record GetCachedImagePath(string FileName, ArtworkKind ArtworkKind, string ContentType, int? MaxHeight = null)
+public record GetCachedImagePath(string FileName, ArtworkKind ArtworkKind, int? MaxHeight = null)
    : IRequest<
        Either<BaseError, CachedImagePathViewModel>>;
@@ -1,6 +1,7 @@
 using CliWrap;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Images;
 using ErsatzTV.Core.Interfaces.FFmpeg;
 using ErsatzTV.Core.Interfaces.Images;
 using ErsatzTV.Core.Interfaces.Repositories;
@@ -95,9 +96,13 @@ public class
            }
            else
            {
-                mimeType = !string.IsNullOrWhiteSpace(request.ContentType)
-                    ? request.ContentType
-                    : MimeTypes.GetMimeTypeFromFile(cachePath).Name;
+                // Always derive the type from the stored file — never from a client-supplied value
+                // (issue #283 — the old ?contentType= reflection was the stored-XSS sink). Clamp the
+                // sniffed type to the image allow-list so a file whose bytes are not an accepted image
+                // (a legacy cache entry poisoned before the upload sniff landed, or a hypothetical
+                // polyglot) is served as a non-renderable download, never as HTML/script.
+                string sniffed = MimeTypes.GetMimeTypeFromFile(cachePath)?.Name;
+                mimeType = ImageContentTypes.IsAccepted(sniffed) ? sniffed : "application/octet-stream";
            }

            return new CachedImagePathViewModel(cachePath, mimeType);
@@ -22,7 +22,7 @@ public abstract class CallLibraryScannerHandler<TRequest>(
    IRuntimeInfo runtimeInfo,
    ILogger logger)
 {
-    protected static string GetBaseUrl(Guid scanId) => $"http://localhost:{Settings.UiPort}/api/scan/{scanId}";
+    protected static string GetBaseUrl(Guid scanId) => $"http://localhost:{Settings.UiPort}/api/v1/scan/{scanId}";

    protected async Task<Either<BaseError, string>> PerformScan(
        ScanParameters parameters,
@@ -42,17 +42,28 @@ public class AddArtistToCollectionHandler :

    private async Task<Unit> ApplyAddArtistRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.Artist);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.Artist.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Artist.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.Artist);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Artist.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -44,17 +44,28 @@ public class AddEpisodeToCollectionHandler :

    private async Task<Unit> ApplyAddTelevisionEpisodeRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.Episode);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.Episode.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Episode.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.Episode);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Episode.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Infrastructure.Data;
 using ErsatzTV.Infrastructure.Extensions;
@@ -15,10 +15,10 @@ public class AddEpisodeToPlaylistHandler(IDbContextFactory<TvContext> dbContextF
    {
        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
        Validation<BaseError, Parameters> validation = await Validate(dbContext, request, cancellationToken);
-        return await validation.Apply(parameters => ApplyAddEpisodeRequest(dbContext, parameters));
+        return await validation.Apply(parameters => ApplyAddEpisodeRequest(dbContext, parameters, cancellationToken));
    }

-    private static async Task<Unit> ApplyAddEpisodeRequest(TvContext dbContext, Parameters parameters)
+    private static async Task<Unit> ApplyAddEpisodeRequest(TvContext dbContext, Parameters parameters, CancellationToken cancellationToken)
    {
        int index = parameters.Playlist.Items.Count > 0 ? parameters.Playlist.Items.Max(i => i.Index) + 1 : 0;

@@ -36,7 +36,7 @@ public class AddEpisodeToPlaylistHandler(IDbContextFactory<TvContext> dbContextF
        // Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
        parameters.Playlist.Version++;

-        await dbContext.SaveChangesAsync();
+        await dbContext.SaveChangesForcingVersion(cancellationToken);
        return Unit.Default;
    }

@@ -41,17 +41,28 @@ public class AddImageToCollectionHandler : IRequestHandler<AddImageToCollection,

    private async Task<Unit> ApplyAddImageRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.Image);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.Image.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Image.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.Image);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Image.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -73,24 +73,35 @@ public class AddItemsToCollectionHandler :
            .ToList();

        var toAddIds = allItems.Where(item => collection.MediaItems.All(mi => mi.Id != item)).ToList();
+
+        // No-op when every requested item is already a member: don't rotate the ETag or fan out
+        // rebuilds for an idempotent re-add — #269.
+        if (toAddIds.Count == 0)
+        {
+            return Unit.Default;
+        }
+
        List<MediaItem> toAdd = await dbContext.MediaItems
            .Filter(mi => toAddIds.Contains(mi.Id))
            .ToListAsync(cancellationToken);

        collection.MediaItems.AddRange(toAdd);

-        if (await dbContext.SaveChangesAsync(cancellationToken) > 0)
-        {
-            // post-commit side effect runs on CancellationToken.None so a late request cancellation
-            // can't abort it after the commit landed (#254)
-            await _searchChannel.WriteAsync(new ReindexMediaItems(toAddIds.ToArray()), CancellationToken.None);
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a).
+        collection.Version++;
+        await dbContext.SaveChangesForcingVersion(cancellationToken);

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(request.CollectionId))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
-            }
+        // post-commit side effect runs on CancellationToken.None so a late request cancellation
+        // can't abort it after the commit landed (#254)
+        await _searchChannel.WriteAsync(new ReindexMediaItems(toAddIds.ToArray()), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(request.CollectionId))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Core.Interfaces.Repositories;
 using ErsatzTV.Infrastructure.Data;
@@ -72,7 +72,7 @@ public class AddItemsToPlaylistHandler : IRequestHandler<AddItemsToPlaylist, Eit
        // Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
        playlist.Version++;

-        await dbContext.SaveChangesAsync(cancellationToken);
+        await dbContext.SaveChangesForcingVersion(cancellationToken);

        return Unit.Default;
    }
@@ -42,17 +42,28 @@ public class AddMediaItemToCollectionHandler :

    private async Task<Unit> ApplyAddMediaItemRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.MediaItem);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.MediaItem.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.MediaItem.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.MediaItem);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.MediaItem.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -42,17 +42,28 @@ public class AddMovieToCollectionHandler :

    private async Task<Unit> ApplyAddMovieRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.Movie);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.Movie.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Movie.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.Movie);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Movie.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Infrastructure.Data;
 using ErsatzTV.Infrastructure.Extensions;
@@ -15,10 +15,10 @@ public class AddMovieToPlaylistHandler(IDbContextFactory<TvContext> dbContextFac
    {
        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
        Validation<BaseError, Parameters> validation = await Validate(dbContext, request, cancellationToken);
-        return await validation.Apply(parameters => ApplyAddMovieRequest(dbContext, parameters));
+        return await validation.Apply(parameters => ApplyAddMovieRequest(dbContext, parameters, cancellationToken));
    }

-    private static async Task<Unit> ApplyAddMovieRequest(TvContext dbContext, Parameters parameters)
+    private static async Task<Unit> ApplyAddMovieRequest(TvContext dbContext, Parameters parameters, CancellationToken cancellationToken)
    {
        int index = parameters.Playlist.Items.Count > 0 ? parameters.Playlist.Items.Max(i => i.Index) + 1 : 0;

@@ -36,7 +36,7 @@ public class AddMovieToPlaylistHandler(IDbContextFactory<TvContext> dbContextFac
        // Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
        parameters.Playlist.Version++;

-        await dbContext.SaveChangesAsync();
+        await dbContext.SaveChangesForcingVersion(cancellationToken);
        return Unit.Default;
    }

@@ -44,17 +44,28 @@ public class AddMusicVideoToCollectionHandler :

    private async Task<Unit> ApplyAddMusicVideoRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.MusicVideo);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.MusicVideo.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.MusicVideo.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.MusicVideo);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.MusicVideo.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -44,17 +44,28 @@ public class AddOtherVideoToCollectionHandler :

    private async Task<Unit> ApplyAddOtherVideoRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.OtherVideo);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.OtherVideo.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.OtherVideo.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.OtherVideo);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.OtherVideo.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -42,17 +42,28 @@ public class AddSeasonToCollectionHandler :

    private async Task<Unit> ApplyAddSeasonRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.Season);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.Season.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Season.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.Season);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Season.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Infrastructure.Data;
 using ErsatzTV.Infrastructure.Extensions;
@@ -15,10 +15,10 @@ public class AddSeasonToPlaylistHandler(IDbContextFactory<TvContext> dbContextFa
    {
        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
        Validation<BaseError, Parameters> validation = await Validate(dbContext, request, cancellationToken);
-        return await validation.Apply(parameters => ApplyAddSeasonRequest(dbContext, parameters));
+        return await validation.Apply(parameters => ApplyAddSeasonRequest(dbContext, parameters, cancellationToken));
    }

-    private static async Task<Unit> ApplyAddSeasonRequest(TvContext dbContext, Parameters parameters)
+    private static async Task<Unit> ApplyAddSeasonRequest(TvContext dbContext, Parameters parameters, CancellationToken cancellationToken)
    {
        int index = parameters.Playlist.Items.Count > 0 ? parameters.Playlist.Items.Max(i => i.Index) + 1 : 0;

@@ -36,7 +36,7 @@ public class AddSeasonToPlaylistHandler(IDbContextFactory<TvContext> dbContextFa
        // Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
        parameters.Playlist.Version++;

-        await dbContext.SaveChangesAsync();
+        await dbContext.SaveChangesForcingVersion(cancellationToken);
        return Unit.Default;
    }

@@ -42,17 +42,28 @@ public class AddShowToCollectionHandler :

    private async Task<Unit> ApplyAddShowRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.Show);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.Show.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Show.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.Show);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Show.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Infrastructure.Data;
 using ErsatzTV.Infrastructure.Extensions;
@@ -15,10 +15,10 @@ public class AddShowToPlaylistHandler(IDbContextFactory<TvContext> dbContextFact
    {
        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
        Validation<BaseError, Parameters> validation = await Validate(dbContext, request, cancellationToken);
-        return await validation.Apply(parameters => ApplyAddShowRequest(dbContext, parameters));
+        return await validation.Apply(parameters => ApplyAddShowRequest(dbContext, parameters, cancellationToken));
    }

-    private static async Task<Unit> ApplyAddShowRequest(TvContext dbContext, Parameters parameters)
+    private static async Task<Unit> ApplyAddShowRequest(TvContext dbContext, Parameters parameters, CancellationToken cancellationToken)
    {
        int index = parameters.Playlist.Items.Count > 0 ? parameters.Playlist.Items.Max(i => i.Index) + 1 : 0;

@@ -36,7 +36,7 @@ public class AddShowToPlaylistHandler(IDbContextFactory<TvContext> dbContextFact
        // Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
        parameters.Playlist.Version++;

-        await dbContext.SaveChangesAsync();
+        await dbContext.SaveChangesForcingVersion(cancellationToken);
        return Unit.Default;
    }

@@ -42,17 +42,28 @@ public class AddSongToCollectionHandler :

    private async Task<Unit> ApplyAddSongRequest(TvContext dbContext, Parameters parameters)
    {
-        parameters.Collection.MediaItems.Add(parameters.Song);
-        if (await dbContext.SaveChangesAsync() > 0)
+        // No-op on an idempotent re-add: don't rotate the ETag or fan out rebuilds for an item that is
+        // already a member (also avoids a duplicate CollectionItem row) — #269.
+        if (parameters.Collection.MediaItems.Any(mi => mi.Id == parameters.Song.Id))
        {
-            await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Song.Id]));
+            return Unit.Default;
+        }

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository
-                         .PlayoutIdsUsingCollection(parameters.Collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
-            }
+        parameters.Collection.MediaItems.Add(parameters.Song);
+
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this add takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a). Post-commit enqueues run on CancellationToken.None.
+        parameters.Collection.Version++;
+        await dbContext.SaveChangesForcingVersion(CancellationToken.None);
+
+        await _searchChannel.WriteAsync(new ReindexMediaItems([parameters.Song.Id]), CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository
+                     .PlayoutIdsUsingCollection(parameters.Collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -35,7 +35,7 @@ public class CreatePlaylistHandler(IDbContextFactory<TvContext> dbContextFactory
        TvContext dbContext,
        CreatePlaylist request)
    {
-        if (request.Name.Length > 50)
+        if (string.IsNullOrWhiteSpace(request.Name) || request.Name.Length > 50)
        {
            return BaseError.New($"Playlist name \"{request.Name}\" is invalid");
        }
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Core.Errors;
 using ErsatzTV.Core.Interfaces.Search;
@@ -34,7 +34,7 @@ public class DeleteCollectionHandler : IRequestHandler<DeleteCollection, Either<
    private async Task<Unit> DoDeletion(TvContext dbContext, Collection collection, CancellationToken cancellationToken)
    {
        dbContext.Collections.Remove(collection);
-        await dbContext.SaveChangesAsync(cancellationToken);
+        await dbContext.SaveChangesForcingVersion(cancellationToken);
        _searchTargets.SearchTargetsChanged();
        return Unit.Default;
    }
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Core.Interfaces.Search;
 using ErsatzTV.Infrastructure.Data;
@@ -37,7 +37,7 @@ public class DeleteMultiCollectionHandler : IRequestHandler<DeleteMultiCollectio
        CancellationToken cancellationToken)
    {
        dbContext.MultiCollections.Remove(multiCollection);
-        await dbContext.SaveChangesAsync(cancellationToken);
+        await dbContext.SaveChangesForcingVersion(cancellationToken);
        _searchTargets.SearchTargetsChanged();
        return Unit.Default;
    }
@@ -24,7 +24,7 @@ public class DeletePlaylistHandler(IDbContextFactory<TvContext> dbContextFactory
            }

            dbContext.Playlists.Remove(playlist);
-            await dbContext.SaveChangesAsync(cancellationToken);
+            await dbContext.SaveChangesForcingVersion(cancellationToken);
        }

        return maybePlaylist.Match(
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Infrastructure.Data;
 using ErsatzTV.Infrastructure.Extensions;
@@ -27,7 +27,7 @@ public class DeleteRerunCollectionHandler(IDbContextFactory<TvContext> dbContext
        CancellationToken cancellationToken)
    {
        dbContext.RerunCollections.Remove(rerunCollection);
-        await dbContext.SaveChangesAsync(cancellationToken);
+        await dbContext.SaveChangesForcingVersion(cancellationToken);
        return Unit.Default;
    }

@@ -59,21 +59,30 @@ public class RemoveItemsFromCollectionHandler : IRequestHandler<RemoveItemsFromC
            return new NotFoundError("Collection item does not exist.");
        }

+        // No-op when nothing is actually removed: don't rotate the ETag or fan out rebuilds — #269.
+        if (itemsToRemove.Count == 0)
+        {
+            return Unit.Default;
+        }
+
        itemsToRemove.ForEach(m => collection.MediaItems.Remove(m));

-        if (itemsToRemove.Count != 0 && await dbContext.SaveChangesAsync(cancellationToken) > 0)
-        {
-            // post-commit side effect runs on CancellationToken.None so a late request cancellation
-            // can't abort it after the commit landed (#254)
-            await _searchChannel.WriteAsync(
-                new ReindexMediaItems(itemsToRemove.Select(mi => mi.Id).ToArray()),
-                CancellationToken.None);
+        // Rotate the collection ETag so an open custom-order editor's If-Match invalidates (#269);
+        // force-write past a concurrent replace-all Version bump — this remove takes no If-Match, so a
+        // benign race must not 500 (#253/#269 §7a).
+        collection.Version++;
+        await dbContext.SaveChangesForcingVersion(cancellationToken);

-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository.PlayoutIdsUsingCollection(collection.Id))
-            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
-            }
+        // post-commit side effect runs on CancellationToken.None so a late request cancellation
+        // can't abort it after the commit landed (#254)
+        await _searchChannel.WriteAsync(
+            new ReindexMediaItems(itemsToRemove.Select(mi => mi.Id).ToArray()),
+            CancellationToken.None);
+
+        // refresh all playouts that use this collection
+        foreach (int playoutId in await _mediaCollectionRepository.PlayoutIdsUsingCollection(collection.Id))
+        {
+            await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
        }

        return Unit.Default;
@@ -6,5 +6,5 @@ public record ReplacePlaylistItems(
    int PlaylistId,
    string Name,
    List<ReplacePlaylistItem> Items,
-    Option<int> ExpectedVersion = default)
+    Option<Seq<int>> ExpectedVersions = default)
    : IRequest<Either<BaseError, List<PlaylistItemViewModel>>>;
@@ -22,7 +22,7 @@ public class ReplacePlaylistItemsHandler(IDbContextFactory<TvContext> dbContextF
        // LanguageExtensions.ToEither joins the Seq<BaseError> to a single BaseError (the native
        // Validation.ToEither() would keep Seq and is called explicitly here to avoid that shadow).
        Either<BaseError, Playlist> validated = LanguageExtensions.ToEither(validation)
-            .Bind(playlist => playlist.CheckVersion(request.ExpectedVersion));
+            .Bind(playlist => playlist.CheckVersion(request.ExpectedVersions));

        return await validated.Match(
            Right: playlist => Persist(dbContext, request, playlist, cancellationToken),
@@ -1,10 +1,10 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;

 namespace ErsatzTV.Application.MediaCollections;

 public record UpdateCollectionCustomOrder(
    int CollectionId,
    List<MediaItemCustomOrder> MediaItemCustomOrders,
-    Option<int> ExpectedVersion = default) : IRequest<Either<BaseError, Unit>>;
+    Option<Seq<int>> ExpectedVersions = default) : IRequest<Either<BaseError, Unit>>;

 public record MediaItemCustomOrder(int MediaItemId, int CustomIndex);
@@ -1,4 +1,4 @@
-using System.Threading.Channels;
+using System.Threading.Channels;
 using ErsatzTV.Application.Playouts;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
@@ -36,7 +36,7 @@ public class UpdateCollectionCustomOrderHandler : IRequestHandler<UpdateCollecti
        // Optimistic-concurrency check as a standalone Either AFTER validation, never via Apply (which
        // Join()s the error Seq and would flatten PreconditionFailedError to a 422) — issue #253 §7a.
        Either<BaseError, Collection> validated = LanguageExtensions.ToEither(validation)
-            .Bind(c => c.CheckVersion(request.ExpectedVersion));
+            .Bind(c => c.CheckVersion(request.ExpectedVersions));

        return await validated.Match(
            Right: c => ApplyUpdateRequest(dbContext, c, request, cancellationToken),
@@ -59,17 +59,25 @@ public class UpdateCollectionHandler : IRequestHandler<UpdateCollection, Either<
            c.UseCustomPlaybackOrder = useCustomPlaybackOrder;
        }

-        // Force-write past a concurrent Version bump from the custom-order editor (this name/flag writer
-        // doesn't participate in If-Match, so the active token must not 500 a benign race) — #253/#269.
-        if (await dbContext.SaveChangesForcingVersion(cancellationToken) > 0 && request.UseCustomPlaybackOrder.IsSome)
+        // Only rotate the ETag when the name/flag actually changed — a no-op re-submit must not bump the
+        // Version (spurious rebuilds / editor invalidation) — #269. When it did change, force-write past a
+        // concurrent bump from the custom-order editor (this writer takes no If-Match, so a benign race
+        // must not 500) — #253/#269 §7a.
+        if (dbContext.ChangeTracker.HasChanges())
        {
-            // post-commit side effect runs on CancellationToken.None so a late request cancellation
-            // can't abort it after the commit landed (#254)
-            // refresh all playouts that use this collection
-            foreach (int playoutId in await _mediaCollectionRepository.PlayoutIdsUsingCollection(
-                         request.CollectionId))
+            c.Version++;
+            await dbContext.SaveChangesForcingVersion(cancellationToken);
+
+            if (request.UseCustomPlaybackOrder.IsSome)
            {
-                await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
+                // post-commit side effect runs on CancellationToken.None so a late request cancellation
+                // can't abort it after the commit landed (#254)
+                // refresh all playouts that use this collection
+                foreach (int playoutId in await _mediaCollectionRepository.PlayoutIdsUsingCollection(
+                             request.CollectionId))
+                {
+                    await _channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
+                }
            }
        }

@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;

 namespace ErsatzTV.Application.MediaCollections;
@@ -13,4 +13,4 @@ public record UpdateMultiCollection(
    int MultiCollectionId,
    string Name,
    List<UpdateMultiCollectionItem> Items,
-    Option<int> ExpectedVersion = default) : IRequest<Either<BaseError, Unit>>;
+    Option<Seq<int>> ExpectedVersions = default) : IRequest<Either<BaseError, Unit>>;
@@ -1,4 +1,4 @@
-using System.Threading.Channels;
+using System.Threading.Channels;
 using ErsatzTV.Application.Playouts;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
@@ -40,7 +40,7 @@ public class UpdateMultiCollectionHandler : IRequestHandler<UpdateMultiCollectio
        // Optimistic-concurrency check as a standalone Either AFTER validation, never via Apply (which
        // Join()s the error Seq and would flatten PreconditionFailedError to a 422) — issue #253 §7a.
        Either<BaseError, MultiCollection> validated = LanguageExtensions.ToEither(validation)
-            .Bind(c => c.CheckVersion(request.ExpectedVersion));
+            .Bind(c => c.CheckVersion(request.ExpectedVersions));

        return await validated.Match(
            Right: c => ApplyUpdateRequest(dbContext, c, request, cancellationToken),
@@ -1,4 +1,4 @@
-using ErsatzTV.Application.MediaItems;
+using ErsatzTV.Application.MediaItems;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;

@@ -14,5 +14,5 @@ public record UpdateRerunCollection(
    NamedMediaItemViewModel MediaItem,
    PlaybackOrder FirstRunPlaybackOrder,
    PlaybackOrder RerunPlaybackOrder,
-    Option<int> ExpectedVersion = default)
+    Option<Seq<int>> ExpectedVersions = default)
    : IRequest<Either<BaseError, Unit>>;
@@ -1,4 +1,4 @@
-using System.Threading.Channels;
+using System.Threading.Channels;
 using ErsatzTV.Application.Playouts;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
@@ -26,7 +26,7 @@ public class UpdateRerunCollectionHandler(
        // Optimistic-concurrency check as a standalone Either AFTER validation, never via Apply (which
        // Join()s the error Seq and would flatten PreconditionFailedError to a 422) — issue #253 §7a.
        Either<BaseError, RerunCollection> validated = LanguageExtensions.ToEither(validation)
-            .Bind(c => c.CheckVersion(request.ExpectedVersion));
+            .Bind(c => c.CheckVersion(request.ExpectedVersions));

        return await validated.Match(
            Right: c => ApplyUpdateRequest(dbContext, c, request, cancellationToken),
@@ -0,0 +1,5 @@
+using ErsatzTV.Core.Api.MediaSources;
+
+namespace ErsatzTV.Application.MediaSources;
+
+public record GetCollectionsScanStatus : IRequest<List<CollectionsScanStatusResponseModel>>;
@@ -0,0 +1,38 @@
+#nullable enable
+using ErsatzTV.Core.Api.MediaSources;
+using ErsatzTV.Core.Interfaces.Locking;
+
+namespace ErsatzTV.Application.MediaSources;
+
+// Reports which media-source families currently hold their external-collections scan lock. The lock
+// is the running scan (the scan-collections controllers acquire it before enqueueing and the scanner
+// releases it on completion), so IEntityLocker is the authoritative source — analogous to how
+// GetLibraryScanStatus reads IScannerProxyService.GetActiveScans(). Collections locks are family-global,
+// so this returns at most one entry per family, and only for families actively scanning.
+public class GetCollectionsScanStatusHandler(IEntityLocker entityLocker)
+    : IRequestHandler<GetCollectionsScanStatus, List<CollectionsScanStatusResponseModel>>
+{
+    public Task<List<CollectionsScanStatusResponseModel>> Handle(
+        GetCollectionsScanStatus request,
+        CancellationToken cancellationToken)
+    {
+        var result = new List<CollectionsScanStatusResponseModel>();
+
+        if (entityLocker.ArePlexCollectionsLocked())
+        {
+            result.Add(new CollectionsScanStatusResponseModel("plex"));
+        }
+
+        if (entityLocker.AreJellyfinCollectionsLocked())
+        {
+            result.Add(new CollectionsScanStatusResponseModel("jellyfin"));
+        }
+
+        if (entityLocker.AreEmbyCollectionsLocked())
+        {
+            result.Add(new CollectionsScanStatusResponseModel("emby"));
+        }
+
+        return Task.FromResult(result);
+    }
+}
@@ -1,4 +1,4 @@
-using System.IO.Abstractions;
+using System.IO.Abstractions;
 using System.Threading.Channels;
 using ErsatzTV.Application.Channels;
 using ErsatzTV.Core;
@@ -39,7 +39,7 @@ public class DeletePlayoutHandler(
            }

            dbContext.Playouts.Remove(playout);
-            await dbContext.SaveChangesAsync(cancellationToken);
+            await dbContext.SaveChangesForcingVersion(cancellationToken);

            // post-commit side effects run on CancellationToken.None so a late request cancellation can't
            // abort them after the delete committed (#254)
@@ -5,5 +5,5 @@ namespace ErsatzTV.Application.Playouts;
 public record ReplacePlayoutAlternateScheduleItems(
    int PlayoutId,
    List<ReplacePlayoutAlternateSchedule> Items,
-    Option<int> ExpectedVersion = default)
+    Option<Seq<int>> ExpectedVersions = default)
    : IRequest<Either<BaseError, Unit>>;
@@ -44,7 +44,7 @@ public class ReplacePlayoutAlternateScheduleItemsHandler(
                // PreconditionFailedError (→ 412) before any mutation. Introduced as a standalone Either,
                // and returned directly (a value, not a throw) so it escapes the catch(Exception) below
                // rather than being reshaped into a bare 422 (§9/H1).
-                Either<BaseError, Playout> versionCheck = playout.CheckVersion(request.ExpectedVersion);
+                Either<BaseError, Playout> versionCheck = playout.CheckVersion(request.ExpectedVersions);
                if (versionCheck.IsLeft)
                {
                    return versionCheck.Match<Either<BaseError, Unit>>(
@@ -40,10 +40,14 @@ public class
    {
        playout.ScheduleFile = request.ScheduleFile;

-        // Force-write past a concurrent Version bump from a replace-all editor (schedule-file writer
-        // doesn't participate in If-Match, so an active token must not 500 a benign race) — #253/#269.
-        if (await dbContext.SaveChangesForcingVersion(cancellationToken) > 0)
+        // Rotate the playout ETag only when the schedule-file actually changed — a no-op re-submit must
+        // not bump (#269). When it changed, force-write past a concurrent Version bump from a replace-all
+        // editor (this writer takes no If-Match, so a benign race must not 500) — #253/#269 §7a.
+        if (dbContext.ChangeTracker.HasChanges())
        {
+            playout.Version++;
+            await dbContext.SaveChangesForcingVersion(cancellationToken);
+
            // post-commit side effect runs on CancellationToken.None so a late request cancellation
            // can't abort it after the commit landed (#254)
            await _workerChannel.WriteAsync(new RefreshChannelData(playout.Channel.Number), CancellationToken.None);
@@ -35,9 +35,15 @@ public class UpdatePlayoutHandler : IRequestHandler<UpdatePlayout, Either<BaseEr
            playout.DailyRebuildTime = dailyRebuildTime;
        }

-        // Force-write past a concurrent Version bump from a replace-all editor (this settings writer
-        // doesn't participate in If-Match, so a missing token = force-write, not a 500) — #253/#269.
-        await dbContext.SaveChangesForcingVersion(cancellationToken);
+        // Rotate the playout ETag only when the daily-rebuild-time actually changed — a no-op re-submit
+        // must not bump (#269). When it changed, force-write past a concurrent Version bump from a
+        // replace-all editor (this settings writer takes no If-Match, so a benign race must not 500) —
+        // #253/#269 §7a.
+        if (dbContext.ChangeTracker.HasChanges())
+        {
+            playout.Version++;
+            await dbContext.SaveChangesForcingVersion(cancellationToken);
+        }

        return new PlayoutNameViewModel(
            playout.Id,
@@ -35,10 +35,14 @@ public class
    {
        playout.ScheduleFile = request.ScheduleFile;

-        // Force-write past a concurrent Version bump from a replace-all editor (schedule-file writer
-        // doesn't participate in If-Match, so an active token must not 500 a benign race) — #253/#269.
-        if (await dbContext.SaveChangesForcingVersion(cancellationToken) > 0)
+        // Rotate the playout ETag only when the schedule-file actually changed — a no-op re-submit must
+        // not bump (#269). When it changed, force-write past a concurrent Version bump from a replace-all
+        // editor (this writer takes no If-Match, so a benign race must not 500) — #253/#269 §7a.
+        if (dbContext.ChangeTracker.HasChanges())
        {
+            playout.Version++;
+            await dbContext.SaveChangesForcingVersion(cancellationToken);
+
            // post-commit side effect runs on CancellationToken.None so a late request cancellation
            // can't abort it after the commit landed (#254)
            await workerChannel.WriteAsync(new RefreshChannelData(playout.Channel.Number), CancellationToken.None);
@@ -40,10 +40,14 @@ public class
    {
        playout.ScheduleFile = request.ScheduleFile;

-        // Force-write past a concurrent Version bump from a replace-all editor (schedule-file writer
-        // doesn't participate in If-Match, so an active token must not 500 a benign race) — #253/#269.
-        if (await dbContext.SaveChangesForcingVersion(cancellationToken) > 0)
+        // Rotate the playout ETag only when the schedule-file actually changed — a no-op re-submit must
+        // not bump (#269). When it changed, force-write past a concurrent Version bump from a replace-all
+        // editor (this writer takes no If-Match, so a benign race must not 500) — #253/#269 §7a.
+        if (dbContext.ChangeTracker.HasChanges())
        {
+            playout.Version++;
+            await dbContext.SaveChangesForcingVersion(cancellationToken);
+
            // post-commit side effect runs on CancellationToken.None so a late request cancellation
            // can't abort it after the commit landed (#254)
            await _workerChannel.WriteAsync(new RefreshChannelData(playout.Channel.Number), CancellationToken.None);
@@ -0,0 +1,3 @@
+namespace ErsatzTV.Application.Playouts;
+
+public record GetPlayoutIdByChannelId(int ChannelId) : IRequest<Option<int>>;
@@ -0,0 +1,18 @@
+using ErsatzTV.Infrastructure.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace ErsatzTV.Application.Playouts;
+
+public class GetPlayoutIdByChannelIdHandler(IDbContextFactory<TvContext> dbContextFactory)
+    : IRequestHandler<GetPlayoutIdByChannelId, Option<int>>
+{
+    public async Task<Option<int>> Handle(GetPlayoutIdByChannelId request, CancellationToken cancellationToken)
+    {
+        await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
+        return await dbContext.Playouts
+            .Filter(p => p.Channel.Id == request.ChannelId)
+            .Map(p => p.Id)
+            .ToListAsync(cancellationToken)
+            .Map(list => list.HeadOrNone());
+    }
+}
@@ -1,4 +1,4 @@
-using System.Threading.Channels;
+using System.Threading.Channels;
 using ErsatzTV.Application.Playouts;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
@@ -55,7 +55,7 @@ public class AddProgramScheduleItemHandler : ProgramScheduleItemCommandBase,
        // bump the optimistic-concurrency token so this config edit rotates other clients' ETags (#253)
        programSchedule.Version++;

-        await dbContext.SaveChangesAsync(cancellationToken);
+        await dbContext.SaveChangesForcingVersion(cancellationToken);

        // refresh any playouts that use this schedule
        // post-commit side effect runs on CancellationToken.None so a late request cancellation
@@ -1,4 +1,4 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Core.Errors;
 using ErsatzTV.Infrastructure.Data;
@@ -24,15 +24,18 @@ public class DeleteProgramScheduleHandler : IRequestHandler<DeleteProgramSchedul
            request,
            cancellationToken);
        return await maybeProgramSchedule.Match(
-            Some: programSchedule => DoDeletion(dbContext, programSchedule).Map(Right<BaseError, Unit>),
+            Some: programSchedule => DoDeletion(dbContext, programSchedule, cancellationToken).Map(Right<BaseError, Unit>),
            None: () => Task.FromResult<Either<BaseError, Unit>>(
                new NotFoundError($"ProgramSchedule {request.ProgramScheduleId} does not exist.")));
    }

-    private static Task<Unit> DoDeletion(TvContext dbContext, ProgramSchedule programSchedule)
+    private static Task<Unit> DoDeletion(
+        TvContext dbContext,
+        ProgramSchedule programSchedule,
+        CancellationToken cancellationToken)
    {
        dbContext.ProgramSchedules.Remove(programSchedule);
-        return dbContext.SaveChangesAsync().ToUnit();
+        return dbContext.SaveChangesForcingVersion(cancellationToken).ToUnit();
    }

    private static Task<Option<ProgramSchedule>> ProgramScheduleMustExist(
@@ -38,7 +38,7 @@ public class DeleteProgramScheduleItemHandler(
        // bump the optimistic-concurrency token so this config edit rotates other clients' ETags (#253)
        item.ProgramSchedule.Version++;

-        await dbContext.SaveChangesAsync(cancellationToken);
+        await dbContext.SaveChangesForcingVersion(cancellationToken);

        // post-commit side effect runs on CancellationToken.None so a late request cancellation
        // can't abort it after the commit landed (#254)
@@ -1,10 +1,11 @@
-using ErsatzTV.Core;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Core.Scheduling;

 namespace ErsatzTV.Application.ProgramSchedules;

 public record ReplaceProgramScheduleItem(
+    int? Id,
    int Index,
    StartType StartType,
    TimeSpan? StartTime,
@@ -47,5 +48,5 @@ public record ReplaceProgramScheduleItem(
 public record ReplaceProgramScheduleItems(
    int ProgramScheduleId,
    List<ReplaceProgramScheduleItem> Items,
-    Option<int> ExpectedVersion = default) : IRequest<
+    Option<Seq<int>> ExpectedVersions = default) : IRequest<
    Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>>>;
@@ -1,4 +1,4 @@
-using System.Threading.Channels;
+using System.Threading.Channels;
 using ErsatzTV.Application.Playouts;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
@@ -31,7 +31,7 @@ public class ReplaceProgramScheduleItemsHandler(
                // pipeline (never via Apply) so a PreconditionFailedError survives to a 412 and is not
                // flattened to a generic 422 by Join() (issue #253 / api-conventions §7a).
                Either<BaseError, ProgramSchedule> validated = LanguageExtensions.ToEither(validation)
-                    .Bind(ps => ps.CheckVersion(request.ExpectedVersion));
+                    .Bind(ps => ps.CheckVersion(request.ExpectedVersions));

                return await validated.Match(
                    Right: ps => PersistItems(dbContext, request, ps, cancellationToken),
@@ -48,16 +48,22 @@ public class ReplaceProgramScheduleItemsHandler(
        ProgramSchedule programSchedule,
        CancellationToken cancellationToken)
    {
-        // Positional in-place reconcile (rather than delete-and-reinsert): a schedule item owns the
-        // persisted fill-group/shuffle enumerator state via PlayoutScheduleItemFillGroupIndex, whose
+        // In-place reconcile (rather than delete-and-reinsert): a schedule item owns persisted
+        // fill-group/shuffle enumerator state via PlayoutScheduleItemFillGroupIndex, whose
        // ProgramScheduleItemId FK is OnDelete(Cascade). Removing and re-inserting every item — as the
        // original handler did on every save, including a no-op PUT-back — cascade-deleted that state for
-        // all playouts using the schedule (#252). Reusing the existing item row for the same-typed slot
-        // keeps its id, so the cascade never fires and progression survives. The request DTO carries no
-        // stable item id, so position is the only key available here; true content-aware stable identity
-        // is deferred to the shared concurrency/round-trip contract in #253.
+        // all playouts using the schedule (#252). Reusing the existing item row keeps its id, so the cascade
+        // never fires and progression survives.
+        //
+        // Two reconcile modes (#259):
+        //   * id-based (preferred) — when the client round-trips each existing item's server id, map request
+        //     items to existing rows BY id, so per-child state follows the LOGICAL item across reorders and
+        //     mid-list inserts rather than staying with whatever previously occupied a slot.
+        //   * positional (legacy fallback) — a fully id-less payload keeps the original by-array-position
+        //     reconcile. This preserves today's misattribution on legacy reorders; it is temporary and
+        //     retires with the §7a Phase-2 If-Match flip.
+        // Index (ordering) is always derived from array position; identity (id) is a separate axis.
        var orderedItems = request.Items.OrderBy(i => i.Index).ToList();
-        List<ProgramScheduleItem> existingItems = programSchedule.Items.OrderBy(i => i.Index).ToList();

        // load the watermark/graphics join rows for the existing items so they can be rebuilt in place
        await dbContext.Entry(programSchedule)
@@ -67,39 +73,112 @@ public class ReplaceProgramScheduleItemsHandler(
            .Include(i => i.ProgramScheduleItemGraphicsElements)
            .LoadAsync(cancellationToken);

-        int commonCount = Math.Min(existingItems.Count, orderedItems.Count);
-        for (var i = 0; i < commonCount; i++)
+        List<ProgramScheduleItem> existingItems = programSchedule.Items.ToList();
+        List<int> requestIds = orderedItems.Where(i => i.Id.HasValue).Select(i => i.Id.Value).ToList();
+
+        if (requestIds.Count == 0)
        {
-            ProgramScheduleItem existing = existingItems[i];
-            ProgramScheduleItem built = BuildItem(programSchedule, i, orderedItems[i]);
-            if (existing.GetType() == built.GetType())
+            // ---- positional fallback (verbatim pre-#259 behavior) ----
+            List<ProgramScheduleItem> orderedExisting = existingItems.OrderBy(i => i.Index).ToList();
+            int commonCount = Math.Min(orderedExisting.Count, orderedItems.Count);
+            for (var i = 0; i < commonCount; i++)
            {
-                // same TPT subtype: copy all scalar values in place (BuildItem is the single source of
-                // item construction, so no field is silently dropped) and rebuild the join rows, keeping
-                // the item's id — and with it the fill-group index that would otherwise cascade away.
-                built.Id = existing.Id;
-                dbContext.Entry(existing).CurrentValues.SetValues(built);
-                RebuildChildren(existing, orderedItems[i]);
+                ProgramScheduleItem existing = orderedExisting[i];
+                ProgramScheduleItem built = BuildItem(programSchedule, i, orderedItems[i]);
+                if (existing.GetType() == built.GetType())
+                {
+                    built.Id = existing.Id;
+                    dbContext.Entry(existing).CurrentValues.SetValues(built);
+                    RebuildChildren(existing, orderedItems[i]);
+                }
+                else
+                {
+                    dbContext.Remove(existing);
+                    programSchedule.Items.Add(built);
+                }
            }
-            else
+
+            for (int i = commonCount; i < orderedExisting.Count; i++)
            {
-                // EF can't change a TPT row's type in place; this slot must be replaced (its fill-group
-                // index resets, which is acceptable — the item fundamentally changed).
-                dbContext.Remove(existing);
-                programSchedule.Items.Add(built);
+                dbContext.Remove(orderedExisting[i]);
+            }
+
+            for (int i = commonCount; i < orderedItems.Count; i++)
+            {
+                programSchedule.Items.Add(BuildItem(programSchedule, i, orderedItems[i]));
            }
        }
-
-        // remove surplus existing items
-        for (int i = commonCount; i < existingItems.Count; i++)
+        else
        {
-            dbContext.Remove(existingItems[i]);
-        }
+            // ---- id-based reconcile ----
+            // Guards run HERE (inside PersistItems, after CheckVersion in Handle) so a client that is BOTH
+            // version-stale and id-stale gets 412 (reload signal) — not 422, which reads as a payload bug
+            // (§7c). Both guards persist nothing (plain BaseError → 422).

-        // add surplus incoming items
-        for (int i = commonCount; i < orderedItems.Count; i++)
-        {
-            programSchedule.Items.Add(BuildItem(programSchedule, i, orderedItems[i]));
+            // 7b: a duplicated id would map two request items onto one row (SetValues twice, last-writer-wins,
+            // one item's config silently lost). Always a client bug.
+            int? duplicateId = requestIds.GroupBy(id => id).Where(g => g.Count() > 1).Select(g => (int?)g.Key)
+                .FirstOrDefault();
+            if (duplicateId.HasValue)
+            {
+                return new BaseError($"Schedule item id {duplicateId.Value} appears more than once in the request.");
+            }
+
+            // 7a: an id not belonging to THIS schedule is a stale/foreign identity. Under Phase-1 (a missing
+            // If-Match force-writes) it is a live lost-update signal; inserting-as-new would silently duplicate
+            // the item and return a different id than the client sent. Reject loudly rather than mask it.
+            var existingIds = existingItems.Select(e => e.Id).ToHashSet();
+            foreach (int id in requestIds)
+            {
+                if (!existingIds.Contains(id))
+                {
+                    return new BaseError($"Schedule item id {id} does not belong to this schedule.");
+                }
+            }
+
+            // delete pass: existing rows the request no longer references (their fill-group state cascades —
+            // correct, the logical item is gone)
+            var referencedIds = requestIds.ToHashSet();
+            foreach (ProgramScheduleItem existing in existingItems)
+            {
+                if (!referencedIds.Contains(existing.Id))
+                {
+                    dbContext.Remove(existing);
+                }
+            }
+
+            // match/insert pass in array order (Index = i)
+            var existingById = existingItems.ToDictionary(e => e.Id);
+            for (var i = 0; i < orderedItems.Count; i++)
+            {
+                ReplaceProgramScheduleItem requestItem = orderedItems[i];
+                ProgramScheduleItem built = BuildItem(programSchedule, i, requestItem);
+                if (requestItem.Id.HasValue && existingById.TryGetValue(requestItem.Id.Value, out ProgramScheduleItem existing))
+                {
+                    if (existing.GetType() == built.GetType())
+                    {
+                        // same TPT subtype: copy all scalars in place (BuildItem is the single source of item
+                        // construction, so no field is dropped) and rebuild join rows, keeping the id — and
+                        // with it the fill-group index that would otherwise cascade away. State follows the
+                        // logical item regardless of its new position.
+                        built.Id = existing.Id;
+                        dbContext.Entry(existing).CurrentValues.SetValues(built);
+                        RebuildChildren(existing, requestItem);
+                    }
+                    else
+                    {
+                        // EF can't retype a TPT row in place; replace it. Fill-group state resets and the
+                        // response returns a NEW id (the item fundamentally changed — clients re-sync from it).
+                        dbContext.Remove(existing);
+                        programSchedule.Items.Add(built);
+                    }
+                }
+                else
+                {
+                    // id-less request item → new (unknown ids were already rejected above)
+                    programSchedule.Items.Add(built);
+                }
+            }
        }

        // Unconditional bump: this handler frequently saves with only CHILD changes and no root-scalar
@@ -1,4 +1,4 @@
-using System.Threading.Channels;
+using System.Threading.Channels;
 using ErsatzTV.Application.Playouts;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Domain;
@@ -27,7 +27,7 @@ public class UpdateProgramScheduleHandler(
            Some: async programSchedule =>
            {
                Validation<BaseError, ProgramSchedule> validation = await Validate(dbContext, request, programSchedule, cancellationToken);
-                return await validation.Apply(ps => ApplyUpdateRequest(dbContext, ps, request));
+                return await validation.Apply(ps => ApplyUpdateRequest(dbContext, ps, request, cancellationToken));
            },
            None: () => Task.FromResult<Either<BaseError, UpdateProgramScheduleResult>>(
                new NotFoundError("Schedule does not exist")));
@@ -36,7 +36,8 @@ public class UpdateProgramScheduleHandler(
    private async Task<UpdateProgramScheduleResult> ApplyUpdateRequest(
        TvContext dbContext,
        ProgramSchedule programSchedule,
-        UpdateProgramSchedule request)
+        UpdateProgramSchedule request,
+        CancellationToken cancellationToken)
    {
        // we need to refresh playouts if the playback order or keep multi-episodes has been modified
        bool needToRefreshPlayout =
@@ -54,21 +55,25 @@ public class UpdateProgramScheduleHandler(
        programSchedule.RandomStartPoint = request.RandomStartPoint;
        programSchedule.FixedStartTimeBehavior = request.FixedStartTimeBehavior;

-        // bump the optimistic-concurrency token so this config edit rotates other clients' ETags (#253)
+        // bump the optimistic-concurrency token so this config edit rotates other clients' ETags (#253).
+        // Force-write past a concurrent Version bump (e.g. a parallel schedule-items replace) instead of
+        // surfacing the IsConcurrencyToken guard as an unhandled DbUpdateConcurrencyException → 500 (#269).
        programSchedule.Version++;

-        await dbContext.SaveChangesAsync();
+        await dbContext.SaveChangesForcingVersion(cancellationToken);

        if (needToRefreshPlayout)
        {
+            // post-commit side effect: run the affected-playout query + enqueue on CancellationToken.None
+            // so a late request cancellation can't abort the rebuild after the edit already committed (#254)
            List<int> playoutIds = await dbContext.Playouts
                .Filter(p => p.ProgramScheduleId == programSchedule.Id)
                .Map(p => p.Id)
-                .ToListAsync();
+                .ToListAsync(CancellationToken.None);

            foreach (int playoutId in playoutIds)
            {
-                await channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh));
+                await channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Refresh), CancellationToken.None);
            }
        }

@@ -53,7 +53,7 @@ public class CreateBlockHandler(IDbContextFactory<TvContext> dbContextFactory)
        TvContext dbContext,
        CreateBlock request)
    {
-        if (request.Name.Length > 50)
+        if (string.IsNullOrWhiteSpace(request.Name) || request.Name.Length > 50)
        {
            return BaseError.New($"Block name \"{request.Name}\" is invalid");
        }
--- a/Show More
+++ b/Show More