fix(desktop): verified update teardown on Windows+WSL, install integrity check, and resilient WSL readiness handshake

[Jgratton24]

What Changed

Two Windows+WSL reliability fixes that share one user-visible symptom (an indefinite "Connecting to WSL…" splash), plus a guard that turns the corrupted-install crash into an actionable dialog. Desktop-only; no apps/server changes.

1. Update apply is verified before the installer runs (fixes the half-applied-update corruption).

• DesktopBackendInstance.stop() now reports whether the child process actually finalized within the timeout instead of silently swallowing it (DesktopBackendManager.ts).
• The install path (DesktopUpdates.ts) aborts — restarting backends and surfacing the error through the update state machine — if any backend can't be verified stopped, instead of handing off to NSIS while a process still holds files under the install dir.
• For WSL backends, a stopped wsl.exe relay does not mean the Linux-side server (or helpers it spawned, e.g. cloudflared) exited with it. New ensureWindowsPathReleased (DesktopWslEnvironment.ts) terminates and verifies from inside the distro that no Linux process still holds cwd/exe/fd/mmap references under /mnt/c/<install dir> — 9p/DrvFs handles held from WSL block file replacement on the Windows side, which is how app.asar and app.asar.unpacked end up from different builds.
• Post-apply integrity check: the build stamps apps/server/dist/desktop-build-manifest.json (under app.asar.unpacked on Windows); startup compares it against the asar's version and refuses to launch a mixed-build install with a clear repair dialog (DesktopInstallIntegrity.ts) instead of the opaque ERR_MODULE_NOT_FOUND main-process crash. Missing manifest (dev, macOS/Linux, pre-stamp installs) skips the check, so no false positives.

2. WSL endpoint detection and the readiness handshake are no longer single-point-of-failure.

• Networking mode now comes from wslinfo --networking-mode (first-party, present on WSL 2.6.x and 2.7.x) instead of being inferred from the first address in hostname -I — whose ordering shifts whenever Tailscale, Docker bridges, or VPN adapters exist inside the distro. Heuristic fallback for older WSL matches any distro IP against Windows interfaces, never position one, and CGNAT 100.64/10 addresses are never advertised.
• Readiness probes race loopback plus every enumerated distro address; the first candidate that answers wins and becomes the advertised base URL — so a wrong guess degrades startup by nothing worse than a probe race.
• After all static candidates time out, the backend's persisted server-runtime.json origin is consulted as a last-resort candidate (gated on it naming this instance's port).
• The readiness probe is no longer one-shot: a run that spawns but never answers is terminated and retried, and after 3 readiness timeouts the failure surfaces like an exhausted preflight (dialog + Windows fallback on the primary, inline Connections error on the secondary) with every probed URL named. Resolved mode and candidates are logged at startup.

25 new tests across DesktopBackendManager, DesktopUpdates, DesktopWslEnvironment, DesktopBackendConfiguration, and DesktopInstallIntegrity cover the regressions above (CGNAT-first ordering, docker0-first, wslinfo absent, one-shot-probe limbo, unverified stop, WSL busy at install time, mixed-build detection). Full desktop suite: 473 passing.

Why

Two field incidents on 0.0.33-nightly builds, plus these open issues:

• Fixes[Bug]: Desktop stuck on "Connecting to WSL" — getDistroIp picks unreachable Docker bridge IP instead of eth0 #5211 — getDistroIpImpl takes the first IPv4 from hostname -I; Docker bridge IPs sort first and are unreachable from Windows. The same mechanism breaks with a WSL-side tailscaled (CGNAT address first under mirrored networking), which we reproduced on 0.0.33-nightly: the server was listening on 0.0.0.0:3773, reachable via loopback, and logged zero client requests because every probe went to the CGNAT address.
• Fixes[Bug]: Desktop stops probing backend readiness after the 60s budget, leaving "Connecting to WSL…" stuck forever even though the backend becomes healthy #5522 — runBackendProcess forked a single waitForHttpReady with a 60s budget; on timeout onReadinessFailure only logged, leaving the run alive, never ready, never retried, never surfaced.
• Likely fixes[Bug]: "Connecting to WSL" infinite loading #5967 (symptom-level report of the same infinite splash; root cause unconfirmed in that issue).
• Improves [Bug]: Unusable. WSL backend readiness timesout at 60s because the server bundle loads over /mnt/c (takin 80s to boot) and app stuck on "Connecting to WSL…" forever #4535 — a >60s cold boot now gets terminated-and-retried (warm second boot typically fits the budget), and after 3 attempts surfaces an actionable dialog with Windows fallback instead of an infinite splash. The 60s budget itself is unchanged, so this is mitigation, not a full fix.
• Related: Windows: app stays launchable during the multi-minute NSIS update extraction, crashes with ERR_MODULE_NOT_FOUND (false-positive #4154) #5520 — the mid-extraction launch race produces the same ERR_MODULE_NOT_FOUND signature; the integrity check turns the mixed-state launch into a clear "installation is damaged/incomplete" dialog whenever the unpacked stamp has diverged from the asar. It does not (and cannot, from app code) stop NSIS from leaving the exe launchable during extraction.

The half-applied update we debugged: an in-app update left app.asar + the exe at the old build while app.asar.unpacked/node_modules was new → ERR_MODULE_NOT_FOUND on every launch, with the updater having reported nothing. Root cause: install teardown killed the wsl.exe relay and proceeded on a 5s timeout that was silently swallowed, while the Linux-side server exited asynchronously still holding 9p handles into the install dir. Same version installed fine with the app closed.

Sizing note: aware of the contribution guidelines — roughly half of this diff is tests, and the two fixes share the same touched files (DesktopBackendManager/DesktopWslEnvironment), which is why they're one PR. Happy to split into updater-atomicity and handshake PRs if you'd prefer.

This PR deliberately avoids every file touched by #2829 (orchestrator v2) — verified against its full file list, so it merges cleanly before or after.

UI Changes

No renderer UI changes. Two native dialogs are added/extended (update-install-aborted error via the existing update state machine; "installation is damaged" message box with an Open Download Page button). Not screenshotted — they require a packaged Windows build to trigger, which this dev environment can't produce; dialog copy is in DesktopInstallIntegrity.ts and DesktopUpdates.ts.

Checklist

• This PR is small and focused (two related reliability fixes, no feature work; ~half the diff is tests)
• I explained what changed and why
• I included before/after screenshots for any UI changes (native dialogs only; see UI Changes)
• I included a video for animation/interaction changes (n/a)

🤖 Generated with Claude Code

---

Note

High Risk
Changes touch critical Windows update apply, WSL process killing (root), and startup abort paths; incorrect readiness or release checks could block launches or updates, though behavior is heavily tested.

Overview
This PR targets two reliability problems on Windows with WSL—indefinite “connecting” and half-applied updates—and adds a startup guard for corrupted installs.

WSL backend reachability no longer trusts the first hostname -I address. Networking mode comes from wslinfo --networking-mode (with heuristics when unknown), CGNAT 100.64/10 IPs are never advertised, and readiness races loopback plus every distro IP; the winning URL is rebound into currentConfig. After static probes time out, server-runtime.json supplies fallback candidates. Runs that never become ready are terminated and retried, with caps that surface failures via onPreflightFailed instead of hanging forever. getDistroIp is replaced by getDistroIps.

Updates require each backend stop() to return whether the child actually exited within a 10s budget; failed installs abort, restart backends, and leave the update downloadable. On Windows, ensureWindowsPathReleased verifies WSL has released the install directory (released / busy / unknown) before quitAndInstall.

Install integrity compares the packaged app version to desktop-build-manifest.json under app.asar.unpacked (stamped at build time); mismatches or a missing manifest on packaged Windows show a repair dialog and exit before bootstrap. The build script writes the manifest into staged apps/server/dist.

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

Note

Fix update teardown on Windows+WSL with install integrity checks and resilient WSL readiness handshake

• Startup now runs an install-integrity check via DesktopInstallIntegrity before bootstrapping; on Windows, a desktop-build-manifest.json stamped at build time is compared against the app version and, on mismatch, shows an error dialog and quits.
• The update install flow in DesktopUpdates.ts now requires each running backend to confirm a finalized stop within 10 seconds and, on Windows+WSL, calls ensureWindowsPathReleased to verify the install directory is free before invoking quitAndInstall; on failure it restarts backends and surfaces an error.
• WSL readiness probing in DesktopBackendManager.ts now races multiple candidate URLs (loopback + all distro IPs) and optionally consults persisted runtime-state fallback URLs before timing out; stop() now returns a boolean indicating whether the process finalized before the timeout.
• DesktopWslEnvironment.ts replaces the single-IP getDistroIp with getDistroIps (all IPv4s), and adds getNetworkingMode, readServerRuntimeState, and ensureWindowsPathReleased with fixed timeouts and fallback semantics.
• Risk: backends that do not finalize within 10 seconds during an update will block the installer and restart, changing prior best-effort stop behavior.

^{Macroscope summarized 249a6d9.}

[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: e310a9a5-be8d-496e-b0cb-2823e06b141c

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]

Effect service conventions review: one convention violation found — the new readiness fallback path uses Effect.catchTag, which the conventions replace with Effect.catchTags({ ... }) even when recovering a single tag. Everything else (subpath namespace imports, service-member additions on DesktopWslEnvironment with matching layerTest stubs, environment-based dependency acquisition in DesktopUpdates.make, Schema.TaggedErrorClass attributes with an attribute-derived message) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f49d4ea5f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new runtime behavior beyond a simple fix: a startup integrity check that can block app launch, fundamental changes to WSL backend connection logic with multi-candidate probing, new update install abort conditions when backends don't fully stop, and new capabilities to kill Linux processes holding files. The ~2200 additions span multiple subsystems and warrant human review.

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

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

[SunkenInTime]

Current head 249a6d93da1c094c9fe2f94af989a6377dcbe6cb is not merge-ready because the required Check job is red on formatting.

The failing job reports formatting issues in:

• DesktopInstallIntegrity.ts
• DesktopBackendConfiguration.test.ts / .ts
• DesktopBackendManager.test.ts / .ts
• DesktopUpdates.test.ts / .ts

Please run the repository formatter and push the result. I reproduced the functional focused suite on Windows at 126/127 passing; the one failure is the pre-existing Windows slash assertion in the external resource-monitor test, and both desktop and script-scope typechecks pass.

[Jgratton24]

What Changed

Two Windows+WSL reliability fixes that share one user-visible symptom (an indefinite "Connecting to WSL…" splash), plus a guard that turns the corrupted-install crash into an actionable dialog. Desktop-only; no apps/server changes.

1. Update apply is verified before the installer runs (fixes the half-applied-update corruption).

• DesktopBackendInstance.stop() now reports whether the child process actually finalized within the timeout instead of silently swallowing it (DesktopBackendManager.ts).
• The install path (DesktopUpdates.ts) aborts — restarting backends and surfacing the error through the update state machine — if any backend can't be verified stopped, instead of handing off to NSIS while a process still holds files under the install dir.
• For WSL backends, a stopped wsl.exe relay does not mean the Linux-side server (or helpers it spawned, e.g. cloudflared) exited with it. New ensureWindowsPathReleased (DesktopWslEnvironment.ts) terminates and verifies from inside the distro that no Linux process still holds cwd/exe/fd/mmap references under /mnt/c/<install dir> — 9p/DrvFs handles held from WSL block file replacement on the Windows side, which is how app.asar and app.asar.unpacked end up from different builds.
• Post-apply integrity check: the build stamps apps/server/dist/desktop-build-manifest.json (under app.asar.unpacked on Windows); startup compares it against the asar's version and refuses to launch a mixed-build install with a clear repair dialog (DesktopInstallIntegrity.ts) instead of the opaque ERR_MODULE_NOT_FOUND main-process crash. Missing manifest (dev, macOS/Linux, pre-stamp installs) skips the check, so no false positives.

2. WSL endpoint detection and the readiness handshake are no longer single-point-of-failure.

• Networking mode now comes from wslinfo --networking-mode (first-party, present on WSL 2.6.x and 2.7.x) instead of being inferred from the first address in hostname -I — whose ordering shifts whenever Tailscale, Docker bridges, or VPN adapters exist inside the distro. Heuristic fallback for older WSL matches any distro IP against Windows interfaces, never position one, and CGNAT 100.64/10 addresses are never advertised.
• Readiness probes race loopback plus every enumerated distro address; the first candidate that answers wins and becomes the advertised base URL — so a wrong guess degrades startup by nothing worse than a probe race.
• After all static candidates time out, the backend's persisted server-runtime.json origin is consulted as a last-resort candidate (gated on it naming this instance's port).
• The readiness probe is no longer one-shot: a run that spawns but never answers is terminated and retried, and after 3 readiness timeouts the failure surfaces like an exhausted preflight (dialog + Windows fallback on the primary, inline Connections error on the secondary) with every probed URL named. Resolved mode and candidates are logged at startup.

