fix(session): parse the owner key without assuming the pod id

Ownership is claimed with a Lua check-and-set keyed on the instance holding
the websocket, routing prefers a live controller over a local copy, the
session list deduplicates by owner, removal is ownership-checked, undelivered
routed messages surface, single-session lookups stop scanning the keyspace and
directory writes leave the request path bounded by a timeout.

.woodpecker/ci.yaml

@@ -47,6 +47,7 @@ steps:
   # Its data directory lives on the step's ephemeral storage, not on the workspace volume.
   # Both projects attach to it through JELLYFIN_TEST_POSTGRES and give every test a database of
   # its own, so nothing here depends on a docker daemon.
+  # Valkey runs in the step for the same reason, reached through JELLYFIN_TEST_REDIS.
   - name: postgres-migration-chain
     image: mcr.microsoft.com/dotnet/sdk:10.0
     depends_on:
@@ -55,13 +56,16 @@ steps:
       DOTNET_CLI_TELEMETRY_OPTOUT: "1"
       DOTNET_NOLOGO: "1"
       JELLYFIN_TEST_POSTGRES: "Host=127.0.0.1;Port=5432;Database=postgres;Username=postgres"
+      JELLYFIN_TEST_REDIS: "127.0.0.1:6379"
     commands:
       - apt-get -o Acquire::Retries=3 update || apt-get -o Acquire::Retries=3 update
