@specific.dev/spectest 0.131.3 → 0.131.4

package/dist/browser-coverage.d.ts

@@ -12,16 +12,16 @@ export declare function browserCoverageActive(): boolean;
 export declare function attachBrowserCoverage(cdp: CDPSession): Promise<void>;
 /**
  * Take the session's counters and fold them into the totals. Concurrent
- * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
- * a closed view) are swallowed: the counters then stay in V8 for the next
- * take, nothing is lost.
+ * calls coalesce onto the in-flight one. A timed-out take is ambiguous: V8
+ * may already have reset its counters. Retain that error for service capture
+ * rather than issuing another take or reporting an apparently complete file.
  */
-export declare function harvestBrowserCoverage(cdp: CDPSession): Promise<void>;
+export declare function harvestBrowserCoverage(cdp: CDPSession, signal?: AbortSignal): Promise<void>;
 /** Fold one script's per-file counts into a service's totals. */
 export declare function foldBrowserCoverage(service: string, files: FileCounts): void;
 /** Harvest every live session, so a capture sees the counters of code
  *  that ran since the last browser op. */
-export declare function harvestAllBrowserCoverage(): Promise<void>;
+export declare function harvestAllBrowserCoverage(signal?: AbortSignal): Promise<void>;
 /** Take one service's lcov report and clear only its totals. Other
  *  services retain their coverage until their own capture. Each capture
  *  is a delta; after every service is captured, a forked child inherits

package/dist/browser-coverage.js

@@ -60,28 +60,62 @@ export async function attachBrowserCoverage(cdp) {
 }
 /**
  * Take the session's counters and fold them into the totals. Concurrent
- * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
- * a closed view) are swallowed: the counters then stay in V8 for the next
- * take, nothing is lost.
+ * calls coalesce onto the in-flight one. A timed-out take is ambiguous: V8
+ * may already have reset its counters. Retain that error for service capture
+ * rather than issuing another take or reporting an apparently complete file.
  */
