fix(desktop): attach to a daemon that owns the data dir instead of wedging

The desktop app and a standalone `executor daemon run` both default to owning
~/.executor, and only one process can own it. boot() attaches to an existing
daemon before spawning, but the restart and boot-fallback paths only spawned:
when a foreign cli-daemon already owned the scope, the spawn died on the scope
lock ("already running ... owns the current data directory") and was treated as
fatal, wedging the app on the sidecar crash screen until the daemon was stopped
by hand.

startWithCurrentSettings now adopts a healthy cli-daemon that already owns the
data dir instead of failing, polling briefly to ride out an owner that is alive
but still finishing startup (the health-probe vs scope-lock race). Adopted
daemons are watched by the supervised monitor, since they have no child process
for onUnexpectedSidecarExit to observe.

Also adds EXECUTOR_TEST_SKIP_BACKGROUND_SERVICE so the packaged app can boot
headlessly, a deterministic dev e2e regression test, and a headless Linux+Xvfb
harness that reproduces the wedge against the real packaged bundle.

Author: RhysSullivan

.oxlintrc.jsonc

@@ -153,6 +153,7 @@
     "vendor/",
     "emulators/",
     "e2e/runs/",
+    "e2e/desktop-packaged/linux-vm/repro.mjs",
     "node_modules/",
     "packages/core/fumadb/",
     "packages/core/sdk/src/vendor/json-schema-to-typescript/",

apps/desktop/src/main/index.ts

@@ -231,6 +231,13 @@ const ensureSupervisedConnection = async (): Promise<SidecarConnection | null> =
     });
   }
 
+  // Headless/e2e: the first-run background-service prompt and the systemd/
+  // launchd install both need a user (and a real session bus) present. With
+  // this set, fall straight through to managed-spawn after the attach attempt
+  // so the packaged app can be driven without a window server. Mirrors
+  // EXECUTOR_TEST_AUTO_CONFIRM_RESET in reset-state.ts.
+  if (process.env.EXECUTOR_TEST_SKIP_BACKGROUND_SERVICE === "1") return null;
+
   const status = await supervisedServiceStatus();
   if (!status.supported) return null;
 
