The best way to control Claude Code, Codex and more from any computer or phone
fix(desktop): WSL backend honors T3CODE_HOME from the distro's login shell (#39771)
Julius Marminge committed
Nov 20, 2026 at 07:25 UTC
905346e0d091bd447eff72d17f1b8296845e0aa2
5 files changed
+159
-119
apps/desktop/src/backend/DesktopBackendConfiguration.test.ts
+33
-22
@@ -354,7 +354,12 @@ describe("DesktopBackendConfiguration", () => {
354
},
355
ensureNodePty: (distro) => {
356
observedDistros.push(distro);
357
- return { ok: true, nodePath: "/usr/bin/node", resolvedPath: "/usr/bin:/bin" };
357
+ return {
358
+ ok: true,
359
+ nodePath: "/usr/bin/node",
360
+ resolvedPath: "/usr/bin:/bin",
361
+ t3Home: null,
362
+ };
363
},
364
getDistroIp: (distro) => {
365
observedDistros.push(distro);
@@ -385,10 +390,12 @@ describe("DesktopBackendConfiguration", () => {
390
windowsArchivePath: string;
391
runtimeId: string;
392
sha256: string;
393
+ t3Home: string | null;
394
}> = [];
395
let probeCount = 0;
396
let legacyCleanupCount = 0;
391
- const linuxAppRoot = "/home/test/.t3/wsl-runtime/1.2.3-x64";
397
+ const t3Home = "/home/test/.config/t3";
398
+ const linuxAppRoot = `${t3Home}/wsl-runtime/1.2.3-x64`;
399
const resolvedPath = "/home/test/.local/bin:/usr/bin:/bin";
400
401
return withPackagedWslHarness(
@@ -399,17 +406,18 @@ describe("DesktopBackendConfiguration", () => {
406
legacyCleanupCount += 1;
407
}),
408
wsl: () => ({
402
- prepareRuntime: (_distro, archive) => {
409
+ prepareRuntime: (_distro, archive, archiveT3Home) => {
410
observedArchives.push({
411
windowsArchivePath: archive.windowsPath,
412
runtimeId: archive.runtimeId,
413
sha256: archive.sha256,
414
+ t3Home: archiveT3Home,
415
});
416
return { ok: true, linuxAppRoot };
417
},
418
probeRuntime: () => {
419
probeCount += 1;
412
- return { ok: true, resolvedPath };
420
+ return { ok: true, resolvedPath, t3Home };
421
},
422
ensureNodePty: () => {
423
throw new Error("the staged runtime must not probe for node-pty");
@@ -427,6 +435,7 @@ describe("DesktopBackendConfiguration", () => {
435
windowsArchivePath: archivePath,
436
runtimeId: `sha256-${archiveHash}`,
437
sha256: archiveHash,
438
+ t3Home,
439
},
440
]);
441
assert.equal(probeCount, 1);
@@ -442,12 +451,14 @@ describe("DesktopBackendConfiguration", () => {
451
"--exec",
452
"env",
453
`PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:${resolvedPath}`,
454
+ `T3CODE_HOME=${t3Home}`,
455
`${linuxAppRoot}/t3`,
456
"--bootstrap-fd",
457
"0",
458
]);
459
assert.notInclude(config.args, "/usr/bin/node");
460
assert.equal(config.wslRuntimeId, `sha256-${archiveHash}`);
461
+ assert.equal(config.wslT3Home, t3Home);
462
assert.equal(legacyCleanupCount, 1);
463
assert.isTrue(Option.isNone(config.preflightFailure));
464
}),
@@ -470,6 +481,7 @@ describe("DesktopBackendConfiguration", () => {
481
ok: true,
482
nodePath: "/usr/bin/node",
483
resolvedPath: "/usr/bin:/bin",
484
+ t3Home: null,
485
}),
486
}),
487
},
@@ -502,10 +514,14 @@ describe("DesktopBackendConfiguration", () => {
514
archiveHash: "b".repeat(64),
515
wsl: () => ({
516
prepareRuntime: () => ({ ok: false, reason: "archive is corrupt" }),
505
- invalidateRuntime: () => Effect.die("failed staging must not invalidate a runtime"),
517
ensureNodePty: (_distro, root) => {
518
observedNodePtyRoots.push(root);
508
- return { ok: true, nodePath: "/usr/bin/node", resolvedPath: "/usr/bin:/bin" };
519
+ return {
520
+ ok: true,
521
+ nodePath: "/usr/bin/node",
522
+ resolvedPath: "/usr/bin:/bin",
523
+ t3Home: null,
524
+ };
525
},
526
}),
527
},
@@ -524,28 +540,30 @@ describe("DesktopBackendConfiguration", () => {
540
);
541
});
542
527
- it.effect("resolveWsl retires a staged runtime whose launch probe fails", () => {
543
+ it.effect("resolveWsl does not stage a runtime when the login-shell probe fails", () => {
544
const archiveHash = "c".repeat(64);
545
const stagedAppRoot = `/home/test/.t3/wsl-runtime/sha256-${archiveHash}`;
546
let probeCount = 0;
547
const observedNodePtyRoots: string[] = [];
532
- const invalidatedRuntimeIds: string[] = [];
548
return withPackagedWslHarness(
549
{
550
archiveHash,
551
wsl: () => ({
537
- prepareRuntime: () => ({ ok: true, linuxAppRoot: stagedAppRoot }),
538
- invalidateRuntime: (_distro, runtimeId) =>
539
- Effect.sync(() => {
540
- invalidatedRuntimeIds.push(runtimeId);
541
- }),
552
+ prepareRuntime: () => {
553
+ throw new Error("a failed probe must not stage the runtime");
554
+ },
555
probeRuntime: () => {
556
probeCount += 1;
557
return { ok: false, reason: "WSL login-shell PATH could not be resolved" };
558
},
559
ensureNodePty: (_distro, root) => {
560
observedNodePtyRoots.push(root);
548
- return { ok: true, nodePath: "/usr/bin/node", resolvedPath: "/usr/bin:/bin" };
561
+ return {
562
+ ok: true,
563
+ nodePath: "/usr/bin/node",
564
+ resolvedPath: "/usr/bin:/bin",
565
+ t3Home: null,
566
+ };
567
},
568
}),
569
},
@@ -562,23 +580,17 @@ describe("DesktopBackendConfiguration", () => {
580
assert.equal(config.entryPath, mountedEntryPath);
581
assert.isUndefined(config.wslRuntimeId);
582
assert.isTrue(Option.isNone(config.preflightFailure));
565
- assert.deepEqual(invalidatedRuntimeIds, [`sha256-${archiveHash}`]);
583
}),
584
);
585
});
586
587
it.effect("resolveWsl keeps WSL retryable when the mounted fallback fails transiently", () => {
588
const stagedAppRoot = "/home/test/.t3/wsl-runtime/cache";
572
- const invalidatedRuntimeIds: string[] = [];
589
return withPackagedWslHarness(
590
{
591
archiveHash: "f".repeat(64),
592
wsl: () => ({
593
prepareRuntime: () => ({ ok: true, linuxAppRoot: stagedAppRoot }),
578
- invalidateRuntime: (_distro, runtimeId) =>
579
- Effect.sync(() => {
580
- invalidatedRuntimeIds.push(runtimeId);
581
- }),
594
probeRuntime: () => ({ ok: false, reason: "WSL login-shell PATH could not be resolved" }),
595
ensureNodePty: () => ({
596
ok: false,
@@ -596,7 +608,6 @@ describe("DesktopBackendConfiguration", () => {
608
assert.isFalse(failure.fatal);
609
assert.equal(failure.retryLimit, 12);
610
assert.include(failure.reason, "timed out");
599
- assert.deepEqual(invalidatedRuntimeIds, []);
611
}),
612
);
613
});
@@ -633,7 +644,7 @@ describe("DesktopBackendConfiguration", () => {
644
isAvailable: true,
645
distros: [{ name: "Ubuntu", isDefault: true, version: 2 }],
646
windowsToWslPath: () => Option.some(linuxAppRoot),
636
- ensureNodePty: () => ({ ok: true, nodePath, resolvedPath }),
647
+ ensureNodePty: () => ({ ok: true, nodePath, resolvedPath, t3Home: null }),
648
getDistroIp: () => Option.some("172.27.0.99"),
649
}),
650
),
apps/desktop/src/backend/DesktopBackendConfiguration.ts
+24
-17
@@ -293,6 +293,7 @@ interface WslPreflightSuccess {
293
readonly windowsEntryPath: string;
294
readonly runtime: WslPreflightRuntime;
295
readonly resolvedPath: string;
296
+ readonly t3Home: string | null;
297
readonly runtimeId?: string;
298
}
299
@@ -412,7 +413,7 @@ const runWslPreflight = Effect.fn("desktop.backendConfiguration.wslPreflight")(f
413
: ({ ok: true, windowsEntryPath, linuxAppRoot: mountedAppRoot.value } as const);
414
});
415
415
- let stagedFailure: { readonly runtimeId?: string; readonly reason: string } | undefined;
416
+ let stagedFailure: { readonly reason: string } | undefined;
417
const failedStaged = (failure: { readonly reason: string }) =>
418
({
419
_tag: "Failed",
@@ -421,11 +422,16 @@ const runWslPreflight = Effect.fn("desktop.backendConfiguration.wslPreflight")(f
422
}) as const;
423
424
if (input.runtimeArchive !== null) {
424
- const runtime = yield* wslEnv.prepareRuntime(runningDistro, input.runtimeArchive);
425
- if (runtime.ok) {
426
- // Staged runtimes bundle Node and node-pty; provider PATH discovery must not require them.
427
- const stagedProbe = yield* wslEnv.probeRuntime(runningDistro);
428
- if (stagedProbe.ok) {
425
+ // Staged runtimes bundle Node and node-pty; provider PATH discovery must not require them.
426
+ // Probe first: the runtime cache lives under the login shell's T3CODE_HOME.
427
+ const stagedProbe = yield* wslEnv.probeRuntime(runningDistro);
428
+ if (stagedProbe.ok) {
429
+ const runtime = yield* wslEnv.prepareRuntime(
430
+ runningDistro,
431
+ input.runtimeArchive,
432
+ stagedProbe.t3Home,
433
+ );
434
+ if (runtime.ok) {
435
yield* wslServerTree.cleanupLegacy;
436
return {
437
_tag: "Ready",
@@ -433,20 +439,21 @@ const runWslPreflight = Effect.fn("desktop.backendConfiguration.wslPreflight")(f
439
windowsEntryPath: environment.backendEntryPath,
440
runtime: { kind: "executable", entryPath: `${runtime.linuxAppRoot}/t3` },
441
resolvedPath: stagedProbe.resolvedPath,
442
+ t3Home: stagedProbe.t3Home,
443
runtimeId: input.runtimeArchive.runtimeId,
444
} as const;
445
}
439
- yield* Effect.logWarning(
440
- "The staged WSL runtime probe failed; retrying from the mounted server tree.",
441
- { reason: stagedProbe.reason },
442
- );
443
- stagedFailure = { runtimeId: input.runtimeArchive.runtimeId, reason: stagedProbe.reason };
444
- } else {
446
stagedFailure = { reason: runtime.reason };
447
yield* Effect.logWarning(
448
"Could not stage the WSL runtime; launching from the mounted server tree instead.",
449
{ reason: runtime.reason },
450
);
451
+ } else {
452
+ yield* Effect.logWarning(
453
+ "The staged WSL runtime probe failed; retrying from the mounted server tree.",
454
+ { reason: stagedProbe.reason },
455
+ );
456
+ stagedFailure = { reason: stagedProbe.reason };
457
}
458
}
459
@@ -469,10 +476,6 @@ const runWslPreflight = Effect.fn("desktop.backendConfiguration.wslPreflight")(f
476
: failedNodePty(nodePtyResult);
477
}
478
472
- if (stagedFailure?.runtimeId) {
473
- yield* wslEnv.invalidateRuntime(runningDistro, stagedFailure.runtimeId);
474
- }
475
-
479
return {
480
_tag: "Ready",
481
runningDistro,
@@ -483,6 +486,7 @@ const runWslPreflight = Effect.fn("desktop.backendConfiguration.wslPreflight")(f
486
linuxEntryPath: `${mounted.linuxAppRoot}/apps/server/dist/bin.mjs`,
487
},
488
resolvedPath: nodePtyResult.resolvedPath,
489
+ t3Home: nodePtyResult.t3Home,
490
} as const;
491
});
492
@@ -745,13 +749,16 @@ const resolveWslStartConfig = Effect.fn("desktop.backendConfiguration.resolveWsl
749
"--exec",
750
"env",
751
`PATH=${launchPath}`,
752
+ ...(preflight.t3Home === null ? [] : [`T3CODE_HOME=${preflight.t3Home}`]),
753
...command,
754
"--bootstrap-fd",
755
"0",
756
...devUrlArgs,
757
],
758
preflightFailure: Option.none(),
754
- ...(preflight.runtimeId === undefined ? {} : { wslRuntimeId: preflight.runtimeId }),
759
+ ...(preflight.runtimeId === undefined
760
+ ? {}
761
+ : { wslRuntimeId: preflight.runtimeId, wslT3Home: preflight.t3Home }),
762
} satisfies DesktopBackendManager.DesktopBackendStartConfig;
763
});
764
apps/desktop/src/backend/DesktopBackendManager.ts
+2
@@ -84,6 +84,7 @@ export interface DesktopBackendStartConfig extends BackendProcessContext {
84
readonly preflightFailure: Option.Option<PreflightFailure>;
85
readonly runningDistro?: string;
86
readonly wslRuntimeId?: string;
87
+ readonly wslT3Home?: string | null;
88
}
89
90
export interface PreflightFailure {
@@ -992,6 +993,7 @@ export const makeBackendInstance = Effect.fn("makeBackendInstance")(function* (
993
yield* wslEnvironment.pruneRuntimes(
994
config.value.runningDistro,
995
config.value.wslRuntimeId,
996
+ config.value.wslT3Home ?? null,
997
);
998
}
999
}),
apps/desktop/src/wsl/DesktopWslEnvironment.test.ts
+36
-14
@@ -22,10 +22,10 @@ import {
22
layer as layerDesktopWslEnvironment,
23
buildWslRuntimeInstallScript,
24
makeIsAvailable,
25
- buildWslRuntimeInvalidateScript,
25
buildWslRuntimePruneScript,
26
buildWslRuntimeProbeScript,
27
parseResolvedPath,
28
+ parseT3Home,
29
parseWslRuntimeRoot,
30
windowsToWslPathImpl,
31
} from "./DesktopWslEnvironment.ts";
@@ -96,10 +96,9 @@ describe("WSL runtime cache", () => {
96
it.each([
97
[
98
"install",
99
- (id: string) => buildWslRuntimeInstallScript("/runtime.tar.gz", id, "b".repeat(64)),
99
+ (id: string) => buildWslRuntimeInstallScript("/runtime.tar.gz", id, "b".repeat(64), null),
100
],
101
- ["prune", buildWslRuntimePruneScript],
102
- ["invalidate", buildWslRuntimeInvalidateScript],
101
+ ["prune", (id: string) => buildWslRuntimePruneScript(id, null)],
102
] as const)("sanitizes cache ids in the %s script", (_, buildScript) => {
103
const runtimeId = "1.2.3/x64; touch /tmp/nope";
104
const script = buildScript(runtimeId);
@@ -139,11 +138,11 @@ describe.skipIf(posixShellRunner === null)("WSL runtime install script (executed
138
const archiveSha = readField(result.stdout, "archiveSha");
139
const runtimeId = `sha256-${archiveSha}`;
140
// WSL does not inherit HOME; embed the fixture's override in the script.
142
- const installScript = (archive = archivePath, sha = archiveSha) =>
141
+ const installScript = (archive = archivePath, sha = archiveSha, t3Home: string | null = null) =>
142
[
143
`HOME=${sh(`${work}/home`)}`,
144
"export HOME",
146
- buildWslRuntimeInstallScript(archive, runtimeId, sha),
145
+ buildWslRuntimeInstallScript(archive, runtimeId, sha, t3Home),
146
].join("\n");
147
return {
148
work,
@@ -154,7 +153,8 @@ describe.skipIf(posixShellRunner === null)("WSL runtime install script (executed
153
runtimeRoot: `${work}/home/.t3/wsl-runtime/${runtimeId}`,
154
serverEntry: `${work}/home/.t3/wsl-runtime/${runtimeId}/t3`,
155
installScript,
157
- install: (archive?: string, sha?: string) => runShell(installScript(archive, sha)),
156
+ install: (archive?: string, sha?: string, t3Home?: string | null) =>
157
+ runShell(installScript(archive, sha, t3Home)),
158
};
159
};
160
@@ -200,6 +200,24 @@ describe.skipIf(posixShellRunner === null)("WSL runtime install script (executed
200
expect(provider.stdout).toBe("linux-node-provider\n");
201
});
202
203
+ it("stages the runtime under the login shell's T3CODE_HOME and reports it to the launcher", () => {
204
+ const fixture = createFixture();
205
+ const t3Home = `${fixture.work}/home/.config/t3 home`;
206
+ const install = fixture.install(undefined, undefined, t3Home);
207
+ expect(install.status, install.stderr).toBe(0);
208
+ expect(parseWslRuntimeRoot(install.stdout)).toBe(`${t3Home}/wsl-runtime/${fixture.runtimeId}`);
209
+ expect(runShell(`test ! -e ${sh(`${fixture.work}/home/.t3`)}`).status).toBe(0);
210
+
211
+ const probe = runShell(
212
+ [
213
+ `bash() { ( export T3CODE_HOME=${sh(t3Home)}; eval "$2" ); }`,
214
+ buildWslRuntimeProbeScript(),
215
+ ].join("\n"),
216
+ );
217
+ expect(probe.status, probe.stderr).toBe(0);
218
+ expect(parseT3Home(probe.stdout)).toBe(t3Home);
219
+ });
220
+
221
it("keeps the inherited PATH when bash is unavailable", () => {
222
const fixture = createFixture();
223
expect(fixture.install().status).toBe(0);
@@ -382,7 +400,7 @@ describe.skipIf(posixShellRunner === null)("WSL runtime install script (executed
400
`sh ${sh(`${fixture.work}/select.sh`)}`,
401
`HOME=${sh(`${fixture.work}/home`)}`,
402
"export HOME",
385
- buildWslRuntimePruneScript("sha256-current"),
403
+ buildWslRuntimePruneScript("sha256-current", null),
404
`test -d ${sh(fixture.runtimeRoot)}`,
405
].join("\n"),
406
);
@@ -463,11 +481,15 @@ describe.skipIf(posixShellRunner === null)("WSL runtime install script (executed
481
const translated = yield* wsl.windowsToWslPath("Ubuntu", fixture.archivePath);
482
expect(translated._tag).toBe("None");
483
466
- const prepared = yield* wsl.prepareRuntime("Ubuntu", {
467
- windowsPath: fixture.archivePath,
468
- runtimeId: fixture.runtimeId,
469
- sha256: fixture.archiveSha,
470
- });
484
+ const prepared = yield* wsl.prepareRuntime(
485
+ "Ubuntu",
486
+ {
487
+ windowsPath: fixture.archivePath,
488
+ runtimeId: fixture.runtimeId,
489
+ sha256: fixture.archiveSha,
490
+ },
491
+ null,
492
+ );
493
494
expect(prepared).toEqual({ ok: true, linuxAppRoot: fixture.runtimeRoot });
495
const version = runShell(`${sh(fixture.serverEntry)} --version`);
@@ -500,7 +522,7 @@ describe.skipIf(posixShellRunner === null)("WSL runtime install script (executed
522
holdInstallLock('"$runtime_parent/.sha256-locked.install.lock"'),
523
`HOME="$home"`,
524
"export HOME",
503
- buildWslRuntimePruneScript("sha256-current"),
525
+ buildWslRuntimePruneScript("sha256-current", null),
526
'test -d "$runtime_parent/sha256-current"',
527
'test -d "$runtime_parent/sha256-previous"',
528
'test -d "$runtime_parent/sha256-active"',
apps/desktop/src/wsl/DesktopWslEnvironment.ts
+64
-66
@@ -60,6 +60,7 @@ export type EnsureWslNodePtyResult =
60
readonly ok: true;
61
readonly nodePath: string;
62
readonly resolvedPath: string;
63
+ readonly t3Home: string | null;
64
}
65
| {
66
readonly ok: false;
@@ -72,6 +73,7 @@ export type ProbeWslRuntimeResult =
73
| {
74
readonly ok: true;
75
readonly resolvedPath: string;
76
+ readonly t3Home: string | null;
77
}
78
| {
79
readonly ok: false;
@@ -104,12 +106,17 @@ export class DesktopWslEnvironment extends Context.Service<
106
readonly getUserHome: (distro: string | null) => Effect.Effect<Option.Option<string>>;
107
// Use the distro IP to avoid unreliable wslhost localhost forwarding.
108
readonly getDistroIp: (distro: string | null) => Effect.Effect<Option.Option<string>>;
109
+ // A null t3Home means the distro's login shell has no absolute T3CODE_HOME, so ~/.t3 applies.
110
readonly prepareRuntime: (
111
distro: string | null,
112
archive: WslRuntimeArchive,
113
+ t3Home: string | null,
114
) => Effect.Effect<PrepareWslRuntimeResult>;
111
- readonly pruneRuntimes: (distro: string | null, runtimeId: string) => Effect.Effect<void>;
112
- readonly invalidateRuntime: (distro: string | null, runtimeId: string) => Effect.Effect<void>;
115
+ readonly pruneRuntimes: (
116
+ distro: string | null,
117
+ runtimeId: string,
118
+ t3Home: string | null,
119
+ ) => Effect.Effect<void>;
120
readonly probeRuntime: (distro: string | null) => Effect.Effect<ProbeWslRuntimeResult>;
121
readonly ensureNodePty: (
122
distro: string | null,
@@ -264,16 +271,22 @@ const WSL_RUNTIME_SELECTION_GRACE_MINUTES = 5;
271
272
const sanitizeWslRuntimeId = (value: string): string => value.replace(/[^A-Za-z0-9._-]/g, "_");
273
274
+const runtimeParentAssignment = (t3Home: string | null): string =>
275
+ t3Home === null
276
+ ? 'runtime_parent="$HOME/.t3/wsl-runtime"'
277
+ : `runtime_parent=${shellQuote(`${t3Home}/wsl-runtime`)}`;
278
+
279
// A null archive path asks for a staging directory to copy the archive into, unless the cache is ready.
280
export const buildWslRuntimeInstallScript = (
281
linuxArchivePath: string | null,
282
runtimeId: string,
283
archiveSha256: string,
284
+ t3Home: string | null,
285
): string => {
286
const safeRuntimeId = sanitizeWslRuntimeId(runtimeId);
287
const readyCheck = [
288
"set -eu",
276
- 'runtime_parent="$HOME/.t3/wsl-runtime"',
289
+ runtimeParentAssignment(t3Home),
290
`runtime_root="$runtime_parent/${safeRuntimeId}"`,
291
`ready_marker="$runtime_root/${WSL_RUNTIME_READY_MARKER}"`,
292
"runtime_entry_runs() {",
@@ -369,11 +382,11 @@ export const buildWslRuntimeInstallScript = (
382
// Two hours exceeds cold-install time while bounding orphan retention.
383
const ORPHANED_RUNTIME_SCRATCH_MAX_AGE_MINUTES = 120;
384
372
-export const buildWslRuntimePruneScript = (runtimeId: string): string => {
385
+export const buildWslRuntimePruneScript = (runtimeId: string, t3Home: string | null): string => {
386
const safeRuntimeId = sanitizeWslRuntimeId(runtimeId);
387
return [
388
"set -eu",
376
- 'runtime_parent="$HOME/.t3/wsl-runtime"',
389
+ runtimeParentAssignment(t3Home),
390
`current_runtime="$runtime_parent/${safeRuntimeId}"`,
391
'[ -d "$runtime_parent" ] || exit 0',
392
// Serialize pruning so backends cannot select and delete different previous caches.
@@ -419,15 +432,6 @@ export const buildWslRuntimePruneScript = (runtimeId: string): string => {
432
].join("\n");
433
};
434
422
-// Invalidate trees that pass install checks but fail launch probes, or each launch reuses the broken cache.
423
-export const buildWslRuntimeInvalidateScript = (runtimeId: string): string => {
424
- const safeRuntimeId = sanitizeWslRuntimeId(runtimeId);
425
- return [
426
- "set -eu",
427
- `rm -f "$HOME/.t3/wsl-runtime/${safeRuntimeId}/${WSL_RUNTIME_READY_MARKER}"`,
428
- ].join("\n");
429
-};
430
-
435
const parseAbsolutePathField = (stdout: string, field: string): string | null => {
436
const prefix = `${field}:`;
437
const line = stdout.split("\n").find((candidate) => candidate.startsWith(prefix));
@@ -448,12 +452,15 @@ const formatNodePtyProbeFailureReason = (exitCode: number): string | null =>
452
453
// Capture login-shell PATH because the server launches provider CLIs by name.
454
const RESOLVED_PATH_LINE = `printf 'resolvedPath:%s\\n' "$PATH"`;
455
+// wsl.exe --exec skips the profile, so the server only sees a profile-exported T3CODE_HOME if passed on.
456
+const T3_HOME_LINE = `printf 't3Home:%s\\n' "\${T3CODE_HOME:-}"`;
457
458
const NODE_PTY_PROBE_SCRIPT = (
459
linuxServerDir: string,
460
) => `printf 'nodePath:%s\\n' "$(command -v node 2>/dev/null)"
461
printf 'nodeVersion:%s\\n' "$(node -p 'process.versions.node' 2>/dev/null)"
462
${RESOLVED_PATH_LINE}
463
+${T3_HOME_LINE}
464
cd ${shellQuote(linuxServerDir)} && node <<'NODE' >/dev/null 2>&1
465
// The WSL Node can't read inside app.asar, so confirm what the server needs is
466
// unpacked on the real filesystem before reporting the backend healthy. Exit 3
@@ -482,7 +489,7 @@ NODE`;
489
// Resolve version-managed Node for providers without making runtime readiness depend on it.
490
// The install script already ran the staged t3, so running it again here only adds a second startup.
491
export const buildWslRuntimeProbeScript = () =>
485
- `bash -lc ${shellQuote(`${buildWslNodeEnvPreamble()}${RESOLVED_PATH_LINE}`)} 2>/dev/null || ${RESOLVED_PATH_LINE}`;
492
+ `bash -lc ${shellQuote(`${buildWslNodeEnvPreamble()}${RESOLVED_PATH_LINE}\n${T3_HOME_LINE}`)} 2>/dev/null || ${RESOLVED_PATH_LINE}`;
493
494
const TOOLCHAIN_CHECK_SCRIPT = [
495
"for tool in node make g++ python3; do",
@@ -553,6 +560,10 @@ export const parseResolvedPath = (stdout: string): string | null => {
560
return resolvedPath.length > 0 ? resolvedPath : null;
561
};
562
563
+// Relative values are ignored: the runtime scripts and the server would resolve them from different cwds.
564
+export const parseT3Home = (stdout: string): string | null =>
565
+ parseAbsolutePathField(stdout, "t3Home");
566
+
567
const formatMissingToolsReason = (
568
report: ToolchainReport,
569
requiredRange: string | null,
@@ -614,7 +625,7 @@ const probeWslRuntimeImpl = Effect.fn("DesktopWslEnvironment.probeWslRuntimeImpl
625
reason: "WSL login-shell PATH could not be resolved during backend preflight.",
626
} as const;
627
}
617
- return { ok: true, resolvedPath } as const;
628
+ return { ok: true, resolvedPath, t3Home: parseT3Home(probe.stdout) } as const;
629
});
630
631
const ensureNodePtyImpl = Effect.fn("DesktopWslEnvironment.ensureNodePtyImpl")(function* (
@@ -634,6 +645,7 @@ const ensureNodePtyImpl = Effect.fn("DesktopWslEnvironment.ensureNodePtyImpl")(f
645
);
646
const nodePath = parseNodePath(probe.stdout);
647
const resolvedPath = parseResolvedPath(probe.stdout);
648
+ const t3Home = parseT3Home(probe.stdout);
649
650
const transportFailureReason = formatWslShellTransportFailureReason(probe.transportFailure);
651
if (transportFailureReason !== null) {
@@ -700,7 +712,7 @@ const ensureNodePtyImpl = Effect.fn("DesktopWslEnvironment.ensureNodePtyImpl")(f
712
fatal: true,
713
} as const;
714
}
703
- return { ok: true, nodePath, resolvedPath } as const;
715
+ return { ok: true, nodePath, resolvedPath, t3Home } as const;
716
}
717
718
if (options.allowBuild !== true) {
@@ -773,7 +785,7 @@ const ensureNodePtyImpl = Effect.fn("DesktopWslEnvironment.ensureNodePtyImpl")(f
785
retryLimit: BUILD_TRANSPORT_RETRY_LIMIT,
786
} as const;
787
}
776
- if (build.exitCode === 0) return { ok: true, nodePath, resolvedPath } as const;
788
+ if (build.exitCode === 0) return { ok: true, nodePath, resolvedPath, t3Home } as const;
789
const trimmedTail = `${build.stdout}${build.stderr}`.trim().slice(-500);
790
return {
791
ok: false,
@@ -789,11 +801,12 @@ type WslRuntimeInstallOutcome =
801
const runWslRuntimeInstall = Effect.fn("desktop.wsl.runRuntimeInstall")(function* (
802
distro: string | null,
803
archive: WslRuntimeArchive,
804
+ t3Home: string | null,
805
linuxArchivePath: string | null,
806
): Effect.fn.Return<WslRuntimeInstallOutcome, never, ChildProcessSpawner.ChildProcessSpawner> {
807
const install = yield* runWslShell(
808
distro,
796
- buildWslRuntimeInstallScript(linuxArchivePath, archive.runtimeId, archive.sha256),
809
+ buildWslRuntimeInstallScript(linuxArchivePath, archive.runtimeId, archive.sha256, t3Home),
810
RUNTIME_INSTALL_TIMEOUT,
811
{ resolveNode: false },
812
);
@@ -832,9 +845,10 @@ const installWslRuntimeFromHostCopy = Effect.fn("desktop.wsl.installRuntimeFromH
845
function* (
846
distro: string | null,
847
archive: WslRuntimeArchive,
848
+ t3Home: string | null,
849
archiveBytes: Stream.Stream<Uint8Array, PlatformError.PlatformError>,
850
): Effect.fn.Return<PrepareWslRuntimeResult, never, ChildProcessSpawner.ChildProcessSpawner> {
837
- const staged = yield* runWslRuntimeInstall(distro, archive, null);
851
+ const staged = yield* runWslRuntimeInstall(distro, archive, t3Home, null);
852
if (!staged.ok || parseWslRuntimeRoot(staged.stdout) !== null) {
853
return toPrepareWslRuntimeResult(staged);
854
}
@@ -875,7 +889,7 @@ const installWslRuntimeFromHostCopy = Effect.fn("desktop.wsl.installRuntimeFromH
889
} as const;
890
}
891
return toPrepareWslRuntimeResult(
878
- yield* runWslRuntimeInstall(distro, archive, linuxArchivePath),
892
+ yield* runWslRuntimeInstall(distro, archive, t3Home, linuxArchivePath),
893
);
894
});
895
@@ -892,6 +906,7 @@ const installWslRuntimeFromHostCopy = Effect.fn("desktop.wsl.installRuntimeFromH
906
const prepareWslRuntimeImpl = Effect.fn("desktop.wsl.prepareRuntimeImpl")(function* (
907
distro: string | null,
908
archive: WslRuntimeArchive,
909
+ t3Home: string | null,
910
windowsToWslPath: (
911
distro: string | null,
912
windowsPath: string,
@@ -907,21 +922,23 @@ const prepareWslRuntimeImpl = Effect.fn("desktop.wsl.prepareRuntimeImpl")(functi
922
return yield* installWslRuntimeFromHostCopy(
923
distro,
924
archive,
925
+ t3Home,
926
fileSystem.stream(archive.windowsPath),
927
);
928
}
929
return toPrepareWslRuntimeResult(
914
- yield* runWslRuntimeInstall(distro, archive, linuxArchivePath.value),
930
+ yield* runWslRuntimeInstall(distro, archive, t3Home, linuxArchivePath.value),
931
);
932
});
933
934
const pruneWslRuntimesImpl = Effect.fn("desktop.wsl.pruneRuntimesImpl")(function* (
935
distro: string | null,
936
runtimeId: string,
937
+ t3Home: string | null,
938
): Effect.fn.Return<void, never, ChildProcessSpawner.ChildProcessSpawner> {
939
const result = yield* runWslShell(
940
distro,
924
- buildWslRuntimePruneScript(runtimeId),
941
+ buildWslRuntimePruneScript(runtimeId, t3Home),
942
RUNTIME_PRUNE_TIMEOUT,
943
{ resolveNode: false },
944
);
@@ -935,26 +952,6 @@ const pruneWslRuntimesImpl = Effect.fn("desktop.wsl.pruneRuntimesImpl")(function
952
});
953
});
954
938
-const invalidateWslRuntimeImpl = Effect.fn("desktop.wsl.invalidateRuntimeImpl")(function* (
939
- distro: string | null,
940
- runtimeId: string,
941
-): Effect.fn.Return<void, never, ChildProcessSpawner.ChildProcessSpawner> {
942
- const result = yield* runWslShell(
943
- distro,
944
- buildWslRuntimeInvalidateScript(runtimeId),
945
- RUNTIME_INVALIDATE_TIMEOUT,
946
- { resolveNode: false },
947
- );
948
- if (result.transportFailure === null && result.exitCode === 0) return;
949
-
950
- const detail = `${result.stdout}${result.stderr}`.trim().slice(-500);
951
- yield* Effect.logWarning("Could not invalidate the staged WSL runtime cache.", {
952
- distro,
953
- runtimeId,
954
- detail: detail || `exit ${result.exitCode}`,
955
- });
956
-});
957
-
955
const probeWslDistros: Effect.Effect<
956
readonly WslDistro[],
957
DesktopWslDistroListError,
@@ -1154,9 +1151,13 @@ export interface DesktopWslEnvironmentTestStub {
1151
readonly prepareRuntime?: (
1152
distro: string | null,
1153
archive: WslRuntimeArchive,
1154
+ t3Home: string | null,
1155
) => PrepareWslRuntimeResult;
1158
- readonly pruneRuntimes?: (distro: string | null, runtimeId: string) => Effect.Effect<void>;
1159
- readonly invalidateRuntime?: (distro: string | null, runtimeId: string) => Effect.Effect<void>;
1156
+ readonly pruneRuntimes?: (
1157
+ distro: string | null,
1158
+ runtimeId: string,
1159
+ t3Home: string | null,
1160
+ ) => Effect.Effect<void>;
1161
readonly probeRuntime?: (distro: string | null) => ProbeWslRuntimeResult;
1162
readonly ensureNodePty?: (
1163
distro: string | null,
@@ -1188,20 +1189,19 @@ export const layerTest = (stub: DesktopWslEnvironmentTestStub = {}) => {
1189
getDistroIp: Effect.fn("DesktopWslEnvironment.getDistroIp")(function (distro) {
1190
return Effect.succeed(stub.getDistroIp?.(distro) ?? Option.none<string>());
1191
}),
1191
- prepareRuntime: Effect.fn("DesktopWslEnvironment.prepareRuntime")(function (distro, archive) {
1192
- return Effect.succeed(
1193
- stub.prepareRuntime?.(distro, archive) ?? {
1194
- ok: false,
1195
- reason: "prepareRuntime stub not configured",
1196
- },
1197
- );
1198
- }),
1199
- pruneRuntimes: Effect.fn("DesktopWslEnvironment.pruneRuntimes")(function (distro, runtimeId) {
1200
- return stub.pruneRuntimes?.(distro, runtimeId) ?? Effect.void;
1201
- }),
1202
- invalidateRuntime: Effect.fn("DesktopWslEnvironment.invalidateRuntime")(
1203
- function (distro, runtimeId) {
1204
- return stub.invalidateRuntime?.(distro, runtimeId) ?? Effect.void;
1192
+ prepareRuntime: Effect.fn("DesktopWslEnvironment.prepareRuntime")(
1193
+ function (distro, archive, t3Home) {
1194
+ return Effect.succeed(
1195
+ stub.prepareRuntime?.(distro, archive, t3Home) ?? {
1196
+ ok: false,
1197
+ reason: "prepareRuntime stub not configured",
1198
+ },
1199
+ );
1200
+ },
1201
+ ),
1202
+ pruneRuntimes: Effect.fn("DesktopWslEnvironment.pruneRuntimes")(
1203
+ function (distro, runtimeId, t3Home) {
1204
+ return stub.pruneRuntimes?.(distro, runtimeId, t3Home) ?? Effect.void;
1205
},
1206
),
1207
probeRuntime: Effect.fn("DesktopWslEnvironment.probeRuntime")(function (distro) {
@@ -1209,6 +1209,7 @@ export const layerTest = (stub: DesktopWslEnvironmentTestStub = {}) => {
1209
stub.probeRuntime?.(distro) ?? {
1210
ok: true,
1211
resolvedPath: "/usr/bin:/bin",
1212
+ t3Home: null,
1213
},
1214
);
1215
}),
@@ -1288,18 +1289,15 @@ export const layer = Layer.effect(
1289
windowsToWslPath,
1290
getUserHome,
1291
getDistroIp,
1291
- prepareRuntime: Effect.fn("desktop.wsl.prepareRuntime")(function (distro, archive) {
1292
+ prepareRuntime: Effect.fn("desktop.wsl.prepareRuntime")(function (distro, archive, t3Home) {
1293
return provideSpawner(
1293
- prepareWslRuntimeImpl(distro, archive, windowsToWslPath).pipe(
1294
+ prepareWslRuntimeImpl(distro, archive, t3Home, windowsToWslPath).pipe(
1295
Effect.provideService(FileSystem.FileSystem, fileSystem),
1296
),
1297
);
1298
}),
1298
- pruneRuntimes: Effect.fn("desktop.wsl.pruneRuntimes")(function (distro, runtimeId) {
1299
- return provideSpawner(pruneWslRuntimesImpl(distro, runtimeId));
1300
- }),
1301
- invalidateRuntime: Effect.fn("desktop.wsl.invalidateRuntime")(function (distro, runtimeId) {
1302
- return provideSpawner(invalidateWslRuntimeImpl(distro, runtimeId));
1299
+ pruneRuntimes: Effect.fn("desktop.wsl.pruneRuntimes")(function (distro, runtimeId, t3Home) {
1300
+ return provideSpawner(pruneWslRuntimesImpl(distro, runtimeId, t3Home));
1301
}),
1302
probeRuntime: Effect.fn("desktop.wsl.probeRuntime")(function (distro) {
1303
return provideSpawner(probeWslRuntimeImpl(distro));