ersatztv/docs/handoffs/chicorytv-issue-queue.md

ChicoryTV issue-queue handoff (living document)

Paste the prompt below into a fresh session to work the next item. Each session ends by UPDATING THIS FILE in place (rewrite the state section and the queue for the next item) so it always holds the current handoff. History: created 2026-07-02 after the plan audit (#59 epic); all backend gap issues (#100–#111), all SPA screens (#84–#89, #93, #109), the rebrand (#90), the cutover root-flip (#91 phase a), full scheduling parity (#144/#162), media/troubleshooting parity (#141/#161/#158/#180), onboarding docs (#185), the collections/API-gap batch (#155/#151/#152-backend/#184), the multi/rerun/playlist SPA editors (#151/#152 PR #194, #153 PR #195), CI speedups (#190 PR #192), and now #145 playback troubleshooting (PR #199) are MERGED. v26.5.0 in prod; v26.6.0 tagged (awaiting Komodo pin bump in server-management).

#145 is CLOSED — every SPA-parity screen exists. Blazor removal (#91 phase b) is now gated ONLY on the cold adversarial review (hard-gate comment on #91; runs from the external ~/adversarial-reviewer project, zero shared context, brief embedded in the #91 comment).

Session state (2026-07-09, #145 playback troubleshooting session): main = af17dafc (post PR #199, merge pre-approved by user after CI green; post-merge main run was being verified at handoff-write time — confirm Build & test + image jobs green before relying on :latest). Tests on main: ErsatzTV.Tests 927, web 385, Core.Tests 493(+1 skip), Architecture 5 — all green. Worktree .worktrees/feat-145 removed after merge.

What PR #199 added:

• Backend: GET /api/troubleshoot/playback/{stream-selectors,subtitles/{id},status}; ITroubleshootingPlaybackStatusStore (Core singleton, TroubleshootingNotifier precedent) filled by a MediatR INotificationHandler<PlaybackTroubleshootingCompletedNotification>, reset at session lock in PrepareTroubleshootingPlaybackHandler — the pollable replacement for Blazor's in-process Courier completion event. GET /api/graphics-elements?refresh=true.
• SPA: /app/troubleshooting/playback (?channel=/?mediaItem= modes) mirroring PlaybackTroubleshooting.razor; reusable web/src/media/HlsPlayer.tsx (hls.js; playToken prop forces re-attach — REQUIRED because the m3u8 GET is what starts a session and identical URLs are React no-ops); 2s status polling with a starting→running→settled phase machine (30s start timeout); entry points: channels-table Troubleshoot action + movie detail page.
• New issues filed: #198 (OpenAPI spec/runtime property-casing drift, see lessons — M, includes a LIVE ChannelEditScreen bug on main), #197 (cold API contract+security review, runs when MCP PR #76 stabilizes; HARD GATE on #58 closing/go-live). #91 got the phase-(b) review-gate comment.

Lessons for all remaining prompts (conventions live in docs/; this is workflow lore):

• READ docs/README.md → the convention docs FIRST; point recon/implementer agents at specific doc sections. Only recon the task-specific delta.
• #198 / spec-typed mocks blind spot: runtime JSON is Newtonsoft-cased (FFmpegProfileId→ffmpegProfileId) but the OpenAPI generator uses STJ naming (fFmpegProfileId) — generated TS types are WRONG for leading-acronym response fields, and unit-test mocks typed from them stay green while the real screen breaks. Until #198 lands: read such fields via a typed escape hatch pinned to the runtime key (precedent: PlaybackTroubleshootingScreen default-profile derivation), and make test mocks use the runtime casing. Only live E2E catches this class — one more reason the per-PR live-E2E gate is non-negotiable.
• Playwright-MCP E2E: never open tabs/window.open for file-download endpoints — a download never renders a page and wedges the browser session hard enough to kill the agent (stalled a sonnet E2E agent 3× this session; had to pkill the mcp-chrome profile). Verify downloads with plain HTTP (curl) instead. If browser tools stall repeatedly, pkill -f ms-playwright-mcp and drive a fresh session.
• The user's main checkout (/Users/timothy/ersatztv) is now ON main and pulled each session — keep it that way (stale-checkout confusion resolved 2026-07-09; stale branches pruned). Still do feature work in worktrees off origin/main; copy web/node_modules from the main checkout into new web worktrees instead of npm ci.
• Subagent connection drops = laptop sleep; re-resume via SendMessage (work survives).
• Build/verify locally, then trust it; CI (VM 127) is the slow confirming step (~9 min warm). Watch by commit status: /api/v1/repos/timothy/ersatztv/commits/{sha}/status. A red MAIN push is most likely a CANCELLED job from VM churn — check conclusion before assuming regression.
• PR routine (works): worktree off origin/main → implement (opus judgment-heavy / sonnet mechanical; doc pointers + exact facts; csharp-lsp for C#) → API changes: build app project FIRST then ./scripts/update-openapi.sh then npm run generate:api → full local test pass → push, PR → fork adversarial review (SCOPED "review only") + live-E2E for UI changes (scripts/e2e-local.sh) → review fixes as follow-up COMMITS (never amend/force-push) → CI green → merge (consent per session; 2026-07-09 session had pre-approval for #199 only) → structured close comments per CLAUDE.md protocol.
• Never run TWO committing agents on one worktree concurrently. Read-only review forks are fine.
• Reusable API facts: DTO records in ErsatzTV.Core/Api need file-scoped #nullable enable; ErsatzTV.Application has NO nullable context (CS8632); Option<T>→nullable = MatchUnsafe(v => (T?)v, () => null); LanguageExtensions.Apply collapses NotFoundError→422, so real 404s need a controller pre-check; id-taking child GETs get an OpenApiErrorResponseContractTests [TestCase].

---

PROMPT — #198 OpenAPI casing drift (live ChannelEditScreen bug) + #193 warm-up

You are Fable, the ORCHESTRATOR in the main Claude Code session. Fable is EXPENSIVE: delegate (recon → Explore/haiku; mechanical → sonnet; judgment-heavy → opus; fable forks for review). FIRST read CLAUDE.md, docs/README.md + the convention docs it indexes, and the Lessons above.

HARD CONSTRAINTS:

• Work in worktrees off origin/main. The main checkout should stay on main/pulled — safe for reading, but do feature work in a worktree. Copy web/node_modules from the main checkout.
• Up to 3 concurrent builds; never 5+. NEVER set ETV_UPDATE_GOLDENS.
• Merge consent in-conversation per session (prior pre-approvals do NOT carry over).
• Live-E2E via scripts/e2e-local.sh; NEVER exercise download endpoints via browser tabs (curl them). Adversarial review fork per PR diff, SCOPED "review only".

Task 1 — #198 OpenAPI spec/runtime casing drift [M]

Read issue #198 first — it has the full analysis. Summary: MVC responses serialize via Newtonsoft (leading acronyms fully lowercased: ffmpegProfileId) but the OpenAPI generator uses STJ naming (fFmpegProfileId), so generated TS types lie about response keys. ChannelEditScreen.tsx:122 reads the phantom key → with >1 ffmpeg profile, editing a channel shows/saves the WRONG profile (repro'd live 2026-07-09).

1. Root fix: make spec generation match runtime naming (schema transformer or serializer alignment — investigate what ErsatzTV/Startup.cs + the OpenAPI pipeline allow). Regen v1.json/endpoint-index/web types (expect broad-but-mechanical v1.json diff).
2. Fix all SPA readers of drifted fields (grep web/src for fFmpeg/fFprobe/rFrameRate/ zIndex; at minimum ChannelEditScreen + remove the #145 escape hatch in PlaybackTroubleshootingScreen) and their test mocks; verify each candidate field against a live scratch instance (curl) — the single-leading-cap ones (zIndex, rFrameRate) may not actually drift.
3. Add the CI guard from the issue: a test that round-trips a known DTO through the real MVC serializer and asserts the OpenAPI schema uses those exact keys.
4. Live-E2E the channel editor with 2 profiles (the repro case) + playback screen preselect.
5. Full PR routine; close #198.

Task 2 (warm-up/interleave) — #193 rerun-collection existence check [S, backend]

Per issue: existence pre-check for selectedId per selection type in RerunCollection create/update → 404/422 ProblemDetails instead of dangling FK/500. api-conventions §3 precedent. Can ride as its own small PR.

On completion — REQUIRED last step

Update THIS handoff (pop #198/#193, promote the #91 phase-(b) queue item), commit to main, print the next prompt in a fenced code block.

---

Issue queue (work top-down)

1. #198 casing drift + #193 rerun existence-check ← PROMPT above.
2. #91 phase (b) Blazor removal — HARD GATE: cold adversarial plan review first (brief in the #91 gate comment; run /review from ~/adversarial-reviewer, zero shared context, findings via /dispatch, MUST-FIXes resolved before implementation). Then: redirect the Section-2 routes in docs/blazor-route-parity.md, delete Blazor pages/MudBlazor deps (also kills the 3 deprecated Renovate-dashboard packages incl. MediatR.Courier), update docs. Likely its own session (or two: review, then removal).
3. #197 cold API contract+security review — runs when MCP PR #76 stabilizes; HARD GATE on #58 close/go-live and MANDATORY before any remote exposure.
4. Backlog: #99 (TS/HLS-Direct session tracking — makes channel-state onAir universal), #66 (artwork magic-byte sniffing), backlog nits (unclamped pageSize, 30 MB bare 413, PlayoutController route Name=/lightweight exists-check, guide 21-include eager-load + fillerKind notes — see #85/#102 issue comments). Cross-refs: v26.6.0 deploy = Komodo pin bump (server-management). Real-transcode E2E of the playback screen: do once on the test container (ersatztv-test runs :latest) — local ffmpeg 8.1.2 lacks subtitles/zscale filters.