Docs: the 2026-10-02 audit reports, the full sweep and the Android design audit, with their screenshots

REPORT.md is the full-app sweep and what became of each finding. ANDROID-DESIGN.md is a walk through every phone screen on the emulator, from a cleared install to SFTP, with findings ranked by severity and a screenshot for each. The home-folder listing in the sweep's transfers screenshot is blurred.
Sync: after a read from the beginning, remove what the server no longer has, and flag an edit that brings a forgotten item back
2026-10-03 11:43:03 +02:00 · 2026-10-02 17:36:11 +02:00 · 2026-10-02 17:36:03 +02:00 · 2026-10-02 17:18:22 +02:00 · 2026-10-02 16:20:51 +02:00 · 2026-10-02 15:27:39 +02:00
341 changed files with 39277 additions and 1383 deletions
@@ -29,6 +29,18 @@ jobs:
  build:
    name: build and test
    runs-on: [linux]
    # ◆ A CEILING, BECAUSE THIS FILE HAD NONE AND A HUNG TEST RAN UNTIL SOMEBODY NOTICED.
    #
    # One test in DodoSSH.Client.App.Tests waited on a named pipe that, on Linux, nothing was ever going
    # to answer — and it waited on a token with no timeout, so the job did not fail, it sat there. It was
    # killed by hand after twenty minutes, having reported nothing but the eighteen suites that had
    # already passed.
    #
    # Twenty-five minutes against a job that ordinarily takes three. It is not a performance budget and
    # must not be read as one: a build that legitimately grows past this should have the number raised.
    # What it buys is that the failure mode is a red job with a named step rather than a runner somebody
    # has to go and stop.
    timeout-minutes: 25
    steps:
      # act_runner runs every `uses:` action with node inside the job container, and this
      # runner's image has none — the run died on the first line of actions/checkout with
@@ -220,7 +232,12 @@ jobs:
      - name: build
        run: dotnet build DodoSSH.slnx --no-restore --configuration Release
      # Tighter than the job's own ceiling, and deliberately so: a hang here is the likeliest of the
      # lot — it is the only step running code written for this repository rather than a tool — and a
      # step-level timeout names the step in the failure instead of leaving a reader to work out which
      # of fifteen was still running. Ten minutes against a suite that takes two.
      - name: test
        timeout-minutes: 10
        run: dotnet test DodoSSH.slnx --no-build --configuration Release
      # The one build shape nothing else here exercises: a self-contained RID-specific publish. Its
@@ -556,6 +573,8 @@ jobs:
          exit 0
  android:
    name: android head
    # See the build job. The docker pull and the toolchain image make this one legitimately slower.
    timeout-minutes: 40
    runs-on: [linux]
    # Writes the nightly release at the end of the job; see that step for what the capability is and why
    # it is acceptable here and nowhere else. Job-scoped, so nothing else in this file gains it.
@@ -915,7 +934,10 @@ jobs:
          # never made.
          published="$(curl -fsS -H "$auth" "$api/releases/$release")"
          for name in $names; do
-            if ! printf '%s' "$published" | grep -qF "\"name\":\"$name\""; then
+            # grep without -q, which has the same exit status and reads to the end of its input. A
            # reader that stops early under pipefail turns the writer's SIGPIPE into this condition's
            # answer; see the note in scripts/ci-linux-rpm.sh, where that cost a green build.
            if ! printf '%s' "$published" | grep -F "\"name\":\"$name\"" >/dev/null; then
              echo "The release was created but $name is not on it:" >&2
              printf '%s\n' "$published" >&2
              exit 1
@@ -926,6 +948,8 @@ jobs:
  desktop:
    name: desktop nightly
    # See the build job. Two publishes, a pack and an upload of about 120 MB.
    timeout-minutes: 40
    # Gated on the tests, like the image job and for a stronger version of its reason: this one is
    # installed by people and replaces itself afterwards. Nothing anybody runs should come out of a
    # commit whose suite was red.
@@ -1226,7 +1250,10 @@ jobs:
          published="$(curl -fsS -H "$auth" "$api/releases/tags/$TAG")"
          for name in releases.win-nightly.json DodoSSH.Desktop.Nightly-win-nightly-Setup.exe; do
-            if ! printf '%s' "$published" | grep -qF "\"name\":\"$name\""; then
+            # grep without -q, which has the same exit status and reads to the end of its input. A
            # reader that stops early under pipefail turns the writer's SIGPIPE into this condition's
            # answer; see the note in scripts/ci-linux-rpm.sh, where that cost a green build.
            if ! printf '%s' "$published" | grep -F "\"name\":\"$name\"" >/dev/null; then
              echo "The release was created but $name is not on it:" >&2
              printf '%s\n' "$published" >&2
              exit 1
@@ -1279,7 +1306,8 @@ jobs:
          # upload it never made.
          withRpm="$(curl -fsS -H "$auth" "$api/releases/$release")"
          for name in $linuxNames; do
-            if ! printf '%s' "$withRpm" | grep -qF "\"name\":\"$name\""; then
+            # grep without -q; see the sibling loops above and scripts/ci-linux-rpm.sh.
            if ! printf '%s' "$withRpm" | grep -F "\"name\":\"$name\"" >/dev/null; then
              echo "The release was created but $name is not on it:" >&2
              printf '%s\n' "$withRpm" >&2
              exit 1
@@ -1290,12 +1318,27 @@ jobs:
  image:
    name: api image
    # See the build job. A cold layer cache is the slow case here.
    timeout-minutes: 40
    # Gated on the tests rather than parallel with them, which costs a few minutes of wall
    # clock on every main commit and buys the thing worth having: no image reaches the
    # registry from a commit whose tests were red. An image is not a build artefact anyone
    # inspects — it is the thing that gets deployed.
    needs: [build]
    runs-on: [linux]
    # Gitea's own container registry, on the forge this workflow runs on, under the same owner as
    # the repository - so the image is listed with the repository's packages rather than on a
    # registry of its own. Lowercase, because an image reference may not contain capitals and
    # the owner is DodoTech-Public.
    #
    # REGISTRY_USERNAME and REGISTRY_PASSWORD are a Gitea account and a token of its own with
    # package read and write, allowed to publish for that owner. Not the job's built-in
    # GITEA_TOKEN, tempting as it is here: the container registry does not accept an Actions
    # task token and answers `unauthorized` at /v2/ (go-gitea/gitea#23642). Spelunk's workflow
    # pushes the same way, with the same two secrets.
    env:
      REGISTRY: git.dodotech.cloud
      IMAGE: dodotech-public/dodossh-api
    steps:
      # Duplicated from the build job; see the comment there for why it cannot be factored
      # out. Any change here has to be made in all three.
@@ -1421,9 +1464,6 @@ jobs:
      # changes, and where setup-buildx-action starts earning its place.
      - name: work out the tags
        id: tags
        env:
          REGISTRY: registry-docker.dodotech.cloud
          IMAGE: dodotech/dodossh-api
        run: |
          set -euo pipefail
          repo="$REGISTRY/$IMAGE"
@@ -1548,7 +1588,7 @@ jobs:
          echo "username: ${#REGISTRY_USERNAME} characters; password: set"
          printf '%s' "$REGISTRY_PASSWORD" \
-            | docker login registry-docker.dodotech.cloud \
+            | docker login "$REGISTRY" \
                --username "$REGISTRY_USERNAME" --password-stdin
      - name: push
@@ -1566,7 +1606,7 @@ jobs:
      # does not leave it behind.
      - name: log out
        if: always() && github.event_name != 'pull_request'
-        run: docker logout registry-docker.dodotech.cloud
+        run: docker logout "$REGISTRY"
 # No job here publishes the desktop *release* channel, and there is not going to be one. The desktop
 # nightly job above publishes a different application — its own pack id, its own Velopack channel, its own
@@ -87,9 +87,16 @@ Releases/
 *.pfx
 *.p12
 *.snk
 # Signing keystores, with one exception that is tracked deliberately. build/nightly.keystore is
 # committed in the open on purpose — see ADR 0014 for why a key everybody holds is what makes the
 # nightly channel safe to run in CI — and a file already tracked is unaffected by an ignore rule
 # anyway. The negation is here so that reading this list does not suggest the tracked one is an
 # oversight. The *release* keystore is a real secret under ADR 0011 rule 1 and must never land here.
 *.keystore
 *.jks
 !build/nightly.keystore
 appsettings.Local.json
 appsettings.*.Local.json
 .env
 .env.*
 !deploy/.env.example
 secrets/
@@ -44,7 +44,7 @@ Three consequences worth knowing before you read further:
 The reasoning behind each major decision is recorded in [`docs/adr/`](docs/adr/), starting with
 [the E2EE trust model](docs/adr/0001-e2ee-trust-model.md).
-The desktop client's interface was built from a design covering more product than exists yet — file
+The desktop client's interface was built from a design covering more product than existed at the time — file
 transfer, teams, saved snippets, port forwarding. Everything that design asked for and this build has not
 got is written down in [`docs/design-import-gaps.md`](docs/design-import-gaps.md), with the layer each
 piece would land in and what the interface shows in its place. Nothing was rendered with invented data to
@@ -69,7 +69,8 @@ src/
  DodoSSH.Client.Terminal  the loopback data plane and credit-based flow control
  DodoSSH.Client.Transfer  the transfer queue, part files and resume, and the local file listing
  DodoSSH.Client.ObjectStore  S3-compatible buckets, behind the same interface as SFTP
-  DodoSSH.Client.Import    reading ~/.ssh/config, and the keys it names when asked
+  DodoSSH.Client.Import    reading ~/.ssh/config and the keys it names when asked; reading a Hetzner
                           Cloud project over its API
  DodoSSH.Client.Shell     the view models both heads drive, the renderer's files, the palette
  DodoSSH.Client.App       the desktop head: its views, and its Windows, macOS and Linux integration
  DodoSSH.Client.Android   the phone head: its views, and its Android integration
