fix(desktop): Cache Runtime locally on WSL Filesystem, dramatically improving launch times

[ikifar2012]

What Changed

• packages a Linux-only WSL server runtime beside the Windows desktop app
• verifies the archive SHA-256 before installing it under ~/.t3/wsl-runtime
• reuses warm installs, repairs corrupted entries, and safely prunes old or invalid caches
• preserves active and concurrently installing runtimes
• removes the legacy Windows extraction tree after the distro-local runtime passes preflight
• keeps the mounted server.asar tree as a fallback
• shares one packaged WSL test harness across the seven cache and fallback cases
• normalizes Windows bsdtar CRLF member listings before payload validation
• invalidates legacy completion markers before best-effort recursive cleanup

Why

Launching the backend from WSL's Linux filesystem avoids repeated /mnt/c reads. The cache now has a desktop-owned directory and one verified archive identity, while the build omits Windows/Darwin native payloads and pnpm install metadata that WSL cannot use.

Verification

• exact head: 180 focused and 819 broader desktop/scripts tests
• synthetic current main: 180 focused and 819 broader desktop/scripts tests
• desktop and scripts typechecks
• lint, formatting, diff checks, and release smoke
• executed POSIX-shell coverage for install locking, archive refusal, corruption recovery, and pruning

T3CodeWSLFixGitHub.mp4

---

Note

Medium Risk
Reworks packaged Windows WSL backend startup, cache identity, and fallback ordering; mis-handled transient vs fatal preflight outcomes could affect launch reliability despite extensive tests.

Overview
Packaged Windows builds now ship wsl-runtime.tar.gz plus a SHA-256 sidecar (when a Linux node-pty prebuild is bundled). WSL resolution prefers installing that archive into ~/.t3/wsl-runtime/sha256-<digest> via new DesktopWslEnvironment APIs (prepareRuntime, invalidateRuntime, pruneRuntimes) and generated install/prune shell scripts (locking, digest checks, readiness markers, in-use detection).

runWslPreflight no longer always materializes server.asar up front: it stages and probes the cached runtime first, runs legacy Windows extraction cleanup on success, and falls back to the mounted /mnt server tree when staging fails or a fatal staged node-pty probe fails (invalidating the bad cache when the fallback works). DesktopBackendManager records wslRuntimeId on the start config and prunes older caches after HTTP readiness.

The desktop artifact builder stages the Linux-only archive (excludes Windows/Darwin natives and pnpm metadata), validates archive/hash/members in packaged payloads, and docs describe the new WSL install behavior. Tests cover configuration fallbacks, manager pruning, server-tree cleanup, script generation, and executed POSIX install races.

