Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs(windows): native SSH transport options, -L forwards and the shared ssh resolver

review243daec7e5f0
diff --git a/CLAUDE.md b/CLAUDE.md
index 640506558..a662c3448 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8440,8 +8440,8 @@ carrying `ControlPath` FAILS rather than falling back — so every remote comman
tunnel of an SSH project failed on a stock Windows machine. Git for Windows' ssh (10.5p1) starts a
master but every session over it is reset and falls back to a full login per command. So on
Windows the app does not run the ssh binary for SSH projects at all: `src/core/remote-ssh/native/`
-holds ONE `ssh2` connection per ControlPath and carries every exec, pty, SFTP session and reverse
-unix-socket forward over it. POSIX keeps OpenSSH untouched.
+holds ONE `ssh2` connection per ControlPath and carries every exec, pty, SFTP session, reverse
+unix-socket forward and dev-server `-L` forward over it. POSIX keeps OpenSSH untouched.
- **One switch:** `useNativeSsh()` — always on win32; `NODETERM_NATIVE_SSH=1` turns it on anywhere
(how it is tested live from macOS against a real host), `=0` forces it off. Decided once per app
@@ -8483,7 +8483,33 @@ unix-socket forward over it. POSIX keeps OpenSSH untouched.
overflow connections REUSE the primary's chain (one bastion login; direct-tcpip does not count
against the bastion's MaxSessions); one-off connections build their own. Known hosts are checked
under `HostName` (or `HostKeyAlias`), as OpenSSH does — not under the alias as typed.
- **ProxyCommand stays refused by name**, on the target and on a hop.
+ **ProxyCommand** (`proxy-command.ts`) runs on the target or the FIRST hop, as OpenSSH does:
+ `%h %p %r %n %k %%` expanded (an unknown `%x` is an error by name), POSIX `sh -c 'exec …'`,
+ Windows `cmd.exe /d /s /c`, the child's stdio is the socket, its stderr is in the connect error,
+ ConnectTimeout covers the wait for its first byte, and it is killed with the connection.
+ `ProxyUseFdpass yes` is refused by name. ProxyJump wins when `ssh -G` prints both.
+- **Other honored `~/.ssh/config` options:** `ForwardAgent` (yes / path / `$VAR`) — requested on
+ the TARGET connection's PTY channels only, never on a hop or a background exec/SFTP channel (that
+ would hand the agent to every status probe), and a server that refuses it costs one log line, not
+ the terminal. Options it does NOT honor (`certificatefile`, config `Local/Remote/DynamicForward`)
+ are named in ONE warning per connection (`UNSUPPORTED_OPTIONS`), never silently dropped; user and
+ `@cert-authority` certificates are a later phase.
+- **`-L` dev-server forwards** (`NativeMux.forwardLocal`): the parser accepts ONLY the loopback spec
+ `localFwdSpec` emits; a duplicate spec is re-acknowledged (the port registry's `maybe-ours`
+ adoption depends on it), a busy port is OpenSSH's "Port forwarding failed", and listeners close
+ on `-O cancel`, `-O exit`, `exitAll` and a dropped connection.
+- **No ssh.exe needed.** `resolveSshProgram()` (native-runtime.ts) is the one ssh lookup: the
+ binary (Windows adds `System32\OpenSSH\ssh.exe`), else — under the native transport only — the
+ bare `ssh` sentinel every runner routes to NativeMux. `findSshBinary()` is for the two callers
+ that exec `ssh -G` themselves. Without a binary, `ssh -G` falls back to OpenSSH's no-config
+ defaults (`defaultHostFromQuery`) and logs once per host that `~/.ssh/config` was not read.
+- **Agents on Windows:** the default is the OpenSSH agent service's pipe, else the user's
+ Pageant / KeeAgent pipe (`pageant.<user>.<hash>`, PuTTY ≥ 0.75); `IdentityAgent pageant` maps to
+ that pipe — NEVER to ssh2's `'pageant'` string, which spawns a 32-bit `pagent.exe` we would have
+ to ship and sign (`windows-agent-discovery.ts`).
+- **Recursive downloads** rename children Windows cannot create (`a:b`, `CON`, trailing dots, and
+ case-only collisions) per directory with `localChildName` / `uniqueChildName`
+ (download-name.ts — the ONE rule, also used for the top-level name) and log how many changed.
- **The Windows ssh-agent only on the user's say-so** (#1080). MEASURED on windows-latest
(OpenSSH_for_Windows_9.5p2): the agent service REFUSES any lifetime or confirm constraint
(`ssh-add -t` / `-c` and our `ADD_ID_CONSTRAINED` alike), and an unconstrained key is stored in
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d258adf6a..cef1157ae 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1181,7 +1181,9 @@ bite most often:
**SSH projects on Windows** run over an in-process transport (`src/core/remote-ssh/native/`),
not the ssh binary. If you add an ssh call site, route it through `useNativeSsh()` like the
others, and if you add an ssh option to `control-master.ts`, teach `ssh-argv.ts` about it (the
-parser refuses unknown options on purpose). Test from macOS/Linux with `NODETERM_NATIVE_SSH=1`.
+parser refuses unknown options on purpose). Test from macOS/Linux with `NODETERM_NATIVE_SSH=1`. Resolve the ssh
+program with `resolveSshProgram()` (never a private `findExecutableSync('ssh', …)`): on Windows it
+may be the bare `ssh` sentinel, which only the native runners can serve.
**A dependency with a native addon that the Server Edition reaches is `--external:` in
`server:build`.** Hosts build the bundle after `npm ci --ignore-scripts`, so no addon is compiled