25 new tests across DesktopBackendManager, DesktopUpdates, DesktopWslEnvironment, DesktopBackendConfiguration, and DesktopInstallIntegrity cover the regressions above (CGNAT-first ordering, docker0-first, wslinfo absent, one-shot-probe limbo, unverified stop, WSL busy at install time, mixed-build detection). Full desktop suite: 473 passing.

Why

Two field incidents on 0.0.33-nightly builds, plus these open issues:

• Fixes[Bug]: Desktop stuck on "Connecting to WSL" — getDistroIp picks unreachable Docker bridge IP instead of eth0 #5211 — getDistroIpImpl takes the first IPv4 from hostname -I; Docker bridge IPs sort first and are unreachable from Windows. The same mechanism breaks with a WSL-side tailscaled (CGNAT address first under mirrored networking), which we reproduced on 0.0.33-nightly: the server was listening on 0.0.0.0:3773, reachable via loopback, and logged zero client requests because every probe went to the CGNAT address.
• Fixes[Bug]: Desktop stops probing backend readiness after the 60s budget, leaving "Connecting to WSL…" stuck forever even though the backend becomes healthy #5522 — runBackendProcess forked a single waitForHttpReady with a 60s budget; on timeout onReadinessFailure only logged, leaving the run alive, never ready, never retried, never surfaced.
• Likely fixes[Bug]: "Connecting to WSL" infinite loading #5967 (symptom-level report of the same infinite splash; root cause unconfirmed in that issue).
• Improves [Bug]: Unusable. WSL backend readiness timesout at 60s because the server bundle loads over /mnt/c (takin 80s to boot) and app stuck on "Connecting to WSL…" forever #4535 — a >60s cold boot now gets terminated-and-retried (warm second boot typically fits the budget), and after 3 attempts surfaces an actionable dialog with Windows fallback instead of an infinite splash. The 60s budget itself is unchanged, so this is mitigation, not a full fix.
• Related: Windows: app stays launchable during the multi-minute NSIS update extraction, crashes with ERR_MODULE_NOT_FOUND (false-positive #4154) #5520 — the mid-extraction launch race produces the same ERR_MODULE_NOT_FOUND signature; the integrity check turns the mixed-state launch into a clear "installation is damaged/incomplete" dialog whenever the unpacked stamp has diverged from the asar. It does not (and cannot, from app code) stop NSIS from leaving the exe launchable during extraction.

The half-applied update we debugged: an in-app update left app.asar + the exe at the old build while app.asar.unpacked/node_modules was new → ERR_MODULE_NOT_FOUND on every launch, with the updater having reported nothing. Root cause: install teardown killed the wsl.exe relay and proceeded on a 5s timeout that was silently swallowed, while the Linux-side server exited asynchronously still holding 9p handles into the install dir. Same version installed fine with the app closed.

Sizing note: aware of the contribution guidelines — roughly half of this diff is tests, and the two fixes share the same touched files (DesktopBackendManager/DesktopWslEnvironment), which is why they're one PR. Happy to split into updater-atomicity and handshake PRs if you'd prefer.

This PR deliberately avoids every file touched by #2829 (orchestrator v2) — verified against its full file list, so it merges cleanly before or after.

UI Changes

No renderer UI changes. Two native dialogs are added/extended (update-install-aborted error via the existing update state machine; "installation is damaged" message box with an Open Download Page button). Not screenshotted — they require a packaged Windows build to trigger, which this dev environment can't produce; dialog copy is in DesktopInstallIntegrity.ts and DesktopUpdates.ts.

Checklist

• This PR is small and focused (two related reliability fixes, no feature work; ~half the diff is tests)
• I explained what changed and why
• I included before/after screenshots for any UI changes (native dialogs only; see UI Changes)
• I included a video for animation/interaction changes (n/a)

🤖 Generated with Claude Code

---

Note

High Risk
Changes touch critical Windows update apply, WSL process killing (root), and startup abort paths; incorrect readiness or release checks could block launches or updates, though behavior is heavily tested.

Overview
This PR targets two reliability problems on Windows with WSL—indefinite “connecting” and half-applied updates—and adds a startup guard for corrupted installs.

WSL backend reachability no longer trusts the first hostname -I address. Networking mode comes from wslinfo --networking-mode (with heuristics when unknown), CGNAT 100.64/10 IPs are never advertised, and readiness races loopback plus every distro IP; the winning URL is rebound into currentConfig. After static probes time out, server-runtime.json supplies fallback candidates. Runs that never become ready are terminated and retried, with caps that surface failures via onPreflightFailed instead of hanging forever. getDistroIp is replaced by getDistroIps.

Updates require each backend stop() to return whether the child actually exited within a 10s budget; failed installs abort, restart backends, and leave the update downloadable. On Windows, ensureWindowsPathReleased verifies WSL has released the install directory (released / busy / unknown) before quitAndInstall.

Install integrity compares the packaged app version to desktop-build-manifest.json under app.asar.unpacked (stamped at build time); mismatches or a missing manifest on packaged Windows show a repair dialog and exit before bootstrap. The build script writes the manifest into staged apps/server/dist.

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

Note

Fix update teardown on Windows+WSL with install integrity checks and resilient WSL readiness handshake

• Startup now runs an install-integrity check via DesktopInstallIntegrity before bootstrapping; on Windows, a desktop-build-manifest.json stamped at build time is compared against the app version and, on mismatch, shows an error dialog and quits.
• The update install flow in DesktopUpdates.ts now requires each running backend to confirm a finalized stop within 10 seconds and, on Windows+WSL, calls ensureWindowsPathReleased to verify the install directory is free before invoking quitAndInstall; on failure it restarts backends and surfaces an error.
• WSL readiness probing in DesktopBackendManager.ts now races multiple candidate URLs (loopback + all distro IPs) and optionally consults persisted runtime-state fallback URLs before timing out; stop() now returns a boolean indicating whether the process finalized before the timeout.
• DesktopWslEnvironment.ts replaces the single-IP getDistroIp with getDistroIps (all IPv4s), and adds getNetworkingMode, readServerRuntimeState, and ensureWindowsPathReleased with fixed timeouts and fallback semantics.
• Risk: backends that do not finalize within 10 seconds during an update will block the installer and restart, changing prior best-effort stop behavior.

^{Macroscope summarized 249a6d9.}

[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: e310a9a5-be8d-496e-b0cb-2823e06b141c

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]

Effect service conventions review: one convention violation found — the new readiness fallback path uses Effect.catchTag, which the conventions replace with Effect.catchTags({ ... }) even when recovering a single tag. Everything else (subpath namespace imports, service-member additions on DesktopWslEnvironment with matching layerTest stubs, environment-based dependency acquisition in DesktopUpdates.make, Schema.TaggedErrorClass attributes with an attribute-derived message) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f49d4ea5f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new runtime behavior beyond a simple fix: a startup integrity check that can block app launch, fundamental changes to WSL backend connection logic with multi-candidate probing, new update install abort conditions when backends don't fully stop, and new capabilities to kill Linux processes holding files. The ~2200 additions span multiple subsystems and warrant human review.

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

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

[SunkenInTime]

Current head 249a6d93da1c094c9fe2f94af989a6377dcbe6cb is not merge-ready because the required Check job is red on formatting.

The failing job reports formatting issues in:

• DesktopInstallIntegrity.ts
• DesktopBackendConfiguration.test.ts / .ts
• DesktopBackendManager.test.ts / .ts
• DesktopUpdates.test.ts / .ts

Please run the repository formatter and push the result. I reproduced the functional focused suite on Windows at 126/127 passing; the one failure is the pre-existing Windows slash assertion in the external resource-monitor test, and both desktop and script-scope typechecks pass.

[Jgratton24]

What Changed

Two Windows+WSL reliability fixes that share one user-visible symptom (an indefinite "Connecting to WSL…" splash), plus a guard that turns the corrupted-install crash into an actionable dialog. Desktop-only; no apps/server changes.

1. Update apply is verified before the installer runs (fixes the half-applied-update corruption).

• DesktopBackendInstance.stop() now reports whether the child process actually finalized within the timeout instead of silently swallowing it (DesktopBackendManager.ts).
• The install path (DesktopUpdates.ts) aborts — restarting backends and surfacing the error through the update state machine — if any backend can't be verified stopped, instead of handing off to NSIS while a process still holds files under the install dir.
• For WSL backends, a stopped wsl.exe relay does not mean the Linux-side server (or helpers it spawned, e.g. cloudflared) exited with it. New ensureWindowsPathReleased (DesktopWslEnvironment.ts) terminates and verifies from inside the distro that no Linux process still holds cwd/exe/fd/mmap references under /mnt/c/<install dir> — 9p/DrvFs handles held from WSL block file replacement on the Windows side, which is how app.asar and app.asar.unpacked end up from different builds.
• Post-apply integrity check: the build stamps apps/server/dist/desktop-build-manifest.json (under app.asar.unpacked on Windows); startup compares it against the asar's version and refuses to launch a mixed-build install with a clear repair dialog (DesktopInstallIntegrity.ts) instead of the opaque ERR_MODULE_NOT_FOUND main-process crash. Missing manifest (dev, macOS/Linux, pre-stamp installs) skips the check, so no false positives.

2. WSL endpoint detection and the readiness handshake are no longer single-point-of-failure.

• Networking mode now comes from wslinfo --networking-mode (first-party, present on WSL 2.6.x and 2.7.x) instead of being inferred from the first address in hostname -I — whose ordering shifts whenever Tailscale, Docker bridges, or VPN adapters exist inside the distro. Heuristic fallback for older WSL matches any distro IP against Windows interfaces, never position one, and CGNAT 100.64/10 addresses are never advertised.
• Readiness probes race loopback plus every enumerated distro address; the first candidate that answers wins and becomes the advertised base URL — so a wrong guess degrades startup by nothing worse than a probe race.
• After all static candidates time out, the backend's persisted server-runtime.json origin is consulted as a last-resort candidate (gated on it naming this instance's port).
• The readiness probe is no longer one-shot: a run that spawns but never answers is terminated and retried, and after 3 readiness timeouts the failure surfaces like an exhausted preflight (dialog + Windows fallback on the primary, inline Connections error on the secondary) with every probed URL named. Resolved mode and candidates are logged at startup.

