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

package/dist/assets/message-square-Dwm7y3C0.js

@@ -0,0 +1 @@
+import{l as e}from"./apiBase-y00JgRBP.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);export{n as t};

package/dist/index.html

@@ -3,15 +3,15 @@
 <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <!-- Graphite canvas; rewritten per theme by applyTheme(). Dark is the
-         designed default, so an unset preference stays dark. -->
-    <meta name="theme-color" content="#17161C" />
+    <!-- Canvas color; rewritten per theme and palette by applyTheme() and
+         syncTitleBar(). With no saved preference the app follows the OS. -->
+    <meta name="theme-color" content="#1A1917" />
     <link rel="icon" type="image/png" href="./favicon.png" />
     <title>GAIA Agent UI</title>
-  <script type="module" crossorigin src="./assets/index-DEPbenxC.js"></script>
+  <script type="module" crossorigin src="./assets/index-I_UyOSz2.js"></script>
   <link rel="modulepreload" crossorigin href="./assets/rolldown-runtime-hePW80VL.js">
-  <link rel="modulepreload" crossorigin href="./assets/jsx-runtime-DVeaULmT.js">
-  <link rel="stylesheet" crossorigin href="./assets/index-CFVpPQal.css">
+  <link rel="modulepreload" crossorigin href="./assets/apiBase-y00JgRBP.js">
+  <link rel="stylesheet" crossorigin href="./assets/index-B3UtHCtQ.css">
 </head>
 <body>
     <div id="root"></div>

package/main-safety-net.cjs

@@ -13,6 +13,11 @@
  *   - process.on('unhandledRejection') catches rejected app.whenReady() chain.
  *   - installLogTee() attaches stream.on('error') so stream errors are handled
  *     before they can become uncaughtException (root-cause fix).
+ *
+ * A fatal error quits through app.quit(), not process.exit(): only the quit
+ * path (will-quit in main.cjs) stops the backend and the agents, so exiting
+ * directly left them running after the window was gone (#3498). A timer
+ * still forces the exit if that cleanup hangs.
  */
 
 "use strict";
@@ -60,6 +65,9 @@ function appendLog(logPath, msg) {
   }
 }
 
+/** How long a fatal error's quit may take before the process is ended outright (ms). */
+const FATAL_EXIT_GRACE_MS = 25000;
+
 // ── Core installer ────────────────────────────────────────────────────────────
 
 /**
@@ -70,24 +78,63 @@ function appendLog(logPath, msg) {
  * @param {object}   opts.dialogModule  - Electron dialog (injected for tests).
  * @param {object}   opts.appModule     - Electron app EventEmitter (injected).
  * @param {Function} [opts.homedirFn]   - Override for os.homedir (tests).
+ * @param {Function} [opts.beforeQuit]  - Called before the fatal quit, e.g.
+ *   so the quit guard does not ask the user to confirm it.
+ * @param {number}   [opts.exitGraceMs] - Override for FATAL_EXIT_GRACE_MS.
  */
