The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 04:30 UTC
fix(devices): explain Windows SSH host failures (#30941)
shivam committed
Nov 5, 2026 at 06:51 UTC
8a65c000433b1a1d7da65897af6456488a9aafc7
5 files changed
+324
-10
apps/server/src/device/DeviceService.test.ts
+133
@@ -2,6 +2,7 @@ import { describe, expect, it } from "@effect/vitest";
2
import {
3
DEFAULT_SERVER_SETTINGS,
4
DeviceBootError,
5
+ DeviceError,
6
DeviceId,
7
DeviceOperationError,
8
LOCAL_DEVICE_HOST_ID,
@@ -13,6 +14,7 @@ import {
14
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
15
import * as NodeServices from "@effect/platform-node/NodeServices";
16
import * as NetService from "@t3tools/shared/Net";
17
+import { SshCommandError } from "@t3tools/ssh/errors";
18
import * as Effect from "effect/Effect";
19
import * as Exit from "effect/Exit";
20
import * as Deferred from "effect/Deferred";
@@ -37,6 +39,7 @@ import { makeDeviceHubOperations } from "./DeviceHubOperations.ts";
39
import { NodeRuntimeUnavailableError } from "@t3tools/shared/nodeRuntime";
40
41
import * as DeviceService from "./DeviceService.ts";
42
+import * as SshDeviceHost from "./SshDeviceHost.ts";
43
import { agentDeviceSession, releaseAgentDeviceSession } from "./AgentDeviceTarget.ts";
44
45
const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
@@ -315,6 +318,7 @@ const fixture = Effect.fn("fixture")(function* (
318
};
319
return {
320
service,
321
+ host,
322
starts,
323
agentStarts,
324
agentStops,
@@ -361,6 +365,61 @@ describe("device setup consent", () => {
365
}).pipe(Effect.scoped),
366
);
367
368
+ it.effect.each([
369
+ {
370
+ name: "a Windows host",
371
+ exitCode: 1,
372
+ stderr: "private diagnostics",
373
+ expected:
374
+ "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.",
375
+ },
376
+ {
377
+ name: "a Windows host returning 9009",
378
+ exitCode: 9009,
379
+ stderr: "private diagnostics",
380
+ expected:
381
+ "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.",
382
+ },
383
+ {
384
+ name: "missing Node on a Windows host with a POSIX shell",
385
+ exitCode: 1,
386
+ stderr: "private diagnostics\nNode is missing from the non-interactive SSH PATH",
387
+ expected:
388
+ "Connected over SSH, but Node is not on this host's PATH for non-interactive SSH commands.",
389
+ },
390
+ ])(
391
+ "reports SSH probe failure on $name through readiness and host status",
392
+ ({ exitCode, stderr, expected }) =>
393
+ Effect.gen(function* () {
394
+ const failure = new DeviceHost.DeviceHostError({
395
+ hostId: LOCAL_DEVICE_HOST_ID,
396
+ step: "probe",
397
+ cause: new SshDeviceHost.SshWindowsHostError({
398
+ cause: new SshCommandError({
399
+ command: ["ssh", "private arguments"],
400
+ exitCode,
401
+ stderr,
402
+ message: "private diagnostics",
403
+ }),
404
+ }),
405
+ });
406
+ const { service, settings } = yield* fixture(Effect.void, undefined, false, failure);
407
+ yield* Ref.update(settings, (current) => ({
408
+ ...current,
409
+ enableDeviceSupport: true,
410
+ enableAgentDeviceAccess: true,
411
+ }));
412
+ for (const readiness of [service.readiness(), service.agentReadinessIfSupported()]) {
413
+ const error = yield* readiness.pipe(Effect.flip);
414
+ expect(error).toMatchObject({ reason: expected, cause: failure });
415
+ expect((yield* service.state).hostStatuses[LOCAL_DEVICE_HOST_ID]).toEqual({
416
+ status: "failed",
417
+ detail: expected,
418
+ });
419
+ }
420
+ }).pipe(Effect.scoped),
421
+ );
422
+
423
it.effect("listing and provider startup do not start helpers before consent", () =>
424
Effect.gen(function* () {
425
const { service, starts, requests } = yield* fixture();
@@ -540,6 +599,80 @@ const layerSecretResolver = Layer.succeed(SecretResolver.SecretResolver, {
599
invalidate: () => Effect.void,
600
});
601
602
+it.effect.each([1, 9009])(
603
+ "Test connection preserves Windows exit %s guidance across the wire",
604
+ (exitCode) =>
605
+ Effect.gen(function* () {
606
+ const { host } = yield* fixture();
607
+ const service = yield* DeviceService.make.pipe(
608
+ Effect.provideService(DeviceHost.DeviceHost, host),
609
+ Effect.provideService(ProcessRunner.ProcessRunner, {
610
+ run: () => Effect.die("Testing SSH does not install local tools"),
611
+ }),
612
+ Effect.provideService(
613
+ HttpClient.HttpClient,
614
+ HttpClient.make(() => Effect.die("Testing SSH makes no hub requests")),
615
+ ),
616
+ Effect.provideService(
617
+ ChildProcessSpawner.ChildProcessSpawner,
618
+ ChildProcessSpawner.make((command) => {
619
+ if (command._tag !== "StandardCommand") return Effect.die("Unexpected command");
620
+ const config = command.args.includes("-G");
621
+ const windows = command.args.includes("echo %OS% $env:OS");
622
+ return Effect.succeed(
623
+ ChildProcessSpawner.makeHandle({
624
+ pid: ChildProcessSpawner.ProcessId(123),
625
+ stdout: Stream.make(
626
+ new TextEncoder().encode(
627
+ config ? "hostname 192.0.2.1\nport 22\n" : windows ? "Windows_NT\r\n" : "",
628
+ ),
629
+ ),
630
+ stderr: Stream.make(new TextEncoder().encode("private SSH diagnostics")),
631
+ all: Stream.empty,
632
+ exitCode: Effect.succeed(
633
+ ChildProcessSpawner.ExitCode(config || windows ? 0 : exitCode),
634
+ ),
635
+ isRunning: Effect.succeed(false),
636
+ kill: () => Effect.void,
637
+ stdin: Sink.drain,
638
+ getInputFd: () => Sink.drain,
639
+ getOutputFd: () => Stream.empty,
640
+ unref: Effect.succeed(Effect.void),
641
+ }),
642
+ );
643
+ }),
644
+ ),
645
+ );
646
+ const error = yield* service
647
+ .testHost({ kind: "ssh", id: "windows", label: "Windows test", target: "windows.test" })
648
+ .pipe(Effect.flip);
649
+ expect(error).toMatchObject({
650
+ _tag: "DeviceHostUnavailableError",
651
+ hostId: "windows",
652
+ hostLabel: "Windows test",
653
+ reason:
654
+ "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.",
655
+ });
656
+ const codec = Schema.fromJsonString(DeviceError);
657
+ const decoded = yield* Schema.decodeEffect(codec)(yield* Schema.encodeEffect(codec)(error));
658
+ expect(decoded.message).toBe(
659
+ "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.",
660
+ );
661
+ expect(decoded.message).not.toContain("private SSH diagnostics");
662
+ }).pipe(
663
+ Effect.provide(
664
+ Layer.mergeAll(
665
+ ServerSettings.layerTest(),
666
+ layerSecretResolver,
667
+ ServerConfig.layerTest(process.cwd(), { prefix: "t3-device-probe-" }),
668
+ NodeCrypto.layer,
669
+ NetService.layer,
670
+ ).pipe(Layer.provideMerge(NodeServices.layer)),
671
+ ),
672
+ Effect.scoped,
673
+ ),
674
+);
675
+
676
it.effect("publishes boot progress and does not restore sessions after support is disabled", () =>
677
Effect.gen(function* () {
678
const started = yield* Deferred.make<void>();
apps/server/src/device/DeviceService.ts
+17
-9
@@ -82,12 +82,13 @@ import * as LocalDeviceHost from "./LocalDeviceHost.ts";
82
export const DEVICE_HUB_ROUTE_PREFIX = "/api/device-hub";
83
84
const sshProbeFailureMessage = (error: DeviceHost.DeviceHostError): string => {
85
- const cause = error.cause;
85
+ const windows = SshDeviceHost.isSshWindowsHostError(error.cause) ? error.cause : null;
86
+ const cause = windows ? windows.cause : error.cause;
87
if (
88
!(cause instanceof SshCommandError) ||
89
cause.exitCode === null ||
90
cause.exitCode < 1 ||
90
- cause.exitCode > 254
91
+ (cause.exitCode > 254 && cause.exitCode !== 9009)
92
)
93
return "Could not connect to this host over SSH.";
94
@@ -99,6 +100,7 @@ const sshProbeFailureMessage = (error: DeviceHost.DeviceHostError): string => {
100
.some((line) => line.trim() === "Node is missing from the non-interactive SSH PATH")
101
)
102
return "Connected over SSH, but Node is not on this host's PATH for non-interactive SSH commands.";
103
+ if (windows) return windows.message;
104
105
return `Connected over SSH, but the device host check failed (exit code ${cause.exitCode}).`;
106
};
@@ -1354,13 +1356,19 @@ export const make = Effect.gen(function* () {
1356
}
1357
return yield* SshDeviceHost.probe(host).pipe(Effect.provide(probeContext));
1358
}).pipe(
1357
- Effect.mapError(
1358
- (error) =>
1359
- new DeviceOperationError({
1360
- operation: "probe host",
1361
- reason: "request_failed",
1362
- cause: error,
1363
- }),
1359
+ Effect.mapError((error) =>
1360
+ error._tag === "DeviceHostError" && SshDeviceHost.isSshWindowsHostError(error.cause)
1361
+ ? new DeviceHostUnavailableError({
1362
+ hostId: host.id,
1363
+ hostLabel: host.label,
1364
+ reason: sshProbeFailureMessage(error),
1365
+ cause: error,
1366
+ })
1367
+ : new DeviceOperationError({
1368
+ operation: "probe host",
1369
+ reason: "request_failed",
1370
+ cause: error,
1371
+ }),
1372
),
1373
),
1374
configureAgent,
apps/server/src/device/SshDeviceHost.test.ts
+116
@@ -386,3 +386,119 @@ it.effect(
386
Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer, TestClock.layer())),
387
),
388
);
389
+
390
+it.effect.each([
391
+ {
392
+ name: "a Windows PowerShell login shell",
393
+ exitCode: 1,
394
+ stderr: "sh : The term 'sh' is not recognized as the name of a cmdlet\r\n",
395
+ shellEcho: "%OS%\r\nWindows_NT\r\n",
396
+ nodePlatform: null,
397
+ windows: true,
398
+ },
399
+ {
400
+ name: "a Windows cmd login shell",
401
+ exitCode: 1,
402
+ stderr: "'sh' is not recognized as an internal or external command,\r\n",
403
+ shellEcho: "Windows_NT $env:OS\r\n",
404
+ nodePlatform: null,
405
+ windows: true,
406
+ },
407
+ {
408
+ name: "a Windows cmd login shell returning 9009",
409
+ exitCode: 9009,
410
+ stderr: "'sh' is not recognized as an internal or external command,\r\n",
411
+ shellEcho: "Windows_NT $env:OS\r\n",
412
+ nodePlatform: null,
413
+ windows: true,
414
+ },
415
+ {
416
+ name: "a Windows Git Bash login shell without a spawnable npm",
417
+ exitCode: 1,
418
+ stderr: "npm is missing from the non-interactive SSH PATH\n",
419
+ shellEcho: "%OS% :OS\n",
420
+ nodePlatform: "win32",
421
+ windows: true,
422
+ },
423
+ {
424
+ name: "a Linux host without npm",
425
+ exitCode: 1,
426
+ stderr: "npm is missing from the non-interactive SSH PATH\n",
427
+ shellEcho: "%OS% :OS\n",
428
+ nodePlatform: "linux",
429
+ windows: false,
430
+ },
431
+ {
432
+ name: "a POSIX host without Node",
433
+ exitCode: 1,
434
+ stderr: "Node is missing from the non-interactive SSH PATH\n",
435
+ shellEcho: "%OS% :OS\n",
436
+ nodePlatform: null,
437
+ windows: false,
438
+ },
439
+ {
440
+ name: "a connection failure",
441
+ exitCode: 255,
442
+ stderr: "Connection refused\n",
443
+ shellEcho: "Windows_NT\n",
444
+ nodePlatform: "win32",
445
+ windows: false,
446
+ },
447
+])(
448
+ "probe failure on $name keeps the SSH cause",
449
+ ({ exitCode, stderr, shellEcho, nodePlatform, windows }) =>
450
+ Effect.gen(function* () {
451
+ const fs = yield* FileSystem.FileSystem;
452
+ const home = yield* fs.makeTempDirectoryScoped();
453
+ const shellChecks: string[] = [];
454
+ const spawner = ChildProcessSpawner.make((command) =>
455
+ Effect.gen(function* () {
456
+ if (command._tag !== "StandardCommand") return yield* Effect.die("Unexpected command");
457
+ const remote = command.args.slice(command.args.indexOf("test.example") + 1).join(" ");
458
+ const shellCheck = remote === "echo %OS% $env:OS";
459
+ const platformCheck = remote === "node -p process.platform";
460
+ if (shellCheck || platformCheck) shellChecks.push(remote);
461
+ return ChildProcessSpawner.makeHandle({
462
+ pid: ChildProcessSpawner.ProcessId(123),
463
+ stdout: Stream.make(
464
+ new TextEncoder().encode(
465
+ shellCheck ? shellEcho : platformCheck ? `${nodePlatform ?? ""}\n` : "",
466
+ ),
467
+ ),
468
+ stderr: Stream.make(
469
+ new TextEncoder().encode(shellCheck || platformCheck ? "" : stderr),
470
+ ),
471
+ all: Stream.empty,
472
+ exitCode: Effect.succeed(
473
+ ChildProcessSpawner.ExitCode(
474
+ shellCheck ? 0 : platformCheck ? (nodePlatform === null ? 1 : 0) : exitCode,
475
+ ),
476
+ ),
477
+ isRunning: Effect.succeed(false),
478
+ kill: () => Effect.void,
479
+ stdin: Sink.drain,
480
+ getInputFd: () => Sink.drain,
481
+ getOutputFd: () => Stream.empty,
482
+ unref: Effect.succeed(Effect.void),
483
+ });
484
+ }),
485
+ );
486
+ const failure = yield* SshDeviceHost.probe({
487
+ kind: "ssh",
488
+ id: "test",
489
+ label: "Test",
490
+ target: "test.example",
491
+ }).pipe(
492
+ Effect.provide(ServerConfig.layerTest(home, home)),
493
+ Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
494
+ Effect.flip,
495
+ );
496
+ expect(failure).toMatchObject({ _tag: "DeviceHostError", step: "probe" });
497
+ const sshFailure = { _tag: "SshCommandError", exitCode, stderr };
498
+ expect(failure.cause).toMatchObject(
499
+ windows ? { _tag: "SshWindowsHostError", cause: sshFailure } : sshFailure,
500
+ );
501
+ // A transport failure has no remote shell to ask.
502
+ if (exitCode === 255) expect(shellChecks).toEqual([]);
503
+ }).pipe(Effect.scoped, Effect.provide(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))),
504
+);
apps/server/src/device/SshDeviceHost.ts
+56
-1
@@ -6,6 +6,7 @@ import {
6
type SshDeviceHostConfig,
7
} from "@t3tools/contracts";
8
import { runSshCommand, baseSshArgs, resolveSshCommand } from "@t3tools/ssh/command";
9
+import { SshCommandError } from "@t3tools/ssh/errors";
10
import * as NetService from "@t3tools/shared/Net";
11
import { waitForHttpReady } from "@t3tools/shared/httpReadiness";
12
import * as Digest from "effect/crypto/Digest";
@@ -29,6 +30,17 @@ import { quoteRemoteArg, remoteDeviceEnvironment, remoteDeviceScript } from "./s
30
31
const UNHEALTHY_PROBE_LIMIT = 3;
32
33
+/** The host bootstrap failed on a host identified as Windows. */
34
+export class SshWindowsHostError extends Schema.TaggedError<SshWindowsHostError>()(
35
+ "SshWindowsHostError",
36
+ { cause: Schema.Defect() },
37
+) {
38
+ override get message(): string {
39
+ return "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.";
40
+ }
41
+}
42
+export const isSshWindowsHostError = Schema.is(SshWindowsHostError);
43
+
44
const Probe = Schema.Struct({
45
nodePath: Schema.String,
46
tools: Schema.optional(DeviceToolVersions),
@@ -78,6 +90,47 @@ const bootstrap = (
90
),
91
);
92
93
+// cmd expands only %OS% and PowerShell only $env:OS; POSIX shells expand neither to Windows_NT.
94
+const explainWindowsHost = Effect.fn("SshDeviceHost.explainWindowsHost")(function* (
95
+ config: SshDeviceHostConfig,
96
+ error: DeviceHost.DeviceHostError,
97
+) {
98
+ const cause = error.cause;
99
+ // Windows ssh.exe preserves full remote exit statuses such as 9009.
100
+ if (
101
+ !(cause instanceof SshCommandError) ||
102
+ cause.exitCode === null ||
103
+ cause.exitCode < 1 ||
104
+ (cause.exitCode > 254 && cause.exitCode !== 9009)
105
+ )
106
+ return yield* error;
107
+ let windows = yield* runSshCommand(targetFor(config), {
108
+ preHostArgs: identityArgs(config),
109
+ remoteCommandArgs: ["echo %OS% $env:OS"],
110
+ timeoutMs: 15_000,
111
+ }).pipe(
112
+ Effect.map(({ stdout }) => /(?:^|\s)Windows_NT(?:\s|$)/u.test(stdout)),
113
+ Effect.orElseSucceed(() => false),
114
+ );
115
+ if (!windows) {
116
+ // Git Bash does not expand Windows shell variables, but its Node still reports win32.
117
+ windows = yield* runSshCommand(targetFor(config), {
118
+ preHostArgs: identityArgs(config),
119
+ remoteCommandArgs: ["node", "-p", "process.platform"],
120
+ timeoutMs: 15_000,
121
+ }).pipe(
122
+ Effect.map(({ stdout }) => stdout.trim() === "win32"),
123
+ Effect.orElseSucceed(() => false),
124
+ );
125
+ }
126
+ if (!windows) return yield* error;
127
+ return yield* new DeviceHost.DeviceHostError({
128
+ hostId: config.id,
129
+ step: error.step,
130
+ cause: new SshWindowsHostError({ cause }),
131
+ });
132
+});
133
+
134
const ownerFor = Effect.fn("SshDeviceHost.ownerFor")(function* (hostId: string) {
135
const fs = yield* FileSystem.FileSystem;
136
const server = yield* ServerConfig.ServerConfig;
@@ -98,7 +151,9 @@ export const probe = Effect.fn("SshDeviceHost.probe")(function* (
151
config: SshDeviceHostConfig,
152
owner?: string,
153
) {
101
- const result = yield* bootstrap(config, owner ?? (yield* ownerFor(config.id)), "probe");
154
+ const result = yield* bootstrap(config, owner ?? (yield* ownerFor(config.id)), "probe").pipe(
155
+ Effect.catchTags({ DeviceHostError: (error) => explainWindowsHost(config, error) }),
156
+ );
157
const value = yield* decodeProbe(result.stdout.trim()).pipe(
158
Effect.mapError(
159
(cause) =>
docs/user/devices.md
+2
@@ -108,6 +108,8 @@ not supported.
108
anything, with a result for each selected environment. Targets that resolve to
109
the environment’s own machine are skipped, since its devices are already local.
110
The first device listing installs pinned device tools on the host.
111
+SSH device hosts currently need macOS or Linux. To use devices on a Windows
112
+machine, run T3 Code on that machine and connect to its environment.
113
Node 22 or newer and npm must be available to non-interactive SSH commands.
114
T3 checks common Homebrew and Android SDK locations; custom installations need
115
the appropriate PATH and ANDROID_HOME on the host. Android emulator video needs