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

[ikifar2012]

What Changed

Cache t3 code backend on local WSL filesystem

Why

Dramatically speed up launch times in WSL only mode

T3CodeWSLFixGitHub.mp4

UI Changes

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes WSL backend bootstrap, cache lifecycle, and packaged artifact layout; failures fall back to /mnt/c, but incorrect cache or prune logic could affect launch reliability or disk use on Windows+WSL.

Overview
Packaged Windows builds can ship a wsl-runtime.tar.gz (plus SHA-256 and content-id sidecars) built from the server tree; the desktop no longer relies on eagerly materializing server.asar for WSL preflight.

WSL backend resolution now prefers installing that archive into ~/.t3/runtime under a cache key sha256-<contentId> (stable across app versions when the server payload is unchanged), probes node-pty against the Linux app root, and launches from the cached tree. If staging or the probe fails, it falls back to the /mnt/c mounted server tree, with rules to invalidate bad caches, preserve retryable vs fatal preflight outcomes, and avoid wiping caches still in use.

After HTTP readiness, DesktopBackendManager prunes older runtime directories (keeping current + one previous). DesktopWslEnvironment gains prepareRuntime, pruneRuntimes, and invalidateRuntime (POSIX install scripts with locking and digest checks); ensureNodePty now takes a Linux app root instead of a Windows repo path.

User install docs describe first-launch extraction and cache behavior; build tests cover content-id hashing and packaging invariants.

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

Note

Add WSL-local runtime cache to avoid /mnt/c overhead on launch

• On first launch, the desktop app extracts a bundled server runtime archive into ~/.t3/runtime inside the WSL distro; subsequent launches reuse this Linux-local copy instead of running from /mnt/c.
• The build packages wsl-runtime.tar.gz, a .sha256, and a .content-id as Windows extraResources (excluded from app.asar), gated on a Linux node-pty prebuild and supported arch.
• Preflight prefers the staged runtime, falls back to the mounted server tree on failure, and invalidates a broken staged cache so the next launch reinstalls it.
• After the backend reports ready, DesktopWslEnvironment.pruneRuntimes removes old caches, retaining the active runtime and one previous for rollback.
• Risk: ensureNodePty now takes linuxAppRoot instead of windowsRepoRoot; callers in DesktopBackendConfiguration.ts and test stubs are updated. Windows builds without a Linux node-pty prebuild will not ship WSL runtime artifacts.

^{Macroscope summarized 1814e23.}

[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: 2149414e-248b-4c38-95cc-be89b0133a0b

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a new persistent WSL runtime-cache lifecycle and changes Windows artifact packaging, startup selection, fallback, native probing, and post-launch pruning. The cross-cutting runtime and filesystem behavior is substantially beyond a small self-contained fix and merits human review.

Notes:

• No code objects were reviewed. Approvability was decided on eligibility alone.

^{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

[ikifar2012]

Hey @SunkenInTime I ran my agent through all your comments, tested it myself and it appears to have fixed the issues you commented on, could you take another look?

[t3-code]

re-reviewed exact updated head 3db01b29d384956d7039f70f87287e6220bcd827.

code review: approved. all prior blockers are fixed: tar receives a relative Windows target; the Arch nightly docs remain with Arch; archive bytes are checked against the SHA-256 sidecar; missing or unloadable node-pty caches reinstall or use the mounted fallback and invalidate safely; active runtime processes are excluded from pruning. an executed adversarial probe confirmed install, missing-native repair, hash-mismatch rejection, and retention of two live runtime processes.

local verification: 146/146 focused tests and 790/790 broader desktop/scripts tests pass at the exact head. desktop/scripts typechecks, formatting, and diff checks pass. lint exits successfully with one unused-variable warning in DesktopBackendConfiguration.test.ts:979.

current-main integration: the exact head merges cleanly with current origin/main (f70eeeeb06d6d96f292be7eef1ed8948103e68dc) and the synthetic merge passes the same 146/146 focused and 790/790 broader tests, typechecks, formatting, and diff checks. current main's repeated readiness probing is preserved.

ci: normal CI/web/mobile workflows remain action_required with zero jobs because this is an unvouched fork. Vercel also reports authorization required. code approval is therefore 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.

[t3-code]

follow-up request: please key the WSL runtime cache directory solely by the verified runtime content identity, rather than ${appVersion}-${arch}-${archiveHash}. for example, a sha256-${archiveHash} key would let a new desktop release reuse the existing distro-local runtime when its server archive is unchanged. the verified archive digest already distinguishes different target payloads, including architecture.

for that reuse to work reliably, the identity also needs to be stable across equivalent builds. the current plain tar -czf output includes filesystem and compression metadata, so logically identical server trees can still produce different archive hashes. please either make archive creation reproducible (stable order, timestamps, ownership, and gzip metadata) or compute a canonical content-tree hash and verify it during installation.

please add regressions proving:

• two app versions with the same runtime content resolve to the same cache directory;
• equivalent source trees with different incidental filesystem metadata produce the same runtime identity;
• changed server content produces a different identity and reinstalls.

this does not affect the normal unpackaged dev path: resolveWsl only uses this archive cache when environment.isPackaged; dev launches from the mounted tree. packaged/dev artifact testing already invalidates when server changes because the archive hash changes. the main win here is cross-release reuse when the server payload did not change.

[ikifar2012]

Can I trigger T3 Code Bot?

[ikifar2012]

Ok I think we are all good

[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.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

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

[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.