@amd-gaia/agent-ui 0.25.4-rc.8 → 0.25.4

package/dist/assets/{zap-CORjwTA2.js → zap-FkXztfRB.js}

@@ -1 +1 @@
-import{W as e}from"./useT-DmcuCJlO.js";var t={name:`message-square`,size:24,node:[[`path`,{d:`M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z`,key:`18887p`}]]};t.node;var n=e(t),r={name:`zap`,size:24,node:[[`path`,{d:`M15.914 4a1.5 1.5 0 00-2.474-1.561l-9 9A1.5 1.5 0 005.5 14h4.002a.5.5 0 01.471.666L8.086 20a1.5 1.5 0 002.475 1.56l9-9A1.5 1.5 0 0018.5 10h-3.997a.5.5 0 01-.472-.667z`,key:`1v7up4`}]]};r.node;var i=e(r);export{n,i as t};
+import{q as e}from"./useT-CtECS-vp.js";var t={name:`message-square`,size:24,node:[[`path`,{d:`M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z`,key:`18887p`}]]};t.node;var n=e(t),r={name:`zap`,size:24,node:[[`path`,{d:`M15.914 4a1.5 1.5 0 00-2.474-1.561l-9 9A1.5 1.5 0 005.5 14h4.002a.5.5 0 01.471.666L8.086 20a1.5 1.5 0 002.475 1.56l9-9A1.5 1.5 0 0018.5 10h-3.997a.5.5 0 01-.472-.667z`,key:`1v7up4`}]]};r.node;var i=e(r);export{n,i as t};

package/dist/index.html

@@ -12,11 +12,11 @@
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-title" content="GAIA" />
     <title>GAIA Agent UI</title>
-  <script type="module" crossorigin src="./assets/index-DBKyXg4y.js"></script>
+  <script type="module" crossorigin src="./assets/index-CsgZhHsw.js"></script>
   <link rel="modulepreload" crossorigin href="./assets/rolldown-runtime-XKyaHtl9.js">
-  <link rel="modulepreload" crossorigin href="./assets/useT-DmcuCJlO.js">
-  <link rel="modulepreload" crossorigin href="./assets/api-BsMIEtSA.js">
-  <link rel="stylesheet" crossorigin href="./assets/index-CNhwlnjv.css">
+  <link rel="modulepreload" crossorigin href="./assets/useT-CtECS-vp.js">
+  <link rel="modulepreload" crossorigin href="./assets/api-D5mTAXjB.js">
+  <link rel="stylesheet" crossorigin href="./assets/index-B7tI0eKR.css">
 </head>
 <body>
     <div id="root"></div>

package/dist/sw.js

@@ -9,7 +9,7 @@
 // never sees a stale UI or stale data.
 
 const CACHE_PREFIX = 'gaia-assets-';
