Merge branch 'main' into the desktop updater, and give way on two numbers

Main landed a realtime push feature while this branch was building the updater,
and the two collided in three places. Every one of them resolves the same way:
main got there first, so this branch moves.

**Two ADRs were both numbered 0012.** Main's is realtime push; this one is now
[ADR 0013](docs/adr/0013-desktop-distribution-and-updates.md). Git did not call
this a conflict — the filenames differ — so it would have merged quietly and left
the directory with two 0012s and every cross-reference ambiguous. Renumbered here
along with the nine places that point at it.

**Two manual-check phases were both numbered 15**, and that one git did catch.
Main's "Changes that arrive without a timer" keeps 15; installing and updating
the desktop client becomes Phase 16, with its checks and every reference to them
renumbered. The file's own rule is that a number is for life, which is exactly
why the one that had not been pushed is the one that gives way.

**The merge rewrote several files with CRLF**, and `.editorconfig` asks for LF on
everything except `*.ps1`. That is not cosmetic here: IDE0055 is an error and
`EnforceCodeStyleInBuild` is on, so it failed the build on three lines of
App.axaml.cs whose only change in this branch was an ADR number in a comment.
Forty-six files normalised back to LF; the release script keeps CRLF, which is
what `.gitattributes` and `.editorconfig` both already say for a PowerShell file.

Nothing else conflicted. The updater does not touch the sync loop or the event
stream, and the one file both sides edited heavily — MainWindowViewModel — merged
without a hunk in common.

Verified after merging: the solution restores locked and builds clean, and 304
shell, 100 layout, 54 session, 28 client-api and 25 contracts tests pass. The
first two counts are higher than before the merge because main's own tests came
with it and pass alongside these.

src/DodoSSH.Api/Features/Events/EventsEndpoint.cs