-      - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends postgresql
+      - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends postgresql valkey-server
       - install -d -o postgres -g postgres /tmp/pgdata /tmp/pgrun
       - PGBIN=$(ls -d /usr/lib/postgresql/*/bin | tail -1)
       - su postgres -c "$PGBIN/initdb -D /tmp/pgdata -A trust -U postgres"
       - su postgres -c "$PGBIN/pg_ctl -D /tmp/pgdata -o \"-c listen_addresses=127.0.0.1 -k /tmp/pgrun\" -l /tmp/pg.log -w start"
+      - valkey-server --daemonize yes --bind 127.0.0.1 --port 6379 --save ""
+      - for i in $(seq 30); do valkey-cli -h 127.0.0.1 ping && break; sleep 1; done
       - dotnet build tests/Jellyfin.Server.Tests/Jellyfin.Server.Tests.csproj -c Release
       - dotnet build tests/Jellyfin.Database.Tests.PostgreSQL/Jellyfin.Database.Tests.PostgreSQL.csproj -c Release
       - dotnet test tests/Jellyfin.Server.Tests/Jellyfin.Server.Tests.csproj -c Release --no-build --verbosity minimal --filter "Category=RequiresDocker"

Emby.Server.Implementations/Session/RedisPodMessageBus.cs

@@ -0,0 +1,95 @@
+using System;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Extensions.Json;
+using MediaBrowser.Controller.Session;
+using Microsoft.Extensions.Logging;
+using StackExchange.Redis;
+
+namespace Emby.Server.Implementations.Session;
+
+/// <summary>
+/// A Redis pub/sub <see cref="IPodMessageBus"/>. Every instance subscribes to a channel named after
+/// itself, which keeps addressed delivery working without the instances being routable to each other.
+/// </summary>
+public sealed class RedisPodMessageBus : IPodMessageBus
+{
+    private const string ChannelPrefix = "jellyfin:pod:";
+
+    private static readonly TimeSpan _publishTimeout = TimeSpan.FromSeconds(5);
+
+    private static readonly JsonSerializerOptions _jsonOptions = JsonDefaults.Options;
+
+    private readonly ISubscriber _subscriber;
+    private readonly ILogger<RedisPodMessageBus> _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RedisPodMessageBus"/> class.
+    /// </summary>
+    /// <param name="redis">The Redis connection multiplexer.</param>
+    /// <param name="logger">The logger.</param>
+    public RedisPodMessageBus(IConnectionMultiplexer redis, ILogger<RedisPodMessageBus> logger)
+    {
+        ArgumentNullException.ThrowIfNull(redis);
+
+        _subscriber = redis.GetSubscriber();
+        _logger = logger;
+        PodId = PodIdentity.Current;
+    }
+
+    /// <inheritdoc />
+    public string PodId { get; }
+
+    /// <inheritdoc />
+    public async Task<long> PublishAsync(string targetPod, PodMessage message, CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(targetPod);
+        ArgumentNullException.ThrowIfNull(message);
+
+        message.OriginPod = PodId;
+
+        try
+        {
+            return await _subscriber.PublishAsync(
+                RedisChannel.Literal(ChannelPrefix + targetPod),
+                JsonSerializer.Serialize(message, _jsonOptions)).WaitAsync(_publishTimeout, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Failed to send a {Kind} message to {TargetPod}.", message.Kind, targetPod);
+            return 0;
+        }
+    }
+
+    /// <inheritdoc />
+    public void Subscribe(Func<PodMessage, Task> handler)
+    {
+        ArgumentNullException.ThrowIfNull(handler);
+
+        try
+        {
+            _subscriber.Subscribe(RedisChannel.Literal(ChannelPrefix + PodId), (_, value) => Dispatch(handler, value));
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Failed to subscribe to {PodId}; messages routed here are dropped.", PodId);
+        }
+    }
+
+    private async void Dispatch(Func<PodMessage, Task> handler, RedisValue value)
+    {
+        try
+        {
+            var message = JsonSerializer.Deserialize<PodMessage>(value.ToString(), _jsonOptions);
+            if (message is not null)
+            {
+                await handler(message).ConfigureAwait(false);
+            }
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Failed to handle a message routed to this instance.");
+        }
+    }
+}

Emby.Server.Implementations/Session/RedisSessionDirectory.cs

@@ -0,0 +1,215 @@
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Extensions.Json;
+using MediaBrowser.Controller.Session;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using StackExchange.Redis;
+
+namespace Emby.Server.Implementations.Session;
+
+/// <summary>
+/// A Redis-backed <see cref="ISessionDirectory"/>. A session is owned by the instance holding its
+/// connection: ownership is claimed through a check-and-set, so an instance that only served a request
+/// for the session cannot take it from the instance the device is actually connected to. Each entry is a
+/// key with an expiry, so the sessions of an instance that stops refreshing them disappear on their own.
+/// </summary>
+public sealed class RedisSessionDirectory : ISessionDirectory
+{
+    private const string KeyPrefix = "jellyfin:session:";
+    private const string OwnerKeyPrefix = "jellyfin:sessionowner:";
+
+    /// <summary>
+    /// Lua script for an atomic ownership claim. The owner key holds <c>connectedTicks|pod</c>, where
+    /// the ticks are zero for an instance that holds no connection. A claim by another instance is
+    /// refused unless its connection is newer than the recorded one, so the instance holding the live
+    /// connection keeps ownership however many requests the others serve.
+    /// </summary>
+    private const string ClaimScript = @"
+local current = redis.call('GET', KEYS[1])
+if current then
+    local separator = string.find(current, '|', 1, true)
+    local connected = tonumber(string.sub(current, 1, separator - 1))
+    local owner = string.sub(current, separator + 1)
+    if owner ~= ARGV[1] and connected > 0 and tonumber(ARGV[2]) <= connected then
+        return 0
+    end
+end
+redis.call('SET', KEYS[1], ARGV[2] .. '|' .. ARGV[1], 'PX', ARGV[4])
+redis.call('SET', KEYS[2], ARGV[3], 'PX', ARGV[4])
+return 1";
+
+    /// <summary>
+    /// Lua script for an atomic, ownership-checked removal, so that an instance ending its own copy of a
+    /// session cannot erase the entry of the instance still holding the connection.
+    /// </summary>
+    private const string ReleaseScript = @"
+local current = redis.call('GET', KEYS[1])
+if not current then return 0 end
+local separator = string.find(current, '|', 1, true)
+if string.sub(current, separator + 1) ~= ARGV[1] then return 0 end
+redis.call('DEL', KEYS[1], KEYS[2])
+return 1";
+
+    private static readonly JsonSerializerOptions _jsonOptions = JsonDefaults.Options;
+
+    private readonly IConnectionMultiplexer _redis;
+    private readonly IDatabase _db;
+    private readonly SessionDirectoryOptions _options;
+    private readonly ILogger<RedisSessionDirectory> _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RedisSessionDirectory"/> class.
+    /// </summary>
+    /// <param name="redis">The Redis connection multiplexer.</param>
+    /// <param name="options">The session directory configuration options.</param>
+    /// <param name="logger">The logger.</param>
+    public RedisSessionDirectory(
+        IConnectionMultiplexer redis,
+        IOptions<SessionDirectoryOptions> options,
+        ILogger<RedisSessionDirectory> logger)
+    {
+        ArgumentNullException.ThrowIfNull(redis);
+        ArgumentNullException.ThrowIfNull(options);
+
+        _redis = redis;
+        _db = redis.GetDatabase();
+        _options = options.Value;
+        _logger = logger;
+    }
+
+    private long EntryTtlMs => Math.Max(1, _options.EntryTtlSeconds) * 1000L;
+
+    private TimeSpan OperationTimeout => TimeSpan.FromSeconds(Math.Max(1, _options.OperationTimeoutSeconds));
+
+    /// <inheritdoc />
+    public async Task<bool> PublishAsync(SessionDirectoryEntry entry, long connectedUtcTicks, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(entry);
+
+        var sessionId = entry.Session?.Id;
+        if (string.IsNullOrEmpty(sessionId))
+        {
+            return false;
+        }
+
+        try
+        {
+            var claimed = (long?)await _db.ScriptEvaluateAsync(
+                ClaimScript,
+                keys: new RedisKey[] { OwnerKeyPrefix + sessionId, KeyPrefix + sessionId },
+                values: new RedisValue[]
+                {
+                    entry.OwnerPod,
+                    connectedUtcTicks.ToString(CultureInfo.InvariantCulture),
+                    JsonSerializer.Serialize(entry, _jsonOptions),
+                    EntryTtlMs
+                }).WaitAsync(OperationTimeout, cancellationToken).ConfigureAwait(false);
+
+            return claimed == 1;
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Failed to publish session {SessionId}; it stays invisible to the other instances.", sessionId);
+            return false;
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task RemoveAsync(string sessionId, string ownerPod, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            await _db.ScriptEvaluateAsync(
+                ReleaseScript,
+                keys: new RedisKey[] { OwnerKeyPrefix + sessionId, KeyPrefix + sessionId },
+                values: new RedisValue[] { ownerPod }).WaitAsync(OperationTimeout, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Failed to remove session {SessionId}; it expires on its own.", sessionId);
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task<SessionDirectoryEntry?> GetAsync(string sessionId, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            var raw = await _db.StringGetAsync(KeyPrefix + sessionId).WaitAsync(OperationTimeout, cancellationToken).ConfigureAwait(false);
+
+            return raw.HasValue ? Deserialize(raw) : null;
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Failed to read session {SessionId} from the directory.", sessionId);
+            return null;
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<SessionDirectoryEntry>> GetAllAsync(CancellationToken cancellationToken = default)
+    {
+        var entries = new List<SessionDirectoryEntry>();
+
+        try
+        {
+            foreach (var server in _redis.GetServers())
+            {
+                if (!server.IsConnected)
+                {
+                    continue;
+                }
+
+                var keys = new List<RedisKey>();
+                await foreach (var key in server.KeysAsync(database: _db.Database, pattern: KeyPrefix + "*", pageSize: 1000).WithCancellation(cancellationToken).ConfigureAwait(false))
+                {
+                    keys.Add(key);
+                }
+
+                var values = await Task.WhenAll(keys.Select(key => _db.StringGetAsync(key)))
+                    .WaitAsync(OperationTimeout, cancellationToken).ConfigureAwait(false);
+
+                foreach (var raw in values)
+                {
+                    if (!raw.HasValue)
+                    {
+                        continue;
+                    }
+
+                    var entry = Deserialize(raw);
+                    if (entry?.Session is not null)
+                    {
+                        entries.Add(entry);
+                    }
+                }
+            }
+        }
+        catch (Exception ex)
+        {
+            // Degrade to the sessions this instance holds rather than failing the request outright.
+            _logger.LogWarning(ex, "Failed to read the session directory; only local sessions are reported.");
+            return Array.Empty<SessionDirectoryEntry>();
+        }
+
+        return entries;
+    }
+
+    private SessionDirectoryEntry? Deserialize(RedisValue raw)
+    {
+        try
+        {
+            return JsonSerializer.Deserialize<SessionDirectoryEntry>(raw.ToString(), _jsonOptions);
+        }
+        catch (JsonException ex)
+        {
+            _logger.LogWarning(ex, "Failed to deserialize a session directory entry.");
+            return null;
+        }
+    }
+}

Emby.Server.Implementations/Session/RemoteSessionController.cs

@@ -0,0 +1,76 @@
+using System;
+using System.Globalization;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Extensions.Json;
+using MediaBrowser.Common.Extensions;
+using MediaBrowser.Controller.Session;
+using MediaBrowser.Model.Session;
+using Microsoft.Extensions.Logging;
+
+namespace Emby.Server.Implementations.Session;
+
+/// <summary>
+/// Stands in for the websocket of a session another instance holds: messages are forwarded to that
+/// instance, which writes them to the connection it owns.
+/// </summary>
+public sealed class RemoteSessionController : ISessionController
+{
+    private readonly IPodMessageBus _bus;
+    private readonly ILogger _logger;
+    private readonly string _ownerPod;
+    private readonly string _sessionId;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RemoteSessionController"/> class.
+    /// </summary>
+    /// <param name="bus">The cross-instance bus.</param>
+    /// <param name="logger">The logger.</param>
+    /// <param name="ownerPod">The instance holding the connection.</param>
+    /// <param name="sessionId">The session identifier.</param>
+    /// <param name="supportsMediaControl">Whether the owner reported the session as controllable.</param>
+    public RemoteSessionController(IPodMessageBus bus, ILogger logger, string ownerPod, string sessionId, bool supportsMediaControl)
+    {
+        _bus = bus;
+        _logger = logger;
+        _ownerPod = ownerPod;
+        _sessionId = sessionId;
+        SupportsMediaControl = supportsMediaControl;
+    }
+
+    /// <inheritdoc />
+    public bool IsSessionActive => true;
+
+    /// <inheritdoc />
+    public bool SupportsMediaControl { get; }
+
+    /// <inheritdoc />
+    public async Task SendMessage<T>(SessionMessageType name, Guid messageId, T data, CancellationToken cancellationToken)
+    {
+        var routed = new RoutedSessionMessage
+        {
+            SessionId = _sessionId,
+            MessageType = name,
+            MessageId = messageId,
+            Data = JsonSerializer.Serialize(data, JsonDefaults.Options)
+        };
+
+        var delivered = await _bus.PublishAsync(
+            _ownerPod,
+            new PodMessage
+            {
+                Kind = RoutedSessionMessage.Kind,
+                Payload = JsonSerializer.Serialize(routed, JsonDefaults.Options)
+            },
+            cancellationToken).ConfigureAwait(false);
+
+        if (delivered == 0)
+        {
+            _logger.LogWarning("Instance {OwnerPod} holds session {SessionId} but is not listening; the {MessageType} message was not delivered.", _ownerPod, _sessionId, name);
+
+            throw new ResourceNotFoundException(
+                string.Format(CultureInfo.InvariantCulture, "The instance holding session {0} is unreachable.", _sessionId));
+        }
+    }
+}

Emby.Server.Implementations/Session/SessionManager.cs

@@ -5,6 +5,7 @@ using System.Collections.Concurrent;
 using System.Collections.Generic;
 using System.Globalization;
 using System.Linq;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
 using Jellyfin.Data;
@@ -15,6 +16,7 @@ using Jellyfin.Database.Implementations.Entities;
 using Jellyfin.Database.Implementations.Entities.Security;
 using Jellyfin.Database.Implementations.Enums;
 using Jellyfin.Extensions;
+using Jellyfin.Extensions.Json;
 using MediaBrowser.Common.Events;
 using MediaBrowser.Common.Extensions;
 using MediaBrowser.Controller;
@@ -39,6 +41,7 @@ using MediaBrowser.Model.SyncPlay;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
 using Episode = MediaBrowser.Controller.Entities.TV.Episode;
 
 namespace Emby.Server.Implementations.Session
@@ -60,15 +63,23 @@ namespace Emby.Server.Implementations.Session
         private readonly IMediaSourceManager _mediaSourceManager;
         private readonly IServerApplicationHost _appHost;
         private readonly IDeviceManager _deviceManager;
+        private readonly ISessionDirectory _sessionDirectory;
+        private readonly IPodMessageBus _podMessageBus;
+        private readonly SessionDirectoryOptions _sessionDirectoryOptions;
+        private readonly bool _directoryEnabled;
         private readonly CancellationTokenRegistration _shutdownCallback;
         private readonly ConcurrentDictionary<string, SessionInfo> _activeConnections
             = new(StringComparer.OrdinalIgnoreCase);
 
+        private readonly ConcurrentDictionary<string, long> _connectionEpochs = new(StringComparer.Ordinal);
+        private readonly ConcurrentDictionary<string, long> _lastDirectoryPublish = new(StringComparer.Ordinal);
+
         private readonly ConcurrentDictionary<string, ConcurrentDictionary<string, string>> _activeLiveStreamSessions
             = new(StringComparer.OrdinalIgnoreCase);
 
         private Timer _idleTimer;
         private Timer _inactiveTimer;
+        private Timer _directoryTimer;
 
         private DtoOptions _itemInfoDtoOptions;
         private bool _disposed;
@@ -89,6 +100,9 @@ namespace Emby.Server.Implementations.Session
         /// <param name="deviceManager">Instance of <see cref="IDeviceManager"/> interface.</param>
         /// <param name="mediaSourceManager">Instance of <see cref="IMediaSourceManager"/> interface.</param>
         /// <param name="hostApplicationLifetime">Instance of <see cref="IHostApplicationLifetime"/> interface.</param>
+        /// <param name="sessionDirectory">Instance of <see cref="ISessionDirectory"/> interface.</param>
+        /// <param name="podMessageBus">Instance of <see cref="IPodMessageBus"/> interface.</param>
+        /// <param name="sessionDirectoryOptions">The session directory options.</param>
         public SessionManager(
             ILogger<SessionManager> logger,
             IEventManager eventManager,
@@ -102,7 +116,10 @@ namespace Emby.Server.Implementations.Session
             IServerApplicationHost appHost,
             IDeviceManager deviceManager,
             IMediaSourceManager mediaSourceManager,
-            IHostApplicationLifetime hostApplicationLifetime)
+            IHostApplicationLifetime hostApplicationLifetime,
+            ISessionDirectory sessionDirectory,
+            IPodMessageBus podMessageBus,
+            IOptions<SessionDirectoryOptions> sessionDirectoryOptions)
         {
             _logger = logger;
             _eventManager = eventManager;
@@ -116,9 +133,21 @@ namespace Emby.Server.Implementations.Session
             _appHost = appHost;
             _deviceManager = deviceManager;
             _mediaSourceManager = mediaSourceManager;
+            _sessionDirectory = sessionDirectory;
+            _podMessageBus = podMessageBus;
+            _sessionDirectoryOptions = sessionDirectoryOptions.Value;
             _shutdownCallback = hostApplicationLifetime.ApplicationStopping.Register(OnApplicationStopping);
 
             _deviceManager.DeviceOptionsUpdated += OnDeviceManagerDeviceOptionsUpdated;
+
+            _directoryEnabled = _sessionDirectory is not NullSessionDirectory;
+
+            if (_directoryEnabled)
+            {
+                _podMessageBus.Subscribe(OnPodMessage);
+                var interval = TimeSpan.FromSeconds(Math.Max(1, _sessionDirectoryOptions.RefreshIntervalSeconds));
+                _directoryTimer = new Timer(RefreshSessionDirectory, null, interval, interval);
+            }
         }
 
         /// <summary>
@@ -218,6 +247,8 @@ namespace Emby.Server.Implementations.Session
 
             _eventManager.Publish(new SessionEndedEventArgs(info));
 
+            await RemoveFromDirectoryAsync(info).ConfigureAwait(false);
+
             await info.DisposeAsync().ConfigureAwait(false);
         }
 
@@ -288,11 +319,13 @@ namespace Emby.Server.Implementations.Session
                     });
             }
 
+            QueueDirectoryPublish(session);
+
             return session;
         }
 
         /// <inheritdoc />
-        public void OnSessionControllerConnected(SessionInfo session)
+        public async Task OnSessionControllerConnected(SessionInfo session)
         {
             EventHelper.QueueEventIfNotNull(
                 SessionControllerConnected,
@@ -302,6 +335,219 @@ namespace Emby.Server.Implementations.Session
                     SessionInfo = session
                 },
                 _logger);
+
+            // Ownership of the session belongs to whichever instance holds its connection, so this one
+            // claims it before the connection is used.
+            _lastDirectoryPublish[session.Id] = Environment.TickCount64;
+            await PublishToDirectoryAsync(session).ConfigureAwait(false);
+        }
+
+        // Keeps the directory write off the request path: the caller does not wait for Redis, and a
+        // session reporting playback every few seconds does not write on every report.
+        private void QueueDirectoryPublish(SessionInfo session)
+        {
+            if (!_directoryEnabled || string.IsNullOrEmpty(session.Id))
+            {
+                return;
+            }
+
+            var now = Environment.TickCount64;
+            var throttleMs = Math.Max(1000L, _sessionDirectoryOptions.RefreshIntervalSeconds * 500L);
+            var scheduled = _lastDirectoryPublish.AddOrUpdate(
+                session.Id,
+                now,
+                (_, last) => now - last >= throttleMs ? now : last);
+
+            if (scheduled == now)
+            {
+                _ = PublishToDirectoryAsync(session);
+            }
+        }
+
+        private async Task PublishToDirectoryAsync(SessionInfo session)
+        {
+            if (!_directoryEnabled || string.IsNullOrEmpty(session.Id))
+            {
+                return;
+            }
+
+            try
+            {
+                var connectedUtcTicks = GetConnectionEpoch(session);
+
+                await _sessionDirectory.PublishAsync(
+                    new SessionDirectoryEntry
+                    {
+                        OwnerPod = _podMessageBus.PodId,
+                        HoldsConnection = connectedUtcTicks > 0,
+                        Session = ToSessionInfoDto(session)
+                    },
+                    connectedUtcTicks).ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                _logger.LogDebug(ex, "Error publishing session {Session} to the directory.", session.Id);
+            }
+        }
+
+        // Ownership follows the connection, not the last request served: an instance without a live
+        // controller claims with epoch zero, which never displaces an instance that has one.
+        private long GetConnectionEpoch(SessionInfo session)
+        {
+            if (!session.SessionControllers.Any(i => i.IsSessionActive))
+            {
+                _connectionEpochs.TryRemove(session.Id, out _);
+                return 0;
+            }
+
+            return _connectionEpochs.GetOrAdd(session.Id, _ => DateTime.UtcNow.Ticks);
+        }
+
+        private async ValueTask RemoveFromDirectoryAsync(SessionInfo session)
+        {
+            _connectionEpochs.TryRemove(session.Id, out _);
+            _lastDirectoryPublish.TryRemove(session.Id, out _);
+
+            if (!_directoryEnabled || string.IsNullOrEmpty(session.Id))
+            {
+                return;
+            }
+
+            await _sessionDirectory.RemoveAsync(session.Id, _podMessageBus.PodId).ConfigureAwait(false);
+        }
+
+        private async void RefreshSessionDirectory(object state)
+        {
+            try
+            {
+                foreach (var session in _activeConnections.Values)
+                {
+                    await PublishToDirectoryAsync(session).ConfigureAwait(false);
+                }
+            }
+            catch (Exception ex)
+            {
+                _logger.LogDebug(ex, "Error refreshing the session directory.");
+            }
+        }
+
+        private async Task<IReadOnlyList<SessionDirectoryEntry>> GetRemoteEntriesAsync(CancellationToken cancellationToken)
+        {
+            if (!_directoryEnabled)
+            {
+                return Array.Empty<SessionDirectoryEntry>();
+            }
+
+            var entries = await _sessionDirectory.GetAllAsync(cancellationToken).ConfigureAwait(false);
+
+            return entries
+                .Where(entry => entry.Session is not null
+                    && !string.Equals(entry.OwnerPod, _podMessageBus.PodId, StringComparison.Ordinal))
+                .ToList();
+        }
+
+        private async Task<SessionInfo> GetRemoteSession(string sessionId)
+        {
+            if (!_directoryEnabled)
+            {
+                return null;
+            }
+
+            var entry = await _sessionDirectory.GetAsync(sessionId).ConfigureAwait(false);
+
+            if (entry?.Session is null
+                || string.Equals(entry.OwnerPod, _podMessageBus.PodId, StringComparison.Ordinal))
+            {
+                return null;
+            }
+
+            var dto = entry.Session;
+            var session = new SessionInfo(this, _logger)
+            {
+                Id = dto.Id,
+                UserId = dto.UserId,
+                UserName = dto.UserName,
+                Client = dto.Client,
+                DeviceId = dto.DeviceId,
+                DeviceName = dto.DeviceName,
+                DeviceType = dto.DeviceType,
+                ApplicationVersion = dto.ApplicationVersion,
+                RemoteEndPoint = dto.RemoteEndPoint,
+                LastActivityDate = dto.LastActivityDate,
+                ServerId = dto.ServerId,
+                AdditionalUsers = dto.AdditionalUsers ?? [],
+                Capabilities = dto.Capabilities?.ToClientCapabilities()
+            };
+
+            if (entry.HoldsConnection)
+            {
+                session.AddController(new RemoteSessionController(_podMessageBus, _logger, entry.OwnerPod, dto.Id, dto.SupportsMediaControl));
+            }
+
+            return session;
+        }
+
+        private Task OnPodMessage(PodMessage message)
+        {
+            switch (message.Kind)
+            {
+                case RoutedSessionMessage.Kind:
+                    return OnRoutedSessionMessage(message);
+                case RoutedAdditionalUserChange.Kind:
+                    OnRoutedAdditionalUserChange(message);
+                    return Task.CompletedTask;
+                default:
+                    return Task.CompletedTask;
+            }
+        }
+
+        private async Task OnRoutedSessionMessage(PodMessage message)
+        {
+            var routed = JsonSerializer.Deserialize<RoutedSessionMessage>(message.Payload, JsonDefaults.Options);
+            if (routed is null)
+            {
+                return;
+            }
+
+            var session = Sessions.FirstOrDefault(i => string.Equals(i.Id, routed.SessionId, StringComparison.Ordinal));
+            var controllers = session?.SessionControllers.Where(i => i.IsSessionActive).ToList();
+
+            if (controllers is null || controllers.Count == 0)
+            {
+                _logger.LogWarning(
+                    "A {MessageType} message for session {Session} was routed to this instance, which no longer holds its connection.",
+                    routed.MessageType,
+                    routed.SessionId);
+                return;
+            }
+
+            using var data = JsonDocument.Parse(routed.Data);
+            foreach (var controller in controllers)
+            {
+                await controller.SendMessage(routed.MessageType, routed.MessageId, data.RootElement, CancellationToken.None).ConfigureAwait(false);
+            }
+        }
+
+        private void OnRoutedAdditionalUserChange(PodMessage message)
+        {
+            var routed = JsonSerializer.Deserialize<RoutedAdditionalUserChange>(message.Payload, JsonDefaults.Options);
+            var session = routed is null
+                ? null
+                : Sessions.FirstOrDefault(i => string.Equals(i.Id, routed.SessionId, StringComparison.Ordinal));
+
+            if (session is null)
+            {
+                return;
+            }
+
+            if (routed.Add)
+            {
+                AttachAdditionalUser(session, routed.UserId, _userManager.GetUserById(routed.UserId)?.Username);
+            }
+            else
+            {
+                DetachAdditionalUser(session, routed.UserId);
+            }
         }
 
         /// <inheritdoc />
@@ -1219,10 +1465,18 @@ namespace Emby.Server.Implementations.Session
             return session;
         }
 
-        private SessionInfo GetSessionToRemoteControl(string sessionId)
+        // A local SessionInfo without a live controller is a copy left behind by a request this instance
+        // happened to serve, not the connection: prefer the owner named by the directory over it.
+        private async Task<SessionInfo> GetSessionToRemoteControl(string sessionId)
         {
-            // Accept either device id or session id
+            var local = Sessions.FirstOrDefault(i => string.Equals(i.Id, sessionId, StringComparison.Ordinal));
-            var session = Sessions.FirstOrDefault(i => string.Equals(i.Id, sessionId, StringComparison.Ordinal));
+
+            if (local is not null && local.SessionControllers.Any(i => i.IsSessionActive))
+            {
+                return local;
+            }
+
+            var session = await GetRemoteSession(sessionId).ConfigureAwait(false) ?? local;
 
             if (session is null)
             {
@@ -1291,19 +1545,19 @@ namespace Emby.Server.Implementations.Session
         }
 
         /// <inheritdoc />
-        public Task SendGeneralCommand(string controllingSessionId, string sessionId, GeneralCommand command, CancellationToken cancellationToken)
+        public async Task SendGeneralCommand(string controllingSessionId, string sessionId, GeneralCommand command, CancellationToken cancellationToken)
         {
             CheckDisposed();
 
-            var session = GetSessionToRemoteControl(sessionId);
+            var session = await GetSessionToRemoteControl(sessionId).ConfigureAwait(false);
 
             if (!string.IsNullOrEmpty(controllingSessionId))
             {
-                var controllingSession = GetSession(controllingSessionId);
+                var controllingSession = await GetSessionToRemoteControl(controllingSessionId).ConfigureAwait(false);
                 AssertCanControl(session, controllingSession);
             }
 
-            return SendMessageToSession(session, SessionMessageType.GeneralCommand, command, cancellationToken);
+            await SendMessageToSession(session, SessionMessageType.GeneralCommand, command, cancellationToken).ConfigureAwait(false);
         }
 
         private static async Task SendMessageToSession<T>(SessionInfo session, SessionMessageType name, T data, CancellationToken cancellationToken)
@@ -1340,7 +1594,7 @@ namespace Emby.Server.Implementations.Session
         {
             CheckDisposed();
 
-            var session = GetSessionToRemoteControl(sessionId);
+            var session = await GetSessionToRemoteControl(sessionId).ConfigureAwait(false);
 
             var user = session.UserId.IsEmpty() ? null : _userManager.GetUserById(session.UserId);
 
@@ -1410,7 +1664,7 @@ namespace Emby.Server.Implementations.Session
 
             if (!string.IsNullOrEmpty(controllingSessionId))
             {
-                var controllingSession = GetSession(controllingSessionId);
+                var controllingSession = await GetSessionToRemoteControl(controllingSessionId).ConfigureAwait(false);
                 AssertCanControl(session, controllingSession);
                 if (!controllingSession.UserId.IsEmpty())
                 {
@@ -1425,7 +1679,16 @@ namespace Emby.Server.Implementations.Session
         public async Task SendSyncPlayCommand(string sessionId, SendCommand command, CancellationToken cancellationToken)
         {
             CheckDisposed();
-            var session = GetSession(sessionId);
+
+            // SyncPlay group membership is instance-local, so a session listed by another instance is not
+            // reachable from here. It is skipped rather than reported as missing.
+            var session = GetSession(sessionId, false);
+            if (session is null)
+            {
+                _logger.LogDebug("SyncPlay command for session {Session} dropped; it is not held by this instance.", sessionId);
+                return;
+            }
+
             await SendMessageToSession(session, SessionMessageType.SyncPlayCommand, command, cancellationToken).ConfigureAwait(false);
         }
 
@@ -1433,7 +1696,14 @@ namespace Emby.Server.Implementations.Session
         public async Task SendSyncPlayGroupUpdate<T>(string sessionId, GroupUpdate<T> command, CancellationToken cancellationToken)
         {
             CheckDisposed();
-            var session = GetSession(sessionId);
+
+            var session = GetSession(sessionId, false);
+            if (session is null)
+            {
+                _logger.LogDebug("SyncPlay group update for session {Session} dropped; it is not held by this instance.", sessionId);
+                return;
+            }
+
             await SendMessageToSession(session, SessionMessageType.SyncPlayGroupUpdate, command, cancellationToken).ConfigureAwait(false);
         }
 
@@ -1521,15 +1791,15 @@ namespace Emby.Server.Implementations.Session
         }
 
         /// <inheritdoc />
-        public Task SendPlaystateCommand(string controllingSessionId, string sessionId, PlaystateRequest command, CancellationToken cancellationToken)
+        public async Task SendPlaystateCommand(string controllingSessionId, string sessionId, PlaystateRequest command, CancellationToken cancellationToken)
         {
             CheckDisposed();
 
-            var session = GetSessionToRemoteControl(sessionId);
+            var session = await GetSessionToRemoteControl(sessionId).ConfigureAwait(false);
 
             if (!string.IsNullOrEmpty(controllingSessionId))
             {
-                var controllingSession = GetSession(controllingSessionId);
+                var controllingSession = await GetSessionToRemoteControl(controllingSessionId).ConfigureAwait(false);
                 AssertCanControl(session, controllingSession);
                 if (!controllingSession.UserId.IsEmpty())
                 {
@@ -1537,7 +1807,7 @@ namespace Emby.Server.Implementations.Session
                 }
             }
 
-            return SendMessageToSession(session, SessionMessageType.Playstate, command, cancellationToken);
+            await SendMessageToSession(session, SessionMessageType.Playstate, command, cancellationToken).ConfigureAwait(false);
         }
 
         private void AssertCanControl(SessionInfo session, SessionInfo controllingSession)
@@ -1606,17 +1876,18 @@ namespace Emby.Server.Implementations.Session
         /// <param name="controllingSessionId">The controlling session identifier.</param>
         /// <param name="sessionId">The session identifier.</param>
         /// <param name="userId">The user identifier.</param>
+        /// <returns>A task representing the operation.</returns>
         /// <exception cref="SecurityException">The controlling user is not allowed to attach the user to the session.</exception>
         /// <exception cref="ArgumentException">The requested user is already the primary user of the session.</exception>
-        public void AddAdditionalUser(string controllingSessionId, string sessionId, Guid userId)
+        public async Task AddAdditionalUser(string controllingSessionId, string sessionId, Guid userId)
         {
             CheckDisposed();
 
-            var session = GetSession(sessionId);
+            var session = await GetSessionToRemoteControl(sessionId).ConfigureAwait(false);
 
             if (!string.IsNullOrEmpty(controllingSessionId))
             {
-                var controllingSession = GetSession(controllingSessionId);
+                var controllingSession = await GetSessionToRemoteControl(controllingSessionId).ConfigureAwait(false);
                 AssertCanControl(session, controllingSession);
                 AssertCanAttachUser(controllingSession, userId);
             }
@@ -1626,18 +1897,16 @@ namespace Emby.Server.Implementations.Session
                 throw new ArgumentException("The requested user is already the primary user of the session.");
             }
 
-            if (session.AdditionalUsers.All(i => !i.UserId.Equals(userId)))
+            var user = _userManager.GetUserById(userId)
-            {
+                ?? throw new ArgumentException("The requested user does not exist.");
-                var user = _userManager.GetUserById(userId)
-                    ?? throw new ArgumentException("The requested user does not exist.");
-                var newUser = new SessionUserInfo
-                {
-                    UserId = userId,
-                    UserName = user.Username
-                };
 
-                session.AdditionalUsers = [.. session.AdditionalUsers, newUser];
+            var local = GetSession(sessionId, false);
+            if (local is not null)
+            {
+                AttachAdditionalUser(local, userId, user.Username);
             }
+
+            await RouteAdditionalUserChange(sessionId, userId, true).ConfigureAwait(false);
         }
 
         /// <summary>
@@ -1646,17 +1915,18 @@ namespace Emby.Server.Implementations.Session
         /// <param name="controllingSessionId">The controlling session identifier.</param>
         /// <param name="sessionId">The session identifier.</param>
         /// <param name="userId">The user identifier.</param>
+        /// <returns>A task representing the operation.</returns>
         /// <exception cref="SecurityException">The controlling user is not allowed to control the session.</exception>
         /// <exception cref="ArgumentException">The requested user is already the primary user of the session.</exception>
-        public void RemoveAdditionalUser(string controllingSessionId, string sessionId, Guid userId)
+        public async Task RemoveAdditionalUser(string controllingSessionId, string sessionId, Guid userId)
         {
             CheckDisposed();
 
-            var session = GetSession(sessionId);
+            var session = await GetSessionToRemoteControl(sessionId).ConfigureAwait(false);
 
             if (!string.IsNullOrEmpty(controllingSessionId))
             {
-                AssertCanControl(session, GetSession(controllingSessionId));
+                AssertCanControl(session, await GetSessionToRemoteControl(controllingSessionId).ConfigureAwait(false));
             }
 
             if (session.UserId.Equals(userId))
@@ -1664,17 +1934,73 @@ namespace Emby.Server.Implementations.Session
                 throw new ArgumentException("The requested user is already the primary user of the session.");
             }
 
-            var user = session.AdditionalUsers.FirstOrDefault(i => i.UserId.Equals(userId));
+            var local = GetSession(sessionId, false);
+            if (local is not null)
+            {
+                DetachAdditionalUser(local, userId);
+            }
 
-            if (user is not null)
+            await RouteAdditionalUserChange(sessionId, userId, false).ConfigureAwait(false);
+        }
+
+        private static void AttachAdditionalUser(SessionInfo session, Guid userId, string userName)
+        {
+            if (session.AdditionalUsers.All(i => !i.UserId.Equals(userId)))
+            {
+                session.AdditionalUsers = [.. session.AdditionalUsers, new SessionUserInfo { UserId = userId, UserName = userName }];
+            }
+        }
+
+        private static void DetachAdditionalUser(SessionInfo session, Guid userId)
+        {
+            var existing = session.AdditionalUsers.FirstOrDefault(i => i.UserId.Equals(userId));
+
+            if (existing is not null)
             {
                 var list = session.AdditionalUsers.ToList();
-                list.Remove(user);
+                list.Remove(existing);
 
                 session.AdditionalUsers = list.ToArray();
             }
         }
 
+        // The owner is the instance whose copy of the session is the one everyone else is shown, so the
+        // change has to be applied there as well as on whichever instance served the request.
+        private async Task RouteAdditionalUserChange(string sessionId, Guid userId, bool add)
+        {
+            if (!_directoryEnabled)
+            {
+                return;
+            }
+
+            var entry = await _sessionDirectory.GetAsync(sessionId).ConfigureAwait(false);
+
+            if (entry is null || string.Equals(entry.OwnerPod, _podMessageBus.PodId, StringComparison.Ordinal))
+            {
+                return;
+            }
+
+            var payload = new RoutedAdditionalUserChange
+            {
+                SessionId = sessionId,
+                UserId = userId,
+                Add = add
+            };
+
+            var delivered = await _podMessageBus.PublishAsync(
+                entry.OwnerPod,
+                new PodMessage
+                {
+                    Kind = RoutedAdditionalUserChange.Kind,
+                    Payload = JsonSerializer.Serialize(payload, JsonDefaults.Options)
+                }).ConfigureAwait(false);
+
+            if (delivered == 0)
+            {
+                _logger.LogWarning("Instance {OwnerPod} holds session {Session} but is not listening; the additional user change was not applied there.", entry.OwnerPod, sessionId);
+            }
+        }
+
         /// <summary>
         /// Authenticates the new session.
         /// </summary>
@@ -2060,14 +2386,25 @@ namespace Emby.Server.Implementations.Session
         }
 
         /// <inheritdoc/>
-        public IReadOnlyList<SessionInfoDto> GetSessions(
+        public async Task<IReadOnlyList<SessionInfoDto>> GetSessions(
             Guid userId,
             string deviceId,
             int? activeWithinSeconds,
             Guid? controllableUserToCheck,
-            bool isApiKey)
+            bool isApiKey,
+            CancellationToken cancellationToken)
         {
-            var result = Sessions;
+            var remote = await GetRemoteEntriesAsync(cancellationToken).ConfigureAwait(false);
+            var ownedElsewhere = remote.Select(entry => entry.Session.Id).ToHashSet(StringComparer.Ordinal);
+
+            // A session this instance only holds a copy of is reported by its owner, whose controllers are
+            // the ones that decide whether it is active and controllable.
+            IEnumerable<SessionInfoDto> result = Sessions
+                .Where(i => !ownedElsewhere.Contains(i.Id))
+                .Select(ToSessionInfoDto)
+                .Concat(remote.Select(entry => entry.Session))
+                .OrderByDescending(i => i.LastActivityDate);
+
             if (!string.IsNullOrEmpty(deviceId))
             {
                 result = result.Where(i => string.Equals(i.DeviceId, deviceId, StringComparison.OrdinalIgnoreCase));
@@ -2115,7 +2452,7 @@ namespace Emby.Server.Implementations.Session
                 if (!userCanControlOthers)
                 {
                     // User cannot control other user's sessions, validate user id.
-                    result = result.Where(i => i.UserId.IsEmpty() || i.ContainsUser(userId));
+                    result = result.Where(i => i.UserId.IsEmpty() || ContainsUser(i, userId));
                 }
 
                 result = result.Where(i =>
@@ -2136,7 +2473,7 @@ namespace Emby.Server.Implementations.Session
             else if (!userIsAdmin)
             {
                 // Request isn't from administrator, limit to "own" sessions.
-                result = result.Where(i => i.UserId.IsEmpty() || i.ContainsUser(userId));
+                result = result.Where(i => i.UserId.IsEmpty() || ContainsUser(i, userId));
             }
 
             if (!userIsAdmin)
@@ -2159,7 +2496,18 @@ namespace Emby.Server.Implementations.Session
                 result = result.Where(i => i.LastActivityDate >= minActiveDate);
             }
 
-            return result.Select(ToSessionInfoDto).ToList();
+            return result.ToList();
+        }
+
+        private static bool ContainsUser(SessionInfoDto session, Guid userId)
+        {
+            if (session.UserId.Equals(userId))
+            {
+                return true;
+            }
+
+            return session.AdditionalUsers is not null
+                && session.AdditionalUsers.Any(i => i.UserId.Equals(userId));
         }
 
         /// <inheritdoc />
@@ -2234,6 +2582,12 @@ namespace Emby.Server.Implementations.Session
                 _inactiveTimer = null;
             }
 
+            if (_directoryTimer is not null)
+            {
+                await _directoryTimer.DisposeAsync().ConfigureAwait(false);
+                _directoryTimer = null;
+            }
+
             await _shutdownCallback.DisposeAsync().ConfigureAwait(false);
 
             _deviceManager.DeviceOptionsUpdated -= OnDeviceManagerDeviceOptionsUpdated;
@@ -2257,6 +2611,7 @@ namespace Emby.Server.Implementations.Session
             // Close open websockets to allow Kestrel to shut down cleanly
             foreach (var session in _activeConnections.Values)
             {
+                await RemoveFromDirectoryAsync(session).ConfigureAwait(false);
                 await session.DisposeAsync().ConfigureAwait(false);
             }
 

Emby.Server.Implementations/Session/SessionWebSocketListener.cs

@@ -114,11 +114,11 @@ namespace Emby.Server.Implementations.Session
         public async Task ProcessWebSocketConnectedAsync(IWebSocketConnection connection, HttpContext httpContext)
         {
             var session = await RequestHelpers.GetSession(_sessionManager, _userManager, httpContext).ConfigureAwait(false);
-            EnsureController(session, connection);
+            await EnsureController(session, connection).ConfigureAwait(false);
             await KeepAliveWebSocket(connection).ConfigureAwait(false);
         }
 
-        private void EnsureController(SessionInfo session, IWebSocketConnection connection)
+        private async Task EnsureController(SessionInfo session, IWebSocketConnection connection)
         {
             var controllerInfo = session.EnsureController<WebSocketController>(
                 s => new WebSocketController(_loggerFactory.CreateLogger<WebSocketController>(), s, _sessionManager));
@@ -126,7 +126,7 @@ namespace Emby.Server.Implementations.Session
             var controller = (WebSocketController)controllerInfo.Item1;
             controller.AddWebSocket(connection);
 
-            _sessionManager.OnSessionControllerConnected(session);
+            await _sessionManager.OnSessionControllerConnected(session).ConfigureAwait(false);
         }
 
         /// <summary>

Jellyfin.Api/Controllers/SessionController.cs

@@ -52,18 +52,19 @@ public class SessionController : BaseJellyfinApiController
     [HttpGet("Sessions")]
     [Authorize]
     [ProducesResponseType(StatusCodes.Status200OK)]
-    public ActionResult<IReadOnlyList<SessionInfoDto>> GetSessions(
+    public async Task<ActionResult<IReadOnlyList<SessionInfoDto>>> GetSessions(
         [FromQuery] Guid? controllableByUserId,
         [FromQuery] string? deviceId,
         [FromQuery] int? activeWithinSeconds)
     {
         Guid? controllableUserToCheck = controllableByUserId is null ? null : RequestHelpers.GetUserId(User, controllableByUserId);
-        var result = _sessionManager.GetSessions(
+        var result = await _sessionManager.GetSessions(
             User.GetUserId(),
             deviceId,
             activeWithinSeconds,
             controllableUserToCheck,
-            User.GetIsApiKey());
+            User.GetIsApiKey(),
+            HttpContext.RequestAborted).ConfigureAwait(false);
 
         return Ok(result);
     }
@@ -310,10 +311,10 @@ public class SessionController : BaseJellyfinApiController
         [FromRoute, Required] string sessionId,
         [FromRoute, Required] Guid userId)
     {
-        _sessionManager.AddAdditionalUser(
+        await _sessionManager.AddAdditionalUser(
             await RequestHelpers.GetSessionId(_sessionManager, _userManager, HttpContext).ConfigureAwait(false),
             sessionId,
-            userId);
+            userId).ConfigureAwait(false);
         return NoContent();
     }
 
@@ -331,10 +332,10 @@ public class SessionController : BaseJellyfinApiController
         [FromRoute, Required] string sessionId,
         [FromRoute, Required] Guid userId)
     {
-        _sessionManager.RemoveAdditionalUser(
+        await _sessionManager.RemoveAdditionalUser(
             await RequestHelpers.GetSessionId(_sessionManager, _userManager, HttpContext).ConfigureAwait(false),
             sessionId,
-            userId);
+            userId).ConfigureAwait(false);
         return NoContent();
     }
 

Jellyfin.Server/CoreAppHost.cs

@@ -116,6 +116,10 @@ namespace Jellyfin.Server
             // to the other instances. Redis-backed when configured, no-op otherwise.
             serviceCollection.AddConfigurationInvalidationBus(_startupConfig, Logger);
 
+            // Session directory: publishes which instance holds which session and routes remote-control
+            // messages to it. Redis-backed when configured, no-op otherwise.
+            serviceCollection.AddSessionDirectory(_startupConfig, Logger);
+
             foreach (var type in GetExportTypes<ILyricProvider>())
             {
                 serviceCollection.AddSingleton(typeof(ILyricProvider), type);

Jellyfin.Server/Extensions/SessionDirectoryServiceCollectionExtensions.cs

@@ -0,0 +1,83 @@
+using System;
+using Emby.Server.Implementations.Session;
+using MediaBrowser.Controller.MediaEncoding;
+using MediaBrowser.Controller.Session;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using StackExchange.Redis;
+
+namespace Jellyfin.Server.Extensions;
+
+/// <summary>
+/// Extensions for registering the session directory and the instance-addressed message bus.
+/// </summary>
+public static class SessionDirectoryServiceCollectionExtensions
+{
+    /// <summary>
+    /// Registers the session directory and message bus, Redis-backed when a connection string is
+    /// configured and no-op otherwise, and reports the selection at <see cref="LogLevel.Information"/>.
+    /// </summary>
+    /// <param name="serviceCollection">The service collection.</param>
+    /// <param name="configuration">The configuration to read <c>Jellyfin:SessionDirectory</c> from.</param>
+    /// <param name="logger">The logger to report the selection on.</param>
+    /// <returns>The updated service collection.</returns>
+    public static IServiceCollection AddSessionDirectory(
+        this IServiceCollection serviceCollection,
+        IConfiguration configuration,
+        ILogger logger)
+    {
+        ArgumentNullException.ThrowIfNull(configuration);
+        ArgumentNullException.ThrowIfNull(logger);
+
+        serviceCollection.Configure<SessionDirectoryOptions>(configuration.GetSection(SessionDirectoryOptions.ConfigurationSection));
+
+        if (string.IsNullOrEmpty(configuration[TranscodeStoreOptions.RedisConnectionStringKey]))
+        {
+            logger.LogInformation(
+                "Session directory: {Directory}. The session list and remote control only reach the sessions this instance holds; set {Key} to share them.",
+                nameof(NullSessionDirectory),
+                TranscodeStoreOptions.RedisConnectionStringKey);
+
+            serviceCollection.AddSingleton<ISessionDirectory>(NullSessionDirectory.Instance);
+            return serviceCollection.AddSingleton<IPodMessageBus>(NullPodMessageBus.Instance);
+        }
+
+        logger.LogInformation(
+            "Session directory: {Directory}. Sessions are visible to, and controllable from, every instance.",
+            nameof(RedisSessionDirectory));
+
+        serviceCollection.AddSingleton<IPodMessageBus>(sp => Create<IPodMessageBus>(
+            sp,
+            () => new RedisPodMessageBus(
+                sp.GetRequiredService<IConnectionMultiplexer>(),
+                sp.GetRequiredService<ILogger<RedisPodMessageBus>>()),
+            NullPodMessageBus.Instance));
+
+        return serviceCollection.AddSingleton<ISessionDirectory>(sp => Create<ISessionDirectory>(
+            sp,
+            () => new RedisSessionDirectory(
+                sp.GetRequiredService<IConnectionMultiplexer>(),
+                sp.GetRequiredService<Microsoft.Extensions.Options.IOptions<SessionDirectoryOptions>>(),
+                sp.GetRequiredService<ILogger<RedisSessionDirectory>>()),
+            NullSessionDirectory.Instance));
+    }
+
+    // Fail open: an unreachable Redis degrades to the single-instance behaviour rather than aborting startup.
+    private static T Create<T>(IServiceProvider serviceProvider, Func<T> factory, T fallback)
+    {
+        try
+        {
+            return factory();
+        }
+        catch (Exception ex)
+        {
+            serviceProvider.GetRequiredService<ILogger<CoreAppHost>>().LogError(
+                ex,
+                "Redis is configured but unavailable, so sessions will not be shared between instances. Check {Key}.",
+                TranscodeStoreOptions.RedisConnectionStringKey);
+
+            return fallback;
+        }
+    }
+}

MediaBrowser.Controller/Session/IPodMessageBus.cs

@@ -0,0 +1,33 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// Point-to-point delivery between instances: every instance listens on a channel of its own, so a
+/// message can be addressed to the one instance holding a given connection.
+/// </summary>
+public interface IPodMessageBus
+{
+    /// <summary>
+    /// Gets the identity of this instance.
+    /// </summary>
+    string PodId { get; }
+
+    /// <summary>
+    /// Sends a message to one instance and reports how many listeners took it, so that a message
+    /// addressed to an instance that is no longer there is not mistaken for a delivered one.
+    /// </summary>
+    /// <param name="targetPod">The instance to deliver to.</param>
+    /// <param name="message">The message.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The number of instances the message reached.</returns>
+    Task<long> PublishAsync(string targetPod, PodMessage message, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Registers a handler for the messages addressed to this instance.
+    /// </summary>
+    /// <param name="handler">The handler.</param>
+    void Subscribe(Func<PodMessage, Task> handler);
+}

MediaBrowser.Controller/Session/ISessionDirectory.cs

@@ -0,0 +1,47 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// The shared record of which instance holds which session. Entries expire, so an instance that stops
+/// refreshing them drops out of every other instance's view instead of lingering.
+/// </summary>
+public interface ISessionDirectory
+{
+    /// <summary>
+    /// Claims a session for the publishing instance and restarts its expiry. The claim is refused when
+    /// another instance holds the connection, so an instance that merely served a request for the session
+    /// cannot take ownership of it.
+    /// </summary>
+    /// <param name="entry">The entry.</param>
+    /// <param name="connectedUtcTicks">When the publishing instance's connection to the session was established, or zero when it holds none.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns><c>true</c> if the entry was written.</returns>
+    Task<bool> PublishAsync(SessionDirectoryEntry entry, long connectedUtcTicks, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes an entry, but only while the calling instance still owns it.
+    /// </summary>
+    /// <param name="sessionId">The session identifier.</param>
+    /// <param name="ownerPod">The instance requesting the removal.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the operation.</returns>
+    Task RemoveAsync(string sessionId, string ownerPod, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets one entry by session identifier.
+    /// </summary>
+    /// <param name="sessionId">The session identifier.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The entry, or <c>null</c> when the session is in no instance's directory.</returns>
+    Task<SessionDirectoryEntry?> GetAsync(string sessionId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets every entry that has not expired.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The entries.</returns>
+    Task<IReadOnlyList<SessionDirectoryEntry>> GetAllAsync(CancellationToken cancellationToken = default);
+}

MediaBrowser.Controller/Session/ISessionManager.cs

@@ -80,7 +80,8 @@ namespace MediaBrowser.Controller.Session
         /// Used to report that a session controller has connected.
         /// </summary>
         /// <param name="session">The session.</param>
-        void OnSessionControllerConnected(SessionInfo session);
+        /// <returns>A task representing the operation.</returns>
+        Task OnSessionControllerConnected(SessionInfo session);
 
         void UpdateDeviceName(string sessionId, string reportedDeviceName);
 
@@ -241,7 +242,8 @@ namespace MediaBrowser.Controller.Session
         /// <param name="controllingSessionId">The controlling session identifier.</param>
         /// <param name="sessionId">The session identifier.</param>
         /// <param name="userId">The user identifier.</param>
-        void AddAdditionalUser(string controllingSessionId, string sessionId, Guid userId);
+        /// <returns>A task representing the operation.</returns>
+        Task AddAdditionalUser(string controllingSessionId, string sessionId, Guid userId);
 
         /// <summary>
         /// Removes the additional user.
@@ -249,7 +251,8 @@ namespace MediaBrowser.Controller.Session
         /// <param name="controllingSessionId">The controlling session identifier.</param>
         /// <param name="sessionId">The session identifier.</param>
         /// <param name="userId">The user identifier.</param>
-        void RemoveAdditionalUser(string controllingSessionId, string sessionId, Guid userId);
+        /// <returns>A task representing the operation.</returns>
+        Task RemoveAdditionalUser(string controllingSessionId, string sessionId, Guid userId);
 
         /// <summary>
         /// Reports the now viewing item.
@@ -306,8 +309,9 @@ namespace MediaBrowser.Controller.Session
         /// <param name="activeWithinSeconds">Active within session limit.</param>
         /// <param name="controllableUserToCheck">Filter for sessions remote controllable for this user.</param>
         /// <param name="isApiKey">Is the request authenticated with API key.</param>
-        /// <returns>IReadOnlyList{SessionInfoDto}.</returns>
+        /// <param name="cancellationToken">The cancellation token.</param>
-        IReadOnlyList<SessionInfoDto> GetSessions(Guid userId, string deviceId, int? activeWithinSeconds, Guid? controllableUserToCheck, bool isApiKey);
+        /// <returns>IReadOnlyList{SessionInfoDto}, including the sessions held by the other instances.</returns>
+        Task<IReadOnlyList<SessionInfoDto>> GetSessions(Guid userId, string deviceId, int? activeWithinSeconds, Guid? controllableUserToCheck, bool isApiKey, CancellationToken cancellationToken);
 
         /// <summary>
         /// Gets the session by authentication token.

MediaBrowser.Controller/Session/NullPodMessageBus.cs

@@ -0,0 +1,28 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// The single-instance <see cref="IPodMessageBus"/>: there is no other instance to reach.
+/// </summary>
+public sealed class NullPodMessageBus : IPodMessageBus
+{
+    /// <summary>
+    /// Gets the shared instance.
+    /// </summary>
+    public static NullPodMessageBus Instance { get; } = new NullPodMessageBus();
+
+    /// <inheritdoc />
+    public string PodId => PodIdentity.Current;
+
+    /// <inheritdoc />
+    public Task<long> PublishAsync(string targetPod, PodMessage message, CancellationToken cancellationToken = default)
+        => Task.FromResult(0L);
+
+    /// <inheritdoc />
+    public void Subscribe(Func<PodMessage, Task> handler)
+    {
+    }
+}

MediaBrowser.Controller/Session/NullSessionDirectory.cs

@@ -0,0 +1,34 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// The single-instance <see cref="ISessionDirectory"/>: nothing is published and no session is held
+/// anywhere but here, which is exactly the behaviour of a deployment without a shared store.
+/// </summary>
+public sealed class NullSessionDirectory : ISessionDirectory
+{
+    /// <summary>
+    /// Gets the shared instance.
+    /// </summary>
+    public static NullSessionDirectory Instance { get; } = new NullSessionDirectory();
+
+    /// <inheritdoc />
+    public Task<bool> PublishAsync(SessionDirectoryEntry entry, long connectedUtcTicks, CancellationToken cancellationToken = default)
+        => Task.FromResult(false);
+
+    /// <inheritdoc />
+    public Task RemoveAsync(string sessionId, string ownerPod, CancellationToken cancellationToken = default)
+        => Task.CompletedTask;
+
+    /// <inheritdoc />
+    public Task<SessionDirectoryEntry?> GetAsync(string sessionId, CancellationToken cancellationToken = default)
+        => Task.FromResult<SessionDirectoryEntry?>(null);
+
+    /// <inheritdoc />
+    public Task<IReadOnlyList<SessionDirectoryEntry>> GetAllAsync(CancellationToken cancellationToken = default)
+        => Task.FromResult<IReadOnlyList<SessionDirectoryEntry>>(Array.Empty<SessionDirectoryEntry>());
+}

MediaBrowser.Controller/Session/PodIdentity.cs

@@ -0,0 +1,14 @@
+using System;
+
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// The identity of this instance among the replicas sharing a deployment.
+/// </summary>
+public static class PodIdentity
+{
+    /// <summary>
+    /// Gets the identity of this instance.
+    /// </summary>
+    public static string Current => Environment.GetEnvironmentVariable("JELLYFIN_INSTANCE_ID") ?? Environment.MachineName;
+}

MediaBrowser.Controller/Session/PodMessage.cs

@@ -0,0 +1,23 @@
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// An envelope addressed to one instance. <see cref="Kind"/> names the payload so that features other
+/// than session routing can share the same channel.
+/// </summary>
+public sealed class PodMessage
+{
+    /// <summary>
+    /// Gets or sets the payload discriminator.
+    /// </summary>
+    public string Kind { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the identity of the sending instance.
+    /// </summary>
+    public string OriginPod { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the serialized payload.
+    /// </summary>
+    public string Payload { get; set; } = string.Empty;
+}

MediaBrowser.Controller/Session/RoutedAdditionalUserChange.cs

@@ -0,0 +1,30 @@
+using System;
+
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// An additional-user change for a session held by another instance, carried as a
+/// <see cref="PodMessage"/>. The calling instance has already authorized it.
+/// </summary>
+public sealed class RoutedAdditionalUserChange
+{
+    /// <summary>
+    /// The <see cref="PodMessage.Kind"/> this payload travels under.
+    /// </summary>
+    public const string Kind = "AdditionalUserChange";
+
+    /// <summary>
+    /// Gets or sets the session the change applies to.
+    /// </summary>
+    public string SessionId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the user to attach or detach.
+    /// </summary>
+    public Guid UserId { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the user is being attached rather than detached.
+    /// </summary>
+    public bool Add { get; set; }
+}

MediaBrowser.Controller/Session/RoutedSessionMessage.cs

@@ -0,0 +1,35 @@
+using System;
+using MediaBrowser.Model.Session;
+
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// A websocket message for a session held by another instance, carried as a <see cref="PodMessage"/>.
+/// </summary>
+public sealed class RoutedSessionMessage
+{
+    /// <summary>
+    /// The <see cref="PodMessage.Kind"/> this payload travels under.
+    /// </summary>
+    public const string Kind = "SessionMessage";
+
+    /// <summary>
+    /// Gets or sets the session the message is addressed to.
+    /// </summary>
+    public string SessionId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the message type.
+    /// </summary>
+    public SessionMessageType MessageType { get; set; }
+
+    /// <summary>
+    /// Gets or sets the message identifier.
+    /// </summary>
+    public Guid MessageId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the message data, serialized as JSON.
+    /// </summary>
+    public string Data { get; set; } = "null";
+}

MediaBrowser.Controller/Session/SessionDirectoryEntry.cs

@@ -0,0 +1,25 @@
+using MediaBrowser.Model.Dto;
+
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// A session held by one instance, as the other instances see it.
+/// </summary>
+public sealed class SessionDirectoryEntry
+{
+    /// <summary>
+    /// Gets or sets the identity of the instance holding the connection.
+    /// </summary>
+    public string OwnerPod { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the owner holds a live connection to the session. Only an
+    /// owner that does can be routed a remote-control message.
+    /// </summary>
+    public bool HoldsConnection { get; set; }
+
+    /// <summary>
+    /// Gets or sets the session as its owner last rendered it.
+    /// </summary>
+    public SessionInfoDto? Session { get; set; }
+}

MediaBrowser.Controller/Session/SessionDirectoryOptions.cs

@@ -0,0 +1,28 @@
+namespace MediaBrowser.Controller.Session;
+
+/// <summary>
+/// Configuration options for the session directory and the cross-instance bus that goes with it.
+/// </summary>
+public sealed class SessionDirectoryOptions
+{
+    /// <summary>
+    /// The configuration section these options bind from.
+    /// </summary>
+    public const string ConfigurationSection = "Jellyfin:SessionDirectory";
+
+    /// <summary>
+    /// Gets or sets how long in seconds a published entry survives without being refreshed. An instance
+    /// that dies stops refreshing, so its sessions leave the directory after this long.
+    /// </summary>
+    public int EntryTtlSeconds { get; set; } = 60;
+
+    /// <summary>
+    /// Gets or sets how often in seconds an instance republishes the sessions it holds.
+    /// </summary>
+    public int RefreshIntervalSeconds { get; set; } = 20;
+
+    /// <summary>
+    /// Gets or sets how long in seconds a single directory operation may take before it is abandoned.
+    /// </summary>
+    public int OperationTimeoutSeconds { get; set; } = 5;
+}

README.md

@@ -116,6 +116,9 @@ Without a connection string the line reads `Transcode session store: NullTransco
 | `Jellyfin:TranscodeStore:RedisConnectionString` | _(empty)_ | StackExchange.Redis connection string. Empty = single-instance mode. |
 | `Jellyfin:TranscodeStore:LeaseDurationSeconds` | `30` | How long a pod's transcode lease is valid before another pod may take over. |
 | `Jellyfin:TranscodeStore:SessionRetentionSeconds` | `300` | How long an unrenewed session record is kept so another pod can still take it over. |
+| `Jellyfin:SessionDirectory:EntryTtlSeconds` | `60` | How long a published session stays visible to the other pods without being refreshed. |
+| `Jellyfin:SessionDirectory:RefreshIntervalSeconds` | `20` | How often a pod republishes the sessions it holds. |
+| `Jellyfin:SessionDirectory:OperationTimeoutSeconds` | `5` | How long a single session directory read or write may take before it is abandoned. |
 
 ### Redis connection string examples
 

tests/Jellyfin.Server.Implementations.Tests/SessionManager/IdlePlaybackTests.cs

@@ -13,6 +13,7 @@ using MediaBrowser.Model.Dto;
 using MediaBrowser.Model.Session;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
 using Moq;
 using Xunit;
 
@@ -44,7 +45,10 @@ public class IdlePlaybackTests
             Mock.Of<IServerApplicationHost>(),
             Mock.Of<IDeviceManager>(),
             Mock.Of<IMediaSourceManager>(),
-            Mock.Of<IHostApplicationLifetime>());
+            Mock.Of<IHostApplicationLifetime>(),
+            NullSessionDirectory.Instance,
+            NullPodMessageBus.Instance,
+            Options.Create(new SessionDirectoryOptions()));
         var session = await sessionManager.LogSessionActivity(
             "Test Client",
             "1.0.0",

tests/Jellyfin.Server.Implementations.Tests/SessionManager/SessionManagerTests.cs

@@ -16,6 +16,7 @@ using MediaBrowser.Controller.Session;
 using MediaBrowser.Model.Session;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
 using Moq;
 using Xunit;
 
@@ -41,7 +42,10 @@ public class SessionManagerTests
             Mock.Of<IServerApplicationHost>(),
             Mock.Of<IDeviceManager>(),
             Mock.Of<IMediaSourceManager>(),
-            Mock.Of<IHostApplicationLifetime>());
+            Mock.Of<IHostApplicationLifetime>(),
+            NullSessionDirectory.Instance,
+            NullPodMessageBus.Instance,
+            Options.Create(new SessionDirectoryOptions()));
 
         await Assert.ThrowsAsync(exceptionType, () => sessionManager.GetAuthorizationToken(
             new User("test", "default", "default"),
@@ -68,7 +72,10 @@ public class SessionManagerTests
             Mock.Of<IServerApplicationHost>(),
             Mock.Of<IDeviceManager>(),
             Mock.Of<IMediaSourceManager>(),
-            Mock.Of<IHostApplicationLifetime>());
+            Mock.Of<IHostApplicationLifetime>(),
+            NullSessionDirectory.Instance,
+            NullPodMessageBus.Instance,
+            Options.Create(new SessionDirectoryOptions()));
 
         await Assert.ThrowsAsync(exceptionType, () => sessionManager.AuthenticateNewSessionInternal(authenticationRequest, false));
     }
@@ -173,7 +180,7 @@ public class SessionManagerTests
 
         var attackerSession = await LogSessionActivity(sessionManager, attacker);
 
-        Assert.Throws<SecurityException>(() => sessionManager.AddAdditionalUser(attackerSession.Id, attackerSession.Id, victim.Id));
+        await Assert.ThrowsAsync<SecurityException>(() => sessionManager.AddAdditionalUser(attackerSession.Id, attackerSession.Id, victim.Id));
     }
 
     [Fact]
@@ -186,7 +193,7 @@ public class SessionManagerTests
 
         var adminSession = await LogSessionActivity(sessionManager, admin);
 
-        sessionManager.AddAdditionalUser(adminSession.Id, adminSession.Id, guest.Id);
+        await sessionManager.AddAdditionalUser(adminSession.Id, adminSession.Id, guest.Id);
 
         Assert.Contains(adminSession.AdditionalUsers, i => i.UserId.Equals(guest.Id));
     }
@@ -201,7 +208,7 @@ public class SessionManagerTests
         var victimSession = await LogSessionActivity(sessionManager, victim);
         var attackerSession = await LogSessionActivity(sessionManager, attacker);
 
-        Assert.Throws<SecurityException>(() => sessionManager.RemoveAdditionalUser(attackerSession.Id, victimSession.Id, attacker.Id));
+        await Assert.ThrowsAsync<SecurityException>(() => sessionManager.RemoveAdditionalUser(attackerSession.Id, victimSession.Id, attacker.Id));
     }
 
     [Fact]
@@ -238,7 +245,10 @@ public class SessionManagerTests
             Mock.Of<IServerApplicationHost>(),
             Mock.Of<IDeviceManager>(),
             Mock.Of<IMediaSourceManager>(),
-            Mock.Of<IHostApplicationLifetime>());
+            Mock.Of<IHostApplicationLifetime>(),
+            NullSessionDirectory.Instance,
+            NullPodMessageBus.Instance,
+            Options.Create(new SessionDirectoryOptions()));
     }
 
     // All sessions are logged with the same client and device id on purpose, those values are taken

tests/Jellyfin.Server.Tests/HighAvailability/RedisTestServer.cs

@@ -0,0 +1,66 @@
+using System;
+using System.Threading.Tasks;
+using StackExchange.Redis;
+using Testcontainers.Redis;
+
+namespace Jellyfin.Server.Tests.HighAvailability;
+
+/// <summary>
+/// Hands out a valkey/Redis server for the tests that need one. A server named by
+/// <c>JELLYFIN_TEST_REDIS</c> is used as is, so CI can run one in the step instead of a docker daemon
+/// of its own; without it a container is started through testcontainers.
+/// </summary>
+public sealed class RedisTestServer : IAsyncDisposable
+{
+    /// <summary>
+    /// The connection string of an already running server.
+    /// </summary>
+    public const string ConnectionStringVariable = "JELLYFIN_TEST_REDIS";
+
+    private readonly RedisContainer? _container;
+
+    private RedisTestServer(RedisContainer? container, string connectionString)
+    {
+        _container = container;
+        ConnectionString = connectionString;
+    }
+
+    /// <summary>
+    /// Gets the connection string of the running server.
+    /// </summary>
+    public string ConnectionString { get; }
+
+    /// <summary>
+    /// Starts or attaches to a server and connects to it.
+    /// </summary>
+    /// <returns>The running server.</returns>
+    public static async Task<RedisTestServer> StartAsync()
+    {
+        var provided = Environment.GetEnvironmentVariable(ConnectionStringVariable);
+        if (!string.IsNullOrWhiteSpace(provided))
+        {
+            return new RedisTestServer(null, provided);
+        }
+
+        var container = new RedisBuilder("valkey/valkey:8-alpine").Build();
+        await container.StartAsync().ConfigureAwait(false);
+
+        return new RedisTestServer(container, container.GetConnectionString());
+    }
+
+    /// <summary>
+    /// Opens a connection to the server.
+    /// </summary>
+    /// <returns>The connection.</returns>
+    public async Task<IConnectionMultiplexer> ConnectAsync()
+        => await ConnectionMultiplexer.ConnectAsync(ConnectionString).ConfigureAwait(false);
+
+    /// <inheritdoc/>
+    public async ValueTask DisposeAsync()
+    {
+        if (_container is not null)
+        {
+            await _container.DisposeAsync().ConfigureAwait(false);
+        }
+    }
+}

tests/Jellyfin.Server.Tests/HighAvailability/SessionDirectoryReplicaTests.cs

@@ -0,0 +1,449 @@
+using System;
+using System.Linq;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Database.Implementations;
+using Jellyfin.Database.Implementations.DbConfiguration;
+using Jellyfin.Database.Implementations.Entities;
+using Jellyfin.Database.Implementations.Locking;
+using Jellyfin.Database.Providers.PostgreSQL;
+using Jellyfin.Server.Implementations.Devices;
+using Jellyfin.Server.Tests.Migrations;
+using MediaBrowser.Common.Extensions;
+using MediaBrowser.Controller;
+using MediaBrowser.Controller.Configuration;
+using MediaBrowser.Controller.Drawing;
+using MediaBrowser.Controller.Dto;
+using MediaBrowser.Controller.Events;
+using MediaBrowser.Controller.Library;
+using MediaBrowser.Controller.Session;
+using MediaBrowser.Model.Session;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+using Moq;
+using Npgsql;
+using StackExchange.Redis;
+using Xunit;
+using RedisPodMessageBus = Emby.Server.Implementations.Session.RedisPodMessageBus;
+using RedisSessionDirectory = Emby.Server.Implementations.Session.RedisSessionDirectory;
+using SessionManager = Emby.Server.Implementations.Session.SessionManager;
+
+namespace Jellyfin.Server.Tests.HighAvailability;
+
+/// <summary>
+/// Two independently constructed <see cref="SessionManager"/> instances over one PostgreSQL database and
+/// one valkey are the in-process stand-in for two replicas without sticky sessions: a session either of
+/// them holds has to be visible to, and controllable from, the other.
+/// </summary>
+[Trait("Category", "RequiresDocker")]
+public sealed class SessionDirectoryReplicaTests : IAsyncLifetime
+{
+    private const string AppName = "Jellyfin Web";
+    private const string AppVersion = "1.0.0";
+    private const string DeviceName = "Living Room TV";
+    private const string RemoteEndPoint = "127.0.0.1";
+
+    private PostgreSqlTestServer _postgres = null!;
+    private RedisTestServer _redis = null!;
+    private NpgsqlDataSource _dataSource = null!;
+    private IConnectionMultiplexer _connection = null!;
+    private ISessionDirectory _directory = null!;
+    private User _user = null!;
+    private User _guest = null!;
+
+    /// <inheritdoc/>
+    public async ValueTask InitializeAsync()
+    {
+        _postgres = await PostgreSqlTestServer.StartAsync();
+        _redis = await RedisTestServer.StartAsync();
+        _connection = await _redis.ConnectAsync();
+        _directory = new RedisSessionDirectory(
+            _connection,
+            Options.Create(new SessionDirectoryOptions()),
+            NullLogger<RedisSessionDirectory>.Instance);
+
+        var connectionString = await _postgres.CreateDatabaseAsync("session_directory", CancellationToken.None);
+        _dataSource = new NpgsqlDataSourceBuilder(connectionString).Build();
+
+        var context = CreateContext(_dataSource);
+        await using (context.ConfigureAwait(false))
+        {
+            await context.Database.EnsureCreatedAsync(CancellationToken.None);
+
+            _user = new User("replica-user", "provider", "provider");
+            _guest = new User("replica-guest", "provider", "provider");
+            context.Users.Add(_user);
+            context.Users.Add(_guest);
+            await context.SaveChangesAsync(CancellationToken.None);
+        }
+    }
+
+    /// <inheritdoc/>
+    public async ValueTask DisposeAsync()
+    {
+        await _connection.DisposeAsync();
+        await _dataSource.DisposeAsync();
+        await _redis.DisposeAsync();
+        await _postgres.DisposeAsync();
+    }
+
+    /// <summary>
+    /// Half the active playback is invisible when the session list only reports what the replica serving
+    /// the request happens to hold, so a session registered on one replica has to appear on the other.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    [Fact]
+    public async Task SessionRegisteredOnOneReplica_IsListedByAnother()
+    {
+        var cancellationToken = TestContext.Current.CancellationToken;
+        await using var replicaA = CreateReplica("pod-a");
+        await using var replicaB = CreateReplica("pod-b");
+
+        var session = await Request(replicaA, "device-listed");
+
+        var listedByB = await replicaB.GetSessions(_user.Id, null, null, null, false, cancellationToken);
+        var listedByA = await replicaA.GetSessions(_user.Id, null, null, null, false, cancellationToken);
+
+        Assert.Contains(listedByB, i => string.Equals(i.Id, session.Id, StringComparison.Ordinal));
+        Assert.Contains(listedByA, i => string.Equals(i.Id, session.Id, StringComparison.Ordinal));
+
+        // The session is reported once, not once per replica that can see it.
+        Assert.Single(listedByB, i => string.Equals(i.Id, session.Id, StringComparison.Ordinal));
+    }
+
+    /// <summary>
+    /// The deployment has no sticky sessions, so one device's requests land on either replica while its
+    /// websocket stays on one of them. Ownership has to follow the connection rather than the last
+    /// request served, or the directory names the wrong replica, the session list doubles up and remote
+    /// control is delivered to a replica with nothing to deliver it to.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    [Fact]
+    public async Task RequestsAlternatingBetweenReplicas_KeepOwnershipWithTheConnection()
+    {
+        var cancellationToken = TestContext.Current.CancellationToken;
+        var options = new SessionDirectoryOptions { EntryTtlSeconds = 60, RefreshIntervalSeconds = 2 };
+        await using var replicaA = CreateReplica("pod-a", options);
+        await using var replicaB = CreateReplica("pod-b", options);
+
+        // The device is first seen by the replica that will not hold its websocket.
+        await Request(replicaB, "device-roaming");
+
+        var session = await Request(replicaA, "device-roaming");
+        var controller = new RecordingSessionController();
+        session.AddController(controller);
+        await replicaA.OnSessionControllerConnected(session);
+
+        // The load balancer keeps handing the device's requests to whichever replica it likes, and the
+        // replica without the websocket must never take the session from the one that has it.
+        for (var i = 0; i < 8; i++)
+        {
+            await Request(replicaB, "device-roaming");
+            await Task.Delay(250, cancellationToken);
+
+            var entry = await _directory.GetAsync(session.Id, cancellationToken);
+            Assert.NotNull(entry);
+            Assert.Equal("pod-a", entry.OwnerPod);
+            Assert.True(entry.HoldsConnection);
+
+            await Request(replicaA, "device-roaming");
+            await Task.Delay(50, cancellationToken);
+        }
+
+        var listedByA = await replicaA.GetSessions(_user.Id, null, null, null, false, cancellationToken);
+        var listedByB = await replicaB.GetSessions(_user.Id, null, null, null, false, cancellationToken);
+
+        Assert.Single(listedByA, i => string.Equals(i.Id, session.Id, StringComparison.Ordinal));
+        Assert.Single(listedByB, i => string.Equals(i.Id, session.Id, StringComparison.Ordinal));
+
+        await replicaB.SendMessageCommand(
+            string.Empty,
+            session.Id,
+            new MessageCommand { Header = "Header", Text = "Dinner is ready" },
+            cancellationToken);
+
+        var (messageType, data) = await controller.WaitForMessageAsync(cancellationToken);
+        Assert.Equal(SessionMessageType.GeneralCommand, messageType);
+        Assert.Contains("Dinner is ready", data, StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    /// Remote control and "send message to session" used to succeed and do nothing when the device is
+    /// connected to another replica; the message has to reach the connection wherever it is held.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    [Fact]
+    public async Task MessageSentOnOneReplica_ReachesTheConnectionHeldByAnother()
+    {
+        var cancellationToken = TestContext.Current.CancellationToken;
+        await using var replicaA = CreateReplica("pod-a");
+        await using var replicaB = CreateReplica("pod-b");
+
+        var session = await Request(replicaA, "device-controlled");
+        var controller = new RecordingSessionController();
+        session.AddController(controller);
+        await replicaA.OnSessionControllerConnected(session);
+
+        await replicaB.SendMessageCommand(
+            string.Empty,
+            session.Id,
+            new MessageCommand { Header = "Header", Text = "Dinner is ready" },
+            cancellationToken);
+
+        var (messageType, data) = await controller.WaitForMessageAsync(cancellationToken);
+        Assert.Equal(SessionMessageType.GeneralCommand, messageType);
+        Assert.Contains("Dinner is ready", data, StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    /// An entry outlives the replica that wrote it by up to its expiry, and a command routed into that
+    /// gap reaches nobody. Reporting it as delivered is the failure this directory exists to remove.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    [Fact]
+    public async Task MessageRoutedToADeadOwner_IsReportedAsUndelivered()
+    {
+        var cancellationToken = TestContext.Current.CancellationToken;
+        await using var replicaA = CreateReplica("pod-a");
+        await using var replicaB = CreateReplica("pod-b");
+
+        var session = await Request(replicaA, "device-dead-owner");
+        session.AddController(new RecordingSessionController());
+        await replicaA.OnSessionControllerConnected(session);
+
+        var entry = await _directory.GetAsync(session.Id, cancellationToken);
+        Assert.NotNull(entry);
+
+        // A replica that is no longer listening, holding the entry until it expires.
+        entry.OwnerPod = "pod-gone";
+        Assert.True(await _directory.PublishAsync(entry, DateTime.UtcNow.Ticks, cancellationToken));
+
+        await Assert.ThrowsAsync<ResourceNotFoundException>(
+            () => replicaB.SendMessageCommand(
+                string.Empty,
+                session.Id,
+                new MessageCommand { Header = "Header", Text = "Dinner is ready" },
+                cancellationToken));
+    }
+
+    /// <summary>
+    /// Both replicas keep a copy of a session whose requests they have served, so the replica ending its
+    /// own copy must not erase the entry of the one still holding the connection.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    [Fact]
+    public async Task ReplicaEndingItsOwnCopy_LeavesTheOwnersEntryAlone()
+    {
+        var cancellationToken = TestContext.Current.CancellationToken;
+        await using var replicaA = CreateReplica("pod-a");
+        await using var replicaB = CreateReplica("pod-b");
+
+        var session = await Request(replicaA, "device-shared-end");
+        session.AddController(new RecordingSessionController());
+        await replicaA.OnSessionControllerConnected(session);
+
+        await Request(replicaB, "device-shared-end");
+        await replicaB.ReportSessionEnded(session.Id);
+
+        var entry = await _directory.GetAsync(session.Id, cancellationToken);
+        Assert.NotNull(entry);
+        Assert.Equal("pod-a", entry.OwnerPod);
+
+        await replicaA.ReportSessionEnded(session.Id);
+
+        Assert.Null(await _directory.GetAsync(session.Id, cancellationToken));
+    }
+
+    /// <summary>
+    /// The session list now shows sessions from every replica, so an action offered against one of them
+    /// has to reach it rather than fail as missing on the replica serving the request.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    [Fact]
+    public async Task AdditionalUserAddedOnOneReplica_ReachesTheOwner()
+    {
+        var cancellationToken = TestContext.Current.CancellationToken;
+        await using var replicaA = CreateReplica("pod-a");
+        await using var replicaB = CreateReplica("pod-b");
+
+        var session = await Request(replicaA, "device-additional-user");
+        session.AddController(new RecordingSessionController());
+        await replicaA.OnSessionControllerConnected(session);
+
+        await replicaB.AddAdditionalUser(string.Empty, session.Id, _guest.Id);
+
+        await WaitUntil(() => session.AdditionalUsers.Any(i => i.UserId.Equals(_guest.Id)), cancellationToken);
+
+        await replicaB.RemoveAdditionalUser(string.Empty, session.Id, _guest.Id);
+
+        await WaitUntil(() => !session.AdditionalUsers.Any(i => i.UserId.Equals(_guest.Id)), cancellationToken);
+    }
+
+    /// <summary>
+    /// A replica that dies stops refreshing its entries, and the sessions it held have to leave the
+    /// directory rather than linger in every other replica's session list forever.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    [Fact]
+    public async Task SessionsOfAReplicaThatStopsRefreshing_LeaveTheDirectory()
+    {
+        var cancellationToken = TestContext.Current.CancellationToken;
+
+        // A never refreshes within the test, so it stands in for a replica that crashed.
+        await using var replicaA = CreateReplica("pod-a", new SessionDirectoryOptions { EntryTtlSeconds = 1, RefreshIntervalSeconds = 3600 });
+        await using var replicaB = CreateReplica("pod-b");
+
+        var session = await Request(replicaA, "device-expiring");
+
+        var listedWhileAlive = await replicaB.GetSessions(_user.Id, null, null, null, false, cancellationToken);
+        Assert.Contains(listedWhileAlive, i => string.Equals(i.Id, session.Id, StringComparison.Ordinal));
+
+        await Task.Delay(TimeSpan.FromSeconds(2), cancellationToken);
+
+        var listedAfterExpiry = await replicaB.GetSessions(_user.Id, null, null, null, false, cancellationToken);
+        Assert.DoesNotContain(listedAfterExpiry, i => string.Equals(i.Id, session.Id, StringComparison.Ordinal));
+    }
+
+    /// <summary>
+    /// A deployment without a shared store keeps the single-instance behaviour: nothing is published and
+    /// the other instance sees nothing.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> representing the asynchronous operation.</returns>
+    [Fact]
+    public async Task WithoutADirectory_ReplicasOnlyReportTheirOwnSessions()
+    {
+        var cancellationToken = TestContext.Current.CancellationToken;
+        await using var replicaA = CreateReplica("pod-a", directory: NullSessionDirectory.Instance, bus: NullPodMessageBus.Instance);
+        await using var replicaB = CreateReplica("pod-b", directory: NullSessionDirectory.Instance, bus: NullPodMessageBus.Instance);
+
+        var session = await Request(replicaA, "device-local");
+
+        var listedByB = await replicaB.GetSessions(_user.Id, null, null, null, false, cancellationToken);
+        Assert.DoesNotContain(listedByB, i => string.Equals(i.Id, session.Id, StringComparison.Ordinal));
+    }
+
+    private static async Task WaitUntil(Func<bool> condition, CancellationToken cancellationToken)
+    {
+        var deadline = DateTime.UtcNow.AddSeconds(10);
+        while (!condition())
+        {
+            Assert.True(DateTime.UtcNow < deadline, "The expected change never arrived.");
+            await Task.Delay(50, cancellationToken);
+        }
+    }
+
+    private static JellyfinDbContext CreateContext(NpgsqlDataSource dataSource)
+    {
+        var optionsBuilder = new DbContextOptionsBuilder<JellyfinDbContext>();
+        var provider = new PostgreSqlDatabaseProvider(dataSource);
+        provider.Initialise(optionsBuilder, new DatabaseConfigurationOptions { DatabaseType = "PostgreSQL" });
+        return new JellyfinDbContext(
+            optionsBuilder.Options,
+            NullLogger<JellyfinDbContext>.Instance,
+            provider,
+            new NoLockBehavior(NullLogger<NoLockBehavior>.Instance));
+    }
+
+    private Task<SessionInfo> Request(SessionManager replica, string deviceId)
+        => replica.LogSessionActivity(AppName, AppVersion, deviceId, DeviceName, RemoteEndPoint, _user);
+
+    private SessionManager CreateReplica(string podId, SessionDirectoryOptions? options = null)
+    {
+        options ??= new SessionDirectoryOptions { EntryTtlSeconds = 60, RefreshIntervalSeconds = 3600 };
+
+        var directory = new RedisSessionDirectory(
+            _connection,
+            Options.Create(options),
+            NullLogger<RedisSessionDirectory>.Instance);
+
+        return CreateReplica(podId, options, directory, CreateBus(podId));
+    }
+
+    private SessionManager CreateReplica(string podId, ISessionDirectory directory, IPodMessageBus bus)
+        => CreateReplica(podId, new SessionDirectoryOptions(), directory, bus);
+
+    private SessionManager CreateReplica(string podId, SessionDirectoryOptions options, ISessionDirectory directory, IPodMessageBus bus)
+    {
+        var userManager = new Mock<IUserManager>();
+        userManager.Setup(i => i.GetUserById(_user.Id)).Returns(_user);
+        userManager.Setup(i => i.GetUserById(_guest.Id)).Returns(_guest);
+
+        var appHost = new Mock<IServerApplicationHost>();
+        appHost.SetupGet(i => i.SystemId).Returns("server-" + podId);
+
+        return new SessionManager(
+            NullLogger<SessionManager>.Instance,
+            Mock.Of<IEventManager>(),
+            Mock.Of<IUserDataManager>(),
+            Mock.Of<IServerConfigurationManager>(),
+            Mock.Of<ILibraryManager>(),
+            userManager.Object,
+            Mock.Of<IMusicManager>(),
+            Mock.Of<IDtoService>(),
+            Mock.Of<IImageProcessor>(),
+            appHost.Object,
+            new DeviceManager(new DataSourceContextFactory(_dataSource), userManager.Object),
+            Mock.Of<IMediaSourceManager>(),
+            Mock.Of<IHostApplicationLifetime>(),
+            directory,
+            bus,
+            Options.Create(options));
+    }
+
+    // The bus reads the instance identity from the environment, so the two replicas are built one at a time.
+    private IPodMessageBus CreateBus(string podId)
+    {
+        var previous = Environment.GetEnvironmentVariable("JELLYFIN_INSTANCE_ID");
+        Environment.SetEnvironmentVariable("JELLYFIN_INSTANCE_ID", podId);
+        try
+        {
+            return new RedisPodMessageBus(
+                _connection,
+                NullLogger<RedisPodMessageBus>.Instance);
+        }
+        finally
+        {
+            Environment.SetEnvironmentVariable("JELLYFIN_INSTANCE_ID", previous);
+        }
+    }
+
+    /// <summary>
+    /// Hands every replica its own context over the one shared database, the way the pooled factory does
+    /// in the server.
+    /// </summary>
+    private sealed class DataSourceContextFactory : IDbContextFactory<JellyfinDbContext>
+    {
+        private readonly NpgsqlDataSource _dataSource;
+
+        public DataSourceContextFactory(NpgsqlDataSource dataSource)
+        {
+            _dataSource = dataSource;
+        }
+
+        public JellyfinDbContext CreateDbContext() => CreateContext(_dataSource);
+    }
+
+    /// <summary>
+    /// Stands in for the websocket the owning replica holds.
+    /// </summary>
+    private sealed class RecordingSessionController : ISessionController
+    {
+        private readonly TaskCompletionSource<(SessionMessageType MessageType, string Data)> _received = new();
+
+        public bool IsSessionActive => true;
+
+        public bool SupportsMediaControl => true;
+
+        public Task SendMessage<T>(SessionMessageType name, Guid messageId, T data, CancellationToken cancellationToken)
+        {
+            _received.TrySetResult((name, JsonSerializer.Serialize(data)));
+            return Task.CompletedTask;
+        }
+
+        public Task<(SessionMessageType MessageType, string Data)> WaitForMessageAsync(CancellationToken cancellationToken)
+            => _received.Task.WaitAsync(TimeSpan.FromSeconds(10), cancellationToken);
+    }
+}

tests/Jellyfin.Server.Tests/Jellyfin.Server.Tests.csproj

@@ -11,7 +11,9 @@
     <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" />
     <PackageReference Include="Npgsql" />
+    <PackageReference Include="StackExchange.Redis" />
     <PackageReference Include="Testcontainers.PostgreSql" />
+    <PackageReference Include="Testcontainers.Redis" />
     <PackageReference Include="xunit.v3" />
     <PackageReference Include="xunit.runner.visualstudio">
       <PrivateAssets>all</PrivateAssets>