perf(desktop): speed up Windows update installation

[StiensWout]

Windows desktop updates still spend most of their install time creating loose files, even after the bundled-server work in #5877 reduced the payload to roughly 1,200 files.

This PR moves the bundled server and only its runtime-external/native dependency closure into a dedicated resources/server.asar sidecar. The Windows primary reads the archive in place through Electron. WSL extracts it atomically into a versioned cache only when WSL is enabled.

After rebasing onto current main with #5877:

• The shared external-package list drives both bundling and the sidecar dependency roots: @ff-labs/fff-node, msgpackr-extract, and node-pty.
• The emitted-bundle guards, native-loader checks, dependency-closure checks, and isolated runtime probe remain in place.
• The final copied sidecar is checked for its server entry, unpacked natives, resource monitor, an 80-file payload budget, and successful node bin.mjs --version execution from a clean extracted tree.
• On same-architecture Windows builds, the packaged primary must also create and destroy a real FileFinder from inside server.asar, proving Electron redirects both fff and ffi natives to the .unpacked sibling. Cross-architecture builds retain the structural and extracted-sidecar checks without executing the target Electron binary.
• WSL extraction uses one globally bounded eight-entry traversal, avoiding recursive concurrency pools and unbounded fiber growth.\n- The existing release path continues to supply the Linux node-pty prebuild used by WSL.

Verification:

• vp run --filter @t3tools/scripts typecheck
• vp run --filter @t3tools/desktop typecheck
• vp run --filter t3 typecheck
• vp run --filter t3 build:bundle
• focused lint and formatting checks\n- direct nested traversal probe: 4,681 entries visited, maximum concurrency 8, active work returned to 0\n- direct x64-host/ARM64-target probe confirmed the target executable is skipped before filesystem access
• real local sidecar stage and extracted-runtime probe: 3 dependency roots, 85,095,471-byte sidecar, 33 unpacked natives, and 36 files in the synthetic packaged payload
• positive and missing-dependency runtime probes both passed
• focused Vitest files remain blocked before collection by the existing @effect/vitest config error, reproduced after vp i

Implemented by GPT-5.6-sol with Codex in the T3 Code harness.

---

Note

High Risk
Large Windows packaging and backend bootstrap change (dual-ASAR layout, WSL extraction, native-load probes); regressions would break installs, updates, or WSL/primary backends on Windows.

Overview
Windows update/install speed is the main goal: the bundled server and its runtime-external/native deps move out of app.asar into a dedicated resources/server.asar sidecar (natives in server.asar.unpacked), delivered via extraResources, with NSIS differentialPackage: true kept on.

Runtime: DesktopEnvironment gains serverRoot (packaged Windows → resources/server.asar; elsewhere unchanged). The Windows primary still runs the entry through asar-aware ELECTRON_RUN_AS_NODE. DesktopWslServerTree materializes the sidecar into a version-keyed wsl-server-tree/<version> directory on first WSL use (bounded copy, serialized callers, stale sweep); resolveWsl preflight now depends on that instead of app.asar.unpacked. The @ff-labs/fff-node patch generalizes .asar → .asar.unpacked for any archive segment.

Build/packaging: Windows drops asarUnpack on the app; stageWindowsServerSidecar hoists a minimal prod install, packs with @electron/asar, and omits the server tree from the app stage. selectCliRuntimeExternalDependencies drives sidecar roots (aligned with bundling). Post-build validateWindowsPackagedPayload checks sidecar integrity, unpacked natives, resource monitor, an 80-file budget, extracted bin.mjs --version, and on same-arch builds a live fff probe via the packaged Electron binary.

Docs/tests: Release notes describe the new Windows payload topology; broad desktop and artifact tests cover the new paths.

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

Note

Ship Windows server bundle as a separate server.asar sidecar to speed up updates

• Moves the Windows server bundle out of app.asar and into a dedicated resources/server.asar (with natives in server.asar.unpacked), so NSIS differential updates only re-download changed blocks rather than a monolithic archive.
• Adds stageWindowsServerSidecar in build-desktop-artifact.ts to install hoisted production dependencies for both win32 and linux targets, pack them into server.asar, and place unpacked natives alongside.
• Adds DesktopWslServerTree in DesktopWslServerTree.ts to extract and version-key the sidecar into a state directory before WSL backend startup, serializing concurrent callers and sweeping stale versions.
• Updates DesktopEnvironment so serverRoot points to resources/server.asar on packaged Windows, and DesktopBackendConfiguration.resolveWsl gates WSL preflight on successful sidecar extraction.
• Adds validateWindowsPackagedPayload to verify sidecar integrity, unpacked native presence, resource-monitor existence, fff native load via ELECTRON_RUN_AS_NODE, isolated self-containment check, and a ≤80-file budget before artifact finalization.
• Behavioral Change: Windows app.asar no longer contains the server tree; NSIS differential packaging is now enabled (differentialPackage: true), which changes blockmap size and update download behavior.