-export async function harvestBrowserCoverage(cdp) {
+export async function harvestBrowserCoverage(cdp, signal) {
     const c = COLLECTORS.get(cdp);
     if (!c || !CONFIG)
         return;
-    if (c.inFlight)
-        return c.inFlight;
-    c.inFlight = harvestInner(c, CONFIG).catch(() => { }).finally(() => {
-        c.inFlight = null;
-    });
-    return c.inFlight;
+    if (c.incomplete)
+        throw c.incomplete;
+    if (signal?.aborted) {
+        c.abort?.abort(signal.reason);
+        signal.throwIfAborted();
+    }
+    if (!c.inFlight) {
+        const config = CONFIG;
+        const abort = c.abort = new AbortController();
+        const interrupted = new Promise((_, reject) => {
+            abort.signal.addEventListener("abort", () => {
+                c.incomplete = new Error("Browser coverage capture was interrupted; coverage is incomplete");
+                reject(c.incomplete);
+            }, { once: true });
+        });
+        c.inFlight = Promise.race([harvestInner(c, config, abort.signal), interrupted]).catch(() => {
+            if (c.incomplete)
+                throw c.incomplete;
+            // Preserve the existing handling of closed/navigating pages.
+        }).finally(() => {
+            c.inFlight = null;
+            c.abort = undefined;
+        });
+    }
+    // Only the existing adapter capture budget can interrupt a take. Browser
+    // operations introduce no new deadline. A capture may join a take that was
+    // started by an earlier browser operation, so wire its signal here too.
+    const abort = c.abort;
+    const interrupt = () => abort.abort(signal?.reason);
+    signal?.addEventListener("abort", interrupt, { once: true });
+    if (signal?.aborted)
+        interrupt();
+    try {
+        await c.inFlight;
+    }
+    finally {
+        signal?.removeEventListener("abort", interrupt);
+    }
 }
-async function harvestInner(c, config) {
+async function harvestInner(c, config, signal) {
     let result;
     try {
         ({ result } = (await c.cdp.send("Profiler.takePreciseCoverage")));
+        signal.throwIfAborted();
     }
     catch (err) {
-        LIVE_COLLECTORS.delete(c); // the session is gone
+        if (!signal.aborted)
+            LIVE_COLLECTORS.delete(c); // the session is gone
         throw err;
     }
     for (const script of result) {
@@ -105,9 +139,11 @@ async function harvestInner(c, config) {
                 const r = (await c.cdp.send("Debugger.getScriptSource", {
                     scriptId: script.scriptId,
                 }));
+                signal.throwIfAborted();
                 info.source = r.scriptSource;
             }
             catch {
+                signal.throwIfAborted();
                 continue; // script gone with its document
             }
             c.scripts.set(script.scriptId, info);
@@ -117,6 +153,7 @@ async function harvestInner(c, config) {
             continue;
         if (info.map === undefined)
             info.map = await sourceMapFor(info, url);
+        signal.throwIfAborted();
         if (!info.map && isDocumentScriptPath(url.pathname))
             continue; // inline script in a page
         const files = info.map
@@ -193,8 +230,8 @@ function parseDataUrl(ref) {
 }
 /** Harvest every live session, so a capture sees the counters of code
  *  that ran since the last browser op. */
-export async function harvestAllBrowserCoverage() {
-    await Promise.all([...LIVE_COLLECTORS].map((c) => harvestBrowserCoverage(c.cdp)));
+export async function harvestAllBrowserCoverage(signal) {
+    await Promise.all([...LIVE_COLLECTORS].map((c) => harvestBrowserCoverage(c.cdp, signal)));
 }
 /** Take one service's lcov report and clear only its totals. Other
  *  services retain their coverage until their own capture. Each capture

package/dist/browser.js

@@ -33,6 +33,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { generateId } from "./ids.js";
 import { rawFetch } from "./harness/raw-fetch.js";
+import { withDeadline } from "./harness/deadline.js";
 import { prepareMicrophoneFixture } from "./harness/microphone-fixture.js";
 import { DESKTOP_INPUT_SYNC_SCRIPT } from "./desktop-recorder.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
@@ -1283,6 +1284,7 @@ function buildBackend(holder, recorder, buildOpts) {
     // `recordingEnded` stops this wrapper's recorder writes (test end);
     // `viewClosed` tracks actual destruction (author called close()).
     let recordingEnded = false;
+    let recordingEnd;
     let viewClosed = false;
     const sessionStart = Date.now();
     let stepSeq = 0;
@@ -1335,12 +1337,20 @@ function buildBackend(holder, recorder, buildOpts) {
             ...(recorder.sessionName ? { sessionName: recorder.sessionName } : {}),
         };
     }
-    async function drain(action, timestamp = Date.now()) {
+    async function drain(action, timestamp = Date.now(), signal) {
         if (!holder.recordingInstalled || !recorder || recordingEnded)
             return;
         try {
             const urlChanged = holder.page.url() !== lastDrainUrl;
-            const events = (await holder.page.evaluate(drainExpr(urlChanged, timestamp)));
+            // Finalization only reads the buffer. A timed-out evaluation may run
+            // after a child/eval attaches; it must not clear that session's events.
+            const expression = action === "close"
+                ? "window.__spectestRrwebEvents || []"
+                : drainExpr(urlChanged, timestamp);
+            const events = (await holder.page.evaluate(expression));
+            signal?.throwIfAborted();
+            if (recordingEnded)
+                return;
             lastDrainUrl = holder.page.url();
             if (Array.isArray(events) && events.length > 0) {
                 recorder.recordStep({
@@ -1352,6 +1362,7 @@ function buildBackend(holder, recorder, buildOpts) {
             }
         }
         catch {
+            signal?.throwIfAborted();
             // Page may be mid-navigation, detached, or the view is closing.
             // Losing an occasional drain is acceptable — the next op picks up
             // the rest of the buffer.
@@ -1369,6 +1380,8 @@ function buildBackend(holder, recorder, buildOpts) {
             catch {
                 /* page mid-navigation or closed — keep the stale cache */
             }
+            if (recordingEnded)
+                return result;
             // `sessionTimestamp` is the post-op wall clock — that's where we
             // want the dashboard's seek to land, so clicking "type 'foo'"
             // shows the input *with* the text, not the empty field just
@@ -1402,12 +1415,16 @@ function buildBackend(holder, recorder, buildOpts) {
             return result;
         }
         catch (err) {
+            if (recordingEnded)
+                throw err;
             const e = err;
             const endT = Date.now();
             const error = e?.message ?? String(err);
             // Captured after the clock stops, so the diagnostic is not billed to
             // the step, and before the event is recorded, so it rides it.
             const pageStructure = await failedPageStructure(action, error);
+            if (recordingEnded)
+                throw err;
             recordBrowser({
                 action,
                 ...fields,
@@ -1422,20 +1439,21 @@ function buildBackend(holder, recorder, buildOpts) {
             throw err;
         }
     }
-    async function endRecording() {
-        if (recordingEnded)
-            return;
-        // Final drain before we stop writing to this recorder.
-        await drain("close");
-        if (browserCoverageActive()) {
+    function endRecording() {
+        // A stuck renderer must not prevent the test result from returning. The
+        // signal and ended guard discard late recorder writes. Missing optional
+        // replay data is a warning, not a failed test. Concurrent close/detach
+        // calls share the same bounded attempt.
+        return recordingEnd ??= (async () => {
             try {
-                await harvestBrowserCoverage(holder.cdp);
+                await withDeadline("Browser recording finalization", 10_000, signal => drain("close", Date.now(), signal));
+                // Coverage is collected by the service capture after recording
+                // finalization. Do not harvest it twice on the test-end path.
             }
-            catch {
-                /* best-effort */
+            finally {
+                recordingEnded = true;
             }
-        }
-        recordingEnded = true;
+        })();
     }
     const strategy = holder.device ? mobileStrategy : desktopStrategy;
     const keyboard = {
@@ -1659,9 +1677,22 @@ function buildBackend(holder, recorder, buildOpts) {
             // the next `ctx.browser()`/`ctx.mobile()` creates a new one. The
             // routine test-end path is `detach` (recording stops, view lives on
             // into the post-test snapshot).
-            await endRecording();
+            try {
+                await endRecording();
+            }
+            catch (error) {
+                console.warn("[browser finalization]", error instanceof Error ? error.message : String(error));
+            }
             if (viewClosed)
                 return;
+            // An explicit close destroys the renderer, unlike detach. Harvest its
+            // counters before destroying it; service capture handles live views.
+            if (browserCoverageActive()) {
+                try {
+                    await harvestBrowserCoverage(holder.cdp);
+                }
+                catch { /* capture reports the error */ }
+            }
             viewClosed = true;
             buildOpts.onDestroy?.();
             try {
@@ -1745,6 +1776,8 @@ function buildBackend(holder, recorder, buildOpts) {
             // A matcher that ran out of budget is the other half of a failed
             // browser step, and the page it settled on is the same evidence.
             const pageStructure = error ? await failedPageStructure(action, error) : undefined;
+            if (recordingEnded)
+                return undefined;
             const seq = recordBrowser({
                 action,
                 ...fields,

package/dist/coverage.js

@@ -1009,7 +1009,7 @@ export function browser(options = {}) {
             ctx.collectBrowserScripts();
         },
         async capture(ctx) {
-            await harvestAllBrowserCoverage();
+            await harvestAllBrowserCoverage(ctx.signal);
             const lcov = takeBrowserCoverageReport(ctx.service);
             await ctx.writeReport("browser.lcov", lcov);
         },

package/dist/daemon.js

@@ -1,3 +1,4 @@
+import { finalizeBrowserRecordings } from "./harness/deadline.js";
 import { ensureServiceNetwork, serviceIpv4Gateway } from "./harness/service-network.js";
 import { collectSecretRefs } from "./fake-upstream.js";
 import { phoneScope, phoneRecordingChunk, releasePhoneRecording } from "./phone.js";
@@ -4437,13 +4438,10 @@ async function runOne(testCase) {
         // this test's recorder. The Chromium itself deliberately stays alive
         // — it's part of the state the post-test snapshot captures for
         // dependsOn children (see the acquire comment above).
-        for (const detach of browserDetaches) {
-            try {
-                await detach();
-            }
-            catch {
-                /* ignore */
-            }
+        const browserErrors = await finalizeBrowserRecordings(browserDetaches);
+        if (browserErrors.length) {
+            const message = browserErrors.join("\n");
+            chunks.push(`[browser finalization] ${message}\n`);
         }
         for (const s of sessions)
             s.markClosed();
@@ -4929,13 +4927,10 @@ async function evalCode(code) {
         process.stderr.write = origStderr;
         // Detach (final rrweb drain) — the browser itself stays alive; see
         // the acquire comment above.
-        for (const detach of browserDetaches) {
-            try {
-                await detach();
-            }
-            catch {
-                /* ignore */
-            }
+        const browserErrors = await finalizeBrowserRecordings(browserDetaches);
+        if (browserErrors.length) {
+            const message = browserErrors.join("\n");
+            chunks.push(`[browser finalization] ${message}\n`);
         }
         for (const s of sessions)
             s.markClosed();

package/dist/harness/deadline.d.ts

@@ -0,0 +1,7 @@
+/** Bound an async operation and invalidate its late result. Work must check
+ * the signal before committing state after an await; racing alone does not
+ * cancel a Playwright/CDP request already sent to the browser. */
+export declare function withDeadline<T>(label: string, timeoutMs: number, work: (signal: AbortSignal) => Promise<T>): Promise<T>;
+/** Start all browser drains together. One wedged view must not consume a
+ * separate finalization allowance for every other view in the test. */
+export declare function finalizeBrowserRecordings(detaches: Array<() => Promise<void>>): Promise<string[]>;

package/dist/harness/deadline.js

@@ -0,0 +1,29 @@
+/** Bound an async operation and invalidate its late result. Work must check
+ * the signal before committing state after an await; racing alone does not
+ * cancel a Playwright/CDP request already sent to the browser. */
+export async function withDeadline(label, timeoutMs, work) {
+    const controller = new AbortController();
+    let timer;
+    try {
+        return await Promise.race([
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    const error = new Error(`${label} did not finish within ${timeoutMs}ms`);
+                    controller.abort(error);
+                    reject(error);
+                }, timeoutMs);
+            }),
+            work(controller.signal),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Start all browser drains together. One wedged view must not consume a
+ * separate finalization allowance for every other view in the test. */
+export async function finalizeBrowserRecordings(detaches) {
+    const results = await Promise.allSettled(detaches.map(detach => Promise.resolve().then(detach)));
+    return results.flatMap(result => result.status === "rejected"
+        ? [result.reason instanceof Error ? result.reason.message : String(result.reason)] : []);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.131.3",
+  "version": "0.131.4",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser-coverage-deadline.test.ts

@@ -0,0 +1,62 @@
+import { expect, test } from "bun:test";
+import type { CDPSession } from "playwright-core";
+import { attachBrowserCoverage, browserCoverageReports, configureBrowserCoverage, harvestAllBrowserCoverage, harvestBrowserCoverage } from "./browser-coverage.js";
+
+test("an ambiguous coverage timeout is retained and a late CDP result cannot publish counts", async () => {
+  configureBrowserCoverage({ serviceForHost: () => "coverage-deadline-test" });
+  let resolveTake!: (value: unknown) => void;
+  const take = new Promise(resolve => { resolveTake = resolve; });
+  let takes = 0;
+  let sourceReads = 0;
+  const cdp = {
+    on() {},
+    async send(method: string) {
+      if (method === "Profiler.takePreciseCoverage") { takes++; return take; }
+      if (method === "Debugger.getScriptSource") { sourceReads++; return {scriptSource:"example();"}; }
+      return {};
+    },
+  } as unknown as CDPSession;
+  try {
+    await attachBrowserCoverage(cdp);
+    const first = harvestBrowserCoverage(cdp);
+    const concurrent = harvestBrowserCoverage(cdp, AbortSignal.timeout(30));
+    const results = await Promise.allSettled([first, concurrent]);
+    expect(results.every(r => r.status === "rejected" && r.reason.message.includes("coverage is incomplete"))).toBe(true);
+    expect(takes).toBe(1);
+    resolveTake({ result: [{scriptId:"1",url:"http://app.test/main.js",functions:[{ranges:[{startOffset:0,endOffset:10,count:1}]}]}] });
+    await Bun.sleep(0);
+    expect(sourceReads).toBe(0);
+    expect(browserCoverageReports().has("coverage-deadline-test")).toBe(false);
+    await expect(harvestAllBrowserCoverage()).rejects.toThrow("Browser coverage capture was interrupted; coverage is incomplete");
+    expect(takes).toBe(1);
+  } finally { configureBrowserCoverage(null); }
+});
+
+test("cancelling during script retrieval discards late source and coverage totals", async () => {
+  configureBrowserCoverage({ serviceForHost: () => "late-source-test" });
+  let resolveSource!: (value: unknown) => void;
+  let sourceStarted!: () => void;
+  const started = new Promise<void>(resolve => { sourceStarted = resolve; });
+  const source = new Promise(resolve => { resolveSource = resolve; });
+  const cdp = {
+    on() {},
+    async send(method: string) {
+      if (method === "Profiler.takePreciseCoverage") return {result:[{scriptId:"1",url:"http://app.test/late.js",functions:[{ranges:[{startOffset:0,endOffset:10,count:1}]}]}]};
+      if (method === "Debugger.getScriptSource") { sourceStarted(); return source; }
+      return {};
+    },
+  } as unknown as CDPSession;
+  try {
+    await attachBrowserCoverage(cdp);
+    const take = harvestBrowserCoverage(cdp);
+    const settled = Promise.allSettled([take]);
+    await started;
+    const cancelled = new AbortController();
+    cancelled.abort();
+    await expect(harvestBrowserCoverage(cdp, cancelled.signal)).rejects.toThrow();
+    expect((await settled)[0].status).toBe("rejected");
+    resolveSource({scriptSource:"example();"});
+    await Bun.sleep(0);
+    expect(browserCoverageReports().has("late-source-test")).toBe(false);
+  } finally { configureBrowserCoverage(null); }
+});

package/src/browser-coverage.ts

@@ -65,6 +65,8 @@ interface Collector {
   cdp: CDPSession;
   scripts: Map<string, ScriptInfo>;
   inFlight: Promise<void> | null;
+  incomplete?: Error;
+  abort?: AbortController;
 }
 
 const COLLECTORS = new WeakMap<CDPSession, Collector>();
@@ -98,26 +100,53 @@ export async function attachBrowserCoverage(cdp: CDPSession): Promise<void> {
 
 /**
  * Take the session's counters and fold them into the totals. Concurrent
- * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
- * a closed view) are swallowed: the counters then stay in V8 for the next
- * take, nothing is lost.
+ * calls coalesce onto the in-flight one. A timed-out take is ambiguous: V8
+ * may already have reset its counters. Retain that error for service capture
+ * rather than issuing another take or reporting an apparently complete file.
  */
-export async function harvestBrowserCoverage(cdp: CDPSession): Promise<void> {
+export async function harvestBrowserCoverage(cdp: CDPSession, signal?: AbortSignal): Promise<void> {
   const c = COLLECTORS.get(cdp);
   if (!c || !CONFIG) return;
-  if (c.inFlight) return c.inFlight;
-  c.inFlight = harvestInner(c, CONFIG).catch(() => {}).finally(() => {
-    c.inFlight = null;
-  });
-  return c.inFlight;
+  if (c.incomplete) throw c.incomplete;
+  if (signal?.aborted) {
+    c.abort?.abort(signal.reason);
+    signal.throwIfAborted();
+  }
+  if (!c.inFlight) {
+    const config = CONFIG;
+    const abort = c.abort = new AbortController();
+    const interrupted = new Promise<never>((_, reject) => {
+      abort.signal.addEventListener("abort", () => {
+        c.incomplete = new Error("Browser coverage capture was interrupted; coverage is incomplete");
+        reject(c.incomplete);
+      }, { once: true });
+    });
+    c.inFlight = Promise.race([harvestInner(c, config, abort.signal), interrupted]).catch(() => {
+      if (c.incomplete) throw c.incomplete;
+      // Preserve the existing handling of closed/navigating pages.
+    }).finally(() => {
+      c.inFlight = null;
+      c.abort = undefined;
+    });
+  }
+  // Only the existing adapter capture budget can interrupt a take. Browser
+  // operations introduce no new deadline. A capture may join a take that was
+  // started by an earlier browser operation, so wire its signal here too.
+  const abort = c.abort!;
+  const interrupt = () => abort.abort(signal?.reason);
+  signal?.addEventListener("abort", interrupt, { once: true });
+  if (signal?.aborted) interrupt();
+  try { await c.inFlight; }
+  finally { signal?.removeEventListener("abort", interrupt); }
 }
 
-async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promise<void> {
+async function harvestInner(c: Collector, config: BrowserCoverageConfig, signal: AbortSignal): Promise<void> {
   let result: { scriptId: string; url: string; functions: V8FunctionCoverage[] }[];
   try {
     ({ result } = (await c.cdp.send("Profiler.takePreciseCoverage")) as { result: typeof result });
+    signal.throwIfAborted();
   } catch (err) {
-    LIVE_COLLECTORS.delete(c); // the session is gone
+    if (!signal.aborted) LIVE_COLLECTORS.delete(c); // the session is gone
     throw err;
   }
   for (const script of result) {
@@ -137,8 +166,10 @@ async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promis
         const r = (await c.cdp.send("Debugger.getScriptSource", {
           scriptId: script.scriptId,
         })) as { scriptSource: string };
+        signal.throwIfAborted();
         info.source = r.scriptSource;
       } catch {
+        signal.throwIfAborted();
         continue; // script gone with its document
       }
       c.scripts.set(script.scriptId, info);
@@ -146,6 +177,7 @@ async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promis
     const generated = rangesToLineCounts(info.source, script.functions);
     if (generated.size === 0) continue;
     if (info.map === undefined) info.map = await sourceMapFor(info, url);
+    signal.throwIfAborted();
     if (!info.map && isDocumentScriptPath(url.pathname)) continue; // inline script in a page
     const files: FileCounts = info.map
       ? mapToOriginal(info.map, generated)
@@ -216,8 +248,8 @@ function parseDataUrl(ref: string): unknown {
 
 /** Harvest every live session, so a capture sees the counters of code
  *  that ran since the last browser op. */
-export async function harvestAllBrowserCoverage(): Promise<void> {
-  await Promise.all([...LIVE_COLLECTORS].map((c) => harvestBrowserCoverage(c.cdp)));
+export async function harvestAllBrowserCoverage(signal?: AbortSignal): Promise<void> {
+  await Promise.all([...LIVE_COLLECTORS].map((c) => harvestBrowserCoverage(c.cdp, signal)));
 }
 
 /** Take one service's lcov report and clear only its totals. Other

package/src/browser-finalization.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "bun:test";
+import { acquirePersistentBrowser } from "./browser.js";
+import { finalizeBrowserRecordings } from "./harness/deadline.js";
+
+const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"));
+
+test.skipIf(!available)("stuck replay drains are bounded warnings and late replies cannot change the recording or clear a later buffer", async () => {
+  const chunks: unknown[] = [];
+  const session = await acquirePersistentBrowser("stuck-finalization", {
+    url: "data:text/html,<title>finalization</title><p>retained page</p>",
+    recorder: { sessionId: "stuck-finalization", recordStep: step => { chunks.push(step); } },
+  });
+  const healthyChunks: unknown[] = [];
+  const healthy = await acquirePersistentBrowser("healthy-finalization", {
+    url: "data:text/html,<p>healthy</p>",
+    recorder: { sessionId: "healthy-finalization", recordStep: step => { healthyChunks.push(step); } },
+  });
+  try {
+    await session.browser.probe(`setTimeout(() => {
+      const until = performance.now() + 12500;
+      while (performance.now() < until) {}
+      window.__spectestRrwebEvents = [{ type: 5, data: { tag: "later-session" } }];
+    }, 50)`);
+    await Bun.sleep(100);
+    const before = chunks.length;
+    const started = performance.now();
+    const warnings = await finalizeBrowserRecordings([session.detach, healthy.detach]);
+    expect(warnings).toEqual(["Browser recording finalization did not finish within 10000ms"]);
+    expect(performance.now() - started).toBeLessThan(12000);
+    expect(healthyChunks.length).toBeGreaterThan(0);
+    expect(chunks.length).toBe(before);
+    // The old evaluation resolves once the renderer wakes. It must neither
+    // append to the finalized recorder nor consume a later session's buffer.
+    await Bun.sleep(3000);
+    expect(chunks.length).toBe(before);
+    expect(await session.browser.probe("window.__spectestRrwebEvents.some(e => e.data?.tag === 'later-session')")).toBe(true);
+    const attached = await acquirePersistentBrowser("stuck-finalization", {
+      recorder: { sessionId: "next-finalization", recordStep() {} },
+    });
+    expect(attached.attached).toBe(true);
+    expect(await attached.browser.probe("document.querySelector('p').textContent")).toBe("retained page");
+    await attached.detach();
+  } finally {
+    await Promise.all([session.browser.close(), healthy.browser.close()]);
+  }
+}, 25000);

package/src/browser.ts

@@ -35,6 +35,7 @@ import { fileURLToPath } from "node:url";
 
 import { generateId } from "./ids.js";
 import { rawFetch } from "./harness/raw-fetch.js";
+import { withDeadline } from "./harness/deadline.js";
 import { prepareMicrophoneFixture, type MicrophoneFixture } from "./harness/microphone-fixture.js";
 export type { MicrophoneFixture } from "./harness/microphone-fixture.js";
 import { DESKTOP_INPUT_SYNC_SCRIPT } from "./desktop-recorder.js";
@@ -1783,6 +1784,7 @@ function buildBackend(
   // `recordingEnded` stops this wrapper's recorder writes (test end);
   // `viewClosed` tracks actual destruction (author called close()).
   let recordingEnded = false;
+  let recordingEnd: Promise<void> | undefined;
   let viewClosed = false;
   const sessionStart = Date.now();
   let stepSeq = 0;
@@ -1837,11 +1839,18 @@ function buildBackend(
     };
   }
 
-  async function drain(action: BrowserAction | "close", timestamp = Date.now()): Promise<void> {
+  async function drain(action: BrowserAction | "close", timestamp = Date.now(), signal?: AbortSignal): Promise<void> {
     if (!holder.recordingInstalled || !recorder || recordingEnded) return;
     try {
       const urlChanged = holder.page.url() !== lastDrainUrl;
-      const events = (await holder.page.evaluate(drainExpr(urlChanged, timestamp))) as unknown[];
+      // Finalization only reads the buffer. A timed-out evaluation may run
+      // after a child/eval attaches; it must not clear that session's events.
+      const expression = action === "close"
+        ? "window.__spectestRrwebEvents || []"
+        : drainExpr(urlChanged, timestamp);
+      const events = (await holder.page.evaluate(expression)) as unknown[];
+      signal?.throwIfAborted();
+      if (recordingEnded) return;
       lastDrainUrl = holder.page.url();
       if (Array.isArray(events) && events.length > 0) {
         recorder.recordStep({
@@ -1852,6 +1861,7 @@ function buildBackend(
         });
       }
     } catch {
+      signal?.throwIfAborted();
       // Page may be mid-navigation, detached, or the view is closing.
       // Losing an occasional drain is acceptable — the next op picks up
       // the rest of the buffer.
@@ -1874,6 +1884,7 @@ function buildBackend(
       } catch {
         /* page mid-navigation or closed — keep the stale cache */
       }
+      if (recordingEnded) return result;
       // `sessionTimestamp` is the post-op wall clock — that's where we
       // want the dashboard's seek to land, so clicking "type 'foo'"
       // shows the input *with* the text, not the empty field just
@@ -1905,12 +1916,14 @@ function buildBackend(
       }
       return result;
     } catch (err) {
+      if (recordingEnded) throw err;
       const e = err as Error;
       const endT = Date.now();
       const error = e?.message ?? String(err);
       // Captured after the clock stops, so the diagnostic is not billed to
       // the step, and before the event is recorded, so it rides it.
       const pageStructure = await failedPageStructure(action, error);
+      if (recordingEnded) throw err;
       recordBrowser({
         action,
         ...fields,
@@ -1926,18 +1939,21 @@ function buildBackend(
     }
   }
 
-  async function endRecording(): Promise<void> {
-    if (recordingEnded) return;
-    // Final drain before we stop writing to this recorder.
-    await drain("close");
-    if (browserCoverageActive()) {
+  function endRecording(): Promise<void> {
+    // A stuck renderer must not prevent the test result from returning. The
+    // signal and ended guard discard late recorder writes. Missing optional
+    // replay data is a warning, not a failed test. Concurrent close/detach
+    // calls share the same bounded attempt.
+    return recordingEnd ??= (async () => {
       try {
-        await harvestBrowserCoverage(holder.cdp);
-      } catch {
-        /* best-effort */
+        await withDeadline("Browser recording finalization", 10_000,
+          signal => drain("close", Date.now(), signal));
+        // Coverage is collected by the service capture after recording
+        // finalization. Do not harvest it twice on the test-end path.
+      } finally {
+        recordingEnded = true;
       }
-    }
-    recordingEnded = true;
+    })();
   }
 
   const strategy: ActionStrategy = holder.device ? mobileStrategy : desktopStrategy;
@@ -2209,8 +2225,15 @@ function buildBackend(
       // the next `ctx.browser()`/`ctx.mobile()` creates a new one. The
       // routine test-end path is `detach` (recording stops, view lives on
       // into the post-test snapshot).
-      await endRecording();
+      try { await endRecording(); } catch (error) {
+        console.warn("[browser finalization]", error instanceof Error ? error.message : String(error));
+      }
       if (viewClosed) return;
+      // An explicit close destroys the renderer, unlike detach. Harvest its
+      // counters before destroying it; service capture handles live views.
+      if (browserCoverageActive()) {
+        try { await harvestBrowserCoverage(holder.cdp); } catch { /* capture reports the error */ }
+      }
       viewClosed = true;
       buildOpts.onDestroy?.();
       try {
@@ -2293,6 +2316,7 @@ function buildBackend(
       // A matcher that ran out of budget is the other half of a failed
       // browser step, and the page it settled on is the same evidence.
       const pageStructure = error ? await failedPageStructure(action, error) : undefined;
+      if (recordingEnded) return undefined;
       const seq = recordBrowser({
         action,
         ...fields,

package/src/coverage.ts

@@ -1205,7 +1205,7 @@ export function browser(options: CoverageSourceOptions = {}): CoverageAdapter {
       ctx.collectBrowserScripts();
     },
     async capture(ctx) {
-      await harvestAllBrowserCoverage();
+      await harvestAllBrowserCoverage(ctx.signal);
       const lcov = takeBrowserCoverageReport(ctx.service);
       await ctx.writeReport("browser.lcov", lcov);
     },

package/src/daemon.ts

@@ -1,3 +1,4 @@
+import { finalizeBrowserRecordings } from "./harness/deadline.js";
 import { ensureServiceNetwork, serviceIpv4Gateway } from "./harness/service-network.js";
 import { collectSecretRefs } from "./fake-upstream.js";
 import { phoneScope, phoneRecordingChunk, releasePhoneRecording, type PhoneRecording } from "./phone.js";
@@ -5309,12 +5310,10 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     // this test's recorder. The Chromium itself deliberately stays alive
     // — it's part of the state the post-test snapshot captures for
     // dependsOn children (see the acquire comment above).
-    for (const detach of browserDetaches) {
-      try {
-        await detach();
-      } catch {
-        /* ignore */
-      }
+    const browserErrors = await finalizeBrowserRecordings(browserDetaches);
+    if (browserErrors.length) {
+      const message = browserErrors.join("\n");
+      chunks.push(`[browser finalization] ${message}\n`);
     }
     for (const s of sessions) s.markClosed();
     androidRecordings = await nativeAndroid.finish();
@@ -5871,12 +5870,10 @@ async function evalCode(code: string): Promise<EvalResult> {
     (process.stderr as any).write = origStderr;
     // Detach (final rrweb drain) — the browser itself stays alive; see
     // the acquire comment above.
-    for (const detach of browserDetaches) {
-      try {
-        await detach();
-      } catch {
-        /* ignore */
-      }
+    const browserErrors = await finalizeBrowserRecordings(browserDetaches);
+    if (browserErrors.length) {
+      const message = browserErrors.join("\n");
+      chunks.push(`[browser finalization] ${message}\n`);
     }
     for (const s of sessions) s.markClosed();
     await nativeAndroid.finish();

package/src/harness/deadline.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from "bun:test";
+import { finalizeBrowserRecordings } from "./deadline.js";
+
+test("all recording finalizers start before waiting and failures are returned as warnings", async () => {
+  let release!: () => void;
+  const gate = new Promise<void>(resolve => { release = resolve; });
+  const started: string[] = [];
+  const done = finalizeBrowserRecordings([
+    async () => { started.push("first"); await gate; throw new Error("optional replay unavailable"); },
+    async () => { started.push("second"); await gate; },
+  ]);
+  await Promise.resolve();
+  expect(started).toEqual(["first", "second"]);
+  release();
+  expect(await done).toEqual(["optional replay unavailable"]);
+});

package/src/harness/deadline.ts

@@ -0,0 +1,33 @@
+/** Bound an async operation and invalidate its late result. Work must check
+ * the signal before committing state after an await; racing alone does not
+ * cancel a Playwright/CDP request already sent to the browser. */
+export async function withDeadline<T>(
+  label: string,
+  timeoutMs: number,
+  work: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          const error = new Error(`${label} did not finish within ${timeoutMs}ms`);
+          controller.abort(error);
+          reject(error);
+        }, timeoutMs);
+      }),
+      work(controller.signal),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Start all browser drains together. One wedged view must not consume a
+ * separate finalization allowance for every other view in the test. */
+export async function finalizeBrowserRecordings(detaches: Array<() => Promise<void>>): Promise<string[]> {
+  const results = await Promise.allSettled(detaches.map(detach => Promise.resolve().then(detach)));
+  return results.flatMap(result => result.status === "rejected"
+    ? [result.reason instanceof Error ? result.reason.message : String(result.reason)] : []);
+}