Latest season until watching starts, then continue sequentially

[Padde86]

Could you add an optional season-selection policy that works with GET 1 / KEEP 1?

• Before watching starts, keep the first episode of the latest available season. When a newer season becomes available, replace the completely unwatched older premiere after the new one has downloaded successfully.
• Once a season has been started, preserve chronological order permanently: finish season 3, then continue with season 4, even if season 5 is already available.
• An unwatched season 4 must remain selected once it follows a watched season 3.
• Continue keeping one next unwatched episode and the last watched episode.

Is this already possible through existing settings? If not, could it become a native rule option?

[Vansmak]

Built this into v4.0.0 as a new always_have rule pattern called "Premiere."

Short version: a new c token (current season) that's re-resolved against Sonarr's actual air dates every check, instead of being fixed to whatever season existed when the rule was applied.

Always Have: sce1 does what you described:

• Keeps the current season's premiere downloaded, held unwatched — nothing else downloads yet
• If a newer season's premiere finishes downloading before you watch it, the old one is automatically swapped out for the new one (no gap where neither is available — it waits for the new one to actually be on disk first)
• The moment you watch whichever premiere is sitting there, it locks in and behaves exactly like Sequential Activation (e1+) from that point on — one season at a time, in order, continuing from wherever you actually started rather than jumping ahead to whatever's newest

So requesting S3/S4 of a mid-run show, or just letting a 5-season show sit until you're ready, both work the same way — whatever season is current gets dangled, and committing to watch it switches you into normal chronological viewing from there.

Docs + example rule are in the README under "Premiere." Thanks for writing this up clearly, it made the design a lot easier to pin down.

[Padde86]

Thanks for implementing Premiere so quickly! I checked the v4.0.0 tag
(d0b5b4ddc8e410dd24f81ee036b35e71f6d94c81) before upgrading.

One catch-up case seems to be missing:

• Rule: always_have=sce1, GET 1 / KEEP 1, action Search.
• S3 is premiere_held, with S3E01 downloaded and still unwatched.
• S4E01 has now aired, but is unmonitored and has no file yet (for example,
  the metadata appeared after the premiere, or Episeerr was offline).

Running reconcile_future_seasons() followed by reconcile_premiere_swaps()
with those inputs produces no monitor/search requests. The first function
skips already-aired seasons, while the swap function waits for the new
premiere to already have hasFile=True.

With exactly the same inputs except S4E01 already having a file, the swap
works and removes S3E01 as intended.

Is another scheduled path supposed to monitor and search the newly current
premiere in the first case, or should the Premiere reconciliation also
initiate that download while retaining the old premiere until import?

[Vansmak]

Good catch, and you were right — fixed in v4.0.1.

The bug was exactly what you traced: reconcile_premiere_swaps() only ever checked whether the new season's premiere already had a file, it never actually triggered a monitor/search for it. So in the exact case you described (S4E1 aired but never got monitored), nothing would ever make hasFile become true, and the swap would just wait forever.

Fixed by having that function proactively monitor and search the newly-current premiere the moment it's detected as current, while still holding off on evicting the old one until the new one is actually confirmed downloaded. reconcile_future_seasons() now also explicitly skips c-token rules (it was silently not matching them anyway, since resolve_current_season() only ever points at an already-aired season — there was never anything for it to correctly do there).

Appreciate you actually tracing it against the shipped code instead of just reporting a vague symptom — made this a same-day fix.

[Padde86]

Thanks! I reran the catch-up case against the unmodified v4.0.1 tag. It now monitors and searches the new premiere while keeping the old one, then swaps after import. All 106 shipped tests also passed.

Before moving to a fully native deployment, could you clarify four related behaviors? These are compatibility requirements from an existing setup, rather than four assumptions that Premiere itself is broken:

1. Jellyfin episode-to-series matching: the integration still looks up the Sonarr series by name. Is there a native path that resolves Jellyfin's SeriesId to the parent series' TVDB ID, so different display titles do not prevent a match?
2. Watched marks imported into Jellyfin by another client/service: is there a periodic native replay/reconciliation path, without requiring playback webhooks or a restart/manual pending-event action?
3. GET 1: after watching E02, E03 is selected, but a previously monitored E04 remains monitored in a direct call to process_episodes_for_webhook(). Is clearing monitoring beyond the GET window intended, or is GET only an additive selection limit?
4. KEEP 1 with gaps on disk: if E02 has a file and E03 is marked watched without a file, the native find_episodes_leaving_keep_block() can select E02 for deletion. Could KEEP count actual files up to the watched position, so the last available watched episode is retained, including across a season boundary?

Are these covered by other native settings or scheduled paths? If not, would you consider native support for them? I can provide small synthetic reproductions for each behavior.

[Vansmak]

Good follow-up questions, answering each:

1 & 2 (Jellyfin matching + reconciliation): #1 is now fixed in v4.0.2 — the integration prefers TVDB ID over title matching when available. Jellyfin's session data already carries the playing episode's SeriesId; it's now resolved to the series' TVDB ID (one extra lightweight API call) and passed into the same TVDB-matching path the Sonarr webhook flow already uses, falling back to the exact same title match as before if that's unavailable. Verified live against a real Jellyfin + Sonarr pair before shipping.