25 new tests across DesktopBackendManager, DesktopUpdates, DesktopWslEnvironment, DesktopBackendConfiguration, and DesktopInstallIntegrity cover the regressions above (CGNAT-first ordering, docker0-first, wslinfo absent, one-shot-probe limbo, unverified stop, WSL busy at install time, mixed-build detection). Full desktop suite: 473 passing.

Why

Two field incidents on 0.0.33-nightly builds, plus these open issues:

• Fixes[Bug]: Desktop stuck on "Connecting to WSL" — getDistroIp picks unreachable Docker bridge IP instead of eth0 #5211 — getDistroIpImpl takes the first IPv4 from hostname -I; Docker bridge IPs sort first and are unreachable from Windows. The same mechanism breaks with a WSL-side tailscaled (CGNAT address first under mirrored networking), which we reproduced on 0.0.33-nightly: the server was listening on 0.0.0.0:3773, reachable via loopback, and logged zero client requests because every probe went to the CGNAT address.
• Fixes[Bug]: Desktop stops probing backend readiness after the 60s budget, leaving "Connecting to WSL…" stuck forever even though the backend becomes healthy #5522 — runBackendProcess forked a single waitForHttpReady with a 60s budget; on timeout onReadinessFailure only logged, leaving the run alive, never ready, never retried, never surfaced.
• Likely fixes[Bug]: "Connecting to WSL" infinite loading #5967 (symptom-level report of the same infinite splash; root cause unconfirmed in that issue).
• Improves [Bug]: Unusable. WSL backend readiness timesout at 60s because the server bundle loads over /mnt/c (takin 80s to boot) and app stuck on "Connecting to WSL…" forever #4535 — a >60s cold boot now gets terminated-and-retried (warm second boot typically fits the budget), and after 3 attempts surfaces an actionable dialog with Windows fallback instead of an infinite splash. The 60s budget itself is unchanged, so this is mitigation, not a full fix.
• Related: Windows: app stays launchable during the multi-minute NSIS update extraction, crashes with ERR_MODULE_NOT_FOUND (false-positive #4154) #5520 — the mid-extraction launch race produces the same ERR_MODULE_NOT_FOUND signature; the integrity check turns the mixed-state launch into a clear "installation is damaged/incomplete" dialog whenever the unpacked stamp has diverged from the asar. It does not (and cannot, from app code) stop NSIS from leaving the exe launchable during extraction.

The half-applied update we debugged: an in-app update left app.asar + the exe at the old build while app.asar.unpacked/node_modules was new → ERR_MODULE_NOT_FOUND on every launch, with the updater having reported nothing. Root cause: install teardown killed the wsl.exe relay and proceeded on a 5s timeout that was silently swallowed, while the Linux-side server exited asynchronously still holding 9p handles into the install dir. Same version installed fine with the app closed.

Sizing note: aware of the contribution guidelines — roughly half of this diff is tests, and the two fixes share the same touched files (DesktopBackendManager/DesktopWslEnvironment), which is why they're one PR. Happy to split into updater-atomicity and handshake PRs if you'd prefer.

This PR deliberately avoids every file touched by #2829 (orchestrator v2) — verified against its full file list, so it merges cleanly before or after.

UI Changes

No renderer UI changes. Two native dialogs are added/extended (update-install-aborted error via the existing update state machine; "installation is damaged" message box with an Open Download Page button). Not screenshotted — they require a packaged Windows build to trigger, which this dev environment can't produce; dialog copy is in DesktopInstallIntegrity.ts and DesktopUpdates.ts.

Checklist

• This PR is small and focused (two related reliability fixes, no feature work; ~half the diff is tests)
• I explained what changed and why
• I included before/after screenshots for any UI changes (native dialogs only; see UI Changes)
• I included a video for animation/interaction changes (n/a)

🤖 Generated with Claude Code

---

Note

High Risk
Changes touch critical Windows update apply, WSL process killing (root), and startup abort paths; incorrect readiness or release checks could block launches or updates, though behavior is heavily tested.

Overview
This PR targets two reliability problems on Windows with WSL—indefinite “connecting” and half-applied updates—and adds a startup guard for corrupted installs.

WSL backend reachability no longer trusts the first hostname -I address. Networking mode comes from wslinfo --networking-mode (with heuristics when unknown), CGNAT 100.64/10 IPs are never advertised, and readiness races loopback plus every distro IP; the winning URL is rebound into currentConfig. After static probes time out, server-runtime.json supplies fallback candidates. Runs that never become ready are terminated and retried, with caps that surface failures via onPreflightFailed instead of hanging forever. getDistroIp is replaced by getDistroIps.

Updates require each backend stop() to return whether the child actually exited within a 10s budget; failed installs abort, restart backends, and leave the update downloadable. On Windows, ensureWindowsPathReleased verifies WSL has released the install directory (released / busy / unknown) before quitAndInstall.

Install integrity compares the packaged app version to desktop-build-manifest.json under app.asar.unpacked (stamped at build time); mismatches or a missing manifest on packaged Windows show a repair dialog and exit before bootstrap. The build script writes the manifest into staged apps/server/dist.

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

Note

Fix update teardown on Windows+WSL with install integrity checks and resilient WSL readiness handshake

• Startup now runs an install-integrity check via DesktopInstallIntegrity before bootstrapping; on Windows, a desktop-build-manifest.json stamped at build time is compared against the app version and, on mismatch, shows an error dialog and quits.
• The update install flow in DesktopUpdates.ts now requires each running backend to confirm a finalized stop within 10 seconds and, on Windows+WSL, calls ensureWindowsPathReleased to verify the install directory is free before invoking quitAndInstall; on failure it restarts backends and surfaces an error.
• WSL readiness probing in DesktopBackendManager.ts now races multiple candidate URLs (loopback + all distro IPs) and optionally consults persisted runtime-state fallback URLs before timing out; stop() now returns a boolean indicating whether the process finalized before the timeout.
• DesktopWslEnvironment.ts replaces the single-IP getDistroIp with getDistroIps (all IPv4s), and adds getNetworkingMode, readServerRuntimeState, and ensureWindowsPathReleased with fixed timeouts and fallback semantics.
• Risk: backends that do not finalize within 10 seconds during an update will block the installer and restart, changing prior best-effort stop behavior.

^{Macroscope summarized 249a6d9.}

[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: e310a9a5-be8d-496e-b0cb-2823e06b141c

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]

Effect service conventions review: one convention violation found — the new readiness fallback path uses Effect.catchTag, which the conventions replace with Effect.catchTags({ ... }) even when recovering a single tag. Everything else (subpath namespace imports, service-member additions on DesktopWslEnvironment with matching layerTest stubs, environment-based dependency acquisition in DesktopUpdates.make, Schema.TaggedErrorClass attributes with an attribute-derived message) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f49d4ea5f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new runtime behavior beyond a simple fix: a startup integrity check that can block app launch, fundamental changes to WSL backend connection logic with multi-candidate probing, new update install abort conditions when backends don't fully stop, and new capabilities to kill Linux processes holding files. The ~2200 additions span multiple subsystems and warrant human review.

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

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

[SunkenInTime]

Current head 249a6d93da1c094c9fe2f94af989a6377dcbe6cb is not merge-ready because the required Check job is red on formatting.

The failing job reports formatting issues in:

• DesktopInstallIntegrity.ts
• DesktopBackendConfiguration.test.ts / .ts
• DesktopBackendManager.test.ts / .ts
• DesktopUpdates.test.ts / .ts

Please run the repository formatter and push the result. I reproduced the functional focused suite on Windows at 126/127 passing; the one failure is the pre-existing Windows slash assertion in the external resource-monitor test, and both desktop and script-scope typechecks pass.

[Jgratton24]

What Changed

Two Windows+WSL reliability fixes that share one user-visible symptom (an indefinite "Connecting to WSL…" splash), plus a guard that turns the corrupted-install crash into an actionable dialog. Desktop-only; no apps/server changes.

1. Update apply is verified before the installer runs (fixes the half-applied-update corruption).

• DesktopBackendInstance.stop() now reports whether the child process actually finalized within the timeout instead of silently swallowing it (DesktopBackendManager.ts).
• The install path (DesktopUpdates.ts) aborts — restarting backends and surfacing the error through the update state machine — if any backend can't be verified stopped, instead of handing off to NSIS while a process still holds files under the install dir.
• For WSL backends, a stopped wsl.exe relay does not mean the Linux-side server (or helpers it spawned, e.g. cloudflared) exited with it. New ensureWindowsPathReleased (DesktopWslEnvironment.ts) terminates and verifies from inside the distro that no Linux process still holds cwd/exe/fd/mmap references under /mnt/c/<install dir> — 9p/DrvFs handles held from WSL block file replacement on the Windows side, which is how app.asar and app.asar.unpacked end up from different builds.
• Post-apply integrity check: the build stamps apps/server/dist/desktop-build-manifest.json (under app.asar.unpacked on Windows); startup compares it against the asar's version and refuses to launch a mixed-build install with a clear repair dialog (DesktopInstallIntegrity.ts) instead of the opaque ERR_MODULE_NOT_FOUND main-process crash. Missing manifest (dev, macOS/Linux, pre-stamp installs) skips the check, so no false positives.

2. WSL endpoint detection and the readiness handshake are no longer single-point-of-failure.

• Networking mode now comes from wslinfo --networking-mode (first-party, present on WSL 2.6.x and 2.7.x) instead of being inferred from the first address in hostname -I — whose ordering shifts whenever Tailscale, Docker bridges, or VPN adapters exist inside the distro. Heuristic fallback for older WSL matches any distro IP against Windows interfaces, never position one, and CGNAT 100.64/10 addresses are never advertised.
• Readiness probes race loopback plus every enumerated distro address; the first candidate that answers wins and becomes the advertised base URL — so a wrong guess degrades startup by nothing worse than a probe race.
• After all static candidates time out, the backend's persisted server-runtime.json origin is consulted as a last-resort candidate (gated on it naming this instance's port).
• The readiness probe is no longer one-shot: a run that spawns but never answers is terminated and retried, and after 3 readiness timeouts the failure surfaces like an exhausted preflight (dialog + Windows fallback on the primary, inline Connections error on the secondary) with every probed URL named. Resolved mode and candidates are logged at startup.

