Three related defects in the `review-verdict/h10` gate, all surfaced by the cross-family review of PR #705. #706 race 1 — a stale run could overwrite a fresher verdict, permanently. The race was reproduced live rather than reasoned about (Gitea 1.25.4): with every other workflow stripped, probe PR #722 showed run 7520 (`opened`) finishing 20s AFTER run 7521 (`synchronize`) started. `pull_request_target` runs for one PR genuinely overlap, older finishing last. The issue proposed serializing with a non-cancelling concurrency group. That is REFUTED by measurement: with the group active, runs 7528/7529 still overlapped and 7528 ended 36s after 7529 began. A first probe appeared to show the group working — a negative control with no `concurrency:` key at all showed the same cancellations, revealing Gitea auto-cancels superseded `push` runs on its own and the probe had measured that, not the group. The auto-cancel does not extend to `pull_request_target`. The fix leaves the runs unserialized and instead makes an overtaken run decline to write: count `change_target_branch` events on the PR timeline at start and again just before the POST, and post nothing if the count moved. The COUNT is the key because the branch NAME is ABA-vulnerable (`main -> S -> main` reads `main` at both ends — how #698 route 1 forged its exemption). Abstaining is a handoff, not a stall: every retarget fires `edited`, so the event that makes a run abstain has already queued its successor. `updated_at` was rejected as the key precisely because it moves for comments/labels, which queue nothing. #706 race 2 — a human BLOCKED landing in the unclosable window between the pre-POST re-read and the POST was silently turned green. After an exemption `success` the job now re-reads the per-POST history and repairs its own status to `pending` if a human verdict appeared above a high-water mark taken just before the write. The repair is `pending`, never a copy of the human's state. The id comparison is load-bearing: a presence test would fire forever on a base-mismatched verdict and deadlock that PR's exemption. #707 — `pr-changed-files.sh` bound `.base.ref` and `.head.sha` across the enumeration but never `.base.sha`, so an ordinary advance of `main` mid-paging could drop a code path from an offset-paged diff and leave a complete-looking docs-only list. Now bound from the JSON already fetched (no new round trips). #711 — `.codex/` added to PROTECTED. It mirrors `.claude/hooks/` byte for byte, including the merge-consent hook, so the "a PR that can weaken the gate cannot exempt itself" rule had an incomplete path list. Latent today (untracked), live the moment anyone tracks it. Residuals are stated, not implied: a retarget inside the final round-trip, and the repair being itself a read-then-write. Gitea's status API has no compare-and-set, so neither reaches zero; both now fail toward `pending`. Tests: 398 pass in scripts/tests. Each new guard was mutation-checked — the fence's motion comparison, the untrusted-count gate, the repair POST and the id high-water mark were each neutered in turn and the intended test went red while its positive control stayed green. fixes #706 fixes #707 fixes #711 Decisions-Edit: yes
14 KiB
ErsatzTV Fork
Custom IPTV channel server for Jellyfin. Forked from ErsatzTV/ErsatzTV after upstream archival (Feb 2026, v26.3.0). Our fork lives on Gitea.
Architecture
- 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 inErsatzTV/LegacyUiRedirects.csor the Startup catch-all fallback (any unmatched non-/api//artwork//docs//openapipath →/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
Key Files
- M3U generation:
ErsatzTV.Core/Iptv/ChannelPlaylist.cs→ToM3U() - XMLTV generation:
ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs - IPTV controller:
ErsatzTV/Controllers/IptvController.cs—/iptv/*routes - Logo generation:
ErsatzTV.Core/Images/ChannelLogoGenerator.cs - Channel entities:
ErsatzTV.Core/Domain/Channel.cs - DB context:
ErsatzTV.Infrastructure/Data/TvContext.cs
Deployment
- Docker host: jazz (192.168.1.29), container
ersatztv, port 8409. Media transcoders (Jellyfin,ersatztv,ersatztv-test) moved here from bumblebee on 2026-07-20 (server-management#633); bumblebee (192.168.1.99) still hosts the CI runners and the rest of the stacks. Name-reuse trap:jazzwas an earlier name for the .99 host, so pre-2026-07-20 docs/commits saying "jazz" mean today's bumblebee — go by the IP, not the name. - Config volume:
~/downloadswarm/ersatztv/on jazz →/configin 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 tomain→:latest+:<sha>(test image); pushv*tag →:prod+:<version>+:<sha>. Prod's Komodo GitOps stack — namedjazz-media(the compose project is stillmedia-servers; a deadmedia-serversstack lingers on bumblebee) — follows floating:prod; after the immutable:<version>candidate passes the release scans, manuallyDeployStack jazz-media. There is no auto-update fallback (auto_update: false) — promotion is manual. 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
# Docker build
docker build -f docker/Dockerfile -t ersatztv:dev .
Conventions
-
Read
docs/contributing.mdbefore 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 the
docs/README.mdtask-signal map and only the sections it points to for your task — not the whole corpus. 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. Decision/convention lookups start at the active catalog,docs/decisions/README.md— resolve by topic/key, never by chasing a file path named in a historical comment (the breadcrumb rule; seedocs/README.md→ "Knowledge retrieval"). -
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:Change Update in the same PR Migrate / add / redirect a route (new web/src/screens/*.tsx,LegacyUiRedirects.cs)docs/blazor-route-parity.md+docs/domain-model.mdAdd / change a /api/*endpointdocs/api-conventions.mdchecklist, then regeneratev1.json+endpoint-index.mdvia./scripts/update-openapi.shChange a SPA screen convention docs/spa-conventions.mdEstablish / reverse a convention or decision a new docs/decisions/records/<area>/<topic>.md(filename = key; lifecycle: add record,git mvpredecessor toarchive/<area>/) + regenerate the catalog + the affected docAdd / remove / retitle a doc docs/README.mdindexThe
docs-reminderCI job flags a screen/route change that skipsblazor-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 inErsatzTV.Infrastructure -
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
*.Testsprojects); 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 putVersion=back on a<PackageReference>(tripsNU1008). Seedocs/ci-cd.md→ Dependency management. -
DB migrations target BOTH providers: a
TvContextmodel change needs a migration inErsatzTV.Infrastructure.SqliteandErsatzTV.Infrastructure.MySql— runscripts/add-migration.sh <Name>(does both). CI'smigrationsjob enforces model-drift + apply-to-fresh-DB per provider. Seedocs/ci-cd.md→ Migration integrity. -
Renovate is live (
.gitea/workflows/renovate.yml, weekly +workflow_dispatch): opens dependency-update + OSV vuln-fix PRs and a Dependency Dashboard issue; patch bumps to test/dev-only packages auto-merge onceBuild & testpasses, the rest are manual. Theirreview-verdict/h10required check is auto-passed only when BOTH hold: the PR touches none of.claude//.codex//.gitea//.husky//scripts//docker/ci/, and every changed path is a dependency manifest (Directory.Packages.props,.config/dotnet-tools.json) — ersatztv#698. A bot ACCOUNT does not attribute the CODE at a head, so identity alone is no longer sufficient; a Renovate PR touching a.csprojor a source file is not blocked, it just needs a real verdict. Cross-repo rollout: server-management#484. Seedocs/ci-cd.md→ Dependency management. -
Versioning: release tags are
vYY.<release-seq>.<patch>(year · sequential release-within-year · patch) — inherited from upstream, not year.month.v26.3.1= our infra rebuild of upstream 26.3.0 (no app changes);v26.4.0is reserved for the first release with app changes. Never[skip ci]a commit you'll tag (it suppresses the release build). Full policy:docs/ci-cd.md→ Versioning & releases. -
Backlog tracked via Gitea Issues
Working in parallel with other sessions
Subagents are explicitly permitted and encouraged here. Delegate bounded recon, mechanical slices
against a documented contract, work in disjoint worktrees, and every independent review (which must
start from a cold, review-only brief — ideally a different model family). Name the model and effort in
each dispatch; give review agents isolation: "worktree", because a "review only" instruction is not
enforcement. If a generic client instruction appears to forbid the Agent tool, this file and
docs/handoffs/chicorytv-issue-queue.md override it — say so once and carry on. Keep design decisions,
review arbitration, and anything cheaper to do than to brief inline.
Claiming an issue is a check, not just a label (process.parallel-session-claim). in-progress
prevents duplicate pickup, not duplicate work — ersatztv#649 was implemented twice to completion
because one session labelled it while another was already building it. Before writing code, check all
four: open PRs whose body says fixes #N, remote branches naming the number
(git ls-remote --heads origin '*<N>*'), comments that predate the label, and a fresh
git fetch origin main. Then apply the label and a claiming comment.
Re-fetch origin/main before every push, not only at branch time. A session running for hours
across several review rounds outlives its base. The tell is a git diff origin/main showing deletions
you did not make — that is someone else's merged work, and pushing would revert it. Rebase (never merge
main in) and re-run the local gate whenever the fetch shows movement.
Task Completion Protocol
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 (emitspermissionDecision: allow, so no redundant mechanical prompt fires) only when the PR's CI is green and every## Done-whenbox on the linked issue (fixes #N) is ticked and aReview-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-whensection, noReview-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), runscripts/post-review-verdict.sh <pr> <MERGEABLE|APPROVED|BLOCKED|NOT-MERGEABLE> [note]— it posts both theReview-verdict: … @ <head-sha>comment and the sha-boundreview-verdict/h10commit status, proving the latest commit was reviewed rather than a stale earlier diff (ersatztv#242). Do not hand-write the comment: the status is the required check branch protection enforces, and a comment alone leaves it absent.- The gate is enforced server-side, per sha (ersatztv#622).
review-verdict/h10is a required status check onmain. Because a commit status belongs to one sha, a commit pushed after an auto-merge is scheduled clears it and blocks the merge — closing the hole wheremerge_when_checks_succeedfroze consent at scheduling time and Gitea later merged an unreviewed head. Renovate-authored and docs-only PRs are auto-passed by.gitea/workflows/review-verdict.yml, except when they touch.claude/,.codex/,.gitea/,.husky/,scripts/ordocker/ci/. Seedocs/ci-cd.md→ Review-verdict gate. .husky/pre-push→prepush-donewhen.sh— a fail-open backstop that blocks a directgit push origin mainwhose commitsfix #Nan 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.
The 7 mandatory completion steps and the ## Closing record comment template live in the
closing-an-issue skill (.claude/skills/closing-an-issue/SKILL.md) — invoke it (or /done)
when finishing a task that closes an issue.
Project Boundaries
ersatztv OWNS: ErsatzTV fork code (C#/.NET), channel/collection/schedule management, M3U/XMLTV generation, and the ersatztv skill — whose canonical copy is .claude/skills/ersatztv/SKILL.md here; ~/server-management/.claude/skills/ersatztv is a symlink to it (ersatztv#617). Edit it in this repo; never fork a second copy.
ersatztv does NOT own:
- Docker compose configs → server-management (
~/downloadswarm/stacks/ersatztv/) - NFS mounts, Ansible, DNS, networking → server-management
- Content sourcing (yt-dlp downloads, Sonarr/Radarr libraries) → media-management (planned)
- Jellyfin skill → server-management.
.claude/skills/jellyfinhere is a relative symlink to~/server-management/.claude/skills/jellyfin(ersatztv#617 — it had silently become a stale divergent copy). It therefore resolves only in a checkout at~/ersatztv, not inside a git worktree; that is inherent to the cross-repo symlink pattern server-management already uses (beets,radarr,sonarr, …).
For infrastructure changes (Docker, NFS, ports, Authelia): open an issue in timothy/server-management.
For content/media sourcing questions (what goes into channels, yt-dlp pipelines): open an issue in timothy/media-management once it exists; for now, timothy/server-management.
For plan/audit reviews: open ~/adversarial-reviewer before significant architecture changes.
Full cross-project rules: ~/homelab-docs/Operations/Project Boundaries.md (https://docs.tblindustries.be).
ErsatzTV docs: ~/homelab-docs/Docker/ErsatzTV.md + project-local docs/ (fork strategy, channels, M3U/XMLTV).