#2 (periodic reconciliation) I'm leaving as-is for now. The missed-watch-event sweep is deliberately startup-only and always queues to a human to review rather than auto-replaying — every media server's definition of "watched" drifts from Episeerr's own detection threshold slightly differently, and guessing wrong silently seemed worse than asking. That part'''s not changing. Tautulli is the integration path I've actually hardened against in practice; Jellyfin support exists and works, it just gets less real-world mileage here.

3: Confirmed — GET is purely additive. It only ever monitors the episodes in its own window and never unmonitors anything outside it. That'''s intentionally Keep'''s job, not Get'''s.

4: You found a real gap, and we'''re going to fix it — just not the way you suggested. Keep still anchors strictly to the watched position and removes everything before it; that part of the model isn'''t changing. But "Keep 1" should mean what it says: make sure that many episodes actually exist, not just assume whatever'''s at that position is there. So instead of searching backward through history for a different already-downloaded episode to protect, Keep will check whether the episode it'''s supposed to be keeping actually has a file — and if not, fetch it. Same anchor, same "remove everything before it" rule, it just actively closes the gap between "Keep says it'''s keeping something" and that thing really being on disk.

[Vansmak]

Update on #4: shipped in v4.0.3. When the rule wants the watched episode to stay present (monitor_watched, default True) and it has no file, Episeerr now actively monitors/searches for it instead of leaving the keep window empty - same anchor, same "remove everything before it" rule, just no longer silently assumes the anchor episode is there when it isn't.

[Padde86]

Thanks for the quick fixes and explanations! I checked the unmodified v4.0.3 tag: all 106 shipped tests passed, the original Premiere catch-up case still works in isolation, and the parent-series TVDB lookup passed my synthetic checks.

I understand you want to preserve the existing model. Before closing this out, would you consider the remaining requirements as explicitly opt-in settings, with defaults unchanged?

• Scheduled reconciliation for externally imported Jellyfin watched marks, optionally trusting those explicit marks after the operator enables it. I understand your concern about differing playback thresholds; a periodic review queue would also be useful if automatic replay is outside scope.
• A strict GET window for episodes managed by that rule: after E02 is watched and GET 1 selects E03, stop monitoring previously monitored E04 and later episodes, while respecting protected anchors and season activation.
• A no-gap KEEP handover: keep the watched position as the anchor you described, but delay deleting the last existing watched file until that anchor has actually downloaded. In my synthetic v4.0.3 check, E02 is still submitted for deletion immediately when E03 is watched without a file, even with monitor_watched=true; E03 is requested, but its import is not awaited. This would preserve your anchor choice while avoiding an empty retained-file window if the release cannot be found.

Would any of these be acceptable as optional native features, or are they outside the project's scope even as opt-ins? Happy to provide the small synthetic cases. Thanks again for adding Premiere and working through the concrete findings!

[Vansmak]

it's alot for one persons use case. the more I add the more I lose track. and it's not a paid gig so no promises

[Padde86]

Understood — no pressure or expectation of a commitment. Thanks for taking the time to implement Premiere, fix the concrete issues, and explain the remaining design choices. I'll keep the remaining items as requests rather than assume they're on a roadmap. I appreciate your work on the project!

[Padde86]

One thought on reducing the implementation work: I already have local implementations and regression tests for watched-state reconciliation, a strict GET window, and retaining the last watched file that actually exists. They would need adapting to the current upstream code; they are not a ready-to-merge PR, and the last-file behavior differs from the delayed-anchor handover I suggested.

If useful, I could prepare a small, separately reviewable contribution for whichever part you would actually want, with optional behavior and existing defaults preserved. Would you be interested in seeing one, or would you prefer to leave these outside the project? No expectation that you take them on or commit to maintenance.

[Vansmak]

sorry, I know I use AI to help me code but your posts sound like ai or a different vernacular to me. or is it translated?

[Vansmak]

i think you are trying to make episeer work for a multi user scenario and it was never designed for that. in theory It could work and I already have a roadmap. just undecided if I want to develop an app that others use who may have paid users.

[Padde86]

Yes, I use AI to help write my English posts. Sorry if that made them sound unnatural. This is just my private home setup, with no paying users. I want one watch history to stay consistent across different playback apps, not separate user profiles. I'll keep the extra behavior local for now. Thanks for everything you've already added!

[Vansmak]

ok that makes sense, just confused me. right now im waiting for my usage to reset and will look more at it. i use AI but I am very meticulous in what I want before I let it touch code. thank you for your understanding.

[Vansmak]

Picked one of these back up: the missed-watch-event sweep (which already detects externally-set watched marks correctly - it reads Jellyfin/Emby playstate directly, not webhooks) was only ever running once at startup. It now also re-runs on the normal cleanup cadence, so it eventually surfaces these on a long-running instance without needing a restart. Still only ever queues to Pending Watch Events for human review, never auto-replays. Shipped in v4.0.5.