25 new tests across DesktopBackendManager, DesktopUpdates, DesktopWslEnvironment, DesktopBackendConfiguration, and DesktopInstallIntegrity cover the regressions above (CGNAT-first ordering, docker0-first, wslinfo absent, one-shot-probe limbo, unverified stop, WSL busy at install time, mixed-build detection). Full desktop suite: 473 passing.

Why

Two field incidents on 0.0.33-nightly builds, plus these open issues:

• Fixes[Bug]: Desktop stuck on "Connecting to WSL" — getDistroIp picks unreachable Docker bridge IP instead of eth0 #5211 — getDistroIpImpl takes the first IPv4 from hostname -I; Docker bridge IPs sort first and are unreachable from Windows. The same mechanism breaks with a WSL-side tailscaled (CGNAT address first under mirrored networking), which we reproduced on 0.0.33-nightly: the server was listening on 0.0.0.0:3773, reachable via loopback, and logged zero client requests because every probe went to the CGNAT address.
• Fixes[Bug]: Desktop stops probing backend readiness after the 60s budget, leaving "Connecting to WSL…" stuck forever even though the backend becomes healthy #5522 — runBackendProcess forked a single waitForHttpReady with a 60s budget; on timeout onReadinessFailure only logged, leaving the run alive, never ready, never retried, never surfaced.
• Likely fixes[Bug]: "Connecting to WSL" infinite loading #5967 (symptom-level report of the same infinite splash; root cause unconfirmed in that issue).
• Improves [Bug]: Unusable. WSL backend readiness timesout at 60s because the server bundle loads over /mnt/c (takin 80s to boot) and app stuck on "Connecting to WSL…" forever #4535 — a >60s cold boot now gets terminated-and-retried (warm second boot typically fits the budget), and after 3 attempts surfaces an actionable dialog with Windows fallback instead of an infinite splash. The 60s budget itself is unchanged, so this is mitigation, not a full fix.
• Related: Windows: app stays launchable during the multi-minute NSIS update extraction, crashes with ERR_MODULE_NOT_FOUND (false-positive #4154) #5520 — the mid-extraction launch race produces the same ERR_MODULE_NOT_FOUND signature; the integrity check turns the mixed-state launch into a clear "installation is damaged/incomplete" dialog whenever the unpacked stamp has diverged from the asar. It does not (and cannot, from app code) stop NSIS from leaving the exe launchable during extraction.

The half-applied update we debugged: an in-app update left app.asar + the exe at the old build while app.asar.unpacked/node_modules was new → ERR_MODULE_NOT_FOUND on every launch, with the updater having reported nothing. Root cause: install teardown killed the wsl.exe relay and proceeded on a 5s timeout that was silently swallowed, while the Linux-side server exited asynchronously still holding 9p handles into the install dir. Same version installed fine with the app closed.

Sizing note: aware of the contribution guidelines — roughly half of this diff is tests, and the two fixes share the same touched files (DesktopBackendManager/DesktopWslEnvironment), which is why they're one PR. Happy to split into updater-atomicity and handshake PRs if you'd prefer.

This PR deliberately avoids every file touched by #2829 (orchestrator v2) — verified against its full file list, so it merges cleanly before or after.

UI Changes

No renderer UI changes. Two native dialogs are added/extended (update-install-aborted error via the existing update state machine; "installation is damaged" message box with an Open Download Page button). Not screenshotted — they require a packaged Windows build to trigger, which this dev environment can't produce; dialog copy is in DesktopInstallIntegrity.ts and DesktopUpdates.ts.

Checklist

• This PR is small and focused (two related reliability fixes, no feature work; ~half the diff is tests)
• I explained what changed and why
• I included before/after screenshots for any UI changes (native dialogs only; see UI Changes)
• I included a video for animation/interaction changes (n/a)

🤖 Generated with Claude Code

---

Note

High Risk
Changes touch critical Windows update apply, WSL process killing (root), and startup abort paths; incorrect readiness or release checks could block launches or updates, though behavior is heavily tested.

Overview
This PR targets two reliability problems on Windows with WSL—indefinite “connecting” and half-applied updates—and adds a startup guard for corrupted installs.

WSL backend reachability no longer trusts the first hostname -I address. Networking mode comes from wslinfo --networking-mode (with heuristics when unknown), CGNAT 100.64/10 IPs are never advertised, and readiness races loopback plus every distro IP; the winning URL is rebound into currentConfig. After static probes time out, server-runtime.json supplies fallback candidates. Runs that never become ready are terminated and retried, with caps that surface failures via onPreflightFailed instead of hanging forever. getDistroIp is replaced by getDistroIps.

Updates require each backend stop() to return whether the child actually exited within a 10s budget; failed installs abort, restart backends, and leave the update downloadable. On Windows, ensureWindowsPathReleased verifies WSL has released the install directory (released / busy / unknown) before quitAndInstall.

Install integrity compares the packaged app version to desktop-build-manifest.json under app.asar.unpacked (stamped at build time); mismatches or a missing manifest on packaged Windows show a repair dialog and exit before bootstrap. The build script writes the manifest into staged apps/server/dist.

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

Note

Fix update teardown on Windows+WSL with install integrity checks and resilient WSL readiness handshake

• Startup now runs an install-integrity check via DesktopInstallIntegrity before bootstrapping; on Windows, a desktop-build-manifest.json stamped at build time is compared against the app version and, on mismatch, shows an error dialog and quits.
• The update install flow in DesktopUpdates.ts now requires each running backend to confirm a finalized stop within 10 seconds and, on Windows+WSL, calls ensureWindowsPathReleased to verify the install directory is free before invoking quitAndInstall; on failure it restarts backends and surfaces an error.
• WSL readiness probing in DesktopBackendManager.ts now races multiple candidate URLs (loopback + all distro IPs) and optionally consults persisted runtime-state fallback URLs before timing out; stop() now returns a boolean indicating whether the process finalized before the timeout.
• DesktopWslEnvironment.ts replaces the single-IP getDistroIp with getDistroIps (all IPv4s), and adds getNetworkingMode, readServerRuntimeState, and ensureWindowsPathReleased with fixed timeouts and fallback semantics.
• Risk: backends that do not finalize within 10 seconds during an update will block the installer and restart, changing prior best-effort stop behavior.

^{Macroscope summarized 249a6d9.}

[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: e310a9a5-be8d-496e-b0cb-2823e06b141c

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]

Effect service conventions review: one convention violation found — the new readiness fallback path uses Effect.catchTag, which the conventions replace with Effect.catchTags({ ... }) even when recovering a single tag. Everything else (subpath namespace imports, service-member additions on DesktopWslEnvironment with matching layerTest stubs, environment-based dependency acquisition in DesktopUpdates.make, Schema.TaggedErrorClass attributes with an attribute-derived message) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f49d4ea5f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new runtime behavior beyond a simple fix: a startup integrity check that can block app launch, fundamental changes to WSL backend connection logic with multi-candidate probing, new update install abort conditions when backends don't fully stop, and new capabilities to kill Linux processes holding files. The ~2200 additions span multiple subsystems and warrant human review.

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

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

[SunkenInTime]

Current head 249a6d93da1c094c9fe2f94af989a6377dcbe6cb is not merge-ready because the required Check job is red on formatting.

The failing job reports formatting issues in:

• DesktopInstallIntegrity.ts
• DesktopBackendConfiguration.test.ts / .ts
• DesktopBackendManager.test.ts / .ts
• DesktopUpdates.test.ts / .ts

Please run the repository formatter and push the result. I reproduced the functional focused suite on Windows at 126/127 passing; the one failure is the pre-existing Windows slash assertion in the external resource-monitor test, and both desktop and script-scope typechecks pass.

[Jgratton24]

What Changed

Two Windows+WSL reliability fixes that share one user-visible symptom (an indefinite "Connecting to WSL…" splash), plus a guard that turns the corrupted-install crash into an actionable dialog. Desktop-only; no apps/server changes.

1. Update apply is verified before the installer runs (fixes the half-applied-update corruption).

• DesktopBackendInstance.stop() now reports whether the child process actually finalized within the timeout instead of silently swallowing it (DesktopBackendManager.ts).
• The install path (DesktopUpdates.ts) aborts — restarting backends and surfacing the error through the update state machine — if any backend can't be verified stopped, instead of handing off to NSIS while a process still holds files under the install dir.
• For WSL backends, a stopped wsl.exe relay does not mean the Linux-side server (or helpers it spawned, e.g. cloudflared) exited with it. New ensureWindowsPathReleased (DesktopWslEnvironment.ts) terminates and verifies from inside the distro that no Linux process still holds cwd/exe/fd/mmap references under /mnt/c/<install dir> — 9p/DrvFs handles held from WSL block file replacement on the Windows side, which is how app.asar and app.asar.unpacked end up from different builds.
• Post-apply integrity check: the build stamps apps/server/dist/desktop-build-manifest.json (under app.asar.unpacked on Windows); startup compares it against the asar's version and refuses to launch a mixed-build install with a clear repair dialog (DesktopInstallIntegrity.ts) instead of the opaque ERR_MODULE_NOT_FOUND main-process crash. Missing manifest (dev, macOS/Linux, pre-stamp installs) skips the check, so no false positives.

2. WSL endpoint detection and the readiness handshake are no longer single-point-of-failure.

• Networking mode now comes from wslinfo --networking-mode (first-party, present on WSL 2.6.x and 2.7.x) instead of being inferred from the first address in hostname -I — whose ordering shifts whenever Tailscale, Docker bridges, or VPN adapters exist inside the distro. Heuristic fallback for older WSL matches any distro IP against Windows interfaces, never position one, and CGNAT 100.64/10 addresses are never advertised.
• Readiness probes race loopback plus every enumerated distro address; the first candidate that answers wins and becomes the advertised base URL — so a wrong guess degrades startup by nothing worse than a probe race.
• After all static candidates time out, the backend's persisted server-runtime.json origin is consulted as a last-resort candidate (gated on it naming this instance's port).
• The readiness probe is no longer one-shot: a run that spawns but never answers is terminated and retried, and after 3 readiness timeouts the failure surfaces like an exhausted preflight (dialog + Windows fallback on the primary, inline Connections error on the secondary) with every probed URL named. Resolved mode and candidates are logged at startup.

