@amd-gaia/agent-ui 0.25.0 → 0.25.1-rc.10

package/services/agent-process-manager.cjs

@@ -26,6 +26,12 @@ const path = require("path");
 const fs = require("fs");
 const os = require("os");
 const { EventEmitter } = require("events");
+const {
+  killProcessTree,
+  listDescendants,
+  listTimeoutMs,
+  worstCaseKillMs,
+} = require("./process-tree.cjs");
 
 // ── Constants ────────────────────────────────────────────────────────────
 
@@ -38,6 +44,9 @@ const MANIFEST_FILENAME = "agent-manifest.json";
 /** Graceful shutdown timeout before force kill (ms) */
 const SHUTDOWN_TIMEOUT = 5000;
 
+/** After the graceful shutdown, how long the tree gets between SIGTERM and SIGKILL (ms) */
+const TREE_KILL_GRACE = 2000;
+
 /** Health check interval (ms) — uses MCP "ping", not "initialize" */
 const HEALTH_CHECK_INTERVAL = 30000;
 
@@ -82,6 +91,7 @@ class AgentProcessManager extends EventEmitter {
    *   handlers proxy to that backend's `/api/agents/*` routes (the real install
    *   runtime), so without a resolver those handlers fail loudly rather than
    *   duplicating download/verify/uv logic in the main process (issue #1721).
+   *   killTree / listDescendants replace the process-tree helpers (tests).
    */
   constructor(mainWindow, options = {}) {
     super();
@@ -110,6 +120,12 @@ class AgentProcessManager extends EventEmitter {
      */
     this.processes = {};
 
+    this._killTree = options.killTree || killProcessTree;
+    this._listDescendants = options.listDescendants || listDescendants;
+
+    /** Set by stopAll(): GAIA is quitting, so nothing may start another agent. */
+    this._shuttingDown = false;
+
     /** Crash timestamps per agent for rate-limiting restart attempts */
     this._crashTimes = {};
 
@@ -130,6 +146,11 @@ class AgentProcessManager extends EventEmitter {
    * @returns {Promise<{ pid: number }>}
    */
   async startAgent(agentId) {
+    if (this._shuttingDown) {
+      throw new Error(
+        `Not starting agent "${agentId}": GAIA is quitting and has already stopped its agents.`
+      );
+    }
     if (this.processes[agentId]) {
       console.log(`[agent-mgr] Agent ${agentId} is already running (PID ${this.processes[agentId].process.pid})`);
       return { pid: this.processes[agentId].process.pid };
@@ -166,10 +187,18 @@ class AgentProcessManager extends EventEmitter {
       pendingRpc: {},
       healthTimer: null,
       stopping: false, // Set to true during intentional shutdown to suppress crash recovery
+      stopPromise: null, // The running stopAgent(), shared by duplicate calls
+      stdinError: null, // The error that broke stdin; nothing more can be written once set
     };
 
     this.processes[agentId] = entry;
 
+    // A write to a child that has died fails later, as an 'error' on the
+    // stream; without a listener that EPIPE crashes the whole app (#3498).
+    child.stdin.on("error", (err) => {
+      this._handleStdinError(agentId, child, err);
+    });
+
     // ── stdout: JSON-RPC message stream ──
     child.stdout.on("data", (data) => {
       this._handleStdout(agentId, data);
@@ -207,6 +236,7 @@ class AgentProcessManager extends EventEmitter {
   /**
    * Stop an agent gracefully using JSON-RPC shutdown protocol.
    * Cross-platform (works on Windows where SIGTERM = TerminateProcess).
+   * A second call while the first runs waits for that same stop.
    * @param {string} agentId
    * @returns {Promise<void>}
    */
@@ -217,23 +247,40 @@ class AgentProcessManager extends EventEmitter {
       return;
     }
 
-    // Guard against concurrent stopAgent() calls for the same agent
-    if (entry.stopping) {
-      console.log(`[agent-mgr] Agent ${agentId} is already being stopped — skipping duplicate`);
-      return;
+    if (entry.stopPromise) {
+      console.log(`[agent-mgr] Agent ${agentId} is already being stopped — waiting for that stop`);
+      return entry.stopPromise;
     }
 
     console.log(`[agent-mgr] Stopping agent ${agentId} (PID ${entry.process.pid})...`);
 
     // Mark as intentionally stopping — suppresses crash recovery in _handleProcessExit
     entry.stopping = true;
+    entry.stopPromise = this._stopAgent(agentId, entry);
+    return entry.stopPromise;
+  }
 
+  async _stopAgent(agentId, entry) {
     // Clear health check timer
     if (entry.healthTimer) {
       clearInterval(entry.healthTimer);
       entry.healthTimer = null;
     }
 
+    // Read the tree while the agent is alive: once it exits, its children
+    // are re-parented on Linux and macOS and can no longer be found from it.
+    let knownDescendants = [];
+    if (entry.process.exitCode === null && entry.process.signalCode === null) {
+      try {
+        ({ descendants: knownDescendants } = await this._listDescendants(entry.process.pid));
+      } catch (err) {
+        console.error(
+          `[agent-mgr] Could not list the processes agent ${agentId} started (${err.message}); ` +
+            "any it leaves behind will keep running."
+        );
+      }
+    }
+
     // Step 1: Send JSON-RPC shutdown request via stdin
     try {
       this._sendJsonRpcRaw(agentId, "shutdown", {});
@@ -247,17 +294,17 @@ class AgentProcessManager extends EventEmitter {
     // Step 2: Wait up to SHUTDOWN_TIMEOUT for clean exit
     const exited = await this._waitForExit(agentId, SHUTDOWN_TIMEOUT);
 
-    // Step 3: Force kill if still running
-    if (!exited && this.processes[agentId]) {
+    // Step 3: Stop the agent if it ignored the request, and anything it started either way.
+    if (!exited) {
       console.warn(
         `[agent-mgr] Agent ${agentId} did not exit within ${SHUTDOWN_TIMEOUT}ms, force killing...`
       );
-      try {
-        entry.process.kill(); // SIGKILL on Unix, TerminateProcess on Windows
-      } catch {
-        // Already dead
-      }
     }
+    await this._killTree(entry.process, {
+      knownDescendants,
+      graceMs: TREE_KILL_GRACE,
+      label: `agent ${agentId}`,
+    });
 
     // Note: _handleProcessExit may have already cleaned up if the process exited.
     // _cleanupProcess is idempotent, so calling it again is safe.
@@ -626,7 +673,13 @@ class AgentProcessManager extends EventEmitter {
 
       entry.pendingRpc[id] = { resolve, reject, timer };
 
-      this._sendJsonRpcRaw(agentId, method, params, id);
+      try {
+        this._sendJsonRpcRaw(agentId, method, params, id);
+      } catch (err) {
+        clearTimeout(timer);
+        delete entry.pendingRpc[id];
+        reject(err);
+      }
     });
   }
 
@@ -639,6 +692,7 @@ class AgentProcessManager extends EventEmitter {
     const agentConfigs = this.config.agents || {};
 
     for (const [agentId, agentCfg] of Object.entries(agentConfigs)) {
+      if (this._shuttingDown) return;
       if (agentCfg.autoStart && !this.processes[agentId]) {
         try {
           await this.startAgent(agentId);
@@ -656,13 +710,16 @@ class AgentProcessManager extends EventEmitter {
   }
 
   /**
-   * Stop all running agents gracefully.
+   * Stop all running agents gracefully. For quitting only: afterwards no
+   * agent can be started, so a pending auto-start or crash restart can't
+   * spawn one the app will never stop.
    */
   async stopAll() {
     const agentIds = Object.keys(this.processes);
     console.log(
       `[agent-mgr] Stopping all agents: ${agentIds.join(", ") || "(none)"}`
     );
+    this._shuttingDown = true;
     await Promise.all(agentIds.map((id) => this.stopAgent(id)));
   }
 
@@ -832,6 +889,7 @@ class AgentProcessManager extends EventEmitter {
     );
 
     setTimeout(async () => {
+      if (this._shuttingDown) return;
       try {
         await this.startAgent(agentId);
         console.log(`[agent-mgr] Agent ${agentId} restarted after crash`);
@@ -858,6 +916,11 @@ class AgentProcessManager extends EventEmitter {
     if (!entry || !entry.process.stdin || entry.process.stdin.destroyed) {
       throw new Error(`Cannot write to stdin of agent "${agentId}"`);
     }
+    if (entry.stdinError) {
+      throw new Error(
+        `Cannot write to stdin of agent "${agentId}": the pipe broke earlier (${entry.stdinError.message})`
+      );
+    }
 
     const msg = {
       jsonrpc: "2.0",
@@ -870,6 +933,36 @@ class AgentProcessManager extends EventEmitter {
     entry.process.stdin.write(payload);
   }
 
+  /**
+   * The agent's stdin failed — almost always EPIPE because the process is
+   * gone. Fail its pending calls now instead of letting them time out, and
+   * make sure the death is reported: a child that only closed its stdin is
+   * unusable, so it is stopped and its exit goes through the crash path.
+   */
+  _handleStdinError(agentId, child, err) {
+    const entry = this.processes[agentId];
+    const current = entry && entry.process === child ? entry : null;
+    const exited = child.exitCode !== null || child.signalCode !== null;
+    console.error(
+      `[agent-mgr] stdin of agent ${agentId} (PID ${child.pid}) failed: ${err.code || "error"} ${err.message}` +
+        (exited ? " — the agent had already exited" : "")
+    );
+    if (!current) return;
+    current.stdinError = err;
+
+    for (const [rpcId, pending] of Object.entries(current.pendingRpc)) {
+      clearTimeout(pending.timer);
+      delete current.pendingRpc[rpcId];
+      pending.reject(new Error(`Agent "${agentId}" stopped reading its input (${err.code || err.message})`));
+    }
+
+    if (exited || current.stopping) return;
+    console.error(`[agent-mgr] Agent ${agentId} can no longer receive requests — stopping it`);
+    this._killTree(child, { graceMs: TREE_KILL_GRACE, label: `agent ${agentId}` }).catch((killErr) => {
+      console.error(`[agent-mgr] Could not stop agent ${agentId} after its stdin broke: ${killErr.message}`);
+    });
+  }
+
   // ── Private: Health check ────────────────────────────────────────────
 
   async _healthCheck(agentId) {
@@ -1096,4 +1189,14 @@ class AgentProcessManager extends EventEmitter {
   }
 }
 
+/**
+ * Longest stopAgent can take on `platform` (ms): the tree read while the
+ * agent is alive, its shutdown wait, then killProcessTree. The quit's
+ * cleanup deadline must cover it.
+ */
+AgentProcessManager.worstCaseStopMs = (platform = process.platform) =>
+  listTimeoutMs(platform) +
+  SHUTDOWN_TIMEOUT +
+  worstCaseKillMs({ platform, graceMs: TREE_KILL_GRACE });
+
 module.exports = AgentProcessManager;

package/services/app-icon.cjs

@@ -0,0 +1,29 @@
+// Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+const path = require("path");
+
+/**
+ * The GAIA window icon. Every BrowserWindow must pass it: a source build runs
+ * as electron.exe, so a window without one shows Electron's logo.
+ *
+ * @param {string} [platform] Defaults to process.platform.
+ * @returns {string} Absolute path to the icon asset.
+ */
+function appIconPath(platform = process.platform) {
+  return path.join(__dirname, "..", "assets", platform === "win32" ? "icon.ico" : "icon.png");
+}
+
+/**
+ * The Windows AppUserModelID. Without one, the taskbar groups GAIA with every
+ * other window of the same electron.exe and shows Electron's icon. Packaged
+ * builds match the installer's shortcut (`appId` in electron-builder.yml).
+ *
+ * @param {boolean} isPackaged app.isPackaged
+ * @returns {string}
+ */
+function appUserModelId(isPackaged) {
+  return isPackaged ? "ai.amd.gaia" : "ai.amd.gaia.dev";
+}
+
+module.exports = { appIconPath, appUserModelId };

package/services/auto-updater.cjs

@@ -106,6 +106,8 @@ const state = {
 };
 
 let mainWindowRef = null;
+/** Asks before an update restart would cut off running work (set by init). */
+let confirmRestartRef = null;
 let checkInProgress = false;
 let scheduledTimeout = null;
 let initialCheckTimeout = null;
@@ -616,13 +618,25 @@ function wireAutoUpdaterEvents() {
         }
       );
       if (choice && choice.response === 0) {
+        // quitAndInstall starts the installer at once, so ask about running
+        // work here; the quit that follows doesn't ask again.
+        if (!(await confirmRestartRef())) {
+          log("info", "Restart put off: work is still running — will install on next quit");
+          return;
+        }
         log("info", "User chose to restart — calling quitAndInstall");
         autoUpdaterRef.quitAndInstall(false, true);
       } else {
         log("info", "User deferred restart — will install on next quit");
       }
     } catch (err) {
-      log("error", "Failed to show restart dialog:", err && err.message);
+      const message = (err && err.message) || String(err);
+      log("error", "Failed to show restart dialog:", message);
+      electronApi.dialog.showErrorBox(
+        "GAIA update",
+        `GAIA couldn't finish asking about the update restart: ${message}\n\n` +
+          "The update installs the next time you quit GAIA."
+      );
     }
   });
 
@@ -689,9 +703,19 @@ function unregisterIpcHandlers() {
  * continues, and this function itself never throws.
  *
  * @param {Electron.BrowserWindow | null} mainWindow
+ * @param {object} options
+ * @param {() => Promise<boolean>} options.confirmRestart - Whether "Restart now"
+ *   may go ahead; asked before the installer starts. Required: without it an
+ *   update restart would silently cut off a running answer.
  */
-function init(mainWindow) {
+function init(mainWindow, options = {}) {
+  if (typeof options.confirmRestart !== "function") {
+    throw new TypeError(
+      "auto-updater init needs options.confirmRestart, so Restart now can ask before it stops running work"
+    );
+  }
   mainWindowRef = mainWindow || null;
+  confirmRestartRef = options.confirmRestart;
 
   // Disabled path — short-circuit BEFORE touching any Electron APIs so
   // this works in plain Node tests where require('electron') returns a

package/services/backend-crash-dialog.cjs

@@ -0,0 +1,102 @@
+// Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * The dialog shown when GAIA's backend exits on its own. Every choice ends
+ * somewhere: Restart relaunches the app, Quit quits it, and Save diagnostics
+ * writes the bundle and comes back to the same choice.
+ */
+
+const RESTART = 0;
+const SAVE_DIAGNOSTICS = 1;
+const QUIT = 2;
+
+// Colour codes the backend's logger writes; a dialog shows them as junk.
+const ANSI_ESCAPE = /\u001b\[[0-9;]*[A-Za-z]/g;
+
+function stripAnsi(text) {
+  return String(text).replace(ANSI_ESCAPE, "");
+}
+
+/** The dialog's detail text: what happened, what to do, then the log tail. */
+function crashDetail(code, signal, tailLines) {
+  const how = signal ? `signal ${signal}` : `exit code ${code}`;
+  const tail = (tailLines || []).map(stripAnsi).join("\n") || "(nothing was logged)";
+  return (
+    `GAIA's background service stopped unexpectedly (${how}). Your chats are saved.\n` +
+    "Restart GAIA to continue. If it keeps happening, save diagnostics and attach " +
+    "them to a bug report.\n\n" +
+    `Last log lines:\n${tail}`
+  );
+}
+
+/**
+ * An AppImage runs from a mount that goes away when the app exits, so a
+ * relaunch must start the AppImage file itself, not process.execPath.
+ */
+function relaunchOptions(env = process.env, argv = process.argv) {
+  return env.APPIMAGE ? { execPath: env.APPIMAGE, args: argv.slice(1) } : undefined;
+}
+
+/**
+ * Show the crash dialog until the user restarts or quits.
+ *
+ * @param {object} deps
+ * @param {object} deps.dialog Electron's dialog module
+ * @param {object} deps.app Electron's app module
+ * @param {() => Promise<string>} deps.writeDiagnostics resolves to the bundle path
+ * @param {() => void} deps.beforeQuit called before app.quit(), e.g. to skip the quit guard
+ * @param {object} [deps.env] where an AppImage's own path is read from
+ * @param {object} [deps.parent] window the dialog is modal to, e.g. mainWindow
+ * @returns {Promise<"restart"|"quit">}
+ */
+async function showBackendCrashDialog({ dialog, app, code, signal, tailLines, writeDiagnostics, beforeQuit, env = process.env, parent }) {
+  const detail = crashDetail(code, signal, tailLines);
+  // Modal to GAIA's window and in front: unparented, it can open behind other apps.
+  const owner = parent && !parent.isDestroyed() ? parent : null;
+  if (owner) {
+    if (owner.isMinimized()) owner.restore();
+    owner.show();
+    owner.focus();
+  }
+  const show = (box) => (owner && !owner.isDestroyed() ? dialog.showMessageBox(owner, box) : dialog.showMessageBox(box));
+  for (;;) {
+    const { response } = await show({
+      type: "error",
+      title: "GAIA stopped",
+      message: "GAIA's background service stopped",
+      detail,
+      buttons: ["Restart GAIA", "Save diagnostics", "Quit"],
+      defaultId: RESTART,
+      cancelId: QUIT,
+      noLink: true,
+    });
+
+    if (response === SAVE_DIAGNOSTICS) {
+      try {
+        const bundlePath = await writeDiagnostics();
+        await show({
+          type: "info",
+          title: "Diagnostics saved",
+          message: "Diagnostics saved",
+          detail: `Attach this file to your bug report:\n${bundlePath}`,
+          buttons: ["OK"],
+        });
+      } catch (err) {
+        dialog.showErrorBox(
+          "Could not save diagnostics",
+          `Writing the diagnostics bundle failed: ${err.message}`
+        );
+      }
+      continue;
+    }
+
+    const choice = response === RESTART ? "restart" : "quit";
+    if (choice === "restart") app.relaunch(relaunchOptions(env));
+    if (beforeQuit) beforeQuit();
+    app.quit();
+    return choice;
+  }
+}
+
+module.exports = { showBackendCrashDialog, crashDetail, stripAnsi, relaunchOptions };

package/services/backend-installer-progress-dialog.cjs

@@ -29,6 +29,7 @@ const path = require("path");
 const { BrowserWindow, dialog, ipcMain, shell, clipboard } = require("electron");
 
 const installer = require("./backend-installer.cjs");
+const { appIconPath } = require("./app-icon.cjs");
 
 // IPC channels. Keep these in sync with preload.cjs.
 const IPC_PROGRESS_EVENT = "install:progress";
@@ -72,14 +73,45 @@ function registerIpcHandlers() {
   });
 }
 
+// ── Stage labels ────────────────────────────────────────────────────────────
+
+// Keyed by installer.STAGES values; the ids themselves stay in the install log.
+const STAGE_LABELS = Object.freeze({
+  "pre-checks": "Checking your PC",
+  "ensure-uv": "Getting the installer ready",
+  "create-venv": "Preparing GAIA's workspace",
+  "install-package": "Installing GAIA",
+  "gaia-init": "Getting the AI model ready",
+  verify: "Finishing up",
+});
+const NEUTRAL_STAGE_LABEL = "Setting up GAIA";
+
+const unlabeledStages = new Set();
+
+/** What the window shows for an installer stage id. */
+function stageLabel(stage) {
+  if (Object.prototype.hasOwnProperty.call(STAGE_LABELS, stage)) return STAGE_LABELS[stage];
+  if (stage && !unlabeledStages.has(stage)) {
+    unlabeledStages.add(stage);
+    installer.log(
+      `Warning: install stage "${stage}" has no label; the window shows "${NEUTRAL_STAGE_LABEL}"`
+    );
+  }
+  return NEUTRAL_STAGE_LABEL;
+}
+
 // ── Embedded HTML ───────────────────────────────────────────────────────────
 
+function escapeHtml(text) {
+  return String(text).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 /**
  * HTML payload for the progress window. Rendered via `loadURL('data:...')`.
  * The script uses `window.gaiaInstall` exposed by preload.cjs.
  */
 function buildProgressHtml({ logPath }) {
-  const escapedLog = String(logPath || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  const escapedLog = escapeHtml(logPath || "");
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -90,13 +122,13 @@ function buildProgressHtml({ logPath }) {
    * src/styles/index.css, so the dark theme's role values are mirrored
    * here. Keep them in step with that file; nothing below names a hex. */
   :root {
-    --bg-primary: #17161C;
-    --bg-tertiary: #2A2831;
-    --border: #3A3842;
-    --text-primary: #F0EDE7;
-    --text-secondary: #AAA5B0;
-    --text-muted: #8C8794;
-    --accent-fill: #9A4930;
+    --bg-primary: #1A1917;
+    --bg-tertiary: #2C2B27;
+    --border: #4A4740;
+    --text-primary: #EFECE6;
+    --text-secondary: #B3ADA5;
+    --text-muted: #958F87;
+    --accent-solid: #D4B47E;
   }
   html, body {
     margin: 0;
@@ -132,8 +164,6 @@ function buildProgressHtml({ logPath }) {
   .stage {
     font-size: 12px;
     color: var(--text-secondary);
-    text-transform: uppercase;
-    letter-spacing: 0.5px;
     margin-bottom: 6px;
     min-height: 15px;
   }
@@ -152,7 +182,7 @@ function buildProgressHtml({ logPath }) {
   }
   .fill {
     height: 100%;
-    background: var(--accent-fill);
+    background: var(--accent-solid);
     border-radius: 9999px;
     transition: width 300ms ease-out;
     width: 0%;
@@ -201,11 +231,11 @@ function buildProgressHtml({ logPath }) {
 </head>
 <body>
   <h1>Setting up GAIA</h1>
-  <p class="subtitle">First-launch backend install — this can take a few minutes</p>
+  <p class="subtitle">First-time setup — this can take a few minutes</p>
   <div class="stage" id="stage">Starting…</div>
   <div class="bar"><div class="fill indeterminate" id="fill"></div></div>
   <div class="percent" id="percent"></div>
-  <div class="message" id="message">Running pre-flight checks…</div>
+  <div class="message" id="message">Checking your PC…</div>
   <div class="footer">Log: <code>${escapedLog}</code></div>
 <script>
   (function() {
@@ -216,7 +246,7 @@ function buildProgressHtml({ logPath }) {
 
     function onProgress(payload) {
       if (!payload) return;
-      const stage = payload.stage || '';
+      const stage = payload.label || '';
       const percent = typeof payload.percent === 'number' ? payload.percent : null;
       const message = payload.message || '';
 
@@ -268,8 +298,9 @@ function createProgressWindow() {
     frame: false,
     transparent: false,
     show: false,
-    backgroundColor: "#17161C", // --bg-primary, dark theme (see the :root block above)
+    backgroundColor: "#1A1917", // --bg-primary, dark theme (see the :root block above)
     title: "Installing GAIA",
+    icon: appIconPath(),
     webPreferences: {
       nodeIntegration: false,
       contextIsolation: true,
@@ -305,7 +336,7 @@ function createProgressWindow() {
   });
 
   const onProgress = (stage, percent, message) => {
-    lastProgress = { stage, percent, message };
+    lastProgress = { stage, label: stageLabel(stage), percent, message };
     if (window.isDestroyed()) return;
     if (!rendererReady) return; // will be replayed on did-finish-load
     try {
@@ -364,21 +395,19 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
     .filter(Boolean)
     .join("\n");
 
-  // Loop so that certain actions (Copy/Open log) return control to the
-  // same dialog rather than exiting the flow. The dialog includes a
-  // one-click "Install uv" action which attempts the packaged rescue
-  // installer and then returns 'retry' on success so the caller can
-  // re-run the full backend install.
-  const buttons = [
-    "Install uv (auto)",
-    "Retry",
-    "Manual install instructions",
-    "Copy log path",
-    "Open log file",
-    "Quit",
+  // Copy/Open log return to the same dialog. "Install uv" is offered only
+  // when uv is what failed; for any other stage it would just repeat Retry.
+  const uvFailed = stage === "ensure-uv";
+  const actions = [
+    ...(uvFailed ? [["install-uv", "Install uv (auto)"]] : []),
+    ["retry", "Retry"],
+    ["manual", "Manual install instructions"],
+    ["copy-log", "Copy log path"],
+    ["open-log", "Open log file"],
+    ["quit", "Quit"],
   ];
+  const buttons = actions.map(([, label]) => label);
 
-  // Helper to show the dialog and handle the response.
   const show = async () => {
     const result = await dialog.showMessageBox(parentWindow || null, {
       type: "error",
@@ -391,15 +420,12 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
       noLink: true,
     });
 
-    switch (result.response) {
-      case 0: {
-        // Run the full packaged install flow (ensureBackend) so the user
-        // gets a single-click recovery that attempts the entire backend
-        // install rather than only uv provisioning. Show progress UI
-        // while the operation runs. On success, tell the caller to retry
-        // (which will detect READY and proceed); on failure, re-show the
-        // dialog with augmented details.
-        const { window, onProgress, close } = createProgressWindow();
+    const action = (actions[result.response] || ["quit"])[0];
+    switch (action) {
+      case "install-uv": {
+        // Run the full packaged install (ensureBackend), with progress, so one
+        // click retries everything, not only uv; re-show with the new error.
+        const { onProgress, close } = createProgressWindow();
         try {
           await installer.ensureBackend({ onProgress, isPackaged: true });
           try { close(); } catch {}
@@ -414,9 +440,9 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
           return showFailureDialog(parentWindow, nextInfo);
         }
       }
-      case 1:
+      case "retry":
         return "retry";
-      case 2: {
+      case "manual": {
         try {
           await shell.openExternal("https://amd-gaia.ai/docs/quickstart#cli-install");
         } catch {
@@ -424,7 +450,7 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
         }
         return "manual";
       }
-      case 3: {
+      case "copy-log": {
         try {
           clipboard.writeText(logPath);
         } catch {
@@ -432,7 +458,7 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
         }
         return showFailureDialog(parentWindow, errorInfo);
       }
-      case 4: {
+      case "open-log": {
         try {
           await shell.openPath(logPath);
         } catch {
@@ -440,7 +466,6 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
         }
         return showFailureDialog(parentWindow, errorInfo);
       }
-      case 5:
       default:
         return "quit";
     }
@@ -472,6 +497,9 @@ async function showPreCheckFailureDialog(parentWindow, { title, message, detail
 
 module.exports = {
   createProgressWindow,
+  buildProgressHtml,
+  stageLabel,
+  STAGE_LABELS,
   showFailureDialog,
   showPreCheckFailureDialog,
   // IPC channel names for preload.cjs