@amd-gaia/agent-ui 0.17.4 → 0.17.6

package/main.cjs

@@ -17,13 +17,47 @@ const { app, BrowserWindow, dialog, shell } = require("electron");
 const path = require("path");
 const fs = require("fs");
 const os = require("os");
-const { spawn } = require("child_process");
+const { spawn, spawnSync } = require("child_process");
+const { pathToFileURL } = require("url");
+
+// ── Shared log path ───────────────────────────────────────────────────────────
+// Single source of truth used by installSafetyNet AND installMainLogTee so
+// both write to the same file without independent path computations that
+// could drift apart.
+const _GAIA_DIR = path.join(os.homedir(), ".gaia");
+const _MAIN_LOG_PATH = path.join(_GAIA_DIR, "electron-main.log");
+
+// ── Safety net (issue #934) ───────────────────────────────────────────────────
+// Install top-level error handlers BEFORE any service module is required so
+// that synchronous throws at module-load time are caught and shown as a
+// GAIA-branded error box instead of Electron's bare JS-error dialog.
+// Extracted into main-safety-net.cjs so tests can require it without
+// triggering main.cjs side effects (Electron modules, service requires).
+// Wrapped in try/catch: a corrupt ASAR or bad path would otherwise bypass the
+// very handler we are trying to install, falling through to Electron's bare
+// JS-error dialog.
+let installSafetyNet, installLogTee, _fatalHandler;
+try {
+  ({ installSafetyNet, installLogTee } = require("./main-safety-net.cjs"));
+  ({ fatal: _fatalHandler } = installSafetyNet({
+    logPath: _MAIN_LOG_PATH,
+    dialogModule: dialog,
+    appModule: app,
+  }));
+} catch (err) {
+  try { process.stderr.write(`[main] safety-net load failed: ${err.message}\n`); } catch { }
+  try { dialog.showErrorBox("GAIA failed to start", String((err && err.stack) || err)); } catch { }
+  // Synchronous exit: service module requires below have no uncaughtException
+  // handler installed, so execution cannot safely continue.
+  process.exit(1);
+}
 
 // Services (loaded after app.whenReady)
 const TrayManager = require("./services/tray-manager.cjs");
 const AgentProcessManager = require("./services/agent-process-manager.cjs");
 const NotificationService = require("./services/notification-service.cjs");
 const PortManager = require("./services/port-manager.cjs");
+const { buildIndexQuery } = require("./services/index-query.cjs");
 const backendInstaller = require("./services/backend-installer.cjs");
 const installerProgressDialog = require("./services/backend-installer-progress-dialog.cjs");
 const autoUpdater = require("./services/auto-updater.cjs");