-function installSafetyNet({ logPath, dialogModule, appModule, homedirFn }) {
+function installSafetyNet({
+  logPath,
+  dialogModule,
+  appModule,
+  homedirFn,
+  beforeQuit,
+  exitGraceMs = FATAL_EXIT_GRACE_MS,
+}) {
   const homedir = homedirFn || (() => os.homedir());
 
   // Per-handler re-entry guard (closure-scoped — each installSafetyNet
   // call gets its own, intentionally; see test_main_error_handling.js).
   let _inFatalHandler = false;
 
+  // Quit through will-quit so its cleanup stops the backend and agents; the
+  // timer ends the process if that cleanup never finishes.
+  function quitAfterFatal() {
+    const timer = setTimeout(() => {
+      appendLog(
+        logPath,
+        `[${new Date().toISOString()}] FATAL_EXIT cleanup did not finish within ${exitGraceMs} ms; exiting`
+      );
+      process.exit(1);
+    }, exitGraceMs);
+    if (typeof beforeQuit === "function") {
+      try {
+        beforeQuit();
+      } catch (hookErr) {
+        appendLog(logPath, `[${new Date().toISOString()}] FATAL_QUIT beforeQuit failed: ${hookErr.stack || hookErr}`);
+      }
+    }
+    try {
+      appModule.quit();
+    } catch (quitErr) {
+      clearTimeout(timer);
+      appendLog(logPath, `[${new Date().toISOString()}] FATAL_QUIT app.quit() failed, exiting now: ${quitErr.stack || quitErr}`);
+      process.exit(1);
+    }
+  }
+
   function fatal(err) {
+    const stack = (err && err.stack) ? err.stack : String(err);
+    const ts = new Date().toISOString();
+
+    // A second fatal while the first is still showing its dialog or quitting
+    // (an EPIPE from a child that died during cleanup, say) is logged only:
+    // exiting here would skip the cleanup that is already under way.
     if (_inFatalHandler) {
-      try { process.exit(2); } catch { }
+      appendLog(logPath, `[${ts}] FATAL (while already quitting) ${stack}`);
       return;
     }
     _inFatalHandler = true;
 
-    const stack = (err && err.stack) ? err.stack : String(err);
-    const ts = new Date().toISOString();
-
     // Write to log BEFORE showing dialog so the entry survives even if
     // dialog.showErrorBox itself crashes.
     appendLog(logPath, `[${ts}] FATAL ${stack}`);
@@ -112,7 +159,7 @@ function installSafetyNet({ logPath, dialogModule, appModule, homedirFn }) {
       }
     } catch { } // intentional: fatal path, no upstream
 
-    try { process.exit(1); } catch { } // intentional: fatal path
+    quitAfterFatal();
   }
 
   // Wire process-level handlers.
@@ -179,4 +226,4 @@ function installLogTee({ stream, logPath }) {
   });
 }
 
-module.exports = { installSafetyNet, installLogTee };
+module.exports = { installSafetyNet, installLogTee, FATAL_EXIT_GRACE_MS };

package/main.cjs

@@ -13,7 +13,16 @@
 //   services/notification-service.js  — Desktop notifications + permission prompts (T5)
 //   preload.cjs                       — contextBridge for IPC channels (T0/T1)
 
-const { app, BrowserWindow, dialog, shell } = require("electron");
+const {
+  app,
+  autoUpdater: electronAutoUpdater,
+  BrowserWindow,
+  Menu,
+  dialog,
+  ipcMain,
+  powerMonitor,
+  shell,
+} = require("electron");
 const path = require("path");
 const fs = require("fs");
 const os = require("os");