@@ -0,0 +1,533 @@
+using System.Collections.Frozen;
+using System.Globalization;
+using System.Net.WebSockets;
+using System.Security.Claims;
+using System.Text.Json;
+using DodoSSH.Api.Authorization;
+using DodoSSH.Api.Setup;
+using DodoSSH.Contracts;
+using DodoSSH.Domain.Authorization;
+using FastEndpoints;
+using Microsoft.Extensions.Options;
+
+namespace DodoSSH.Api.Features.Events;
+
+/// <summary>
+/// The socket that says "pull now" so a client does not have to wait for its timer.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Everything this endpoint sends is a <em>notice</em>. It never carries an item, a payload or a
+/// cursor: the client's answer to a notice is the delta pull it would have run on its own anyway, so
+/// there is exactly one code path that applies a change and this is not it. See ADR 0012 for why
+/// pushing the items themselves is refused.
+/// </para>
+/// <para>
+/// The bearer token authorises the upgrade, unlike the relay's ticket in ADR 0004. The relay's socket
+/// is a byte pipe whose whole authorization decision is made before it opens; this one is a view of
+/// the caller's own vault list and has to keep answering "what may this account read" for as long as
+/// it is held. Its two bounds on that — the token's own expiry, and a periodic re-resolve — are in
+/// <see cref="MindAsync"/>.
+/// </para>
+/// </remarks>
+internal sealed class VaultEventsEndpoint(
+    IServiceScopeFactory scopes,
+    VaultEventHub hub,
+    IOptions<EventsOptions> options,
+    TimeProvider clock,
+    IHostApplicationLifetime lifetime,
+    ILogger<VaultEventsEndpoint> logger)
+    : EndpointWithoutRequest
+{
+    /// <summary>
+    /// The largest message this endpoint will read from a client.
+    /// </summary>
+    /// <remarks>
+    /// A client sends nothing but <c>ping</c>, so the cap is three orders of magnitude of headroom and
+    /// still small enough that a hostile client cannot make the server buffer anything worth having.
+    /// </remarks>
+    private const int MaxInboundFrameBytes = 4 * 1024;
+
+    /// <summary>How long to wait for the close handshake before dropping the socket.</summary>
+    private static readonly TimeSpan CloseTimeout = TimeSpan.FromSeconds(5);
+
+    /// <inheritdoc />
+    public override void Configure()
+    {
+        Get(VaultEvents.Path);
+
+        // Enrolled, matching sync. A caller with no identity key holds no vault key either, so every
+        // notice this socket could send is about ciphertext they cannot read.
+        Policies(Auth.EnrolledPolicy);
+
+        Description(b => b
+            .WithName("VaultEvents")
+            .WithSummary("Pushes a notice when a vault the caller can read has changed.")
+            .WithTags("Events"));
+    }
+
+    /// <inheritdoc />
+    public override async Task HandleAsync(CancellationToken ct)
+    {
+        if (await RefusedAsync().ConfigureAwait(false))
+        {
+            return;
+        }
+
+        var (userId, vaults) = await ResolveAccessAsync(ct).ConfigureAwait(false);
+
+        // Admitted before the upgrade so a refusal costs nothing, but answered *through* the socket
+        // rather than as an HTTP status: a constrained WebSocket client cannot read the status of a
+        // failed upgrade, and "you have too many open" is precisely the case where the client needs
+        // to know to back off rather than retry. Same reasoning as ADR 0004 on request headers.
+        var connection = hub.TryAdmit(userId, vaults);
+
+        try
+        {
+            using var socket = await HttpContext.WebSockets
+                .AcceptWebSocketAsync(new WebSocketAcceptContext { SubProtocol = VaultEvents.SubProtocol })
+                .ConfigureAwait(false);
+
+            if (connection is null)
+            {
+                await CloseAsync(
+                        socket,
+                        new Closure(
+                            VaultEvents.TooManyConnectionsCloseCode, "Too many open event sockets."))
+                    .ConfigureAwait(false);
+
+                return;
+            }
+
+            await PumpAsync(socket, connection, ct).ConfigureAwait(false);
+        }
+        finally
+        {
+            // Inside a try that starts *before* the upgrade, because an accept that throws — a client
+            // that abandoned the handshake — would otherwise leave an admitted connection in the hub
+            // for the life of the process, counting against this account's cap and taking a slot from
+            // the sockets that did open.
+            if (connection is not null)
+            {
+                hub.Remove(connection);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Answers the requests that are not an event socket at all, as ordinary HTTP.
+    /// </summary>
+    /// <returns>Whether a response was sent and the handler should stop.</returns>
+    /// <remarks>
+    /// All three answers are problem documents rather than bare statuses, because each one has a
+    /// different remedy and a client that cannot tell them apart would retry the two that will never
+    /// succeed. Answered before the upgrade, so a caller that got the handshake wrong reads why in a
+    /// body rather than inferring it from a socket that closed.
+    /// </remarks>
+    private async Task<bool> RefusedAsync()
+    {
+        if (!options.Value.Enabled)
+        {
+            // 404 rather than 501: the feature is absent from this deployment, and /api/v1/meta does
+            // not advertise it. A client that dialled anyway keeps polling, which is correct.
+            await Send.ResultAsync(Problems.Coded(
+                    StatusCodes.Status404NotFound,
+                    ProblemCodes.EventsUnavailable,
+                    "This server does not push vault changes. Synchronise on a timer instead; "
+                    + "GET /api/v1/meta lists the features it does offer."))
+                .ConfigureAwait(false);
+
+            return true;
+        }
+
+        if (!HttpContext.WebSockets.IsWebSocketRequest)
+        {
+            await Send.ResultAsync(Problems.Coded(
+                    StatusCodes.Status400BadRequest,
+                    ProblemCodes.MalformedRequest,
+                    "This endpoint is a WebSocket. Send an upgrade request offering the "
+                    + $"'{VaultEvents.SubProtocol}' subprotocol."))
+                .ConfigureAwait(false);
+
+            return true;
+        }
+
+        // The subprotocol is this API's version negotiation for the socket, so an upgrade that does
+        // not offer it is refused rather than accepted and answered in a dialect the caller may not
+        // read. See VaultEvents.SubProtocol.
+        if (!HttpContext.WebSockets.WebSocketRequestedProtocols
+                .Contains(VaultEvents.SubProtocol, StringComparer.Ordinal))
+        {
+            await Send.ResultAsync(Problems.Coded(
+                    StatusCodes.Status400BadRequest,
+                    ProblemCodes.MalformedRequest,
+                    $"This server speaks '{VaultEvents.SubProtocol}', which the upgrade request did "
+                    + "not offer."))
+                .ConfigureAwait(false);
+
+            return true;
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// Reads who the caller is and which vaults they may follow, in a scope of its own.
+    /// </summary>
+    /// <remarks>
+    /// A fresh scope, disposed at once, rather than services injected into this endpoint — which is
+    /// the lesson ADR 0004 records paying for on the relay. This handler runs for as long as the
+    /// socket is open, so anything scoped it held would be a <c>DbContext</c> alive for hours, and a
+    /// few hundred of those exhaust the connection pool. The database is touched here and in
+    /// <see cref="RefreshAsync"/>, briefly, and nowhere else.
+    /// </remarks>
+    private async Task<(Guid UserId, FrozenSet<Guid> Vaults)> ResolveAccessAsync(
+        CancellationToken cancellationToken)
+    {
+        var scope = scopes.CreateAsyncScope();
+        await using var _ = scope.ConfigureAwait(false);
+
+        var currentUser = scope.ServiceProvider.GetRequiredService<ICurrentUserContext>();
+        var vaultAccess = scope.ServiceProvider.GetRequiredService<IVaultAccessService>();
+
+        var user = await currentUser.GetOrProvisionAsync(cancellationToken).ConfigureAwait(false);
+
+        return (user.Id, await ReachableAsync(vaultAccess, user.Id, cancellationToken).ConfigureAwait(false));
+    }
+
+    private static async Task<FrozenSet<Guid>> ReachableAsync(
+        IVaultAccessService vaultAccess,
+        Guid userId,
+        CancellationToken cancellationToken)
+    {
+        var accessible = await vaultAccess.ListAsync(userId, cancellationToken).ConfigureAwait(false);
+
+        return accessible
+            .Where(access => access.Vault is not null
+                && access.Permissions.HasFlag(PermissionFlags.Read))
+            .Select(access => access.Vault!.Id)
+            .ToFrozenSet();
+    }
+
+    /// <summary>Runs the socket until something ends it, then closes it politely.</summary>
+    /// <remarks>
+    /// Three loops rather than one: reading a socket and writing to it are independent waits, and the
+    /// clock is a third. They are joined by <see cref="Task.WhenAny(Task[])"/> and then <em>all</em>
+    /// awaited before the close is written, because a close frame racing a notice frame is a protocol
+    /// violation that presents as a client dropping its connection for no visible reason.
+    /// </remarks>
+    private async Task PumpAsync(
+        WebSocket socket,
+        VaultEventConnection connection,
+        CancellationToken requestAborted)
+    {
+        var settings = options.Value;
+
+        using var pump = CancellationTokenSource.CreateLinkedTokenSource(
+            requestAborted, lifetime.ApplicationStopping);
+
+        var closure = new Closure(
+            (int)WebSocketCloseStatus.NormalClosure, string.Empty);
+
+        connection.TryEnqueue(new VaultEvent(
+            VaultEventKinds.Hello,
+            ServerTime: clock.GetUtcNow(),
+            HeartbeatSeconds: (int)settings.HeartbeatInterval.TotalSeconds,
+            VaultCount: connection.VaultCount));
+
+        var sending = SendAsync(socket, connection, pump.Token);
+        var receiving = ReceiveAsync(socket, connection, pump.Token);
+        var minding = MindAsync(connection, closure, pump.Token);
+
+        await Task.WhenAny(sending, receiving, minding).ConfigureAwait(false);
+
+        await pump.CancelAsync().ConfigureAwait(false);
+
+        // Nothing may still be mid-send when the close frame goes out.
+        await Task.WhenAll(Settled(sending), Settled(receiving), Settled(minding)).ConfigureAwait(false);
+
+        if (lifetime.ApplicationStopping.IsCancellationRequested)
+        {
+            // 1001 "going away", so a client knows to reconnect immediately rather than treating a
+            // rolling deployment as a server that has broken.
+            closure.Set((int)WebSocketCloseStatus.EndpointUnavailable, "The server is shutting down.");
+        }
+
+        EventsLog.ClosingConnection(logger, connection.UserId, closure.Reason);
+
+        await CloseAsync(socket, closure).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Writes queued frames to the socket, one at a time.
+    /// </summary>
+    /// <remarks>
+    /// The <em>only</em> writer, which is what makes concurrent sends impossible without a lock: the
+    /// heartbeat and the pong both go into the same queue rather than to the socket. A WebSocket
+    /// permits one send at a time and faults permanently on a second, so this is not a tidiness
+    /// preference.
+    /// </remarks>
+    private async Task SendAsync(
+        WebSocket socket,
+        VaultEventConnection connection,
+        CancellationToken cancellationToken)
+    {
+        await foreach (var frame in connection.Outbound
+            .ReadAllAsync(cancellationToken)
+            .ConfigureAwait(false))
+        {
+            // Re-resolved before the notice is forwarded, not after: the client's answer to this frame
+            // is to re-read its vault list, and the point of a newly shared vault is that the *next*
+            // change to it produces a notice too. A socket that forwarded first would not follow the
+            // new vault until its next periodic refresh.
+            if (string.Equals(frame.Kind, VaultEventKinds.VaultsChanged, StringComparison.Ordinal))
+            {
+                await RefreshAsync(connection, cancellationToken).ConfigureAwait(false);
+            }
+
+            var bytes = JsonSerializer.SerializeToUtf8Bytes(frame, DodoSshJsonContext.Default.VaultEvent);
+
+            await socket
+                .SendAsync(bytes, WebSocketMessageType.Text, endOfMessage: true, cancellationToken)
+                .ConfigureAwait(false);
+        }
+    }
+
+    /// <summary>
+    /// Reads what the client sends, which in this version is heartbeats and a close.
+    /// </summary>
+    /// <remarks>
+    /// A client cannot ask to follow a vault, and that is deliberate rather than unfinished: a
+    /// <c>subscribe(vaultId)</c> frame is an existence oracle for vault ids, which is the disclosure
+    /// <c>SyncPullEndpoint</c> answers 404 rather than 403 to avoid. Subscription is decided from the
+    /// caller's access and nothing else.
+    /// </remarks>
+    private static async Task ReceiveAsync(
+        WebSocket socket,
+        VaultEventConnection connection,
+        CancellationToken cancellationToken)
+    {
+        var buffer = new byte[MaxInboundFrameBytes];
+
+        while (!cancellationToken.IsCancellationRequested)
+        {
+            var received = await socket.ReceiveAsync(buffer, cancellationToken).ConfigureAwait(false);
+
+            if (received.MessageType == WebSocketMessageType.Close)
+            {
+                return;
+            }
+
+            // Oversized, or split across frames. Nothing this protocol sends is either, so the client
+            // is broken or probing; ending the socket is cheaper than reassembling for it.
+            if (!received.EndOfMessage)
+            {
+                return;
+            }
+
+            // Binary is unused in v1 and skipped rather than refused, because ADR 0012 reserves it for
+            // shared-session data — an older server meeting a newer client must ignore those, not
+            // close on them.
+            if (received.MessageType != WebSocketMessageType.Text)
+            {
+                continue;
+            }
+
+            if (Kind(buffer.AsSpan(0, received.Count)) is VaultEventKinds.Ping)
+            {
+                connection.TryEnqueue(new VaultEvent(VaultEventKinds.Pong));
+            }
+        }
+    }
+
+    /// <summary>
+    /// Reads a frame's kind, or null if it is not one this server understands.
+    /// </summary>
+    /// <remarks>
+    /// A frame that will not parse is skipped rather than closing the socket. This is a control
+    /// channel whose failure mode is "the client polls instead", so tolerating a frame from a newer
+    /// client costs nothing and refusing one costs that client its push for the whole session.
+    /// </remarks>
+    private static string? Kind(ReadOnlySpan<byte> utf8)
+    {
+        try
+        {
+            return JsonSerializer.Deserialize(utf8, DodoSshJsonContext.Default.VaultEvent)?.Kind;
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+
+    /// <summary>
+    /// Keeps the heartbeat going, the vault set current, and the socket inside its token's lifetime.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The deadline is the earlier of the access token's <c>exp</c> and a hard cap on how long any one
+    /// socket may live. Closing on expiry is what keeps a long-lived connection from outliving the
+    /// short-lived credential that authorised it; the client answers by reconnecting with a fresh
+    /// token, which is a sub-second gap in a channel that degrades to polling anyway.
+    /// </para>
+    /// <para>
+    /// The wait is the shorter of the heartbeat and the time left, so the deadline is met to within a
+    /// tick rather than to within a heartbeat.
+    /// </para>
+    /// </remarks>
+    private async Task MindAsync(
+        VaultEventConnection connection,
+        Closure closure,
+        CancellationToken cancellationToken)
+    {
+        var settings = options.Value;
+        var started = clock.GetUtcNow();
+
+        var deadline = TokenExpiry() is { } expiry && expiry < started + settings.MaxConnectionDuration
+            ? (Expiry: expiry, ForToken: true)
+            : (Expiry: started + settings.MaxConnectionDuration, ForToken: false);
+
+        var refreshed = started;
+
+        while (!cancellationToken.IsCancellationRequested)
+        {
+            var now = clock.GetUtcNow();
+            var remaining = deadline.Expiry - now;
+
+            if (remaining <= TimeSpan.Zero)
+            {
+                closure.Set(
+                    deadline.ForToken
+                        ? VaultEvents.TokenExpiredCloseCode
+                        : (int)WebSocketCloseStatus.NormalClosure,
+                    deadline.ForToken
+                        ? "The access token has expired. Reconnect with a fresh one."
+                        : "This connection reached its maximum lifetime.");
+
+                return;
+            }
+
+            var wait = settings.HeartbeatInterval < remaining ? settings.HeartbeatInterval : remaining;
+
+            await Task.Delay(wait, clock, cancellationToken).ConfigureAwait(false);
+
+            now = clock.GetUtcNow();
+
+            if (now - refreshed >= settings.AccessRefreshInterval)
+            {
+                // The backstop for a grant withdrawn while this socket was open. What it bounds is
+                // metadata — that a vault changed — because that is all a notice carries and reading
+                // the vault still needs a key this server has never held. See ADR 0012.
+                await RefreshAsync(connection, cancellationToken).ConfigureAwait(false);
+                refreshed = now;
+            }
+
+            connection.TryEnqueue(new VaultEvent(VaultEventKinds.Ping, ServerTime: now));
+        }
+    }
+
+    /// <summary>Re-reads which vaults this socket may follow.</summary>
+    /// <remarks>
+    /// A failure is logged and swallowed. The alternative is dropping a working socket because one
+    /// database call timed out, which would trade an occasionally stale vault set for an outage.
+    /// </remarks>
+    private async Task RefreshAsync(VaultEventConnection connection, CancellationToken cancellationToken)
+    {
+        try
+        {
+            var scope = scopes.CreateAsyncScope();
+            await using var _ = scope.ConfigureAwait(false);
+
+            var vaultAccess = scope.ServiceProvider.GetRequiredService<IVaultAccessService>();
+
+            connection.Resubscribe(
+                await ReachableAsync(vaultAccess, connection.UserId, cancellationToken)
+                    .ConfigureAwait(false));
+        }
+        catch (OperationCanceledException)
+        {
+            // The socket is closing.
+        }
+        catch (Exception exception) when (exception is not OutOfMemoryException)
+        {
+            EventsLog.AccessRefreshFailed(logger, connection.UserId, exception);
+        }
+    }
+
+    /// <remarks>
+    /// <c>MapInboundClaims</c> is off — see <see cref="Auth"/> — so the claim is spelled as the
+    /// provider issued it rather than as a WS-Federation URI. Null is treated as "no bound from the
+    /// token", which the bearer handler's <c>RequireExpirationTime</c> should make unreachable; the
+    /// lifetime cap covers it either way.
+    /// </remarks>
+    private DateTimeOffset? TokenExpiry() =>
+        long.TryParse(
+            HttpContext.User.FindFirstValue("exp"),
+            NumberStyles.Integer,
+            CultureInfo.InvariantCulture,
+            out var seconds)
+            ? DateTimeOffset.FromUnixTimeSeconds(seconds)
+            : null;
+
+    private static async Task CloseAsync(WebSocket socket, Closure closure)
+    {
+        if (socket.State is not (WebSocketState.Open or WebSocketState.CloseReceived))
+        {
+            return;
+        }
+
+        using var timeout = new CancellationTokenSource(CloseTimeout);
+
+        try
+        {
+            await socket
+                .CloseOutputAsync((WebSocketCloseStatus)closure.Code, closure.Reason, timeout.Token)
+                .ConfigureAwait(false);
+        }
+        catch (Exception exception)
+            when (exception is OperationCanceledException or WebSocketException or ObjectDisposedException)
+        {
+            // The peer is already gone. There is nothing to tell it and nothing to recover.
+        }
+    }
+
+    /// <summary>
+    /// Awaits a pump loop, treating its cancellation and its socket faults as the ordinary end.
+    /// </summary>
+    /// <remarks>
+    /// Every one of these loops ends by being cancelled or by the socket going away, so an exception
+    /// here is the expected shape of "this connection is over" rather than a fault to propagate — and
+    /// propagating it would skip the close frame the other side is waiting for.
+    /// </remarks>
+    private static async Task Settled(Task loop)
+    {
+        try
+        {
+            await loop.ConfigureAwait(false);
+        }
+        catch (Exception exception)
+            when (exception is OperationCanceledException or WebSocketException or ObjectDisposedException)
+        {
+            // Expected.
+        }
+    }
+
+    /// <summary>Why the socket is being closed, decided by whichever loop ended first.</summary>
+    /// <remarks>
+    /// Mutable and shared, and safe without a lock for one specific reason: it is written by the pump
+    /// loops and read only after <see cref="Task.WhenAll(Task[])"/> over all of them, which is a
+    /// memory barrier. Writes race only with each other, and any of them is a true answer.
+    /// </remarks>
+    private sealed class Closure(int code, string reason)
+    {
+        internal int Code { get; private set; } = code;
+
+        internal string Reason { get; private set; } = reason;
+
+        internal void Set(int code, string reason)
+        {
+            Code = code;
+            Reason = reason;
+        }
+    }
+}

src/DodoSSH.Api/Features/Events/EventsLog.cs

@@ -0,0 +1,68 @@
+namespace DodoSSH.Api.Features.Events;
+
+/// <summary>Source-generated log messages for the event socket.</summary>
+/// <remarks>
+/// Ids and counts only, as everywhere else. A notice carries no ciphertext to leak, but which vault
+/// changed and when is still the metadata ADR 0001 asks be kept to what is diagnostically useful.
+/// </remarks>
+internal static partial class EventsLog
+{
+    [LoggerMessage(
+        EventId = 2201,
+        Level = LogLevel.Debug,
+        Message = "Event socket opened for user {UserId} following {VaultCount} vault(s); "
+            + "{ConnectionCount} open on this node.")]
+    internal static partial void ConnectionOpened(
+        ILogger logger,
+        Guid userId,
+        int vaultCount,
+        int connectionCount);
+
+    [LoggerMessage(
+        EventId = 2202,
+        Level = LogLevel.Debug,
+        Message = "Event socket closed for user {UserId}; {ConnectionCount} open on this node.")]
+    internal static partial void ConnectionClosed(ILogger logger, Guid userId, int connectionCount);
+
+    /// <remarks>
+    /// Information rather than Debug: a refused socket is a client that will poll for the rest of its
+    /// session, and an operator seeing these has a cap to raise.
+    /// </remarks>
+    [LoggerMessage(
+        EventId = 2203,
+        Level = LogLevel.Information,
+        Message = "Refused an event socket for user {UserId}: {Limit} is already reached.")]
+    internal static partial void ConnectionRefused(ILogger logger, Guid userId, string limit);
+
+    [LoggerMessage(
+        EventId = 2204,
+        Level = LogLevel.Debug,
+        Message = "Announced vault {VaultId} at sequence {Sequence} to {ConnectionCount} socket(s).")]
+    internal static partial void VaultChangePublished(
+        ILogger logger,
+        Guid vaultId,
+        long sequence,
+        int connectionCount);
+
+    [LoggerMessage(
+        EventId = 2205,
+        Level = LogLevel.Debug,
+        Message = "Announced a vault access change to {ConnectionCount} socket(s) of user {UserId}.")]
+    internal static partial void AccessChangePublished(ILogger logger, Guid userId, int connectionCount);
+
+    /// <remarks>
+    /// Warning, and it is worth being loud: the socket is still open and still delivering, but it is
+    /// delivering about a vault set that may be stale. Everything else here is routine.
+    /// </remarks>
+    [LoggerMessage(
+        EventId = 2206,
+        Level = LogLevel.Warning,
+        Message = "Could not re-resolve which vaults user {UserId}'s event socket may follow.")]
+    internal static partial void AccessRefreshFailed(ILogger logger, Guid userId, Exception exception);
+
+    [LoggerMessage(
+        EventId = 2207,
+        Level = LogLevel.Debug,
+        Message = "Closing user {UserId}'s event socket: {Reason}.")]
+    internal static partial void ClosingConnection(ILogger logger, Guid userId, string reason);
+}

src/DodoSSH.Api/Features/Events/VaultEventHub.cs

@@ -0,0 +1,242 @@
+using System.Collections.Concurrent;
+using System.Collections.Frozen;
+using System.Threading.Channels;
+using DodoSSH.Api.Setup;
+using DodoSSH.Contracts;
+using Microsoft.Extensions.Options;
+
+namespace DodoSSH.Api.Features.Events;
+
+/// <summary>
+/// Tells connected clients that something they can read has moved.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Every method is <c>void</c> and returns having queued, never having sent. That is the contract, not
+/// an implementation detail: the callers are write paths that have just committed a transaction, and a
+/// publish that could block on a slow socket would make one client's bad network everybody else's
+/// latency. A notice that cannot be queued is dropped, which is safe because the client polls anyway.
+/// See ADR 0012.
+/// </para>
+/// <para>
+/// An interface because this is the seam a multi-node backplane implements — PostgreSQL
+/// <c>LISTEN</c>/<c>NOTIFY</c> is the obvious one and needs no infrastructure this stack does not
+/// already run. It is deliberately not implemented: fan-out today is in-process, so a deployment with
+/// more than one API replica notices writes handled by other replicas on the polling interval rather
+/// than at once. That is the behaviour before this feature existed, which is why it degrades rather
+/// than breaks.
+/// </para>
+/// </remarks>
+public interface IVaultEventPublisher
+{
+    /// <summary>Announces that a vault's change log has reached <paramref name="sequence"/>.</summary>
+    /// <remarks>
+    /// Call <em>after</em> the transaction commits, and outside the per-vault advisory lock ADR 0003
+    /// takes. A notice sent from inside names a sequence no reader can see yet, and holds the vault's
+    /// write lock across a socket write.
+    /// </remarks>
+    void VaultChanged(Guid vaultId, long sequence);
+
+    /// <summary>Announces that the set of vaults an account can reach is no longer what it was.</summary>
+    /// <remarks>
+    /// Takes the <em>recipient</em>, not the actor. Sharing is something one account does to another's
+    /// list, and it is the other account that has to re-read.
+    /// </remarks>
+    void VaultAccessChanged(Guid userId);
+}
+
+/// <summary>
+/// Every event socket this node is holding.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Publishing walks the whole connection list and asks each one whether it cares, rather than keeping
+/// an index from vault to subscribers. With a per-node connection cap in the hundreds and an event rate
+/// bounded by how often people edit keychains, the walk is not measurable — and the index is not free:
+/// a connection's vault set is re-resolved while it is live, so every re-subscription would have to
+/// move it between buckets under a lock that publishing also takes. The simpler shape is the one whose
+/// races are obvious.
+/// </para>
+/// <para>
+/// A singleton, holding no scoped service and no database context. Connections outlive requests by
+/// design and anything request-scoped they captured would outlive its scope with them.
+/// </para>
+/// </remarks>
+internal sealed class VaultEventHub(
+    IOptions<EventsOptions> options,
+    TimeProvider clock,
+    ILogger<VaultEventHub> logger) : IVaultEventPublisher
+{
+    private readonly ConcurrentDictionary<Guid, VaultEventConnection> connections = new();
+
+    /// <summary>
+    /// Serialises admission so the caps are caps rather than approximations.
+    /// </summary>
+    /// <remarks>
+    /// Counting and inserting under one lock, because the two done separately let N simultaneous
+    /// connects all read the same under-cap count and all insert. Contended only by connects, which
+    /// happen once per client per session; publishing never takes it.
+    /// </remarks>
+    private readonly Lock admission = new();
+
+    /// <summary>How many sockets this node is holding. Diagnostics and tests.</summary>
+    internal int Count => connections.Count;
+
+    /// <summary>
+    /// Admits a socket, or refuses it because a cap is already met.
+    /// </summary>
+    /// <returns>The connection, or null when a limit refused it.</returns>
+    internal VaultEventConnection? TryAdmit(Guid userId, FrozenSet<Guid> vaults)
+    {
+        var limits = options.Value;
+
+        lock (admission)
+        {
+            if (connections.Count >= limits.MaxConnectionsTotal)
+            {
+                EventsLog.ConnectionRefused(logger, userId, "the node limit");
+                return null;
+            }
+
+            var held = 0;
+            foreach (var existing in connections.Values)
+            {
+                if (existing.UserId == userId && ++held >= limits.MaxConnectionsPerUser)
+                {
+                    EventsLog.ConnectionRefused(logger, userId, "the per-account limit");
+                    return null;
+                }
+            }
+
+            var connection = new VaultEventConnection(userId, vaults, limits.OutboundQueueDepth);
+
+            // Cannot collide: the id is fresh and this is the only insert.
+            connections[connection.Id] = connection;
+
+            EventsLog.ConnectionOpened(logger, userId, vaults.Count, connections.Count);
+
+            return connection;
+        }
+    }
+
+    /// <summary>Forgets a socket that has closed.</summary>
+    internal void Remove(VaultEventConnection connection)
+    {
+        ArgumentNullException.ThrowIfNull(connection);
+
+        connections.TryRemove(connection.Id, out _);
+        connection.Complete();
+
+        EventsLog.ConnectionClosed(logger, connection.UserId, connections.Count);
+    }
+
+    /// <inheritdoc />
+    public void VaultChanged(Guid vaultId, long sequence)
+    {
+        var notice = new VaultEvent(
+            VaultEventKinds.VaultChanged,
+            VaultId: vaultId,
+            Sequence: sequence,
+            ServerTime: clock.GetUtcNow());
+
+        var delivered = 0;
+
+        foreach (var connection in connections.Values)
+        {
+            if (connection.IsSubscribedTo(vaultId) && connection.TryEnqueue(notice))
+            {
+                delivered++;
+            }
+        }
+
+        if (delivered > 0)
+        {
+            EventsLog.VaultChangePublished(logger, vaultId, sequence, delivered);
+        }
+    }
+
+    /// <inheritdoc />
+    public void VaultAccessChanged(Guid userId)
+    {
+        var notice = new VaultEvent(VaultEventKinds.VaultsChanged, ServerTime: clock.GetUtcNow());
+
+        var delivered = 0;
+
+        foreach (var connection in connections.Values)
+        {
+            if (connection.UserId == userId && connection.TryEnqueue(notice))
+            {
+                delivered++;
+            }
+        }
+
+        if (delivered > 0)
+        {
+            EventsLog.AccessChangePublished(logger, userId, delivered);
+        }
+    }
+}
+
+/// <summary>
+/// One open socket, as the hub sees it.
+/// </summary>
+/// <remarks>
+/// Deliberately knows nothing about WebSockets. The hub queues frames here and the endpoint's pump
+/// takes them away, which is what keeps a publish from ever touching a socket — and what lets the
+/// whole fan-out be tested without one.
+/// </remarks>
+internal sealed class VaultEventConnection
+{
+    private readonly Channel<VaultEvent> outbound;
+
+    private FrozenSet<Guid> vaults;
+
+    internal VaultEventConnection(Guid userId, FrozenSet<Guid> vaults, int queueDepth)
+    {
+        Id = Guid.CreateVersion7();
+        UserId = userId;
+        this.vaults = vaults;
+
+        // DropOldest, and the choice is what makes a slow reader harmless. A notice says "vault X has
+        // moved to at least sequence N", so a newer one subsumes the one it displaces and the client's
+        // answer — pull that vault — is identical either way. The writer therefore never waits and
+        // TryWrite never fails, which is what lets the publish path be non-blocking and void.
+        outbound = Channel.CreateBounded<VaultEvent>(new BoundedChannelOptions(queueDepth)
+        {
+            FullMode = BoundedChannelFullMode.DropOldest,
+            SingleReader = true,
+            SingleWriter = false,
+        });
+    }
+
+    /// <summary>Identifies this connection within the hub. Never sent to a client.</summary>
+    internal Guid Id { get; }
+
+    /// <summary>The account that opened it.</summary>
+    internal Guid UserId { get; }
+
+    /// <summary>Frames waiting to be written to the socket.</summary>
+    internal ChannelReader<VaultEvent> Outbound => outbound.Reader;
+
+    /// <summary>How many vaults this socket currently follows.</summary>
+    internal int VaultCount => Volatile.Read(ref vaults).Count;
+
+    /// <summary>Whether a change to this vault concerns this socket.</summary>
+    internal bool IsSubscribedTo(Guid vaultId) => Volatile.Read(ref vaults).Contains(vaultId);
+
+    /// <summary>
+    /// Replaces what this socket follows, after its account's access was re-resolved.
+    /// </summary>
+    /// <remarks>
+    /// A whole-set swap of an immutable set rather than a mutation, so a publish walking the list
+    /// concurrently reads either the old set or the new one and never a half-built one. No lock: the
+    /// only writer is this connection's own pump.
+    /// </remarks>
+    internal void Resubscribe(FrozenSet<Guid> replacement) => Volatile.Write(ref vaults, replacement);
+
+    /// <summary>Queues a frame. Never blocks, and never fails — see the channel's full mode.</summary>
+    internal bool TryEnqueue(VaultEvent frame) => outbound.Writer.TryWrite(frame);
+
+    /// <summary>Signals that nothing more will be queued, which ends the pump's drain loop.</summary>
+    internal void Complete() => outbound.Writer.TryComplete();
+}

src/DodoSSH.Api/Features/Meta/MetaEndpoints.cs

@@ -19,6 +19,7 @@ namespace DodoSSH.Api.Features.Meta;
 internal sealed class GetMetaEndpoint(
     IOptions<SyncOptions> sync,
     IOptions<RelayOptions> relay,
+    IOptions<EventsOptions> events,
     IOptions<ServerOptions> server)
     : EndpointWithoutRequest<Ok<MetaResponse>>
 {
@@ -52,6 +53,14 @@ internal sealed class GetMetaEndpoint(
             features.Add(RelayFeature);
         }
 
+        // Advertised so a client knows whether to hold a socket open or rely on its timer. Absence is
+        // not an error — synchronising on a timer is the supported behaviour and the socket only makes
+        // it early — which is why this is a feature flag rather than a version bump. See ADR 0012.
+        if (events.Value.Enabled)
+        {
+            features.Add(VaultEvents.Feature);
+        }
+
         return Task.FromResult(TypedResults.Ok(new MetaResponse(
             ServerVersion: ServerVersion,
             ApiVersions: [1],

src/DodoSSH.Api/Features/Sync/SyncEndpoints.cs

@@ -1,4 +1,5 @@
 using DodoSSH.Api.Authorization;
+using DodoSSH.Api.Features.Events;
 using DodoSSH.Api.Setup;
 using DodoSSH.Contracts;
 using DodoSSH.Domain.Authorization;
@@ -81,6 +82,7 @@ internal sealed class SyncPullEndpoint(
 internal sealed class SyncPushEndpoint(
     ICurrentUserContext currentUser,
     IVaultAccessService vaultAccess,
+    IVaultEventPublisher events,
     SyncService sync)
     : Endpoint<SyncPushRequest, Results<Ok<SyncPushResponse>, NotFound, ProblemHttpResult>>
 {
@@ -127,6 +129,8 @@ internal sealed class SyncPushEndpoint(
             // single stale item cannot block everything else a client queued while offline.
             var response = await sync.PushAsync(access.Vault!, user.Id, req, ct).ConfigureAwait(false);
 
+            Announce(access.Vault!.Id, response);
+
             return TypedResults.Ok(response);
         }
         catch (PushBatchTooLargeException exception)
@@ -142,4 +146,41 @@ internal sealed class SyncPushEndpoint(
                 StatusCodes.Status400BadRequest, ProblemCodes.PushBatchTooLarge, exception.Message);
         }
     }
+
+    /// <summary>
+    /// Tells every socket following this vault that it has moved.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Here rather than inside <see cref="SyncService.PushAsync"/>, and that placement is the point:
+    /// the push has committed and released the per-vault advisory lock by the time this runs. Announced
+    /// from inside, it would name a sequence no reader could see yet and would hold the lock that
+    /// serialises writers across a fan-out. See ADR 0003 and ADR 0012.
+    /// </para>
+    /// <para>
+    /// The highest <em>applied</em> sequence, ignoring duplicates: a duplicate means an earlier push of
+    /// that operation already landed, and it was announced then. Nothing applied means nothing to say —
+    /// a batch of pure conflicts moved no vault, and announcing one anyway would have every client pull
+    /// for a change that is not there.
+    /// </para>
+    /// </remarks>
+    private void Announce(Guid vaultId, SyncPushResponse response)
+    {
+        var highest = 0L;
+
+        foreach (var result in response.Results)
+        {
+            if (result.Status == SyncOperationStatus.Applied
+                && result.ChangeSequence is { } sequence
+                && sequence > highest)
+            {
+                highest = sequence;
+            }
+        }
+
+        if (highest > 0)
+        {
+            events.VaultChanged(vaultId, highest);
+        }
+    }
 }

src/DodoSSH.Api/Features/Teams/TeamService.cs

@@ -1,4 +1,5 @@
 using System.Globalization;
+using DodoSSH.Api.Features.Events;
 using DodoSSH.Contracts;
 using DodoSSH.Domain;
 using DodoSSH.Infrastructure;
@@ -62,6 +63,7 @@ internal readonly record struct TeamAccess(Team? Team, TeamRole Role)
 internal sealed class TeamService(
     DodoDbContext database,
     TimeProvider clock,
+    IVaultEventPublisher events,
     ILogger<TeamService> logger)
 {
     /// <summary>Longest acceptable slug. Matches the column.</summary>
@@ -548,6 +550,11 @@ internal sealed class TeamService(
 
         TeamLog.MemberAdded(logger, teamId, target.Id, role, actor.Id);
 
+        // Membership is what the server will serve, so every vault this team owns has just appeared in
+        // the new member's list — before anybody wraps a key to them, which is a separate act and its
+        // own notice. Told at once rather than on their next pass. See ADR 0012.
+        events.VaultAccessChanged(target.Id);
+
         return await DescribeAsync(target, membership, cancellationToken).ConfigureAwait(false);
     }
 
@@ -744,6 +751,11 @@ internal sealed class TeamService(
         }).ConfigureAwait(false);
 
         TeamLog.MemberRemoved(logger, teamId, memberId, actor.Id, revoked);
+
+        // After the commit, so their client re-reads a list the server has already stopped serving
+        // those vaults from. Their open socket re-resolves as it forwards this, which is what stops it
+        // announcing changes to vaults they have just lost.
+        events.VaultAccessChanged(memberId);
     }
 
     /// <summary>Revokes one user's grants on every vault a team owns, and flags each for rekey.</summary>

src/DodoSSH.Api/Features/Teams/VaultGrantService.cs

@@ -1,4 +1,5 @@
 using System.Security.Cryptography;
+using DodoSSH.Api.Features.Events;
 using DodoSSH.Contracts;
 using DodoSSH.Domain;
 using DodoSSH.Infrastructure;
@@ -27,6 +28,7 @@ namespace DodoSSH.Api.Features.Teams;
 internal sealed class VaultGrantService(
     DodoDbContext database,
     TimeProvider clock,
+    IVaultEventPublisher events,
     ILogger<VaultGrantService> logger)
 {
     /// <summary>
@@ -414,6 +416,11 @@ internal sealed class VaultGrantService(
 
         TeamLog.GrantIssued(
             logger, vault.Id, generation, request.RecipientUserId, actor.Id);
+
+        // The recipient, never the actor. This is the whole of what makes a shared vault arrive at
+        // once rather than on the recipient's next pass — and it is the case the README has had to
+        // apologise for since sharing shipped. See ADR 0012.
+        events.VaultAccessChanged(request.RecipientUserId);
     }
 
     /// <summary>
@@ -701,6 +708,11 @@ internal sealed class VaultGrantService(
 
         TeamLog.GrantRevoked(logger, vault.Id, recipientUserId, actor.Id);
 
+        // Told so their client stops showing a vault it can no longer open, rather than leaving it
+        // listed until the next pass. It does not reach what they already pulled — nothing can, see
+        // ADR 0001 — and the server-side effect is immediate regardless of whether this arrives.
+        events.VaultAccessChanged(recipientUserId);
+
         return true;
     }
 

src/DodoSSH.Api/Program.cs

@@ -1,4 +1,5 @@
 using DodoSSH.Api.Authorization;
+using DodoSSH.Api.Features.Events;
 using DodoSSH.Api.Features.Identity;
 using DodoSSH.Api.Features.Sync;
 using DodoSSH.Api.Features.Teams;
@@ -47,6 +48,14 @@ builder.Services.AddScoped<VaultGrantService>();
 builder.Services.AddScoped<IIdentityBindingVerifier, IdentityBindingVerifier>();
 builder.Services.AddSingleton<ICursorKeyProvider, CursorKeyProvider>();
 
+// A singleton, because the sockets it holds outlive the requests that opened them. Registered twice
+// resolving to the same instance, for the reason the invitation claim above is: the endpoint needs the
+// whole hub — admit, remove, count — while the write paths that announce a change need only the two
+// methods that announce one, and should not gain a reference to connection management to get them.
+builder.Services.AddSingleton<VaultEventHub>();
+builder.Services.AddSingleton<IVaultEventPublisher>(
+    provider => provider.GetRequiredService<VaultEventHub>());
+
 // Scoped rather than the AddAuthorization default of singleton: the handler reads the request's
 // DbContext, and a singleton would capture one for the lifetime of the process.
 builder.Services.AddScoped<IAuthorizationHandler, EnrolledHandler>();
@@ -65,6 +74,13 @@ var app = builder.Build();
 
 app.BlockFastEndpointsRouteTable();
 
+// Before the authentication middleware, because the upgrade handshake has to survive it: the events
+// endpoint answers an ordinary authenticated request that happens to become a socket, and without
+// this the upgrade is never offered and the handler sees a plain GET. No allow-list of origins is
+// configured, deliberately — every client here is a native application sending a bearer token, so
+// there is no browser origin to trust and nothing a cross-site request could reach without one.
+app.UseWebSockets();
+
 app.UseAuthentication();
 app.UseAuthorization();
 

src/DodoSSH.Api/Setup/Configuration.cs

@@ -38,6 +38,22 @@ internal static class Configuration
                 "Sync:DefaultPullLimit must not exceed Sync:MaxPullLimit.")
             .ValidateOnStart();
 
+        services.AddOptions<EventsOptions>()
+            .BindConfiguration(EventsOptions.SectionName)
+            .ValidateDataAnnotations()
+            .Validate(
+                options => options.HeartbeatInterval > TimeSpan.Zero,
+                "Events:HeartbeatInterval must be greater than zero.")
+            .Validate(
+                options => options.AccessRefreshInterval > TimeSpan.Zero,
+                "Events:AccessRefreshInterval must be greater than zero.")
+            .Validate(
+                options => options.MaxConnectionDuration > options.AccessRefreshInterval,
+                "Events:MaxConnectionDuration must exceed Events:AccessRefreshInterval; a connection "
+                + "that never lives long enough to re-read its own access has none of the bound that "
+                + "setting exists to provide.")
+            .ValidateOnStart();
+
         services.AddOptions<RelayOptions>()
             .BindConfiguration(RelayOptions.SectionName)
             .ValidateDataAnnotations()

src/DodoSSH.Api/Setup/DodoOptions.cs

@@ -159,6 +159,82 @@ public sealed class RelayOptions
     public TimeSpan DrainTimeout { get; set; } = TimeSpan.FromSeconds(30);
 }
 
+/// <summary>Realtime push settings. See ADR 0012.</summary>
+/// <remarks>
+/// Every one of these bounds a socket rather than a feature: with the whole thing off, or every cap
+/// met, clients synchronise on their timer exactly as they did before this existed. That is what
+/// makes it safe for an operator to turn any of them down.
+/// </remarks>
+public sealed class EventsOptions
+{
+    /// <summary>Configuration section name.</summary>
+    public const string SectionName = "Events";
+
+    /// <summary>
+    /// Whether this deployment pushes vault changes at all.
+    /// </summary>
+    /// <remarks>
+    /// On by default, unlike the relay: this needs no outbound network, no target resolution and no
+    /// new trust, and a deployment behind a proxy that will not upgrade should say so here rather than
+    /// have every client discover it by failing.
+    /// </remarks>
+    public bool Enabled { get; set; } = true;
+
+    /// <summary>Maximum concurrent sockets per node.</summary>
+    [Range(1, 100_000)]
+    public int MaxConnectionsTotal { get; set; } = 500;
+
+    /// <summary>
+    /// Maximum concurrent sockets per account.
+    /// </summary>
+    /// <remarks>
+    /// Per account rather than per device, because the server cannot see a device here. Eight is a
+    /// laptop, a desktop, a phone and room to reconnect before the old socket has been reaped.
+    /// </remarks>
+    [Range(1, 1000)]
+    public int MaxConnectionsPerUser { get; set; } = 8;
+
+    /// <summary>
+    /// How many notices may be queued for one socket before the oldest are dropped.
+    /// </summary>
+    /// <remarks>
+    /// A notice names a vault and a position, so a newer one subsumes the one it replaces. The depth
+    /// therefore buys smoothness over a brief stall and nothing else — losing the tail of a burst
+    /// costs a client nothing, because the newest notice still says to pull.
+    /// </remarks>
+    [Range(1, 10_000)]
+    public int OutboundQueueDepth { get; set; } = 64;
+
+    /// <summary>
+    /// How often the server pings an idle socket.
+    /// </summary>
+    /// <remarks>
+    /// Below the sixty seconds most reverse proxies idle out at, because a silent socket that a proxy
+    /// has quietly dropped is indistinguishable from a quiet one until something is sent down it.
+    /// </remarks>
+    public TimeSpan HeartbeatInterval { get; set; } = TimeSpan.FromSeconds(30);
+
+    /// <summary>
+    /// How often an open socket re-reads which vaults its account may follow.
+    /// </summary>
+    /// <remarks>
+    /// The backstop for a grant withdrawn mid-connection. Grants and membership changes publish
+    /// immediately, so this is what covers the paths that do not — and what bounds the window if one
+    /// is ever added without remembering to.
+    /// </remarks>
+    public TimeSpan AccessRefreshInterval { get; set; } = TimeSpan.FromMinutes(5);
+
+    /// <summary>
+    /// The longest any one socket may live, regardless of its token.
+    /// </summary>
+    /// <remarks>
+    /// A socket normally ends at its access token's expiry, which is far shorter. This is the bound
+    /// for a provider that issues long-lived tokens, and it is what makes "no connection is older than
+    /// this" a property of the server rather than of the identity provider's configuration.
+    /// </remarks>
+    public TimeSpan MaxConnectionDuration { get; set; } = TimeSpan.FromHours(12);
+}
+
 /// <summary>Sync protocol limits.</summary>
 public sealed class SyncOptions
 {

src/DodoSSH.Api/Setup/EndpointRegistration.cs

@@ -1,3 +1,4 @@
+using DodoSSH.Api.Features.Events;
 using DodoSSH.Api.Features.Identity;
 using DodoSSH.Api.Features.Meta;
 using DodoSSH.Api.Features.Sync;
@@ -43,6 +44,7 @@ internal static class EndpointRegistration
             typeof(ReadKeyLogEndpoint),
             typeof(SyncPullEndpoint),
             typeof(SyncPushEndpoint),
+            typeof(VaultEventsEndpoint),
             typeof(CreateTeamEndpoint),
             typeof(ListTeamsEndpoint),
             typeof(UpdateTeamEndpoint),

src/DodoSSH.Api/appsettings.json

@@ -26,6 +26,11 @@
     "MaxConcurrentSessionsPerUser": 10,
     "MaxConcurrentSessionsTotal": 200
   },
+  "Events": {
+    "Enabled": true,
+    "MaxConnectionsTotal": 500,
+    "MaxConnectionsPerUser": 8
+  },
   "Sync": {
     "MaxOperationsPerPush": 500,
     "MaxPayloadBytes": 8388608,