SSH remote runtime: work on a destination over SSH as an ordinary Subshell session (replaces the destination-execution model)

.changeset/remote-work-launch-flow.md

@@ -0,0 +1,6 @@
+---
+"@internal/server": patch
+"@internal/desktop-server": patch
+---
+
+Choose an SSH host when creating a subshell or workspace pane, reuse existing connections, and reconnect from remote panes. Keep connection management secondary to starting work. Allow administrators to connect through the server machine's SSH account without enrolling another node, and deliver initial prompts to remote agents.

.changeset/settings-navigation.md

@@ -0,0 +1,6 @@
+---
+"@internal/server": patch
+"@internal/desktop-server": patch
+---
+
+Move Nodes, Presets, and Prompts into the Settings navigation group.

.changeset/ssh-connections-label.md

@@ -0,0 +1,8 @@
+---
+"@internal/server": patch
+"@internal/desktop-server": patch
+"@internal/desktop-client": patch
+"@internal/docs": patch
+---
+
+Rename the personal Connections navigation item to SSH Connections and update setup instructions to match.

.changeset/ssh-friendly-copy.md

@@ -0,0 +1,6 @@
+---
+"@internal/server": patch
+"@internal/desktop-server": patch
+---
+
+Make SSH setup, pairing, and connection errors clearer and more conversational, with plain-language next steps.

.changeset/ssh-personal-connections.md

@@ -0,0 +1,9 @@
+---
+"@internal/server": minor
+"@internal/desktop-server": minor
+"@internal/node": minor
+"@internal/desktop-client": minor
+"@internal/docs": patch
+---
+
+Add personal SSH connections from Subshell Client without node enrollment, saved remote folders, actionable host setup, and in-place pane reconnection. Keep browser connections through owned nodes and authorized server accounts.

.changeset/ssh-setup-guidance.md

@@ -0,0 +1,6 @@
+---
+"@internal/server": patch
+"@internal/desktop-server": patch
+---
+
+Show SSH setup help only when needed, with copyable configuration and recovery commands. Keep launch actions visible while forms scroll and hide launch buttons until SSH is connected.

.changeset/ssh-support-docs.md

@@ -0,0 +1,5 @@
+---
+"@internal/docs": minor
+---
+
+A new SSH connections section: human setup on a node, the per-pane grant model, route identity, and the honest no-replay, takeover-controls-input-not-secrecy, and output-is-data rules, plus what v1 does not do. The MCP tool reference gained the five SSH tools and get_terminal_execution, the exec_in_terminal entry teaches the durable executionId and its late-result recovery, terminal sessions and the MCP overview point at the managed SSH loop, and the security model documents the SSH controls as section 4b.

.changeset/ssh-support.md