@@ -37,12 +46,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;
+// 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"));
   ({ fatal: _fatalHandler } = installSafetyNet({
     logPath: _MAIN_LOG_PATH,
     dialogModule: dialog,
     appModule: app,
+    beforeQuit: () => {
+      fatalQuitting = true;
+    },
   }));
 } catch (err) {
   try { process.stderr.write(`[main] safety-net load failed: ${err.message}\n`); } catch { }
@@ -54,8 +69,17 @@ try {
 
 // Services (loaded after app.whenReady)
 const TrayManager = require("./services/tray-manager.cjs");
+const {
+  attachWindowGuards,
+  confirmQuit,
+  fetchWorkInProgress,
+  installQuitGuard,
+  QUIT,
+  RESTART_FOR_UPDATE,
+} = require("./services/quit-guard.cjs");
 const AgentProcessManager = require("./services/agent-process-manager.cjs");
 const NotificationService = require("./services/notification-service.cjs");
+const KeepAwake = require("./services/keep-awake.cjs");
 const PortManager = require("./services/port-manager.cjs");
 const { isGaiaBackendProcess } = require("./services/backend-orphan.cjs");
 const { buildIndexQuery } = require("./services/index-query.cjs");
@@ -76,6 +100,8 @@ const {
   describeBlockedUrl,
 } = require("./services/link-policy.cjs");
 const { createStartupDeepLinkQueue } = require("./services/deep-link-queue.cjs");
+const { installWindowKeys } = require("./services/window-keys.cjs");
+const { installQuitCleanup } = require("./services/quit-cleanup.cjs");
 
 // ── F7: Ozone hint (issue #782) ─────────────────────────────────────────────
 // Electron-recommended switch for distro-agnostic Linux behaviour: picks
@@ -205,6 +231,11 @@ const windowConfig = appConfig.window || {
 // ── State ──────────────────────────────────────────────────────────────────
 
 let backendProcess = null;
+// The in-flight startBackend(), so a quit during startup can wait for the
+// spawn and stop it instead of leaving it behind.
+let backendStarting = null;
+// Set as cleanup() begins; startup stops at its next step once it is.
+let shutdownStarted = false;
 let backendPort = DEFAULT_BACKEND_PORT;
 let healthCheckUrl = `http://localhost:${backendPort}/api/health`;
 let backendStderrTail = [];
@@ -225,6 +256,9 @@ let agentProcessManager = null;
 /** @type {NotificationService | null} */
 let notificationService = null;
 
+/** @type {KeepAwake | null} */
+let keepAwake = null;
+
 /** @type {PortManager} */
 const portManager = new PortManager({
   logger: { log: console.log.bind(console), error: console.error.bind(console) },
@@ -386,6 +420,7 @@ async function startBackend() {
     }
     const crashed = !isIntentionalKill && code !== 0 && code !== null;
     backendProcess = null;
+    if (trayManager && !isQuitting) trayManager.setBackendAlive(false);
 
     if (crashed && !isQuitting) {
       // Fire-and-forget — don't block the event loop.
@@ -523,8 +558,40 @@ function reportBlockedLink(url) {
     );
 }
 
+// No system title bar: the app's own top row is the window's top edge, and
+// the native window controls are drawn into it (traffic lights on macOS).
+// Keep the height in sync with --titlebar-h in src/styles/index.css. The
+// renderer sends its canvas and text colors once it paints; until then the
+// controls use the dark canvas, like the window background.
+const TITLE_BAR_HEIGHT = 48;
+const TITLE_BAR_INITIAL = { color: "#1A1917", symbolColor: "#EFECE6" };
+const IS_MAC = process.platform === "darwin";
+const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+
+function titleBarOptions() {
+  return IS_MAC
+    ? { titleBarStyle: "hidden", trafficLightPosition: { x: 16, y: 16 } }
+    : {
+        titleBarStyle: "hidden",
+        titleBarOverlay: { ...TITLE_BAR_INITIAL, height: TITLE_BAR_HEIGHT },
+      };
+}
+
+// The renderer sends its canvas and text colors so the controls match the theme.
+ipcMain.handle("window:set-titlebar-colors", (_event, colors) => {
+  const { color, symbolColor } = colors || {};
+  if (!HEX_COLOR.test(color) || !HEX_COLOR.test(symbolColor)) {
+    throw new Error(`Title bar colors must be #rrggbb, got ${JSON.stringify(colors)}`);
+  }
+  if (!IS_MAC && mainWindow && !mainWindow.isDestroyed()) {
+    mainWindow.setTitleBarOverlay({ color, symbolColor });
+  }
+  return true;
+});
+
 function createWindow() {
   mainWindow = new BrowserWindow({
+    ...titleBarOptions(),
     width: windowConfig.width,
     height: windowConfig.height,
     minWidth: windowConfig.minWidth,
@@ -539,7 +606,12 @@ function createWindow() {
     },
   });
 
-  // Remove default menu bar
+  // No File/Edit/View menu: hiding the bar alone still lets Alt bring it back.
+  // macOS keeps its menu, which carries copy, paste and quit.
+  if (process.platform !== "darwin") {
+    Menu.setApplicationMenu(null);
+    installWindowKeys(mainWindow.webContents, { devTools: !app.isPackaged });
+  }
   mainWindow.setMenuBarVisibility(false);
 
   // Open external links in the default browser. The URL here is already
@@ -567,18 +639,27 @@ function createWindow() {
     reportBlockedLink(url);
   });
 
-  // ── Minimize-to-tray on close (C4 fix) ──────────────────────────────
-  // Intercept window close — hide instead of closing when tray mode is active
-  mainWindow.on("close", (event) => {
-    if (!isQuitting && trayManager && trayManager.minimizeToTray) {
-      event.preventDefault();
-      mainWindow.hide();
-      console.log("[main] Window hidden to tray");
-    }
+  // ── Minimize-to-tray on close (C4 fix), first-close notice, quit guard ──
+  attachWindowGuards(mainWindow, {
+    app,
+    guard: quitGuard,
+    getTray: () => trayManager,
+    isQuitting: () => isQuitting,
+    platform: process.platform,
+    reportNoticeError: (err) => {
+      console.error("[main] First-close notice failed:", err.message);
+      const where = process.platform === "darwin" ? "menu bar" : "tray";
+      dialog.showErrorBox(
+        "GAIA is still running",
+        `GAIA is still running in the ${where}. Quit from the ${where} menu to stop it.\n\n` +
+          `(The usual notice failed: ${err.message})`
+      );
+    },
   });
 
   mainWindow.on("closed", () => {
     mainWindow = null;
+    if (trayManager) trayManager.windowClosed();
   });
 
   // Show window when ready (unless --minimized or startMinimized config)
@@ -631,9 +712,9 @@ async function loadApp() {
              * src/styles/index.css, so the dark theme's role values are
              * mirrored here. Keep them in step with that file. */
             :root {
-              --bg-primary: #17161C;
-              --text-primary: #F0EDE7;
-              --text-secondary: #AAA5B0;
+              --bg-primary: #1A1917;
+              --text-primary: #EFECE6;
+              --text-secondary: #B3ADA5;
             }
             body {
               font-family: -apple-system, BlinkMacSystemFont, sans-serif;
@@ -664,6 +745,25 @@ async function loadApp() {
 
 // ── Services Setup ─────────────────────────────────────────────────────────
 
+/**
+ * Recreate the window after it was closed (macOS keeps the app running).
+ * Services are re-pointed at it, not re-created: their IPC handlers stay.
+ * @returns {Electron.BrowserWindow}
+ */
+function reopenWindow() {
+  createWindow();
+  // Asked for from the tray or the dock: show it even when starting minimized.
+  mainWindow.once("ready-to-show", () => mainWindow && mainWindow.show());
+  if (agentProcessManager) agentProcessManager.mainWindow = mainWindow;
+  if (trayManager) trayManager.mainWindow = mainWindow;
+  if (notificationService) notificationService.mainWindow = mainWindow;
+  loadApp().catch((err) => {
+    console.error("[main] Failed to load the reopened window:", err.message);
+    dialog.showErrorBox("GAIA", `GAIA couldn't reopen its window: ${err.message}`);
+  });
+  return mainWindow;
+}
+
 function initializeServices() {
   console.log("[main] Initializing services...");
 
@@ -676,8 +776,16 @@ function initializeServices() {
   });
 
   // T1: Tray Manager (system tray icon + context menu)
-  trayManager = new TrayManager(mainWindow, { backendPort });
+  trayManager = new TrayManager(mainWindow, {
+    backendPort,
+    reopenWindow: () => reopenWindow(),
+  });
   trayManager.create();
+  try {
+    trayManager.syncLoginItem();
+  } catch (err) {
+    console.error(`[main] Could not read the sign-in start setting: ${err.message}`);
+  }
 
   // T5: Notification Service (routes agent notifications to OS + renderer)
   notificationService = new NotificationService(
@@ -686,6 +794,9 @@ function initializeServices() {
     trayManager
   );
 
+  // #5226: hold off idle sleep while a chat turn runs
+  keepAwake = new KeepAwake();
+
   // #2007: System metrics for the observability dashboard
   systemMetrics.registerIpcHandlers();
 
@@ -1111,7 +1222,13 @@ app.whenReady().then(async () => {
   }
 
   // Start the Python backend
-  backendProcess = await startBackend();
+  if (shutdownStarted) return;
+  backendStarting = startBackend();
+  backendProcess = await backendStarting;
+  if (shutdownStarted) {
+    console.log("[main] Quit during startup — not opening the window");
+    return;
+  }
 
   // Create the window (hidden until ready-to-show)
   createWindow();
@@ -1125,7 +1242,7 @@ app.whenReady().then(async () => {
   // Any failure here is logged and swallowed — the app continues to run
   // even if auto-update is unavailable.
   try {
-    autoUpdater.init(mainWindow);
+    autoUpdater.init(mainWindow, { confirmRestart: confirmUpdateRestart });
   } catch (err) {
     console.error(
       "[main] Failed to init auto-updater:",
@@ -1169,18 +1286,12 @@ app.whenReady().then(async () => {
     }
   }
 
-  app.on("activate", 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) {
-      createWindow();
-      // Re-wire existing services to the new window (don't re-create — IPC handlers are already registered)
-      if (agentProcessManager) agentProcessManager.mainWindow = mainWindow;
-      if (trayManager) trayManager.mainWindow = mainWindow;
-      if (notificationService) notificationService.mainWindow = mainWindow;
-      try {
-        await loadApp();
-      } catch (err) {
-        console.error("[main] Failed to load app on activate:", err.message);
-      }
+      reopenWindow();
     } else if (mainWindow) {
       mainWindow.show();
     }
@@ -1215,33 +1326,57 @@ app.on("window-all-closed", () => {
 // Electron's before-quit does NOT await async handlers.
 // We use will-quit + event.preventDefault() to perform async cleanup, then re-quit.
 
-let cleanupDone = false;
-
-app.on("before-quit", () => {
-  isQuitting = true;
-  // Mark any subsequent backend exit as intentional so we don't pop the
-  // crash dialog during normal shutdown.
-  isIntentionalKill = true;
-});
+/** Only while the GAIA service runs: without it, no answer is running. */
+function workCanBeLost() {
+  return Boolean(trayManager && backendProcess);
+}
 
-app.on("will-quit", (event) => {
-  if (cleanupDone) return; // Cleanup already finished, let the app quit
+/** Ask about losing work in front of the window, even when it was hidden in the tray. */
+function askAboutRunningWork(action) {
+  return confirmQuit({
+    action,
+    getWork: () => fetchWorkInProgress(backendPort),
+    showMessageBox: (opts) => {
+      if (!mainWindow || mainWindow.isDestroyed()) return dialog.showMessageBox(opts);
+      if (!mainWindow.isVisible()) mainWindow.show();
+      return dialog.showMessageBox(mainWindow, opts);
+    },
+  });
+}
 
-  event.preventDefault(); // Prevent quit until cleanup is done
-  console.log("[main] will-quit: performing async cleanup...");
+/** The update dialog's "Restart now": the installer starts at once, so ask first. */
+function confirmUpdateRestart() {
+  return workCanBeLost() ? askAboutRunningWork(RESTART_FOR_UPDATE) : Promise.resolve(true);
+}
 
-  cleanup().then(() => {
-    cleanupDone = true;
-    console.log("[main] Cleanup complete, quitting...");
-    app.quit(); // Re-trigger quit — cleanupDone prevents infinite loop
-  }).catch((err) => {
-    console.error("[main] Cleanup error:", err.message);
-    cleanupDone = true;
-    app.quit();
-  });
+// Every quit asks first while an answer or index job would be lost; an
+// update restart (asked in confirmUpdateRestart) and an OS shutdown don't.
+const quitGuard = installQuitGuard({
+  app,
+  updater: electronAutoUpdater,
+  shouldAsk: () => !fatalQuitting && workCanBeLost(),
+  confirm: () => askAboutRunningWork(QUIT),
+  onQuitting: () => {
+    isQuitting = true;
+    // Mark any subsequent backend exit as intentional so we don't pop the
+    // crash dialog during normal shutdown.
+    isIntentionalKill = true;
+  },
+  onError: (err) => {
+    console.error("[main] Quit check failed:", err);
+    dialog.showErrorBox(
+      "GAIA",
+      `GAIA couldn't ask whether to stop the running work: ${err.message}\n\n` +
+        "Quit again within a minute to quit anyway; any answer still being written will be lost."
+    );
+  },
 });
 
+installQuitCleanup({ app, cleanup });
+
 async function cleanup() {
+  shutdownStarted = true;
+
   // Phase F: tear down auto-updater timers and IPC handlers.
   try {
     autoUpdater.destroy();
@@ -1258,24 +1393,48 @@ async function cleanup() {
     notificationService = null;
   }
 
-  // Stop all managed OS agents gracefully
-  if (agentProcessManager) {
-    console.log("Stopping all managed agents...");
-    try {
-      await agentProcessManager.stopAll();
-    } catch (err) {
-      console.error("Error stopping agents:", err.message);
-    }
-    agentProcessManager = null;
+  if (keepAwake) {
+    keepAwake.destroy();
+    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()]);
+
   // Destroy tray icon
   if (trayManager) {
     trayManager.destroy();
     trayManager = null;
   }
+}
+
+async function stopAgentsForQuit() {
+  if (!agentProcessManager) return;
+  console.log("Stopping all managed agents...");
+  try {
+    await agentProcessManager.stopAll();
+  } catch (err) {
+    console.error("Error stopping agents:", err.message);
+  }
+  agentProcessManager = null;
+}
+
+async function stopBackendForQuit() {
+  // A quit during startup: wait for the spawn so it can be stopped below.
+  if (backendStarting) {
+    try {
+      const started = await backendStarting;
+      if (started && !backendProcess && started.exitCode === null && started.signalCode === null) {
+        backendProcess = started;
+      }
+    } catch (err) {
+      console.error("[main] Backend start failed during quit:", err.message);
+    }
+  }
 
-  // Stop the Python backend via the port-manager (SIGTERM → wait 3 s → SIGKILL).
+  // Stop the Python backend and everything it started via the port-manager
+  // (SIGTERM → wait 3 s → SIGKILL).
   // F5: previously we did this inline; extracted so main.cjs stays lean and
   // to prevent orphan leaks across runs (issue #782).
   if (backendProcess) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/agent-ui",
-  "version": "0.25.0",
+  "version": "0.25.1-rc.1",
   "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",
@@ -59,12 +59,14 @@
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:visual": "vite build && playwright test -c visual/playwright.config.ts",
     "gen:api-types": "node scripts/gen-api-types.mjs"
   },
   "dependencies": {
     "electron-updater": "^6.8.3"
   },
   "devDependencies": {
+    "@playwright/test": "1.63.0",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/preload.cjs

@@ -14,6 +14,7 @@
  *   install:*        — First-run backend install progress (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)
  */
 
 const { contextBridge, ipcRenderer } = require("electron");
@@ -53,6 +54,10 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
   tray: {
     getConfig: () => ipcRenderer.invoke("tray:get-config"),
     setConfig: (cfg) => ipcRenderer.invoke("tray:set-config", cfg),
+    // What GAIA is doing, for the tray icon, tooltip and menu.
+    setActivity: (activity) => ipcRenderer.invoke("tray:set-activity", activity),
+    // Tray menu actions: open-chat, new-chat, open-settings, refresh-status.
+    onCommand: (cb) => onEvent("tray:command", cb),
     onNavigate: (cb) => onEvent("tray:navigate", cb),
   },
 
@@ -63,6 +68,16 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
     respondPermission: (id, action, remember) =>
       ipcRenderer.invoke("notification:respond", id, action, remember),
     onNotification: (cb) => onEvent("notification:new", cb),
+    // Chat alerts (#5226)
+    show: (payload) => ipcRenderer.invoke("notification:show", payload),
+    flash: () => ipcRenderer.invoke("notification:flash"),
+    setAttentionCount: (count) =>
+      ipcRenderer.invoke("notification:attention", count),
+  },
+
+  // ── Keep the PC awake while GAIA works (#5226) ────────────────────────
+  power: {
+    setKeepAwake: (on) => ipcRenderer.invoke("power:keep-awake", on),
   },
 
   // ── System metrics for the observability dashboard (#2007) ────────────
@@ -71,6 +86,15 @@ contextBridge.exposeInMainWorld("gaiaAPI", {
   },
 });
 
+// ── Window frame ─────────────────────────────────────────────────────────
+// The app draws its own top row; this says how the native controls sit in it.
+contextBridge.exposeInMainWorld("gaiaWindow", {
+  /** "mac": traffic lights at the top left; "overlay": controls at the top right. */
+  titleBar: process.platform === "darwin" ? "mac" : "overlay",
+  /** Match the native window controls to the app: { color, symbolColor } as #rrggbb. */
+  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