fix(web): require an available machine for SSH terminals

.changeset/clear-segmented-selection.md

@@ -0,0 +1,5 @@
+---
+"@internal/server": patch
+---
+
+Make selected tabs and segmented choices clearly visible throughout the web interface, including Terminal / Desktop App. Choices retain their original icons with the stronger selected highlight.

.changeset/node-ssh-capability-gate.md

@@ -0,0 +1,6 @@
+---
+"@internal/server": minor
+"@internal/node": minor
+---
+
+Per-node SSH capability gate: a new ssh_enabled flag (migration 0047) defaults off on every machine including the control-plane host, owners flip it at PUT /api/nodes/:id/ssh-enabled (admins on the server row) audited as node.ssh_enabled.update, the node caches the value in a mirror file it reads only to refuse, and the node protocol bumps to 16: update the server before the nodes, because the link gate is exact-match and a lagging agent is held (offline for every purpose but update) until it crosses the bump on the update command. The ported foundations (OpenSSH config discovery, ssh -G snapshot resolution, the isolated sshd e2e fixture) land with it; nothing launches SSH yet.

.changeset/ssh-destination-first-ui.md

@@ -0,0 +1,18 @@
+---
+"@internal/server": minor
+"@internal/server-web": minor
+---
+
+The Connect page: one question first - where do you want to work? Pick a
+destination from your remembered hosts, your recent ones, or the connecting
+machine's SSH config aliases, or type any host; one button opens the pane.
+The connecting machine defaults to your chosen one, machines whose SSH is off
+stay named with the remedy rather than silently skipped, and a config that
+needs settings Subshell does not run shows which ones blocked. SSH-terminal
+panes now read as view-only to everyone but their owner everywhere the pane
+is shown (the server's view says so, so the terminal is honestly read-only),
+and the pane's header labels itself SSH and tells a viewer why typing is off.
+
+Milestone 1 of the SSH-anywhere design is complete with this: an operator on
+an enabled machine opens an interactive session at any sshd-only host, and no
+private key or plaintext challenge ever crosses the plane.

.changeset/ssh-in-subshells.md

@@ -0,0 +1,5 @@
+---
+"@internal/server": patch
+---
+
+Open SSH terminals from New subshell, workspace additions, and splits. Explain the destination and connecting machine, move alternate keys under advanced options, and approve keys inside the launch dialog without losing workspace context. Existing Connect links open the shared subshell launcher. The selected subshell type has a distinct highlight, with initial focus following the selected type.

.changeset/ssh-launcher-tier.md

@@ -0,0 +1,30 @@
+---
+"@internal/server": minor
+"@internal/node": minor
+"@internal/subshell-protocol": minor
+"@internal/pane-runtime": minor
+"@internal/server-web": minor
+"@internal/mobile": minor
+---
+
+SSH launcher tier: an enabled node can open interactive SSH-terminal panes at any
+sshd host. `GET /api/ssh/aliases` and `POST /api/ssh/resolve` answer alias discovery
+and `ssh -G` normalization on the connecting machine; `POST /api/ssh/launch` composes
+the pane from the approved snapshot (rendered `-F` config, every-hop confinement
+policy, host keys trusted `accept-new` in the connecting machine's own
+`known_hosts`); saved/recent hosts and a default connecting machine live on the
+plane keyed by the resolved destination. SSH-terminal panes accept input from their
+owner alone (sharees view). The per-node `ssh_enabled` gate from the previous tier
+refuses every one of these doors until the owner turns it on. A launch form with no
+prior choice still defaults to the plain Terminal rather than to SSH, whose bare
+launch has no destination to open; SSH stays pickable, and a preset names its own
+agent.
+
+Deployment: update the server before the nodes. The link gate is exact-match at
+protocol 17, so a lagging agent is held (offline for every purpose but update)
+until it crosses the bump on the update command. Nothing changes for anyone until
+a node's gate is enabled.
+
+Known limitation: keystrokes typed during the initial ssh handshake can be
+swallowed before the remote shell reaches its prompt; the pane is fully usable
+once connected.

.changeset/ssh-machine-availability.md

@@ -0,0 +1,5 @@
+---
+"@internal/server": patch
+---
+
+Block SSH creation when no connecting machine is ready, with setup guidance and links to machine settings. Reject stale machine choices and explain loading failures separately.

.changeset/ssh-relay-browser-journey.md

@@ -0,0 +1,5 @@
+---
+"@internal/server": patch
+---
+
+Choose another machine's SSH keys from Connect, return to the original connection after approval, and distinguish failed settings reads from empty lists. SSH destination setup now shows progress and can be closed and reopened without starting another installation.

.changeset/ssh-relay-milestone-2.md

@@ -0,0 +1,17 @@
+---
+"@internal/server": major
+"@internal/node": major
+"@internal/subshell-protocol": major
+"@internal/pane-runtime": major
+"@internal/server-web": major
+"@internal/node-web": major
+"@internal/node-admin": major
+"@internal/backend-errors": major
+"@internal/mobile": major
+---
+
+SSH sealed agent relay (milestone 2): a machine that holds no keys can open an SSH-terminal pane anywhere its operator's key home can reach. The connecting machine's node binds a per-pane ssh-agent proxy socket (the pane's scoped `SSH_AUTH_SOCK`, unbound at teardown); every agent request is sealed machine-to-machine over the plane, which brokers the pairing and routes opaque envelopes by a routing ref and nothing else. The key home's responder probes the live agent's numbering (OpenSSH classic vs RFC 9987, learned per session, never assumed), forwards only `REQUEST_IDENTITIES` and `SIGN_REQUEST`, and scopes both to the grant's selected fingerprints. Origin rides an ES256 signature inside the sealed envelope; endpoint-contributed nonces and a monotonic per-direction sequence make every relayed byte replay-inert. Grants (`ssh_key_grants`) bind a key home to a destination selector; the first use of a new pair asks the key home's owner to approve (a durable `ssh_grant_requests` row plus an owner notification, a loud fail-fast refusal, never a hung pane), the approval records the chosen public fingerprints and captures the destination's host-key pin from the key home's own `known_hosts`, and revocation is instant both ways. Panes verify D against a per-session pinned `known_hosts` delivered on the signed relay-open (`StrictHostKeyChecking yes`, system-wide file disabled); a changed destination host key is a hard block and delete-plus-fresh-capture is the operator's TOFU recovery. Machine identity: every agent node carries an ES256 signing keypair reported at enroll, peers pin each other's signing AND encryption halves byte-equal in a store separate from channel pins, and the node's loopback dashboard and the machine trust card show the fingerprints for the out-of-band comparison. "Set up Subshell here" turns an open pane's destination into an enrolled node by driving the ordinary install one-liner over a separate non-interactive ssh exec, so the minted setup key never reaches the pane screen or its log; an installer line carrying a key is redacted twice over. The grants screen, the destination trust screen, and the launcher's key-home picker complete the surface.
+
+Deployment: update the server before the nodes. The link gate is exact-match at protocol 18, so an agent that has not crossed the bump is held and takes no relay traffic. Migrations 0049 through 0052 add the signing-key slots, the grants, the pending-approval rows, the host-key pins, and the pane's key-home column; never run them against a live database without a full archive. Nothing changes for anyone until a node's SSH gate is enabled and a launch names a key home.
+
+Proof: e2e spec 23 (the crown jewel) drives the whole path against a real `ssh-agent`, a real `sshd`, real node daemons, and the real broker, with a plane-side capture asserting only opaque envelopes cross, and the 10.x numbering, the fingerprint scope, the revoke cut, the lifetime cap, the setup-key redaction, and the changed-host-key block plus TOFU recovery all asserted end to end.

.changeset/ssh-stack-review.md

@@ -0,0 +1,10 @@
+---
+"@internal/server": patch
+"@internal/node": patch
+"@internal/desktop-client": patch
+"@internal/desktop-server": patch
+---
+
+Fix SSH saved destination ports, jump-host alias resolution, identity paths containing spaces, and multiple known-hosts files. Host-key capture now selects keys for the exact destination port. Approval return links identify the exact request, and enrollment without a confirmed connection links to the enrolled node instead of offering another installation.
+
+Connections using another machine's keys now explain that ProxyJump and HostKeyAlias are unsupported before requesting approval. Direct connections refuse jump-specific authentication or trust settings that cannot be preserved.

.claude/rules/design-system.md

@@ -46,7 +46,9 @@ fields. Name-length limits and historical specs aren't exceptions. Follow
 the [content guide](../../apps/docs/STYLE.md#product-copy-and-confirmations)
 for action labels, consequences, and examples.
 **A required input takes a gold `*` at rest and a gold caption once the caret
-leaves it empty; a hard error (a refused value, a server refusal) stays
+leaves it empty; a required control with no caret-leave moment (a picker whose
+nothing-picked state disables the submit) wears the gold caption at rest once
+its options settle; a hard error (a refused value, a server refusal) stays
 `text-destructive` red** (ruling 2026-09-30: gold says "nothing typed yet",
 red says "what you typed is wrong"; `fieldErrorToned` reads the split).
 **There is no 12px**: `detail` (13) is the floor, and `text-xs` /

.claude/rules/security-context.md

@@ -164,7 +164,7 @@ Per-app mechanics (command lists and shapes, assistant screens, the reset path,
 
 Read via `GET /api/audit?limit=50` (admin). Rules: auth-family metadata carries method and ids, NEVER tokens/emails/IPs/UAs; the user-management family names its subject by email by convention (§3). Sign-in rows are SUCCESS only (failures write nothing so the trail can't be spam-DoSed); `auth.sign_out` is one row per session ended; trusted-origin probes write no row.
 
-Auth `auth.sign_in` / `auth.sign_out` · users/keys `user.create|role_change|password_reset|disabled_change|approve|reject`, `system-key.create|enable|disable|delete`, `emergency_login.rewrite_credential`, `setup_key.create` (no metadata) / `setup_key.revoke`, `settings.update` · auth providers `auth_provider.create|update|delete` (fields + issuer, never the secret) · subshells `subshell.create|terminate|restart|preset_switch|delete` · transfers `transfer.create|complete` (node ids, paths, byte and entry counts, sync flag, outcome; never contents) · nodes `node.enroll|delete|rename|key_rotate|reregister_key|reregister|allowed_dirs.update|config.update|maintenance.update|logging.update|update|update.unknown|shares_set|local_share_changed|service` · server `server.config.update|restart|logging.update|autostart.update|update|supervision.request` · plugins/networks/installers `plugin.install|enable|disable|uninstall|unpublish`, `network.configure|install|join|publish|unpublish|leave`, `agent.install`, `tmux.install`. Per-event metadata detail: §10.
+Auth `auth.sign_in` / `auth.sign_out` · users/keys `user.create|role_change|password_reset|disabled_change|approve|reject`, `system-key.create|enable|disable|delete`, `emergency_login.rewrite_credential`, `setup_key.create` (no metadata) / `setup_key.revoke`, `settings.update` · auth providers `auth_provider.create|update|delete` (fields + issuer, never the secret) · subshells `subshell.create|terminate|restart|preset_switch|delete` · transfers `transfer.create|complete` (node ids, paths, byte and entry counts, sync flag, outcome; never contents) · nodes `node.enroll|delete|rename|key_rotate|reregister_key|reregister|allowed_dirs.update|config.update|maintenance.update|ssh_enabled.update|ssh_identity.register (signing-key bootstrap over the link, ids + via only, never the key)|ssh_grant.request|ssh_grant.create (via first-use|manual; approve/create name the CHOSEN fingerprint VALUES + destination per spec §10 - the approve row is the only durable record of the operator's selection, and a fingerprint appears in NO log line or notification body)|ssh_grant.update|ssh_grant.delete (relaysClosed; the revoke also cuts live relays via closeForGrant "grant-revoked")|ssh_grant.approve|ssh_grant.deny (audit-only; grant-request expiry writes nothing)|ssh_relay.open|ssh_relay.close (plane rows, actorUserId null, named reason word, fingerprint COUNT only)|ssh_upgrade.run (the "Set up Subshell here" act, Task 14: pane/B/A/grant ids, canonical destination, exec id, outcome + service-chosen stage word; the minted setup key and ALL installer output appear in NO row and NO refusal copy)|logging.update|update|update.unknown|shares_set|local_share_changed|service`, and the SSH launcher's `ssh.launch` `{nodeId, destination, subshellId, grantId on a relay launch}` (success only, written after the pane spawned; the canonical `host:port`, never config or key material; saved-host CRUD unaudited, the prompts precedent) · server `server.config.update|restart|logging.update|autostart.update|update|supervision.request` · plugins/networks/installers `plugin.install|enable|disable|uninstall|unpublish`, `network.configure|install|join|publish|unpublish|leave`, `agent.install`, `tmux.install`. Per-event metadata detail: §10.
 
 ## Deliberate non-validation & accepted risks
 

.github/workflows/test.yml

@@ -927,16 +927,49 @@ jobs:
       - name: Trust the bind-mounted workspace
         run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
 
-      # The session-lifecycle spec spawns real tmux sessions (stub harness).
-      - name: Ensure tmux and jq
+      # Spec 12 (session lifecycle) spawns real tmux sessions (stub harness);
+      # spec 22 (ssh terminal) drives a REAL sshd plus an ssh client. Neither
+      # OpenSSH binary is in the builder image; installing here rather than
+      # in the image keeps the shared image lean. The container job runs as
+      # root, so apt-get needs no sudo. Tools map to PACKAGES, not names:
+      # "ssh" is not an apt package (openssh-client ships ssh + ssh-keygen;
+      # openssh-server ships sshd), so the missing binaries are translated
+      # before the deduped set is installed.
+      - name: Ensure tmux, jq, and OpenSSH
         run: |
           set -euo pipefail
-          missing=()
-          for tool in tmux jq; do command -v "$tool" >/dev/null || missing+=("$tool"); done
-          if [ ${#missing[@]} -gt 0 ]; then
-            apt-get update && apt-get install -y --no-install-recommends "${missing[@]}"
+          pkg_for() {
+            case "$1" in
+              tmux) echo tmux ;;
+              jq) echo jq ;;
+              ssh|ssh-keygen) echo openssh-client ;;
+              sshd) echo openssh-server ;;
+            esac
+          }
+          missing_pkgs=()
+          for tool in tmux jq ssh ssh-keygen sshd; do
+            command -v "$tool" >/dev/null && continue
+            pkg="$(pkg_for "$tool")"
+            for p in "${missing_pkgs[@]+"${missing_pkgs[@]}"}"; do
+              [ "$p" = "$pkg" ] && continue 2
+            done
+            missing_pkgs+=("$pkg")
+          done
+          if [ ${#missing_pkgs[@]} -gt 0 ]; then
+            apt-get update && apt-get install -y --no-install-recommends "${missing_pkgs[@]}"
+          fi
+          tmux -V && jq --version && ssh -V
+          # sshd -V prints usage and exits nonzero on some builds, so the
+          # presence proof is the binary: on PATH, else the package's
+          # documented location (the fixture probes /usr/sbin too).
+          command -v sshd || ls -l /usr/sbin/sshd
+          # Loud post-install assertion: an apt package rename would
+          # otherwise surface only as spec 22 skipping, i.e. the proof
+          # silently not running.
+          if ! command -v sshd >/dev/null && [ ! -x /usr/sbin/sshd ]; then
+            echo "::error::openssh-server present in no sshd location (PATH or /usr/sbin/sshd)"
+            exit 1
           fi
-          tmux -V && jq --version
 
       # tsdown/rolldown run under NODE, not bun — their bin shebang is
       # `#!/usr/bin/env node` — so the repo has always had a Node requirement

apps/client/mobile/src/__tests__/push-routing.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "bun:test";
+import { decidePushAction, SETTINGS_HREF } from "../lib/push-routing";
+
+/**
+ * The tap/action decision behind a push (PR #338 review, Important 1): a
+ * `grant_approval` push carries the grant REQUEST uuid as `sid`, so the old
+ * blind push to `/subshell/<sid>` was a 404 dead-end and its Silence bell
+ * PATCHed a nonexistent subshell. `push-bridge` keeps the side effects; this
+ * pure helper owns the choice, which is all the regression needs pinning.
+ */
+describe("decidePushAction", () => {
+  it("grant_approval tap routes to the settings tab, never a phantom pane", () => {
+    const a = decidePushAction({ sid: "req-uuid", kind: "grant_approval", origin: "https://a" }, undefined);
+    expect(a).toEqual({ action: "route", href: SETTINGS_HREF });
+    expect(JSON.stringify(a)).not.toContain("/subshell/");
+    // The settings tab must be the spelled group route the app itself uses.
+    expect(SETTINGS_HREF).toBe("/(tabs)/settings");
+  });
+
+  it("grant_approval silence is ignored: no PATCH intent against a request id", () => {
+    const a = decidePushAction({ sid: "req-uuid", kind: "grant_approval", origin: "https://a" }, "silence");
+    expect(a).toEqual({ action: "ignore" });
+  });
+
+  it("pane kinds tap to /subshell/<sid>, encoded, unchanged", () => {
+    const a = decidePushAction({ sid: "sess-1", kind: "turn_complete", origin: "https://a" }, undefined);
+    expect(a).toEqual({ action: "route", href: "/subshell/sess-1" });
+    expect(decidePushAction({ sid: "a b", kind: "needs_attention" }, "open")).toEqual({
+      action: "route",
+      href: "/subshell/a%20b",
+    });
+  });
+
+  it("pane kinds silence asks for the bell PATCH with the sid", () => {
+    expect(decidePushAction({ sid: "sess-1", kind: "needs_attention" }, "silence")).toEqual({
+      action: "silence",
+      sid: "sess-1",
+    });
+  });
+
+  it("a pane payload with no sid is ignored (the pre-existing guard)", () => {
+    expect(decidePushAction({ kind: "turn_complete", origin: "https://a" }, undefined)).toEqual({
+      action: "ignore",
+    });
+    expect(decidePushAction({ kind: "exited" }, "silence")).toEqual({ action: "ignore" });
+  });
+});

apps/client/mobile/src/lib/__tests__/agent-default.test.ts

@@ -47,6 +47,19 @@ describe("defaultAgentId", () => {
     expect(defaultAgentId([TERMINAL, CLAUDE, CODEX], ALL_INSTALLED, null)).toBe("claude-code");
   });
 
+  it("a second terminal-type plugin does not steal the shell default", () => {
+    // Web mirror (CI e2e 2026-10-08): the catalog arrives id-sorted, so
+    // `ssh` (also type terminal, binary nearly always present) stands before
+    // `terminal`; the last resort must still land on the plain shell, which
+    // runs presetless, not on a bare `ssh` that exits without a host.
+    const SSH = plugin({ id: "ssh", name: "SSH", type: "terminal" });
+    expect(defaultAgentId([SSH, TERMINAL], ALL_INSTALLED, null)).toBe("terminal");
+    // A declared agent still outranks the shell tier.
+    expect(defaultAgentId([SSH, TERMINAL, CLAUDE], ALL_INSTALLED, null)).toBe("claude-code");
+    // The shell tier is a preference, not a filter: ssh alone still fills.
+    expect(defaultAgentId([SSH], ALL_INSTALLED, null)).toBe("ssh");
+  });
+
   it("a missing type (older server) is still pickable, but no longer outranks a declared agent", () => {
     // The middle tier reads `=== "agent-harness"` rather than
     // `!== "terminal"` now, because a third type exists (network) and an