fix(cli): own SIGTERM before the GPU probe browser launches

Author: miguel-heygen

packages/cli/src/browser/launch.fixture.ts

@@ -2,7 +2,7 @@
 import { writeFileSync } from "node:fs";
 import { registerRootExitRequester } from "../utils/commandResult.js";
 import { ensureBrowser } from "./manager.js";
-import { launchManagedBrowser } from "./launch.js";
+import { launchManagedBrowser, resolveManagedGpuMode } from "./launch.js";
 
 const [profileDir, readyPath] = process.argv.slice(2);
 if (!profileDir || !readyPath) throw new Error("Missing fixture arguments");
@@ -14,6 +14,10 @@ registerRootExitRequester((exitCode) => {
 });
 const { executablePath } = await ensureBrowser();
 const puppeteer = await import("puppeteer-core");
+if (process.argv[4] === "probe") {
+  writeFileSync(readyPath, "probing");
+  await resolveManagedGpuMode("auto", executablePath);
+}
 writeFileSync(readyPath, "launching");
 const browser = await launchManagedBrowser(puppeteer.default, {
   headless: true,

packages/cli/src/browser/launch.process.test.ts

@@ -23,10 +23,12 @@ function browserPids(profileDir: string): number[] {
     .map(Number);
 }
 
-function startFixture(profileDir: string, readyPath: string): ChildProcess {
-  const child = spawn(process.execPath, ["--import", "tsx", fixturePath, profileDir, readyPath], {
-    stdio: "ignore",
-  });
+function startFixture(profileDir: string, readyPath: string, mode = "launch"): ChildProcess {
+  const child = spawn(
+    process.execPath,
+    ["--import", "tsx", fixturePath, profileDir, readyPath, mode],
+    { stdio: "ignore" },
+  );
   children.add(child);
   return child;
 }
@@ -67,4 +69,18 @@ describe.skipIf(process.platform !== "linux")("managed browser shutdown", () =>
     },
     60_000,
   );
+
+  it("SIGTERM during the GPU probe asks the CLI to exit instead of being swallowed", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-launch-"));
+    const readyPath = join(dir, "ready");
+    const child = startFixture(join(dir, "profile"), readyPath, "probe");
+    const done = exited(child);
+    await waitForTestCondition(
+      () => existsSync(readyPath) && readFileSync(readyPath, "utf8") === "probing",
+      30_000,
+    );
+    child.kill("SIGTERM");
+    await done;
+    expect(readFileSync(`${readyPath}.exit`, "utf8")).toBe("143");
+  }, 60_000);
 });

packages/cli/src/browser/launch.ts

@@ -1,4 +1,10 @@
 import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core";
+import {
+  resolveCaptureBrowserGpuMode,
+  type BrowserGpuMode,
+  type ResolvedBrowserGpuMode,
+} from "./gpuPolicy.js";
+import { setHostHandlesSigint } from "@hyperframes/engine";
 import { requestCliExit } from "../utils/commandResult.js";
 
 const browsers = new Set<Browser>();
@@ -20,17 +26,30 @@ function stopForSignal(signal: "SIGINT" | "SIGTERM"): void {
   );
 }
 