25 new tests across DesktopBackendManager, DesktopUpdates, DesktopWslEnvironment, DesktopBackendConfiguration, and DesktopInstallIntegrity cover the regressions above (CGNAT-first ordering, docker0-first, wslinfo absent, one-shot-probe limbo, unverified stop, WSL busy at install time, mixed-build detection). Full desktop suite: 473 passing.

Why

Two field incidents on 0.0.33-nightly builds, plus these open issues:

• Fixes[Bug]: Desktop stuck on "Connecting to WSL" — getDistroIp picks unreachable Docker bridge IP instead of eth0 #5211 — getDistroIpImpl takes the first IPv4 from hostname -I; Docker bridge IPs sort first and are unreachable from Windows. The same mechanism breaks with a WSL-side tailscaled (CGNAT address first under mirrored networking), which we reproduced on 0.0.33-nightly: the server was listening on 0.0.0.0:3773, reachable via loopback, and logged zero client requests because every probe went to the CGNAT address.
• Fixes[Bug]: Desktop stops probing backend readiness after the 60s budget, leaving "Connecting to WSL…" stuck forever even though the backend becomes healthy #5522 — runBackendProcess forked a single waitForHttpReady with a 60s budget; on timeout onReadinessFailure only logged, leaving the run alive, never ready, never retried, never surfaced.
• Likely fixes[Bug]: "Connecting to WSL" infinite loading #5967 (symptom-level report of the same infinite splash; root cause unconfirmed in that issue).
• Improves [Bug]: Unusable. WSL backend readiness timesout at 60s because the server bundle loads over /mnt/c (takin 80s to boot) and app stuck on "Connecting to WSL…" forever #4535 — a >60s cold boot now gets terminated-and-retried (warm second boot typically fits the budget), and after 3 attempts surfaces an actionable dialog with Windows fallback instead of an infinite splash. The 60s budget itself is unchanged, so this is mitigation, not a full fix.
• Related: Windows: app stays launchable during the multi-minute NSIS update extraction, crashes with ERR_MODULE_NOT_FOUND (false-positive #4154) #5520 — the mid-extraction launch race produces the same ERR_MODULE_NOT_FOUND signature; the integrity check turns the mixed-state launch into a clear "installation is damaged/incomplete" dialog whenever the unpacked stamp has diverged from the asar. It does not (and cannot, from app code) stop NSIS from leaving the exe launchable during extraction.

The half-applied update we debugged: an in-app update left app.asar + the exe at the old build while app.asar.unpacked/node_modules was new → ERR_MODULE_NOT_FOUND on every launch, with the updater having reported nothing. Root cause: install teardown killed the wsl.exe relay and proceeded on a 5s timeout that was silently swallowed, while the Linux-side server exited asynchronously still holding 9p handles into the install dir. Same version installed fine with the app closed.

Sizing note: aware of the contribution guidelines — roughly half of this diff is tests, and the two fixes share the same touched files (DesktopBackendManager/DesktopWslEnvironment), which is why they're one PR. Happy to split into updater-atomicity and handshake PRs if you'd prefer.

This PR deliberately avoids every file touched by #2829 (orchestrator v2) — verified against its full file list, so it merges cleanly before or after.

UI Changes

No renderer UI changes. Two native dialogs are added/extended (update-install-aborted error via the existing update state machine; "installation is damaged" message box with an Open Download Page button). Not screenshotted — they require a packaged Windows build to trigger, which this dev environment can't produce; dialog copy is in DesktopInstallIntegrity.ts and DesktopUpdates.ts.

Checklist

• This PR is small and focused (two related reliability fixes, no feature work; ~half the diff is tests)
• I explained what changed and why
• I included before/after screenshots for any UI changes (native dialogs only; see UI Changes)
• I included a video for animation/interaction changes (n/a)

🤖 Generated with Claude Code

---

Note

High Risk
Changes touch critical Windows update apply, WSL process killing (root), and startup abort paths; incorrect readiness or release checks could block launches or updates, though behavior is heavily tested.

Overview
This PR targets two reliability problems on Windows with WSL—indefinite “connecting” and half-applied updates—and adds a startup guard for corrupted installs.

WSL backend reachability no longer trusts the first hostname -I address. Networking mode comes from wslinfo --networking-mode (with heuristics when unknown), CGNAT 100.64/10 IPs are never advertised, and readiness races loopback plus every distro IP; the winning URL is rebound into currentConfig. After static probes time out, server-runtime.json supplies fallback candidates. Runs that never become ready are terminated and retried, with caps that surface failures via onPreflightFailed instead of hanging forever. getDistroIp is replaced by getDistroIps.

Updates require each backend stop() to return whether the child actually exited within a 10s budget; failed installs abort, restart backends, and leave the update downloadable. On Windows, ensureWindowsPathReleased verifies WSL has released the install directory (released / busy / unknown) before quitAndInstall.

Install integrity compares the packaged app version to desktop-build-manifest.json under app.asar.unpacked (stamped at build time); mismatches or a missing manifest on packaged Windows show a repair dialog and exit before bootstrap. The build script writes the manifest into staged apps/server/dist.

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

Note

Fix update teardown on Windows+WSL with install integrity checks and resilient WSL readiness handshake

• Startup now runs an install-integrity check via DesktopInstallIntegrity before bootstrapping; on Windows, a desktop-build-manifest.json stamped at build time is compared against the app version and, on mismatch, shows an error dialog and quits.
• The update install flow in DesktopUpdates.ts now requires each running backend to confirm a finalized stop within 10 seconds and, on Windows+WSL, calls ensureWindowsPathReleased to verify the install directory is free before invoking quitAndInstall; on failure it restarts backends and surfaces an error.
• WSL readiness probing in DesktopBackendManager.ts now races multiple candidate URLs (loopback + all distro IPs) and optionally consults persisted runtime-state fallback URLs before timing out; stop() now returns a boolean indicating whether the process finalized before the timeout.
• DesktopWslEnvironment.ts replaces the single-IP getDistroIp with getDistroIps (all IPv4s), and adds getNetworkingMode, readServerRuntimeState, and ensureWindowsPathReleased with fixed timeouts and fallback semantics.
• Risk: backends that do not finalize within 10 seconds during an update will block the installer and restart, changing prior best-effort stop behavior.

^{Macroscope summarized 249a6d9.}

[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: e310a9a5-be8d-496e-b0cb-2823e06b141c

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]

Effect service conventions review: one convention violation found — the new readiness fallback path uses Effect.catchTag, which the conventions replace with Effect.catchTags({ ... }) even when recovering a single tag. Everything else (subpath namespace imports, service-member additions on DesktopWslEnvironment with matching layerTest stubs, environment-based dependency acquisition in DesktopUpdates.make, Schema.TaggedErrorClass attributes with an attribute-derived message) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f49d4ea5f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new runtime behavior beyond a simple fix: a startup integrity check that can block app launch, fundamental changes to WSL backend connection logic with multi-candidate probing, new update install abort conditions when backends don't fully stop, and new capabilities to kill Linux processes holding files. The ~2200 additions span multiple subsystems and warrant human review.

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

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

[SunkenInTime]

Current head 249a6d93da1c094c9fe2f94af989a6377dcbe6cb is not merge-ready because the required Check job is red on formatting.

The failing job reports formatting issues in:

• DesktopInstallIntegrity.ts
• DesktopBackendConfiguration.test.ts / .ts
• DesktopBackendManager.test.ts / .ts
• DesktopUpdates.test.ts / .ts

Please run the repository formatter and push the result. I reproduced the functional focused suite on Windows at 126/127 passing; the one failure is the pre-existing Windows slash assertion in the external resource-monitor test, and both desktop and script-scope typechecks pass.

[Jgratton24]

What Changed

Two Windows+WSL reliability fixes that share one user-visible symptom (an indefinite "Connecting to WSL…" splash), plus a guard that turns the corrupted-install crash into an actionable dialog. Desktop-only; no apps/server changes.

1. Update apply is verified before the installer runs (fixes the half-applied-update corruption).

• DesktopBackendInstance.stop() now reports whether the child process actually finalized within the timeout instead of silently swallowing it (DesktopBackendManager.ts).
• The install path (DesktopUpdates.ts) aborts — restarting backends and surfacing the error through the update state machine — if any backend can't be verified stopped, instead of handing off to NSIS while a process still holds files under the install dir.
• For WSL backends, a stopped wsl.exe relay does not mean the Linux-side server (or helpers it spawned, e.g. cloudflared) exited with it. New ensureWindowsPathReleased (DesktopWslEnvironment.ts) terminates and verifies from inside the distro that no Linux process still holds cwd/exe/fd/mmap references under /mnt/c/<install dir> — 9p/DrvFs handles held from WSL block file replacement on the Windows side, which is how app.asar and app.asar.unpacked end up from different builds.
• Post-apply integrity check: the build stamps apps/server/dist/desktop-build-manifest.json (under app.asar.unpacked on Windows); startup compares it against the asar's version and refuses to launch a mixed-build install with a clear repair dialog (DesktopInstallIntegrity.ts) instead of the opaque ERR_MODULE_NOT_FOUND main-process crash. Missing manifest (dev, macOS/Linux, pre-stamp installs) skips the check, so no false positives.

2. WSL endpoint detection and the readiness handshake are no longer single-point-of-failure.

• Networking mode now comes from wslinfo --networking-mode (first-party, present on WSL 2.6.x and 2.7.x) instead of being inferred from the first address in hostname -I — whose ordering shifts whenever Tailscale, Docker bridges, or VPN adapters exist inside the distro. Heuristic fallback for older WSL matches any distro IP against Windows interfaces, never position one, and CGNAT 100.64/10 addresses are never advertised.
• Readiness probes race loopback plus every enumerated distro address; the first candidate that answers wins and becomes the advertised base URL — so a wrong guess degrades startup by nothing worse than a probe race.
• After all static candidates time out, the backend's persisted server-runtime.json origin is consulted as a last-resort candidate (gated on it naming this instance's port).
• The readiness probe is no longer one-shot: a run that spawns but never answers is terminated and retried, and after 3 readiness timeouts the failure surfaces like an exhausted preflight (dialog + Windows fallback on the primary, inline Connections error on the secondary) with every probed URL named. Resolved mode and candidates are logged at startup.