^{Reviewed by Cursor Bugbot for commit cee8a4a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Cache WSL runtime on WSL filesystem to improve desktop launch times

• Ships a compressed Linux-only WSL runtime archive (wsl-runtime.tar.gz + .sha256 sidecar) as a Windows extraResource; build-desktop-artifact.ts stages, hashes, and validates it during the Windows build
• runWslPreflight in DesktopBackendConfiguration.ts now stages the packaged archive into a distro-local cache via DesktopWslEnvironment.prepareRuntime, probes it, and falls back to the mounted server tree only when staging fails fatally
• DesktopWslEnvironment.ts gains prepareRuntime, pruneRuntimes, and invalidateRuntime; the install script uses POSIX flock, SHA-256 digest verification, atomic promotion, and in-use safety; the prune script retains the current and one previous cache
• After backend readiness, makeBackendInstance in DesktopBackendManager.ts calls pruneRuntimes to remove older caches; cleanupLegacy in DesktopWslServerTree.ts removes the old Windows extraction cache once the staged runtime is healthy
• Risk: ensureNodePty now expects a linuxAppRoot path instead of converting a Windows path internally; any caller still passing windowsRepoRoot will break. WSL launches that previously always used the mounted tree now depend on a staged cache and may fall back if the archive is missing or corrupt

^{Macroscope summarized dc98770.}

request provenance

• requested by: @UtkarshUsername

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 901a1437-6992-474d-859a-c6238ec08835

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a large, cross-cutting change to packaged WSL startup and Windows release artifacts, introducing local runtime extraction, integrity checks, fallback ordering, cache invalidation, pruning, and filesystem cleanup. Because the new path is automatically selected and has significant runtime and persistent side effects, its blast radius requires human review despite the extensive test coverage.

^{You can add or adjust custom eligibility rules. Learn more.}

[moinmir]

One idea: key the cache on a hash of the archive instead of <version>-<arch>. A release that does not change the server would then reuse the existing directory in ~/.t3/runtime.

[carlospedreira]

This is actually a better solution than the one that I'm proposing on #4825 because it's actually fixing the issue rather than just increasing the wait time. Happy to close my PR and support this one instead.

[moinmir]

I was working on a similar PR and saw this created. The solution looks correct. I ran an AI review comparing this PR to my solution and found some issues that I'm posting here. I don't understand the code 100% but these seem reasonable. Feel free to disregard if they are not useful.

[ikifar2012]

Asked my agent to implement some of the changes suggested by @moinmir, all seems to work well, waiting on other pending checks on github but I guess I can get to those tomorrow, if the PR agents have any more suggestions... looks like there are a bunch of other WSL PR's as well so idk who's will get merged, after this I gotta see if there's anything I can do about install speed because it takes forever

[t3-code]

re-reviewed exact updated head cb5d9dd15d2a382d03698e79ee7ef0fc16bf1451.

changes requested: cross-release content-only cache naming is implemented, but two cache-identity/recovery gaps remain. details inline.

verified fixed: the cache key is now sha256-<contentId> with no app version or architecture prefix; equivalent trees with different mtimes keep one id; changed file bytes change the id; archive bytes and the embedded content-id manifest are checked; the new extra resource is excluded from app.asar; reinstalls preserve in-use runtimes. all earlier tar, docs, node-pty recovery, archive-integrity, and prune-lease fixes remain present.

local verification: exact head passes 154/154 focused tests and 798/798 broader desktop/scripts tests. desktop/scripts typechecks, formatting, and diff checks pass. lint exits successfully with one unused-variable warning in DesktopBackendConfiguration.test.ts:1079.

current-main integration: cleanly mergeable with current origin/main (e67074f80933a27bd3cdc4e24f486358407690fb); synthetic merge passes 157/157 focused and 802/802 broader tests, typechecks, formatting, and diff checks.

ci: normal CI/web/mobile workflows are still action_required with zero jobs because this is an unvouched fork. code review, CI, and actual merge readiness remain separate.

release readiness: I did not run a Windows packaged WSL end-to-end launch, so this review does not establish Windows + WSL release readiness.

[t3-code]

re-reviewed exact updated head 1814e23fcefb740eeb7a65de72699c528a126773.

code review: approved. both prior blockers are fixed. warm-cache reuse now verifies bin.mjs against the digest recorded at install, and the former zero-byte-entry reproduction now fails over when the archive is unavailable or repairs from it when available. the content id now includes semantic executable bits, entry types, root-directory modes, and symlink targets while remaining insensitive to ownership and mtimes. real-shell regressions exercise warm reuse, corruption repair/fallback, concurrent installation, failed extraction cleanup, archive-digest refusal, and content-id refusal. no new code findings.

local verification: exact head passes 170/170 focused tests and 815/815 broader desktop/scripts tests. desktop/scripts typechecks, formatting, and diff checks pass. lint exits successfully with one unused-variable warning in DesktopBackendConfiguration.test.ts:1079.

current-main integration: cleanly mergeable with current origin/main (a3a8cbd60539b4af4de8f96c892dbd07a2b6c041); synthetic merge passes the same 170/170 focused and 815/815 broader tests, typechecks, formatting, and diff checks.

ci: normal CI, web/mobile previews, fingerprint, and desktop macOS preview remain action_required with zero jobs because this is an unvouched fork. code approval is separate from actual merge readiness.

release readiness: I did not run a Windows packaged WSL end-to-end launch, so this review does not establish Windows + WSL release readiness.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit cee8a4a. Configure here.}