From 196d78ff6dd3a48bbc8a541b331f0c017dfc00d1 Mon Sep 17 00:00:00 2001
From: Chen Yu <chenyu.nus@gmail.com>
Date: Thu, 6 Aug 2026 11:06:33 +0800
Subject: [PATCH 1/3] feat(engine): add strict browser sandbox mode

---
 packages/engine/README.md                     | 12 +++++
 packages/engine/src/index.ts                  |  9 ++++
 .../src/services/browserManager.test.ts       | 23 ++++++++
 .../engine/src/services/browserManager.ts     | 31 ++++++++---
 .../src/services/browserSandbox.test.ts       | 53 ++++++++++++++++++
 .../engine/src/services/browserSandbox.ts     | 54 +++++++++++++++++++
 packages/engine/src/services/hdrCapture.ts    | 13 +++--
 7 files changed, 186 insertions(+), 9 deletions(-)
 create mode 100644 packages/engine/src/services/browserSandbox.test.ts
 create mode 100644 packages/engine/src/services/browserSandbox.ts

diff --git a/packages/engine/README.md b/packages/engine/README.md
index 1adf934d89..1e0a8cd841 100644
--- a/packages/engine/README.md
+++ b/packages/engine/README.md
@@ -66,6 +66,18 @@ await browserLease.release();
 
 Most users should use `@hyperframes/producer` or the `hyperframes` CLI instead of calling the engine directly.
 