^{Macroscope summarized f9a65c2.}

[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: 571fd5f2-ac02-447c-abd9-ca7ab067f5cb

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: Needs human review

This PR restructures Windows packaging from loose files to a server.asar sidecar architecture and introduces lazy runtime extraction for WSL users. With ~1800 additions including a new DesktopWslServerTree service, new build/validation logic, new dependencies, and production deployment topology changes, this significant architectural change warrants human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[SunkenInTime]

I reproduced two Windows blockers on the current head (4e8da44e5018a19e8cb8a2f1d2d7e053cc00e9db) with a real unsigned x64 NSIS build.

Command:

node scripts/build-desktop-artifact.ts --platform win --target nsis --arch x64 \
  --build-version 0.0.34-nightly.20260812.6169 \
  --output-dir release/pr-review/6169/head --keep-stage

1. The build runs for 255.22 s, produces the installer, then exits 1 in validateWindowsPackagedPayload:

WindowsPackagedPayloadValidationError: Windows packaged payload contains an invalid server.asar sidecar.
[cause]: Error: "apps/server/dist/bin.mjs" was not found in this archive

The entry is present. On Windows, @electron/asar.statFile expects a native-separator path: statFile(asarPath, "apps\\server\\dist\\bin.mjs") succeeds, while the current hard-coded "apps/server/dist/bin.mjs" fails. The three new payload-validation tests fail for the same reason.

2. Independently, the generated win-unpacked/resources has server.asar but no server.asar.unpacked directory. The source staging directory contains 35 native files (29,905,936 bytes), and the ASAR header declares all 35 as unpacked, but none are copied into the packaged app. The resulting payload has only 34 total files. Bypassing the validator would therefore still ship a Windows backend that cannot load those native modules.

Please fix both paths and add a Windows-running regression test/build check before merging. The current Linux CI is green but does not exercise this behavior.

[SunkenInTime]

Follow-up from launching the exact generated win-unpacked/T3 Code (Nightly).exe with isolated APPDATA and T3CODE_HOME:

• The Electron root stays alive but has MainWindowHandle = 0; no renderer/window is created.
• No server-runtime.json readiness receipt is written.
• The backend restarted 11 times during the observation window.
• Every child exits with ERR_DLOPEN_FAILED while resolving the absent path:

resources\server.asar.unpacked\node_modules\@yuuang\ffi-rs-win32-x64-msvc\ffi-rs.win32-x64-msvc.node

So the missing unpacked sidecar is confirmed as a user-visible startup failure, not just a packaging invariant.

[StiensWout]

[gpt-5.6-sol] RESPONDING ON BEHALF OF WOUT:

@SunkenInTime Thanks for the concrete Windows repro. Both blockers are fixed on the latest head.

• The ASAR entry check now uses the host-native path from path.join(...), so statFile succeeds on Windows.
• server.asar and server.asar.unpacked are now staged under one parent resource directory and copied with a single electron-builder matcher, avoiding the dropped standalone .unpacked FileSet.
• Added a path-filtered Windows CI workflow that builds and validates a real unsigned x64 NSIS artifact.

The new Windows package run passed: Windows Package Smoke. The final payload validator reported 70 files and all 35 ASAR-unpacked sidecar natives present. The fixes landed in e8e553cb3; the current head is f9b6fbf5b.

[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 f9b6fbf. Configure here.}

[SunkenInTime]

Re-tested the updated head 5a0b97e1d671008a7ae507e47997c8cb9ccd30c6 end to end on Windows 11 after the three follow-up commits.

The original blockers are fixed:

• the exact release build completed successfully in 285.31s and validated server.asar plus 35 unpacked native sidecars
• the resulting installer is 161,607,727 bytes (154.12 MiB)
• an isolated silent install completed in 11.42s and produced 70 installed files
• the packaged backend receipt appeared 3.88s after process start
• the actual installed Electron window rendered the T3 Code UI successfully
• focused desktop/scripts typechecks pass, and the new CI Package unsigned x64 NSIS artifact job is green

The remaining 7/69 failures in my Windows-focused local test selection are path-separator expectations in tests; the functional sidecar validation cases passed and CI Check/Test are green. I consider the two packaging findings I reported above resolved and this updated PR ready to merge.

[t3-code]

hey @StiensWout, thanks for the work and the Windows verification here. could you update/rework this PR on current main now that #5877 has merged?

the merged work improves the foundation this PR can build on:

• the server cli now bundles ordinary js dependencies
• one shared external-package list drives both bundling and packaging
• Windows only needs the required external/native closure outside the asar instead of the whole node_modules tree
• emitted-bundle guards and an isolated runtime probe catch missing, incorrectly bundled, or staging-leaked dependencies

with that in place, server.asar should be buildable from the bundled server output plus only the required external/native packages. it should no longer need a separate hoisted install of the full server dependency tree. that should make the sidecar smaller and simpler while retaining the merged correctness checks.

suggested rework:

1. rebase onto current main; the current textual conflicts are in scripts/build-desktop-artifact.ts and its test.
2. preserve the shared external list, emitted-bundle checks, selective packaging model, symlink-isolated probe, and regression tests.
3. derive the sidecar contents from the bundled server plus the shared runtime-external/native closure instead of resolvedServerDependencies wholesale.
4. adapt the self-containment probe to validate the extracted sidecar tree, in addition to checking the asar entry, unpacked natives, resource monitor, and file-count budget.
5. recalibrate the file-count budget against the current topology.
6. expand the Windows smoke workflow paths to cover the bundler/external-list and desktop runtime files. either include the release WSL prebuild or clearly scope the job as Windows-primary/package-only.
7. rerun the real NSIS install/launch and WSL backend test with build staging removed, then report the incremental file-count, install/update-time, and artifact-size benefit over current main.

one possible approach is to split this into:

• a low-risk PR for Windows package CI and payload/integrity guards
• a measured architecture PR for server.asar, backend-root changes, and lazy WSL extraction/cache

that would let the validation improvements land independently while the runtime topology gets focused benchmarking and review. the sidecar reportedly reduced the installed payload from 1,192 files to 70, so keeping it together may also be reasonable if the new benchmark still shows a worthwhile gain. happy for you to choose whichever structure you think is best.

[StiensWout]

[gpt-5.6-sol] RESPONDING ON BEHALF OF WOUT:

Rebased and reworked on current main (7e01d33f0); the latest head is db44b0f3b.

• The sidecar is now built from the bundled server plus the shared runtime-external closure only: @ff-labs/fff-node, msgpackr-extract, and node-pty.
• The emitted-bundle/native guards, selective closure checks, and symlink-isolated runtime probe from perf(build): stop unpacking node_modules wholesale from the Windows asar #5877 remain intact.
• Validation now extracts the final copied resources/server.asar, blocks ancestor/global module leakage, checks the server entry, unpacked natives and resource monitor, then executes node bin.mjs --version from that clean tree.
• The payload budget is recalibrated to 80 files.
• WSL still extracts atomically into its versioned cache on first use.

Wout requested that this PR not add repository CI, so the PR-added Windows package-smoke workflow has been removed; the final diff has no .github changes. The standard Check, Test, Release Smoke, native analysis, fingerprint, Cursor, and Macroscope checks are green on the latest head.

For concrete topology evidence, the local isolated stage has 3 dependency roots, 33 unpacked natives, and 36 files in the synthetic packaged payload. The Windows package run on the immediately preceding code-equivalent head also passed with 70 files and 35 sidecar natives; the only subsequent source change was deleting that workflow. I have not claimed fresh NSIS install/update timing or a real WSL end-to-end run for the rebased topology, because those were not rerun from this Linux worktree.

[t3-code]

requesting changes on exact head db44b0f3bca31c678ac1aaa6a275cac27822a95a. the sidecar rework now correctly uses the bundled server plus the shared minimal external/native closure, and the focused tests/static checks pass. however, the windows primary has a native-library path blocker: it runs from server.asar, while the existing fff patch only redirects app.asar paths to their .unpacked sibling. the current extracted plain-node probe cannot catch failures caused by electron's in-asar path. please fix the redirect for this sidecar and add a primary-runtime probe that exercises fff from inside the packed archive.

verified locally: 90 focused tests, desktop/server/scripts typechecks, formatting, focused lint, build:desktop, a real minimal sidecar stage, extracted native imports, and materialized linux node-pty spawn. these do not replace windows nsis + primary + wsl end-to-end validation or performance measurements on this rebased head.

[t3-code]

re-reviewed exact head ee24370b6116e34d19b5f14f92f78c3b34b30c49. the prior server.asar fff blocker is fixed: the patch now selects the nearest .asar segment, and the packaged windows-primary validator exercises FileFinder.create() and destroy() through the final archive. regular-file payload validation is also fixed.

two blockers remain. first, the executable probe gates only on win32, so an x64 windows host building the documented arm64 target will produce the arm64 payload and then try to execute its arm64 electron binary locally. second, the shared WSL semaphore caps filesystem operations and retained file buffers, but each recursive directory still creates its own eight-way Effect.forEach, so recursive task growth remains unbounded.

verified locally: frozen install, 92 focused tests, the full desktop/scripts suites (753 tests), desktop/server/scripts typechecks, focused lint/formatting, build:desktop, and git diff --check pass. exact-head check, test, and release smoke are green; the vercel authorization failure is unrelated. no exact-head windows nsis or windows+wsl end-to-end run is present.

[t3-code]

re-reviewed exact head 7a1e399c3c40ca41829ec488b685067624a38df6. the prior WSL traversal blocker is fixed: extraction now uses one iterative work list with a global eight-task bound, and the 4,681-node regression holds the active maximum at eight. the original cross-architecture execution failure and helper-executable selection are also fixed.

one packaging blocker remains: the architecture mismatch returns before validating that the expected application executable exists and is a regular file. an x64 host can therefore accept an arm64 payload with a valid sidecar/resource monitor but no primary app executable. keep executable existence/type validation architecture-independent and skip only its execution; add a mismatch regression that deletes the expected app executable.

verified locally: frozen install, 94 focused tests, all 755 desktop/scripts tests, desktop/server/scripts typechecks, full lint and formatting, build:desktop, and git diff --check pass. exact-head required checks (Test, Check, Mobile Native Static Analysis, and Release Smoke) pass. the vercel authorization failure is non-required and unrelated. windows + WSL release readiness remains separate, with no fresh same-architecture windows NSIS, packaged-primary, or WSL end-to-end evidence.

[t3-code]

re-reviewed exact head f9a65c27628a032cc2b81c03a510aff39665aa79. the final blocker is fixed: the expected application executable is now constructed and stat-validated for every target before architecture compatibility skips only execution, and the new x64-host/arm64-target regression removes the executable and requires WindowsPrimaryNativeProbeError. the previously verified fff sidecar loading, exact app selection, WSL traversal bound, payload checks, and bundled/minimal external closure remain intact.

verified locally: 95 focused tests and all 756 desktop/scripts tests pass; desktop/server/scripts typechecks, focused lint/formatting, and git diff --check pass. exact-head required checks (Test, Check, Mobile Native Static Analysis, and Release Smoke) pass. the vercel authorization failure is non-required and unrelated.

code review approved. the PR is textually mergeable and its required checks are green. windows + WSL release readiness remains separate because this head still has no fresh same-architecture windows NSIS, packaged-primary, or WSL end-to-end evidence.

[SunkenInTime]

Re-tested exact head f9a65c27628a032cc2b81c03a510aff39665aa79 on Windows with the worktree-local/locked toolchain.

The real unsigned x64 NSIS flow is green: it produced the installer + blockmap, validated a 69-file payload with all 35 ASAR-unpacked natives, successfully ran the packaged T3 Code (Alpha).exe fff/FileFinder probe, and completed the isolated extracted-sidecar node bin.mjs --version check.

One non-blocking test-portability follow-up remains. This focused command reports 85 passed / 10 failed on Windows:

.\node_modules\.bin\vp.cmd test run `
  apps/desktop/src/app/DesktopEnvironment.test.ts `
  apps/desktop/src/backend/DesktopBackendConfiguration.test.ts `
  apps/desktop/src/wsl/DesktopWslServerTree.test.ts `
  scripts/build-desktop-artifact.test.ts `
  scripts/lib/cli-external-packages.test.ts

The PR-added failures are:

• validates every ASAR-unpacked native... and rejects a sidecar whose extracted server bundle cannot resolve reach the same-arch primary probe and try to spawn the fixture's text file named t3code.exe, which fails with spawn UNKNOWN on Windows. Those cases need a mock child-process layer (or another fixture strategy) when the test is exercising validation rather than the real executable.
• skips the primary native probe for cross-architecture Windows payloads observes an ELECTRON_RUN_AS_NODE=1 command on Windows and fails its assertion, so the host-architecture override/layer precedence is not doing what this regression expects in the actual target environment.
• The new DesktopEnvironment sidecar assertion and DesktopBackendConfiguration primary assertion build/expect paths with literal /, so they fail against the Windows Path.Path implementation. Using the injected path service (or normalizing before comparison) would make them platform-safe.

There are additional pre-existing POSIX-path assertions in those suites, but the cases above are introduced by this PR. I would fix these so the Windows-specific regression suite is trustworthy on Windows; I did not find a new functional packaging blocker in the real artifact flow.