@@ -0,0 +1,6 @@
+---
+"@internal/server": minor
+"@internal/node": minor
+---
+
+Agents can work on plain SSH machines: a human saves an SSH connection through an enrolled node (aliases discovered from the node's config, destination resolved and tested, nothing but an approved normalized snapshot stored), grants it to individual running panes, and the granted pane can run structured commands with bounded incremental output and honest lifecycle, cancel them, and open managed interactive SSH terminals whose input and output ride the ordinary pane tools. The five MCP SSH tools plus get_terminal_execution and the /api/ssh routes carry it; machine credentials cannot configure anything, every generic pane surface asks the same SSH policy, and sharing managed panes is refused in v1. Nothing is ever replayed after an ambiguous disconnect (a lost answer stays `accepted`, reconciliation asks, never restarts), exit 255 is never claimed as a confirmed remote result, and cancellation confirms only the local process stopped. Commands run under a mandatory every-hop policy (strict host checking, no forwarding, no escape characters, no control sockets, key/certificate auth only); credentials, config contents, command text, and output never reach the server, its logs, or the audit trail. The node protocol becomes 16 to carry the nine ssh_* commands, so update the server before the nodes: a lagging agent is held and crosses the bump on the update command.

.github/workflows/test.yml

@@ -928,15 +928,24 @@ jobs:
         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 21's real-sshd composition needs ssh, ssh-keygen and sshd: the
+      # builder image carries none of them, so WITHOUT these the SSH specs
+      # loud-skip on every CI run - an honest skip, but a flagship suite that
+      # silently never runs is what e2e/AGENTS.md promises against. The
+      # fixture daemon's privilege-separation dir (/run/sshd) is NOT created
+      # by the postinst in this non-systemd container (measured on the exact
+      # image); the fixture itself ensures it before spawning.
+      - 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
+          { command -v ssh >/dev/null && command -v ssh-keygen >/dev/null; } || missing+=(openssh-client)
+          command -v sshd >/dev/null || [ -x /usr/sbin/sshd ] || missing+=(openssh-server)
           if [ ${#missing[@]} -gt 0 ]; then
             apt-get update && apt-get install -y --no-install-recommends "${missing[@]}"
           fi
-          tmux -V && jq --version
+          tmux -V && jq --version && ssh -V && ls -x /usr/sbin/sshd
 
       # 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/desktop/AGENTS.md

@@ -430,7 +430,9 @@ plan parsed from the node's own `status --json` `paths` block AT PRESS TIME
 with `config.json` deleted LAST so a half-run stays resumable
 (`deletion_order` is a tested pure function), the shared guards in
 `subshell_desktop_core::reset_guards`, and `Err` only for refusals before
-the first mutation. `planeUrl` is KEPT. **Working on reset: read
+the first mutation. Saved control planes are cleared. Desktop SSH children
+are stopped and their saved credentials and connection metadata are removed
+before deleting node config; failed cleanup remains retryable. **Working on reset: read
 `apps/client/desktop/docs/reset.md` first.**
 
 ## Things that will bite
@@ -536,3 +538,19 @@ the first mutation. `planeUrl` is KEPT. **Working on reset: read
   plum here, near-black for the server), which is also why the tray icon is
   NOT `icon_as_template(true)` on macOS: a template icon is drawn from the alpha
   channel alone and both would collapse to the same filled square.
+
+## Desktop SSH connections
+
+The bundled assistant's **SSH Connections** screen pairs this computer with a
+signed-in server account without node enrollment. A first-run SSH choice reaches
+it directly. The server-loaded main window still has exactly one command;
+`node_ssh_*` permissions belong only to `capabilities/node.json`.
+
+`src-tauri/src/ssh.rs` starts the bundled `subshell ssh-broker` child (resolved
+CLI fallback in development), passes pairing codes over stdin, and retains that
+pipe for the child's lifetime. EOF or a stop line drains the broker's SSH children.
+The CLI holds private, origin-bound credentials; native metadata stores only the
+server, broker id, and display name. Pairing also remembers the server bookmark,
+so an SSH-only client remains configured after restart. Disconnected connections
+are resumed explicitly from the bundled screen. See the public procedure at
+`apps/docs/content/docs/ssh/index.mdx`.

apps/client/desktop/docs/reset.md

@@ -38,9 +38,16 @@ binary where its own data lived.
   manage window and a zero-window moment quits it; resetting a node here
   invalidates neither of this app's windows, and the page's own re-probe lands
   it on Enroll.
-- **`planeUrl` is KEPT.** The control plane this person watches is not what they
-  reset; making them retype its address to get their dashboard back would be
-  the reset reaching past what it promised.
+- **Saved control planes are cleared**, including the last-open memory, so a
+  successful reset returns to first run (operator ruling 2026-09-22).
+- **Desktop SSH access is removed before node config deletion.** Reset stops
+  every broker child, calls the CLI's idempotent `ssh-broker --forget` for each
+  remembered connection, and clears native connection metadata. A failure
+  keeps the metadata and node config so Retry can complete. The connection
+  lock remains held until reset returns, and concurrent pairing refuses.
+  Remote panes stay running; SSH keys and config are untouched. An SSH-only
+  client has no node delete plan: the dialog directs it to SSH Connections →
+  Disconnect → Forget instead.
 - **Channel discipline:** `Err` only for refusals BEFORE the first mutation. A
   half-run is `Ok(ActionResult { ok: false })` with the verbatim log and the
   plan still stashed, so a Retry converges.

apps/client/desktop/src-tauri/capabilities/node.json

@@ -28,6 +28,10 @@
     "allow-node-about",
     "allow-node-open-web",
     "allow-node-check-app-update",
-    "allow-node-install-app-update"
+    "allow-node-install-app-update",
+    "allow-node-ssh-connections",
+    "allow-node-ssh-connect",
+    "allow-node-ssh-disconnect",
+    "allow-node-ssh-forget"
   ]
 }

