From bee6202949010c68ee532f85c896f1768554762d Mon Sep 17 00:00:00 2001
From: Jaap-Jan de Wit | DodoTech <jaap-jan@dodotech.dev>
Date: Tue, 4 Aug 2026 16:04:15 +0200
Subject: [PATCH 1/7] Let a host be moved to another vault
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The one thing the host editor's vault picker has always been unable to offer,
and the comment beside it said so: an existing host's vault was not a field
because the two vaults are encrypted under different keys. That is still true.
What changed is that it is no longer a reason to have nothing.

**A move is a copy and a tombstone, and it cannot be anything else.** A payload
is sealed under its vault's key and its AAD binds the vault, the entity id and
the item version, so no edit moves one and no server call could — the server
holds ciphertext it cannot read. What crosses is the plaintext, in this process,
between an unwrap under one key and a seal under another. VaultItemRepository
gained MoveAsync for it, so the three decisions below live in one place with
their reasons rather than being re-derived at each call site.

The item takes a new id. Keeping it would put one entity id in two vaults, and
the item table is keyed on the type and the id rather than on the vault — so the
destination's row and the source's tombstone would be the same row, and the move
would delete what it had just written.

The write comes first and the tombstone second, which decides what an
interruption leaves: a copy in both vaults, visible and deletable, rather than a
tombstone with nothing on the other side. Both are queued rather than sent, so
the window is a crash between two local writes; it is still worth being on the
survivable side of.

Two activity lines rather than one, because that is what the two vaults actually
record. A single "moved" line would have to be written to one of them and would
be missing from the other's history.

**The group and the tags stay behind, and that is the half that makes this
honest.** Both are items of the vault the host is leaving: the editor's group
picker offers one vault's groups and the chips are drawn from one vault's tags.
A host carrying either across would resolve it on the machine that moved it —
groups and tags are resolved over every readable vault — and dangle for everybody
else in the destination. The mover and their colleagues would be looking at two
different hosts. Cleared and reported beats carried and invisible.

The key or password binding is kept, and the difference is not inconsistency.
Those genuinely resolve across vaults — one key on twenty hosts in three vaults
is the arrangement they exist for — so clearing them would take a working host
and make one that cannot connect. What the message does instead is name a
binding that is now outside the destination, because that is precisely what the
other members of it will not be able to resolve.

**It is not in the editor**, on either head: the desktop puts it in the detail
pane's ⋯ menu above the separator Delete sits below, and the phone beside EDIT.
A picker inside the form would move a machine as a side effect of correcting a
port, which is the bug the editor's own vault picker was fenced off to prevent in
the first place. The panel takes the footer as the deletion question does, and
says what will be left behind before the tap rather than after it — on a phone,
where the status line afterwards is one line on a screen somebody has already
navigated away from, that is the only place it reliably gets read.

The phone hides the button where there is nowhere to go rather than offering one
that answers with a refusal; the desktop keeps its menu entry either way, because
a menu that grew and shrank would be a menu whose items move.

One thing found while writing the test and deliberately not changed. The pass
that follows every write on this screen reports what it moved and supersedes the
confirmation — for a save and a delete as much as for a move — so the move's own
sentence is what somebody sees offline. The test asserts it in that state and
says why. Making confirmations survive their own sync pass is a question about
the whole screen rather than about this.

Four places said an item could never be moved, two of them sentences on screen in
both heads. All four now say what is true, including the design gaps document,
where the chevron beside the vault name stays undrawn for a different reason: a
chevron on a subtitle implies an edit, and this is a re-seal, a new id and two
references left behind.
---
 README.md                                     |  14 +-
 docs/design-import-gaps.md                    |   2 +-
 .../Views/HostsScreen.axaml                   | 120 +++++---
 src/DodoSSH.Client.App/Views/HostDrawer.axaml |  79 +++--
 .../ViewModels/VaultViewModel.cs              | 269 +++++++++++++++++-
 src/DodoSSH.Client.Sync/HostRepository.cs     |   9 +
 .../VaultItemRepository.cs                    |  66 +++++
 .../ScreenLayoutTests.cs                      |  30 ++
 .../VaultSharingTests.cs                      | 115 ++++++++
 9 files changed, 634 insertions(+), 70 deletions(-)

diff --git a/README.md b/README.md
index bac43c1..1ea0717 100644
--- a/README.md
+++ b/README.md
@@ -342,10 +342,16 @@ Six limits, stated rather than discovered:
   into it that is not there.
 
 Items are filed into one vault at a time, and which one is asked at the moment the item is made. **A host's
-editor has its own picker**, beside the name, because that is the decision that cannot be undone: the two
-vaults are encrypted under different keys, so moving an item afterwards means deleting it and typing it
-again — and the picker is therefore absent when you edit an existing host rather than present and refusing.
-Keys, passwords and buckets take theirs from a standing "new items go to" picker on the Keychain screen.
+editor has its own picker**, beside the name, because it is the decision on that form that decides who can
+read the host. It is absent when you edit an existing one rather than present and refusing, and that is not
+because the host is stuck: **a host can be moved to another vault** — "Move to another vault…" in the detail
+pane's menu on the desktop, MOVE beside EDIT on the phone. It is a separate act because it is not a save.
+The two vaults are encrypted under different keys, so a move is a re-seal into one and a tombstone in the
+other; the host gets a new id, and **its group and its tags stay behind**, because both are items of the
+vault it is leaving. A picker inside the form would do all of that as a side effect of correcting a port.
+What a move cannot do is reach a machine that has already synced the host, which is the same limit
+everything else about revocation has. Keys, passwords and buckets take theirs from a standing "new items go
+to" picker on the Keychain screen and cannot be moved yet.
 Both default to your personal vault and neither moves on its own, because an item put in a shared vault is
 visible to everybody holding that vault's key. Choosing a vault in the host editor also decides which groups
 it can be filed under: a group is an item like any other and lives in exactly one vault.
diff --git a/docs/design-import-gaps.md b/docs/design-import-gaps.md
index 9cf65d9..830da52 100644
--- a/docs/design-import-gaps.md
+++ b/docs/design-import-gaps.md
@@ -157,7 +157,7 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
 > | **Add Telnet**, and **Serial** in the toolbar | Omitted. `ISshConnection` is the only transport there is. This is also why the card subtitle's `ssh` is a constant today rather than a reading — it is stated in `HostRowViewModel.Summary`, which is the one place in this interface where a constant is printed on purpose. |
 > | **+ SSH ID, Certificate, FIDO2** | Omitted. `IDENTITIES` and `CERTIFICATES` have been on this document's list since the first import — neither is even a reserved `SyncEntityType` — and there is no security-key path anywhere in the SSH layer. One control offering three item types that do not exist. |
 > | The **Backspace / Default** row | Omitted. It is a terminal setting, and the client has no preferences store and no frame to carry one to the renderer — see the Preferences section. It would be a control whose value could not survive the window closing. |
-> | The **chevron beside the vault name** | The name alone, on the pane about an existing host: an item cannot be moved between vaults, because the two are encrypted under different keys and moving one is a delete and a retype. The half of the question that *does* have an answer — where a new host goes — is asked in the host editor, as a picker beside the name; keys, passwords and buckets take theirs from the keychain screen's standing picker instead. |
+> | The **chevron beside the vault name** | The name alone, and the move behind the pane's ⋯ menu instead. A host *can* now be moved between vaults, so the gap is no longer that there is nothing to offer — it is that a chevron on a subtitle implies an edit, and this is not one: the two vaults are encrypted under different keys, so it is a re-seal into one and a tombstone in the other, the host takes a new id, and its group and tags stay behind. A control that implied "just change this field" would be describing something else. Where a *new* host goes is still asked in the host editor, as a picker beside the name; keys, passwords and buckets take theirs from the keychain screen's standing picker and cannot be moved yet. |
 > | **Show more ⌄** | Not drawn as a disclosure. What it would hide — notes, the relay switch, forgetting the host key — is in the editor, one press away, and a second fold inside a pane that already scrolls is a second place for a field to be missing from. |
 > | **Port Forwarding** in the sidebar | Nothing, for the third time in this document. |
 > | The host grid's toolbar avatar, share and tag-filter controls | Omitted, as in v3 and for the same reasons. |
diff --git a/src/DodoSSH.Client.Android/Views/HostsScreen.axaml b/src/DodoSSH.Client.Android/Views/HostsScreen.axaml
index 821f6f2..fd589c3 100644
--- a/src/DodoSSH.Client.Android/Views/HostsScreen.axaml
+++ b/src/DodoSSH.Client.Android/Views/HostsScreen.axaml
@@ -262,10 +262,12 @@
 
           <!--
             ◆ WHICH VAULT THIS HOST WILL LIVE IN. Drawn only while adding and only where there is more than
-            one vault that can be written to, exactly as on the desktop — an existing host's vault cannot
-            change, because the two are encrypted under different keys and moving an item is a delete and a
-            retype. Above GROUP rather than below it because it decides what GROUP can offer: a group is an
-            item in one vault, so choosing a vault refills that list with that vault's groups.
+            one vault that can be written to, exactly as on the desktop — an existing host's vault is not a
+            field of this form, because the two are encrypted under different keys and changing it is a
+            re-seal into one vault and a tombstone in the other. That is MOVE, beside EDIT under the host,
+            and it is separate so that it cannot happen as a side effect of saving something else. Above
+            GROUP rather than below it because it decides what GROUP can offer: a group is an item in one
+            vault, so choosing a vault refills that list with that vault's groups.
           -->
           <StackPanel Spacing="6" IsVisible="{Binding ShowsEditorVaultChoice}">
             <TextBlock Classes="label" Text="VAULT" Margin="0,4,0,0" />
@@ -279,7 +281,7 @@
               </ComboBox.ItemTemplate>
             </ComboBox>
             <TextBlock Classes="body"
-                       Text="A host in a shared vault is readable by everybody holding that vault's key, and it cannot be moved out afterwards." />
+                       Text="A host in a shared vault is readable by everybody holding that vault's key. It can be moved out later, with MOVE under the host — what it cannot do is become unreadable to somebody who has already synced it." />
           </StackPanel>
 
           <TextBlock Classes="label" Text="GROUP" Margin="0,4,0,0" />
@@ -432,45 +434,97 @@
             BorderThickness="0,1,0,0" Padding="14,12">
       <StackPanel Spacing="10">
 
-        <StackPanel Orientation="Horizontal" Spacing="8">
-          <TextBlock Classes="label" Text="CONNECT TO" />
-          <TextBlock Classes="mono" FontSize="11" Text="{Binding SelectedHost.Label}" />
-        </StackPanel>
-
         <!--
-          Shown only for a host that actually asks for one. A password box beside a key-authenticated host
-          is an invitation to type a secret nothing will use.
-
-          The tick below it is the phone's whole answer to storing one, and on this head it is the only one:
-          the keychain lists credentials here but has no editor to create one in, so before this a password
-          typed on a phone could only ever be typed again. The host editor's picker could then bind it.
+          Everything about connecting, in one group so that the move panel below can take the bar rather
+          than appear underneath it. A password box and a CONNECT button under a form asking which vault to
+          move the host into would be two unrelated questions in one bar, and the taller of the two would
+          push the other off a phone screen.
         -->
-        <TextBox Classes="field secret" IsVisible="{Binding SelectedHostAsksForAPassword}"
-                 Text="{Binding ConnectPassword}" PlaceholderText="password">
-          <TextBox.KeyBindings>
-            <KeyBinding Gesture="Enter" Command="{Binding ConnectCommand}" />
-          </TextBox.KeyBindings>
-        </TextBox>
+        <StackPanel Spacing="10" IsVisible="{Binding !IsMovingHost}">
 
-        <CheckBox IsChecked="{Binding RemembersConnectPassword}" MinHeight="44"
-                  IsVisible="{Binding SelectedHostAsksForAPassword}">
-          <TextBlock Classes="mono" FontSize="11.5" TextWrapping="Wrap"
-                     Text="Remember this password for this host" />
-        </CheckBox>
+          <StackPanel Orientation="Horizontal" Spacing="8">
+            <TextBlock Classes="label" Text="CONNECT TO" />
+            <TextBlock Classes="mono" FontSize="11" Text="{Binding SelectedHost.Label}" />
+          </StackPanel>
 
-        <TextBlock Classes="detail" TextWrapping="Wrap" IsVisible="{Binding !SelectedHostAsksForAPassword}"
-                   Text="{Binding SelectedHostAuthenticationNote}" />
+          <!--
+            Shown only for a host that actually asks for one. A password box beside a key-authenticated host
+            is an invitation to type a secret nothing will use.
 
-        <Button Classes="primary" Content="CONNECT" Command="{Binding ConnectCommand}"
-                IsEnabled="{Binding !IsBusy}" />
+            The tick below it is the phone's whole answer to storing one, and on this head it is the only
+            one: the keychain lists credentials here but has no editor to create one in, so before this a
+            password typed on a phone could only ever be typed again. The host editor's picker could then
+            bind it.
+          -->
+          <TextBox Classes="field secret" IsVisible="{Binding SelectedHostAsksForAPassword}"
+                   Text="{Binding ConnectPassword}" PlaceholderText="password">
+            <TextBox.KeyBindings>
+              <KeyBinding Gesture="Enter" Command="{Binding ConnectCommand}" />
+            </TextBox.KeyBindings>
+          </TextBox>
+
+          <CheckBox IsChecked="{Binding RemembersConnectPassword}" MinHeight="44"
+                    IsVisible="{Binding SelectedHostAsksForAPassword}">
+            <TextBlock Classes="mono" FontSize="11.5" TextWrapping="Wrap"
+                       Text="Remember this password for this host" />
+          </CheckBox>
+
+          <TextBlock Classes="detail" TextWrapping="Wrap"
+                     IsVisible="{Binding !SelectedHostAsksForAPassword}"
+                     Text="{Binding SelectedHostAuthenticationNote}" />
+
+          <Button Classes="primary" Content="CONNECT" Command="{Binding ConnectCommand}"
+                  IsEnabled="{Binding !IsBusy}" />
+        </StackPanel>
 
         <!--
           Not asked for by the design, and here because a + that adds hosts with no way to correct one is a
           strange thing to ship. It costs nothing: the editor above serves both, so this is the same panel
           opened on an existing row.
+
+          MOVE is beside it rather than inside it, and that is the same line the desktop's menu draws: which
+          vault a host is in is not a field of the host. The two vaults are encrypted under different keys,
+          so it is a re-seal into one and a tombstone in the other — nothing a SAVE could do. It shows only
+          where there is somewhere to move to; see VaultViewModel.CanMoveSelectedHost.
         -->
-        <Button Classes="secondary" Height="44" Content="EDIT"
-                Command="{Binding EditSelectedHostCommand}" />
+        <Grid ColumnDefinitions="*,8,*" IsVisible="{Binding !IsMovingHost}">
+          <Button Grid.Column="0" Classes="secondary" Height="44" Content="EDIT"
+                  Command="{Binding EditSelectedHostCommand}" />
+          <Button Grid.Column="2" Classes="secondary" Height="44" Content="MOVE"
+                  IsVisible="{Binding CanMoveSelectedHost}"
+                  Command="{Binding MoveHostCommand}" />
+        </Grid>
+
+        <!--
+          ◆ MOVING THE HOST TO ANOTHER VAULT, in the place the connect controls were. A picker and two
+          buttons rather than a question with a yes: what is being asked is which vault, and a move is
+          undone by moving it back.
+
+          The sentence is not decoration. A group and a tag are items of the vault the host is leaving, so
+          neither can come with it — and on a phone, where the status line afterwards is one line at the
+          bottom of a screen somebody has already navigated away from, saying it before the tap is the only
+          place it reliably gets read.
+        -->
+        <StackPanel Spacing="10" IsVisible="{Binding IsMovingHost}">
+          <TextBlock Classes="label" Text="MOVE TO VAULT" />
+          <ComboBox HorizontalAlignment="Stretch" MinHeight="44"
+                    ItemsSource="{Binding MoveVaultChoices}"
+                    SelectedItem="{Binding SelectedMoveVault}">
+            <ComboBox.ItemTemplate>
+              <DataTemplate x:DataType="vm:VaultChoiceViewModel">
+                <TextBlock Classes="mono" FontSize="12" Text="{Binding Display}" />
+              </DataTemplate>
+            </ComboBox.ItemTemplate>
+          </ComboBox>
+          <TextBlock Classes="body"
+                     Text="The host is re-encrypted with the other vault's key, so everybody who holds that key can read it and nobody else can. Its group and tags stay behind — both belong to the vault it is leaving." />
+          <Grid ColumnDefinitions="*,8,*">
+            <Button Grid.Column="0" Classes="primary" Height="44" Content="MOVE"
+                    Command="{Binding ConfirmMoveHostCommand}" IsEnabled="{Binding !IsBusy}" />
+            <Button Grid.Column="2" Classes="secondary" Height="44" Content="CANCEL"
+                    Command="{Binding CancelMoveHostCommand}" />
+          </Grid>
+        </StackPanel>
       </StackPanel>
     </Border>
 
diff --git a/src/DodoSSH.Client.App/Views/HostDrawer.axaml b/src/DodoSSH.Client.App/Views/HostDrawer.axaml
index 24b4813..21063d7 100644
--- a/src/DodoSSH.Client.App/Views/HostDrawer.axaml
+++ b/src/DodoSSH.Client.App/Views/HostDrawer.axaml
@@ -71,11 +71,12 @@
         One row for all three panels, which is why what it says is on the view model rather than repeated
         three times here. See VaultViewModel.DrawerTitle.
 
-        The subtitle is the vault this host is filed in, and the design's chevron beside it is not drawn:
-        an item cannot be moved between vaults — the two are encrypted under different keys, so moving one
-        is a delete and a retype — and a picker offering the move would be offering something no layer below
-        this can do. Choosing the vault at the moment a host is created is a different question and does
-        have an answer; it is in the editor, beside the name.
+        The subtitle is the vault this host is filed in, and the design's chevron beside it is still not
+        drawn although a host can now be moved. The two are encrypted under different keys, so a move is a
+        re-seal into one vault and a tombstone in the other — it leaves the host's group and tags behind and
+        gives it a new id, none of which a chevron on a subtitle would lead anybody to expect. It is in the
+        menu instead, next to the two other things that happen to a whole host. Choosing the vault at the
+        moment a host is created is a different question, and it is in the editor beside the name.
       -->
       <Border Grid.Row="0" Padding="14,10" Background="{StaticResource Panel}"
               BorderBrush="{StaticResource Border}" BorderThickness="0,0,0,1">
@@ -91,10 +92,15 @@
           </StackPanel>
 
           <!--
-            The host's own two actions, behind a menu rather than as a row of buttons under the pane. They
-            are what EDIT and DELETE were; a pane whose footer is CONNECT has one action worth a button, and
-            the other two are things you go looking for. It hides with the deletion question for the reason
-            the buttons did — see VaultViewModel.ShowsHostPaneActions.
+            The host's own actions, behind a menu rather than as a row of buttons under the pane. They are
+            what EDIT and DELETE were; a pane whose footer is CONNECT has one action worth a button, and the
+            rest are things you go looking for. It hides with the deletion question and with the move panel
+            for the reason the buttons did — see VaultViewModel.ShowsHostPaneActions.
+
+            Moving is here rather than in the editor, and the separator says which side of the line it is
+            on: it is not a field of the host. The two vaults are encrypted under different keys, so it is a
+            re-seal into one and a tombstone in the other — nothing a SAVE could do — and a picker inside
+            the form would let somebody correcting a port move a machine by leaving it where they found it.
           -->
           <Button Grid.Column="1" Classes="flat paneicon" Content="⋯"
                   IsVisible="{Binding ShowsHostPaneActions}"
@@ -102,6 +108,7 @@
             <Button.Flyout>
               <MenuFlyout>
                 <MenuItem Header="Edit…" Command="{Binding EditSelectedHostCommand}" />
+                <MenuItem Header="Move to another vault…" Command="{Binding MoveHostCommand}" />
                 <Separator />
                 <MenuItem Header="Delete…" Command="{Binding DeleteHostCommand}" />
               </MenuFlyout>
@@ -365,12 +372,16 @@
                 <TextBox Text="{Binding EditorLabel}" PlaceholderText="name" />
 
                 <!--
-                  ◆ WHICH VAULT THIS HOST WILL LIVE IN, asked here because it is the one decision on this
-                  form that cannot be changed afterwards: the vaults are encrypted under different keys, so
-                  moving an item between them is a delete and a retype. It is a field of the host rather
-                  than the keychain screen's standing "new items go to" preference, and it is a separate
-                  selection from it — moving this one does not move that one, and a click over there cannot
-                  move a host half-typed here.
+                  ◆ WHICH VAULT THIS HOST WILL LIVE IN, asked here because it decides who can read it and
+                  because it is the one thing on this form that no later SAVE can change: the vaults are
+                  encrypted under different keys, so changing it is a re-seal into one and a tombstone in
+                  the other. That is offered — "Move to another vault…" in the pane's own menu — and it is
+                  deliberately not this control, because a picker inside the form would move a machine as a
+                  side effect of correcting a port.
+
+                  It is a field of the host rather than the keychain screen's standing "new items go to"
+                  preference, and it is a separate selection from it — moving this one does not move that
+                  one, and a click over there cannot move a host half-typed here.
 
                   Shown only while adding, and only where there is more than one vault that can be written
                   to. An existing host's row is not drawn at all rather than drawn disabled; the drawer's
@@ -390,7 +401,7 @@
                     </ComboBox.ItemTemplate>
                   </ComboBox>
                   <TextBlock Classes="hint" FontSize="11" TextWrapping="Wrap"
-                             Text="A host in a shared vault is readable by everybody holding that vault's key, and it cannot be moved out afterwards." />
+                             Text="A host in a shared vault is readable by everybody holding that vault's key. It can be moved out later, from this pane's own menu — what it cannot do is become unreadable to somebody who has already synced it." />
                 </StackPanel>
 
                 <!--
@@ -602,13 +613,13 @@
 
       <!-- ============ THE FOOTER ============ -->
       <!--
-        One row, and exactly one of its four contents is showing — the same by-construction exclusivity the
+        One row, and exactly one of its five contents is showing — the same by-construction exclusivity the
         panels above have, from the same flags. It is what each panel is for: connecting, saving a host,
-        saving a group, or answering the question about deleting one.
+        saving a group, answering the question about deleting one, or choosing where to move one.
 
         ◆ THE QUESTION TAKES CONNECT'S PLACE rather than stacking under it, as it always did with the row of
         buttons this footer replaced, so that DELETE cannot be pressed again while its own question is on
-        screen. See VaultViewModel.ShowsHostPaneActions.
+        screen. See VaultViewModel.ShowsHostPaneActions. The move panel takes it for the same reason.
       -->
       <Border Grid.Row="2" Padding="12" Background="{StaticResource Panel}"
               BorderBrush="{StaticResource Border}" BorderThickness="0,1,0,0">
@@ -624,6 +635,36 @@
             <views:ConfirmDeleteCard />
           </Border>
 
+          <!--
+            ◆ MOVING THE HOST TO ANOTHER VAULT. A picker and two buttons, not a question with a yes: what
+            is being asked is which vault, and a move is undone by moving it back rather than by being
+            careful — so this is not drawn in the danger colours the deletion question uses.
+
+            The sentence under it is the part worth keeping. A group and a tag are items of the vault the
+            host is leaving, so neither can come; saying so here rather than only in the status line
+            afterwards is the difference between a warning and a surprise. What it deliberately does not
+            promise is anything about the key or password the host authenticates with — those resolve
+            across vaults, they are kept, and the status line names one that is left outside.
+          -->
+          <StackPanel Spacing="8" IsVisible="{Binding IsMovingHost}">
+            <TextBlock Classes="label" Text="MOVE TO VAULT" />
+            <ComboBox HorizontalAlignment="Stretch" ItemsSource="{Binding MoveVaultChoices}"
+                      SelectedItem="{Binding SelectedMoveVault}">
+              <ComboBox.ItemTemplate>
+                <DataTemplate x:DataType="vm:VaultChoiceViewModel">
+                  <TextBlock Text="{Binding Display}" FontSize="12" />
+                </DataTemplate>
+              </ComboBox.ItemTemplate>
+            </ComboBox>
+            <TextBlock Classes="hint" FontSize="10.5" TextWrapping="Wrap"
+                       Text="The host is re-encrypted with the other vault's key, so everybody who holds that key can read it and nobody else can. Its group and tags stay behind — both belong to the vault it is leaving." />
+            <StackPanel Orientation="Horizontal" Spacing="6">
+              <Button Classes="accent" Content="MOVE" Command="{Binding ConfirmMoveHostCommand}"
+                      IsEnabled="{Binding !IsBusy}" />
+              <Button Classes="ghost" Content="CANCEL" Command="{Binding CancelMoveHostCommand}" />
+            </StackPanel>
+          </StackPanel>
+
           <StackPanel Orientation="Horizontal" Spacing="6" IsVisible="{Binding IsEditing}">
             <Button Classes="accent" Content="SAVE" Command="{Binding SaveHostCommand}" />
             <Button Classes="ghost" Content="CANCEL" Command="{Binding CancelEditCommand}" />
diff --git a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
index 1340856..65373b8 100644
--- a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
+++ b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
@@ -1817,8 +1817,58 @@ internal sealed partial class VaultViewModel(
     /// while the deletion question is up it would offer to ask it again — which is the rule
     /// <see cref="ShowsHostActions"/> has always carried for the row of buttons these two replaced. The
     /// question takes CONNECT's place in the footer for the same reason it took DELETE's.
+    /// <para>
+    /// The move panel is in that list too and for the same reason. It takes the footer as well, so leaving
+    /// CONNECT under it would put two things in one row — and the menu it came from would still be offering
+    /// to open it.
+    /// </para>
     /// </remarks>
-    internal bool ShowsHostPaneActions => IsShowingHostDetail && !IsConfirmingHostDeletion;
+    internal bool ShowsHostPaneActions =>
+        IsShowingHostDetail && !IsConfirmingHostDeletion && !IsMovingHost;
+
+    /// <summary>
+    /// Whether the panel asking which vault to move the selected host to is up.
+    /// </summary>
+    /// <remarks>
+    /// The armed-state idiom this window uses everywhere instead of a modal, and here it carries a choice
+    /// rather than a yes: the question is not "are you sure" but "which vault", and the sentence beside it
+    /// says what will be left behind. See <see cref="MoveHost"/>.
+    /// </remarks>
+    [ObservableProperty]
+    [NotifyPropertyChangedFor(nameof(ShowsHostPaneActions))]
+    private bool isMovingHost;
+
+    /// <summary>Which host the open move panel is about. Null when it is closed.</summary>
+    /// <remarks>
+    /// Held rather than read off the selection, so the panel survives a reload replacing every row object —
+    /// see <see cref="OnSelectedHostChanged"/>, which is the only thing that reads it.
+    /// </remarks>
+    private Guid? movingHostId;
+
+    /// <summary>Where the selected host could be moved: every vault this session can write to but its own.</summary>
+    internal ObservableCollection<VaultChoiceViewModel> MoveVaultChoices { get; } = [];
+
+    [ObservableProperty]
+    private VaultChoiceViewModel? selectedMoveVault;
+
+    /// <summary>
+    /// Whether the selected host has anywhere to move to.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Asked so the phone can leave the button out rather than offer one that answers with a refusal — it
+    /// has room for two buttons under a host and no room to explain a third that does nothing. The desktop
+    /// keeps its menu entry either way: a menu that grew and shrank would be a menu whose items move.
+    /// </para>
+    /// <para>
+    /// It counts vaults rather than merely asking whether there are two, because the answer is per host: a
+    /// host already in the only other writable vault has nowhere to go, and a read-only vault is not
+    /// somewhere anything can be moved to.
+    /// </para>
+    /// </remarks>
+    internal bool CanMoveSelectedHost =>
+        SelectedHost is { IsReadOnly: false } row
+        && session.ReadableVaults.Any(vault => vault.CanWrite && vault.VaultId != row.VaultId);
 
     /// <summary>
     /// What the drawer's header says it is about.
@@ -1839,11 +1889,12 @@ internal sealed partial class VaultViewModel(
     /// The line under it: which keychain this is filed in, or what a group is for.
     /// </summary>
     /// <remarks>
-    /// The vault's name and not a picker for it, although the design draws one with a chevron. An item
-    /// cannot be moved between vaults here — that is a delete and a retype, because the two are encrypted
-    /// under different keys — so a control offering the move would be offering something no layer below
-    /// this can do. Where a *new* item goes is chosen on the keychain screen's own picker; see
-    /// <see cref="TargetVaults"/>.
+    /// The vault's name and not a picker for it, although the design draws one with a chevron. A host can
+    /// be moved between vaults now — see <see cref="MoveHost"/> — and it is still not a field: the move is
+    /// a re-seal under another key and a tombstone under this one, so binding it to a control that saves
+    /// with the rest of the form would let somebody correcting a port move a machine by leaving a picker
+    /// where they found it. It has its own panel and its own button. Where a *new* item goes is chosen on
+    /// the keychain screen's own picker; see <see cref="TargetVaults"/>.
     /// </remarks>
     internal string DrawerSubtitle => (IsEditing, IsEditingGroup) switch
     {
@@ -1961,9 +2012,10 @@ internal sealed partial class VaultViewModel(
     /// <remarks>
     /// <para>
     /// Only while creating, and only where there is more than one vault to choose between. An existing
-    /// host's vault is not editable and the picker is not shown disabled beside it: the two are encrypted
-    /// under different keys, so moving an item is a delete and a retype rather than a save — see the note
-    /// on the drawer's header, which says where the host is filed.
+    /// host's vault is not a field of this form and the picker is not shown disabled beside it: the two
+    /// are encrypted under different keys, so moving one is a re-seal and a tombstone rather than a save.
+    /// That is offered — by <see cref="MoveHost"/>, from the pane's own menu — and it is a separate act
+    /// precisely because it must not happen as a side effect of saving something else.
     /// </para>
     /// <para>
     /// Hidden at one vault rather than shown with a single option, which is the rule
@@ -4907,6 +4959,185 @@ internal sealed partial class VaultViewModel(
         return imported;
     }
 
+    /// <summary>
+    /// Opens the panel that asks which vault the selected host should move to.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// A panel rather than a picker in the host editor, and the reason is what a move is underneath: the
+    /// item is re-sealed under another vault's key and the one it came from gets a tombstone — see
+    /// <c>VaultItemRepository.MoveAsync</c>. That is not a field of the host and must not be saved with
+    /// one, or somebody correcting a port would move a machine into a colleague's vault by leaving a
+    /// picker where they found it.
+    /// </para>
+    /// <para>
+    /// Refused for a host written by a newer client, exactly as editing one is: the move re-encodes the
+    /// payload, so a field this build cannot represent would be dropped on the way across.
+    /// </para>
+    /// </remarks>
+    [RelayCommand]
+    private void MoveHost()
+    {
+        if (SelectedHost is not { } row || AHostEditorIsInTheWay())
+        {
+            return;
+        }
+
+        if (row.IsReadOnly)
+        {
+            Status = "This host was written by a newer version of DodoSSH. Moving it would re-encode it "
+                + "here and lose what this build cannot read. Update first.";
+            return;
+        }
+
+        BuildMoveVaultChoices(row.VaultId);
+
+        if (MoveVaultChoices.Count == 0)
+        {
+            // The one-vault case, and the honest sentence rather than an empty picker. It is also what
+            // somebody in a team whose only other vault is read-only sees.
+            Status = $"There is nowhere to move '{row.Label}' to: this is the only vault you can write to.";
+            return;
+        }
+
+        // Disarms a deletion aimed at the same host. Two questions about one machine, one of which
+        // destroys it, is not a pane anybody should have to read carefully.
+        PendingDeletion = null;
+        movingHostId = row.EntityId;
+        IsMovingHost = true;
+        Status = string.Empty;
+    }
+
+    /// <summary>Abandons the move panel.</summary>
+    [RelayCommand]
+    private void CancelMoveHost()
+    {
+        IsMovingHost = false;
+        movingHostId = null;
+        MoveVaultChoices.Clear();
+        SelectedMoveVault = null;
+        Status = string.Empty;
+    }
+
+    /// <summary>
+    /// Moves the selected host into the chosen vault.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>The group and the tags are left behind, and that is the whole of what makes this honest.</b> Both
+    /// are items of the vault the host is leaving: the group picker in the editor offers one vault's groups
+    /// and the tag chips are drawn from one vault's tags, so a host carrying either across would point at
+    /// something the destination does not contain. On this machine it would still resolve — groups and tags
+    /// are resolved across every readable vault — and for everybody else in the destination it would dangle,
+    /// which means the mover and their colleagues would see two different hosts. Cleared and reported beats
+    /// carried and invisible.
+    /// </para>
+    /// <para>
+    /// <b>The key or password binding is kept</b>, and the difference is not inconsistency. Those genuinely
+    /// resolve across vaults — one key on twenty hosts in three vaults is the arrangement they exist for —
+    /// so clearing them would take a working host and make it one that cannot connect. What it can do is say
+    /// when the binding is now in a different vault from the host, because that is exactly what the other
+    /// members of the destination will not be able to resolve.
+    /// </para>
+    /// <para>
+    /// The row is re-selected by its new id afterwards. A move that left the pane on a host that no longer
+    /// exists would read as the machine having been deleted.
+    /// </para>
+    /// </remarks>
+    [RelayCommand]
+    private async Task ConfirmMoveHostAsync(CancellationToken cancellationToken)
+    {
+        if (SelectedHost is not { } row || SelectedMoveVault is not { } target)
+        {
+            return;
+        }
+
+        var name = target.Name;
+        var dropped = WhatWasLeftBehind(row.Host);
+        var stranded = BindingOutside(row.Host, target.VaultId);
+
+        var moved = row.Host with { GroupId = null, TagIds = TagSet.Empty };
+
+        IsMovingHost = false;
+        movingHostId = null;
+        MoveVaultChoices.Clear();
+        SelectedMoveVault = null;
+
+        await RunAsync(
+            "Moving…",
+            async () =>
+            {
+                var entityId = await session.Hosts
+                    .MoveAsync(row.VaultId, target.VaultId, row.EntityId, moved, cancellationToken)
+                    .ConfigureAwait(true);
+
+                await ReloadAsync(cancellationToken).ConfigureAwait(true);
+
+                SelectedHost = Hosts.FirstOrDefault(host => host.EntityId == entityId);
+
+                Status = $"Moved '{row.Label}' to {name}.{dropped}{stranded}";
+            }).ConfigureAwait(true);
+
+        // As a save and a deletion do. A move is two writes in two vaults, and a machine that syncs one of
+        // them and not the other shows the host twice or not at all until the next pass.
+        await AutoSyncAsync(cancellationToken).ConfigureAwait(true);
+    }
+
+    /// <summary>What the move left behind, said only when it left something.</summary>
+    private static string WhatWasLeftBehind(HostSecret host) =>
+        (host.GroupId is not null, host.TagIds.Count > 0) switch
+        {
+            (true, true) => " Its group and tags were left behind — both belong to the vault it came from.",
+            (true, false) => " Its group was left behind — a group belongs to the vault it is in.",
+            (false, true) => " Its tags were left behind — a tag belongs to the vault it is in.",
+            _ => string.Empty,
+        };
+
+    /// <summary>
+    /// The warning about a key or password that is not in the vault the host has moved to.
+    /// </summary>
+    /// <remarks>
+    /// Named rather than counted, because which one it is decides what to do about it — and the answer is
+    /// usually to put a copy of that key in the destination vault, which needs to know which key.
+    /// </remarks>
+    private string BindingOutside(HostSecret host, Guid vaultId)
+    {
+        if (host.SshKeyId is { } keyId
+            && Keys.FirstOrDefault(row => row.EntityId == keyId) is { } key
+            && key.VaultId != vaultId)
+        {
+            return $" It still authenticates with the key '{key.Label}', which is in another vault — "
+                + "everybody else in this one will find that binding unresolvable.";
+        }
+
+        if (host.CredentialId is { } credentialId
+            && Credentials.FirstOrDefault(row => row.EntityId == credentialId) is { } credential
+            && credential.VaultId != vaultId)
+        {
+            return $" It still authenticates with the password '{credential.Label}', which is in another "
+                + "vault — everybody else in this one will find that binding unresolvable.";
+        }
+
+        return string.Empty;
+    }
+
+    /// <summary>Fills the move panel's picker with every vault this session can write to but that one.</summary>
+    private void BuildMoveVaultChoices(Guid vaultId)
+    {
+        MoveVaultChoices.Clear();
+
+        foreach (var choice in session.ReadableVaults
+            .Where(vault => vault.CanWrite && vault.VaultId != vaultId)
+            .OrderByDescending(vault => vault.IsPersonal)
+            .ThenBy(vault => vault.Name, StringComparer.CurrentCulture)
+            .Select(vault => new VaultChoiceViewModel(vault.VaultId, vault.Name, vault.IsPersonal)))
+        {
+            MoveVaultChoices.Add(choice);
+        }
+
+        SelectedMoveVault = MoveVaultChoices.FirstOrDefault();
+    }
+
     /// <summary>Asks whether the selected host should go.</summary>
     /// <remarks>
     /// A terminal already open on the host is disclosed rather than prevented, because deleting a host does
@@ -7039,10 +7270,10 @@ internal sealed partial class VaultViewModel(
     /// Moves a half-typed host into the vault just chosen for it.
     /// </summary>
     /// <remarks>
-    /// Only while creating. An existing host's vault is fixed, and this guard is what makes that true
-    /// rather than the view merely not drawing the control: an item cannot be moved between vaults, so a
-    /// path that reassigned this on an edit would write the host into a second vault and leave the
-    /// original behind.
+    /// Only while creating, and this guard is what makes that true rather than the view merely not drawing
+    /// the control. An existing host <em>can</em> change vaults — see <see cref="MoveHost"/> — but not this
+    /// way and not as part of a save: reassigning it here on an edit would write the host into a second
+    /// vault and leave the original behind, which is a fork rather than a move.
     /// </remarks>
     partial void OnEditorSelectedVaultChanged(VaultChoiceViewModel? value)
     {
@@ -7427,6 +7658,7 @@ internal sealed partial class VaultViewModel(
         OnPropertyChanged(nameof(IsDrawerOpen));
         OnPropertyChanged(nameof(IsShowingHostDetail));
         OnPropertyChanged(nameof(ShowsHostPaneActions));
+        OnPropertyChanged(nameof(CanMoveSelectedHost));
 
         // Kept in step so that selecting a host in code — a reload restoring one, the palette connecting to
         // one — lights the right row. Assigning the same value again is a no-op, so the two do not chase each
@@ -7434,6 +7666,17 @@ internal sealed partial class VaultViewModel(
         SelectedSidebarRow = value;
 
         DisarmIfAimedElsewhere(DeletionTarget.Host, value?.EntityId);
+
+        // The move panel goes with the selection, as the deletion question does — and by entity id for the
+        // same reason DisarmIfAimedElsewhere compares them: a background pass replaces every row object in
+        // the list, so a panel closed on row identity would fold up once a minute under somebody who was
+        // still choosing a vault in it. A click onto a different host is the case that needs handling, and
+        // it is cleared rather than re-aimed: which vault to move to is a choice about the host it was
+        // asked for.
+        if (IsMovingHost && movingHostId != value?.EntityId)
+        {
+            CancelMoveHostCommand.Execute(null);
+        }
     }
 
     /// <remarks>
diff --git a/src/DodoSSH.Client.Sync/HostRepository.cs b/src/DodoSSH.Client.Sync/HostRepository.cs
index 14044b6..531b8a3 100644
--- a/src/DodoSSH.Client.Sync/HostRepository.cs
+++ b/src/DodoSSH.Client.Sync/HostRepository.cs
@@ -38,6 +38,15 @@ public sealed class HostRepository(
         CancellationToken cancellationToken) =>
         hosts.UpdateAsync(vaultId, entityId, host, cancellationToken);
 
+    /// <inheritdoc cref="VaultItemRepository{TSecret}.MoveAsync" />
+    public Task<Guid> MoveAsync(
+        Guid fromVaultId,
+        Guid toVaultId,
+        Guid entityId,
+        HostSecret host,
+        CancellationToken cancellationToken) =>
+        hosts.MoveAsync(fromVaultId, toVaultId, entityId, host, cancellationToken);
+
     /// <inheritdoc cref="VaultItemRepository{TSecret}.DeleteAsync" />
     public Task DeleteAsync(Guid vaultId, Guid entityId, CancellationToken cancellationToken) =>
         hosts.DeleteAsync(vaultId, entityId, cancellationToken);
diff --git a/src/DodoSSH.Client.Sync/VaultItemRepository.cs b/src/DodoSSH.Client.Sync/VaultItemRepository.cs
index b46ce78..bc0936b 100644
--- a/src/DodoSSH.Client.Sync/VaultItemRepository.cs
+++ b/src/DodoSSH.Client.Sync/VaultItemRepository.cs
@@ -234,6 +234,72 @@ internal sealed class VaultItemRepository<TSecret>(
         }
     }
 
+    /// <summary>
+    /// Moves an item into another vault.
+    /// </summary>
+    /// <param name="fromVaultId">The vault it is in.</param>
+    /// <param name="toVaultId">The vault it should be in.</param>
+    /// <param name="entityId">The item.</param>
+    /// <param name="secret">
+    /// What to write into the destination. The caller's, rather than read from here, because moving is the
+    /// one operation where the item does not arrive unchanged: references to things that live in the vault
+    /// it is leaving are the mover's to resolve, and this layer has no way to know which those are.
+    /// </param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The id the item has in its new vault.</returns>
+    /// <remarks>
+    /// <para>
+    /// <b>A copy and a tombstone, and it cannot be anything else.</b> An item's payload is sealed under
+    /// its vault's key and its AAD binds the vault, the entity id and the item version — so there is no
+    /// edit that moves one, and no server call that could: the server holds ciphertext it cannot read.
+    /// What crosses is the plaintext, in this process, between an unwrap under one key and a seal under
+    /// another.
+    /// </para>
+    /// <para>
+    /// <b>A new id, deliberately.</b> Keeping it would put one entity id in two vaults, and the item table
+    /// is keyed on the type and the id rather than on the vault — so the destination's row and the
+    /// source's tombstone would be the same row, and the move would delete what it had just written.
+    /// Callers holding the old id have to take the new one back.
+    /// </para>
+    /// <para>
+    /// <b>The write comes first and the tombstone second</b>, which decides what an interruption leaves
+    /// behind: a copy in both vaults, which is visible and can be deleted, rather than a tombstone with
+    /// nothing on the other side, which is the host gone. Both are queued rather than sent, so the window
+    /// is a crash between two local writes — narrow, and worth choosing the survivable side of anyway.
+    /// </para>
+    /// <para>
+    /// Two activity lines, not one: a create in the destination and a delete in the source, which is what
+    /// the vaults actually record. A single "moved" line would have to be written to one of them and would
+    /// be missing from the other's history.
+    /// </para>
+    /// </remarks>
+    internal async Task<Guid> MoveAsync(
+        Guid fromVaultId,
+        Guid toVaultId,
+        Guid entityId,
+        TSecret secret,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(secret);
+
+        if (fromVaultId == toVaultId)
+        {
+            throw new ArgumentException(
+                "That item is already in that vault.", nameof(toVaultId));
+        }
+
+        // Both keys before either write, so a destination this session cannot write to is refused with
+        // nothing having happened rather than after the source item has gone.
+        _ = Key(fromVaultId);
+        _ = Key(toVaultId);
+
+        var moved = await CreateAsync(toVaultId, secret, cancellationToken).ConfigureAwait(false);
+
+        await DeleteAsync(fromVaultId, entityId, cancellationToken).ConfigureAwait(false);
+
+        return moved;
+    }
+
     /// <summary>
     /// Deletes an item.
     /// </summary>
diff --git a/tests/DodoSSH.Client.App.Layout.Tests/ScreenLayoutTests.cs b/tests/DodoSSH.Client.App.Layout.Tests/ScreenLayoutTests.cs
index 75e8441..c9633cb 100644
--- a/tests/DodoSSH.Client.App.Layout.Tests/ScreenLayoutTests.cs
+++ b/tests/DodoSSH.Client.App.Layout.Tests/ScreenLayoutTests.cs
@@ -223,6 +223,36 @@ public sealed class ScreenLayoutTests : IAsyncLifetime
         await MeasureDrawerAsync(faults => faults.ShouldBeEmpty());
     }
 
+    /// <remarks>
+    /// <para>
+    /// The move panel, which takes the footer as the deletion question does and is the taller of the two: a
+    /// heading, a combo box, a wrapping paragraph and two buttons, in a 304-pixel column. The paragraph is
+    /// the risk — it is what says the group and the tags stay behind — and the footer is one of the two
+    /// parts of this drawer that is not inside a <c>ScrollViewer</c>, so nothing brings it back into view.
+    /// </para>
+    /// <para>
+    /// The state is set here rather than through <c>MoveHostCommand</c>, which would refuse: this fixture's
+    /// account holds one vault, and the command declines rather than open a picker with nothing in it. What
+    /// this test is about is the rectangle, and the flow that fills it is covered in
+    /// <c>DodoSSH.Client.App.Tests</c>.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task TheHostDrawerFitsWithTheMovePanelOpen()
+    {
+        vault.OpenHostPaneCommand.Execute(vault.Hosts[0]);
+
+        vault.MoveVaultChoices.Add(
+            new VaultChoiceViewModel(Guid.CreateVersion7(), "Platform Engineering secrets", false));
+
+        vault.SelectedMoveVault = vault.MoveVaultChoices[0];
+        vault.IsMovingHost = true;
+
+        vault.ShowsHostPaneActions.ShouldBeFalse("the panel takes the footer rather than sharing it");
+
+        await MeasureDrawerAsync(faults => faults.ShouldBeEmpty());
+    }
+
     /// <remarks>
     /// <para>
     /// What a double-click on a machine does everywhere else, and did not do here: it opens a shell on it.
diff --git a/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs b/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
index 5a61ec9..e29bb5c 100644
--- a/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
+++ b/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
@@ -532,6 +532,121 @@ public sealed class VaultSharingTests : IAsyncLifetime
         row.VaultId.ShouldBe(sharedVaultId);
     }
 
+    /// <remarks>
+    /// <para>
+    /// Moving a host into a shared vault, which is the operation that used to require deleting it and
+    /// typing it again: the two vaults are encrypted under different keys, so what happens underneath is a
+    /// re-seal into one and a tombstone in the other. The host has to arrive intact, be gone from where it
+    /// was, and carry a new id — one entity id in two vaults would make the destination's row and the
+    /// source's tombstone the same row.
+    /// </para>
+    /// <para>
+    /// The group is asserted cleared, and that is the half worth a test rather than a comment. A group is
+    /// an item of the vault the host is leaving, so a host that carried the reference across would resolve
+    /// it on this machine — groups are resolved over every readable vault — and dangle for everybody else
+    /// in the destination. The mover and their colleagues would be looking at two different hosts.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task MovingAHostToAnotherVault_ReSealsItThereAndLeavesItsGroupBehind()
+    {
+        await UnlockedAsync();
+
+        var vaults = shell.Vaults;
+
+        await CreateVaultAsync(vaults, "Platform secrets");
+
+        var vault = shell.Vault!;
+        var sharedVaultId = vaults.SelectedVault!.VaultId;
+
+        await vault.LoadAsync(Token);
+
+        // In the personal vault, under a group of its own, which is what the move has to leave behind.
+        vault.NewGroupCommand.Execute(null);
+        vault.GroupEditorLabel = "Production";
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+
+        vault.NewHostCommand.Execute(null);
+        vault.EditorLabel = "prod-db";
+        vault.EditorHostname = "db.internal";
+        vault.EditorUsername = "deploy";
+        vault.EditorSelectedGroup = vault.EditorGroupChoices.Single(
+            choice => string.Equals(choice.Label, "Production", StringComparison.Ordinal));
+
+        await vault.SaveHostCommand.ExecuteAsync(null);
+
+        var before = vault.Hosts.Single(
+            host => string.Equals(host.Label, "prod-db", StringComparison.Ordinal));
+
+        before.VaultId.ShouldNotBe(sharedVaultId);
+        before.Host.GroupId.ShouldNotBeNull("the host was filed under a group before the move");
+
+        vault.SelectedHost = before;
+        vault.CanMoveSelectedHost.ShouldBeTrue("there is a second vault this session can write to");
+
+        vault.MoveHostCommand.Execute(null);
+
+        vault.IsMovingHost.ShouldBeTrue(vault.Status);
+        vault.MoveVaultChoices.ShouldNotContain(choice => choice.VaultId == before.VaultId);
+
+        vault.SelectedMoveVault =
+            vault.MoveVaultChoices.Single(choice => choice.VaultId == sharedVaultId);
+
+        // The pass that follows every write on this screen is made to fail, so that the move's own sentence
+        // is still on the status line to be read. That is not a contrivance to dodge a race: a successful
+        // pass reports what it moved and supersedes the confirmation of every save, delete and move alike —
+        // pre-existing behaviour of the whole screen — and the state asserted here is the one where the
+        // sentence matters most, because nothing has reached the server yet.
+        server.SyncFailure = new IOException("The server is not answering.");
+
+        await vault.ConfirmMoveHostCommand.ExecuteAsync(null);
+
+        var after = vault.Hosts.Single(
+            host => string.Equals(host.Label, "prod-db", StringComparison.Ordinal));
+
+        after.VaultId.ShouldBe(sharedVaultId, vault.Status);
+        after.EntityId.ShouldNotBe(before.EntityId, "an id belongs to one vault");
+        after.Host.Hostname.ShouldBe("db.internal");
+        after.Host.Username.ShouldBe("deploy");
+        after.Host.GroupId.ShouldBeNull("a group belongs to the vault the host came from");
+
+        vault.SelectedHost?.EntityId.ShouldBe(after.EntityId, "the pane follows the host it moved");
+        vault.Status.ShouldContain("Platform secrets");
+        vault.Status.ShouldContain("group", Case.Insensitive);
+    }
+
+    /// <remarks>
+    /// The move is refused where it would have nowhere to go, by the command rather than by an empty
+    /// picker — and the phone reads the same question to decide whether to draw the button at all.
+    /// </remarks>
+    [Fact]
+    public async Task MovingAHostWithNowhereToMoveIt_SaysSoRatherThanOpeningAnEmptyPicker()
+    {
+        await UnlockedAsync();
+
+        var vault = shell.Vault!;
+
+        await vault.LoadAsync(Token);
+
+        vault.NewHostCommand.Execute(null);
+        vault.EditorLabel = "prod-db";
+        vault.EditorHostname = "db.internal";
+        vault.EditorUsername = "deploy";
+
+        await vault.SaveHostCommand.ExecuteAsync(null);
+
+        vault.SelectedHost = vault.Hosts.Single(
+            host => string.Equals(host.Label, "prod-db", StringComparison.Ordinal));
+
+        vault.CanMoveSelectedHost.ShouldBeFalse("the personal vault is the only one there is");
+
+        vault.MoveHostCommand.Execute(null);
+
+        vault.IsMovingHost.ShouldBeFalse();
+        vault.MoveVaultChoices.ShouldBeEmpty();
+        vault.Status.ShouldContain("only vault you can write to");
+    }
+
     /// <remarks>
     /// <para>
     /// The picker the host editor grew, and the thing it is for: choosing at the moment a host is created,

From be012585b352cdec40d18f2aed01fceffbba9efd Mon Sep 17 00:00:00 2001
From: Jaap-Jan de Wit | DodoTech <jaap-jan@dodotech.dev>
Date: Tue, 4 Aug 2026 16:27:01 +0200
Subject: [PATCH 2/7] Let a group be right-clicked, as a host already can
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The host cards have had a menu since the grid replaced the sidebar; the group
cards above them had a double-click and two buttons beside the heading, and
nothing that named the card under the pointer. Open, Edit and Delete are on them
now, drawn and aimed the same way.

On the list rather than in the item template, for the reason the host grid's is:
the three commands are the vault's, and a ContextMenu inside a DataTemplate has
the row for its data context, so every binding in it would silently resolve to
nothing. The code-behind selects whatever was right-clicked before the menu
opens, and that is what makes one menu act on the card under the pointer rather
than on whichever was selected before.

**Cancelled over the space around the cards, and here that guard is doing more
than the host grid's.** GroupTarget falls back to the group whose contents are on
screen when no card is selected — the right answer for a pair of buttons beside
the heading, which would otherwise have no subject the moment a group with
nothing inside it is opened, and the wrong one for a menu that opened on a card.
Without the guard, right-clicking the gap beside the cards would offer to delete
the group the trail ends with: a question about something the user is not
pointing at, in the one menu where the answer is a deletion.

Only Open takes a parameter, and it has to. OpenGroupCommand's null is a real
argument rather than a missing one — it is the trail's first crumb, ALL HOSTS —
so an entry with no parameter would not open the card, it would leave the group
the user right-clicked and go back to the top level.

Two tests beside the two the host menu already had. What they hold that a build
cannot is the CommandParameter binding: a path that resolves to nothing compiles
and draws, and the entry would then quietly do the opposite of what it says. The
popup itself is still the platform's, so manual-checks 7.9 gained the group half
of the same check.
---
 docs/manual-checks.md                         | 10 ++
 .../Views/HostsScreen.axaml                   | 28 ++++++
 .../Views/HostsScreen.axaml.cs                | 32 +++++++
 .../HostGridTests.cs                          | 95 ++++++++++++++++++-
 4 files changed, 160 insertions(+), 5 deletions(-)

diff --git a/docs/manual-checks.md b/docs/manual-checks.md
index a33fdd8..3a53cc7 100644
--- a/docs/manual-checks.md
+++ b/docs/manual-checks.md
@@ -795,6 +795,16 @@ With host A selected, right-click host B and choose Delete.
 wrong machine. `HostGridTests` covers both halves headlessly, so this is a confirmation that a real popup
 behaves as the headless one did.
 
+**And the same on the group cards above.** Open a group, then right-click a card inside it and choose
+Delete.
+
+**Pass:** the question names the **card**, not the group that is open — and Open on that menu goes into the
+card, rather than back out to ALL HOSTS. Right-clicking the space around the group cards opens no menu.
+
+**Failure means:** the menu is reading `GroupTarget`'s fallback, which is the group whose contents are on
+screen. That fallback is right for the EDIT and DELETE buttons beside the heading and wrong for a menu that
+opened on a card.
+
 ### 7.10 Clicking a host in the palette connects
 
 Ctrl+K, then click a result with the mouse rather than pressing Enter.
diff --git a/src/DodoSSH.Client.App/Views/HostsScreen.axaml b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
index 77700f9..f57211e 100644
--- a/src/DodoSSH.Client.App/Views/HostsScreen.axaml
+++ b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
@@ -282,6 +282,34 @@
               <ListBox.ItemsPanel>
                 <ItemsPanelTemplate><WrapPanel /></ItemsPanelTemplate>
               </ListBox.ItemsPanel>
+
+              <!--
+                The three things you can do to a group, on the group itself — the same menu the host grid
+                below has, for the same reasons. On the list rather than in the item template, because the
+                commands are the vault's and a menu inside a DataTemplate would have the row for its data
+                context; the code-behind selects whatever was right-clicked before the menu opens, and
+                cancels it outright over the space around the cards.
+
+                Open is here as well as on the double-click, and Edit and Delete as well as on the two
+                buttons above, and neither is a duplicate for its own sake: a gesture is unreachable without
+                a pointer, and the buttons act on GroupTarget — which with no card selected is the group the
+                trail ends with rather than the one under the pointer. This menu is the one place all three
+                act on the card that was right-clicked.
+
+                Only Open takes a parameter, because OpenGroupCommand's null means ALL HOSTS rather than
+                nothing; Edit and Delete read GroupTarget, which the selection the code-behind has just made
+                is the first half of.
+              -->
+              <ListBox.ContextMenu>
+                <ContextMenu>
+                  <MenuItem Header="Open" Command="{Binding OpenGroupCommand}"
+                            CommandParameter="{Binding SelectedGroup}" />
+                  <MenuItem Header="Edit…" Command="{Binding EditGroupCommand}" />
+                  <Separator />
+                  <MenuItem Header="Delete…" Command="{Binding DeleteGroupCommand}" />
+                </ContextMenu>
+              </ListBox.ContextMenu>
+
               <ListBox.ItemTemplate>
                 <DataTemplate x:DataType="vm:HostGroupRowViewModel">
                   <Border Classes="tile">
diff --git a/src/DodoSSH.Client.App/Views/HostsScreen.axaml.cs b/src/DodoSSH.Client.App/Views/HostsScreen.axaml.cs
index e291c2e..35adc4f 100644
--- a/src/DodoSSH.Client.App/Views/HostsScreen.axaml.cs
+++ b/src/DodoSSH.Client.App/Views/HostsScreen.axaml.cs
@@ -96,6 +96,11 @@ internal sealed partial class HostsScreen : UserControl
         HostGrid.AddHandler(PointerPressedEvent, OnPointerPressed, RoutingStrategies.Tunnel);
         HostGrid.AddHandler(ContextRequestedEvent, OnContextRequested, RoutingStrategies.Tunnel);
 
+        // And the group cards answer a right click the same way, for the same reason: their menu's commands
+        // read the vault's group selection, and without this they would act on whichever card was selected
+        // before — or, with none, on the group the trail ends with, which is not on screen at all.
+        GroupGrid.AddHandler(ContextRequestedEvent, OnGroupContextRequested, RoutingStrategies.Tunnel);
+
         HostGrid.PointerMoved += OnPointerMoved;
         HostGrid.PointerReleased += OnPointerReleased;
         HostGrid.PointerCaptureLost += OnPointerCaptureLost;
@@ -204,6 +209,33 @@ internal sealed partial class HostsScreen : UserControl
         vault.SelectedSidebarRow = row;
     }
 
+    /// <summary>
+    /// Points the group menu at whatever was right-clicked.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The host grid's rule, applied to the cards above it — see <see cref="OnContextRequested"/>. What is
+    /// different is what an unaimed menu would have done: <c>GroupTarget</c> falls back to the open group
+    /// when no card is selected, so Edit and Delete over a card would have been offered about the group whose
+    /// contents are showing rather than the one the pointer is on. That fallback is right for a pair of
+    /// buttons that sit beside the heading and wrong for a menu that opened on a card.
+    /// </para>
+    /// <para>
+    /// Cancelled outright over the space around the cards, as the host grid's is. That is not a group, and
+    /// the fallback is exactly what would make the menu look like it worked there.
+    /// </para>
+    /// </remarks>
+    private void OnGroupContextRequested(object? sender, ContextRequestedEventArgs e)
+    {
+        if (Vault is not { } vault || RowUnder(e.Source) is not HostGroupRowViewModel row)
+        {
+            e.Handled = true;
+            return;
+        }
+
+        vault.SelectedGroup = row;
+    }
+
     /// <remarks>
     /// Remembered rather than acted on. Whether this press is a click or the start of a drag is not known
     /// until the pointer moves, so this is the point at which both are still possible.
diff --git a/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs b/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
index c193c7a..773eb43 100644
--- a/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
+++ b/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
@@ -29,10 +29,11 @@ namespace DodoSSH.Client.App.Layout.Tests;
 /// <para>
 /// Separate from <see cref="ScreenLayoutTests"/>, which measures these controls rather than driving them.
 /// What is here is the one gesture that cannot be expressed as a binding and cannot be checked by
-/// measuring: a right click has to move the selection <em>before</em> the menu opens, because all three of
-/// that menu's commands read the vault's host selection. A menu that quietly acted on whichever host
+/// measuring: a right click has to move the selection <em>before</em> the menu opens, because the commands
+/// on both of that screen's menus read the vault's selection. A menu that quietly acted on whichever host
 /// happened to be selected would delete the wrong machine, which is the version of this mistake worth a
-/// suite.
+/// suite — and the group cards have the same menu with a fallback behind it that makes getting it wrong
+/// quieter still.
 /// </para>
 /// <para>
 /// A real <see cref="VaultViewModel"/> over a real unlocked vault, for the reason the other suites here use
@@ -159,6 +160,82 @@ public sealed class HostGridTests : IAsyncLifetime
         });
     }
 
+    /// <summary>
+    /// The same rule on the cards above, where getting it wrong is quieter and worse.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The host grid's menu acts on nothing when it is not aimed; this one acts on the <em>wrong group</em>.
+    /// <c>GroupTarget</c> falls back to the group whose contents are on screen when no card is selected — the
+    /// right answer for the pair of buttons beside the heading, and the wrong one for a menu that opened on a
+    /// card, which would then offer to delete a group the pointer is nowhere near.
+    /// </para>
+    /// <para>
+    /// Open is the one entry that takes a parameter, because <c>OpenGroupCommand</c>'s null is a real
+    /// argument — it is ALL HOSTS. That makes its <c>CommandParameter</c> binding the half most likely to
+    /// rot: a path that resolves to nothing compiles, draws, and quietly leaves the grid at the top level.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task ARightClickSelectsTheGroupUnderThePointer()
+    {
+        await AddGroupAsync("staging");
+
+        await OnTheGridAsync((screen, window) =>
+        {
+            var first = GroupRow(vault, "production");
+            var other = GroupRow(vault, "staging");
+
+            vault.SelectedGroup = first;
+
+            RightClick(CardFor(screen, other), window);
+
+            vault.SelectedGroup.ShouldBeSameAs(other);
+
+            var menu = screen.GroupGrid.ContextMenu.ShouldNotBeNull();
+            menu.IsOpen.ShouldBeTrue();
+
+            var items = menu.Items.OfType<MenuItem>().ToList();
+
+            var open = items.Single(item => item.Header is "Open");
+            open.Command.ShouldBeSameAs(vault.OpenGroupCommand);
+            open.CommandParameter.ShouldBeSameAs(other, "the card under the pointer, not ALL HOSTS");
+
+            var edit = items.Single(item => item.Header is "Edit…");
+            edit.Command.ShouldBeSameAs(vault.EditGroupCommand);
+
+            edit.Command!.Execute(null);
+
+            vault.IsEditingGroup.ShouldBeTrue();
+            vault.GroupEditorLabel.ShouldBe(
+                other.Label, "the card that was right-clicked, not the one selected before");
+        });
+    }
+
+    /// <remarks>
+    /// The space around the group cards, where a menu would be at its most misleading: nothing is under the
+    /// pointer, so an unguarded one would open against the fallback and offer Delete about the group the
+    /// trail ends with — which, once it is open, is not a card on screen at all.
+    /// </remarks>
+    [Fact]
+    public async Task ARightClickOffAnyGroupCardOpensNothingAndMovesNothing()
+    {
+        await OnTheGridAsync((screen, _) =>
+        {
+            var selected = GroupRow(vault, "production");
+            vault.SelectedGroup = selected;
+
+            screen.GroupGrid.RaiseEvent(new ContextRequestedEventArgs
+            {
+                RoutedEvent = Control.ContextRequestedEvent,
+                Source = screen.GroupGrid,
+            });
+
+            vault.SelectedGroup.ShouldBeSameAs(selected, "the selection the menu would have acted on");
+            screen.GroupGrid.ContextMenu.ShouldNotBeNull().IsOpen.ShouldBeFalse();
+        });
+    }
+
     /// <summary>
     /// A host held over a group card would be filed there, and one held over another host card would not.
     /// </summary>
@@ -474,14 +551,22 @@ public sealed class HostGridTests : IAsyncLifetime
             .OfType<ListBoxItem>()
             .Single(item => item.DataContext is HostGroupRowViewModel);
 
-    private static ListBoxItem CardFor(Visual screen, HostRowViewModel host) =>
+    /// <remarks>Any row: a host card or a group card, which are both items of a list on this screen.</remarks>
+    private static ListBoxItem CardFor(Visual screen, object row) =>
         screen.GetVisualDescendants()
             .OfType<ListBoxItem>()
-            .First(item => ReferenceEquals(item.DataContext, host));
+            .First(item => ReferenceEquals(item.DataContext, row));
 
     private static HostRowViewModel Row(VaultViewModel vault, string label) =>
         vault.Hosts.First(row => string.Equals(row.Label, label, StringComparison.Ordinal));
 
+    /// <remarks>
+    /// Out of the cards on screen rather than out of every group, because that is what the card's own data
+    /// context is — <c>Groups</c> holds the same row objects, but only one level of them is drawn.
+    /// </remarks>
+    private static HostGroupRowViewModel GroupRow(VaultViewModel vault, string label) =>
+        vault.VisibleGroups.First(row => string.Equals(row.Label, label, StringComparison.Ordinal));
+
     private static Point Centre(Visual control, Visual window) =>
         control.TranslatePoint(new Point(control.Bounds.Width / 2, control.Bounds.Height / 2), window)
         ?? throw new InvalidOperationException("the control is not in this window's tree");

From c39df3f51e0c2f0b8c64e1d161d368c66a2e3baf Mon Sep 17 00:00:00 2001
From: Jaap-Jan de Wit | DodoTech <jaap-jan@dodotech.dev>
Date: Tue, 4 Aug 2026 16:27:16 +0200
Subject: [PATCH 3/7] Share the shelf as well as what is on it, and ask a group
 which vault
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A group is where hosts are filed and what lends them a port, a username and a key,
and until now it could only ever be made in the vault this machine files new items
into. So sharing a vault shared the machines and not the arrangement: a colleague
opened four hosts filed under a group they could read the name of and nothing else,
and the group a teammate made had no card, no heading and no way to be corrected
from the screen looking straight at the hosts inside it. Recorded as half shipped in
docs/design-import-gaps.md, and this is the other half.

The list stopped being the active vault's. It was narrow for two stated reasons —
a row shown across vaults has to carry which vault it lives in, because rename and
delete both need it, and two vaults may hold a "production" each, which a layout
with one heading per group cannot tell apart — and both are now paid for rather than
avoided. Every row carries its vault, the badge beside the name says which, and the
two cards sit side by side saying what they are.

The three shapes of the group read are now deliberately different sizes. The list is
what a person looks at, so a hidden vault's groups leave it: a card that cannot be
opened onto anything is worse than no card. The per-vault lists are what a picker
offers, because a picker is always asking about one vault. The map is what a host's
GroupId resolves through, and it stays widest of all — including over hidden vaults,
since a group lends a port and hiding a vault must never change what one of its
hosts dials. RebuildGroups is the one place hiding is applied, which is what keeps
those answers apart.

The editor asks which vault on the terms the host editor's picker set: while adding
only, hidden where there is one writable vault, and never offered afterwards, because
the two are encrypted under different keys and moving an item is a delete and a
retype. Its parent picker is that vault's alone, for the reason the host editor's
group picker is one level down — a parent in another vault is a level half the key
holders cannot resolve, and their hosts would inherit from nothing. + NEW GROUP
inside an open group departs from NewHost and takes that group's vault rather than
the standing preference: a group made inside another is in its parent's vault by
construction, and answering "inside PLATFORM" with a group elsewhere and no parent
would drop the one thing the button said.

Two smaller things follow from the cards spanning vaults. Dragging a host onto a
group card in another vault is refused with both names, because the write it would
make is exactly the id-nobody-can-resolve the host editor's picker was fixed to
prevent, and treating it as "no group" would unfile a host somebody was plainly
filing. And a group being renamed says its vault in the drawer's header, since the
picker is not drawn for an existing one and renaming a colleague's shelf without
being told whose it is is the edit most worth naming.

The save target is a nullable field behind a property that falls back to the standing
preference. The group name box is bound whether or not anything raised an editor over
it — that is what the desktop's group bar was, and typing a name into it and pressing
ADD is still a way to make a group, which would otherwise have written to no vault
at all.

1575 tests pass, five more than before: a group filed into a shared vault is listed
and renamed there, the editor's picker does not move the keychain screen's, the
parent picker offers only its own vault, a cross-vault drop is refused, and hiding a
vault takes the cards without changing what its hosts dial.
---
 docs/design-import-gaps.md                    |   2 +-
 docs/manual-checks.md                         |  25 +
 .../Views/HostsScreen.axaml                   |  37 +-
 src/DodoSSH.Client.App/Views/HostDrawer.axaml |  28 +
 .../Views/HostsScreen.axaml                   |  11 +
 .../ViewModels/VaultViewModel.cs              | 488 ++++++++++++++----
 .../VaultSharingTests.cs                      | 212 +++++++-
 .../VaultVisibilityTests.cs                   |  67 ++-
 8 files changed, 762 insertions(+), 108 deletions(-)

diff --git a/docs/design-import-gaps.md b/docs/design-import-gaps.md
index 9cf65d9..da94fc3 100644
--- a/docs/design-import-gaps.md
+++ b/docs/design-import-gaps.md
@@ -307,7 +307,7 @@ caption buttons and window title drawn on top of the application's own — two s
 | Tag chips (`nginx`, `eu`, `pg16`) | client-domain | A tag item type, and a way to put one on a host. | **Shipped.** `Tag = 5` is a live item kind and `HostSecret.TagIds` names them, merged per tag so two people tagging one host both keep theirs — which is what `HostTag = 6` was going to buy, so it stays reserved and unused. Chips are drawn on host rows on both heads and toggled in the host editor, which also creates one inline; renaming and deleting are a TAGS category on the keychain screen. The filter box still searches name, address and notes only — a chip is read rather than typed. |
 | Groups `PRODUCTION` / `STAGING` / `PERSONAL` | client-domain | A host-group item type (`HostGroup = 4`, reserved) or a group field on `HostSecret`. | **Shipped**, as both: `VaultHostGroup` is a synced item kind and `HostSecret.GroupId` names one. A group carries a `ParentId` and the defaults its hosts inherit, and the two heads draw the nesting differently on purpose. The desktop is a grid of cards holding one level at a time, the way a directory pane holds one directory; the phone has no room for a row of cards, so it flattens the whole tree into one heading per group in label order with no indentation. A keychain with no groups renders exactly as it did before on both — one flat list, no headings and no cards. |
 | Group badge `TEAM·PLATFORM` | server | **Built in M3.** | The vault's name on each row, and the personal vault ordered first. Not the team's name: two of a team's vaults would then carry the same badge and the badge would be naming the wrong thing. Distinct from the groups above, and deliberately so — a group is a shelf the user chose, a vault is who can read the item. |
-| Groups on a **team's** hosts | client-domain | A vault id on each group row for rename and delete, and a way to tell two vaults' identically-named groups apart in a list with one heading per group. | **Half shipped, and the half that shipped had to.** Every readable vault's groups are now read into the resolution map, because a group lends a port, a username and a binding — so a host whose group went unread would silently dial 22 as nobody while the machine is on 2222 as `deploy`. A missing heading is cosmetic; a missing port is a connection to the wrong place. The editable list is still the active vault's alone, so a group a teammate made has no card and no heading and cannot be renamed from here. A host filed into one is drawn at the outermost level of the desktop's grid and under UNGROUPED on the phone — reachable either way, which is the point — with the chip on its card still naming the group, because the label is resolved through the wide map while the level is decided from the narrow list. |
+| Groups on a **team's** hosts | client-domain | A vault id on each group row for rename and delete, and a way to tell two vaults' identically-named groups apart in a list with one heading per group. | **Shipped, and it is what makes a shared vault an arrangement rather than a heap.** Both halves are paid for: the row carries the vault it came out of, so rename and delete go back to it, and the vault's name is drawn beside the group's on the desktop's cards and the phone's headings wherever the session holds more than one — which is what lets two `production` groups sit side by side. The group editor asks which vault a new group goes into, on the terms the host editor's picker set: while adding only, hidden at one writable vault, and never offered afterwards, because the two are encrypted under different keys. The parent picker is that vault's alone, for the reason the host editor's group picker is — a parent in another vault is a level half the key holders cannot resolve. Dragging a host card onto a group card in another vault is refused with the reason, rather than filing it under an id nobody in its own vault can read. The resolution map stays wider than the list and still spans hidden vaults: a group lends a port, a username and a binding, so a host whose group went unread would silently dial 22 as nobody while the machine is on 2222 as `deploy`. |
 | Per-host status dot, three colours | client-ssh | The amber state would mean "reachable but not connected", and nothing here ever probes a host. | Two states, both real: green when a terminal is open on that host, grey when not. |
 | `· ⤷ bastion-eu` in the host subtitle | client-ssh | **Jump hosts are data-only.** `HostSecret.JumpHostIds` is a `JumpChain` that is stored, encrypted, synced and three-way merged — and nothing reads it at connect time. `SshConnectionRequest` carries one host. | Omitted. The stored chain is preserved untouched by every edit. |
 | `SPLIT ⌘D` and side-by-side panes | client-ssh + ui | The renderer stacks panes and shows one (`terminal.css`: `.pane { position:absolute; inset:0; display:none }`). Tiling needs a real pane geometry and a splitter. | Omitted. Tabs ship instead, over the same one-WebView multiplexing. |
diff --git a/docs/manual-checks.md b/docs/manual-checks.md
index a33fdd8..c5e8827 100644
--- a/docs/manual-checks.md
+++ b/docs/manual-checks.md
@@ -1279,6 +1279,31 @@ rather than a broken role.
 under the people who share it is an administrative act reached without the role for it. The server refuses
 it too — this is the interface not offering what the server would turn down.
 
+### 12.10 A group made in a shared vault arrives as a group, not as a heap · **needs two accounts**
+
+1. As Alice, on HOSTS, press + NEW GROUP, choose the shared vault in the editor's VAULT picker, name it
+   `production`, and give it a default port and username.
+2. Add two hosts to the same shared vault and file them under it.
+3. Make a second group called `production` in the **personal** vault.
+4. Sync, then look at Bob's machine after his own sync.
+
+**Pass on Alice's:** the two cards are told apart by the vault name printed under each — same name, two
+folders — and on the phone the two headings carry the same badge. Opening either shows only its own hosts.
+Dragging one of the shared vault's host cards onto the personal `production` card is **refused with a
+sentence naming both vaults**, and the host stays where it was.
+
+**Pass on Bob's:** the group is a card and a heading on his machine too, with the hosts inside it, and the
+port and username they dial are the ones Alice typed into the group rather than 22 and his own account. He
+can rename it, and the rename comes back to Alice rather than arriving as a second group in his personal
+vault.
+
+**Failure means:** a group that reaches Bob as UNGROUPED hosts is the resolution map having gone narrow
+again — cosmetic on its own, except that the port and the username go with it, so his terminal dials the
+wrong place. A rename of his that turns up as a new group in his own vault is the editor writing to the
+active vault rather than to the row's, which forks the shelf and leaves Alice's untouched. Two identical
+cards with no vault under them means one of them is a folder somebody outside the team can read, and
+nothing on screen says which.
+
 ---
 
 ## Phase 13 — Unlocking the phone with a fingerprint
diff --git a/src/DodoSSH.Client.Android/Views/HostsScreen.axaml b/src/DodoSSH.Client.Android/Views/HostsScreen.axaml
index 821f6f2..55b5dfa 100644
--- a/src/DodoSSH.Client.Android/Views/HostsScreen.axaml
+++ b/src/DodoSSH.Client.Android/Views/HostsScreen.axaml
@@ -125,7 +125,21 @@
         <DataTemplate DataType="vm:SidebarGroupHeader">
           <Grid ColumnDefinitions="Auto,*,Auto,Auto" Margin="8,12,8,5">
             <TextBlock Grid.Column="0" Classes="detail" Text="{Binding Chevron}" VerticalAlignment="Center" />
-            <TextBlock Grid.Column="1" Classes="section" Text="{Binding Label}" Margin="7,0,0,0" />
+
+            <!--
+              The name, and the vault it is in where this session holds more than one. The badge is what
+              makes one heading per group survive a shared vault: two vaults may each hold a "production",
+              and this list has no nesting to tell the two apart with. Drawn as the same outline tag a host
+              row wears, so "which vault" looks the same wherever it is answered.
+            -->
+            <StackPanel Grid.Column="1" Orientation="Horizontal" Spacing="6" Margin="7,0,0,0">
+              <TextBlock Classes="section" Text="{Binding Label}" TextTrimming="CharacterEllipsis" />
+              <Border Classes="tag outline" VerticalAlignment="Center"
+                      IsVisible="{Binding HasVaultBadge}">
+                <TextBlock Text="{Binding VaultBadge}" />
+              </Border>
+            </StackPanel>
+
             <TextBlock Grid.Column="2" Classes="detail" Text="{Binding Count}" FontSize="9"
                        VerticalAlignment="Center" />
 
@@ -367,6 +381,27 @@
 
           <TextBox Classes="field" Text="{Binding GroupEditorLabel}" PlaceholderText="group name" />
 
+          <!--
+            ◆ WHICH VAULT THIS GROUP WILL LIVE IN, on the same terms as the host editor's picker above and
+            for the same reason: it is what makes the group shared, and it cannot be changed afterwards.
+            Above INSIDE because it decides what INSIDE can offer — a parent belongs to one vault, and one
+            from another is a level half the readers cannot resolve.
+          -->
+          <StackPanel Spacing="6" IsVisible="{Binding ShowsGroupEditorVaultChoice}">
+            <TextBlock Classes="label" Text="VAULT" Margin="0,4,0,0" />
+            <ComboBox ItemsSource="{Binding GroupEditorVaultChoices}"
+                      SelectedItem="{Binding GroupEditorSelectedVault}"
+                      HorizontalAlignment="Stretch" MinHeight="44">
+              <ComboBox.ItemTemplate>
+                <DataTemplate x:DataType="vm:VaultChoiceViewModel">
+                  <TextBlock Classes="mono" FontSize="12" Text="{Binding Display}" />
+                </DataTemplate>
+              </ComboBox.ItemTemplate>
+            </ComboBox>
+            <TextBlock Classes="body"
+                       Text="A group in a shared vault is visible to everybody holding that vault's key, and only hosts in the same vault can be filed under it." />
+          </StackPanel>
+
           <TextBlock Classes="label" Text="INSIDE" Margin="0,4,0,0" />
           <ComboBox ItemsSource="{Binding GroupEditorParentChoices}"
                     SelectedItem="{Binding GroupEditorSelectedParent}"
diff --git a/src/DodoSSH.Client.App/Views/HostDrawer.axaml b/src/DodoSSH.Client.App/Views/HostDrawer.axaml
index 24b4813..7bd4956 100644
--- a/src/DodoSSH.Client.App/Views/HostDrawer.axaml
+++ b/src/DodoSSH.Client.App/Views/HostDrawer.axaml
@@ -554,6 +554,34 @@
 
                 <TextBox Text="{Binding GroupEditorLabel}" PlaceholderText="group name" />
 
+                <!--
+                  ◆ WHICH VAULT THIS GROUP WILL LIVE IN, on the same terms as the host editor's picker
+                  above: asked while adding, hidden where there is only one vault to write to, and never
+                  offered for an existing group, because the vaults are encrypted under different keys and
+                  moving an item between them is a delete and a retype.
+
+                  A group in a shared vault is what gives a team an arrangement rather than a heap: the
+                  people holding that vault's key see the folder, and the hosts inside it inherit its port,
+                  its username and its key.
+
+                  The parent picker below follows it, for the reason the host's group picker follows the
+                  host's vault — a parent in another vault would be a level half the readers cannot resolve.
+                  See VaultViewModel.ShowsGroupEditorVaultChoice.
+                -->
+                <StackPanel Spacing="4" IsVisible="{Binding ShowsGroupEditorVaultChoice}">
+                  <ComboBox ItemsSource="{Binding GroupEditorVaultChoices}"
+                            SelectedItem="{Binding GroupEditorSelectedVault}"
+                            HorizontalAlignment="Stretch">
+                    <ComboBox.ItemTemplate>
+                      <DataTemplate x:DataType="vm:VaultChoiceViewModel">
+                        <TextBlock Text="{Binding Display}" FontSize="12" />
+                      </DataTemplate>
+                    </ComboBox.ItemTemplate>
+                  </ComboBox>
+                  <TextBlock Classes="hint" FontSize="11" TextWrapping="Wrap"
+                             Text="A group in a shared vault is visible to everybody holding that vault's key, and only hosts in the same vault can be filed under it." />
+                </StackPanel>
+
                 <ComboBox ItemsSource="{Binding GroupEditorParentChoices}"
                           SelectedItem="{Binding GroupEditorSelectedParent}"
                           HorizontalAlignment="Stretch">
diff --git a/src/DodoSSH.Client.App/Views/HostsScreen.axaml b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
index 77700f9..d70d357 100644
--- a/src/DodoSSH.Client.App/Views/HostsScreen.axaml
+++ b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
@@ -304,6 +304,17 @@
                         </Grid>
                         <TextBlock Text="{Binding Description}" FontSize="11"
                                    Foreground="{StaticResource TextFaint}" />
+                        <!--
+                          Which vault this group is in, on the same rule and in the same place as the host
+                          card's: only where there is more than one vault to be in. It matters more on a
+                          folder than on a machine — two vaults may each hold a "production", and without
+                          this the cards are two identical folders side by side, one of which a colleague
+                          can read. It is also what says a group is shared at all.
+                        -->
+                        <TextBlock Classes="mono" Text="{Binding VaultBadge}" FontSize="10"
+                                   Foreground="{StaticResource TextFaint}"
+                                   TextTrimming="CharacterEllipsis"
+                                   IsVisible="{Binding HasVaultBadge}" />
                       </StackPanel>
                     </Grid>
                   </Border>
diff --git a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
index 1340856..7dc27a6 100644
--- a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
+++ b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
@@ -39,29 +39,70 @@ internal interface ISidebarRow;
 internal sealed record SidebarGroupHeader(Guid? GroupId, string Label, int Count, bool IsExpanded)
     : ISidebarRow
 {
+    /// <summary>
+    /// The vault this heading's group lives in, or empty where there is only one vault to be in.
+    /// </summary>
+    /// <remarks>
+    /// The one thing a heading could not say while the headings were one vault's. Two vaults may each hold
+    /// a group called "production" — they are separate folders under separate keys — and a list with one
+    /// heading per group has nothing else to tell them apart with. Decided by the list rather than the row,
+    /// for the reason <see cref="HostRowViewModel.VaultBadge"/> is.
+    /// </remarks>
+    internal string VaultBadge { get; init; } = string.Empty;
+
+    /// <summary>Whether this heading has a vault to name.</summary>
+    internal bool HasVaultBadge => VaultBadge.Length > 0;
+
     /// <summary>The chevron, as text, because the heading is drawn in the list's own item template.</summary>
     internal string Chevron => IsExpanded ? "▾" : "▸";
 }
 
+/// <summary>One group as it came out of a vault, with the vault it came out of.</summary>
+/// <remarks>
+/// The pair the group reload hands the group rebuild, and the vault half of it is what makes a group a
+/// shared thing rather than a private one: a rename and a delete both have to go back to the vault the group
+/// is in, and the row that offers them is drawn from a list that now spans every readable vault.
+/// </remarks>
+/// <param name="Item">The group, decrypted.</param>
+/// <param name="VaultId">The vault it lives in.</param>
+/// <param name="VaultName">That vault's display name.</param>
+internal sealed record VaultGroupItem(VaultItem<HostGroupSecret> Item, Guid VaultId, string VaultName);
+
 /// <summary>One group, as a row in the group list.</summary>
 /// <remarks>
 /// Thinner than the other row types because a group is thinner: a name, and how many hosts name it. The
 /// count is computed from the host list rather than stored on the group — see <see cref="HostGroupSecret"/>
 /// for why membership lives on the host — so it is passed in rather than read off the item.
 /// </remarks>
-internal sealed class HostGroupRowViewModel(VaultItem<HostGroupSecret> group, int hostCount)
+internal sealed class HostGroupRowViewModel(VaultGroupItem group, int hostCount)
 {
-    internal Guid EntityId => group.EntityId;
+    internal Guid EntityId => group.Item.EntityId;
 
-    internal HostGroupSecret Group => group.Secret;
+    /// <summary>Which vault this group lives in. See <see cref="HostRowViewModel.VaultId"/>.</summary>
+    internal Guid VaultId => group.VaultId;
 
-    internal string Label => group.Secret.Label;
+    /// <summary>The vault's display name.</summary>
+    internal string VaultName => group.VaultName;
+
+    /// <summary>
+    /// The vault name to print on this card, or empty when there is only one vault to be in.
+    /// </summary>
+    /// <inheritdoc cref="HostRowViewModel.VaultBadge" path="/remarks" />
+    internal string VaultBadge { get; init; } = string.Empty;
+
+    /// <summary>Whether this row has a vault to name.</summary>
+    internal bool HasVaultBadge => VaultBadge.Length > 0;
+
+    internal HostGroupSecret Group => group.Item.Secret;
+
+    internal string Label => group.Item.Secret.Label;
 
     internal int HostCount => hostCount;
 
-    internal bool IsReadOnly => group.IsReadOnly;
+    internal bool IsReadOnly => group.Item.IsReadOnly;
 
-    internal string Badge => ItemBadge.For(group.IsBlocked, group.IsReadOnly, group.HasUnsyncedChanges);
+    internal string Badge =>
+        ItemBadge.For(group.Item.IsBlocked, group.Item.IsReadOnly, group.Item.HasUnsyncedChanges);
 
     /// <summary>What the row says under the name.</summary>
     internal string Description => hostCount == 1 ? "1 host" : $"{hostCount} hosts";
@@ -1047,13 +1088,15 @@ internal sealed partial class VaultViewModel(
     private readonly SemaphoreSlim syncGate = new(1, 1);
 
     /// <summary>
-    /// The groups as they came out of the vault, before the host counts are attached.
+    /// The groups as they came out of the vaults, before the host counts are attached.
     /// </summary>
     /// <remarks>
     /// Held between the group reload and the host reload, which are two passes because a group row says how
-    /// many hosts name it and the hosts are read second. See <see cref="RebuildGroups"/>.
+    /// many hosts name it and the hosts are read second. See <see cref="RebuildGroups"/>. Every readable
+    /// vault's, each entry carrying which one it came from — a group is shared by being in a shared vault,
+    /// so the vault has to travel with it as far as the row that renames and deletes it.
     /// </remarks>
-    private IReadOnlyList<VaultItem<HostGroupSecret>> groupItems = [];
+    private IReadOnlyList<VaultGroupItem> groupItems = [];
 
     /// <summary>
     /// The same groups by id, which is the shape the inheritance walk takes.
@@ -1467,11 +1510,43 @@ internal sealed partial class VaultViewModel(
     /// What the group's parent picker offers: "no parent", then every group that may legally be one.
     /// </summary>
     /// <inheritdoc cref="EditorAuthenticationChoices" path="/remarks" />
+    /// <remarks>
+    /// One vault's, and the one this group is going into — see <see cref="BuildGroupParentChoices"/>. A
+    /// parent in another vault would be a group half the people holding this one's key cannot resolve, and
+    /// the tree they see would be missing a level nobody can point at.
+    /// </remarks>
     internal ObservableCollection<GroupChoice> GroupEditorParentChoices { get; } = [];
 
     [ObservableProperty]
     private GroupChoice? groupEditorSelectedParent;
 
+    /// <summary>
+    /// Which vault a group being created will be filed into.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The same picker the host editor has, on the form beside it, and for the same reason: this is the
+    /// decision that makes the thing shared, it cannot be changed afterwards, and the only other control
+    /// that could have answered it is a standing preference on a different screen. A group is where hosts
+    /// are filed and what lends them a port, a username and a key — so putting one in a shared vault is how
+    /// a team gets an arrangement rather than twenty machines in a heap, which is most of what sharing is
+    /// for.
+    /// </para>
+    /// <para>
+    /// Filled from <see cref="TargetVaults"/>, so it offers what every other "file this into" control does:
+    /// vaults this session can both read and write.
+    /// </para>
+    /// </remarks>
+    internal ObservableCollection<VaultChoiceViewModel> GroupEditorVaultChoices { get; } = [];
+
+    [ObservableProperty]
+    private VaultChoiceViewModel? groupEditorSelectedVault;
+
+    /// <summary>Whether the editor should be asking which vault this group goes into.</summary>
+    /// <inheritdoc cref="ShowsEditorVaultChoice" path="/remarks" />
+    internal bool ShowsGroupEditorVaultChoice =>
+        EditingGroupId is null && GroupEditorVaultChoices.Count > 1;
+
     /// <summary>What the group's authentication picker offers, for the hosts beneath it.</summary>
     /// <remarks>
     /// The host picker's list without its first entry. A group cannot default to "ask for a password each
@@ -1486,8 +1561,33 @@ internal sealed partial class VaultViewModel(
 
     /// <summary>The group being renamed, or null when the box would create one.</summary>
     [ObservableProperty]
+    [NotifyPropertyChangedFor(nameof(ShowsGroupEditorVaultChoice))]
     private Guid? editingGroupId;
 
+    /// <summary>
+    /// Which vault the group editor will write to, or null until an editor has been opened.
+    /// </summary>
+    /// <remarks>
+    /// Nullable where <see cref="editingHostVaultId"/> is not, because the group name box is bound whether
+    /// or not anything raised an editor over it — that is what the desktop's group bar was, and typing a
+    /// name into it and pressing ADD is still a way to make a group. <see cref="GroupEditorVaultId"/> is
+    /// what answers for that case, and it answers with the standing preference: a group made without
+    /// choosing a vault is a new item like any other.
+    /// </remarks>
+    private Guid? editingGroupVaultId;
+
+    /// <summary>The vault the group editor writes to, whether or not one was ever chosen for it.</summary>
+    private Guid GroupEditorVaultId => editingGroupVaultId ?? TargetVaultId;
+
+    /// <summary>
+    /// The name of the vault a group being renamed is in, for the drawer's header, or empty.
+    /// </summary>
+    /// <remarks>
+    /// Kept rather than looked up per redraw, and empty wherever there is only one vault to be in — the
+    /// same rule the badges follow, because a header naming the only vault there is says nothing.
+    /// </remarks>
+    private string editingGroupVaultName = string.Empty;
+
     [ObservableProperty]
     private SshKeyRowViewModel? selectedKey;
 
@@ -1839,14 +1939,23 @@ internal sealed partial class VaultViewModel(
     /// The line under it: which keychain this is filed in, or what a group is for.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// The vault's name and not a picker for it, although the design draws one with a chevron. An item
     /// cannot be moved between vaults here — that is a delete and a retype, because the two are encrypted
     /// under different keys — so a control offering the move would be offering something no layer below
-    /// this can do. Where a *new* item goes is chosen on the keychain screen's own picker; see
-    /// <see cref="TargetVaults"/>.
+    /// this can do. Where a *new* item goes is chosen in the editor's own picker.
+    /// </para>
+    /// <para>
+    /// A group being renamed says its vault here for the same reason a host being edited does, and it is
+    /// the only line that says it: the picker is hidden for an existing group, and renaming a colleague's
+    /// shelf without being told whose it is is exactly the edit worth naming. A group being *made* says
+    /// what a group is for instead, because the picker under it is already answering "which vault".
+    /// </para>
     /// </remarks>
     internal string DrawerSubtitle => (IsEditing, IsEditingGroup) switch
     {
+        (_, true) when EditingGroupId is not null && editingGroupVaultName.Length > 0 =>
+            editingGroupVaultName,
         (_, true) => "A heading, and what its hosts inherit",
         (true, _) when editingEntityId is null => SelectedTargetVault?.Name ?? string.Empty,
         _ => SelectedHost?.VaultName ?? string.Empty,
@@ -3007,42 +3116,35 @@ internal sealed partial class VaultViewModel(
     /// <see cref="RebuildGroups"/>, which is where the two meet.
     /// </para>
     /// <para>
-    /// <b>Two reads, and they cover different vaults on purpose.</b> The editable list — the rows the
-    /// sidebar draws headings from and the group editor renames — is the active vault's alone. The
-    /// resolution map is every readable vault's.
+    /// <b>Three shapes of the same read, and every one of them spans every readable vault.</b> The editable
+    /// list is what the cards and the headings are drawn from and what the editor renames; the per-vault
+    /// lists are what a picker offers, because a picker is always asking about one vault; the map is what a
+    /// host's <c>GroupId</c> resolves through.
     /// </para>
     /// <para>
-    /// The list stays narrow for the reasons it always did: a row shown across vaults has to carry which
-    /// vault it lives in, because rename and delete both need it, and two vaults may hold groups with the
-    /// same name, which the one-heading-per-group layout cannot tell apart. Both are worth doing and neither
-    /// is a merge's business. Recorded in <c>docs/design-import-gaps.md</c>.
+    /// <b>The list stopped being the active vault's, which is what makes a group shareable.</b> It was
+    /// narrow because a row shown across vaults has to carry the vault it lives in — a rename and a delete
+    /// both need it — and because two vaults may hold groups with the same name, which a list with one
+    /// heading per group cannot tell apart. Both are now paid for rather than avoided: the row carries the
+    /// vault, and the badge beside the name says which. Until it did, a group a colleague made in a shared
+    /// vault had no card, no heading and no way to be corrected from the machine looking straight at the
+    /// hosts filed under it.
     /// </para>
     /// <para>
-    /// <b>The map could not stay narrow, and that changed with inheritance.</b> While a group was only a
-    /// name, a host in a team's vault whose group this did not read appeared under UNGROUPED and lost
-    /// nothing else — the same thing the sidebar shows for a group that has been deleted. Since a group
-    /// began lending a port, a username and a binding, the same omission silently drops all three: that host
-    /// would dial 22 as nobody, while the machine it names is on 2222 as <c>deploy</c>, and nothing on
-    /// screen would say why. A missing heading is cosmetic; a missing port is a connection to the wrong
-    /// place.
-    /// </para>
-    /// <para>
-    /// Widening the map costs nothing the narrow list was protecting. Group ids are UUIDv7 and unique across
-    /// vaults, so there is no name collision to resolve here and no vault to carry — the map is only ever
-    /// asked "what does this id say", which is exactly the question a host's <c>GroupId</c> poses.
+    /// <b>The map was widened first, and it had to be, which is why it is separate.</b> While a group was
+    /// only a name, a host in a team's vault whose group this did not read appeared under UNGROUPED and lost
+    /// nothing else. Since a group began lending a port, a username and a binding, the same omission
+    /// silently drops all three: that host would dial 22 as nobody, while the machine it names is on 2222 as
+    /// <c>deploy</c>. So the map answers "what does this id say" for every vault, including the ones
+    /// <see cref="IsVaultShown"/> is keeping off the screen — hiding a vault must never change what a host
+    /// dials, and the list is where hiding is applied. See <see cref="RebuildGroups"/>.
     /// </para>
     /// </remarks>
     private async Task<int> ReloadGroupsAsync(CancellationToken cancellationToken)
     {
         var unreadable = 0;
         var resolvable = new Dictionary<Guid, HostGroupSecret>();
-
-        // Emptied before the loop rather than assigned inside it, because the active vault may not be in
-        // the readable set at all — a grant withdrawn mid-session is exactly that — and a loop that only
-        // ever writes on a match would leave the last readable vault's groups on screen as though they were
-        // still this one's.
-        groupItems = [];
-
+        var items = new List<VaultGroupItem>();
         var perVault = new Dictionary<Guid, List<GroupChoice>>();
 
         foreach (var vault in session.ReadableVaults)
@@ -3056,6 +3158,8 @@ internal sealed partial class VaultViewModel(
             foreach (var group in listing.Items)
             {
                 resolvable[group.EntityId] = group.Secret;
+
+                items.Add(new VaultGroupItem(group, vault.VaultId, vault.Name));
             }
 
             perVault[vault.VaultId] =
@@ -3064,14 +3168,19 @@ internal sealed partial class VaultViewModel(
                     .OrderBy(group => group.Secret.Label, StringComparer.CurrentCulture)
                     .Select(group => new GroupChoice(group.EntityId, group.Secret.Label)),
             ];
-
-            if (vault.VaultId == session.ActiveVaultId)
-            {
-                groupItems =
-                    [.. listing.Items.OrderBy(group => group.Secret.Label, StringComparer.CurrentCulture)];
-            }
         }
 
+        // Ordered here rather than in the rebuild, and by the same three keys the host and key lists use:
+        // the vault new items go into first, then by vault name, then by label inside each. Two vaults may
+        // hold a group with the same name and both are drawn; which vault it is in is what tells them apart.
+        groupItems =
+        [
+            .. items
+                .OrderByDescending(entry => entry.VaultId == session.ActiveVaultId)
+                .ThenBy(entry => entry.VaultName, StringComparer.CurrentCulture)
+                .ThenBy(entry => entry.Item.Secret.Label, StringComparer.CurrentCulture),
+        ];
+
         groupsById = resolvable;
         groupsByVault = perVault;
 
@@ -3188,21 +3297,40 @@ internal sealed partial class VaultViewModel(
         groupId is { } id && groupsById.TryGetValue(id, out var group) ? group.Label : string.Empty;
 
     /// <summary>Refills <see cref="Groups"/>, counting the hosts filed under each.</summary>
+    /// <remarks>
+    /// <b>Where a hidden vault's groups are dropped, and the only place they are.</b> The reload above keeps
+    /// every readable vault's, because the map built beside them decides what a host dials; this is the list
+    /// a person looks at, and a card for a vault whose forty hosts have been switched off is a folder that
+    /// cannot be opened onto anything. Dropping them here rather than at the read is what keeps the two
+    /// answers apart. See <see cref="IsVaultShown"/>.
+    /// </remarks>
     private void RebuildGroups()
     {
         var selectedId = SelectedGroup?.EntityId;
         var filteredId = GroupFilter?.EntityId;
 
+        // The same test the host rows are badged by, and it counts the vaults this session can read rather
+        // than the ones with a group in them: a badge that appeared the moment a colleague made their first
+        // group would be a column arriving on its own.
+        var several = session.ReadableVaults.Take(2).Count() > 1;
+
         Groups.Clear();
 
-        foreach (var group in groupItems)
+        foreach (var group in groupItems.Where(entry => IsVaultShown(entry.VaultId)))
         {
             // Counted over the shown vaults rather than over every host, so a card cannot claim members the
             // grid beside it is not drawing. Not counted over VisibleHosts, which would be both too early —
             // that list is rebuilt after this — and wrong: a card must not lose members to the search box.
-            var count = Hosts.Count(row => row.Host.GroupId == group.EntityId && IsVaultShown(row.VaultId));
+            var count = Hosts.Count(
+                row => row.Host.GroupId == group.Item.EntityId && IsVaultShown(row.VaultId));
 
-            Groups.Add(new HostGroupRowViewModel(group, count));
+            Groups.Add(new HostGroupRowViewModel(group, count)
+            {
+                // Only when there is something to tell apart, as on a host card — and it matters more here,
+                // because two vaults may each hold a "production" and the cards would otherwise be two
+                // identical folders side by side.
+                VaultBadge = several ? group.VaultName.ToUpperInvariant() : string.Empty,
+            });
         }
 
         // Re-resolved by id rather than kept: every row object here is replaced on every reload, so an open
@@ -3436,41 +3564,57 @@ internal sealed partial class VaultViewModel(
 
         foreach (var group in Groups)
         {
-            AddSection(group.EntityId, group.Label, host => host.Host.GroupId == group.EntityId);
+            AddSidebarSection(shown, group, host => host.Host.GroupId == group.EntityId);
         }
 
-        AddSection(
+        AddSidebarSection(
+            shown,
             null,
-            "UNGROUPED",
             host => host.Host.GroupId is not { } id || !known.Contains(id),
             onlyWhenOccupied: true);
+    }
 
-        void AddSection(
-            Guid? groupId,
-            string label,
-            Func<HostRowViewModel, bool> belongs,
-            bool onlyWhenOccupied = false)
+    /// <summary>Adds one heading to the sidebar, and the hosts under it when it is not folded away.</summary>
+    /// <param name="shown">The hosts that survived the filters, which every section draws its members from.</param>
+    /// <param name="group">
+    /// The group this heading is for, or null for the ungrouped one. The row rather than its id and label,
+    /// because a heading now says which vault the group is in as well — and null has no vault to name, since
+    /// it is every vault's unfiled hosts at once.
+    /// </param>
+    /// <param name="belongs">Which of the shown hosts fall under it.</param>
+    /// <param name="onlyWhenOccupied">Whether an empty section is left out altogether.</param>
+    private void AddSidebarSection(
+        IReadOnlyList<HostRowViewModel> shown,
+        HostGroupRowViewModel? group,
+        Func<HostRowViewModel, bool> belongs,
+        bool onlyWhenOccupied = false)
+    {
+        var members = shown.Where(belongs).ToArray();
+
+        if (onlyWhenOccupied && members.Length == 0)
         {
-            var members = shown.Where(belongs).ToArray();
+            return;
+        }
 
-            if (onlyWhenOccupied && members.Length == 0)
-            {
-                return;
-            }
+        var expanded = !collapsedGroups.Contains(group?.EntityId ?? Guid.Empty);
 
-            var expanded = !collapsedGroups.Contains(groupId ?? Guid.Empty);
+        SidebarRows.Add(new SidebarGroupHeader(
+            group?.EntityId,
+            group?.Label ?? "UNGROUPED",
+            members.Length,
+            expanded)
+        {
+            VaultBadge = group?.VaultBadge ?? string.Empty,
+        });
 
-            SidebarRows.Add(new SidebarGroupHeader(groupId, label, members.Length, expanded));
+        if (!expanded)
+        {
+            return;
+        }
 
-            if (!expanded)
-            {
-                return;
-            }
-
-            foreach (var member in members)
-            {
-                SidebarRows.Add(member);
-            }
+        foreach (var member in members)
+        {
+            SidebarRows.Add(member);
         }
     }
 
@@ -3516,8 +3660,16 @@ internal sealed partial class VaultViewModel(
     /// host would be a save the user never asked for, and one they would then be unable to cancel.
     /// </para>
     /// <para>
-    /// A group id that is not in this vault is not refused — it is treated as no group at all, which is what
-    /// the list already does with a dangling reference. See <see cref="RebuildSidebarRows"/>.
+    /// A group id that is in no readable vault is not refused — it is treated as no group at all, which is
+    /// what the list already does with a dangling reference. See <see cref="RebuildSidebarRows"/>.
+    /// </para>
+    /// <para>
+    /// <b>A group in a different vault to the host is refused, and said so.</b> The cards are every readable
+    /// vault's since a group became a thing that can be shared, so this gesture can now be aimed across a
+    /// boundary that a save cannot cross: the host would keep an id only the other vault's holders can
+    /// resolve, and everybody in this one would see it filed under nothing. Refusing beats the two
+    /// alternatives — filing it anyway is the quiet wrong, and treating it as "no group" would unfile a host
+    /// somebody was plainly trying to file.
     /// </para>
     /// <para>
     /// No cancellation token, for the reason <see cref="ConnectAsync"/> has none: a command generated over a
@@ -3535,33 +3687,24 @@ internal sealed partial class VaultViewModel(
             return;
         }
 
-        if (row.IsReadOnly)
-        {
-            // The same refusal editing makes, and for the same reason: re-encoding an item a newer client
-            // wrote would drop the fields this build has no concept of.
-            Status = "This host was written by a newer version of DodoSSH. Update before filing it.";
-            return;
-        }
-
-        if (IsEditing)
-        {
-            Status = "Finish or cancel the host you are editing first.";
-            return;
-        }
-
-        Guid? target = request.GroupId is { } wanted && Groups.Any(group => group.EntityId == wanted)
-            ? wanted
+        var card = request.GroupId is { } wanted
+            ? Groups.FirstOrDefault(group => group.EntityId == wanted)
             : null;
 
+        if (RefusesTheDrop(row, card))
+        {
+            return;
+        }
+
+        Guid? target = card?.EntityId;
+
         if (row.Host.GroupId == target)
         {
             return;
         }
 
         var moved = row.Host with { GroupId = target };
-        var name = target is null
-            ? "no group"
-            : Groups.First(group => group.EntityId == target).Label;
+        var name = card?.Label ?? "no group";
 
         await RunAsync(
             $"Filing {row.Label} under {name}…",
@@ -3587,6 +3730,40 @@ internal sealed partial class VaultViewModel(
         await AutoSyncAsync(CancellationToken.None).ConfigureAwait(true);
     }
 
+    /// <summary>Whether a drop has to be turned down, saying why on the status line when it does.</summary>
+    /// <param name="row">The host that was dragged.</param>
+    /// <param name="card">The group card it was dropped on, or null for the drop that unfiles a host.</param>
+    /// <remarks>
+    /// Three refusals rather than one, and separated from the write so that the reason reaches the status
+    /// line before anything is encrypted. Every one of them is a thing the layer below would either refuse
+    /// or, worse, accept: a newer client's item re-encoded loses fields, a write under an open editor is a
+    /// save nobody asked for, and a group in another vault is an id half the readers cannot resolve.
+    /// </remarks>
+    private bool RefusesTheDrop(HostRowViewModel row, HostGroupRowViewModel? card)
+    {
+        if (row.IsReadOnly)
+        {
+            Status = "This host was written by a newer version of DodoSSH. Update before filing it.";
+            return true;
+        }
+
+        if (IsEditing)
+        {
+            Status = "Finish or cancel the host you are editing first.";
+            return true;
+        }
+
+        if (card is not null && card.VaultId != row.VaultId)
+        {
+            Status =
+                $"'{card.Label}' is in {card.VaultName} and '{row.Label}' is in {row.VaultName}. "
+                + "A host can only be filed under a group in its own vault.";
+            return true;
+        }
+
+        return false;
+    }
+
     /// <summary>Whether one host belongs on the grid at the level it is currently showing.</summary>
     /// <remarks>
     /// <para>
@@ -4421,7 +4598,14 @@ internal sealed partial class VaultViewModel(
     /// Duplicate names are allowed. Two groups called "staging" are confusing and they are not
     /// <em>wrong</em> — hosts point at ids, so the two are genuinely separate folders — and refusing the
     /// second one would mean a name somebody chose on another machine could block one they choose here, at
-    /// the next sync, with the rename already saved.
+    /// the next sync, with the rename already saved. Two vaults holding one each is not even confusing: the
+    /// card and the heading both say which vault, and they are as separate as two vaults can make them.
+    /// </para>
+    /// <para>
+    /// Writes to <see cref="editingGroupVaultId"/>, which is the group's own vault on a rename and whatever
+    /// the picker said when the form opened on a create. Never the active vault, which is what it was while
+    /// the list held one vault's groups: a rename typed into a colleague's group would have created a second
+    /// group of that name in the personal vault and left theirs untouched.
     /// </para>
     /// </remarks>
     [RelayCommand]
@@ -4454,13 +4638,13 @@ internal sealed partial class VaultViewModel(
                 if (renaming is { } entityId)
                 {
                     await session.HostGroups
-                        .UpdateAsync(session.ActiveVaultId, entityId, group, cancellationToken)
+                        .UpdateAsync(GroupEditorVaultId, entityId, group, cancellationToken)
                         .ConfigureAwait(true);
                 }
                 else
                 {
                     await session.HostGroups
-                        .CreateAsync(session.ActiveVaultId, group, cancellationToken)
+                        .CreateAsync(GroupEditorVaultId, group, cancellationToken)
                         .ConfigureAwait(true);
                 }
 
@@ -4491,10 +4675,19 @@ internal sealed partial class VaultViewModel(
         }
 
         EditingGroupId = row.EntityId;
+
+        // The group's own vault, and it does not move — the same rule an existing host's follows, and the
+        // same reason: the two are encrypted under different keys, so saving anywhere else would leave a
+        // copy behind rather than move anything. The picker is not drawn for an existing group at all.
+        editingGroupVaultId = row.VaultId;
+        editingGroupVaultName = row.HasVaultBadge ? row.VaultName : string.Empty;
+
         GroupEditorLabel = row.Label;
         GroupEditorDefaultPort = row.Group.DefaultPort;
         GroupEditorDefaultUsername = row.Group.DefaultUsername ?? string.Empty;
 
+        // Before the parent picker, because that picker is one vault's and this is which one.
+        BuildGroupEditorVaultChoices(row.VaultId);
         BuildGroupParentChoices(row.EntityId, row.Group.ParentId);
         BuildGroupAuthenticationChoices(row.Group.DefaultSshKeyId, row.Group.DefaultCredentialId);
 
@@ -4561,6 +4754,14 @@ internal sealed partial class VaultViewModel(
     /// as "and the next group goes inside it" would nest one because somebody had highlighted something,
     /// while the open group is the screen everybody can see they are on.
     /// </para>
+    /// <para>
+    /// <b>And in the open group's vault, which is where this differs from <see cref="NewHost"/> a second
+    /// time.</b> A host opens on the standing "new items go to" preference and takes the open group only if
+    /// that group happens to be in the same vault; a group made inside another group is in that group's
+    /// vault by construction, because a parent in a second vault is a level half the readers cannot resolve.
+    /// Defaulting to the preference instead would answer "+ NEW GROUP inside PLATFORM" with a group
+    /// somewhere else and no parent — a form that silently dropped the one thing the button said.
+    /// </para>
     /// </remarks>
     [RelayCommand]
     private void NewGroup()
@@ -4574,6 +4775,17 @@ internal sealed partial class VaultViewModel(
 
         ClearGroupEditor();
 
+        // The open group's vault, where there is one and this session can write to it. A viewer of a shared
+        // vault gets the standing preference instead — and, with it, no parent, because the group they were
+        // looking inside belongs to a vault they cannot add to.
+        if (GroupFilter is { } open
+            && GroupEditorVaultChoices.FirstOrDefault(choice => choice.VaultId == open.VaultId) is { } vault)
+        {
+            // Assigned rather than written to the field, so the parent picker is refilled for it: the
+            // handler below is what keeps the two in step, here and when the user moves the picker by hand.
+            GroupEditorSelectedVault = vault;
+        }
+
         // Falls back to no parent, which is both what the picker's first entry says and what the phone always
         // gets: it has no group cards and no way to go inside one, so nothing there is ever open.
         GroupEditorSelectedParent =
@@ -4624,21 +4836,31 @@ internal sealed partial class VaultViewModel(
     /// terminates on a cycle. Walking down would need a child index this view model does not keep, and
     /// building one that has to survive a cycle is the same problem twice.
     /// </para>
+    /// <para>
+    /// <b>One vault's candidates, and it is the vault this group is going into rather than the one it is
+    /// on screen beside.</b> The list this picker used to be built from held one vault's groups, so the
+    /// restriction came free; it spans every readable vault now, and offering all of them would let somebody
+    /// file a shared group under a personal one — a parent nobody else can resolve, whose port and username
+    /// would then be lent to their hosts and to nobody else's. Which is the same failure the host editor's
+    /// group picker was fixed for, one level up.
+    /// </para>
     /// </remarks>
     private void BuildGroupParentChoices(Guid groupId, Guid? parentId)
     {
         GroupEditorParentChoices.Clear();
         GroupEditorParentChoices.Add(GroupChoice.None);
 
-        foreach (var candidate in groupItems.Where(item => item.EntityId != groupId))
+        foreach (var candidate in groupItems.Where(
+            entry => entry.VaultId == GroupEditorVaultId && entry.Item.EntityId != groupId))
         {
             var descends = HostInheritance
-                .Chain(candidate.EntityId, groupsById)
+                .Chain(candidate.Item.EntityId, groupsById)
                 .Any(entry => entry.Id == groupId);
 
             if (!descends)
             {
-                GroupEditorParentChoices.Add(new GroupChoice(candidate.EntityId, candidate.Secret.Label));
+                GroupEditorParentChoices.Add(
+                    new GroupChoice(candidate.Item.EntityId, candidate.Item.Secret.Label));
             }
         }
 
@@ -4654,6 +4876,53 @@ internal sealed partial class VaultViewModel(
             ?? GroupChoice.None;
     }
 
+    /// <summary>Refills the group editor's vault picker, landing on the vault the editor will write to.</summary>
+    /// <inheritdoc cref="BuildEditorVaultChoices" path="/remarks" />
+    private void BuildGroupEditorVaultChoices(Guid vaultId)
+    {
+        GroupEditorVaultChoices.Clear();
+
+        foreach (var choice in TargetVaults)
+        {
+            GroupEditorVaultChoices.Add(choice);
+        }
+
+        // Null where the group's vault is one this session cannot write — a shared vault this account is a
+        // viewer of. The picker is not drawn for an existing group anyway, and an empty box is a better
+        // answer than an option that would move the group if it were touched.
+        GroupEditorSelectedVault =
+            GroupEditorVaultChoices.FirstOrDefault(choice => choice.VaultId == vaultId);
+
+        OnPropertyChanged(nameof(ShowsGroupEditorVaultChoice));
+    }
+
+    /// <summary>
+    /// Moves a half-typed group into the vault just chosen for it.
+    /// </summary>
+    /// <remarks>
+    /// Only while creating, for the reason <see cref="OnEditorSelectedVaultChanged"/> gives: a group cannot
+    /// be moved between vaults, so a path that reassigned this on a rename would write a second group into
+    /// the other vault and leave the original standing with the old name.
+    /// </remarks>
+    partial void OnGroupEditorSelectedVaultChanged(VaultChoiceViewModel? value)
+    {
+        if (value is null || EditingGroupId is not null || editingGroupVaultId == value.VaultId)
+        {
+            return;
+        }
+
+        editingGroupVaultId = value.VaultId;
+
+        // The parent picker is the vault's, so it has to be rebuilt — and whatever was chosen in it belongs
+        // to the vault just left, so it is dropped rather than carried: a group is one item in one vault,
+        // and there is nothing in the new one it could mean instead. The defaults below it are not touched,
+        // because a key or a credential may legitimately come from another vault, exactly as a host's may.
+        //
+        // Guid.Empty for the group being edited, because the guard above means there is not one: this only
+        // ever runs while creating, and a group that does not exist yet cannot be its own parent.
+        BuildGroupParentChoices(Guid.Empty, parentId: null);
+    }
+
     /// <summary>Fills the group's binding picker, keeping whatever it currently defaults to selectable.</summary>
     /// <remarks>
     /// <see cref="BuildAuthenticationChoices"/> without the typed-password entry and without the inherited
@@ -4717,6 +4986,14 @@ internal sealed partial class VaultViewModel(
         GroupEditorDefaultPort = null;
         GroupEditorDefaultUsername = string.Empty;
 
+        // Back to the standing preference rather than to whatever the last group edited was in, which is
+        // the same clearing every other field here gets and matters more than any of them: a vault carried
+        // over from a colleague's group is where the next one would silently go.
+        editingGroupVaultId = TargetVaultId;
+        editingGroupVaultName = string.Empty;
+
+        // Before the parent choices, which are that vault's.
+        BuildGroupEditorVaultChoices(GroupEditorVaultId);
         BuildGroupParentChoices(Guid.Empty, parentId: null);
         BuildGroupAuthenticationChoices(boundKeyId: null, boundCredentialId: null);
     }
@@ -4751,7 +5028,13 @@ internal sealed partial class VaultViewModel(
         PendingDeletion = new DeletionRequest(
             DeletionTarget.Group,
             row.EntityId,
-            $"Delete the group '{row.Label}'?",
+
+            // Named with its vault where there is more than one, because two of them may hold a group of
+            // this name and the question is about exactly one of the two. The badge is already the answer
+            // the card gives; this is the same answer at the moment it decides something.
+            row.HasVaultBadge
+                ? $"Delete the group '{row.Label}' in {row.VaultName}?"
+                : $"Delete the group '{row.Label}'?",
             HowFarADeletionGoes("The group"),
             row.HostCount switch
             {
@@ -4774,8 +5057,11 @@ internal sealed partial class VaultViewModel(
             "Deleting…",
             async () =>
             {
+                // The row's own vault, which is why the row is re-found above rather than the id being
+                // enough: a tombstone written to the active vault would delete nothing and leave a
+                // colleague's group standing while this machine reported it gone.
                 await session.HostGroups
-                    .DeleteAsync(session.ActiveVaultId, row.EntityId, cancellationToken)
+                    .DeleteAsync(row.VaultId, row.EntityId, cancellationToken)
                     .ConfigureAwait(true);
 
                 if (EditingGroupId == entityId)
@@ -7515,8 +7801,10 @@ internal sealed partial class VaultViewModel(
     {
         OnPropertyChanged(nameof(GroupSaveLabel));
 
-        // Which of the two things the group editor is doing, which its header says as well as its button.
+        // Which of the two things the group editor is doing, which its header says as well as its button —
+        // and, under it, the vault a group being renamed is in, which only a rename has an answer for.
         OnPropertyChanged(nameof(DrawerTitle));
+        OnPropertyChanged(nameof(DrawerSubtitle));
     }
 
     /// <summary>
diff --git a/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs b/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
index 5a61ec9..facd13a 100644
--- a/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
+++ b/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
@@ -612,12 +612,216 @@ public sealed class VaultSharingTests : IAsyncLifetime
         vault.ShowsEditorVaultChoice.ShouldBeFalse("an item cannot be moved between vaults");
     }
 
+    /// <remarks>
+    /// <para>
+    /// A group is a shelf, and a shared vault is what makes it everybody's shelf. The assertions are the
+    /// three things that were missing while the group list was the active vault's alone: it is listed at
+    /// all, the row says which vault it is in, and a rename typed into it goes back to that vault rather
+    /// than forking a second group of the new name into the personal one.
+    /// </para>
+    /// <para>
+    /// Reloaded between the write and the read, so what is asserted is what came back out of the vault
+    /// rather than the row the save left behind.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task AGroupFiledIntoASharedVault_IsListedThereAndRenamedThere()
+    {
+        await UnlockedAsync();
+
+        var vaults = shell.Vaults;
+
+        await CreateVaultAsync(vaults, "Platform secrets");
+
+        var vault = shell.Vault!;
+        var sharedVaultId = vaults.SelectedVault!.VaultId;
+
+        await vault.LoadAsync(Token);
+
+        vault.NewGroupCommand.Execute(null);
+
+        vault.ShowsGroupEditorVaultChoice.ShouldBeTrue("there are two vaults to choose between");
+
+        vault.GroupEditorSelectedVault =
+            vault.GroupEditorVaultChoices.Single(choice => choice.VaultId == sharedVaultId);
+
+        vault.GroupEditorLabel = "production";
+
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+        await vault.LoadAsync(Token);
+
+        var group = vault.Groups.ShouldHaveSingleItem();
+
+        group.VaultId.ShouldBe(sharedVaultId, vault.Status);
+        group.VaultBadge.ShouldBe("PLATFORM SECRETS", "a card in a session holding two vaults says which");
+
+        vault.SelectedGroup = group;
+        vault.EditGroupCommand.Execute(null);
+
+        vault.ShowsGroupEditorVaultChoice.ShouldBeFalse("an item cannot be moved between vaults");
+
+        vault.DrawerSubtitle.ShouldBe(
+            "Platform secrets", "with no picker drawn, the header is what says whose shelf this is");
+
+        vault.GroupEditorLabel = "live";
+
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+        await vault.LoadAsync(Token);
+
+        var renamed = vault.Groups.ShouldHaveSingleItem();
+
+        renamed.Label.ShouldBe("live");
+        renamed.VaultId.ShouldBe(sharedVaultId, "a rename must not fork a copy into the personal vault");
+    }
+
+    /// <remarks>
+    /// <para>
+    /// The group editor's picker is the group's, exactly as the host editor's is the host's: moving it must
+    /// not move the keychain screen's standing preference, and moving that one must not move a group
+    /// half-typed here.
+    /// </para>
+    /// <para>
+    /// The second half is the one worth the test. The picker is read when the form opens and the vault is
+    /// captured there, so a click on the other screen between typing the name and pressing ADD cannot
+    /// redirect the group somebody was making.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task TheGroupEditorChoosesItsOwnVault_WithoutMovingTheKeychainScreensPicker()
+    {
+        await UnlockedAsync();
+
+        var vaults = shell.Vaults;
+
+        await CreateVaultAsync(vaults, "Platform secrets");
+
+        var vault = shell.Vault!;
+        var sharedVaultId = vaults.SelectedVault!.VaultId;
+
+        await vault.LoadAsync(Token);
+
+        var personal = vault.SelectedTargetVault!;
+
+        vault.NewGroupCommand.Execute(null);
+
+        vault.GroupEditorSelectedVault =
+            vault.GroupEditorVaultChoices.Single(choice => choice.VaultId == sharedVaultId);
+
+        vault.GroupEditorLabel = "production";
+
+        // Moved back after the editor opened, the way a click on the keychain screen would. The group must
+        // still land in the shared vault.
+        vault.SelectedTargetVault = personal;
+
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+
+        vault.Groups.ShouldHaveSingleItem().VaultId.ShouldBe(sharedVaultId, vault.Status);
+
+        vault.SelectedTargetVault.ShouldBe(
+            personal, "the editor's picker is the group's, not the screen's standing preference");
+    }
+
+    /// <remarks>
+    /// A parent belongs to one vault, and a group filed under one in another vault would be a level half
+    /// the people holding the key cannot resolve — their hosts would inherit a port and a username from
+    /// nothing. The same rule the host editor's group picker follows, one level up the same tree.
+    /// </remarks>
+    [Fact]
+    public async Task AGroupsParentPicker_OffersOnlyTheVaultItIsGoingInto()
+    {
+        await UnlockedAsync();
+
+        var vaults = shell.Vaults;
+
+        await CreateVaultAsync(vaults, "Platform secrets");
+
+        var vault = shell.Vault!;
+        var sharedVaultId = vaults.SelectedVault!.VaultId;
+
+        await vault.LoadAsync(Token);
+
+        // In the personal vault, which is where the standing preference points.
+        vault.NewGroupCommand.Execute(null);
+        vault.GroupEditorLabel = "estate";
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+
+        vault.Groups.ShouldHaveSingleItem().Label.ShouldBe("estate", vault.Status);
+
+        vault.NewGroupCommand.Execute(null);
+
+        vault.GroupEditorParentChoices
+            .Any(choice => string.Equals(choice.Label, "estate", StringComparison.Ordinal))
+            .ShouldBeTrue("a group in the personal vault may be filed under a personal group");
+
+        vault.GroupEditorSelectedVault =
+            vault.GroupEditorVaultChoices.Single(choice => choice.VaultId == sharedVaultId);
+
+        vault.GroupEditorParentChoices.ShouldHaveSingleItem()
+            .EntityId.ShouldBeNull("only 'no parent' is left once the group is going somewhere else");
+    }
+
+    /// <remarks>
+    /// <para>
+    /// Dragging a host card onto a group card is the one gesture that files a host without opening its
+    /// editor, and it can now be aimed across a vault boundary, because both grids draw every readable
+    /// vault. The write it would make is the exact thing the host editor's group picker was fixed to
+    /// prevent: an id only the other vault's holders can resolve.
+    /// </para>
+    /// <para>
+    /// Refused and said so, rather than quietly treated as "no group" — the user is plainly filing
+    /// something, and unfiling it instead would be the wrong answer delivered silently.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task AHostDraggedOntoAnotherVaultsGroup_IsRefusedRatherThanFiledUnderIt()
+    {
+        await UnlockedAsync();
+
+        var vaults = shell.Vaults;
+
+        await CreateVaultAsync(vaults, "Platform secrets");
+
+        var vault = shell.Vault!;
+        var sharedVaultId = vaults.SelectedVault!.VaultId;
+
+        await vault.LoadAsync(Token);
+
+        vault.NewGroupCommand.Execute(null);
+
+        vault.GroupEditorSelectedVault =
+            vault.GroupEditorVaultChoices.Single(choice => choice.VaultId == sharedVaultId);
+
+        vault.GroupEditorLabel = "production";
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+
+        // The host stays in the personal vault, which is where a new one goes without being told otherwise.
+        vault.NewHostCommand.Execute(null);
+        vault.EditorLabel = "prod-db";
+        vault.EditorHostname = "db.internal";
+        await vault.SaveHostCommand.ExecuteAsync(null);
+
+        var host = vault.Hosts.Single(row => string.Equals(row.Label, "prod-db", StringComparison.Ordinal));
+        var group = vault.Groups.Single(row => row.VaultId == sharedVaultId);
+
+        host.VaultId.ShouldNotBe(sharedVaultId, "this test is meaningless with both in one vault");
+
+        await vault.MoveHostToGroupCommand.ExecuteAsync(new HostGroupMove(host, group.EntityId));
+
+        vault.Status.ShouldContain("its own vault");
+
+        vault.Hosts
+            .Single(row => string.Equals(row.Label, "prod-db", StringComparison.Ordinal))
+            .Host.GroupId
+            .ShouldBeNull("the host is left where it was rather than filed under an unresolvable group");
+    }
+
     /// <remarks>
     /// The mirror image of the host test above, and it goes the other way on purpose. A host filed into a
-    /// shared vault has to stay there, because hosts are read across every readable vault and so come back.
-    /// Tags are not — the editable list is the active vault's alone, like groups and buckets — so a tag
-    /// filed anywhere else would be created, pushed, reported as added and then invisible, with nothing on
-    /// the keychain screen able to rename or delete it and no active-vault switcher to go and find it with.
+    /// shared vault has to stay there, because hosts are read across every readable vault and so come back;
+    /// so does a group, since its list spans them too. Tags are not — the editable list is the active
+    /// vault's alone, like buckets — so a tag filed anywhere else would be created, pushed, reported as
+    /// added and then invisible, with nothing on the keychain screen able to rename or delete it and no
+    /// active-vault switcher to go and find it with.
     /// </remarks>
     [Fact]
     public async Task ATagIgnoresTheTargetPicker_BecauseItsListOnlyEverShowsOneVault()
diff --git a/tests/DodoSSH.Client.App.Tests/VaultVisibilityTests.cs b/tests/DodoSSH.Client.App.Tests/VaultVisibilityTests.cs
index dff6e75..b837568 100644
--- a/tests/DodoSSH.Client.App.Tests/VaultVisibilityTests.cs
+++ b/tests/DodoSSH.Client.App.Tests/VaultVisibilityTests.cs
@@ -451,8 +451,10 @@ public sealed class VaultVisibilityTests : IAsyncLifetime
     /// <remarks>
     /// It is drawn in the menu and ticked, because a vault missing from a list of vaults reads as something
     /// having gone wrong — and it cannot be switched off, because snippets, logs, buckets and the editable
-    /// group and tag lists are all read from it alone. Switching it off would empty half the application
-    /// rather than filter it, so the refusal says why instead of doing nothing.
+    /// tag list are all read from it alone. Switching it off would empty half the application rather than
+    /// filter it, so the refusal says why instead of doing nothing. The group list is no longer among them:
+    /// it spans every readable vault, and hiding one drops that vault's cards and headings the way it drops
+    /// its hosts.
     /// </remarks>
     [Fact]
     public async Task ThePersonalVaultIsListedAndCannotBeHidden()
@@ -471,6 +473,67 @@ public sealed class VaultVisibilityTests : IAsyncLifetime
         shell.StatusMessage.ShouldContain("always shown");
     }
 
+    /// <remarks>
+    /// <para>
+    /// The two halves of a group, and hiding a vault has to move exactly one of them. The cards and
+    /// headings are a list a person reads, so a hidden vault's group leaves it — a folder that cannot be
+    /// opened onto anything is worse than no folder. What a group also is is a port, a username and a
+    /// binding lent to the hosts beneath it, and that must not move: those hosts are still in
+    /// <c>Hosts</c>, which is what the connect path and the transfers screen read.
+    /// </para>
+    /// <para>
+    /// Asserted through the resolved port rather than through the map directly, because the resolved port
+    /// is what a connection actually dials. A hidden vault whose hosts silently fell back to 22 would be
+    /// this split having collapsed, and nothing on screen would say so.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task HidingAVault_TakesItsGroupCardsButNotWhatItsHostsDial()
+    {
+        await UnlockedAsync();
+
+        await shell.Vaults.LoadAsync(Token);
+
+        var teamVaultId = await CreateVaultAsync("Platform secrets");
+        var vault = shell.Vault!;
+
+        await vault.LoadAsync(Token);
+
+        vault.NewGroupCommand.Execute(null);
+
+        vault.GroupEditorSelectedVault =
+            vault.GroupEditorVaultChoices.Single(choice => choice.VaultId == teamVaultId);
+
+        vault.GroupEditorLabel = "production";
+        vault.GroupEditorDefaultPort = 2222;
+
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+
+        await AddHostAsync(vault, teamVaultId, "prod-db", "db.internal");
+
+        vault.SelectedHost = vault.Hosts.Single(
+            row => string.Equals(row.Label, "prod-db", StringComparison.Ordinal));
+
+        vault.EditSelectedHostCommand.Execute(null);
+
+        vault.EditorSelectedGroup = vault.EditorGroupChoices.Single(
+            choice => string.Equals(choice.Label, "production", StringComparison.Ordinal));
+
+        await vault.SaveHostCommand.ExecuteAsync(null);
+
+        vault.Groups.ShouldHaveSingleItem().VaultId.ShouldBe(teamVaultId, vault.Status);
+
+        await HideAsync(teamVaultId);
+        await vault.LoadAsync(Token);
+
+        vault.Groups.ShouldBeEmpty("a hidden vault's groups are cards onto hosts that are not drawn");
+
+        vault.Hosts
+            .Single(row => string.Equals(row.Label, "prod-db", StringComparison.Ordinal))
+            .Resolved.Port.Value
+            .ShouldBe(2222, "hiding a vault must never change what one of its hosts dials");
+    }
+
     /// <remarks>
     /// The switches are the readable vaults, personal first. A vault whose grant awaits re-wrap has nothing
     /// that would decrypt, so a switch for it would do nothing at all.

From 3f419cb19bbeb0a0a53947736678a3cfe8d97ce2 Mon Sep 17 00:00:00 2001
From: Jaap-Jan de Wit | DodoTech <jaap-jan@dodotech.dev>
Date: Tue, 4 Aug 2026 16:27:20 +0200
Subject: [PATCH 4/7] Let one card be selected at a time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hosts screen draws two grids, one above the other, and each is a ListBox
with a selection of its own. Nothing joined them, so a group card and a host card
could be lit at the same moment — two chosen things, under two pairs of buttons
of which only one would act on whichever the eye had settled on. Both grids mark
a selection the same way, so there was nothing on screen to say which of the two
the next press belonged to.

They share one mark now. Selecting a host clears the group and selecting a group
clears the host, and that second one takes the detail pane down with it: a pane
about one machine cannot go on standing beside a marked group, because nothing
on it would be about what is selected.

Losing a selection deliberately clears nothing. A null arrives whenever either
list is rebuilt — every keystroke in the filter box and every background sync —
and treating that as somebody deselecting would take the mark off a group card
because a search emptied the grid beneath it.

The reload needed the same guard for the same reason. It falls back to the first
host when nothing is selected, which is what puts a target under CONNECT on a
fresh unlock; with one mark between the two grids that fallback would have
unselected a group nobody had touched, once a minute. It is skipped while a group
holds the selection, and it moved into a method of its own because the comment
saying why pushed ReloadHostsAsync past sixty lines.

One consequence needed handling rather than accepting. The phone's only route
into the group editor is a button on a heading in the host list, and it worked by
selecting the group first — which under this rule takes the highlight off the
machine somebody was about to connect to, on a screen that draws no group cards
to say where it has gone. EditGroup takes the group as an argument now: the
heading passes its own row, and the desktop's button beside the cards passes
nothing and still means "the card that is selected".

What the tests hold is the half that lives in the controls. Clearing the property
has to reach the list that is drawing the card, and a selection nulled in the
view model while the card stays highlighted is the exact failure this is about —
so the rule is driven on the real screen, in both directions, against the
ListBoxes' own SelectedItem. The desktop's EDIT is pressed through its binding
for the same kind of reason: a command refusing the button's empty parameter
would be a button that never fires, and nothing about the markup would say so.
---
 .../Views/HostsScreen.axaml                   |  5 +
 .../ViewModels/VaultViewModel.cs              | 82 ++++++++++++++--
 .../HostGridTests.cs                          | 93 +++++++++++++++++++
 .../ShellFlowTests.cs                         | 29 ++++++
 4 files changed, 201 insertions(+), 8 deletions(-)

diff --git a/src/DodoSSH.Client.App/Views/HostsScreen.axaml b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
index 77700f9..40bead6 100644
--- a/src/DodoSSH.Client.App/Views/HostsScreen.axaml
+++ b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
@@ -262,6 +262,11 @@
               opens a shell on a host. One click used to mean both, and a card was then the only place a
               group could be named while also being the control that threw the rest of the grid away.
 
+              ◆ ONE SELECTION, TWO LISTS. Selecting a card here takes the mark off the host grid below, and
+              selecting a host takes it off this one. Two controls each keep their own SelectedItem, so the
+              vault is what joins them — see VaultViewModel.OnSelectedHostChanged. Without it both grids
+              could be lit at once, which is two chosen things under two pairs of buttons.
+
               ◆ THIS IS ONE LEVEL, NOT EVERY GROUP. It binds VisibleGroups: what is inside the group the
               trail above ends with, or the outermost groups when it ends at ALL HOSTS. Folded away entirely
               at a group with nothing inside it, which is an ordinary thing to open — the trail and the two
diff --git a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
index 65373b8..284aac9 100644
--- a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
+++ b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
@@ -1365,6 +1365,14 @@ internal sealed partial class VaultViewModel(
     [ObservableProperty]
     private VaultChoiceViewModel? selectedTargetVault;
 
+    /// <summary>
+    /// The host card that is selected, or null when none is.
+    /// </summary>
+    /// <remarks>
+    /// The application's selection, which everything that acts on a host reads — connecting, editing,
+    /// deleting. <b>It shares one selection with <see cref="SelectedGroup"/>:</b> selecting a host takes the
+    /// mark off a group card and the other way about. See <see cref="OnSelectedHostChanged"/>.
+    /// </remarks>
     [ObservableProperty]
     private HostRowViewModel? selectedHost;
 
@@ -1392,8 +1400,14 @@ internal sealed partial class VaultViewModel(
     /// The group card that is selected, or null when none is.
     /// </summary>
     /// <remarks>
+    /// <para>
     /// One click, and nothing more than a highlight: it is what the group's own EDIT and DELETE act on. What
     /// it deliberately no longer does is narrow the grid — see <see cref="OpenGroup"/>.
+    /// </para>
+    /// <para>
+    /// <b>It shares one selection with <see cref="SelectedHost"/>.</b> Setting either clears the other, so
+    /// exactly one card on the screen is ever lit. See <see cref="OnSelectedHostChanged"/>.
+    /// </para>
     /// </remarks>
     [ObservableProperty]
     private HostGroupRowViewModel? selectedGroup;
@@ -2915,9 +2929,7 @@ internal sealed partial class VaultViewModel(
             Hosts.Add(host);
         }
 
-        // Selection survives a reload. Losing it on every sync would move the terminal's target out from
-        // under the user.
-        SelectedHost = Hosts.FirstOrDefault(row => row.EntityId == selectedId) ?? Hosts.FirstOrDefault();
+        SelectedHost = SelectionAfterReload(selectedId);
 
         // Both, in this order: the group rows carry a host count, and the sidebar's headings are built from
         // the group rows.
@@ -2927,6 +2939,25 @@ internal sealed partial class VaultViewModel(
         return unreadable;
     }
 
+    /// <summary>Which host a freshly filled <see cref="Hosts"/> leaves selected.</summary>
+    /// <param name="selectedId">Whatever was selected before the list was refilled.</param>
+    /// <remarks>
+    /// <para>
+    /// The selection survives a reload, because losing it on every sync would move the terminal's target out
+    /// from under the user. The first host is the fallback rather than nothing, so that a fresh unlock has
+    /// something under CONNECT.
+    /// </para>
+    /// <para>
+    /// That fallback is skipped while a group card holds the selection, and it has to be: the two grids
+    /// share one mark — see <see cref="OnSelectedHostChanged"/> — so a sync that invented a host would
+    /// quietly unselect a group nobody had touched, once a minute. Read before <see cref="RebuildGroups"/>
+    /// runs, which is where <see cref="SelectedGroup"/> is re-resolved against the rows this pass makes.
+    /// </para>
+    /// </remarks>
+    private HostRowViewModel? SelectionAfterReload(Guid? selectedId) =>
+        Hosts.FirstOrDefault(row => row.EntityId == selectedId)
+        ?? (SelectedGroup is null ? Hosts.FirstOrDefault() : null);
+
     /// <returns>How many buckets would not decrypt.</returns>
     /// <remarks>
     /// The selection survives a reload and a reload never invents one, as the key and credential lists do and
@@ -4527,11 +4558,21 @@ internal sealed partial class VaultViewModel(
     }
 
     /// <summary>Loads the group being acted on into the box, so saving renames it.</summary>
-    /// <remarks>The selected card, or the open group when no card is selected. See <see cref="GroupTarget"/>.</remarks>
+    /// <param name="group">
+    /// The group to edit, or null for whatever the screen is aimed at — the selected card, or the open group
+    /// when no card is selected. See <see cref="GroupTarget"/>. The desktop's EDIT button passes nothing and
+    /// means the second; the phone has no card to select and passes the group its heading names.
+    /// </param>
+    /// <remarks>
+    /// Taking it as an argument is what keeps the phone from having to select a group in order to edit one.
+    /// A selection is shared with the host grid now — see <see cref="OnSelectedHostChanged"/> — so a command
+    /// reachable only through <see cref="SelectedGroup"/> would deselect the machine somebody was about to
+    /// connect to, on a screen that draws no group cards at all.
+    /// </remarks>
     [RelayCommand]
-    private void EditGroup()
+    private void EditGroup(HostGroupRowViewModel? group)
     {
-        if (GroupTarget is not { } row)
+        if ((group ?? GroupTarget) is not { } row)
         {
             return;
         }
@@ -4577,6 +4618,12 @@ internal sealed partial class VaultViewModel(
     /// deleted by a sync between the list being drawn and the button being pressed — is ignored rather than
     /// opening an editor on nothing.
     /// </para>
+    /// <para>
+    /// The row is handed to <see cref="EditGroup"/> rather than selected first, which it used to be. A group
+    /// selection now clears the host selection — the two grids share one mark — and the phone draws no group
+    /// cards, so selecting one here would have taken the highlight off the machine in the list with nothing
+    /// on screen to say where it had gone.
+    /// </para>
     /// </remarks>
     [RelayCommand]
     private void EditGroupFromHeading(SidebarGroupHeader? header)
@@ -4587,8 +4634,7 @@ internal sealed partial class VaultViewModel(
             return;
         }
 
-        SelectedGroup = row;
-        EditGroupCommand.Execute(null);
+        EditGroupCommand.Execute(row);
     }
 
     /// <summary>Starts a new group, inside whichever one the screen is showing.</summary>
@@ -7633,6 +7679,16 @@ internal sealed partial class VaultViewModel(
 
     partial void OnSelectedHostChanged(HostRowViewModel? value)
     {
+        // One selection, across both grids. The two lists are drawn one above the other and they are marked
+        // the same way, so two lit cards read as two things chosen — and the buttons underneath them are two
+        // pairs, only one of which would act. Losing a selection leaves the other alone: a null here is what
+        // a filter matching nothing writes, and taking the mark off a group card because a search box
+        // emptied the grid beneath it would be this rule firing at something that is not a choice.
+        if (value is not null)
+        {
+            SelectedGroup = null;
+        }
+
         OnPropertyChanged(nameof(SelectedHostAsksForAPassword));
         OnPropertyChanged(nameof(SelectedHostAuthenticationNote));
         OnPropertyChanged(nameof(ShowsConnectBar));
@@ -7711,8 +7767,18 @@ internal sealed partial class VaultViewModel(
         }
     }
 
+    /// <remarks>
+    /// The other half of the shared selection; see <see cref="OnSelectedHostChanged"/>. Clearing the host
+    /// takes the drawer with it, and that is the point rather than a side effect: a pane about one machine
+    /// cannot go on standing beside a marked group, since nothing on it would be about what is selected.
+    /// </remarks>
     partial void OnSelectedGroupChanged(HostGroupRowViewModel? value)
     {
+        if (value is not null)
+        {
+            SelectedHost = null;
+        }
+
         DisarmIfAimedElsewhere(DeletionTarget.Group, GroupTarget?.EntityId);
 
         OnPropertyChanged(nameof(GroupTarget));
diff --git a/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs b/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
index c193c7a..29a2789 100644
--- a/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
+++ b/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
@@ -259,6 +259,99 @@ public sealed class HostGridTests : IAsyncLifetime
         vault.ShowsGroupActions.ShouldBeFalse("a pair of buttons with no subject is hidden rather than shown");
     }
 
+    /// <summary>
+    /// The two grids share one selection, so at most one card on the screen is ever lit.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// They are two <c>ListBox</c>es, each holding a selection of its own and each drawing it the same way.
+    /// Left to themselves both stay marked — a group above and a host below — under two pairs of buttons of
+    /// which only one acts on whichever card the eye has settled on. The vault is what joins them.
+    /// </para>
+    /// <para>
+    /// Driven on the screen rather than on the view model alone, because half of the rule lives in the
+    /// controls: clearing the property has to reach the list that is drawing the card, and a selection
+    /// nulled in the view model while the card stays highlighted is the exact failure this is about.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task TheHostAndGroupGridsShareOneSelection()
+    {
+        await OnTheGridAsync((screen, _) =>
+        {
+            var host = Row(vault, "stage-web");
+
+            vault.OpenHostPaneCommand.Execute(host);
+            Dispatcher.UIThread.RunJobs();
+
+            vault.SelectedGroup = vault.VisibleGroups.Single();
+            Dispatcher.UIThread.RunJobs();
+
+            vault.SelectedHost.ShouldBeNull("choosing a group is choosing something else");
+            vault.SelectedSidebarRow.ShouldBeNull("and the list that draws the hosts is told");
+            screen.HostGrid.SelectedItem.ShouldBeNull();
+            CardFor(screen, host).IsSelected.ShouldBeFalse("the card the pointer left has to go dark");
+            vault.IsDrawerOpen.ShouldBeFalse("a pane about one host cannot stand beside a marked group");
+
+            vault.SelectedHost = host;
+            Dispatcher.UIThread.RunJobs();
+
+            vault.SelectedGroup.ShouldBeNull("and the same in the other direction");
+            screen.GroupGrid.SelectedItem.ShouldBeNull();
+            GroupCard(screen).IsSelected.ShouldBeFalse();
+            vault.ShowsGroupActions.ShouldBeFalse("so the group's own two buttons have nothing to act on");
+        });
+    }
+
+    /// <remarks>
+    /// EDIT takes the group as an argument now, so that the phone can open the editor on a heading without
+    /// selecting a group and losing the host selection to it — see <c>VaultViewModel.EditGroup</c>. The
+    /// button beside the cards passes nothing and means "the card that is selected", which is the half of
+    /// that change that would fail silently: a command refusing a null parameter is a button that never
+    /// fires, and nothing about the markup would say so.
+    /// </remarks>
+    [Fact]
+    public async Task TheGroupsEditButtonStillActsOnTheSelectedCard()
+    {
+        await OnTheGridAsync((screen, _) =>
+        {
+            vault.SelectedGroup = vault.VisibleGroups.Single();
+            Dispatcher.UIThread.RunJobs();
+
+            var edit = screen.GetVisualDescendants()
+                .OfType<Button>()
+                .Single(button => ReferenceEquals(button.Command, vault.EditGroupCommand));
+
+            edit.IsEffectivelyEnabled.ShouldBeTrue("the command has to accept the button's empty parameter");
+
+            edit.Command.ShouldNotBeNull().Execute(edit.CommandParameter);
+
+            vault.IsEditingGroup.ShouldBeTrue();
+            vault.GroupEditorLabel.ShouldBe("production", "the card that was selected");
+        });
+    }
+
+    /// <remarks>
+    /// The half of the shared selection that is nobody's gesture. A reload falls back to the first host when
+    /// nothing is selected, which is what puts a target under CONNECT on a fresh unlock — and with one mark
+    /// between the two grids that fallback would quietly unselect a group card every time a sync landed.
+    /// </remarks>
+    [Fact]
+    public async Task ASyncDoesNotTakeTheSelectionOffAGroupCard()
+    {
+        var production = vault.VisibleGroups.Single();
+
+        vault.SelectedGroup = production;
+        vault.SelectedHost.ShouldBeNull("the seed's load left a host selected, and the group took the mark");
+
+        await vault.LoadAsync(Token);
+
+        vault.SelectedHost.ShouldBeNull("the reload invented none under the card that was chosen");
+        vault.SelectedGroup
+            .ShouldNotBeNull("re-found by id, since the reload replaces every row object in the list")
+            .EntityId.ShouldBe(production.EntityId);
+    }
+
     /// <remarks>
     /// The gesture, performed. It is wired in the control rather than bound in the markup — which is exactly
     /// the sort of wiring that compiles whether or not it is connected to anything — and the first half of
diff --git a/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs b/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
index 1d6c39c..cf35c3e 100644
--- a/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
+++ b/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
@@ -4333,6 +4333,35 @@ public sealed class ShellFlowTests : IAsyncLifetime
         vault.GroupEditorLabel.ShouldBe("production", "the heading pressed, not the group selected");
     }
 
+    /// <remarks>
+    /// The heading hands its group to the editor rather than selecting it first, and this is why. A group
+    /// selection clears the host selection — the desktop's two grids share one mark — and the phone draws no
+    /// group cards at all, so selecting one here would take the highlight off the machine in the list with
+    /// nothing on screen to say where it had gone, or how to get it back.
+    /// </remarks>
+    [Fact]
+    public async Task AGroupsHeading_LeavesTheChosenMachineChosen()
+    {
+        await UnlockedAsync();
+        var vault = shell.Vault!;
+
+        await AddHostAsync(vault, "prod-db");
+        await AddGroupAsync(vault, "production");
+        await FileAsync(vault, "prod-db", "production");
+
+        var host = vault.Hosts.Single();
+        vault.SelectedHost = host;
+
+        var heading = vault.SidebarRows.OfType<SidebarGroupHeader>().Single(
+            row => string.Equals(row.Label, "production", StringComparison.Ordinal));
+
+        vault.EditGroupFromHeadingCommand.Execute(heading);
+
+        vault.IsEditingGroup.ShouldBeTrue("the editor still opens on the group the heading names");
+        vault.GroupEditorLabel.ShouldBe("production");
+        vault.SelectedHost.ShouldBeSameAs(host, "and the list is still on the machine it was on");
+    }
+
     [Fact]
     public async Task TheUngroupedHeading_OpensNothing()
     {

From 4b706bc3c3201e7fc14d1f3a3206f704c4ddbf79 Mon Sep 17 00:00:00 2001
From: Jaap-Jan de Wit | DodoTech <jaap-jan@dodotech.dev>
Date: Tue, 4 Aug 2026 16:37:41 +0200
Subject: [PATCH 5/7] Say when a vault has moved, so nobody waits out the
 minute
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The delta pull was cheap enough to run on a timer and the client did, once a
minute. That is fine for a machine and wrong for two people: an edit a colleague
makes is up to a minute stale, which is long enough for both of them to make it
and produce a conflict neither needed to have. Shortening the interval is the
obvious answer and the wrong one — it costs a request per client per interval
whether or not anything happened, and it converges on a busier server that is
still late.

So the server now says so. A client holds a WebSocket open at GET /api/v1/events,
subprotocol dodossh.events.v1, and gets a line down it when something it can read
has changed. ADR 0012 has the reasoning; three parts of it are worth repeating
here, because they are what everything else rests on.

**What crosses the socket is a notice, never data.** A frame names a vault and
how far its change log has got. No item, no ciphertext, not even which item it
was. The client's answer is the delta pull it would have run anyway, so there is
still exactly one code path that applies a change to a keychain, and it is not
this one. Pushing the items themselves would save a round trip and fork that path
in two, with the cursor, the merge and the tombstone rules duplicated across both
— ADR 0003 put every mutation through one write path for that reason, and this
keeps every read on one for the same one. It also makes a dropped notice
harmless, which is what lets the fan-out below be as simple as it is.

**Polling stays, and is what guarantees a pass.** The minute timer is unchanged.
A network that eats WebSockets, a server with Events:Enabled off, an older
server, a proxy that will not upgrade, a notice dropped under backpressure —
every one of those leaves a client behaving exactly as it did before this commit.
Nothing is reachable only over the socket and nothing is meant to become so;
VaultViewModel's AutoSyncInterval remark now says that where somebody changing it
will read it.

**The bearer token authorises the upgrade, unlike the relay's ticket.** Not an
inconsistency with ADR 0004: the relay's socket is a byte pipe whose whole
authorization decision — which host, which IPs, which port — is made before it
opens and never revisited, and it is the extraction seam for a process that must
hold no ACL code. 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. A ticket
would carry that answer in a token and be wrong the moment the account's access
changed. The two bounds that arrangement needs are met rather than waved at: the
socket is closed at the token's exp with close code 4401 and the client comes
straight back with a fresh one, and the vault set is re-resolved every few
minutes as well as on the changes known to affect it. Both bound *metadata*,
because a notice contains nothing else and reading a vault still needs a key this
server has never held.

**The fan-out.** VaultEventHub is a singleton holding the sockets this node
accepted; publishing walks them and asks each whether it cares, rather than
keeping a vault-to-subscriber index that every re-subscription would have to move
entries between under a lock publishing also takes. At a few hundred sockets per
node and an event rate bounded by how often people edit keychains, the walk is
not measurable and its races are obvious. Per-connection queues are bounded and
drop the *oldest*: a notice means "pull vault X, which is at least at sequence
N", so the newest subsumes what it displaces and the client's answer is identical
either way — which is what lets the publish path be void, never block, and never
fail.

Announced from the endpoint rather than from SyncService, and that placement is
the point: by then the push has committed and released the per-vault advisory
lock. From inside it would name a sequence no reader can see yet and would hold
the lock that serialises writers across a socket write. Only the highest
*applied* sequence, so a batch of pure conflicts announces nothing, and a
duplicate — already announced when it first landed — announces nothing either.

Grants and membership publish too, and those take the *recipient* rather than the
actor. This is what AdmitNewVaultsAsync has been apologising for since sharing
shipped — "the recipient is handed nothing, there is no push channel" — and the
README with it. A vault shared with somebody now turns up as it is shared. The
comment and the README paragraph both say what is true now, and both keep saying
that the pass is what *discovers* the vault, because a client with no socket has
to arrive at the same place.

**On the client**, VaultEventStream is really a reconnection policy wrapped round
a ClientWebSocket: a dropped socket is the ordinary case here — laptops sleep,
proxies time out, tokens expire, servers are redeployed — so nothing in it treats
a failure as exceptional, and every path ends in "wait, then dial again". A
connection that lived long enough to say hello resets the backoff, so a laptop
that woke, worked, and lost its network an hour later does not inherit a
minute-long wait it has already proved it need not take. A 4401 close skips the
backoff entirely and asks the token provider again, which is the whole reason
that close code is distinct. A server that does not advertise the events feature
gets IdleVaultEventStream, which never delivers — so IVaultServer.Events is never
null and every caller stays on one shape, because the correct behaviour without a
socket is the behaviour with a silent one.

The shell's background loop now selects between the timer and a notice, and both
waits are held across iterations. That is load-bearing rather than tidy:
PeriodicTimer permits one outstanding WaitForNextTickAsync and throws on a
second, and an abandoned channel read stays registered and consumes the next
notice written. Either defect leaves the first notice working and every one after
it silently lost, which is why NoticesKeepWakingTheLoop_NotJustTheFirst pushes
three and not one. Notices are coalesced over a quarter of a second, so one
person's save — a host and its log entry are two items — and a colleague clearing
a folder each cost one pass rather than a dozen.

**The kind is a string, not an enum**, and that is a compatibility decision.
UseStringEnumConverter throws on a value it does not know, so a newer server
sending a kind an older client had never heard of would not add an unreadable
frame — it would break that client's socket outright. A string is ignored
instead. ProblemCodes is the same shape for the same reason.

**Tested on both sides, through the real pipeline.** The endpoint suite opens a
genuine socket against TestServer and proves a push produces a notice, that
another account's push does not reach it, that a ping is answered, and that a
frame this server cannot parse does not end the connection. Two of those assert
on *ordering* rather than on absence within a timeout — the stranger's write goes
first, so a socket that leaked would have announced it before the one the test
waits for — because "nothing arrived in two seconds" is a test that passes on a
slow machine for the wrong reason. And ANoticeCarriesNoCiphertext asserts on the
bytes that crossed the wire rather than on the record's fields, since the latter
would only prove that this type has no payload member, which is a tautology; the
former is what catches a field added later without anybody thinking about
disclosure.

The client suite drives VaultEventStream through an injected connector, because
the one thing a test cannot do to a real network is make it fail on cue — and
failure is the entire subject. The shell suite proves a notice produces a pull
inside ten seconds against a sixty-second timer, so the timer cannot be what
caused it.

**Two limits, stated rather than left to be discovered.** Fan-out is in-process,
so a deployment running more than one API replica only pushes for writes its own
replica handled and the rest arrive on the timer. IVaultEventPublisher is the
seam a PostgreSQL LISTEN/NOTIFY backplane implements and it is deliberately not
implemented: an untested backplane is worse than a documented gap, and multiple
replicas degrade to the behaviour before this commit rather than breaking. And a
client is notified of its own writes; it pushed, so it already pulled, and the
extra pass finds nothing. Suppressing that echo correctly needs a per-device
identity on the socket, and the same user's other machines must still be told.

Manual checks phase 15 covers what no test here can reach, which is the network
in between: a proxy that will not upgrade, one that drops an idle socket without
telling either end, a laptop lid, a token expiring. Every one of those is
invisible inside a test host, and every check there passes only if the change
arrives quickly *and* still arrives with the socket taken away.

ADR 0012 also fixes one thing about the shared terminal session this is the
transport for, so it need not be renegotiated later: session data will be binary
frames on this same socket, because base64 in a JSON envelope is the wrong shape
for the one payload here that is continuous rather than occasional. Two questions
it explicitly does not answer by implication — whether those bytes go through the
API at all, and what end-to-end encryption means when the second party watches a
stream rather than holding a key — are ADR 0001 questions and get their own
decision.

1512 tests pass. DodoSSH.SystemTests was not run — it needs the whole compose
stack — so the end-to-end path is unverified for this change beyond what the
manual checks describe.
---
 README.md                                     |  60 +-
 docs/adr/0003-sync-protocol.md                |   6 +-
 docs/adr/0012-realtime-push.md                | 167 ++++++
 docs/manual-checks.md                         |  80 +++
 .../Features/Events/EventsEndpoint.cs         | 533 +++++++++++++++++
 src/DodoSSH.Api/Features/Events/EventsLog.cs  |  68 +++
 .../Features/Events/VaultEventHub.cs          | 242 ++++++++
 .../Features/Meta/MetaEndpoints.cs            |   9 +
 .../Features/Sync/SyncEndpoints.cs            |  41 ++
 src/DodoSSH.Api/Features/Teams/TeamService.cs |  12 +
 .../Features/Teams/VaultGrantService.cs       |  12 +
 src/DodoSSH.Api/Program.cs                    |  16 +
 src/DodoSSH.Api/Setup/Configuration.cs        |  16 +
 src/DodoSSH.Api/Setup/DodoOptions.cs          |  76 +++
 src/DodoSSH.Api/Setup/EndpointRegistration.cs |   2 +
 src/DodoSSH.Api/appsettings.json              |   5 +
 src/DodoSSH.Client.Api/VaultEventStream.cs    | 552 ++++++++++++++++++
 .../ServerConnection.cs                       |  37 +-
 .../ViewModels/VaultViewModel.cs              | 126 +++-
 src/DodoSSH.Contracts/DodoSshJsonContext.cs   |   5 +
 src/DodoSSH.Contracts/Events.cs               | 134 +++++
 src/DodoSSH.Contracts/ProblemCodes.cs         |  10 +
 src/DodoSSH.Contracts/PublicAPI.Unshipped.txt |  35 ++
 tests/DodoSSH.Api.Tests/ApiFixture.cs         |  30 +
 .../EndpointInventoryTests.cs                 |   6 +
 .../DodoSSH.Api.Tests/EventsEndpointTests.cs  | 461 +++++++++++++++
 .../VaultEventStreamTests.cs                  | 388 ++++++++++++
 .../StubTeamServer.cs                         |  11 +
 .../FakeVaultEventStream.cs                   |  49 ++
 .../FakeVaultServer.cs                        |  25 +
 .../ShellFlowTests.cs                         |  84 +++
 31 files changed, 3285 insertions(+), 13 deletions(-)
 create mode 100644 docs/adr/0012-realtime-push.md
 create mode 100644 src/DodoSSH.Api/Features/Events/EventsEndpoint.cs
 create mode 100644 src/DodoSSH.Api/Features/Events/EventsLog.cs
 create mode 100644 src/DodoSSH.Api/Features/Events/VaultEventHub.cs
 create mode 100644 src/DodoSSH.Client.Api/VaultEventStream.cs
 create mode 100644 src/DodoSSH.Contracts/Events.cs
 create mode 100644 tests/DodoSSH.Api.Tests/EventsEndpointTests.cs
 create mode 100644 tests/DodoSSH.Client.Api.Tests/VaultEventStreamTests.cs
 create mode 100644 tests/DodoSSH.Client.App.Tests/FakeVaultEventStream.cs

diff --git a/README.md b/README.md
index bac43c1..12b9403 100644
--- a/README.md
+++ b/README.md
@@ -350,6 +350,42 @@ Both default to your personal vault and neither moves on its own, because an ite
 visible to everybody holding that vault's key. Choosing a vault in the host editor also decides which groups
 it can be filed under: a group is an item like any other and lives in exactly one vault.
 
+### Changes that do not wait
+
+A client holds a WebSocket open to the server — `GET /api/v1/events`, subprotocol
+`dodossh.events.v1` — and the server sends a line down it whenever something you can read has moved. The
+client's answer is the same delta pull it would have run on its timer, only now rather than in up to a
+minute. Two things you can see: an edit somebody else makes appears while you are looking at the list, and
+a vault shared with you turns up as soon as they share it.
+
+**What is on that socket is a notice, not your data.** A frame says which vault changed and how far its
+change log has got, and nothing else: no item, no ciphertext, not even which item it was. That is the
+decision the rest of this rests on, and it is deliberate twice over — the server has nothing else it
+*could* send, and keeping it that way means there is still exactly one path that applies a change to your
+keychain, so the socket can be wrong or absent without anything being applied incorrectly.
+
+**Polling is still there and is still what guarantees a pass.** The minute timer is unchanged. A network
+that eats WebSockets, a server with `Events:Enabled` off, an older server, a proxy that will not upgrade, a
+notice dropped because your machine was too slow to read it — every one of those leaves you with exactly
+what this product did before the socket existed. Nothing is reachable only this way, and nothing is
+supposed to become so.
+
+Three limits are worth knowing rather than discovering:
+
+- **One node.** Fan-out is in-process, so a deployment running more than one API replica only pushes for
+  writes that its own replica handled. The rest arrive on the timer. The seam for a PostgreSQL
+  `LISTEN`/`NOTIFY` backplane is in place and is not implemented, because an untested backplane would be
+  worse than a documented gap.
+- **The socket does not outlive your access token.** It is closed at the token's expiry and the client
+  reconnects with a fresh one, which is a gap you will not see. That, plus re-reading your vault list every
+  few minutes, is what bounds how long a withdrawn grant can keep producing notices — and what it bounds is
+  *metadata*, because reading a vault needs a key the server has never held.
+- **You are told about your own writes.** Your client pushed, so it has already pulled; the extra pass finds
+  nothing. Notices are coalesced over a quarter of a second so that a burst is one pass rather than a dozen.
+
+The reasoning, including why this is a WebSocket rather than server-sent events and where a shared terminal
+session will attach to it, is in [ADR 0012](docs/adr/0012-realtime-push.md).
+
 ### The Android head
 
 `src/DodoSSH.Client.Android` is a phone-first head that shares every view model with the desktop one — the
@@ -618,6 +654,20 @@ keychain plus a terminal — and the spike that gates all of it.
   directories, an interrupted **upload** starts again rather than resuming (an object cannot be written from
   the middle), and a rename is a copy and a delete rather than one atomic operation. Downloads do resume — a
   ranged GET is part of the protocol, which is the one place a bucket beats SFTP.
+
+  *Realtime done:* a WebSocket the client holds open, over which the server says which vault has moved so a
+  pull happens now rather than within the minute. What crosses it is a notice and never an item, which is
+  what keeps one code path applying changes and makes a dropped socket cost latency and nothing else — the
+  timer is unchanged and is still the guarantee. Two limits are stated rather than implied: fan-out is
+  in-process, so a multi-replica deployment falls back to the timer for writes another replica handled, and
+  a socket is closed at its access token's expiry rather than outliving the credential that authorised it.
+  See [Changes that do not wait](#changes-that-do-not-wait) and
+  [ADR 0012](docs/adr/0012-realtime-push.md).
+
+  It is also the transport a **shared terminal session** will use — one person's shell, watched or driven by
+  somebody else. Nothing of that exists yet, and ADR 0012 records the one decision made early so it need not
+  be renegotiated: session data will be binary frames on this same socket, because base64 in a JSON envelope
+  is the wrong shape for the one payload here that is continuous rather than occasional.
 - **M3 — shared vaults**, sharing, ACLs. *Done.* Membership with roles, a public-key directory, the
   append-only key log served for clients to verify against, shared vaults, and vault key grants
   wrapped by a client and stored opaquely by the server. `VaultAccessService` now resolves team
@@ -641,10 +691,12 @@ keychain plus a terminal — and the spike that gates all of it.
   the rotation is re-sealed as it is pushed, so nothing reaches the server under a superseded key at all.
   See [ADR 0010](docs/adr/0010-vault-key-rotation.md).
 
-  **A vault shared with you arrives on the next synchronisation pass**, within the minute, with no sign-in
-  and nothing to press. There is no push channel, so each pass asks the server which vaults this account can
-  reach before syncing the ones it already knows — which is also how a vault that has been deleted, or one
-  whose grant was withdrawn, stops being listed.
+  **A vault shared with you arrives at once**, with no sign-in and nothing to press. Each pass asks the
+  server which vaults this account can reach before syncing the ones it already knows — which is also how a
+  vault that has been deleted, or one whose grant was withdrawn, stops being listed — and the server now
+  says so the moment somebody wraps a key to you rather than leaving it for the next pass. Without a
+  reachable socket that becomes "within the minute", which is what it always was; see
+  [Changes that do not wait](#changes-that-do-not-wait).
 
   **Ownership transfer is here, and it is one write rather than two.** The member you name becomes owner
   and you become an admin, in a single transaction — because ownership is sole, so promoting first leaves
diff --git a/docs/adr/0003-sync-protocol.md b/docs/adr/0003-sync-protocol.md
index cdfbda5..05443d8 100644
--- a/docs/adr/0003-sync-protocol.md
+++ b/docs/adr/0003-sync-protocol.md
@@ -58,7 +58,11 @@ the Npgsql connection string** — the default; do not enable multiplexing.
 - One place enforces revision, change-log and ACL invariants. That halves both the endpoint
   count and the authorization surface, which is the main reason for the single write path.
 - Delta pull makes frequent polling cheap, so multi-device feels live; push notification over
-  SSE or the existing WebSocket can layer on with polling as the fallback.
+  SSE or the existing WebSocket can layer on with polling as the fallback. **That has since been
+  built — see [ADR 0012](0012-realtime-push.md)** — and nothing in this ADR changed to accommodate
+  it. The socket carries a notice naming a vault and a sequence, whose answer is the delta pull
+  above, so there is still exactly one path that applies a change; and polling is still what
+  guarantees a pass rather than a legacy route kept for old clients.
 - Conflict resolution is entirely client-side. The client retains a `BaseCiphertext` common
   ancestor and performs a field-level three-way merge for structured items, or creates a
   visible conflicted copy for opaque ones. **It must never silently drop a key or a host.**
diff --git a/docs/adr/0012-realtime-push.md b/docs/adr/0012-realtime-push.md
new file mode 100644
index 0000000..2bb7b61
--- /dev/null
+++ b/docs/adr/0012-realtime-push.md
@@ -0,0 +1,167 @@
+# ADR 0012 — A WebSocket that carries notices, not data
+
+- Status: accepted
+- Date: 2026-08-04
+
+## Context
+
+[ADR 0003](0003-sync-protocol.md) built a delta pull that is cheap enough to run on a timer, and
+the client does: one pass a minute. That is the difference between a colleague's change appearing
+"soon" and appearing *now*, and it shows up in three places that are not equally forgivable.
+
+- **A vault shared with you** arrives on the next pass. `AdmitNewVaultsAsync` says so in its own
+  remarks — "the recipient is handed nothing — there is no push channel" — and the README repeats
+  it. Sharing works and looks broken.
+- **Two people editing one keychain** see each other up to a minute late, which is long enough to
+  make the same edit twice and produce a conflict that nobody needed to have.
+- **A revoked grant** keeps serving a client that has not noticed yet, for up to a pass.
+
+Shortening the interval is the obvious answer and the wrong one: it costs a request per client per
+interval whether or not anything happened, and it does not converge on *immediate* — it converges
+on a busier server that is still late.
+
+There is also a second thing coming that this decision has to not preclude. The intended feature is
+a **shared terminal session** — one person's shell, watched or driven by another, TeamViewer-shaped.
+That is bidirectional, continuous, and latency-sensitive in a way a keychain notice is not.
+
+## Decision
+
+### One WebSocket per signed-in client, at `GET /api/v1/events`
+
+Subprotocol `dodossh.events.v1`. The client opens it after unlock and keeps it open; the server
+sends a notice whenever something the client can read has changed.
+
+**Not SSE.** Server-sent events would carry today's notices perfectly well and would be less code.
+It is one-directional, so the shared-session feature would need a second mechanism next to it, and
+then two transports would need reconnection, authorization and lifetime rules that agree. The cost
+of a WebSocket over SSE is small; the cost of two transports is not.
+
+**Not SignalR.** It brings hub protocol negotiation, its own serialisation and transport fallbacks,
+none of which are wanted here: `DodoSSH.Contracts` and its source-generated serialiser are "the
+actual contract between the two sides", and a second wire format alongside it is exactly the silent
+drift `Setup/Json.cs` records having already cost this project once.
+
+### The notice carries no ciphertext
+
+A `vault.changed` frame is `{ kind, vaultId, sequence }` and nothing else. The client's answer to it
+is the pull it would have done on the timer anyway.
+
+This is the load-bearing decision, and it is worth being explicit about why the tempting alternative
+is refused. Pushing the changed items themselves would save a round trip and would fork the code
+path that applies a change into two — one that arrives by pull and one that arrives by socket — with
+the cursor, the merge and the tombstone rules duplicated across both. ADR 0003 put every mutation
+through one write path for exactly that reason; this keeps every *read* on one path for the same
+one. The socket decides *when* to sync. It never decides *what* a vault contains.
+
+It also means a dropped notice is harmless, which is what lets everything below be simple.
+
+### Polling stays, and is the fallback rather than a legacy path
+
+The one-minute pass is unchanged. The socket makes it *early*; it does not make it *necessary*. A
+client on a network that eats WebSockets, an older client, a server that has the feature off, a
+notice dropped under backpressure, a second API replica that did not see the write — every one of
+those degrades to what the product does today, which is correct and up to a minute late.
+
+Nothing may be reachable only by socket. That is a rule about future features, not an observation
+about this one.
+
+### Authorization: the bearer token on the upgrade, not a ticket
+
+[ADR 0004](0004-relay-authorization.md) gives the relay a two-step ticket so its WebSocket carries
+no API authority. This one goes the other way and takes the ordinary bearer JWT on the upgrade
+request, which is an ordinary authenticated HTTP request. The difference is not inconsistency:
+
+- The relay's socket is a **byte pipe to a third party**, and its whole authorization decision —
+  which host, which IPs, which port — is made *before* the socket opens and never revisited. It is
+  also the extraction seam for a standalone relay process that must not hold ACL code.
+- This socket is a **view of the caller's own vault list**, and it has to keep answering "what may
+  this account read" for as long as it is open. It needs the full ACL context, in-process, for the
+  life of the connection. A ticket would carry that context in a token instead, and it would be
+  wrong the moment the account's access changed.
+
+A long-lived connection authorised by a short-lived token is the problem this creates, and it is met
+head-on rather than ignored:
+
+1. **The socket does not outlive the token.** The `exp` claim is read at accept, and the connection
+   is closed with `4401` when it passes. The client reconnects with a fresh token; that is a
+   sub-second gap in a channel whose failure mode is already "poll instead".
+2. **The vault set is re-resolved periodically** (`Events:AccessRefreshInterval`, default five
+   minutes) as well as on the changes that are known to affect it. A withdrawn grant therefore stops
+   producing notices within that window at the latest, and immediately in the ordinary case.
+
+Both are bounds on **metadata** — the fact that a vault changed and roughly when — because that is
+all a notice contains. Nobody's ciphertext is behind this socket, and a client that stayed subscribed
+one interval too long could still not read a byte of it: reading requires a vault key grant, which
+this server has never held.
+
+### The frames
+
+Text frames, JSON, `DodoSshJsonContext`. Server to client:
+
+| kind | meaning |
+| --- | --- |
+| `hello` | accepted; carries the heartbeat interval and the vault count subscribed |
+| `vault.changed` | `vaultId` moved to `sequence`; pull it |
+| `vaults.changed` | the set of vaults this account can reach is different; re-read it |
+| `ping` | heartbeat; the client answers `pong` |
+
+Client to server: `ping`, answered with `pong`. Nothing else — subscription is decided by the server
+from the caller's access, not asked for by the client, because a client that could ask to subscribe
+to a vault id is a client that can probe for vault ids.
+
+`kind` is a **string**, not an enum, and that is deliberate. `UseStringEnumConverter` throws on a
+value it does not know, so a newer server sending a kind an older client has never heard of would
+not add an unknown frame — it would break that client's socket entirely. A string is ignored
+instead, which is what makes the table above extensible. `ProblemCodes` is the same shape for the
+same reason.
+
+### Where the shared session will attach
+
+The socket is the seam, and one thing about it is chosen now so that it need not be renegotiated
+later: **session data will be binary frames on this same connection, not JSON on the table above.**
+Terminal output base64'd into a JSON envelope would cost a third of the bandwidth for nothing, on
+the one payload here that is continuous rather than occasional. Control — offer, accept, resize,
+end — is JSON like everything else.
+
+That is as far as this ADR goes. Two questions are open and are not being answered by implication:
+whether a shared session's bytes go through the API at all or peer-to-peer past it, and what
+end-to-end encryption means when the second party is watching a stream rather than holding a key.
+Both are ADR 0001 questions and deserve their own decision. What this one buys is that they will not
+also be transport questions.
+
+## Consequences
+
+- **Fan-out is in-process, and the deployment is therefore single-node for this feature.** Every
+  connection is held by the node that accepted it; a write handled by another node produces no
+  notice on this one. `IVaultEventPublisher` is the seam a backplane implements — PostgreSQL
+  `LISTEN`/`NOTIFY` needs no infrastructure this stack does not already run — and it is deliberately
+  **not implemented**, because an untested backplane is worse than a documented gap. Multiple API
+  replicas do not break: they degrade to polling, which is the state before this ADR. `/api/v1/meta`
+  advertises `events` so a client knows which it is getting.
+- **Per-connection queues are bounded and drop the oldest.** A notice is "pull vault X, which is at
+  least at sequence N", so the newest is strictly more useful than the one it displaces and the
+  client's answer is identical either way. A slow reader costs itself latency, never the publisher's
+  progress — the publish path never blocks and never awaits a socket.
+- **The publish happens after the transaction commits**, outside the advisory lock ADR 0003 takes.
+  A notice sent from inside it would name a sequence a reader cannot yet see, and would hold the
+  per-vault write lock across a socket write.
+- **A client is notified of its own writes.** It pushed, so it already pulled; the extra pass finds
+  nothing. The client coalesces notices over a short window rather than the server suppressing an
+  echo, because suppressing it correctly needs a per-*device* identity on the socket and the same
+  user's other machines must still be told.
+- **Connections are capped** per user and per node (`Events:MaxConnectionsPerUser`,
+  `Events:MaxConnectionsTotal`). A socket is cheap but not free, and an unbounded count of them is a
+  denial of service that authenticates first.
+- The feature can be turned off entirely (`Events:Enabled`). A deployment behind a proxy that will
+  not upgrade should say so rather than have every client discover it by failing.
+
+### Rejected
+
+- **Shorter polling.** Cheaper to build, converges on a busier server that is still late.
+- **Long polling.** No new transport and genuinely immediate, but it holds a request thread and a
+  connection per client for the same money as a WebSocket while offering none of the bidirectionality
+  the shared session needs.
+- **Pushing the changed items down the socket.** Saves a round trip; forks the apply path in two. See
+  above.
+- **Client-chosen subscriptions.** A `subscribe(vaultId)` frame is an existence oracle for vault ids,
+  which is the disclosure `SyncPullEndpoint` answers 404 rather than 403 to avoid.
diff --git a/docs/manual-checks.md b/docs/manual-checks.md
index a33fdd8..b250f2b 100644
--- a/docs/manual-checks.md
+++ b/docs/manual-checks.md
@@ -1465,3 +1465,83 @@ delivery survives the failure because it is held against the transfer rather tha
 **Failure means:** a retry that succeeds but leaves the destination empty is the delivery having been
 dropped on the failure. An error saying the staged file is missing is the copy having been deleted at the
 stop, which is what `QueueDeliveredDownload` documents it does not do.
+
+## Phase 15 — Changes that arrive without a timer
+
+The socket is covered by tests on both sides: the endpoint suite opens a real one against a real
+`TestServer` and proves a push produces a notice, that another account's push does not, and that a frame
+carries no ciphertext; the shell suite proves a notice wakes the synchronisation loop long before the
+minute. What none of that can reach is **the network in between**, and that is where this feature is most
+likely to fail: a reverse proxy that will not upgrade, one that drops an idle socket without telling either
+end, a corporate middlebox, a phone moving between Wi-Fi and mobile data. Every one of those looks the same
+from inside a test host, which has no proxy and no radio.
+
+The pass condition throughout is *two* things, and the second matters as much as the first: it arrives
+quickly, **and** it still arrives when the socket is gone. A build where the timer had stopped working would
+pass every "it was fast" check here and fail nobody until somebody's proxy changed.
+
+### 15.1 A colleague's edit appears while you are looking at it
+
+Two accounts sharing a vault, both unlocked, both on the Hosts screen. On the first machine, rename a host
+in the shared vault and save.
+
+**Pass:** the second machine's list shows the new name within a second or two, with nothing pressed and no
+screen flicker — the row updates, the selection does not move, and the status line is not repainted with a
+sync report.
+
+**Failure means:** nothing within a minute, then the new name, is the socket not being established at all —
+that is the timer doing its job, which is the correct fallback and not the feature. Check `/api/v1/meta`
+lists `events`, then whether the proxy in front of the API forwards `Upgrade` and `Connection`. A list that
+never updates at all is a synchronisation failure and has nothing to do with this phase.
+
+### 15.2 A vault shared with you turns up as it is shared
+
+The second account signed in and unlocked, sitting on the VAULTS screen. From the first, add them to a team
+and press SHARE KEY.
+
+**Pass:** the vault appears in their list within a second or two of the key being wrapped, and reads as
+waiting for a key until the share, then as readable.
+
+**Failure means:** the vault appearing only on the minute is the `vaults.changed` notice not being published
+or not being followed. Both the membership add and the grant publish one; if the membership arrives promptly
+and the key does not, the grant path is the one to look at.
+
+### 15.3 It still works with the socket taken away
+
+On the second machine, block the WebSocket — the simplest way is a proxy rule rejecting the upgrade, or
+setting `Events:Enabled` to `false` on the server and restarting it.
+
+**Pass:** everything above still happens, within the minute rather than within seconds. Nothing on the
+screen says anything is wrong, because nothing is: no error, no OFFLINE badge, no repeated status message.
+The Sync button still works and still reports.
+
+**Failure means:** an error message, a titlebar claiming to be offline, or a status line that repaints with
+a socket failure is the client treating an absent push channel as a fault. It is not one — the timer is the
+guarantee and the socket is the optimisation, and a user with a strict proxy must never be told their
+keychain is broken.
+
+### 15.4 A laptop that slept comes back on its own
+
+With the second machine idle and connected, close the lid for a few minutes — or disable Wi-Fi for two
+minutes and re-enable it. Then make a change on the first machine.
+
+**Pass:** the change arrives quickly again, without the vault having been locked or the application
+restarted. The reconnection is invisible.
+
+**Failure means:** changes that arrive only on the timer from then on are the stream having given up after
+its socket died — the reconnection loop is what should make that impossible, and a client that reconnects
+once and not twice is the specific defect its tests exist to catch. Changes that never arrive again, timer
+included, are a different and worse bug in the synchronisation loop rather than in the socket.
+
+### 15.5 An expiring token does not end the push
+
+This one needs a short access-token lifetime in the identity provider — the dev realm's Keycloak client can
+be set to a couple of minutes. Leave a machine unlocked and idle for longer than that, then make a change
+elsewhere.
+
+**Pass:** the change still arrives quickly. The socket is closed by the server at the token's expiry and the
+client reconnects with a fresh one, which should be invisible.
+
+**Failure means:** notices stopping at roughly the token's lifetime is the reconnection not asking for a new
+token — it would be dialling with the spent one and being closed again immediately. A burst of reconnection
+attempts in the server log is the same defect seen from the other end.
diff --git a/src/DodoSSH.Api/Features/Events/EventsEndpoint.cs b/src/DodoSSH.Api/Features/Events/EventsEndpoint.cs
new file mode 100644
index 0000000..46246b2
--- /dev/null
+++ b/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;
+        }
+    }
+}
diff --git a/src/DodoSSH.Api/Features/Events/EventsLog.cs b/src/DodoSSH.Api/Features/Events/EventsLog.cs
new file mode 100644
index 0000000..b912b04
--- /dev/null
+++ b/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);
+}
diff --git a/src/DodoSSH.Api/Features/Events/VaultEventHub.cs b/src/DodoSSH.Api/Features/Events/VaultEventHub.cs
new file mode 100644
index 0000000..dbd918e
--- /dev/null
+++ b/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();
+}
diff --git a/src/DodoSSH.Api/Features/Meta/MetaEndpoints.cs b/src/DodoSSH.Api/Features/Meta/MetaEndpoints.cs
index 3533372..e9a3b7a 100644
--- a/src/DodoSSH.Api/Features/Meta/MetaEndpoints.cs
+++ b/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],
diff --git a/src/DodoSSH.Api/Features/Sync/SyncEndpoints.cs b/src/DodoSSH.Api/Features/Sync/SyncEndpoints.cs
index bf402da..0f8d1d8 100644
--- a/src/DodoSSH.Api/Features/Sync/SyncEndpoints.cs
+++ b/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);
+        }
+    }
 }
diff --git a/src/DodoSSH.Api/Features/Teams/TeamService.cs b/src/DodoSSH.Api/Features/Teams/TeamService.cs
index 737d786..ff681f3 100644
--- a/src/DodoSSH.Api/Features/Teams/TeamService.cs
+++ b/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>
diff --git a/src/DodoSSH.Api/Features/Teams/VaultGrantService.cs b/src/DodoSSH.Api/Features/Teams/VaultGrantService.cs
index 277d8b1..3506c01 100644
--- a/src/DodoSSH.Api/Features/Teams/VaultGrantService.cs
+++ b/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;
     }
 
diff --git a/src/DodoSSH.Api/Program.cs b/src/DodoSSH.Api/Program.cs
index abc8cdb..d5702d6 100644
--- a/src/DodoSSH.Api/Program.cs
+++ b/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();
 
diff --git a/src/DodoSSH.Api/Setup/Configuration.cs b/src/DodoSSH.Api/Setup/Configuration.cs
index 6ed888f..1deb6ef 100644
--- a/src/DodoSSH.Api/Setup/Configuration.cs
+++ b/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()
diff --git a/src/DodoSSH.Api/Setup/DodoOptions.cs b/src/DodoSSH.Api/Setup/DodoOptions.cs
index d51d5c1..31ed25d 100644
--- a/src/DodoSSH.Api/Setup/DodoOptions.cs
+++ b/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
 {
diff --git a/src/DodoSSH.Api/Setup/EndpointRegistration.cs b/src/DodoSSH.Api/Setup/EndpointRegistration.cs
index bb9d545..5260569 100644
--- a/src/DodoSSH.Api/Setup/EndpointRegistration.cs
+++ b/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),
diff --git a/src/DodoSSH.Api/appsettings.json b/src/DodoSSH.Api/appsettings.json
index 6df91bf..fde102b 100644
--- a/src/DodoSSH.Api/appsettings.json
+++ b/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,
diff --git a/src/DodoSSH.Client.Api/VaultEventStream.cs b/src/DodoSSH.Client.Api/VaultEventStream.cs
new file mode 100644
index 0000000..df1cb0b
--- /dev/null
+++ b/src/DodoSSH.Client.Api/VaultEventStream.cs
@@ -0,0 +1,552 @@
+using System.Net.WebSockets;
+using System.Security.Cryptography;
+using System.Text.Json;
+using System.Threading.Channels;
+using DodoSSH.Contracts;
+
+namespace DodoSSH.Client.Api;
+
+/// <summary>
+/// A server's "pull now" notices, as everything above the transport needs them.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A queue to read from rather than an event to subscribe to, and that shape is the point: the one
+/// consumer is a synchronisation loop that already waits on a timer, so it can wait on this the same
+/// way and keep every continuation on the thread it started from. An event would deliver on whichever
+/// thread the socket happened to complete on, which in a user interface is the difference between
+/// working and an intermittent rendering fault nobody can reproduce.
+/// </para>
+/// <para>
+/// <b>Reading this is never how a change is applied.</b> A notice says which vault moved and nothing
+/// else; the answer to it is the ordinary delta pull. See ADR 0012.
+/// </para>
+/// </remarks>
+public interface IVaultEventStream : IDisposable
+{
+    /// <summary>Whether a socket is currently established.</summary>
+    /// <remarks>
+    /// For the interface to say whether it is live, not for a caller to branch on before reading:
+    /// synchronising is correct whether or not this is true, because the timer is the fallback.
+    /// </remarks>
+    bool IsConnected { get; }
+
+    /// <summary>
+    /// Waits for the next notice.
+    /// </summary>
+    /// <remarks>
+    /// Connects on the first call and reconnects for as long as it is read, so a caller neither starts
+    /// nor restarts anything. A server that cannot be reached is not an error here — it is a wait that
+    /// has not finished — because the caller's alternative is the timer it is already running.
+    /// </remarks>
+    ValueTask<VaultEvent> ReadAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Takes a notice if one is already waiting, without blocking.
+    /// </summary>
+    /// <returns>Whether there was one.</returns>
+    /// <remarks>
+    /// How a caller coalesces a burst. Five people saving at once produces five notices whose answer
+    /// is a single synchronisation pass, so the loop reads one, waits a moment, and swallows the rest
+    /// rather than running the same pull five times.
+    /// </remarks>
+    bool TryRead(out VaultEvent notice);
+}
+
+/// <summary>
+/// A stream that never delivers anything.
+/// </summary>
+/// <remarks>
+/// For a server that does not advertise the <c>events</c> feature, and for tests. Deliberately waits
+/// for ever rather than completing: a caller selecting between this and a timer must fall through to
+/// the timer, and a read that returned immediately would spin that loop as fast as the machine allows.
+/// </remarks>
+public sealed class IdleVaultEventStream : IVaultEventStream
+{
+    /// <summary>The one instance. It holds nothing.</summary>
+    public static IdleVaultEventStream Instance { get; } = new();
+
+    /// <inheritdoc />
+    public bool IsConnected => false;
+
+    /// <inheritdoc />
+    public async ValueTask<VaultEvent> ReadAsync(CancellationToken cancellationToken)
+    {
+        await Task.Delay(System.Threading.Timeout.Infinite, cancellationToken).ConfigureAwait(false);
+
+        // Unreachable: the delay above only ever ends by throwing.
+        return new VaultEvent(VaultEventKinds.Ping);
+    }
+
+    /// <inheritdoc />
+    public bool TryRead(out VaultEvent notice)
+    {
+        notice = new VaultEvent(VaultEventKinds.Ping);
+        return false;
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        // Nothing is held.
+    }
+}
+
+/// <summary>Tuning for <see cref="VaultEventStream"/>.</summary>
+/// <remarks>
+/// Every value here bounds a reconnection rather than a feature. With the socket permanently
+/// unavailable the client synchronises on its timer, so the cost of getting these wrong is latency,
+/// never correctness.
+/// </remarks>
+public sealed record VaultEventStreamOptions
+{
+    /// <summary>The defaults.</summary>
+    public static VaultEventStreamOptions Default { get; } = new();
+
+    /// <summary>How long to wait before the first reconnection attempt.</summary>
+    public TimeSpan InitialBackoff { get; init; } = TimeSpan.FromSeconds(1);
+
+    /// <summary>The longest the backoff may grow to.</summary>
+    /// <remarks>
+    /// A minute, which is the polling interval: past that point reconnecting sooner buys nothing,
+    /// because the timer has already done the work the socket would have prompted.
+    /// </remarks>
+    public TimeSpan MaxBackoff { get; init; } = TimeSpan.FromMinutes(1);
+
+    /// <summary>
+    /// How long a socket may be silent before it is presumed dead.
+    /// </summary>
+    /// <remarks>
+    /// The server pings on an interval it states in its <c>hello</c>, so silence past a multiple of
+    /// that means the connection is gone rather than idle — which is otherwise indistinguishable, and
+    /// is exactly what a reverse proxy that quietly drops idle sockets produces. Used only until a
+    /// <c>hello</c> arrives; after that the server's own figure is trusted.
+    /// </remarks>
+    public TimeSpan InitialSilenceTimeout { get; init; } = TimeSpan.FromSeconds(90);
+
+    /// <summary>How many notices may be waiting before the oldest are dropped.</summary>
+    /// <remarks>
+    /// Small on purpose. A notice means "pull that vault", so a newer one subsumes the one it
+    /// displaces; a backlog would only make the loop pull repeatedly for work it has already done.
+    /// </remarks>
+    public int QueueDepth { get; init; } = 32;
+}
+
+/// <summary>
+/// Holds a socket to one server open, and hands over what it says.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The whole class is a reconnection policy. A dropped socket is the ordinary case — laptops sleep,
+/// proxies time out, tokens expire, servers are redeployed — so nothing here treats a failure as
+/// exceptional: it backs off and dials again, for as long as somebody is reading.
+/// </para>
+/// <para>
+/// It is safe to have no server at all. Every failure path ends in "wait, then try again", and the
+/// caller's synchronisation timer runs regardless, which is what makes it correct for this class to
+/// stay silent about problems rather than surface them.
+/// </para>
+/// </remarks>
+public sealed class VaultEventStream : IVaultEventStream, IAsyncDisposable
+{
+    private readonly Uri endpoint;
+    private readonly IAccessTokenProvider tokens;
+    private readonly TimeProvider clock;
+    private readonly VaultEventStreamOptions options;
+    private readonly Func<Uri, string, CancellationToken, Task<WebSocket>> connect;
+    private readonly Channel<VaultEvent> notices;
+    private readonly CancellationTokenSource closing = new();
+    private readonly Lock starting = new();
+
+    private Task? pump;
+    private bool disposed;
+
+    /// <summary>Creates a stream against one server.</summary>
+    /// <param name="serverUrl">The server's base URL, as an ordinary <c>http</c> or <c>https</c> address.</param>
+    /// <param name="tokens">Supplies a bearer token, refreshing it when it is due.</param>
+    /// <param name="clock">Time source, for the backoff and the silence timeout.</param>
+    /// <param name="options">Tuning, or null for the defaults.</param>
+    public VaultEventStream(
+        Uri serverUrl,
+        IAccessTokenProvider tokens,
+        TimeProvider clock,
+        VaultEventStreamOptions? options = null)
+        : this(serverUrl, tokens, clock, DialAsync, options)
+    {
+    }
+
+    /// <remarks>
+    /// The connector is injected so the suite can drive this against a test host's in-memory socket.
+    /// Reconnection is the entire behaviour of this class, and testing it against a real network would
+    /// mean testing it against the one thing that cannot be made to fail on demand.
+    /// </remarks>
+    internal VaultEventStream(
+        Uri serverUrl,
+        IAccessTokenProvider tokens,
+        TimeProvider clock,
+        Func<Uri, string, CancellationToken, Task<WebSocket>> connect,
+        VaultEventStreamOptions? options = null)
+    {
+        ArgumentNullException.ThrowIfNull(serverUrl);
+        ArgumentNullException.ThrowIfNull(tokens);
+        ArgumentNullException.ThrowIfNull(clock);
+        ArgumentNullException.ThrowIfNull(connect);
+
+        endpoint = EventsUrl(serverUrl);
+        this.tokens = tokens;
+        this.clock = clock;
+        this.connect = connect;
+        this.options = options ?? VaultEventStreamOptions.Default;
+
+        notices = Channel.CreateBounded<VaultEvent>(new BoundedChannelOptions(this.options.QueueDepth)
+        {
+            FullMode = BoundedChannelFullMode.DropOldest,
+            SingleReader = true,
+            SingleWriter = true,
+        });
+    }
+
+    /// <inheritdoc />
+    public bool IsConnected { get; private set; }
+
+    /// <inheritdoc />
+    public ValueTask<VaultEvent> ReadAsync(CancellationToken cancellationToken)
+    {
+        ObjectDisposedException.ThrowIf(disposed, this);
+
+        Start();
+
+        return notices.Reader.ReadAsync(cancellationToken);
+    }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// Does not start the connection, unlike <see cref="ReadAsync"/>: a caller draining a burst has
+    /// already read one notice, and "is there another right now" is not a reason to dial a server.
+    /// </remarks>
+    public bool TryRead(out VaultEvent notice) => notices.Reader.TryRead(out notice!);
+
+    /// <summary>
+    /// Ends the connection, without waiting for it to unwind.
+    /// </summary>
+    /// <remarks>
+    /// What a shell calls when a connection is dropped, from a synchronous path that must not block —
+    /// <c>IVaultServer</c> is <see cref="IDisposable"/>, and blocking on a socket teardown from the
+    /// user-interface thread is exactly the sync-over-async this repository bans. Cancelling is enough:
+    /// every loop reads the token, and the pump has nothing to flush.
+    /// </remarks>
+    public void Dispose()
+    {
+        if (disposed)
+        {
+            return;
+        }
+
+        disposed = true;
+        closing.Cancel();
+
+        // The source is deliberately left undisposed. The pump may still be inside a linked token
+        // source derived from this one, and disposing a parent out from under a live child is how a
+        // clean shutdown becomes an ObjectDisposedException on a background thread. It holds no timer
+        // and no handle once cancelled; DisposeAsync is the path that cleans it up properly.
+    }
+
+    /// <summary>Ends the connection and waits for it to unwind.</summary>
+    /// <remarks>The deterministic form, for a caller that can await one — tests, mostly.</remarks>
+    public async ValueTask DisposeAsync()
+    {
+        if (disposed)
+        {
+            return;
+        }
+
+        disposed = true;
+
+        await closing.CancelAsync().ConfigureAwait(false);
+
+        if (pump is not null)
+        {
+            try
+            {
+                await pump.ConfigureAwait(false);
+            }
+            catch (OperationCanceledException)
+            {
+                // The point of the cancel above.
+            }
+        }
+
+        closing.Dispose();
+    }
+
+    /// <summary>
+    /// Turns a server's base URL into its event socket's.
+    /// </summary>
+    /// <remarks>
+    /// The path is replaced rather than appended, matching every other call in this client: request
+    /// paths here are absolute — <c>/api/v1/…</c> — so a deployment behind a path prefix is already
+    /// unsupported, and pretending otherwise in this one place would be a difference nobody could act
+    /// on.
+    /// </remarks>
+    private static Uri EventsUrl(Uri serverUrl) =>
+        new UriBuilder(serverUrl)
+        {
+            Scheme = string.Equals(serverUrl.Scheme, Uri.UriSchemeHttps, StringComparison.OrdinalIgnoreCase)
+                ? "wss"
+                : "ws",
+            Path = VaultEvents.Path,
+            Query = string.Empty,
+            Fragment = string.Empty,
+        }.Uri;
+
+    private static async Task<WebSocket> DialAsync(Uri url, string token, CancellationToken cancellationToken)
+    {
+        var socket = new ClientWebSocket();
+
+        try
+        {
+            socket.Options.AddSubProtocol(VaultEvents.SubProtocol);
+
+            // A header rather than the Sec-WebSocket-Protocol smuggling ADR 0004 needs for the relay:
+            // this client is a native application and can set one, and the token here is the ordinary
+            // bearer credential rather than a ticket.
+            socket.Options.SetRequestHeader("Authorization", $"Bearer {token}");
+
+            await socket.ConnectAsync(url, cancellationToken).ConfigureAwait(false);
+
+            return socket;
+        }
+        catch
+        {
+            socket.Dispose();
+            throw;
+        }
+    }
+
+    private void Start()
+    {
+        if (pump is not null)
+        {
+            return;
+        }
+
+        lock (starting)
+        {
+            pump ??= Task.Run(() => RunAsync(closing.Token), closing.Token);
+        }
+    }
+
+    /// <summary>Connects, reads until it cannot, waits, and does it again.</summary>
+    private async Task RunAsync(CancellationToken cancellationToken)
+    {
+        var backoff = options.InitialBackoff;
+
+        while (!cancellationToken.IsCancellationRequested)
+        {
+            var outcome = await AttemptAsync(cancellationToken).ConfigureAwait(false);
+
+            // A socket that lived long enough to say hello proves the server is there and willing, so
+            // the next failure starts from the bottom again rather than inheriting the backoff that
+            // got us here. Without this a laptop that woke, connected, and then lost its network an
+            // hour later would wait a full minute before trying, having already proved it need not.
+            if (outcome == Outcome.Established)
+            {
+                backoff = options.InitialBackoff;
+            }
+
+            // The server said this token is spent, which the token provider can fix without waiting.
+            // Reconnecting at once is the whole reason that close code is distinct.
+            var wait = outcome == Outcome.TokenExpired ? TimeSpan.Zero : Jitter(backoff);
+
+            if (wait > TimeSpan.Zero)
+            {
+                try
+                {
+                    await Task.Delay(wait, clock, cancellationToken).ConfigureAwait(false);
+                }
+                catch (OperationCanceledException)
+                {
+                    return;
+                }
+
+                backoff = backoff < options.MaxBackoff
+                    ? Shorter(backoff * 2, options.MaxBackoff)
+                    : options.MaxBackoff;
+            }
+        }
+    }
+
+    /// <summary>One connection, from dial to close.</summary>
+    private async Task<Outcome> AttemptAsync(CancellationToken cancellationToken)
+    {
+        WebSocket? socket = null;
+
+        try
+        {
+            var token = await tokens.GetAccessTokenAsync(cancellationToken).ConfigureAwait(false);
+
+            socket = await connect(endpoint, token, cancellationToken).ConfigureAwait(false);
+
+            IsConnected = true;
+
+            return await PumpAsync(socket, cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException)
+        {
+            return Outcome.Cancelled;
+        }
+        catch (Exception exception) when (exception is not OutOfMemoryException)
+        {
+            // Every failure this can meet — no network, a refused upgrade, a server that has not been
+            // deployed with this feature, a token that cannot be refreshed — has the same remedy, and
+            // none of them is worth telling a user about. The synchronisation timer is still running.
+            return Outcome.Failed;
+        }
+        finally
+        {
+            IsConnected = false;
+            socket?.Dispose();
+        }
+    }
+
+    /// <summary>Reads frames until the socket ends or goes quiet.</summary>
+    private async Task<Outcome> PumpAsync(WebSocket socket, CancellationToken cancellationToken)
+    {
+        var buffer = new byte[8 * 1024];
+        var silence = options.InitialSilenceTimeout;
+        var established = false;
+
+        while (socket.State == WebSocketState.Open && !cancellationToken.IsCancellationRequested)
+        {
+            // Rebuilt per frame rather than reset, because a linked source cannot be un-cancelled and
+            // the deadline is what detects a socket that has silently gone away.
+            using var deadline = new CancellationTokenSource(silence, clock);
+            using var quiet = CancellationTokenSource.CreateLinkedTokenSource(
+                cancellationToken, deadline.Token);
+
+            WebSocketReceiveResult received;
+
+            try
+            {
+                received = await socket.ReceiveAsync(buffer, quiet.Token).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
+            {
+                // Silent for longer than the server said it would be. The socket is gone in a way that
+                // only reconnecting can discover, which is what a proxy dropping an idle connection
+                // looks like from this end.
+                return Ended(established);
+            }
+
+            if (received.MessageType == WebSocketMessageType.Close)
+            {
+                return (int?)received.CloseStatus == VaultEvents.TokenExpiredCloseCode
+                    ? Outcome.TokenExpired
+                    : Ended(established);
+            }
+
+            // Binary is reserved by ADR 0012 for shared-session data, and text that arrived in pieces
+            // is longer than anything this protocol defines. Skipped rather than fatal, so a newer
+            // server does not cost this client its push for the whole session.
+            if (received.MessageType != WebSocketMessageType.Text || !received.EndOfMessage)
+            {
+                continue;
+            }
+
+            if (Parse(buffer.AsSpan(0, received.Count)) is not { } frame)
+            {
+                continue;
+            }
+
+            established = true;
+            silence = await AbsorbAsync(socket, frame, silence, cancellationToken).ConfigureAwait(false);
+        }
+
+        return Ended(established);
+    }
+
+    /// <summary>Deals with one frame, and says how long the socket may now stay quiet.</summary>
+    private async Task<TimeSpan> AbsorbAsync(
+        WebSocket socket,
+        VaultEvent frame,
+        TimeSpan silence,
+        CancellationToken cancellationToken)
+    {
+        if (frame.HeartbeatSeconds is > 0 and var seconds)
+        {
+            // Three missed heartbeats. Two is within one paused thread of a false positive, and a
+            // false positive here costs a reconnection rather than anything a user sees.
+            silence = TimeSpan.FromSeconds(seconds * 3);
+        }
+
+        if (string.Equals(frame.Kind, VaultEventKinds.Ping, StringComparison.Ordinal))
+        {
+            await socket.SendAsync(
+                    JsonSerializer.SerializeToUtf8Bytes(
+                        new VaultEvent(VaultEventKinds.Pong), DodoSshJsonContext.Default.VaultEvent),
+                    WebSocketMessageType.Text,
+                    endOfMessage: true,
+                    cancellationToken)
+                .ConfigureAwait(false);
+
+            return silence;
+        }
+
+        // Everything else, including a kind this build has never heard of, goes to the reader — which
+        // is what makes the frame table extensible. An unrecognised kind is one the caller ignores;
+        // refusing it here would be this class deciding what a newer server may say.
+        notices.Writer.TryWrite(frame);
+
+        return silence;
+    }
+
+    private static Outcome Ended(bool established) =>
+        established ? Outcome.Established : Outcome.Failed;
+
+    private static VaultEvent? Parse(ReadOnlySpan<byte> utf8)
+    {
+        try
+        {
+            return JsonSerializer.Deserialize(utf8, DodoSshJsonContext.Default.VaultEvent);
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+
+    /// <summary>
+    /// Spreads reconnections out, so a server that restarts is not met by every client at once.
+    /// </summary>
+    /// <remarks>
+    /// <c>RandomNumberGenerator</c> because <c>System.Random</c> is banned repo-wide. Nothing here is
+    /// security-relevant — the ban exists so that nothing key-, token- or nonce-adjacent can reach for
+    /// the weak one by habit, and paying a few microseconds to keep that rule absolute is the cheaper
+    /// side of the trade.
+    /// </remarks>
+    private static TimeSpan Jitter(TimeSpan delay)
+    {
+        var milliseconds = (int)Math.Clamp(delay.TotalMilliseconds, 1, int.MaxValue / 2);
+
+        return TimeSpan.FromMilliseconds(
+            milliseconds + RandomNumberGenerator.GetInt32(0, Math.Max(1, milliseconds / 2)));
+    }
+
+    private static TimeSpan Shorter(TimeSpan left, TimeSpan right) => left < right ? left : right;
+
+    /// <summary>How one connection attempt ended.</summary>
+    private enum Outcome
+    {
+        /// <summary>Never got as far as a frame. Back off.</summary>
+        Failed,
+
+        /// <summary>Ran, and then ended. Back off, but from the bottom.</summary>
+        Established,
+
+        /// <summary>The server closed it because the token expired. Reconnect at once with a new one.</summary>
+        TokenExpired,
+
+        /// <summary>The stream is being disposed.</summary>
+        Cancelled,
+    }
+}
diff --git a/src/DodoSSH.Client.Session/ServerConnection.cs b/src/DodoSSH.Client.Session/ServerConnection.cs
index 9b7370b..d89890a 100644
--- a/src/DodoSSH.Client.Session/ServerConnection.cs
+++ b/src/DodoSSH.Client.Session/ServerConnection.cs
@@ -150,6 +150,17 @@ public interface IVaultServer : IDisposable
     /// <summary>Vault key grants: who can open a vault, and who let them.</summary>
     IVaultGrantApi Grants { get; }
 
+    /// <summary>
+    /// Notices that something changed, so a synchronisation need not wait for the timer.
+    /// </summary>
+    /// <remarks>
+    /// Always present, never null: a server that does not offer the feature — or a test standing in
+    /// for one — supplies <see cref="IdleVaultEventStream"/>, which simply never delivers. That keeps
+    /// every caller on one shape, because the correct behaviour without a socket is the behaviour
+    /// with a silent one: synchronise on the timer. See ADR 0012.
+    /// </remarks>
+    IVaultEventStream Events { get; }
+
     /// <summary>Obtains the identity provider's signature over a key statement.</summary>
     IKeyBindingAuthorizer KeyBinding { get; }
 
@@ -197,7 +208,8 @@ public sealed class ServerConnection : IVaultServer
         MetaResponse meta,
         OidcClient oidc,
         RefreshingAccessTokenProvider tokens,
-        DodoSshApiClient api)
+        DodoSshApiClient api,
+        TimeProvider clock)
     {
         ServerUrl = serverUrl;
         this.http = http;
@@ -206,6 +218,14 @@ public sealed class ServerConnection : IVaultServer
         Oidc = oidc;
         this.tokens = tokens;
         Api = api;
+
+        // Decided from what this server said it supports rather than attempted and allowed to fail,
+        // which is the same capability negotiation SyncOptions below does — see ADR 0002. A client
+        // that dialled anyway would reconnect against a 404 for the whole session, and would look
+        // from the outside exactly like one whose network was eating WebSockets.
+        Events = meta.Features.Contains(VaultEvents.Feature, StringComparer.Ordinal)
+            ? new VaultEventStream(serverUrl, tokens, clock)
+            : IdleVaultEventStream.Instance;
     }
 
     /// <summary>The server this is connected to.</summary>
@@ -238,6 +258,9 @@ public sealed class ServerConnection : IVaultServer
     /// <inheritdoc />
     public IVaultGrantApi Grants => Api;
 
+    /// <inheritdoc />
+    public IVaultEventStream Events { get; }
+
     /// <inheritdoc />
     public IKeyBindingAuthorizer KeyBinding => Oidc;
 
@@ -311,7 +334,8 @@ public sealed class ServerConnection : IVaultServer
                 meta,
                 oidc,
                 refreshing,
-                new DodoSshApiClient(transport, refreshing));
+                new DodoSshApiClient(transport, refreshing),
+                clock);
         }
         catch
         {
@@ -382,7 +406,8 @@ public sealed class ServerConnection : IVaultServer
                 meta,
                 oidc,
                 refreshing,
-                new DodoSshApiClient(transport, refreshing));
+                new DodoSshApiClient(transport, refreshing),
+                clock);
         }
         catch
         {
@@ -400,6 +425,12 @@ public sealed class ServerConnection : IVaultServer
         }
 
         disposed = true;
+
+        // First, and without waiting: the socket's own loops read the token provider and the transport
+        // below, so tearing either down while it is still dialling would surface as a fault on a
+        // background thread at the moment a user signed out.
+        Events.Dispose();
+
         tokens.Dispose();
         http.Dispose();
     }
diff --git a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
index 1340856..41a2c58 100644
--- a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
+++ b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
@@ -10,6 +10,7 @@ using DodoSSH.Client.Session;
 using DodoSSH.Client.Ssh;
 using DodoSSH.Client.Sync;
 using DodoSSH.Client.Terminal;
+using DodoSSH.Contracts;
 
 namespace DodoSSH.Client.Shell.ViewModels;
 
@@ -1025,13 +1026,29 @@ internal sealed partial class VaultViewModel(
     VaultVisibility? visibility = null) : ObservableObject, IAsyncDisposable
 {
     /// <remarks>
+    /// <para>
     /// A minute. The pull is a delta keyed on a cursor, so an idle pass is one small request and costs the
     /// server almost nothing; the number that matters is how stale a teammate's change may look, and a
     /// minute is short enough not to be noticed. Anything much shorter would be polling for its own sake,
     /// and a change made on this machine does not wait for the timer anyway — saving pushes immediately.
+    /// </para>
+    /// <para>
+    /// Unchanged by the push channel, and deliberately so. The socket makes a pass <em>early</em>; this is
+    /// what makes one happen at all, for a client whose network eats WebSockets, whose server has the
+    /// feature off, or whose notice was dropped. See <see cref="WaitForWorkAsync"/> and ADR 0012.
+    /// </para>
     /// </remarks>
     private static readonly TimeSpan AutoSyncInterval = TimeSpan.FromMinutes(1);
 
+    /// <summary>How long a pushed notice waits, in case more are on their way.</summary>
+    /// <remarks>
+    /// A quarter of a second, which is below what anybody perceives and above the gap between the
+    /// notices one person's save produces — a host and its activity log entry are two items in one
+    /// push, and a colleague clearing a folder is a burst. Without it each notice would run its own
+    /// full pass, and the pass a burst deserves is one.
+    /// </remarks>
+    private static readonly TimeSpan NoticeDebounce = TimeSpan.FromMilliseconds(250);
+
     /// <summary>How often the logs are pruned, at most.</summary>
     /// <remarks>
     /// Hours rather than minutes, because pruning writes tombstones that sync. Retention is measured in days
@@ -4030,10 +4047,16 @@ internal sealed partial class VaultViewModel(
     /// <para>
     /// <b>This is the whole of how a shared vault arrives.</b> Sharing is two acts on two machines: the
     /// person sharing wraps the vault key to the recipient, and the recipient's own client has to notice.
-    /// The recipient is handed nothing — there is no push channel — so without this the vault list stayed
-    /// exactly as it was cached at sign-in, and a vault shared with somebody appeared on their machine only
-    /// if they happened to sign in through the browser again. Everything else was already right, which is
-    /// why it looked like sharing was broken rather than like a list that was never re-read.
+    /// Without this the vault list stayed exactly as it was cached at sign-in, and a vault shared with
+    /// somebody appeared on their machine only if they happened to sign in through the browser again.
+    /// Everything else was already right, which is why it looked like sharing was broken rather than like a
+    /// list that was never re-read.
+    /// </para>
+    /// <para>
+    /// The server now says when this is worth doing — a <c>vaults.changed</c> notice wakes the pass, so the
+    /// vault turns up as it is shared rather than within the minute — but that only decides <em>when</em>.
+    /// This call is still what discovers the vault, on the notice and on every timed pass alike, because a
+    /// client with no socket has to arrive at the same place. See ADR 0012.
     /// </para>
     /// <para>
     /// A failure is left to the caller, which treats it as the pass failing: the call is to the same server
@@ -4080,6 +4103,7 @@ internal sealed partial class VaultViewModel(
     private async Task RunAutoSyncLoopAsync(CancellationToken cancellationToken)
     {
         using var timer = new PeriodicTimer(AutoSyncInterval);
+        var waits = new AutoSyncWaits();
 
         try
         {
@@ -4094,7 +4118,7 @@ internal sealed partial class VaultViewModel(
             // user is doing something.
             await SyncOnOpenAsync(cancellationToken).ConfigureAwait(true);
 
-            while (await timer.WaitForNextTickAsync(cancellationToken).ConfigureAwait(true))
+            while (await WaitForWorkAsync(timer, waits, cancellationToken).ConfigureAwait(true))
             {
                 await AutoSyncAsync(cancellationToken).ConfigureAwait(true);
             }
@@ -4105,6 +4129,98 @@ internal sealed partial class VaultViewModel(
         }
     }
 
+    /// <summary>
+    /// Waits for the timer to come round, or for the server to say there is something to fetch.
+    /// </summary>
+    /// <returns>Whether to run a pass. False means the loop is over.</returns>
+    /// <remarks>
+    /// <para>
+    /// The timer is unchanged and is still what guarantees a pass. The socket only makes one
+    /// <em>early</em>, which is why nothing here treats its absence as a problem: no connection, a
+    /// server without the feature, a network that eats WebSockets, or a notice dropped under
+    /// backpressure all leave a loop that behaves exactly as it did before this existed. See ADR 0012.
+    /// </para>
+    /// <para>
+    /// <b>Both waits are held across iterations, and that is load-bearing rather than an
+    /// optimisation.</b> <see cref="PeriodicTimer"/> permits only one outstanding
+    /// <c>WaitForNextTickAsync</c> and throws on a second, and an abandoned channel read stays
+    /// registered and consumes the next notice written — which would silently lose exactly the wake-up
+    /// this is for. Whichever wait did not win is kept and awaited again.
+    /// </para>
+    /// </remarks>
+    private async Task<bool> WaitForWorkAsync(
+        PeriodicTimer timer,
+        AutoSyncWaits waits,
+        CancellationToken cancellationToken)
+    {
+        // Re-read every time, because signing out and back in replaces the connection — and with it
+        // the stream. A read still pending against the old one is left to be cancelled with it.
+        var stream = connection()?.Events;
+
+        if (!ReferenceEquals(stream, waits.Watching))
+        {
+            waits.Watching = stream;
+            waits.Notice = null;
+        }
+
+        waits.Tick ??= timer.WaitForNextTickAsync(cancellationToken).AsTask();
+        waits.Notice ??= stream?.ReadAsync(cancellationToken).AsTask();
+
+        if (waits.Notice is null)
+        {
+            var only = waits.Tick;
+            waits.Tick = null;
+
+            return await only.ConfigureAwait(true);
+        }
+
+        var first = await Task.WhenAny(waits.Tick, waits.Notice).ConfigureAwait(true);
+
+        if (ReferenceEquals(first, waits.Tick))
+        {
+            var ticked = waits.Tick;
+            waits.Tick = null;
+
+            return await ticked.ConfigureAwait(true);
+        }
+
+        // Observed so a faulted read does not go unhandled, and so a stream that has been disposed
+        // ends this wait rather than being asked again.
+        await waits.Notice.ConfigureAwait(true);
+        waits.Notice = null;
+
+        // A burst — one person's save is two items, and a colleague tidying a folder is a dozen —
+        // deserves one pass rather than one each.
+        await Task.Delay(NoticeDebounce, cancellationToken).ConfigureAwait(true);
+
+        while (stream!.TryRead(out _))
+        {
+            // Swallowed on purpose. Every notice means the same thing, which is what the pass about to
+            // run already does; what they say about *which* vault is not read, because a pass syncs
+            // every vault this session can reach anyway.
+        }
+
+        return true;
+    }
+
+    /// <summary>The two waits the background loop keeps alive between passes.</summary>
+    /// <remarks>
+    /// A class rather than three locals because <see cref="WaitForWorkAsync"/> has to hand them back
+    /// changed, and a method that took three <c>ref</c> parameters could not be <c>async</c>. See that
+    /// method for why abandoning either of them is a defect rather than a tidiness question.
+    /// </remarks>
+    private sealed class AutoSyncWaits
+    {
+        /// <summary>The pending timer tick, or null when the last one has been consumed.</summary>
+        internal Task<bool>? Tick { get; set; }
+
+        /// <summary>The pending read from the server's push channel.</summary>
+        internal Task<VaultEvent>? Notice { get; set; }
+
+        /// <summary>The stream <see cref="Notice"/> was taken from, to notice a reconnection.</summary>
+        internal IVaultEventStream? Watching { get; set; }
+    }
+
     /// <summary>Shows one kind of item, if nothing is being edited.</summary>
     /// <remarks>
     /// Takes the section rather than there being one command per kind, so a third kind is an enum member and
diff --git a/src/DodoSSH.Contracts/DodoSshJsonContext.cs b/src/DodoSSH.Contracts/DodoSshJsonContext.cs
index e368c1c..fd1c3b4 100644
--- a/src/DodoSSH.Contracts/DodoSshJsonContext.cs
+++ b/src/DodoSSH.Contracts/DodoSshJsonContext.cs
@@ -66,6 +66,11 @@ namespace DodoSSH.Contracts;
 // Registered in its own right, not only as a member of the sync DTOs: the client's local
 // cache seals this record under the LocalCacheKey and needs its type info directly.
 [JsonSerializable(typeof(SyncPlaintextFields))]
+
+// The event socket's only frame type. Registered although nothing else references it: frames are
+// written straight onto a WebSocket rather than through a response body, so the resolver never
+// infers it from an endpoint's signature the way it does for every DTO above.
+[JsonSerializable(typeof(VaultEvent))]
 [JsonSerializable(typeof(RelayTicketRequest))]
 [JsonSerializable(typeof(RelayTicketResponse))]
 [JsonSerializable(typeof(RelaySessionSummary))]
diff --git a/src/DodoSSH.Contracts/Events.cs b/src/DodoSSH.Contracts/Events.cs
new file mode 100644
index 0000000..1545923
--- /dev/null
+++ b/src/DodoSSH.Contracts/Events.cs
@@ -0,0 +1,134 @@
+namespace DodoSSH.Contracts;
+
+/// <summary>
+/// The event socket's protocol constants.
+/// </summary>
+/// <remarks>
+/// The version lives in the subprotocol name rather than in the URL, for the reason ADR 0002 gives
+/// about the rest of this API: a client and a server that upgrade independently have to agree by
+/// negotiating rather than by assuming, and a WebSocket handshake already has a field for exactly
+/// that. A server that does not offer <see cref="SubProtocol"/> fails the handshake, which a client
+/// can act on — rather than opening a socket that then speaks a dialect it cannot read.
+/// </remarks>
+public static class VaultEvents
+{
+    /// <summary>The path the event socket is served from.</summary>
+    public const string Path = "/api/v1/events";
+
+    /// <summary>The only subprotocol this version speaks.</summary>
+    public const string SubProtocol = "dodossh.events.v1";
+
+    /// <summary>The <c>/api/v1/meta</c> feature flag advertising that this server pushes at all.</summary>
+    public const string Feature = "events";
+
+    /// <summary>
+    /// Close code for a socket whose access token has expired.
+    /// </summary>
+    /// <remarks>
+    /// In the 4000–4999 range, which the WebSocket specification reserves for applications. Its own
+    /// code because it is the one close a client should answer by reconnecting immediately with a
+    /// fresh token, rather than by backing off as it would for a server that went away.
+    /// </remarks>
+    public const int TokenExpiredCloseCode = 4401;
+
+    /// <summary>
+    /// Close code for a caller already holding as many sockets as it may.
+    /// </summary>
+    /// <remarks>
+    /// Distinguished from <see cref="TokenExpiredCloseCode"/> because the remedy is the opposite:
+    /// reconnecting at once is what caused it. A client that meets this backs off and keeps polling.
+    /// </remarks>
+    public const int TooManyConnectionsCloseCode = 4429;
+}
+
+/// <summary>
+/// The kinds of event this socket carries.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Constants rather than an <c>enum</c>, and that is a compatibility decision rather than a style
+/// one. <c>DodoSshJsonContext</c> sets <c>UseStringEnumConverter</c>, which <em>throws</em> on a
+/// value it does not know — so a newer server sending a kind an older client has never heard of
+/// would not merely add an unreadable frame, it would break that client's socket. A string is
+/// ignored instead, which is what makes this list extensible. <see cref="ProblemCodes"/> is the same
+/// shape for the same reason.
+/// </para>
+/// <para>
+/// <b>Anything a client cannot parse must be skipped, not treated as an error.</b> That rule is what
+/// the shared-session frames of ADR 0012 will rely on when they arrive.
+/// </para>
+/// </remarks>
+public static class VaultEventKinds
+{
+    /// <summary>The server accepted the socket. Always the first frame.</summary>
+    public const string Hello = "hello";
+
+    /// <summary>
+    /// A vault has changes at or before <see cref="VaultEvent.Sequence"/>.
+    /// </summary>
+    /// <remarks>
+    /// Carries no ciphertext and no item identity — the client's answer is the delta pull it would
+    /// have run on its timer anyway. See ADR 0012 for why pushing the items themselves is refused.
+    /// </remarks>
+    public const string VaultChanged = "vault.changed";
+
+    /// <summary>
+    /// The set of vaults this account can reach is no longer what it was.
+    /// </summary>
+    /// <remarks>
+    /// A vault shared with the caller, or a grant withdrawn. Deliberately says nothing about
+    /// <em>which</em>: the client re-reads the list, which is the same call it already makes at the
+    /// start of every synchronisation pass.
+    /// </remarks>
+    public const string VaultsChanged = "vaults.changed";
+
+    /// <summary>Heartbeat. Whichever side receives one answers <see cref="Pong"/>.</summary>
+    public const string Ping = "ping";
+
+    /// <summary>The answer to a <see cref="Ping"/>.</summary>
+    public const string Pong = "pong";
+}
+
+/// <summary>
+/// One frame on the event socket.
+/// </summary>
+/// <remarks>
+/// <para>
+/// One flat record for every kind, with the fields a given kind does not use left null, rather than
+/// a polymorphic hierarchy. The set is small, the frames are tiny, and <c>System.Text.Json</c>
+/// polymorphism would put a second discriminator mechanism next to the <see cref="Kind"/> string
+/// that is already the discriminator. Nothing else in <c>DodoSSH.Contracts</c> is polymorphic.
+/// </para>
+/// <para>
+/// <b>Nothing here is secret, by construction.</b> The server cannot read a vault's contents, so a
+/// notice cannot describe them; what it does disclose — that a vault changed, and when — is the same
+/// metadata ADR 0001 already accepts the server holding.
+/// </para>
+/// </remarks>
+/// <param name="Kind">One of <see cref="VaultEventKinds"/>. An unrecognised kind must be ignored.</param>
+/// <param name="VaultId">The vault a <see cref="VaultEventKinds.VaultChanged"/> is about.</param>
+/// <param name="Sequence">
+/// The change-log position that vault has reached. A hint for logging and for coalescing, not a
+/// cursor: cursors are opaque and HMAC-tagged, and this is neither.
+/// </param>
+/// <param name="ServerTime">
+/// The server's clock when the frame was written. The client already measures skew against
+/// <c>SyncPullResponse.ServerTime</c>; this lets a socket that is quiet for other reasons keep that
+/// measurement current.
+/// </param>
+/// <param name="HeartbeatSeconds">
+/// How often the server will ping, sent with <see cref="VaultEventKinds.Hello"/>. The client uses it
+/// to decide when silence means the connection is dead rather than idle.
+/// </param>
+/// <param name="VaultCount">
+/// How many vaults this socket is subscribed to, sent with <see cref="VaultEventKinds.Hello"/>.
+/// Diagnostic: a socket subscribed to nothing is a real state — an account with no vaults yet — and
+/// is otherwise indistinguishable from one that is quietly broken.
+/// </param>
+public sealed record VaultEvent(
+    string Kind,
+    Guid? VaultId = null,
+    long? Sequence = null,
+    DateTimeOffset? ServerTime = null,
+    int? HeartbeatSeconds = null,
+    int? VaultCount = null);
diff --git a/src/DodoSSH.Contracts/ProblemCodes.cs b/src/DodoSSH.Contracts/ProblemCodes.cs
index 1695912..5ee03b5 100644
--- a/src/DodoSSH.Contracts/ProblemCodes.cs
+++ b/src/DodoSSH.Contracts/ProblemCodes.cs
@@ -66,6 +66,16 @@ public static class ProblemCodes
     /// </remarks>
     public const string MalformedRequest = "malformed-request";
 
+    /// <summary>
+    /// This deployment does not push vault changes over a socket.
+    /// </summary>
+    /// <remarks>
+    /// Not a failure to recover from: synchronising on a timer is the supported behaviour and the
+    /// socket only ever made it early. A client that meets this stops dialling and keeps polling. See
+    /// ADR 0012.
+    /// </remarks>
+    public const string EventsUnavailable = "events-unavailable";
+
     /// <summary>The relay refused the requested target. Never states why, to avoid a probe oracle.</summary>
     public const string RelayTargetRejected = "relay-target-rejected";
 
diff --git a/src/DodoSSH.Contracts/PublicAPI.Unshipped.txt b/src/DodoSSH.Contracts/PublicAPI.Unshipped.txt
index b1b291e..30967e9 100644
--- a/src/DodoSSH.Contracts/PublicAPI.Unshipped.txt
+++ b/src/DodoSSH.Contracts/PublicAPI.Unshipped.txt
@@ -2,6 +2,7 @@
 const DodoSSH.Contracts.ProblemCodes.AlreadyEnrolled = "already-enrolled" -> string!
 const DodoSSH.Contracts.ProblemCodes.ClientTooOld = "client-too-old" -> string!
 const DodoSSH.Contracts.ProblemCodes.EnrollmentRequired = "enrollment-required" -> string!
+const DodoSSH.Contracts.ProblemCodes.EventsUnavailable = "events-unavailable" -> string!
 const DodoSSH.Contracts.ProblemCodes.Forbidden = "forbidden" -> string!
 const DodoSSH.Contracts.ProblemCodes.IdempotencyKeyReuse = "idempotency-key-reuse" -> string!
 const DodoSSH.Contracts.ProblemCodes.IdentityBindingInvalid = "identity-binding-invalid" -> string!
@@ -22,6 +23,16 @@ const DodoSSH.Contracts.ProblemCodes.TeamNotEmpty = "team-not-empty" -> string!
 const DodoSSH.Contracts.ProblemCodes.TeamSlugTaken = "team-slug-taken" -> string!
 const DodoSSH.Contracts.ProblemCodes.TypeBaseUri = "https://dodossh.dev/problems/" -> string!
 const DodoSSH.Contracts.ProblemCodes.VaultConflict = "vault-conflict" -> string!
+const DodoSSH.Contracts.VaultEventKinds.Hello = "hello" -> string!
+const DodoSSH.Contracts.VaultEventKinds.Ping = "ping" -> string!
+const DodoSSH.Contracts.VaultEventKinds.Pong = "pong" -> string!
+const DodoSSH.Contracts.VaultEventKinds.VaultChanged = "vault.changed" -> string!
+const DodoSSH.Contracts.VaultEventKinds.VaultsChanged = "vaults.changed" -> string!
+const DodoSSH.Contracts.VaultEvents.Feature = "events" -> string!
+const DodoSSH.Contracts.VaultEvents.Path = "/api/v1/events" -> string!
+const DodoSSH.Contracts.VaultEvents.SubProtocol = "dodossh.events.v1" -> string!
+const DodoSSH.Contracts.VaultEvents.TokenExpiredCloseCode = 4401 -> int
+const DodoSSH.Contracts.VaultEvents.TooManyConnectionsCloseCode = 4429 -> int
 DodoSSH.Contracts.AddTeamMemberRequest
 DodoSSH.Contracts.AddTeamMemberRequest.<Clone>$() -> DodoSSH.Contracts.AddTeamMemberRequest!
 DodoSSH.Contracts.AddTeamMemberRequest.AddTeamMemberRequest(System.Guid UserId, DodoSSH.Contracts.TeamMemberRole Role, string? Email = null) -> void
@@ -686,6 +697,25 @@ DodoSSH.Contracts.UpdateVaultRequest.Equals(DodoSSH.Contracts.UpdateVaultRequest
 DodoSSH.Contracts.UpdateVaultRequest.Name.get -> string!
 DodoSSH.Contracts.UpdateVaultRequest.Name.init -> void
 DodoSSH.Contracts.UpdateVaultRequest.UpdateVaultRequest(string! Name) -> void
+DodoSSH.Contracts.VaultEvent
+DodoSSH.Contracts.VaultEvent.<Clone>$() -> DodoSSH.Contracts.VaultEvent!
+DodoSSH.Contracts.VaultEvent.Deconstruct(out string! Kind, out System.Guid? VaultId, out long? Sequence, out System.DateTimeOffset? ServerTime, out int? HeartbeatSeconds, out int? VaultCount) -> void
+DodoSSH.Contracts.VaultEvent.Equals(DodoSSH.Contracts.VaultEvent? other) -> bool
+DodoSSH.Contracts.VaultEvent.HeartbeatSeconds.get -> int?
+DodoSSH.Contracts.VaultEvent.HeartbeatSeconds.init -> void
+DodoSSH.Contracts.VaultEvent.Kind.get -> string!
+DodoSSH.Contracts.VaultEvent.Kind.init -> void
+DodoSSH.Contracts.VaultEvent.Sequence.get -> long?
+DodoSSH.Contracts.VaultEvent.Sequence.init -> void
+DodoSSH.Contracts.VaultEvent.ServerTime.get -> System.DateTimeOffset?
+DodoSSH.Contracts.VaultEvent.ServerTime.init -> void
+DodoSSH.Contracts.VaultEvent.VaultCount.get -> int?
+DodoSSH.Contracts.VaultEvent.VaultCount.init -> void
+DodoSSH.Contracts.VaultEvent.VaultEvent(string! Kind, System.Guid? VaultId = null, long? Sequence = null, System.DateTimeOffset? ServerTime = null, int? HeartbeatSeconds = null, int? VaultCount = null) -> void
+DodoSSH.Contracts.VaultEvent.VaultId.get -> System.Guid?
+DodoSSH.Contracts.VaultEvent.VaultId.init -> void
+DodoSSH.Contracts.VaultEventKinds
+DodoSSH.Contracts.VaultEvents
 DodoSSH.Contracts.VaultGrantsResponse
 DodoSSH.Contracts.VaultGrantsResponse.<Clone>$() -> DodoSSH.Contracts.VaultGrantsResponse!
 DodoSSH.Contracts.VaultGrantsResponse.Deconstruct(out System.Guid VaultId, out uint KeyGeneration, out bool RekeyRequired, out System.Collections.Generic.IReadOnlyList<DodoSSH.Contracts.VaultGrantSummary!>! Grants) -> void
@@ -877,6 +907,9 @@ override DodoSSH.Contracts.UpdateTeamRequest.ToString() -> string!
 override DodoSSH.Contracts.UpdateVaultRequest.Equals(object? obj) -> bool
 override DodoSSH.Contracts.UpdateVaultRequest.GetHashCode() -> int
 override DodoSSH.Contracts.UpdateVaultRequest.ToString() -> string!
+override DodoSSH.Contracts.VaultEvent.Equals(object? obj) -> bool
+override DodoSSH.Contracts.VaultEvent.GetHashCode() -> int
+override DodoSSH.Contracts.VaultEvent.ToString() -> string!
 override DodoSSH.Contracts.VaultGrantsResponse.Equals(object? obj) -> bool
 override DodoSSH.Contracts.VaultGrantsResponse.GetHashCode() -> int
 override DodoSSH.Contracts.VaultGrantsResponse.ToString() -> string!
@@ -972,6 +1005,8 @@ static DodoSSH.Contracts.UpdateTeamRequest.operator !=(DodoSSH.Contracts.UpdateT
 static DodoSSH.Contracts.UpdateTeamRequest.operator ==(DodoSSH.Contracts.UpdateTeamRequest? left, DodoSSH.Contracts.UpdateTeamRequest? right) -> bool
 static DodoSSH.Contracts.UpdateVaultRequest.operator !=(DodoSSH.Contracts.UpdateVaultRequest? left, DodoSSH.Contracts.UpdateVaultRequest? right) -> bool
 static DodoSSH.Contracts.UpdateVaultRequest.operator ==(DodoSSH.Contracts.UpdateVaultRequest? left, DodoSSH.Contracts.UpdateVaultRequest? right) -> bool
+static DodoSSH.Contracts.VaultEvent.operator !=(DodoSSH.Contracts.VaultEvent? left, DodoSSH.Contracts.VaultEvent? right) -> bool
+static DodoSSH.Contracts.VaultEvent.operator ==(DodoSSH.Contracts.VaultEvent? left, DodoSSH.Contracts.VaultEvent? right) -> bool
 static DodoSSH.Contracts.VaultGrantsResponse.operator !=(DodoSSH.Contracts.VaultGrantsResponse? left, DodoSSH.Contracts.VaultGrantsResponse? right) -> bool
 static DodoSSH.Contracts.VaultGrantsResponse.operator ==(DodoSSH.Contracts.VaultGrantsResponse? left, DodoSSH.Contracts.VaultGrantsResponse? right) -> bool
 static DodoSSH.Contracts.VaultGrantSummary.operator !=(DodoSSH.Contracts.VaultGrantSummary? left, DodoSSH.Contracts.VaultGrantSummary? right) -> bool
diff --git a/tests/DodoSSH.Api.Tests/ApiFixture.cs b/tests/DodoSSH.Api.Tests/ApiFixture.cs
index e78e4c9..0836578 100644
--- a/tests/DodoSSH.Api.Tests/ApiFixture.cs
+++ b/tests/DodoSSH.Api.Tests/ApiFixture.cs
@@ -1,4 +1,6 @@
 using System.Net.Http.Headers;
+using System.Net.WebSockets;
+using DodoSSH.Contracts;
 using DodoSSH.Infrastructure;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Mvc.Testing;
@@ -107,6 +109,34 @@ public sealed class ApiFixture : WebApplicationFactory<Program>, IAsyncLifetime
 
     /// <summary>Opens a database scope for arranging state and asserting on it.</summary>
     public AsyncServiceScope CreateScope() => Services.CreateAsyncScope();
+
+    /// <summary>
+    /// Opens the event socket as the given subject, through the real pipeline.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The bearer token goes on the upgrade request, which is the whole of the socket's authorization
+    /// — see ADR 0012 — so a test that stubbed it would be testing nothing. The subprotocol is offered
+    /// because the server refuses an upgrade that does not, and that refusal is itself under test.
+    /// </para>
+    /// <para>
+    /// <c>TestServer</c> speaks WebSockets in-memory with no port and no network, so these run
+    /// wherever the rest of the suite does.
+    /// </para>
+    /// </remarks>
+    public Task<WebSocket> ConnectEventsAsync(string subject, CancellationToken cancellationToken)
+    {
+        var token = IdentityProvider.MintToken(subject);
+        var client = Server.CreateWebSocketClient();
+
+        client.SubProtocols.Add(VaultEvents.SubProtocol);
+        // The server-side request, so the header is a raw string rather than a typed value.
+        client.ConfigureRequest = request => request.Headers.Authorization = $"Bearer {token}";
+
+        return client.ConnectAsync(
+            new Uri(Server.BaseAddress, VaultEvents.Path.TrimStart('/')),
+            cancellationToken);
+    }
 }
 
 /// <summary>Shares one host and container across every test class in the assembly.</summary>
diff --git a/tests/DodoSSH.Api.Tests/EndpointInventoryTests.cs b/tests/DodoSSH.Api.Tests/EndpointInventoryTests.cs
index b0aecd0..4a81fc0 100644
--- a/tests/DodoSSH.Api.Tests/EndpointInventoryTests.cs
+++ b/tests/DodoSSH.Api.Tests/EndpointInventoryTests.cs
@@ -56,6 +56,12 @@ public sealed class EndpointInventoryTests(ApiFixture fixture)
         "POST /api/v1/vaults/{vaultId:guid}/sync/pull name=SyncPull tags=Sync policies=Enrolled anon=False",
         "POST /api/v1/vaults/{vaultId:guid}/sync/push name=SyncPush tags=Sync policies=Enrolled anon=False",
 
+        // The WebSocket, gated exactly as sync is and for the same reason — it announces changes to
+        // vaults, and a caller who could not read one has nothing to be told about. It appears here as
+        // an ordinary route because that is what it is until the upgrade: the bearer token authorises
+        // the handshake, unlike the relay's ticket. See ADR 0012.
+        "GET /api/v1/events name=VaultEvents tags=Events policies=Enrolled anon=False",
+
         // Enrolled, because the answer exists to be wrapped to and a caller with no key of their own has
         // nothing to wrap and no signature to attribute it with. There is no search here — see
         // DirectoryService for why an exact-match-only directory is a decision rather than a shortcut.
diff --git a/tests/DodoSSH.Api.Tests/EventsEndpointTests.cs b/tests/DodoSSH.Api.Tests/EventsEndpointTests.cs
new file mode 100644
index 0000000..6509660
--- /dev/null
+++ b/tests/DodoSSH.Api.Tests/EventsEndpointTests.cs
@@ -0,0 +1,461 @@
+using System.Net;
+using System.Net.WebSockets;
+using System.Text;
+using System.Text.Json;
+using DodoSSH.Contracts;
+using DodoSSH.Domain;
+using DodoSSH.Infrastructure;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace DodoSSH.Api.Tests;
+
+/// <summary>
+/// The push channel, over a real socket through the real authentication pipeline.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The tests that matter most here are the two negatives: an unauthenticated upgrade is refused, and a
+/// change to somebody else's vault does not reach this socket. A push channel that leaked <em>which
+/// vault ids exist and when they change</em> would be a disclosure the pull path takes deliberate
+/// trouble to avoid — <c>SyncPullEndpoint</c> answers 404 rather than 403 for exactly that reason —
+/// and it would be invisible in a test that only checked that notices arrive.
+/// </para>
+/// <para>
+/// Ordering is asserted rather than absence-within-a-timeout wherever possible. "Nothing arrived in
+/// two seconds" is a test that passes on a slow machine for the wrong reason; "the first notice this
+/// socket saw was about its own vault, although another vault was written to first" is not.
+/// </para>
+/// </remarks>
+[Collection(ApiCollection.Name)]
+public sealed class EventsEndpointTests(ApiFixture fixture)
+{
+    private static readonly DateTimeOffset Now = new(2026, 8, 4, 12, 0, 0, TimeSpan.Zero);
+
+    /// <summary>
+    /// How long a test will wait for a frame before calling it a failure.
+    /// </summary>
+    /// <remarks>
+    /// Generous, because it is not a measurement: every wait here is for something already committed,
+    /// so the only thing this bounds is how long a genuinely broken build hangs before it reports.
+    /// </remarks>
+    private static readonly TimeSpan FrameTimeout = TimeSpan.FromSeconds(30);
+
+    // ---- The handshake ----
+
+    [Fact]
+    public async Task WithoutAToken_TheUpgradeIsRefused()
+    {
+        var client = fixture.Server.CreateWebSocketClient();
+        client.SubProtocols.Add(VaultEvents.SubProtocol);
+
+        var connecting = client.ConnectAsync(
+            new Uri(fixture.Server.BaseAddress, VaultEvents.Path.TrimStart('/')),
+            TestContext.Current.CancellationToken);
+
+        await Should.ThrowAsync<InvalidOperationException>(connecting);
+    }
+
+    [Fact]
+    public async Task BeforeEnrolling_Is403WithAnActionableCode()
+    {
+        // The same bar as sync: a caller with no identity key holds no vault key either, so every
+        // notice this socket could carry is about ciphertext they cannot read.
+        var client = fixture.CreateClientFor(NewSubject());
+
+        var response = await client.GetAsync(
+            new Uri(VaultEvents.Path, UriKind.Relative),
+            TestContext.Current.CancellationToken);
+
+        response.StatusCode.ShouldBe(HttpStatusCode.Forbidden);
+
+        var problem = await response.Content.ReadProblemAsync();
+        problem.ShouldNotBeNull();
+        problem.Code.ShouldBe(ProblemCodes.EnrollmentRequired);
+    }
+
+    [Fact]
+    public async Task APlainGet_SaysItIsAWebSocket()
+    {
+        // A person, or a client with the wrong URL. Answering with a problem document rather than a
+        // socket that closes is the difference between a diagnosable mistake and a mysterious one.
+        var client = fixture.CreateClientFor(await SeedEnrolledUserAsync());
+
+        var response = await client.GetAsync(
+            new Uri(VaultEvents.Path, UriKind.Relative),
+            TestContext.Current.CancellationToken);
+
+        response.StatusCode.ShouldBe(HttpStatusCode.BadRequest);
+
+        var problem = await response.Content.ReadProblemAsync();
+        problem.ShouldNotBeNull();
+        problem.Code.ShouldBe(ProblemCodes.MalformedRequest);
+        problem.Detail.ShouldNotBeNull().ShouldContain(VaultEvents.SubProtocol);
+    }
+
+    [Fact]
+    public async Task AnUpgradeWithoutTheSubprotocol_IsRefused()
+    {
+        // The subprotocol is this socket's version negotiation, so accepting an upgrade that did not
+        // offer it would mean answering a client in a dialect it never agreed to read.
+        var (subject, _) = await SeedUserWithVaultAsync();
+
+        var client = fixture.Server.CreateWebSocketClient();
+        client.ConfigureRequest = request => request.Headers.Authorization =
+            $"Bearer {fixture.IdentityProvider.MintToken(subject)}";
+
+        var connecting = client.ConnectAsync(
+            new Uri(fixture.Server.BaseAddress, VaultEvents.Path.TrimStart('/')),
+            TestContext.Current.CancellationToken);
+
+        await Should.ThrowAsync<InvalidOperationException>(connecting);
+    }
+
+    [Fact]
+    public async Task TheFirstFrameIsHello()
+    {
+        var (subject, _) = await SeedUserWithVaultAsync();
+
+        using var timeout = Timeout();
+        using var socket = await fixture.ConnectEventsAsync(subject, timeout.Token);
+
+        var hello = await ReadAsync(socket, timeout.Token);
+
+        hello.Kind.ShouldBe(VaultEventKinds.Hello);
+
+        // Sent so a client knows when silence means the socket is dead rather than quiet, and so a
+        // socket following nothing — a real state, for an account with no vaults — is distinguishable
+        // from one that is broken.
+        hello.HeartbeatSeconds.ShouldNotBeNull().ShouldBeGreaterThan(0);
+        hello.VaultCount.ShouldBe(1);
+    }
+
+    [Fact]
+    public async Task MetaAdvertisesTheFeature()
+    {
+        // How a client decides whether to hold a socket open at all. Absence is not an error — it
+        // means synchronise on the timer, which is what every client did before this existed.
+        var client = fixture.CreateClient();
+
+        var meta = await (await client.GetAsync(
+                new Uri("/api/v1/meta", UriKind.Relative),
+                TestContext.Current.CancellationToken))
+            .Content.ReadContractAsync<MetaResponse>();
+
+        meta.ShouldNotBeNull();
+        meta.Features.ShouldContain(
+            feature => string.Equals(feature, VaultEvents.Feature, StringComparison.Ordinal));
+    }
+
+    // ---- Notices ----
+
+    [Fact]
+    public async Task APush_AnnouncesTheVaultToAFollowingSocket()
+    {
+        var (subject, vaultId) = await SeedUserWithVaultAsync();
+
+        using var timeout = Timeout();
+        using var socket = await fixture.ConnectEventsAsync(subject, timeout.Token);
+
+        await ReadAsync(socket, timeout.Token);
+
+        var client = fixture.CreateClientFor(subject);
+        var push = await client.PostContractAsync(PushUrl(vaultId), NewCreateBatch());
+        push.EnsureSuccessStatusCode();
+
+        var notice = await ReadUntilAsync(socket, VaultEventKinds.VaultChanged, timeout.Token);
+
+        notice.VaultId.ShouldBe(vaultId);
+
+        // A hint for logging and coalescing, never a cursor: cursors are opaque and integrity-tagged,
+        // and a client that tried to resume from this would be resuming from a number it invented.
+        notice.Sequence.ShouldNotBeNull().ShouldBeGreaterThan(0);
+    }
+
+    [Fact]
+    public async Task ANoticeCarriesNoCiphertext()
+    {
+        // The load-bearing property of the whole design. A notice says only that a vault moved; the
+        // client's answer is the delta pull it would have run on its timer anyway, which keeps exactly
+        // one code path applying changes. See ADR 0012.
+        var (subject, vaultId) = await SeedUserWithVaultAsync();
+
+        using var timeout = Timeout();
+        using var socket = await fixture.ConnectEventsAsync(subject, timeout.Token);
+
+        await ReadAsync(socket, timeout.Token);
+
+        var client = fixture.CreateClientFor(subject);
+        var batch = NewCreateBatch();
+        await client.PostContractAsync(PushUrl(vaultId), batch);
+
+        var raw = await ReadRawUntilAsync(socket, VaultEventKinds.VaultChanged, timeout.Token);
+
+        // The envelope this test pushed, as it would appear if a payload had been forwarded.
+        raw.ShouldNotContain(Convert.ToBase64String(batch.Operations[0].Payload!.Envelope));
+        raw.ShouldNotContain("payload", Case.Insensitive);
+        raw.ShouldNotContain(batch.Operations[0].EntityId.ToString());
+    }
+
+    [Fact]
+    public async Task APushToAnotherAccountsVault_IsNotAnnouncedHere()
+    {
+        // The disclosure that would matter: a socket learning that vault ids it cannot read exist,
+        // and when somebody works on them.
+        var (subject, vaultId) = await SeedUserWithVaultAsync();
+        var (stranger, strangersVaultId) = await SeedUserWithVaultAsync();
+
+        using var timeout = Timeout();
+        using var socket = await fixture.ConnectEventsAsync(subject, timeout.Token);
+
+        await ReadAsync(socket, timeout.Token);
+
+        // The stranger's write goes first, so a socket that leaked would have announced it before the
+        // one this test then waits for. Ordering, not a timeout: "nothing arrived in two seconds"
+        // passes on a slow machine for the wrong reason.
+        var strangersClient = fixture.CreateClientFor(stranger);
+        (await strangersClient.PostContractAsync(PushUrl(strangersVaultId), NewCreateBatch()))
+            .EnsureSuccessStatusCode();
+
+        var ownClient = fixture.CreateClientFor(subject);
+        (await ownClient.PostContractAsync(PushUrl(vaultId), NewCreateBatch()))
+            .EnsureSuccessStatusCode();
+
+        var notice = await ReadUntilAsync(socket, VaultEventKinds.VaultChanged, timeout.Token);
+
+        notice.VaultId.ShouldBe(vaultId);
+        notice.VaultId.ShouldNotBe(strangersVaultId);
+    }
+
+    [Fact]
+    public async Task APushThatAppliedNothing_AnnouncesNothing()
+    {
+        // A batch of pure conflicts moved no vault. Announcing one anyway would have every client on
+        // it pull for a change that is not there.
+        var (subject, vaultId) = await SeedUserWithVaultAsync();
+        var client = fixture.CreateClientFor(subject);
+
+        using var timeout = Timeout();
+        using var socket = await fixture.ConnectEventsAsync(subject, timeout.Token);
+
+        await ReadAsync(socket, timeout.Token);
+
+        // An update to an item that does not exist: rejected as a conflict, nothing written.
+        var stale = new SyncPushRequest(
+        [
+            NewOperation(Guid.CreateVersion7(), expectedVersion: 7, envelope: [9, 9]),
+        ]);
+
+        var conflicted = await client.PostContractAsync(PushUrl(vaultId), stale);
+        conflicted.EnsureSuccessStatusCode();
+
+        var results = await conflicted.Content.ReadContractAsync<SyncPushResponse>();
+        results.ShouldNotBeNull();
+        results.Results[0].Status.ShouldBe(SyncOperationStatus.Conflict);
+
+        // Then a write that did land. The first notice must be that one.
+        (await client.PostContractAsync(PushUrl(vaultId), NewCreateBatch())).EnsureSuccessStatusCode();
+
+        var notice = await ReadUntilAsync(socket, VaultEventKinds.VaultChanged, timeout.Token);
+
+        notice.Sequence.ShouldNotBeNull().ShouldBeGreaterThan(0);
+    }
+
+    [Fact]
+    public async Task APing_IsAnswered()
+    {
+        var (subject, _) = await SeedUserWithVaultAsync();
+
+        using var timeout = Timeout();
+        using var socket = await fixture.ConnectEventsAsync(subject, timeout.Token);
+
+        await ReadAsync(socket, timeout.Token);
+
+        await SendAsync(socket, new VaultEvent(VaultEventKinds.Ping), timeout.Token);
+
+        var pong = await ReadUntilAsync(socket, VaultEventKinds.Pong, timeout.Token);
+
+        pong.Kind.ShouldBe(VaultEventKinds.Pong);
+    }
+
+    [Fact]
+    public async Task AFrameThisServerCannotRead_DoesNotEndTheSocket()
+    {
+        // A control channel whose failure mode is "the client polls instead" should tolerate a frame
+        // from a newer client rather than cost that client its push for the whole session.
+        var (subject, vaultId) = await SeedUserWithVaultAsync();
+
+        using var timeout = Timeout();
+        using var socket = await fixture.ConnectEventsAsync(subject, timeout.Token);
+
+        await ReadAsync(socket, timeout.Token);
+
+        await socket.SendAsync(
+            Encoding.UTF8.GetBytes("{ not json at all"),
+            WebSocketMessageType.Text,
+            endOfMessage: true,
+            timeout.Token);
+
+        var client = fixture.CreateClientFor(subject);
+        (await client.PostContractAsync(PushUrl(vaultId), NewCreateBatch())).EnsureSuccessStatusCode();
+
+        var notice = await ReadUntilAsync(socket, VaultEventKinds.VaultChanged, timeout.Token);
+
+        notice.VaultId.ShouldBe(vaultId);
+        socket.State.ShouldBe(WebSocketState.Open);
+    }
+
+    // ---- Helpers ----
+
+    /// <summary>A token that gives up rather than letting a broken build hang the suite.</summary>
+    private static CancellationTokenSource Timeout()
+    {
+        var source = CancellationTokenSource.CreateLinkedTokenSource(
+            TestContext.Current.CancellationToken);
+
+        source.CancelAfter(FrameTimeout);
+
+        return source;
+    }
+
+    private static async Task<VaultEvent> ReadAsync(WebSocket socket, CancellationToken cancellationToken)
+    {
+        var json = await ReadRawAsync(socket, cancellationToken);
+
+        return JsonSerializer.Deserialize(json, DodoSshJsonContext.Default.VaultEvent)
+            ?? throw new InvalidOperationException($"The server sent a null frame: {json}");
+    }
+
+    private static async Task<string> ReadRawAsync(WebSocket socket, CancellationToken cancellationToken)
+    {
+        var buffer = new byte[8 * 1024];
+
+        var received = await socket.ReceiveAsync(buffer, cancellationToken);
+
+        if (received.MessageType == WebSocketMessageType.Close)
+        {
+            throw new InvalidOperationException(
+                $"The server closed the socket: {received.CloseStatus} {received.CloseStatusDescription}");
+        }
+
+        return Encoding.UTF8.GetString(buffer, 0, received.Count);
+    }
+
+    /// <summary>Reads past the frames a test does not care about — hello, and heartbeats.</summary>
+    private static async Task<VaultEvent> ReadUntilAsync(
+        WebSocket socket,
+        string kind,
+        CancellationToken cancellationToken)
+    {
+        while (true)
+        {
+            var frame = await ReadAsync(socket, cancellationToken);
+
+            if (string.Equals(frame.Kind, kind, StringComparison.Ordinal))
+            {
+                return frame;
+            }
+        }
+    }
+
+    /// <summary>
+    /// The same, but keeping the bytes.
+    /// </summary>
+    /// <remarks>
+    /// Deserialising and asserting on the fields would prove only that this <em>record</em> has no
+    /// payload member, which is a tautology. Asserting on what actually crossed the socket is what
+    /// would catch a field added to the frame later without anybody thinking about disclosure.
+    /// </remarks>
+    private static async Task<string> ReadRawUntilAsync(
+        WebSocket socket,
+        string kind,
+        CancellationToken cancellationToken)
+    {
+        while (true)
+        {
+            var json = await ReadRawAsync(socket, cancellationToken);
+            var frame = JsonSerializer.Deserialize(json, DodoSshJsonContext.Default.VaultEvent);
+
+            if (string.Equals(frame?.Kind, kind, StringComparison.Ordinal))
+            {
+                return json;
+            }
+        }
+    }
+
+    private static Task SendAsync(WebSocket socket, VaultEvent frame, CancellationToken cancellationToken) =>
+        socket.SendAsync(
+            JsonSerializer.SerializeToUtf8Bytes(frame, DodoSshJsonContext.Default.VaultEvent),
+            WebSocketMessageType.Text,
+            endOfMessage: true,
+            cancellationToken);
+
+    private static string PushUrl(Guid vaultId) => $"/api/v1/vaults/{vaultId}/sync/push";
+
+    private static string NewSubject() => $"events-{Guid.CreateVersion7():N}";
+
+    private static SyncPushOperation NewOperation(Guid entityId, int? expectedVersion, byte[] envelope) =>
+        new(
+            Guid.CreateVersion7(),
+            SyncEntityType.Host,
+            entityId,
+            SyncOperation.Upsert,
+            expectedVersion,
+            new EncryptedPayload(envelope, [0xD, 0xE], Guid.CreateVersion7(), 1, 1),
+            new SyncPlaintextFields());
+
+    private static SyncPushRequest NewCreateBatch() =>
+        new([NewOperation(Guid.CreateVersion7(), expectedVersion: null, envelope: [1, 2, 3, 4])]);
+
+    private async Task<string> SeedEnrolledUserAsync()
+    {
+        var subject = NewSubject();
+
+        await using var scope = fixture.CreateScope();
+        var database = scope.ServiceProvider.GetRequiredService<DodoDbContext>();
+
+        var user = NewUser(subject);
+        database.Users.Add(user);
+        database.UserKeys.Add(Seed.CurrentKey(user.Id, Now));
+        await database.SaveChangesAsync();
+
+        return subject;
+    }
+
+    private async Task<(string Subject, Guid VaultId)> SeedUserWithVaultAsync()
+    {
+        var subject = NewSubject();
+
+        await using var scope = fixture.CreateScope();
+        var database = scope.ServiceProvider.GetRequiredService<DodoDbContext>();
+
+        var user = NewUser(subject);
+
+        var vault = new Vault
+        {
+            Id = Guid.CreateVersion7(),
+            Name = "Personal",
+            OwnerKind = VaultOwnerKind.Personal,
+            OwnerUserId = user.Id,
+            KeyGeneration = 1,
+            CreatedAtUtc = Now,
+            UpdatedAtUtc = Now,
+        };
+
+        database.Users.Add(user);
+        database.UserKeys.Add(Seed.CurrentKey(user.Id, Now));
+        database.Vaults.Add(vault);
+        await database.SaveChangesAsync();
+
+        return (subject, vault.Id);
+    }
+
+    private UserAccount NewUser(string subject) => new()
+    {
+        Id = Guid.CreateVersion7(),
+        Issuer = fixture.IdentityProvider.Authority,
+        Subject = subject,
+        Status = UserStatus.Active,
+        CreatedAtUtc = Now,
+        UpdatedAtUtc = Now,
+    };
+}
diff --git a/tests/DodoSSH.Client.Api.Tests/VaultEventStreamTests.cs b/tests/DodoSSH.Client.Api.Tests/VaultEventStreamTests.cs
new file mode 100644
index 0000000..3637e63
--- /dev/null
+++ b/tests/DodoSSH.Client.Api.Tests/VaultEventStreamTests.cs
@@ -0,0 +1,388 @@
+using System.Net.WebSockets;
+using System.Text;
+using System.Text.Json;
+using System.Threading.Channels;
+using DodoSSH.Client.Api;
+using DodoSSH.Contracts;
+
+namespace DodoSSH.Client.Api.Tests;
+
+/// <summary>
+/// The reconnection policy, which is what this class actually is.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A dropped socket is the ordinary case here rather than the exception — laptops sleep, proxies time
+/// out, tokens expire, servers are redeployed — so the behaviour worth covering is what happens
+/// <em>after</em> a failure, not the happy path. Driven through the injected connector, because the one
+/// thing a test cannot do to a real network is make it fail on cue.
+/// </para>
+/// <para>
+/// The backoff is configured down to milliseconds throughout. What is under test is the shape of the
+/// policy — does it try again, does it wait, does it stop waiting when told the token was the problem —
+/// and none of that depends on the intervals a shipped client uses.
+/// </para>
+/// </remarks>
+public sealed class VaultEventStreamTests
+{
+    private static readonly Uri Server = new("https://dodossh.example");
+
+    private static readonly VaultEventStreamOptions Impatient = new()
+    {
+        InitialBackoff = TimeSpan.FromMilliseconds(1),
+        MaxBackoff = TimeSpan.FromMilliseconds(5),
+        InitialSilenceTimeout = TimeSpan.FromSeconds(30),
+    };
+
+    [Fact]
+    public async Task ItDialsTheWebSocketFormOfTheServersUrl()
+    {
+        // https becomes wss, and the path is the one in the contract. Getting either wrong is a client
+        // that reconnects against a 404 for the whole session, which from outside is indistinguishable
+        // from a network that eats WebSockets.
+        var dialled = new List<Uri>();
+        var socket = new FakeWebSocket();
+
+        await using var stream = Stream(
+            (url, _, _) =>
+            {
+                dialled.Add(url);
+                return Task.FromResult<WebSocket>(socket);
+            });
+
+        socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 1));
+
+        await stream.ReadAsync(Token);
+
+        dialled[0].ShouldBe(new Uri("wss://dodossh.example/api/v1/events"));
+    }
+
+    [Fact]
+    public async Task ItSendsTheBearerTokenOnTheUpgrade()
+    {
+        // The whole of this socket's authorization, unlike the relay's ticket. See ADR 0012.
+        var presented = new List<string>();
+        var socket = new FakeWebSocket();
+
+        await using var stream = Stream(
+            (_, token, _) =>
+            {
+                presented.Add(token);
+                return Task.FromResult<WebSocket>(socket);
+            });
+
+        socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 1));
+
+        await stream.ReadAsync(Token);
+
+        presented[0].ShouldBe(StubTokens.Token);
+    }
+
+    [Fact]
+    public async Task ANoticeReachesTheReader()
+    {
+        var vaultId = Guid.CreateVersion7();
+        var socket = new FakeWebSocket();
+
+        await using var stream = Stream((_, _, _) => Task.FromResult<WebSocket>(socket));
+
+        socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, vaultId, 42));
+
+        var notice = await stream.ReadAsync(Token);
+
+        notice.Kind.ShouldBe(VaultEventKinds.VaultChanged);
+        notice.VaultId.ShouldBe(vaultId);
+        notice.Sequence.ShouldBe(42);
+    }
+
+    [Fact]
+    public async Task AHeartbeatIsAnsweredAndNotHandedToTheReader()
+    {
+        // A ping is housekeeping between the two ends. Passing it up would wake a synchronisation loop
+        // every thirty seconds for a frame that says nothing happened.
+        var socket = new FakeWebSocket();
+
+        await using var stream = Stream((_, _, _) => Task.FromResult<WebSocket>(socket));
+
+        socket.Deliver(new VaultEvent(VaultEventKinds.Ping, HeartbeatSeconds: 30));
+        socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 1));
+
+        var first = await stream.ReadAsync(Token);
+
+        first.Kind.ShouldBe(VaultEventKinds.VaultChanged, "the ping should not have been forwarded");
+
+        var answered = await socket.SentAsync(Token);
+        answered.Kind.ShouldBe(VaultEventKinds.Pong);
+    }
+
+    [Fact]
+    public async Task AKindThisBuildDoesNotKnow_IsStillHandedOver()
+    {
+        // What makes the frame table extensible: this class must not decide what a newer server may
+        // say. Deciding to ignore it is the caller's, and costs that caller one redundant pass.
+        var socket = new FakeWebSocket();
+
+        await using var stream = Stream((_, _, _) => Task.FromResult<WebSocket>(socket));
+
+        socket.Deliver(new VaultEvent("session.offered"));
+
+        var notice = await stream.ReadAsync(Token);
+
+        notice.Kind.ShouldBe("session.offered");
+    }
+
+    [Fact]
+    public async Task AFailedDial_IsRetried()
+    {
+        // No server yet, or no network. Neither is an error to report: the caller's synchronisation
+        // timer is running regardless, which is what lets this stay silent and keep trying.
+        var attempts = 0;
+        var socket = new FakeWebSocket();
+
+        await using var stream = Stream((_, _, _) =>
+        {
+            if (++attempts < 3)
+            {
+                throw new WebSocketException("no route to host");
+            }
+
+            return Task.FromResult<WebSocket>(socket);
+        });
+
+        socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 1));
+
+        var notice = await stream.ReadAsync(Token);
+
+        notice.Kind.ShouldBe(VaultEventKinds.VaultChanged);
+        attempts.ShouldBe(3);
+    }
+
+    [Fact]
+    public async Task ADroppedSocket_IsReplaced()
+    {
+        // The case that decides whether this feature survives a laptop lid. A stream that gave up on
+        // the first close would work all morning and be silently dead after lunch.
+        var sockets = new List<FakeWebSocket>();
+
+        await using var stream = Stream((_, _, _) =>
+        {
+            var socket = new FakeWebSocket();
+            sockets.Add(socket);
+
+            if (sockets.Count == 1)
+            {
+                socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 1));
+                socket.Close(WebSocketCloseStatus.EndpointUnavailable);
+            }
+            else
+            {
+                socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 2));
+            }
+
+            return Task.FromResult<WebSocket>(socket);
+        });
+
+        (await stream.ReadAsync(Token)).Sequence.ShouldBe(1);
+        (await stream.ReadAsync(Token)).Sequence.ShouldBe(2);
+
+        sockets.Count.ShouldBeGreaterThanOrEqualTo(2);
+    }
+
+    [Fact]
+    public async Task AnExpiredTokenClose_ReconnectsAndAsksForAFreshToken()
+    {
+        // The bound that lets a long-lived socket be authorised by a short-lived credential: the server
+        // closes at the token's expiry and the client comes straight back with a new one. The token
+        // provider being asked again is the half that matters — reconnecting with the spent token would
+        // be an unbroken loop of closes.
+        var tokens = new StubTokens();
+        var sockets = 0;
+
+        await using var stream = new VaultEventStream(
+            Server,
+            tokens,
+            TimeProvider.System,
+            (_, _, _) =>
+            {
+                var socket = new FakeWebSocket();
+
+                if (++sockets == 1)
+                {
+                    socket.Close((WebSocketCloseStatus)VaultEvents.TokenExpiredCloseCode);
+                }
+                else
+                {
+                    socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 7));
+                }
+
+                return Task.FromResult<WebSocket>(socket);
+            },
+            Impatient);
+
+        (await stream.ReadAsync(Token)).Sequence.ShouldBe(7);
+
+        tokens.Requests.ShouldBeGreaterThanOrEqualTo(2);
+    }
+
+    [Fact]
+    public async Task TryRead_TakesWhatIsWaitingAndSaysWhenNothingIs()
+    {
+        // How a caller coalesces a burst: read one, wait a moment, swallow the rest. Without this a
+        // colleague tidying a folder would produce a synchronisation pass per item.
+        var socket = new FakeWebSocket();
+
+        await using var stream = Stream((_, _, _) => Task.FromResult<WebSocket>(socket));
+
+        socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 1));
+        socket.Deliver(new VaultEvent(VaultEventKinds.VaultChanged, Guid.CreateVersion7(), 2));
+
+        (await stream.ReadAsync(Token)).Sequence.ShouldBe(1);
+
+        // Delivery is asynchronous, so the second may not have landed yet; this is the same
+        // wait-then-drain the caller performs.
+        await Task.Delay(TimeSpan.FromMilliseconds(200), Token);
+
+        stream.TryRead(out var queued).ShouldBeTrue();
+        queued.Sequence.ShouldBe(2);
+
+        stream.TryRead(out _).ShouldBeFalse();
+    }
+
+    [Fact]
+    public async Task AnIdleStream_NeverDelivers()
+    {
+        // What a server without the feature supplies. Waiting for ever rather than completing is the
+        // point: a caller selecting between this and a timer has to fall through to the timer, and a
+        // read that returned at once would spin that loop as fast as the machine allows.
+        using var stream = IdleVaultEventStream.Instance;
+        using var giveUp = CancellationTokenSource.CreateLinkedTokenSource(Token);
+
+        giveUp.CancelAfter(TimeSpan.FromMilliseconds(100));
+
+        await Should.ThrowAsync<OperationCanceledException>(
+            async () => await stream.ReadAsync(giveUp.Token));
+
+        stream.TryRead(out _).ShouldBeFalse();
+        stream.IsConnected.ShouldBeFalse();
+    }
+
+    private static CancellationToken Token => TestContext.Current.CancellationToken;
+
+    private static VaultEventStream Stream(
+        Func<Uri, string, CancellationToken, Task<WebSocket>> connect) =>
+        new(Server, new StubTokens(), TimeProvider.System, connect, Impatient);
+
+    /// <summary>A token provider that hands out one value and counts who asked.</summary>
+    private sealed class StubTokens : IAccessTokenProvider
+    {
+        internal const string Token = "access-token";
+
+        internal int Requests { get; private set; }
+
+        public ValueTask<string> GetAccessTokenAsync(CancellationToken cancellationToken)
+        {
+            Requests++;
+
+            return ValueTask.FromResult(Token);
+        }
+    }
+
+    /// <summary>
+    /// A socket a test writes the server's half of.
+    /// </summary>
+    /// <remarks>
+    /// Frames queued with <see cref="Deliver"/> are handed out by <see cref="ReceiveAsync"/> in order;
+    /// once the queue is empty the receive waits, which is what an idle connection does. <see
+    /// cref="Close"/> queues the close instead, so a test can script "two notices and then the server
+    /// went away" as a value rather than as a race.
+    /// </remarks>
+    private sealed class FakeWebSocket : WebSocket
+    {
+        private readonly Channel<byte[]> inbound = Channel.CreateUnbounded<byte[]>();
+        private readonly Channel<VaultEvent> outbound = Channel.CreateUnbounded<VaultEvent>();
+
+        private WebSocketCloseStatus? closing;
+        private WebSocketState state = WebSocketState.Open;
+
+        public override WebSocketCloseStatus? CloseStatus => closing;
+
+        public override string? CloseStatusDescription => null;
+
+        public override WebSocketState State => state;
+
+        public override string? SubProtocol => VaultEvents.SubProtocol;
+
+        /// <summary>Queues a frame for the client to read.</summary>
+        internal void Deliver(VaultEvent frame) =>
+            inbound.Writer.TryWrite(
+                JsonSerializer.SerializeToUtf8Bytes(frame, DodoSshJsonContext.Default.VaultEvent));
+
+        /// <summary>Ends the socket, after everything already queued has been read.</summary>
+        internal void Close(WebSocketCloseStatus status)
+        {
+            closing = status;
+            inbound.Writer.TryWrite([]);
+        }
+
+        /// <summary>The next frame the client sent.</summary>
+        internal ValueTask<VaultEvent> SentAsync(CancellationToken cancellationToken) =>
+            outbound.Reader.ReadAsync(cancellationToken);
+
+        public override async Task<WebSocketReceiveResult> ReceiveAsync(
+            ArraySegment<byte> buffer,
+            CancellationToken cancellationToken)
+        {
+            var frame = await inbound.Reader.ReadAsync(cancellationToken);
+
+            // The empty frame Close queues. Reported as a close, exactly as a real socket does once the
+            // peer's close frame arrives.
+            if (frame.Length == 0)
+            {
+                state = WebSocketState.Closed;
+
+                return new WebSocketReceiveResult(
+                    0, WebSocketMessageType.Close, endOfMessage: true, closing, null);
+            }
+
+            frame.CopyTo(buffer.Array!, buffer.Offset);
+
+            return new WebSocketReceiveResult(frame.Length, WebSocketMessageType.Text, endOfMessage: true);
+        }
+
+        public override Task SendAsync(
+            ArraySegment<byte> buffer,
+            WebSocketMessageType messageType,
+            bool endOfMessage,
+            CancellationToken cancellationToken)
+        {
+            var json = Encoding.UTF8.GetString(buffer.Array!, buffer.Offset, buffer.Count);
+
+            if (JsonSerializer.Deserialize(json, DodoSshJsonContext.Default.VaultEvent) is { } frame)
+            {
+                outbound.Writer.TryWrite(frame);
+            }
+
+            return Task.CompletedTask;
+        }
+
+        public override void Abort() => state = WebSocketState.Aborted;
+
+        public override Task CloseAsync(
+            WebSocketCloseStatus closeStatus,
+            string? statusDescription,
+            CancellationToken cancellationToken) => CloseOutputAsync(
+            closeStatus, statusDescription, cancellationToken);
+
+        public override Task CloseOutputAsync(
+            WebSocketCloseStatus closeStatus,
+            string? statusDescription,
+            CancellationToken cancellationToken)
+        {
+            state = WebSocketState.Closed;
+
+            return Task.CompletedTask;
+        }
+
+        public override void Dispose() => state = WebSocketState.Closed;
+    }
+}
diff --git a/tests/DodoSSH.Client.App.Layout.Tests/StubTeamServer.cs b/tests/DodoSSH.Client.App.Layout.Tests/StubTeamServer.cs
index a8261ed..dce73c8 100644
--- a/tests/DodoSSH.Client.App.Layout.Tests/StubTeamServer.cs
+++ b/tests/DodoSSH.Client.App.Layout.Tests/StubTeamServer.cs
@@ -57,6 +57,17 @@ internal sealed class StubTeamServer : IVaultServer, ITeamApi, IVaultGrantApi
     /// <inheritdoc />
     public IKeyBindingAuthorizer KeyBinding => throw new NotSupportedException();
 
+    /// <summary>
+    /// A push channel that never pushes.
+    /// </summary>
+    /// <remarks>
+    /// Not <c>NotSupportedException</c> like its neighbours: the background synchronisation loop reads
+    /// this on every wait, so a layout test that opened a screen would throw from a timer thread rather
+    /// than draw anything. Waiting for ever is the honest stand-in — an offline layout test has no
+    /// server to be pushed from.
+    /// </remarks>
+    public IVaultEventStream Events => IdleVaultEventStream.Instance;
+
     /// <inheritdoc />
     public SyncOptions SyncOptions => new();
 
diff --git a/tests/DodoSSH.Client.App.Tests/FakeVaultEventStream.cs b/tests/DodoSSH.Client.App.Tests/FakeVaultEventStream.cs
new file mode 100644
index 0000000..209b7ce
--- /dev/null
+++ b/tests/DodoSSH.Client.App.Tests/FakeVaultEventStream.cs
@@ -0,0 +1,49 @@
+using System.Threading.Channels;
+using DodoSSH.Client.Api;
+using DodoSSH.Contracts;
+
+namespace DodoSSH.Client.App.Tests;
+
+/// <summary>
+/// A server's push channel, driven by a test rather than by a socket.
+/// </summary>
+/// <remarks>
+/// The real <c>VaultEventStream</c> is a reconnection policy wrapped round a WebSocket, and none of
+/// that is what the shell's behaviour depends on: what the shell does with a notice is the same
+/// whether it arrived over a healthy socket, after four reconnections, or from this. Driving it by
+/// hand is what makes "the loop synchronised because it was told to, not because a minute passed" a
+/// test that finishes in milliseconds and cannot flake.
+/// </remarks>
+internal sealed class FakeVaultEventStream : IVaultEventStream
+{
+    private readonly Channel<VaultEvent> notices = Channel.CreateUnbounded<VaultEvent>();
+
+    /// <inheritdoc />
+    public bool IsConnected => true;
+
+    /// <summary>How many times the shell has waited on this. Proves the loop is watching at all.</summary>
+    internal int Reads { get; private set; }
+
+    /// <summary>Delivers a notice, as a server would.</summary>
+    internal void Push(Guid vaultId, long sequence = 1) =>
+        notices.Writer.TryWrite(
+            new VaultEvent(VaultEventKinds.VaultChanged, vaultId, sequence));
+
+    /// <summary>Delivers the notice that says the caller's vault list has changed.</summary>
+    internal void PushAccessChanged() =>
+        notices.Writer.TryWrite(new VaultEvent(VaultEventKinds.VaultsChanged));
+
+    /// <inheritdoc />
+    public ValueTask<VaultEvent> ReadAsync(CancellationToken cancellationToken)
+    {
+        Reads++;
+
+        return notices.Reader.ReadAsync(cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public bool TryRead(out VaultEvent notice) => notices.Reader.TryRead(out notice!);
+
+    /// <inheritdoc />
+    public void Dispose() => notices.Writer.TryComplete();
+}
diff --git a/tests/DodoSSH.Client.App.Tests/FakeVaultServer.cs b/tests/DodoSSH.Client.App.Tests/FakeVaultServer.cs
index 932c4fe..8878091 100644
--- a/tests/DodoSSH.Client.App.Tests/FakeVaultServer.cs
+++ b/tests/DodoSSH.Client.App.Tests/FakeVaultServer.cs
@@ -39,6 +39,16 @@ internal sealed partial class FakeVaultServer : IVaultServer, IAccountApi, ISync
 
     internal int PushCount { get; private set; }
 
+    /// <summary>
+    /// How many delta reads this server has served.
+    /// </summary>
+    /// <remarks>
+    /// The one observable a synchronisation pass always produces. <see cref="PushCount"/> only moves when
+    /// there is something queued, so a test asking "did a pass run" — which is what the push channel's
+    /// whole purpose comes down to — has to count pulls.
+    /// </remarks>
+    internal int PullCount { get; private set; }
+
     internal bool IsEnrolled => statement is not null;
 
     /// <summary>
@@ -99,6 +109,19 @@ internal sealed partial class FakeVaultServer : IVaultServer, IAccountApi, ISync
     /// <inheritdoc />
     public IKeyBindingAuthorizer KeyBinding => this;
 
+    /// <summary>
+    /// The push channel, which a test drives by hand.
+    /// </summary>
+    /// <remarks>
+    /// A real queue rather than an idle stand-in, because the behaviour worth covering here is the one
+    /// the socket exists for: a notice arriving makes the background loop synchronise without waiting
+    /// out its minute. See <see cref="FakeVaultEventStream.Push"/>.
+    /// </remarks>
+    internal FakeVaultEventStream Notices { get; } = new();
+
+    /// <inheritdoc />
+    public IVaultEventStream Events => Notices;
+
     /// <inheritdoc />
     public SyncOptions SyncOptions => SyncOptions.Default;
 
@@ -238,6 +261,8 @@ internal sealed partial class FakeVaultServer : IVaultServer, IAccountApi, ISync
         SyncPullRequest request,
         CancellationToken cancellationToken)
     {
+        PullCount++;
+
         if (SyncFailure is { } failure)
         {
             return Task.FromException<SyncPullResponse>(failure);
diff --git a/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs b/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
index 1d6c39c..d77fde4 100644
--- a/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
+++ b/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
@@ -523,6 +523,90 @@ public sealed class ShellFlowTests : IAsyncLifetime
         vault.Status.ShouldContain("bad day");
     }
 
+    /// <summary>
+    /// The whole point of the push channel: a pass that did not wait for the minute.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The timing is what makes this an assertion rather than a hope. The background timer is a full
+    /// minute and the wait below gives up in ten seconds, so a pull that arrives can only have been
+    /// caused by the notice — there is no interval at which the timer could have produced it.
+    /// </para>
+    /// <para>
+    /// The vault id in the notice is arbitrary, and deliberately so: a pass synchronises every vault
+    /// this session can reach, so the loop reads the notice as "there is something to fetch" and never
+    /// as "fetch this one". A test that seeded a real id would imply a targeting this does not do.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task APushedNotice_SynchronisesWithoutWaitingForTheTimer()
+    {
+        await UnlockedAsync();
+
+        // The unlock starts the loop, whose first act is a pass; waited out so the count below is a
+        // baseline rather than a race with it.
+        await EventuallyAsync(
+            () => server.PullCount > 0,
+            "the pass on open should have run");
+
+        var before = server.PullCount;
+
+        server.Notices.Push(Guid.CreateVersion7());
+
+        await EventuallyAsync(
+            () => server.PullCount > before,
+            "a notice should have woken the loop long before the one-minute timer");
+    }
+
+    /// <remarks>
+    /// The half that is easy to get wrong. The loop selects between two waits, and both have to survive
+    /// losing: <c>PeriodicTimer</c> throws if a second wait is started while one is outstanding, and an
+    /// abandoned channel read stays registered and swallows the next notice written. Either defect
+    /// leaves the first notice working and every one after it silently lost, which is why one notice is
+    /// not enough to prove this.
+    /// </remarks>
+    [Fact]
+    public async Task NoticesKeepWakingTheLoop_NotJustTheFirst()
+    {
+        await UnlockedAsync();
+
+        await EventuallyAsync(() => server.PullCount > 0, "the pass on open should have run");
+
+        for (var round = 1; round <= 3; round++)
+        {
+            var before = server.PullCount;
+
+            server.Notices.Push(Guid.CreateVersion7());
+
+            await EventuallyAsync(
+                () => server.PullCount > before,
+                $"notice {round} should have woken the loop as the first one did");
+        }
+    }
+
+    /// <summary>Waits for something a background loop is expected to do, or fails saying what.</summary>
+    /// <remarks>
+    /// Polled rather than signalled because the thing under test is a loop nobody hands a completion
+    /// source to. The bound is generous — this is not measuring latency, only proving that the timer
+    /// cannot be what caused the result.
+    /// </remarks>
+    private static async Task EventuallyAsync(Func<bool> condition, string because)
+    {
+        var deadline = TimeProvider.System.GetUtcNow().AddSeconds(10);
+
+        while (TimeProvider.System.GetUtcNow() < deadline)
+        {
+            if (condition())
+            {
+                return;
+            }
+
+            await Task.Delay(TimeSpan.FromMilliseconds(20), Token);
+        }
+
+        throw new ShouldAssertException(because);
+    }
+
     /// <remarks>
     /// <para>
     /// The page's own <c>term.focus()</c> focuses the textarea inside the document, which does nothing

From d02d103569c3e91df3cc247e458d52d6c5da2964 Mon Sep 17 00:00:00 2001
From: Jaap-Jan de Wit | DodoTech <jaap-jan@dodotech.dev>
Date: Tue, 4 Aug 2026 16:39:14 +0200
Subject: [PATCH 6/7] Take the group's EDIT and DELETE off the heading row
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A pair of buttons sat at the end of the GROUPS heading, and the card's own
right-click menu arrived later offering the same two things. Two controls for one
job, and the buttons were the harder of the two to read: a button beside a
heading has no card under a pointer to mean, so it had to work its subject out —
the selected card, or failing that the group the trail ends with, which once a
group is open is not a card on screen at all. The menu never has that problem,
because opening it is what aims it.

The menu is the whole of Edit and Delete on the desktop now. ShowsGroupActions
went with the buttons, since hiding them was all it did. GroupTarget stays: the
menu's two entries read it after the code-behind has selected whatever was
right-clicked, and its fallback to the open group is what makes + NEW HOST open
on the group somebody is standing in rather than on none.

One case changes shape. Opening a group with nothing inside it folds the card
grid away, so from in there nothing can be right-clicked — renaming that group
means pressing the trail back one level, to where it has a card of its own. The
buttons used to cover it through the fallback. The trail was already the way out
of an empty group, and 3.2a says so now.

The test that pressed EDIT through its binding is replaced by one holding that
no button on the screen commands either of them, which is the failure worth
catching: a button coming back is not a compile error, and it would draw itself
in place, aimed at the group the trail ends with. What that test covered — a
command that has to accept an empty parameter, and act on the card the pointer
was on — the two menu tests beside it already do.
---
 docs/manual-checks.md                         | 16 ++++---
 .../Views/HostsScreen.axaml                   | 41 ++++++----------
 .../Views/HostsScreen.axaml.cs                |  4 +-
 .../ViewModels/VaultViewModel.cs              | 39 +++++++--------
 .../HostGridTests.cs                          | 48 ++++++++-----------
 5 files changed, 63 insertions(+), 85 deletions(-)

diff --git a/docs/manual-checks.md b/docs/manual-checks.md
index 460c146..90d8ef1 100644
--- a/docs/manual-checks.md
+++ b/docs/manual-checks.md
@@ -324,7 +324,8 @@ phone's, whose list has no room for a row of group cards and draws the whole tre
 host filed, the grid says so in a sentence rather than sitting empty.
 
 **Then press a group card once.** It is marked as chosen and **nothing else happens** — the grid is still the
-level it was, and EDIT and DELETE now aim at that group. **Then double-press it.** The group opens: its hosts
+level it was, and no buttons appear beside the GROUPS heading: editing and deleting a group are on the card's
+own right-click menu, which is 7.9. **Then double-press it.** The group opens: its hosts
 are the grid, the trail above the cards reads `ALL HOSTS › <name> ›`, each card carrying the group's name as
 an accent chip, and the card grid shows what is *inside* that group rather than every group in the keychain.
 Pressing ALL HOSTS goes back to the outermost level.
@@ -347,9 +348,9 @@ Make two groups and file one under the other with the parent picker in the group
 
 **Pass:** only the outer group has a card to start with. Double-press it and the inner one is the only card
 shown, with the trail reading `ALL HOSTS › <outer> ›`. Double-press that, and the cards disappear entirely —
-it has nothing inside it — while the trail, EDIT and DELETE stay: with no card selected the two buttons act
-on the group the trail ends with, so a group with nothing in it can still be renamed after being opened.
-Pressing the **middle** crumb goes back one level rather than all the way out.
+it has nothing inside it — while the trail stays. Pressing the **middle** crumb goes back one level rather
+than all the way out, which is also how a group with nothing inside it is renamed: back out to the level
+where it has a card, and right-click that.
 
 **Failure means:** cards for groups that are not at this level is `VisibleGroups` having been bound past —
 the flat `Groups` is the phone's and the lookups'. A group that cannot be reached at all is worse and is the
@@ -370,7 +371,7 @@ takes only the group that is open.
 
 ### 3.3 Deleting a group with hosts in it
 
-Select a group with hosts and press DELETE.
+Right-click a group with hosts in it and choose **Delete…**.
 
 **Pass:** the question names how many hosts are filed under it and says they stay. Agreeing removes the
 group; the hosts lose their chip and are otherwise unchanged.
@@ -802,8 +803,9 @@ Delete.
 card, rather than back out to ALL HOSTS. Right-clicking the space around the group cards opens no menu.
 
 **Failure means:** the menu is reading `GroupTarget`'s fallback, which is the group whose contents are on
-screen. That fallback is right for the EDIT and DELETE buttons beside the heading and wrong for a menu that
-opened on a card.
+screen rather than the card the pointer is on. This menu is the only way to edit or delete a group on the
+desktop — there are no buttons beside the GROUPS heading any more — so a menu aimed wrongly is the whole of
+the mistake.
 
 ### 7.10 Clicking a host in the palette connects
 
diff --git a/src/DodoSSH.Client.App/Views/HostsScreen.axaml b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
index 7a3cc5d..e55b92e 100644
--- a/src/DodoSSH.Client.App/Views/HostsScreen.axaml
+++ b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
@@ -226,25 +226,14 @@
               </ItemsControl.ItemTemplate>
             </ItemsControl>
 
-            <Grid ColumnDefinitions="Auto,*,Auto">
-              <TextBlock Grid.Column="0" Classes="label" Text="GROUPS"
-                         Foreground="{StaticResource TextDim}" VerticalAlignment="Center" />
-
-              <!--
-                The group's own two actions, beside the group cards rather than in the toolbar, because they
-                act on the card that is selected — and this is where the selection is made. Hidden rather
-                than disabled while DELETE's question is up, as every other pair in this application is, so
-                it cannot be pressed twice, and hidden again when there is nothing for them to act on. What
-                that is, with no card selected, is the group the trail above ends with; see
-                VaultViewModel.GroupTarget.
-              -->
-              <StackPanel Grid.Column="2" Orientation="Horizontal" Spacing="6">
-                <Button Classes="ghost" Content="EDIT" Command="{Binding EditGroupCommand}"
-                        IsVisible="{Binding ShowsGroupActions}" />
-                <Button Classes="ghost" Content="DELETE" Command="{Binding DeleteGroupCommand}"
-                        IsVisible="{Binding ShowsGroupActions}" />
-              </StackPanel>
-            </Grid>
+            <!--
+              The heading and nothing else. This used to be a row with EDIT and DELETE at the far end of it,
+              and the card's own menu is where both live now — see the note on it below. They were a second
+              control for the job that menu already does, and the harder of the two to read: a button beside
+              a heading has to say which card it means, and with none selected it meant the group the trail
+              ends with rather than anything on screen.
+            -->
+            <TextBlock Classes="label" Text="GROUPS" Foreground="{StaticResource TextDim}" />
 
             <Border Padding="10" Background="{StaticResource DangerWash}" CornerRadius="6"
                     IsVisible="{Binding IsConfirmingGroupDeletion}">
@@ -269,8 +258,8 @@
 
               ◆ THIS IS ONE LEVEL, NOT EVERY GROUP. It binds VisibleGroups: what is inside the group the
               trail above ends with, or the outermost groups when it ends at ALL HOSTS. Folded away entirely
-              at a group with nothing inside it, which is an ordinary thing to open — the trail and the two
-              buttons stay, because leaving it is a gesture and editing it is a button.
+              at a group with nothing inside it, which is an ordinary thing to open — the trail stays, and
+              it is also the way back to the level where that group has a card of its own to be edited from.
 
               ◆ THESE CARDS ARE THE DROP TARGET. A host card dragged onto one is filed under that group, and
               that is the whole of what a drag does on this screen. It used to be a heading inside the host
@@ -295,11 +284,11 @@
                 context; the code-behind selects whatever was right-clicked before the menu opens, and
                 cancels it outright over the space around the cards.
 
-                Open is here as well as on the double-click, and Edit and Delete as well as on the two
-                buttons above, and neither is a duplicate for its own sake: a gesture is unreachable without
-                a pointer, and the buttons act on GroupTarget — which with no card selected is the group the
-                trail ends with rather than the one under the pointer. This menu is the one place all three
-                act on the card that was right-clicked.
+                Open is here as well as on the double-click, which is not a duplicate for its own sake: a
+                gesture is unreachable without a pointer. Edit and Delete are here and nowhere else — they
+                were also a pair of buttons beside the heading above, which acted on GroupTarget and so with
+                no card selected meant the group the trail ends with rather than any card on screen. All
+                three act on the card that was right-clicked, which is the whole of what this menu is for.
 
                 Only Open takes a parameter, because OpenGroupCommand's null means ALL HOSTS rather than
                 nothing; Edit and Delete read GroupTarget, which the selection the code-behind has just made
diff --git a/src/DodoSSH.Client.App/Views/HostsScreen.axaml.cs b/src/DodoSSH.Client.App/Views/HostsScreen.axaml.cs
index 35adc4f..07fc0f5 100644
--- a/src/DodoSSH.Client.App/Views/HostsScreen.axaml.cs
+++ b/src/DodoSSH.Client.App/Views/HostsScreen.axaml.cs
@@ -217,8 +217,8 @@ internal sealed partial class HostsScreen : UserControl
     /// The host grid's rule, applied to the cards above it — see <see cref="OnContextRequested"/>. What is
     /// different is what an unaimed menu would have done: <c>GroupTarget</c> falls back to the open group
     /// when no card is selected, so Edit and Delete over a card would have been offered about the group whose
-    /// contents are showing rather than the one the pointer is on. That fallback is right for a pair of
-    /// buttons that sit beside the heading and wrong for a menu that opened on a card.
+    /// contents are showing rather than the one the pointer is on. This menu is the only way to either of
+    /// them now, so aiming it is the whole of aiming them.
     /// </para>
     /// <para>
     /// Cancelled outright over the space around the cards, as the host grid's is. That is not a group, and
diff --git a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
index 860fbf8..14407e5 100644
--- a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
+++ b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
@@ -1466,7 +1466,7 @@ internal sealed partial class VaultViewModel(
     /// </para>
     /// <para>
     /// <b>Separate from <see cref="SelectedGroup"/>, and no longer sets it.</b> The two answer different
-    /// questions — "what is on screen" and "what would EDIT and DELETE act on" — and while one click meant
+    /// questions — "what is on screen" and "which card is chosen" — and while one click meant
     /// both there was no way to name a group without also narrowing the grid to it. Two gestures, two
     /// properties; <see cref="GroupTarget"/> is where the two meet.
     /// </para>
@@ -2584,26 +2584,23 @@ internal sealed partial class VaultViewModel(
     internal bool IsConfirmingGroupDeletion => PendingDeletion?.Target is DeletionTarget.Group;
 
     /// <summary>
-    /// What the group panel's EDIT and DELETE act on: the card that is selected, or the group that is open.
+    /// What a group command with no argument acts on: the card that is selected, or the group that is open.
     /// </summary>
     /// <remarks>
-    /// Two answers, because a card is no longer where the user is. Selecting one aims the buttons at it,
-    /// which is what a click has always done; with nothing selected they aim at the group whose contents are
-    /// on screen — the one the trail ends with. Without that fallback a group with no groups inside it could
-    /// be opened and then never edited, because opening a group is exactly what takes its own card off the
-    /// screen. It is also what a file manager does: act on the selection, and on the current folder when
-    /// there is none.
+    /// Two answers, because a card is no longer where the user is. Selecting one aims at it, which is what a
+    /// click has always done; with nothing selected the answer is the group whose contents are on screen —
+    /// the one the trail ends with. That fallback is what makes + NEW HOST open on the group somebody is
+    /// standing in rather than on none, and it is what a file manager does: act on the selection, and on the
+    /// current folder when there is none.
+    /// <para>
+    /// The desktop's Edit and Delete reach this through the card menu, which selects whatever was
+    /// right-clicked first, so the fallback is not what they read — see <c>HostsScreen.OnGroupContextRequested</c>.
+    /// They used to be a pair of buttons beside the GROUPS heading, which had no card under a pointer to
+    /// mean and so leaned on it.
+    /// </para>
     /// </remarks>
     internal HostGroupRowViewModel? GroupTarget => SelectedGroup ?? GroupFilter;
 
-    /// <summary>Whether the group panel's buttons are showing.</summary>
-    /// <remarks>
-    /// Hidden with nothing to act on as well as while the question is up. A pair of buttons over a grid of
-    /// cards nobody has chosen between is a pair whose subject the user has to work out, and the answer
-    /// would be "neither" — see <see cref="GroupTarget"/>.
-    /// </remarks>
-    internal bool ShowsGroupActions => GroupTarget is not null && !IsConfirmingGroupDeletion;
-
     /// <summary>Whether this vault has any groups, which is what makes the sidebar draw headings.</summary>
     internal bool HasGroups => Groups.Count > 0;
 
@@ -4743,8 +4740,9 @@ internal sealed partial class VaultViewModel(
     /// <summary>Loads the group being acted on into the box, so saving renames it.</summary>
     /// <param name="group">
     /// The group to edit, or null for whatever the screen is aimed at — the selected card, or the open group
-    /// when no card is selected. See <see cref="GroupTarget"/>. The desktop's EDIT button passes nothing and
-    /// means the second; the phone has no card to select and passes the group its heading names.
+    /// when no card is selected. See <see cref="GroupTarget"/>. The desktop's card menu passes nothing and
+    /// means the card that was right-clicked, which opening the menu has already selected; the phone has no
+    /// card to select and passes the group its heading names.
     /// </param>
     /// <remarks>
     /// Taking it as an argument is what keeps the phone from having to select a group in order to edit one.
@@ -5110,7 +5108,7 @@ internal sealed partial class VaultViewModel(
     /// up under the ungrouped heading — so what the user needs to know is exactly how many machines are about
     /// to move, and that none of them are going anywhere else.
     /// <para>
-    /// Aims where EDIT does: at the selected card, or at the open group when no card is selected. See
+    /// Aims where Edit does: at the selected card, which on the desktop is the one the menu opened on. See
     /// <see cref="GroupTarget"/>.
     /// </para>
     /// </remarks>
@@ -8067,7 +8065,6 @@ internal sealed partial class VaultViewModel(
         DisarmIfAimedElsewhere(DeletionTarget.Group, GroupTarget?.EntityId);
 
         OnPropertyChanged(nameof(GroupTarget));
-        OnPropertyChanged(nameof(ShowsGroupActions));
     }
 
     /// <remarks>
@@ -8088,7 +8085,6 @@ internal sealed partial class VaultViewModel(
         DisarmIfAimedElsewhere(DeletionTarget.Group, GroupTarget?.EntityId);
 
         OnPropertyChanged(nameof(GroupTarget));
-        OnPropertyChanged(nameof(ShowsGroupActions));
 
         RebuildGroupLevel();
         RebuildVisibleHosts();
@@ -8101,7 +8097,6 @@ internal sealed partial class VaultViewModel(
         OnPropertyChanged(nameof(IsConfirmingGroupDeletion));
         OnPropertyChanged(nameof(ShowsHostActions));
         OnPropertyChanged(nameof(ShowsHostPaneActions));
-        OnPropertyChanged(nameof(ShowsGroupActions));
         OnPropertyChanged(nameof(ShowsItemActions));
     }
 
diff --git a/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs b/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
index 0311c7b..8dfe995 100644
--- a/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
+++ b/tests/DodoSSH.Client.App.Layout.Tests/HostGridTests.cs
@@ -166,9 +166,9 @@ public sealed class HostGridTests : IAsyncLifetime
     /// <remarks>
     /// <para>
     /// The host grid's menu acts on nothing when it is not aimed; this one acts on the <em>wrong group</em>.
-    /// <c>GroupTarget</c> falls back to the group whose contents are on screen when no card is selected — the
-    /// right answer for the pair of buttons beside the heading, and the wrong one for a menu that opened on a
-    /// card, which would then offer to delete a group the pointer is nowhere near.
+    /// <c>GroupTarget</c> falls back to the group whose contents are on screen when no card is selected, and
+    /// a menu that opened on a card would then offer to delete a group the pointer is nowhere near. It is
+    /// also the only way to Edit or Delete a group on the desktop, so this is the only place it is aimed.
     /// </para>
     /// <para>
     /// Open is the one entry that takes a parameter, because <c>OpenGroupCommand</c>'s null is a real
@@ -287,10 +287,10 @@ public sealed class HostGridTests : IAsyncLifetime
 
     /// <remarks>
     /// <para>
-    /// The rule one press was split into two gestures for. Selecting a group aims its EDIT and DELETE at it
-    /// and does nothing else; opening one is what narrows the grid, and the trail is the way back out of it.
-    /// While a single press meant both, a group could not be named without every host outside it leaving the
-    /// screen at the same moment.
+    /// The rule one press was split into two gestures for. Selecting a group marks it and does nothing else;
+    /// opening one is what narrows the grid, and the trail is the way back out of it. While a single press
+    /// meant both, a group could not be named without every host outside it leaving the screen at the same
+    /// moment.
     /// </para>
     /// <para>
     /// Driven through the properties the cards bind rather than through a click, because what is worth
@@ -299,7 +299,7 @@ public sealed class HostGridTests : IAsyncLifetime
     /// </para>
     /// </remarks>
     [Fact]
-    public async Task SelectingAGroupAimsItsButtonsAtItAndOpeningOneNarrowsTheGrid()
+    public async Task SelectingAGroupMarksItAndOpeningOneNarrowsTheGrid()
     {
         await vault.MoveHostToGroupCommand.ExecuteAsync(
             new HostGroupMove(Row(vault, "prod-db"), vault.Groups.Single().EntityId));
@@ -312,8 +312,7 @@ public sealed class HostGridTests : IAsyncLifetime
         vault.GroupFilter.ShouldBeNull("one press selects a group and does not open it");
         vault.VisibleHosts.Select(row => row.Label)
             .ShouldBe(["stage-web"], "so the grid is still the outermost level, and prod-db is inside a group");
-        vault.GroupTarget.ShouldBeSameAs(production, "what EDIT and DELETE act on");
-        vault.ShowsGroupActions.ShouldBeTrue();
+        vault.GroupTarget.ShouldBeSameAs(production, "what a group command with no argument acts on");
 
         vault.OpenGroupCommand.Execute(production);
 
@@ -324,7 +323,7 @@ public sealed class HostGridTests : IAsyncLifetime
 
         vault.SelectedGroup.ShouldBeNull("the card it was on is not one of the cards on screen any more");
         vault.GroupTarget.ShouldBeSameAs(
-            production, "so the buttons fall back to the group whose contents are showing");
+            production, "so an unaimed command falls back to the group whose contents are showing");
 
         // Back out, which is the trail's first crumb and nothing else: SHOW ALL was a second control for the
         // same job and went with the change.
@@ -333,7 +332,6 @@ public sealed class HostGridTests : IAsyncLifetime
         vault.VisibleHosts.Select(row => row.Label)
             .ShouldBe(["stage-web"], "ALL HOSTS is the outermost level, not every host in the keychain");
         vault.GroupTarget.ShouldBeNull("and nothing is aimed at once no group is open or selected");
-        vault.ShowsGroupActions.ShouldBeFalse("a pair of buttons with no subject is hidden rather than shown");
     }
 
     /// <summary>
@@ -376,35 +374,29 @@ public sealed class HostGridTests : IAsyncLifetime
             vault.SelectedGroup.ShouldBeNull("and the same in the other direction");
             screen.GroupGrid.SelectedItem.ShouldBeNull();
             GroupCard(screen).IsSelected.ShouldBeFalse();
-            vault.ShowsGroupActions.ShouldBeFalse("so the group's own two buttons have nothing to act on");
         });
     }
 
     /// <remarks>
-    /// EDIT takes the group as an argument now, so that the phone can open the editor on a heading without
-    /// selecting a group and losing the host selection to it — see <c>VaultViewModel.EditGroup</c>. The
-    /// button beside the cards passes nothing and means "the card that is selected", which is the half of
-    /// that change that would fail silently: a command refusing a null parameter is a button that never
-    /// fires, and nothing about the markup would say so.
+    /// A pair of EDIT and DELETE buttons used to sit beside the GROUPS heading, and the card's own menu is
+    /// the whole of both now — the menu came second and did the same job better, since it acts on the card
+    /// under the pointer rather than on <c>GroupTarget</c>. Held here because a button coming back is not a
+    /// compile error and barely a visible one: it would draw itself in place, aimed with no card selected at
+    /// the group the trail ends with, which is the mistake the two menu tests above exist to catch.
     /// </remarks>
     [Fact]
-    public async Task TheGroupsEditButtonStillActsOnTheSelectedCard()
+    public async Task AGroupsEditAndDeleteAreOnItsCardsMenuAndNowhereElse()
     {
         await OnTheGridAsync((screen, _) =>
         {
             vault.SelectedGroup = vault.VisibleGroups.Single();
             Dispatcher.UIThread.RunJobs();
 
-            var edit = screen.GetVisualDescendants()
+            screen.GetVisualDescendants()
                 .OfType<Button>()
-                .Single(button => ReferenceEquals(button.Command, vault.EditGroupCommand));
-
-            edit.IsEffectivelyEnabled.ShouldBeTrue("the command has to accept the button's empty parameter");
-
-            edit.Command.ShouldNotBeNull().Execute(edit.CommandParameter);
-
-            vault.IsEditingGroup.ShouldBeTrue();
-            vault.GroupEditorLabel.ShouldBe("production", "the card that was selected");
+                .Where(button => ReferenceEquals(button.Command, vault.EditGroupCommand)
+                    || ReferenceEquals(button.Command, vault.DeleteGroupCommand))
+                .ShouldBeEmpty("a selected group card puts no buttons on the screen");
         });
     }
 

From a86731ee08487df06418b9df75631c116e77aec9 Mon Sep 17 00:00:00 2001
From: Jaap-Jan de Wit | DodoTech <jaap-jan@dodotech.dev>
Date: Tue, 4 Aug 2026 17:04:06 +0200
Subject: [PATCH 7/7] Move the shelf as well as what is on it, and ask what a
 deletion takes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two things about a group, and they turn out to be the same argument twice.

**A group can be moved to another vault, and it takes everything on it.** The
host's move shipped last week and stopped one level too low: moving twenty
machines into a shared vault meant twenty trips through a menu, and each one
arrived stripped of the group it had been filed under, so the shelf had to be
rebuilt by hand on the other side. Moving the shelf is what people were
attempting. MOVE sits between EDIT and DELETE over the group cards, and on the
card's own menu above the separator DELETE is below — the same place, and the
same reasoning, as the host pane's ⋯ entry.

**The whole subtree goes, and taking less was never coherent.** A group's
children are items of the vault it is leaving, so a parent moved alone leaves
them naming a tombstone and they surface as roots in the vault the user has just
emptied: half a shelf here and half there, from one gesture that said "move
this". The hosts are the same argument and are the half the request was about.

The groups go first, top down, and the hosts last. Each item is re-sealed under
the destination's key and takes a new id — VaultItemRepository.MoveAsync, which
HostGroupRepository now exposes — so nothing pointing at a group can be written
until that group has landed and its new id is known, and a child's parent must
already be over there. What an interruption leaves is therefore hosts still in
the vault they started in, under UNGROUPED: visible, and re-movable. The reverse
order would leave hosts in the destination filed under nothing.

The parent stays behind and the tags are dropped, which is the host move's rule
one level up: both are items of the vault being left, so a reference carried
across would resolve on the machine that moved it and dangle for everybody else
in the destination. The moved group arrives at the top level, and the panel says
so before the press rather than the status line saying it after. Keys and
passwords are kept — those genuinely resolve across vaults, and clearing them
would take a working host and make one that cannot connect — and any now outside
the destination is named, because that is precisely what the other members of it
will not be able to resolve.

Refused as a whole where anything under the group was written by a newer client,
rather than skipped item by item: a move that left behind what it could not
re-encode would file some of the shelf in one vault and the rest in the other,
which is the state this exists to prevent. Refused with a host editor open, as
the drop gesture is, because it rewrites hosts. And the walk carries a visited
set, for the reason every walk over this tree does: a group that is its own
parent — which two offline clients can build and no editor was ever shown —
would otherwise be appended to the move list for as long as there was memory.

**Deleting a group now asks what should become of the hosts under it, and that
reverses a decision this repository had written down.** The deletion did not
touch them: the reference was left dangling, the list resolved it to nothing,
and the machines turned up under UNGROUPED. That was right for one of the two
things people delete a group for and wrong for the other — a heading being tidied
away should leave its machines alone, and a project that has been decommissioned
is a shelf and everything on it — and nothing in the code can tell which of the
two it is looking at. So it is asked.

A tick rather than a pair of options, because the two answers are not equally
weighted: keeping the hosts is recoverable and deleting them is not, so the safe
answer is the one that needs no decision. It is off on every question, including
the one that disarms it, or a tick left standing would destroy the next group's
machines on the strength of a decision about the last one's.

Once the deletion knows which hosts it means, leaving them naming something that
has gone is a state kept for no reason, so the unticked answer writes too: N
hosts with the reference cleared, where the ticked one writes N tombstones. That
is the N writes HostGroupRepository refuses to hide behind a DeleteAsync
overload, made where somebody asked for them and where the count is on screen
first. The nested groups take the deleted group's place in the tree rather than
being orphaned to the top level. A read-only host is skipped, counted and named,
because unfiling it would re-encode a payload this build cannot represent — and
the cost of skipping is a dangling id, which every reader here already survives.

**Both are the desktop's alone**, and that is not an omission. The phone draws
groups as headings in the host list and has never had a way to delete or move
one; the two panels take the row of buttons over the group cards, and there is
no such row on a 360dp screen to take.

One test had to change its premise rather than its assertion.
EditingAHostWhoseGroupIsGone built its dangling reference by deleting the group,
which now unfiles instead — so it imports a host naming an id nothing resolves,
which is what a group deleted on another machine actually looks like and is the
only way that state still arises. The picker's placeholder is still needed and
still covered.

Four places said an item could not be moved between vaults. Two were about a
group and were true when written; the other two were left stale by the host's
move. All four now say what is true, including the design gaps document, where
the chevron beside the vault name stays undrawn for the reason it already had.
---
 README.md                                     |  28 +
 docs/design-import-gaps.md                    |   2 +-
 .../Views/ConfirmDeleteCard.axaml             |  15 +
 src/DodoSSH.Client.App/Views/HostDrawer.axaml |  15 +-
 .../Views/HostsScreen.axaml                   |  61 +-
 .../ViewModels/VaultViewModel.cs              | 702 +++++++++++++++++-
 .../HostGroupRepository.cs                    |  37 +-
 .../ScreenLayoutTests.cs                      |  41 +-
 .../ShellFlowTests.cs                         | 151 +++-
 .../VaultSharingTests.cs                      | 149 ++++
 10 files changed, 1125 insertions(+), 76 deletions(-)

diff --git a/README.md b/README.md
index 1ea0717..e136ce2 100644
--- a/README.md
+++ b/README.md
@@ -352,6 +352,24 @@ vault it is leaving. A picker inside the form would do all of that as a side eff
 What a move cannot do is reach a machine that has already synced the host, which is the same limit
 everything else about revocation has. Keys, passwords and buckets take theirs from a standing "new items go
 to" picker on the Keychain screen and cannot be moved yet.
+
+**A group can be moved too, and it takes its contents with it** — MOVE beside EDIT and DELETE over the group
+cards, or "Move to another vault…" on the card's own menu. That is the desktop only, because the phone draws
+groups as headings in the host list and has never had a way to delete or move one. It is the same re-seal
+and tombstone underneath, applied to every item involved: the group, the groups nested inside it, and every
+host filed under any of them, each taking a new id in the destination. Moving less than that was never
+coherent — the machines and the child groups are items of the vault the group is leaving, so a group that
+travelled alone would leave half a shelf behind. What stays is the group it was itself nested under, which
+belongs to the old vault, so it arrives at the top level; the hosts' tags stay for the same reason. Keys and
+passwords are kept, because those genuinely resolve across vaults, and the sentence afterwards names any
+that are now outside the destination.
+
+**Deleting a group asks what should become of the hosts under it.** The default answer keeps them: the
+reference is cleared and they move to UNGROUPED. Ticking the box deletes them with it. Both answers are a
+change — the deletion used to leave the hosts holding an id that no longer resolved, which looked the same
+and cost nothing, and stopped being the right shape once the deletion could take them with it. A group with
+nothing filed under it is not asked. Whichever answer is given, the groups nested inside take the deleted
+group's place in the tree rather than being orphaned to the top level.
 Both default to your personal vault and neither moves on its own, because an item put in a shared vault is
 visible to everybody holding that vault's key. Choosing a vault in the host editor also decides which groups
 it can be filed under: a group is an item like any other and lives in exactly one vault.
@@ -598,6 +616,16 @@ keychain plus a terminal — and the spike that gates all of it.
   than to a shell that never opens. Given a walk that had to be cycle-safe anyway, refusing to nest bought
   nothing.
 
+  Membership living on the host has one further consequence, and it took two goes to settle. Deleting a
+  group could not clear it without rewriting every host under the heading, so at first it did not: the hosts
+  kept an id that resolved to nothing and turned up under UNGROUPED, which reads identically and costs no
+  writes. That held until the deletion had to be able to take the hosts *with* it — a group is sometimes a
+  heading being tidied away and sometimes a project that has been decommissioned, and nothing in the code can
+  tell which. Once a deletion knows which hosts it means, leaving them naming something that has gone is a
+  state kept for no reason, so both answers now write: N deletions, or N hosts with the reference cleared.
+  The dangling case still has to be survived everywhere it is read, because a group deleted on *another*
+  machine arrives exactly that way.
+
   Inserting a snippet types it at the prompt and stops. Pressing Enter is a per-snippet decision, off by
   default, and the reason is worth stating: a terminal is one input stream with no notion of being at a
   prompt — the remote may be in an editor, or at a password prompt with the echo off — so this client cannot
diff --git a/docs/design-import-gaps.md b/docs/design-import-gaps.md
index 027f97d..0292ce6 100644
--- a/docs/design-import-gaps.md
+++ b/docs/design-import-gaps.md
@@ -157,7 +157,7 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
 > | **Add Telnet**, and **Serial** in the toolbar | Omitted. `ISshConnection` is the only transport there is. This is also why the card subtitle's `ssh` is a constant today rather than a reading — it is stated in `HostRowViewModel.Summary`, which is the one place in this interface where a constant is printed on purpose. |
 > | **+ SSH ID, Certificate, FIDO2** | Omitted. `IDENTITIES` and `CERTIFICATES` have been on this document's list since the first import — neither is even a reserved `SyncEntityType` — and there is no security-key path anywhere in the SSH layer. One control offering three item types that do not exist. |
 > | The **Backspace / Default** row | Omitted. It is a terminal setting, and the client has no preferences store and no frame to carry one to the renderer — see the Preferences section. It would be a control whose value could not survive the window closing. |
-> | The **chevron beside the vault name** | The name alone, and the move behind the pane's ⋯ menu instead. A host *can* now be moved between vaults, so the gap is no longer that there is nothing to offer — it is that a chevron on a subtitle implies an edit, and this is not one: the two vaults are encrypted under different keys, so it is a re-seal into one and a tombstone in the other, the host takes a new id, and its group and tags stay behind. A control that implied "just change this field" would be describing something else. Where a *new* host goes is still asked in the host editor, as a picker beside the name; keys, passwords and buckets take theirs from the keychain screen's standing picker and cannot be moved yet. |
+> | The **chevron beside the vault name** | The name alone, and the move behind the pane's ⋯ menu instead. A host *can* now be moved between vaults, so the gap is no longer that there is nothing to offer — it is that a chevron on a subtitle implies an edit, and this is not one: the two vaults are encrypted under different keys, so it is a re-seal into one and a tombstone in the other, the host takes a new id, and its group and tags stay behind. A control that implied "just change this field" would be describing something else. Where a *new* host goes is still asked in the host editor, as a picker beside the name. A group moves too, from MOVE over the group cards, and takes its nested groups and every host filed under them; keys, passwords and buckets take theirs from the keychain screen's standing picker and cannot be moved yet. |
 > | **Show more ⌄** | Not drawn as a disclosure. What it would hide — notes, the relay switch, forgetting the host key — is in the editor, one press away, and a second fold inside a pane that already scrolls is a second place for a field to be missing from. |
 > | **Port Forwarding** in the sidebar | Nothing, for the third time in this document. |
 > | The host grid's toolbar avatar, share and tag-filter controls | Omitted, as in v3 and for the same reasons. |
diff --git a/src/DodoSSH.Client.App/Views/ConfirmDeleteCard.axaml b/src/DodoSSH.Client.App/Views/ConfirmDeleteCard.axaml
index 0d08387..93b1e01 100644
--- a/src/DodoSSH.Client.App/Views/ConfirmDeleteCard.axaml
+++ b/src/DodoSSH.Client.App/Views/ConfirmDeleteCard.axaml
@@ -41,6 +41,21 @@
                  Text="{Binding PendingDeletion.Usage}" />
     </Border>
 
+    <!--
+      The second question, and only a group's deletion has one: whether the machines filed under it go with
+      it. See VaultViewModel.DeleteGroup for why it is asked rather than stated, and DeletionTakesTheHostsToo
+      for why it is a tick rather than a pair of options — the two answers are not equally weighted, and the
+      recoverable one is the one that needs no decision.
+
+      Below the usage box on purpose: that box is the count this is about, and a tick offered above the
+      number it applies to is a tick somebody answers before reading how many.
+    -->
+    <CheckBox IsVisible="{Binding PendingDeletion.HasChoice, FallbackValue=False}"
+              IsChecked="{Binding DeletionTakesTheHostsToo}">
+      <TextBlock Foreground="{StaticResource WarnText}" FontSize="12" TextWrapping="Wrap"
+                 Text="{Binding PendingDeletion.Choice}" />
+    </CheckBox>
+
     <StackPanel Orientation="Horizontal" Spacing="6">
       <Button Classes="danger" Content="DELETE" Command="{Binding ConfirmDeleteCommand}"
               IsEnabled="{Binding !IsBusy}" />
diff --git a/src/DodoSSH.Client.App/Views/HostDrawer.axaml b/src/DodoSSH.Client.App/Views/HostDrawer.axaml
index c8a0a04..08dffe6 100644
--- a/src/DodoSSH.Client.App/Views/HostDrawer.axaml
+++ b/src/DodoSSH.Client.App/Views/HostDrawer.axaml
@@ -55,10 +55,11 @@
     renderer. They are listed in docs/design-import-gaps.md with what ships instead, and none of them is
     drawn disabled.
 
-    The design's fifth missing control was the vault picker's chevron, and half of it now exists: a host
-    being *created* is asked which vault it goes into, in the editor below. What still does not exist is
-    the other half — moving an existing host — because the two vaults are encrypted under different keys,
-    so that is a delete and a retype rather than an edit.
+    The design's fifth missing control was the vault picker's chevron, and both halves of what it stood for
+    now exist without it: a host being *created* is asked which vault it goes into, in the editor below, and
+    an existing one is moved from the pane's ⋯ menu. The chevron itself stays undrawn, because a chevron on
+    a subtitle implies an edit and this is not one — the two vaults are encrypted under different keys, so a
+    move is a re-seal into one and a tombstone in the other, and the host takes a new id.
   -->
 
   <Border Width="304" Background="{StaticResource Sidebar}"
@@ -568,8 +569,10 @@
                 <!--
                   ◆ WHICH VAULT THIS GROUP WILL LIVE IN, on the same terms as the host editor's picker
                   above: asked while adding, hidden where there is only one vault to write to, and never
-                  offered for an existing group, because the vaults are encrypted under different keys and
-                  moving an item between them is a delete and a retype.
+                  offered for an existing group. Not because the group is stuck — MOVE over the group cards
+                  takes it to another vault, with everything on the shelf — but because moving it is a
+                  re-seal of every item involved into new ids, which is nothing a SAVE on this form could
+                  do, and a picker here would do it as a side effect of correcting a default port.
 
                   A group in a shared vault is what gives a team an arrangement rather than a heap: the
                   people holding that vault's key see the folder, and the hosts inside it inherit its port,
diff --git a/src/DodoSSH.Client.App/Views/HostsScreen.axaml b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
index 7a3cc5d..f060df8 100644
--- a/src/DodoSSH.Client.App/Views/HostsScreen.axaml
+++ b/src/DodoSSH.Client.App/Views/HostsScreen.axaml
@@ -231,16 +231,23 @@
                          Foreground="{StaticResource TextDim}" VerticalAlignment="Center" />
 
               <!--
-                The group's own two actions, beside the group cards rather than in the toolbar, because they
-                act on the card that is selected — and this is where the selection is made. Hidden rather
-                than disabled while DELETE's question is up, as every other pair in this application is, so
-                it cannot be pressed twice, and hidden again when there is nothing for them to act on. What
-                that is, with no card selected, is the group the trail above ends with; see
+                The group's own actions, beside the group cards rather than in the toolbar, because they act
+                on the card that is selected — and this is where the selection is made. Hidden rather than
+                disabled while either panel below is up, as every other row of buttons in this application
+                is, so none of them can be pressed twice, and hidden again when there is nothing for them to
+                act on. What that is, with no card selected, is the group the trail above ends with; see
                 VaultViewModel.GroupTarget.
+
+                MOVE is between them rather than beside DELETE, and it stays visible with nowhere to go: the
+                command answers with a sentence naming the reason, which is more use than a button that has
+                quietly gone. The host pane's ⋯ menu keeps its own entry on the same reasoning.
               -->
               <StackPanel Grid.Column="2" Orientation="Horizontal" Spacing="6">
                 <Button Classes="ghost" Content="EDIT" Command="{Binding EditGroupCommand}"
                         IsVisible="{Binding ShowsGroupActions}" />
+                <Button Classes="ghost" Content="MOVE" Command="{Binding MoveGroupCommand}"
+                        IsVisible="{Binding ShowsGroupActions}"
+                        ToolTip.Tip="Moves this group to another vault, with the groups inside it and every host filed under them." />
                 <Button Classes="ghost" Content="DELETE" Command="{Binding DeleteGroupCommand}"
                         IsVisible="{Binding ShowsGroupActions}" />
               </StackPanel>
@@ -251,6 +258,42 @@
               <views:ConfirmDeleteCard />
             </Border>
 
+            <!--
+              ◆ MOVING THE GROUP TO ANOTHER VAULT. The host drawer's move panel, one level up and in the
+              place this section's buttons were. A picker and two buttons rather than a question with a yes:
+              what is being asked is which vault, and a move is undone by moving it back — so it is not
+              drawn in the danger colours the deletion question above it uses.
+
+              The sentence is what the panel is for. A group cannot go anywhere alone: the machines under it
+              are items of the vault it is leaving, and so are the groups nested inside it, so all of them
+              are re-sealed under the destination's key and all of them take new ids. What cannot come is
+              the group it is nested under, which is why it arrives at the top level. Saying that here
+              rather than only in the status line afterwards is the difference between a warning and a
+              surprise.
+            -->
+            <Border Padding="10" Background="{StaticResource Panel}" CornerRadius="6"
+                    BorderBrush="{StaticResource Border}" BorderThickness="1"
+                    IsVisible="{Binding IsMovingGroup}">
+              <StackPanel Spacing="8">
+                <TextBlock Classes="label" Text="MOVE GROUP TO VAULT" />
+                <ComboBox HorizontalAlignment="Stretch" ItemsSource="{Binding MoveGroupVaultChoices}"
+                          SelectedItem="{Binding SelectedMoveGroupVault}">
+                  <ComboBox.ItemTemplate>
+                    <DataTemplate x:DataType="vm:VaultChoiceViewModel">
+                      <TextBlock Text="{Binding Display}" FontSize="12" />
+                    </DataTemplate>
+                  </ComboBox.ItemTemplate>
+                </ComboBox>
+                <TextBlock Classes="hint" FontSize="10.5" TextWrapping="Wrap"
+                           Text="The group goes with the groups inside it and every host filed under them, all re-encrypted with the other vault's key. Any group it is nested under stays behind, so it arrives at the top level, and the hosts' tags stay behind with it." />
+                <StackPanel Orientation="Horizontal" Spacing="6">
+                  <Button Classes="accent" Content="MOVE" Command="{Binding ConfirmMoveGroupCommand}"
+                          IsEnabled="{Binding !IsBusy}" />
+                  <Button Classes="ghost" Content="CANCEL" Command="{Binding CancelMoveGroupCommand}" />
+                </StackPanel>
+              </StackPanel>
+            </Border>
+
             <!--
               A ListBox rather than an ItemsControl of buttons, and that is what marks the chosen group for
               free: selection is a state the control already has, and the tile style draws it the same way
@@ -302,14 +345,20 @@
                 act on the card that was right-clicked.
 
                 Only Open takes a parameter, because OpenGroupCommand's null means ALL HOSTS rather than
-                nothing; Edit and Delete read GroupTarget, which the selection the code-behind has just made
+                nothing; the other three read GroupTarget, which the selection the code-behind has just made
                 is the first half of.
+
+                Moving is above the separator that Delete sits below, exactly as it is in the host pane's
+                menu, and for the same reason: it is not a field of the group and it is not a deletion
+                either. The two vaults are encrypted under different keys, so it is a re-seal of the whole
+                shelf into one and a tombstone per item in the other.
               -->
               <ListBox.ContextMenu>
                 <ContextMenu>
                   <MenuItem Header="Open" Command="{Binding OpenGroupCommand}"
                             CommandParameter="{Binding SelectedGroup}" />
                   <MenuItem Header="Edit…" Command="{Binding EditGroupCommand}" />
+                  <MenuItem Header="Move to another vault…" Command="{Binding MoveGroupCommand}" />
                   <Separator />
                   <MenuItem Header="Delete…" Command="{Binding DeleteGroupCommand}" />
                 </ContextMenu>
diff --git a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
index 860fbf8..35a971c 100644
--- a/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
+++ b/src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs
@@ -982,6 +982,27 @@ internal sealed record DeletionRequest(
 {
     /// <summary>Whether anything depends on the item, which is the line worth reading twice.</summary>
     internal bool HasUsage => Usage.Length > 0;
+
+    /// <summary>
+    /// The second question this deletion has to ask, or empty where it has none.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Only a group has one, and it is the one deletion in this application whose scope is not decided by
+    /// what is being deleted: a group is a heading, and the machines under it may be the reason the heading
+    /// existed or may be forty perfectly good hosts that want a different shelf. Nothing here can tell which,
+    /// so it is asked — see <see cref="VaultViewModel.DeletionTakesTheHostsToo"/>, which is the answer.
+    /// </para>
+    /// <para>
+    /// A sentence rather than a flag, because the card that draws it is shared by six kinds of deletion and
+    /// must not grow a branch per kind. Empty is "there is no second question", which is also what a group
+    /// with nothing filed under it gets.
+    /// </para>
+    /// </remarks>
+    internal string Choice { get; init; } = string.Empty;
+
+    /// <summary>Whether this deletion has a second question to put.</summary>
+    internal bool HasChoice => Choice.Length > 0;
 }
 
 /// <summary>
@@ -1540,13 +1561,19 @@ internal sealed partial class VaultViewModel(
     /// <remarks>
     /// <para>
     /// The same picker the host editor has, on the form beside it, and for the same reason: this is the
-    /// decision that makes the thing shared, it cannot be changed afterwards, and the only other control
-    /// that could have answered it is a standing preference on a different screen. A group is where hosts
-    /// are filed and what lends them a port, a username and a key — so putting one in a shared vault is how
-    /// a team gets an arrangement rather than twenty machines in a heap, which is most of what sharing is
+    /// decision that makes the thing shared, it cannot be changed <em>by saving</em>, and the only other
+    /// control that could have answered it is a standing preference on a different screen. A group is where
+    /// hosts are filed and what lends them a port, a username and a key — so putting one in a shared vault is
+    /// how a team gets an arrangement rather than twenty machines in a heap, which is most of what sharing is
     /// for.
     /// </para>
     /// <para>
+    /// Changed afterwards it can be, by <see cref="MoveGroup"/>, which is a separate act for the reason
+    /// moving a host is: it re-seals the group, everything nested inside it and every host filed under them
+    /// into a second vault's key, and nothing that happens as a side effect of pressing SAVE on a form should
+    /// be that.
+    /// </para>
+    /// <para>
     /// Filled from <see cref="TargetVaults"/>, so it offers what every other "file this into" control does:
     /// vaults this session can both read and write.
     /// </para>
@@ -1984,6 +2011,48 @@ internal sealed partial class VaultViewModel(
         SelectedHost is { IsReadOnly: false } row
         && session.ReadableVaults.Any(vault => vault.CanWrite && vault.VaultId != row.VaultId);
 
+    /// <summary>
+    /// Whether the panel asking which vault to move the group to is up.
+    /// </summary>
+    /// <remarks>
+    /// The host's panel again — see <see cref="IsMovingHost"/> — in the one place a group can be acted on,
+    /// which is the GROUPS section of the hosts screen rather than the drawer. It takes that section's two
+    /// buttons the way the deletion question does, and for the same reason: a MOVE that could be pressed
+    /// again while its own picker was open would be a second panel about the same shelf.
+    /// </remarks>
+    [ObservableProperty]
+    [NotifyPropertyChangedFor(nameof(ShowsGroupActions))]
+    private bool isMovingGroup;
+
+    /// <summary>Which group the open move panel is about. Null when it is closed.</summary>
+    /// <inheritdoc cref="movingHostId" path="/remarks" />
+    private Guid? movingGroupId;
+
+    /// <summary>Where the group could be moved: every vault this session can write to but its own.</summary>
+    internal ObservableCollection<VaultChoiceViewModel> MoveGroupVaultChoices { get; } = [];
+
+    [ObservableProperty]
+    private VaultChoiceViewModel? selectedMoveGroupVault;
+
+    /// <summary>
+    /// Whether the group the buttons are aimed at has anywhere to move to.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Counted per group rather than asked once of the session, exactly as <see cref="CanMoveSelectedHost"/>
+    /// is: a group already in the only other writable vault has nowhere to go.
+    /// </para>
+    /// <para>
+    /// The read-only test is the group's own and not the whole subtree's. That is deliberate rather than
+    /// sloppy — this decides whether a button is worth drawing, and walking every descendant and every host
+    /// under them to answer it would be that walk on every selection. The subtree is checked once, where it
+    /// decides something, in <see cref="ConfirmMoveGroupAsync"/>.
+    /// </para>
+    /// </remarks>
+    internal bool CanMoveGroupTarget =>
+        GroupTarget is { IsReadOnly: false } row
+        && session.ReadableVaults.Any(vault => vault.CanWrite && vault.VaultId != row.VaultId);
+
     /// <summary>
     /// What the drawer's header says it is about.
     /// </summary>
@@ -2004,10 +2073,12 @@ internal sealed partial class VaultViewModel(
     /// </summary>
     /// <remarks>
     /// <para>
-    /// The vault's name and not a picker for it, although the design draws one with a chevron. An item
-    /// cannot be moved between vaults here — that is a delete and a retype, because the two are encrypted
-    /// under different keys — so a control offering the move would be offering something no layer below
-    /// this can do. Where a *new* item goes is chosen in the editor's own picker; see <see cref="TargetVaults"/>
+    /// The vault's name and not a picker for it, although the design draws one with a chevron. A host and a
+    /// group can both be moved between vaults — see <see cref="MoveHost"/> and <see cref="MoveGroup"/> — but
+    /// not from here and not by saving: the two vaults are encrypted under different keys, so a move is a
+    /// re-seal into one and a tombstone in the other, and every item involved takes a new id. A chevron on a
+    /// subtitle implies an edit and would be describing something else. Where a *new* item goes is chosen in
+    /// the editor's own picker; see <see cref="TargetVaults"/>
     /// </para>
     /// <para>
     /// A group being renamed says its vault here for the same reason a host being edited does, and it is
@@ -2559,6 +2630,26 @@ internal sealed partial class VaultViewModel(
     [ObservableProperty]
     private DeletionRequest? pendingDeletion;
 
+    /// <summary>
+    /// The answer to <see cref="DeletionRequest.Choice"/>: whether a group's hosts go with it.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>Off is the answer that keeps the machines</b>, and it is off by default and reset to off on every
+    /// question — see <see cref="OnPendingDeletionChanged"/>. A tick left standing from the last group
+    /// deleted would delete forty hosts on behalf of somebody who was only tidying a heading away, and there
+    /// is no undo on either side of it.
+    /// </para>
+    /// <para>
+    /// A tick rather than a pair of options, and deliberately not two equally weighted answers: they are not
+    /// equally weighted. Keeping the hosts is recoverable — they turn up under UNGROUPED and can be filed
+    /// again — and deleting them is not, so the safe answer is the one that needs no decision and the
+    /// destructive one is the one that has to be reached for.
+    /// </para>
+    /// </remarks>
+    [ObservableProperty]
+    private bool deletionTakesTheHostsToo;
+
     internal bool IsConfirmingDeletion => PendingDeletion is not null;
 
     /// <summary>Whether the sidebar's row of host buttons is showing.</summary>
@@ -2598,11 +2689,17 @@ internal sealed partial class VaultViewModel(
 
     /// <summary>Whether the group panel's buttons are showing.</summary>
     /// <remarks>
-    /// Hidden with nothing to act on as well as while the question is up. A pair of buttons over a grid of
-    /// cards nobody has chosen between is a pair whose subject the user has to work out, and the answer
-    /// would be "neither" — see <see cref="GroupTarget"/>.
+    /// Hidden with nothing to act on as well as while the question is up. A row of buttons over a grid of
+    /// cards nobody has chosen between is a row whose subject the user has to work out, and the answer
+    /// would be "none of them" — see <see cref="GroupTarget"/>.
+    /// <para>
+    /// The move panel takes the row as well, on the same reasoning the host pane's menu hides for it: both
+    /// panels are drawn where the buttons were, and leaving them there would offer to open a panel that is
+    /// already open.
+    /// </para>
     /// </remarks>
-    internal bool ShowsGroupActions => GroupTarget is not null && !IsConfirmingGroupDeletion;
+    internal bool ShowsGroupActions =>
+        GroupTarget is not null && !IsConfirmingGroupDeletion && !IsMovingGroup;
 
     /// <summary>Whether this vault has any groups, which is what makes the sidebar draw headings.</summary>
     internal bool HasGroups => Groups.Count > 0;
@@ -4768,9 +4865,10 @@ internal sealed partial class VaultViewModel(
 
         EditingGroupId = row.EntityId;
 
-        // The group's own vault, and it does not move — the same rule an existing host's follows, and the
+        // The group's own vault, and no save moves it — the same rule an existing host's follows, and the
         // same reason: the two are encrypted under different keys, so saving anywhere else would leave a
-        // copy behind rather than move anything. The picker is not drawn for an existing group at all.
+        // copy behind rather than move anything. The picker is not drawn for an existing group at all, and
+        // the move that does work is MoveGroup, from the buttons over the cards.
         editingGroupVaultId = row.VaultId;
         editingGroupVaultName = row.HasVaultBadge ? row.VaultName : string.Empty;
 
@@ -4997,9 +5095,10 @@ internal sealed partial class VaultViewModel(
     /// Moves a half-typed group into the vault just chosen for it.
     /// </summary>
     /// <remarks>
-    /// Only while creating, for the reason <see cref="OnEditorSelectedVaultChanged"/> gives: a group cannot
-    /// be moved between vaults, so a path that reassigned this on a rename would write a second group into
-    /// the other vault and leave the original standing with the old name.
+    /// Only while creating, for the reason <see cref="OnEditorSelectedVaultChanged"/> gives: a save cannot
+    /// move a group between vaults, so a path that reassigned this on a rename would write a second group
+    /// into the other vault and leave the original standing with the old name. Moving one is
+    /// <see cref="MoveGroup"/>, which does the re-seal and the tombstone this could not.
     /// </remarks>
     partial void OnGroupEditorSelectedVaultChanged(VaultChoiceViewModel? value)
     {
@@ -5103,12 +5202,28 @@ internal sealed partial class VaultViewModel(
         Status = string.Empty;
     }
 
-    /// <summary>Asks whether the group being acted on should go.</summary>
+    /// <summary>Asks whether the group being acted on should go, and what should become of its hosts.</summary>
     /// <remarks>
-    /// The count is the whole reason this asks rather than acting. Deleting a group does not delete the hosts
-    /// in it and deliberately does not rewrite them either — they keep an id that no longer resolves and turn
-    /// up under the ungrouped heading — so what the user needs to know is exactly how many machines are about
-    /// to move, and that none of them are going anywhere else.
+    /// <para>
+    /// <b>The hosts are a second question rather than a stated consequence, and that is a reversal.</b> This
+    /// used to say what would happen to them — they stay, and turn up under UNGROUPED — because a group's
+    /// deletion did not touch them at all. That answer was right for one of the two things people delete a
+    /// group for and wrong for the other: a heading being tidied away should leave its machines alone, and a
+    /// project that has been decommissioned is a shelf and everything on it. Nothing here can tell which of
+    /// the two it is looking at, so it is asked. See <see cref="DeletionTakesTheHostsToo"/>.
+    /// </para>
+    /// <para>
+    /// The count is still the reason this asks rather than acting, and it now counts twice over: it is the
+    /// number of machines about to be unfiled, or — with the box ticked — the number about to be destroyed.
+    /// A group with nothing under it gets no second question and no tick, because there is nothing for
+    /// either to be about.
+    /// </para>
+    /// <para>
+    /// <b>Refused with a host editor open</b>, which the deletion of a single host is not. The difference is
+    /// that this one writes to hosts: unfiling rewrites every machine under the heading, and doing that
+    /// beneath a half-typed edit of one of them is the save nobody asked for that
+    /// <see cref="MoveHostToGroupAsync"/> refuses for the same reason.
+    /// </para>
     /// <para>
     /// Aims where EDIT does: at the selected card, or at the open group when no card is selected. See
     /// <see cref="GroupTarget"/>.
@@ -5122,6 +5237,17 @@ internal sealed partial class VaultViewModel(
             return;
         }
 
+        // Only where it would write to a host. A heading with nothing under it is deleted with an editor
+        // open, because nothing on that form is about to be rewritten underneath it.
+        if (row.HostCount > 0 && AHostEditorIsInTheWay())
+        {
+            return;
+        }
+
+        // Disarms a move aimed at the same group, on the reasoning MoveHost uses in the other direction: two
+        // panels about one shelf, one of which destroys it, is not something to make anybody read carefully.
+        CancelMoveGroupCommand.Execute(null);
+
         PendingDeletion = new DeletionRequest(
             DeletionTarget.Group,
             row.EntityId,
@@ -5136,13 +5262,52 @@ internal sealed partial class VaultViewModel(
             row.HostCount switch
             {
                 0 => string.Empty,
-                1 => "1 host is filed under it. The host stays; it moves to UNGROUPED.",
-                _ => $"{row.HostCount} hosts are filed under it. They stay; they move to UNGROUPED.",
-            });
+                1 => "1 host is filed under it. Left as it is, the host stays and moves to UNGROUPED.",
+                _ => $"{row.HostCount} hosts are filed under it. Left as it is, they stay and move to "
+                    + "UNGROUPED.",
+            })
+        {
+            Choice = row.HostCount switch
+            {
+                0 => string.Empty,
+                1 => "Delete the host filed under it as well.",
+                _ => $"Delete the {row.HostCount} hosts filed under it as well.",
+            },
+        };
     }
 
-    /// <summary>Queues a tombstone for the group that was agreed to.</summary>
-    private async Task DeleteGroupNowAsync(Guid entityId, CancellationToken cancellationToken)
+    /// <summary>
+    /// Queues the tombstone for the group that was agreed to, and settles what pointed at it.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>Nothing is left pointing at the group.</b> That is the change: the hosts filed under it are
+    /// rewritten — unfiled, or deleted where that was asked for — and the groups nested inside it take its
+    /// place in the tree rather than being orphaned into roots. It costs one write per item and it is the
+    /// honest cost of the question above it. The dangling reference the list used to absorb is still handled
+    /// everywhere it is read, because a group deleted on <em>another</em> machine still arrives that way.
+    /// </para>
+    /// <para>
+    /// <b>Everything that points at it is written before the group's own tombstone.</b> A crash in the middle
+    /// then leaves a heading standing over fewer things, which is visible and can simply be deleted again;
+    /// the other order leaves a group gone with its members still naming it, which is exactly the state this
+    /// exists to stop producing. It also matters against a merge: the group's tombstone can lose one, and if
+    /// it does, the unfiling has already been recorded on its own items rather than riding on it.
+    /// </para>
+    /// <para>
+    /// <b>A read-only host is skipped and counted rather than rewritten.</b> Unfiling it would re-encode a
+    /// payload this build cannot fully represent, which is the same refusal editing and moving one already
+    /// make — and the cost of skipping is a dangling id, which is the behaviour every reader here already
+    /// survives. Deleting one is <em>not</em> skipped: a tombstone re-encodes nothing.
+    /// </para>
+    /// </remarks>
+    /// <param name="entityId">The group.</param>
+    /// <param name="takesTheHosts">Whether the hosts filed under it were agreed to go too.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    private async Task DeleteGroupNowAsync(
+        Guid entityId,
+        bool takesTheHosts,
+        CancellationToken cancellationToken)
     {
         if (Groups.FirstOrDefault(row => row.EntityId == entityId) is not { } row)
         {
@@ -5150,10 +5315,24 @@ internal sealed partial class VaultViewModel(
             return;
         }
 
+        // Its own vault's, both of them. A host in another vault naming this group is a reference the editor
+        // cannot make and the drop gesture refuses, so the only way to hold one is a hand-edited payload —
+        // and rewriting somebody else's vault because a group in this one went is worse than the dangle.
+        var filed = Hosts
+            .Where(host => host.VaultId == row.VaultId && host.Host.GroupId == entityId)
+            .ToList();
+
+        var nested = Groups
+            .Where(group => group.VaultId == row.VaultId && group.Group.ParentId == entityId)
+            .ToList();
+
         await RunAsync(
             "Deleting…",
             async () =>
             {
+                var skipped = await ReleaseWhatPointedAtAsync(row, filed, nested, takesTheHosts, cancellationToken)
+                    .ConfigureAwait(true);
+
                 // The row's own vault, which is why the row is re-found above rather than the id being
                 // enough: a tombstone written to the active vault would delete nothing and leave a
                 // colleague's group standing while this machine reported it gone.
@@ -5168,12 +5347,91 @@ internal sealed partial class VaultViewModel(
                 }
 
                 await ReloadAsync(cancellationToken).ConfigureAwait(true);
-                Status = $"Deleted the group '{row.Label}'.";
+
+                Status = $"Deleted the group '{row.Label}'."
+                    + WhatBecameOfTheHosts(filed.Count, takesTheHosts, skipped);
             }).ConfigureAwait(true);
 
         await AutoSyncAsync(cancellationToken).ConfigureAwait(true);
     }
 
+    /// <summary>
+    /// Rewrites everything naming the group about to go, and says how many could not be.
+    /// </summary>
+    /// <remarks>
+    /// Before the tombstone and in this order, which <see cref="DeleteGroupNowAsync"/> gives the reasons for.
+    /// </remarks>
+    /// <returns>How many hosts were left holding the reference because they could not be rewritten.</returns>
+    private async Task<int> ReleaseWhatPointedAtAsync(
+        HostGroupRowViewModel row,
+        IEnumerable<HostRowViewModel> filed,
+        IEnumerable<HostGroupRowViewModel> nested,
+        bool takesTheHosts,
+        CancellationToken cancellationToken)
+    {
+        var skipped = 0;
+
+        foreach (var host in filed)
+        {
+            if (takesTheHosts)
+            {
+                await session.Hosts
+                    .DeleteAsync(host.VaultId, host.EntityId, cancellationToken)
+                    .ConfigureAwait(true);
+
+                continue;
+            }
+
+            if (host.IsReadOnly)
+            {
+                skipped++;
+                continue;
+            }
+
+            await session.Hosts
+                .UpdateAsync(
+                    host.VaultId,
+                    host.EntityId,
+                    host.Host with { GroupId = null },
+                    cancellationToken)
+                .ConfigureAwait(true);
+        }
+
+        // Promoted to where the group they were under sat, rather than to the top level. A nested group whose
+        // parent goes has not been moved by anybody, and dropping it to a root would rearrange a tree on a
+        // delete that was about one heading.
+        foreach (var child in nested.Where(child => !child.IsReadOnly))
+        {
+            await session.HostGroups
+                .UpdateAsync(
+                    child.VaultId,
+                    child.EntityId,
+                    child.Group with { ParentId = row.Group.ParentId },
+                    cancellationToken)
+                .ConfigureAwait(true);
+        }
+
+        return skipped;
+    }
+
+    /// <summary>What the group's deletion did to the machines under it, said only when there were any.</summary>
+    /// <remarks>
+    /// The skipped count is named rather than folded into the total, because those hosts are the ones still
+    /// holding the deleted group's id: they show up under UNGROUPED like the rest, so nothing looks wrong,
+    /// and the sentence is the only place anybody is told that updating this client is what finishes the job.
+    /// </remarks>
+    private static string WhatBecameOfTheHosts(int filed, bool takesTheHosts, int skipped) =>
+        (filed, takesTheHosts, skipped) switch
+        {
+            (0, _, _) => string.Empty,
+            (1, true, _) => " Its host went with it.",
+            (_, true, _) => $" Its {filed} hosts went with it.",
+            (1, false, 0) => " Its host moved to UNGROUPED.",
+            (_, false, 0) => $" Its {filed} hosts moved to UNGROUPED.",
+            _ => $" Its {filed} hosts moved to UNGROUPED, except {skipped} written by a newer version of "
+                + "DodoSSH — those still name the group that has gone. Update to unfile them.",
+        };
+
     /// <summary>Abandons the editor.</summary>
     [RelayCommand]
     private void CancelEdit()
@@ -5457,11 +5715,7 @@ internal sealed partial class VaultViewModel(
     {
         MoveVaultChoices.Clear();
 
-        foreach (var choice in session.ReadableVaults
-            .Where(vault => vault.CanWrite && vault.VaultId != vaultId)
-            .OrderByDescending(vault => vault.IsPersonal)
-            .ThenBy(vault => vault.Name, StringComparer.CurrentCulture)
-            .Select(vault => new VaultChoiceViewModel(vault.VaultId, vault.Name, vault.IsPersonal)))
+        foreach (var choice in WritableVaultsBesides(vaultId))
         {
             MoveVaultChoices.Add(choice);
         }
@@ -5469,6 +5723,357 @@ internal sealed partial class VaultViewModel(
         SelectedMoveVault = MoveVaultChoices.FirstOrDefault();
     }
 
+    /// <summary>Every vault this session can write to except one, in the order a picker should offer them.</summary>
+    /// <remarks>
+    /// Shared by the host's picker and the group's rather than written twice. The order is the one every
+    /// vault picker in this application uses: your own first, then the shared ones by name — a list that
+    /// re-sorted itself per control would make "the second entry" mean something different on each.
+    /// </remarks>
+    private IEnumerable<VaultChoiceViewModel> WritableVaultsBesides(Guid vaultId) =>
+        session.ReadableVaults
+            .Where(vault => vault.CanWrite && vault.VaultId != vaultId)
+            .OrderByDescending(vault => vault.IsPersonal)
+            .ThenBy(vault => vault.Name, StringComparer.CurrentCulture)
+            .Select(vault => new VaultChoiceViewModel(vault.VaultId, vault.Name, vault.IsPersonal));
+
+    /// <summary>
+    /// Opens the panel that asks which vault the group — and everything under it — should move to.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The host's panel, one level up, and the reason it exists at all is that the host's did not go far
+    /// enough. Moving twenty machines into a shared vault one at a time meant twenty round trips through a
+    /// menu, and each one arrived stripped of the group it had been filed under, so the shelf had to be
+    /// rebuilt by hand on the other side. Moving the shelf is the operation people were actually attempting.
+    /// </para>
+    /// <para>
+    /// Refused for a group written by a newer client, as editing one is, and refused with a host editor open,
+    /// as <see cref="DeleteGroup"/> is: this rewrites hosts.
+    /// </para>
+    /// </remarks>
+    [RelayCommand]
+    private void MoveGroup()
+    {
+        if (GroupTarget is not { } row || AHostEditorIsInTheWay() || AGroupEditorIsInTheWay())
+        {
+            return;
+        }
+
+        if (row.IsReadOnly)
+        {
+            Status = "This group was written by a newer version of DodoSSH. Moving it would re-encode it "
+                + "here and lose what this build cannot read. Update first.";
+            return;
+        }
+
+        BuildMoveGroupVaultChoices(row.VaultId);
+
+        if (MoveGroupVaultChoices.Count == 0)
+        {
+            Status = $"There is nowhere to move '{row.Label}' to: this is the only vault you can write to.";
+            return;
+        }
+
+        // As MoveHost disarms a deletion aimed at the same host.
+        PendingDeletion = null;
+        movingGroupId = row.EntityId;
+        IsMovingGroup = true;
+        Status = string.Empty;
+    }
+
+    /// <summary>Abandons the group's move panel.</summary>
+    [RelayCommand]
+    private void CancelMoveGroup()
+    {
+        if (!IsMovingGroup)
+        {
+            return;
+        }
+
+        IsMovingGroup = false;
+        movingGroupId = null;
+        MoveGroupVaultChoices.Clear();
+        SelectedMoveGroupVault = null;
+        Status = string.Empty;
+    }
+
+    /// <summary>
+    /// Moves the group, everything nested inside it and every host filed under any of them.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>The whole subtree goes, and taking less than that was never coherent.</b> A group's children are
+    /// items of the vault it is leaving: move the parent alone and they are left naming a tombstone, so they
+    /// surface as roots in the vault the user has just emptied — half a shelf here and half there, from one
+    /// gesture that said "move this". The hosts are the same argument and are the half the user asked about.
+    /// </para>
+    /// <para>
+    /// <b>The groups go first, top down, and the hosts last.</b> Each item is re-sealed under the
+    /// destination's key and takes a new id — see <c>VaultItemRepository.MoveAsync</c> — so nothing that
+    /// points at a group can be written until that group has landed and its new id is known. Top down for
+    /// the same reason one level up: a child's parent must already be over there. What an interruption
+    /// leaves is therefore hosts still in the vault they started in, under UNGROUPED, which is visible and
+    /// re-movable; the reverse order would leave hosts in the destination filed under nothing.
+    /// </para>
+    /// <para>
+    /// <b>The parent is left behind and the tags are dropped</b>, and both are the same rule the host's move
+    /// follows: a parent group and a tag are items of the vault being left, so a reference carried across
+    /// would resolve on this machine — groups and tags resolve over every readable vault — and dangle for
+    /// everybody else in the destination. The moved group becomes a root, which is what the trail will show,
+    /// and it is said in the sentence afterwards rather than discovered.
+    /// </para>
+    /// <para>
+    /// <b>Keys and passwords are kept</b>, on the host and on the group's own defaults, because those do
+    /// genuinely resolve across vaults — one key on twenty hosts in three vaults is the arrangement they
+    /// exist for. What is reported is a binding now outside the destination, since that is precisely what
+    /// the other holders of it will not be able to resolve.
+    /// </para>
+    /// </remarks>
+    [RelayCommand]
+    private async Task ConfirmMoveGroupAsync(CancellationToken cancellationToken)
+    {
+        if (GroupTarget is not { } row
+            || movingGroupId != row.EntityId
+            || SelectedMoveGroupVault is not { } target)
+        {
+            return;
+        }
+
+        var subtree = SubtreeOf(row);
+        var moving = subtree.Select(group => group.EntityId).ToHashSet();
+
+        var filed = Hosts
+            .Where(host => host.VaultId == row.VaultId && host.Host.GroupId is { } id && moving.Contains(id))
+            .ToList();
+
+        // Asked once, over everything that is about to be re-encoded, and refused as a whole rather than
+        // half-done: a move that skipped the items it could not represent would file some of the shelf in one
+        // vault and leave the rest in the other, which is the state this operation exists to prevent.
+        if (subtree.Any(group => group.IsReadOnly) || filed.Any(host => host.IsReadOnly))
+        {
+            Status = "Something under this group was written by a newer version of DodoSSH. Moving it would "
+                + "re-encode it here and lose what this build cannot read. Update first.";
+            return;
+        }
+
+        var name = target.Name;
+        var stranded = BindingsOutside(subtree, filed, target.VaultId);
+        var uprooted = row.Group.ParentId is not null;
+        var tagged = filed.Count(host => host.Host.TagIds.Count > 0);
+
+        CancelMoveGroupCommand.Execute(null);
+
+        await RunAsync(
+            "Moving…",
+            async () =>
+            {
+                var landed = await ReSealTheSubtreeAsync(subtree, filed, target.VaultId, cancellationToken)
+                    .ConfigureAwait(true);
+
+                await ReloadAsync(cancellationToken).ConfigureAwait(true);
+
+                // By its new id, as a moved host's pane is: leaving the buttons aimed at a card that no
+                // longer exists would read as the shelf having been deleted rather than moved.
+                SelectedGroup = VisibleGroups.FirstOrDefault(card => card.EntityId == landed);
+
+                Status = $"Moved '{row.Label}' to {name}.{WhatCameAlong(subtree.Count, filed.Count)}"
+                    + $"{WhatStayedBehind(uprooted, tagged)}{stranded}";
+            }).ConfigureAwait(true);
+
+        await AutoSyncAsync(cancellationToken).ConfigureAwait(true);
+    }
+
+    /// <summary>
+    /// Re-seals a group, its nested groups and their hosts under another vault's key.
+    /// </summary>
+    /// <remarks>
+    /// The order and what it costs an interruption are <see cref="ConfirmMoveGroupAsync"/>'s to explain. What
+    /// lives here is the id map every write after the first depends on: each item lands with an id of the
+    /// destination's making, so a parent's is looked up rather than reused, and a host's group is the entry
+    /// its old group left behind.
+    /// </remarks>
+    /// <param name="subtree">The group and its nested groups, each after its parent.</param>
+    /// <param name="filed">The hosts under any of them.</param>
+    /// <param name="vaultId">The vault they are all going to.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The id the group at the root of it has in its new vault.</returns>
+    private async Task<Guid> ReSealTheSubtreeAsync(
+        List<HostGroupRowViewModel> subtree,
+        IEnumerable<HostRowViewModel> filed,
+        Guid vaultId,
+        CancellationToken cancellationToken)
+    {
+        var root = subtree[0].EntityId;
+        var remapped = new Dictionary<Guid, Guid>();
+
+        foreach (var group in subtree)
+        {
+            // Null for the root, whose parent is staying behind in the vault it came from; every other group
+            // in the list was discovered by its own parent, so that parent has already landed.
+            var parent = group.EntityId == root
+                ? (Guid?)null
+                : remapped[group.Group.ParentId!.Value];
+
+            remapped[group.EntityId] = await session.HostGroups
+                .MoveAsync(
+                    group.VaultId,
+                    vaultId,
+                    group.EntityId,
+                    group.Group with { ParentId = parent },
+                    cancellationToken)
+                .ConfigureAwait(true);
+        }
+
+        foreach (var host in filed)
+        {
+            await session.Hosts
+                .MoveAsync(
+                    host.VaultId,
+                    vaultId,
+                    host.EntityId,
+                    host.Host with
+                    {
+                        GroupId = remapped[host.Host.GroupId!.Value],
+                        TagIds = TagSet.Empty,
+                    },
+                    cancellationToken)
+                .ConfigureAwait(true);
+        }
+
+        return remapped[root];
+    }
+
+    /// <summary>
+    /// The group and every group nested under it, each one after the group it hangs from.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// A breadth-first walk from the root, and the order is the whole reason it is one: every group but the
+    /// first is discovered <em>by</em> its parent, so a caller writing the list in order always has the
+    /// parent's new id in hand before it needs it.
+    /// </para>
+    /// <para>
+    /// Its own vault's only, because a child in another vault is a level half the readers cannot resolve and
+    /// the editor refuses to make one.
+    /// </para>
+    /// <para>
+    /// <b>Cycle-safe, and it has to be.</b> A group already found is not walked again and not added twice —
+    /// the same visited set every walk over this tree carries, for the reason
+    /// <see cref="HostGroupSecret.ParentId"/> gives: two offline clients can each re-parent one group under
+    /// the other, and the pair that results was never shown to an editor. Without the set, a group that is
+    /// its own parent would be appended to this list for as long as there was memory to append to.
+    /// </para>
+    /// </remarks>
+    private List<HostGroupRowViewModel> SubtreeOf(HostGroupRowViewModel root)
+    {
+        var ordered = new List<HostGroupRowViewModel> { root };
+        var found = new HashSet<Guid> { root.EntityId };
+
+        for (var index = 0; index < ordered.Count; index++)
+        {
+            var parent = ordered[index].EntityId;
+
+            foreach (var child in Groups.Where(
+                group => group.VaultId == root.VaultId && group.Group.ParentId == parent))
+            {
+                if (found.Add(child.EntityId))
+                {
+                    ordered.Add(child);
+                }
+            }
+        }
+
+        return ordered;
+    }
+
+    /// <summary>What the move brought with it, said as the counts the user can check against the cards.</summary>
+    private static string WhatCameAlong(int groups, int hosts)
+    {
+        var nested = groups switch
+        {
+            1 => string.Empty,
+            2 => " with the group inside it",
+            _ => $" with the {groups - 1} groups inside it",
+        };
+
+        return hosts switch
+        {
+            0 when groups == 1 => string.Empty,
+            0 => $" It went{nested}, and no hosts were filed under any of them.",
+            1 => $" Its host came too{nested}.",
+            _ => $" Its {hosts} hosts came too{nested}.",
+        };
+    }
+
+    /// <summary>The two things a group cannot take across, said only where it had one.</summary>
+    private static string WhatStayedBehind(bool uprooted, int tagged) =>
+        (uprooted, tagged > 0) switch
+        {
+            (true, true) => " The group it was nested under stayed behind and the hosts' tags were dropped —"
+                + " both belong to the vault it came from, so it now sits at the top level.",
+            (true, false) => " The group it was nested under stayed behind — a parent belongs to the vault it"
+                + " is in — so it now sits at the top level.",
+            (false, true) => " The hosts' tags were left behind — a tag belongs to the vault it is in.",
+            _ => string.Empty,
+        };
+
+    /// <summary>
+    /// The warning about keys or passwords that are not in the vault the group has moved to.
+    /// </summary>
+    /// <remarks>
+    /// Counted and named to one, where <see cref="BindingOutside"/> names the only one there can be. A shelf
+    /// of twenty machines may strand five different keys, and twenty sentences is not a status line — but a
+    /// bare number is not actionable either, so the first is named and the rest are counted. Both the hosts'
+    /// own bindings and the groups' defaults are asked, because a group that lends a key is the one case
+    /// where a machine can be unable to connect without naming anything itself.
+    /// </remarks>
+    private string BindingsOutside(
+        IEnumerable<HostGroupRowViewModel> groups,
+        IEnumerable<HostRowViewModel> hosts,
+        Guid vaultId)
+    {
+        var stranded = groups
+            .SelectMany(group => new[] { group.Group.DefaultSshKeyId, group.Group.DefaultCredentialId })
+            .Concat(hosts.SelectMany(host => new[] { host.Host.SshKeyId, host.Host.CredentialId }))
+            .OfType<Guid>()
+            .Distinct()
+            .Select(LabelOfBindingOutside)
+            .OfType<string>()
+            .ToList();
+
+        return stranded.Count switch
+        {
+            0 => string.Empty,
+            1 => $" It still authenticates with '{stranded[0]}', which is in another vault — everybody else "
+                + "in this one will find that binding unresolvable.",
+            _ => $" It still authenticates with '{stranded[0]}' and {stranded.Count - 1} other key(s) or "
+                + "password(s) in other vaults — everybody else in this one will find those bindings "
+                + "unresolvable.",
+        };
+
+        string? LabelOfBindingOutside(Guid entityId) =>
+            (Keys.FirstOrDefault(key => key.EntityId == entityId) is { } key && key.VaultId != vaultId
+                ? key.Label
+                : null)
+            ?? (Credentials.FirstOrDefault(row => row.EntityId == entityId) is { } credential
+                && credential.VaultId != vaultId
+                    ? credential.Label
+                    : null);
+    }
+
+    /// <summary>Fills the group move panel's picker with every vault this session can write to but that one.</summary>
+    private void BuildMoveGroupVaultChoices(Guid vaultId)
+    {
+        MoveGroupVaultChoices.Clear();
+
+        foreach (var choice in WritableVaultsBesides(vaultId))
+        {
+            MoveGroupVaultChoices.Add(choice);
+        }
+
+        SelectedMoveGroupVault = MoveGroupVaultChoices.FirstOrDefault();
+    }
+
     /// <summary>Asks whether the selected host should go.</summary>
     /// <remarks>
     /// A terminal already open on the host is disclosed rather than prevented, because deleting a host does
@@ -6314,6 +6919,10 @@ internal sealed partial class VaultViewModel(
             return;
         }
 
+        // Read before the disarming below, which resets it. The answer belongs to the question that was on
+        // screen, and taking it afterwards would read whatever the next question starts from.
+        var takesTheHosts = DeletionTakesTheHostsToo;
+
         PendingDeletion = null;
 
         switch (request.Target)
@@ -6331,7 +6940,8 @@ internal sealed partial class VaultViewModel(
                 break;
 
             case DeletionTarget.Group:
-                await DeleteGroupNowAsync(request.EntityId, cancellationToken).ConfigureAwait(true);
+                await DeleteGroupNowAsync(request.EntityId, takesTheHosts, cancellationToken)
+                    .ConfigureAwait(true);
                 break;
 
             case DeletionTarget.ObjectStore:
@@ -8065,9 +8675,11 @@ internal sealed partial class VaultViewModel(
         }
 
         DisarmIfAimedElsewhere(DeletionTarget.Group, GroupTarget?.EntityId);
+        CloseTheGroupMovePanelIfAimedElsewhere();
 
         OnPropertyChanged(nameof(GroupTarget));
         OnPropertyChanged(nameof(ShowsGroupActions));
+        OnPropertyChanged(nameof(CanMoveGroupTarget));
     }
 
     /// <remarks>
@@ -8086,16 +8698,38 @@ internal sealed partial class VaultViewModel(
     partial void OnGroupFilterChanged(HostGroupRowViewModel? value)
     {
         DisarmIfAimedElsewhere(DeletionTarget.Group, GroupTarget?.EntityId);
+        CloseTheGroupMovePanelIfAimedElsewhere();
 
         OnPropertyChanged(nameof(GroupTarget));
         OnPropertyChanged(nameof(ShowsGroupActions));
+        OnPropertyChanged(nameof(CanMoveGroupTarget));
 
         RebuildGroupLevel();
         RebuildVisibleHosts();
     }
 
+    /// <summary>Folds the group's move panel away once the buttons under it point at something else.</summary>
+    /// <remarks>
+    /// By entity id and not by row, for the reason <see cref="DisarmIfAimedElsewhere"/> compares ids: every
+    /// row object in the list is replaced on every reload, so a panel closed on row identity would fold up
+    /// once a minute under somebody who was still choosing a vault in it. It is cleared rather than re-aimed,
+    /// because which vault to move to is a choice about the shelf it was asked for.
+    /// </remarks>
+    private void CloseTheGroupMovePanelIfAimedElsewhere()
+    {
+        if (IsMovingGroup && movingGroupId != GroupTarget?.EntityId)
+        {
+            CancelMoveGroupCommand.Execute(null);
+        }
+    }
+
     partial void OnPendingDeletionChanged(DeletionRequest? value)
     {
+        // Back to "keep them" on every question, including the one that disarms it. A tick is the answer to
+        // the group that was named in the sentence above it and to nothing else; carried into the next
+        // question it would delete a second group's machines on the strength of a decision about the first.
+        DeletionTakesTheHostsToo = false;
+
         OnPropertyChanged(nameof(IsConfirmingDeletion));
         OnPropertyChanged(nameof(IsConfirmingHostDeletion));
         OnPropertyChanged(nameof(IsConfirmingGroupDeletion));
diff --git a/src/DodoSSH.Client.Sync/HostGroupRepository.cs b/src/DodoSSH.Client.Sync/HostGroupRepository.cs
index 8a3b05f..aacdd3b 100644
--- a/src/DodoSSH.Client.Sync/HostGroupRepository.cs
+++ b/src/DodoSSH.Client.Sync/HostGroupRepository.cs
@@ -11,11 +11,19 @@ namespace DodoSSH.Client.Sync;
 /// The fifth facade over the same generic repository, and like the fourth it needed no new sync logic at all.
 /// </para>
 /// <para>
-/// <b>Deleting a group does not touch the hosts in it.</b> There is deliberately no <c>DeleteAsync</c>
-/// overload that unfiles its members: one user action would become N host writes, N outbox rows and N chances
-/// to merge against an edit nobody made, and the group's own tombstone can still lose a merge — by which time
-/// the membership it was clearing is gone. Hosts left holding a dangling id fall under the ungrouped heading,
-/// which is where the interface handles it. See <see cref="HostSecret.GroupId"/>.
+/// <b>Deleting a group still does not touch the hosts in it, here.</b> There is deliberately no
+/// <c>DeleteAsync</c> overload that unfiles its members: one call would become N host writes, N outbox rows
+/// and N chances to merge against an edit nobody made, and the group's own tombstone can still lose a merge —
+/// by which time the membership it was clearing would be gone. A host left holding a dangling id falls under
+/// the ungrouped heading, so this layer is safe whatever happens above it. See
+/// <see cref="HostSecret.GroupId"/>.
+/// </para>
+/// <para>
+/// What changed above it is that the deletion is no longer silent about the choice: the interface asks
+/// whether the hosts should go too, and writes them one by one through <c>HostRepository</c> either way —
+/// as N deletions, or as N hosts with the reference cleared. That is the same N writes, made where somebody
+/// asked for them and where the count can be shown before the fact rather than issued by a repository call
+/// that reads like one delete.
 /// </para>
 /// </remarks>
 public sealed class HostGroupRepository(
@@ -48,6 +56,25 @@ public sealed class HostGroupRepository(
         CancellationToken cancellationToken) =>
         groups.UpdateAsync(vaultId, entityId, group, cancellationToken);
 
+    /// <inheritdoc cref="VaultItemRepository{TSecret}.MoveAsync" />
+    /// <remarks>
+    /// <inheritdoc cref="VaultItemRepository{TSecret}.MoveAsync" path="/remarks" />
+    /// <para>
+    /// The new id matters more for a group than for anything else that can be moved, because a group is the
+    /// one item other items point at. Everything naming the old id — the hosts filed under it, the groups
+    /// nested inside it — has to be rewritten with the id this returns, or it is left pointing at a
+    /// tombstone. That rewriting is the caller's, for the reason the <c>secret</c> parameter is: this layer
+    /// cannot know which references cross with the group and which stay behind.
+    /// </para>
+    /// </remarks>
+    public Task<Guid> MoveAsync(
+        Guid fromVaultId,
+        Guid toVaultId,
+        Guid entityId,
+        HostGroupSecret group,
+        CancellationToken cancellationToken) =>
+        groups.MoveAsync(fromVaultId, toVaultId, entityId, group, cancellationToken);
+
     /// <inheritdoc cref="VaultItemRepository{TSecret}.DeleteAsync" />
     public Task DeleteAsync(Guid vaultId, Guid entityId, CancellationToken cancellationToken) =>
         groups.DeleteAsync(vaultId, entityId, cancellationToken);
diff --git a/tests/DodoSSH.Client.App.Layout.Tests/ScreenLayoutTests.cs b/tests/DodoSSH.Client.App.Layout.Tests/ScreenLayoutTests.cs
index c9633cb..cb2ca1e 100644
--- a/tests/DodoSSH.Client.App.Layout.Tests/ScreenLayoutTests.cs
+++ b/tests/DodoSSH.Client.App.Layout.Tests/ScreenLayoutTests.cs
@@ -557,9 +557,11 @@ public sealed class ScreenLayoutTests : IAsyncLifetime
     }
 
     /// <remarks>
-    /// The question replaces the group's two buttons rather than stacking under them — the same rule every
-    /// other pair in this application follows — and it is the taller of the two, because it says how many
-    /// hosts are about to move.
+    /// The question replaces the group's row of buttons rather than stacking under it — the same rule every
+    /// other row in this application follows — and it is the tallest thing this section draws: a heading, a
+    /// consequence, a boxed count, and now a tick with a sentence beside it asking whether the machines go
+    /// too. The tick is the part worth measuring, because it is a wrapping paragraph inside a control whose
+    /// own height the layout does not obviously account for.
     /// </remarks>
     [Fact]
     public async Task TheHostsScreenFitsWhileAGroupDeletionIsBeingConfirmed()
@@ -570,10 +572,43 @@ public sealed class ScreenLayoutTests : IAsyncLifetime
         vault.DeleteGroupCommand.Execute(null);
 
         vault.IsConfirmingGroupDeletion.ShouldBeTrue("the question has to be up for this to measure it");
+        vault.PendingDeletion.ShouldNotBeNull().HasChoice
+            .ShouldBeTrue("the hosts filed under it are what makes this the long shape");
 
         await MeasureHostsAsync(faults => faults.ShouldBeEmpty("with the group question up"));
     }
 
+    /// <remarks>
+    /// <para>
+    /// The group's move panel, which takes that same row of buttons and is the wordier of the two: a
+    /// heading, a combo box, a wrapping paragraph naming everything that travels and everything that does
+    /// not, and two buttons — above a wrap of group cards and the host grid, all of which still have to fit
+    /// under it.
+    /// </para>
+    /// <para>
+    /// The state is set here rather than through <c>MoveGroupCommand</c>, which would refuse: this fixture's
+    /// account holds one vault, and the command declines rather than open a picker with nothing in it. The
+    /// flow that fills it is covered in <c>DodoSSH.Client.App.Tests</c>.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task TheHostsScreenFitsWithTheGroupMovePanelOpen()
+    {
+        await SeedGroupsAsync(3);
+
+        vault.SelectedGroup = vault.Groups[0];
+
+        vault.MoveGroupVaultChoices.Add(
+            new VaultChoiceViewModel(Guid.CreateVersion7(), "Platform Engineering secrets", false));
+
+        vault.SelectedMoveGroupVault = vault.MoveGroupVaultChoices[0];
+        vault.IsMovingGroup = true;
+
+        vault.ShowsGroupActions.ShouldBeFalse("the panel takes the row rather than sharing it");
+
+        await MeasureHostsAsync(faults => faults.ShouldBeEmpty("with the group move panel up"));
+    }
+
     // ---- The vault screen ----
 
     [Fact]
diff --git a/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs b/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
index cf35c3e..6fce402 100644
--- a/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
+++ b/tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs
@@ -3801,13 +3801,20 @@ public sealed class ShellFlowTests : IAsyncLifetime
     }
 
     /// <remarks>
-    /// Deleting a group deliberately does not rewrite the hosts in it — one delete would otherwise become N
-    /// writes, N outbox rows and N chances to merge against a change nobody made — so those hosts keep an id
-    /// that resolves to nothing. "The group is gone" and "this host is in no group" have to look the same,
-    /// because to the person reading the list they are the same thing.
+    /// <para>
+    /// Deleting a group leaves the machines under it alone <em>and</em> stops them naming it. It used to do
+    /// only the first: the reference was left dangling and the list resolved it to nothing, which looked
+    /// identical and cost no writes. The tick is what changed that — a deletion that can take the hosts with
+    /// it has to be a deletion that knows which hosts it means, and once it knows, leaving them holding the
+    /// id of something that has gone is a state kept for no reason.
+    /// </para>
+    /// <para>
+    /// The tick is deliberately not touched here, which is the point of the assertions: the default answer
+    /// is the one that keeps the machines.
+    /// </para>
     /// </remarks>
     [Fact]
-    public async Task DeletingAGroup_LeavesItsHostsUnderTheUngroupedHeading()
+    public async Task DeletingAGroup_UnfilesItsHostsRatherThanLeavingThemNamingIt()
     {
         await UnlockedAsync();
         var vault = shell.Vault!;
@@ -3816,32 +3823,136 @@ public sealed class ShellFlowTests : IAsyncLifetime
         await AddGroupAsync(vault, "production");
         await FileAsync(vault, "prod-db", "production");
 
-        var groupId = vault.Groups.Single().EntityId;
-
         vault.SelectedGroup = vault.Groups.Single();
         vault.DeleteGroupCommand.Execute(null);
 
-        vault.PendingDeletion.ShouldNotBeNull().Usage
+        var question = vault.PendingDeletion.ShouldNotBeNull();
+
+        question.Usage
             .ShouldContain("1 host", Case.Sensitive, "the count is what makes the question worth reading");
 
+        question.HasChoice.ShouldBeTrue("a group with a host under it has a second question");
+        vault.DeletionTakesTheHostsToo.ShouldBeFalse("the safe answer is the one nobody has to choose");
+
+        // The pass that follows every write on this screen reports what it moved and supersedes the
+        // confirmation, for a deletion as much as for a save — so it is made to fail, and what the sentence
+        // says is asserted in the state where somebody actually reads it.
+        server.SyncFailure = new HttpRequestException("The server is having a bad day.");
+
         await vault.ConfirmDeleteCommand.ExecuteAsync(null);
 
         vault.Groups.ShouldBeEmpty();
         vault.HasGroups.ShouldBeFalse();
 
-        // The host keeps the id, which is what makes this cheap; the list is what resolves it to nothing.
-        vault.Hosts.Single().Host.GroupId.ShouldBe(groupId);
+        vault.Hosts.Single().Host.GroupId.ShouldBeNull(vault.Status);
+        vault.Hosts.Single().GroupLabel.ShouldBeEmpty();
         vault.SidebarRows.ShouldAllBe(row => row is HostRowViewModel);
 
-        // The card says the same thing the phone's list does: nothing. An id nobody can name is drawn as no
-        // group rather than as a GUID on a chip.
-        vault.Hosts.Single().GroupLabel.ShouldBeEmpty();
+        vault.Status.ShouldContain("UNGROUPED", Case.Sensitive);
     }
 
     /// <remarks>
-    /// The picker keeps a placeholder entry for a group the vault no longer has, exactly as the
+    /// The other answer, and the reason the question is asked at all: a group is sometimes a heading being
+    /// tidied away and sometimes a project that has been decommissioned, and nothing in the view model can
+    /// tell which of the two it is looking at.
+    /// </remarks>
+    [Fact]
+    public async Task DeletingAGroupWithTheTickSet_TakesItsHostsWithIt()
+    {
+        await UnlockedAsync();
+        var vault = shell.Vault!;
+
+        await AddHostAsync(vault, "prod-db");
+        await AddHostAsync(vault, "prod-web");
+        await AddGroupAsync(vault, "production");
+        await FileAsync(vault, "prod-db", "production");
+
+        vault.SelectedGroup = vault.Groups.Single();
+        vault.DeleteGroupCommand.Execute(null);
+
+        vault.PendingDeletion.ShouldNotBeNull().Choice.ShouldContain("host");
+        vault.DeletionTakesTheHostsToo = true;
+
+        await vault.ConfirmDeleteCommand.ExecuteAsync(null);
+
+        vault.Groups.ShouldBeEmpty();
+
+        // Only the machine that was filed under it. A deletion aimed at a heading must not reach the hosts
+        // that were never on it.
+        vault.Hosts.Select(row => row.Label).ShouldBe(["prod-web"], vault.Status);
+    }
+
+    /// <remarks>
+    /// The answer is not carried from one question to the next. A tick left standing would delete the next
+    /// group's machines on the strength of a decision about the last one's, and there is no undo on either
+    /// side of that.
+    /// </remarks>
+    [Fact]
+    public async Task AskingAboutASecondGroup_StartsFromKeepingItsHosts()
+    {
+        await UnlockedAsync();
+        var vault = shell.Vault!;
+
+        await AddHostAsync(vault, "prod-db");
+        await AddGroupAsync(vault, "production");
+        await AddGroupAsync(vault, "staging");
+        await FileAsync(vault, "prod-db", "production");
+
+        vault.SelectedGroup = vault.Groups.Single(
+            row => string.Equals(row.Label, "production", StringComparison.Ordinal));
+
+        vault.DeleteGroupCommand.Execute(null);
+        vault.DeletionTakesTheHostsToo = true;
+        vault.CancelDeleteCommand.Execute(null);
+
+        vault.SelectedGroup = vault.Groups.Single(
+            row => string.Equals(row.Label, "staging", StringComparison.Ordinal));
+
+        vault.DeleteGroupCommand.Execute(null);
+
+        vault.DeletionTakesTheHostsToo.ShouldBeFalse("every question starts from keeping the machines");
+    }
+
+    /// <remarks>
+    /// Unfiling rewrites every host under the heading, so it is refused with a host editor open for the
+    /// reason a drop onto a group card is: rewriting the saved host under a half-typed edit of it would be a
+    /// save nobody asked for, and one they could then not cancel. Deleting a single host is not refused,
+    /// because that one writes nothing to a form anybody is looking at.
+    /// </remarks>
+    [Fact]
+    public async Task DeletingAGroupWhileTheHostEditorIsOpen_IsRefused()
+    {
+        await UnlockedAsync();
+        var vault = shell.Vault!;
+
+        await AddHostAsync(vault, "prod-db");
+        await AddGroupAsync(vault, "production");
+        await FileAsync(vault, "prod-db", "production");
+
+        vault.SelectedHost = vault.Hosts.Single();
+        vault.EditSelectedHostCommand.Execute(null);
+        vault.EditorLabel = "half-typed";
+
+        vault.SelectedGroup = vault.Groups.Single();
+        vault.DeleteGroupCommand.Execute(null);
+
+        vault.PendingDeletion.ShouldBeNull("the question was never put");
+        vault.IsEditing.ShouldBeTrue("and the edit is still there to finish");
+        vault.Status.ShouldContain("editing");
+    }
+
+    /// <remarks>
+    /// <para>
+    /// The picker keeps a placeholder entry for a group the vault does not have, exactly as the
     /// authentication picker does for a deleted key. Without it the picker would open on "No group" and
     /// somebody editing the host's port would unfile it by saving.
+    /// </para>
+    /// <para>
+    /// The dangling id is imported rather than produced by deleting the group, and that is a consequence of
+    /// the change above rather than a contrivance: a group deleted <em>here</em> now unfiles its hosts on the
+    /// way out, so the only way a host still names one is that the group went on another machine and this
+    /// client has yet to be told — which is exactly what a host arriving with an id nothing resolves is.
+    /// </para>
     /// </remarks>
     [Fact]
     public async Task EditingAHostWhoseGroupIsGone_DoesNotUnfileItBySaving()
@@ -3849,15 +3960,13 @@ public sealed class ShellFlowTests : IAsyncLifetime
         await UnlockedAsync();
         var vault = shell.Vault!;
 
-        await AddHostAsync(vault, "prod-db");
-        await AddGroupAsync(vault, "production");
-        await FileAsync(vault, "prod-db", "production");
+        var groupId = Guid.CreateVersion7();
 
-        var groupId = vault.Groups.Single().EntityId;
+        await vault.ImportHostsAsync(
+            [new HostSecret { Label = "prod-db", Hostname = "db.internal", GroupId = groupId }],
+            Token);
 
-        vault.SelectedGroup = vault.Groups.Single();
-        vault.DeleteGroupCommand.Execute(null);
-        await vault.ConfirmDeleteCommand.ExecuteAsync(null);
+        vault.Groups.ShouldBeEmpty("nothing in this keychain answers to that id");
 
         vault.SelectedHost = vault.Hosts.Single();
         vault.EditSelectedHostCommand.Execute(null);
diff --git a/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs b/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
index c09bdb2..ab0ce0b 100644
--- a/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
+++ b/tests/DodoSSH.Client.App.Tests/VaultSharingTests.cs
@@ -875,6 +875,155 @@ public sealed class VaultSharingTests : IAsyncLifetime
             .EntityId.ShouldBeNull("only 'no parent' is left once the group is going somewhere else");
     }
 
+    /// <remarks>
+    /// <para>
+    /// Moving the shelf rather than what is on it, which is the operation people were attempting one host at
+    /// a time: a group cannot go anywhere alone, because the machines filed under it and the groups nested
+    /// inside it are items of the vault it is leaving. All of them are re-sealed under the destination's key
+    /// and all of them take new ids, so what this asserts is not only that they arrived but that the tree
+    /// arrived — the child is still under the parent, and the host is still under the child, through two
+    /// levels of ids that were rewritten on the way across.
+    /// </para>
+    /// <para>
+    /// The parent the moved group was nested under is asserted <em>gone</em>, and that is the honest half. A
+    /// parent belongs to the vault it is in, so carrying the reference would leave everybody else in the
+    /// destination looking at a group hanging from nothing. It arrives at the top level and the sentence
+    /// says so.
+    /// </para>
+    /// </remarks>
+    [Fact]
+    public async Task MovingAGroupToAnotherVault_TakesItsHostsAndItsNestedGroupsWithIt()
+    {
+        await UnlockedAsync();
+
+        var vaults = shell.Vaults;
+
+        await CreateVaultAsync(vaults, "Platform secrets");
+
+        var vault = shell.Vault!;
+        var sharedVaultId = vaults.SelectedVault!.VaultId;
+
+        await vault.LoadAsync(Token);
+
+        await SeedNestedShelfAsync(vault);
+
+        var production = Named(vault, "production");
+
+        production.VaultId.ShouldNotBe(sharedVaultId, "this test is meaningless with both in one vault");
+        production.Group.ParentId.ShouldNotBeNull("it was nested, which is what has to stay behind");
+
+        vault.SelectedGroup = production;
+        vault.CanMoveGroupTarget.ShouldBeTrue("there is a second vault this session can write to");
+
+        vault.MoveGroupCommand.Execute(null);
+
+        vault.IsMovingGroup.ShouldBeTrue(vault.Status);
+        vault.ShowsGroupActions.ShouldBeFalse("the panel takes the row of buttons rather than sharing it");
+        vault.MoveGroupVaultChoices.ShouldNotContain(choice => choice.VaultId == production.VaultId);
+
+        vault.SelectedMoveGroupVault =
+            vault.MoveGroupVaultChoices.Single(choice => choice.VaultId == sharedVaultId);
+
+        // The pass that follows every write on this screen is made to fail, so that the move's own sentence
+        // is still on the status line to be read — the same arrangement, and for the same reason, as the
+        // host's move test above.
+        server.SyncFailure = new IOException("The server is not answering.");
+
+        await vault.ConfirmMoveGroupCommand.ExecuteAsync(null);
+
+        var moved = Named(vault, "production");
+        var nested = Named(vault, "web");
+
+        moved.VaultId.ShouldBe(sharedVaultId, vault.Status);
+        moved.EntityId.ShouldNotBe(production.EntityId, "an id belongs to one vault");
+        moved.Group.ParentId.ShouldBeNull("a parent belongs to the vault the group came from");
+
+        nested.VaultId.ShouldBe(sharedVaultId, "a group inside it cannot be left in the other vault");
+        nested.Group.ParentId.ShouldBe(moved.EntityId, "and it is still nested under the group it was in");
+
+        var host = vault.Hosts.Single(row => string.Equals(row.Label, "prod-db", StringComparison.Ordinal));
+
+        host.VaultId.ShouldBe(sharedVaultId, "the hosts came with the shelf");
+        host.Host.GroupId.ShouldBe(nested.EntityId, "and are still filed where they were");
+
+        // The group it was nested under is the one thing that stayed, and it stayed where it was.
+        Named(vault, "estate").VaultId.ShouldBe(production.VaultId);
+
+        vault.SelectedGroup?.EntityId.ShouldBe(moved.EntityId, "the buttons follow the group they moved");
+        vault.Status.ShouldContain("Platform secrets");
+        vault.Status.ShouldContain("top level");
+    }
+
+    /// <remarks>
+    /// The move is refused where it would have nowhere to go, by the command rather than by an empty picker
+    /// — the same answer <c>MoveHostCommand</c> gives one level down.
+    /// </remarks>
+    [Fact]
+    public async Task MovingAGroupWithNowhereToMoveIt_SaysSoRatherThanOpeningAnEmptyPicker()
+    {
+        await UnlockedAsync();
+
+        var vault = shell.Vault!;
+
+        await vault.LoadAsync(Token);
+
+        vault.NewGroupCommand.Execute(null);
+        vault.GroupEditorLabel = "production";
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+
+        vault.SelectedGroup = vault.Groups.ShouldHaveSingleItem();
+
+        vault.CanMoveGroupTarget.ShouldBeFalse("the personal vault is the only one there is");
+
+        vault.MoveGroupCommand.Execute(null);
+
+        vault.IsMovingGroup.ShouldBeFalse();
+        vault.MoveGroupVaultChoices.ShouldBeEmpty();
+        vault.Status.ShouldContain("only vault you can write to");
+    }
+
+    /// <summary>The group card with a given name, re-found because every row is replaced on every reload.</summary>
+    private static HostGroupRowViewModel Named(VaultViewModel vault, string label) =>
+        vault.Groups.Single(row => string.Equals(row.Label, label, StringComparison.Ordinal));
+
+    /// <summary>
+    /// Builds estate › production › web in the personal vault, with prod-db on the innermost shelf.
+    /// </summary>
+    /// <remarks>
+    /// Three levels, because two would not tell a subtree that was walked from one that was assumed a single
+    /// level deep — the middle group is the one that has to arrive with a rewritten parent and a rewritten
+    /// child at once.
+    /// </remarks>
+    private static async Task SeedNestedShelfAsync(VaultViewModel vault)
+    {
+        await AddGroupAsync(vault, "estate", under: null);
+        await AddGroupAsync(vault, "production", under: "estate");
+        await AddGroupAsync(vault, "web", under: "production");
+
+        vault.NewHostCommand.Execute(null);
+        vault.EditorLabel = "prod-db";
+        vault.EditorHostname = "db.internal";
+        vault.EditorSelectedGroup = vault.EditorGroupChoices.Single(
+            choice => string.Equals(choice.Label, "web", StringComparison.Ordinal));
+
+        await vault.SaveHostCommand.ExecuteAsync(null);
+    }
+
+    /// <summary>Adds a group, optionally nested under one already there.</summary>
+    private static async Task AddGroupAsync(VaultViewModel vault, string label, string? under)
+    {
+        vault.NewGroupCommand.Execute(null);
+        vault.GroupEditorLabel = label;
+
+        if (under is not null)
+        {
+            vault.GroupEditorSelectedParent = vault.GroupEditorParentChoices.Single(
+                choice => string.Equals(choice.Label, under, StringComparison.Ordinal));
+        }
+
+        await vault.SaveGroupCommand.ExecuteAsync(null);
+    }
+
     /// <remarks>
     /// <para>
     /// Dragging a host card onto a group card is the one gesture that files a host without opening its