25 new tests across DesktopBackendManager, DesktopUpdates, DesktopWslEnvironment, DesktopBackendConfiguration, and DesktopInstallIntegrity cover the regressions above (CGNAT-first ordering, docker0-first, wslinfo absent, one-shot-probe limbo, unverified stop, WSL busy at install time, mixed-build detection). Full desktop suite: 473 passing.

Why

Two field incidents on 0.0.33-nightly builds, plus these open issues:

• Fixes[Bug]: Desktop stuck on "Connecting to WSL" — getDistroIp picks unreachable Docker bridge IP instead of eth0 #5211 — getDistroIpImpl takes the first IPv4 from hostname -I; Docker bridge IPs sort first and are unreachable from Windows. The same mechanism breaks with a WSL-side tailscaled (CGNAT address first under mirrored networking), which we reproduced on 0.0.33-nightly: the server was listening on 0.0.0.0:3773, reachable via loopback, and logged zero client requests because every probe went to the CGNAT address.
• Fixes[Bug]: Desktop stops probing backend readiness after the 60s budget, leaving "Connecting to WSL…" stuck forever even though the backend becomes healthy #5522 — runBackendProcess forked a single waitForHttpReady with a 60s budget; on timeout onReadinessFailure only logged, leaving the run alive, never ready, never retried, never surfaced.
• Likely fixes[Bug]: "Connecting to WSL" infinite loading #5967 (symptom-level report of the same infinite splash; root cause unconfirmed in that issue).
• Improves [Bug]: Unusable. WSL backend readiness timesout at 60s because the server bundle loads over /mnt/c (takin 80s to boot) and app stuck on "Connecting to WSL…" forever #4535 — a >60s cold boot now gets terminated-and-retried (warm second boot typically fits the budget), and after 3 attempts surfaces an actionable dialog with Windows fallback instead of an infinite splash. The 60s budget itself is unchanged, so this is mitigation, not a full fix.
• Related: Windows: app stays launchable during the multi-minute NSIS update extraction, crashes with ERR_MODULE_NOT_FOUND (false-positive #4154) #5520 — the mid-extraction launch race produces the same ERR_MODULE_NOT_FOUND signature; the integrity check turns the mixed-state launch into a clear "installation is damaged/incomplete" dialog whenever the unpacked stamp has diverged from the asar. It does not (and cannot, from app code) stop NSIS from leaving the exe launchable during extraction.

The half-applied update we debugged: an in-app update left app.asar + the exe at the old build while app.asar.unpacked/node_modules was new → ERR_MODULE_NOT_FOUND on every launch, with the updater having reported nothing. Root cause: install teardown killed the wsl.exe relay and proceeded on a 5s timeout that was silently swallowed, while the Linux-side server exited asynchronously still holding 9p handles into the install dir. Same version installed fine with the app closed.

Sizing note: aware of the contribution guidelines — roughly half of this diff is tests, and the two fixes share the same touched files (DesktopBackendManager/DesktopWslEnvironment), which is why they're one PR. Happy to split into updater-atomicity and handshake PRs if you'd prefer.

This PR deliberately avoids every file touched by #2829 (orchestrator v2) — verified against its full file list, so it merges cleanly before or after.

UI Changes

No renderer UI changes. Two native dialogs are added/extended (update-install-aborted error via the existing update state machine; "installation is damaged" message box with an Open Download Page button). Not screenshotted — they require a packaged Windows build to trigger, which this dev environment can't produce; dialog copy is in DesktopInstallIntegrity.ts and DesktopUpdates.ts.

Checklist

• This PR is small and focused (two related reliability fixes, no feature work; ~half the diff is tests)
• I explained what changed and why
• I included before/after screenshots for any UI changes (native dialogs only; see UI Changes)
• I included a video for animation/interaction changes (n/a)

🤖 Generated with Claude Code

---

Note

High Risk
Changes touch critical Windows update apply, WSL process killing (root), and startup abort paths; incorrect readiness or release checks could block launches or updates, though behavior is heavily tested.

Overview
This PR targets two reliability problems on Windows with WSL—indefinite “connecting” and half-applied updates—and adds a startup guard for corrupted installs.

WSL backend reachability no longer trusts the first hostname -I address. Networking mode comes from wslinfo --networking-mode (with heuristics when unknown), CGNAT 100.64/10 IPs are never advertised, and readiness races loopback plus every distro IP; the winning URL is rebound into currentConfig. After static probes time out, server-runtime.json supplies fallback candidates. Runs that never become ready are terminated and retried, with caps that surface failures via onPreflightFailed instead of hanging forever. getDistroIp is replaced by getDistroIps.

Updates require each backend stop() to return whether the child actually exited within a 10s budget; failed installs abort, restart backends, and leave the update downloadable. On Windows, ensureWindowsPathReleased verifies WSL has released the install directory (released / busy / unknown) before quitAndInstall.

Install integrity compares the packaged app version to desktop-build-manifest.json under app.asar.unpacked (stamped at build time); mismatches or a missing manifest on packaged Windows show a repair dialog and exit before bootstrap. The build script writes the manifest into staged apps/server/dist.

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

Note

Fix update teardown on Windows+WSL with install integrity checks and resilient WSL readiness handshake

• Startup now runs an install-integrity check via DesktopInstallIntegrity before bootstrapping; on Windows, a desktop-build-manifest.json stamped at build time is compared against the app version and, on mismatch, shows an error dialog and quits.
• The update install flow in DesktopUpdates.ts now requires each running backend to confirm a finalized stop within 10 seconds and, on Windows+WSL, calls ensureWindowsPathReleased to verify the install directory is free before invoking quitAndInstall; on failure it restarts backends and surfaces an error.
• WSL readiness probing in DesktopBackendManager.ts now races multiple candidate URLs (loopback + all distro IPs) and optionally consults persisted runtime-state fallback URLs before timing out; stop() now returns a boolean indicating whether the process finalized before the timeout.
• DesktopWslEnvironment.ts replaces the single-IP getDistroIp with getDistroIps (all IPv4s), and adds getNetworkingMode, readServerRuntimeState, and ensureWindowsPathReleased with fixed timeouts and fallback semantics.
• Risk: backends that do not finalize within 10 seconds during an update will block the installer and restart, changing prior best-effort stop behavior.

^{Macroscope summarized 249a6d9.}

[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: e310a9a5-be8d-496e-b0cb-2823e06b141c

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]

Effect service conventions review: one convention violation found — the new readiness fallback path uses Effect.catchTag, which the conventions replace with Effect.catchTags({ ... }) even when recovering a single tag. Everything else (subpath namespace imports, service-member additions on DesktopWslEnvironment with matching layerTest stubs, environment-based dependency acquisition in DesktopUpdates.make, Schema.TaggedErrorClass attributes with an attribute-derived message) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f49d4ea5f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new runtime behavior beyond a simple fix: a startup integrity check that can block app launch, fundamental changes to WSL backend connection logic with multi-candidate probing, new update install abort conditions when backends don't fully stop, and new capabilities to kill Linux processes holding files. The ~2200 additions span multiple subsystems and warrant human review.

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

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

[SunkenInTime]

Current head 249a6d93da1c094c9fe2f94af989a6377dcbe6cb is not merge-ready because the required Check job is red on formatting.

The failing job reports formatting issues in:

• DesktopInstallIntegrity.ts
• DesktopBackendConfiguration.test.ts / .ts
• DesktopBackendManager.test.ts / .ts
• DesktopUpdates.test.ts / .ts

Please run the repository formatter and push the result. I reproduced the functional focused suite on Windows at 126/127 passing; the one failure is the pre-existing Windows slash assertion in the external resource-monitor test, and both desktop and script-scope typechecks pass.

[Jgratton24]

What Changed

Two Windows+WSL reliability fixes that share one user-visible symptom (an indefinite "Connecting to WSL…" splash), plus a guard that turns the corrupted-install crash into an actionable dialog. Desktop-only; no apps/server changes.

1. Update apply is verified before the installer runs (fixes the half-applied-update corruption).

• DesktopBackendInstance.stop() now reports whether the child process actually finalized within the timeout instead of silently swallowing it (DesktopBackendManager.ts).
• The install path (DesktopUpdates.ts) aborts — restarting backends and surfacing the error through the update state machine — if any backend can't be verified stopped, instead of handing off to NSIS while a process still holds files under the install dir.
• For WSL backends, a stopped wsl.exe relay does not mean the Linux-side server (or helpers it spawned, e.g. cloudflared) exited with it. New ensureWindowsPathReleased (DesktopWslEnvironment.ts) terminates and verifies from inside the distro that no Linux process still holds cwd/exe/fd/mmap references under /mnt/c/<install dir> — 9p/DrvFs handles held from WSL block file replacement on the Windows side, which is how app.asar and app.asar.unpacked end up from different builds.
• Post-apply integrity check: the build stamps apps/server/dist/desktop-build-manifest.json (under app.asar.unpacked on Windows); startup compares it against the asar's version and refuses to launch a mixed-build install with a clear repair dialog (DesktopInstallIntegrity.ts) instead of the opaque ERR_MODULE_NOT_FOUND main-process crash. Missing manifest (dev, macOS/Linux, pre-stamp installs) skips the check, so no false positives.

2. WSL endpoint detection and the readiness handshake are no longer single-point-of-failure.

• Networking mode now comes from wslinfo --networking-mode (first-party, present on WSL 2.6.x and 2.7.x) instead of being inferred from the first address in hostname -I — whose ordering shifts whenever Tailscale, Docker bridges, or VPN adapters exist inside the distro. Heuristic fallback for older WSL matches any distro IP against Windows interfaces, never position one, and CGNAT 100.64/10 addresses are never advertised.
• Readiness probes race loopback plus every enumerated distro address; the first candidate that answers wins and becomes the advertised base URL — so a wrong guess degrades startup by nothing worse than a probe race.
• After all static candidates time out, the backend's persisted server-runtime.json origin is consulted as a last-resort candidate (gated on it naming this instance's port).
• The readiness probe is no longer one-shot: a run that spawns but never answers is terminated and retried, and after 3 readiness timeouts the failure surfaces like an exhausted preflight (dialog + Windows fallback on the primary, inline Connections error on the secondary) with every probed URL named. Resolved mode and candidates are logged at startup.

