[Bug]: SSH environment tunnel fails with ControlMaster auto / ControlPersist#3533

openedJun 23, 2026byPPratham-commits-code

Before submitting

I searched existing issues and did not find a duplicate.
I included enough detail to reproduce or investigate the problem.

Area

apps/desktop

Steps to reproduce

Configure an SSH host entry that uses OpenSSH connection multiplexing:

sshconfig

1	Host <ssh-alias>
2	HostName <host>
3	User <user>
4	IdentityFile ~/.ssh/<key>
5	IdentitiesOnly yes
6	AddKeysToAgent yes
7	ConnectTimeout 5
8	ConnectionAttempts 2
9	ServerAliveInterval 15
10	ServerAliveCountMax 2
11	ControlMaster auto
12	ControlPath ~/.ssh/cm-%C
13	ControlPersist 10m

Ensure a master connection / control socket already exists for that host.
Ask T3 Code Desktop to connect to that SSH environment.
T3 Code launches the remote server successfully, then the supervised local tunnel process exits 0 and the app surfaces a failure.

Manual validation of the underlying behavior:

1	# With ControlMaster auto in the host config:
2	ssh -o BatchMode=yes -o ConnectTimeout=10 -p 22 \
3	-o ExitOnForwardFailure=yes \
4	-o ServerAliveInterval=15 \
5	-o ServerAliveCountMax=3 \
6	-n -N -L 52620:127.0.0.1:3773 <user>@<ssh-alias>
7	# Returns immediately with exit code 0 in the failing setup.

After disabling multiplexing for the alias (ControlMaster no, ControlPath none, ControlPersist no), the same tunnel command stays alive and curl -I http://127.0.0.1:<local-port>/ returns HTTP/1.1 200 OK.

Expected behavior

T3 Code should support common SSH config variants that use multiplexing — or force the supervised tunnel command to opt out of it. Possible fixes:

Add -o ControlMaster=no -o ControlPath=none to the supervised ssh -N -L tunnel command so the process lifetime reflects the tunnel lifetime.
Alternatively, if multiplexing is allowed, treat exitCode: 0 plus localPortListening: true as a possibly-successful delegated tunnel rather than an immediate failure.
Provide a clearer diagnostic when the SSH child exits 0 under a ControlMaster auto config.

Actual behavior

With ControlMaster auto, OpenSSH delegates the local forward to the existing master connection and the supervised child process exits successfully (0). T3 Code treats that exit as a tunnel failure, even though the forwarded port is actually listening, and connecting fails.

Impact

Major degradation or frequent failure (SSH environments with multiplexing configs cannot connect; a workaround exists).

Version or commit

T3 Code Alpha 0.0.27; remote package launched by T3 t3@0.0.27.

Environment

Local OS: macOS, OpenSSH_10.2p1
Remote OS: macOS, OpenSSH_10.0
T3 Code Alpha 0.0.27 / remote t3@0.0.27

Logs or stack traces

text

1	Error invoking remote method 'desktop:ensure-ssh-environment': SshCommandError: SSH tunnel exited unexpectedly for <ssh-alias> (exit 0).
2
3	ssh.tunnel.process.exited
4	exitCode: 0
5	stderr: ""
6	localPort: 52609
7	remotePort: 3773
8	httpBaseUrl: http://127.0.0.1:52609/
9
10	# Readiness then failed despite:
11	processRunning: false
12	localPortListening: true
13
14	# Final error:
15	SshCommandError: SSH tunnel exited unexpectedly for <ssh-alias> (exit 0).

Workaround

Disable SSH multiplexing for the affected alias:

sshconfig

1	Host <ssh-alias>
2	ControlMaster no
3	ControlPath none
4	ControlPersist no

JJulius MarmingeJul 20, 2026

Implementation is ready without opening a PR: branch codex/issue-3533-ssh-controlmaster at commit d2de12535.

The supervised ssh -N -L process now explicitly disables ControlMaster, ControlPath, and ControlPersist while leaving other SSH flows unchanged. Verification passed all 26 @t3tools/ssh tests, package typecheck, and targeted lint/format/diff checks. Deterministic lifecycle coverage proves the overrides apply only to the supervised tunnel, disconnect reaps it, and reconnect spawns a fresh tunnel. A supplementary ssh -G fixture was blocked by approval-review infrastructure, so no live recording is claimed. No PR has been opened.