@amd-gaia/agent-ui 0.25.3 → 0.25.4-rc.10

package/main.cjs

@@ -47,11 +47,18 @@ const _MAIN_LOG_PATH = path.join(_GAIA_DIR, "electron-main.log");
 // very handler we are trying to install, falling through to Electron's bare
 // JS-error dialog.
 let installSafetyNet, installLogTee, _fatalHandler;
+let readCount, runSafeModePrompt, SAFE_MODE_THRESHOLD;
 // Set when a fatal error quits the app: the crash dialog was the question,
 // so the quit guard must not ask again.
 let fatalQuitting = false;
 try {
-  ({ installSafetyNet, installLogTee } = require("./main-safety-net.cjs"));
+  ({
+    installSafetyNet,
+    installLogTee,
+    readCount,
+    runSafeModePrompt,
+    SAFE_MODE_THRESHOLD,
+  } = require("./main-safety-net.cjs"));
   ({ fatal: _fatalHandler } = installSafetyNet({
     logPath: _MAIN_LOG_PATH,
     dialogModule: dialog,
@@ -59,6 +66,8 @@ try {
     beforeQuit: () => {
       fatalQuitting = true;
     },
+    // The install screen takes focus before anything has proved it can run.
+    holdCrashCount: () => showingInstallScreen,
   }));
 } catch (err) {
   try { process.stderr.write(`[main] safety-net load failed: ${err.message}\n`); } catch { }
@@ -68,6 +77,12 @@ try {
   process.exit(1);
 }
 
+// ── Safe mode (issue #938) ────────────────────────────────────────────────────
+// After SAFE_MODE_THRESHOLD crashes in a row, skip the log tee (the #934 crash
+// path) and ask the user what to do before any other start-up work runs.
+const _crashCount = readCount(() => os.homedir());
+const _inSafeMode = _crashCount >= SAFE_MODE_THRESHOLD;
+
 // Services (loaded after app.whenReady)
 const TrayManager = require("./services/tray-manager.cjs");
 const { appIconPath, appUserModelId } = require("./services/app-icon.cjs");
@@ -77,6 +92,7 @@ const {
   fetchWorkInProgress,
   installQuitGuard,
   QUIT,
+  quitOnTermSignal,
   RESTART_FOR_UPDATE,
 } = require("./services/quit-guard.cjs");
 const AgentProcessManager = require("./services/agent-process-manager.cjs");
@@ -85,9 +101,9 @@ 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 { buildIndexQuery } = require("./services/index-query.cjs");
+const { buildIndexQuery, INSTALL_SCREEN_QUERY } = require("./services/index-query.cjs");
 const backendInstaller = require("./services/backend-installer.cjs");
-const installerProgressDialog = require("./services/backend-installer-progress-dialog.cjs");
+const { createEngineInstall } = require("./services/engine-install.cjs");
 const autoUpdater = require("./services/auto-updater.cjs");
 const agentSeeder = require("./services/agent-seeder.cjs");
 const systemMetrics = require("./services/system-metrics.cjs");
@@ -119,7 +135,7 @@ for (const [name, value] of chromiumSwitches({ platform: process.platform, env:
 // Users often launch AppImages by double-click, not from a terminal, so
 // console output vanishes. Mirror console.log/error to a file so the
 // diagnostics bundler has something to attach.
-(function installMainLogTee() {
+function installMainLogTee() {
   try {
     try { fs.mkdirSync(_GAIA_DIR, { recursive: true }); } catch { /* ignore */ }
     const logPath = _MAIN_LOG_PATH;
@@ -186,7 +202,8 @@ for (const [name, value] of chromiumSwitches({ platform: process.platform, env:
     // not refuse to launch over a log-tee failure.
     process.stderr.write(`[main] log tee failed: ${err.message}\n`);
   }
-})();
+}
+if (!_inSafeMode) installMainLogTee();
 
 // ── Configuration ──────────────────────────────────────────────────────────
 
@@ -232,10 +249,11 @@ let backendStderrTail = [];
 let isIntentionalKill = false;
 let mainWindow = null;
 
-// True until createWindow() runs. Guards window-all-closed from firing app.quit()
-// while the backend-installer progress dialog is open (it's the only window during
-// bootstrap, so destroying it would trigger a premature quit — issue #934).
-let isBootstrapping = true;
+// The window shows EngineInstallScreen, not the app, until the backend answers.
+let showingInstallScreen = false;
+
+/** @type {ReturnType<typeof createEngineInstall> | null} */
+let engineInstall = null;
 
 /** @type {TrayManager | null} */
 let trayManager = null;
@@ -269,7 +287,7 @@ let isQuitting = false;
  * orphaned `gaia chat --ui` process. On Windows that process keeps an open
  * handle on `gaia.exe`, so the next upgrade's `uv pip install --refresh` fails
  * with `os error 32` (file in use) — issue #1388. We MUST run this BEFORE the
- * installer (`bootstrapBackend()`), not just before spawning the new backend,
+ * installer (`engineInstall.run()`), not just before spawning the new backend,
  * so the executable can be replaced.
  *
  * The PID is read from ~/.gaia/backend.pid and verified to be a GAIA backend
@@ -316,7 +334,7 @@ async function cleanupOrphanedBackend() {
 /**
  * Start the GAIA Python backend. Expects the backend installer to have
  * already ensured the venv is populated — callers should await
- * `bootstrapBackend()` first.
+ * `engineInstall.run()` first.
  *
  * Returns the ChildProcess, or null if the gaia binary cannot be found
  * (shouldn't happen post-ensureBackend, but we guard just in case).
@@ -363,7 +381,15 @@ async function startBackend() {
       stdio: ["ignore", "pipe", "pipe"],
       // GAIA_APP_PID: GAIA's daemon unloads its models once this app exits
       // and no other GAIA client is using them.
-      env: { ...process.env, GAIA_APP_PID: String(process.pid) },
+      // GAIA_BUNDLED_LEMONADE_DIR: where EmbeddedLemonade.install() finds the
+      // archive this app ships (electron-builder.yml) instead of downloading it.
+      env: {
+        ...process.env,
+        GAIA_APP_PID: String(process.pid),
+        ...(app.isPackaged && {
+          GAIA_BUNDLED_LEMONADE_DIR: path.join(process.resourcesPath, "vendor", "lemonade"),
+        }),
+      },
       detached: false,
       windowsHide: true, // Prevent console window flash on Windows
     }
@@ -440,6 +466,7 @@ async function startBackend() {
  * Quit. Invoked from child.on("exit") when the kill was NOT initiated by us.
  */
 async function handleBackendCrash(code, signal) {
+  autoUpdater.reportStartFailure();
   try {
     const choice = await showBackendCrashDialog({
       dialog,
@@ -548,11 +575,21 @@ function titleDownloadSaveDialogs() {
   session.defaultSession.on("will-download", (_event, item) => {
     item.setSaveDialogOptions({
       title: "Save from GAIA",
-      defaultPath: path.join(app.getPath("downloads"), item.getFilename()),
+      defaultPath: saveFolderFor(item.getFilename()),
     });
   });
 }
 
+// Windows throws when the user's Downloads folder is missing or redirected away; the dialog still lets them pick one.
+function saveFolderFor(filename) {
+  try {
+    return path.join(app.getPath("downloads"), filename);
+  } catch (err) {
+    console.warn(`[GAIA] No Downloads folder to suggest for ${filename}: ${err.message}`);
+    return filename;
+  }
+}
+
 function createWindow() {
   mainWindow = new BrowserWindow({
     ...titleBarOptions(process.platform),
@@ -656,8 +693,8 @@ async function loadApp() {
     // renderer (apiBase.ts) validates this value against an allowlist
     // before using it — keep buildIndexQuery in sync with TRUSTED_API_RE.
     const indexPath = path.join(distPath, "index.html");
-    const indexQuery = buildIndexQuery(backendPort);
-    console.log("Loading app from:", indexPath, "api:", indexQuery.api);
+    const indexQuery = showingInstallScreen ? INSTALL_SCREEN_QUERY : buildIndexQuery(backendPort);
+    console.log("Loading app from:", indexPath, "query:", indexQuery);
     // Use pathToFileURL so the file:// URL always has forward slashes on
     // Windows — Chromium 130+ (Electron 40) rejects backslash file URLs
     // that Node's url.format() (used by loadFile) produces on Windows.
@@ -808,117 +845,30 @@ function setupJumpList() {
 
 // ── Backend Bootstrap (Phase A) ───────────────────────────────────────────
 
-/** First install found a Lemonade already running: use it, or install GAIA's own? */
-async function chooseLemonadeInDialog(found, parent) {
-  // Modal to the progress window and in front: otherwise it can open behind
-  // other windows while the install sits at 70% waiting for it.
-  const owner = parent && !parent.isDestroyed() ? parent : null;
-  if (owner) {
-    if (owner.isMinimized()) owner.restore();
-    owner.show();
-    owner.moveTop();
-    owner.focus();
-    // Windows can refuse focus to a background app; the taskbar flash is the hint.
-    if (!owner.isFocused()) owner.flashFrame(true);
+/** A failed install is on screen, even for a launch that started in the tray. */
+function showInstallFailure(err) {
+  // No frontend build to show it in: a source checkout that never ran `npm run build`.
+  if (!findDistPath()) {
+    _fatalHandler(err);
+    return;
   }
-  const box = {
-    type: "question",
-    title: "Lemonade Server found",
-    message: `A Lemonade Server (v${found.version}) is already running at ${found.url}. Use it instead of installing GAIA's own?`,
-    detail: "This avoids running two servers and keeping two copies of each model.",
-    buttons: ["Use my Lemonade", "Install GAIA's own"],
-    defaultId: 0,
-    cancelId: 1,
-    noLink: true,
-  };
-  const { response } = owner
-    ? await dialog.showMessageBox(owner, box)
-    : await dialog.showMessageBox(box);
-  if (owner && !owner.isDestroyed()) owner.flashFrame(false);
-  return response === 0 ? "external" : "gaia";
+  const win = mainWindow && !mainWindow.isDestroyed() ? mainWindow : reopenWindow();
+  if (win.isMinimized()) win.restore();
+  win.show();
 }
 
-/**
- * Ensure the Python backend is installed before the main window loads.
- *
- * Shows a borderless progress window while the install runs. On failure,
- * surfaces a retry / manual / quit dialog. Loops until the user either
- * succeeds, chooses manual install, or quits.
- *
- * Returns true if the backend is ready, false if the user chose to quit.
- */
-async function bootstrapBackend() {
-  // Fast-path: if an install is obviously not needed (binary present and
-  // version matches), skip the progress window entirely and go straight to
-  // ensureBackend which will confirm readiness.
-  const existingBin = backendInstaller.findGaiaBin();
-  if (existingBin) {
-    const installedVersion = backendInstaller.getInstalledVersion(existingBin);
-    let expectedVersion = null;
-    try {
-      const pkg = JSON.parse(
-        fs.readFileSync(path.join(__dirname, "package.json"), "utf8")
-      );
-      expectedVersion = pkg.version;
-    } catch {
-      // ignore
-    }
-    if (installedVersion && installedVersion === expectedVersion) {
-      console.log(
-        `[main] GAIA backend already at ${installedVersion} — skipping bootstrap UI`
-      );
-      // Clean up any stale state file so the state machine reflects reality.
-      backendInstaller.setState(backendInstaller.STATES.READY, {
-        version: expectedVersion,
-        installedVersion,
-      });
-      return true;
-    }
-  }
-
-  // Slow path: need to install or upgrade. Show the progress window.
-  let keepTrying = true;
-  while (keepTrying) {
-    const progress = installerProgressDialog.createProgressWindow();
-
-    try {
-      await backendInstaller.ensureBackend({
-        onProgress: progress.onProgress,
-        isPackaged: app.isPackaged,
-        chooseLemonade: (found) => chooseLemonadeInDialog(found, progress.window),
-      });
-      progress.close();
-      console.log("[main] Backend bootstrap complete");
-      return true;
-    } catch (err) {
-      progress.close();
-      console.error(
-        `[main] Backend bootstrap failed: ${err && err.message ? err.message : err}`
-      );
-
-      const errorInfo = {
-        message: (err && err.message) || "GAIA install failed.",
-        stage: (err && err.stage) || null,
-        suggestion: (err && err.suggestion) || null,
-      };
-
-      const choice = await installerProgressDialog.showFailureDialog(
-        null,
-        errorInfo
-      );
+/** Lets an update fetch its backend before the restart, so the first launch is offline. */
+function updateBackendHooks() {
+  return {
+    prefetchBackend: (version) => backendInstaller.prefetchBackend(version, { isPackaged: app.isPackaged }),
+    isBackendPrefetched: backendInstaller.isBackendPrefetched,
+  };
+}
 
-      if (choice === "retry") {
-        continue; // loop
-      }
-      if (choice === "manual") {
-        // The user was directed to the docs in an external browser. Quit so
-        // they can complete the manual install and restart.
-        return false;
-      }
-      return false; // quit
-    }
-  }
-  return false;
+/** Setup failed after an update: download the version before it and restart into it. */
+async function goBackToPreviousVersion() {
+  autoUpdater.init(null, { confirmRestart: async () => true, ...updateBackendHooks() });
+  await autoUpdater.revertUpdate();
 }
 
 // ── gaia:// deep-link install bridge (issue #1725) ──────────────────────────
@@ -1153,10 +1103,7 @@ if (process.platform === "win32") {
 
 app.on("second-instance", (_event, argv, _cwd) => {
   // A second launch happened while we were running. Surface our window
-  // (the user almost certainly wanted to see it). mainWindow may be null
-  // if we're still in the bootstrap phase — in that case the first
-  // instance is already showing the install progress dialog and there's
-  // nothing else to do.
+  // (the user almost certainly wanted to see it).
   if (typeof mainWindow !== "undefined" && mainWindow && !mainWindow.isDestroyed()) {
     if (mainWindow.isMinimized()) mainWindow.restore();
     if (!mainWindow.isVisible()) mainWindow.show();
@@ -1170,6 +1117,44 @@ app.on("second-instance", (_event, argv, _cwd) => {
 });
 
 app.whenReady().then(async () => {
+  if (_inSafeMode) {
+    await runSafeModePrompt({
+      count: _crashCount,
+      dialogModule: dialog,
+      appModule: app,
+      shellModule: shell,
+    });
+    return;
+  }
+
+  // The window, and the tray that keeps a closed one reachable, come before
+  // anything that can take time, so an install runs in plain sight.
+  titleDownloadSaveDialogs();
+  createWindow();
+  initializeServices();
+  engineInstall = createEngineInstall({
+    installer: backendInstaller,
+    ipcMain,
+    shell,
+    getWindow: () => mainWindow,
+    isPackaged: app.isPackaged,
+    onFailed: showInstallFailure,
+    previousVersion: () => autoUpdater.previousVersion(),
+    revert: goBackToPreviousVersion,
+  });
+
+  app.on("activate", () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      reopenWindow();
+    } else if (mainWindow) {
+      mainWindow.show();
+    }
+  });
+
+  // Decided before the window has a page, so a current backend never sees this screen.
+  showingInstallScreen = !backendInstaller.isBackendCurrent();
+  if (showingInstallScreen) await loadApp();
+
   // Phase 0: seed bundled agents BEFORE the Python backend starts, so the
   // agent registry sees them on its first discovery pass. Failures here are
   // non-fatal — the app must still launch even if seeding is blocked (e.g.
@@ -1198,13 +1183,14 @@ app.whenReady().then(async () => {
   // unless that process is gone first (issue #1388).
   await cleanupOrphanedBackend();
 
-  // Phase A: ensure the Python backend is installed BEFORE creating the
-  // main window. The progress dialog owns the UI during this phase.
-  const bootstrapOk = await bootstrapBackend();
-  if (!bootstrapOk) {
-    console.log("[main] Backend bootstrap aborted — quitting");
-    app.quit();
-    return;
+  // Phase A: install or upgrade the Python backend behind EngineInstallScreen.
+  if (showingInstallScreen) {
+    const installed = await engineInstall.run();
+    if (!installed) {
+      console.log("[main] Quit during the backend install");
+      return;
+    }
+    engineInstall.starting();
   }
 
   // Start the Python backend
@@ -1215,21 +1201,16 @@ app.whenReady().then(async () => {
     console.log("[main] Quit during startup — not opening the window");
     return;
   }
-
-  // Create the window (hidden until ready-to-show)
-  titleDownloadSaveDialogs();
-  createWindow();
-  isBootstrapping = false; // progress dialog is gone; window-all-closed may now quit
-
-  // Initialize services (tray, agent manager, notifications)
-  initializeServices();
+  if (trayManager) trayManager.setBackendPort(backendPort);
+  // macOS: the user closed the window during a long install.
+  if (!mainWindow) reopenWindow();
 
   // Phase F: start the auto-updater (non-blocking). First check runs on
   // a 10s delay inside the module so it never competes with app launch.
   // Any failure here is logged and swallowed — the app continues to run
   // even if auto-update is unavailable.
   try {
-    autoUpdater.init(mainWindow, { confirmRestart: confirmUpdateRestart });
+    autoUpdater.init(mainWindow, { confirmRestart: confirmUpdateRestart, ...updateBackendHooks() });
   } catch (err) {
     console.error(
       "[main] Failed to init auto-updater:",
@@ -1240,8 +1221,8 @@ app.whenReady().then(async () => {
   // Setup Windows Jump List (T11)
   setupJumpList();
 
-  // Show loading state
-  await loadApp();
+  // The install screen stays until the backend answers, then gives way to the app.
+  if (!showingInstallScreen) await loadApp();
 
   // Wait for backend API to be reachable. The bundled frontend
   // (loaded from dist/index.html in the asar) auto-detects when the
@@ -1258,6 +1239,19 @@ app.whenReady().then(async () => {
       console.warn("Backend did not respond within timeout.");
     }
   }
+  if (!backendReady) {
+    autoUpdater.reportStartFailure();
+    if (backendProcess) {
+      waitForBackend(STARTUP_TIMEOUT * 10).then((ready) => {
+        if (ready) autoUpdater.clearStartFailure();
+      });
+    }
+  }
+
+  if (showingInstallScreen) {
+    showingInstallScreen = false;
+    if (mainWindow) await loadApp();
+  }
 
   // Act on any gaia:// deep link that arrived during bootstrap or via the
   // cold-start command line (issue #1725) — after the backend is listening,
@@ -1275,14 +1269,6 @@ app.whenReady().then(async () => {
 
   // macOS and Linux: the shutdown is the OS's, so don't ask.
   powerMonitor.on("shutdown", () => quitGuard.allow());
-
-  app.on("activate", () => {
-    if (BrowserWindow.getAllWindows().length === 0) {
-      reopenWindow();
-    } else if (mainWindow) {
-      mainWindow.show();
-    }
-  });
 }).catch((err) => {
   // Route explicit rejection through the safety-net so the user gets a
   // GAIA-branded dialog and a stack trace in the log (issue #934).
@@ -1292,12 +1278,6 @@ app.whenReady().then(async () => {
 // ── Window-all-closed (C4 fix) ────────────────────────────────────────────
 // Don't quit when window is hidden — tray keeps app alive
 app.on("window-all-closed", () => {
-  // During bootstrap the progress dialog is the only open window. Destroying
-  // it (progress.close()) fires this event before the main window exists, which
-  // would trigger a premature app.quit() that races with the startup sequence
-  // and causes loadURL() to fail with ERR_FAILED (-2) — issue #934.
-  if (isBootstrapping) return;
-
   // If minimize-to-tray is active, the window is just hidden, not closed.
   // Only quit on macOS if the user explicitly quit (Cmd+Q).
   const trayActive = trayManager && trayManager.minimizeToTray;
@@ -1331,7 +1311,7 @@ function askAboutRunningWork(action) {
   });
 }
 
-/** The update dialog's "Restart now": the installer starts at once, so ask first. */
+/** Restarting into an update: the installer starts at once, so ask first. */
 function confirmUpdateRestart() {
   return workCanBeLost() ? askAboutRunningWork(RESTART_FOR_UPDATE) : Promise.resolve(true);
 }
@@ -1359,10 +1339,13 @@ const quitGuard = installQuitGuard({
   },
 });
 
+quitOnTermSignal({ proc: process, app, guard: quitGuard });
+
 installQuitCleanup({ app, cleanup });
 
 async function cleanup() {
   shutdownStarted = true;
+  const installStopped = engineInstall ? engineInstall.stop() : null;
 
   // Phase F: tear down auto-updater timers and IPC handlers.
   try {
@@ -1385,9 +1368,9 @@ async function cleanup() {
     keepAwake = null;
   }
 
-  // The agents and the backend stop side by side: each waits out its own
-  // grace period, and in series they could overrun the quit's time limit.
-  await Promise.all([stopAgentsForQuit(), stopBackendForQuit()]);
+  // The install, the agents and the backend stop side by side: each waits out
+  // its own grace period, and in series they could overrun the quit's time limit.
+  await Promise.all([installStopped, stopAgentsForQuit(), stopBackendForQuit()]);
 
   // Destroy tray icon
   if (trayManager) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/agent-ui",
-  "version": "0.25.3",
+  "version": "0.25.4-rc.10",
   "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",
@@ -51,15 +51,17 @@
     "build": "tsc && vite build",
     "preview": "vite preview",
     "start": "electron .",
-    "package": "npm run build && electron-builder --config electron-builder.yml",
+    "package": "npm run build && node scripts/strip-appimage-copyleft.cjs && electron-builder --config electron-builder.yml",
     "make": "npm run package",
     "package:win": "npm run build && electron-builder --win --config electron-builder.yml",
     "package:mac": "npm run build && electron-builder --mac --config electron-builder.yml",
-    "package:linux": "npm run build && electron-builder --linux --config electron-builder.yml",
+    "package:linux": "npm run build && node scripts/strip-appimage-copyleft.cjs && electron-builder --linux --config electron-builder.yml",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:visual": "vite build && playwright test -c visual/playwright.config.ts",
+    "test:rtl": "vite build && playwright test -c visual/playwright.config.ts rtl --project=light",
+    "test:scroll": "vite build && playwright test -c visual/playwright.config.ts autoscroll --project=light",
     "gen:api-types": "node scripts/gen-api-types.mjs"
   },
   "dependencies": {

package/preload.cjs

@@ -11,7 +11,7 @@
  *   agent:*          — Agent process management (T2)
  *   tray:*           — Tray icon/config (T1)
  *   notification:*   — Desktop notifications & permission prompts (T5)
- *   install:*        — First-run backend install progress (Phase A)
+ *   install:*        — Backend install status, retry and log (Phase A)
  *   gaia:update:*    — Auto-update status & manual check (Phase F)
  *   system:*         — System metrics for the observability dashboard (#2007)
  *   power:*          — Keep the PC awake while a chat turn runs (#5226)
@@ -105,19 +105,26 @@ contextBridge.exposeInMainWorld("gaiaWindow", {
   setColors: (colors) => ipcRenderer.invoke("window:set-titlebar-colors", colors),
 });
 
-// ── Install progress (Phase A) ──────────────────────────────────────────
-// Exposed as a separate global so the progress window can use it without
-// pulling in the full gaiaAPI surface (and so it keeps working if an
-// install dialog runs before the main window is ready).
+// ── Backend install (Phase A) ───────────────────────────────────────────
+// EngineInstallScreen runs with no backend, so this stands apart from gaiaAPI.
 contextBridge.exposeInMainWorld("gaiaInstall", {
-  // Subscribe to progress updates. Returns an unsubscribe function.
+  // Subscribe to status updates. Returns an unsubscribe function.
   onProgress: (cb) => onEvent("install:progress", cb),
 
-  // Query the current install state (state machine + log/state paths).
+  // The current status: { phase, stage, percent, message, error, logPath }.
   status: () => ipcRenderer.invoke("install:status"),
 
-  // Copy the log file path to the clipboard.
-  copyLogPath: () => ipcRenderer.invoke("install:copy-log-path"),
+  // After a failure, install again. Resolves false when none is waiting.
+  retry: () => ipcRenderer.invoke("install:retry"),
+
+  // Goes on past a failed agent update; the next launch tries it again.
+  continueWithoutAgentUpdate: () => ipcRenderer.invoke("install:continue"),
+
+  // After a failed update, go back to the version before it; the app restarts into it.
+  revert: () => ipcRenderer.invoke("install:revert"),
+
+  // After a 'locked' failure held only by GAIA processes: ends those and installs again.
+  closeLockingPrograms: () => ipcRenderer.invoke("install:close-lockers"),
 
   // Open the log file in the OS's default viewer.
   openLogFile: () => ipcRenderer.invoke("install:open-log-file"),
@@ -159,6 +166,9 @@ contextBridge.exposeInMainWorld("gaiaUpdater", {
    */
   installVersion: (tag) => ipcRenderer.invoke("gaia:update:install-version", tag),
 
+  /** Go back to the version before the last update, and pin it. */
+  revertUpdate: () => ipcRenderer.invoke("gaia:update:revert"),
+
   /**
    * Resume normal auto-updates — clears the version pin set by installVersion.
    * Resolves with the updated state.

package/services/agent-seeder.cjs

@@ -41,10 +41,11 @@
  * Recovery: to get a deleted bundled agent back, remove
  * `~/.gaia/seeder/<id>.seeded` and relaunch.
  *
- * Legacy cleanup: the retired `zoo-agent` demo is removed from
- * ~/.gaia/agents/ when it is provably an unmodified seeded copy — sentinel
- * present, no file newer than its seededAt (+5s slack), never through a
- * symlink. Removed ids are reported via the additive `cleaned` array.
+ * Legacy cleanup: the retired `zoo-agent` and `example-agent` demos are
+ * removed from ~/.gaia/agents/ when provably an unmodified seeded copy —
+ * sentinel present, no file newer than its seededAt (+5s slack), never
+ * through a symlink, and never while this build still bundles that id.
+ * Removed ids are reported via the additive `cleaned` array.
  *
  * Behaviour:
  *   - `process.resourcesPath` unset (dev / Jest) → empty result, no error,
@@ -310,7 +311,7 @@ function seedOneAgent(sourceDir, targetRoot, id) {
 // ── Legacy cleanup ───────────────────────────────────────────────────────
 
 // Retired bundled ids removed from user machines when provably unmodified.
-const LEGACY_CLEANUP_IDS = ["zoo-agent"];
+const LEGACY_CLEANUP_IDS = ["zoo-agent", "example-agent"];
 
 // Filesystem mtime granularity + copy latency headroom for the
 // modified-since-seed check.
@@ -334,20 +335,28 @@ function listFilesRecursive(dir) {
 }
 
 /**
- * Remove retired seeded demo agents (currently `zoo-agent`) from
+ * Remove retired seeded demo agents (LEGACY_CLEANUP_IDS) from
  * ~/.gaia/agents/. Deletes ONLY when the dir is provably an unmodified
- * seeded copy; anything ambiguous is left in place. Failures are logged
+ * seeded copy; anything ambiguous is left in place. An id the current
+ * installer still bundles is skipped: deleting it would leave a marker
+ * that blocks the re-seed, so the bundled agent would vanish for good. Failures are logged
  * and retried on the next launch (the sentinel keys the retry — no marker
  * is involved, since a retired id can never be re-seeded anyway).
  *
+ * @param {string} sourceDir  `<resourcesPath>/agents` of this build.
  * @returns {string[]} ids actually removed (verified gone from disk).
  */
-function cleanupLegacyAgents() {
+function cleanupLegacyAgents(sourceDir) {
   const cleaned = [];
 
   for (const id of LEGACY_CLEANUP_IDS) {
     const target = path.join(agentsTargetRoot(), id);
 
+    if (sourceDir && isDirectory(path.join(sourceDir, id))) {
+      log("INFO", `Legacy "${id}" is still bundled by this build — not removing it`);
+      continue;
+    }
+
     let st;
     try {
       st = fs.lstatSync(target);
@@ -467,13 +476,13 @@ async function seedBundledAgents() {
     return result;
   }
 
-  // Legacy cleanup runs before the missing-source guard: an upgraded
-  // install must shed the retired zoo-agent even if this build ships no
-  // bundled agents.
-  result.cleaned = cleanupLegacyAgents();
-
   const sourceDir = path.join(process.resourcesPath, "agents");
 
+  // Legacy cleanup runs before the missing-source guard: an upgraded
+  // install must shed retired demos even if this build ships no bundled
+  // agents.
+  result.cleaned = cleanupLegacyAgents(sourceDir);
+
   if (!fs.existsSync(sourceDir) || !isDirectory(sourceDir)) {
     // Not an error — a build might simply ship without bundled agents.
     // In a packaged Electron app the directory is expected to exist, so raise