@@ -491,6 +498,17 @@ const showPortInUseDialog = async (port: number) => {
 // user-facing dialog instead of letting the app vanish without a window.
 let lastSidecarStartError: unknown = null;
 
+// A spawn aborts with this when another local server already owns ~/.executor:
+// the bundled `executor daemon run` (packaged) or assertNoOtherLocalServerOwner
+// (dev) both phrase it the same way. Treated as fatal historically, which
+// wedged the app into the crash screen whenever a CLI `executor daemon run`
+// (or a daemon a prior run left behind) held the data dir.
+const isScopeOwnershipConflict = (error: unknown): boolean => {
+  // oxlint-disable-next-line executor/no-instanceof-error, executor/no-unknown-error-message -- boundary: spawn-conflict failures arrive as plain Node errors from startSidecar; classified by message text
+  const message = error instanceof Error ? error.message : String(error);
+  return /already running|owns the current data directory/i.test(message);
+};
+
 const startWithCurrentSettings = async (): Promise<SidecarConnection | null> => {
   // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: bind failures surface as a user-facing dialog
   try {
@@ -501,6 +519,21 @@ const startWithCurrentSettings = async (): Promise<SidecarConnection | null> =>
       await showPortInUseDialog(error.port);
       return null;
     }
+    // The data dir is already owned by another local daemon. If it's a healthy
+    // cli-daemon, adopt it instead of failing — the same handoff boot() does up
+    // front, applied here so the fallback and restart paths recover from a
+    // mid-session daemon takeover. Poll briefly to ride out an owner that's
+    // alive but still finishing its own startup (the health-probe vs.
+    // scope-lock race that left the app wedged on the crash screen).
+    if (isScopeOwnershipConflict(error)) {
+      const adopted = await waitForSupervisedAttach(10_000);
+      if (adopted) {
+        log.info(
+          "Adopted the local daemon that owns the data dir instead of spawning a second one",
+        );
+        return adopted;
+      }
+    }
     lastSidecarStartError = error;
     log.error("Failed to start executor sidecar", error);
     return null;
@@ -537,6 +570,12 @@ const restartSidecarAndReload = async (): Promise<DesktopServerConnection> => {
     throw new Error("Sidecar failed to restart — see Settings");
   }
   connection = next;
+  // A restart can adopt a daemon that already owns the data dir (the
+  // attach-on-conflict fallback). An adopted daemon has no child process, so
+  // onUnexpectedSidecarExit can't see it die — watch it with the supervised
+  // monitor instead. A freshly spawned sidecar keeps the child-exit path.
+  if (next.supervisedDaemon) armSupervisedMonitor();
+  else stopSupervisedMonitor();
   installBearerAuthHeader(next.baseUrl, next.authToken);
   const window = liveMainWindow();
   if (window) await window.loadURL(webUrlForConnection(next));
@@ -910,6 +949,11 @@ const boot = async () => {
   // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: renderer navigation failure must show the startup recovery dialog, not a black window
   try {
     await createWindow(connection);
+    // The fallback can adopt a daemon that owns the data dir instead of
+    // spawning (attach-on-conflict). Like the primary supervised path, watch an
+    // adopted daemon with the supervised monitor — it has no child process for
+    // onUnexpectedSidecarExit to observe.
+    if (connection.supervisedDaemon) armSupervisedMonitor();
   } catch (error) {
     log.error("Failed to load managed sidecar web UI", error);
     const failedConnection = connection;

e2e/desktop-packaged/linux-vm/Dockerfile

@@ -0,0 +1,26 @@
+# Headless Linux box for reproducing the desktop daemon attach/spawn wedge
+# against the REAL packaged app (no macOS, no Aqua, no host GUI). The linux
+# bundle is built on the host (electron-builder --linux --arm64) and mounted at
+# /app; this image only provides Xvfb plus Electron's runtime shared libraries
+# and a Node to run the CDP repro driver.
+FROM node:22-bookworm-slim
+
+# Electron 41 runtime deps + Xvfb. Kept to the libs Chromium actually dlopen()s
+# at startup so the image stays small and the failure surface is just "missing
+# lib" (loud) rather than a silent renderer crash.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      xvfb xauth \
+      libnss3 libnspr4 \
+      libatk1.0-0 libatk-bridge2.0-0 libatspi2.0-0 \
+      libgtk-3-0 libgbm1 libdrm2 \
+      libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libxkbcommon0 \
+      libasound2 libcups2 libpango-1.0-0 libcairo2 \
+      libx11-6 libxcb1 libxext6 libxi6 libxtst6 libglib2.0-0 \
+      ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY repro.mjs /repro/repro.mjs
+
+# xvfb-run gives Chromium a virtual display; --no-sandbox is required because the
+# container runs as root and we are not setuid-installing chrome-sandbox.
+ENTRYPOINT ["xvfb-run", "-a", "-s", "-screen 0 1280x800x24", "node", "/repro/repro.mjs"]

e2e/desktop-packaged/linux-vm/README.md

@@ -0,0 +1,56 @@
+# Headless Linux reproduction: desktop daemon attach/spawn wedge
+
+Reproduces, against the REAL packaged desktop app (no macOS, no host GUI), the
+production incident where the app wedges on the sidecar crash screen because a
+standalone `executor daemon run` (the CLI daemon) already owns `~/.executor`.
+
+See `../../../notes/desktop-daemon-ownership-wedge.md` for the root cause. The
+fix lives in `apps/desktop/src/main/index.ts` (`startWithCurrentSettings`):
+when a spawn aborts because the data dir is already owned, the app attaches to
+the running cli-daemon instead of failing.
+
+## What the driver does (`repro.mjs`)
+
+Replays the exact incident over the Chrome DevTools Protocol:
+
+1. Cold boot with no daemon -> the app spawns its own managed sidecar.
+2. SIGKILL that sidecar -> the in-window crash screen appears.
+3. Start a separate `executor daemon run` that takes over `~/.executor`.
+4. Click "Restart server".
+
+Exit 0 = the app recovered by ATTACHING to the cli-daemon (fixed). Non-zero =
+it re-spawned into the scope lock and stayed wedged (the bug), or a harness
+failure. A watchdog (`REPRO_WATCHDOG_MS`, default 240s) bails loudly rather than
+hanging.
+
+## Requirements
+
+- Docker / OrbStack with linux/arm64 (Apple Silicon runs arm64 Linux natively;
+  on x64 build the bundle for linux-x64 and pass `--platform linux/amd64`).
+
+## Run
+
+Build the linux bundle on the host, then run it in the container:
+
+```sh
+# from apps/desktop — build the bundled CLI sidecar + the linux app bundle
+BUN_TARGET=linux-arm64 bun ./scripts/build-sidecar.ts
+bunx --bun electron-vite build
+bunx --bun electron-builder --linux --arm64 --config electron-builder.e2e.config.ts
+
+# from this dir — build the image and run the repro
+cd ../../e2e/desktop-packaged/linux-vm
+docker build --platform linux/arm64 -t executor-linux-repro .
+docker run --rm --init --platform linux/arm64 \
+  -v "$PWD/../../../apps/desktop/dist/linux-arm64-unpacked":/app:ro \
+  executor-linux-repro
+```
+
+Always run with `--init` so Electron's detached children are reaped and the
+container exits cleanly.
+
+## Proving the bug (RED)
+
+Build the bundle from a commit BEFORE the fix and run the same image against it:
+the driver reports `FAIL: app stayed wedged on the crash screen after restart`
+and exits non-zero. Against the fixed bundle it prints `PASS`.