The best way to control Claude Code, Codex and more from any computer or phone
fix(server): SSH device host probe failures say what ssh refused (#31695)
Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>
ahalekelly committed
Nov 14, 2026 at 18:51 UTC
dd86dd6d91c491bf8ab730e035fb4f2b4e07f633
4 files changed
+238
-73
apps/server/src/device/DeviceService.test.ts
+97
-68
@@ -677,77 +677,106 @@ const layerSecretResolver = Layer.succeed(SecretResolver.SecretResolver, {
677
invalidate: () => Effect.void,
678
});
679
680
-it.effect.each([1, 9009])(
681
- "Test connection preserves Windows exit %s guidance across the wire",
682
- (exitCode) =>
683
- Effect.gen(function* () {
684
- const { host } = yield* fixture();
685
- const service = yield* DeviceService.make.pipe(
686
- Effect.provideService(DeviceHost.DeviceHost, host),
687
- Effect.provideService(ProcessRunner.ProcessRunner, {
688
- run: () => Effect.die("Testing SSH does not install local tools"),
689
- }),
690
- Effect.provideService(
691
- HttpClient.HttpClient,
692
- HttpClient.make(() => Effect.die("Testing SSH makes no hub requests")),
693
- ),
694
- Effect.provideService(
695
- ChildProcessSpawner.ChildProcessSpawner,
696
- ChildProcessSpawner.make((command) => {
697
- if (command._tag !== "StandardCommand") return Effect.die("Unexpected command");
698
- const config = command.args.includes("-G");
699
- const windows = command.args.includes("echo %OS% $env:OS");
700
- return Effect.succeed(
701
- ChildProcessSpawner.makeHandle({
702
- pid: ChildProcessSpawner.ProcessId(123),
703
- stdout: Stream.make(
704
- new TextEncoder().encode(
705
- config ? "hostname 192.0.2.1\nport 22\n" : windows ? "Windows_NT\r\n" : "",
706
- ),
707
- ),
708
- stderr: Stream.make(new TextEncoder().encode("private SSH diagnostics")),
709
- all: Stream.empty,
710
- exitCode: Effect.succeed(
711
- ChildProcessSpawner.ExitCode(config || windows ? 0 : exitCode),
680
+const WINDOWS_HOST_GUIDANCE = new SshDeviceHost.SshWindowsHostError({ cause: null }).message;
681
+
682
+it.effect.each([
683
+ {
684
+ name: "Windows exit 1",
685
+ exitCode: 1,
686
+ stderr: "private SSH diagnostics",
687
+ reason: WINDOWS_HOST_GUIDANCE,
688
+ },
689
+ {
690
+ name: "Windows exit 9009",
691
+ exitCode: 9009,
692
+ stderr: "private SSH diagnostics",
693
+ reason: WINDOWS_HOST_GUIDANCE,
694
+ },
695
+ {
696
+ name: "untrusted host key",
697
+ exitCode: 255,
698
+ stderr: "Host key verification failed.\r\n",
699
+ reason:
700
+ "SSH encountered an untrusted host key while connecting to probe.test from the machine running this T3 Code server. Connect once with ssh from there to identify the host and verify its key before accepting it.",
701
+ },
702
+ {
703
+ name: "unrecognized SSH failure",
704
+ exitCode: 255,
705
+ stderr: "private SSH diagnostics",
706
+ reason: "Could not connect to this host over SSH.",
707
+ },
708
+])("Test connection preserves $name guidance across the wire", ({ exitCode, stderr, reason }) =>
709
+ Effect.gen(function* () {
710
+ const { host } = yield* fixture();
711
+ const service = yield* DeviceService.make.pipe(
712
+ Effect.provideService(DeviceHost.DeviceHost, host),
713
+ Effect.provideService(ProcessRunner.ProcessRunner, {
714
+ run: () => Effect.die("Testing SSH does not install local tools"),
715
+ }),
716
+ Effect.provideService(
717
+ HttpClient.HttpClient,
718
+ HttpClient.make(() => Effect.die("Testing SSH makes no hub requests")),
719
+ ),
720
+ Effect.provideService(
721
+ ChildProcessSpawner.ChildProcessSpawner,
722
+ ChildProcessSpawner.make((command) => {
723
+ if (command._tag !== "StandardCommand") return Effect.die("Unexpected command");
724
+ const config = command.args.includes("-G");
725
+ const windows = command.args.includes("echo %OS% $env:OS");
726
+ return Effect.succeed(
727
+ ChildProcessSpawner.makeHandle({
728
+ pid: ChildProcessSpawner.ProcessId(123),
729
+ stdout: Stream.make(
730
+ new TextEncoder().encode(
731
+ config ? "hostname 192.0.2.1\nport 22\n" : windows ? "Windows_NT\r\n" : "",
732
),
713
- isRunning: Effect.succeed(false),
714
- kill: () => Effect.void,
715
- stdin: Sink.drain,
716
- getInputFd: () => Sink.drain,
717
- getOutputFd: () => Stream.empty,
718
- unref: Effect.succeed(Effect.void),
719
- }),
720
- );
721
- }),
722
- ),
723
- );
724
- const error = yield* service
725
- .testHost({ kind: "ssh", id: "windows", label: "Windows test", target: "windows.test" })
726
- .pipe(Effect.flip);
727
- expect(error).toMatchObject({
728
- _tag: "DeviceHostUnavailableError",
729
- hostId: "windows",
730
- hostLabel: "Windows test",
731
- reason:
732
- "Connected over SSH, but this host runs Windows, and SSH device hosts currently need macOS or Linux. To use this machine's devices, run T3 Code on it and connect to that environment.",
733
- });
734
- const codec = Schema.fromJsonString(DeviceError);
735
- const decoded = yield* Schema.decodeEffect(codec)(yield* Schema.encodeEffect(codec)(error));
736
- expect(decoded.message).toBe(
737
- "Windows test is unavailable: Connected over SSH, but this host runs Windows, and SSH device hosts currently need macOS or Linux. To use this machine's devices, run T3 Code on it and connect to that environment.",
738
- );
739
- expect(decoded.message).not.toContain("private SSH diagnostics");
740
- }).pipe(
741
- Effect.provide(
742
- Layer.mergeAll(
743
- ServerSettings.layerTest(),
744
- layerSecretResolver,
745
- ServerConfig.layerTest(process.cwd(), { prefix: "t3-device-probe-" }),
746
- NodeCrypto.layer,
747
- NetService.layer,
748
- ).pipe(Layer.provideMerge(NodeServices.layer)),
733
+ ),
734
+ stderr: Stream.make(new TextEncoder().encode(stderr)),
735
+ all: Stream.empty,
736
+ exitCode: Effect.succeed(
737
+ ChildProcessSpawner.ExitCode(config || windows ? 0 : exitCode),
738
+ ),
739
+ isRunning: Effect.succeed(false),
740
+ kill: () => Effect.void,
741
+ stdin: Sink.drain,
742
+ getInputFd: () => Sink.drain,
743
+ getOutputFd: () => Stream.empty,
744
+ unref: Effect.succeed(Effect.void),
745
+ }),
746
+ );
747
+ }),
748
),
749
+ );
750
+ const error = yield* service
751
+ .testHost({
752
+ kind: "ssh",
753
+ id: "probe",
754
+ label: "Probe test",
755
+ target: "probe.test",
756
+ port: 2222,
757
+ })
758
+ .pipe(Effect.flip);
759
+ expect(error).toMatchObject({
760
+ _tag: "DeviceHostUnavailableError",
761
+ hostId: "probe",
762
+ hostLabel: "Probe test",
763
+ reason,
764
+ });
765
+ const codec = Schema.fromJsonString(DeviceError);
766
+ const decoded = yield* Schema.decodeEffect(codec)(yield* Schema.encodeEffect(codec)(error));
767
+ expect(decoded.message).toBe(`Probe test is unavailable: ${reason}`);
768
+ expect(decoded.message).not.toContain("private SSH diagnostics");
769
+ }).pipe(
770
+ Effect.provide(
771
+ Layer.mergeAll(
772
+ ServerSettings.layerTest(),
773
+ layerSecretResolver,
774
+ ServerConfig.layerTest(process.cwd(), { prefix: "t3-device-probe-" }),
775
+ NodeCrypto.layer,
776
+ NetService.layer,
777
+ ).pipe(Layer.provideMerge(NodeServices.layer)),
778
),
779
+ ),
780
);
781
782
it.effect("publishes boot progress and does not restore sessions after support is disabled", () =>
apps/server/src/device/DeviceService.ts
+5
-1
@@ -90,6 +90,7 @@ export const DEVICE_HUB_ROUTE_PREFIX = "/api/device-hub";
90
const isSshCommandError = Schema.is(SshCommandError);
91
92
const sshProbeFailureMessage = (error: DeviceHost.DeviceHostError): string => {
93
+ if (SshDeviceHost.isSshConnectError(error.cause)) return error.cause.message;
94
const windows = SshDeviceHost.isSshWindowsHostError(error.cause) ? error.cause : null;
95
const cause = windows ? windows.cause : error.cause;
96
if (
@@ -1406,7 +1407,10 @@ export const make = Effect.gen(function* () {
1407
return yield* SshDeviceHost.probe(host).pipe(Effect.provide(probeContext));
1408
}).pipe(
1409
Effect.mapError((error) =>
1409
- error._tag === "DeviceHostError" && SshDeviceHost.isSshWindowsHostError(error.cause)
1410
+ error._tag === "DeviceHostError" &&
1411
+ (isSshCommandError(error.cause) ||
1412
+ SshDeviceHost.isSshConnectError(error.cause) ||
1413
+ SshDeviceHost.isSshWindowsHostError(error.cause))
1414
? new DeviceHostUnavailableError({
1415
hostId: host.id,
1416
hostLabel: host.label,
apps/server/src/device/SshDeviceHost.test.ts
+70
-3
@@ -530,16 +530,79 @@ it.effect.each([
530
windows: false,
531
},
532
{
533
- name: "a connection failure",
533
+ name: "an unrecognized SSH failure",
534
exitCode: 255,
535
stderr: "Connection refused\n",
536
shellEcho: "Windows_NT\n",
537
nodePlatform: "win32",
538
windows: false,
539
},
540
+ {
541
+ name: "a ProxyCommand permission error",
542
+ exitCode: 255,
543
+ stderr: "bash: /usr/local/bin/proxy: Permission denied\n",
544
+ shellEcho: "",
545
+ nodePlatform: null,
546
+ windows: false,
547
+ },
548
+ {
549
+ name: "an untrusted host key",
550
+ exitCode: 255,
551
+ stderr: "Host key verification failed.\r\n",
552
+ shellEcho: "Windows_NT\n",
553
+ nodePlatform: "win32",
554
+ windows: false,
555
+ connect: { reason: "host_key_unknown", detail: "Host key verification failed." },
556
+ },
557
+ {
558
+ name: "a changed host key",
559
+ exitCode: 255,
560
+ stderr:
561
+ "@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\n@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @\n@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\nIT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!\nHost key verification failed.\n",
562
+ shellEcho: "",
563
+ nodePlatform: null,
564
+ windows: false,
565
+ connect: {
566
+ reason: "host_key_changed",
567
+ detail: "@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @",
568
+ },
569
+ },
570
+ {
571
+ name: "a rejected login",
572
+ exitCode: 255,
573
+ stderr: "me@test.example: Permission denied (publickey).\n",
574
+ shellEcho: "",
575
+ nodePlatform: null,
576
+ windows: false,
577
+ connect: { reason: "auth", detail: "me@test.example: Permission denied (publickey)." },
578
+ },
579
+ {
580
+ name: "an unresolvable host name",
581
+ exitCode: 255,
582
+ stderr: "ssh: Could not resolve hostname test.example: Name or service not known\n",
583
+ shellEcho: "",
584
+ nodePlatform: null,
585
+ windows: false,
586
+ connect: {
587
+ reason: "resolve",
588
+ detail: "ssh: Could not resolve hostname test.example: Name or service not known",
589
+ },
590
+ },
591
+ {
592
+ name: "a refused connection",
593
+ exitCode: 255,
594
+ stderr: "ssh: connect to host test.example port 22: Connection refused\n",
595
+ shellEcho: "",
596
+ nodePlatform: null,
597
+ windows: false,
598
+ connect: {
599
+ reason: "connect",
600
+ detail: "ssh: connect to host test.example port 22: Connection refused",
601
+ },
602
+ },
603
])(
604
"probe failure on $name keeps the SSH cause",
542
- ({ exitCode, stderr, shellEcho, nodePlatform, windows }) =>
605
+ ({ exitCode, stderr, shellEcho, nodePlatform, windows, connect }) =>
606
Effect.gen(function* () {
607
const fs = yield* FileSystem.FileSystem;
608
const home = yield* fs.makeTempDirectoryScoped();
@@ -589,7 +652,11 @@ it.effect.each([
652
expect(failure).toMatchObject({ _tag: "DeviceHostError", step: "probe" });
653
const sshFailure = { _tag: "SshCommandError", exitCode, stderr };
654
expect(failure.cause).toMatchObject(
592
- windows ? { _tag: "SshWindowsHostError", cause: sshFailure } : sshFailure,
655
+ windows
656
+ ? { _tag: "SshWindowsHostError", cause: sshFailure }
657
+ : connect
658
+ ? { _tag: "SshConnectError", ...connect, target: "test.example", cause: sshFailure }
659
+ : sshFailure,
660
);
661
// A transport failure has no remote shell to ask.
662
if (exitCode === 255) expect(shellChecks).toEqual([]);
apps/server/src/device/SshDeviceHost.ts
+66
-1
@@ -41,6 +41,33 @@ export class SshWindowsHostError extends Schema.TaggedError<SshWindowsHostError>
41
}
42
export const isSshWindowsHostError = Schema.is(SshWindowsHostError);
43
44
+/** ssh itself refused the connection before the host bootstrap ran. */
45
+export class SshConnectError extends Schema.TaggedError<SshConnectError>()("SshConnectError", {
46
+ reason: Schema.Literals(["host_key_unknown", "host_key_changed", "auth", "resolve", "connect"]),
47
+ target: Schema.String,
48
+ /** The ssh diagnostic line that identified the reason. */
49
+ detail: Schema.String,
50
+ cause: Schema.Defect(),
51
+}) {
52
+ override get message(): string {
53
+ const here = "the machine running this T3 Code server";
54
+ const detail = this.detail.replace(/\.$/u, "");
55
+ switch (this.reason) {
56
+ case "host_key_unknown":
57
+ return `SSH encountered an untrusted host key while connecting to ${this.target} from ${here}. Connect once with ssh from there to identify the host and verify its key before accepting it.`;
58
+ case "host_key_changed":
59
+ return `SSH encountered a changed host key while connecting to ${this.target} from ${here}. Connect once with ssh from there to identify the affected host. If the change is expected, remove that host's old key with \`ssh-keygen -R\`, then verify and accept its new key.`;
60
+ case "auth":
61
+ return `SSH login failed while connecting to ${this.target}: ${detail}. SSH from ${here} must log in without a prompt.`;
62
+ case "resolve":
63
+ return `Could not resolve the host name ${this.target} from ${here}: ${detail}.`;
64
+ case "connect":
65
+ return `Could not reach ${this.target} from ${here}: ${detail}. Check that the host is on, its SSH server is running, and the address and port are right.`;
66
+ }
67
+ }
68
+}
69
+export const isSshConnectError = Schema.is(SshConnectError);
70
+
71
const Probe = Schema.Struct({
72
nodePath: Schema.String,
73
tools: Schema.optional(DeviceToolVersions),
@@ -92,6 +119,41 @@ const bootstrap = (
119
120
const isSshCommandError = Schema.is(SshCommandError);
121
122
+// ssh exits 255 for its own failures; the remote bootstrap never does.
123
+const SSH_CONNECT_FAILURES: ReadonlyArray<readonly [SshConnectError["reason"], RegExp]> = [
124
+ ["host_key_changed", /REMOTE HOST IDENTIFICATION HAS CHANGED/u],
125
+ ["host_key_unknown", /^Host key verification failed\.$/u],
126
+ [
127
+ "auth",
128
+ /^\S+: (?:Permission denied \(|No supported authentication methods)|: Too many authentication failures$/u,
129
+ ],
130
+ ["resolve", /^ssh: Could not resolve hostname /u],
131
+ ["connect", /^ssh: connect to host /u],
132
+];
133
+const explainSshConnectFailure = (
134
+ config: SshDeviceHostConfig,
135
+ error: DeviceHost.DeviceHostError,
136
+): DeviceHost.DeviceHostError => {
137
+ const cause = error.cause;
138
+ if (!isSshCommandError(cause) || cause.exitCode !== 255) return error;
139
+ const lines = cause.stderr.split(/\r?\n/u).map((line) => line.trim());
140
+ for (const [reason, pattern] of SSH_CONNECT_FAILURES) {
141
+ const detail = lines.find((line) => pattern.test(line));
142
+ if (detail === undefined) continue;
143
+ return new DeviceHost.DeviceHostError({
144
+ hostId: config.id,
145
+ step: error.step,
146
+ cause: new SshConnectError({
147
+ reason,
148
+ target: config.target,
149
+ detail,
150
+ cause,
151
+ }),
152
+ });
153
+ }
154
+ return error;
155
+};
156
+
157
// cmd expands only %OS% and PowerShell only $env:OS; POSIX shells expand neither to Windows_NT.
158
const explainWindowsHost = Effect.fn("SshDeviceHost.explainWindowsHost")(function* (
159
config: SshDeviceHostConfig,
@@ -154,7 +216,10 @@ export const probe = Effect.fn("SshDeviceHost.probe")(function* (
216
owner?: string,
217
) {
218
const result = yield* bootstrap(config, owner ?? (yield* ownerFor(config.id)), "probe").pipe(
157
- Effect.catchTags({ DeviceHostError: (error) => explainWindowsHost(config, error) }),
219
+ Effect.catchTags({
220
+ DeviceHostError: (error) =>
221
+ explainWindowsHost(config, explainSshConnectFailure(config, error)),
222
+ }),
223
);
224
const value = yield* decodeProbe(result.stdout.trim()).pipe(
225
Effect.mapError(