-const CACHE_NAME = CACHE_PREFIX + '0.25.4rc8-9ac42cdd460c7b27';
+const CACHE_NAME = CACHE_PREFIX + '0.25.4-f9c04029eab871f5';
 const ASSETS_PATH = new URL('assets/', self.registration.scope).pathname;
 
 self.addEventListener('install', () => {

package/main.cjs

@@ -85,6 +85,7 @@ const _inSafeMode = _crashCount >= SAFE_MODE_THRESHOLD;
 
 // Services (loaded after app.whenReady)
 const TrayManager = require("./services/tray-manager.cjs");
+const { probeTrayHost } = require("./services/tray-host.cjs");
 const { appIconPath, appUserModelId } = require("./services/app-icon.cjs");
 const {
   attachWindowGuards,
@@ -101,6 +102,7 @@ const KeepAwake = require("./services/keep-awake.cjs");
 const PortManager = require("./services/port-manager.cjs");
 const { isGaiaBackendProcess } = require("./services/backend-orphan.cjs");
 const { showBackendCrashDialog } = require("./services/backend-crash-dialog.cjs");
+const { createBackendSupervisor } = require("./services/backend-supervisor.cjs");
 const { buildIndexQuery, INSTALL_SCREEN_QUERY } = require("./services/index-query.cjs");
 const backendInstaller = require("./services/backend-installer.cjs");
 const { createEngineInstall } = require("./services/engine-install.cjs");
@@ -213,6 +215,8 @@ const APP_NAME = "GAIA";
 // from prior aborted sessions (issue #782 / T5).
 const DEFAULT_BACKEND_PORT = 4200;
 const STARTUP_TIMEOUT = 30000;
+// A restart must answer within this, or it counts as a failed try.
+const RESTART_TIMEOUT = 90000;
 
 // Parse CLI args (T11: --minimized flag for auto-start)
 const startMinimized = process.argv.includes("--minimized");
@@ -243,6 +247,8 @@ let backendProcess = null;
 let backendStarting = null;
 // Set as cleanup() begins; startup stops at its next step once it is.
 let shutdownStarted = false;
+// Set once an update install starts quitting the app.
+let updateQuitStarted = false;
 let backendPort = DEFAULT_BACKEND_PORT;
 let healthCheckUrl = `http://localhost:${backendPort}/api/health`;
 let backendStderrTail = [];
@@ -257,6 +263,8 @@ let engineInstall = null;
 
 /** @type {TrayManager | null} */
 let trayManager = null;
+/** Settles once the tray knows whether this desktop shows tray icons. */
+let trayHostReady = null;
 
 /** @type {AgentProcessManager | null} */
 let agentProcessManager = null;
@@ -278,6 +286,11 @@ const portManager = new PortManager({
  */
 let isQuitting = false;
 
+/** Any quit is under way, an update install's included: start no backend. */
+function quitStarted() {
+  return shutdownStarted || isQuitting || updateQuitStarted;
+}
+
 // ── Backend Process ────────────────────────────────────────────────────────
 
 /**
@@ -386,6 +399,8 @@ async function startBackend() {
       env: {
         ...process.env,
         GAIA_APP_PID: String(process.pid),
+        // Piped stdout is block-buffered: a dying backend's last lines would never arrive.
+        PYTHONUNBUFFERED: "1",
         ...(app.isPackaged && {
           GAIA_BUNDLED_LEMONADE_DIR: path.join(process.resourcesPath, "vendor", "lemonade"),
         }),
@@ -431,17 +446,16 @@ async function startBackend() {
   }
 
   child.on("exit", (code, signal) => {
-    if (code !== 0 && code !== null) {
-      console.error(`Backend exited with code ${code} (signal=${signal})`);
+    // Any exit we didn't ask for leaves the window without a backend, even code 0.
+    const crashed = !isIntentionalKill && !isQuitting;
+    if (crashed) {
+      console.error(`Backend exited with code ${code} (signal=${signal}, pid=${child.pid})`);
     }
-    const crashed = !isIntentionalKill && code !== 0 && code !== null;
-    backendProcess = null;
+    if (backendProcess === child) backendProcess = null;
     if (trayManager && !isQuitting) trayManager.setBackendAlive(false);
 
-    if (crashed && !isQuitting) {
-      // Fire-and-forget — don't block the event loop.
-      void handleBackendCrash(code, signal);
-    }
+    // Once restarts run out, the supervisor's onStopped shows the crash dialog.
+    if (crashed) backendSupervisor.crashed({ code, signal });
 
     // Remove pidfile on exit to avoid leaving stale PID behind.
     try {
@@ -458,12 +472,82 @@ async function startBackend() {
     }
   });
 
+  // "close" waits for stdio to drain, so the tail holds the backend's last words.
+  child.once("close", (code, signal) => {
+    if (isIntentionalKill || isQuitting) return;
+    const tail = backendStderrTail.length ? backendStderrTail.join("\n") : "(nothing on stderr)";
+    console.error(`[main] Backend pid ${child.pid} closed (code=${code}, signal=${signal}). Last stderr lines:\n${tail}`);
+  });
+
   return child;
 }
 
+/**
+ * Start a new backend for the supervisor and resolve once it answers.
+ * Rejects when it exits first or never answers, so the supervisor retries.
+ */
+async function restartBackend() {
+  backendStarting = startBackend();
+  const child = await backendStarting;
+  if (!child) {
+    throw new Error("GAIA's backend program is missing, so it can't restart. Reinstall GAIA.");
+  }
+  if (quitStarted()) {
+    isIntentionalKill = true;
+    await portManager.killBackend(child);
+    throw new Error("GAIA is quitting, so the restarted backend was stopped.");
+  }
+  backendProcess = child;
+  const alive = () => child.exitCode === null && child.signalCode === null;
+  const ready = await waitForBackend(RESTART_TIMEOUT, alive);
+  if (!ready) {
+    if (!alive()) {
+      throw new Error(`The backend exited (code ${child.exitCode}, signal ${child.signalCode}) before it answered.`);
+    }
+    isIntentionalKill = true;
+    await portManager.killBackend(child);
+    throw new Error(`The backend did not answer within ${RESTART_TIMEOUT / 1000} s.`);
+  }
+  console.log(`[main] Backend restarted on port ${backendPort} (pid=${child.pid})`);
+  if (trayManager) {
+    trayManager.setBackendPort(backendPort);
+    trayManager.setBackendAlive(true);
+  }
+  return { port: backendPort };
+}
+
+/** What the renderer needs: the supervisor's state plus the API base to use. */
+function backendStateForRenderer(state) {
+  return { ...state, apiBase: state.port ? buildIndexQuery(state.port).api : null };
+}
+
+const backendSupervisor = createBackendSupervisor({
+  start: restartBackend,
+  onStopped: (state) => {
+    const { code = null, signal = null } = state.lastExit || {};
+    void handleBackendCrash(code, signal);
+  },
+  onState: (state) => {
+    console.log(
+      `[main] Backend ${state.status}` +
+        (state.status === "restarting" ? ` (try ${state.attempt} of ${state.maxRestarts})` : "") +
+        (state.lastError ? `: ${state.lastError}` : "")
+    );
+    if (mainWindow && !mainWindow.isDestroyed()) {
+      mainWindow.webContents.send("backend:state", backendStateForRenderer(state));
+    }
+  },
+});
+
+ipcMain.handle("backend:get-state", () => backendStateForRenderer(backendSupervisor.getState()));
+ipcMain.handle("backend:restart", () => {
+  backendSupervisor.restartNow();
+  return backendStateForRenderer(backendSupervisor.getState());
+});
+
 /**
  * Tell the user the backend stopped and offer Restart / Save diagnostics /
- * Quit. Invoked from child.on("exit") when the kill was NOT initiated by us.
+ * Quit. Invoked by the supervisor's onStopped once automatic restarts run out.
  */
 async function handleBackendCrash(code, signal) {
   autoUpdater.reportStartFailure();
@@ -485,11 +569,11 @@ async function handleBackendCrash(code, signal) {
   }
 }
 
-async function waitForBackend(timeoutMs) {
+async function waitForBackend(timeoutMs, isAlive = () => true) {
   const start = Date.now();
   const http = require("http");
 
-  while (Date.now() - start < timeoutMs) {
+  while (Date.now() - start < timeoutMs && isAlive()) {
     try {
       await new Promise((resolve, reject) => {
         const req = http.get(healthCheckUrl, (res) => {
@@ -666,15 +750,20 @@ function createWindow() {
   // Show window when ready (unless --minimized or startMinimized config)
   mainWindow.once("ready-to-show", () => {
     console.log("[main] ready-to-show fired");
-    const shouldStartMinimized =
-      startMinimized || (trayManager && trayManager.startMinimized);
-
-    if (!shouldStartMinimized) {
-      console.log("[main] mainWindow.show() called");
-      mainWindow.show();
-    } else {
-      console.log("[main] Starting minimized to tray");
-    }
+    Promise.resolve(trayHostReady).then(() => {
+      if (!mainWindow || mainWindow.isDestroyed()) return;
+      // Never start hidden where no tray icon would bring the window back.
+      const canHide = Boolean(trayManager && trayManager.trayHost.available);
+      const shouldStartMinimized =
+        canHide && (startMinimized || trayManager.startMinimized);
+
+      if (!shouldStartMinimized) {
+        console.log("[main] mainWindow.show() called");
+        mainWindow.show();
+      } else {
+        console.log("[main] Starting minimized to tray");
+      }
+    });
   });
 
   return mainWindow;
@@ -782,6 +871,14 @@ function initializeServices() {
     reopenWindow: () => reopenWindow(),
   });
   trayManager.create();
+  trayHostReady = probeTrayHost()
+    .then((host) => {
+      if (trayManager) trayManager.setHost(host);
+    })
+    .catch((err) => {
+      // The host stays unknown, so closing quits instead of hiding.
+      console.error(`[main] Could not record the tray host: ${err.message}`);
+    });
   try {
     trayManager.syncLoginItem();
   } catch (err) {
@@ -1197,6 +1294,7 @@ app.whenReady().then(async () => {
   if (shutdownStarted) return;
   backendStarting = startBackend();
   backendProcess = await backendStarting;
+  if (backendProcess) backendSupervisor.running(backendPort);
   if (shutdownStarted) {
     console.log("[main] Quit during startup — not opening the window");
     return;
@@ -1328,6 +1426,7 @@ const quitGuard = installQuitGuard({
     // Mark any subsequent backend exit as intentional so we don't pop the
     // crash dialog during normal shutdown.
     isIntentionalKill = true;
+    backendSupervisor.stop();
   },
   onError: (err) => {
     console.error("[main] Quit check failed:", err);
@@ -1339,12 +1438,19 @@ const quitGuard = installQuitGuard({
   },
 });
 
+// The installer is already running: a restart now would hold its files open.
+electronAutoUpdater.on("before-quit-for-update", () => {
+  updateQuitStarted = true;
+  backendSupervisor.stop();
+});
+
 quitOnTermSignal({ proc: process, app, guard: quitGuard });
 
 installQuitCleanup({ app, cleanup });
 
 async function cleanup() {
   shutdownStarted = true;
+  backendSupervisor.stop();
   const installStopped = engineInstall ? engineInstall.stop() : null;
 
   // Phase F: tear down auto-updater timers and IPC handlers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/agent-ui",
-  "version": "0.25.4-rc.8",
+  "version": "0.25.4",
   "type": "module",
   "productName": "GAIA Agent UI",
   "description": "Chat with the GAIA agent - local and private by default on AMD Ryzen AI, cloud models when you choose them",

package/preload.cjs

@@ -16,6 +16,7 @@
  *   system:*         — System metrics for the observability dashboard (#2007)
  *   power:*          — Keep the PC awake while a chat turn runs (#5226)
  *   dialog:*         — The OS folder picker
+ *   backend:*        — Backend restarts after a crash (services/backend-supervisor.cjs)
  */
 
 const { contextBridge, ipcRenderer } = require("electron");
@@ -90,6 +91,13 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
   dialog: {
     pickFolder: (defaultPath) => ipcRenderer.invoke("dialog:pick-folder", defaultPath),
   },
+
+  // ── GAIA's backend process: restarts after a crash, and its new port ──
+  backend: {
+    getState: () => ipcRenderer.invoke("backend:get-state"),
+    restart: () => ipcRenderer.invoke("backend:restart"),
+    onState: (cb) => onEvent("backend:state", cb),
+  },
 });
 
 // ── Window frame ─────────────────────────────────────────────────────────

package/services/auto-updater.cjs

@@ -1705,10 +1705,10 @@ function init(mainWindow, options = {}) {
     isBackendPrefetchedRef = options.isBackendPrefetched;
   }
 
-  // Disabled path — short-circuit BEFORE touching any Electron APIs so
-  // this works in plain Node tests where require('electron') returns a
-  // string and the electron-updater singleton throws on access.
+  // Disabled path — short-circuit before electron-updater, whose singleton
+  // throws on access in plain Node tests.
   if (isDisabled()) {
+    _initDisabled();
     setState({ status: STATES.DISABLED });
     log("info", "Auto-updater disabled via GAIA_DISABLE_UPDATE=1");
     return;
@@ -1844,6 +1844,29 @@ function init(mainWindow, options = {}) {
   );
 }
 
+/**
+ * Settings still needs the running version and the disabled status, so record
+ * the one and answer the status request. Plain Node's require("electron") is a
+ * path string, so a missing app or ipcMain leaves the updater as it is.
+ */
+function _initDisabled() {
+  let electron;
+  try {
+    // eslint-disable-next-line global-require
+    electron = require("electron");
+  } catch (err) {
+    log("warn", "Electron unavailable — Settings can't show the running version:", err && err.message);
+    return;
+  }
+  if (!electron || !electron.app || !electron.ipcMain) return;
+  electronApi = { app: electron.app, ipcMain: electron.ipcMain, dialog: electron.dialog, net: electron.net };
+  state.currentVersion = electron.app.getVersion() || null;
+  if (!ipcHandlersRegistered) {
+    electron.ipcMain.handle("gaia:update:get-status", () => getState());
+    ipcHandlersRegistered = true;
+  }
+}
+
 function _onBeforeQuit(event) {
   _refreshPreferences();
   if (state.status !== STATES.DOWNLOADED || !autoUpdaterRef || !autoUpdaterRef.autoInstallOnAppQuit) {

package/services/backend-supervisor.cjs

@@ -0,0 +1,150 @@
+// Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Restarts GAIA's backend when it exits on its own: after a growing wait,
+ * at most `maxRestarts` times in `windowMs`, then it stops and waits for the
+ * user's Restart GAIA (restartNow). No Electron imports, so it unit-tests.
+ *
+ * State, as sent to the renderer:
+ *   status        "running" | "restarting" | "stopped"
+ *   port          the backend's port once running
+ *   since         when this outage began (ms epoch), for the banner's timer
+ *   attempt       which try this outage is on
+ *   nextAttemptAt when the next try starts, or null while one is starting
+ *   lastExit      { code, signal } of the last exit
+ *   lastError     why the last start failed, if it did
+ */
+
+"use strict";
+
+const DEFAULTS = Object.freeze({
+  maxRestarts: 3,
+  windowMs: 10 * 60_000,
+  backoffMs: [1000, 5000, 15000],
+});
+
+/**
+ * @param {object} deps
+ * @param {() => Promise<{port: number}>} deps.start spawns the backend and resolves once it answers
+ * @param {(state: object) => void} deps.onState called with every new state
+ * @param {(state: object) => void} [deps.onStopped] called once each time restarts run out
+ */
+function createBackendSupervisor({
+  start,
+  onState,
+  onStopped = () => {},
+  maxRestarts = DEFAULTS.maxRestarts,
+  windowMs = DEFAULTS.windowMs,
+  backoffMs = DEFAULTS.backoffMs,
+  now = Date.now,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+}) {
+  if (!Number.isInteger(maxRestarts) || maxRestarts < 1) {
+    throw new Error(`backend supervisor: maxRestarts must be a positive integer, got ${maxRestarts}`);
+  }
+  if (!Array.isArray(backoffMs) || backoffMs.length === 0) {
+    throw new Error("backend supervisor: backoffMs must list at least one delay");
+  }
+
+  // Automatic restarts in the window; a user's Restart GAIA isn't counted.
+  let history = [];
+  let timer = null;
+  let starting = false;
+  let stopped = false;
+  let state = { status: "running", port: null, since: null, attempt: 0, nextAttemptAt: null, lastExit: null, lastError: null };
+
+  function emit(next) {
+    state = { ...state, ...next, maxRestarts };
+    onState({ ...state });
+  }
+
+  function attemptStart() {
+    timer = null;
+    starting = true;
+    emit({ nextAttemptAt: null });
+    let started;
+    try {
+      started = Promise.resolve(start());
+    } catch (err) {
+      started = Promise.reject(err);
+    }
+    started.then(
+        ({ port }) => {
+          starting = false;
+          if (stopped) return;
+          emit({ status: "running", port, since: null, attempt: 0, lastError: null });
+        },
+        (err) => {
+          starting = false;
+          if (stopped) return;
+          schedule({ lastError: err && err.message ? err.message : String(err) });
+        }
+      );
+  }
+
+  function schedule(extra) {
+    const t = now();
+    history = history.filter((at) => t - at < windowMs);
+    const outage = state.status === "running" ? { since: t, attempt: 0 } : {};
+    if (history.length >= maxRestarts) {
+      const wasStopped = state.status === "stopped";
+      emit({ status: "stopped", nextAttemptAt: null, ...outage, ...extra });
+      if (!wasStopped) onStopped({ ...state });
+      return "stopped";
+    }
+    const delay = backoffMs[Math.min(history.length, backoffMs.length - 1)];
+    history.push(t + delay);
+    const attempt = (outage.attempt ?? state.attempt) + 1;
+    emit({ ...outage, status: "restarting", attempt, nextAttemptAt: t + delay, ...extra });
+    timer = setTimer(attemptStart, delay);
+    return "restarting";
+  }
+
+  return {
+    /** The backend is up on `port` (the first start, outside the supervisor). */
+    running(port) {
+      emit({ status: "running", port, since: null, attempt: 0, nextAttemptAt: null, lastError: null });
+    },
+
+    /** The backend exited on its own. Returns what happens next. */
+    crashed({ code = null, signal = null } = {}) {
+      if (stopped) return "stopped";
+      // An exit during a start is that start's failure, reported by start() itself;
+      // keep its exit so the crash dialog names the latest one.
+      if (starting) {
+        state = { ...state, lastExit: { code, signal } };
+        return state.status;
+      }
+      if (timer) return state.status;
+      return schedule({ lastExit: { code, signal } });
+    },
+
+    /** The user's Restart GAIA: start now, with a fresh budget. */
+    restartNow() {
+      if (stopped || starting) return;
+      if (timer) {
+        clearTimer(timer);
+        timer = null;
+      }
+      history = [];
+      if (state.status === "running") return;
+      emit({ status: "restarting", attempt: 1 });
+      attemptStart();
+    },
+
+    /** GAIA is quitting: no more restarts. */
+    stop() {
+      stopped = true;
+      if (timer) clearTimer(timer);
+      timer = null;
+    },
+
+    getState() {
+      return { ...state, maxRestarts };
+    },
+  };
+}
+
+module.exports = { createBackendSupervisor, DEFAULTS };

package/services/port-manager.cjs

@@ -111,6 +111,9 @@ async function writeDiagnosticsBundle(destPath, logger) {
     "gaia.log",
     "electron-main.log",
     "electron-install-state.json",
+    // Fatal-crash stacks from the backend (src/gaia/ui/fault_log.py), and its rotated copy.
+    "logs/backend-faults.log",
+    "logs/backend-faults.log.1",
   ];
 
   const present = candidates.filter((rel) =>

package/services/quit-guard.cjs

@@ -242,6 +242,7 @@ function attachWindowGuards(win, { app, guard, getTray, isQuitting, platform, re
  *
  * @param {{proc: NodeJS.Process, app: Electron.App,
  *   guard: ReturnType<typeof installQuitGuard>, logger?: {log: Function}}} deps
+ * @returns {Promise<void>} Settles once the handler is back on top of Electron's.
  */
 function quitOnTermSignal({ proc, app, guard, logger = console }) {
   proc.on("SIGTERM", () => {
@@ -249,6 +250,14 @@ function quitOnTermSignal({ proc, app, guard, logger = console }) {
     guard.allow();
     app.quit();
   });
+  // Electron installs its own SIGTERM handler after the main script runs, and
+  // it replaces Node's, so the listener above never fires. Re-adding every
+  // listener once ready makes Node install its handler again, over Electron's.
+  return app.whenReady().then(() => {
+    const listeners = proc.listeners("SIGTERM");
+    proc.removeAllListeners("SIGTERM");
+    for (const listener of listeners) proc.on("SIGTERM", listener);
+  });
 }
 
 module.exports = {

package/services/tray-host.cjs

@@ -0,0 +1,84 @@
+// Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Whether this desktop can show GAIA's tray icon at all.
+ *
+ * Windows and macOS always can. On Linux, Electron's tray is a
+ * StatusNotifierItem, which shows only when a host owns the
+ * `org.kde.StatusNotifierWatcher` name on the session bus. Stock GNOME has
+ * none (its AppIndicator extension adds one), so hiding the window there
+ * leaves GAIA running with no way back to it.
+ */
+
+const { execFile } = require("child_process");
+
+const WATCHER = "org.kde.StatusNotifierWatcher";
+const PROBE_TIMEOUT_MS = 2000;
+
+/** The two bus clients a Linux desktop ships, and how each reports NameHasOwner. */
+const PROBES = [
+  {
+    cmd: "gdbus",
+    args: [
+      "call", "--session",
+      "--dest", "org.freedesktop.DBus",
+      "--object-path", "/org/freedesktop/DBus",
+      "--method", "org.freedesktop.DBus.NameHasOwner", WATCHER,
+    ],
+    parse: (out) => /\(\s*true\s*,?\s*\)/.test(out) ? true : /\(\s*false\s*,?\s*\)/.test(out) ? false : null,
+  },
+  {
+    cmd: "dbus-send",
+    args: [
+      "--session", "--print-reply", "--dest=org.freedesktop.DBus",
+      "/org/freedesktop/DBus", "org.freedesktop.DBus.NameHasOwner", `string:${WATCHER}`,
+    ],
+    parse: (out) => /boolean\s+true/.test(out) ? true : /boolean\s+false/.test(out) ? false : null,
+  },
+];
+
+function runCommand(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: PROBE_TIMEOUT_MS, encoding: "utf8" }, (err, stdout, stderr) => {
+      if (err) {
+        err.stderr = stderr;
+        reject(err);
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+/**
+ * @typedef {{available: boolean, reason: null | "no-host" | "check-failed", detail?: string}} TrayHost
+ * `no-host`: the bus answered and nothing hosts tray icons.
+ * `check-failed`: the bus couldn't be asked; treated as no tray, so closing never strands the app.
+ */
+
+/**
+ * @param {{platform?: string, run?: (cmd: string, args: string[]) => Promise<string>}} [deps]
+ * @returns {Promise<TrayHost>}
+ */
+async function probeTrayHost({ platform = process.platform, run = runCommand } = {}) {
+  if (platform !== "linux") return { available: true, reason: null };
+  const failures = [];
+  for (const probe of PROBES) {
+    let out;
+    try {
+      out = await run(probe.cmd, probe.args);
+    } catch (err) {
+      const why = err.code === "ENOENT" ? "not installed" : (err.stderr || err.message || String(err)).trim();
+      failures.push(`${probe.cmd}: ${why}`);
+      continue;
+    }
+    const owned = probe.parse(out);
+    if (owned === true) return { available: true, reason: null };
+    if (owned === false) return { available: false, reason: "no-host", detail: `nothing owns ${WATCHER}` };
+    failures.push(`${probe.cmd}: unexpected reply ${JSON.stringify(out.trim())}`);
+  }
+  return { available: false, reason: "check-failed", detail: failures.join("; ") };
+}
+
+module.exports = { probeTrayHost, WATCHER, PROBE_TIMEOUT_MS };