feat(desktop): surface dual-mode WSL backend preflight failures in settings

A fatal preflight failure on the dual-mode WSL secondary used to stop silently
after the cap, leaving the user with WSL enabled but no backend and no reason
why. Record the reason on DesktopWslBackend, expose it via the getWslState IPC,
and show it inline in the Connections WSL row (no modal dialog; Windows keeps
working). Cleared on any reconcile so it reflects the current attempt; stays
null in wsl-only mode, which surfaces via a dialog + fallback instead.

Author: Jgratton24

apps/desktop/src/ipc/methods/wsl.ts

@@ -1,5 +1,6 @@
 import { DesktopWslStateSchema, type DesktopWslState } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 
 import * as DesktopLifecycle from "../../app/DesktopLifecycle.ts";
@@ -12,21 +13,28 @@ import { makeIpcMethod } from "../DesktopIpc.ts";
 const readWslState: Effect.Effect<
   DesktopWslState,
   never,
-  DesktopAppSettings.DesktopAppSettings | DesktopWslEnvironment.DesktopWslEnvironment
+  | DesktopAppSettings.DesktopAppSettings
+  | DesktopWslEnvironment.DesktopWslEnvironment
+  | DesktopWslBackend.DesktopWslBackend
 > = Effect.gen(function* () {
   const appSettings = yield* DesktopAppSettings.DesktopAppSettings;
   const wslEnvironment = yield* DesktopWslEnvironment.DesktopWslEnvironment;
+  const wslBackend = yield* DesktopWslBackend.DesktopWslBackend;
   const settings = yield* appSettings.get;
   const available = yield* wslEnvironment.isAvailable;
   // Only enumerate distros when WSL is actually available — listDistros on a
   // non-WSL host would spawn wsl.exe and hit the timeout for nothing.
   const distros = available ? yield* wslEnvironment.listDistros : [];
+  const preflightError = yield* wslBackend.lastPreflightError;
   return {
     enabled: settings.wslBackendEnabled,
     distro: settings.wslDistro,
     available,
     wslOnly: settings.wslOnly,
     distros,
+    // Only the dual-mode secondary records this; a wsl-only failure surfaces via
+    // a dialog + Windows fallback, so it stays null there.
+    preflightError: settings.wslOnly ? null : Option.getOrNull(preflightError),
   };
 });
 

apps/desktop/src/wsl/DesktopWslBackend.ts

@@ -25,6 +25,7 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Ref from "effect/Ref";
 import * as Semaphore from "effect/Semaphore";
 
 import * as NetService from "@t3tools/shared/Net";