apps/client/desktop/src-tauri/permissions/desktop.toml

@@ -129,3 +129,24 @@ commands.allow = ["node_install_app_update"]
 identifier = "allow-desktop-open-in-browser"
 description = "Open one page of the control plane this window is already on, in the system browser. `desktop_`, not `node_`, because it is the one permission in this file that is NOT a node verb: it is granted to `main` (the plane's own page) and to nothing else, which is the opposite of every rule above it. It takes a PATH and nothing else (no scheme, no protocol-relative '//host', no backslash, no whitespace or control characters; see crates/desktop-core's browser::browser_url) and joins it onto the origin windows.rs's PlanePin holds, so the page names the route and this side names the host. The tray and menu-bar routes to the same act need no permission at all: they run in Rust."
 commands.allow = ["desktop_open_in_browser"]
+
+
+[[permission]]
+identifier = "allow-node-ssh-connections"
+description = "Bundled page only: read this computer's SSH connections."
+commands.allow = ["node_ssh_connections"]
+
+[[permission]]
+identifier = "allow-node-ssh-connect"
+description = "Bundled page only: connect this computer to a reviewed server for SSH."
+commands.allow = ["node_ssh_connect"]
+
+[[permission]]
+identifier = "allow-node-ssh-disconnect"
+description = "Bundled page only: disconnect this computer's SSH transport."
+commands.allow = ["node_ssh_disconnect"]
+
+[[permission]]
+identifier = "allow-node-ssh-forget"
+description = "Bundled page only: remove a local SSH connection credential."
+commands.allow = ["node_ssh_forget"]

apps/client/desktop/src-tauri/src/lib.rs

@@ -16,6 +16,7 @@ mod app_update;
 mod control;
 mod node_bin;
 mod reset;
+mod ssh;
 // macOS only: a GTK menu bar is per-window chrome rather than a system bar, so
 // Linux has none — and a module compiled there would be entirely dead code.
 // Gated at the MODULE, never at the call site, so `cargo clippy` on Linux sees
@@ -162,7 +163,12 @@ pub fn run() {
         .manage(windows::PlanePin::new())
         .manage(windows::PendingScreen::new())
         .manage(reset::Stash::default())
+        .manage(ssh::SshState::default())
         .invoke_handler(tauri::generate_handler![
+            ssh::node_ssh_connections,
+            ssh::node_ssh_connect,
+            ssh::node_ssh_disconnect,
+            ssh::node_ssh_forget,
             control::node_probe,
             control::node_install_cli,
             control::node_install_tmux,
@@ -265,6 +271,7 @@ pub fn run() {
             // from the Dock, only from the tray.
             #[cfg(target_os = "macos")]
             tauri::RunEvent::Reopen { .. } => windows::focus_any(app),
+            tauri::RunEvent::Exit => ssh::shutdown(app),
             _ => {}
         });
 }

apps/client/desktop/src-tauri/src/reset.rs

@@ -235,6 +235,20 @@ pub fn node_reset(app: AppHandle, settings: State<'_, SettingsState>, typed: Str
             ),
         });
     }
+    // Desktop SSH is independent of node enrollment. Remove its authority
+    // before config.json, preserving the staged node plan for a failed retry.
+    // The guard prevents a new pairing until the entire reset has returned.
+    let _ssh_reset = match crate::ssh::reset_access(&app) {
+        Ok(guard) => guard,
+        Err(stderr) => {
+            return Ok(ActionResult {
+                ok: false,
+                stdout: log,
+                stderr,
+            })
+        }
+    };
+    log.push_str("disconnected desktop SSH and removed saved SSH credentials\n");
     // 4. Delete, absence = done, config.json last. Every deletion's failure
     // ends the chain: a surviving node key announced as a completed reset is
     // worse than a refusal, because the hostname was typed against the promise