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

package/services/backend-installer.cjs

@@ -55,8 +55,8 @@ const GAIA_PYTHON_BIN = IS_WINDOWS
 const STATE_FILE = path.join(GAIA_HOME, "electron-install-state.json");
 const LOG_FILE = path.join(GAIA_HOME, "electron-install.log");
 
-// 5 GB — PyTorch wheels have grown significantly and `gaia init` downloads
-// additional model data on first run; 3 GB is no longer enough headroom.
+// Floor for uv, Python and the GAIA package only. The models, often 30 GB,
+// are checked by `gaia init` against Lemonade's model store, which it sizes.
 const MIN_DISK_SPACE_BYTES = 5 * 1024 * 1024 * 1024; // 5 GB
 const NETWORK_CHECK_HOSTS = Object.freeze([
   "https://pypi.org/simple/",
@@ -135,6 +135,12 @@ const STAGES = Object.freeze({
   VERIFY: "verify",
 });
 
+const GAIA_INIT_MESSAGE =
+  "Setting up Lemonade Server and downloading models (this can take several minutes)";
+const WAITING_FOR_LEMONADE_CHOICE_MESSAGE =
+  "Waiting for your answer: GAIA found a Lemonade Server already running " +
+  "and is asking whether to use it. Setup continues once you choose.";
+
 // Weight each stage contributes to the overall 0-100 progress.
 // Sum must equal 100.
 const STAGE_WEIGHTS = {
@@ -399,6 +405,148 @@ function makeProgressReporter(onProgress) {
   };
 }
 
+// ── gaia init progress (`gaia init --progress-json`) ─────────────────────────
+
+// Where the plan and the end of the downloads land in the GAIA_INIT slice; the
+// rest of the slice is Lemonade setup before and verification after.
+const INIT_PLAN_PERCENT = 5;
+const INIT_DOWNLOADED_PERCENT = 95;
+
+/**
+ * Read one line of `gaia init --progress-json` output. Returns `{ event }` for
+ * a progress event, `{ error }` for a line that looks like one but is not, and
+ * null for human output.
+ */
+function parseInitEventLine(line) {
+  const text = String(line || "").trim();
+  if (!text.startsWith("{")) return null;
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (err) {
+    return { error: err.message };
+  }
+  if (!value || typeof value !== "object" || typeof value.event !== "string") {
+    return { error: 'no "event" field' };
+  }
+  return { event: value };
+}
+
+function formatGB(bytes) {
+  return `${(Math.max(0, bytes || 0) / 1e9).toFixed(1)} GB`;
+}
+
+function formatSpeed(bytesPerSecond) {
+  return `${(bytesPerSecond / 1e6).toFixed(1)} MB/s`;
+}
+
+function formatTimeLeft(seconds) {
+  if (seconds < 60) return "less than a minute left";
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `about ${minutes} min left`;
+  return `about ${Math.floor(minutes / 60)} h ${minutes % 60} min left`;
+}
+
+/**
+ * Map `gaia init --progress-json` events onto the GAIA_INIT slice of the bar.
+ * `report(withinStagePercent, message)` receives a percent that never goes
+ * back. `onLine` returns true for the lines too frequent to log.
+ */
+function createInitProgress(report, logFn = log) {
+  const models = new Map();
+  let percent = 0;
+
+  const advance = (within, message) => {
+    percent = Math.max(percent, Math.round(within));
+    report(percent, message);
+  };
+  const totals = () => {
+    let done = 0;
+    let total = 0;
+    for (const m of models.values()) {
+      total += m.total;
+      done += Math.min(m.done, m.total);
+    }
+    return { done, total };
+  };
+  const downloadPercent = () => {
+    const { done, total } = totals();
+    const share = total > 0 ? done / total : 0;
+    return INIT_PLAN_PERCENT + (INIT_DOWNLOADED_PERCENT - INIT_PLAN_PERCENT) * share;
+  };
+  const model = (id) => {
+    if (!models.has(id)) models.set(id, { done: 0, total: 0 });
+    return models.get(id);
+  };
+
+  function handle(event) {
+    switch (event.event) {
+      case "step":
+        advance(percent, `Step ${event.step} of ${event.total}: ${event.message}`);
+        return true;
+      case "plan":
+        for (const m of event.models || []) {
+          if (!m.downloaded) model(m.id).total = m.bytes_total || 0;
+        }
+        advance(
+          INIT_PLAN_PERCENT,
+          event.bytes_total > 0
+            ? `Downloading ${formatGB(event.bytes_total)} of models`
+            : "Models already downloaded"
+        );
+        return true;
+      case "progress": {
+        const m = model(event.model);
+        m.done = event.bytes_done || 0;
+        m.total = Math.max(event.bytes_total || 0, m.done);
+        const parts = [
+          `Downloading ${event.model} (${event.index} of ${event.count}): ` +
+            `${formatGB(m.done)} of ${formatGB(m.total)}`,
+        ];
+        if (event.speed_bps > 0) {
+          const { done, total } = totals();
+          parts.push(
+            `at ${formatSpeed(event.speed_bps)}, ` +
+              formatTimeLeft((total - done) / event.speed_bps)
+          );
+        }
+        advance(downloadPercent(), parts.join(" "));
+        return true;
+      }
+      case "model_done": {
+        const m = model(event.model);
+        m.done = m.total;
+        advance(downloadPercent(), `${event.model} ready`);
+        return true;
+      }
+      case "done":
+        advance(
+          event.ok ? INIT_DOWNLOADED_PERCENT : percent,
+          event.ok ? "Models downloaded, finishing setup" : "Model download did not finish"
+        );
+        return true;
+      case "error":
+        advance(percent, String(event.message || "gaia init reported an error").trim());
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  function onLine(line) {
+    const parsed = parseInitEventLine(line);
+    if (!parsed) return false;
+    if (parsed.error) {
+      logFn(`Malformed gaia init progress line (${parsed.error}): ${line}`);
+      return false;
+    }
+    handle(parsed.event);
+    return parsed.event.event === "progress";
+  }
+
+  return { onLine, handle };
+}
+
 // ── Command helpers ──────────────────────────────────────────────────────────
 
 /**
@@ -430,8 +578,11 @@ function findGaiaBin() {
 /**
  * Run a child process and stream output to the log file in real time.
  * Returns a Promise that resolves with { code, stdout, stderr }.
+ *
+ * `onLine(line)` sees each whole stdout line as it arrives; a line it returns
+ * true for is left out of the log.
  */
-function runCommand(cmd, args, { env, stageLabel } = {}) {
+function runCommand(cmd, args, { env, stageLabel, onLine } = {}) {
   return new Promise((resolve) => {
     log(`$ ${cmd} ${args.join(" ")}`);
     let proc;
@@ -451,14 +602,42 @@ function runCommand(cmd, args, { env, stageLabel } = {}) {
 
     let stdout = "";
     let stderr = "";
+    let partial = "";
+    const logLine = (line) => {
+      if (line) log(`  ${stageLabel ? `[${stageLabel}] ` : ""}${line}`);
+    };
+    // An in-place progress bar redraws with \r, so each redraw is its own segment.
+    const takeLine = (line) => {
+      let quiet = true;
+      for (const segment of line.split("\r")) {
+        if (!segment) continue;
+        try {
+          quiet = onLine(segment) === true && quiet;
+        } catch (err) {
+          logError(`onLine callback threw: ${err.message}`);
+          quiet = false;
+        }
+      }
+      if (!quiet) logLine(line);
+    };
 
     proc.stdout.on("data", (data) => {
       const chunk = data.toString();
       stdout += chunk;
-      chunk.split(/\r?\n/).forEach((line) => {
-        if (line) log(`  ${stageLabel ? `[${stageLabel}] ` : ""}${line}`);
-      });
+      if (!onLine) {
+        chunk.split(/\r?\n/).forEach(logLine);
+        return;
+      }
+      const lines = (partial + chunk).split(/\r?\n/);
+      partial = lines.pop();
+      lines.forEach(takeLine);
     });
+    if (onLine) {
+      proc.stdout.on("end", () => {
+        if (partial) takeLine(partial);
+        partial = "";
+      });
+    }
 
     proc.stderr.on("data", (data) => {
       const chunk = data.toString();
@@ -1387,37 +1566,52 @@ function shouldSkipGaiaInit(opts) {
  * `chooseLemonade` is asked about a Lemonade Server already running here; see
  * lemonadeInitArgs.
  *
- * Returns "done", "failed" or "skipped". The state file records it: a backend
- * whose setup never finished is not installed, and the next launch runs it.
+ * Returns `{ init }`, "done", "failed" or "skipped", plus `initError` when it
+ * failed. The state file records both: a backend whose setup never finished is
+ * not installed, so the next launch runs it, and the app shows the error.
  */
 async function runGaiaInit(gaiaBin, report, version, skipGaiaInit, chooseLemonade) {
   if (skipGaiaInit) {
     log("Skipping gaia init (skipGaiaInit=true or GAIA_SKIP_GAIA_INIT set)");
-    return "skipped";
+    return { init: "skipped" };
   }
   setState(STATES.INSTALLING, { stage: STAGES.GAIA_INIT, version });
-  report(
-    STAGES.GAIA_INIT,
-    0,
-    "Setting up Lemonade Server and downloading models (this can take several minutes)"
+  report(STAGES.GAIA_INIT, 0, GAIA_INIT_MESSAGE);
+  const lemonadeArgs = await lemonadeInitArgs(gaiaBin, chooseLemonade, runCommand, report);
+  const progress = createInitProgress((within, message) =>
+    report(STAGES.GAIA_INIT, within, message)
   );
-  const lemonadeArgs = await lemonadeInitArgs(gaiaBin, chooseLemonade);
   const initResult = await runCommand(
     gaiaBin,
-    ["init", "--profile", "gaia", "--yes", "--skip-webui-build", ...lemonadeArgs],
-    { stageLabel: "gaia-init" }
+    ["init", "--profile", "gaia", "--yes", "--skip-webui-build", "--progress-json", ...lemonadeArgs],
+    // Unwrapped, so an error line reaches initFailureReason whole.
+    { stageLabel: "gaia-init", env: { ...process.env, COLUMNS: "1000" }, onLine: progress.onLine }
   );
   if (initResult.code !== 0) {
-    // Non-fatal: the app opens and its setup screen retries, and so does the
-    // next launch, because the state file records that setup did not finish.
+    // Non-fatal: the app opens and its start screen shows initError, and the
+    // next launch runs setup again, because the state file records the failure.
     log(
       `Warning: gaia init exited with code ${initResult.code}. Continuing; setup runs again next launch.`
     );
     report(STAGES.GAIA_INIT, 100, "Lemonade Server setup did not finish");
-    return "failed";
+    return { init: "failed", initError: initFailureReason(initResult) };
   }
   report(STAGES.GAIA_INIT, 100, "Lemonade Server setup complete");
-  return "done";
+  return { init: "done" };
+}
+
+/** Why `gaia init` failed, in its own words: its last ❌ line, else its last line. */
+function initFailureReason({ code, stdout, stderr }) {
+  const lines = `${stdout || ""}\n${stderr || ""}`
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    // --progress-json event lines are for the progress bar, not the user.
+    .filter((line) => line && !line.startsWith('{"event"'));
+  const marked = lines.filter((line) => line.startsWith("❌"));
+  const reason = marked.length
+    ? marked[marked.length - 1].replace(/^❌\s*/, "")
+    : lines[lines.length - 1];
+  return reason || `gaia init exited with code ${code} and printed nothing.`;
 }
 
 /**
@@ -1448,8 +1642,11 @@ async function readGaiaJson(run, gaiaBin, args) {
  * `--lemonade-url <url>`, "gaia" adds `--gaia-lemonade`, null adds nothing:
  * init then sets up GAIA's own and prints how to switch, as it always has.
  * A server that needs a key or is too old is left to the app's setup screen.
+ *
+ * `report` is the progress reporter: while the question is open the progress
+ * window says setup is waiting on the user, then goes back to GAIA_INIT_MESSAGE.
  */
-async function lemonadeInitArgs(gaiaBin, chooseLemonade, run = runCommand) {
+async function lemonadeInitArgs(gaiaBin, chooseLemonade, run = runCommand, report = () => {}) {
   if (typeof chooseLemonade !== "function") return [];
   const unchanged = "gaia init will set up GAIA's own Lemonade Server; to use yours later run `gaia lemonade connect <url>`.";
   const status = await readGaiaJson(run, gaiaBin, ["lemonade", "status", "--json"]);
@@ -1469,11 +1666,14 @@ async function lemonadeInitArgs(gaiaBin, chooseLemonade, run = runCommand) {
     return [];
   }
   let answer;
+  report(STAGES.GAIA_INIT, 0, WAITING_FOR_LEMONADE_CHOICE_MESSAGE);
   try {
     answer = await chooseLemonade(found);
   } catch (err) {
     log(`Warning: could not ask whether to use the Lemonade Server at ${found.url}: ${err.message}; ${unchanged}`);
     return [];
+  } finally {
+    report(STAGES.GAIA_INIT, 0, GAIA_INIT_MESSAGE);
   }
   log(`Lemonade Server at ${found.url}: user chose ${answer || "not to answer"}`);
   if (answer === "external") return ["--lemonade-url", found.url];
@@ -1708,7 +1908,7 @@ async function installBackend(opts = {}) {
   report(STAGES.INSTALL_PACKAGE, 100, "GAIA package installed");
 
   // Stage 4: gaia init
-  const init = await runGaiaInit(
+  const setup = await runGaiaInit(
     GAIA_BIN,
     report,
     version,
@@ -1774,7 +1974,7 @@ async function installBackend(opts = {}) {
     log(`Shim creation check failed: ${err.message}`);
   }
 
-  setState(STATES.READY, { stage: null, version, installedVersion, init });
+  setState(STATES.READY, { stage: null, version, installedVersion, ...setup });
   log("Backend install complete");
 }
 
@@ -1914,14 +2114,14 @@ async function ensureBackend(opts = {}) {
             `(state=${prev.state}, stage=${prev.stage || "-"}) — running gaia init`
         );
         const report = makeProgressReporter(opts.onProgress);
-        const init = await runGaiaInit(
+        const setup = await runGaiaInit(
           existingBin,
           report,
           expectedVersion,
           shouldSkipGaiaInit(opts),
           opts.chooseLemonade
         );
-        setState(STATES.READY, { version: expectedVersion, installedVersion, init });
+        setState(STATES.READY, { version: expectedVersion, installedVersion, ...setup });
         report(STAGES.VERIFY, 100, `GAIA ${installedVersion} ready`);
         return existingBin;
       }
@@ -1997,6 +2197,7 @@ module.exports = {
   findGaiaBin,
   toPep440,
   lemonadeInitArgs,
+  initFailureReason,
 
   // Pre-checks
   runPreChecks,
@@ -2015,6 +2216,11 @@ module.exports = {
   setState,
   clearState,
 
+  // gaia init progress
+  parseInitEventLine,
+  createInitProgress,
+  computeOverallPercent,
+
   // Logging
   openLog,
   closeLog,
@@ -2026,6 +2232,8 @@ module.exports = {
   // Constants
   STATES,
   STAGES,
+  GAIA_INIT_MESSAGE,
+  WAITING_FOR_LEMONADE_CHOICE_MESSAGE,
   GAIA_HOME,
   GAIA_VENV,
   GAIA_BIN,

package/services/chromium-switches.cjs

@@ -0,0 +1,29 @@
+// Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Chromium switches main.cjs appends before app.whenReady(). Pure so the
+ * per-platform and per-env choices are testable without launching Electron.
+ */
+
+const TRUTHY = new Set(["1", "true", "yes"]);
+
+function gpuDisabled(env) {
+  return TRUTHY.has(String(env.GAIA_DISABLE_GPU || "").trim().toLowerCase());
+}
+
+/** @returns {Array<[string, string?]>} switch name and optional value, in append order */
+function chromiumSwitches({ platform, env }) {
+  const switches = [];
+  if (platform === "linux") {
+    // chrome-sandbox is stripped by after-pack.cjs, and direct ./AppImage runs skip the .desktop flag (#782).
+    switches.push(["no-sandbox"]);
+    // Partial wp_color_manager support in some Wayland compositors SIGTRAPs Chromium.
+    switches.push(["disable-features", "WaylandColorManagement"]);
+  }
+  // Opt-in escape hatch for GPU stacks whose GPU process aborts at startup (#999).
+  if (gpuDisabled(env)) switches.push(["disable-gpu"]);
+  return switches;
+}
+
+module.exports = { chromiumSwitches, gpuDisabled };

package/services/keep-awake.cjs

@@ -0,0 +1,52 @@
+// Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+/**
+ * Keep the PC from idle-sleeping while GAIA works (#5226).
+ *
+ * The renderer decides when (a turn is running, the setting is on, and the
+ * battery policy allows it) and calls `power:keep-awake`; this service owns
+ * the one powerSaveBlocker. The display may still turn off — only system
+ * sleep is held off.
+ */
+
+const { ipcMain, powerSaveBlocker } = require("electron");
+
+class KeepAwake {
+  constructor() {
+    /** @type {number | null} */
+    this._blockerId = null;
+    ipcMain.handle("power:keep-awake", (_event, on) => this.set(on));
+  }
+
+  /**
+   * @param {boolean} on
+   * @returns {boolean} whether sleep is now being held off.
+   */
+  set(on) {
+    if (typeof on !== "boolean") {
+      throw new TypeError(`power:keep-awake expects a boolean, got ${typeof on}`);
+    }
+    if (on && this._blockerId === null) {
+      this._blockerId = powerSaveBlocker.start("prevent-app-suspension");
+      console.log("[power] Holding off idle sleep while GAIA works");
+    } else if (!on && this._blockerId !== null) {
+      powerSaveBlocker.stop(this._blockerId);
+      this._blockerId = null;
+      console.log("[power] Idle sleep allowed again");
+    }
+    return this.active;
+  }
+
+  /** @returns {boolean} */
+  get active() {
+    return this._blockerId !== null && powerSaveBlocker.isStarted(this._blockerId);
+  }
+
+  destroy() {
+    this.set(false);
+    ipcMain.removeHandler("power:keep-awake");
+  }
+}
+
+module.exports = KeepAwake;

package/services/notification-service.cjs

@@ -314,6 +314,55 @@ class NotificationService extends EventEmitter {
     this._sendToRenderer("tray:navigate", `notification:${notif.id}`);
   }
 
+  // ── Chat alerts ──────────────────────────────────────────────────────
+
+  /**
+   * Show an OS banner for a chat event. Clicking it focuses the window and
+   * opens that chat. Silent: the renderer plays the user's chosen sound.
+   *
+   * @param {{title: string, body: string, sessionId: string}} payload
+   * @returns {boolean} false when the OS has no notification support.
+   */
+  showChatBanner(payload) {
+    if (!payload || typeof payload.title !== "string" || typeof payload.sessionId !== "string") {
+      throw new TypeError("notification:show expects {title, body, sessionId}");
+    }
+    if (!Notification.isSupported()) {
+      console.warn("[notif] OS notifications not supported on this platform");
+      return false;
+    }
+    const osNotif = new Notification({
+      title: payload.title,
+      body: typeof payload.body === "string" ? payload.body : "",
+      icon: path.join(__dirname, "..", "assets", "icon.png"),
+      silent: true,
+    });
+    osNotif.on("click", () => {
+      if (!this.mainWindow || this.mainWindow.isDestroyed()) return;
+      if (this.mainWindow.isMinimized()) this.mainWindow.restore();
+      this.mainWindow.show();
+      this.mainWindow.focus();
+      this._sendToRenderer("tray:navigate", `session:${payload.sessionId}`);
+    });
+    osNotif.show();
+    return true;
+  }
+
+  /**
+   * Flash the taskbar button until the window is focused. A no-op while
+   * it already has focus.
+   * @returns {boolean} whether it flashed.
+   */
+  flashWindow() {
+    const win = this.mainWindow;
+    if (!win || win.isDestroyed() || win.isFocused()) return false;
+    win.flashFrame(true);
+    win.once("focus", () => {
+      if (!win.isDestroyed()) win.flashFrame(false);
+    });
+    return true;
+  }
+
   // ── Private: Tray badge ──────────────────────────────────────────────
 
   _updateTrayBadge() {
@@ -423,6 +472,19 @@ class NotificationService extends EventEmitter {
         this._respondToPermission(notifId, action, remember);
       }
     );
+
+    // Chat alerts (#5226): the renderer decides what fires per the user's
+    // settings; main owns the OS surfaces it can't reach.
+    ipcMain.handle("notification:show", (_event, payload) =>
+      this.showChatBanner(payload)
+    );
+    ipcMain.handle("notification:flash", () => this.flashWindow());
+    ipcMain.handle("notification:attention", (_event, count) => {
+      if (!this.trayManager) {
+        throw new Error("No tray to badge: the tray manager was not created");
+      }
+      this.trayManager.setAttentionCount(count);
+    });
   }
 
   // ── Private: Helpers ─────────────────────────────────────────────────

package/services/port-manager.cjs

@@ -22,6 +22,10 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
+const { killProcessTree } = require("./process-tree.cjs");
+
+const BACKEND_KILL_GRACE_MS = 3000;
+const BACKEND_FORCE_WAIT_MS = 1000;
 
 /**
  * Resolve the GAIA home directory lazily so tests can point it elsewhere
@@ -54,86 +58,29 @@ function findFreePort() {
 }
 
 /**
- * Terminate a spawned backend: SIGTERM, wait up to 3 s, then SIGKILL.
+ * Terminate a spawned backend and everything it started: SIGTERM the tree,
+ * wait up to 3 s, then SIGKILL what is left. Without the tree walk, killing
+ * the uv `gaia.exe` launcher on Windows left its Python running.
  * Accepts either a ChildProcess reference (preferred — lets us
  * short-circuit via `exitCode` so PID reuse can never hit us) or a raw
- * pid (useful for tests). Safe to call with nullish.
+ * pid (the orphan cleanup and tests). Safe to call with nullish.
  */
 async function killBackend(procOrPid, logger) {
   const log = (logger && logger.log) || console.log;
   const logError = (logger && logger.error) || console.error;
-
   if (!procOrPid) return;
-
-  // Distinguish ChildProcess vs raw pid. A ChildProcess has both .pid
-  // and .exitCode/.signalCode; typeof === "object" is enough.
-  const isChildProcess = typeof procOrPid === "object";
-  const proc = isChildProcess ? procOrPid : null;
-  const pid = isChildProcess ? procOrPid.pid : procOrPid;
-
-  if (!pid) return;
-
-  // If we have the ChildProcess handle, trust it — the exitCode is set
-  // synchronously by Node's child_process before any pid reuse could
-  // happen, so this closes the PID-reuse TOCTOU that a pid-only API has.
+  const proc = typeof procOrPid === "object" ? procOrPid : null;
   if (proc && (proc.exitCode !== null || proc.signalCode !== null)) {
-    log(`[port-manager] child pid ${pid} already exited (exitCode=${proc.exitCode} signal=${proc.signalCode})`);
-    return;
-  }
-
-  // Is the process still alive? kill(pid, 0) throws ESRCH if not.
-  // Only relied on when the caller passed a raw pid (tests); callers
-  // with a ChildProcess were already short-circuited above.
-  const alive = (p) => {
-    try {
-      process.kill(p, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  };
-
-  if (!alive(pid)) {
-    log(`[port-manager] pid ${pid} already gone`);
+    log(`[port-manager] child pid ${proc.pid} already exited (exitCode=${proc.exitCode} signal=${proc.signalCode})`);
     return;
   }
-
-  try {
-    process.kill(pid, "SIGTERM");
-    log(`[port-manager] SIGTERM sent to pid ${pid}`);
-  } catch (err) {
-    logError(`[port-manager] SIGTERM failed for pid ${pid}: ${err.message}`);
-    return;
-  }
-
-  const deadline = Date.now() + 3000;
-  while (Date.now() < deadline) {
-    if (!alive(pid)) {
-      log(`[port-manager] pid ${pid} exited after SIGTERM`);
-      return;
-    }
-    await new Promise((r) => setTimeout(r, 100));
-  }
-
-  try {
-    process.kill(pid, "SIGKILL");
-    log(`[port-manager] SIGKILL sent to pid ${pid} (did not exit on SIGTERM)`);
-  } catch (err) {
-    logError(`[port-manager] SIGKILL failed for pid ${pid}: ${err.message}`);
-    return;
-  }
-
-  // Poll until the kernel reaps the process so callers can safely rebind
-  // the port immediately after we return. 1 s cap at 50 ms intervals —
-  // SIGKILL is synchronous in the kernel but reaping the zombie can lag.
-  const killDeadline = Date.now() + 1000;
-  while (Date.now() < killDeadline) {
-    if (!alive(pid)) return;
-    await new Promise((r) => setTimeout(r, 50));
-  }
-  logError(
-    `[port-manager] pid ${pid} still alive 1s after SIGKILL — orphan risk`,
-  );
+  await killProcessTree(procOrPid, {
+    graceMs: BACKEND_KILL_GRACE_MS,
+    forceWaitMs: BACKEND_FORCE_WAIT_MS,
+    log,
+    logError,
+    label: "backend",
+  });
 }
 
 /**
@@ -231,4 +178,6 @@ module.exports = PortManager;
 module.exports.PortManager = PortManager;
 module.exports.findFreePort = findFreePort;
 module.exports.killBackend = killBackend;
+module.exports.BACKEND_KILL_GRACE_MS = BACKEND_KILL_GRACE_MS;
+module.exports.BACKEND_FORCE_WAIT_MS = BACKEND_FORCE_WAIT_MS;
 module.exports.writeDiagnosticsBundle = writeDiagnosticsBundle;