25 new tests across DesktopBackendManager, DesktopUpdates, DesktopWslEnvironment, DesktopBackendConfiguration, and DesktopInstallIntegrity cover the regressions above (CGNAT-first ordering, docker0-first, wslinfo absent, one-shot-probe limbo, unverified stop, WSL busy at install time, mixed-build detection). Full desktop suite: 473 passing.

Why

Two field incidents on 0.0.33-nightly builds, plus these open issues:

• Fixes[Bug]: Desktop stuck on "Connecting to WSL" — getDistroIp picks unreachable Docker bridge IP instead of eth0 #5211 — getDistroIpImpl takes the first IPv4 from hostname -I; Docker bridge IPs sort first and are unreachable from Windows. The same mechanism breaks with a WSL-side tailscaled (CGNAT address first under mirrored networking), which we reproduced on 0.0.33-nightly: the server was listening on 0.0.0.0:3773, reachable via loopback, and logged zero client requests because every probe went to the CGNAT address.
• Fixes[Bug]: Desktop stops probing backend readiness after the 60s budget, leaving "Connecting to WSL…" stuck forever even though the backend becomes healthy #5522 — runBackendProcess forked a single waitForHttpReady with a 60s budget; on timeout onReadinessFailure only logged, leaving the run alive, never ready, never retried, never surfaced.
• Likely fixes[Bug]: "Connecting to WSL" infinite loading #5967 (symptom-level report of the same infinite splash; root cause unconfirmed in that issue).
• Improves [Bug]: Unusable. WSL backend readiness timesout at 60s because the server bundle loads over /mnt/c (takin 80s to boot) and app stuck on "Connecting to WSL…" forever #4535 — a >60s cold boot now gets terminated-and-retried (warm second boot typically fits the budget), and after 3 attempts surfaces an actionable dialog with Windows fallback instead of an infinite splash. The 60s budget itself is unchanged, so this is mitigation, not a full fix.
• Related: Windows: app stays launchable during the multi-minute NSIS update extraction, crashes with ERR_MODULE_NOT_FOUND (false-positive #4154) #5520 — the mid-extraction launch race produces the same ERR_MODULE_NOT_FOUND signature; the integrity check turns the mixed-state launch into a clear "installation is damaged/incomplete" dialog whenever the unpacked stamp has diverged from the asar. It does not (and cannot, from app code) stop NSIS from leaving the exe launchable during extraction.

The half-applied update we debugged: an in-app update left app.asar + the exe at the old build while app.asar.unpacked/node_modules was new → ERR_MODULE_NOT_FOUND on every launch, with the updater having reported nothing. Root cause: install teardown killed the wsl.exe relay and proceeded on a 5s timeout that was silently swallowed, while the Linux-side server exited asynchronously still holding 9p handles into the install dir. Same version installed fine with the app closed.

Sizing note: aware of the contribution guidelines — roughly half of this diff is tests, and the two fixes share the same touched files (DesktopBackendManager/DesktopWslEnvironment), which is why they're one PR. Happy to split into updater-atomicity and handshake PRs if you'd prefer.

This PR deliberately avoids every file touched by #2829 (orchestrator v2) — verified against its full file list, so it merges cleanly before or after.

UI Changes

No renderer UI changes. Two native dialogs are added/extended (update-install-aborted error via the existing update state machine; "installation is damaged" message box with an Open Download Page button). Not screenshotted — they require a packaged Windows build to trigger, which this dev environment can't produce; dialog copy is in DesktopInstallIntegrity.ts and DesktopUpdates.ts.

Checklist

• This PR is small and focused (two related reliability fixes, no feature work; ~half the diff is tests)
• I explained what changed and why
• I included before/after screenshots for any UI changes (native dialogs only; see UI Changes)
• I included a video for animation/interaction changes (n/a)

🤖 Generated with Claude Code

---

Note

High Risk
Changes touch critical Windows update apply, WSL process killing (root), and startup abort paths; incorrect readiness or release checks could block launches or updates, though behavior is heavily tested.

Overview
This PR targets two reliability problems on Windows with WSL—indefinite “connecting” and half-applied updates—and adds a startup guard for corrupted installs.

WSL backend reachability no longer trusts the first hostname -I address. Networking mode comes from wslinfo --networking-mode (with heuristics when unknown), CGNAT 100.64/10 IPs are never advertised, and readiness races loopback plus every distro IP; the winning URL is rebound into currentConfig. After static probes time out, server-runtime.json supplies fallback candidates. Runs that never become ready are terminated and retried, with caps that surface failures via onPreflightFailed instead of hanging forever. getDistroIp is replaced by getDistroIps.

Updates require each backend stop() to return whether the child actually exited within a 10s budget; failed installs abort, restart backends, and leave the update downloadable. On Windows, ensureWindowsPathReleased verifies WSL has released the install directory (released / busy / unknown) before quitAndInstall.

Install integrity compares the packaged app version to desktop-build-manifest.json under app.asar.unpacked (stamped at build time); mismatches or a missing manifest on packaged Windows show a repair dialog and exit before bootstrap. The build script writes the manifest into staged apps/server/dist.

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

Note

Fix update teardown on Windows+WSL with install integrity checks and resilient WSL readiness handshake

• Startup now runs an install-integrity check via DesktopInstallIntegrity before bootstrapping; on Windows, a desktop-build-manifest.json stamped at build time is compared against the app version and, on mismatch, shows an error dialog and quits.
• The update install flow in DesktopUpdates.ts now requires each running backend to confirm a finalized stop within 10 seconds and, on Windows+WSL, calls ensureWindowsPathReleased to verify the install directory is free before invoking quitAndInstall; on failure it restarts backends and surfaces an error.
• WSL readiness probing in DesktopBackendManager.ts now races multiple candidate URLs (loopback + all distro IPs) and optionally consults persisted runtime-state fallback URLs before timing out; stop() now returns a boolean indicating whether the process finalized before the timeout.
• DesktopWslEnvironment.ts replaces the single-IP getDistroIp with getDistroIps (all IPv4s), and adds getNetworkingMode, readServerRuntimeState, and ensureWindowsPathReleased with fixed timeouts and fallback semantics.
• Risk: backends that do not finalize within 10 seconds during an update will block the installer and restart, changing prior best-effort stop behavior.

^{Macroscope summarized 249a6d9.}

[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: e310a9a5-be8d-496e-b0cb-2823e06b141c

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]

Effect service conventions review: one convention violation found — the new readiness fallback path uses Effect.catchTag, which the conventions replace with Effect.catchTags({ ... }) even when recovering a single tag. Everything else (subpath namespace imports, service-member additions on DesktopWslEnvironment with matching layerTest stubs, environment-based dependency acquisition in DesktopUpdates.make, Schema.TaggedErrorClass attributes with an attribute-derived message) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f49d4ea5f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new runtime behavior beyond a simple fix: a startup integrity check that can block app launch, fundamental changes to WSL backend connection logic with multi-candidate probing, new update install abort conditions when backends don't fully stop, and new capabilities to kill Linux processes holding files. The ~2200 additions span multiple subsystems and warrant human review.

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

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

[SunkenInTime]

Current head 249a6d93da1c094c9fe2f94af989a6377dcbe6cb is not merge-ready because the required Check job is red on formatting.

The failing job reports formatting issues in:

• DesktopInstallIntegrity.ts
• DesktopBackendConfiguration.test.ts / .ts
• DesktopBackendManager.test.ts / .ts
• DesktopUpdates.test.ts / .ts

Please run the repository formatter and push the result. I reproduced the functional focused suite on Windows at 126/127 passing; the one failure is the pre-existing Windows slash assertion in the external resource-monitor test, and both desktop and script-scope typechecks pass.

[Jgratton24]

What Changed

Two Windows+WSL reliability fixes that share one user-visible symptom (an indefinite "Connecting to WSL…" splash), plus a guard that turns the corrupted-install crash into an actionable dialog. Desktop-only; no apps/server changes.

1. Update apply is verified before the installer runs (fixes the half-applied-update corruption).

• DesktopBackendInstance.stop() now reports whether the child process actually finalized within the timeout instead of silently swallowing it (DesktopBackendManager.ts).
• The install path (DesktopUpdates.ts) aborts — restarting backends and surfacing the error through the update state machine — if any backend can't be verified stopped, instead of handing off to NSIS while a process still holds files under the install dir.
• For WSL backends, a stopped wsl.exe relay does not mean the Linux-side server (or helpers it spawned, e.g. cloudflared) exited with it. New ensureWindowsPathReleased (DesktopWslEnvironment.ts) terminates and verifies from inside the distro that no Linux process still holds cwd/exe/fd/mmap references under /mnt/c/<install dir> — 9p/DrvFs handles held from WSL block file replacement on the Windows side, which is how app.asar and app.asar.unpacked end up from different builds.
• Post-apply integrity check: the build stamps apps/server/dist/desktop-build-manifest.json (under app.asar.unpacked on Windows); startup compares it against the asar's version and refuses to launch a mixed-build install with a clear repair dialog (DesktopInstallIntegrity.ts) instead of the opaque ERR_MODULE_NOT_FOUND main-process crash. Missing manifest (dev, macOS/Linux, pre-stamp installs) skips the check, so no false positives.

2. WSL endpoint detection and the readiness handshake are no longer single-point-of-failure.

• Networking mode now comes from wslinfo --networking-mode (first-party, present on WSL 2.6.x and 2.7.x) instead of being inferred from the first address in hostname -I — whose ordering shifts whenever Tailscale, Docker bridges, or VPN adapters exist inside the distro. Heuristic fallback for older WSL matches any distro IP against Windows interfaces, never position one, and CGNAT 100.64/10 addresses are never advertised.
• Readiness probes race loopback plus every enumerated distro address; the first candidate that answers wins and becomes the advertised base URL — so a wrong guess degrades startup by nothing worse than a probe race.
• After all static candidates time out, the backend's persisted server-runtime.json origin is consulted as a last-resort candidate (gated on it naming this instance's port).
• The readiness probe is no longer one-shot: a run that spawns but never answers is terminated and retried, and after 3 readiness timeouts the failure surfaces like an exhausted preflight (dialog + Windows fallback on the primary, inline Connections error on the secondary) with every probed URL named. Resolved mode and candidates are logged at startup.

