dsh-clean-desktop-shell 0.1.12 → 0.1.13

package/electron/service.js

@@ -6,6 +6,16 @@
  *  - start() / stop() / restart()
  *  - status: 'running' | 'stopped' | 'starting' | 'error'
  *
+ * Lifecycle vs responsiveness: every status carries a `cause` so consumers
+ * can tell a CONFIRMED lifecycle event from an OBSERVED state:
+ *  - cause 'exit'  — the managed child process really exited (or died while
+ *    starting);
+ *  - cause 'stop'  — an explicit tray stop terminated the backend;
+ *  - cause 'probe' — detect() found nothing answering on the port (an
+ *    observation; the backend may merely be slow or external).
+ * Only 'exit'/'stop' mean the backend that owns a loaded page is gone; a
+ * 'probe'-derived 'stopped' must never be treated as a process exit.
+ *
  * Shell/core decoupling: when a remote target URL is configured, no local
  * backend is ever touched — this module only manages the local dsh CLI.
  */
@@ -32,6 +42,7 @@ function cappedAppend(prev, chunk) {
 let child = null
 let currentStatus = 'stopped'
 let lastError = null
+let currentCause = null
 let startResolver = null
 
 // dsh 0.1.2+ gates the web index behind a per-process launch token: the
@@ -64,10 +75,14 @@ export function onStatusChange(cb) {
   return () => listeners.delete(cb)
 }
 
-function setStatus(next, error = null) {
-  if (currentStatus !== next || lastError !== error) {
+function setStatus(next, error = null, cause = null) {
+  // A same-status re-emission with a different cause (e.g. probe-derived
+  // 'stopped' followed by the real child exit) must still notify — the
+  // cause is what upgrades an observation to a confirmed lifecycle event.
+  if (currentStatus !== next || lastError !== error || currentCause !== cause) {
     currentStatus = next
     lastError = error
+    currentCause = cause
     for (const cb of listeners) {
       try {
         cb(getStatus())
@@ -81,6 +96,7 @@ function setStatus(next, error = null) {
 export function getStatus() {
   return {
     status: currentStatus,
+    cause: currentCause,
     port: DEFAULT_PORT,
     url: LOCAL_URL,
     launchUrl: currentLaunchUrl,
@@ -122,17 +138,30 @@ export async function probe(url, timeoutMs = 1500) {
  * Detect a reachable local dsh web service.
  * Returns the URL when something already listens on the port,
  * or null when the backend is down.
+ *
+ * Never demotes a shell-managed child: while one is alive, reachability is
+ * the liveness watch's job (window.js probes), so a transient probe failure
+ * here cannot corrupt lifecycle state. The status is likewise never
+ * promoted here — during 'starting' the launch URL is not minted yet, and
+ * only the ready line (or the start-timeout probe) may flip 'starting' →
+ * 'running'. Unmanaged results are observations and are reported with
+ * cause 'probe' — not confirmed exits.
  */
 export async function detect() {
+  if (child && child.exitCode === null) {
+    // Managed child alive — lifecycle state owns itself; no probe, no
+    // status change (in particular: no promotion out of 'starting').
+    return LOCAL_URL
+  }
   const state = await probeState(LOCAL_URL)
   if (state.alive) {
-    setStatus('running')
+    setStatus('running', null, 'probe')
     return LOCAL_URL
   }
   // The old process token (if any) belongs to a backend that is no longer
   // listening. Keep it out of the next backend's bootstrap.
   currentLaunchUrl = null
-  setStatus('stopped')
+  setStatus('stopped', null, 'probe')
   return null
 }
 
@@ -196,10 +225,14 @@ export async function start({ backendPath } = {}) {
     if (currentStatus === 'starting' && startResolver) {
       const r = startResolver
       startResolver = null
-      setStatus('error', `dsh 后端异常退出 (code ${code})`)
+      setStatus('error', `dsh 后端异常退出 (code ${code})`, 'exit')
       r.reject(new Error(lastError))
-    } else if (currentStatus !== 'stopped') {
-      setStatus('stopped')
+    } else {
+      // Confirmed lifecycle exit. Always (re)emit with cause 'exit' — when a
+      // probe-derived 'stopped' preceded the real exit, the cause upgrade is
+      // what tells listeners this was a genuine process death, not an
+      // observation.
+      setStatus('stopped', null, 'exit')
     }
   })
 
@@ -274,7 +307,9 @@ export async function stop() {
   if (child) {
     const proc = child
     child = null
-    setStatus('stopped')
+    // Intentional lifecycle stop of the managed child — a confirmed exit
+    // (cause 'stop'), unlike an observed unreachability.
+    setStatus('stopped', null, 'stop')
     await terminate(proc)
     await ensurePortFree(DEFAULT_PORT)
     return
@@ -287,9 +322,12 @@ export async function stop() {
     if (name && /node/i.test(name)) {
       await killProcess(pid)
       await ensurePortFree(DEFAULT_PORT)
+      setStatus('stopped', null, 'stop')
     }
   }
-  setStatus('stopped')
+  // Nothing was terminated: no status change at all. Emitting 'stopped'
+  // here would fabricate a confirmed exit (cause 'stop') where none
+  // happened — a probe-derived 'stopped' must stay an observation.
 }
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

package/electron/window.js

@@ -5,21 +5,30 @@
  * window-controls overlay (Win) / hiddenInset (mac), and nothing else.
  * No Mica, no vibrancy — keep it clean.
  *
- * Window reliability (Edge-style instant refresh):
+ * Window reliability (non-destructive recovery):
  *  - the window shows immediately on launch (never waits for the backend);
- *  - while the backend is unreachable the page load fails and we swap in a
- *    local "backend offline" screen;
- *  - a background poll keeps probing the target; as soon as the backend
- *    answers, the real page is loaded automatically;
- *  - the moment the backend goes down (tray stop, external kill, crash) the
- *    window flips back to the offline screen instead of showing a stale page
- *    that suggests the app is still alive.
+ *  - without a loaded session (boot, or a page load that failed) an
+ *    unreachable backend swaps in the local "backend offline" screen, which
+ *    re-probes and loads the real page automatically when it answers;
+ *  - once a real page is loaded, a failed liveness probe NEVER navigates
+ *    away: the page stays up (draft, scroll, selection intact) and an
+ *    in-page notice appears with retry/reload actions. The notice clears by
+ *    itself once BOTH health signals are clear — the HTTP probe answers AND
+ *    the page's own DSH client runtime reports 'connected' (bridged from
+ *    src/client/client.js) — so recovery syncs through the app's own
+ *    reconnect loop, never an artificial full reload;
+ *  - a confirmed backend exit (service status cause 'exit'/'stop': tray
+ *    stop, managed child crash) is the one case that still flips a loaded
+ *    page to the offline screen — visible recovery instead of a stale
+ *    "online" page. Probe-observed states (watch or detect() timeouts,
+ *    cause 'probe') are never treated as a process exit.
  */
 import { app, BrowserWindow, ipcMain } from 'electron'
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { probe, onStatusChange, detect, getStatus } from './service.js'
+import { OutageRun } from './outage.js'
 import { startBackendWithProgress, chooseBackendFolder } from './tray.js'
 import { APP_USER_MODEL_ID } from './aumid.js'
 
@@ -59,10 +68,11 @@ const RECONNECT_INTERVAL_MS = 2500
 // How often we check the backend is still alive while the page is shown.
 const WATCH_INTERVAL_MS = 4000
 
-// Top drag-strip geometry. Must mirror the strip the preload injects
-// (preload.js: dragHeight 32 on Windows, 28 elsewhere) — the strip swallows
-// pointer events over the top band, so dockable panels must be told how many
-// pixels to yield. better-sidebar reads this through its documented shell
+// Top drag-strip geometry. The preload strip is 32px on Windows, 12px on
+// macOS (kept BELOW the web UI's own ~16px toolbar padding so no clickable
+// control is swallowed). The inset stamped here is deliberately 28px on
+// macOS — larger than the strip — so dockable panels (better-sidebar) both
+// clear the swallow band and keep clear of the traffic lights. better-sidebar reads this through its documented shell
 // contract: `dsh-desktop-titlebar-inset` on the render URL.
 function isWin() {
   return process.platform === 'win32'
@@ -97,6 +107,82 @@ const reconnectTimers = new Map()
 const watchTimers = new Map()
 const windowTargets = new Map()
 const statusUnsubs = new Map()
+// Per-window backend-outage run (see outage.js): consecutive-failure
+// escalation for the notice + the navigation token that discards stale
+// probe results after a flip/navigation/disposal.
+const outageRuns = new Map()
+// Single-flight guard: at most one backend probe per window at a time,
+// shared by the watch tick, the reconnect tick and manual retries, so two
+// overlapping polls can never double-act on the same result.
+const pollInFlight = new Map()
+// Merged per-window connection state: HTTP liveness outcome (from the
+// outage run) + DSH client-runtime reports from the loaded page (client
+// half, src/client/client.js). The notice reflects BOTH — an HTTP success
+// must never hide a known terminal disconnect of the page's own connection.
+//   http: last committed probe payload ({state:'ok'|'degraded',…}) or null
+//   client: 'connected'|'connecting'|'disconnected', or null until the
+//           page runtime's first report (bridge forward of the initial
+//           snapshot covers the disconnect-before-first-probe case)
+//   reconnectPending: a shell-requested client reconnect is outstanding
+//           (cleared when the runtime reports connecting/connected)
+const connStates = new Map()
+
+/** Fresh merged state for a window that (re)loaded a page. */
+function resetConn(win) {
+  connStates.set(win.id, { http: null, client: null, reconnectPending: false })
+}
+
+function connStateOf(win) {
+  let st = connStates.get(win.id)
+  if (!st) {
+    st = { http: null, client: null, reconnectPending: false }
+    connStates.set(win.id, st)
+  }
+  return st
+}
+
+/**
+ * Recompute what the in-page notice should show from the merged state and
+ * push it to the renderer. The notice is visible whenever the page's own
+ * connection is known bad (client 'connecting'/'disconnected') OR the last
+ * HTTP probe failed; it hides only when both are clear. The persistent copy
+ * (stronger copy + reload action) is offered for anything terminal — a
+ * long HTTP outage OR the client runtime sitting in 'disconnected' — but
+ * not for 'connecting', where an automatic retry attempt is already in
+ * progress and must not be interrupted or escalated.
+ */
+function refreshNotice(win) {
+  if (win.isDestroyed()) return
+  const st = connStateOf(win)
+  const httpOk = !st.http || st.http.state === 'ok'
+  const clientBad = st.client === 'connecting' || st.client === 'disconnected'
+  let payload
+  if (!clientBad && httpOk) {
+    payload = { state: 'ok' }
+  } else {
+    payload = {
+      state: 'degraded',
+      persistent:
+        st.client === 'disconnected'
+        || !!(st.http && st.http.state !== 'ok' && st.http.persistent),
+    }
+  }
+  win.webContents.send('shell:connection-state', payload)
+}
+
+/**
+ * Ask the loaded page's DSH client runtime to reconnect through its own
+ * reconnect loop (shell:client-reconnect → preload → client.js →
+ * ctx.connection.reconnect()). Never sent while the runtime already
+ * reports 'connecting' (an attempt is in progress) and never repeated per
+ * watch tick while an earlier request is still outstanding.
+ */
+function requestClientReconnect(win) {
+  const st = connStateOf(win)
+  if (st.reconnectPending || st.client === 'connecting') return
+  st.reconnectPending = true
+  win.webContents.send('shell:client-reconnect')
+}
 // Pending launch URL for this window. It exists only until DSH exchanges the
 // ?token= for the HttpOnly cookie and 303s back to clean "/", then it is
 // cleared so normal reloads/reconnects use the bare canonical target.
@@ -119,6 +205,27 @@ function clearLaunchUrl(win) {
   if (windowLaunchUrls.has(win.id)) windowLaunchUrls.set(win.id, null)
 }
 
+/** The outage run of this window (created lazily on first use). */
+function runFor(win) {
+  let run = outageRuns.get(win.id)
+  if (!run) {
+    run = new OutageRun()
+    outageRuns.set(win.id, run)
+  }
+  return run
+}
+
+/**
+ * The window is about to navigate (flip, reload, reconnect success):
+ * invalidate every in-flight probe of this window and start fresh outage +
+ * merged-connection state, so stale results can never act on the newer
+ * navigation.
+ */
+function bumpNav(win) {
+  runFor(win).reset()
+  resetConn(win)
+}
+
 // Manual reload requests come from the tray button and from the offline
 // screen's retry button (via preload -> ipcRenderer). Route them to the
 // window that sent the message.
@@ -129,6 +236,37 @@ ipcMain.on('shell:reload', (event) => {
   }
 })
 
+// Manual retries share the same probe and reconnect guards as the watch.
+// A reachable backend may need a fresh client generation even if the page
+// has not yet reported its old connection as disconnected.
+ipcMain.on('shell:retry-connection', (event) => {
+  const win = BrowserWindow.fromWebContents(event.sender)
+  if (win && !win.isDestroyed()) {
+    const target = windowTargets.get(win.id)
+    checkBackend(win, target, true)
+  }
+})
+
+// The loaded page's DSH client runtime reports its own connection lifecycle
+// (client.js → shellAPI.connectionReport). Terminal disconnect of the page
+// connection is invisible to HTTP probes — merge it into the notice state.
+ipcMain.on('shell:client-connection', (event, state) => {
+  if (state !== 'connected' && state !== 'connecting' && state !== 'disconnected') return
+  const win = BrowserWindow.fromWebContents(event.sender)
+  if (!win || win.isDestroyed()) return
+  // Only reports from the loaded real page count; the offline screen has no
+  // client runtime and stale frames after navigation must not act.
+  const target = windowTargets.get(win.id)
+  if (!target || !win.webContents.getURL().startsWith(target)) return
+  const st = connStateOf(win)
+  st.client = state
+  // A request is outstanding only while the runtime stays 'disconnected':
+  // 'connecting' means an attempt is in progress, 'connected' means done.
+  if (state !== 'disconnected') st.reconnectPending = false
+  refreshNotice(win)
+  // Automatic retries are paced by checkBackend, not by failure feedback.
+})
+
 // Offline-screen quick actions: start / detect backend, pick install
 // folder. The resulting state changes propagate via onStatusChange
 // (window flip + tray refresh), so no extra wiring is needed here.
@@ -136,6 +274,69 @@ ipcMain.on('shell:start-backend', () => startBackendWithProgress())
 ipcMain.on('shell:detect-backend', () => detect())
 ipcMain.on('shell:choose-backend-folder', () => chooseBackendFolder())
 
+// ---------- backend probing (shared by reconnect + watch + manual retry) ----------
+
+/**
+ * Run one guarded backend probe for this window.
+ *
+ * `commit` true (liveness watch / manual retry): the result advances the
+ * window's outage run and returns the renderer notice payload
+ * ({state:'ok'} / {state:'degraded', persistent}) — or null when skipped
+ * (another poll already in flight) or stale (run reset because the window
+ * navigated or was disposed while the probe was in flight).
+ *
+ * `commit` false (offline reconnect): returns the bare probe result
+ * (true/false) or null for the same skip/stale cases, without touching the
+ * outage run.
+ *
+ * Timeout stays at 1500ms — the same value as the service.js probe default.
+ */
+async function guardedProbe(win, target, commit = false) {
+  if (win.isDestroyed() || pollInFlight.get(win.id)) return null
+  const run = runFor(win)
+  const token = run.checkpoint()
+  pollInFlight.set(win.id, true)
+  let up = false
+  try {
+    up = await probe(target, 1500)
+  } finally {
+    pollInFlight.delete(win.id)
+  }
+  if (win.isDestroyed()) return null
+  return commit ? run.apply(token, up) : run.isCurrent(token) ? up : null
+}
+
+/**
+ * Probe the backend while the real page is shown and record the outcome
+ * into the merged per-window connection state (refreshNotice then decides
+ * the notice — HTTP and client-runtime signals combined). Never navigates:
+ * a failed probe keeps the loaded page (draft, scroll, selection) and only
+ * escalates the notice copy after consecutive failures (OutageRun). The
+ * offline screen is reached exclusively via confirmed lifecycle exits
+ * (service status cause 'exit'/'stop') or boot without a loaded page.
+ */
+async function checkBackend(win, target, forceReconnect = false) {
+  if (win.isDestroyed() || !target) return
+  const outcome = await guardedProbe(win, target, true)
+  if (!outcome) return
+  // Only the loaded real page carries the notice overlay; the offline screen
+  // has its own copy and mid-navigation pages must not get a stray message.
+  if (!win.webContents.getURL().startsWith(target)) {
+    // Page left the target (navigation in progress / other origin) — when it
+    // comes back, outage + connection state start fresh.
+    bumpNav(win)
+    return
+  }
+  const st = connStateOf(win)
+  st.http = outcome
+  refreshNotice(win)
+  // Retry only after a fresh successful probe. An immediately failing
+  // client generation must not feed back into another immediate attempt.
+  if (outcome.state === 'ok' && (forceReconnect || st.client === 'disconnected')) {
+    requestClientReconnect(win)
+  }
+}
+
 // ---------- offline mode ----------
 
 function stopReconnect(win) {
@@ -159,9 +360,13 @@ function startReconnect(win, target) {
     // and lose the ?token= bootstrap. Wait for service.start() to deliver
     // running + launchUrl instead.
     if ((await getStatus()).status === 'starting') return
-    const up = await probe(target)
+    const up = await guardedProbe(win, target)
+    if (up === null) return
     if (up) {
       stopReconnect(win)
+      // Navigating away from the offline screen — invalidate any probe that
+      // started before this moment so it cannot race the navigation.
+      bumpNav(win)
       win.webContents.loadURL(urlToLoad(win)).catch(() => startReconnect(win, target))
     }
   }, RECONNECT_INTERVAL_MS)
@@ -181,17 +386,12 @@ function stopWatch(win) {
 /** While the real page is shown, watch that the backend stays alive. */
 function startWatch(win, target) {
   if (watchTimers.has(win.id)) return
-  const timer = setInterval(async () => {
+  const timer = setInterval(() => {
     if (win.isDestroyed()) {
       stopWatch(win)
       return
     }
-    const up = await probe(target, 1500)
-    if (!up) {
-      // Backend vanished — flip to the offline screen immediately so the
-      // stale page cannot fool the user into thinking the app is alive.
-      showOffline(win)
-    }
+    checkBackend(win, target)
   }, WATCH_INTERVAL_MS)
   watchTimers.set(win.id, timer)
 }
@@ -203,6 +403,7 @@ function showOffline(win) {
   if (win.isDestroyed()) return
   const target = windowTargets.get(win.id)
   stopWatch(win)
+  bumpNav(win)
   win.loadFile(ERROR_PAGE).catch(() => {})
   if (target) startReconnect(win, target)
 }
@@ -213,6 +414,7 @@ function showOnline(win) {
   const target = windowTargets.get(win.id)
   if (!target) return
   stopReconnect(win)
+  bumpNav(win)
   win.webContents.loadURL(urlToLoad(win)).catch(() => startReconnect(win, target))
 }
 
@@ -220,6 +422,7 @@ function showOnline(win) {
 export function reloadWindow(win, target) {
   if (!win || win.isDestroyed()) return
   stopReconnect(win)
+  bumpNav(win)
   win.webContents.loadURL(urlToLoad(win)).catch(() => startReconnect(win, target))
 }
 
@@ -290,7 +493,18 @@ export function createMainWindow({ target, launchUrl }) {
   const unsub = onStatusChange((st) => {
     if (win.isDestroyed()) return
     const isOffline = win.webContents.getURL().startsWith(ERROR_PAGE_URL)
-    if (st.status === 'stopped' || st.status === 'error') {
+    // Confirmed lifecycle exit only: the status machine witnessed the
+    // backend leave — the managed child really exited (cause 'exit',
+    // whether it died while running → 'stopped' or while starting →
+    // 'error') or an explicit tray stop actually terminated it (cause
+    // 'stop' → 'stopped'). Probe-derived states (detect() timeouts →
+    // cause 'probe') and start failures are observations, not exits — they
+    // must never navigate a loaded page away; the liveness watch reports
+    // them through the in-page notice.
+    const confirmedExit =
+      (st.status === 'stopped' || st.status === 'error')
+      && (st.cause === 'exit' || st.cause === 'stop')
+    if (confirmedExit) {
       // The old process token died with the backend. Drop it so a later
       // reconnect cannot replay a stale launch URL.
       windowLaunchUrls.set(win.id, null)
@@ -327,7 +541,10 @@ export function createMainWindow({ target, launchUrl }) {
       startReconnect(win, windowTargets.get(win.id) || target)
       return
     }
-    // Backend unreachable: show the offline screen and start re-probing.
+    // The navigation itself failed, so no loaded session is on screen
+    // (a user reload or initial boot reached a dead backend). The offline
+    // screen is the honest fallback here — unlike a liveness-probe timeout,
+    // this is not navigating away from a live page.
     showOffline(win)
   })
 
@@ -350,8 +567,11 @@ export function createMainWindow({ target, launchUrl }) {
         }
         if (clean) clearLaunchUrl(win)
       }
-      // Real backend page reached — stop re-probing and watch it.
+      // Real backend page reached — stop re-probing, start a fresh outage
+      // run + merged connection state and watch it.
       stopReconnect(win)
+      runFor(win).reset()
+      resetConn(win)
       startWatch(win, active)
       // The token exchange 303s to clean "/", which drops the shell contract
       // params. Re-load the stamped target once so panels relying on the
@@ -374,6 +594,9 @@ export function createMainWindow({ target, launchUrl }) {
     windowTargets.delete(win.id)
     windowLaunchUrls.delete(win.id)
     restampedWindows.delete(win.id)
+    outageRuns.delete(win.id)
+    pollInFlight.delete(win.id)
+    connStates.delete(win.id)
   })
 
   return win

package/lib/client.js

@@ -1,11 +1,21 @@
 /**
  * dsh-clean-desktop-shell — client half (web browser bundle).
  *
- * The shell is a standalone Electron window; it injects nothing into the
- * dsh web UI. This client module exists only to satisfy the client-modules
- * loader contract — a bundle's client entry must register itself via
- * `window.__ModuleLoader__.load({ id, factory })`, otherwise dsh reports
- * "loaded without registering … via __ModuleLoader__.load".
+ * Bridges the page's DSH client-runtime connection lifecycle into the
+ * Electron shell so HTTP health alone can never hide a terminal disconnect
+ * (e.g. the backend restarted under the page: HTTP answers again while the
+ * page's WebSocket generation is dead).
+ *
+ *  - ctx.connection.state ('connected' | 'connecting' | 'disconnected') is
+ *    forwarded to the main process (shell:client-connection → preload
+ *    shellAPI.connectionReport);
+ *  - main-process reconnect requests (shell:client-reconnect →
+ *    shellAPI.onReconnectRequest) call ctx.connection.reconnect() —
+ *    recovery through the app's own reconnect loop, never a reload.
+ *
+ * The supported baseline provides ctx.connection.state / reconnect();
+ * missing APIs fail activation loudly instead of degrading. A plain browser
+ * (no shellAPI — no Electron shell) is the only silent case.
  */
 window.__ModuleLoader__.load({
   id: 'dsh-clean-desktop-shell',
@@ -13,7 +23,32 @@ window.__ModuleLoader__.load({
     var module = { exports: {} };
     var exports = module.exports;
     Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-    exports.apply = () => {};
+    exports.inject = ['connection'];
+    exports.apply = function (ctx) {
+      var api = window.shellAPI;
+      if (!api) return;
+      var connection = ctx.connection;
+      var latest = null;
+      var notify = function () {
+        var state = connection.state.getSnapshot();
+        if (state === latest) return;
+        latest = state;
+        if (state === 'connected' || state === 'connecting' || state === 'disconnected') {
+          api.connectionReport(state);
+        }
+      };
+      var unsubscribe = connection.state.subscribe(notify);
+      notify(); // report whatever the runtime already is — a lost initial disconnect must not be hidden
+      var unregisterRequest = api.onReconnectRequest(function () {
+        connection.reconnect();
+      });
+      ctx.effect(function () {
+        return function () {
+          unsubscribe();
+          unregisterRequest();
+        };
+      });
+    };
     return module.exports;
   },
 });

package/lib/icon.js

@@ -16,6 +16,48 @@ import { existsSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { PKG_ROOT, isWin, runtimeRoot, fetchFile } from './common.js'
 
+const RCEDIT_NAME = 'rcedit-x64.exe'
+const RCEDIT_URL = 'https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe'
+
+/**
+ * rcedit is a ~1.3 MB self-contained exe, and its download sits on the launch
+ * path (Windows locks a running image, so the patch has to happen before the
+ * exe is spawned). fetchFile's default budget — 600 s — is sized for the
+ * ~100 MB Electron runtime, not for this: behind a stalled proxy it could keep
+ * the window off screen for ten minutes. Cap it well below that; a miss only
+ * costs the default icon.
+ */
+const RCEDIT_TIMEOUT_SEC = 20
+
+let rceditPromise = null
+
+/**
+ * Fetch (once) the cached rcedit binary next to the runtimes. Memoised so the
+ * host half can start this alongside the Electron runtime download and have
+ * the icon step reuse the same fetch instead of serialising behind it.
+ *
+ * Never rejects: every failure mode just means "no rcedit, default icon".
+ */
+export function ensureRcedit(ctx) {
+  if (!rceditPromise) {
+    rceditPromise = (async () => {
+      try {
+        const rcedit = join(runtimeRoot(), RCEDIT_NAME)
+        if (existsSync(rcedit)) return rcedit
+        ctx.logger.info('[clean-desktop-shell] downloading rcedit for icon patching')
+        if (await fetchFile(RCEDIT_URL, rcedit, RCEDIT_TIMEOUT_SEC)) return rcedit
+        ctx.logger.warn('[clean-desktop-shell] rcedit download failed — taskbar icon stays default')
+      } catch (err) {
+        ctx.logger.warn(`[clean-desktop-shell] rcedit unavailable (${err?.message ?? err}) — taskbar icon stays default`)
+      }
+      // Not memoised as a failure: a later launch deserves a fresh attempt.
+      rceditPromise = null
+      return null
+    })()
+  }
+  return rceditPromise
+}
+
 export async function patchExeIcon(ctx, exe) {
   if (!isWin) return
   const ico = join(PKG_ROOT, 'build', 'icon.ico')
@@ -23,16 +65,8 @@ export async function patchExeIcon(ctx, exe) {
   const marker = `${exe}.whale-icon`
   if (existsSync(marker)) return
 
-  // rcedit is a single self-contained exe, cached next to the runtimes.
-  const rcedit = join(runtimeRoot(), 'rcedit-x64.exe')
-  if (!existsSync(rcedit)) {
-    const url = 'https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe'
-    ctx.logger.info('[clean-desktop-shell] downloading rcedit for icon patching')
-    if (!(await fetchFile(url, rcedit))) {
-      ctx.logger.warn('[clean-desktop-shell] rcedit download failed — taskbar icon stays default')
-      return
-    }
-  }
+  const rcedit = await ensureRcedit(ctx)
+  if (!rcedit) return
 
   const child = spawn(rcedit, [exe, '--set-icon', ico], {
     windowsHide: true,