Add ITranscodeSessionStore interface and HA recovery unit tests (#19)

* Initial plan

* Add ITranscodeSessionStore interface, TranscodeSession record, InMemoryTranscodeSessionStore fake, and HA unit tests"

Co-authored-by: ZoltyMat <177592743+ZoltyMat@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: ZoltyMat <177592743+ZoltyMat@users.noreply.github.com>

MediaBrowser.Controller/MediaEncoding/ITranscodeSessionStore.cs

@@ -0,0 +1,62 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace MediaBrowser.Controller.MediaEncoding;
+
+/// <summary>
+/// Provides a durable store for HLS transcoding session state, enabling
+/// HA recovery and lease-based ownership between pods.
+/// </summary>
+public interface ITranscodeSessionStore
+{
+    /// <summary>
+    /// Attempts to retrieve a transcoding session by its play session identifier.
+    /// </summary>
+    /// <param name="playSessionId">The play session identifier.</param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    /// <returns>
+    /// The <see cref="TranscodeSession"/> if it exists and its lease has not expired;
+    /// otherwise <c>null</c>.
+    /// </returns>
+    Task<TranscodeSession?> TryGetAsync(string playSessionId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Attempts to take over ownership of an existing session by claiming the lease for
+    /// <paramref name="claimingPod"/>. Takeover succeeds only when the session exists and
+    /// its current lease has already expired.
+    /// </summary>
+    /// <param name="playSessionId">The play session identifier.</param>
+    /// <param name="claimingPod">The name of the pod attempting to claim ownership.</param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    /// <returns>
+    /// <c>true</c> if the takeover succeeded (the claiming pod now holds the lease);
+    /// <c>false</c> if the session does not exist, its lease is still valid, or another
+    /// concurrent caller already claimed it.
+    /// </returns>
+    Task<bool> TryTakeoverAsync(string playSessionId, string claimingPod, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Persists a new or updated transcoding session.
+    /// </summary>
+    /// <param name="session">The session to store.</param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    Task SetAsync(TranscodeSession session, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Renews the lease for an existing session, extending its
+    /// <see cref="TranscodeSession.LeaseExpiresUtc"/> by the store's configured lease duration.
+    /// </summary>
+    /// <param name="playSessionId">The play session identifier.</param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    Task RenewLeaseAsync(string playSessionId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes a transcoding session from the store.
+    /// </summary>
+    /// <param name="playSessionId">The play session identifier.</param>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    Task DeleteAsync(string playSessionId, CancellationToken cancellationToken = default);
+}

MediaBrowser.Controller/MediaEncoding/TranscodeSession.cs

@@ -0,0 +1,49 @@
+using System;
+
+namespace MediaBrowser.Controller.MediaEncoding;
+
+/// <summary>
+/// Represents a durable record of an HLS transcoding session for HA pod recovery.
+/// </summary>
+public sealed class TranscodeSession
+{
+    /// <summary>
+    /// Gets or sets the unique play session identifier.
+    /// </summary>
+    public string PlaySessionId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the name of the pod that currently owns this session's lease.
+    /// </summary>
+    public string OwnerPod { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the UTC time at which the owning pod's lease expires.
+    /// </summary>
+    public DateTime LeaseExpiresUtc { get; set; }
+
+    /// <summary>
+    /// Gets or sets the absolute path to the HLS manifest (.m3u8) file on shared storage.
+    /// </summary>
+    public string ManifestPath { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the path prefix for transcoded segment files on shared storage.
+    /// </summary>
+    public string SegmentPathPrefix { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the media source identifier associated with this session.
+    /// </summary>
+    public string MediaSourceId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the zero-based index of the last segment that was fully written to durable storage.
+    /// </summary>
+    public int LastCompletedSegmentIndex { get; set; }
+
+    /// <summary>
+    /// Gets or sets the last durable playback offset in ticks, used to resume playback after failover.
+    /// </summary>
+    public long LastDurablePlaybackOffset { get; set; }
+}

tests/Jellyfin.Api.Tests/Controllers/DynamicHlsHaTakeoverTests.cs

@@ -0,0 +1,189 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Api.Controllers;
+using MediaBrowser.Controller.MediaEncoding;
+using Xunit;
+
+namespace Jellyfin.Api.Tests.Controllers
+{
+    /// <summary>
+    /// Tests for HA recovery scenarios that will be wired into <see cref="DynamicHlsController"/>
+    /// in Phase 5.2. These tests verify the <see cref="ITranscodeSessionStore"/> contract that
+    /// the controller will rely on for missing-local-job recovery, claim racing, and cleanup guarding.
+    /// </summary>
+    public class DynamicHlsHaTakeoverTests
+    {
+        private static TranscodeSession CreateSession(string id, string pod, DateTime leaseExpiry)
+            => new TranscodeSession
+            {
+                PlaySessionId = id,
+                OwnerPod = pod,
+                LeaseExpiresUtc = leaseExpiry,
+                ManifestPath = $"/transcode/{id}/manifest.m3u8",
+                SegmentPathPrefix = $"/transcode/{id}/segment",
+                MediaSourceId = "media-source-1",
+                LastCompletedSegmentIndex = 3,
+                LastDurablePlaybackOffset = 18_000_000L,
+            };
+
+        /// <summary>
+        /// Missing-local-job + durable-manifest-present: the store returns the session so
+        /// the controller can serve the existing manifest instead of returning an error.
+        /// </summary>
+        [Fact]
+        [Trait("Category", "UnitTest")]
+        public async Task DurableManifestPresent_WithLiveSession_StoreReturnsSession()
+        {
+            var store = new HaTestSessionStore();
+            var session = CreateSession("ha-session-1", "pod-a", DateTime.UtcNow.AddMinutes(5));
+            await store.SetAsync(session);
+
+            // Simulate controller recovery: look up the session in the durable store.
+            var recovered = await store.TryGetAsync("ha-session-1");
+
+            Assert.NotNull(recovered);
+            Assert.Equal("/transcode/ha-session-1/manifest.m3u8", recovered.ManifestPath);
+        }
+
+        /// <summary>
+        /// Claim-race between two concurrent requesters: only one wins
+        /// <see cref="ITranscodeSessionStore.TryTakeoverAsync"/>.
+        /// The other receives <c>false</c>, indicating it should redirect (302) or wait.
+        /// </summary>
+        [Fact]
+        [Trait("Category", "UnitTest")]
+        public async Task ClaimRace_TwoConcurrentRequesters_OnlyOneWinsTakeover()
+        {
+            var store = new HaTestSessionStore();
+
+            // Original pod crashed – lease is expired.
+            var session = CreateSession("ha-session-2", "pod-a", DateTime.UtcNow.AddMilliseconds(-1));
+            await store.SetAsync(session);
+
+            // Two pods simultaneously attempt to claim the orphaned session.
+            var task1 = store.TryTakeoverAsync("ha-session-2", "pod-b");
+            var task2 = store.TryTakeoverAsync("ha-session-2", "pod-c");
+            var results = await Task.WhenAll(task1, task2);
+
+            // Exactly one pod must win.
+            var wins = Array.FindAll(results, r => r);
+            Assert.Single(wins);
+        }
+
+        /// <summary>
+        /// Stale-manifest cleanup guard: a lease that has expired beyond the recovery window
+        /// causes the store to return <c>null</c>, signalling that cleanup may proceed safely.
+        /// </summary>
+        [Fact]
+        [Trait("Category", "UnitTest")]
+        public async Task StaleManifestCleanupGuard_ExpiredBeyondRecoveryWindow_StoreReturnsNull()
+        {
+            var store = new HaTestSessionStore();
+
+            // Lease expired hours ago – well beyond any recovery window.
+            var session = CreateSession("ha-session-3", "pod-a", DateTime.UtcNow.AddHours(-2));
+            await store.SetAsync(session);
+
+            // Controller or cleanup task checks the store before deleting files.
+            var liveSession = await store.TryGetAsync("ha-session-3");
+
+            // Store returns null → cleanup may proceed without risking data loss.
+            Assert.Null(liveSession);
+        }
+
+        /// <summary>
+        /// Minimal in-memory <see cref="ITranscodeSessionStore"/> used within this test class
+        /// to avoid a cross-project reference to Jellyfin.MediaEncoding.Tests.
+        /// </summary>
+        private sealed class HaTestSessionStore : ITranscodeSessionStore
+        {
+            private static readonly TimeSpan LeaseDuration = TimeSpan.FromSeconds(30);
+
+            private readonly Dictionary<string, TranscodeSession> _sessions =
+                new(StringComparer.OrdinalIgnoreCase);
+
+            private readonly Lock _lock = new();
+
+            public Task<TranscodeSession?> TryGetAsync(string playSessionId, CancellationToken cancellationToken = default)
+            {
+                lock (_lock)
+                {
+                    if (_sessions.TryGetValue(playSessionId, out var s) && s.LeaseExpiresUtc > DateTime.UtcNow)
+                    {
+                        return Task.FromResult<TranscodeSession?>(Clone(s));
+                    }
+
+                    return Task.FromResult<TranscodeSession?>(null);
+                }
+            }
+
+            public Task<bool> TryTakeoverAsync(string playSessionId, string claimingPod, CancellationToken cancellationToken = default)
+            {
+                lock (_lock)
+                {
+                    if (!_sessions.TryGetValue(playSessionId, out var s))
+                    {
+                        return Task.FromResult(false);
+                    }
+
+                    if (s.LeaseExpiresUtc > DateTime.UtcNow)
+                    {
+                        return Task.FromResult(false);
+                    }
+
+                    s.OwnerPod = claimingPod;
+                    s.LeaseExpiresUtc = DateTime.UtcNow.Add(LeaseDuration);
+                    return Task.FromResult(true);
+                }
+            }
+
+            public Task SetAsync(TranscodeSession session, CancellationToken cancellationToken = default)
+            {
+                lock (_lock)
+                {
+                    _sessions[session.PlaySessionId] = session;
+                }
+
+                return Task.CompletedTask;
+            }
+
+            public Task RenewLeaseAsync(string playSessionId, CancellationToken cancellationToken = default)
+            {
+                lock (_lock)
+                {
+                    if (_sessions.TryGetValue(playSessionId, out var s))
+                    {
+                        s.LeaseExpiresUtc = DateTime.UtcNow.Add(LeaseDuration);
+                    }
+                }
+
+                return Task.CompletedTask;
+            }
+
+            public Task DeleteAsync(string playSessionId, CancellationToken cancellationToken = default)
+            {
+                lock (_lock)
+                {
+                    _sessions.Remove(playSessionId);
+                }
+
+                return Task.CompletedTask;
+            }
+
+            private static TranscodeSession Clone(TranscodeSession source)
+                => new TranscodeSession
+                {
+                    PlaySessionId = source.PlaySessionId,
+                    OwnerPod = source.OwnerPod,
+                    LeaseExpiresUtc = source.LeaseExpiresUtc,
+                    ManifestPath = source.ManifestPath,
+                    SegmentPathPrefix = source.SegmentPathPrefix,
+                    MediaSourceId = source.MediaSourceId,
+                    LastCompletedSegmentIndex = source.LastCompletedSegmentIndex,
+                    LastDurablePlaybackOffset = source.LastDurablePlaybackOffset,
+                };
+        }
+    }
+}

tests/Jellyfin.MediaEncoding.Tests/Fakes/InMemoryTranscodeSessionStore.cs

@@ -0,0 +1,107 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using MediaBrowser.Controller.MediaEncoding;
+
+namespace Jellyfin.MediaEncoding.Tests.Fakes;
+
+/// <summary>
+/// Thread-safe, in-memory implementation of <see cref="ITranscodeSessionStore"/> for use in unit tests.
+/// </summary>
+public sealed class InMemoryTranscodeSessionStore : ITranscodeSessionStore
+{
+    /// <summary>
+    /// The duration added to <see cref="DateTime.UtcNow"/> when a lease is renewed or first claimed.
+    /// </summary>
+    public static readonly TimeSpan DefaultLeaseDuration = TimeSpan.FromSeconds(30);
+
+    private readonly Dictionary<string, TranscodeSession> _sessions = new(StringComparer.OrdinalIgnoreCase);
+    private readonly Lock _lock = new();
+
+    /// <inheritdoc />
+    public Task<TranscodeSession?> TryGetAsync(string playSessionId, CancellationToken cancellationToken = default)
+    {
+        lock (_lock)
+        {
+            if (_sessions.TryGetValue(playSessionId, out var session) && session.LeaseExpiresUtc > DateTime.UtcNow)
+            {
+                return Task.FromResult<TranscodeSession?>(Clone(session));
+            }
+
+            return Task.FromResult<TranscodeSession?>(null);
+        }
+    }
+
+    /// <inheritdoc />
+    public Task<bool> TryTakeoverAsync(string playSessionId, string claimingPod, CancellationToken cancellationToken = default)
+    {
+        lock (_lock)
+        {
+            if (!_sessions.TryGetValue(playSessionId, out var session))
+            {
+                return Task.FromResult(false);
+            }
+
+            if (session.LeaseExpiresUtc > DateTime.UtcNow)
+            {
+                // Another pod's lease is still valid – takeover not permitted.
+                return Task.FromResult(false);
+            }
+
+            // Lease has expired – claim it atomically.
+            session.OwnerPod = claimingPod;
+            session.LeaseExpiresUtc = DateTime.UtcNow.Add(DefaultLeaseDuration);
+            return Task.FromResult(true);
+        }
+    }
+
+    /// <inheritdoc />
+    public Task SetAsync(TranscodeSession session, CancellationToken cancellationToken = default)
+    {
+        lock (_lock)
+        {
+            _sessions[session.PlaySessionId] = session;
+        }
+
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public Task RenewLeaseAsync(string playSessionId, CancellationToken cancellationToken = default)
+    {
+        lock (_lock)
+        {
+            if (_sessions.TryGetValue(playSessionId, out var session))
+            {
+                session.LeaseExpiresUtc = DateTime.UtcNow.Add(DefaultLeaseDuration);
+            }
+        }
+
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public Task DeleteAsync(string playSessionId, CancellationToken cancellationToken = default)
+    {
+        lock (_lock)
+        {
+            _sessions.Remove(playSessionId);
+        }
+
+        return Task.CompletedTask;
+    }
+
+    private static TranscodeSession Clone(TranscodeSession source)
+        => new TranscodeSession
+        {
+            PlaySessionId = source.PlaySessionId,
+            OwnerPod = source.OwnerPod,
+            LeaseExpiresUtc = source.LeaseExpiresUtc,
+            ManifestPath = source.ManifestPath,
+            SegmentPathPrefix = source.SegmentPathPrefix,
+            MediaSourceId = source.MediaSourceId,
+            LastCompletedSegmentIndex = source.LastCompletedSegmentIndex,
+            LastDurablePlaybackOffset = source.LastDurablePlaybackOffset,
+        };
+}

tests/Jellyfin.MediaEncoding.Tests/Transcoding/TranscodeManagerTests.cs

@@ -0,0 +1,167 @@
+using System;
+using System.Threading.Tasks;
+using Jellyfin.MediaEncoding.Tests.Fakes;
+using MediaBrowser.Controller.MediaEncoding;
+using Xunit;
+
+namespace Jellyfin.MediaEncoding.Tests.Transcoding;
+
+/// <summary>
+/// Unit tests for the HA session-store contract: lease expiry, double-claim prevention,
+/// heartbeat renewal, and stale-session cleanup.
+/// All tests exercise <see cref="InMemoryTranscodeSessionStore"/> which implements the
+/// <see cref="ITranscodeSessionStore"/> interface that will be backed by Redis in Phase 5.2.
+/// </summary>
+public class TranscodeManagerTests
+{
+    private static TranscodeSession CreateSession(
+        string id,
+        string pod,
+        DateTime leaseExpiry,
+        int lastSegmentIndex = 0,
+        long lastOffset = 0L)
+        => new TranscodeSession
+        {
+            PlaySessionId = id,
+            OwnerPod = pod,
+            LeaseExpiresUtc = leaseExpiry,
+            ManifestPath = $"/transcode/{id}/manifest.m3u8",
+            SegmentPathPrefix = $"/transcode/{id}/segment",
+            MediaSourceId = $"media-source-{id}",
+            LastCompletedSegmentIndex = lastSegmentIndex,
+            LastDurablePlaybackOffset = lastOffset,
+        };
+
+    /// <summary>
+    /// Lease expiry: <see cref="ITranscodeSessionStore.TryGetAsync"/> returns <c>null</c>
+    /// once <see cref="TranscodeSession.LeaseExpiresUtc"/> has passed.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task TryGetAsync_AfterLeaseExpires_ReturnsNull()
+    {
+        var store = new InMemoryTranscodeSessionStore();
+        var session = CreateSession("session-expired", "pod-a", DateTime.UtcNow.AddMilliseconds(-1));
+        await store.SetAsync(session);
+
+        var result = await store.TryGetAsync("session-expired");
+
+        Assert.Null(result);
+    }
+
+    /// <summary>
+    /// A session whose lease has not yet expired is returned correctly.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task TryGetAsync_WithinLease_ReturnsSession()
+    {
+        var store = new InMemoryTranscodeSessionStore();
+        var session = CreateSession("session-live", "pod-a", DateTime.UtcNow.AddMinutes(5), lastSegmentIndex: 3, lastOffset: 18_000_000L);
+        await store.SetAsync(session);
+
+        var result = await store.TryGetAsync("session-live");
+
+        Assert.NotNull(result);
+        Assert.Equal("session-live", result.PlaySessionId);
+        Assert.Equal("pod-a", result.OwnerPod);
+        Assert.Equal(3, result.LastCompletedSegmentIndex);
+        Assert.Equal(18_000_000L, result.LastDurablePlaybackOffset);
+    }
+
+    /// <summary>
+    /// Double-claim prevention: <see cref="ITranscodeSessionStore.TryTakeoverAsync"/> returns
+    /// <c>false</c> while the first pod's lease is still valid.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task TryTakeoverAsync_WhileLeaseValid_ReturnsFalse()
+    {
+        var store = new InMemoryTranscodeSessionStore();
+        var session = CreateSession("session-valid", "pod-a", DateTime.UtcNow.AddMinutes(5));
+        await store.SetAsync(session);
+
+        var firstAttempt = await store.TryTakeoverAsync("session-valid", "pod-b");
+        var secondAttempt = await store.TryTakeoverAsync("session-valid", "pod-c");
+
+        Assert.False(firstAttempt);
+        Assert.False(secondAttempt);
+    }
+
+    /// <summary>
+    /// After a lease expires, the first concurrent caller that invokes
+    /// <see cref="ITranscodeSessionStore.TryTakeoverAsync"/> wins; the second caller returns <c>false</c>.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task TryTakeoverAsync_AfterLeaseExpires_OnlyFirstClaimerSucceeds()
+    {
+        var store = new InMemoryTranscodeSessionStore();
+        var session = CreateSession("session-stale", "pod-a", DateTime.UtcNow.AddMilliseconds(-1));
+        await store.SetAsync(session);
+
+        // First pod wins; its takeover renews the lease atomically.
+        var firstTakeover = await store.TryTakeoverAsync("session-stale", "pod-b");
+
+        // Second pod is too late – pod-b already holds a fresh lease.
+        var secondTakeover = await store.TryTakeoverAsync("session-stale", "pod-c");
+
+        Assert.True(firstTakeover);
+        Assert.False(secondTakeover);
+    }
+
+    /// <summary>
+    /// Heartbeat renewal: <see cref="ITranscodeSessionStore.RenewLeaseAsync"/> extends
+    /// <see cref="TranscodeSession.LeaseExpiresUtc"/> beyond its original value.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task RenewLeaseAsync_ExtendsLeaseExpiry()
+    {
+        var store = new InMemoryTranscodeSessionStore();
+        var originalExpiry = DateTime.UtcNow.AddSeconds(5);
+        var session = CreateSession("session-renew", "pod-a", originalExpiry, lastSegmentIndex: 2, lastOffset: 10_000_000L);
+        await store.SetAsync(session);
+
+        await store.RenewLeaseAsync("session-renew");
+
+        var renewed = await store.TryGetAsync("session-renew");
+        Assert.NotNull(renewed);
+        Assert.True(
+            renewed.LeaseExpiresUtc > originalExpiry,
+            "Renewed lease expiry should be later than the original expiry.");
+    }
+
+    /// <summary>
+    /// Stale-session cleanup: an expired session can be deleted without error, and a
+    /// subsequent <see cref="ITranscodeSessionStore.TryGetAsync"/> returns <c>null</c>.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task DeleteAsync_ExpiredSession_CompletesWithoutError()
+    {
+        var store = new InMemoryTranscodeSessionStore();
+        var session = CreateSession("session-delete", "pod-a", DateTime.UtcNow.AddMilliseconds(-1));
+        await store.SetAsync(session);
+
+        var ex = await Record.ExceptionAsync(() => store.DeleteAsync("session-delete"));
+        Assert.Null(ex);
+
+        var result = await store.TryGetAsync("session-delete");
+        Assert.Null(result);
+    }
+
+    /// <summary>
+    /// Deleting a session that was never stored must complete without error.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task DeleteAsync_NonExistentSession_CompletesWithoutError()
+    {
+        var store = new InMemoryTranscodeSessionStore();
+
+        var ex = await Record.ExceptionAsync(() => store.DeleteAsync("nonexistent-session"));
+
+        Assert.Null(ex);
+    }
+}

tests/Jellyfin.Server.Implementations.Tests/ScheduledTasks/DeleteTranscodeFileTaskTests.cs

@@ -0,0 +1,182 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using MediaBrowser.Controller.MediaEncoding;
+using Xunit;
+
+namespace Jellyfin.Server.Implementations.Tests.ScheduledTasks;
+
+/// <summary>
+/// Tests for lease-aware cleanup behavior expected of <c>DeleteTranscodeFileTask</c> once
+/// it is made HA-aware in Phase 5.2.
+/// <para>
+/// The current <c>DeleteTranscodeFileTask</c> implementation uses file-age only and does not
+/// check <see cref="ITranscodeSessionStore"/>, which creates a data-loss risk on shared NFS
+/// storage. These tests document the correct contract by exercising the store directly.
+/// </para>
+/// </summary>
+public class DeleteTranscodeFileTaskTests
+{
+    private static TranscodeSession CreateSession(string id, string pod, DateTime leaseExpiry)
+        => new TranscodeSession
+        {
+            PlaySessionId = id,
+            OwnerPod = pod,
+            LeaseExpiresUtc = leaseExpiry,
+            ManifestPath = $"/transcode/{id}/manifest.m3u8",
+            SegmentPathPrefix = $"/transcode/{id}/segment",
+            MediaSourceId = $"media-source-{id}",
+            LastCompletedSegmentIndex = 2,
+            LastDurablePlaybackOffset = 12_000_000L,
+        };
+
+    /// <summary>
+    /// A directory that belongs to a session with a live lease must NOT be deleted.
+    /// The store returns non-null, signalling to the cleanup task that the session is active.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task LiveLease_StoreReturnsSession_DirectoryShouldNotBeDeleted()
+    {
+        var store = new CleanupTestSessionStore();
+        var session = CreateSession("cleanup-session-1", "pod-a", DateTime.UtcNow.AddMinutes(5));
+        await store.SetAsync(session);
+
+        // The cleanup task should query the store before deleting.
+        var liveSession = await store.TryGetAsync("cleanup-session-1");
+
+        // Non-null result → lease is active → directory must be retained.
+        Assert.NotNull(liveSession);
+        Assert.Equal("pod-a", liveSession.OwnerPod);
+        Assert.True(liveSession.LeaseExpiresUtc > DateTime.UtcNow);
+    }
+
+    /// <summary>
+    /// A directory whose session lease has expired beyond the recovery window MAY be deleted.
+    /// The store returns <c>null</c>, signalling to the cleanup task that deletion is safe.
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task ExpiredBeyondRecoveryWindow_StoreReturnsNull_DirectoryMayBeDeleted()
+    {
+        var store = new CleanupTestSessionStore();
+
+        // Lease expired two hours ago – beyond any reasonable recovery window.
+        var session = CreateSession("cleanup-session-2", "pod-a", DateTime.UtcNow.AddHours(-2));
+        await store.SetAsync(session);
+
+        var liveSession = await store.TryGetAsync("cleanup-session-2");
+
+        // Null result → lease is expired → cleanup task may delete the directory.
+        Assert.Null(liveSession);
+    }
+
+    /// <summary>
+    /// When no session record exists in the store for a given directory, the cleanup task
+    /// should treat the directory as deletable (store returns <c>null</c>).
+    /// </summary>
+    [Fact]
+    [Trait("Category", "UnitTest")]
+    public async Task NoSessionRecord_StoreReturnsNull_DirectoryMayBeDeleted()
+    {
+        var store = new CleanupTestSessionStore();
+
+        var liveSession = await store.TryGetAsync("unknown-session");
+
+        Assert.Null(liveSession);
+    }
+
+    /// <summary>
+    /// Minimal in-memory <see cref="ITranscodeSessionStore"/> used within this test class
+    /// to avoid a cross-project reference to Jellyfin.MediaEncoding.Tests.
+    /// </summary>
+    private sealed class CleanupTestSessionStore : ITranscodeSessionStore
+    {
+        private static readonly TimeSpan LeaseDuration = TimeSpan.FromSeconds(30);
+
+        private readonly Dictionary<string, TranscodeSession> _sessions =
+            new(StringComparer.OrdinalIgnoreCase);
+
+        private readonly Lock _lock = new();
+
+        public Task<TranscodeSession?> TryGetAsync(string playSessionId, CancellationToken cancellationToken = default)
+        {
+            lock (_lock)
+            {
+                if (_sessions.TryGetValue(playSessionId, out var s) && s.LeaseExpiresUtc > DateTime.UtcNow)
+                {
+                    return Task.FromResult<TranscodeSession?>(Clone(s));
+                }
+
+                return Task.FromResult<TranscodeSession?>(null);
+            }
+        }
+
+        public Task<bool> TryTakeoverAsync(string playSessionId, string claimingPod, CancellationToken cancellationToken = default)
+        {
+            lock (_lock)
+            {
+                if (!_sessions.TryGetValue(playSessionId, out var s))
+                {
+                    return Task.FromResult(false);
+                }
+
+                if (s.LeaseExpiresUtc > DateTime.UtcNow)
+                {
+                    return Task.FromResult(false);
+                }
+
+                s.OwnerPod = claimingPod;
+                s.LeaseExpiresUtc = DateTime.UtcNow.Add(LeaseDuration);
+                return Task.FromResult(true);
+            }
+        }
+
+        public Task SetAsync(TranscodeSession session, CancellationToken cancellationToken = default)
+        {
+            lock (_lock)
+            {
+                _sessions[session.PlaySessionId] = session;
+            }
+
+            return Task.CompletedTask;
+        }
+
+        public Task RenewLeaseAsync(string playSessionId, CancellationToken cancellationToken = default)
+        {
+            lock (_lock)
+            {
+                if (_sessions.TryGetValue(playSessionId, out var s))
+                {
+                    s.LeaseExpiresUtc = DateTime.UtcNow.Add(LeaseDuration);
+                }
+            }
+
+            return Task.CompletedTask;
+        }
+
+        public Task DeleteAsync(string playSessionId, CancellationToken cancellationToken = default)
+        {
+            lock (_lock)
+            {
+                _sessions.Remove(playSessionId);
+            }
+
+            return Task.CompletedTask;
+        }
+
+        private static TranscodeSession Clone(TranscodeSession source)
+            => new TranscodeSession
+            {
+                PlaySessionId = source.PlaySessionId,
+                OwnerPod = source.OwnerPod,
+                LeaseExpiresUtc = source.LeaseExpiresUtc,
+                ManifestPath = source.ManifestPath,
+                SegmentPathPrefix = source.SegmentPathPrefix,
+                MediaSourceId = source.MediaSourceId,
+                LastCompletedSegmentIndex = source.LastCompletedSegmentIndex,
+                LastDurablePlaybackOffset = source.LastDurablePlaybackOffset,
+            };
+    }
+}