@@ -49,6 +50,11 @@ export interface DesktopWslBackendShape {
   // Idempotent. Never fails (errors are logged); callers can chain it
   // after persisting settings without an error-handling dance.
   readonly reconcile: Effect.Effect<void>;
+  // Reason the dual-mode WSL secondary last failed preflight (no node, wrong
+  // version, missing build tools), or None. Read by the getWslState IPC so
+  // Connections settings can show it inline. None in wsl-only mode (that path
+  // surfaces via a dialog + Windows fallback).
+  readonly lastPreflightError: Effect.Effect<Option.Option<string>>;
 }
 
 export class DesktopWslBackend extends Context.Service<DesktopWslBackend, DesktopWslBackendShape>()(
@@ -102,6 +108,13 @@ export const layer = Layer.effect(
     // with different distros, leaving the loser stranded.
     const reconcileMutex = yield* Semaphore.make(1);
 
+    // Last fatal preflight failure from the dual-mode WSL *secondary*, surfaced
+    // inline in Connections settings. The primary's failure is handled by the
+    // pool (dialog + Windows fallback) instead; here the app stays usable on
+    // Windows, so we record the reason rather than interrupting. Cleared on any
+    // reconcile state change so it reflects the current attempt.
+    const preflightErrorRef = yield* Ref.make(Option.none<string>());
+
     const findExistingWslInstance = pool.list.pipe(
       Effect.map((instances) => instances.find((instance) => isWslInstanceId(instance.id))),
       Effect.map(Option.fromNullishOr),
@@ -150,6 +163,10 @@ export const layer = Layer.effect(
           id: targetId,
           label: Effect.succeed(buildLabel(input.distro)),
           configResolve: configuration.resolveWsl({ port: allocatedPort, distro: input.distro }),
+          // Dual-mode secondary: record a fatal preflight failure so Connections
+          // settings can show why the WSL backend never appeared. No dialog or
+          // fallback — Windows is the primary and keeps working.
+          onPreflightFailed: (reason) => Ref.set(preflightErrorRef, Option.some(reason)),
         })
         .pipe(
           Effect.map((registered) => Option.some(registered)),
@@ -195,6 +212,11 @@ export const layer = Layer.effect(
         return;
       }
 
+      // A real state change is happening (start, stop, or distro swap). Clear
+      // any stale secondary preflight error so it reflects this fresh attempt;
+      // onPreflightFailed re-sets it only if the new secondary exhausts retries.
+      yield* Ref.set(preflightErrorRef, Option.none());
+
       if (Option.isSome(existingId)) {
         yield* logWslBackendInfo("tearing down WSL backend", { id: existingId.value });
         yield* stopExisting(existingId.value);
@@ -227,6 +249,9 @@ export const layer = Layer.effect(
         Effect.withSpan("desktop.wslBackend.reconcile"),
       );
 
-    return DesktopWslBackend.of({ reconcile });
+    return DesktopWslBackend.of({
+      reconcile,
+      lastPreflightError: Ref.get(preflightErrorRef),
+    });
   }),
 );

apps/web/src/components/settings/ConnectionsSettings.tsx

@@ -3031,6 +3031,10 @@ export function ConnectionsSettings() {
           status={
             desktopWslError ? (
               <span className="block text-destructive">{desktopWslError}</span>
+            ) : desktopWslState.preflightError ? (
+              <span className="block text-destructive">
+                WSL backend couldn't start: {desktopWslState.preflightError}
+              </span>
             ) : null
           }
           control={

apps/web/src/localApi.test.ts

@@ -235,27 +235,31 @@ function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridg
       available: false,
       wslOnly: false,
       distros: [],
+      preflightError: null,
     }),
     setWslBackendEnabled: async () => ({
       enabled: false,
       distro: null,
       available: false,
       wslOnly: false,
       distros: [],
+      preflightError: null,
     }),
     setWslDistro: async () => ({
       enabled: false,
       distro: null,
       available: false,
       wslOnly: false,
       distros: [],
+      preflightError: null,
     }),
     setWslOnly: async () => ({
       enabled: false,
       distro: null,
       available: false,
       wslOnly: false,
       distros: [],
+      preflightError: null,
     }),
     pickFolder: async () => null,
     confirm: async () => true,

packages/contracts/src/ipc.ts

@@ -421,6 +421,11 @@ export interface DesktopWslState {
   // primary backend's spec is captured once at layer init.
   wslOnly: boolean;
   distros: readonly DesktopWslDistro[];
+  // Reason the dual-mode WSL backend last failed preflight (no node, wrong
+  // version, missing build tools), or null. Surfaced inline in Connections
+  // settings. Always null in wsl-only mode — that path shows a dialog and
+  // falls back to Windows instead.
+  preflightError: string | null;
 }
 
 export const DesktopWslStateSchema = Schema.Struct({
@@ -429,6 +434,7 @@ export const DesktopWslStateSchema = Schema.Struct({
   available: Schema.Boolean,
   wslOnly: Schema.Boolean,
   distros: Schema.Array(DesktopWslDistroSchema),
+  preflightError: Schema.NullOr(Schema.String),
 });
 
 export const DesktopCloudAuthFetchInputSchema = Schema.Struct({