+function ownSignals(): void {
+  if (listening) return;
+  listening = true;
+  setHostHandlesSigint(true);
+  process.on("SIGINT", () => stopForSignal("SIGINT"));
+  process.on("SIGTERM", () => stopForSignal("SIGTERM"));
+}
+
+/** The GPU probe launches its own Chrome, so the signal owner must exist before it runs. */
+export async function resolveManagedGpuMode(
+  requestedMode: BrowserGpuMode,
+  chromePath?: string,
+): Promise<ResolvedBrowserGpuMode> {
+  ownSignals();
+  return resolveCaptureBrowserGpuMode(requestedMode, chromePath);
+}
+
 /** One owner for every CLI browser, including a launch cancelled before its connection is ready. */
 export async function launchManagedBrowser(
   puppeteer: PuppeteerNode,
   options: LaunchOptions,
 ): Promise<Browser> {
   if (shutdown) throw new Error("The CLI is stopping; no browser can start.");
-  if (!listening) {
-    listening = true;
-    process.on("SIGINT", () => stopForSignal("SIGINT"));
-    process.on("SIGTERM", () => stopForSignal("SIGTERM"));
-  }
+  ownSignals();
   const abort = new AbortController();
   const signal = options.signal ? AbortSignal.any([options.signal, abort.signal]) : abort.signal;
   const launch = puppeteer.launch({

packages/cli/src/capture/captureCompositionFrame.ts

@@ -1,11 +1,10 @@
-import { launchManagedBrowser } from "../browser/launch.js";
+import { launchManagedBrowser, resolveManagedGpuMode } from "../browser/launch.js";
 import { spawn } from "node:child_process";
 import type { Browser, Page } from "puppeteer-core";
 import { c } from "../ui/colors.js";
 import {
   assertWebGpuAdapterAvailable,
   compositionRequiresWebGpu,
-  resolveCaptureBrowserGpuMode,
   resolveLocalBrowserGpuMode,
   type BrowserGpuMode,
 } from "../browser/gpuPolicy.js";
@@ -180,7 +179,7 @@ export async function openSettledCompositionPage(
   const requestedGpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
   const requiresWebGpu = compositionRequiresWebGpu(html);
   const launch = async (executablePath: string): Promise<Browser> => {
-    const resolvedGpuMode = await resolveCaptureBrowserGpuMode(requestedGpuMode, executablePath);
+    const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath);
     return launchManagedBrowser(puppeteer.default, {
       headless: true,
       executablePath,

packages/cli/src/commands/layout.ts

@@ -1,4 +1,4 @@
-import { launchManagedBrowser } from "../browser/launch.js";
+import { launchManagedBrowser, resolveManagedGpuMode } from "../browser/launch.js";
 import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
 import { defineCommand } from "citty";
 import { existsSync, readFileSync } from "node:fs";
@@ -204,12 +204,8 @@ async function runLayoutAudit(
   const { ensureBrowser } = await import("../browser/manager.js");
   const puppeteer = await import("puppeteer-core");
   const { buildChromeArgs } = await import("@hyperframes/engine");
-  const {
-    assertWebGpuAdapterAvailable,
-    compositionRequiresWebGpu,
-    resolveCaptureBrowserGpuMode,
-    resolveLocalBrowserGpuMode,
-  } = await import("../browser/gpuPolicy.js");
+  const { assertWebGpuAdapterAvailable, compositionRequiresWebGpu, resolveLocalBrowserGpuMode } =
+    await import("../browser/gpuPolicy.js");
   const html = await bundleProjectHtml(projectDir);
   const server = await serveStaticProjectHtml(
     projectDir,
@@ -221,10 +217,7 @@ async function runLayoutAudit(
   try {
     const browser = await ensureBrowser();
     const requestedGpuMode = resolveLocalBrowserGpuMode();
-    const resolvedGpuMode = await resolveCaptureBrowserGpuMode(
-      requestedGpuMode,
-      browser.executablePath,
-    );
+    const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, browser.executablePath);
     const requiresWebGpu = compositionRequiresWebGpu(html);
     chromeBrowser = await launchManagedBrowser(puppeteer.default, {
       headless: true,

packages/cli/src/commands/motionShot.ts

@@ -1,4 +1,4 @@
-import { launchManagedBrowser } from "../browser/launch.js";
+import { launchManagedBrowser, resolveManagedGpuMode } from "../browser/launch.js";
 // Onion-skin motion screenshot: seek the LIVE timeline at N equal-time steps and
 // project the REAL element at each step, so an agent can SELF-VERIFY motion (the
 // rendered result — every channel: position, rotation, scale, opacity, colour),
@@ -18,7 +18,6 @@ import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport
 import {
   assertWebGpuAdapterAvailable,
   compositionRequiresWebGpu,
-  resolveCaptureBrowserGpuMode,
   resolveLocalBrowserGpuMode,
 } from "../browser/gpuPolicy.js";
 import {
@@ -401,7 +400,7 @@ async function openCompositionPage(
   const { buildChromeArgs } = await import("@hyperframes/engine");
   const size = resolveCompositionViewportFromHtml(html);
   const requestedGpuMode = resolveLocalBrowserGpuMode();
-  const resolvedGpuMode = await resolveCaptureBrowserGpuMode(requestedGpuMode, executablePath);
+  const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath);
   const requiresWebGpu = compositionRequiresWebGpu(html);
   const browser = await launchManagedBrowser(puppeteer.default, {
     headless: true,

packages/cli/src/commands/validate.ts

@@ -1,4 +1,4 @@
-import { launchManagedBrowser } from "../browser/launch.js";
+import { launchManagedBrowser, resolveManagedGpuMode } from "../browser/launch.js";
 // The media-metadata wait exists twice on purpose: once Node-side and once
 // inside a page.evaluate() body, which is serialized into the browser and
 // cannot import the Node helper. Line-level markers don't survive the clone
@@ -433,15 +433,9 @@ async function validateInBrowser(
     const puppeteer = await import("puppeteer-core");
     const { buildChromeArgs, analyzeClipMediaFit } = await import("@hyperframes/engine");
     const requestedGpuMode = resolveCliChromeGpuMode();
-    const {
-      assertWebGpuAdapterAvailable,
-      compositionRequiresWebGpu,
-      resolveCaptureBrowserGpuMode,
-    } = await import("../browser/gpuPolicy.js");
-    const resolvedGpuMode = await resolveCaptureBrowserGpuMode(
-      requestedGpuMode,
-      browser.executablePath,
-    );
+    const { assertWebGpuAdapterAvailable, compositionRequiresWebGpu } =
+      await import("../browser/gpuPolicy.js");
+    const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, browser.executablePath);
     const requiresWebGpu = compositionRequiresWebGpu(html);
     const chromeBrowser = await launchManagedBrowser(puppeteer.default, {
       headless: true,

packages/engine/src/services/browserManager.ts

@@ -33,12 +33,15 @@ let _puppeteer: PuppeteerNode | undefined;
 
 let hostHandlesSigint = false;
 
-/** Set while the host cancels renders on Ctrl+C; Puppeteer's own handler would exit before any cleanup ran. */
+/** Set while the host owns SIGINT and SIGTERM; Puppeteer's own handlers would exit before any cleanup ran. */
 export function setHostHandlesSigint(owned: boolean): void {
   hostHandlesSigint = owned;
 }
 
-export const sigintLaunchOptions = () => ({ handleSIGINT: !hostHandlesSigint });
+export const sigintLaunchOptions = () => ({
+  handleSIGINT: !hostHandlesSigint,
+  handleSIGTERM: !hostHandlesSigint,
+});
 
 interface WebGlProbeInfo {
   hasWebGL: boolean;