@@ -425,6 +426,90 @@ What is not here: transferring a directory, dragging between the panes, and rout
 bastion — the last needs jump hosts the connection layer has not got. All three are in
 [`docs/design-import-gaps.md`](docs/design-import-gaps.md).
 ### Forwarding ports
 A host can carry **port forwards**, added under PORT FORWARDS in its editor, in the three kinds OpenSSH has:
 **local** (`-L`, a port here reaching a machine the remote can see), **remote** (`-R`, a port on the remote
 reaching back to one this machine can see) and **dynamic** (`-D`, a SOCKS proxy here whose connections leave
 from the remote). They are saved in the host's encrypted payload, so they sync, merge and are shared with the
 host, and they start with every terminal opened to it, on either head. The session sidebar lists them under
 FORWARDS with the state of each, and the status bar counts the ones listening; on the phone the same list is a
 sheet off the terminal's bar.
 Three things about them are worth expecting rather than discovering.
 **Everything listens on localhost, and there is no setting for it.** A forward is a field any member of a
 shared keychain can fill in, and one bound to every interface would hand the remote's network to anybody who
 can reach your machine for as long as the terminal is open. A remote forward asks the remote for its loopback
 too; whether the remote honours that is its own `GatewayPorts`.
 **A forward lives as long as its terminal.** It runs over that tab's connection, so closing the tab, losing
 the connection or reconnecting stops it — a reconnect starts the host's forwards again on the new session. A
 second tab to the same host runs the same forwards, and they fail there because the ports are taken; the row
 says so, and the terminal is unaffected. Any row can be switched off and on while its session is up.
 **No byte counts**, which the design draws: SSH.NET keeps none, so a number there would be invented. The
 phone runs forwards too, listed behind a `⇄` in its terminal's bar, but cannot edit them yet; see
 [The Android head](#the-android-head).
 ### Reaching a server through Spelunk
 A server managed by Spelunk runs Spelunk's agent, which keeps a connection open to Spelunk. DodoSSH can use
 that connection instead of dialling: tick **Connect through Spelunk** in the host editor and fill in
 Spelunk's API address, the server's id in Spelunk, and your Spelunk API key. A connection then asks Spelunk
 for a ticket, opens a WebSocket, and the agent connects to the SSH server on the machine's own loopback — so
 the server needs no open SSH port at all. Shells and file transfers both go this way; the relay and Spelunk
 are one choice, and ticking one unticks the other.
 - **Fill in the API key once, under Settings → Security → Spelunk.** Give Spelunk's API address and paste
  the key (`spelunk_…`, with the Admin role). It is saved as a *Spelunk key* in your personal vault —
  encrypted, synced to your other devices, never shown again — together with the address, and **it is only
  ever sent to that address**: a host that names the key with any other address is refused at connect. One
  key serves every server in that Spelunk organisation; saving a key for an address that already has one
  replaces it, and every host using it connects with the new key. The host editor offers saved keys first
  and picks the one for the address you type. The API address must be `https://`, except for a Spelunk on
  this machine.
 - A key kept the older way, as a credential's password, still works and is still offered in the editor;
  its password goes to whatever address the host names.
 - **The hostname and port still matter**, though nothing dials them: the host key is pinned under them as it
  is for every host, and the port is what the agent connects to on the server.
 - **There is no falling back to a direct dial**, and a refusal is said in Spelunk's terms: a key Spelunk will
  not take, a key whose role is too low, a server outside the key's organisation, an agent that is not
  connected, an agent that could not reach the SSH port or is too old to open terminals.
 **Sign in through Spelunk (no SSH key needed)**, the box under the key in the same card, lets Spelunk log
 you in instead of an SSH key or password of the host's own. For each connection DodoSSH makes a throwaway
 Ed25519 key pair in memory and sends the public half with the ticket request, which the API key authorises;
 the agent runs a one-connection `sshd -i` on the server whose only authorised key is that one, and says
 which account it logs in as (`root`). It is real SSH to the server's real host key, so shells, file
 transfers and port forwards all work, and the key is gone with the connection — it is never stored,
 synced or logged. The login and authentication choices are greyed out while it is ticked and saved as
 nothing. The server needs OpenSSH's `sshd` installed (not running, and no open port); an agent too old
 to sign in, or a server without `sshd`, is said so. Such a host is written at host schema version 10,
 so a DodoSSH older than this shows it read-only.
 **"Open in DodoSSH" in Spelunk** starts DodoSSH with a `dodossh://spelunk/connect?api=…&server=…&name=…&host=…`
 link, or hands the link to the copy already running, and **connects straight away.** The link never
 carries a credential. The hosts links make live in your personal vault, tagged `spelunk`:
 - If your personal vault has a host tagged `spelunk` for that server on that Spelunk, DodoSSH connects to it.
 - Otherwise, when you have saved a Spelunk key for that Spelunk under Settings → Security — or a saved host
  already sends an API key there — DodoSSH saves a new host in your personal vault — named as the link
  names it, at the link's address (or `spelunk-<server id>`), port 22, signing in through Spelunk with that
  key, tagged `spelunk` (the tag is made if the vault has none) — and connects to it. It syncs like any host
  you saved yourself.
 - **A link from a Spelunk with no key** opens the host editor instead, filled in the same way with sign-in
  ticked and the tag on, and you choose that Spelunk's API key once and save. Every later link from that
  Spelunk connects straight away. A link can be sent by anything on this machine, so an API key is never
  sent to an address you have not sent it to — saving the key under Security is how you say you have.
 A host you set up by hand, or one in a team's vault, is left as it is: a link for its server adds a host of
 its own. A link that arrives while the vault is locked waits for the unlock.
 The Windows installer registers the scheme for your user and removes it on uninstall, the macOS bundle
 declares it in its `Info.plist`, and the Linux package's desktop entry declares `x-scheme-handler/dodossh`.
 The phone reaches Spelunk hosts the same way but does not answer links yet.
 ### Sharing a vault
 **VAULTS** in the nav rail lists every vault you can see, makes new ones, adds people to one,
@@ -640,8 +725,9 @@ its host if it has one and back into the box if it does not.
 **A connected phone shows one bar and then the terminal.** The header, the session strip and the bottom
 bar are collapsed while a shell is up, and a single 35-pixel row replaces them: back on the left, the
 sessions as pills, and a `+` on the right offering the three connections this application can make — a
-shell, a host's files over SFTP, or a bucket. The system back gesture does what the arrow does, and lowers
+shell, a host's files over SFTP, or a bucket. Beside the `+`, for a tab whose host has port forwards, a `⇄`
-that menu first if it is open.
+opens them; see below. The system back gesture does what the arrow does, and lowers either sheet first if
 one is open.
 Widening the rail moved the desktop window's minimum from `880x560` to `1016x574`, which leaves every
 screen exactly the width it was designed against.
@@ -709,10 +795,25 @@ What it does *not* yet do is use the extra width inside a screen: the host list
 size. Two columns needs the row model to change — the list is headings and hosts in one sequence, and a
 heading has to span — which is shared with the desktop and is its own piece of work.
-**Port forwarding is not built anywhere**, and the phone's More screen says so in a paragraph rather than
+**Port forwarding runs here too, and is edited on the desktop.** A host's forwards start with every
-leaving a gap. The v2 design draws a whole screen for it; nothing in the SSH layer forwards anything, so
+terminal the phone opens to it, as they do on the desktop. The terminal's bar grows a `⇄` for a tab that has
-every control on that screen would have had no effect. See
+any, carrying the number listening in green, or turning red when one could not start; it opens a sheet
-[`docs/design-import-gaps.md`](docs/design-import-gaps.md).
+listing the tab's forwards with their route, their state, the reason a failed one gave, and a tap on each to
 switch it off or on — the desktop sidebar's FORWARDS section, over the same rows. The v2 design's whole
 FORWARDING screen is not drawn, for the reason the desktop has none: a forward belongs to a host and runs
 with a session, and both already have a place. What the phone has not got is an editor for them — its host
 form has no PORT FORWARDS section — so they are added on the desktop and arrive with the host; the More
 screen says so in a paragraph.
 Forwards ride the **keep-alive** a shell already has. A forward runs over its tab's connection, so the
 foreground service that holds a shell open in the background is holding its forwards open too, and nothing
 else needs to: the service is never started for a forward alone, because there is never a listening forward
 without a live shell. What forwards change is the notification, which counts them beside the shells —
 `1 shell connected · 2 ports forwarded` — because a phone in a pocket holding ports open is something its
 owner should be able to see. Local and SOCKS forwards listen on the phone's own loopback, which every app on
 the phone can reach; that is what makes one useful here — a database client on the phone reaching a server
 behind the remote — and it is the same exposure the desktop's localhost has to its own processes. See
 [Forwarding ports](#forwarding-ports) and [`docs/design-import-gaps.md`](docs/design-import-gaps.md).
 It is deliberately **not** in `DodoSSH.slnx`. Putting it there would make the `android` workload and a full
 Android SDK a prerequisite of `dotnet build DodoSSH.slnx` for everybody; it has its own CI job instead, which
@@ -872,6 +973,13 @@ keychain plus a terminal — and the spike that gates all of it.
  [Moving files](#moving-files) for the two things about it worth knowing before you use it, both of which
  are consequences rather than choices.
  *Relay done:* a host with "Connect through the server relay" ticked is reached through the deployment,
  for a machine this one cannot dial. The server issues a single-use, thirty-second ticket for that host
  alone, resolves its address and checks it against a deny list with no configuration escape — loopback,
  link-local, metadata endpoints — and then pipes raw TCP; the SSH session still ends on your machine, so
  the relay sees ciphertext. It is off by default (`Relay:Enabled`), and it only helps when the server can
  reach what you cannot. See [ADR 0004](docs/adr/0004-relay-authorization.md).
  *Organising done:* hosts can be filed into groups, and commands can be saved as snippets. Both are ordinary
  synced items — encrypted, merged and pushed like every other — and both are invisible until used: a
  keychain with no groups draws the flat host list it always did. Two things about them are deliberate.
@@ -0,0 +1,328 @@
 # Android design audit — 2026-10-02
 Run on the emulator (`dodossh_api36`, Pixel 5 profile, 1080×2340 @ 440 dpi, Android 16). It used a
 standalone **Debug** APK from `main` at `858e362`, against a local API, Keycloak and a throwaway `sshd`.
 The walk went from a cleared install through sign-in, enrolment, recovery code, unlock, adding a host,
 connecting, host-key trust, terminal, and every Settings sub-page.
 Screenshots are in [`android/`](android/), downscaled. The recovery-code screen can't be captured,
 because `FLAG_SECURE` blocks it, so it was reviewed from its markup and the accessibility tree.
 **How to read the evidence.** "a11y tree" means `uiautomator dump`, which reads what TalkBack and any
 other accessibility service see. Times and hangs come from a Debug build on an emulator (JIT, no AOT),
 so treat any performance note as "confirm on Release".
 ---
 ## What works well
 - **Connection progress card** ([11](android/11-connecting.png)): five named steps, the current one lit,
  with *close* and *logs* available while it's in progress.
 - **Host-key sheet** ([13](android/13-host-key.png)): "UNKNOWN HOST KEY", first contact, the algorithm,
  the full SHA256 fingerprint, and an instruction to compare. **TRUST AND CONNECT** and **CANCEL** are
  both full width.
 - **Recovery-code screen**:
  - no back and no skip;
  - **CONTINUE** stays disabled until the tick;
  - a full-width **COPY CODE**;
  - capture is blocked.
 - **Terminal** ([14](android/14-terminal.png)):
  - resizes above the keyboard;
  - the two-row accessory bar (esc, tab, ctrl, `| - ~ /`, arrows, A−/A+) stays reachable;
  - the open-sessions strip and the tab strip are clear.
 - **Busy states**: enrolment disables its fields and button and explains the wait ("deliberately takes a
  moment").
 - **Touch targets** measure 44 dp or more almost everywhere: checkboxes, buttons, rows.
 - **Back** closes sheets. The soft keyboard's ✓ submits single-field forms (unlock, connect).
 - **Copy is honest and specific**, e.g. "works with no network — the keychain decrypts on this phone",
  and the Vaults explanation.
 ---
 ## Critical / high
 ### H1 · Password fields expose their plaintext to accessibility services
 - **What:** the vault passphrase field ([05](android/05-unlock-prefilled.png)) and the SSH password field
  ([10](android/10-connect-sheet.png)) both report `password="false"` in the a11y tree. Their `text`
  attribute is the secret itself, in clear.
 - **Evidence:** the a11y tree on both screens; the values matched exactly what was typed (redacted here).
 - **Why it matters:** any installed app holding an accessibility service can read every passphrase and
  host password typed into DodoSSH. That's a common Android malware technique. TalkBack would also read
  the passphrase aloud character by character.
 - **Where:** `TextBox.secret` sets `PasswordChar` and `ContentType=Password`
  (`Theme/Phone.axaml:583`). That's correct for the input method, but Avalonia's Android automation peer
  ignores it.
 - **Fix:** give secret boxes an automation peer that reports `IsPassword` and returns no value. At
  minimum, override the exposed text on `TextBox.secret`. File it upstream with Avalonia as well. Check
  the desktop's UIA peer for the same leak.
 ### H2 · The passphrase survives enrolment and pre-fills the unlock box
 - **What:** right after the recovery code, the unlock screen already holds the passphrase (16 dots;
  [05](android/05-unlock-prefilled.png)) beside "Unlock with the passphrase you just chose."
 - **Why:** `ConfirmRecoveryCode` clears `RecoveryCode` from memory on purpose ("keeping it in a view
  model … would undo that"), but `Passphrase` is never cleared after enrolment. Combined with H1, it's
  readable from the a11y tree on that screen. It also skips the one moment that proves the user
  remembers the passphrase.
 - **Fix:** clear `Passphrase` and its confirmation when enrolment completes, as the recovery code is
  cleared.
 ### H3 · A hardware Enter that submits the connect sheet leaves the window "not responding"
 - **What:** I typed the password and pressed Enter (an injected `KEYCODE_ENTER`, which is what a
  Bluetooth or DeX keyboard sends). The connection started, but Android reported the window
  unresponsive. The key-up was never acknowledged (`InputDispatcher: Waited 5009ms for
  KeyEvent … ENTER … action=UP`). The ANR dialog then kept coming back
  ([12](android/12-anr.png)) until the process was killed. Meanwhile the main thread was idle in
  `Looper.pollOnce`: it wasn't busy, the event was simply lost.
 - **Not affected:** tapping **CONNECT**, and the soft keyboard's ✓ (which sends an editor action, not a
  key event). Both connected cleanly.
 - **Likely cause:** focus moves to the terminal's native renderer (`Platform/RendererFocus.cs`) while
  the Enter key-up is still in flight.
 - **Repro:** host row → type password → hardware Enter.
 - **Confidence:** reproduced once, and an accessibility dump was running at the time. Confirm on a real
  device with a keyboard.
 ### H4 · Screen-reader names are type names across the app
 The a11y tree announces these:
 | Control | Announced as |
 |---|---|
 | Bottom nav (Hosts / Connections / Settings) | `Avalonia.Controls.Panel` ×3 |
 | Add-sheet rows, Settings rows, session chip | `Avalonia.Controls.StackPanel` / `Avalonia.Controls.Grid` |
 | Keychain filter chips | `Avalonia.Controls.StackPanel` ×5 |
 | Host list rows | `DodoSSH.Client.Shell.ViewModels.HostRowViewModel` |
 | Host editor dropdowns | `AuthenticationChoice { Kind = Typed, EntityId = , … }`, `GroupChoice { … }` |
 | Vault row | `VaultRowViewModel { VaultId = 01a0fe77-… }` (leaks an internal id) |
 | FAB / header add | `+` (no name) |
 | Decorative glyphs | `⌕ ▤ ⌗ ⚙ ⚿ ❯ ⇅ ◳ ≡ ◎ ›` exposed as text |
 There are two further problems:
 - **Hidden content:** the hosts list stays in the tree under the full-screen host editor, so a
  screen-reader user can wander into a screen they can't see.
 - **Leftover desktop controls:** the desktop scrollbar's "Line up / Page down" buttons are exposed too.
 **Fix:** set `AutomationProperties.Name` on every button whose content isn't a string. Give row
 templates a name, or override `ToString` on the row view models. Mark glyph `TextBlock`s
 `AutomationProperties.AccessibilityView="Raw"`. Hide covered content from the tree while an editor
 covers it.
 ### H5 · Copying the recovery code isn't marked sensitive
 `CopyRecoveryCode` goes through Avalonia's plain `SetTextAsync` (`App.axaml.cs:187`). On Android 13+,
 the system shows a clipboard preview of the copied text. That overlay is system UI, so this screen's
 `FLAG_SECURE` doesn't cover it, and Gboard keeps the text in its clipboard history. Use a native
 `ClipData` with `ClipDescription.EXTRA_IS_SENSITIVE` for any secret the app copies. (Read from code;
 not observed, because the screen can't be captured.)
 ---
 ## Medium — visual system
 ### M1 · The accent glow is clipped to a square on every primary button and the FAB
 Each gradient button sits on a slightly lighter rectangle, and its corners show past the rounded shape:
 - [z-glow-button](android/z-glow-button.png): SIGN IN, CREATE THE VAULT, UNLOCK, CONNECT, SAVE, ADD
  FILES;
 - [z-glow-fab](android/z-glow-fab.png): the round FAB sits inside a visible square.
 `AccentGlow` (`0 0 22 0`) is set on the template's `ContentPresenter`
 (`Phone.axaml` `Button.primary` / `Button.fab /template/ ContentPresenter`) and gets clipped to the
 button's own bounds. The desktop's `Button.accent` uses the same pattern, so check it there too. Fix:
 draw the glow from an unclipped wrapper (a `Border` with margin), or drop it on the phone.
 ### M2 · Body copy is monospace, against the shared-typeface decision
 `docs/design-import-gaps.md` ("The phone catches up") records that the phone shares the desktop's
 faces. On the desktop, prose (`hint`, `heading`, the settings titles and captions) is Montserrat, and
 mono is kept for identifiers (`.mono`) and labels (`.label`). On the phone, `TextBlock.body`, `.title`
 and `.detail` all still set `MonoFont` (`Phone.axaml:661–680`). So every paragraph, title and caption is
 JetBrains Mono, and only screen headers (Personal, Settings, New host) are Montserrat. The result is
 long, wide-set paragraphs that are tiring to read ([03](android/03-enrol.png),
 [16](android/16-settings.png), [19](android/19-sftp.png)).
 Keep mono for labels, buttons (the recorded ALL-CAPS-mono convention), addresses and code. Move
 `.body`, `.title` and `.detail` to the default sans.
 ### M3 · Fluent's selection fill leaks into the host list
 After a connect, the tapped row stays lit in `#3d486b` ([15](android/15-selected-row.png)). That
 slate-blue isn't in `Palette.axaml`, which says selection is `Active` `#1E1E2C`. The comment at
 `HostsScreen.axaml:360` says the selection fill was deliberately removed ("a lit row would be a mark
 with no action behind it"). But only the custom `Border.hostrow.chosen` style was changed. Fluent's
 `ListBoxItem:selected /template/ ContentPresenter` background was never overridden.
 ### M4 · Disabled secondary buttons are heavier than enabled ones
 `Button.secondary` has no `:disabled` style, so Fluent's `#3c3c43` slab shows through. SFTP's disabled
 **SAVE FILE** is the most prominent button in its row ([z-sftp-actions](android/z-sftp-actions.png)).
 Mirror `Button.primary:disabled`: a `Raised` fill and `TextFaint` text.
 ### M5 · Unstyled Fluent controls among styled ones
 - **Dropdowns:** `ComboBox` keeps Fluent's ~4 px radius, bright white border and black fill beside
  10 px, softly bordered fields (host editor, SFTP host picker; [08](android/08-host-editor.png)).
 - **Checkboxes:** the default `CheckBox`, with its label sitting below the box's centre (relay, remember
  password, press-Enter; [10](android/10-connect-sheet.png)).
 - **Focused fields:** the fill switches from `Field` to pure `#000`.
 - **Scrollbars:** desktop scrollbars are always visible. On Keychain, the horizontal bar is drawn over
  the bottom of the filter chips ([17](android/17-keychain.png)). Android expects auto-hiding overlay
  bars.
 - **Stuck hover:** after a tap, Vaults' ↻ keeps a grey hover square. Touch has no hover, so
  `:pointerover` styles need a touch-safe variant.
 ### M6 · The terminal's colour and font have drifted from the palette
 `WebAssets/terminal.css` says its `#171a26` background "is `TerminalSurface` in Palette.axaml". The
 palette now says `#18161F`. The terminal therefore reads navy, against the app's purple-black
 ([14](android/14-terminal.png)). Its font stack starts at `ui-monospace` and never names the embedded
 JetBrains Mono, so on Android the WebView falls back to the system mono. That makes two different
 monospace faces on one screen.
 ### M7 · Iconography
 - **Glyphs, not icons:** the phone uses Unicode glyphs (`⚿ ❯ ⇅ ◳ ≡ ◎ ⚙ ▤ ⌗ ⌕`), even though Material
  Icons is embedded and the desktop uses it. Weights and optical sizes vary (the heavy purple `❯` beside
  hairline `◳`; [16](android/16-settings.png)).
 - **Reused meanings:** ⚙ is both the Settings tab and the Preferences row, and ⚿ is both Keychain and
  "Lock the keychain".
 - **Splash:** the splash shows a flat purple circle, while the app's own icon is a rounded square with
  the gradient.
 ---
 ## Medium — information architecture and flows
 ### M8 · "Settings" holds the product
 Keychain, Snippets, SFTP, S3, Logs and Vaults all sit under the ⚙ **Settings** tab, beside
 Preferences and Lock ([16](android/16-settings.png)). File transfer and snippets are working tools, not
 settings. Options:
 - rename the tab ("More" or "Tools") and keep Preferences as one row in it;
 - or promote SFTP to the bottom nav. Its icon is already ⇅.
 ### M9 · Keychain can't add anything
 The empty state says "Add an SSH key or a password to stop typing one" ([17](android/17-keychain.png)).
 The screen has no add control: no FAB, no header +, nothing in the a11y tree. Passwords can only be
 created from the host editor's "+ NEW CREDENTIAL", and no phone path adds an SSH key. If keys are
 desktop-only, the empty state should say so.
 ### M10 · Three ways to add, two ways to edit
 - **Add:** Hosts has a FAB, Snippets a header "+", Keychain nothing, and the terminal's header "+"
  means "new session".
 - **Edit:** the host editor is a full-screen page with ← and ✓ ([08](android/08-host-editor.png)). The
  snippet editor is an inline card with **SAVE/CANCEL**, and the header "+" stays live while it's open
  ([18](android/18-snippet-editor.png)).
 Pick one pattern for each.
 ### M11 · SFTP
 - **Action block:** it covers more than half the screen (seven buttons, a permanent help paragraph and a
  status line), so only about four file rows are visible ([19](android/19-sftp.png)).
 - **No selection:** RENAME, MOVE, PERMS and DELETE are enabled with nothing selected. Tapping one only
  writes "Choose something on the host to rename." into the status line at the bottom.
 - **DELETE:** neutral-styled here, while delete is danger-red on hosts and the keychain.
 - **Directory rows:** marked only by a tiny purple ▸, with no folder icon.
 - **Password again:** it's asked for again although a shell to the same host is already open.
 - **S3:** blocked while an SFTP session is open. Tapping S3 bounces to SFTP, with "An SFTP session is
  open. Close it before opening a bucket." at the bottom ([20](android/20-s3-bounced.png)).
 Suggestion: a contextual action bar that appears with a selection, help moved behind an ⓘ, and the
 listing given the screen.
 ### M12 · Bottom sheets
 - **Partial scrim:** the scrim covers only the content area. The header (with **LOCK**) and the bottom
  nav stay bright and tappable under every sheet ([07](android/07-add-sheet.png),
  [10](android/10-connect-sheet.png)).
 - **Decorative handle:** it has a drag handle, but swipe-down doesn't dismiss.
 - **Button order:** the primary action is on the left (CONNECT | CANCEL, SAVE | CANCEL). Android puts
  the confirming action on the right.
 - **No autofocus:** the connect sheet's password field isn't focused on open, so it takes an extra tap.
 - **Nav above keyboard:** the bottom nav rides up above the keyboard and eats the sheet's space
  ([13 before trust](android/13-host-key.png)).
 ### M13 · Sign-in and enrolment
 - **Full browser:** sign-in opens a full Chrome tab (`ChromeTabbedActivity`), not a Custom Tab, so the
  user leaves the app. Chrome's own first-run prompts then land on top.
 - **Unannounced second sign-in:** step 2 asks for a passphrase, and **CREATE THE VAULT** then sends the
  user to the identity provider's login form a second time. That's the deliberate `prompt=login` key
  binding (`OidcClient.AuthorizeKeyBindingAsync`), but no copy warns that it's coming. Say "you'll
  confirm your identity once more" on the passphrase screen.
 - **Blank resume:** after the browser returns, the app showed a blank `#05050a` canvas for 5–10 s with
  no progress indicator. Every shell state has a screen, so this looks like surface re-creation on
  resume (Debug + emulator). Confirm on Release, and keep a visible state on screen while it happens.
 - **Step labels:** start at "STEP 2 OF 3"; step 1 is never labelled.
 ### M14 · The global status line leaks across screens
 A single `StatusMessage` follows the user around:
 - "Unlocked 'Personal'." in the middle of Preferences ([21](android/21-preferences.png));
 - "Synchronised: 2 in, 2 out." after adding one host. `Describe` counts `Pulled`/`Pushed`, which include
  the app's own log entries, while `PulledItems`/`PushedItems` already exist for this;
 - "audit-box asks for a password." repeated under the sheet that asks for it.
 Scope messages to the screen that raised them, or use transient snackbars.
 ---
 ## Low — input, copy, polish
 - **Keyboards:**
  - the server URL field gets a text keyboard with contact suggestions, not the URL keyboard
    ([02](android/02-server-keyboard.png));
  - the port field gets the full letter keyboard ([z-port-keyboard](android/z-port-keyboard.png));
  - hostname and username get autocorrect suggestions.
  Set `TextInputOptions.ContentType` (`Url`, `Digits`) and turn autocorrect off for those.
 - **Placeholder-as-label:** name, hostname, username and notes in the host editor, the unlock field,
  and the snippet fields have no labels, so each field's meaning disappears once typed in.
 - **Terminology:**
  - "CREATE THE VAULT", then "Creating your keychain";
  - "vault passphrase" (placeholder) next to "Enter your keychain passphrase" on the same screen;
  - "ENROLLMENT" (US spelling) in a British-English app ("Synchronised", "unopenable").
 - **Fingerprint wrapping:** a single "I" wraps onto its own line. Chunk it, or size it to fit
  ([13](android/13-host-key.png)).
 - **Address format:** "10.0.2.2 · 2222" on the host-key sheet, "10.0.2.2:2222" everywhere else.
 - **Dates:** "10/2/2026 11:29 PM" in Logs ([23](android/23-logs.png)), "2026-10-02 21:04" in SFTP.
 - **Notification permission:** Android's prompt appears without explanation at the first connect.
  Explain the keep-alive notification first.
 - **Terminal width:** the default size gives about 37 columns, so `ls -la` wraps every line.
 - **Empty and loading states:**
  - Hosts' empty state is one grey line at the top left ([06](android/06-hosts-empty.png));
  - Vaults first rendered an empty list with no loading indicator;
  - the keychain shows both "0 items" and an empty-state sentence.
 - **Connecting card:** **CLOSE THIS TAB** and **SHOW LOGS** are indented past the card's left edge
  ([11](android/11-connecting.png)).
 - **Host-key context:** the sheet opened over the Quick Connect form, not over the connection progress
  it belongs to.
 - **Disabled fields:** on the enrolment busy state they turn a flat mid-grey
  ([04](android/04-enrol-busy.png)), and the keyboard stays up.
 - **Fingerprint setting:** "Unlock with a fingerprint" in Preferences is drawn as a bare circle; it reads
  as a radio button, not a switch.
 ## Not verified here
 - **System font size:** whether the app honours it. No `FontScale` handling exists in the phone code,
  and Avalonia scales by density, so text likely ignores the setting. I didn't change device settings
  to confirm.
 - **Landscape and tablet:** an `IsWide` layout exists but wasn't exercised.
 - **TalkBack:** not run end to end. The H4 findings come from the tree TalkBack reads.
 ## Environment notes for a re-run
 - **Keycloak port:** 18080 was taken by another project's container, so Keycloak ran on **18180** via a
  compose override, with `Oidc__Authority=http://127.0.0.1:18180/realms/dodossh` and
  `adb reverse tcp:18180`.
 - **`adb root`** restarts adbd and drops `adb reverse`. Re-add both forwards afterwards, or the app
  shows OFFLINE.
 - **The sshd** was a throwaway `linuxserver/openssh-server` container (`dodossh-audit-sshd`, port 2222,
  user `dodo`).
 - **Build:** `-p:RuntimeIdentifier=android-x64` adds an `android-x64` section to every
  `packages.lock.json`. Restore those files afterwards.
@@ -0,0 +1,147 @@
 # DodoSSH full sweep — 2026-10-02
 ## Fix status (same day)
 Every fix below has a regression test. Where marked ✔✔, the test was also checked to fail with the fix taken out.
 | Item | Fix |
 |---|---|
 | C1 ✔✔ | `LocalDirectory.ChildPath` cleans remote names and requires the resolved parent to be the target folder. It is used by every download path and by EDIT. `LocalEditor` opens a file that would run (PATHEXT plus a known list, and macOS launchers) with the type's own `edit` verb or with Notepad / `open -t`. On Linux, opening a `.desktop` file is refused. |
 | C2 ✔✔ | Pinned key types are offered first. A key under an algorithm with no pin of its own is accepted only if its fingerprint matches one of the endpoint's pins (the same RSA key under `rsa-sha2-256` vs `-512`); otherwise it is a hard mismatch. Tested against the real OpenSSH container. |
 | C3 ✔✔ | Complete, Revise and Park take the `PendingOperation` and act only while the row still holds that operation id. A later edit is rebased onto the version that was just accepted, so it pushes without a conflict. |
 | C4 | Pull leaves out change entries the item has moved past, so a revision is never paired with newer ciphertext. This also stops re-sending an item's payload once per historical edit. |
 | C5 | Deleting a team's last vault archives the team only when the owner does it. `TeamService.ArchiveAsync` now checks ownership itself. |
 | C6 | `DeviceKeyNames`: the default profile keeps `DodoSSH.DeviceKey.v1`, and every other profile gets its own name. Sign-out deletes only its own key. A profile still sealed under the shared key keeps reading it. The same applies to the macOS keychain tag. |
 | H1–H3 | The data plane reassembles messages up to 16 MiB. A frame that throws stays with its own session. Input writes are serialized per pump, so a slow write is never overtaken. |
 | H4 | The host and bucket the user chose are remembered across reloads. A typed password is only sent to the host it was typed for. |
 | H5 | Selecting a vault reads its people even while the screen is busy. A generation counter discards answers for an older selection. |
 | H6 / U9 | Locking or signing out leaves Settings, and the Members panel closes with it. Escape closes the Members panel first. |
 | H7 ✔✔ | The tracked user is reloaded after the out-of-band last-seen update. |
 | H8 | `sync_state.pulled_types` (with a client migration) restarts the pull once when the synced type list changes. |
 | H9 | `ActiveAccountRequirement` on both policies. A suspended account gets 403 `account-not-active`. |
 | H10 | `DevicePinWindow` palette keys fixed, and it now uses `InitializeComponent`. `Load` never assigned the named fields, so the window could never have opened. Covered by a new layout test. |
 | H11 ✔✔ | `IRemoteFileStore.CanWriteFromAnOffset`: false for buckets, so a retried upload starts over. |
 | H12 | `ImportOutcome` carries refused hosts and the reason a batch stopped early, including a busy keychain. Both import screens say so. |
 | U1–U4 | The host card's sync badge moved to the address line, so names show in full. Tag chips wrap and trim. Keychain names trim inside their column, with a tooltip. The Security caption wraps. |
 Second round, on branch `claude/audit-followups`:
 | Item | Fix |
 |---|---|
 | U5 ✔✔ | The closed vault's card takes the keyboard on launch and on each new card (server address, enrolment, passphrase). Enter signs in and enrols. |
 | U6 ✔✔ | The host-key, delete and sign-out questions give the keyboard to their harmless answer (CANCEL / CLOSE, never TRUST or DELETE). Escape says no to each, and closes the hosts drawer. Tab stays inside the host-key card. |
 | U7 ✔✔ | Arrow-key selection on the Hosts board is written back to the vault, from the list that has the keyboard only. An arrow on the board itself enters the cards. Enter on a card connects. |
 | U8 | `DeviceUnlockWording`: Windows Hello, Touch ID, a TPM-checked device PIN or a fingerprint, according to the platform. |
 | U10 | Session tab labels are capped at 200 px and trimmed, with the full label in a tooltip. |
 | U11 | The keychain's VAULT column is an Auto column in a shared size group, so it takes no width when no row names a vault. The Tags page's always-empty column is gone. The snippet buttons appear only with a snippet chosen. |
 | U12 ✔✔ | `TerminalTabViewModel.EndedAt`: the status-bar timer stops when the shell ends. |
 | P1 (part) ✔✔ | A sync pass that moved nothing no longer reloads (and decrypts) the whole keychain. It restrings the ago-texts instead. Failed vaults still reload. The Clear-plus-Add rebuild itself is unchanged. |
 | P3 | `ProbedDeviceKeyStore`: the TPM probe runs once per process, on the thread pool. |
 | P5 | A pulled page is mirrored in one write, and the outbox is read once per page. Changes with a local edit waiting still go one at a time, in order. |
 | P6 ✔✔ | `OpenShellAsync` makes its three round trips on the thread pool, honours cancellation, and closes a shell that arrives after the caller gave up. |
 | Transfers ✔✔ | Lost wake-up fixed with a `pumping` flag cleared under the same lock that finds the queue empty (a stress test failed 2 of 2 runs before the fix). Cancel as a transfer finishes no longer throws. A drop or download refused while busy says so. |
 | EF retry ✔✔ | `FreshAttempts.ExecuteFreshAsync`: a retried write transaction clears the tracker and reloads what it carries in. Before this, a lost commit made a team hand-over answer 204 with nothing changed. Tested with an interceptor that fails one commit. |
 | Rejected delete ✔✔ | A delete of a create that never landed is complete when the server says it has no such item. A create that did land still behaves as before: the delete gives way, and the user is told. |
 | Team archive race | Archive and team-vault creation take a per-team advisory lock. Archive re-counts the team's vaults, and creation re-checks the team is live. No race test. |
 | Relay revocation ✔✔ | `RelayAccessWatch` re-checks a user's open relay sessions when their access changes and ends lost ones with 4403 / `AccessRevoked`. |
 | Shell | `ToggleVaultAsync` catches a failure and redraws. `CrashLog` writes uncaught exceptions to `crash.log` in the profile (the process still exits). A lock pressed during an unlock now wins (✔✔). |
 | Window chrome | `CaptionPresses` decides a double-click on the press, before `BeginMoveDrag`. Only a headless test covers it; it is not verified on a real Windows window. |
 | P1 (rest) ✔✔ | `ReplaceableCollection.ReplaceAll`: the host, visible-host, section and bucket lists are swapped in whole and announced once, and each transfers picker refreshes only from its own list. |
 | P2 (most) | The transfer queue and import lists are virtualised (✔✔: 2,000 of 2,000 rows were built before). The find box hands its text to the vault after a 150 ms pause in typing, and the view model still filters synchronously. |
 | P2 (board) ✔✔ | `VirtualizingWrapPanel` builds only the host cards near the view. Measured headless, after warm-up: first layout with 300 hosts went from about 3 s to about 0.5 s, and with 1,000 from 8.3 s to 0.2 s. Clearing a filter went from 1–8 s to about 0.1–0.2 s. Arrow keys, End, the band and selection still work. |
 | P4 ✔✔ | **Server:** `TombstoneCollector` runs every 6 h. It deletes tombstones past the 90-day retention together with their change entries, and compacts each item's superseded entries down to its newest. It then raises the vault's `SyncHorizon`, and a cursor from before it is refused. A cursor now carries the horizon it was issued under. Without that, the read from the beginning that a refused client starts was refused on its own second page and looped for ever on any vault larger than a page (✔✔: found by a client test, then reproduced in an API test). **Client** ("resync and prune", as chosen): a read from the beginning marks every item it reads, keeping the mark in the sync state because the read can span passes. When it finishes, it removes unmarked items of the synced types. It keeps items with an unsent change, and items pushed during the read. Such an edit is then sent as a create, as before, but now records a `RecreatedAfterCollection` conflict and is named in the sync message. The removed items are named too. New client cache migration `AddSweepMarks`. |
 Not done, and why:
 - **Live-run observations** (production as the default server URL, Keycloak on host port 18080): product decisions, not bugs.
 Pre-existing flakiness: on untouched HEAD, 3 of 8 runs of `ShellFlowTests` each had one test fail: `TheCountsAPhoneShows_FollowEveryForwardsState`, `ASpelunkHost_IsDialledThroughTheTunnel_AndStillAsItself` and `ReconnectingAHostThatWantsAPassword_AsksForOneRatherThanDiallingWithout`. These races are in the tests and predate this work.
 How it was done:
 - The desktop client ran on Windows with an isolated profile against a local stack: Postgres, Keycloak and the API on :5333.
 - The real MainWindow was rendered headless through every screen and settings page, 39 captures at 1081×583 and 1440×900.
 - Four parallel code audits covered: the Shell view models; SSH/terminal/transfer; the server and sync; the desktop views and platform code.
 - The findings marked **✔ verified** were re-read in code by me, or seen in a screenshot. The rest come from the audits; each one was traced, but I did not check them again.
 The live session could not get past OIDC sign-in. The default browser is Edge, which I can't type into, so the terminal, SFTP and host-key flows were reviewed in code only.
 ---
 ## Critical — data loss, security
 | # | Finding | Where |
 |---|---|---|
 | C1 | **Path traversal on download / open-to-edit.** Remote names go straight into `Path.Combine(LocalPath, row.Name)`. SFTP only drops `.` and `..`, so on Windows a name with backslashes (`..\..\AppData\…\Startup\x.bat`) or a rooted name escapes the folder. S3 keys `../..` do the same on every OS. EDIT then opens the file with `UseShellExecute`, so a `.bat`/`.hta` *runs*. The Android head sanitises names; the desktop doesn't. ✔ verified | `TransfersViewModel.cs:2682,2698,2780,2784,3165`; `SshNetSftpSession.cs:105`; `ObjectKeys.cs:50`; `App.axaml.cs:380` |
 | C2 | **Host-key pin bypass by changing the key algorithm.** Pins are looked up per algorithm. A MITM that offers ecdsa or rsa to a host pinned for ed25519 gets the "never seen before" first-use prompt instead of the mismatch hard block. ✔ verified | `SshNetConnectionFactory.cs:261-272` |
 | C3 | **The outbox loses an edit made while a push is in flight.** `CompleteAsync` deletes the row by `Sequence` only, but `QueueAsync` folds a newer edit into that same row with a new `OperationId`. When the older push is acknowledged, the newer edit is deleted silently. ✔ verified | `OutboxStore.cs:239-250` vs `:71-97`; `SyncEngine.cs:554` |
 | C4 | **Pull pairs historical revision numbers with the current ciphertext.** `Describe` sends `Version: change.Revision`, but the payload comes from the item's current row. The AAD binds the version, so the payload fails to decrypt. A concurrent offline edit gets parked as "Undecryptable". ✔ verified | `SyncService.cs:565,592` |
 | C5 | **A team admin can archive the team (meant to be owner-only).** If an admin deletes the last vault, `ArchiveAsync` runs with no role check and revokes every membership, the owner's included. | `VaultGrantEndpoints.cs:182,196`; `TeamService.cs:242-289` |
 | C6 | **The shared TPM key name breaks other profiles.** `WindowsDeviceKeyStore` uses one CNG key name (`DodoSSH.DeviceKey.v1`) for the release and nightly profiles. Sign-out in one (`ForgetAsync`) deletes the key, and the other profile's device unlock stops working. This contradicts `ClientPaths.ForChannel`, which says the two installs are kept apart. ✔ verified | `WindowsDeviceKeyStore.cs:127,233-246` |
 ## High — broken behaviour
 | # | Finding | Where |
 |---|---|---|
 | H1 | **Terminal input >64 KiB (a large paste or copy) is lost.** On a frame that doesn't fit the buffer, the loop `continue`s, and the tail is then dispatched as if it were a frame. ✔ verified | `TerminalDataPlane.cs:465-472` |
 | H2 | **Keystrokes can race.** Input frames are written to `ShellStream` without awaiting and without a lock, and the base `FlushAsync` runs on the pool. A snippet RUN (text, then `\r`) over about 4 KiB can execute truncated. | `TerminalDataPlane.cs:505`; `SshNetConnectionFactory.cs:554-558` |
 | H3 | **One resize on a closing shell tears down the renderer socket for every tab** (`ObjectDisposedException` escapes the receive loop). | `TerminalDataPlane.cs:516-520` |
 | H4 | **The SFTP host picker resets to the first host on every sync pass**, about once a minute. Selection is lost on `Hosts.Clear()`, so CONNECT can dial host[0] with the password typed for host X. The same Clear-then-Add pattern resets the Known Hosts and Snippets selection and closes the snippet delete card. | `TransfersViewModel.cs:3905,3923-3950`; `KnownHostsViewModel.cs:264`; `SnippetsViewModel.cs:689` |
 | H5 | **The Vaults Members panel can show vault A's members under vault B**, and SHARE / REVOKE then act on that mix. | `VaultsViewModel.cs:1646,1698-1765` |
 | H6 | **Locking or signing out from Settings leaves a window with no title bar** (no close, minimize or drag). Unlock then returns to Settings. ✔ verified by screenshot | `MainWindowViewModel.cs:3254,3400`; see `locked-from-settings-no-titlebar.png` |
 | H7 | **Enrollment returns 500 if last-seen is more than an hour old.** `ExecuteUpdate` changes `xmin` under a tracked entity, and the `SaveChanges` that follows throws a concurrency exception. | `CurrentUserContext.cs:92,120`; `EnrollmentService.cs:177` |
 | H8 | **A new synced type never back-fills.** A filtered pull moves the cursor past types the client didn't request, so after an upgrade adds a type (SpelunkKey, ObjectStore), older changes of that type never arrive. | `SyncService.cs:50,69`; `SyncEngine.cs:145` |
 | H9 | **Suspended users keep full access.** `UserStatus` is checked nowhere on the request path. | `CurrentUserContext.cs:126` |
 | H10 | **`DevicePinWindow` references `Surface` and `MutedText`, which don't exist**, so Linux TPM-PIN register/unlock should throw on open. ✔ verified | `DevicePinWindow.axaml:7,35` |
 | H11 | **A failed S3 upload commits a truncated part, and every retry then fails.** | `S3UploadStream.cs:126-146` |
 | H12 | **Import screens report success when the vault skipped or failed the import** (busy, or a mid-batch exception). | `ImportViewModel.cs:374`; `HetznerImportViewModel.cs:561` |
 ## UI issues seen in the running app
 | # | Finding | Where |
 |---|---|---|
 | U1 | **Host card labels are cut to 3-4 characters even at 1440px.** "bastion" shows as "bast…", and k8s-worker-a / -b both show as "k8s…", as do web-prod-01 / -02. The label is the primary identifier, and the "not synced" badge takes most of its width. ✔ `hosts-truncated-labels.png` | `HostsScreen.axaml` card template |
 | U2 | **Tag chips overflow the host card edge.** The WrapPanel sits inside a horizontal StackPanel, so it never wraps. ✔ | `HostsScreen.axaml:737-774` |
 | U3 | **Keychain table: long names overprint the TYPE / USED BY columns.** `TextTrimming` has no effect inside a horizontal StackPanel. The same pattern appears in Logs, SessionSidebar, Snippets, NavRail and Transfers. ✔ `keychain-overlap.png` | `KeychainScreen.axaml:294` et al. |
 | U4 | **Security page: the "End-to-end encrypted" caption runs past the card edge.** ✔ `security-text-clipped.png` | `SettingsSecurityPage.axaml:49-60` |
 | U5 | **Enter does nothing in the server URL box** (verified live). The same applies to the enrollment passphrase boxes. The passphrase box is not focused on launch. | `MainWindow.axaml:385` |
 | U6 | **Overlay cards (host key, delete, sign-out, host editor) have no Enter/Escape and don't take focus**, and Tab walks the page behind them. | `HostKeyCard.axaml` etc. |
 | U7 | **Hosts board: arrow-key selection isn't written back to the view model**, so the drawer's Connect / Delete act on the previously clicked host. There is no Enter-to-connect. | `HostsScreen.axaml:573` |
 | U8 | **Windows-only wording on macOS/Linux:** "USE WINDOWS HELLO", "Waiting for Windows…". | `UnlockCard.axaml:51`; `MainWindowViewModel.GestureWait` |
 | U9 | **Escape over the Members panel leaves Settings and leaves the panel open** for the next visit. | `MainWindow.axaml.cs:242` |
 | U10 | **Session tab labels are unbounded.** One long label pushes "+" off the strip. | `SessionTabRow.axaml:89` |
 | U11 | **A VAULT column is drawn and empty** with a single vault (Keychain, Tags). The snippets list footer shows Edit / Move / Delete with nothing selected. | screenshots |
 | U12 | **The status-bar session timer keeps counting after a shell has ended.** | `MainWindowViewModel.cs:4979` |
 ## Performance
 | # | Finding | Where |
 |---|---|---|
 | P1 | **Every sync pass, about once a minute, decrypts the entire keychain even when nothing changed**, then rebuilds each list with Clear + Add. That is O(n²) notification fan-out: with 300 hosts, roughly 45k collection notifications per pass. | `VaultViewModel.cs:6375,4709`; `MainWindowViewModel.cs:4549` |
 | P2 | **The Hosts board is not virtualised and is rebuilt on every filter keystroke.** The transfer queue (one row per file in a folder download) and the import lists are not virtualised either. | `HostsScreen.axaml:448-576`; `TransfersScreen.axaml:1193` |
 | P3 | **The TPM probe (create and delete an RSA-2048 key) runs synchronously on the UI thread** at startup and after every unlock. | `WindowsDeviceKeyStore.cs:152`; `MainWindowViewModel.cs:2594,2970` |
 | P4 | **Pull re-sends the full current payload once per historical change.** There is no change-log compaction and no tombstone GC, even though ADR 0003 promises 90-day GC. | `SyncService.cs:45-56,565` |
 | P5 | **The client applies each pulled change in 2 or more separate SQLite transactions.** | `SyncEngine.cs:157-169,303` |
 | P6 | **`OpenShellAsync` does blocking network round trips wrapped in `Task.FromResult`** and ignores cancellation. | `SshNetConnectionFactory.cs:401-418` |
 ## Lower / plausible
 - **Transfers:**
  - A wake-up can be lost, leaving a transfer queued forever (`FileTransferQueue.cs:452-505`).
  - Cancel at the moment a transfer finishes can throw `ObjectDisposedException`.
  - Drops and downloads are ignored silently while busy (`TransfersViewModel.cs:2272`).
 - **Sync and server:**
  - The EF retry strategy re-runs a push with stale tracked state (`Persistence.cs:38`).
  - Deleting a create that never landed leaves a permanent "Rejected" conflict.
  - A team can be archived while a vault is being created in it.
  - Relay sessions survive removal from the team, for up to 12 hours.
 - **Shell:**
  - Lock can race an unlock that is still loading.
  - `ToggleVaultAsync` has no try/catch, and there is no global `UnhandledException` handler.
 - **Window chrome:** double-click to maximise may be swallowed by `BeginMoveDrag`.
 ## Observations from the live run
 - **The first-launch default is the production server, and sign-in completes without a credential prompt.** `DefaultServerUrl = "https://ssh.dodotech.cloud"` is pre-filled. With a live browser SSO session, one press of SIGN IN on a brand-new profile completed sign-in with no password typed, and wrote the account's wrapped key and vault list into the new profile. For a self-hosted product, an empty field with a placeholder is the safer default.
 - **The local dev compose hard-codes host port 18080 for Keycloak**, which collides with other projects on this machine.
@@ -247,6 +247,13 @@ ln -s ../../opt/%{dodo_dir}/DodoSSH %{buildroot}%{_bindir}/%{dodo_bin}
 # window is a second, unlabelled icon in the dock beside the one that launched it. It is the assembly
 # name deliberately and not the package's binary name — the window does not know which package
 # started it.
 #
 # %%u — RPM's spelling of a literal %u, the field code for "one URL" — and the MimeType line make this
 # the handler for dodossh:// links, which is how Spelunk's "Open in DodoSSH" reaches the application:
 # the desktop starts the binary with the link as its one argument, and Program.Main reads and checks
 # it, or passes it to the instance already running. update-desktop-database in the post-install
 # scriptlet is what makes xdg-open see the handler. Both channels declare it, so whichever is
 # installed answers, and with both installed the desktop's own default decides.
 mkdir -p %{buildroot}%{_datadir}/applications
 cat > %{buildroot}%{_datadir}/applications/%{dodo_bin}.desktop <<DESKTOP
 [Desktop Entry]
@@ -255,13 +262,14 @@ Version=1.0
 Name=%{dodo_title}
 GenericName=SSH Client
 Comment=SSH and SFTP with an end-to-end encrypted credential vault
-Exec=%{dodo_bin}
+Exec=%{dodo_bin} %%u
 Icon=%{dodo_bin}
 Terminal=false
 StartupNotify=true
 StartupWMClass=DodoSSH
 Categories=Network;RemoteAccess;System;
 Keywords=SSH;SFTP;Terminal;Remote;Shell;
 MimeType=x-scheme-handler/dodossh;
 DESKTOP
 # One file per size into the hicolor theme, named for the package so the two channels show different
@@ -119,6 +119,25 @@
  <key>LSUIElement</key>
  <false/>
  <!--
    The dodossh:// scheme, which is how Spelunk's "Open in DodoSSH" reaches the application. macOS
    does not pass the link as an argument: Launch Services sends an "open URL" event to the running
    application, or to the one it has just started, and DodoSshApp.ListenForOpenedLinks takes it from
    Avalonia's activation event. Registered when the bundle is first seen by Launch Services, which
    for a Velopack install is on first launch from /Applications.
  -->
  <key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleURLName</key>
      <string>dev.dodotech.dodossh.link</string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>dodossh</string>
      </array>
    </dict>
  </array>
  <key>NSHumanReadableCopyright</key>
  <string>© DodoTech. MIT licensed.</string>
 </dict>
@@ -1,7 +1,12 @@
 # Development dependencies only: PostgreSQL and Keycloak.
 #
 # The API itself runs from the IDE or `dotnet run`, so the inner loop stays fast while the
-# schema is still churning. The production stack is deploy/docker-compose.yml.
+# schema is still churning.
 #
 # There is no production compose file in this repository. This one said there was, naming a
 # deploy/docker-compose.yml that has never existed in any commit. What ships instead is the
 # container image the CI image job builds and pushes; a compose file to run it belongs to the
 # self-hosting guide in M4, and until that exists the honest thing to say is that it does not.
 #
 #   docker compose -f deploy/docker-compose.dev.yml up -d
 #   dotnet run --project src/DodoSSH.Api
@@ -26,7 +26,8 @@
        "post.logout.redirect.uris": "http://127.0.0.1/*"
      },
      "redirectUris": [
-        "http://127.0.0.1/callback"
+        "http://127.0.0.1/callback",
        "dev.dodotech.dodossh:/callback"
      ],
      "webOrigins": [],
      "protocolMappers": [
@@ -68,7 +68,15 @@ the Npgsql connection string** — the default; do not enable multiplexing.
  visible conflicted copy for opaque ones. **It must never silently drop a key or a host.**
 - Deletes are revisioned tombstones, garbage-collected after 90 days. Sync must therefore be
  able to read tombstones, which is the one place that legitimately bypasses the soft-delete
-  query filter — guarded by an explicit permission check.
+  query filter — guarded by an explicit permission check. **The collection has since been built**
  (`TombstoneCollector`), and it costs a machine away for longer than the retention its news of
  those deletions. So a collection raises the vault's sync horizon, and a cursor from before it is
  refused. The client then reads from the beginning, and when that read finishes it removes the
  items it held that the read never mentioned. An item with an unsent local edit is kept: the
  push finds the server without it, puts it back, and records a `RecreatedAfterCollection`
  conflict. A cursor carries the horizon it was issued under. Without that, the read from the
  beginning would be refused on its own early pages, which sit behind the horizon whenever an
  older item survives.
 - **An `Infrastructure.Tests` case must prove cursor ordering under N concurrent pushes.**
  Without it this ADR's central bug is invisible until production.
 - Two concurrency mechanisms, deliberately: `version integer` is the client-visible monotonic
@@ -99,3 +99,22 @@ real ones.
 - **Client-supplied target address.** One line of convenience, and the relay becomes an open
  proxy into the operator's network.
 - **Allow-listing by hostname.** Defeated by DNS rebinding.
 ## Implementation notes
 Built in `DodoSSH.Api/Features/Relay` and, on the client, `RelayBridge` and `ServerRelay`; see
 `docs/reaching-a-host-you-cannot-dial.md`, "What step 3 built". Three places differ from the text above:
 - **Backpressure is an awaited copy loop, not `System.IO.Pipelines`.** Each direction reads one buffer and
  writes it before reading again. The property is the same — a slow peer stops the read, and TCP throttles
  the origin — and the bound is tighter: two 32 KiB buffers per session.
 - **There is no `?ticket=` fallback.** Both clients can set a subprotocol, and the fallback's cost — a bearer
  credential in the URL — was the reason it needed scrubbing at all. It can be added if a constrained
  client ever needs it; the scrubbing requirement stands.
 - **The ticket carries no device id.** The server does not see a device on an ordinary request, so there was
  nothing to put there. `PortForwardId` on the request is refused: a forward's port is ciphertext, and
  honouring one would mean taking the port from the client.
 The loopback bridge serves the relay only. SSH.NET's `ForwardedPortDynamic` already is the jump-host path's
 listener, so "one mechanism, two features" is true one level down: both features reach their target through
 a loopback SOCKS5 proxy named on the connection request.
@@ -0,0 +1,246 @@
 # ADR 0015 — The Android terminal's input path leaves the WebView
 - Status: proposed — **Stage 1 built, unverified on a device**
 - Date: 2026-08-25
 - Builds on: [`docs/android-port.md`](../android-port.md) §9, [ADR 0011](0011-android-distribution.md)
 - Does not settle: whether the renderer stays xterm.js. That is [Stage 3](#stage-3--the-renderer-deliberately-unsettled), and it is deliberately left open.
 ## Context
 The phone got the desktop's terminal, and the reasons were good ones. `TerminalDataPlane` already
 served the page and a binary protocol over a loopback WebSocket, the xterm.js bundles were embedded
 resources and platform-neutral, and `Avalonia.Controls.WebView` shipped a `net10.0-android36.0`
 target. `docs/android-port.md` called it *"better news than expected"*, and for rendering it was.
 **For typing it was not, and typing is the complaint.** Not scrollback, not colour, not throughput —
 the act of putting characters into a shell. That narrows the problem usefully, because the input path
 and the render path are separable, and only one of them is wrong.
 ### Three things sit between a finger and a byte, and the middle one is the fault
 **1. Avalonia and the WebView fight over native focus.** `AvaloniaView.DispatchTouchEvent` ends every
 handled touch — DOWN and UP alike — with a `RequestFocus()` for Avalonia's own view. The WebView's
 input connection dies with its focus, so the keyboard swaps layouts and the inset churn can park it
 over the accessory row that was tapped. `Platform/TerminalFocus.cs` exists to hand focus back, posted
 to the next main-looper message so the platform has taken its turn first. It works. It is also a
 counter-move in a fight that only exists because the thing holding the input connection is not the
 thing the framework thinks is focused.
 **2. The keyboard is a prose keyboard, and no DOM attribute makes it stop.** This is the one that was
 worth checking rather than assuming, and the check inverted the obvious conclusion.
 The vendored xterm.js *already* sets every hint the web platform has on its helper textarea —
 `autocapitalize="off"`, `autocorrect="off"`, `spellcheck="false"`. They are set, and Gboard shows the
 suggestion strip and predictive text anyway. So this is not a missing attribute; it is a ceiling.
 Termux's `TerminalView.onCreateInputConnection` says what the ceiling is. It sets:
 ```
 InputType.TYPE_TEXT_VARIATION_VISIBLE_PASSWORD | InputType.TYPE_TEXT_FLAG_NO_SUGGESTIONS
 ```
 **`VISIBLE_PASSWORD` is the load-bearing half.** `NO_SUGGESTIONS` alone is advisory and most keyboards
 ignore it — a point made in Avalonia's own Android keyboard PR discussion, not only in Termux's. What
 actually turns off autocorrect, the suggestion strip and the predictive composing layer is the
 *variation*: a field the keyboard believes is a visible password gets no dictionary. That is an
 `EditorInfo.inputType` on a native `InputConnection`, and a page inside a WebView has no way to reach
 it — Chromium computes the `EditorInfo` from the focused DOM node, and no combination of attributes on
 a `<textarea>` produces the visible-password variation.
 **3. The accessory row is a workaround for a keyboard, not a keyboard.** Esc, Tab, Ctrl and the arrows
 are right and stay. But every tap on one costs the focus round-trip in (1), and none of them can be
 held or repeated.
 ### The finding that decides this ADR
 Avalonia already emits Termux's exact `inputType`. Decompiled from the pinned
 `Avalonia.Android` 12.1.1, `AndroidInputMethod<TView>.OnCreateInputConnection`:
 ```csharp
 if ((int)outAttrs.InputType == 1 && options.ShowSuggestions == false)
 {
    outAttrs.InputType = (InputTypes)(outAttrs.InputType | 0x80080);
 }
 ```
 `0x80080` is `TYPE_TEXT_VARIATION_VISIBLE_PASSWORD | TYPE_TEXT_FLAG_NO_SUGGESTIONS`. The guard reads:
 `ContentType` left at `Normal`, `Multiline` false, `AutoCapitalization` false, and
 `TextInputOptions.ShowSuggestions` explicitly `false` — a `bool?` whose default is `null`, so it must
 be set, not merely left alone. The same method also ORs `IME_FLAG_NO_EXTRACT_UI |
 IME_FLAG_NO_FULLSCREEN` into `imeOptions`, which is the other thing Termux sets and for the same
 reason: a terminal must never be replaced by a full-screen extract editor in landscape.
 So the keyboard behaviour that makes Termux feel like a terminal is **already available on the
 version this repository pins**, to any Avalonia control that asks for it. It is not available to the
 WebView, and never will be. That asymmetry is the whole decision.
 ## Decision
 ### Avalonia owns the keystrokes. The WebView renders and nothing else.
 A focusable Avalonia control — `TerminalInputSurface` — becomes the terminal's input target. It draws
 nothing. It sits in the same `Panel` as the renderer, takes focus when the terminal surface is shown,
 and keeps it for as long as that surface is up.
 - `TextInputOptions.ShowSuggestions = false`, with `ContentType`, `Multiline` and `AutoCapitalization`
  left at the defaults the guard above requires. This is the entire fix for the suggestion strip.
 - `TextInputOptions.ReturnKeyType = Return`, which is the fix for Enter — see the correction below.
 - It implements `TextInputMethodClient` with an empty surrounding text and a zero-length selection.
  A terminal has no document for an IME to edit; committed text is forwarded and nothing is retained.
 - Committed text and key events are encoded to bytes and written to the session through the same path
  `TerminalScreen`'s accessory keys already use. No new transport, no change to `TerminalDataPlane`.
 - The native WebView is made non-focusable (`Focusable = false`, `FocusableInTouchMode = false`) once,
  at attach.
 **`Platform/TerminalFocus.cs` is deleted by this, not amended.** The fight it referees ends when only
 one side is a focus candidate. Its remarks should move into the new control as the record of why the
 WebView is deliberately unfocusable, because that reasoning outlives the workaround.
 `Platform/SoftKeyboard.cs` stays. Dismissing a keyboard on the way to a sheet is still a platform
 call, and Avalonia still offers no way to close one.
 ### Not: patching xterm.js's textarea
 Already tried by xterm.js itself, and already failing — see Context (2). The attributes are set. The
 platform ignores them. There is no version of this that reaches `VISIBLE_PASSWORD` from inside a
 WebView, so the effort buys nothing.
 ### Not: a native Android `View`, Termux-shaped, today
 Termux's `TerminalView` + `TerminalRenderer` drawing to a `Canvas` is the right architecture for a
 phone-only terminal, and DodoSSH is not a phone-only terminal. Writing one now means two terminal
 implementations — this one and the desktop's — with two escape-sequence behaviours to keep honest
 against each other, for a defect that is entirely in the input path. That is a large bill for the
 wrong problem.
 It also does not become unavailable later. Stage 3 keeps it on the table.
 ### Not: replacing xterm.js now
 Rendering is not the complaint. xterm.js with the WebGL addon draws a correct, fast grid, and
 `terminal.js` already handles renderer death, reattach and refit — hard-won behaviour recorded in
 `docs/android-port.md` that a rewrite would have to re-earn. Replacing a working renderer to fix a
 keyboard is the wrong trade, and doing it in the same change as the input move would make neither
 half attributable when the result is judged on a device.
 ## Staging
 ### Stage 1 — the input surface · **built**
 The decision above, and nothing else. This is the change that answers the complaint, and it should be
 judged on a device on its own before anything else is built on it.
 What landed:
 | | |
 | --- | --- |
 | `Views/TerminalInputSurface.cs` | The 1×1 focusable control, `ShowSuggestions = false`, the IME client that retains nothing, and the key→escape-sequence table |
 | `Views/TerminalInputEventArgs.cs` | One keystroke's bytes, on the way to `TerminalScreen.SendAsync` |
 | `Platform/RendererFocus.cs` | Makes the `WebView` non-focusable and reports taps on it |
 | `Platform/TerminalFocus.cs` | **Deleted.** The fight it refereed has one contestant now |
 | `Views/TerminalScreen.axaml{,.cs}` | Hosts the surface, raises the keyboard on arrival, drops the two posted focus counter-moves from the accessory row |
 **One thing gained that was not asked for, and it was a real defect:** the Ctrl latch now reaches the
 software keyboard. It never did before — everything typed went straight into the page and never passed
 `SendAsync`, which is where the latch lives — so `ctrl` then `c` was inert unless the second key also came
 from the accessory row. Check 11.10d covers it.
 **Verify before building anything on this:** checks 11.10a–11.10e in `docs/manual-checks.md`, and 11.10b
 first of all, because it is the falsification test at the end of this document.
 > **⚠️ Corrected on the first device run: every Enter closed the keyboard.** The premise held — the
 > suggestion strip, autocorrect and predictive text were all gone — but the field had been left with
 > Avalonia's default `ReturnKeyType`, and the same `OnCreateInputConnection` maps that, on a field that is
 > not `Multiline`, to `IME_ACTION_DONE`:
 >
 > ```csharp
 > _ => options.Multiline ? 1073741824 : 6,   // 6 is IME_ACTION_DONE
 > ```
 >
 > Done means done: the keyboard performs the action and dismisses itself. On a text box that is right, and
 > on a terminal it fires on every command. `TextInputReturnKeyType.Return` — value 1, so
 > `returnKeyType - 1 => 0 => 1073741824` — is `IME_ACTION_NONE`, which leaves Enter a plain newline with no
 > action for the IME to perform and no reason for it to hide.
 >
 > **The trap worth recording, because it is the same trap 11.10b already warned about from the other side:**
 > `Multiline = true` also reaches `IME_ACTION_NONE`, through the default arm, and is the wrong way there. It
 > ORs `TYPE_TEXT_FLAG_MULTI_LINE` into `InputType`, which moves it off `1` and silently fails the
 > `ShowSuggestions` guard. Taking the obvious route to a working Enter would have handed the suggestion
 > strip back and looked like the whole ADR had failed. `ReturnKeyType` touches `imeOptions` only.
 >
 > Enter's *byte* was never in doubt and is not what changed — `IME_ACTION_DONE` was already synthesising
 > `KEYCODE_ENTER` through `AvaloniaInputConnection.PerformEditorAction`, so commands ran; the keyboard just
 > left afterwards. `OnTextInput` now also normalises line endings to CR, for the case where a keyboard with
 > no editor action commits `"\n"` as ordinary text instead of sending a key event, and so that a pasted
 > `"\r\n"` does not run its line twice.
 ### Stage 2 — the keys around it
 Only once Stage 1 is proven, because each of these is cheap *given* Avalonia owning input and awkward
 without it:
 - **Hold-to-repeat** on the arrows and Backspace. Currently impossible without a focus round-trip per
  tap.
 - **Ctrl held rather than latched**, with latching kept as the fallback. `TerminalScreen`'s remark is
  right that latching is what phone SSH clients do; held becomes possible when one control sees both
  the modifier press and the following keystroke.
 - **Pinch and volume keys for font size**, replacing the pinned `A−`/`A+` buttons. Both are what
  JuiceSSH does and what its users name first; the buttons stay as the discoverable path.
 Volume-key capture is an `onKeyDown` on the activity and is deliberately opt-in — a phone that cannot
 change its volume with a shell open is a worse phone.
 ### Stage 3 — the renderer, deliberately unsettled
 If, after Stages 1 and 2, the terminal still reads as a web page — touch selection, scrollback
 survival across renderer death, scroll feel — then the renderer is the next question, and the
 candidates are known:
 | Option | What it is | Cost |
 | --- | --- | --- |
 | [XTerm.NET](https://github.com/tomlm/XTerm.NET) | MIT, headless, UI-agnostic; VT100/ANSI, dual buffers, 256/true colour, wide chars | Evaluate emulation fidelity against xterm.js |
 | [VtNetCore](https://github.com/darrenstarr/VtNetCore) | MIT, .NET Standard 2.0, older but proven | Maintenance status |
 | Port xterm.js's core | Exact behavioural parity with the desktop | Largest, and a permanent fork |
 Rendered by a custom Avalonia `Control` via `DrawGlyphRun`, which is Termux's architecture expressed
 in Avalonia and would work on the desktop too — eventually letting the WebView2 dependency go, and
 with it the `targetSdk` 36 floor `Avalonia.Controls.WebView` currently forces.
 **Stage 1 is not wasted if Stage 3 happens.** The input surface is exactly the layer such a control
 would need, unchanged. That is the reason for splitting them.
 ## Consequences
 **What gets better, and it is one thing done properly.** No suggestion strip, no autocorrect, no
 predictive composing layer, no full-screen extract editor, and no focus flap on an accessory key.
 That is the difference between typing at a shell and fighting a phone.
 **CJK and other composing input is degraded, and this is a real cost.** `VISIBLE_PASSWORD` suppresses
 composition, which is precisely what makes it work for a terminal and precisely what a Chinese,
 Japanese or Korean user needs. Termux has the same limitation and lives with it. If it ever needs
 answering, the answer is a per-session toggle that drops `ShowSuggestions = false` and accepts the
 prose keyboard back — not a middle setting, because there isn't one.
 **Text selection and copy are unchanged**, still xterm.js's own DOM handling, still without touch
 selection handles — [xterm.js #5377](https://github.com/xtermjs/xterm.js/issues/5377) is open and
 unassigned and this ADR does not fix it. Stage 3 territory.
 **Scrollback still dies with the renderer process.** Unchanged, still honest about it via the replay
 banner, still Stage 3 territory.
 **Nothing here is verifiable headless**, for the reason `docs/manual-checks.md` §11 already gives.
 Stage 1 needs new manual checks — at minimum: the suggestion strip is absent with a shell open; an
 accessory key does not disturb the keyboard (§11.10a, which should now pass trivially rather than by
 posted counter-move); landscape does not produce a full-screen extract editor; and a hardware
 keyboard still reaches the shell.
 **The hardware-keyboard path moves.** It currently arrives through the WebView; after this it arrives
 through Avalonia. Behaviour should be identical and probably will not be on the first try.
 ## What would falsify this
 If, on a device, `ShowSuggestions = false` does not suppress the suggestion strip — because the guard
 was not satisfied, or the keyboard ignores the variation too — then Stage 1's premise is wrong and
 the honest next step is Stage 3 with a native `InputConnection`, not more Avalonia. **Check this
 first, on the smallest possible spike, before building `TerminalInputSurface` properly.** It is one
 attached property on a focusable control and a look at the keyboard.
@@ -269,6 +269,12 @@ accessory key row for this. That is UI work, not porting.
 > reconnected; earlier output stayed on the host"* — is that honesty put where the person looking at the
 > terminal will actually read it, not buried in a log.
 > **⚠️ Under review, on the input half only.** The renderer's story above stands; what has not held up in
 > use is *typing*. A software keyboard over a WebView cannot be told to stop autocorrecting — the DOM
 > attributes xterm.js already sets are advisory and Android ignores them — and the accessory row pays a
 > focus round-trip per tap. [ADR 0015](adr/0015-android-terminal-input.md) proposes moving the input path to
 > Avalonia and leaving the renderer exactly as this section describes it.
 ---
 ## Decisions taken
@@ -625,7 +631,8 @@ go at 360dp:
   for. `ShellScreen` gained `More` and `Buckets`. The palette went blue and the two heads moved together,
   because it is shared. What v2 asked for and did not get is in
   [`docs/design-import-gaps.md`](design-import-gaps.md) — the short version being that port forwarding is
-   named as absent rather than drawn, because nothing in the SSH layer forwards anything.
+   named rather than drawn as a screen: it has since been built, and this head runs a host's forwards with
   every terminal and lists them in a sheet off the terminal's bar. It cannot edit them yet.
   **The bar has since gone from four entries to three.** The keychain joined the hub, which is now called
   SETTINGS rather than MORE and wears a gear: a bottom bar is for the places a session moves between, and
@@ -749,6 +756,12 @@ Recorded so they are choices rather than accidents. Any of them is cheap to revi
  local-and-non-roaming requirement more cleanly than any desktop platform does.
 - **The device name** on log entries comes from the head, not `Environment.MachineName`, which returns
  something like `localhost` on Android and would make every entry from a phone indistinguishable.
 - **The Hetzner Cloud importer is not ported, and it is the one gap here that is not a platform limit.**
  Its view model is in `DodoSSH.Client.Shell` like every other and its reader is an `HttpClient` call, so
  both halves already run on a phone — unlike the `~/.ssh/config` importer beside it, which has no file to
  read under scoped storage and never will. What is missing is a layout: the desktop draws a five-column
  table of servers, and a phone version of that is a different screen rather than the same one narrower.
  Said on the Preferences screen rather than left to be discovered.
 - **`NativeKeyboardFocus` is not ported.** It exists for a documented Win32 asymmetry — focus crosses into
  WebView2 but does not come back — and Android's focus model is different enough that the problem should be
  confirmed to exist before anything is written to solve it.
@@ -299,7 +299,8 @@ value can forge a field boundary. UUIDs must be serialised in RFC 4122 order —
 `1` User, `2` Device, `3` Vault, `4` Host, `5` Credential, `6` SshKey, `7` HostGroup,
 `8` Tag, `9` Snippet, `10` PortForward, `11` KnownHostKey, `12` HostTag,
-`13` HostCredential, `14` ConnectionLogEntry, `15` ActivityLogEntry, `16` ObjectStore.
+`13` HostCredential, `14` ConnectionLogEntry, `15` ActivityLogEntry, `16` ObjectStore,
 `17` SpelunkKey.
 > **Added 2026-07-29:** `12` and `13`. `Contracts.SyncEntityType` has listed `HostTag` and
 > `HostCredential` as syncable since the contract was frozen, but this table had no value for
@@ -318,6 +319,9 @@ value can forge a field boundary. UUIDs must be serialised in RFC 4122 order —
 > `ConnectionLogEntry` is `11` there and `14` here. Nothing casts between them, and
 > `AadResourceTypeTests` pins each pairing by name for exactly that reason.
 > **Added 2026-09-29:** `17` SpelunkKey, a Spelunk API key and the address it may be sent to. It is
 > `14` on the wire, three behind, as `16` ObjectStore is `13`.
 `0` means not applicable and is legal only where the table in §4.2 implies no resource.
 ### 4.4 What this prevents
@@ -39,8 +39,8 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
 >
 > | v2 element | What ships instead |
 > | --- | --- |
-> | The **FORWARDING** screen: local/remote/dynamic rules, toggles, bytes transferred | **Nothing, said out loud.** `ISshConnection` offers `OpenShellAsync` and nothing else, so there is no tunnel for a rule to run through; `SyncEntityType.PortForward = 9` is still reserved and still unused. The MORE screen carries a paragraph naming the absence, for the reason the desktop keeps VAULTS in its rail. |
+> | The **FORWARDING** screen: local/remote/dynamic rules, toggles, bytes transferred | **Built, as a sheet off the terminal rather than a screen, and running on the phone as on the desktop.** A host's forwards start with every terminal opened to it on either head — `MainWindowViewModel.StartForwards` no longer skips Android. The terminal's bar draws a `⇄` for a tab that has forwards, with the listening count in green and the glyph in the danger colour when one failed, and it raises a sheet (`IsForwardsSheetOpen`) listing `SelectedTab.Forwards` with notation, route, state word, failure reason and a tap-to-toggle per row — the desktop sidebar's FORWARDS section over the same rows. Not a screen, for the desktop's reason: a forward belongs to a host and runs with a session. **Two gaps remain.** The phone's host form has no PORT FORWARDS section, so forwards are edited on the desktop and arrive with the host; the MORE screen's paragraph, now tagged IN THE TERMINAL, says so. And byte counts are built on neither head: SSH.NET keeps none. The keep-alive notification counts listening forwards beside the shells they run over, and is never started for a forward alone, since a forward cannot outlive its shell. |
-> | `23 ms · fwd 5432` on the terminal's connection line | ◆ **The line is gone, and what was real on it moved.** There was never an RTT to draw — SSH.NET measures none — and nothing forwards anything, so what shipped was the account and endpoint actually dialled. In v3 a connected phone draws one 35-pixel bar and then the terminal, so a second 36-pixel row naming the machine is exactly the chrome that surface exists to give back: the address is on the connecting card, where it is read before anything has answered, and the shell's own prompt says it afterwards. The two text-size buttons that shared the line are pinned at the end of the accessory row, outside its scroller, which is what the line was protecting them from. |
+> | `23 ms · fwd 5432` on the terminal's connection line | ◆ **The line is gone, and what was real on it moved.** There was never an RTT to draw — SSH.NET measures none — and nothing forwarded anything at the time (forwards now have the `⇄` in the bar above; see the row before this one), so what shipped was the account and endpoint actually dialled. In v3 a connected phone draws one 35-pixel bar and then the terminal, so a second 36-pixel row naming the machine is exactly the chrome that surface exists to give back: the address is on the connecting card, where it is read before anything has answered, and the shell's own prompt says it afterwards. The two text-size buttons that shared the line are pinned at the end of the accessory row, outside its scroller, which is what the line was protecting them from. |
 > | `ED25519` badge and `SHA256:kQ9f…Zw2M` on every keychain card | `Detail`, which is what is genuinely known *about* an item. Unchanged from the first import: no algorithm field, no fingerprint, and computing either means parsing armour the type stores verbatim. |
 > | An `agent` chip on a key | Omitted. There is no agent of any kind — see the first import's Vault section. |
 > | Snippet cards footed with `edge-eu-1 · today 10:58 · exit 0` | The command and its badge. Nothing records where a snippet ran, when, or what it returned; the shell it is typed into never reports back. |
@@ -78,7 +78,7 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
 >
 > | v2 element | What ships instead |
 > | --- | --- |
-> | The **FORWARDING** screen, the `⇄ N forwards` chip on the session strip, and the host detail's FORWARDING card | Nothing, as on the phone and for the same reason. Three surfaces for a feature the SSH layer does not have. |
+> | The **FORWARDING** screen, the `⇄ N forwards` chip on the session strip, and the host detail's FORWARDING card | **Built, as three smaller things.** Forwards are rules on the host, edited in its drawer under PORT FORWARDS and shown read-only on its detail pane; they run per terminal, listed with a switch each under FORWARDS in the session sidebar; and the session status bar counts the listening ones as `⇄ N FORWARDS`. No screen of their own, because a forward is not a thing you visit — it belongs to a host and runs with a session, and both of those already have a place. |
 > | The host detail's 2×2 card grid — IDENTITY fingerprint, TAGS, LAST SESSION | Not drawn as a grid. There is no fingerprint on a stored key and no last-used timestamp at any layer, so two of the three cards have nothing behind them. Tags are real and are drawn — as chips on the row and a picker in the editor, which is where they are used rather than in a card beside two empty ones. |
 > | The keychain detail's public-key block, USED BY hosts, and **Rotate** | The detail pane as it stands. Copy public key is real and already there; rotation is not a thing this client can do. |
 > | Logs: **FOLLOW**, the severity chips, and `tailing via ssh · journald + files` | The two logs it really has. Same as the phone — these are synced audit records, not a tail, and the footer sentence describes a feature rather than the screen. |
@@ -171,7 +171,7 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
 > | The **Backspace / Default** row | Omitted, and it is the one row on this list that could now be built cheaply — a setting, an opcode and a control, the way the text size was. What it lacks is a reason: which byte backspace sends is a fact about the remote's `stty`, so a client-side switch fixes a mismatch by hiding it. See the Preferences section. |
 > | 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 its card's right-click menu, 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. |
+> | **Port Forwarding** in the sidebar | No rail entry; see the FORWARDING row above for where forwards are instead. |
 > | The host grid's toolbar avatar, share and tag-filter controls | Omitted, as in v3 and for the same reasons. |
 >
 > ## The desktop's v5 — hosts, restyled, and two reversals
@@ -254,7 +254,7 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
 > | v5 element | What ships instead |
 > | --- | --- |
 > | The status dot's third, amber state | ◆ **Still two states, on the same reasoning v3 and v4 both gave and v5 was asked to reconsider.** Green means a terminal is open on that host, grey means one is not; nothing here pings a machine, so the amber "reachable but not connected" state has no fact behind it to draw. |
-> | The relay checkbox's mock copy | The pre-existing sentence, unchanged, "(not wired up yet)" included — restyled into the mock's own nested-card shape (radius 12, a title beside the box rather than under it) but not reworded. The mock's own copy implies a relay this client can dial; it cannot, for the reason `HostDrawer.axaml`'s own remarks give. |
+> | The relay checkbox's mock copy | Restyled into the mock's own nested-card shape (radius 12, a title beside the box rather than under it). The "(not wired up yet)" it carried while this client could not dial the relay came out when it could; the sentence under it now says what ticking it does — the server dials the host, so the server has to be able to reach it, and the address is stored in plain text. |
 > | The host card as a link straight to a terminal | Click still selects, double-click still connects, and the pencil still opens the pane — the mock's card-as-link is not adopted, because multi-select (Ctrl, Shift, the marquee band) depends on a plain click meaning "choose this one" rather than "go". |
 > | Quick connect's SSH/SFTP kind column | The auth word — credential, key, or password — see above. |
 > | A collapsed section staying collapsed after a restart | In memory only, for the running session. `settings.json` holds two scalars by decision — the terminal's text size and whether this machine checks for updates on its own — and collapse state is not judged worth a third. |
@@ -295,7 +295,7 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
 > | v5b element | What ships instead |
 > | --- | --- |
 > | The host header's OS label (`Ubuntu 24.04 LTS`) and latency reading (`12 ms`) | Neither. The client does not know the remote's OS and nothing measures round-trip time — the same two absences the terminal pane header already recorded before this pass, carried into the new header rather than reopened. |
-> | A **Port forward** button on the host header | Omitted. The feature does not exist; see the FORWARDING rows earlier in this document. |
+> | A **Port forward** button on the host header | **Add forward**, at the foot of the session sidebar's FORWARDS list, which opens the host's editor the way Pin folder does. The header it would have sat on has since moved into that sidebar. |
 > | The tab and status dots' third, amber state | ◆ **Still two states**, for the reason the hosts screen's own dot has stayed two states since v3: green means a shell is open (or a session is connected), grey means it is not, and nothing here pings a host to justify a third colour meaning "reachable but not connected". |
 > | The status bar's negotiated cipher, host-key algorithm and key/credential name | ◆ **Shipped, on both surfaces, with three honest deviations.** `ISshConnection` and `ISftpSession` now both carry `Cipher` — the server-to-client algorithm off SSH.NET's own `ConnectionInfo.CurrentServerEncryption`, captured once at construction because a rekey is not an event SSH.NET raises — and `TerminalWorkspace.GetSessionFacts` hands the cipher and the host key's algorithm back to the shell the moment a session opens; `VaultViewModel.TryBuildAuthentication` now threads the authenticating key's or credential's own `Label` into `HostAuthentication.IdentityLabel`, all the way to `MainWindowViewModel`'s surface-aware `SessionCipher`, `SessionHostKeyAlgorithm` and `SessionIdentityLabel`, composed into one `SessionIdentityText` run for the status bar. Three deviations from the mock, not omissions: the algorithm prints exactly as negotiated (`ssh-ed25519`), not the design's shortened `ed25519`, because trimming it would be an edit to a string this client did not choose; the run is plain text rather than the design's clickable element, because there is no pin-details modal for a session that is already open, and drawing a click target for a screen that does not exist would itself be a fabrication; and a typed-password session — nothing filed in the keychain to name — shows the host-key algorithm alone, with no `·` after it, because there is no item behind the dot. |
 > | S3 dimmed in the design's own switcher | **Enabled.** The mock leaves S3 as future work; this application already has bucket browsing, so SSH, SFTP and S3 are a true three-way segment, wired to `IsSshShowing`, `IsTransfersShowing` and `IsBucketsShowing` exactly alike. |
@@ -392,9 +392,10 @@ sharing that would rest on them — or a decision recorded here not to build the
 Three facts explain nearly every row below.
-**An SSH connection here opens exactly one channel.** `ISshConnection` offers `OpenShellAsync` and nothing
+**An SSH connection here opens a shell, and forwards beside it.** `ISshConnection` offers `OpenShellAsync`
-else (`src/DodoSSH.Client.Ssh/SshConnection.cs`). No port forwarding, no ProxyJump. That one fact removes
+and `StartForwardAsync` (`src/DodoSSH.Client.Ssh/SshConnection.cs`). There is still no ProxyJump, which is
-the `FORWARDS` chip, the status bar's port list, and every `via bastion-eu` in the design.
+what removes every `via bastion-eu` in the design. Port forwarding arrived later than most of what this
 document accounts for, and the rows about it now say where it went.
 It used to remove the file-transfer screen too. M2 did not lift the restriction — it worked around it:
 file transfer is a *separate connection* rather than a second channel, because SSH.NET's `SftpClient` owns
@@ -461,8 +462,10 @@ configuration, a server kind that refuses every plaintext field, a codec, a merg
 same way, for the same cost, and is the clearest case the reservation ever paid for: a whole item kind, a
 table, a migration and an AAD arm, with `PublicAPI.Unshipped.txt` untouched.
-`HostTag`, `HostCredential` and `PortForward` are still reserved and still unused — and `HostTag` is now
+`HostTag`, `HostCredential` and `PortForward` are still reserved and still unused — and `HostTag` and
-reserved *against a decision* rather than pending one. Which hosts wear a tag is a set of ids inside each
+`PortForward` are now reserved *against a decision* rather than pending one. Port forwards shipped inside the
 host's payload, for the reason `RelayTicketRequest.PortForwardId` already assumed and the one below gives for
 tags. Which hosts wear a tag is a set of ids inside each
 host's payload, not a join: the one thing a join buys over that is two machines tagging the same host
 without either losing, and the client's per-key three-way merge already gives it. A second item type would
 be a second table and a second pass through every rule in this file, for nothing.
@@ -509,7 +512,7 @@ field cannot be removed and stays as a permanently refused member; `SyncEndpoint
 | `VAULT SYNCED 11:02` | client-session | `StoredSyncState.LastPulledAt`/`LastPushedAt` are persisted, but `VaultSession` exposes the store as `internal`. A property away. | Omitted. The one honest sync fact — the outbox depth — is in the titlebar and the status bar. |
 | `⌘K` command palette running commands | client-domain | A snippet or saved-command item type (`SyncEntityType.Snippet = 8` is reserved). | Ctrl+K opens a real host search that connects on Enter. The box says "search hosts", not "search hosts · run command". |
 | Status bar `· via bastion-eu` | client-ssh | Jump-host execution. See below. | Omitted. |
-| Status bar port forwards | client-ssh | Port forwarding. See below. | Omitted. |
+| Status bar port forwards | client-ssh | — | **Shipped** on the session status bar as a count of listening forwards; the ports themselves are in the session sidebar. |
 | Status bar `sftp · 2 transfers` | client-app | Nothing now — file transfer is built. What is missing is the count reaching the status bar, which is a screen away from where the queue lives. | Omitted from the status bar. The queue itself is on the FILES screen, with a row per transfer. |
 | Status bar `locks in 09:41` | client-app | An idle auto-lock. See preferences below. | Omitted. |
 | IBM Plex Mono / IBM Plex Sans | ui | Shipping the font files as `AvaloniaResource` and registering them. The design loads them from Google Fonts, which a desktop app cannot. | **Shipped, since v5, and not IBM Plex.** The v5 design asked for Montserrat, JetBrains Mono and Material Icons instead, and all three are embedded as `AvaloniaResource` in the Shell project rather than requested by name and left to whatever the machine happens to have. Montserrat is the default sans, with Inter — the earlier substitution — kept only as its fallback; `MonoFont` puts JetBrains Mono first, ahead of the system-monospace stack the terminal still falls back to. Named once each in `Program.cs` and `Palette.axaml`, so a later design's fonts are still a one-line swap. |
@@ -533,7 +536,7 @@ caption buttons and window title drawn on top of the application's own — two s
 | 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. |
-| `⇄ FORWARDS · 2` | client-ssh | Port forwarding. `SyncEntityType.PortForward = 9` is reserved; nothing in the SSH layer forwards anything. | Omitted. |
+| `⇄ FORWARDS · 2` | client-ssh | — | **Shipped**, as `⇄ 2 FORWARDS` on the session status bar, counting only forwards actually listening. |
 | `SNIPPETS` panel, `↵` to run | client-domain | A snippet item type (`Snippet = 8`, reserved). | **Shipped**, as a screen rather than a panel. `↵` is per snippet and off by default: inserting types the command at the prompt and stops, because nothing here can tell whether the terminal is at a prompt at all. |
 | Broadcast to all panes (`⌥↵`) | client-ssh | Input is routed strictly by session id in `TerminalDataPlane.Dispatch`; there is no fan-out. Needs splits first. | Omitted. |
 | Pane header `24ms` | client-ssh | Round-trip measurement. SSH.NET offers no RTT API. | Omitted. |
@@ -741,3 +744,27 @@ to a 34-pixel rail carrying the chevron that brings it back — a rail rather th
 that vanishes without trace is one people report as lost. The choice is written through to
 `ClientSettings.SessionSidebarOpen` rather than held for the session: it is a decision about how much of the
 window a terminal gets, and one that had to be made again on every launch would not really be on offer.
 ## v5c-5 — one door to settings, not three
 **The user-chip popover keeps its Settings row and has lost Vaults and Preferences.** v5c gave it three, and
 the table above records why: until that pass "Settings" and "Preferences" had been two doors onto the same
 bare screen, so splitting them was a real fix, and Vaults arrived beside them when `VaultsScreen` became a
 settings page too.
 Living with it made the shape of the mistake clear. All three opened the same full-window mode and differed
 only in which of its seven pages they landed on — and `SettingsNav`, which lists every one of those pages
 including Vaults and Preferences, is on screen the entire time you are in there. So two of the three rows
 were deep links into a place the third one opens, saving one click and costing a menu that read as though it
 offered three destinations. A menu at the foot of the rail is for getting into settings at all; which page
 you want is a question that has a rail of its own once you are there.
 Nothing became unreachable: both pages are one click deeper, from the rail that was always going to be the
 way to them. `NavRailTests` asserts the rows are gone from the markup rather than merely unwired, because a
 row left behind with no handler is a menu entry that does nothing when pressed — which reads as a broken
 application rather than a tidied menu.
 Logout stays, and still lands on a page rather than on General: its confirmation card is drawn inline on the
 Account page and nowhere else, so arming it from anywhere else would be a card raised where nobody could see
 it. The vault switches and **New vault** above the divider stay too — they are what the popover is for
 besides settings, and neither is a page of the settings mode.
@@ -118,15 +118,17 @@ view models — this check is the version with a real connection on the end of i
 ### 1.8 Entering and leaving settings mode
-From HOSTS, press the user chip at the foot of the nav rail and choose **Settings**. Then repeat from a
+From HOSTS, press the user chip at the foot of the nav rail and choose **Settings** — which is the menu's
-fresh open, choosing **Vaults**, and again choosing **Preferences**.
+only way in now; the Vaults and Preferences rows beside it were folded back into it, because all three
 opened this same mode and differed only in which page they landed on.
-**Pass:** each of the three swaps the whole window's chrome — the titlebar becomes the 53px "Back to
+**Pass:** it swaps the whole window's chrome — the titlebar becomes the 53px "Back to application" bar, the
-application" bar, the ordinary nav rail is replaced by the 340px SettingsNav, and the status bar and the
+ordinary nav rail is replaced by the 340px SettingsNav, and the status bar and the update banner (if either
-update banner (if either was showing) are both gone. **Settings** lands on General; **Vaults** and
+was showing) are both gone. It lands on **General**, with SettingsNav's own list beside it —
-**Preferences** land on their own pages, each lit in SettingsNav's own list — General/Vaults/Account under
+General/Vaults/Account under SETTINGS, Security/Preferences/Groups/Tags under CUSTOMIZE, Logout pinned below
-SETTINGS, Security/Preferences/Groups/Tags under CUSTOMIZE, Logout pinned below both. Click every one of the
+both. Click every one of the seven rows in turn: each swaps the content column without leaving settings mode
-seven rows in turn: each swaps the content column without leaving settings mode or touching the titlebar.
+or touching the titlebar, and Vaults and Preferences are among them — which is the whole reason the popover
 no longer carries its own rows for those two.
 Now open a terminal, leave it showing, and open Settings from the user chip again. Press **Back to
 application** — or, without touching anything else, press Esc.
@@ -134,7 +136,8 @@ application** — or, without touching anything else, press Esc.
 **Pass:** both return to exactly the screen that was showing before Settings was opened — the terminal,
 still running, rather than HOSTS or anywhere else. Switching between settings pages first (General → Vaults
 → Preferences) does not change what "back" goes back to; only the screen open the moment Settings was
-**first** entered does.
+**first** entered does. The other doors into this mode — the palette, and the Preferences page's own two
 importer rows — behave the same way, so the popover having one row rather than three changes nothing here.
 **Failure means:** a return to HOSTS regardless of where Settings was opened from is
 `MainWindowViewModel.settingsReturnScreen` being recaptured on every `EnterSettings` call rather than only on
@@ -165,7 +168,9 @@ ordinary nav rail destination does through `MainWindowViewModel.ShowScreen`. An
 comes up over settings mode the same way it would over any other screen.
 **Failure means:** a back button that never changes label is `SettingsTitleBar.axaml`'s two buttons both
-bound to the same side of `IsImportOpen`. SettingsNav lighting a different row while the importer is up is
+bound to the same side of `IsImporterOpen` — which is the flag now, rather than `IsImportOpen`, because
 there are two importers over that page and the bar behaves identically for both. SettingsNav lighting a
 different row while an importer is up is
 `MainWindowViewModel.IsSettingsPreferencesPage` reading `IsImportOpen` when it must not —
 `Import.dc.html` draws the rail unmoved on purpose; see the remark on `IsImportOpen`. Ctrl+K doing nothing
 over the importer would be a guard added to `OnKeyDown` for `IsSettingsMode` that the design never asked for
@@ -197,6 +202,126 @@ That is what the "is this still the page's socket" guard in `connect()` exists t
 input while the banner is *clear* is neither: the socket is open and dead, which nothing on this page can
 currently see — see the note at the end of 11.12a.
 ### 1.10a A remote that floods the terminal does not grow the process · **watch Task Manager**
 Open a shell and run `yes dodossh`. Leave it running for a full minute with the tab in front of you, then
 switch to another screen and leave it another minute, then come back. Watch the application's memory in
 Task Manager (Details tab, *Memory (active private working set)*) the whole time.
 **Pass:** memory settles at a plateau and stays there — the number moves as the GC breathes, but there is no
 staircase. Ctrl+C, and the prompt comes back straight away. Somewhere in the scrollback there may be a dim
 grey line reading `── N MB of output was dropped; the terminal could not keep up ──`; that line is a pass,
 not a failure. It is this client saying it discarded output it could not draw, which is what keeps the
 plateau flat, and the number after it tells you how far behind the display got.
 **Failure means:** a working set that climbs steadily for the whole minute and does not come back down after
 Ctrl+C is the defect this check exists for, and it will not be in this repository's own buffers — it is
 SSH.NET's. `ShellStream` copies everything the channel delivers into a buffer that doubles and is never
 given back, and the channel keeps delivering because `Channel.OnData` re-opens the SSH receive window as
 bytes *arrive* rather than as they are consumed. Measured against the container in
 `DodoSSH.Client.Ssh.Tests`, a reader that stops entirely leaves that buffer holding 44 MB after five
 seconds. The only thing that keeps it empty is `TerminalSessionPump` reading continuously and bounding what
 it holds in `OutputBacklog` instead — so a staircase here means something has put a wait back into that read
 loop. `ARunawayRemote_KeepsBeingReadAndStaysInsideTheBacklog` is the test that fails first.
 ### 1.10b A tab whose shell exited stops costing anything · **needs a debugger or `netstat`**
 Open a shell, type `exit`, and **leave the tab open**. Note the host and port. Then, from a terminal outside
 the application, run `netstat -ano | findstr <port>` and look for the connection to that host.
 **Pass:** the connection is gone within a second or two of the shell exiting, even though the tab is still on
 screen showing the session ended and still offering RECONNECT. Clicking that reconnect still works, and
 closing the tab afterwards still works.
 **Failure means:** a connection that is still ESTABLISHED for as long as the tab is open is the session
 holding an authenticated socket it has no further use for — with a keep-alive putting a packet on the wire
 every thirty seconds and SSH.NET's read buffer still at whatever size the session's busiest moment grew it
 to. It used to do exactly that, until whichever tab it was got closed. `TerminalWorkspace.ReleaseAsync` is
 what gives it back now, and `ASessionWhoseRemoteHasExited_GivesBackItsConnectionWithoutWaitingForTheTab` is
 the test that says so.
 ### 1.11 The right button copies and pastes, and never opens a menu
 Open a shell and run something that prints a few lines — `ls -la /etc`. Drag a selection across part of the
 output with the left button, then **right-click inside the selection**.
 **Pass:** the highlight disappears at once, **no menu appears anywhere**, and the text is on the clipboard —
 paste it into Notepad, or into the connect box, to be sure. The pane still takes typing straight afterwards.
 Now **right-click again with nothing selected.**
 **Pass:** the clipboard's text appears at the prompt as one insertion and **Enter is not pressed** — it sits
 there waiting. On bash it will be highlighted in reverse video until the next keystroke, which is right: that
 is bash marking a bracketed paste, and it is how you can see the markers arrived.
 **And the multi-line case, which is the one worth the most care.** Copy three separate lines out of a text
 editor — `cd /tmp`, `pwd`, `ls` — and right-click in the terminal.
 **Pass:** all three lines land at the prompt as one thing being edited and **nothing runs** until Enter is
 pressed. Three commands executing the moment you right-click is the failure this is looking for.
 **On a Mac, one more:** right-click over a word with nothing selected and confirm it pastes rather than
 selecting the word under the pointer. xterm.js defaults `rightClickSelectsWord` to true on macOS alone;
 `terminal.js` turns it off, and this is the one platform where forgetting to would show.
 **What the tests already own.** `RendererClipboardTests` runs `terminal.js` itself and proves which frame a
 right-click sends, which session it is addressed to, that the selection is dropped after a copy and that the
 answer comes back through `paste()` rather than `input()`. `ShellFlowTests` proves the round trip through the
 host's own clipboard. What is left here is the WebView: that a real `contextmenu` event reaches a listener
 registered in the capture phase, that no native menu is drawn once it is prevented, and that xterm's real
 `paste()` brackets the text — none of which a Jint engine can answer.
 **Failure means:**
 - **A context menu appears.** The event is not being prevented, or not being seen. `handleRightClick` takes
  it in the capture phase on the pane; a listener registered without the third argument to
  `addEventListener` would still prevent the menu, so a menu means the listener is not attached at all.
 - **A permission prompt appears** — *"…wants to see text and images copied to the clipboard"*. Somebody has
  routed the read through `navigator.clipboard.readText()`, which is exactly what the `ClipboardPaste`
  opcode exists to avoid. The clipboard is the host's.
 - **A drag started exactly where you last right-clicked selects nothing.** xterm's own `contextmenu`
  handler ran: it parks its invisible helper textarea under the pointer, 20 pixels square at z-index 1000,
  to serve the native menu. The page stops the event as well as preventing it, and `stopPropagation` is the
  half that was left out. Subtle enough to be worth looking for on purpose rather than waiting to notice.
 - **Three commands run on a multi-line paste.** The text went through `input()` rather than `paste()`, so
  bracketed paste never happened and the shell read each newline as "run this". That is the whole reason the
  `Clipboard` opcode is separate from `Paste`; see `TerminalFrame.cs`.
 - **Nothing happens at all, in either direction.** The head is not passing a clipboard. Both pass one — see
  `ClipboardWriter` and `ClipboardReader` in each `App.axaml.cs` — and the view model is deliberately silent
  when neither is there, because there is no status line on this screen to say it on.
 ### 1.12 Something is on screen while it starts
 Close DodoSSH and start it again. Watch the first second.
 **Pass:** a small panel — about 420 pixels wide, no titlebar — appears saying **DodoSSH** and *Starting…*,
 and is then replaced by the main window. Measured on a debug build against a cold
 profile: the panel at 668 ms, the window at 3.1 s. A release install is quicker and the shape is the same.
 What must never come back is the old behaviour, which was nothing at all on screen for the whole of it.
 **Pass, and worth checking separately:** the panel is **gone** once the window is up, there is never a moment
 with two windows both claiming to be DodoSSH, and clicking another application while the panel is up puts
 that application in front of it. The last one is deliberate — a splash that stays on top is a splash sitting
 over whatever you gave up and went back to.
 **And the failure state, which is the part with something to get wrong.** It needs provoking: put a
 *directory* where `cache.db` should be — `%LOCALAPPDATA%\DodoSSH.Nightly\cache.db` for the nightly — and
 start the application.
 **Pass:** the panel stays and the line becomes *DodoSSH could not start:* followed by the reason and
 *Press Escape to close.* Escape closes it. Remove the directory afterwards.
 There is deliberately nothing else on the card to contradict that line — the progress bar this check used to
 describe was taken off in "Take the frozen bar off the splash, and leave the line that is true", because an
 indeterminate bar over a composition that had stopped was the one thing a splash must never do.
 **Failure means:** a panel left saying *Starting…* is the main window having failed to show with nothing
 catching it, which is the one outcome worse than the crash it replaced — `DodoSshApp.ComposeBehind` exists to
 make it impossible. Two windows at once is the show-then-close order in that method having been swapped:
 closing the only open window ends the process, so the real window is shown while the panel is still up.
 Nothing appearing at all means composition is running in the same dispatcher turn that has to paint the
 panel, which is what posting it at `DispatcherPriority.Background` prevents.
 ---
 ## Phase 2 — Known Hosts as its own page
@@ -360,6 +485,74 @@ machine. That is the ordinary case rather than an error.
 ---
 ## Phase 2 — Importing from Hetzner Cloud
 The reader has its own suite over the shapes the API returns, and the end-to-end path is covered by
 `ImportingFromHetzner_ShowsTheProjectFirstAndThenStoresWhatWasTicked` against a stubbed transport. What no
 test in this repository does is talk to Hetzner — there is no account, no token and no network in the
 ordinary suite — so everything below needs a real project.
 ### 2.11a A read-only token lists your project
 Make a token in the Hetzner console under **Security → API tokens** with **Read** permission only. Settings
 → Preferences → **OPEN WIZARD**, paste it, press **READ THE PROJECT**.
 **Pass:** every server in that project is listed, with the address, the plan and the location the Hetzner
 console shows for it. The token box is **empty** afterwards — it is used for one request and dropped — and
 the Hosts screen is unchanged, because reading writes nothing.
 **What to look for specifically:**
 - A project with more than fifty servers must list all of them. Fifty is Hetzner's page size, and a list
  that stops there exactly is the paginator not being followed.
 - A server with no public IPv4 should show the first address of its `/64` with a warning chip saying so.
  Check that address against what the server actually answers on — the convention is Hetzner's own images,
  not a fact the API states, and a machine whose operator moved it elsewhere in the `/64` will not answer.
 - A server the console shows as **off** should still be listed, with `off` in the STATE column.
 **Failure means:** the importer and the console disagree about what the project holds, which produces
 bookmarks that dial the wrong machine. Worse than an import that refused.
 ### 2.11b A wrong token says so, and says where tokens come from
 Paste anything that is not a valid token — a truncated one is the realistic case, since the console shows
 the value once.
 **Pass:** the wizard stays on the token step, the message names the Hetzner console and the Security → API
 tokens page, and the box is cleared for a fresh paste. Nothing has been stored.
 Now try a token from a **different** project.
 **Pass:** it lists that project instead. A token belongs to one project and there is no API call that will
 say which — an account with several projects runs this once per project, which the note above the box says.
 ### 2.11c The private-network choice does not fall back
 With a project holding at least one server on a private network and one on none, press **PRIVATE NETWORK**.
 **Pass:** the server with no private network shows an em dash for its address, a chip reading *no address of
 that kind*, and a tickbox that cannot be ticked — including by the tick-all box in the header. The other
 one shows its `10.x` address.
 **Failure means:** a public address quietly stored under a choice that asked to stay off the internet. This
 is the one asymmetry in how addresses resolve and it is deliberate; v4 and v6 fall back to each other,
 private does not.
 ### 2.11d Imported hosts are correct, and ask for a password
 Import a couple, then open one on the Hosts screen.
 **Pass:** the address, port and login user are what the wizard showed, and the notes carry the server id,
 the plan, the location and the image — and **not** the power state, which would be stale the moment somebody
 pressed a button in the console. Connecting asks for a **password**: no key came with these hosts, because
 Hetzner has never held the private half of one. Bind it to a key in your keychain and it connects.
 Now go back to the list and import the same project again.
 **Pass:** the ones already stored are marked *already here* and arrive unticked. Importing one twice is
 allowed and takes a click.
 ---
 ## Phase 2 — Drag and drop on the SFTP page
 **This is the least-covered thing in the repository, and unavoidably so.** Headless Avalonia has no native
@@ -1687,6 +1880,27 @@ bottom and no scroll position left part way down.
 **Failure means:** the inset is being applied but not cleared — the closed state is not being read from the
 event, or the margin is only ever added to.
 ### 10.4a Nothing is stranded when the keyboard is still up on the way *out* · **the one 10.4 missed**
 Focus any box, and with the keyboard still on screen leave the application — Home, or the task switcher,
 or anything that puts another app in front. Come back to it.
 **Pass:** the interface fills the screen. Do it from the terminal too, where the keypad and the shell should
 both be where they were.
 **Failure means:** `PhoneShell` is not re-reading the inset on the way back in. This is a separate path from
 10.4 and it is the one that has actually shipped broken: Android takes the keyboard away when the activity
 stops and Avalonia's input pane raises no `StateChanged` for it, because the pane goes with the window
 rather than closing in front of one. So the last value applied was for a keyboard that was up, and the
 application returns holding a whole keyboard's height of empty canvas — measured at 838 of 2340 pixels on a
 Pixel 5, on every screen, and staying that way until something opens and closes the keyboard. See
 `PhoneShell.OnActivityResumed` and `PhoneEnvironment.Resumed`.
 Worth doing in both directions: a resume that *should* keep the inset is the other half. Trigger a
 permission prompt or the biometric sheet with the keyboard up, dismiss it, and check the box being typed
 into is still clear of a keyboard that is genuinely still there — a fix that flattened the inset on every
 resume would pass the paragraph above and fail this one.
 ### 10.5 Rotating with the keyboard up
 Focus a passphrase box, then turn the phone sideways.
@@ -1840,12 +2054,22 @@ Now tap **Tab** on the accessory row, or **A+**, and type again.
 keyboard.
 **Failure means:** the buttons on that row have become focusable again. An ordinary Avalonia button takes
-focus on tap, which takes it off the `NativeWebView` — and the package's own `OnLostFocus` then resigns the
+focus on tap, which takes it off `TerminalInputSurface`. The row goes on working, because its keys are
-page's focus. The row goes on working, because its keys are pressed rather than typed into, so the symptom
+pressed rather than typed into, so the symptom is a terminal that answers the buttons and ignores the
-is a terminal that answers the buttons and ignores the keyboard: it reads as the session having died. See
+keyboard: it reads as the session having died. See `Focusable = false` in `TerminalScreen.axaml.cs`.
 `Focusable = false` in `TerminalScreen.axaml.cs` and the focus entry in `docs/platform-flags.md`.
-Worth doing on the software keyboard too, where the same fault shows as the keyboard closing on the first
+**Also worth typing while a hardware keyboard is attached**, because that path moved under
 [ADR 0015](adr/0015-android-terminal-input.md) and is the one most likely to have been broken by the move:
 it used to arrive through the `WebView`'s own key handling and now arrives through Avalonia's. Confirm that
 Ctrl-C interrupts **and leaves no stray `c` at the prompt** — Avalonia raises the letter's own text event
 whether or not the key event was handled, so a doubled character here means `controlByteAlreadySent` is not
 doing its job — that the arrow keys reach shell history, that Backspace deletes one character, and that Tab
 completes a path. **Forward-delete is a known, deliberate loss** — the Delete key sends a backspace,
 because Avalonia turns an IME's `deleteSurroundingText` into a `KEYCODE_FORWARD_DEL` and a broken backspace
 on every phone is worse than a missing forward-delete on the few devices with the key. See
 `TerminalInputSurface.TryTranslate`.
 Worth doing on the software keyboard too, where the old fault showed as the keyboard closing on the first
 tap of an arrow key.
 ### 11.10a The accessory keys do not cost the terminal its *software* keyboard either
@@ -1853,18 +2077,98 @@ tap of an arrow key.
 With a shell open and the software keyboard up, tap **esc**, **tab** or an arrow on the accessory row, then
 keep typing on the software keyboard.
-**Pass:** the keyboard settles back unchanged — same layout, same suggestion strip, same height — and
+**Pass:** the keyboard settles back unchanged — same layout, same height — and everything typed after the
-everything typed after the tap still reaches the terminal. The accessory row stays visible above the
+tap still reaches the terminal. The accessory row stays visible above the keyboard throughout. There should
-keyboard throughout. A blink during the press itself is tolerable: the platform takes the focus on both
+be **no blink at all** now: under [ADR 0015](adr/0015-android-terminal-input.md) the input target is an
-halves of every touch and the return is posted right behind each theft, so the connection can visibly flap
+Avalonia control, so the focus the platform hands to Avalonia's own view after every dispatched touch is
-for the press's own duration — what it must never do is *stay* swapped after the finger lifts.
+already the focus the keyboard wants, and there is nothing to hand back.
-**Failure means:** Android's own view focus stayed on Avalonia's input view after the tap instead of being
+**Failure means:** the buttons on that row have become focusable again, taking Avalonia's focus off
-handed back. This is the half `Focusable = false` cannot reach — the platform requests focus for its own
+`TerminalInputSurface`. The old failure — a keyboard that swapped layouts and parked itself over the row —
-view after dispatching every handled touch — and the symptom chain is the keyboard swapping to its no-input
+belonged to the arrangement where the `WebView` held the input connection and is not reachable from here;
-layout and the inset churn parking it over the very row that was tapped. The first fix for this failed by
+if it reappears, the renderer has taken focus back and `RendererFocus.Suppress` did not run. See check
-timing alone: it handed focus back from inside the very dispatch the platform re-steals it after. See
+11.10c.
-`TerminalFocus` in the Android head's Platform folder for both the mechanism and the fix's shape.
+
 ### 11.10b The keyboard over a terminal is a terminal's keyboard · **the important one for ADR 0015**
 Open a shell and look at the keyboard, without typing anything yet. Then type a few words of ordinary
 English — `ls`, `cd etc`, `sudo apt update`.
 **Pass:** there is **no suggestion strip** above the keys, nothing is autocapitalised at the start of a line,
 no word is autocorrected, and no predictive text appears ahead of the cursor. Backspace deletes exactly one
 character per press. Rotating to landscape does not replace the terminal with a full-screen text editor.
 **Failure means:** the premise of ADR 0015 is wrong and everything staged on it needs rethinking, so find
 out *which* half failed before concluding anything. Either `TextInputOptions.ShowSuggestions` is not
 reaching Avalonia's `AndroidInputMethod` — the guard there is narrow and needs `InputType` to be exactly
 `TYPE_CLASS_TEXT`, so anything that sets `ContentType`, `Multiline` or `AutoCapitalization` on
 `TerminalInputSurface` or an ancestor silently disables it, `inherits: true` being the trap — or the
 keyboard is ignoring `TYPE_TEXT_VARIATION_VISIBLE_PASSWORD`, which would mean no Avalonia-side fix exists
 and the honest next step is a native input connection. Worth repeating on a second keyboard (Gboard and one
 other) before deciding, because this is a claim about keyboards rather than about Android.
 ### 11.10c The renderer cannot take the keyboard, and a tap still brings it back
 With a shell open, put the keyboard away with the system back gesture. Then tap the terminal. Separately:
 with the keyboard up, drag the terminal to scroll its scrollback.
 **Pass:** the tap brings the keyboard straight back. The drag scrolls the scrollback and does **not** raise
 the keyboard. At no point does a text caret or a selection handle appear inside the terminal.
 **Failure means:** if the tap does nothing, `RendererFocus.Suppress` never found the `WebView` — it is
 called from two places, the posted `EnvironmentRequested` handler and the `IsTerminalShowing` transition,
 and a miss in both leaves no tap listener. If the drag raises the keyboard, the touch-slop test is not
 working. If a caret appears, the `WebView` is still focusable and the page has taken the input connection
 back, which is the whole failure ADR 0015 exists to prevent.
 ### 11.10d The Ctrl latch reaches the software keyboard
 With a shell open and something running that can be interrupted — `sleep 60`, or `top` — tap **ctrl** on the
 accessory row and then press **c** on the software keyboard.
 **Pass:** the process is interrupted, and the ctrl key returns to its unlatched colour.
 **Failure means:** typed characters are not going through `TerminalScreen.SendAsync`. Note that this check
 could not pass *before* ADR 0015 and is not a regression test but a new capability: the latch used to apply
 only to the accessory row's own keys, because everything typed went straight into the page and never passed
 the code that holds the latch.
 ### 11.10e Enter runs the command and the keyboard stays where it is
 With a shell open and the software keyboard up, type `pwd` and press Enter. Then type another command.
 **Pass:** the command runs and **the keyboard is still up**, unmoved, ready for the next one. The Enter key
 reads as a return arrow rather than as `DONE` or a tick. Ten commands in a row cost ten Enters and no taps
 to bring the keyboard back.
 **Failure means:** `TextInputOptions.ReturnKeyType` is not `Return` on `TerminalInputSurface`, so Avalonia
 has mapped the field's default to `IME_ACTION_DONE` and the keyboard is doing exactly what Done means. This
 was the first defect the first device run found. **Do not fix it with `Multiline = true`** — that reaches
 the same `IME_ACTION_NONE` by a route that ORs `TYPE_TEXT_FLAG_MULTI_LINE` into `InputType`, which fails the
 `ShowSuggestions` guard and hands the suggestion strip back; check 11.10b would then start failing and the
 cause would look unrelated. See the correction in [ADR 0015](adr/0015-android-terminal-input.md).
 Worth pressing Enter on an empty prompt a few times too: each one should give a fresh prompt and nothing
 else. A doubled prompt per press means a line ending is arriving as both CR and LF.
 ### 11.10f Every key on the keypad is there, and pressing one presses it
 With a shell open, look at the two rows above the keyboard without touching anything: **esc tab ctrl | - ~ /**
 on the upper row and **← ↓ ↑ →** with **A−** and **A+** on the lower one. All thirteen, at once, on a 360dp
 phone in portrait.
 Then press them with a thumb rather than a fingertip, at an angle, twenty or so times across both rows —
 including the keys at the far left and far right ends.
 **Pass:** every press registers, the key darkens under the thumb while it is down, and **nothing slides
 sideways**. The row is exactly where it was after twenty presses as it was before the first.
 **Failure means:** a key that misses is a target that has got smaller — `Button.hotkey` is 40 tall for a
 reason and Android asks for 48. A row that *moves* is the one that matters: it means something has put a
 `ScrollViewer` back around the keys. That is how this row shipped originally and it does not survive contact
 with a thumb — a pan and a press begin with the same few pixels of travel, the scroller claims them, and the
 press is never delivered. If the set of keys outgrows the width, add a third row; do not make it scroll.
 See the keypad's own remark in `TerminalScreen.axaml`.
 ### 11.11 Closing a connection and opening a new one both take you somewhere real
@@ -1922,6 +2226,26 @@ without either end noticing, which a suspended renderer can leave behind — sho
 connected and swallows what is typed. If that is ever seen, it is a different bug from this one and needs a
 liveness probe rather than a faster retry.
 ### 11.13 The right button on a phone with a pointer · **needs a mouse, a trackpad or a dock**
 The same page as 1.11 runs on this head, so the gesture is here too — but only for a device that has a
 secondary click at all. Attach a mouse or use a keyboard case's trackpad, or dock the phone, open a shell,
 select some output and right-click it; then right-click again with nothing selected.
 **Pass:** exactly as 1.11 — the selection drops with no menu, and the second click pastes.
 **Unverified, and that is why this check exists.** Nothing here has been run against Android's WebView with
 a pointer attached, so whether it delivers a secondary click as a DOM `contextmenu` event at all is an open
 question. `ClipboardReader` is wired on this head regardless, because the alternative is a head where the
 paste half silently does nothing and nobody finds out.
 **Failure means:** if the copy works and the paste does not, the clipboard read is being refused — Android
 returns nothing from the clipboard to an app that is not the foreground one, and a WebView taking the
 secondary click may be leaving Avalonia's window in a state where `TopLevel` has none. If neither works,
 Android is not delivering the click as a `contextmenu` event, and the gesture needs a native listener on the
 `WebView` instead of a page one. Neither costs this head anything it has today: a phone without a pointer
 has no right button to miss.
 ---
 ## Phase 12 — Shared vaults: the operations that span two accounts
@@ -2565,6 +2889,32 @@ having been broken, and the fallback is to move the offer into the titlebar inst
 the swap having been blocked, usually by a process still holding a file under `current\`. Being asked to
 enrol again means the profile directory did not survive, which is 16.1's failure arriving late.
 ### 16.7a Two releases published while it is running cost one update · **needs two releases**
 The nightly channel is the easier place to do this — every push to `main` publishes one — but it works the
 same way on the release channel with two tags. With the client running and the banner already up for one
 build, publish a second. Then press **RESTART NOW** on the banner.
 **Pass:** one download and one restart, landing on the **second** build. The banner says
 *"A newer build appeared. Fetching it before restarting"* with a percentage while it does, and it stays on
 screen throughout rather than vanishing. Starting up afterwards offers nothing, because there is nothing
 left to offer.
 **And the timer's half, if you have six hours or a debugger.** Leave the client running past a check
 interval with a build already fetched and a newer one published. The banner's version changes on its own,
 and LATER having been pressed does not stop it coming back — a different version is a different question.
 **Failure means:** two downloads and two restarts is the regression this check exists for, and it was the
 shipped behaviour: the background pass skipped itself entirely once anything was fetched, so a running
 client was pinned to whichever build it first saw and installed that, then found the next one at the launch
 straight afterwards. On a rolling channel — where the release is deleted and remade on every push, so the
 feed holds exactly one build — that was the normal case rather than a corner.
 A banner that disappears when RESTART NOW is pressed is `IsRestarting` not reaching it; everything the strip
 draws keys off `IsReady`, and the last look moves the state off that. A restart that does not happen at all
 when the forge is unreachable is the last look having become a gate: it is a courtesy, and the build already
 on disk is still newer than the one running.
 ### 16.8 The first connect after an update is not a cold start
 Immediately after 16.7, connect to a host.
@@ -2610,6 +2960,43 @@ offer a nightly, ever, however many have been published since. It reads a differ
 prereleases; if a nightly version is ever offered there, stop and treat it as a release-channel incident
 rather than as a bug in the nightly.
 ### 16.11 One instance, and what a second launch does instead
 With DodoSSH running, start it again — Start menu, desktop shortcut, or the executable directly. Do it three
 times: with the window in front, with it minimised, and with it behind another application.
 **Pass:** no second window appears, and the one already open comes forward, un-minimised if it was
 minimised. **A flashing taskbar button rather than a raised window is also a pass**: Windows refuses the
 foreground to a process that did not receive the input, which is its own rule about focus stealing and not
 something to defeat. Nothing happening at all is the failure.
 **And the side-by-side case, which is the whole reason the lock lives where it does.** 16.10's arrangement,
 both builds installed, both started.
 **Pass:** both run. They are separate applications with separate profiles, and the lock is a file inside the
 profile — so neither can see the other's. Two people signed in to one machine is the same property from the
 other direction and needs no check of its own.
 **And the update relaunch · needs a release.** Take an update (16.7) and press RESTART NOW.
 **Pass:** the application comes back. This is the race worth naming: the updater starts the new build as the
 old one is exiting, and a lock held a moment too long would make the new process refuse itself and disappear
 — an update that looked like an uninstall. `SingleInstance.Claim` keeps trying for three seconds while the
 lock is held by something that does not answer its pipe, which is what covers it.
 **Failure means:** a second window means the lock is not being taken. A profile directory that cannot be
 written to answers "you are the only one" on purpose — refusing to start an SSH client over a permissions
 problem would be the wrong trade — so check that the profile exists, is writable, and has an
 `instance.lock` in it while the application runs. A second launch that exits without raising the first means
 the lock worked and the doorbell did not: the pipe name is derived from the profile path, so two processes
 disagreeing about it means they disagree about which profile they are in. Two windows *after an update* is
 the opposite failure — the outgoing process never released the lock, which means something is holding it
 open past `Shutdown`.
 `SingleInstanceTests` covers everything reachable without a second process: the lock, its release, the
 doorbell answering more than once, and two profiles not excluding each other. What is left for a person is a
 second *executable* and a real window coming forward.
 ---
 ## Phase 17 — Installing and updating the phone
@@ -1,26 +1,30 @@
 # Reaching a host you cannot dial
 Some machines do not answer from where the user is sitting. This product has **two** answers to that, and
-neither of them works.
+one of them works.
- The **relay** pipes raw TCP through the deployment. The server half is built and shipped; the client
+- The **relay** pipes raw TCP through the deployment. Both halves are built: the server issues a ticket and
-  half does not exist, and both heads offer a checkbox that promises it.
+  pipes a WebSocket to the host, and the client reaches it through a loopback SOCKS5 bridge. Step 3 below.
 - A **jump host** reaches the target through a machine already in the keychain. `HostSecret.JumpHostIds`
  stores the chain; nothing writes it and nothing reads it.
 ◆ **An earlier version of this page said the relay's server half was "built and shipped". It was not.** What
 existed was ADR 0004, the contract records, the options and the CHECK constraint — and `RelayOptions` said,
 in its own remarks, that there was no endpoint and no dialler. Both halves were built together at step 3.
 This document is the comparison between them, which is the thing that has to be settled before either is
 built, and then the plan. It replaces an earlier draft of `docs/jump-hosts.md` that recommended deleting the
 jump chain — see the last section for why that was wrong.
-> **Status: step 0 done, the rest planned.**
+> **Status: steps 0, 1 and 3 done, and step 4 for the relay. Jump hosts are next.**
 >
 > | Step | State | Notes |
 > | --- | --- | --- |
-> | 0. Stop promising the relay | **Done** | Both heads say the box is not wired up and that ticking it stores the address and changes nothing. Left tickable, so a host already carrying the flag can lose it |
+> | 0. Stop promising the relay | **Done, then retired at step 3** | The "not wired up yet" sentence came out of both heads when the relay started working |
 > | 1. Dial through a loopback proxy | **Done** | `SshLoopbackProxy` on the request, honoured in `BuildConnectionInfo`. **Not the bridge** — see below |
 > | 2. Jump hosts over it | Not started | No server change, and no bridge either: SSH.NET's own forward is the proxy |
-> | 3. The relay: the bridge, then the ticket | Not started | The bridge's only consumer, so it lands with the feature that uses it |
+> | 3. The relay: the bridge, then the ticket | **Done** | Server: `Features/Relay`. Client: `RelayBridge`, `ServerRelay`, and `VaultViewModel.OpenThroughAsync`. See "What step 3 built" |
-> | 4. File transfer parity | Not started | The transfers screen opens its own connection. Already half-done — `OpenSftpAsync` shares `BuildConnectionInfo`, so it honours a proxy today; what is missing is anything passing it one |
+> | 4. File transfer parity | **Done for the relay** | `TransfersViewModel` opens a relay for a relayed host exactly as the shell does. A jump chain will need the same line when step 2 lands |
 ## ◆ The relay's checkbox is a false promise, and that is a defect
@@ -171,7 +175,64 @@ the sentence step 0 added comes out of both heads.
 **4. File transfer.** `ISftpSessionFactory.OpenSftpAsync` opens its own second connection, so a host that
 needs a chain or a relay to reach needs it there too, or SFTP silently fails for exactly the hosts this
-work exists for.
+work exists for. ✅ for the relay.
 ## What step 3 built
 **The server**, in `DodoSSH.Api/Features/Relay`:
 - `POST /api/v1/relay/tickets` makes every decision. It finds the host, requires Connect on its vault and
  the relay switched on, resolves the stored name, and runs every answer through `RelayAddressPolicy` —
  the non-overridable list first, then the operator's denials, allow-list and private-network switch. What
  passes goes into a Data Protection ticket; the name is not resolved again. **Every target refusal is one
  answer**, 403 `relay-target-rejected` with one sentence, because anybody who can write a host can point
  it anywhere, and a distinct "resolves, but refused" would be a scanner for the operator's DNS. The real
  reason is logged (event 2301).
 - `GET /api/v1/relay/connect` is anonymous at the HTTP layer and takes the ticket as the second
  subprotocol. It verifies, checks expiry against `TimeProvider`, and spends the ticket with a unique
  insert into `relay_ticket_use` before accepting the upgrade — so a refused ticket is a 401 and no socket.
  After the upgrade, a refusal the client could not have avoided is a close code: 4429 for a limit, 4502
  for a host the server could not reach, 4408 idle, 4409 lifetime, 1001 at the end of a shutdown's drain.
 - `relay_session` is the audit row: opened before the dial, closed after, each from a scope of its own.
 **The client:**
 - `RelayBridge` (Client.Ssh) is the loopback SOCKS5 listener. It binds `127.0.0.1`, accepts once, answers
  one CONNECT without acting on its target, and pipes to the WebSocket. It is handed to the connection as
  the new `SshLoopbackProxy.Lifetime`, so the connection disposes it on every way a session ends, and a
  failed connect disposes it before throwing.
 - `ServerRelay` (Client.Session) asks for the ticket, opens the socket and starts the bridge, and turns
  every refusal into a sentence. It is `IVaultServer.Relay`, decided from `/api/v1/meta` the way `Events`
  is; a server without the feature supplies `UnavailableServerRelay`.
 - `VaultViewModel` opens a relay for a host with the box ticked and **never falls back to dialling it
  directly** — the user ticked it because that path does not work, or goes somewhere they do not mean. A
  relay that closed with a reason replaces SSH.NET's transport error with that reason, and the
  reachability probe is skipped for a relayed host, because it would test the direct path.
 ### ◆ Two things that are not what ADR 0004 wrote
 - **No `System.IO.Pipelines`.** Each direction reads one buffer and does not read again until the write
  has completed. That is the same end-to-end backpressure — a slow peer stops the read, which fills the
  kernel's window, which throttles the far sender — with a tighter bound: two 32 KiB buffers a session
  rather than ~2 MiB.
 - **No `?ticket=` fallback, and no device id in the ticket.** The fallback exists for clients that cannot
  set a subprotocol, which neither head is, and it would put a bearer credential in the one place — the
  URL — that access logs keep. A device is never visible to the server on an ordinary request.
 ### ◆ A WebSocket operation is never cancelled, on either side
 Cancelling a pending receive or send on a .NET WebSocket aborts it, and an aborted socket sends no close
 frame. The close frame is the only way the client learns that the server could not reach the host, so both
 the server's pump and the client's bridge stop a direction by closing and waiting a bounded time instead.
 `AnIdleSession_IsClosedWithTheIdleCode` holds the server to it: it asserts the code arrives, not merely that
 the socket ended.
 ### What a developer meets
 The relay refuses loopback with no configuration escape, so the development stack's sshd on
 `localhost:2222` cannot be reached through it. Point a relayed host at an address the API process reaches
 on a real interface — the machine's own LAN address works — or at the container's address on the Docker
 network.
 ## Traps already known
@@ -226,8 +287,8 @@ is right, sharing a lifetime policy is not.
  row, and the status bar's `via bastion-eu` row, all of which say jump hosts are data-only.
 - `Client.Import/ImportedHost.cs` — the note written onto every imported host with a `ProxyJump`, and the
  remark above it.
- `README.md` and `docs/android-port.md` wherever the relay is described as available.
+- `README.md` and `docs/android-port.md` wherever the relay is described as available. ✅ at step 3.
- ADR 0004 gains a note that its last consequence was built, and how.
+- ADR 0004 gains a note that its last consequence was built, and how. ✅ at step 3.
 ## What the first draft of this document got wrong
@@ -223,6 +223,25 @@ echo "==> $(basename "$rpm_file"), $(wc -c < "$rpm_file") bytes"
 #
 # Everything above can succeed and still produce something nobody can install, and none of the ways
 # that happens are visible in an exit code. Each check below is one of them.
 #
 # ◆ EVERY READER IN A PIPELINE HERE MUST CONSUME ALL OF ITS INPUT, AND THAT IS NOT A STYLE RULE.
 #
 # `set -o pipefail` at the top of this file means a pipeline's status is the rightmost non-zero one.
 # A reader that stops early — `grep -q`, `head -n` — closes the pipe while the writer is still
 # writing, the writer dies of SIGPIPE with status 141, and pipefail hands that 141 to the `if`. So a
 # check that found what it was looking for reports the opposite, and a diagnostic printed on the way
 # to `exit 1` kills the script under `set -e` before it gets there.
 #
 # It is a threshold rather than a constant, which is what made it look like somebody else's bug: the
 # writer only blocks once it has more than a pipe buffer left to write, about 64 KB on Linux. `$files`
 # is one line per packaged file, so this passed for as long as the published tree was small and then
 # failed on the commit that pushed the path text past 64 KB — reporting `/opt/DodoSSH/DodoSSH` missing
 # from a package that plainly contained it, and exiting 141 rather than the 1 it meant to.
 #
 # Hence `grep pattern >/dev/null` rather than `grep -q pattern`, which has the same exit status and
 # reads to the end; and `awk 'NR<=40'` rather than `head -40`, which prints the same lines and reads
 # to the end. Nothing here is allowed to stop early, and `|| true` is not the fix — it would hide a
 # real failure of the writer alongside the imaginary one.
 requires="$(rpm -qp --requires "$rpm_file")"
 provides="$(rpm -qp --provides "$rpm_file")"
@@ -236,7 +255,7 @@ files="$(rpm -qp --list "$rpm_file")"
 carried="$(printf '%s\n' "$files" | sed -n 's|^/opt/.*/\(lib[^/]*\.so[^/]*\)$|\1|p' | sort -u)"
 unsatisfiable=""
 for soname in $carried; do
-    if printf '%s\n' "$requires" | grep -qF "$soname("; then
+    if printf '%s\n' "$requires" | grep -F "$soname(" >/dev/null; then
        unsatisfiable="$unsatisfiable $soname"
    fi
 done
@@ -251,7 +270,7 @@ fi
 # 2. The provides exclusion still doing its job. A package advertising libcoreclr.so to the whole
 #    system is the thing that exclusion exists to prevent, and a future rpm that stopped honouring
 #    the macro would break it silently and in the direction nobody looks.
-if printf '%s\n' "$provides" | grep -qE '^lib.*\.so'; then
+if printf '%s\n' "$provides" | grep -E '^lib.*\.so' >/dev/null; then
    echo "This package advertises bundled libraries to the system:" >&2
    printf '%s\n' "$provides" | grep -E '^lib.*\.so' >&2
    echo "__provides_exclude_from in build/linux/dodossh.spec is meant to stop that." >&2
@@ -262,7 +281,7 @@ fi
 #    without libelf would do exactly that — the package would carry no glibc requirement at all and
 #    would install cheerfully onto a host too old to run it. libc.so.6 is the one dependency a
 #    self-contained .NET tree cannot fail to have.
-if ! printf '%s\n' "$requires" | grep -q '^libc\.so\.6'; then
+if ! printf '%s\n' "$requires" | grep '^libc\.so\.6' >/dev/null; then
    echo "This package does not require libc, which a self-contained .NET tree cannot be true of." >&2
    echo "The automatic ELF scan produced nothing; rpm here is probably built without elfdeps." >&2
    printf '%s\n' "$requires" >&2
@@ -279,9 +298,9 @@ for expected in \
    "/usr/share/icons/hicolor/256x256/apps/$bin.png" \
    "/usr/lib/udev/rules.d/71-dodossh-tpm.rules"
 do
-    if ! printf '%s\n' "$files" | grep -qxF "$expected"; then
+    if ! printf '%s\n' "$files" | grep -xF "$expected" >/dev/null; then
        echo "The package was built and $expected is not in it." >&2
-        printf '%s\n' "$files" | head -40 >&2
+        printf '%s\n' "$files" | awk 'NR<=40' >&2
        exit 1
    fi
 done
@@ -169,16 +169,66 @@ Bump ApplicationVersion, commit, move the tag, and run this again.
    if (Test-Path $Staging) { Remove-Item -Recurse -Force $Staging }
    New-Item -ItemType Directory -Path $Staging | Out-Null
-    # No RuntimeIdentifier, so every supported ABI is packaged. An arm64-only APK will not install on a
+    # ◆ THE PASSWORDS GO THROUGH THE ENVIRONMENT, BECAUSE -p: PUTS THEM ON A COMMAND LINE.
-    # 32-bit handset or an x86_64 emulator, and this is the package strangers are pointed at.
+    #
-    & dotnet build $Project --no-restore --configuration Release `
+    # They used to be written straight into -p:AndroidSigningStorePass=..., which reads as private and is
-        -t:SignAndroidPackage `
+    # not. A process's command line is not a secret on Windows: any process running as this user can read
-        -p:DodoChannel=release `
+    # every argument of every other with one call —
-        -p:AndroidKeyStore=true `
+    #
-        -p:AndroidSigningKeyStore=$KeystorePath `
+    #     Get-CimInstance Win32_Process | Select-Object Name, CommandLine
-        -p:AndroidSigningKeyAlias=$KeyAlias `
+    #
-        -p:AndroidSigningStorePass=$storePlain `
+    # — and process-creation auditing, EDR agents and crash dumps all record it as a matter of course. The
-        -p:AndroidSigningKeyPass=$keyPlain
+    # comment above says the passwords are never stored, and with the arguments written that way it was
    # true of the disk and false of everything watching the machine.
    #
    # env: is .NET for Android's own answer to exactly this, and it names the variable rather than carrying
    # the value: MSBuild is handed the string "env:DODOSSH_ANDROID_STOREPASS" and reads the password out of
    # the environment itself. The one restriction is $(AndroidPackageFormat) = aab, where env: is not
    # supported and file: is the documented alternative; this channel ships an APK, and the guard below
    # fails loudly rather than silently signing with the literal string if that ever changes.
    #
    # Not a perfect channel — an environment block is readable by a process with rights over this one, the
    # same as memory is — but it is off the command line, out of the audit trail and out of any log that
    # echoes the build invocation, which is the whole of the difference being bought here.
    #
    # -nodeReuse:false so no MSBuild worker outlives this call holding the variables in its environment.
    # The finally clears them from this process either way, and a persistent node would have kept its own
    # inherited copy for the next quarter of an hour regardless of what happens here.
    $packageFormat = (& dotnet msbuild $Project -getProperty:AndroidPackageFormat -nologo `
        -p:DodoChannel=release | ForEach-Object { $_.Trim() } | Where-Object { $_ })
    if ($packageFormat -eq 'aab') {
        Stop-With @'
 This channel now builds an aab, and the env: prefix this script signs with is not supported for that
 format. The signing would silently take "env:DODOSSH_ANDROID_STOREPASS" for the password itself.
 Switch both passwords to the file: prefix, which is supported for aab, and make sure whatever writes
 that file removes it again.
 '@
    }
    try {
        $env:DODOSSH_ANDROID_STOREPASS = $storePlain
        $env:DODOSSH_ANDROID_KEYPASS = $keyPlain
        # No RuntimeIdentifier, so every supported ABI is packaged. An arm64-only APK will not install on a
        # 32-bit handset or an x86_64 emulator, and this is the package strangers are pointed at.
        & dotnet build $Project --no-restore --configuration Release `
            -nodeReuse:false `
            -t:SignAndroidPackage `
            -p:DodoChannel=release `
            -p:AndroidKeyStore=true `
            -p:AndroidSigningKeyStore=$KeystorePath `
            -p:AndroidSigningKeyAlias=$KeyAlias `
            -p:AndroidSigningStorePass=env:DODOSSH_ANDROID_STOREPASS `
            -p:AndroidSigningKeyPass=env:DODOSSH_ANDROID_KEYPASS
    }
    finally {
        # SetEnvironmentVariable rather than Remove-Item, which throws when the variable is not there —
        # and this runs on the failure path, where it may well not be.
        [Environment]::SetEnvironmentVariable('DODOSSH_ANDROID_STOREPASS', $null)
        [Environment]::SetEnvironmentVariable('DODOSSH_ANDROID_KEYPASS', $null)
    }
    if ($LASTEXITCODE -ne 0) { Stop-With 'The build failed.' }
@@ -38,9 +38,11 @@
 #   xcrun notarytool store-credentials DodoSSH \
 #     --apple-id you@example.com --team-id TEAMID --password <app-specific-password>
 #
-# The forge token is the one real secret, and it is prompted for rather than read from a file or the
+# The forge token is the one real secret, and it is prompted for rather than read from a file or an
-# environment, and only in the phase that needs it — for the reason the Windows script gives: the fewer
+# ambient environment variable, and only in the phase that needs it — for the reason the Windows script
-# minutes a credential that can publish an update spends in a shell's memory the better.
+# gives: the fewer minutes a credential that can publish an update spends in a shell's memory the better.
 # It reaches vpk through VPK_TOKEN, exported for that one call and unset afterwards, because the
 # alternative is --token on a command line that is not private. See the comment at the upload itself.
 #
 # Usage:
 #   bash scripts/release-macos.sh
@@ -195,10 +197,18 @@ if [ "$UPLOAD" -eq 1 ]; then
    # also already hold the Windows package for the same tag, which is the case --merge is really doing
    # the work for: without it the second platform to publish a given version fails on a release that
    # exists, and with it the two sit side by side under one tag. --channel keeps the indexes apart.
    #
    # No --token in this array, and that is deliberate. It used to be there, and an argument is not a
    # private place to put a credential: /proc/<pid>/cmdline is world-readable on Linux, `ps` hands out
    # other processes' arguments freely, and whatever agent is auditing process creation on this machine
    # keeps its own copy. The comment above is about shell history and was never the whole story.
    #
    # vpk documents VPK_TOKEN as --token's environment fallback, so the value never becomes an argument.
    # Exported for the one call and unset straight after; an environment block is still readable by a
    # process with rights over this one, but it is out of every process listing and audit log.
    UPLOAD_ARGS=(
        upload gitea
        --repoUrl "$REPO_URL"
        --token "$TOKEN"
        --outputDir "$RELEASES_DIR"
        --channel "$CHANNEL"
        --releaseName "$TAG"
@@ -214,7 +224,15 @@ if [ "$UPLOAD" -eq 1 ]; then
    esac
    write_step 'Uploading'
-    dotnet vpk "${UPLOAD_ARGS[@]}" || stop_with 'vpk upload failed.'
+
    # Unset on the way out whether or not the upload worked, so a failed release does not leave the token
    # sitting in this shell for whatever runs next.
    export VPK_TOKEN="$TOKEN"
    vpk_status=0
    dotnet vpk "${UPLOAD_ARGS[@]}" || vpk_status=$?
    unset VPK_TOKEN
    [ "$vpk_status" -eq 0 ] || stop_with 'vpk upload failed.'
    write_step "Published $TAG."
    exit 0
@@ -16,9 +16,11 @@
      2. With -Upload: asks for the forge token and publishes what phase 1 produced. It does not rebuild,
         so the bytes that reach users are the bytes that were installed and checked.
-    The token is prompted for rather than read from a file or an environment variable, and only in the phase
+    The token is prompted for rather than read from a file or an ambient environment variable, and only in
-    that needs it — the build does not, and the fewer minutes a credential that can publish an update spends
+    the phase that needs it — the build does not, and the fewer minutes a credential that can publish an
-    in a shell's memory the better.
+    update spends in a shell's memory the better. It reaches vpk through VPK_TOKEN, set for that one call
    and cleared afterwards, because the alternative is --token on a command line every process on this
    machine can read. See the comment at the upload itself.
 .PARAMETER Upload
    Publish the packages already in Releases/ instead of building.
@@ -152,10 +154,24 @@ try {
        # --merge because Gitea already has a release entry for the pushed tag, and without it the upload
        # fails on a release that exists. --pre mirrors the rule the docker image job already applies to the
        # same tag, so a release candidate is a prerelease in both channels or in neither.
        #
        # ◆ NO --token HERE. IT WAS AN ARGUMENT, AND AN ARGUMENT IS PUBLIC ON THIS MACHINE.
        #
        # The comment above says the token never lands in shell history, which was true and was not the
        # whole story: it went straight into vpk's command line, and any process running as this user can
        # read that off a running process with one call —
        #
        #     Get-CimInstance Win32_Process | Select-Object Name, CommandLine
        #
        # — with process-creation auditing and EDR agents keeping their own copy afterwards. A token that
        # can publish an update every installed copy will fetch and run deserves better than that.
        #
        # vpk documents VPK_TOKEN as --token's environment fallback, so the flag simply goes away and the
        # value never becomes an argument at all. An environment block is still readable by a process with
        # rights over this one; what it is not is a string sitting in a process listing and an audit log.
        $uploadArgs = @(
            'upload', 'gitea',
            '--repoUrl', $RepoUrl,
            '--token', $token,
            '--outputDir', $ReleasesDir,
            '--channel', $Channel,
            '--releaseName', $tag,
@@ -169,7 +185,17 @@ try {
        }
        Write-Step 'Uploading'
-        & dotnet vpk @uploadArgs
+
        try {
            $env:VPK_TOKEN = $token
            & dotnet vpk @uploadArgs
        }
        finally {
            # SetEnvironmentVariable rather than Remove-Item, which throws when the variable is not there —
            # and this runs on the failure path, where it may well not be.
            [Environment]::SetEnvironmentVariable('VPK_TOKEN', $null)
        }
        if ($LASTEXITCODE -ne 0) { Stop-With 'vpk upload failed.' }
        Write-Step "Published $tag."
@@ -0,0 +1,49 @@
 using DodoSSH.Domain;
 using Microsoft.AspNetCore.Authorization;
 namespace DodoSSH.Api.Authorization;
 /// <summary>Requires the caller's account to be <see cref="UserStatus.Active"/>.</summary>
 /// <remarks>
 /// <para>
 /// <see cref="UserStatus.Suspended"/> is documented as "sign-in blocked", and nothing blocked it: the identity
 /// provider still issues tokens for the person, every endpoint resolved them through the current-user context,
 /// and that context looked an account up by issuer, subject and deletion alone. A suspended account could pull
 /// and push vaults, take relay tickets and hold the events socket open. This is the check, on both policies, so
 /// that no endpoint can be reached without it.
 /// </para>
 /// <para>
 /// A connection already open when the account is suspended — a relay tunnel, the events socket — is not
 /// reached by this; it ends on its own idle and lifetime limits.
 /// </para>
 /// </remarks>
 internal sealed class ActiveAccountRequirement : IAuthorizationRequirement;
 /// <summary>Satisfies <see cref="ActiveAccountRequirement"/> from the account row.</summary>
 internal sealed class ActiveAccountHandler(ICurrentUserContext currentUser, IHttpContextAccessor accessor)
    : AuthorizationHandler<ActiveAccountRequirement>
 {
    /// <inheritdoc />
    protected override async Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        ActiveAccountRequirement requirement)
    {
        ArgumentNullException.ThrowIfNull(context);
        // The policy's authentication requirement already refuses an anonymous caller with a 401; failing this
        // as well would turn that into a 403.
        if (context.User.Identity?.IsAuthenticated != true)
        {
            return;
        }
        var cancellationToken = accessor.HttpContext?.RequestAborted ?? CancellationToken.None;
        var user = await currentUser.GetOrProvisionAsync(cancellationToken).ConfigureAwait(false);
        if (user.Status == UserStatus.Active)
        {
            context.Succeed(requirement);
        }
    }
 }
@@ -102,8 +102,14 @@ internal sealed class CurrentUserContext(
    /// read-then-write: <c>user_account</c> carries the xmin concurrency token, so two overlapping
    /// requests from one user would each read the row, each set the timestamp, and the second would
    /// fail on a version that had moved under it. This writes at most one row and cannot conflict.
-    /// The tracked entity is deliberately left alone — a value up to an hour stale in memory changes
+    /// <para>
-    /// nothing, and marking it modified would enlist the user row in whatever the request saves next.
+    /// ◆ <b>But the write moves xmin under the tracked entity, so the entity is re-read after it.</b> It is
    /// not marked modified — that would enlist the user row in whatever the request saves next — and a
    /// stale timestamp in memory would change nothing on its own. A stale concurrency token does: the next
    /// save in the same request that touches this user (enrolment stamps <c>EnrolledAtUtc</c>) compared
    /// against the version from before the update and failed, so enrolling more than an hour after first
    /// signing in answered 500. Only when a row was actually written, which is once an hour at most.
    /// </para>
    /// </remarks>
    private async Task RefreshLastSeenAsync(UserAccount user, CancellationToken cancellationToken)
    {
@@ -114,13 +120,18 @@ internal sealed class CurrentUserContext(
            return;
        }
-        await database.Users
+        var written = await database.Users
            .Where(u => u.Id == user.Id
                && (u.LastSeenAtUtc == null || u.LastSeenAtUtc < now - LastSeenWindow))
            .ExecuteUpdateAsync(
                setters => setters.SetProperty(u => u.LastSeenAtUtc, now),
                cancellationToken)
            .ConfigureAwait(false);
        if (written > 0)
        {
            await database.Entry(user).ReloadAsync(cancellationToken).ConfigureAwait(false);
        }
    }
    private Task<UserAccount?> FindAsync(string issuer, string subject, CancellationToken cancellationToken) =>
@@ -80,6 +80,26 @@ internal sealed class DodoAuthorizationResultHandler : IAuthorizationMiddlewareR
        ArgumentNullException.ThrowIfNull(context);
        ArgumentNullException.ThrowIfNull(authorizeResult);
        var accountNotActive = authorizeResult.Forbidden
            && authorizeResult.AuthorizationFailure is { } refusal
            && refusal.FailedRequirements.OfType<ActiveAccountRequirement>().Any();
        if (accountNotActive)
        {
            await TypedResults.Problem(
                    detail: "This account has been suspended. Ask whoever runs this DodoSSH server.",
                    statusCode: StatusCodes.Status403Forbidden,
                    type: ProblemCodes.TypeBaseUri + ProblemCodes.AccountNotActive,
                    extensions: new Dictionary<string, object?>(StringComparer.Ordinal)
                    {
                        ["code"] = ProblemCodes.AccountNotActive,
                    })
                .ExecuteAsync(context)
                .ConfigureAwait(false);
            return;
        }
        var enrollmentMissing = authorizeResult.Forbidden
            && authorizeResult.AuthorizationFailure is { } failure
            && failure.FailedRequirements.OfType<EnrolledRequirement>().Any();
@@ -2,9 +2,18 @@
 #
 #   docker build -f src/DodoSSH.Api/Dockerfile .
 #
-# Directory.Build.props, Directory.Packages.props, NuGet.config and global.json all sit at
+# Directory.Build.props, Directory.Build.targets, Directory.Packages.props, NuGet.config and
-# the root and all four are load-bearing here — central package management means a csproj
+# global.json all sit at the root and all five are load-bearing here — central package
-# alone does not name a single version, and a build that cannot see them resolves nothing.
+# management means a csproj alone does not name a single version, and a build that cannot see
 # them resolves nothing.
 #
 # Directory.Build.targets is the one that is easy to forget, because leaving it out breaks
 # nothing until the day it does: it pins the version of the trimmer the SDK adds to
 # DodoSSH.Contracts and DodoSSH.Crypto by itself (see the comment there). Without it the restore
 # below asks for whatever ILLink the image's SDK bundles, which matches the lock files only
 # until .NET ships a servicing release — and then this image fails with NU1004 while ci.yml,
 # which does see the pin, stays green. That is how it was found: sdk:10.0-noble moved to
 # 10.0.401 (ILLink 10.0.12) and this build broke with no commit touching a package.
 # ---------------------------------------------------------------------------------------
 # Build
@@ -26,7 +35,7 @@ WORKDIR /src
 # dependency change and by nothing else. Every project in DodoSSH.Api's reference closure
 # has to be here — restore walks ProjectReference, and a missing csproj fails the graph
 # rather than skipping a node.
-COPY global.json NuGet.config Directory.Build.props Directory.Packages.props ./
+COPY global.json NuGet.config Directory.Build.props Directory.Build.targets Directory.Packages.props ./
 COPY src/DodoSSH.Api/DodoSSH.Api.csproj                       src/DodoSSH.Api/
 COPY src/DodoSSH.Api/packages.lock.json                       src/DodoSSH.Api/
 COPY src/DodoSSH.Contracts/DodoSSH.Contracts.csproj           src/DodoSSH.Contracts/
@@ -211,10 +211,23 @@ internal sealed class VaultEventsEndpoint(
    /// <summary>Runs the socket until something ends it, then closes it politely.</summary>
    /// <remarks>
    /// <para>
    /// 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>
+    /// clock is a third. They are joined by <see cref="Task.WhenAny(Task[])"/>, and the sender is
-    /// awaited before the close is written, because a close frame racing a notice frame is a protocol
+    /// finished 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.
    /// </para>
    /// <para>
    /// <b>No operation on the WebSocket is ever cancelled.</b> Cancelling a pending receive or send on
    /// the socket Kestrel hands over aborts it, and an aborted socket cannot send the close frame that
    /// is the only way a client learns <em>why</em> it was dropped — 4401 "reconnect with a fresh
    /// token" against 1001 "the server is going away" against a failure to back off from. This was
    /// once the case here, and it went unnoticed because <c>TestServer</c>'s in-memory socket survives
    /// the cancellation that a real one does not. So the token stops the queue and the clock; the
    /// sender is let finish its last write; the close goes out; and the receiver ends on the client's
    /// answering close. Each wait is bounded, and the socket is aborted only when a peer has stopped
    /// answering altogether. The relay's pump does the same, for the same reason.
    /// </para>
    /// </remarks>
    private async Task PumpAsync(
        WebSocket socket,
@@ -236,15 +249,21 @@ internal sealed class VaultEventsEndpoint(
            VaultCount: connection.VaultCount));
        var sending = SendAsync(socket, connection, pump.Token);
-        var receiving = ReceiveAsync(socket, connection, pump.Token);
+        var receiving = ReceiveAsync(socket, connection);
        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.
+        // Nothing may still be mid-send when the close frame goes out. A send that does not finish is
-        await Task.WhenAll(Settled(sending), Settled(receiving), Settled(minding)).ConfigureAwait(false);
+        // a client that has stopped reading, which will not read a close frame either.
        if (!await SettlesAsync(sending).ConfigureAwait(false))
        {
            socket.Abort();
        }
        await SettlesAsync(minding).ConfigureAwait(false);
        if (lifetime.ApplicationStopping.IsCancellationRequested)
        {
@@ -256,6 +275,14 @@ internal sealed class VaultEventsEndpoint(
        EventsLog.ClosingConnection(logger, connection.UserId, closure.Reason);
        await CloseAsync(socket, closure).ConfigureAwait(false);
        // The client's answering close is what ends the receiver. Returning before it arrives would
        // dispose the socket under a close frame still in flight.
        if (!await SettlesAsync(receiving).ConfigureAwait(false))
        {
            socket.Abort();
            await SettlesAsync(receiving).ConfigureAwait(false);
        }
    }
    /// <summary>
@@ -287,8 +314,9 @@ internal sealed class VaultEventsEndpoint(
            var bytes = JsonSerializer.SerializeToUtf8Bytes(frame, DodoSshJsonContext.Default.VaultEvent);
            // Not cancellable, deliberately. See PumpAsync.
            await socket
-                .SendAsync(bytes, WebSocketMessageType.Text, endOfMessage: true, cancellationToken)
+                .SendAsync(bytes, WebSocketMessageType.Text, endOfMessage: true, CancellationToken.None)
                .ConfigureAwait(false);
        }
    }
@@ -297,21 +325,26 @@ internal sealed class VaultEventsEndpoint(
    /// Reads what the client sends, which in this version is heartbeats and a close.
    /// </summary>
    /// <remarks>
    /// <para>
    /// 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.
    /// </para>
    /// <para>
    /// It takes no token: it ends on the client's close, a frame it refuses, or the socket failing —
    /// and when the server is the one ending the connection, the close it sends is what prompts the
    /// first of those. See <see cref="PumpAsync"/>.
    /// </para>
    /// </remarks>
-    private static async Task ReceiveAsync(
+    private static async Task ReceiveAsync(WebSocket socket, VaultEventConnection connection)
        WebSocket socket,
        VaultEventConnection connection,
        CancellationToken cancellationToken)
    {
        var buffer = new byte[MaxInboundFrameBytes];
-        while (!cancellationToken.IsCancellationRequested)
+        while (true)
        {
-            var received = await socket.ReceiveAsync(buffer, cancellationToken).ConfigureAwait(false);
+            // Not cancellable, deliberately. See PumpAsync.
            var received = await socket.ReceiveAsync(buffer, CancellationToken.None).ConfigureAwait(false);
            if (received.MessageType == WebSocketMessageType.Close)
            {
@@ -492,31 +525,39 @@ internal sealed class VaultEventsEndpoint(
    }
    /// <summary>
-    /// Awaits a pump loop, treating its cancellation and its socket faults as the ordinary end.
+    /// Waits for a pump loop to finish, for at most the close timeout.
    /// </summary>
    /// <returns>Whether it finished.</returns>
    /// <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)
+    private static async Task<bool> SettlesAsync(Task loop)
    {
        try
        {
-            await loop.ConfigureAwait(false);
+            await loop.WaitAsync(CloseTimeout).ConfigureAwait(false);
            return true;
        }
        catch (TimeoutException)
        {
            return false;
        }
        catch (Exception exception)
            when (exception is OperationCanceledException or WebSocketException or ObjectDisposedException)
        {
-            // Expected.
+            return true;
        }
    }
    /// <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
+    /// Mutable and shared, and safe without a lock for one specific reason: it is written only by
-    /// loops and read only after <see cref="Task.WhenAll(Task[])"/> over all of them, which is a
+    /// <see cref="MindAsync"/>, and read only after that loop has been awaited, which is a memory
-    /// memory barrier. Writes race only with each other, and any of them is a true answer.
+    /// barrier. If that loop outlived the close timeout, a late write races the read, and either
    /// answer is still a true one.
    /// </remarks>
    private sealed class Closure(int code, string reason)
    {
@@ -0,0 +1,24 @@
 using DodoSSH.Api.Features.Relay;
 namespace DodoSSH.Api.Features.Events;
 /// <summary>
 /// Announces a change to everything on this node that acts on one: the event sockets, and the relay.
 /// </summary>
 /// <remarks>
 /// What the write paths are given as their <see cref="IVaultEventPublisher"/>. They announce a change once and
 /// do not know who listens, which is the point: the relay learning about removals from teams did not have to
 /// touch any of the places a removal happens.
 /// </remarks>
 internal sealed class VaultEventFanOut(VaultEventHub hub, RelayAccessWatch relay) : IVaultEventPublisher
 {
    /// <inheritdoc />
    public void VaultChanged(Guid vaultId, long sequence) => hub.VaultChanged(vaultId, sequence);
    /// <inheritdoc />
    public void VaultAccessChanged(Guid userId)
    {
        hub.VaultAccessChanged(userId);
        _ = relay.AccessChangedAsync(userId);
    }
 }
@@ -1,5 +1,6 @@
 using System.Security.Cryptography;
 using System.Text.Json;
 using DodoSSH.Api.Setup;
 using DodoSSH.Contracts;
 using DodoSSH.Crypto;
 using DodoSSH.Domain;
@@ -106,9 +107,7 @@ internal sealed class EnrollmentService(
        byte[] fingerprint,
        CancellationToken cancellationToken)
    {
-        var strategy = database.Database.CreateExecutionStrategy();
+        return await database.ExecuteFreshAsync([user], async () =>
        return await strategy.ExecuteAsync(async () =>
        {
            var transaction = await database.Database
                .BeginTransactionAsync(cancellationToken)
@@ -26,9 +26,6 @@ internal sealed class GetMetaEndpoint(
    /// <summary>Sync semantics version. Bumped when push or pull behaviour changes.</summary>
    internal const int SyncProtocolVersion = 1;
    /// <summary>Feature flag for the relay.</summary>
    internal const string RelayFeature = "relay";
    /// <inheritdoc />
    public override void Configure()
    {
@@ -50,7 +47,7 @@ internal sealed class GetMetaEndpoint(
        List<string> features = ["teams"];
        if (relay.Value.Enabled)
        {
-            features.Add(RelayFeature);
+            features.Add(RelayProtocol.Feature);
        }
        // Advertised so a client knows whether to hold a socket open or rely on its timer. Absence is
@@ -0,0 +1,62 @@
 using DodoSSH.Api.Authorization;
 using DodoSSH.Domain.Authorization;
 namespace DodoSSH.Api.Features.Relay;
 /// <summary>
 /// Ends a user's relay sessions to vaults they can no longer reach, when their access changes.
 /// </summary>
 /// <remarks>
 /// <para>
 /// A relay session is authorised once, when its ticket is issued, and used to run on for as long as it
 /// carried bytes — up to the maximum lifetime, twelve hours by default. Removing somebody from a team took
 /// their keys and their vault list away at once, and left any shell they had open through the relay running
 /// into the team's machines until it went idle.
 /// </para>
 /// <para>
 /// Told by the same announcement that tells their event socket to re-read its vaults — see
 /// <see cref="Events.IVaultEventPublisher.VaultAccessChanged"/> — and it asks the same question the ticket
 /// endpoint asked, against the database as it now stands. Off the announcing request, because that request
 /// has already committed and answered, and a slow re-check must not hold it.
 /// </para>
 /// </remarks>
 internal sealed class RelayAccessWatch(
    RelaySessionRegistry sessions,
    IServiceScopeFactory scopes,
    ILogger<RelayAccessWatch> logger)
 {
    /// <summary>Re-checks every session the user has open, in the background.</summary>
    /// <returns>The re-check, for a caller that wants to wait for it; the announcement does not.</returns>
    internal Task AccessChangedAsync(Guid userId)
    {
        var open = sessions.SessionsOf(userId);
        return open.Count == 0 ? Task.CompletedTask : Task.Run(() => RecheckAsync(userId, open));
    }
    private async Task RecheckAsync(Guid userId, IReadOnlyList<RelaySessionRegistry.Lease> open)
    {
        try
        {
            var scope = scopes.CreateAsyncScope();
            await using var _ = scope.ConfigureAwait(false);
            var access = scope.ServiceProvider.GetRequiredService<IVaultAccessService>();
            foreach (var lease in open)
            {
                var resolved = await access.ResolveAsync(userId, lease.VaultId, CancellationToken.None)
                    .ConfigureAwait(false);
                if (!resolved.Granted || !resolved.Permissions.HasFlag(PermissionFlags.Connect))
                {
                    lease.Revoke();
                }
            }
        }
        catch (Exception exception) when (exception is not OutOfMemoryException)
        {
            RelayLog.AccessRecheckFailed(logger, userId, exception);
        }
    }
 }
@@ -0,0 +1,192 @@
 using System.Net;
 using System.Net.Sockets;
 using DodoSSH.Api.Setup;
 namespace DodoSSH.Api.Features.Relay;
 /// <summary>
 /// Decides which addresses and ports the relay may dial. ADR 0004 §3, in the order it is written.
 /// </summary>
 /// <remarks>
 /// <para>
 /// This runs on <em>addresses</em>, never on names. The name is resolved once, at ticket issue, and what
 /// this permits goes into the ticket; the socket dials those addresses and nothing else. A check on the
 /// name would be defeated by DNS rebinding — answer with a public address for the check and a loopback
 /// one for the dial — which is the attack ADR 0004 is built around.
 /// </para>
 /// <para>
 /// Three layers, and the order is the security property. The <see cref="Refused"/> list comes first and
 /// has no configuration at all: nothing an operator sets, and nothing a host row says, reaches a
 /// loopback, link-local, unspecified, multicast or metadata address. Then the operator's own denials,
 /// then their allow-list, then the private-network switch.
 /// </para>
 /// <para>
 /// <b>An address that embeds another is judged as the one it embeds.</b> <c>::ffff:127.0.0.1</c> is
 /// loopback however it is spelled, and a check that compared it against IPv6 loopback alone would pass
 /// it — the classic bypass the ADR names. The NAT64 well-known prefix is unwrapped the same way, because
 /// on a network with a NAT64 gateway <c>64:ff9b::a9fe:a9fe</c> <em>is</em> the metadata endpoint.
 /// </para>
 /// </remarks>
 internal sealed class RelayAddressPolicy
 {
    /// <summary>
    /// Addresses the relay never dials, whatever it is configured to do.
    /// </summary>
    /// <remarks>
    /// Broader than the ADR's list in two places, both deliberately. <c>240.0.0.0/4</c> — reserved, and
    /// containing the limited broadcast address — has no host worth reaching. And IPv6 <c>::/96</c>, the
    /// deprecated IPv4-compatible block, covers the unspecified address and loopback while also refusing
    /// the spellings of IPv4 that a stack may or may not map; nothing legitimate lives there.
    /// </remarks>
    private static readonly IPNetwork[] Refused =
    [
        // IPv4: "this network", loopback, link-local (which holds 169.254.169.254), multicast, reserved.
        IPNetwork.Parse("0.0.0.0/8"),
        IPNetwork.Parse("127.0.0.0/8"),
        IPNetwork.Parse("169.254.0.0/16"),
        IPNetwork.Parse("224.0.0.0/4"),
        IPNetwork.Parse("240.0.0.0/4"),
        // Alibaba Cloud's metadata endpoint, which sits inside carrier-grade NAT space and so would
        // otherwise be permitted as private — the range a Tailnet also uses, which is why the whole
        // block cannot simply be refused.
        IPNetwork.Parse("100.100.100.200/32"),
        // IPv6: IPv4-compatible (with unspecified and loopback), link-local, multicast, and the AWS
        // metadata endpoint's IPv6 address.
        IPNetwork.Parse("::/96"),
        IPNetwork.Parse("fe80::/10"),
        IPNetwork.Parse("ff00::/8"),
        IPNetwork.Parse("fd00:ec2::254/128"),
    ];
    /// <summary>
    /// Ranges <see cref="RelayOptions.AllowPrivateNetworks"/> governs.
    /// </summary>
    /// <remarks>
    /// Carrier-grade NAT is here rather than treated as public, because it is where a Tailnet lives and
    /// "the server is on the same Tailnet" is one of the shapes the relay exists for. Site-local
    /// <c>fec0::/10</c> is deprecated and was private while it lived.
    /// </remarks>
    private static readonly IPNetwork[] Private =
    [
        IPNetwork.Parse("10.0.0.0/8"),
        IPNetwork.Parse("172.16.0.0/12"),
        IPNetwork.Parse("192.168.0.0/16"),
        IPNetwork.Parse("100.64.0.0/10"),
        IPNetwork.Parse("fc00::/7"),
        IPNetwork.Parse("fec0::/10"),
    ];
    /// <summary>The NAT64 well-known prefix, RFC 6052, whose low 32 bits are an IPv4 address.</summary>
    private static readonly IPNetwork Nat64 = IPNetwork.Parse("64:ff9b::/96");
    /// <summary>
    /// Ports the relay never dials.
    /// </summary>
    /// <remarks>
    /// SMTP and nothing else, per ADR 0004: a relay that reached port 25 is a spam cannon with the
    /// operator's address on it. Database ports stay open, because forwarding to one is a headline use,
    /// and the control that matters there is who may dial the host at all.
    /// </remarks>
    private static readonly int[] RefusedPorts = [25, 465, 587];
    private readonly bool allowPrivate;
    private readonly IPNetwork[] allowed;
    private readonly IPNetwork[] denied;
    public RelayAddressPolicy(RelayOptions options)
    {
        ArgumentNullException.ThrowIfNull(options);
        allowPrivate = options.AllowPrivateNetworks;
        allowed = ParseAll(options.AllowedNetworks);
        denied = ParseAll(options.DeniedNetworks);
    }
    /// <summary>Whether a port may be dialled at all.</summary>
    internal static bool PermitsPort(int port) =>
        port is >= 1 and <= 65535 && !RefusedPorts.Contains(port);
    /// <summary>
    /// Whether every entry is a network this policy can read.
    /// </summary>
    /// <remarks>
    /// For startup validation. A typo in a deny list that was silently skipped would be a hole the
    /// operator believes is closed, so an unreadable entry stops the server instead.
    /// <para>
    /// Host bits are refused as well, although <see cref="IPNetwork.TryParse(string?, out IPNetwork)"/>
    /// would mask them off quietly. <c>10.20.5.7/16</c> could be a /16 written from memory or a /32 with
    /// the wrong suffix, and in a deny list those differ by sixty-five thousand addresses.
    /// </para>
    /// </remarks>
    internal static bool AreNetworks(IEnumerable<string> entries) =>
        entries.All(entry =>
            IPNetwork.TryParse(entry, out var network)
            && IPAddress.TryParse(entry.AsSpan(0, entry.IndexOf('/', StringComparison.Ordinal)), out var written)
            && written.Equals(network.BaseAddress));
    /// <summary>
    /// The address the relay would actually be talking to, with any embedding unwrapped.
    /// </summary>
    internal static IPAddress Normalise(IPAddress address)
    {
        ArgumentNullException.ThrowIfNull(address);
        if (address.IsIPv4MappedToIPv6)
        {
            return address.MapToIPv4();
        }
        if (address.AddressFamily == AddressFamily.InterNetworkV6 && Nat64.Contains(address))
        {
            var bytes = address.GetAddressBytes();
            return new IPAddress(bytes.AsSpan(12, 4));
        }
        // A scope id is how an address names an interface on this machine, which is not something a
        // host row gets to choose. Dropped, so what is judged is what is dialled.
        return address.AddressFamily == AddressFamily.InterNetworkV6 && address.ScopeId != 0
            ? new IPAddress(address.GetAddressBytes())
            : address;
    }
    /// <summary>Whether the relay may dial this address.</summary>
    /// <remarks>
    /// Judges the normalised address. Callers should dial <see cref="Normalise"/>'s answer too, so that
    /// the address checked and the address connected to are the same object rather than two spellings
    /// the operating system is trusted to agree about.
    /// </remarks>
    internal bool Permits(IPAddress address)
    {
        var target = Normalise(address);
        if (Refused.Any(network => Within(network, target)))
        {
            return false;
        }
        if (denied.Any(network => Within(network, target)))
        {
            return false;
        }
        if (allowed.Length > 0)
        {
            return allowed.Any(network => Within(network, target));
        }
        return allowPrivate || !Private.Any(network => Within(network, target));
    }
    /// <remarks>
    /// <see cref="IPNetwork.Contains"/> answers false across address families rather than throwing, so
    /// a list mixing IPv4 and IPv6 needs no sorting — but it is spelled out here because the one-line
    /// alternative reads as though it compared across families.
    /// </remarks>
    private static bool Within(IPNetwork network, IPAddress address) =>
        network.BaseAddress.AddressFamily == address.AddressFamily && network.Contains(address);
    private static IPNetwork[] ParseAll(IEnumerable<string> entries) =>
        [.. entries.Select(entry => IPNetwork.Parse(entry))];
 }
@@ -0,0 +1,759 @@
 using System.Buffers;
 using System.Net;
 using System.Net.WebSockets;
 using DodoSSH.Api.Setup;
 using DodoSSH.Contracts;
 using DodoSSH.Domain;
 using DodoSSH.Infrastructure;
 using FastEndpoints;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Options;
 using Npgsql;
 namespace DodoSSH.Api.Features.Relay;
 /// <summary>
 /// The relay socket: a ticket in, raw bytes to one host and back.
 /// </summary>
 /// <remarks>
 /// <para>
 /// Anonymous at the HTTP layer, because the ticket is the authorization and it is the whole of it. A
 /// ticket carries no API authority — it names one host, one set of addresses and one session — so this
 /// endpoint can accept it from a client that cannot set an <c>Authorization</c> header on an upgrade,
 /// which is the constraint ADR 0004 was written around. It is verified, checked for freshness and
 /// redeemed before the upgrade is accepted, so a refused ticket costs a problem document and no socket.
 /// </para>
 /// <para>
 /// <b>Nothing here is scoped to the request.</b> A session lasts as long as a shell does, which is hours,
 /// and anything scoped held across it is a pooled database connection held across it. The database is
 /// touched three times — redeem, open the audit row, close it — each from a scope of its own that is
 /// disposed before the next byte moves. That is ADR 0004's consequence about <c>DbContext</c> lifetime.
 /// </para>
 /// <para>
 /// Backpressure is the await. Each direction reads one buffer, writes it, and does not read again until
 /// the write has completed, so a slow reader on either side stops this side reading, which fills the
 /// kernel's receive window, which throttles the sender at the far end. Nothing is queued in between, and
 /// a session costs its two buffers whatever the peers do.
 /// </para>
 /// </remarks>
 internal sealed class RelayConnectEndpoint(
    IServiceScopeFactory scopes,
    IRelayNetwork network,
    RelayTicketCodec codec,
    RelaySessionRegistry sessions,
    IOptions<RelayOptions> options,
    TimeProvider clock,
    IHostApplicationLifetime lifetime,
    ILogger<RelayConnectEndpoint> logger)
    : EndpointWithoutRequest
 {
    /// <summary>
    /// One direction's buffer.
    /// </summary>
    /// <remarks>
    /// Room for an SSH packet at the size OpenSSH sends them, so a bulk transfer moves in one read and
    /// one write per packet rather than several.
    /// </remarks>
    private const int BufferBytes = 32 * 1024;
    /// <summary>How long a close handshake, or a peer's last write, may take before the socket is dropped.</summary>
    private static readonly TimeSpan CloseTimeout = TimeSpan.FromSeconds(5);
    /// <inheritdoc />
    public override void Configure()
    {
        Get(RelayProtocol.ConnectPath);
        // The ticket is the authorization. See the remarks on this class, and ADR 0004.
        AllowAnonymous();
        Description(b => b
            .WithName("RelayConnect")
            .WithSummary("Pipes raw bytes between a WebSocket and the host a relay ticket names.")
            .WithTags("Relay"));
    }
    /// <inheritdoc />
    public override async Task HandleAsync(CancellationToken ct)
    {
        var ticket = await AdmitTicketAsync(ct).ConfigureAwait(false);
        if (ticket is null)
        {
            return;
        }
        var lease = sessions.TryAdmit(ticket.UserId, ticket.VaultId);
        try
        {
            using var socket = await HttpContext.WebSockets
                .AcceptWebSocketAsync(new WebSocketAcceptContext { SubProtocol = RelayProtocol.SubProtocol })
                .ConfigureAwait(false);
            if (lease is null)
            {
                RelayLog.LimitReached(logger, ticket.UserId, sessions.Count);
                await CloseAsync(
                        socket,
                        new Ending(
                            RelayCloseReason.Unspecified,
                            RelayProtocol.TooManySessionsCloseCode,
                            "Too many relay sessions are open."))
                    .ConfigureAwait(false);
                return;
            }
            if (lifetime.ApplicationStopping.IsCancellationRequested)
            {
                await CloseAsync(socket, ShuttingDown).ConfigureAwait(false);
                return;
            }
            await RelayAsync(socket, ticket, lease.Revoked, ct).ConfigureAwait(false);
        }
        finally
        {
            // Inside a try that starts before the upgrade, for the reason VaultEventsEndpoint gives: an
            // accept that throws would otherwise hold a place against this user's cap forever.
            lease?.Dispose();
        }
    }
    private static Ending ShuttingDown { get; } = new(
        RelayCloseReason.ServerShutdown,
        (int)WebSocketCloseStatus.EndpointUnavailable,
        "The server is shutting down.");
    /// <summary>
    /// Answers everything that is not a redeemable ticket, as ordinary HTTP, before any socket exists.
    /// </summary>
    /// <returns>The redeemed ticket, or null when a response has been sent.</returns>
    /// <remarks>
    /// A ticket that is forged, expired, spent, or simply absent all answer 401
    /// <c>relay-ticket-invalid</c>, with one remedy — ask for another — and no hint of which it was.
    /// </remarks>
    private async Task<RelayTicket?> AdmitTicketAsync(CancellationToken cancellationToken)
    {
        if (!options.Value.Enabled)
        {
            await Send.ResultAsync(Problems.Coded(
                    StatusCodes.Status404NotFound,
                    ProblemCodes.RelayUnavailable,
                    "This server does not relay. GET /api/v1/meta lists the features it does offer."))
                .ConfigureAwait(false);
            return null;
        }
        var offered = HttpContext.WebSockets.WebSocketRequestedProtocols;
        if (!HttpContext.WebSockets.IsWebSocketRequest
            || !offered.Contains(RelayProtocol.SubProtocol, StringComparer.Ordinal))
        {
            await Send.ResultAsync(Problems.Coded(
                    StatusCodes.Status400BadRequest,
                    ProblemCodes.MalformedRequest,
                    "This endpoint is a WebSocket. Send an upgrade request offering the "
                    + $"'{RelayProtocol.SubProtocol}' subprotocol and the ticket as a second one, "
                    + $"'{RelayProtocol.TicketProtocolPrefix}<ticket>'."))
                .ConfigureAwait(false);
            return null;
        }
        var sealedTicket = offered
            .FirstOrDefault(protocol => protocol.StartsWith(RelayProtocol.TicketProtocolPrefix, StringComparison.Ordinal))
            ?[RelayProtocol.TicketProtocolPrefix.Length..];
        var ticket = sealedTicket is { Length: > 0 } ? codec.TryOpen(sealedTicket) : null;
        if (ticket is null || !await RedeemAsync(ticket, cancellationToken).ConfigureAwait(false))
        {
            RelayLog.TicketRefused(logger, ticket?.SessionId);
            await Send.ResultAsync(Problems.Coded(
                    StatusCodes.Status401Unauthorized,
                    ProblemCodes.RelayTicketInvalid,
                    "This relay ticket is not valid: it is expired, already used, or was not issued here. "
                    + $"Ask for another from POST {RelayProtocol.TicketsPath}."))
                .ConfigureAwait(false);
            return null;
        }
        return ticket;
    }
    /// <summary>
    /// Spends the ticket, or answers false when it has been spent already.
    /// </summary>
    /// <remarks>
    /// <para>
    /// A unique insert, which is the only form of "once" that holds across nodes: two redemptions racing
    /// on two nodes both attempt the insert and the database lets exactly one of them win.
    /// </para>
    /// <para>
    /// Rows for tickets that can no longer verify are swept on the way. They guard nothing, and sweeping
    /// here — on a path that runs once per session rather than once per request — keeps the table the
    /// size of the last thirty seconds without a background job to forget about.
    /// </para>
    /// </remarks>
    private async Task<bool> RedeemAsync(RelayTicket ticket, CancellationToken cancellationToken)
    {
        var scope = scopes.CreateAsyncScope();
        await using var _ = scope.ConfigureAwait(false);
        var database = scope.ServiceProvider.GetRequiredService<DodoDbContext>();
        var now = clock.GetUtcNow();
        await database.RelayTicketUses
            .Where(use => use.ExpiresAtUtc < now)
            .ExecuteDeleteAsync(cancellationToken)
            .ConfigureAwait(false);
        database.RelayTicketUses.Add(new RelayTicketUse
        {
            TicketId = ticket.TicketId,
            ExpiresAtUtc = ticket.ExpiresAt,
            UsedAtUtc = now,
        });
        try
        {
            await database.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
            return true;
        }
        catch (DbUpdateException exception)
            when (string.Equals(
                (exception.InnerException as PostgresException)?.SqlState,
                PostgresErrorCodes.UniqueViolation,
                StringComparison.Ordinal))
        {
            return false;
        }
    }
    /// <summary>Dials the target, pipes until something ends it, and writes down what happened.</summary>
    private async Task RelayAsync(
        WebSocket socket,
        RelayTicket ticket,
        CancellationToken revoked,
        CancellationToken requestAborted)
    {
        var started = clock.GetUtcNow();
        await OpenAuditAsync(ticket, started).ConfigureAwait(false);
        var dialled = await DialAsync(ticket, requestAborted).ConfigureAwait(false);
        if (dialled is not var (target, address))
        {
            RelayLog.TargetUnreachable(logger, ticket.SessionId, ticket.HostId);
            var unreachable = new Ending(
                RelayCloseReason.TargetUnreachable,
                RelayProtocol.TargetUnreachableCloseCode,
                "The relay could not reach the host.");
            await CloseAsync(socket, unreachable).ConfigureAwait(false);
            await CloseAuditAsync(ticket.SessionId, null, new Counters(clock, started), unreachable.Reason).ConfigureAwait(false);
            return;
        }
        var counters = new Counters(clock, started);
        Ending ending;
        await using (target.ConfigureAwait(false))
        {
            RelayLog.SessionOpened(logger, ticket.SessionId, ticket.UserId, ticket.HostId, sessions.Count);
            ending = await PumpAsync(socket, target, counters, started, revoked, requestAborted).ConfigureAwait(false);
        }
        RelayLog.SessionClosed(
            logger,
            ticket.SessionId,
            ending.Reason,
            counters.ClientToTarget,
            counters.TargetToClient);
        await CloseAuditAsync(ticket.SessionId, address, counters, ending.Reason).ConfigureAwait(false);
    }
    /// <summary>
    /// Connects to the first of the ticket's addresses that answers, within the connect timeout overall.
    /// </summary>
    /// <remarks>
    /// Overall rather than per address, so a name with sixteen dead addresses costs five seconds rather
    /// than eighty. In the order resolved, which is the order the operating system's resolver prefers.
    /// </remarks>
    private async Task<(Stream Target, IPAddress Address)?> DialAsync(
        RelayTicket ticket,
        CancellationToken cancellationToken)
    {
        using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        timeout.CancelAfter(options.Value.ConnectTimeout);
        foreach (var address in ticket.TargetAddresses)
        {
            try
            {
                var target = await network
                    .ConnectAsync(address, ticket.TargetPort, timeout.Token)
                    .ConfigureAwait(false);
                return (target, address);
            }
            catch (OperationCanceledException)
            {
                return null;
            }
            catch (Exception exception) when (exception is IOException or System.Net.Sockets.SocketException)
            {
                // The next address, if there is one.
            }
        }
        return null;
    }
    /// <summary>
    /// Runs both directions and the clock until one of them ends the session, then ends it politely.
    /// </summary>
    /// <remarks>
    /// <para>
    /// <b>No operation on the WebSocket is ever cancelled.</b> Cancelling a pending receive or send on a
    /// .NET WebSocket aborts it, and an aborted socket cannot send the close frame that is the only way
    /// a client learns <em>why</em> its session ended — which, for an idle timeout or a drain, is the
    /// difference between "reconnect" and "something is broken". So the token stops the target side and
    /// the clock; the sender is let finish its last write; the close goes out; and the receiver ends on
    /// the client's answering close. Each wait is bounded, and the socket is aborted only when a peer
    /// has stopped answering altogether.
    /// </para>
    /// </remarks>
    private async Task<Ending> PumpAsync(
        WebSocket socket,
        Stream target,
        Counters counters,
        DateTimeOffset started,
        CancellationToken revoked,
        CancellationToken requestAborted)
    {
        using var pump = CancellationTokenSource.CreateLinkedTokenSource(requestAborted);
        var upstream = ClientToTargetAsync(socket, target, counters, pump.Token);
        var downstream = TargetToClientAsync(target, socket, counters, pump.Token);
        var minding = MindAsync(counters, started, revoked, pump.Token);
        var first = await Task.WhenAny(upstream, downstream, minding).ConfigureAwait(false);
        var ending = await first.ConfigureAwait(false) ?? new Ending(
            RelayCloseReason.ClientClosed, (int)WebSocketCloseStatus.NormalClosure, string.Empty);
        await pump.CancelAsync().ConfigureAwait(false);
        // The only sender must be done before the close frame is written: a WebSocket permits one send
        // at a time and faults permanently on a second.
        if (!await SettlesAsync(downstream).ConfigureAwait(false))
        {
            socket.Abort();
        }
        await CloseAsync(socket, ending).ConfigureAwait(false);
        if (!await SettlesAsync(upstream).ConfigureAwait(false))
        {
            socket.Abort();
            await SettlesAsync(upstream).ConfigureAwait(false);
        }
        await SettlesAsync(minding).ConfigureAwait(false);
        return ending;
    }
    /// <summary>Client to target: every binary message is the next bytes of the stream.</summary>
    private static async Task<Ending?> ClientToTargetAsync(
        WebSocket socket,
        Stream target,
        Counters counters,
        CancellationToken cancellationToken)
    {
        var buffer = ArrayPool<byte>.Shared.Rent(BufferBytes);
        try
        {
            while (true)
            {
                ValueWebSocketReceiveResult received;
                try
                {
                    // Not cancellable, deliberately. See PumpAsync.
                    received = await socket.ReceiveAsync(buffer.AsMemory(), CancellationToken.None)
                        .ConfigureAwait(false);
                }
                catch (Exception exception) when (exception is WebSocketException or OperationCanceledException)
                {
                    return ClientGone;
                }
                if (received.MessageType == WebSocketMessageType.Close)
                {
                    return ClientGone;
                }
                // A byte pipe has no text. A client sending some has the wrong idea about this endpoint,
                // and forwarding it into an SSH stream would corrupt that stream at best.
                if (received.MessageType != WebSocketMessageType.Binary)
                {
                    return new Ending(
                        RelayCloseReason.Error,
                        (int)WebSocketCloseStatus.InvalidMessageType,
                        "The relay carries binary messages only.");
                }
                try
                {
                    await target.WriteAsync(buffer.AsMemory(0, received.Count), cancellationToken)
                        .ConfigureAwait(false);
                }
                catch (OperationCanceledException)
                {
                    return null;
                }
                catch (IOException)
                {
                    return TargetGone;
                }
                counters.AddClientToTarget(received.Count);
            }
        }
        finally
        {
            ArrayPool<byte>.Shared.Return(buffer);
        }
    }
    /// <summary>Target to client: every read becomes one binary message.</summary>
    private static async Task<Ending?> TargetToClientAsync(
        Stream target,
        WebSocket socket,
        Counters counters,
        CancellationToken cancellationToken)
    {
        var buffer = ArrayPool<byte>.Shared.Rent(BufferBytes);
        try
        {
            while (true)
            {
                int read;
                try
                {
                    read = await target.ReadAsync(buffer.AsMemory(0, BufferBytes), cancellationToken)
                        .ConfigureAwait(false);
                }
                catch (OperationCanceledException)
                {
                    return null;
                }
                catch (IOException)
                {
                    return TargetGone;
                }
                if (read == 0)
                {
                    return TargetGone;
                }
                try
                {
                    // Not cancellable, deliberately. See PumpAsync.
                    await socket
                        .SendAsync(
                            buffer.AsMemory(0, read),
                            WebSocketMessageType.Binary,
                            endOfMessage: true,
                            CancellationToken.None)
                        .ConfigureAwait(false);
                }
                catch (Exception exception) when (exception is WebSocketException or ObjectDisposedException)
                {
                    return ClientGone;
                }
                counters.AddTargetToClient(read);
            }
        }
        finally
        {
            ArrayPool<byte>.Shared.Return(buffer);
        }
    }
    /// <summary>
    /// Ends the session at the idle timeout, the lifetime cap, or the end of a shutdown's drain.
    /// </summary>
    /// <remarks>
    /// <para>
    /// A shutdown does not end a session; it starts a countdown. ADR 0004 asks that a
    /// <c>docker compose up -d</c> not guillotine live shells, so a session in progress when the server is
    /// told to stop is given the drain timeout to finish — most will, because the user was already
    /// closing it or the deployment waits — and is closed with 1001 only when that runs out, which tells
    /// the client to reconnect rather than to report a fault. The host's own shutdown timeout is set
    /// longer than the drain for this to be possible at all.
    /// </para>
    /// <para>
    /// Idle means no bytes in either direction. WebSocket pings are not bytes of the stream and do not
    /// count; SSH's own keepalives do, which is how a client that wants an idle shell kept open says so.
    /// </para>
    /// </remarks>
    private async Task<Ending?> MindAsync(
        Counters counters,
        DateTimeOffset started,
        CancellationToken revoked,
        CancellationToken cancellationToken)
    {
        var settings = options.Value;
        var hardDeadline = started + settings.MaxSessionDuration;
        DateTimeOffset? drainDeadline = null;
        while (!cancellationToken.IsCancellationRequested)
        {
            var now = clock.GetUtcNow();
            if (drainDeadline is null && lifetime.ApplicationStopping.IsCancellationRequested)
            {
                drainDeadline = now + settings.DrainTimeout;
            }
            var idleDeadline = counters.LastActivity + settings.IdleTimeout;
            if (Due(now, revoked.IsCancellationRequested, hardDeadline, drainDeadline, idleDeadline) is { } ending)
            {
                return ending;
            }
            var next = new[] { hardDeadline, idleDeadline, drainDeadline ?? DateTimeOffset.MaxValue }.Min();
            // Woken early by the start of a shutdown, so the drain is measured from when it began rather
            // than from whenever the idle clock next came round.
            using var wake = drainDeadline is null
                ? CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, revoked, lifetime.ApplicationStopping)
                : CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, revoked);
            try
            {
                await Task.Delay(next - now, clock, wake.Token).ConfigureAwait(false);
            }
            catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
            {
                // The shutdown began, or access was withdrawn. Round again to act on whichever it was.
            }
            catch (OperationCanceledException)
            {
                return null;
            }
        }
        return null;
    }
    /// <summary>Whichever reason to end the session has come due, or null while none has.</summary>
    /// <remarks>
    /// Revocation first, because it is the one reason here that is about the user rather than the session:
    /// they were removed from the team, or the vault was taken from them, after this session was admitted.
    /// It used to run on for as long as it carried bytes, up to the maximum lifetime.
    /// </remarks>
    private static Ending? Due(
        DateTimeOffset now,
        bool revoked,
        DateTimeOffset hardDeadline,
        DateTimeOffset? drainDeadline,
        DateTimeOffset idleDeadline)
    {
        if (revoked)
        {
            return AccessRevoked;
        }
        if (now >= hardDeadline)
        {
            return new Ending(
                RelayCloseReason.DurationLimit,
                RelayProtocol.DurationLimitCloseCode,
                "This relay session reached its maximum lifetime.");
        }
        if (drainDeadline is { } drain && now >= drain)
        {
            return ShuttingDown;
        }
        return now >= idleDeadline
            ? new Ending(
                RelayCloseReason.IdleTimeout,
                RelayProtocol.IdleTimeoutCloseCode,
                "This relay session carried nothing for the idle timeout.")
            : null;
    }
    private static Ending AccessRevoked { get; } = new(
        RelayCloseReason.AccessRevoked,
        RelayProtocol.AccessRevokedCloseCode,
        "You no longer have access to this host.");
    private static Ending ClientGone { get; } =
        new(RelayCloseReason.ClientClosed, (int)WebSocketCloseStatus.NormalClosure, string.Empty);
    private static Ending TargetGone { get; } =
        new(RelayCloseReason.TargetClosed, (int)WebSocketCloseStatus.NormalClosure, "The host closed the connection.");
    /// <summary>
    /// Opens the audit row, before the target is dialled, so a session that never reached its host is
    /// still one the operator can see.
    /// </summary>
    private async Task OpenAuditAsync(RelayTicket ticket, DateTimeOffset started)
    {
        var scope = scopes.CreateAsyncScope();
        await using var _ = scope.ConfigureAwait(false);
        var database = scope.ServiceProvider.GetRequiredService<DodoDbContext>();
        database.RelaySessions.Add(new RelaySession
        {
            Id = ticket.SessionId,
            UserId = ticket.UserId,
            HostId = ticket.HostId,
            VaultId = ticket.VaultId,
            TargetHost = ticket.TargetHost,
            TargetPort = ticket.TargetPort,
            ClientAddress = HttpContext.Connection.RemoteIpAddress?.ToString(),
            StartedAtUtc = started,
        });
        // Not the request's token: the row has to be written even for a client that has already gone,
        // or a session that was cut off would be the one with no record.
        await database.SaveChangesAsync(CancellationToken.None).ConfigureAwait(false);
    }
    /// <summary>
    /// Closes the audit row. A failure is logged and swallowed: the bytes have already moved, and
    /// throwing here would only turn a finished session into an unhandled exception.
    /// </summary>
    private async Task CloseAuditAsync(
        Guid sessionId,
        IPAddress? address,
        Counters counters,
        RelayCloseReason reason)
    {
        try
        {
            var scope = scopes.CreateAsyncScope();
            await using var _ = scope.ConfigureAwait(false);
            var database = scope.ServiceProvider.GetRequiredService<DodoDbContext>();
            var ended = clock.GetUtcNow();
            var dialled = address?.ToString();
            await database.RelaySessions
                .Where(session => session.Id == sessionId)
                .ExecuteUpdateAsync(
                    set => set
                        .SetProperty(session => session.EndedAtUtc, ended)
                        .SetProperty(session => session.TargetAddress, dialled)
                        .SetProperty(session => session.BytesClientToTarget, counters.ClientToTarget)
                        .SetProperty(session => session.BytesTargetToClient, counters.TargetToClient)
                        .SetProperty(session => session.CloseReason, reason),
                    CancellationToken.None)
                .ConfigureAwait(false);
        }
        catch (Exception exception) when (exception is DbUpdateException or NpgsqlException or InvalidOperationException)
        {
            RelayLog.AuditCloseFailed(logger, sessionId, exception);
        }
    }
    private static async Task CloseAsync(WebSocket socket, Ending ending)
    {
        if (socket.State is not (WebSocketState.Open or WebSocketState.CloseReceived))
        {
            return;
        }
        using var timeout = new CancellationTokenSource(CloseTimeout);
        try
        {
            await socket
                .CloseOutputAsync((WebSocketCloseStatus)ending.Code, ending.Description, 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.
        }
    }
    /// <summary>Waits for a loop to finish, for at most the close timeout.</summary>
    /// <returns>Whether it finished.</returns>
    private static async Task<bool> SettlesAsync(Task loop)
    {
        try
        {
            await loop.WaitAsync(CloseTimeout).ConfigureAwait(false);
            return true;
        }
        catch (TimeoutException)
        {
            return false;
        }
        catch (Exception exception)
            when (exception is OperationCanceledException or WebSocketException or IOException or ObjectDisposedException)
        {
            return true;
        }
    }
    /// <summary>How a session ended, and what the client is told.</summary>
    private sealed record Ending(RelayCloseReason Reason, int Code, string Description);
    /// <summary>
    /// Byte counts and the time of the last byte, written by the two directions and read by the clock.
    /// </summary>
    private sealed class Counters(TimeProvider clock, DateTimeOffset started)
    {
        private long clientToTarget;
        private long targetToClient;
        private long lastActivityTicks = started.UtcTicks;
        internal long ClientToTarget => Interlocked.Read(ref clientToTarget);
        internal long TargetToClient => Interlocked.Read(ref targetToClient);
        internal DateTimeOffset LastActivity => new(Interlocked.Read(ref lastActivityTicks), TimeSpan.Zero);
        internal void AddClientToTarget(int count)
        {
            Interlocked.Add(ref clientToTarget, count);
            Interlocked.Exchange(ref lastActivityTicks, clock.GetUtcNow().UtcTicks);
        }
        internal void AddTargetToClient(int count)
        {
            Interlocked.Add(ref targetToClient, count);
            Interlocked.Exchange(ref lastActivityTicks, clock.GetUtcNow().UtcTicks);
        }
    }
 }
@@ -0,0 +1,104 @@
 using DodoSSH.Domain;
 namespace DodoSSH.Api.Features.Relay;
 /// <summary>Source-generated log messages for the relay.</summary>
 /// <remarks>
 /// <para>
 /// Ids, counts and reasons. Never a ticket, which is a bearer credential for thirty seconds, and never
 /// the target's address: that is in the audit table, where retention is the operator's decision, and
 /// copying it into a log would make it the log pipeline's decision too.
 /// </para>
 /// <para>
 /// <see cref="TargetRejected"/> is the one place the reason for a refused target is written down. The
 /// client is told nothing specific, deliberately — see <c>RelayTicketEndpoint</c> — so this line is how
 /// an operator answers "why will the relay not reach this host".
 /// </para>
 /// </remarks>
 internal static partial class RelayLog
 {
    [LoggerMessage(
        EventId = 2301,
        Level = LogLevel.Information,
        Message = "Relay ticket refused for user {UserId} and host {HostId}: {Reason}.")]
    internal static partial void TargetRejected(ILogger logger, Guid userId, Guid hostId, string reason);
    [LoggerMessage(
        EventId = 2302,
        Level = LogLevel.Debug,
        Message = "Relay ticket issued to user {UserId} for host {HostId}, session {SessionId}, with "
            + "{AddressCount} permitted address(es).")]
    internal static partial void TicketIssued(
        ILogger logger,
        Guid userId,
        Guid hostId,
        Guid sessionId,
        int addressCount);
    /// <remarks>
    /// The session id is known only for a ticket that verified and had already been spent, which is the
    /// case worth an operator's attention: a replay, or a client retrying a redemption it thinks failed.
    /// </remarks>
    [LoggerMessage(
        EventId = 2303,
        Level = LogLevel.Information,
        Message = "Relay ticket refused at the socket (session {SessionId}): forged, expired or already used.")]
    internal static partial void TicketRefused(ILogger logger, Guid? sessionId);
    [LoggerMessage(
        EventId = 2304,
        Level = LogLevel.Information,
        Message = "Relay session refused for user {UserId}: a session limit is met, with {SessionCount} "
            + "open on this node.")]
    internal static partial void LimitReached(ILogger logger, Guid userId, int sessionCount);
    [LoggerMessage(
        EventId = 2305,
        Level = LogLevel.Information,
        Message = "Relay session {SessionId} could not reach host {HostId} on any permitted address.")]
    internal static partial void TargetUnreachable(ILogger logger, Guid sessionId, Guid hostId);
    [LoggerMessage(
        EventId = 2306,
        Level = LogLevel.Debug,
        Message = "Relay session {SessionId} opened for user {UserId} to host {HostId}; {SessionCount} "
            + "open on this node.")]
    internal static partial void SessionOpened(
        ILogger logger,
        Guid sessionId,
        Guid userId,
        Guid hostId,
        int sessionCount);
    [LoggerMessage(
        EventId = 2307,
        Level = LogLevel.Debug,
        Message = "Relay session {SessionId} closed ({Reason}) after {ClientToTarget} byte(s) up and "
            + "{TargetToClient} down.")]
    internal static partial void SessionClosed(
        ILogger logger,
        Guid sessionId,
        RelayCloseReason reason,
        long clientToTarget,
        long targetToClient);
    /// <remarks>
    /// A warning rather than an error: the session itself is over and was fine. What is lost is the
    /// audit row's second half, which leaves it looking like a session still open.
    /// </remarks>
    [LoggerMessage(
        EventId = 2308,
        Level = LogLevel.Warning,
        Message = "Relay session {SessionId} ended but its audit record could not be closed.")]
    internal static partial void AuditCloseFailed(ILogger logger, Guid sessionId, Exception exception);
    /// <remarks>
    /// A warning: the sessions it was checking stay open, which is how they all behaved before the check
    /// existed, and each still ends at its idle timeout or its lifetime.
    /// </remarks>
    [LoggerMessage(
        EventId = 2309,
        Level = LogLevel.Warning,
        Message = "Re-checking relay access for user {UserId} after an access change failed.")]
    internal static partial void AccessRecheckFailed(ILogger logger, Guid userId, Exception exception);
 }
@@ -0,0 +1,61 @@
 using System.Net;
 using System.Net.Sockets;
 namespace DodoSSH.Api.Features.Relay;
 /// <summary>
 /// The two things the relay asks of the network: what a name resolves to, and a connection to an address.
 /// </summary>
 /// <remarks>
 /// <para>
 /// A seam for tests, and a narrow one on purpose. <see cref="RelayAddressPolicy"/> is not behind it:
 /// whatever this answers, the policy judges, and a test that replaces this still runs every address
 /// through the real rules. What a test cannot do without the seam is dial anything, because every
 /// address a test machine can reach on its own — loopback — is one the policy refuses outright.
 /// </para>
 /// </remarks>
 internal interface IRelayNetwork
 {
    /// <summary>Resolves a stored hostname, which may be an address literal.</summary>
    Task<IPAddress[]> ResolveAsync(string host, CancellationToken cancellationToken);
    /// <summary>Opens a TCP connection to one address.</summary>
    /// <returns>A stream that owns the connection.</returns>
    Task<Stream> ConnectAsync(IPAddress address, int port, CancellationToken cancellationToken);
 }
 /// <summary>The operating system's resolver and sockets.</summary>
 internal sealed class SystemRelayNetwork : IRelayNetwork
 {
    /// <inheritdoc />
    public Task<IPAddress[]> ResolveAsync(string host, CancellationToken cancellationToken) =>
        // A literal parses to itself without a lookup, which is what an address typed into a host
        // editor should do — and what makes "10.0.0.5" mean the same thing on every node.
        IPAddress.TryParse(host, out var literal)
            ? Task.FromResult<IPAddress[]>([literal])
            : Dns.GetHostAddressesAsync(host, cancellationToken);
    /// <inheritdoc />
    public async Task<Stream> ConnectAsync(IPAddress address, int port, CancellationToken cancellationToken)
    {
        var socket = new Socket(address.AddressFamily, SocketType.Stream, ProtocolType.Tcp)
        {
            // An interactive shell is a stream of keystrokes; Nagle would hold each one back for the
            // acknowledgement of the last, which is the latency the user feels as a sticky terminal.
            NoDelay = true,
        };
        try
        {
            await socket.ConnectAsync(new IPEndPoint(address, port), cancellationToken).ConfigureAwait(false);
            return new NetworkStream(socket, ownsSocket: true);
        }
        catch
        {
            socket.Dispose();
            throw;
        }
    }
 }
@@ -0,0 +1,150 @@
 using DodoSSH.Api.Setup;
 using Microsoft.Extensions.Options;
 namespace DodoSSH.Api.Features.Relay;
 /// <summary>
 /// Counts the relay sessions open on this node, and refuses the ones over ADR 0004's limits.
 /// </summary>
 /// <remarks>
 /// <para>
 /// Per node, and so per user <em>per node</em>: a user behind a round-robin balancer with three nodes
 /// could hold three times the per-user cap. That is accepted rather than fixed, because fixing it means
 /// shared state on the hot path of every connect, and the cap exists to stop one account exhausting a
 /// node — which a per-node count does exactly.
 /// </para>
 /// <para>
 /// A singleton, because a session outlives the request that opened it. It holds counts and nothing else;
 /// the sockets belong to the handlers that opened them.
 /// </para>
 /// </remarks>
 internal sealed class RelaySessionRegistry(IOptions<RelayOptions> options)
 {
    private readonly Lock gate = new();
    private readonly Dictionary<Guid, int> perUser = [];
    private readonly HashSet<Lease> open = [];
    private int total;
    /// <summary>How many sessions are open on this node.</summary>
    internal int Count
    {
        get
        {
            lock (gate)
            {
                return total;
            }
        }
    }
    /// <summary>Whether a session for this user would be admitted now.</summary>
    /// <remarks>
    /// Advisory, for the ticket endpoint: it lets a caller already at the cap hear so as an HTTP status
    /// before it has spent a ticket, but only <see cref="TryAdmit"/> decides, since the answer here can
    /// be stale by the time the socket arrives — possibly at another node.
    /// </remarks>
    internal bool HasRoomFor(Guid userId)
    {
        var settings = options.Value;
        lock (gate)
        {
            return total < settings.MaxConcurrentSessionsTotal
                && perUser.GetValueOrDefault(userId) < settings.MaxConcurrentSessionsPerUser;
        }
    }
    /// <summary>Admits a session, or answers null when a limit is met.</summary>
    /// <returns>A lease that gives the place back when disposed.</returns>
    /// <summary>The sessions a user has open now, for re-checking their access.</summary>
    internal IReadOnlyList<Lease> SessionsOf(Guid userId)
    {
        lock (gate)
        {
            return [.. open.Where(lease => lease.UserId == userId)];
        }
    }
    internal Lease? TryAdmit(Guid userId, Guid vaultId)
    {
        var settings = options.Value;
        lock (gate)
        {
            var held = perUser.GetValueOrDefault(userId);
            if (total >= settings.MaxConcurrentSessionsTotal || held >= settings.MaxConcurrentSessionsPerUser)
            {
                return null;
            }
            perUser[userId] = held + 1;
            total++;
            var lease = new Lease(this, userId, vaultId);
            open.Add(lease);
            return lease;
        }
    }
    private void Release(Lease lease, Guid userId)
    {
        lock (gate)
        {
            open.Remove(lease);
            total--;
            // Removed at zero rather than left behind, so the dictionary is the size of the users with a
            // session open and not of every user who ever had one.
            if (perUser[userId] <= 1)
            {
                perUser.Remove(userId);
            }
            else
            {
                perUser[userId]--;
            }
        }
    }
    /// <summary>One admitted session's place. Idempotent to dispose.</summary>
    internal sealed class Lease(RelaySessionRegistry registry, Guid userId, Guid vaultId) : IDisposable
    {
        private readonly CancellationTokenSource revoked = new();
        private int released;
        /// <summary>Whose session this is.</summary>
        internal Guid UserId { get; } = userId;
        /// <summary>The vault the ticket's host is filed in, which is what the session's access hangs on.</summary>
        internal Guid VaultId { get; } = vaultId;
        /// <summary>Cancelled when the session's user loses access to <see cref="VaultId"/>.</summary>
        internal CancellationToken Revoked => revoked.Token;
        /// <summary>Ends the session, because its user can no longer reach the vault it was opened for.</summary>
        internal void Revoke()
        {
            try
            {
                revoked.Cancel();
            }
            catch (ObjectDisposedException)
            {
                // Already over.
            }
        }
        /// <inheritdoc />
        public void Dispose()
        {
            if (Interlocked.Exchange(ref released, 1) == 0)
            {
                registry.Release(this, UserId);
                revoked.Dispose();
            }
        }
    }
 }
@@ -0,0 +1,171 @@
 using System.Net;
 using System.Security.Cryptography;
 using Microsoft.AspNetCore.DataProtection;
 using Microsoft.AspNetCore.WebUtilities;
 namespace DodoSSH.Api.Features.Relay;
 /// <summary>
 /// Everything the relay socket needs to know, decided by the ticket endpoint.
 /// </summary>
 /// <remarks>
 /// The addresses are the resolved ones and the socket dials nothing else. There is no hostname for it
 /// to resolve again — <see cref="TargetHost"/> is carried for the audit row only — which is what keeps a
 /// DNS answer that changes between issue and connect from changing where the bytes go.
 /// </remarks>
 /// <param name="TicketId">The replay guard's key.</param>
 /// <param name="SessionId">The audit row's id, already given to the client.</param>
 /// <param name="UserId">Who asked.</param>
 /// <param name="HostId">The host it is for.</param>
 /// <param name="VaultId">The host's vault at issue.</param>
 /// <param name="TargetHost">The hostname as stored, for the audit row.</param>
 /// <param name="TargetAddresses">The permitted addresses the name resolved to, in the order to try.</param>
 /// <param name="TargetPort">The port.</param>
 /// <param name="ExpiresAt">When the ticket stops verifying.</param>
 internal sealed record RelayTicket(
    Guid TicketId,
    Guid SessionId,
    Guid UserId,
    Guid HostId,
    Guid VaultId,
    string TargetHost,
    IReadOnlyList<IPAddress> TargetAddresses,
    int TargetPort,
    DateTimeOffset ExpiresAt);
 /// <summary>
 /// Seals and opens relay tickets.
 /// </summary>
 /// <remarks>
 /// <para>
 /// A Data Protection payload, per ADR 0004: authenticated and encrypted, with key rotation handled by
 /// the framework, and verifiable on any node that shares the key ring. Encrypted rather than merely
 /// signed because the ticket travels in a header every proxy on the way can read, and what it holds is
 /// the resolved address of a machine on the operator's network.
 /// </para>
 /// <para>
 /// The expiry is inside the payload and checked against <see cref="TimeProvider"/>, rather than left to
 /// the framework's time-limited protector, which reads the system clock directly — the thing this
 /// repository bans so that time can be faked in tests.
 /// </para>
 /// <para>
 /// The layout is a version byte and fixed fields, written by hand. Small enough that a serialiser would
 /// be the larger half of the code, and a hand layout has no reflection for trimming to break.
 /// </para>
 /// </remarks>
 internal sealed class RelayTicketCodec(IDataProtectionProvider protection, TimeProvider clock)
 {
    /// <summary>The purpose string, which isolates these payloads from every other protector's.</summary>
    private const string Purpose = "DodoSSH.Relay.Ticket";
    private const byte LayoutVersion = 1;
    /// <summary>More addresses than any real name resolves to, and a bound on what a ticket can carry.</summary>
    internal const int MaxAddresses = 16;
    private readonly IDataProtector protector = protection.CreateProtector(Purpose);
    internal string Seal(RelayTicket ticket)
    {
        ArgumentNullException.ThrowIfNull(ticket);
        using var buffer = new MemoryStream();
        using (var writer = new BinaryWriter(buffer))
        {
            writer.Write(LayoutVersion);
            writer.Write(ticket.TicketId.ToByteArray());
            writer.Write(ticket.SessionId.ToByteArray());
            writer.Write(ticket.UserId.ToByteArray());
            writer.Write(ticket.HostId.ToByteArray());
            writer.Write(ticket.VaultId.ToByteArray());
            writer.Write(ticket.ExpiresAt.ToUnixTimeMilliseconds());
            writer.Write(ticket.TargetPort);
            writer.Write(ticket.TargetHost);
            writer.Write((byte)ticket.TargetAddresses.Count);
            foreach (var address in ticket.TargetAddresses)
            {
                var bytes = address.GetAddressBytes();
                writer.Write((byte)bytes.Length);
                writer.Write(bytes);
            }
        }
        // Base64url, whose alphabet is all token characters, so it can stand in a subprotocol name.
        return WebEncoders.Base64UrlEncode(protector.Protect(buffer.ToArray()));
    }
    /// <summary>Opens a ticket, or answers null for one that is forged, damaged or expired.</summary>
    /// <remarks>
    /// One answer for all three, because the caller's remedy is the same — ask for another — and a
    /// distinct "expired" would tell a forger which of their attempts had verified.
    /// </remarks>
    internal RelayTicket? TryOpen(string sealedTicket)
    {
        byte[] payload;
        try
        {
            payload = protector.Unprotect(WebEncoders.Base64UrlDecode(sealedTicket));
        }
        catch (Exception exception) when (exception is CryptographicException or FormatException)
        {
            return null;
        }
        RelayTicket ticket;
        try
        {
            ticket = Read(payload);
        }
        catch (Exception exception)
            when (exception is EndOfStreamException or ArgumentException or FormatException)
        {
            return null;
        }
        return ticket.ExpiresAt > clock.GetUtcNow() ? ticket : null;
    }
    private static RelayTicket Read(byte[] payload)
    {
        using var reader = new BinaryReader(new MemoryStream(payload));
        if (reader.ReadByte() != LayoutVersion)
        {
            throw new FormatException("Unknown ticket layout.");
        }
        var ticketId = new Guid(reader.ReadBytes(16));
        var sessionId = new Guid(reader.ReadBytes(16));
        var userId = new Guid(reader.ReadBytes(16));
        var hostId = new Guid(reader.ReadBytes(16));
        var vaultId = new Guid(reader.ReadBytes(16));
        var expiresAt = DateTimeOffset.FromUnixTimeMilliseconds(reader.ReadInt64());
        var port = reader.ReadInt32();
        var host = reader.ReadString();
        var count = reader.ReadByte();
        if (count is 0 or > MaxAddresses)
        {
            throw new FormatException("A ticket names between one and sixteen addresses.");
        }
        var addresses = new IPAddress[count];
        for (var index = 0; index < count; index++)
        {
            var length = reader.ReadByte();
            if (length is not (4 or 16))
            {
                throw new FormatException("An address is four or sixteen bytes.");
            }
            addresses[index] = new IPAddress(reader.ReadBytes(length));
        }
        return new RelayTicket(ticketId, sessionId, userId, hostId, vaultId, host, addresses, port, expiresAt);
    }
 }
@@ -0,0 +1,231 @@
 using System.Net;
 using System.Net.Sockets;
 using DodoSSH.Api.Authorization;
 using DodoSSH.Api.Setup;
 using DodoSSH.Contracts;
 using DodoSSH.Domain.Authorization;
 using DodoSSH.Infrastructure;
 using FastEndpoints;
 using Microsoft.AspNetCore.Http.HttpResults;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Options;
 namespace DodoSSH.Api.Features.Relay;
 /// <summary>
 /// Issues the ticket that lets exactly one relay socket reach exactly one host.
 /// </summary>
 /// <remarks>
 /// <para>
 /// Every decision the relay makes is made here, with the full bearer token and the full access model in
 /// hand: which host, whether the caller may connect to it, which addresses its name resolves to and
 /// which of those the policy permits. The socket that follows decides nothing. It checks that the ticket
 /// is genuine, fresh and unused, and dials what the ticket says. See ADR 0004.
 /// </para>
 /// <para>
 /// <b>Every refusal about the target is the same refusal.</b> A host that does not exist, one in a vault
 /// the caller cannot reach, one without the relay switched on, one whose name does not resolve, and one
 /// whose every address the policy refuses all answer 403 <c>relay-target-rejected</c> with the same
 /// sentence. Anyone who can write a host can set its address to anything, so a distinct answer for
 /// "resolves, but refused" would turn this endpoint into a scanner for the operator's internal DNS. The
 /// real reason goes to the server log, where the operator can read it.
 /// </para>
 /// </remarks>
 internal sealed class RelayTicketEndpoint(
    ICurrentUserContext currentUser,
    IVaultAccessService vaultAccess,
    DodoDbContext database,
    IRelayNetwork network,
    RelayTicketCodec codec,
    RelaySessionRegistry sessions,
    IOptions<RelayOptions> options,
    TimeProvider clock,
    ILogger<RelayTicketEndpoint> logger)
    : Endpoint<RelayTicketRequest, Results<Ok<RelayTicketResponse>, ProblemHttpResult>>
 {
    /// <summary>What every target refusal says, whatever the reason was.</summary>
    private const string RejectedDetail =
        "The relay will not connect to this host. Check that the relay is switched on for it and that its "
        + "address is one this server may reach; the server's log records which.";
    /// <inheritdoc />
    public override void Configure()
    {
        Post(RelayProtocol.TicketsPath);
        // Enrolled, matching sync. A relayed host is still a host whose name, username and key are
        // ciphertext, so a caller with no identity key has no way to have learned which host to ask for.
        Policies(Auth.EnrolledPolicy);
        Description(b => b
            .WithName("IssueRelayTicket")
            .WithSummary("Issues a single-use ticket for one relay connection to one host.")
            .WithTags("Relay"));
    }
    /// <inheritdoc />
    public override async Task<Results<Ok<RelayTicketResponse>, ProblemHttpResult>> ExecuteAsync(
        RelayTicketRequest req,
        CancellationToken ct)
    {
        var settings = options.Value;
        if (!settings.Enabled)
        {
            return Problems.Coded(
                StatusCodes.Status404NotFound,
                ProblemCodes.RelayUnavailable,
                "This server does not relay. Connect to the host directly; GET /api/v1/meta lists the "
                + "features this server does offer.");
        }
        var user = await currentUser.GetOrProvisionAsync(ct).ConfigureAwait(false);
        var (target, refusal) = await FindTargetAsync(user.Id, req, ct).ConfigureAwait(false);
        if (target is not var (hostname, port, vaultId))
        {
            return Rejected(user.Id, req.HostId, refusal!);
        }
        // Before resolving rather than after: a caller already at the cap is told so without this server
        // spending a DNS query on a ticket that could not be redeemed.
        if (!sessions.HasRoomFor(user.Id))
        {
            RelayLog.LimitReached(logger, user.Id, sessions.Count);
            return Problems.Coded(
                StatusCodes.Status429TooManyRequests,
                ProblemCodes.RelayLimitReached,
                "You have as many relay sessions open as this server allows. Close one and try again.");
        }
        var addresses = await ResolvePermittedAsync(hostname, ct).ConfigureAwait(false);
        if (addresses is not { Length: > 0 })
        {
            return Rejected(user.Id, req.HostId, addresses is null
                ? "its name did not resolve"
                : "every address its name resolved to is refused by policy");
        }
        var ticket = new RelayTicket(
            TicketId: Guid.CreateVersion7(),
            SessionId: Guid.CreateVersion7(),
            UserId: user.Id,
            HostId: req.HostId,
            VaultId: vaultId,
            TargetHost: hostname,
            TargetAddresses: addresses,
            TargetPort: port,
            ExpiresAt: clock.GetUtcNow() + settings.TicketLifetime);
        RelayLog.TicketIssued(logger, user.Id, req.HostId, ticket.SessionId, addresses.Length);
        return TypedResults.Ok(new RelayTicketResponse(
            Ticket: codec.Seal(ticket),
            WebSocketUrl: new Uri(settings.WebSocketUrl!, UriKind.Absolute),
            SubProtocol: RelayProtocol.SubProtocol,
            SessionId: ticket.SessionId,
            ExpiresAt: ticket.ExpiresAt));
    }
    /// <summary>
    /// Finds the host, and decides whether this caller may be relayed to it at all.
    /// </summary>
    /// <returns>The stored target, or the reason there is none — for the log, never for the caller.</returns>
    private async Task<((string Hostname, int Port, Guid VaultId)? Target, string? Refusal)> FindTargetAsync(
        Guid userId,
        RelayTicketRequest req,
        CancellationToken cancellationToken)
    {
        if (req.PortForwardId is not null)
        {
            return (null, "a port forward was requested, which v1 does not relay");
        }
        var host = await database.Hosts
            .AsNoTracking()
            .SingleOrDefaultAsync(h => h.Id == req.HostId && h.DeletedAtUtc == null, cancellationToken)
            .ConfigureAwait(false);
        if (host is null)
        {
            return (null, "no such host");
        }
        var access = await vaultAccess.ResolveAsync(userId, host.VaultId, cancellationToken).ConfigureAwait(false);
        // Connect rather than Read, because Connect is the permission that says what this is. Every role
        // that reads today also connects — see VaultAccessService.ForRole — but a role that ever split
        // them should be refused a relay here without anybody remembering to look.
        if (!access.Granted || !access.Permissions.HasFlag(PermissionFlags.Connect))
        {
            return (null, "the caller may not connect to this host's vault");
        }
        // The CHECK constraint makes the second half unreachable while the first is true. Tested anyway,
        // because the cost of trusting it is dialling a null.
        if (!host.RelayEnabled || host.Hostname is not { } hostname || host.Port is not { } port)
        {
            return (null, "the relay is not switched on for this host");
        }
        return RelayAddressPolicy.PermitsPort(port)
            ? ((hostname, port, host.VaultId), null)
            : (null, $"port {port} is refused by policy");
    }
    /// <summary>
    /// Resolves the stored name, and keeps the addresses the policy permits.
    /// </summary>
    /// <returns>The permitted addresses, possibly none; or null when the name did not resolve.</returns>
    /// <remarks>
    /// <para>
    /// Filtered rather than refused as a whole when one answer is bad. A name that resolves to a public
    /// address and a link-local one is dialled on the public address, and never on the other — the
    /// ticket carries only what passed, so there is nothing else for the socket to try.
    /// </para>
    /// <para>
    /// The addresses kept are the normalised ones, so what is dialled is exactly what was judged rather
    /// than a second spelling of it.
    /// </para>
    /// </remarks>
    private async Task<IPAddress[]?> ResolvePermittedAsync(string hostname, CancellationToken cancellationToken)
    {
        var policy = new RelayAddressPolicy(options.Value);
        using var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        timeout.CancelAfter(options.Value.ConnectTimeout);
        IPAddress[] resolved;
        try
        {
            resolved = await network.ResolveAsync(hostname, timeout.Token).ConfigureAwait(false);
        }
        catch (SocketException)
        {
            return null;
        }
        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
        {
            return null;
        }
        return
        [
            .. resolved
                .Where(policy.Permits)
                .Select(RelayAddressPolicy.Normalise)
                .Distinct()
                .Take(RelayTicketCodec.MaxAddresses),
        ];
    }
    private ProblemHttpResult Rejected(Guid userId, Guid hostId, string reason)
    {
        RelayLog.TargetRejected(logger, userId, hostId, reason);
        return Problems.Coded(StatusCodes.Status403Forbidden, ProblemCodes.RelayTargetRejected, RejectedDetail);
    }
 }
@@ -73,6 +73,7 @@ internal static class ItemKinds
            (IItemKind)new HostKind(), new SshKeyKind(), new CredentialKind(), new KnownHostKeyKind(),
            new HostGroupKind(), new TagKind(), new SnippetKind(),
            new ConnectionLogEntryKind(), new ActivityLogEntryKind(), new ObjectStoreKind(),
            new SpelunkKeyKind(),
        }.ToDictionary(kind => kind.WireType);
    /// <summary>The kind for a wire type, or null when this server does not synchronise it yet.</summary>
@@ -1093,3 +1094,98 @@ internal sealed class ObjectStoreKind : IItemKind
    /// <inheritdoc />
    public SyncPlaintextFields? Hydrate(IVaultItem item) => null;
 }
 /// <summary>Spelunk keys: an envelope and nothing else.</summary>
 /// <remarks>
 /// <see cref="ObjectStoreKind"/>'s rules, because it holds the same class of thing: an API key is a password,
 /// and the address beside it is where somebody manages their servers. Nothing on the server calls Spelunk.
 /// </remarks>
 internal sealed class SpelunkKeyKind : IItemKind
 {
    /// <inheritdoc />
    public SyncEntityType WireType => SyncEntityType.SpelunkKey;
    /// <inheritdoc />
    public ChangeEntityType ChangeType => ChangeEntityType.SpelunkKey;
    /// <inheritdoc />
    public async Task<IVaultItem?> FindAsync(
        DodoDbContext database,
        Guid id,
        CancellationToken cancellationToken) =>
        await database.SpelunkKeys.SingleOrDefaultAsync(s => s.Id == id, cancellationToken)
            .ConfigureAwait(false);
    /// <inheritdoc />
    public async Task<Dictionary<Guid, IVaultItem>> LoadAsync(
        DodoDbContext database,
        Guid vaultId,
        Guid[] ids,
        CancellationToken cancellationToken)
    {
        var rows = await database.SpelunkKeys
            .Where(s => s.VaultId == vaultId && ids.Contains(s.Id))
            .ToListAsync(cancellationToken)
            .ConfigureAwait(false);
        return rows.ToDictionary(row => row.Id, row => (IVaultItem)row);
    }
    /// <inheritdoc />
    public IVaultItem Add(DodoDbContext database, Guid id, Guid vaultId)
    {
        var key = new VaultSpelunkKey { Id = id, VaultId = vaultId };
        database.SpelunkKeys.Add(key);
        return key;
    }
    /// <summary>Refuses every plaintext field there is.</summary>
    /// <remarks>
    /// The relay fields are refused although this type holds an address, as they are for a bucket: the
    /// address belongs in the ciphertext, and the server has no business keeping a list of where its users
    /// manage their servers from.
    /// </remarks>
    /// <inheritdoc />
    public bool ValidateFields(SyncPlaintextFields fields, out string error)
    {
        ArgumentNullException.ThrowIfNull(fields);
        error = string.Empty;
        if (fields.RelayEnabled || fields.Hostname is not null || fields.Port is not null)
        {
            error = "A Spelunk key is not something the server dials; its address stays encrypted.";
            return false;
        }
        if (fields.GroupId is not null || fields.ParentId is not null || fields.RelatedId is not null)
        {
            error = "A Spelunk key's contents are inside its payload.";
            return false;
        }
        if (fields.Kind is not null || fields.PublicKeyFingerprint is not null)
        {
            error = "A Spelunk key carries no plaintext fields at all.";
            return false;
        }
        return true;
    }
    /// <remarks>Nothing to copy: this type has no plaintext columns to copy anything into.</remarks>
    /// <inheritdoc />
    public void ApplyFields(IVaultItem item, SyncPlaintextFields fields)
    {
    }
    /// <inheritdoc />
    public void ClearFieldsOnDelete(IVaultItem item)
    {
    }
    /// <inheritdoc />
    public SyncPlaintextFields? Hydrate(IVaultItem item) => null;
 }
@@ -27,4 +27,16 @@ internal static partial class SyncLog
        int appliedCount,
        int operationCount,
        Guid vaultId);
    [LoggerMessage(
        EventId = 2003,
        Level = LogLevel.Information,
        Message = "Collected {Count} expired tombstone(s) and superseded change-log entries.")]
    internal static partial void Collected(ILogger logger, int count);
    [LoggerMessage(
        EventId = 2004,
        Level = LogLevel.Warning,
        Message = "Tombstone collection failed; it will run again at the next interval.")]
    internal static partial void CollectionFailed(ILogger logger, Exception exception);
 }
@@ -26,12 +26,59 @@ internal sealed class SyncService(
        CancellationToken cancellationToken)
    {
        var afterSequence = 0L;
        var issuedUnder = 0L;
        if (!string.IsNullOrEmpty(request.Cursor)
-            && !SyncCursor.TryDecode(cursorKeys.Key, request.Cursor, vault.Id, out afterSequence))
+            && !SyncCursor.TryDecode(cursorKeys.Key, request.Cursor, vault.Id, out afterSequence, out issuedUnder))
        {
            throw new InvalidCursorException();
        }
        // Read before the changes, for the cursor this read hands out; see the check after it.
        var horizonBefore = await HorizonAsync(vault.Id, cancellationToken).ConfigureAwait(false);
        var (changes, hasMore) = await ReadPageAsync(vault.Id, afterSequence, request, cancellationToken)
            .ConfigureAwait(false);
        // ◆ After the read, not before it. The collector deletes a tombstone's entries and raises the horizon
        // in one transaction, so a read that already missed an entry is followed by a horizon that says so;
        // checked first, the two could straddle a collection and the deletion would go unnoticed for good.
        //
        // A cursor behind the horizon is refused only if it was issued before it. One issued since belongs to
        // a read from the beginning that started after the collection, and its early pages are behind the
        // horizon because old, untouched items are; refusing those would send that read back to the start
        // for ever. See SyncCursor.
        var horizon = await HorizonAsync(vault.Id, cancellationToken).ConfigureAwait(false);
        if (afterSequence > 0 && afterSequence < horizon && issuedUnder < horizon)
        {
            throw new InvalidCursorException();
        }
        var hydrated = await HydrateAsync(vault, changes, cancellationToken).ConfigureAwait(false);
        // When nothing came back the cursor must not move, or a concurrent write landing between
        // this read and the next would be skipped forever.
        var nextSequence = changes.Count > 0 ? changes[^1].Sequence : afterSequence;
        return new SyncPullResponse(
            Changes: hydrated,
            // The horizon from before the read, never the one after: a collection landing between the two
            // could have taken an entry this page would otherwise have carried, and a cursor claiming the
            // later horizon would vouch for a client that never heard of it. The earlier one costs at most
            // a restart.
            NextCursor: SyncCursor.Encode(cursorKeys.Key, vault.Id, nextSequence, horizonBefore),
            HasMore: hasMore,
            ServerTime: clock.GetUtcNow(),
            CurrentKeyGeneration: (uint)vault.KeyGeneration);
    }
    /// <summary>The changes after a position, one page of them, and whether there are more.</summary>
    private async Task<(List<VaultChange> Changes, bool HasMore)> ReadPageAsync(
        Guid vaultId,
        long afterSequence,
        SyncPullRequest request,
        CancellationToken cancellationToken)
    {
        var limit = Math.Clamp(
            request.Limit ?? options.DefaultPullLimit,
            1,
@@ -43,7 +90,7 @@ internal sealed class SyncService(
        // One extra row, so "is there more" needs no second query.
        var query = database.VaultChanges
-            .Where(c => c.VaultId == vault.Id && c.Sequence > afterSequence);
+            .Where(c => c.VaultId == vaultId && c.Sequence > afterSequence);
        if (types is not null)
        {
@@ -62,18 +109,7 @@ internal sealed class SyncService(
            changes.RemoveAt(changes.Count - 1);
        }
-        var hydrated = await HydrateAsync(vault, changes, cancellationToken).ConfigureAwait(false);
+        return (changes, hasMore);
        // When nothing came back the cursor must not move, or a concurrent write landing between
        // this read and the next would be skipped forever.
        var nextSequence = changes.Count > 0 ? changes[^1].Sequence : afterSequence;
        return new SyncPullResponse(
            Changes: hydrated,
            NextCursor: SyncCursor.Encode(cursorKeys.Key, vault.Id, nextSequence),
            HasMore: hasMore,
            ServerTime: clock.GetUtcNow(),
            CurrentKeyGeneration: (uint)vault.KeyGeneration);
    }
    /// <summary>
@@ -100,9 +136,7 @@ internal sealed class SyncService(
    {
        ValidateBatchLimits(request);
-        var strategy = database.Database.CreateExecutionStrategy();
+        return await database.ExecuteFreshAsync([vault], async () =>
        return await strategy.ExecuteAsync(async () =>
        {
            var transaction = await database.Database
                .BeginTransactionAsync(cancellationToken)
@@ -536,9 +570,21 @@ internal sealed class SyncService(
    /// <summary>Attaches current row state to change-log entries.</summary>
    /// <remarks>
    /// <para>
    /// A page of changes can mix item types, so rows are loaded per type — one query each, not one per
    /// change — and then matched back in the log's order. Ordering is the log's, never the load's: a pull
    /// that returned changes grouped by type would hand the client a sequence its cursor cannot resume from.
    /// </para>
    /// <para>
    /// ◆ <b>An entry an item has since moved past is left out.</b> The log keeps every revision, but the
    /// table keeps only the latest ciphertext — so hydrating an old entry paired that entry's revision number
    /// with the newest payload, and the payload's AAD binds the revision it was sealed at. A client opened it
    /// at the old number, failed, and parked its own unsent edit to that item as undecryptable. The later
    /// entry is in this page or a later one, since the item's <c>ChangeSequence</c> is that entry's sequence;
    /// it carries the same payload under the right number, so nothing is lost by sending it once. Leaving
    /// the old entries out also stops a fresh device downloading an item once per edit it ever had. The
    /// cursor is computed from the unfiltered page by the caller, so it still moves past them.
    /// </para>
    /// </remarks>
    private async Task<List<Contracts.SyncChange>> HydrateAsync(
        Vault vault,
@@ -571,10 +617,13 @@ internal sealed class SyncService(
            }
        }
-        return [.. changes.Select(change => Describe(
+        return [.. changes
-            change,
+            .Where(change => rows.GetValueOrDefault((change.EntityType, change.EntityId)) is not { } row
-            kinds.GetValueOrDefault(change.EntityType),
+                || row.ChangeSequence <= change.Sequence)
-            rows.GetValueOrDefault((change.EntityType, change.EntityId))))];
+            .Select(change => Describe(
                change,
                kinds.GetValueOrDefault(change.EntityType),
                rows.GetValueOrDefault((change.EntityType, change.EntityId))))];
    }
    /// <summary>Turns one change-log entry and its row into what a client receives.</summary>
@@ -609,14 +658,30 @@ internal sealed class SyncService(
    /// <summary>The kind behind a change-log entry, or null for a type this server does not synchronise.</summary>
    private static IItemKind? KindForChange(ChangeEntityType type) => ItemKinds.For(ToWire(type));
-    private async Task<long> CurrentHeadAsync(Guid vaultId, CancellationToken cancellationToken) =>
+    /// <remarks>
-        await database.VaultChanges
+    /// Never below the vault's horizon: collecting a tombstone can take the newest entries with it, and a
    /// head reported lower than a cursor the client already holds would rewind it under the horizon and
    /// cost a full resync for nothing.
    /// </remarks>
    private async Task<long> CurrentHeadAsync(Guid vaultId, CancellationToken cancellationToken)
    {
        var head = await database.VaultChanges
            .Where(c => c.VaultId == vaultId)
            .OrderByDescending(c => c.Sequence)
            .Select(c => c.Sequence)
            .FirstOrDefaultAsync(cancellationToken)
            .ConfigureAwait(false);
        return Math.Max(head, await HorizonAsync(vaultId, cancellationToken).ConfigureAwait(false));
    }
    /// <summary>The vault's horizon as the database holds it now, not as the request loaded it.</summary>
    private Task<long> HorizonAsync(Guid vaultId, CancellationToken cancellationToken) =>
        database.Vaults
            .Where(v => v.Id == vaultId)
            .Select(v => v.SyncHorizon)
            .SingleAsync(cancellationToken);
    private static SyncPushResult Invalid(SyncPushOperation operation, string detail) =>
        new(
            operation.OperationId,
@@ -0,0 +1,198 @@
 using DodoSSH.Api.Setup;
 using DodoSSH.Domain;
 using DodoSSH.Infrastructure;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Options;
 namespace DodoSSH.Api.Features.Sync;
 /// <summary>
 /// Removes tombstones past their retention, and change-log entries a later one has superseded.
 /// </summary>
 /// <remarks>
 /// <para>
 /// ADR 0003 promised this and nothing did it: every deletion stayed a row for ever, and every edit stayed a
 /// change-log entry for ever, so the log grew without bound and a client starting from nothing walked every
 /// edit ever made to read the items that exist.
 /// </para>
 /// <para>
 /// <b>Superseded entries go at any time.</b> A pull returns entries after a cursor in order, so a client
 /// before both an item's old entry and its new one reads the new one, and a client between them already has
 /// the old one. Nothing reads history: a conflict resolves against the newest entry alone.
 /// </para>
 /// <para>
 /// <b>Tombstones go after the retention</b>, and taking them is the one change here a client can notice: a
 /// machine that last synced before the deletion would never hear of it. So each vault records the highest
 /// sequence collected from it — <see cref="Vault.SyncHorizon"/> — and a pull from a cursor below that is
 /// refused. The client answers by starting over, and a pull from nothing removes what the server no longer
 /// has; see the client's <c>SyncEngine</c>.
 /// </para>
 /// <para>
 /// Per vault under the same advisory lock a push takes, so a collection never interleaves with a write to
 /// the vault — and the items are read again under it, so one restored since it was found is left alone.
 /// </para>
 /// </remarks>
 internal sealed class TombstoneCollector(
    DodoDbContext database,
    IOptions<SyncOptions> syncOptions,
    TimeProvider clock,
    ILogger<TombstoneCollector> logger)
 {
    /// <summary>Collects what is due, once.</summary>
    /// <returns>How many tombstones and superseded entries went.</returns>
    internal async Task<int> RunOnceAsync(CancellationToken cancellationToken)
    {
        var before = clock.GetUtcNow() - TimeSpan.FromDays(syncOptions.Value.TombstoneRetentionDays);
        var collected = 0;
        collected += await CollectAsync(db => db.Hosts, ChangeEntityType.SshHost, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.SshKeys, ChangeEntityType.SshKey, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.Credentials, ChangeEntityType.Credential, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.KnownHostKeys, ChangeEntityType.KnownHostKey, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.HostGroups, ChangeEntityType.HostGroup, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.Tags, ChangeEntityType.Tag, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.Snippets, ChangeEntityType.Snippet, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.ConnectionLog, ChangeEntityType.ConnectionLogEntry, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.ActivityLog, ChangeEntityType.ActivityLogEntry, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.ObjectStores, ChangeEntityType.ObjectStore, before, cancellationToken).ConfigureAwait(false);
        collected += await CollectAsync(db => db.SpelunkKeys, ChangeEntityType.SpelunkKey, before, cancellationToken).ConfigureAwait(false);
        collected += await CompactAsync(cancellationToken).ConfigureAwait(false);
        SyncLog.Collected(logger, collected);
        return collected;
    }
    private async Task<int> CollectAsync<T>(
        Func<DodoDbContext, DbSet<T>> table,
        ChangeEntityType type,
        DateTimeOffset before,
        CancellationToken cancellationToken)
        where T : class, IVaultItem
    {
        var due = await table(database)
            .Where(item => item.DeletedAtUtc != null && item.DeletedAtUtc < before)
            .Select(item => new { item.VaultId, item.Id })
            .ToListAsync(cancellationToken)
            .ConfigureAwait(false);
        var collected = 0;
        foreach (var vault in due.GroupBy(item => item.VaultId))
        {
            var ids = vault.Select(item => item.Id).ToArray();
            collected += await database.ExecuteFreshAsync(
                [],
                () => CollectFromVaultAsync(table, type, vault.Key, ids, before, cancellationToken))
                .ConfigureAwait(false);
        }
        return collected;
    }
    private async Task<int> CollectFromVaultAsync<T>(
        Func<DodoDbContext, DbSet<T>> table,
        ChangeEntityType type,
        Guid vaultId,
        Guid[] ids,
        DateTimeOffset before,
        CancellationToken cancellationToken)
        where T : class, IVaultItem
    {
        var transaction = await database.Database.BeginTransactionAsync(cancellationToken).ConfigureAwait(false);
        await using var _ = transaction.ConfigureAwait(false);
        await database.Database
            .ExecuteSqlAsync($"SELECT pg_advisory_xact_lock(hashtextextended({vaultId.ToString()}, 0))", cancellationToken)
            .ConfigureAwait(false);
        // Read again under the lock: an item restored since it was found is no longer due.
        var still = await table(database)
            .Where(item => item.VaultId == vaultId
                && ids.Contains(item.Id)
                && item.DeletedAtUtc != null
                && item.DeletedAtUtc < before)
            .Select(item => new { item.Id, item.ChangeSequence })
            .ToListAsync(cancellationToken)
            .ConfigureAwait(false);
        if (still.Count == 0)
        {
            return 0;
        }
        var going = still.Select(item => item.Id).ToArray();
        var horizon = still.Max(item => item.ChangeSequence);
        await table(database)
            .Where(item => item.VaultId == vaultId && going.Contains(item.Id))
            .ExecuteDeleteAsync(cancellationToken)
            .ConfigureAwait(false);
        await database.VaultChanges
            .Where(change => change.VaultId == vaultId && change.EntityType == type && going.Contains(change.EntityId))
            .ExecuteDeleteAsync(cancellationToken)
            .ConfigureAwait(false);
        await database.Vaults
            .Where(v => v.Id == vaultId && v.SyncHorizon < horizon)
            .ExecuteUpdateAsync(set => set.SetProperty(v => v.SyncHorizon, horizon), cancellationToken)
            .ConfigureAwait(false);
        await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
        return still.Count;
    }
    /// <summary>Removes every change-log entry a later entry for the same item has superseded.</summary>
    private Task<int> CompactAsync(CancellationToken cancellationToken) =>
        database.Database.ExecuteSqlRawAsync(
            "DELETE FROM " + DodoDbContext.SchemaName + ".sync_change AS older "
            + "USING " + DodoDbContext.SchemaName + ".sync_change AS newer "
            + "WHERE newer.vault_id = older.vault_id "
            + "AND newer.entity_type = older.entity_type "
            + "AND newer.entity_id = older.entity_id "
            + "AND newer.sequence > older.sequence",
            cancellationToken);
 }
 /// <summary>Runs the <see cref="TombstoneCollector"/> on a schedule, in a scope of its own each time.</summary>
 internal sealed class TombstoneCollectionService(
    IServiceScopeFactory scopes,
    IOptions<SyncOptions> syncOptions,
    TimeProvider clock,
    ILogger<TombstoneCollectionService> logger) : BackgroundService
 {
    /// <inheritdoc />
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var interval = TimeSpan.FromMinutes(syncOptions.Value.TombstoneCollectionIntervalMinutes);
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await Task.Delay(interval, clock, stoppingToken).ConfigureAwait(false);
                var scope = scopes.CreateAsyncScope();
                await using var _ = scope.ConfigureAwait(false);
                await scope.ServiceProvider.GetRequiredService<TombstoneCollector>()
                    .RunOnceAsync(stoppingToken)
                    .ConfigureAwait(false);
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                return;
            }
            catch (Exception exception) when (exception is not OutOfMemoryException)
            {
                // The next run tries again; nothing collected late is harmed by waiting.
                SyncLog.CollectionFailed(logger, exception);
            }
        }
    }
 }
@@ -179,8 +179,8 @@ internal sealed class ArchiveTeamEndpoint(ICurrentUserContext currentUser, TeamS
        }
        // Owner, not admin. An admin the owner promoted must not be able to archive the team out
-        // from under them — that is the boundary IsOwner exists to draw. Nothing behind this
+        // from under them — that is the boundary IsOwner exists to draw. TeamService.ArchiveAsync
-        // re-checks it, unlike the transfer below, so this line is the whole of the guard.
+        // checks it again, because deleting a team's last vault archives it too.
        if (!access.IsOwner)
        {
            return Problems.Coded(
@@ -0,0 +1,27 @@
 using DodoSSH.Infrastructure;
 using Microsoft.EntityFrameworkCore;
 namespace DodoSSH.Api.Features.Teams;
 /// <summary>
 /// Serialises the writes that decide what a team owns, for the life of the transaction.
 /// </summary>
 /// <remarks>
 /// <para>
 /// Archiving a team refuses while it owns a vault, and creating a vault refuses on an archived team — but each
 /// used to check outside any transaction the other could see, so the two could pass each other: the archive
 /// counted no vaults, a create landed a moment later, and the team was archived with a live vault in it that
 /// nobody could reach. Both now take this lock inside their transaction and check again under it.
 /// </para>
 /// <para>
 /// The same advisory lock the sync push takes per vault, keyed apart so a team and a vault never share one.
 /// Requires <c>Multiplexing=false</c> on the connection, as that one does.
 /// </para>
 /// </remarks>
 internal static class TeamLock
 {
    internal static Task<int> AcquireAsync(DodoDbContext database, Guid teamId, CancellationToken cancellationToken) =>
        database.Database.ExecuteSqlAsync(
            $"SELECT pg_advisory_xact_lock(hashtextextended({"team:" + teamId.ToString()}, 0))",
            cancellationToken);
 }
@@ -1,5 +1,6 @@
 using System.Globalization;
 using DodoSSH.Api.Features.Events;
 using DodoSSH.Api.Setup;
 using DodoSSH.Contracts;
 using DodoSSH.Domain;
 using DodoSSH.Infrastructure;
@@ -244,28 +245,37 @@ internal sealed class TeamService(
        Team team,
        CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(actor);
        ArgumentNullException.ThrowIfNull(team);
-        var vaultCount = await CountVaultsAsync(team.Id, cancellationToken).ConfigureAwait(false);
+        // Both callers check this first and answer the caller properly; this is what stops a third one that
-
+        // forgets from letting an admin archive the team out from under its owner.
-        if (vaultCount > 0)
+        if (!(await ResolveAsync(actor.Id, team.Id, cancellationToken).ConfigureAwait(false)).IsOwner)
        {
-            throw new TeamNotEmptyException(
+            throw new InvalidOperationException("Only the owner of a team can archive it.");
                string.Create(
                    CultureInfo.InvariantCulture,
                    $"This team still owns {vaultCount} vault(s), and archiving it would take them away from everybody holding a key — including you. Delete those vaults first, which asks about each one and withdraws every key to it."));
        }
        var now = clock.GetUtcNow();
-        var strategy = database.Database.CreateExecutionStrategy();
+        var archived = await database.ExecuteFreshAsync([team], async () =>
        var archived = await strategy.ExecuteAsync(async () =>
        {
            var transaction = await database.Database
                .BeginTransactionAsync(cancellationToken)
                .ConfigureAwait(false);
            await using var _ = transaction.ConfigureAwait(false);
            // Counted under the lock a vault create takes, so one cannot land between this and the archive.
            await TeamLock.AcquireAsync(database, team.Id, cancellationToken).ConfigureAwait(false);
            var vaultCount = await CountVaultsAsync(team.Id, cancellationToken).ConfigureAwait(false);
            if (vaultCount > 0)
            {
                throw new TeamNotEmptyException(
                    string.Create(
                        CultureInfo.InvariantCulture,
                        $"This team still owns {vaultCount} vault(s), and archiving it would take them away from everybody holding a key — including you. Delete those vaults first, which asks about each one and withdraws every key to it."));
            }
            var memberships = await database.TeamMemberships
                .Where(m => m.TeamId == team.Id && m.DeletedAtUtc == null)
                .ToListAsync(cancellationToken)
@@ -335,9 +345,7 @@ internal sealed class TeamService(
        var incoming = await RequireMembershipAsync(teamId, request.UserId, cancellationToken)
            .ConfigureAwait(false);
-        var strategy = database.Database.CreateExecutionStrategy();
+        await database.ExecuteFreshAsync([incoming, outgoing], async () =>
        await strategy.ExecuteAsync(async () =>
        {
            var transaction = await database.Database
                .BeginTransactionAsync(cancellationToken)
@@ -716,9 +724,7 @@ internal sealed class TeamService(
        }
        var now = clock.GetUtcNow();
-        var strategy = database.Database.CreateExecutionStrategy();
+        var revoked = await database.ExecuteFreshAsync([membership], async () =>
        var revoked = await strategy.ExecuteAsync(async () =>
        {
            var transaction = await database.Database
                .BeginTransactionAsync(cancellationToken)
@@ -191,7 +191,12 @@ internal sealed class DeleteVaultEndpoint(
        {
            var orphaned = await grants.DeleteVaultAsync(user, access.Vault!, ct).ConfigureAwait(false);
-            if (orphaned is not null)
+            // Archived only by its owner. Archiving revokes every membership, the owner's included, and an
            // admin the owner promoted must not be able to do that by deleting vaults one at a time when the
            // archive endpoint refuses them outright. An admin's delete stands; the empty team is left for
            // the owner, who can archive it or make a vault in it.
            if (orphaned is not null
                && (await teams.ResolveAsync(user.Id, orphaned.Id, ct).ConfigureAwait(false)).IsOwner)
            {
                await teams.ArchiveAsync(user, orphaned, ct).ConfigureAwait(false);
            }
@@ -1,5 +1,6 @@
 using System.Security.Cryptography;
 using DodoSSH.Api.Features.Events;
 using DodoSSH.Api.Setup;
 using DodoSSH.Contracts;
 using DodoSSH.Domain;
 using DodoSSH.Infrastructure;
@@ -76,19 +77,7 @@ internal sealed class VaultGrantService(
                "That vault id is already in use. Generate a new UUIDv7 and retry.");
        }
-        AddVaultWithSelfGrant(user, team, request, name, key, clock.GetUtcNow());
+        await WriteVaultAsync(user, team, request, name, key, cancellationToken).ConfigureAwait(false);
        try
        {
            await database.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
        }
        catch (DbUpdateException exception) when (IsUniqueViolation(exception))
        {
            // The pre-check covers the ordinary case; this is the race between two creates choosing
            // the same id, which must not surface as a 500 about a constraint.
            throw new TeamInvalidException(
                "That vault id is already in use. Generate a new UUIDv7 and retry.");
        }
        TeamLog.TeamVaultCreated(logger, request.VaultId, team.Id, user.Id);
@@ -103,6 +92,55 @@ internal sealed class VaultGrantService(
            RekeyRequired: false);
    }
    /// <summary>Writes the vault and its first grant, under the team's lock, in one transaction.</summary>
    private Task WriteVaultAsync(
        UserAccount user,
        Team team,
        CreateTeamVaultRequest request,
        string name,
        UserKey key,
        CancellationToken cancellationToken) =>
        database.ExecuteFreshAsync([team], async () =>
        {
            var transaction = await database.Database
                .BeginTransactionAsync(cancellationToken)
                .ConfigureAwait(false);
            await using var _ = transaction.ConfigureAwait(false);
            // Under the lock an archive takes, and the team re-read under it: see TeamLock.
            await TeamLock.AcquireAsync(database, team.Id, cancellationToken).ConfigureAwait(false);
            await RequireTeamStillLiveAsync(team.Id, cancellationToken).ConfigureAwait(false);
            AddVaultWithSelfGrant(user, team, request, name, key, clock.GetUtcNow());
            try
            {
                await database.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
            }
            catch (DbUpdateException exception) when (IsUniqueViolation(exception))
            {
                // The pre-check covers the ordinary case; this is the race between two creates choosing
                // the same id, which must not surface as a 500 about a constraint.
                throw new TeamInvalidException(
                    "That vault id is already in use. Generate a new UUIDv7 and retry.");
            }
            await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
        });
    /// <summary>Refuses a vault for a team archived since the request resolved it.</summary>
    private async Task RequireTeamStillLiveAsync(Guid teamId, CancellationToken cancellationToken)
    {
        var live = await database.Teams
            .AnyAsync(t => t.Id == teamId && t.DeletedAtUtc == null, cancellationToken)
            .ConfigureAwait(false);
        if (!live)
        {
            throw new TeamInvalidException("This team has been archived, so it can no longer own a new vault.");
        }
    }
    /// <summary>Adds the vault row and the creator's own grant, in one unit of work.</summary>
    private void AddVaultWithSelfGrant(
        UserAccount user,
@@ -41,17 +41,24 @@ 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
+// A singleton, because the sockets it holds outlive the requests that opened them. The endpoint needs the
-// resolving to the same instance: the endpoint needs the whole hub — admit, remove, count — while the
+// whole hub — admit, remove, count — while the write paths that announce a change need only the two methods
-// write paths that announce a change need only the two methods that announce one, and should not gain
+// that announce one, and get them from a fan-out that also tells the relay: a user who loses access to a
-// a reference to connection management to get them.
+// vault loses their relay sessions into it too. See VaultEventFanOut and RelayAccessWatch.
 builder.Services.AddSingleton<VaultEventHub>();
-builder.Services.AddSingleton<IVaultEventPublisher>(
+builder.Services.AddSingleton<IVaultEventPublisher, VaultEventFanOut>();
-    provider => provider.GetRequiredService<VaultEventHub>());
+
 // ADR 0003's tombstone collection, and the compaction of the change log that goes with it.
 builder.Services.AddScoped<TombstoneCollector>();
 builder.Services.AddHostedService<TombstoneCollectionService>();
 // The relay's services, its ticket key ring, and a shutdown long enough for its drain. See ADR 0004.
 builder.Services.AddDodoRelay();
 // 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>();
 builder.Services.AddScoped<IAuthorizationHandler, ActiveAccountHandler>();
 // Replaces the framework default, which is also registered as a singleton. Last registration wins.
 builder.Services.AddSingleton<IAuthorizationMiddlewareResultHandler, DodoAuthorizationResultHandler>();
@@ -62,7 +62,14 @@ internal static class Auth
    private static void AddDodoPolicies(AuthorizationOptions options)
    {
-        options.AddPolicy(AuthenticatedPolicy, policy => policy.RequireAuthenticatedUser());
+        // Both policies also require the account to be active. A suspended or deprovisioned account still
        // holds a token the identity provider will vouch for until it expires — the status is this server's
        // own decision, so it is this server that has to refuse. See ActiveAccountHandler.
        options.AddPolicy(
            AuthenticatedPolicy,
            policy => policy
                .RequireAuthenticatedUser()
                .AddRequirements(new Authorization.ActiveAccountRequirement()));
        // Enrollment state lives in the database, so this is satisfied by EnrolledHandler.
        // An unmet EnrolledRequirement is rewritten into a ProblemDetails carrying
@@ -72,7 +79,7 @@ internal static class Auth
            EnrolledPolicy,
            policy => policy
                .RequireAuthenticatedUser()
-                .AddRequirements(new Authorization.EnrolledRequirement()));
+                .AddRequirements(new Authorization.ActiveAccountRequirement(), new Authorization.EnrolledRequirement()));
        // Deny by default: an endpoint without an explicit policy still requires a caller.
        options.FallbackPolicy = options.GetPolicy(AuthenticatedPolicy);
@@ -54,6 +54,13 @@ internal static class Configuration
                + "setting exists to provide.")
            .ValidateOnStart();
        services.AddRelayOptions();
        return services;
    }
    /// <summary>The relay's options, which carry more rules than any other section. See ADR 0004.</summary>
    private static void AddRelayOptions(this IServiceCollection services) =>
        services.AddOptions<RelayOptions>()
            .BindConfiguration(RelayOptions.SectionName)
            .ValidateDataAnnotations()
@@ -63,11 +70,28 @@ internal static class Configuration
            .Validate(
                options => options.IdleTimeout < options.MaxSessionDuration,
                "Relay:IdleTimeout must be shorter than Relay:MaxSessionDuration.")
            .Validate(
                options => options.TicketLifetime > TimeSpan.Zero
                    && options.TicketLifetime <= TimeSpan.FromSeconds(30),
                "Relay:TicketLifetime must be positive and at most 30 seconds. A ticket is a bearer "
                + "credential in a header; ADR 0004 bounds how long one may be worth stealing.")
            .Validate(
                options => options.ConnectTimeout > TimeSpan.Zero && options.DrainTimeout >= TimeSpan.Zero,
                "Relay:ConnectTimeout must be positive and Relay:DrainTimeout must not be negative.")
            .Validate(
                options => Features.Relay.RelayAddressPolicy.AreNetworks(options.AllowedNetworks)
                    && Features.Relay.RelayAddressPolicy.AreNetworks(options.DeniedNetworks),
                "Relay:AllowedNetworks and Relay:DeniedNetworks must hold CIDR networks such as "
                + "10.20.0.0/16, with no host bits set. An entry this server cannot read would be a gap "
                + "the operator believes is closed.")
            .Validate(
                options => !options.Enabled
                    || (Uri.TryCreate(options.WebSocketUrl, UriKind.Absolute, out var url)
                        && (string.Equals(url.Scheme, Uri.UriSchemeWs, StringComparison.Ordinal)
                            || string.Equals(url.Scheme, Uri.UriSchemeWss, StringComparison.Ordinal))),
                "Relay:WebSocketUrl must be an absolute ws:// or wss:// URL.")
            .ValidateOnStart();
        return services;
    }
    /// <summary>
    /// Warns about configuration that is individually valid but dangerous in combination.
    /// </summary>
@@ -115,13 +115,50 @@ public sealed class RelayOptions
    /// Whether RFC1918 and other private ranges may be dialled.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Defaults to true, unlike a typical SSRF allow-list, because reaching private
    /// infrastructure is the entire purpose of a self-hosted SSH tool. The control that matters is
-    /// the ACL: only hosts in a vault the caller holds Connect on can be dialled at all. Loopback,
+    /// the ACL: only hosts in a vault the caller holds Connect on can be dialled at all.
-    /// link-local and cloud metadata ranges are denied unconditionally and are not configurable.
+    /// </para>
    /// <para>
    /// Governs the private ranges only — RFC1918, carrier-grade NAT (which is where a Tailnet lives) and
    /// IPv6 unique-local — and never the list <c>RelayAddressPolicy</c> refuses with no configuration
    /// escape: loopback, link-local, <c>0.0.0.0/8</c>, multicast and the cloud metadata addresses.
    /// Nothing here can re-open those, which is what ADR 0004 §3 means by non-overridable.
    /// </para>
    /// </remarks>
    public bool AllowPrivateNetworks { get; set; } = true;
    /// <summary>
    /// Networks, in CIDR form, that a relay target must fall inside. Empty means any network the other
    /// rules permit.
    /// </summary>
    /// <remarks>
    /// When set, this is the whole answer for the ranges it names: a target inside one is permitted even
    /// with <see cref="AllowPrivateNetworks"/> off, because "only 10.20.0.0/16" is the precise thing an
    /// operator means by setting both. It still cannot reach the non-overridable list, and
    /// <see cref="DeniedNetworks"/> still wins over it.
    /// </remarks>
    public IList<string> AllowedNetworks { get; } = [];
    /// <summary>Networks, in CIDR form, that a relay target may never fall inside.</summary>
    /// <remarks>
    /// Checked before <see cref="AllowedNetworks"/>, so a deny inside an allow is a hole in it — the way
    /// round that lets an operator carve the database subnet out of an otherwise permitted range.
    /// </remarks>
    public IList<string> DeniedNetworks { get; } = [];
    /// <summary>
    /// A directory to keep the ticket key ring in. Unset means the platform default.
    /// </summary>
    /// <remarks>
    /// Losing the key ring is harmless in the way losing <c>Sync:CursorSigningKey</c> is: a ticket lives
    /// thirty seconds, so a restart invalidates at most the connects in flight and the client asks
    /// again. What does need it is more than one node — every node must be able to read every other's
    /// tickets for round-robin to work, so a multi-node deployment points this at shared storage.
    /// </remarks>
    public string? KeyRingDirectory { get; set; }
    /// <summary>Maximum concurrent sessions per user.</summary>
    [Range(1, 1000)]
    public int MaxConcurrentSessionsPerUser { get; set; } = 10;
@@ -252,6 +289,10 @@ public sealed class SyncOptions
    [Range(1, 3650)]
    public int TombstoneRetentionDays { get; set; } = 90;
    /// <summary>How often the tombstone collector runs, in minutes.</summary>
    [Range(1, 7 * 24 * 60)]
    public int TombstoneCollectionIntervalMinutes { get; set; } = 6 * 60;
    /// <summary>
    /// Key used to sign sync cursors, base64.
    /// </summary>
@@ -1,6 +1,7 @@
 using DodoSSH.Api.Features.Events;
 using DodoSSH.Api.Features.Identity;
 using DodoSSH.Api.Features.Meta;
 using DodoSSH.Api.Features.Relay;
 using DodoSSH.Api.Features.Sync;
 using DodoSSH.Api.Features.Teams;
 using DodoSSH.Contracts;
@@ -45,6 +46,8 @@ internal static class EndpointRegistration
            typeof(SyncPullEndpoint),
            typeof(SyncPushEndpoint),
            typeof(VaultEventsEndpoint),
            typeof(RelayTicketEndpoint),
            typeof(RelayConnectEndpoint),
            typeof(CreateTeamEndpoint),
            typeof(ListTeamsEndpoint),
            typeof(UpdateTeamEndpoint),
@@ -65,7 +68,6 @@ internal static class EndpointRegistration
            // Registered as each feature lands:
            //   Identity   — key rotation, passphrase change
            //   Vaults     — per-item ACLs
            //   Relay      — tickets and the WebSocket
            //   Audit, Admin
        });
@@ -0,0 +1,72 @@
 using DodoSSH.Infrastructure;
 using Microsoft.EntityFrameworkCore;
 namespace DodoSSH.Api.Setup;
 /// <summary>
 /// Runs a write transaction under the retrying execution strategy so that a retry starts from the database
 /// rather than from what the failed attempt left in the change tracker.
 /// </summary>
 /// <remarks>
 /// <para>
 /// <b>The strategy re-runs the delegate on the same context, and the context remembers the attempt that
 /// failed.</b> When the failure is the commit itself — a connection dropped after <c>SaveChanges</c> had
 /// already succeeded — every entity that attempt wrote is marked unchanged, holding values the database
 /// rolled back. The retry then assigns the same values again, change detection sees nothing to save, and
 /// the transaction commits without them. Enrolment lost <c>EnrolledAtUtc</c> that way, and a team hand-over
 /// its two role changes, each reporting success.
 /// </para>
 /// <para>
 /// So a retry clears the tracker, and reloads each entity the delegate was handed from outside it — the ones
 /// it modifies or reads but did not load itself — so they are tracked again with what the database actually
 /// holds and the delegate's own assignments register as changes. The first attempt runs exactly as it did
 /// before: nothing is cleared or reloaded until something has failed.
 /// </para>
 /// </remarks>
 internal static class FreshAttempts
 {
    /// <summary>Runs <paramref name="attempt"/> under the context's execution strategy, freshly each time.</summary>
    /// <param name="database">The request's context.</param>
    /// <param name="carried">Entities loaded before the transaction that the attempt reads or modifies.</param>
    /// <param name="attempt">The transaction, which begins and commits its own.</param>
    internal static Task<T> ExecuteFreshAsync<T>(
        this DodoDbContext database,
        IReadOnlyList<object> carried,
        Func<Task<T>> attempt)
    {
        ArgumentNullException.ThrowIfNull(database);
        ArgumentNullException.ThrowIfNull(carried);
        ArgumentNullException.ThrowIfNull(attempt);
        var strategy = database.Database.CreateExecutionStrategy();
        var attempts = 0;
        return strategy.ExecuteAsync(async () =>
        {
            if (attempts++ > 0)
            {
                database.ChangeTracker.Clear();
                foreach (var entity in carried)
                {
                    await database.Entry(entity).ReloadAsync().ConfigureAwait(false);
                }
            }
            return await attempt().ConfigureAwait(false);
        });
    }
    /// <inheritdoc cref="ExecuteFreshAsync{T}" />
    internal static Task ExecuteFreshAsync(
        this DodoDbContext database,
        IReadOnlyList<object> carried,
        Func<Task> attempt) =>
        database.ExecuteFreshAsync(
            carried,
            async () =>
            {
                await attempt().ConfigureAwait(false);
                return true;
            });
 }
@@ -1,5 +1,6 @@
 using DodoSSH.Infrastructure;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Diagnostics;
 using Microsoft.Extensions.Diagnostics.HealthChecks;
 using Microsoft.Extensions.Options;
 using Npgsql;
@@ -29,14 +30,18 @@ internal static class Persistence
            ?? throw new InvalidOperationException(
                $"ConnectionStrings:{ConnectionStringName} is not configured.");
-        services.AddDbContext<DodoDbContext>(options => options
+        services.AddDbContext<DodoDbContext>((provider, options) => options
            .UseNpgsql(connectionString, npgsql => npgsql
                .MigrationsHistoryTable("__EFMigrationsHistory", DodoDbContext.SchemaName)
-                // Retry on transient faults only. Note this is safe here because writes go
+                // Retry on transient faults only. A write transaction replayed by the strategy runs on
-                // through explicitly-managed transactions rather than relying on the execution
+                // the same context, which still holds what the failed attempt tracked — every such
-                // strategy to replay ambient ones.
+                // transaction goes through FreshAttempts.ExecuteFreshAsync, which starts a retry from
                // the database instead.
                .EnableRetryOnFailure(3))
-            .UseSnakeCaseNamingConvention());
+            .UseSnakeCaseNamingConvention()
            // None in production. The seam a test uses to make a commit fail the way a dropped
            // connection would, which is the only way to watch a retry happen.
            .AddInterceptors(provider.GetServices<IInterceptor>()));
        services.AddHealthChecks()
            .AddCheck<DatabaseHealthCheck>(
@@ -0,0 +1,60 @@
 using DodoSSH.Api.Features.Relay;
 using Microsoft.AspNetCore.DataProtection;
 using Microsoft.AspNetCore.DataProtection.KeyManagement;
 using Microsoft.AspNetCore.DataProtection.Repositories;
 using Microsoft.Extensions.Options;
 namespace DodoSSH.Api.Setup;
 /// <summary>The relay's services. See ADR 0004.</summary>
 internal static class RelaySetup
 {
    /// <summary>
    /// How much longer than the drain the host waits before it stops regardless.
    /// </summary>
    /// <remarks>
    /// Room for the close handshakes and the audit rows' final writes once the drain has run out, which
    /// is the part of a shutdown an operator would otherwise lose without noticing.
    /// </remarks>
    private static readonly TimeSpan ShutdownMargin = TimeSpan.FromSeconds(10);
    internal static IServiceCollection AddDodoRelay(this IServiceCollection services)
    {
        // Singletons: a session outlives the request that opened it, a protector is safe to share, and
        // the network seam holds no state.
        services.AddSingleton<RelayTicketCodec>();
        services.AddSingleton<RelaySessionRegistry>();
        services.AddSingleton<RelayAccessWatch>();
        services.AddSingleton<IRelayNetwork, SystemRelayNetwork>();
        // The application name isolates this deployment's payloads from any other ASP.NET application
        // sharing a key directory, and — unlike the default, which is derived from the content root —
        // is the same on every node, which is what lets any node verify any node's ticket.
        services.AddDataProtection().SetApplicationName("DodoSSH");
        services.AddOptions<KeyManagementOptions>()
            .Configure<IOptions<RelayOptions>, ILoggerFactory>((keys, relay, loggers) =>
            {
                if (relay.Value.KeyRingDirectory is { Length: > 0 } directory)
                {
                    keys.XmlRepository = new FileSystemXmlRepository(new DirectoryInfo(directory), loggers);
                }
            });
        // Longer than the drain, or the host would stop waiting for live sessions before the drain ADR 0004
        // promises them had run. Harmless with the relay off: nothing else holds a request open that long,
        // and the host stops as soon as the last request has.
        services.AddOptions<HostOptions>()
            .Configure<IOptions<RelayOptions>>((host, relay) =>
            {
                var wanted = relay.Value.DrainTimeout + ShutdownMargin;
                if (wanted > host.ShutdownTimeout)
                {
                    host.ShutdownTimeout = wanted;
                }
            });
        return services;
    }
 }
@@ -86,7 +86,13 @@ public sealed partial class DodoSshApp : Avalonia.Application
        var shell = new PhoneShell();
        var viewModel = ComposeShell(
-            paths, caches, workspace, knownHosts, connections, ClipboardWriter(shell));
+            paths,
            caches,
            workspace,
            knownHosts,
            connections,
            ClipboardWriter(shell),
            ClipboardReader(shell));
        shell.DataContext = viewModel;
@@ -126,7 +132,8 @@ public sealed partial class DodoSshApp : Avalonia.Application
        var keepAlive = new SessionKeepAlive(
            workspace,
            activeTransfers: () => viewModel.Transfers.ActiveTransfers,
-            holdsFileSession: () => viewModel.Transfers.HasLiveFileSession);
+            holdsFileSession: () => viewModel.Transfers.HasLiveFileSession,
            listeningForwards: () => viewModel.ListeningForwardCount);
        // The other end of the same wire: the workspace announces its own sessions ending, and the queue
        // announces transfers appearing and finishing, and a Files session connecting or disconnecting.
@@ -142,6 +149,11 @@ public sealed partial class DodoSshApp : Avalonia.Application
        // in the first place, which was precisely the promise this whole arrangement exists to keep.
        viewModel.TerminalSessionOpened += (_, _) => keepAlive.Refresh();
        // A forward starting, stopping or failing changes the notification's wording and nothing else — it
        // rides a shell's connection, so the shell is already what holds the service up. The user is still
        // entitled to know a phone in their pocket is holding ports open.
        viewModel.ForwardsChanged += (_, _) => keepAlive.Refresh();
        keepAlive.Refresh();
    }
@@ -176,6 +188,26 @@ public sealed partial class DodoSshApp : Avalonia.Application
            }
        };
    /// <summary>Reads this phone's clipboard.</summary>
    /// <remarks>
    /// <para>
    /// The other direction, looked up per call for the same reason and with the same fall-through. One
    /// caller: the terminal's right-click paste, which the renderer cannot serve itself — see
    /// <c>TerminalClientOpcode.ClipboardPaste</c>.
    /// </para>
    /// <para>
    /// Wired on this head although a phone has no right button, and not for symmetry: this head runs the same
    /// renderer page, and a device with a mouse, a trackpad case or a desktop dock has a secondary click.
    /// Whether Android's WebView delivers one as a DOM <c>contextmenu</c> event is unverified — see
    /// <c>docs/manual-checks.md</c> 11.13 — and leaving this out in the meantime would make the paste half
    /// the one thing that worked on one head and silently did nothing on the other.
    /// </para>
    /// </remarks>
    private static Func<Task<string?>> ClipboardReader(Visual surface) =>
        async () => TopLevel.GetTopLevel(surface) is { Clipboard: { } clipboard }
            ? await clipboard.TryGetTextAsync().ConfigureAwait(false)
            : null;
    /// <remarks>
    /// Split from <see cref="Compose"/> only for length. The division is a real one though: above this is
    /// the platform graph, and below it is the shell every head shares.
@@ -186,7 +218,8 @@ public sealed partial class DodoSshApp : Avalonia.Application
        TerminalWorkspace workspace,
        VaultKnownHostStore knownHosts,
        SshNetConnectionFactory connections,
-        Func<string, Task> copyToClipboard)
+        Func<string, Task> copyToClipboard,
        Func<Task<string?>> readClipboard)
    {
        // Difference 3: the Android keystore, with a fingerprint or the device credential releasing the
        // key. A straight implementation of the interface the session layer has always taken.
@@ -236,6 +269,7 @@ public sealed partial class DodoSshApp : Avalonia.Application
            deviceName: PhoneEnvironment.DeviceName,
            copyToClipboard: copyToClipboard,
            readClipboard: readClipboard,
            updates: updates);
@@ -90,6 +90,11 @@ public sealed class MainActivity : AvaloniaMainActivity
        PhoneEnvironment.CurrentActivity = this;
        AndroidRedirectCallback.Abandon();
        // And the keyboard may have gone away while this activity was not on screen, without Avalonia's
        // input pane raising anything to say so. PhoneShell re-reads the inset from this. See
        // PhoneEnvironment.Resumed, which carries the whole of why.
        PhoneEnvironment.RaiseResumed();
    }
    /// <inheritdoc />
@@ -100,6 +100,35 @@ internal static class PhoneEnvironment
    /// </remarks>
    public static global::Android.App.Activity? CurrentActivity { get; set; }
    /// <summary>Raised each time the launcher activity comes back to the foreground.</summary>
    /// <remarks>
    /// <para>
    /// ◆ <b>Exists because the software keyboard can go away without Avalonia being told.</b>
    /// <c>IInputPane.StateChanged</c> is the only signal <c>PhoneShell</c> has for the keyboard opening and
    /// closing, and it is not raised when Android dismisses the keyboard on the way out of the app — the
    /// activity is being paused, and the pane is simply gone by the time anything could have reported it.
    /// So the inset that holds the interface clear of the keyboard was still applied on the way back in,
    /// and the whole phone drew an entire keyboard's height above the bottom of a screen with no keyboard
    /// on it. Reproduced every time: open the keyboard anywhere, press Home, return — 838 of 2340 pixels
    /// dead, and staying that way until the keyboard was opened and closed again.
    /// </para>
    /// <para>
    /// An event here rather than a call into the view, because the view is Avalonia's and this is Android's:
    /// <c>MainActivity</c> already owns <c>OnResume</c> and already writes <see cref="CurrentActivity"/>
    /// from it, and a static event is the same shape of hand-off one step further. Anything else that needs
    /// to re-read platform state on the way back in can subscribe without <c>MainActivity</c> learning what
    /// it is.
    /// </para>
    /// <para>
    /// Subscribers are responsible for unsubscribing — this is a static event and holds whatever it is
    /// given for the life of the process. <c>PhoneShell</c> attaches and detaches with its visual tree.
    /// </para>
    /// </remarks>
    public static event EventHandler? Resumed;
    /// <summary>Announces that the launcher activity is foreground again.</summary>
    internal static void RaiseResumed() => Resumed?.Invoke(null, EventArgs.Empty);
    /// <summary>The application context, once <see cref="Attach"/> has run.</summary>
    public static Context Require() =>
        context ?? throw new InvalidOperationException(
@@ -0,0 +1,155 @@
 using global::Android.Views;
 namespace DodoSSH.Client.Android.Platform;
 /// <summary>
 /// Takes the keyboard away from the terminal's <c>WebView</c>, and reports the taps that should bring it
 /// back.
 /// </summary>
 /// <remarks>
 /// <para>
 /// <b>This replaces <c>TerminalFocus</c>, and it is the opposite move.</b> That class handed Android's own
 /// view focus <em>back</em> to the <c>WebView</c> after Avalonia's <c>DispatchTouchEvent</c> took it, because
 /// the input connection the keyboard was attached to belonged to the page. Under ADR 0015 it no longer does:
 /// <see cref="Views.TerminalInputSurface"/> is the input target, and it is an Avalonia control, so the focus
 /// the platform requests for Avalonia's view after every handled touch is now the focus we want. The fight
 /// ends by removing one of the contestants rather than by refereeing it faster.
 /// </para>
 /// <para>
 /// <b>Non-focusable, not non-interactive, and the distinction is the whole design.</b> Focusability governs
 /// where keyboard and D-pad input go; it has nothing to do with touch delivery. A <c>WebView</c> with
 /// <c>Focusable=false</c> still receives, scrolls and hit-tests every touch it is given — so the page keeps
 /// its <c>touch-action: pan-y</c> scrollback exactly as before — but it can no longer take an input
 /// connection, and Chromium's own <c>showSoftInput</c> for the focused DOM node cannot succeed from an
 /// unfocused view. That is precisely the split wanted: the page keeps the finger, Avalonia keeps the
 /// keyboard.
 /// </para>
 /// <para>
 /// <b>Why a tap has to be reported at all.</b> With the page unable to raise a keyboard, the ordinary way
 /// back after the system back gesture lowers one — touch the terminal — would otherwise do nothing. The
 /// listener is attached with <c>Handled = false</c> throughout, so it observes without consuming: the
 /// <c>WebView</c>'s own <c>OnTouchEvent</c> runs after it exactly as if nothing were listening.
 /// </para>
 /// <para>
 /// A tap is distinguished from a scroll the way every Android view does it, by
 /// <c>ViewConfiguration.ScaledTouchSlop</c>. Without that test, dragging the scrollback would raise the
 /// keyboard over the very output being scrolled to.
 /// </para>
 /// <para>
 /// Found by walking the decor view rather than asked of the <c>NativeWebView</c> control, for the reason
 /// <c>TerminalFocus</c> gave and which has not changed: the control does not expose its platform child, and
 /// this application only ever has the one <c>WebView</c>, so the walk's first match is necessarily the
 /// terminal. Every step is allowed to be absent — there is no activity while backgrounded, and no
 /// <c>WebView</c> until the terminal surface has been shown once.
 /// </para>
 /// </remarks>
 internal static class RendererFocus
 {
    /// <summary>The view already configured, so that showing the terminal twice does not listen twice.</summary>
    /// <remarks>
    /// Weak, because this is a static holding an Android view: a strong reference would keep the whole view
    /// hierarchy, and the activity behind it, alive for the life of the process.
    /// </remarks>
    private static WeakReference<global::Android.Webkit.WebView>? configured;
    /// <summary>
    /// Makes the renderer unable to hold the keyboard, and calls <paramref name="onTapped"/> when somebody
    /// taps it.
    /// </summary>
    /// <remarks>
    /// Idempotent, and called on every transition into the terminal rather than once at startup, because the
    /// <c>WebView</c> does not exist until the surface it lives on has been shown — and because Android is
    /// free to tear its renderer down and build a new one, which is a case this head already handles
    /// elsewhere (see <c>docs/android-port.md</c>).
    /// </remarks>
    public static void Suppress(Action onTapped)
    {
        if (PhoneEnvironment.CurrentActivity?.Window?.DecorView is not ViewGroup decor)
        {
            return;
        }
        if (FindWebView(decor) is not { } webView)
        {
            return;
        }
        if (configured is not null && configured.TryGetTarget(out var already) && ReferenceEquals(already, webView))
        {
            return;
        }
        webView.Focusable = false;
        webView.FocusableInTouchMode = false;
        webView.ClearFocus();
        WatchForTaps(webView, onTapped);
        configured = new WeakReference<global::Android.Webkit.WebView>(webView);
    }
    /// <summary>
    /// Calls <paramref name="onTapped"/> for a tap, and stays out of the way of everything else.
    /// </summary>
    /// <remarks>
    /// A tap is a press and a release that did not travel further than the platform's own
    /// <c>ScaledTouchSlop</c> — the same test every Android view uses, and necessary rather than fastidious:
    /// without it, dragging the scrollback would raise the keyboard over the output being scrolled to.
    /// </remarks>
    private static void WatchForTaps(global::Android.Webkit.WebView webView, Action onTapped)
    {
        // The fallback is the platform's own historical default, for a context that has somehow gone.
        var slop = webView.Context is { } context ? ViewConfiguration.Get(context)?.ScaledTouchSlop ?? 8 : 8;
        var downX = 0f;
        var downY = 0f;
        var moved = false;
        webView.Touch += (_, e) =>
        {
            // Observed, never consumed. The WebView's own OnTouchEvent still runs, so the page scrolls.
            e.Handled = false;
            if (e.Event is not { } motion)
            {
                return;
            }
            switch (motion.Action)
            {
                case MotionEventActions.Down:
                    downX = motion.GetX();
                    downY = motion.GetY();
                    moved = false;
                    break;
                case MotionEventActions.Move:
                    moved |= Math.Abs(motion.GetX() - downX) > slop || Math.Abs(motion.GetY() - downY) > slop;
                    break;
                case MotionEventActions.Up when !moved:
                    onTapped();
                    break;
            }
        };
    }
    private static global::Android.Webkit.WebView? FindWebView(ViewGroup parent)
    {
        for (var i = 0; i < parent.ChildCount; i++)
        {
            switch (parent.GetChildAt(i))
            {
                case global::Android.Webkit.WebView webView:
                    return webView;
                case ViewGroup child when FindWebView(child) is { } found:
                    return found;
            }
        }
        return null;
    }
 }
@@ -141,6 +141,11 @@ internal sealed class SessionForegroundService : Service
    /// <param name="liveSessions">Shells with a live channel behind them.</param>
    /// <param name="activeTransfers">Transfers still moving bytes.</param>
    /// <param name="holdsFileSession">Whether the Files screen holds a live, idle SFTP connection.</param>
    /// <param name="listeningForwards">
    /// Port forwards listening over those shells. Named in the summary and nothing else: a forward rides a
    /// shell's connection, so it cannot be the reason the process has to stay up — see
    /// <see cref="SessionKeepAlive"/>.
    /// </param>
    /// <remarks>
    /// Three outcomes, not the two a plain start-or-stop would have. Nothing live stops the service, as
    /// always. Something live and the service not yet running starts it. Something live and the service
@@ -152,7 +157,7 @@ internal sealed class SessionForegroundService : Service
    /// which needs no foreground-start permission at all. A foregrounded refresh still prefers a real
    /// start even over a service that looks like it is running; the inline remark below is why.
    /// </remarks>
-    public static void Reconcile(int liveSessions, int activeTransfers, bool holdsFileSession)
+    public static void Reconcile(int liveSessions, int activeTransfers, bool holdsFileSession, int listeningForwards)
    {
        var context = PhoneEnvironment.Require();
@@ -165,7 +170,7 @@ internal sealed class SessionForegroundService : Service
        // The summary says what is actually held, counted rather than generic — the same principle the
        // delete confirmations follow. "DodoSSH is running" would tell the user nothing they could act on.
-        var summary = Summarise(liveSessions, activeTransfers, holdsFileSession);
+        var summary = Summarise(liveSessions, activeTransfers, holdsFileSession, listeningForwards);
        // In-place only while backgrounded, where it is the only legal move. Foregrounded, a real start is
        // always allowed and is preferred even when `running` says the service is up: a disconnect followed
@@ -255,15 +260,22 @@ internal sealed class SessionForegroundService : Service
            activity.RequestPermissions([postNotifications], NotificationPermissionRequestCode));
    }
-    private static string Summarise(int liveSessions, int activeTransfers, bool holdsFileSession)
+    private static string Summarise(int liveSessions, int activeTransfers, bool holdsFileSession, int listeningForwards)
    {
-        var parts = new List<string>(3);
+        var parts = new List<string>(4);
        if (liveSessions > 0)
        {
            parts.Add(liveSessions == 1 ? "1 shell connected" : $"{liveSessions} shells connected");
        }
        // Beside the shells they run over, and only while one is: a count left over from a session that has
        // just ended would be a receipt for ports nothing holds open any more.
        if (liveSessions > 0 && listeningForwards > 0)
        {
            parts.Add(listeningForwards == 1 ? "1 port forwarded" : $"{listeningForwards} ports forwarded");
        }
        if (holdsFileSession)
        {
            parts.Add("Files connected");
@@ -24,12 +24,20 @@ namespace DodoSSH.Client.Android.Platform;
 /// looked, to this class, exactly like nothing being open at all. <c>holdsFileSession</c> below is that
 /// gap closed, read the same way the other two facts are: asked, not cached.
 /// </para>
 /// <para>
 /// Listening port forwards are a fourth fact, and a different kind: they only change what the notification
 /// says. A forward runs over a shell's connection and stops with it, so there is never a listening forward
 /// without a live shell already holding the service up — and a count that could start the service on its own
 /// would only ever be wrong, in the moment a forward's Stopped had not been heard yet. What they add is the
 /// receipt: the user is entitled to know the phone is holding ports open, as well as shells.
 /// </para>
 /// </remarks>
 internal sealed class SessionKeepAlive : IDisposable
 {
    private readonly TerminalWorkspace workspace;
    private readonly Func<int> activeTransfers;
    private readonly Func<bool> holdsFileSession;
    private readonly Func<int> listeningForwards;
    /// <param name="workspace">The live shells.</param>
    /// <param name="activeTransfers">
@@ -40,11 +48,20 @@ internal sealed class SessionKeepAlive : IDisposable
    /// Whether the Files screen holds a live SFTP connection with nothing moving on it — the idle-but-
    /// connected case a transfer count alone would miss. See <c>TransfersViewModel.HasLiveFileSession</c>.
    /// </param>
-    public SessionKeepAlive(TerminalWorkspace workspace, Func<int> activeTransfers, Func<bool> holdsFileSession)
+    /// <param name="listeningForwards">
    /// How many port forwards are listening, across every tab. For the notification's wording only; see the
    /// class remarks. See <c>MainWindowViewModel.ListeningForwardCount</c>.
    /// </param>
    public SessionKeepAlive(
        TerminalWorkspace workspace,
        Func<int> activeTransfers,
        Func<bool> holdsFileSession,
        Func<int> listeningForwards)
    {
        this.workspace = workspace;
        this.activeTransfers = activeTransfers;
        this.holdsFileSession = holdsFileSession;
        this.listeningForwards = listeningForwards;
        // Raised on whatever thread the workspace announced from — a continuation of the ended run, or the
        // closer's own — which is fine: starting and stopping a service is a binder call and needs no
@@ -56,14 +73,15 @@ internal sealed class SessionKeepAlive : IDisposable
    /// <summary>Re-reads the counts and starts or stops the service to match.</summary>
    /// <remarks>
-    /// Called after anything that could change any of the three facts — opening a shell, closing a tab, a
+    /// Called after anything that could change any of the facts — opening a shell, closing a tab, a transfer
-    /// transfer finishing, a Files connection opening or closing. Calling it when nothing changed is free:
+    /// finishing, a Files connection opening or closing, a forward starting or stopping. Calling it when nothing changed is free:
    /// reconciling to the state it is already in is either a redundant <c>startForegroundService</c> — or,
    /// now, a redundant notification post — on a running service, or a <c>stopService</c> on a stopped one,
    /// and Android treats all of those as no-ops.
    /// </remarks>
    public void Refresh() =>
-        SessionForegroundService.Reconcile(workspace.LiveSessionCount, activeTransfers(), holdsFileSession());
+        SessionForegroundService.Reconcile(
            workspace.LiveSessionCount, activeTransfers(), holdsFileSession(), listeningForwards());
    /// <inheritdoc />
    public void Dispose()
@@ -72,7 +90,7 @@ internal sealed class SessionKeepAlive : IDisposable
        // The notification goes with the composition root. Leaving it up over a process that is shutting
        // down is how an SSH client acquires a reputation for a notification you cannot get rid of.
-        SessionForegroundService.Reconcile(0, 0, false);
+        SessionForegroundService.Reconcile(0, 0, false, 0);
    }
    private void OnSessionEnded(object? sender, TerminalSessionEndedEventArgs e) => Refresh();
@@ -1,79 +0,0 @@
 using global::Android.Views;
 namespace DodoSSH.Client.Android.Platform;
 /// <summary>
 /// Hands native focus back to the terminal's WebView after Avalonia chrome took it.
 /// </summary>
 /// <remarks>
 /// <para>
 /// <b>The sibling of <see cref="SoftKeyboard"/>, and it exists for the same reason that one does:</b> the
 /// keyboard over a terminal belongs to the WebView's own native view, which Avalonia's focus manager does
 /// not own. The accessory row's keys are already <c>Focusable=false</c> — see TerminalScreen — so Avalonia's
 /// idea of focus never leaves the terminal when one is tapped. What still moves is <em>Android's</em>:
 /// <c>AvaloniaView.DispatchTouchEvent</c> (decompiled from Avalonia.Android 12.1.1) ends every handled
 /// touch — DOWN and UP alike — with a <c>RequestFocus()</c> for Avalonia's own view. The WebView's input
 /// connection dies with its focus, the keyboard swaps to the layout it shows an editor that takes no text,
 /// and the inset churn that follows can leave it sitting on top of the very row that was tapped.
 /// </para>
 /// <para>
 /// <b>Posted, not called — the posting is the fix's second attempt, and the first one's failure is why.</b>
 /// The first version called <c>RequestFocus()</c> from the keys' own Click handlers, which fire
 /// <em>inside</em> the UP event's dispatch — and the platform's own request runs <em>after</em> dispatch
 /// returns, so it undid ours a few microseconds later and the terminal stayed unfocused. A posted runnable
 /// runs on the next main-looper message, after the platform has taken its turn, so ours is the request that
 /// sticks. The focus check lives inside the posted runnable for the same reason: the answer at call time is
 /// about to be made stale by the very mechanism this exists to counter.
 /// </para>
 /// <para>
 /// The page inside the WebView never noticed any of this — its own DOM focus never moved — so regaining
 /// native focus re-establishes the same input connection and the keyboard settles back to what it was.
 /// </para>
 /// <para>
 /// Found by walking the decor view rather than asked of the <c>NativeWebView</c> control, because the
 /// control does not expose its platform child and this application only ever has the one WebView — the
 /// walk's first match is necessarily the terminal. Every step is allowed to be absent, exactly as
 /// <see cref="SoftKeyboard.Hide"/>'s are: no activity while backgrounded, no WebView while the terminal
 /// surface has never been shown, and nothing to do in either case.
 /// </para>
 /// </remarks>
 internal static class TerminalFocus
 {
    public static void Return()
    {
        if (PhoneEnvironment.CurrentActivity?.Window?.DecorView is not ViewGroup decor)
        {
            return;
        }
        if (FindWebView(decor) is not { } webView)
        {
            return;
        }
        webView.Post(() =>
        {
            if (!webView.IsFocused)
            {
                webView.RequestFocus();
            }
        });
    }
    private static View? FindWebView(ViewGroup parent)
    {
        for (var i = 0; i < parent.ChildCount; i++)
        {
            switch (parent.GetChildAt(i))
            {
                case global::Android.Webkit.WebView webView:
                    return webView;
                case ViewGroup child when FindWebView(child) is { } found:
                    return found;
            }
        }
        return null;
    }
 }
@@ -167,10 +167,124 @@
    <Setter Property="Foreground" Value="{StaticResource AccentText}" />
    <Setter Property="FontSize" Value="20" />
  </Style>
  <!--
    ◆ THE FILL BELOW IS NOT DECORATION. IT IS UNDOING ONE FLUENT PUTS THERE.
    `accent` is not a name this theme invented — Fluent ships a `Button.accent` style of its own, and a
    button classed `icon accent` matches it. So these three buttons were being painted with Fluent's
    system-accent slab, #6275AC, a blue that appears nowhere in Palette.axaml and reads as a control from
    a different application sitting in this one's header. Measured off a screenshot rather than guessed:
    the fill was #6275AC where the accent is #5D42DE.
    The rule above could not stop it, because it sets Foreground and FontSize and Fluent's fill is on the
    ContentPresenter — which is also why `Button.icon`'s own Background="Transparent" does not reach it.
    App.axaml has carried the desktop's answer to exactly this since v5b: override the ContentPresenter,
    not the Button. This head simply never had one, so the desktop looked right and the phone did not.
    Transparent rather than the desktop's gradient, and the difference is the control rather than an
    inconsistency. The desktop's Button.accent is a filled primary slab — this head has one of those too,
    and it is Button.primary. `icon accent` is a 44-pixel glyph in a header row beside other glyphs; what
    "accent" asks for there is the accent *colour on the mark*, which is what the rule above gives it. A
    slab would make one header icon a button and its neighbours not.
    Pressed is deliberately not restated: Button.icon:pressed below sets ChromeHover on every icon button
    and, coming later in this file, wins over this rule for the moment a finger is down. That is the
    feedback the plain icon buttons give and there is no reason this one should differ.
  -->
  <Style Selector="Button.icon.accent /template/ ContentPresenter#PART_ContentPresenter">
    <Setter Property="Background" Value="Transparent" />
    <Setter Property="BorderThickness" Value="0" />
    <Setter Property="Foreground" Value="{StaticResource AccentText}" />
  </Style>
  <Style Selector="Button.icon.accent:pointerover /template/ ContentPresenter#PART_ContentPresenter">
    <Setter Property="Background" Value="Transparent" />
    <Setter Property="Foreground" Value="{StaticResource AccentText}" />
  </Style>
  <Style Selector="Button.icon.accent:disabled /template/ ContentPresenter#PART_ContentPresenter">
    <Setter Property="Background" Value="Transparent" />
    <Setter Property="Foreground" Value="{StaticResource TextFaint}" />
  </Style>
  <Style Selector="Button.icon:pressed /template/ ContentPresenter">
    <Setter Property="Background" Value="{StaticResource ChromeHover}" />
  </Style>
  <!--
    ============ one key of the terminal's accessory keypad ============
    A class rather than eleven sets of attributes assigned in code, and the move out of the code-behind is
    most of what makes the latched state honest: Ctrl on and Ctrl off used to be two Background values
    written by hand in TerminalScreen.axaml.cs, which meant the row named two of this palette's brushes
    itself and any third state would have named a third. It is `latched` here, and the code toggles a class.
    ── the numbers, and why they are these ─────────────────────────────────────────────────────────────────
    40 tall, where the row this replaced was 30. Android asks for 48 on a touch target and every terminal on
    the platform lands near it; 30 was chosen to save a strip of the terminal above and took the keypad past
    the point of working, which is the wrong end of that trade. 40 with a 2-pixel margin gives 44 of pitch,
    which is the same figure TextBox.field uses for a box a thumb has to hit.
    HorizontalAlignment Stretch, because these live in UniformGrid cells and the cell is the share of the
    width the key is entitled to. Left to Center a key would shrink to its label and "|" would be a sliver
    between two wide neighbours — which is the layout the flexed row exists to stop.
    ── pressed has to be visible, and it was not ───────────────────────────────────────────────────────────
    These keys are Focusable="False" so that using one does not take the keyboard away from the terminal
    (see TerminalScreen.axaml.cs), and a button that never takes focus also never shows the focus adorner
    Fluent would otherwise give it. That left a press with no feedback at all on a control whose entire job
    is to be pressed while somebody is looking at the line of output above it. The pressed fill below is the
    only thing that says a key was hit — and on a keypad over a remote shell, "did that send?" is a question
    worth answering in the interface rather than in the scrollback.
  -->
  <Style Selector="Button.hotkey">
    <Setter Property="Height" Value="40" />
    <Setter Property="MinHeight" Value="40" />
    <Setter Property="MinWidth" Value="0" />
    <Setter Property="Margin" Value="2,0" />
    <Setter Property="Padding" Value="0" />
    <Setter Property="CornerRadius" Value="10" />
    <Setter Property="Background" Value="{StaticResource Panel}" />
    <Setter Property="BorderBrush" Value="{StaticResource BorderMid}" />
    <Setter Property="BorderThickness" Value="1" />
    <Setter Property="Foreground" Value="{StaticResource TextDim}" />
    <Setter Property="FontFamily" Value="{StaticResource MonoFont}" />
    <Setter Property="FontSize" Value="12" />
    <Setter Property="HorizontalAlignment" Value="Stretch" />
    <Setter Property="VerticalAlignment" Value="Center" />
    <Setter Property="HorizontalContentAlignment" Value="Center" />
    <Setter Property="VerticalContentAlignment" Value="Center" />
  </Style>
  <Style Selector="Button.hotkey /template/ ContentPresenter#PART_ContentPresenter">
    <Setter Property="Background" Value="{StaticResource Panel}" />
    <Setter Property="BorderBrush" Value="{StaticResource BorderMid}" />
    <Setter Property="BorderThickness" Value="1" />
    <Setter Property="CornerRadius" Value="10" />
  </Style>
  <Style Selector="Button.hotkey:pointerover /template/ ContentPresenter#PART_ContentPresenter">
    <Setter Property="Background" Value="{StaticResource Panel}" />
    <Setter Property="BorderBrush" Value="{StaticResource BorderMid}" />
  </Style>
  <Style Selector="Button.hotkey:pressed /template/ ContentPresenter#PART_ContentPresenter">
    <Setter Property="Background" Value="{StaticResource Active}" />
    <Setter Property="BorderBrush" Value="{StaticResource Accent}" />
  </Style>
  <!--
    Latched Ctrl. The same fill a press gives, held rather than flashed — a modifier that is on and does not
    look on is how somebody sends ^L to a database prompt believing they typed an l.
  -->
  <Style Selector="Button.hotkey.latched">
    <Setter Property="Foreground" Value="{StaticResource AccentText}" />
  </Style>
  <Style Selector="Button.hotkey.latched /template/ ContentPresenter#PART_ContentPresenter">
    <Setter Property="Background" Value="{StaticResource Active}" />
    <Setter Property="BorderBrush" Value="{StaticResource Accent}" />
  </Style>
  <Style Selector="Button.hotkey:disabled /template/ ContentPresenter#PART_ContentPresenter">
    <Setter Property="Background" Value="{StaticResource Panel}" />
    <Setter Property="BorderBrush" Value="{StaticResource Border}" />
  </Style>
  <Style Selector="Button.hotkey:disabled">
    <Setter Property="Foreground" Value="{StaticResource TextFaint}" />
  </Style>
  <!--
    The floating action button the design has asked for since v2, and which this theme refused twice — on
    the grounds that it would open an editor this head had not got, and that an unused style is a claim the
@@ -398,6 +512,58 @@
    <Setter Property="FontSize" Value="12" />
  </Style>
  <!--
    ◆ The two port boxes, which are NumericUpDowns and were the only unthemed controls on this head.
    They sit in a two-column Grid with a plain TextBox.field beside them — port next to username in the host
    editor, and port next to default-user in the group editor — so the mismatch was not subtle: a bright
    Fluent border and a near-black fill against this theme's #101019 and hairline, at the one place on the
    screen where the two are a hand's width apart and directly comparable.
    Not `Classes="field"` on the two call sites, because that class is a TextBox class and this is not a
    TextBox: NumericUpDown is a ButtonSpinner wrapping one, so half the chrome being corrected belongs to
    the spinner and would not take a TextBox setter. Typing the control instead also means a third port box
    added later is right without anybody remembering, which is the property the desktop's own bare
    `Selector="NumericUpDown"` in App.axaml has had since it was written.
    Three selectors rather than one for the same reason Button.icon.accent needs two: Fluent puts the fill
    and the border on template parts, and a value set on the control alone is a TemplateBinding the theme's
    own wins over. The numbers are TextBox.field's, exactly — 44 tall, 10 radius, Field on BorderMid — so
    the pair reads as one row of two boxes rather than as a box and a visitor.
  -->
  <Style Selector="NumericUpDown">
    <Setter Property="Height" Value="44" />
    <Setter Property="MinHeight" Value="44" />
    <Setter Property="VerticalContentAlignment" Value="Center" />
    <Setter Property="Background" Value="{StaticResource Field}" />
    <Setter Property="BorderBrush" Value="{StaticResource BorderMid}" />
    <Setter Property="BorderThickness" Value="1" />
    <Setter Property="CornerRadius" Value="10" />
    <Setter Property="Foreground" Value="{StaticResource Text}" />
    <Setter Property="FontFamily" Value="{StaticResource MonoFont}" />
    <Setter Property="FontSize" Value="12" />
  </Style>
  <Style Selector="NumericUpDown /template/ ButtonSpinner">
    <Setter Property="Background" Value="{StaticResource Field}" />
    <Setter Property="BorderBrush" Value="{StaticResource BorderMid}" />
    <Setter Property="BorderThickness" Value="1" />
    <Setter Property="CornerRadius" Value="10" />
    <Setter Property="MinHeight" Value="44" />
  </Style>
  <!--
    The inner box gives its chrome up entirely: the spinner above is drawing the border and the fill, and a
    TextBox that kept its own would put a second rounded rectangle a pixel inside the first.
  -->
  <Style Selector="NumericUpDown /template/ TextBox">
    <Setter Property="Background" Value="Transparent" />
    <Setter Property="BorderThickness" Value="0" />
    <Setter Property="Padding" Value="14,0" />
    <Setter Property="VerticalContentAlignment" Value="Center" />
    <Setter Property="Foreground" Value="{StaticResource Text}" />
    <Setter Property="FontFamily" Value="{StaticResource MonoFont}" />
    <Setter Property="FontSize" Value="12" />
  </Style>
  <!--
    Every box on this head that takes a secret, and it is a class rather than two attributes repeated five
    times because the two attributes are not interchangeable and both are needed.
@@ -473,10 +639,29 @@
    <Setter Property="FontSize" Value="9.5" />
    <Setter Property="FontWeight" Value="SemiBold" />
  </Style>
  <!--
    ◆ Wraps, like .body below it, and the omission was doing real damage rather than none.
    A TextBlock that neither wraps nor trims does not shrink to fit and does not report that it did not:
    it lays out at its full single-line width and the parent clips whatever runs past the edge. So a
    .detail long enough to overflow ended mid-word against the screen, with no ellipsis to say anything
    was missing — "A machine to connect to, filed under a group if you" on the add sheet, which reads as
    a sentence somebody forgot to finish rather than as text that was cut.
    It is a style rather than an attribute on the ones that overflow today, because which of the fifty-odd
    .detail blocks overflows is a function of the device's width and the user's font scale, not of the
    string: every one of them is a candidate at 320dp that is fine at 411dp, and fixing the handful that
    happen to be visibly wrong on a Pixel 5 would leave the rest to be found one narrow phone at a time.
    The nine that genuinely want one line — list rows and log lines, where a wrapped detail would push the
    row's own height around — now say TextWrapping="NoWrap" beside their TextTrimming, which is the pairing
    that was always meant and was previously being had by accident.
  -->
  <Style Selector="TextBlock.detail">
    <Setter Property="FontFamily" Value="{StaticResource MonoFont}" />
    <Setter Property="Foreground" Value="{StaticResource TextFaint}" />
    <Setter Property="FontSize" Value="10" />
    <Setter Property="TextWrapping" Value="Wrap" />
  </Style>
  <Style Selector="TextBlock.body">
    <Setter Property="FontFamily" Value="{StaticResource MonoFont}" />
@@ -551,7 +551,7 @@
                                 Foreground="{StaticResource Accent}"
                                 Background="{StaticResource Raised}" />
                    <TextBlock Classes="detail" Text="{Binding Progress}"
-                               TextTrimming="CharacterEllipsis" />
+                               TextWrapping="NoWrap" TextTrimming="CharacterEllipsis" />
                  </StackPanel>
                  <!--
@@ -49,12 +49,29 @@
            <TextBlock Classes="title" Text="UNKNOWN HOST KEY" FontSize="13" />
            <!--
              ◆ The port and the full stop are one Run, and that is the whole of the fix.
              Avalonia puts a space between adjacent Runs, which is what makes "First contact with", the
              host and the separator read as a sentence without any of them carrying padding. The trailing
              Run began with a full stop, so it got that space too and the sheet said
                  First contact with 10.0.2.2 · 2222 . Nothing in this keychain…
              — a gap before the stop, on the one dialogue in this application whose entire job is to be
              read carefully before somebody answers it. StringFormat welds the stop to the number inside a
              single Run, where no inter-Run space can get in, and the sentence that follows starts a Run of
              its own so it still gets the space it wants.
              The `{}` prefix is required: a StringFormat beginning with a brace would otherwise be parsed
              as a markup extension.
            -->
            <TextBlock Classes="body" Margin="0,6,0,0">
              <Run Text="First contact with" />
              <Run Text="{Binding PendingHostKey.Host}" Foreground="{StaticResource Text}" />
              <Run Text="·" />
-              <Run Text="{Binding PendingHostKey.Port}" />
+              <Run Text="{Binding PendingHostKey.Port, StringFormat='{}{0}.'}" />
-              <Run Text=". Nothing in this keychain has approved this key." />
+              <Run Text="Nothing in this keychain has approved this key." />
            </TextBlock>
            <TextBlock Classes="label" Margin="0,14,0,5" Foreground="{StaticResource TextFaint}"
@@ -465,7 +465,7 @@
                </StackPanel>
                <StackPanel Orientation="Horizontal" Spacing="6">
                  <TextBlock Classes="detail" FontSize="10.5" Text="{Binding Address}"
-                             TextTrimming="CharacterEllipsis" />
+                             TextWrapping="NoWrap" TextTrimming="CharacterEllipsis" />
                  <TextBlock Classes="detail" FontSize="10.5" Text="·" />
                  <TextBlock Classes="detail" FontSize="10.5" Text="{Binding Authentication}" />
                </StackPanel>
@@ -1002,7 +1002,8 @@
                           FormatString="0" ShowButtonSpinner="False" MinHeight="44"
                           PlaceholderText="{Binding EditorPortPlaceholder}" />
            <TextBox Grid.Column="2" Classes="field" Text="{Binding EditorUsername}"
-                     PlaceholderText="{Binding EditorUsernamePlaceholder}" />
+                     PlaceholderText="{Binding EditorUsernamePlaceholder}"
                     IsEnabled="{Binding EditorAsksForLogin}" />
          </Grid>
          <TextBox Classes="field" Text="{Binding EditorNotes}" PlaceholderText="notes" />
@@ -1016,6 +1017,7 @@
          <TextBlock Classes="label" Text="AUTHENTICATION" Margin="0,4,0,0" />
          <ComboBox ItemsSource="{Binding EditorAuthenticationChoices}"
                    SelectedItem="{Binding EditorSelectedAuthentication}"
                    IsEnabled="{Binding EditorAsksForLogin}"
                    HorizontalAlignment="Stretch" MinHeight="44">
            <ComboBox.ItemTemplate>
              <DataTemplate x:DataType="vm:AuthenticationChoice">
@@ -1028,6 +1030,9 @@
              </DataTemplate>
            </ComboBox.ItemTemplate>
          </ComboBox>
          <!-- Why the login is greyed out, as on the desktop. See VaultViewModel.EditorAsksForLogin. -->
          <TextBlock Classes="detail" TextWrapping="Wrap" IsVisible="{Binding !EditorAsksForLogin}"
                     Text="Spelunk signs you in to this host, so it needs no username, SSH key or password." />
          <!--
            Making a credential without leaving the host, as on the desktop and on the same reasoning: the
@@ -1199,19 +1204,53 @@
            port into plaintext columns the server can read, which is the single deliberate concession in
            the design — see ADR 0004 — so it says so rather than being a switch labelled "relay".
-            ◆ AND IT SAYS, FIRST, THAT IT BUYS NOTHING TODAY. The relay's server half is built and this
+            It also says the two things a user would otherwise find out by failing: the server, not this
-            client has no path to it — the connect path dials the address directly whether this is ticked or
+            phone, has to be able to reach the address, and a relayed host does not fall back to dialling
-            not — so the box as it stood spent that concession and delivered nothing for it. Left tickable
+            directly, so it connects only while the server is reachable. See
            rather than disabled, so a host already carrying the flag can lose it. See
            docs/reaching-a-host-you-cannot-dial.md.
          -->
          <CheckBox IsChecked="{Binding EditorRelayEnabled}" MinHeight="44">
            <TextBlock Classes="mono" FontSize="11.5"
-                       Text="Reach this host through the server relay (not wired up yet)"
+                       Text="Reach this host through the server relay"
                       TextWrapping="Wrap" />
          </CheckBox>
          <TextBlock Classes="body"
-                     Text="Not built yet: this app always dials the host itself, so ticking this stores the address on the server and changes nothing about how the host is reached. When it works, the relay will dial on your behalf — which is why the address and port have to be stored in the clear. Everything else about the host stays encrypted either way, and a relayed host needs a port of its own rather than its group's." />
+                     Text="The server dials this host on your behalf, for a machine this phone cannot reach — so the server has to be able to reach it. That is why the address and port are stored on the server in the clear; everything else about the host stays encrypted. A relayed host needs a port of its own rather than its group's, and connects only while you are online." />
          <!--
            The relay's alternative, and the desktop drawer's Spelunk card in this head's controls: ticking
            one unticks the other. The key is a keychain credential chosen here, never typed here. See
            VaultViewModel.Spelunk.cs.
          -->
          <CheckBox IsChecked="{Binding EditorThroughSpelunk}" MinHeight="44">
            <TextBlock Classes="mono" FontSize="11.5"
                       Text="Reach this host through Spelunk"
                       TextWrapping="Wrap" />
          </CheckBox>
          <StackPanel Spacing="8" IsVisible="{Binding EditorThroughSpelunk}">
            <TextBox Classes="field" Text="{Binding EditorSpelunkApi}"
                     PlaceholderText="Spelunk API address (https://api.…)" />
            <TextBox Classes="field" Text="{Binding EditorSpelunkServerId}"
                     PlaceholderText="Spelunk server id" />
            <TextBlock Classes="detail" Text="Spelunk API key" />
            <ComboBox ItemsSource="{Binding EditorSpelunkKeyChoices}"
                      SelectedItem="{Binding EditorSelectedSpelunkKey}"
                      HorizontalAlignment="Stretch" MinHeight="44">
              <ComboBox.ItemTemplate>
                <DataTemplate x:DataType="vm:AuthenticationChoice">
                  <TextBlock Classes="mono" FontSize="12" Text="{Binding Label}" />
                </DataTemplate>
              </ComboBox.ItemTemplate>
            </ComboBox>
            <!-- The desktop card's sign-in box. See SpelunkRoute.SignInThroughSpelunk. -->
            <CheckBox IsChecked="{Binding EditorSpelunkSignIn}" MinHeight="44">
              <TextBlock Classes="mono" FontSize="11.5"
                         Text="Sign in through Spelunk (no SSH key needed)"
                         TextWrapping="Wrap" />
            </CheckBox>
          </StackPanel>
          <TextBlock Classes="body"
                     Text="Spelunk's agent on the server connects to its SSH server for you, so the server needs no open SSH port. Choose a Spelunk API key (Admin role) saved from the desktop's Settings → Security, or a credential whose password is the key; it is sent only to the address above. Signing in through Spelunk logs you in as the account Spelunk names, with a key made for each connection and never kept. Connects only while Spelunk and its agent are reachable." />
          <!--
            This page covers the whole screen while it is open, which is why it needs a Status line of its
@@ -287,7 +287,7 @@
                    </Border>
                  </StackPanel>
                  <!-- What is known *about* an item, never the secret. -->
-                  <TextBlock Classes="detail" Text="{Binding Detail}" TextTrimming="CharacterEllipsis" />
+                  <TextBlock Classes="detail" Text="{Binding Detail}" TextWrapping="NoWrap" TextTrimming="CharacterEllipsis" />
                </StackPanel>
                <TextBlock Grid.Column="2" Text="›" Foreground="{StaticResource TextGhost}" FontSize="15"
@@ -106,11 +106,11 @@
                    <TextBlock Classes="detail" FontSize="10" Text="{Binding HostLabel}"
                               Foreground="{StaticResource TextDim}" VerticalAlignment="Center"
-                               TextTrimming="CharacterEllipsis" />
+                               TextWrapping="NoWrap" TextTrimming="CharacterEllipsis" />
                  </StackPanel>
                  <TextBlock Classes="detail" FontSize="10.5" Foreground="{StaticResource Text}"
-                             Text="{Binding Address}" TextTrimming="CharacterEllipsis" />
+                             Text="{Binding Address}" TextWrapping="NoWrap" TextTrimming="CharacterEllipsis" />
                  <!--
                    TextDim rather than the `detail` class's own faint step. This block is drawn on
@@ -124,7 +124,7 @@
                    <TextBlock Classes="detail" FontSize="9.5" Foreground="{StaticResource TextDim}"
                               Text="·" />
                    <TextBlock Classes="detail" FontSize="9.5" Foreground="{StaticResource TextDim}"
-                               Text="{Binding DeviceName}" TextTrimming="CharacterEllipsis" />
+                               Text="{Binding DeviceName}" TextWrapping="NoWrap" TextTrimming="CharacterEllipsis" />
                  </StackPanel>
                  <!-- A refused host key is the one outcome worth a colour of its own. -->
@@ -158,7 +158,7 @@
                  </StackPanel>
                  <TextBlock Classes="detail" FontSize="10.5" Foreground="{StaticResource Text}"
-                             Text="{Binding ItemLabel}" TextTrimming="CharacterEllipsis" />
+                             Text="{Binding ItemLabel}" TextWrapping="NoWrap" TextTrimming="CharacterEllipsis" />
                  <!-- The names of the fields that changed, never their values. -->
                  <TextBlock Classes="detail" FontSize="9.5" IsVisible="{Binding HasChangedFields}"
@@ -189,14 +189,18 @@
          ◆ Port forwarding, stated rather than drawn.
          The v2 design gives this hub a sixth entry and a full screen behind it: local, remote and dynamic
-          rules with toggles and byte counters. Nothing in this application forwards anything — ISshConnection
+          rules with toggles and byte counters. Forwarding is built and runs here as on the desktop — a host's
-          offers OpenShellAsync and nothing else — so every switch on that screen would be a control with no
+          forwards start with every terminal opened to it — but it is not a destination, so it has no row. A
-          effect and every counter a number with no source.
+          forward belongs to a host and runs with a session, and on this head the session's forwards are a
          sheet off the terminal's bar: the ⇄ button, drawn for a tab that has some, lists them with a switch
          each. See MainWindowViewModel.IsForwardsSheetOpen.
          What the phone lacks is the editor: its host form has no PORT FORWARDS section yet, so forwards are
          added on the desktop and arrive here with the host. The byte counters are not built anywhere;
          SSH.NET keeps no count to draw.
          It is a paragraph here rather than a missing row for the reason the desktop keeps TEAMS in its rail:
-          a destination that is quietly absent reads as a product that never intended it, and this one is
+          a place somebody looks for a feature should say where it went. See docs/design-import-gaps.md.
          intended. SyncEntityType.PortForward = 9 is reserved on the wire and unused. See
          docs/design-import-gaps.md.
        -->
        <Border Classes="card" Margin="6,16,6,0">
          <StackPanel Spacing="7">
@@ -206,11 +210,11 @@
              <TextBlock Classes="mono" FontSize="13.5" FontWeight="SemiBold"
                         Foreground="{StaticResource TextDim}" Text="Port forwarding" />
              <Border Classes="tag outline" VerticalAlignment="Center">
-                <TextBlock Text="NOT BUILT" />
+                <TextBlock Text="IN THE TERMINAL" />
              </Border>
            </StackPanel>
            <TextBlock Classes="body"
-                       Text="A connection here opens one channel — a shell — and nothing else, so there is no tunnel for a rule to run through. The wire protocol reserves a slot for forwarding rules and no client writes one. Nothing on this screen is hidden by a setting; the feature is absent." />
+                       Text="Forwards saved on a host start with every terminal opened to it, here as on the desktop. The ⇄ button in the terminal's bar lists them, with a switch each and the reason one could not start. They are added and edited in the desktop app's host editor; this phone runs them but has no editor for them yet." />
          </StackPanel>
        </Border>