@devries-cameron20 / t3code Mirror · read-only / commits / 8a65c00043
Fork 0

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