25 new tests across DesktopBackendManager, DesktopUpdates, DesktopWslEnvironment, DesktopBackendConfiguration, and DesktopInstallIntegrity cover the regressions above (CGNAT-first ordering, docker0-first, wslinfo absent, one-shot-probe limbo, unverified stop, WSL busy at install time, mixed-build detection). Full desktop suite: 473 passing.

Why

Two field incidents on 0.0.33-nightly builds, plus these open issues:

• Fixes[Bug]: Desktop stuck on "Connecting to WSL" — getDistroIp picks unreachable Docker bridge IP instead of eth0 #5211 — getDistroIpImpl takes the first IPv4 from hostname -I; Docker bridge IPs sort first and are unreachable from Windows. The same mechanism breaks with a WSL-side tailscaled (CGNAT address first under mirrored networking), which we reproduced on 0.0.33-nightly: the server was listening on 0.0.0.0:3773, reachable via loopback, and logged zero client requests because every probe went to the CGNAT address.
• Fixes[Bug]: Desktop stops probing backend readiness after the 60s budget, leaving "Connecting to WSL…" stuck forever even though the backend becomes healthy #5522 — runBackendProcess forked a single waitForHttpReady with a 60s budget; on timeout onReadinessFailure only logged, leaving the run alive, never ready, never retried, never surfaced.
• Likely fixes[Bug]: "Connecting to WSL" infinite loading #5967 (symptom-level report of the same infinite splash; root cause unconfirmed in that issue).
• Improves [Bug]: Unusable. WSL backend readiness timesout at 60s because the server bundle loads over /mnt/c (takin 80s to boot) and app stuck on "Connecting to WSL…" forever #4535 — a >60s cold boot now gets terminated-and-retried (warm second boot typically fits the budget), and after 3 attempts surfaces an actionable dialog with Windows fallback instead of an infinite splash. The 60s budget itself is unchanged, so this is mitigation, not a full fix.
• Related: Windows: app stays launchable during the multi-minute NSIS update extraction, crashes with ERR_MODULE_NOT_FOUND (false-positive #4154) #5520 — the mid-extraction launch race produces the same ERR_MODULE_NOT_FOUND signature; the integrity check turns the mixed-state launch into a clear "installation is damaged/incomplete" dialog whenever the unpacked stamp has diverged from the asar. It does not (and cannot, from app code) stop NSIS from leaving the exe launchable during extraction.

The half-applied update we debugged: an in-app update left app.asar + the exe at the old build while app.asar.unpacked/node_modules was new → ERR_MODULE_NOT_FOUND on every launch, with the updater having reported nothing. Root cause: install teardown killed the wsl.exe relay and proceeded on a 5s timeout that was silently swallowed, while the Linux-side server exited asynchronously still holding 9p handles into the install dir. Same version installed fine with the app closed.

Sizing note: aware of the contribution guidelines — roughly half of this diff is tests, and the two fixes share the same touched files (DesktopBackendManager/DesktopWslEnvironment), which is why they're one PR. Happy to split into updater-atomicity and handshake PRs if you'd prefer.

This PR deliberately avoids every file touched by #2829 (orchestrator v2) — verified against its full file list, so it merges cleanly before or after.

UI Changes

No renderer UI changes. Two native dialogs are added/extended (update-install-aborted error via the existing update state machine; "installation is damaged" message box with an Open Download Page button). Not screenshotted — they require a packaged Windows build to trigger, which this dev environment can't produce; dialog copy is in DesktopInstallIntegrity.ts and DesktopUpdates.ts.

Checklist

• This PR is small and focused (two related reliability fixes, no feature work; ~half the diff is tests)
• I explained what changed and why
• I included before/after screenshots for any UI changes (native dialogs only; see UI Changes)
• I included a video for animation/interaction changes (n/a)

🤖 Generated with Claude Code

---

Note

High Risk
Changes touch critical Windows update apply, WSL process killing (root), and startup abort paths; incorrect readiness or release checks could block launches or updates, though behavior is heavily tested.

Overview
This PR targets two reliability problems on Windows with WSL—indefinite “connecting” and half-applied updates—and adds a startup guard for corrupted installs.

WSL backend reachability no longer trusts the first hostname -I address. Networking mode comes from wslinfo --networking-mode (with heuristics when unknown), CGNAT 100.64/10 IPs are never advertised, and readiness races loopback plus every distro IP; the winning URL is rebound into currentConfig. After static probes time out, server-runtime.json supplies fallback candidates. Runs that never become ready are terminated and retried, with caps that surface failures via onPreflightFailed instead of hanging forever. getDistroIp is replaced by getDistroIps.

Updates require each backend stop() to return whether the child actually exited within a 10s budget; failed installs abort, restart backends, and leave the update downloadable. On Windows, ensureWindowsPathReleased verifies WSL has released the install directory (released / busy / unknown) before quitAndInstall.

Install integrity compares the packaged app version to desktop-build-manifest.json under app.asar.unpacked (stamped at build time); mismatches or a missing manifest on packaged Windows show a repair dialog and exit before bootstrap. The build script writes the manifest into staged apps/server/dist.

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

Note

Fix update teardown on Windows+WSL with install integrity checks and resilient WSL readiness handshake

• Startup now runs an install-integrity check via DesktopInstallIntegrity before bootstrapping; on Windows, a desktop-build-manifest.json stamped at build time is compared against the app version and, on mismatch, shows an error dialog and quits.
• The update install flow in DesktopUpdates.ts now requires each running backend to confirm a finalized stop within 10 seconds and, on Windows+WSL, calls ensureWindowsPathReleased to verify the install directory is free before invoking quitAndInstall; on failure it restarts backends and surfaces an error.
• WSL readiness probing in DesktopBackendManager.ts now races multiple candidate URLs (loopback + all distro IPs) and optionally consults persisted runtime-state fallback URLs before timing out; stop() now returns a boolean indicating whether the process finalized before the timeout.
• DesktopWslEnvironment.ts replaces the single-IP getDistroIp with getDistroIps (all IPv4s), and adds getNetworkingMode, readServerRuntimeState, and ensureWindowsPathReleased with fixed timeouts and fallback semantics.
• Risk: backends that do not finalize within 10 seconds during an update will block the installer and restart, changing prior best-effort stop behavior.

^{Macroscope summarized 249a6d9.}

[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: e310a9a5-be8d-496e-b0cb-2823e06b141c

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]

Effect service conventions review: one convention violation found — the new readiness fallback path uses Effect.catchTag, which the conventions replace with Effect.catchTags({ ... }) even when recovering a single tag. Everything else (subpath namespace imports, service-member additions on DesktopWslEnvironment with matching layerTest stubs, environment-based dependency acquisition in DesktopUpdates.make, Schema.TaggedErrorClass attributes with an attribute-derived message) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:f49d4ea5f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new runtime behavior beyond a simple fix: a startup integrity check that can block app launch, fundamental changes to WSL backend connection logic with multi-candidate probing, new update install abort conditions when backends don't fully stop, and new capabilities to kill Linux processes holding files. The ~2200 additions span multiple subsystems and warrant human review.

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

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

[SunkenInTime]

Current head 249a6d93da1c094c9fe2f94af989a6377dcbe6cb is not merge-ready because the required Check job is red on formatting.

The failing job reports formatting issues in:

• DesktopInstallIntegrity.ts
• DesktopBackendConfiguration.test.ts / .ts
• DesktopBackendManager.test.ts / .ts
• DesktopUpdates.test.ts / .ts

Please run the repository formatter and push the result. I reproduced the functional focused suite on Windows at 126/127 passing; the one failure is the pre-existing Windows slash assertion in the external resource-monitor test, and both desktop and script-scope typechecks pass.