From 511e4feca48d7ec1ee31e98ff258c4b96653da4a Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Thu, 29 Oct 2026 23:01:32 -0700
Subject: [PATCH] docs(wsl): say what keeps a WSL distro up besides the holder
 (#36241)

On WSL 2.7.10 a process started through wsl.exe (orcad via setsid -f, its
terminals) keeps the distro Running with no Windows-side client; the holder
only covers the gaps when nothing runs. Reword the comments that assumed
only a Windows client keeps a distro from idling out.
---
 src/main/wsl/wsl-distro-holder-command.ts | 3 ++-
 src/main/wsl/wsl-distro-holder-types.ts   | 2 +-
 src/main/wsl/wsl-host-removal.ts          | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/main/wsl/wsl-distro-holder-command.ts b/src/main/wsl/wsl-distro-holder-command.ts
index 6ef57c2733e..8660ec1b551 100644
--- a/src/main/wsl/wsl-distro-holder-command.ts
+++ b/src/main/wsl/wsl-distro-holder-command.ts
@@ -72,7 +72,8 @@ export function buildWslDistroHolderScript(
   ].join('\n')
 }
 
-/** `wsl.exe` argv for a holder: only a Windows-side WSL client keeps a distro from idling out. */
+/** `wsl.exe` argv for a holder. WSL keeps a distro up while a Windows-side client or anything started
+ * through one still runs (orcad, its terminals); the holder covers the gaps when nothing does. */
 export function buildWslDistroHolderArgs(distro: string): string[] {
   return buildWslExecArgs(distro, [
     '/bin/sh',
diff --git a/src/main/wsl/wsl-distro-holder-types.ts b/src/main/wsl/wsl-distro-holder-types.ts
index 6131bac172a..7e3d64903c7 100644
--- a/src/main/wsl/wsl-distro-holder-types.ts
+++ b/src/main/wsl/wsl-distro-holder-types.ts
@@ -57,7 +57,7 @@ export type WslDistroHolder = {
   ): Promise<WslDistroHolderEnsureResult>
   /** Startup: keep holders a previous Orca left running, drop records that are provably stale. */
   adoptHolders(): Promise<WslDistroHolderAdoption[]>
-  /** Explicit stop only; the distro then idles out on WSL's own schedule. */
+  /** Explicit stop only; the distro then stops on WSL's schedule once nothing else runs in it. */
   release(distro: string): Promise<WslDistroHolderState>
   /** Every recorded holder (uninstall, hosts turned off); kills only verified holders. */
   releaseAll(options?: WslDistroHolderReleaseOptions): Promise<WslDistroHolderAdoption[]>
diff --git a/src/main/wsl/wsl-host-removal.ts b/src/main/wsl/wsl-host-removal.ts
index 3c2efa9e3c6..a3681986eb2 100644
--- a/src/main/wsl/wsl-host-removal.ts
+++ b/src/main/wsl/wsl-host-removal.ts
@@ -42,7 +42,7 @@ export async function removeWslHostServer(
         }))
     }
     await connector.disconnect(record.distro)
-    // Without its holder the distro idles out, pending or not.
+    // Without its holder the distro stops once nothing started in it (a peer's orcad, user jobs) runs.
     await connector.releaseHolder(record.distro)
   }
   serverStop = noteServerKeptForPeers(userDataPath, record.environmentId, serverStop)