Function ensureSupervisedConnection

apps/desktop/src/main/index.ts:269–321

()

 * declined — the caller then falls back to managed-spawn.
 */
const ensureSupervisedConnection = async (): Promise<SidecarConnection | null> => {
  // 1. Already running → attach.
  const attached = await attachToSupervisedDaemon();
  if (attached) {
    return acceptSupervisedConnection(attached);
  }

  // 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;

  // 2. Registered and running, but the first attach missed it. Kick once and
  // wait only when the kick command succeeds.
  if (status.registered) {
    if (status.running) {
      const attachedAfterStatus = await attachToSupervisedDaemon();
      if (attachedAfterStatus) return acceptSupervisedConnection(attachedAfterStatus);
      // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: a restart failure just falls through to managed-spawn
      try {
        await restartSupervisedService();
      } catch (error) {
        log.warn(
          "Failed to restart running supervised service after attach failed; using managed sidecar",
          error,
        );
        return null;
      }
      return waitForSupervisedAttach(15_000);
    }

    // 3. Registered but not running usually means a stale plist/unit/task. Try
    // restart first, then reinstall the service if the OS manager cannot start it.
    // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: restart failure triggers supervised service self-heal
    try {
      await restartSupervisedService();
    } catch (error) {
      log.warn("Failed to restart registered supervised service; reinstalling", error);
      return installSupervisedAndWait("registered service restart failure");
    }
    return waitForSupervisedAttach(15_000);
  }

  // 4. First run → ask, then install + start. The unit carries no secret; the
  // supervised daemon mints/loads its bearer from auth.json under DESKTOP_DATA_DIR.
  if (!(await confirmEnableBackgroundService())) return null;
  return installSupervisedAndWait("first-run prompt");
};

// Crash monitor for the supervised daemon: the OS service manager restarts it
// on crash, but during that window the window's requests fail. Poll, show a