harnery 0.45.1 → 0.46.0

package/src/lib/admission.ts

@@ -18,6 +18,9 @@
 // file; process death leaves a dead-PID file for the next participant to
 // prune.
 //
+// Every ticket that ends (released, timed out, or pruned after its process
+// died) appends one record to the admission history (admission-history.ts).
+//
 // Toolkit tier: this module must not import src/core (layering check).
 
 import { randomUUID } from "node:crypto";
@@ -31,8 +34,17 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import {
+  ADMISSION_HISTORY_SCHEMA_VERSION,
+  type AdmissionHistoryOutcome,
+  type AdmissionReleaseResult,
+  appendAdmissionHistory,
+  resolveAdmissionHistoryDir,
+} from "./admission-history.ts";
 import { coordEnv } from "./env.ts";
 
+export type { AdmissionReleaseResult } from "./admission-history.ts";
+
 export interface AdmissionConfig {
   /** Base directory holding one subdirectory per resource. */
   dir: string;
@@ -44,6 +56,11 @@ export interface AdmissionConfig {
   pollMs?: number;
   /** Entries older than this are pruned regardless of PID (default 6h). */
   ttlMs?: number;
+  /**
+   * Directory for the slot-use history. Omitted: resolved from the queue
+   * directory (see resolveAdmissionHistoryDir). null: record nothing.
+   */
+  historyDir?: string | null;
 }
 
 export interface AdmissionEntry {
@@ -52,6 +69,12 @@ export interface AdmissionEntry {
   created_at: string;
   /** Set on holders once admitted. */
   acquired_at?: string;
+  /** Working directory of the queueing process. */
+  cwd?: string;
+  /** Capacity the queueing process asked for. */
+  capacity?: number;
+  /** Set on holders that had to wait: the holder labels they first waited behind. */
+  waited_behind?: string[];
 }
 
 export interface AdmissionWaitInfo {
@@ -67,6 +90,8 @@ export interface AdmissionAcquireOptions {
   timeoutMs?: number;
   /** Progress callback, invoked at most once per poll while waiting. */
   onWait?: (info: AdmissionWaitInfo) => void;
+  /** Time the caller already spent deferring for memory pressure, for the history. */
+  pressureWaitMs?: number;
 }
 
 export interface AdmissionHandle {
@@ -74,8 +99,11 @@ export interface AdmissionHandle {
   entry: string;
   /** Milliseconds spent waiting in the queue. */
   waitedMs: number;
-  /** Give the slot back. Safe to call more than once. */
-  release: () => void;
+  /**
+   * Give the slot back and record the slot use in the history. Safe to call
+   * more than once; only the first call records.
+   */
+  release: (result?: AdmissionReleaseResult) => void;
 }
 
 export class AdmissionTimeoutError extends Error {
@@ -143,7 +171,13 @@ interface LiveEntry {
 /** List live entries in lexical (= enqueue) order, pruning dead-PID, expired,
  * and torn files as a side effect. Every participant prunes, so a crashed
  * holder's slot frees as soon as anyone else looks. */
-function listLive(dir: string, ttlMs: number): LiveEntry[] {
+type PruneReason = Extract<AdmissionHistoryOutcome, "abandoned" | "expired">;
+
+function listLive(
+  dir: string,
+  ttlMs: number,
+  onPrune?: (entry: AdmissionEntry, reason: PruneReason) => void,
+): LiveEntry[] {
   let names: string[];
   try {
     names = readdirSync(dir)
@@ -167,6 +201,15 @@ function listLive(dir: string, ttlMs: number): LiveEntry[] {
             label: typeof record.label === "string" ? record.label : "",
             created_at: record.created_at,
             ...(typeof record.acquired_at === "string" ? { acquired_at: record.acquired_at } : {}),
+            ...(typeof record.cwd === "string" ? { cwd: record.cwd } : {}),
+            ...(typeof record.capacity === "number" ? { capacity: record.capacity } : {}),
+            ...(Array.isArray(record.waited_behind)
+              ? {
+                  waited_behind: record.waited_behind.filter(
+                    (label): label is string => typeof label === "string",
+                  ),
+                }
+              : {}),
           };
         }
       }
@@ -188,12 +231,16 @@ function listLive(dir: string, ttlMs: number): LiveEntry[] {
       continue;
     }
     const age = now - Date.parse(entry.created_at);
-    if (!pidAlive(entry.pid) || Number.isNaN(age) || age > ttlMs) {
+    const dead = !pidAlive(entry.pid);
+    if (dead || Number.isNaN(age) || age > ttlMs) {
+      let pruned = false;
       try {
         unlinkSync(path);
+        pruned = true;
       } catch {
-        // a peer pruned it first
+        // a peer pruned it first, and records it
       }
+      if (pruned) onPrune?.(entry, dead ? "abandoned" : "expired");
       continue;
     }
     live.push({ name, entry });
@@ -201,6 +248,42 @@ function listLive(dir: string, ttlMs: number): LiveEntry[] {
   return live;
 }
 
+function historyDirFor(config: Pick<AdmissionConfig, "dir" | "historyDir">): string | null {
+  return config.historyDir !== undefined
+    ? config.historyDir
+    : resolveAdmissionHistoryDir(config.dir);
+}
+
+/** Record an entry a participant pruned because its process died or it expired. */
+function recordPruned(
+  historyDir: string | null,
+  resource: string,
+  entry: AdmissionEntry,
+  reason: PruneReason,
+): void {
+  if (!historyDir) return;
+  const now = Date.now();
+  const enqueuedMs = Date.parse(entry.created_at);
+  const acquiredMs = entry.acquired_at ? Date.parse(entry.acquired_at) : Number.NaN;
+  appendAdmissionHistory(historyDir, {
+    v: ADMISSION_HISTORY_SCHEMA_VERSION,
+    resource,
+    label: entry.label,
+    pid: entry.pid,
+    ...(entry.cwd ? { cwd: entry.cwd } : {}),
+    ...(entry.capacity !== undefined ? { capacity: entry.capacity } : {}),
+    outcome: reason,
+    enqueued_at: entry.created_at,
+    ...(entry.acquired_at ? { acquired_at: entry.acquired_at } : {}),
+    ended_at: new Date(now).toISOString(),
+    wait_ms: Number.isNaN(enqueuedMs)
+      ? 0
+      : Math.max(0, (Number.isNaN(acquiredMs) ? now : acquiredMs) - enqueuedMs),
+    ...(Number.isNaN(acquiredMs) ? {} : { hold_ms: Math.max(0, now - acquiredMs) }),
+    ...(entry.waited_behind?.length ? { waited_behind: entry.waited_behind } : {}),
+  });
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
@@ -224,11 +307,18 @@ export async function acquireAdmission(
   const tickets = ticketsDir(config);
   const held = heldDir(config);
 
+  const historyDir = historyDirFor(config);
+  const onPrune = (entry: AdmissionEntry, reason: PruneReason): void =>
+    recordPruned(historyDir, config.resource, entry, reason);
   const myEntry: AdmissionEntry = {
     pid: process.pid,
     label: options.label,
     created_at: new Date().toISOString(),
+    cwd: process.cwd(),
+    capacity: config.capacity,
   };
+  let waitedBehind: string[] | undefined;
+  const pressureWait = options.pressureWaitMs ? { pressure_wait_ms: options.pressureWaitMs } : {};
   const myName = `${String(Date.now()).padStart(13, "0")}-${process.pid}-${randomUUID().slice(0, 8)}.json`;
   writeEntry(tickets, myName, myEntry);
 
@@ -236,8 +326,8 @@ export async function acquireAdmission(
   const deadline = startedWaiting + timeoutMs;
   try {
     while (true) {
-      const liveHeld = listLive(held, ttlMs);
-      const liveTickets = listLive(tickets, ttlMs);
+      const liveHeld = listLive(held, ttlMs, onPrune);
+      const liveTickets = listLive(tickets, ttlMs, onPrune);
       const myIndex = liveTickets.findIndex((ticket) => ticket.name === myName);
       if (myIndex === -1) {
         // Pruned by a peer (should not happen while we are alive) or lost to
@@ -253,7 +343,7 @@ export async function acquireAdmission(
         // between two waiters' listings. Lexical order (= enqueue order)
         // decides who stays; the loser rejoins the queue with its original
         // priority because the filename keeps its enqueue timestamp.
-        const heldNow = listLive(held, ttlMs);
+        const heldNow = listLive(held, ttlMs, onPrune);
         if (heldNow.length > config.capacity) {
           const keepers = new Set(
             heldNow.slice(0, config.capacity).map((holderEntry) => holderEntry.name),
@@ -264,12 +354,14 @@ export async function acquireAdmission(
             continue;
           }
         }
-        writeEntry(held, myName, { ...myEntry, acquired_at: new Date().toISOString() });
+        const acquiredAt = new Date();
+        writeEntry(held, myName, { ...myEntry, acquired_at: acquiredAt.toISOString() });
+        const waitedMs = acquiredAt.getTime() - startedWaiting;
         let released = false;
         return {
           entry: myName,
-          waitedMs: Date.now() - startedWaiting,
-          release: () => {
+          waitedMs,
+          release: (result?: AdmissionReleaseResult) => {
             if (released) return;
             released = true;
             try {
@@ -277,14 +369,55 @@ export async function acquireAdmission(
             } catch {
               // already pruned
             }
+            const endedAt = new Date();
+            appendAdmissionHistory(historyDir, {
+              v: ADMISSION_HISTORY_SCHEMA_VERSION,
+              resource: config.resource,
+              label: myEntry.label,
+              pid: myEntry.pid,
+              ...(myEntry.cwd ? { cwd: myEntry.cwd } : {}),
+              capacity: config.capacity,
+              outcome: "released",
+              enqueued_at: myEntry.created_at,
+              acquired_at: acquiredAt.toISOString(),
+              ended_at: endedAt.toISOString(),
+              wait_ms: waitedMs,
+              hold_ms: endedAt.getTime() - acquiredAt.getTime(),
+              ...(waitedBehind?.length ? { waited_behind: waitedBehind } : {}),
+              ...pressureWait,
+              ...(result?.exitCode !== undefined ? { exit_code: result.exitCode } : {}),
+              ...(result?.signal !== undefined ? { signal: result.signal } : {}),
+            });
           },
         };
       }
+      if (waitedBehind === undefined) {
+        // Persist who this ticket waits behind, so the record survives even
+        // if this process dies in the queue and a peer prunes the ticket.
+        waitedBehind = liveHeld.map((holderEntry) => holderEntry.entry.label);
+        myEntry.waited_behind = waitedBehind;
+        writeEntry(tickets, myName, myEntry);
+      }
       options.onWait?.({
         position: myIndex + 1,
         holders: liveHeld.map((holderEntry) => holderEntry.entry),
       });
       if (Date.now() >= deadline) {
+        const endedAt = new Date();
+        appendAdmissionHistory(historyDir, {
+          v: ADMISSION_HISTORY_SCHEMA_VERSION,
+          resource: config.resource,
+          label: myEntry.label,
+          pid: myEntry.pid,
+          ...(myEntry.cwd ? { cwd: myEntry.cwd } : {}),
+          capacity: config.capacity,
+          outcome: "timeout",
+          enqueued_at: myEntry.created_at,
+          ended_at: endedAt.toISOString(),
+          wait_ms: endedAt.getTime() - startedWaiting,
+          ...(waitedBehind?.length ? { waited_behind: waitedBehind } : {}),
+          ...pressureWait,
+        });
         throw new AdmissionTimeoutError(
           config.resource,
           timeoutMs,
@@ -313,25 +446,90 @@ export interface AdmissionStatus {
 
 /** Snapshot the queue for one resource, pruning dead entries on the way. */
 export function admissionStatus(
-  config: Pick<AdmissionConfig, "dir" | "resource" | "ttlMs">,
+  config: Pick<AdmissionConfig, "dir" | "resource" | "ttlMs" | "historyDir">,
 ): AdmissionStatus {
   const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
   const full: AdmissionConfig = { ...config, capacity: 1 };
+  const historyDir = historyDirFor(config);
+  const onPrune = (entry: AdmissionEntry, reason: PruneReason): void =>
+    recordPruned(historyDir, config.resource, entry, reason);
   return {
     resource: config.resource,
-    holders: listLive(heldDir(full), ttlMs).map((holderEntry) => holderEntry.entry),
-    waiters: listLive(ticketsDir(full), ttlMs).map((ticket) => ticket.entry),
+    holders: listLive(heldDir(full), ttlMs, onPrune).map((holderEntry) => holderEntry.entry),
+    waiters: listLive(ticketsDir(full), ttlMs, onPrune).map((ticket) => ticket.entry),
   };
 }
 
 /**
- * Base directory for admission queue state. tmpdir clears on reboot, which
- * is correct — stale queue state must not outlive the boot. Override with
- * HARNERY_ADMISSION_DIR. Host CLIs and harn commands must share this helper
- * so they join the same machine-wide queues.
+ * Base directory for admission queue state. The temp directory clears on
+ * reboot, which is correct: stale queue state must not outlive the boot.
+ * Override with HARNERY_ADMISSION_DIR. Host CLIs and harn commands must share
+ * this helper so they join the same machine-wide queues.
+ *
+ * On POSIX the default is the literal /tmp, not os.tmpdir(): agent sandboxes
+ * often set a private TMPDIR per session, and a queue under it would admit
+ * every session on its own.
  */
 export function admissionBaseDir(): string {
-  return coordEnv("ADMISSION_DIR") ?? join(tmpdir(), "harnery-admission");
+  return (
+    coordEnv("ADMISSION_DIR") ??
+    (process.platform === "win32" ? join(tmpdir(), "harnery-admission") : "/tmp/harnery-admission")
+  );
+}
+
+/**
+ * Linux memory pressure: the `full avg10` figure from /proc/pressure/memory,
+ * the share of the last ten seconds in which every runnable task stalled on
+ * memory. Undefined where pressure stall information is unavailable.
+ */
+export function memoryPressureFullAvg10(): number | undefined {
+  try {
+    const line = readFileSync("/proc/pressure/memory", "utf8")
+      .split("\n")
+      .find((candidate) => candidate.startsWith("full"));
+    const match = line ? /avg10=([0-9.]+)/.exec(line) : null;
+    return match?.[1] !== undefined ? Number(match[1]) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export interface PressureWaitOptions {
+  /** Defer while `full avg10` is above this value. */
+  threshold: number;
+  /** Give up deferring after this long and let the caller start anyway. */
+  maxWaitMs: number;
+  pollMs?: number;
+  /** Pressure reader; tests inject one. */
+  read?: () => number | undefined;
+  /** Called once when deferral starts and once if it gives up. */
+  onWait?: (event: { pressure: number; waitedMs: number; gaveUp: boolean }) => void;
+}
+
+/**
+ * Wait, holding no slot, while the machine is already stalling on memory, so
+ * a heavy job does not start into a storm. Never blocks forever: after
+ * maxWaitMs it returns and the caller starts anyway. Returns the time waited.
+ */
+export async function waitForMemoryPressure(options: PressureWaitOptions): Promise<number> {
+  const read = options.read ?? memoryPressureFullAvg10;
+  const pollMs = options.pollMs ?? 5_000;
+  const started = Date.now();
+  let announced = false;
+  while (true) {
+    const pressure = read();
+    if (pressure === undefined || pressure <= options.threshold) return Date.now() - started;
+    const waitedMs = Date.now() - started;
+    if (waitedMs + pollMs > options.maxWaitMs) {
+      options.onWait?.({ pressure, waitedMs, gaveUp: true });
+      return waitedMs;
+    }
+    if (!announced) {
+      announced = true;
+      options.onWait?.({ pressure, waitedMs, gaveUp: false });
+    }
+    await sleep(pollMs);
+  }
 }
 
 /** Resources present under an admission base directory. */

package/src/lib/browser/client.ts

@@ -15,6 +15,7 @@ import {
   type CookieJar,
   CookieStoreParseError,
   type Cookie as JarCookie,
+  violatesCookiePrefix,
 } from "../cookies/index.ts";
 import { PaceGate, pacePolicyFromEnv } from "../pace/index.ts";
 import { type AssertResult, type AssertSpec, buildAssertCheck } from "./asserts.js";
@@ -170,8 +171,22 @@ export interface BrowserOptions {
   userAgent?: string;
   /** Authenticated browser proxy passed directly to Playwright. */
   proxy?: { server: string; username?: string; password?: string };
+  /**
+   * Inspect the live cookies of the browser context. Runs before each request
+   * is sent, after each response, and once more at close. If it throws, the
+   * request is cancelled, the context closes without saving cookies to the
+   * jar, and the error is kept as `cookieGuardFault` for the caller to report.
+   */
+  cookieGuard?: CookieGuard;
 }
 
+export type CookieGuardPhase = "request" | "response" | "close";
+
+export type CookieGuard = (
+  cookies: readonly PWCookie[],
+  event: { phase: CookieGuardPhase; url: string | null },
+) => void | Promise<void>;
+
 export interface NavigateResult {
   url: string;
   title: string;
@@ -422,16 +437,35 @@ export class Browser {
       : undefined;
     if (identity) await this.context.addInitScript(installDocumentIdentity, identity);
 
-    if (jarCookies.length > 0) {
-      await this.context.addCookies(jarCookies.map(toPWCookie));
+    // The jar's domain field is the delivery rule: a dotless domain is
+    // host-only, which Chromium honors for exactly that host. A cookie that
+    // breaks its name prefix would make Chromium reject the whole batch, so
+    // it is left out rather than aborting the session.
+    const injectable = jarCookies.filter((cookie) => !violatesCookiePrefix(cookie));
+    if (injectable.length > 0) {
+      await this.context.addCookies(injectable.map(toPWCookie));
     }
 
     // Gate actual document requests, including links, forms, script navigation,
     // and the first request of a popup. Method-level waits miss those loads.
     // Redirect hops are part of the original load, not additional reservations.
     const headersCb = this.opts.extraHeaders;
-    if (this.getPaceGate()?.policy.enabled || headersCb || this.opts.userAgent) {
+    const cookieGuard = this.opts.cookieGuard;
+    if (cookieGuard) {
+      this.context.on("response", (response) => {
+        void this.guardCookies("response", response.url()).catch(() => undefined);
+      });
+    }
+    if (this.getPaceGate()?.policy.enabled || headersCb || this.opts.userAgent || cookieGuard) {
       await this.context.route("**/*", async (route, request) => {
+        if (cookieGuard) {
+          try {
+            await this.guardCookies("request", request.url());
+          } catch {
+            await route.abort("failed").catch(() => undefined);
+            return;
+          }
+        }
         let mainDocument = false;
         if (request.isNavigationRequest() && !request.redirectedFrom()) {
           try {
@@ -848,24 +882,31 @@ export class Browser {
           `captureRegionByScroll: rect must have a positive size (got ${rect.width}×${rect.height})`,
         );
       }
-    const settle = (top: number) =>
-      page.evaluate(async (target: number) => {
-        window.scrollTo({ left: window.scrollX, top: target, behavior: "instant" });
-        const frame = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
-        let last = Number.NaN;
-        for (let i = 0; i < 8; i++) {
-          await frame();
-          const now = window.scrollY;
-          if (now === last) break;
-          last = now;
-        }
-        return {
-          scrollX: window.scrollX,
-          scrollY: window.scrollY,
-          innerWidth: window.innerWidth,
-          innerHeight: window.innerHeight,
-        };
-      }, top);
+    const settle = (top: number, left?: number) =>
+      page.evaluate(
+        async (target: { top: number; left?: number }) => {
+          window.scrollTo({
+            left: target.left ?? window.scrollX,
+            top: target.top,
+            behavior: "instant",
+          });
+          const frame = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
+          let last = Number.NaN;
+          for (let i = 0; i < 8; i++) {
+            await frame();
+            const now = window.scrollY;
+            if (now === last) break;
+            last = now;
+          }
+          return {
+            scrollX: window.scrollX,
+            scrollY: window.scrollY,
+            innerWidth: window.innerWidth,
+            innerHeight: window.innerHeight,
+          };
+        },
+        { top, left },
+      );
     const original = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
     const captures: Buffer[] = [];
     // Viewport-pinned candidates, measured at scroll 0 so each later capture
@@ -884,6 +925,8 @@ export class Browser {
         priorOpacityPriority: string;
         priorTransition: string;
         priorTransitionPriority: string;
+        priorStyle: string | null;
+        appliedStyle?: string;
       }> = [];
       // Fixed controls can live inside a static shadow host. Walk open roots
       // without hiding their ordinary content or exceeding the total node cap.
@@ -907,6 +950,7 @@ export class Browser {
           priorOpacityPriority: el.style.getPropertyPriority("opacity"),
           priorTransition: el.style.getPropertyValue("transition"),
           priorTransitionPriority: el.style.getPropertyPriority("transition"),
+          priorStyle: el.getAttribute("style"),
         });
       }
       return out;
@@ -916,16 +960,36 @@ export class Browser {
         async ([entries, action]) => {
           for (const entry of entries) {
             const restore = () => {
+              if (entry.appliedStyle === undefined) return;
+              const unchanged = entry.el.getAttribute("style") === entry.appliedStyle;
               // Restore opacity while transitions are still disabled. Restoring both
               // declarations in one style flush starts a new fade from zero.
-              entry.el.style.setProperty("transition", "none", "important");
-              entry.el.style.setProperty("opacity", entry.priorOpacity, entry.priorOpacityPriority);
+              if (
+                entry.el.style.getPropertyValue("opacity") === "0" &&
+                entry.el.style.getPropertyPriority("opacity") === "important"
+              )
+                entry.el.style.setProperty(
+                  "opacity",
+                  entry.priorOpacity,
+                  entry.priorOpacityPriority,
+                );
               void getComputedStyle(entry.el).opacity;
-              entry.el.style.setProperty(
-                "transition",
-                entry.priorTransition,
-                entry.priorTransitionPriority,
-              );
+              if (
+                entry.el.style.getPropertyValue("transition") === "none" &&
+                entry.el.style.getPropertyPriority("transition") === "important"
+              )
+                entry.el.style.setProperty(
+                  "transition",
+                  entry.priorTransition,
+                  entry.priorTransitionPriority,
+                );
+              // Preserve the exact original attribute, including its absence. Do
+              // not replace styles changed by the page while our override was active.
+              if (unchanged) {
+                if (entry.priorStyle === null) entry.el.removeAttribute("style");
+                else entry.el.setAttribute("style", entry.priorStyle);
+              }
+              entry.appliedStyle = undefined;
             };
             if (action === "restore") {
               restore();
@@ -933,8 +997,21 @@ export class Browser {
             }
             const now = entry.el.getBoundingClientRect().top + window.scrollY;
             if (Math.abs(now - entry.top) > 1) {
+              if (entry.appliedStyle !== undefined) {
+                if (entry.el.getAttribute("style") !== entry.appliedStyle)
+                  throw new Error(
+                    "Pinned styles changed during native capture; source is unstable.",
+                  );
+                continue;
+              }
+              entry.priorStyle = entry.el.getAttribute("style");
+              entry.priorOpacity = entry.el.style.getPropertyValue("opacity");
+              entry.priorOpacityPriority = entry.el.style.getPropertyPriority("opacity");
+              entry.priorTransition = entry.el.style.getPropertyValue("transition");
+              entry.priorTransitionPriority = entry.el.style.getPropertyPriority("transition");
               entry.el.style.setProperty("transition", "none", "important");
               entry.el.style.setProperty("opacity", "0", "important");
+              entry.appliedStyle = entry.el.getAttribute("style")!;
             } else {
               restore();
             }
@@ -990,11 +1067,8 @@ export class Browser {
         await syncPinned("restore");
       } finally {
         await pinned.dispose();
-        await page.evaluate(
-          ({ x, y }: { x: number; y: number }) =>
-            window.scrollTo({ left: x, top: y, behavior: "instant" }),
-          original,
-        );
+        await settle(original.y, original.x);
+        await this.waitForReviewReady();
       }
     }
     return captures;
@@ -1863,10 +1937,17 @@ export class Browser {
    * visual line. Word-count per line via per-word Range rects (the width
    * of the last line is deliberately NOT the signal; see runts.ts).
    */
-  async checkRunts(opts: { scope?: string | null; minChars?: number } = {}): Promise<RuntsResult> {
+  async checkRunts(
+    opts: { scope?: string | null; minChars?: number; maxFindings?: number } = {},
+  ): Promise<RuntsResult> {
+    const maxFindings = opts.maxFindings === undefined ? 50 : opts.maxFindings;
+    if (!Number.isInteger(maxFindings) || maxFindings < 1 || maxFindings > 5000) {
+      throw new Error("maxFindings must be an integer from 1 to 5000.");
+    }
     return await this.currentPage.evaluate(buildRuntsCheck(), {
       scope: opts.scope ?? null,
       minChars: opts.minChars ?? 40,
+      maxFindings,
     });
   }
 
@@ -1973,6 +2054,30 @@ export class Browser {
     await this.context.addInitScript(script);
   }
 
+  /** The error a `cookieGuard` threw, once it has stopped the session. */
+  get cookieGuardFault(): unknown {
+    return this.cookieFault;
+  }
+
+  private cookieFault: unknown;
+
+  /** Run the cookie guard; on a throw, record it, tear the context down, and rethrow. */
+  private async guardCookies(phase: CookieGuardPhase, url: string | null): Promise<void> {
+    const guard = this.opts.cookieGuard;
+    const context = this.context;
+    if (!guard || !context || this.cookieFault) {
+      if (this.cookieFault) throw this.cookieFault;
+      return;
+    }
+    try {
+      await guard(await context.cookies(), { phase, url });
+    } catch (error) {
+      this.cookieFault ??= error;
+      await this.close();
+      throw error;
+    }
+  }
+
   /** Snapshot all cookies in the live persistent context. */
   async cookies(): Promise<PWCookie[]> {
     if (!this.context) throw new Error("Browser not opened. Call open() first.");
@@ -1985,7 +2090,14 @@ export class Browser {
    */
   async close(): Promise<void> {
     if (!this.context) return;
-    if (this.opts.jar) {
+    if (this.opts.cookieGuard && !this.cookieFault) {
+      try {
+        await this.guardCookies("close", null);
+      } catch {
+        return;
+      }
+    }
+    if (this.opts.jar && !this.cookieFault) {
       try {
         const live = await this.context.cookies();
         this.opts.jar.merge(live.map(toJarCookie));