@@ -52,9 +86,8 @@ if (process.platform === "linux") {
 // diagnostics bundler has something to attach.
 (function installMainLogTee() {
   try {
-    const gaiaDir = path.join(os.homedir(), ".gaia");
-    try { fs.mkdirSync(gaiaDir, { recursive: true }); } catch { /* ignore */ }
-    const logPath = path.join(gaiaDir, "electron-main.log");
+    try { fs.mkdirSync(_GAIA_DIR, { recursive: true }); } catch { /* ignore */ }
+    const logPath = _MAIN_LOG_PATH;
 
     // Rotate if > 5 MB — truncate to last ~5 MB on startup.
     try {
@@ -80,6 +113,10 @@ if (process.platform === "linux") {
     }
 
     const stream = fs.createWriteStream(logPath, { flags: "a" });
+    // Root-cause fix for #934: stream.write() after end emits 'error'
+    // asynchronously — the try/catch in wrap() below doesn't catch it.
+    // This listener absorbs the event before it becomes uncaughtException.
+    installLogTee({ stream, logPath });
     stream.write(
       `\n──── electron-main opened (${new Date().toISOString()}) pid=${process.pid} ────\n`
     );
@@ -155,6 +192,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;
+
 /** @type {TrayManager | null} */
 let trayManager = null;
 
@@ -206,6 +248,70 @@ async function startBackend() {
     backendPort = DEFAULT_BACKEND_PORT;
   }
   healthCheckUrl = `http://localhost:${backendPort}/api/health`;
+  // Clean up any stale backend PID left from previous runs. The AppImage
+  // may be double-clicked multiple times or crash, leaving orphaned
+  // backend processes. We store a PID file under ~/.gaia/backend.pid and
+  // attempt to SIGTERM any still-running PID before starting a new backend.
+  try {
+    const pidFile = path.join(_GAIA_DIR, "backend.pid");
+    if (fs.existsSync(pidFile)) {
+      try {
+        const existingPid = parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+        if (!Number.isNaN(existingPid)) {
+          console.log(`[main] Found existing backend pidfile (${existingPid}) — verifying process identity`);
+
+          // Verify the PID belongs to a GAIA backend before signalling it.
+          // Prefer a conservative match on the process command to avoid
+          // accidentally killing unrelated user processes (TOCTOU mitigation).
+          let isBackend = false;
+          try {
+            if (process.platform === "linux") {
+              const procCmd = `/proc/${existingPid}/cmdline`;
+              if (fs.existsSync(procCmd)) {
+                const raw = fs.readFileSync(procCmd, "utf8");
+                // /proc/<pid>/cmdline is NUL-separated; use a stricter match to
+                // avoid killing unrelated Python processes (Jupyter, LSP, etc.).
+                // Legitimate backend uses: `gaia chat --ui --ui-port <port>`
+                const looksLikeGaiaBackend = raw.includes("gaia") && (raw.includes("chat") || raw.includes("--ui-port"));
+                if (looksLikeGaiaBackend) {
+                  isBackend = true;
+                }
+              }
+            } else if (process.platform === "darwin") {
+              try {
+                const out = spawnSync("ps", ["-p", String(existingPid), "-o", "command="], { encoding: "utf8" });
+                const cmd = (out && out.stdout) ? out.stdout : "";
+                const looksLikeGaiaBackend = cmd.includes("gaia") && (cmd.includes("chat") || cmd.includes("--ui-port"));
+                if (looksLikeGaiaBackend) {
+                  isBackend = true;
+                }
+              } catch {
+                // fallthrough
+              }
+            }
+          } catch (err) {
+            console.warn(`[main] Could not verify pid ${existingPid}: ${err.message}`);
+          }
+
+          if (!isBackend) {
+            console.log(`[main] PID ${existingPid} does not appear to be a GAIA backend; skipping kill`);
+          } else {
+            try {
+              await portManager.killBackend(existingPid);
+              console.log(`[main] Cleaned up previous backend pid ${existingPid}`);
+            } catch (err) {
+              console.warn(`[main] Could not clean previous backend pid ${existingPid}: ${err.message}`);
+            }
+          }
+        }
+      } catch (err) {
+        console.warn(`[main] Failed reading backend pidfile: ${err.message}`);
+      }
+      try { fs.unlinkSync(pidFile); } catch { /* ignore */ }
+    }
+  } catch (err) {
+    console.warn(`[main] PID cleanup check failed: ${err.message}`);
+  }
 
   console.log(`Starting backend: ${gaiaCmd} chat --ui --ui-port ${backendPort}`);
 
@@ -248,6 +354,18 @@ async function startBackend() {
     console.error("Failed to start backend:", err.message);
   });
 
+  // Write a PID file so subsequent AppImage launches can detect and
+  // cleanup this backend if it becomes orphaned. The pidfile is removed
+  // when the child exits.
+  try {
+    try { fs.mkdirSync(_GAIA_DIR, { recursive: true }); } catch { /* ignore */ }
+    const pidFile = path.join(_GAIA_DIR, "backend.pid");
+    fs.writeFileSync(pidFile, String(child.pid), { mode: 0o600 });
+    console.log(`[main] Wrote backend pidfile ${pidFile} (pid=${child.pid})`);
+  } catch (err) {
+    console.warn(`[main] Could not write backend pidfile: ${err.message}`);
+  }
+
   child.on("exit", (code, signal) => {
     if (code !== 0 && code !== null) {
       console.error(`Backend exited with code ${code} (signal=${signal})`);
@@ -259,6 +377,20 @@ async function startBackend() {
       // Fire-and-forget — don't block the event loop.
       void handleBackendCrash(code, signal);
     }
+
+    // Remove pidfile on exit to avoid leaving stale PID behind.
+    try {
+      const pidFile = path.join(_GAIA_DIR, "backend.pid");
+      if (fs.existsSync(pidFile)) {
+        const p = fs.readFileSync(pidFile, "utf8").trim();
+        if (p && parseInt(p, 10) === child.pid) {
+          try { fs.unlinkSync(pidFile); } catch { /* ignore */ }
+        }
+      }
+    } catch (err) {
+      // Non-fatal — just log and continue.
+      console.warn(`[main] Failed to remove backend pidfile: ${err.message}`);
+    }
   });
 
   return child;
@@ -421,13 +553,18 @@ async function loadApp() {
     // http://localhost:4200/ would show raw JSON instead of the UI.
     //
     // Pass the real backend base URL as a query parameter so the renderer
-    // can reach whatever random port port-manager picked (see #851).
-    // Without this, the compiled bundle falls back to its hardcoded
-    // `http://localhost:4200/api` and every API call 404s.
+    // can reach whatever random port port-manager picked (see #851). The
+    // 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 apiBase = `http://127.0.0.1:${backendPort}/api`;
-    console.log("Loading app from:", indexPath, "api:", apiBase);
-    await mainWindow.loadFile(indexPath, { query: { api: apiBase } });
+    const indexQuery = buildIndexQuery(backendPort);
+    console.log("Loading app from:", indexPath, "api:", indexQuery.api);
+    // 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.
+    const fileUrl = pathToFileURL(indexPath);
+    fileUrl.search = new URLSearchParams(indexQuery).toString();
+    await mainWindow.loadURL(fileUrl.href);
   } else {
     // Show a simple loading/error page
     mainWindow.loadURL(
@@ -673,6 +810,7 @@ app.whenReady().then(async () => {
 
   // Create the window (hidden until ready-to-show)
   createWindow();
+  isBootstrapping = false; // progress dialog is gone; window-all-closed may now quit
 
   // Initialize services (tray, agent manager, notifications)
   initializeServices();
@@ -736,11 +874,21 @@ app.whenReady().then(async () => {
       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).
+  _fatalHandler(err);
 });
 
 // ── 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amd-gaia/agent-ui",
-  "version": "0.17.4",
+  "version": "0.17.6",
   "type": "module",
   "productName": "GAIA Agent UI",
   "description": "Privacy-first agentic AI interface with document Q&A - runs 100% locally on AMD Ryzen AI",
@@ -35,6 +35,7 @@
     "bin/",
     "dist/",
     "main.cjs",
+    "main-safety-net.cjs",
     "preload.cjs",
     "services/",
     "assets/",

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

@@ -345,55 +345,89 @@ async function showFailureDialog(parentWindow, errorInfo = {}) {
     .filter(Boolean)
     .join("\n");
 
-  const result = await dialog.showMessageBox(parentWindow || null, {
-    type: "error",
-    title: "GAIA install failed",
-    message,
-    detail,
-    buttons: [
-      "Retry",
-      "Manual install instructions",
-      "Copy log path",
-      "Open log file",
-      "Quit",
-    ],
-    defaultId: 0,
-    cancelId: 4,
-    noLink: true,
-  });
-
-  switch (result.response) {
-    case 0:
-      return "retry";
-    case 1: {
-      try {
-        await shell.openExternal("https://amd-gaia.ai/quickstart#cli-install");
-      } catch {
-        // ignore
+  // 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",
+  ];
+
+  // Helper to show the dialog and handle the response.
+  const show = async () => {
+    const result = await dialog.showMessageBox(parentWindow || null, {
+      type: "error",
+      title: "GAIA install failed",
+      message,
+      detail,
+      buttons,
+      defaultId: 0,
+      cancelId: buttons.length - 1,
+      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();
+        try {
+          await installer.ensureBackend({ onProgress, isPackaged: true });
+          try { close(); } catch {}
+          return "retry";
+        } catch (err) {
+          try { close(); } catch {}
+          const nextInfo = Object.assign({}, errorInfo, {
+            message: err.message || String(err),
+            stage: err.stage || "ensure-backend",
+            suggestion: err.suggestion || errorInfo.suggestion,
+          });
+          return showFailureDialog(parentWindow, nextInfo);
+        }
       }
-      return "manual";
-    }
-    case 2: {
-      try {
-        clipboard.writeText(logPath);
-      } catch {
-        // ignore
+      case 1:
+        return "retry";
+      case 2: {
+        try {
+          await shell.openExternal("https://amd-gaia.ai/quickstart#cli-install");
+        } catch {
+          // ignore
+        }
+        return "manual";
       }
-      // Keep the user in the loop — re-show the dialog so they can pick an action.
-      return showFailureDialog(parentWindow, errorInfo);
-    }
-    case 3: {
-      try {
-        await shell.openPath(logPath);
-      } catch {
-        // ignore
+      case 3: {
+        try {
+          clipboard.writeText(logPath);
+        } catch {
+          // ignore
+        }
+        return showFailureDialog(parentWindow, errorInfo);
+      }
+      case 4: {
+        try {
+          await shell.openPath(logPath);
+        } catch {
+          // ignore
+        }
+        return showFailureDialog(parentWindow, errorInfo);
       }
-      return showFailureDialog(parentWindow, errorInfo);
+      case 5:
+      default:
+        return "quit";
     }
-    case 4:
-    default:
-      return "quit";
-  }
+  };
+
+  return show();
 }
 
 // ── Pre-check failure dialogs ───────────────────────────────────────────────

package/services/backend-installer.cjs

@@ -77,10 +77,28 @@ const NETWORK_CHECK_TIMEOUT_MS = 5000;
 // archive against upstream's published .sha256, then extracts the `uv` binary
 // which is what `ensureUv()` hashes at runtime.
 //
-// Currently pinned: uv v0.5.14 linux-x64.
+// Currently pinned: uv v0.5.14 linux-x64, mac-arm64.
+// (win-x64 deferred to a follow-up issue — its SHA must ship together with an
+// NSIS structural-smoke verifier, not on its own; see the #849 lesson.)
+//
+// IMPORTANT: per-platform SHA origin differs:
+//   - linux-x64:  raw extracted-from-tarball digest (no post-build modification).
+//   - mac-arm64:  POST-CODESIGN digest. electron-builder code-signs the bundled
+//                 uv during packaging, so this hash matches what ensureUv() sees
+//                 at runtime, NOT the upstream tarball. Bumping this pin means
+//                 running the CI build, then copying the SHA from the
+//                 dmg-structural-smoke failure message — never from `shasum`
+//                 against the freshly downloaded tarball.
 const BUNDLED_UV_VERSION = "0.5.14";
 const BUNDLED_UV_SHA256 = {
   "linux-x64": "0e05d828b5708e8a927724124db3746396afddad6273c47283d7c562dc795bd6",
+  // The Windows extracted uv.exe SHA is populated by CI during the
+  // build step. The placeholder MUST be replaced in CI before packaging
+  // so runtime verification remains strict.
+  "win-x64": "055d55eec85a91cfb5e9c8bc7f6463f9883866796c5bcb205fbcdfed9c088c88",
+  // mac-arm64: POST-codesign digest. CI should populate this value when
+  // packaging the macOS DMG and running the dmg-structural-smoke job.
+  "mac-arm64": "6099aa8cd701f0c81227ee30c304777ce151e4d47c53a75ce53cd2243448d8c8",
 };
 
 const MANAGED_UV_DIR = path.join(GAIA_HOME, "bin");
@@ -697,9 +715,12 @@ function findBundledUvResource() {
  */
 async function installBundledUv(sourcePath, platformKey) {
   const expected = BUNDLED_UV_SHA256[platformKey];
-  if (!expected) {
+  if (!expected || expected.startsWith("<")) {
+    // Enforce strict verification: builds MUST populate the expected SHA
+    // for packaged binaries. Failing fast prevents shipping an unverified
+    // uv binary which would be a supply-chain regression.
     throw new InstallError(
-      `No bundled uv checksum registered for platform ${platformKey}.`,
+      `No bundled uv checksum registered for platform ${platformKey}. Build must populate BUNDLED_UV_SHA256.${platformKey}`,
       { stage: STAGES.ENSURE_UV }
     );
   }
@@ -741,16 +762,20 @@ async function installBundledUv(sourcePath, platformKey) {
     );
   }
 
-  if (actual !== expected) {
-    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
-    throw new InstallError(
-      `Bundled uv SHA256 mismatch (expected ${expected}, got ${actual}).`,
-      {
-        stage: STAGES.ENSURE_UV,
-        suggestion:
-          "The AppImage/installer may be corrupt. Re-download from https://amd-gaia.ai and try again.",
-      }
-    );
+  if (expected) {
+    if (actual !== expected) {
+      try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+      throw new InstallError(
+        `Bundled uv SHA256 mismatch (expected ${expected}, got ${actual}).`,
+        {
+          stage: STAGES.ENSURE_UV,
+          suggestion:
+            "The AppImage/installer may be corrupt. Re-download from https://amd-gaia.ai and try again.",
+        }
+      );
+    }
+  } else {
+    log("No expected SHA registered for bundled uv; installed binary will not be verified locally.");
   }
 
   try {
@@ -836,6 +861,10 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
 
     // Verify the source resource matches the manifest before copying —
     // catches AppImage corruption before we touch the user's home.
+    // Enforce that the packaged build provides an expected SHA for the
+    // bundled resource. CI replaces the placeholder with the extracted
+    // binary's SHA during the build; missing/placeholder values are a
+    // build-time error and are rejected at runtime here.
     const srcHash = await sha256File(bundled);
     if (srcHash !== expectedSha) {
       throw new InstallError(
@@ -925,6 +954,52 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
     return;
   }
 
+  // Packaged Windows rescue: try the Astral PowerShell installer even when
+  // running a packaged build. This provides an automated recovery path for
+  // end users on clean machines that don't have uv and where the installer
+  // build unexpectedly omitted a bundled binary. It is a last-resort and
+  // non-fatal attempt; on failure we fall through to the generic error.
+  if (IS_WINDOWS && !isDev) {
+    log("Packaged Windows: attempting automated uv installer (rescue)");
+    try {
+      const rescue = await runCommand(
+        "powershell",
+        [
+          "-ExecutionPolicy",
+          "Bypass",
+          "-Command",
+          "irm https://astral.sh/uv/install.ps1 | iex",
+        ],
+        { stageLabel: "uv-install-packaged-rescue" }
+      );
+      if (rescue.code === 0) {
+        // Ensure common install locations are present on PATH for this
+        // process in case the installer placed uv in a user-local bin.
+        const candidates = [
+          path.join(os.homedir(), ".local", "bin"),
+          path.join(os.homedir(), ".cargo", "bin"),
+        ];
+        for (const uvDir of candidates) {
+          if (process.env.PATH && !process.env.PATH.includes(uvDir)) {
+            process.env.PATH = `${uvDir}${path.delimiter}${process.env.PATH}`;
+            log(`Added ${uvDir} to PATH for this process`);
+          }
+        }
+        if (commandExists("uv")) {
+          log("Packaged Windows: uv installed and found on PATH (rescue succeeded)");
+          addManagedBinToPath();
+          report(STAGES.ENSURE_UV, 100, "uv ready (system, unverified)");
+          return;
+        }
+        log("Packaged Windows: uv installer ran but uv not found on PATH");
+      } else {
+        log(`Packaged Windows: automated uv installer exited ${rescue.code}`);
+      }
+    } catch (rescueErr) {
+      log(`Packaged Windows: rescue installer threw: ${rescueErr.message}`);
+    }
+  }
+
   // Packaged build, but we somehow don't have a bundled binary for this
   // platform AND no system uv. Last-ditch: accept an unverified system uv
   // if present; otherwise fail with a clear message.
@@ -937,11 +1012,11 @@ async function ensureUv({ onProgress, isPackaged } = {}) {
   }
 
   throw new InstallError(
-    `No bundled uv available for ${process.platform}-${process.arch} and no system uv found.`,
+    `GAIA could not find or install its Python helper (uv) required to provision the backend.`,
     {
       stage: STAGES.ENSURE_UV,
       suggestion:
-        "Install uv manually from https://astral.sh/uv and re-launch GAIA.",
+        "GAIA attempted automatic recovery but could not install uv. Please either: (a) click 'Install uv' in the dialog to let GAIA try again, or (b) install uv from https://astral.sh/uv and re-launch GAIA.",
     }
   );
 }
@@ -1135,6 +1210,46 @@ async function installBackend(opts = {}) {
   log(`Verified gaia binary: ${verifiedBin} (version=${installedVersion || "unknown"})`);
   report(STAGES.VERIFY, 100, "Install verified");
 
+  // Ensure a user-accessible shim is created so users who installed via
+  // AppImage can run `gaia` from a terminal without manually adding the
+  // venv bin directory to their PATH. Do not overwrite an existing system
+  // `gaia` or an existing shim the user may have created.
+  try {
+    // Only create shims on POSIX-like systems (AppImage target).
+    if (process.platform !== "win32") {
+      const userBin = process.env.XDG_BIN_HOME || path.join(os.homedir(), ".local", "bin");
+      const shimPath = path.join(userBin, "gaia");
+
+      // Only create a shim if there's no `gaia` already on PATH and no shim
+      // at the target location. This avoids clobbering system packages.
+      if (!commandExists("gaia") && !fs.existsSync(shimPath)) {
+        try {
+          // Basic sanity-check on the target path to avoid writing a
+          // wrapper that could execute an arbitrary command. The
+          // verifiedBin is produced by our installer and is expected to be
+          // a normal filesystem path (alphanum, dash, dot, slash, underscore).
+          if (!/^[\w\-./]+$/.test(verifiedBin)) {
+            log(`Refusing to create shim: verified bin path looks suspicious: ${verifiedBin}`);
+          } else {
+            fs.mkdirSync(userBin, { recursive: true });
+            const wrapper = `#!/bin/sh\nexec \"${verifiedBin}\" \"$@\"\n`;
+            fs.writeFileSync(shimPath, wrapper, { mode: 0o755 });
+            log(`Created user shim at ${shimPath} pointing to ${verifiedBin}`);
+          }
+        } catch (err) {
+          log(`Could not create user shim at ${shimPath}: ${err.message}`);
+        }
+      } else if (fs.existsSync(shimPath)) {
+        log(`User shim already exists at ${shimPath}; leaving it intact`);
+      } else {
+        log("A system 'gaia' binary was found on PATH; skipping shim creation");
+      }
+    }
+  } catch (err) {
+    // Non-fatal: proceed even if shim creation fails.
+    log(`Shim creation check failed: ${err.message}`);
+  }
+
   setState(STATES.READY, { stage: null, version, installedVersion });
   log("Backend install complete");
 }

package/services/index-query.cjs

@@ -0,0 +1,49 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * index-query.cjs — Build the `?api=` query object that main.cjs hands
+ * to BrowserWindow.loadFile() so the renderer can reach the random
+ * backend port that PortManager picked.
+ *
+ * Extracted from main.cjs (issue #851) so it can be unit-tested without
+ * an Electron runtime. Pure CommonJS, no Node built-ins required, no
+ * Electron imports.
+ *
+ * Contract: this module must stay in sync with the TRUSTED_API_RE
+ * allowlist in src/gaia/apps/webui/src/utils/apiBase.ts. The renderer
+ * rejects any value that does not match that regex, so the URL produced
+ * here MUST satisfy `/^https?:\/\/(127\.0\.0\.1|localhost):\d+\/api$/`.
+ *
+ * The cross-file invariant is enforced by tests/electron/test_loadapp_query.mjs.
+ */
+
+"use strict";
+
+/** Path the backend serves its API under. Shared so a future change is one edit. */
+const API_PATH = "/api";
+
+/**
+ * Build the loadFile query object for a given backend port.
+ *
+ * @param {number} port - Integer in (0, 65535]. Typically chosen by
+ *   PortManager.findFreePort(); falls back to DEFAULT_BACKEND_PORT (4200)
+ *   in main.cjs if findFreePort fails.
+ * @returns {{api: string}} - Object passed as `loadFile(..., { query })`.
+ *   Electron URL-encodes the values; the renderer reads them back via
+ *   `URLSearchParams(window.location.search).get('api')`.
+ * @throws {Error} - If port is not a valid integer in (0, 65535].
+ */
+function buildIndexQuery(port) {
+  if (
+    typeof port !== "number" ||
+    !Number.isInteger(port) ||
+    port <= 0 ||
+    port > 65535
+  ) {
+    throw new Error(`buildIndexQuery: invalid port ${port}`);
+  }
+  return { api: `http://127.0.0.1:${port}${API_PATH}` };
+}
+
+module.exports = { buildIndexQuery, API_PATH };