+## Strict Chromium sandbox mode
+
+HyperFrames keeps its existing browser launch behavior by default for backwards compatibility. A trusted Linux renderer can opt into a fail-closed Chromium process sandbox and site isolation profile with:
+
+```bash
+PRODUCER_BROWSER_SANDBOX_MODE=strict hyperframes render ./composition
+```
+
+Strict mode refuses to launch on Linux unless HyperFrames can verify that it is running as a non-root user. It also omits `--no-sandbox`, `--disable-setuid-sandbox`, and `--no-zygote`, enables `--site-per-process`, and prevents the normal render engine from disabling site isolation. The host or container must provide a working Chromium sandbox; HyperFrames does not fall back to an unsafe launch when strict mode fails.
+
+This setting governs browsers launched by the render engine. Auxiliary CLI commands that launch their own browser are outside this contract.
+
 ## Documentation
 
 Full documentation: [hyperframes.heygen.com/packages/engine](https://hyperframes.heygen.com/packages/engine)
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index e9c3481438..8b6d9665f3 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -89,6 +89,15 @@ export {
   type CaptureMode,
   type AcquiredBrowser,
 } from "./services/browserManager.js";
+export {
+  BROWSER_SANDBOX_MODE_ENV,
+  assertBrowserSandboxRuntime,
+  buildDisabledBrowserFeaturesArg,
+  getBrowserSandboxLaunchArgs,
+  getBrowserSandboxProcessArgs,
+  resolveBrowserSandboxMode,
+  type BrowserSandboxMode,
+} from "./services/browserSandbox.js";
 export {
   augmentProtocolTimeoutError,
   isProtocolTimeoutError,
diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts
index db6e7e4686..0e46b05357 100644
--- a/packages/engine/src/services/browserManager.test.ts
+++ b/packages/engine/src/services/browserManager.test.ts
@@ -121,6 +121,15 @@ describe("BeginFrame capability probe", () => {
 
 describe("buildChromeArgs browser GPU mode", () => {
   const base = { width: 1920, height: 1080 };
+  const originalBrowserSandboxMode = process.env.PRODUCER_BROWSER_SANDBOX_MODE;
+
+  afterEach(() => {
+    if (originalBrowserSandboxMode === undefined) {
+      delete process.env.PRODUCER_BROWSER_SANDBOX_MODE;
+    } else {
+      process.env.PRODUCER_BROWSER_SANDBOX_MODE = originalBrowserSandboxMode;
+    }
+  });
 
   it("uses SwiftShader software GL by default for reproducible local renders", () => {
     const args = buildChromeArgs(base);
@@ -187,6 +196,20 @@ describe("buildChromeArgs browser GPU mode", () => {
     expect(args).toContain("--use-angle=swiftshader");
     expect(args).not.toContain("--use-angle=metal");
   });
+
+  it("uses the Chromium process sandbox and site isolation in strict mode", () => {
+    process.env.PRODUCER_BROWSER_SANDBOX_MODE = "strict";
+
+    const args = buildChromeArgs({ ...base, platform: "linux" });
+
+    expect(args).toContain("--site-per-process");
+    expect(args).not.toContain("--no-sandbox");
+    expect(args).not.toContain("--disable-setuid-sandbox");
+    expect(args).not.toContain("--no-zygote");
+    const disabledFeatures = args.find((arg) => arg.startsWith("--disable-features="));
+    expect(disabledFeatures).not.toContain("IsolateOrigins");
+    expect(disabledFeatures).not.toContain("site-per-process");
+  });
 });
 
 describe("browser launch capture-mode contract", () => {
diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts
index 762626eb3c..6a394bc41b 100644
--- a/packages/engine/src/services/browserManager.ts
+++ b/packages/engine/src/services/browserManager.ts
@@ -11,6 +11,13 @@ import { existsSync, readdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
+import {
+  assertBrowserSandboxRuntime,
+  buildDisabledBrowserFeaturesArg,
+  getBrowserSandboxLaunchArgs,
+  getBrowserSandboxProcessArgs,
+  resolveBrowserSandboxMode,
+} from "./browserSandbox.js";
 import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
 import {
   BrowserLeasePool,
@@ -449,9 +456,10 @@ async function getPuppeteerOrNull(): Promise<PuppeteerNode | null> {
 }
 
 function getHardwareGpuProbeArgs(platform: NodeJS.Platform): string[] {
+  const browserSandboxMode = resolveBrowserSandboxMode();
+  assertBrowserSandboxRuntime(browserSandboxMode);
   return [
-    "--no-sandbox",
-    "--disable-setuid-sandbox",
+    ...getBrowserSandboxLaunchArgs(browserSandboxMode),
     "--disable-dev-shm-usage",
     "--enable-webgl",
     "--ignore-gpu-blocklist",
@@ -761,6 +769,8 @@ export function buildChromeArgs(
   options: BuildChromeArgsOptions,
   config?: Partial<Pick<EngineConfig, "browserGpuMode" | "disableGpu" | "chromePath">>,
 ): string[] {
+  const browserSandboxMode = resolveBrowserSandboxMode();
+  assertBrowserSandboxRuntime(browserSandboxMode);
   const platform = options.platform ?? process.platform;
   const gpuDisabled = config?.disableGpu ?? DEFAULT_CONFIG.disableGpu;
   const browserGpuMode = gpuDisabled
@@ -771,8 +781,7 @@ export function buildChromeArgs(
   // appear in Puppeteer's defaults, Playwright, Remotion, and Chrome's own
   // headless-shell guidance.
   const chromeArgs = [
-    "--no-sandbox",
-    "--disable-setuid-sandbox",
+    ...getBrowserSandboxLaunchArgs(browserSandboxMode),
     "--disable-dev-shm-usage",
     CANVAS_DRAW_ELEMENT_FEATURE_FLAG,
     "--enable-webgl",
@@ -800,13 +809,23 @@ export function buildChromeArgs(
     "--disable-domain-reliability",
     "--disable-print-preview",
     "--no-pings",
-    "--no-zygote",
+    ...getBrowserSandboxProcessArgs(browserSandboxMode),
     // Memory — scale GPU budget to available system RAM
     `--force-gpu-mem-available-mb=${getGpuMemBudgetMb()}`,
     "--disk-cache-size=268435456",
     ...getLowMemoryFlags(),
     // Disable features that add overhead
-    "--disable-features=AudioServiceOutOfProcess,IsolateOrigins,site-per-process,Translate,BackForwardCache,IntensiveWakeUpThrottling",
+    buildDisabledBrowserFeaturesArg(
+      [
+        "AudioServiceOutOfProcess",
+        "IsolateOrigins",
+        "site-per-process",
+        "Translate",
+        "BackForwardCache",
+        "IntensiveWakeUpThrottling",
+      ],
+      browserSandboxMode,
+    ),
     // Allow AudioContext to start without a user gesture in headless Chrome.
     // Without this flag, any code path that constructs an AudioContext
     // (including GSAP tweening an <audio> element's volume) triggers the
diff --git a/packages/engine/src/services/browserSandbox.test.ts b/packages/engine/src/services/browserSandbox.test.ts
new file mode 100644
index 0000000000..00367044d3
--- /dev/null
+++ b/packages/engine/src/services/browserSandbox.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  assertBrowserSandboxRuntime,
+  buildDisabledBrowserFeaturesArg,
+  getBrowserSandboxLaunchArgs,
+  getBrowserSandboxProcessArgs,
+  resolveBrowserSandboxMode,
+} from "./browserSandbox.js";
+
+describe("browser sandbox policy", () => {
+  it("keeps the existing unsafe launch policy unless strict mode is explicit", () => {
+    expect(resolveBrowserSandboxMode(undefined)).toBe("legacy-unsafe");
+    expect(getBrowserSandboxLaunchArgs("legacy-unsafe")).toEqual([
+      "--no-sandbox",
+      "--disable-setuid-sandbox",
+    ]);
+    expect(getBrowserSandboxProcessArgs("legacy-unsafe")).toEqual(["--no-zygote"]);
+  });
+
+  it("enables site isolation without sandbox-disabling launch switches in strict mode", () => {
+    expect(resolveBrowserSandboxMode(" strict ")).toBe("strict");
+    expect(getBrowserSandboxLaunchArgs("strict")).toEqual(["--site-per-process"]);
+    expect(getBrowserSandboxProcessArgs("strict")).toEqual([]);
+    expect(
+      buildDisabledBrowserFeaturesArg(
+        ["AudioServiceOutOfProcess", "IsolateOrigins", "site-per-process", "Translate"],
+        "strict",
+      ),
+    ).toBe("--disable-features=AudioServiceOutOfProcess,Translate");
+  });
+
+  it("rejects unknown modes instead of silently weakening the browser policy", () => {
+    expect(() => resolveBrowserSandboxMode("enabled")).toThrow(
+      'PRODUCER_BROWSER_SANDBOX_MODE must be "legacy-unsafe" or "strict"',
+    );
+  });
+
+  it("rejects a strict Linux launch as root", () => {
+    expect(() => assertBrowserSandboxRuntime("strict", { platform: "linux", uid: 0 })).toThrow(
+      "requires HyperFrames to run as a non-root user",
+    );
+    expect(() =>
+      assertBrowserSandboxRuntime("strict", { platform: "linux", uid: 1000 }),
+    ).not.toThrow();
+  });
+
+  it("rejects strict Linux mode when the process uid cannot be verified", () => {
+    expect(() =>
+      assertBrowserSandboxRuntime("strict", { platform: "linux", uid: undefined }),
+    ).toThrow("requires HyperFrames to verify a non-root Linux user");
+  });
+});
diff --git a/packages/engine/src/services/browserSandbox.ts b/packages/engine/src/services/browserSandbox.ts
new file mode 100644
index 0000000000..2616da795a
--- /dev/null
+++ b/packages/engine/src/services/browserSandbox.ts
@@ -0,0 +1,54 @@
+export const BROWSER_SANDBOX_MODE_ENV = "PRODUCER_BROWSER_SANDBOX_MODE";
+
+export type BrowserSandboxMode = "legacy-unsafe" | "strict";
+
+export function resolveBrowserSandboxMode(
+  rawValue: string | undefined = process.env[BROWSER_SANDBOX_MODE_ENV],
+): BrowserSandboxMode {
+  const value = rawValue?.trim().toLowerCase();
+  if (value === undefined || value === "" || value === "legacy-unsafe") {
+    return "legacy-unsafe";
+  }
+  if (value === "strict") return value;
+  throw new Error(
+    `${BROWSER_SANDBOX_MODE_ENV} must be "legacy-unsafe" or "strict"; received ${JSON.stringify(rawValue)}`,
+  );
+}
+
+export function assertBrowserSandboxRuntime(
+  mode: BrowserSandboxMode,
+  runtime: { platform: NodeJS.Platform; uid: number | undefined } = {
+    platform: process.platform,
+    uid: process.getuid?.(),
+  },
+): void {
+  if (mode === "strict" && runtime.platform === "linux" && runtime.uid === undefined) {
+    throw new Error(
+      `${BROWSER_SANDBOX_MODE_ENV}=strict requires HyperFrames to verify a non-root Linux user`,
+    );
+  }
+  if (mode === "strict" && runtime.platform === "linux" && runtime.uid === 0) {
+    throw new Error(
+      `${BROWSER_SANDBOX_MODE_ENV}=strict requires HyperFrames to run as a non-root user`,
+    );
+  }
+}
+
+export function getBrowserSandboxLaunchArgs(mode: BrowserSandboxMode): string[] {
+  return mode === "strict" ? ["--site-per-process"] : ["--no-sandbox", "--disable-setuid-sandbox"];
+}
+
+export function getBrowserSandboxProcessArgs(mode: BrowserSandboxMode): string[] {
+  return mode === "strict" ? [] : ["--no-zygote"];
+}
+
+export function buildDisabledBrowserFeaturesArg(
+  features: readonly string[],
+  mode: BrowserSandboxMode,
+): string {
+  const disabledFeatures =
+    mode === "strict"
+      ? features.filter((feature) => feature !== "IsolateOrigins" && feature !== "site-per-process")
+      : [...features];
+  return `--disable-features=${disabledFeatures.join(",")}`;
+}
diff --git a/packages/engine/src/services/hdrCapture.ts b/packages/engine/src/services/hdrCapture.ts
index 93ac78f23e..8ae0dceea1 100644
--- a/packages/engine/src/services/hdrCapture.ts
+++ b/packages/engine/src/services/hdrCapture.ts
@@ -23,6 +23,12 @@ import type { Page, Browser, PuppeteerNode } from "puppeteer-core";
 import { existsSync, readdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import {
+  assertBrowserSandboxRuntime,
+  getBrowserSandboxLaunchArgs,
+  getBrowserSandboxProcessArgs,
+  resolveBrowserSandboxMode,
+} from "./browserSandbox.js";
 
 // ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
 
@@ -294,10 +300,11 @@ export async function launchHdrBrowser(
 }
 
 export function buildHdrChromeArgs(width: number, height: number): string[] {
+  const browserSandboxMode = resolveBrowserSandboxMode();
+  assertBrowserSandboxRuntime(browserSandboxMode);
   return [
     "--enable-unsafe-webgpu",
-    "--no-sandbox",
-    "--disable-setuid-sandbox",
+    ...getBrowserSandboxLaunchArgs(browserSandboxMode),
     "--window-position=-10000,-10000",
     `--window-size=${width},${height}`,
     "--disable-background-timer-throttling",
@@ -308,7 +315,7 @@ export function buildHdrChromeArgs(width: number, height: number): string[] {
     "--disable-component-update",
     "--disable-default-apps",
     "--disable-sync",
-    "--no-zygote",
+    ...getBrowserSandboxProcessArgs(browserSandboxMode),
     "--force-gpu-mem-available-mb=4096",
     "--autoplay-policy=no-user-gesture-required",
   ];

From 03b0e984f4bc4ecdb061eae0b3d2194b81b9db1b Mon Sep 17 00:00:00 2001
From: Chen Yu <chenyu.nus@gmail.com>
Date: Thu, 6 Aug 2026 13:06:45 +0800
Subject: [PATCH 2/3] feat(engine): expose exact-browser sandbox status

---
 packages/engine/README.md                     |   2 +
 .../src/services/browserManager.test.ts       |  43 ++++
 .../engine/src/services/browserManager.ts     |   2 +
 .../src/services/browserSandboxStatus.test.ts | 113 ++++++++++
 .../src/services/browserSandboxStatus.ts      | 212 ++++++++++++++++++
 5 files changed, 372 insertions(+)
 create mode 100644 packages/engine/src/services/browserSandboxStatus.test.ts
 create mode 100644 packages/engine/src/services/browserSandboxStatus.ts

diff --git a/packages/engine/README.md b/packages/engine/README.md
index 1e0a8cd841..e859ddbf77 100644
--- a/packages/engine/README.md
+++ b/packages/engine/README.md
@@ -78,6 +78,8 @@ Strict mode refuses to launch on Linux unless HyperFrames can verify that it is
 
 This setting governs browsers launched by the render engine. Auxiliary CLI commands that launch their own browser are outside this contract.
 
+Trusted renderer health checks can additionally set `PRODUCER_SANDBOX_STATUS_PATH` to an absolute file path. Before any composition page is opened, HyperFrames uses the final render browser itself to load `chrome://sandbox` and atomically writes a bounded, mode-`0600` JSON status record. The browser launch fails if that opted-in capture cannot complete. This record is runtime diagnostic evidence, not a cryptographic attestation or a substitute for container isolation.
+
 ## Documentation
 
 Full documentation: [hyperframes.heygen.com/packages/engine](https://hyperframes.heygen.com/packages/engine)
diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts
index 0e46b05357..e70c82d74c 100644
--- a/packages/engine/src/services/browserManager.test.ts
+++ b/packages/engine/src/services/browserManager.test.ts
@@ -782,3 +782,46 @@ describe("browser pool", () => {
     await acquirePromise.catch(() => {});
   });
 });
+
+describe("browser sandbox status launch gate", () => {
+  const originalStatusPath = process.env.PRODUCER_SANDBOX_STATUS_PATH;
+
+  afterEach(async () => {
+    if (originalStatusPath === undefined) {
+      delete process.env.PRODUCER_SANDBOX_STATUS_PATH;
+    } else {
+      process.env.PRODUCER_SANDBOX_STATUS_PATH = originalStatusPath;
+    }
+    await drainBrowserPool();
+    _setPuppeteerForTests(undefined);
+  });
+
+  it("closes Chromium and rejects acquisition when the opted-in status capture fails", async () => {
+    const directory = mkdtempSync(join(tmpdir(), "hf-sandbox-gate-"));
+    const close = vi.fn().mockResolvedValue(undefined);
+    const browser = {
+      connected: true,
+      version: vi.fn().mockResolvedValue("HeadlessChrome/131.0.0.0"),
+      process: vi.fn().mockReturnValue({ pid: 4242, kill: vi.fn(), killed: false }),
+      newPage: vi.fn().mockResolvedValue({
+        goto: vi.fn().mockRejectedValue(new Error("sandbox status unavailable")),
+        close: vi.fn().mockResolvedValue(undefined),
+      }),
+      close,
+      disconnect: vi.fn(),
+    } as unknown as Browser;
+    _setPuppeteerForTests({
+      launch: vi.fn().mockResolvedValue(browser),
+    } as unknown as PuppeteerNode);
+    process.env.PRODUCER_SANDBOX_STATUS_PATH = join(directory, "status.json");
+
+    try {
+      await expect(
+        acquireBrowser(["--no-sandbox"], { enableBrowserPool: false, forceScreenshot: true }),
+      ).rejects.toThrow("sandbox status unavailable");
+      expect(close).toHaveBeenCalledOnce();
+    } finally {
+      rmSync(directory, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts
index 6a394bc41b..c3d4b05945 100644
--- a/packages/engine/src/services/browserManager.ts
+++ b/packages/engine/src/services/browserManager.ts
@@ -25,6 +25,7 @@ import {
   type BrowserLease,
   type CaptureMode,
 } from "./browserLeasePool.js";
+import { captureBrowserSandboxStatus } from "./browserSandboxStatus.js";
 
 export { BrowserLeasePool } from "./browserLeasePool.js";
 export type {
@@ -653,6 +654,7 @@ async function launchBrowser(
       }
     }
 
+    await captureBrowserSandboxStatus(browser);
     return { browser, captureMode };
   } catch (error) {
     await browser?.close().catch(() => {});
diff --git a/packages/engine/src/services/browserSandboxStatus.test.ts b/packages/engine/src/services/browserSandboxStatus.test.ts
new file mode 100644
index 0000000000..37d2b4d284
--- /dev/null
+++ b/packages/engine/src/services/browserSandboxStatus.test.ts
@@ -0,0 +1,113 @@
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { Browser } from "puppeteer-core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  _fitSandboxStatusDocumentForTests,
+  _truncateSandboxStatusUtf8ForTests,
+  captureBrowserSandboxStatus,
+  type BrowserSandboxStatusV1,
+} from "./browserSandboxStatus.js";
+
+const temporaryDirectories: string[] = [];
+
+function makeTemporaryDirectory(): string {
+  const directory = mkdtempSync(join(tmpdir(), "hf-sandbox-status-"));
+  temporaryDirectories.push(directory);
+  return directory;
+}
+
+afterEach(() => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+describe("browser sandbox status capture", () => {
+  it("is completely inert when the opt-in path is absent", async () => {
+    const browser = { newPage: vi.fn() } as unknown as Browser;
+
+    await captureBrowserSandboxStatus(browser, undefined);
+
+    expect(browser.newPage).not.toHaveBeenCalled();
+  });
+
+  it("captures chrome://sandbox from the passed Browser and closes its temporary page", async () => {
+    const outputPath = join(makeTemporaryDirectory(), "sandbox-status.json");
+    const close = vi.fn().mockResolvedValue(undefined);
+    const goto = vi.fn().mockResolvedValue(null);
+    const evaluate = vi.fn().mockResolvedValue({
+      bodyText: "Sandbox Status\nSeccomp-BPF sandbox: Yes",
+      rows: [{ label: "Seccomp-BPF sandbox", value: "Yes" }],
+    });
+    const browser = {
+      process: vi.fn().mockReturnValue({ pid: 4242 }),
+      newPage: vi.fn().mockResolvedValue({ goto, evaluate, close }),
+    } as unknown as Browser;
+
+    await captureBrowserSandboxStatus(browser, outputPath);
+
+    const status = JSON.parse(readFileSync(outputPath, "utf8")) as BrowserSandboxStatusV1;
+    expect(browser.newPage).toHaveBeenCalledOnce();
+    expect(goto).toHaveBeenCalledWith("chrome://sandbox", { waitUntil: "domcontentloaded" });
+    expect(status).toMatchObject({
+      schemaVersion: "hyperframes.chromium-sandbox.v1",
+      browserPid: 4242,
+      url: "chrome://sandbox",
+      bodyTextTruncated: false,
+      rowsTruncated: false,
+      rows: [{ label: "Seccomp-BPF sandbox", value: "Yes" }],
+    });
+    expect(statSync(outputPath).mode & 0o777).toBe(0o600);
+    expect(close).toHaveBeenCalledOnce();
+  });
+
+  it("propagates capture failures and still closes the temporary page", async () => {
+    const close = vi.fn().mockResolvedValue(undefined);
+    const browser = {
+      process: vi.fn().mockReturnValue({ pid: 4242 }),
+      newPage: vi.fn().mockResolvedValue({
+        goto: vi.fn().mockRejectedValue(new Error("sandbox page unavailable")),
+        close,
+      }),
+    } as unknown as Browser;
+
+    await expect(
+      captureBrowserSandboxStatus(browser, join(makeTemporaryDirectory(), "status.json")),
+    ).rejects.toThrow("sandbox page unavailable");
+    expect(close).toHaveBeenCalledOnce();
+  });
+
+  it("caps UTF-8 text without splitting a code point", () => {
+    const result = _truncateSandboxStatusUtf8ForTests("a🙂b", 5);
+
+    expect(result).toEqual({ value: "a🙂", truncated: true });
+    expect(Buffer.byteLength(result.value, "utf8")).toBe(5);
+  });
+
+  it("bounds the complete serialized status document to the consumer's 64 KiB limit", () => {
+    const status = _fitSandboxStatusDocumentForTests({
+      schemaVersion: "hyperframes.chromium-sandbox.v1",
+      browserPid: 4242,
+      capturedAt: "2026-08-06T00:00:00.000Z",
+      url: "chrome://sandbox",
+      bodyText: "\\".repeat(32 * 1024),
+      bodyTextTruncated: false,
+      rows: [
+        { label: "Layer 1 Sandbox", value: "SUID" },
+        { label: "PID namespaces", value: "Yes" },
+        { label: "Network namespaces", value: "Yes" },
+        { label: "Seccomp-BPF sandbox", value: "Yes" },
+      ],
+      rowsTruncated: false,
+    });
+
+    expect(Buffer.byteLength(`${JSON.stringify(status)}\n`, "utf8")).toBeLessThanOrEqual(64 * 1024);
+    expect(status.bodyTextTruncated).toBe(true);
+    expect(status.rows).toHaveLength(4);
+    expect(status.rowsTruncated).toBe(false);
+  });
+});
diff --git a/packages/engine/src/services/browserSandboxStatus.ts b/packages/engine/src/services/browserSandboxStatus.ts
new file mode 100644
index 0000000000..db44c8b767
--- /dev/null
+++ b/packages/engine/src/services/browserSandboxStatus.ts
@@ -0,0 +1,212 @@
+import { randomUUID } from "node:crypto";
+import { open, rename, unlink } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+
+import type { Browser } from "puppeteer-core";
+
+const STATUS_URL = "chrome://sandbox";
+export const BROWSER_SANDBOX_STATUS_PATH_ENV = "PRODUCER_SANDBOX_STATUS_PATH";
+const MAX_STATUS_DOCUMENT_BYTES = 64 * 1024;
+const MAX_BODY_TEXT_BYTES = 32 * 1024;
+const MAX_ROWS = 64;
+const MAX_ROW_FIELD_BYTES = 256;
+
+interface BrowserSandboxStatusRow {
+  label: string;
+  value: string;
+}
+
+export interface BrowserSandboxStatusV1 {
+  schemaVersion: "hyperframes.chromium-sandbox.v1";
+  browserPid: number;
+  capturedAt: string;
+  url: typeof STATUS_URL;
+  bodyText: string;
+  bodyTextTruncated: boolean;
+  rows: BrowserSandboxStatusRow[];
+  rowsTruncated: boolean;
+}
+
+interface CapturedSandboxPage {
+  bodyText: string;
+  rows: BrowserSandboxStatusRow[];
+}
+
+function truncateUtf8(value: string, maximumBytes: number): { value: string; truncated: boolean } {
+  if (Buffer.byteLength(value, "utf8") <= maximumBytes) {
+    return { value, truncated: false };
+  }
+
+  let byteLength = 0;
+  let prefix = "";
+  for (const character of value) {
+    const characterBytes = Buffer.byteLength(character, "utf8");
+    if (byteLength + characterBytes > maximumBytes) break;
+    prefix += character;
+    byteLength += characterBytes;
+  }
+  return { value: prefix, truncated: true };
+}
+
+function boundRows(rows: readonly BrowserSandboxStatusRow[]): {
+  rows: BrowserSandboxStatusRow[];
+  truncated: boolean;
+} {
+  const bounded = rows.slice(0, MAX_ROWS).map((row) => ({
+    label: truncateUtf8(row.label, MAX_ROW_FIELD_BYTES).value,
+    value: truncateUtf8(row.value, MAX_ROW_FIELD_BYTES).value,
+  }));
+  const fieldWasTruncated = bounded.some(
+    (row, index) => row.label !== rows[index]?.label || row.value !== rows[index]?.value,
+  );
+  return {
+    rows: bounded,
+    truncated: rows.length > MAX_ROWS || fieldWasTruncated,
+  };
+}
+
+function serializeStatus(status: BrowserSandboxStatusV1): string {
+  return `${JSON.stringify(status)}\n`;
+}
+
+function fitStatusDocument(status: BrowserSandboxStatusV1): BrowserSandboxStatusV1 {
+  const candidate: BrowserSandboxStatusV1 = {
+    ...status,
+    rows: [...status.rows],
+  };
+  if (Buffer.byteLength(serializeStatus(candidate), "utf8") <= MAX_STATUS_DOCUMENT_BYTES) {
+    return candidate;
+  }
+
+  const characters = Array.from(candidate.bodyText);
+  let low = 0;
+  let high = characters.length;
+  while (low < high) {
+    const midpoint = Math.ceil((low + high) / 2);
+    candidate.bodyText = characters.slice(0, midpoint).join("");
+    if (Buffer.byteLength(serializeStatus(candidate), "utf8") <= MAX_STATUS_DOCUMENT_BYTES) {
+      low = midpoint;
+    } else {
+      high = midpoint - 1;
+    }
+  }
+  candidate.bodyText = characters.slice(0, low).join("");
+  candidate.bodyTextTruncated = candidate.bodyTextTruncated || low < characters.length;
+  while (
+    candidate.rows.length > 0 &&
+    Buffer.byteLength(serializeStatus(candidate), "utf8") > MAX_STATUS_DOCUMENT_BYTES
+  ) {
+    candidate.rows.pop();
+    candidate.rowsTruncated = true;
+  }
+  if (Buffer.byteLength(serializeStatus(candidate), "utf8") > MAX_STATUS_DOCUMENT_BYTES) {
+    throw new Error("Unable to bound Chromium sandbox status document");
+  }
+  return candidate;
+}
+
+async function writeStatusAtomically(path: string, status: BrowserSandboxStatusV1): Promise<void> {
+  if (!isAbsolute(path)) {
+    throw new Error("PRODUCER_SANDBOX_STATUS_PATH must be an absolute path");
+  }
+
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(temporaryPath, "wx", 0o600);
+    await handle.writeFile(serializeStatus(fitStatusDocument(status)), "utf8");
+    await handle.chmod(0o600);
+    const metadata = await handle.stat();
+    if (!metadata.isFile() || (metadata.mode & 0o777) !== 0o600) {
+      throw new Error("sandbox status output is not a mode-0600 regular file");
+    }
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await unlink(temporaryPath).catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * Capture Chromium's own sandbox diagnostics from the exact Browser instance
+ * that will later open the untrusted composition. The hook is deliberately
+ * inert unless the caller supplies an output path.
+ */
+export async function captureBrowserSandboxStatus(
+  browser: Browser,
+  outputPath = process.env[BROWSER_SANDBOX_STATUS_PATH_ENV],
+): Promise<void> {
+  const path = outputPath?.trim();
+  if (!path) return;
+
+  const browserPid = browser.process()?.pid;
+  if (!Number.isSafeInteger(browserPid) || browserPid === undefined || browserPid <= 0) {
+    throw new Error("Unable to identify the launched Chromium process for sandbox status capture");
+  }
+
+  const page = await browser.newPage();
+  try {
+    await page.goto(STATUS_URL, { waitUntil: "domcontentloaded" });
+    const captured = await page.evaluate((): CapturedSandboxPage => {
+      const normalize = (value: string | null | undefined): string =>
+        (value ?? "").replace(/\s+/g, " ").trim();
+      const rows: BrowserSandboxStatusRow[] = [];
+
+      for (const tableRow of document.querySelectorAll("tr")) {
+        const cells = Array.from(tableRow.querySelectorAll("th, td"));
+        if (cells.length < 2) continue;
+        const label = normalize(cells[0]?.textContent);
+        const value = normalize(
+          cells
+            .slice(1)
+            .map((cell) => cell.textContent ?? "")
+            .join(" "),
+        );
+        if (label && value) rows.push({ label, value });
+      }
+
+      for (const term of document.querySelectorAll("dt")) {
+        const description = term.nextElementSibling;
+        if (!description || description.tagName.toLowerCase() !== "dd") continue;
+        const label = normalize(term.textContent);
+        const value = normalize(description.textContent);
+        if (label && value) rows.push({ label, value });
+      }
+
+      const bodyText = document.body?.innerText ?? "";
+      if (rows.length === 0) {
+        for (const line of bodyText.split(/\r?\n/)) {
+          const match = /^\s*([^:]+):\s*(.+?)\s*$/.exec(line);
+          if (!match) continue;
+          const label = normalize(match[1]);
+          const value = normalize(match[2]);
+          if (label && value) rows.push({ label, value });
+        }
+      }
+
+      return { bodyText, rows };
+    });
+
+    const bodyText = truncateUtf8(captured.bodyText, MAX_BODY_TEXT_BYTES);
+    const rows = boundRows(captured.rows);
+    await writeStatusAtomically(path, {
+      schemaVersion: "hyperframes.chromium-sandbox.v1",
+      browserPid,
+      capturedAt: new Date().toISOString(),
+      url: STATUS_URL,
+      bodyText: bodyText.value,
+      bodyTextTruncated: bodyText.truncated,
+      rows: rows.rows,
+      rowsTruncated: rows.truncated,
+    });
+  } finally {
+    await page.close().catch(() => {});
+  }
+}
+
+export const _truncateSandboxStatusUtf8ForTests = truncateUtf8;
+export const _fitSandboxStatusDocumentForTests = fitStatusDocument;

From 862c82154d5ed4e6fa5e044a7fd66a188adebdb7 Mon Sep 17 00:00:00 2001
From: Chen Yu <chenyu.nus@gmail.com>
Date: Thu, 6 Aug 2026 15:14:33 +0800
Subject: [PATCH 3/3] feat(engine): expose target renderer proof

---
 .../frameCapture-targetRendererProof.test.ts  |  92 +++++
 packages/engine/src/services/frameCapture.ts  |  42 +++
 .../src/services/targetRendererStatus.test.ts | 257 +++++++++++++
 .../src/services/targetRendererStatus.ts      | 342 ++++++++++++++++++
 4 files changed, 733 insertions(+)
 create mode 100644 packages/engine/src/services/frameCapture-targetRendererProof.test.ts
 create mode 100644 packages/engine/src/services/targetRendererStatus.test.ts
 create mode 100644 packages/engine/src/services/targetRendererStatus.ts

diff --git a/packages/engine/src/services/frameCapture-targetRendererProof.test.ts b/packages/engine/src/services/frameCapture-targetRendererProof.test.ts
new file mode 100644
index 0000000000..c16ea2269b
--- /dev/null
+++ b/packages/engine/src/services/frameCapture-targetRendererProof.test.ts
@@ -0,0 +1,92 @@
+import type { CDPSession, Page } from "puppeteer-core";
+import { describe, expect, it, vi } from "vitest";
+
+import type { CaptureSession } from "./frameCapture.js";
+import {
+  captureFramesBatchPipelined,
+  captureFrameToBuffer,
+  captureFrameToBufferPipelined,
+  recaptureDrawElementFrameForVerify,
+} from "./frameCapture.js";
+
+function proofSession(overrides: Partial<CaptureSession> = {}): CaptureSession {
+  return {
+    targetRendererStatusTracker: {},
+    ...overrides,
+  } as unknown as CaptureSession;
+}
+
+describe("target renderer frame proof", () => {
+  it("acknowledges the target renderer only after synchronous screenshot capture", async () => {
+    const order: string[] = [];
+    const cdpSession = {
+      send: vi.fn(async (method: string) => {
+        if (method !== "Page.captureScreenshot") throw new Error(`Unexpected CDP call: ${method}`);
+        order.push("capture");
+        return { data: Buffer.from("captured-frame").toString("base64") };
+      }),
+    } as unknown as CDPSession;
+    const page = {
+      evaluate: vi.fn(async () => false),
+      createCDPSession: vi.fn(async () => cdpSession),
+    } as unknown as Page;
+    const checkpoint = vi.fn(async () => {
+      order.push("checkpoint");
+    });
+    const session = proofSession({
+      page,
+      options: {
+        width: 1920,
+        height: 1080,
+        fps: { num: 30, den: 1 },
+        format: "jpeg",
+      },
+      onBeforeCapture: null,
+      isInitialized: true,
+      captureMode: "screenshot",
+      capturePerf: {
+        frames: 0,
+        seekMs: 0,
+        beforeCaptureMs: 0,
+        screenshotMs: 0,
+        totalMs: 0,
+        frameMs: [],
+      },
+      targetRendererStatusTracker: { checkpoint } as unknown as NonNullable<
+        CaptureSession["targetRendererStatusTracker"]
+      >,
+    });
+
+    const result = await captureFrameToBuffer(session, 4, 4 / 30);
+
+    expect(result.buffer.toString()).toBe("captured-frame");
+    expect(order).toEqual(["capture", "checkpoint"]);
+    expect(checkpoint).toHaveBeenCalledWith("frame", 4);
+  });
+
+  it("fails closed instead of reusing a static-deduplicated frame", async () => {
+    const session = proofSession({
+      options: { fps: { num: 30, den: 1 } } as CaptureSession["options"],
+      staticFrames: new Set([0]),
+      lastFrameBuffer: Buffer.from("prior-frame"),
+    });
+
+    await expect(captureFrameToBuffer(session, 0, 0)).rejects.toThrow(
+      "does not support static-frame deduplication",
+    );
+  });
+
+  it("fails closed on asynchronous worker and batch capture paths", async () => {
+    const session = proofSession();
+
+    await expect(captureFrameToBufferPipelined(session, 0, 0)).rejects.toThrow(
+      "does not support pipelined worker capture",
+    );
+    await expect(recaptureDrawElementFrameForVerify(session, 0, 0)).rejects.toThrow(
+      "does not support pipelined verification recapture",
+    );
+    await expect(captureFramesBatchPipelined(session, [0], [0])).rejects.toThrow(
+      "does not support batch capture",
+    );
+  });
+});
diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts
index 7fdb61f281..517c327b21 100644
--- a/packages/engine/src/services/frameCapture.ts
+++ b/packages/engine/src/services/frameCapture.ts
@@ -57,6 +57,10 @@ import type {
   SubTimelineWaitOutcome,
 } from "../types.js";
 import { cloneCaptureWarnings } from "./captureWarning.js";
+import {
+  createTargetRendererStatusTracker,
+  type TargetRendererStatusTracker,
+} from "./targetRendererStatus.js";
 export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";
 
 export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSummary };
@@ -69,6 +73,8 @@ export interface CaptureSession {
   /** Exact ownership token for this browser acquisition. */
   browserLease?: BrowserLease;
   page: Page;
+  /** Canary-only exact target-to-renderer checkpoint/acknowledgement hook. */
+  targetRendererStatusTracker?: TargetRendererStatusTracker;
   options: CaptureOptions;
   serverUrl: string;
   outputDir: string;
@@ -1169,6 +1175,7 @@ async function constructCaptureSession(
 
   const page = await browser.newPage();
   onPageCreated(page);
+  const targetRendererStatusTracker = createTargetRendererStatusTracker(page);
   // Polyfill esbuild's keepNames helper inside the page.
   //
   // The engine is published as raw TypeScript (`packages/engine/package.json`
@@ -1280,6 +1287,7 @@ async function constructCaptureSession(
     browser,
     browserLease,
     page,
+    targetRendererStatusTracker,
     options: sessionOptions,
     serverUrl,
     outputDir,
@@ -2025,6 +2033,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
     // Screenshot mode: standard navigation, rAF works normally
     await gotoEntryPage();
     logInitPhase("page.goto complete");
+    await session.targetRendererStatusTracker?.checkpoint("navigated");
 
     // Flush the GSAP proxy queue synchronously instead of waiting for
     // rAF-based batch ticks (100 ops/tick at ~16ms). In headless mode there's
@@ -2182,6 +2191,7 @@ export async function initializeSession(session: CaptureSession): Promise<void>
 
   await gotoEntryPage();
   logInitPhase("page.goto complete");
+  await session.targetRendererStatusTracker?.checkpoint("navigated");
 
   // Flush the GSAP proxy queue synchronously. In BeginFrame mode the rAF-based
   // batch drain runs on the warmup loop's 33ms ticks — for tween-heavy
@@ -3060,6 +3070,11 @@ async function captureFrameCore(
   // with the frame the seek actually lands on, even if `time` ever isn't exactly i/fps.
   const absFrameIndex = Math.floor(time * fpsToNumber(options.fps) + 1e-9);
   if (session.staticFrames?.has(absFrameIndex) && session.lastFrameBuffer) {
+    if (session.targetRendererStatusTracker) {
+      throw new Error(
+        "Target renderer proof does not support static-frame deduplication; disable HF_STATIC_DEDUP",
+      );
+    }
     session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
     return {
       buffer: session.lastFrameBuffer,
@@ -3178,6 +3193,11 @@ async function captureFrameCore(
       screenshotBuffer = await pageScreenshotCapture(page, options);
     }
 
+    // The renderer identity is sampled only after the final pixel buffer exists.
+    // This makes the acknowledged PID evidence causal for the frame we return,
+    // rather than merely for the page-side seek that preceded capture.
+    await session.targetRendererStatusTracker?.checkpoint("frame", frameIndex);
+
     const screenshotMs = Date.now() - screenshotStart;
     const captureTimeMs = Date.now() - startTime;
 
@@ -3272,6 +3292,11 @@ export async function captureFrameToBufferPipelined(
   frameIndex: number,
   time: number,
 ): Promise<{ encodeResult: Promise<Buffer>; captureTimeMs: number }> {
+  if (session.targetRendererStatusTracker) {
+    throw new Error(
+      "Target renderer proof does not support pipelined worker capture; use synchronous capture",
+    );
+  }
   const { page, options } = session;
   const startTime = Date.now();
 
@@ -3417,6 +3442,11 @@ export async function recaptureDrawElementFrameForVerify(
   frameIndex: number,
   time: number,
 ): Promise<Buffer> {
+  if (session.targetRendererStatusTracker) {
+    throw new Error(
+      "Target renderer proof does not support pipelined verification recapture; use synchronous capture",
+    );
+  }
   const { page, options } = session;
   if (!session.isInitialized) {
     throw new Error("[FrameCapture] Session not initialized");
@@ -3446,6 +3476,9 @@ export async function captureFramesBatchPipelined(
   frameIndices: number[],
   times: number[],
 ): Promise<Array<{ frameIndex: number; encodeResult: Promise<Buffer> }>> {
+  if (session.targetRendererStatusTracker) {
+    throw new Error("Target renderer proof does not support batch capture; disable HF_DE_BATCH");
+  }
   const { page, options } = session;
   if (!session.isInitialized) {
     throw new Error("[FrameCapture] Session not initialized");
@@ -3605,6 +3638,14 @@ export async function closeCaptureSession(session: CaptureSession): Promise<void
   // Example: page release succeeds, browser release throws → pageReleased=true
   // but browserReleased=false → second call no-ops on page and retries browser.
   // This matches the orchestrator's intent for HDR cleanup.
+  let targetRendererStatusError: unknown;
+  if (!session.pageReleased && session.page && session.targetRendererStatusTracker?.hasCheckpoint) {
+    try {
+      await session.targetRendererStatusTracker.checkpoint("completed");
+    } catch (error) {
+      targetRendererStatusError = error;
+    }
+  }
   if (session.workerEncodeEnabled && session.page && !session.pageReleased) {
     cleanupDrawElementWorkerEncode(session.page);
   }
@@ -3630,6 +3671,7 @@ export async function closeCaptureSession(session: CaptureSession): Promise<void
     session.browserReleased = true;
   }
   session.isInitialized = false;
+  if (targetRendererStatusError !== undefined) throw targetRendererStatusError;
 }
 
 export function prepareCaptureSessionForReuse(
diff --git a/packages/engine/src/services/targetRendererStatus.test.ts b/packages/engine/src/services/targetRendererStatus.test.ts
new file mode 100644
index 0000000000..a34ddf8c4d
--- /dev/null
+++ b/packages/engine/src/services/targetRendererStatus.test.ts
@@ -0,0 +1,257 @@
+import { EventEmitter } from "node:events";
+import { mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { CDPSession, Page } from "puppeteer-core";
+import { describe, expect, it } from "vitest";
+
+import {
+  TARGET_RENDERER_ACK_SCHEMA,
+  TargetRendererStatusTracker,
+  resolveTargetRendererTraceMapping,
+} from "./targetRendererStatus.js";
+
+describe("target renderer trace mapping", () => {
+  it("maps the exact main-frame id and URL to the latest Chromium renderer PID", () => {
+    expect(
+      resolveTargetRendererTraceMapping(
+        [
+          {
+            name: "TracingStartedInBrowser",
+            args: {
+              data: {
+                frames: [
+                  { frame: "other", url: "http://127.0.0.1/other", processId: 301 },
+                  { frame: "main", url: "http://127.0.0.1/index.html", processId: 302 },
+                ],
+              },
+            },
+          },
+          {
+            name: "ProcessReadyInBrowser",
+            args: { data: { frame: "main", processId: 303 } },
+          },
+        ],
+        "main",
+        "http://127.0.0.1/index.html",
+      ),
+    ).toEqual({
+      rendererPid: 303,
+      exactUrlObserved: true,
+      evidenceEvent: "ProcessReadyInBrowser",
+    });
+  });
+
+  it("rejects generic renderer metadata without exact URL/frame causality", () => {
+    expect(() =>
+      resolveTargetRendererTraceMapping(
+        [
+          {
+            name: "TracingStartedInBrowser",
+            args: {
+              data: {
+                frames: [{ frame: "other", url: "http://127.0.0.1/index.html", processId: 302 }],
+              },
+            },
+          },
+        ],
+        "main",
+        "http://127.0.0.1/index.html",
+      ),
+    ).toThrow("exact target URL/frame");
+  });
+
+  it("blocks a checkpoint until the exact sequence, target, and renderer PID are ACKed", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "target-renderer-status-test-"));
+    const statusPath = join(directory, "status.json");
+    const ackPath = join(directory, "ack.json");
+    class FakeSession extends EventEmitter {
+      readonly sentMethods: string[] = [];
+
+      constructor(readonly scope: "page" | "browser") {
+        super();
+      }
+
+      async send(method: string): Promise<unknown> {
+        this.sentMethods.push(method);
+        if (method.startsWith("Tracing.") && this.scope !== "page") {
+          throw new Error("Tracing must run on the page-target CDP session");
+        }
+        if (method === "Page.getFrameTree") {
+          return {
+            frameTree: { frame: { id: "frame-a", url: "http://127.0.0.1:4321/index.html" } },
+          };
+        }
+        if (method === "Target.getTargetInfo") {
+          return {
+            targetInfo: {
+              targetId: "target-a",
+              type: "page",
+              url: "http://127.0.0.1:4321/index.html",
+            },
+          };
+        }
+        if (method === "SystemInfo.getProcessInfo") {
+          if (this.scope !== "browser") {
+            throw new Error("SystemInfo.getProcessInfo requires the browser-target session");
+          }
+          return { processInfo: [{ id: 302, type: "renderer", cpuTime: 0 }] };
+        }
+        if (method === "Tracing.end") {
+          queueMicrotask(() => {
+            this.emit("Tracing.dataCollected", {
+              value: [
+                {
+                  name: "TracingStartedInBrowser",
+                  args: {
+                    data: {
+                      frames: [
+                        {
+                          frame: "frame-a",
+                          url: "http://127.0.0.1:4321/index.html",
+                          processId: 302,
+                        },
+                      ],
+                    },
+                  },
+                },
+              ],
+            });
+            this.emit("Tracing.tracingComplete", { dataLossOccurred: false });
+          });
+        }
+        return {};
+      }
+
+      async detach(): Promise<void> {}
+    }
+
+    const browserSession = new FakeSession("browser");
+    const pageSession = new FakeSession("page");
+    const page = {
+      createCDPSession: async () => pageSession as unknown as CDPSession,
+      url: () => "http://127.0.0.1:4321/index.html",
+      browser: () => ({
+        target: () => ({
+          createCDPSession: async () => browserSession as unknown as CDPSession,
+        }),
+      }),
+    } as unknown as Page;
+
+    try {
+      const tracker = new TargetRendererStatusTracker(page, statusPath, ackPath, 200);
+      let ackSequence = 0;
+      const writeAckAtomically = async (value: unknown) => {
+        const temporaryPath = `${ackPath}.${++ackSequence}.tmp`;
+        await writeFile(temporaryPath, `${JSON.stringify(value)}\n`);
+        await rename(temporaryPath, ackPath);
+      };
+      let settled = false;
+      const pending = tracker.checkpoint("navigated").finally(() => {
+        settled = true;
+      });
+
+      let status: Record<string, unknown> | undefined;
+      for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+          status = JSON.parse(await readFile(statusPath, "utf8"));
+          break;
+        } catch {
+          await new Promise((resolve) => setTimeout(resolve, 2));
+        }
+      }
+      expect(status).toMatchObject({ sequence: 1, targetId: "target-a", rendererPid: 302 });
+      expect(settled).toBe(false);
+
+      await writeAckAtomically({
+        schemaVersion: TARGET_RENDERER_ACK_SCHEMA,
+        sequence: 1,
+        targetId: "target-a",
+        rendererPid: 999,
+      });
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      expect(settled).toBe(false);
+
+      await writeAckAtomically({
+        schemaVersion: TARGET_RENDERER_ACK_SCHEMA,
+        sequence: 1,
+        targetId: "target-a",
+        rendererPid: 302,
+      });
+      await pending;
+      expect(settled).toBe(true);
+      expect(pageSession.sentMethods).toContain("Tracing.start");
+      expect(pageSession.sentMethods).toContain("Tracing.end");
+      expect(browserSession.sentMethods).not.toContain("Tracing.start");
+      expect(browserSession.sentMethods).toContain("SystemInfo.getProcessInfo");
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+
+  it("settles trace cleanup before detaching when a parallel metadata request fails", async () => {
+    const order: string[] = [];
+    class PageSession extends EventEmitter {
+      async send(method: string): Promise<unknown> {
+        if (method === "Page.getFrameTree") {
+          return {
+            frameTree: { frame: { id: "frame-a", url: "http://127.0.0.1:4321/index.html" } },
+          };
+        }
+        if (method === "Target.getTargetInfo") {
+          return {
+            targetInfo: {
+              targetId: "target-a",
+              type: "page",
+              url: "http://127.0.0.1:4321/index.html",
+            },
+          };
+        }
+        if (method === "Tracing.end") {
+          setTimeout(() => {
+            order.push("trace-complete");
+            this.emit("Tracing.tracingComplete", { dataLossOccurred: false });
+          }, 20);
+        }
+        return {};
+      }
+
+      async detach(): Promise<void> {
+        order.push("page-detach");
+      }
+    }
+    class BrowserSession extends EventEmitter {
+      async send(method: string): Promise<unknown> {
+        if (method === "SystemInfo.getProcessInfo") {
+          throw new Error("process metadata failed");
+        }
+        return {};
+      }
+
+      async detach(): Promise<void> {
+        order.push("browser-detach");
+      }
+    }
+
+    const pageSession = new PageSession();
+    const browserSession = new BrowserSession();
+    const page = {
+      createCDPSession: async () => pageSession as unknown as CDPSession,
+      url: () => "http://127.0.0.1:4321/index.html",
+      browser: () => ({
+        target: () => ({
+          createCDPSession: async () => browserSession as unknown as CDPSession,
+        }),
+      }),
+    } as unknown as Page;
+    const tracker = new TargetRendererStatusTracker(page, "/tmp/status.json", "/tmp/ack.json", 200);
+
+    await expect(tracker.checkpoint("navigated")).rejects.toThrow("process metadata failed");
+
+    expect(order[0]).toBe("trace-complete");
+    expect(order.slice(1).sort()).toEqual(["browser-detach", "page-detach"]);
+    expect(pageSession.listenerCount("Tracing.dataCollected")).toBe(0);
+    expect(pageSession.listenerCount("Tracing.tracingComplete")).toBe(0);
+  });
+});
diff --git a/packages/engine/src/services/targetRendererStatus.ts b/packages/engine/src/services/targetRendererStatus.ts
new file mode 100644
index 0000000000..89be6b2625
--- /dev/null
+++ b/packages/engine/src/services/targetRendererStatus.ts
@@ -0,0 +1,342 @@
+import { randomUUID } from "node:crypto";
+import { open, readFile, rename, unlink } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+
+import type { CDPSession, Page } from "puppeteer-core";
+
+export const TARGET_RENDERER_STATUS_PATH_ENV = "PRODUCER_TARGET_RENDERER_STATUS_PATH";
+export const TARGET_RENDERER_ACK_PATH_ENV = "PRODUCER_TARGET_RENDERER_ACK_PATH";
+export const TARGET_RENDERER_STATUS_SCHEMA = "hyperframes.target-renderer.v1";
+export const TARGET_RENDERER_ACK_SCHEMA = "hyperframes.target-renderer-ack.v1";
+
+const ACK_TIMEOUT_MS = 5_000;
+const MAX_ACK_BYTES = 4 * 1024;
+const TRACE_TIMEOUT_MS = 5_000;
+
+export type TargetRendererCheckpointPhase = "navigated" | "frame" | "completed";
+
+interface TraceEvent {
+  name?: string;
+  args?: {
+    data?: {
+      frame?: string;
+      processId?: number;
+      url?: string;
+      frames?: Array<{
+        frame?: string;
+        processId?: number;
+        url?: string;
+      }>;
+    };
+  };
+}
+
+export interface TargetRendererTraceMapping {
+  rendererPid: number;
+  exactUrlObserved: boolean;
+  evidenceEvent: "TracingStartedInBrowser" | "FrameCommittedInBrowser" | "ProcessReadyInBrowser";
+}
+
+export interface TargetRendererStatusV1 {
+  schemaVersion: typeof TARGET_RENDERER_STATUS_SCHEMA;
+  sequence: number;
+  phase: TargetRendererCheckpointPhase;
+  frameIndex?: number;
+  capturedAt: string;
+  browserPid: number;
+  targetId: string;
+  targetType: string;
+  frameId: string;
+  targetUrl: string;
+  rendererPid: number;
+  rendererPids: number[];
+  processInfoType: string;
+  traceEvidenceEvent: TargetRendererTraceMapping["evidenceEvent"];
+}
+
+function isPositiveSafeInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && typeof value === "number" && value > 0;
+}
+
+/** Resolve only the process mapped by Chromium trace metadata to the exact main frame. */
+export function resolveTargetRendererTraceMapping(
+  events: readonly TraceEvent[],
+  frameId: string,
+  targetUrl: string,
+): TargetRendererTraceMapping {
+  const candidates: Array<{
+    rendererPid: number;
+    url?: string;
+    evidenceEvent: TargetRendererTraceMapping["evidenceEvent"];
+  }> = [];
+
+  for (const event of events) {
+    if (event.name === "TracingStartedInBrowser") {
+      for (const frame of event.args?.data?.frames ?? []) {
+        if (frame.frame === frameId && isPositiveSafeInteger(frame.processId)) {
+          candidates.push({
+            rendererPid: frame.processId,
+            url: frame.url,
+            evidenceEvent: "TracingStartedInBrowser",
+          });
+        }
+      }
+      continue;
+    }
+    if (event.name !== "FrameCommittedInBrowser" && event.name !== "ProcessReadyInBrowser") {
+      continue;
+    }
+    const data = event.args?.data;
+    if (data?.frame === frameId && isPositiveSafeInteger(data.processId)) {
+      candidates.push({
+        rendererPid: data.processId,
+        url: data.url,
+        evidenceEvent: event.name,
+      });
+    }
+  }
+
+  const exactUrlObserved = candidates.some(({ url }) => url === targetUrl);
+  const latest = candidates.at(-1);
+  if (!latest || !exactUrlObserved) {
+    throw new Error("Trace metadata did not map the exact target URL/frame to a renderer PID");
+  }
+  return {
+    rendererPid: latest.rendererPid,
+    exactUrlObserved,
+    evidenceEvent: latest.evidenceEvent,
+  };
+}
+
+async function writeJsonAtomically(path: string, value: unknown): Promise<void> {
+  if (!isAbsolute(path)) throw new Error("Target renderer status path must be absolute");
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(temporaryPath, "wx", 0o600);
+    await handle.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+    await handle.chmod(0o600);
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await unlink(temporaryPath).catch(() => {});
+    throw error;
+  }
+}
+
+async function waitForAcknowledgement(
+  path: string,
+  status: Pick<TargetRendererStatusV1, "sequence" | "targetId" | "rendererPid">,
+): Promise<void> {
+  const deadline = Date.now() + ACK_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    try {
+      const bytes = await readFile(path);
+      if (bytes.byteLength > MAX_ACK_BYTES) throw new Error("Target renderer ACK is oversized");
+      const acknowledgement = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
+      if (
+        acknowledgement.schemaVersion === TARGET_RENDERER_ACK_SCHEMA &&
+        acknowledgement.sequence === status.sequence &&
+        acknowledgement.targetId === status.targetId &&
+        acknowledgement.rendererPid === status.rendererPid
+      ) {
+        return;
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(`Target renderer checkpoint ${status.sequence} was not acknowledged`);
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  let timeout: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_resolve, reject) => {
+        timeout = setTimeout(
+          () => reject(new Error(`${label} timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+        timeout.unref();
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+async function collectTraceSnapshot(pageSession: CDPSession): Promise<TraceEvent[]> {
+  const events: TraceEvent[] = [];
+  const onData = (event: { value?: TraceEvent[] }) => {
+    if (Array.isArray(event.value)) events.push(...event.value);
+  };
+  let resolveComplete = () => {};
+  const complete = new Promise<void>((resolve) => {
+    resolveComplete = resolve;
+  });
+  const onComplete = () => resolveComplete();
+  let tracingMayBeActive = false;
+  let endCommandCompleted = false;
+  pageSession.on("Tracing.dataCollected", onData);
+  pageSession.on("Tracing.tracingComplete", onComplete);
+  try {
+    tracingMayBeActive = true;
+    await withTimeout(
+      pageSession.send("Tracing.start", {
+        transferMode: "ReportEvents",
+        traceConfig: {
+          recordMode: "recordUntilFull",
+          includedCategories: [
+            "__metadata",
+            "devtools.timeline",
+            "disabled-by-default-devtools.timeline",
+          ],
+        },
+      }),
+      TRACE_TIMEOUT_MS,
+      "Tracing.start",
+    );
+    await withTimeout(
+      pageSession.send("Runtime.evaluate", { expression: "void 0", returnByValue: true }),
+      TRACE_TIMEOUT_MS,
+      "Trace Runtime.evaluate",
+    );
+    await withTimeout(
+      pageSession.send("Tracing.recordClockSyncMarker", {
+        syncId: `target-renderer-${randomUUID()}`,
+      }),
+      TRACE_TIMEOUT_MS,
+      "Tracing.recordClockSyncMarker",
+    );
+    await withTimeout(pageSession.send("Tracing.end"), TRACE_TIMEOUT_MS, "Tracing.end");
+    endCommandCompleted = true;
+    await withTimeout(complete, TRACE_TIMEOUT_MS, "Tracing.tracingComplete");
+    tracingMayBeActive = false;
+    return events;
+  } catch (error) {
+    if (tracingMayBeActive && !endCommandCompleted) {
+      await withTimeout(
+        pageSession.send("Tracing.end"),
+        TRACE_TIMEOUT_MS,
+        "Tracing.end cleanup",
+      ).catch(() => {});
+    }
+    if (tracingMayBeActive) {
+      await withTimeout(complete, TRACE_TIMEOUT_MS, "Tracing.tracingComplete cleanup").catch(
+        () => {},
+      );
+    }
+    throw error;
+  } finally {
+    pageSession.off("Tracing.dataCollected", onData);
+    pageSession.off("Tracing.tracingComplete", onComplete);
+  }
+}
+
+export class TargetRendererStatusTracker {
+  readonly #page: Page;
+  readonly #statusPath: string;
+  readonly #ackPath: string;
+  readonly #browserPid: number;
+  readonly #rendererPids = new Set<number>();
+  #sequence = 0;
+
+  constructor(page: Page, statusPath: string, ackPath: string, browserPid: number) {
+    this.#page = page;
+    this.#statusPath = statusPath;
+    this.#ackPath = ackPath;
+    this.#browserPid = browserPid;
+  }
+
+  get hasCheckpoint(): boolean {
+    return this.#sequence > 0;
+  }
+
+  async checkpoint(phase: TargetRendererCheckpointPhase, frameIndex?: number): Promise<void> {
+    const pageSession = await this.#page.createCDPSession();
+    let browserSession: CDPSession | undefined;
+    try {
+      browserSession = await this.#page.browser().target().createCDPSession();
+      const tracePromise = collectTraceSnapshot(pageSession);
+      try {
+        const [events, frameTreeResult, targetInfoResult, processInfoResult] = await Promise.all([
+          tracePromise,
+          pageSession.send("Page.getFrameTree"),
+          pageSession.send("Target.getTargetInfo"),
+          browserSession.send("SystemInfo.getProcessInfo"),
+        ]);
+        const frame = frameTreeResult.frameTree.frame;
+        const target = targetInfoResult.targetInfo;
+        const targetUrl = this.#page.url();
+        if (frame.url !== targetUrl || target.url !== targetUrl || target.type !== "page") {
+          throw new Error("Page, frame-tree, and target metadata do not identify one exact page");
+        }
+
+        const mapping = resolveTargetRendererTraceMapping(events, frame.id, targetUrl);
+        const processInfo = processInfoResult.processInfo.find(
+          ({ id }) => id === mapping.rendererPid,
+        );
+        if (processInfo?.type !== "renderer") {
+          throw new Error("Mapped target PID is not a live Chromium renderer process");
+        }
+
+        this.#rendererPids.add(mapping.rendererPid);
+        const status: TargetRendererStatusV1 = {
+          schemaVersion: TARGET_RENDERER_STATUS_SCHEMA,
+          sequence: ++this.#sequence,
+          phase,
+          ...(frameIndex === undefined ? {} : { frameIndex }),
+          capturedAt: new Date().toISOString(),
+          browserPid: this.#browserPid,
+          targetId: target.targetId,
+          targetType: target.type,
+          frameId: frame.id,
+          targetUrl,
+          rendererPid: mapping.rendererPid,
+          rendererPids: [...this.#rendererPids],
+          processInfoType: processInfo.type,
+          traceEvidenceEvent: mapping.evidenceEvent,
+        };
+        await writeJsonAtomically(this.#statusPath, status);
+        await waitForAcknowledgement(this.#ackPath, status);
+      } finally {
+        // Promise.all rejects as soon as any metadata request fails. Do not detach
+        // the CDP sessions until tracing has reached its own bounded cleanup path.
+        await tracePromise.catch(() => {});
+      }
+    } finally {
+      await Promise.all([
+        withTimeout(pageSession.detach(), TRACE_TIMEOUT_MS, "Page CDP detach").catch(() => {}),
+        browserSession
+          ? withTimeout(browserSession.detach(), TRACE_TIMEOUT_MS, "Browser CDP detach").catch(
+              () => {},
+            )
+          : undefined,
+      ]);
+    }
+  }
+}
+
+/** Inert unless both canary-only status and acknowledgement paths are set. */
+export function createTargetRendererStatusTracker(
+  page: Page,
+  environment = process.env,
+): TargetRendererStatusTracker | undefined {
+  const statusPath = environment[TARGET_RENDERER_STATUS_PATH_ENV]?.trim();
+  const ackPath = environment[TARGET_RENDERER_ACK_PATH_ENV]?.trim();
+  if (!statusPath && !ackPath) return undefined;
+  if (!statusPath || !ackPath || !isAbsolute(statusPath) || !isAbsolute(ackPath)) {
+    throw new Error("Both target renderer status/ACK paths must be absolute");
+  }
+  const browserPid = page.browser().process()?.pid;
+  if (!isPositiveSafeInteger(browserPid)) {
+    throw new Error("Unable to identify browser PID for target renderer status");
+  }
+  return new TargetRendererStatusTracker(page, statusPath, ackPath, browserPid);
+}