@reticlehq/server 3.8.1 → 3.9.0

package/dist/portal/pool/browser-pool.js

@@ -14,10 +14,11 @@ import { log } from '../../log.js';
 import { closeLeaseTab, LEASE_CLOSE_TIMED_OUT, settledWithin } from './bounded-close.js';
 import { seedStorageInto, targetOriginOf } from './storage-seed.js';
 import { installLeaseMarker, leaseMarkerOf } from './lease-marker-stamp.js';
-import { grantLeasePermissions, readNotificationPermission } from './context-permissions.js';
+import { grantLeasePermissions, grantLocalNetworkAccess, readNotificationPermission, widenLeaseCsp, } from './context-permissions.js';
 import { readViewport } from './lease-emulation.js';
 import { NotHtmlDocumentError, READER_NOT_HTML } from './zero-install.js';
-import { DEFAULT_LEASE_TTL_MS, DEFAULT_NAV_TIMEOUT_MS, INIT_SCRIPT_UNSUPPORTED, MAX_REMEMBERED_REAPED_LEASES, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, pageLoading, PoolAtCapacityError, } from './pool-lease.js';
+import { DEFAULT_LEASE_TTL_MS, DEFAULT_NAV_TIMEOUT_MS, INIT_SCRIPT_UNSUPPORTED, MAX_REMEMBERED_REAPED_LEASES, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, navStatusOf, pageLoading, PoolAtCapacityError, } from './pool-lease.js';
+import { listenForPageErrors, reportLeaseClosed, } from './lease-page-error.js';
 export { DEFAULT_LEASE_TTL_MS, NO_HEADED_BROWSER, ORPHANED_LEASE_GRACE_MS, PoolAtCapacityError, } from './pool-lease.js';
 /**
  * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
@@ -30,6 +31,8 @@ export class BrowserPool {
     #now;
     #ttl;
     #zeroInstall;
+    #daemonOrigin;
+    #pageErrorHooks;
     #navTimeout;
     #headless;
     #headed;
@@ -73,6 +76,8 @@ export class BrowserPool {
         this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
         this.#zeroInstall = opts.zeroInstallScript;
+        this.#daemonOrigin = opts.daemonOrigin;
+        this.#pageErrorHooks = { onPageError: opts.onPageError, onLeaseClosed: opts.onLeaseClosed };
     }
     /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
     leaseTtlMs() {
@@ -109,17 +114,9 @@ export class BrowserPool {
             return undefined;
         }
         for (const [leaseId, lease] of this.#active) {
-            if (lease.owner !== owner) {
-                continue;
-            }
-            let leaseOrigin;
-            try {
-                leaseOrigin = new URL(lease.url).origin;
-            }
-            catch {
-                continue;
-            }
-            if (leaseOrigin !== origin) {
+            if (lease.owner !== owner ||
+                !URL.canParse(lease.url) ||
+                new URL(lease.url).origin !== origin) {
                 continue;
             }
             for (const [alias, id] of this.#aliases) {
@@ -247,15 +244,21 @@ export class BrowserPool {
             return undefined;
         }
         this.touch(sessionId);
+        delete lease.captureError;
         try {
             return await lease.page.screenshot(opts);
         }
-        catch {
-            // A capture that fails is not a broken lease. Report "could not capture" and leave the lease
-            // usable — the alternative is losing a working context to one bad frame.
+        catch (error) {
+            // A capture that fails is not a broken lease. Keep the reason and leave the lease usable,
+            // so the screenshot error says why the browser capture failed.
+            lease.captureError = error instanceof Error ? error.message : String(error);
             return undefined;
         }
     }
+    /** The reason {@link screenshotLease} last failed for this session, if it did. */
+    leaseCaptureError(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.captureError;
+    }
     /** The URL a lease was opened on — the one that carries its Reticle identity. */
     leaseUrl(sessionId) {
         return this.#active.get(this.#leaseIdOf(sessionId))?.url;
@@ -516,10 +519,10 @@ export class BrowserPool {
             if (opts.permissions !== undefined) {
                 await grantLeasePermissions(context, opts.permissions, url);
             }
+            await grantLocalNetworkAccess(context, url);
+            const csp = await widenLeaseCsp(context, url, this.#daemonOrigin);
             const page = await context.newPage();
-            // A caller-supplied init script is a stub of the bindings a desktop shell injects, and it has
-            // to exist before the app's first module runs. Installed here — before goto — so the very
-            // first document gets it, and kept for the lease (see hostStub) so a reload keeps it too.
+            // A desktop-shell stub must exist before the app's first module: added before goto, and kept.
             let hostStub;
             if (opts.initScript !== undefined) {
                 const added = await page.addInitScript?.(opts.initScript);
@@ -562,6 +565,8 @@ export class BrowserPool {
                 }
                 void dialog.dismiss();
             });
+            // Listener on BEFORE goto — an import-time throw lands during it (#1966).
+            listenForPageErrors(page, sessionId, this.#pageErrorHooks);
             const marker = leaseMarkerOf(url);
             if (marker?.session === sessionId) {
                 await installLeaseMarker(page, sessionId, targetOriginOf(url), marker.project);
@@ -593,24 +598,7 @@ export class BrowserPool {
             // Foreground it: a page opened beside other tabs can start hidden (#1351). Best-effort — a tab
             // that stays hidden is reported by name at the lease, which failing here would lose.
             await page.bringToFront?.().catch(() => undefined);
-            let navStatus;
-            if (null !== navRes && 'object' === typeof navRes && 'status' in navRes) {
-                const s = navRes.status;
-                if ('function' === typeof s) {
-                    try {
-                        const code = s.call(navRes);
-                        if ('number' === typeof code) {
-                            navStatus = code;
-                        }
-                    }
-                    catch {
-                        // ignore
-                    }
-                }
-                else if ('number' === typeof s) {
-                    navStatus = s;
-                }
-            }
+            const navStatus = navStatusOf(navRes);
             this.#active.set(sessionId, {
                 headed: slot.headed,
                 context,
@@ -620,6 +608,7 @@ export class BrowserPool {
                 touchedAt: this.#now(),
                 permissions: opts.permissions ?? [],
                 ignoresHTTPSErrors: true === opts.ignoreHTTPSErrors,
+                csp,
                 ...(pending === undefined ? {} : { dialFailureUrl: pending }),
                 ...(pendingDialogMessage === undefined ? {} : { lastDialogMessage: pendingDialogMessage }),
                 ...(hostStub === undefined || opts.initScript === undefined
@@ -632,7 +621,7 @@ export class BrowserPool {
                 ...(navStatus !== undefined ? { navStatus } : {}),
                 release: () => this.#release(sessionId),
                 injectReader: async () => {
-                    const script = this.#zeroInstall?.();
+                    const script = this.#zeroInstall?.(url);
                     if (script === undefined || page.evaluate === undefined) {
                         return false;
                     }
@@ -703,6 +692,7 @@ export class BrowserPool {
             return;
         } // already released or lost to a crash
         this.#active.delete(sessionId);
+        reportLeaseClosed(this.#pageErrorHooks, sessionId);
         // Drop any alias pointing here, or the map grows for the life of the daemon and a later lease
         // reusing that registered name would resolve to a context that is already closed.
         for (const [registered, leaseId] of this.#aliases) {
@@ -863,6 +853,10 @@ export class BrowserPool {
             waiter();
         } // let them re-claim + relaunch
     }
+    /** The origin added to this lease's page CSP `connect-src`, or undefined if none was (#2016). */
+    cspWidenedFor(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.csp.widenedFor;
+    }
     /** Whether this lease's context skips certificate checks. A context cannot change it later. */
     ignoresHTTPSErrors(sessionId) {
         return true === this.#active.get(this.#leaseIdOf(sessionId))?.ignoresHTTPSErrors;

package/dist/portal/pool/context-permissions.d.ts

@@ -1,20 +1,3 @@
-/**
- * Browser permissions on a leased context: granted before the first navigation, and read back where
- * the browser can contradict the grant.
- *
- * Never changed on a lease that is already open. Acquire hands an origin's live lease to whoever asks
- * for that origin, so the lease may be another agent's tab mid-flow, and nothing here knows whose it
- * is. A different set means a fresh lease.
- *
- * Each grant is scoped to the origin the lease was opened on, so a third-party frame the app embeds
- * is not handed the same grant as the app.
- *
- * Notifications are why the read-back exists. Playwright's headless shell — what the pool launches
- * when Playwright's own Chromium is installed — has no notification support: after a grant,
- * `navigator.permissions.query` reports `granted` while `Notification.permission` still reads
- * `denied`. A page that gates its UI on the second never sees the grant, so a lease that reported
- * "granted" there would be reporting something the page cannot see.
- */
 import type { PooledContext, PooledPage } from './pool-contract.js';
 /** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
 export declare const NOTIFICATIONS_PERMISSION = "notifications";
@@ -31,6 +14,19 @@ export declare class LeasePermissionError extends Error {
 }
 /** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
 export declare function grantLeasePermissions(context: PooledContext, permissions: readonly string[], url: string): Promise<void>;
+/** The origin of `url` when the page is not on loopback, else undefined (also for no url). */
+export declare function offLoopbackOrigin(url: string | undefined): string | undefined;
+/** Playwright's name for Chrome's Local Network Access grant (local + loopback network). */
+export declare const LOCAL_NETWORK_ACCESS = "local-network-access";
+/**
+ * Let a page that is not on loopback dial the bridge on loopback. Chromium blocks that unless a
+ * person grants Local Network Access, and a leased browser has no person, so a lease on a hosted
+ * preview loaded, signed in, and answered `sdk_never_dialled`. A loopback page needs no grant.
+ *
+ * ponytail: best effort. A Playwright older than the permission name refuses it; the lease then
+ * opens as before, and a page that cannot dial still reports `sdk_never_dialled`.
+ */
+export declare function grantLocalNetworkAccess(context: PooledContext, url: string): Promise<void>;
 /**
  * What the page's `Notification.permission` says, or undefined when it cannot be asked.
  *
@@ -39,3 +35,10 @@ export declare function grantLeasePermissions(context: PooledContext, permission
  * instead of holding the caller.
  */
 export declare function readNotificationPermission(page: PooledPage): Promise<string | undefined>;
+/**
+ * On a lease off loopback, add `daemonOrigin` to the page CSP `connect-src` (#2016). The returned
+ * record gets `widenedFor` once a response was really widened, so the lease can say so.
+ */
+export declare function widenLeaseCsp(context: PooledContext, url: string, daemonOrigin: string | undefined): Promise<{
+    widenedFor?: string;
+}>;

package/dist/portal/pool/context-permissions.js

@@ -1,3 +1,21 @@
+/**
+ * Browser permissions on a leased context: granted before the first navigation, and read back where
+ * the browser can contradict the grant.
+ *
+ * Never changed on a lease that is already open. Acquire hands an origin's live lease to whoever asks
+ * for that origin, so the lease may be another agent's tab mid-flow, and nothing here knows whose it
+ * is. A different set means a fresh lease.
+ *
+ * Each grant is scoped to the origin the lease was opened on, so a third-party frame the app embeds
+ * is not handed the same grant as the app.
+ *
+ * Notifications are why the read-back exists. Playwright's headless shell — what the pool launches
+ * when Playwright's own Chromium is installed — has no notification support: after a grant,
+ * `navigator.permissions.query` reports `granted` while `Notification.permission` still reads
+ * `denied`. A page that gates its UI on the second never sees the grant, so a lease that reported
+ * "granted" there would be reporting something the page cannot see.
+ */
+import { isLoopbackHostname } from '@reticlehq/core';
 /** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
 export const NOTIFICATIONS_PERMISSION = 'notifications';
 /** Evaluated in the leased page. A string, because the pool's page surface evaluates scripts. */
@@ -19,8 +37,9 @@ function reasonOf(err) {
 }
 /** Grant `permissions` on the origin of `url`. Nothing to grant is a no-op, not a refusal. */
 export async function grantLeasePermissions(context, permissions, url) {
-    if (0 === permissions.length)
+    if (0 === permissions.length) {
         return;
+    }
     if (context.grantPermissions === undefined) {
         throw new LeasePermissionError('this browser context cannot grant permissions');
     }
@@ -31,6 +50,36 @@ export async function grantLeasePermissions(context, permissions, url) {
         throw new LeasePermissionError(`could not grant ${permissions.join(', ')}: ${reasonOf(err)}`);
     }
 }
+/** The origin of `url` when the page is not on loopback, else undefined (also for no url). */
+export function offLoopbackOrigin(url) {
+    if (url === undefined || !URL.canParse(url)) {
+        return undefined;
+    }
+    const target = new URL(url);
+    return isLoopbackHostname(target.hostname) ? undefined : target.origin;
+}
+/** Playwright's name for Chrome's Local Network Access grant (local + loopback network). */
+export const LOCAL_NETWORK_ACCESS = 'local-network-access';
+/**
+ * Let a page that is not on loopback dial the bridge on loopback. Chromium blocks that unless a
+ * person grants Local Network Access, and a leased browser has no person, so a lease on a hosted
+ * preview loaded, signed in, and answered `sdk_never_dialled`. A loopback page needs no grant.
+ *
+ * ponytail: best effort. A Playwright older than the permission name refuses it; the lease then
+ * opens as before, and a page that cannot dial still reports `sdk_never_dialled`.
+ */
+export async function grantLocalNetworkAccess(context, url) {
+    const origin = offLoopbackOrigin(url);
+    if (context.grantPermissions === undefined || origin === undefined) {
+        return;
+    }
+    try {
+        await context.grantPermissions([LOCAL_NETWORK_ACCESS], { origin });
+    }
+    catch {
+        // An unknown permission name on an older Playwright: open the lease without it.
+    }
+}
 /**
  * What the page's `Notification.permission` says, or undefined when it cannot be asked.
  *
@@ -57,3 +106,16 @@ export async function readNotificationPermission(page) {
         clearTimeout(timer);
     }
 }
+/**
+ * On a lease off loopback, add `daemonOrigin` to the page CSP `connect-src` (#2016). The returned
+ * record gets `widenedFor` once a response was really widened, so the lease can say so.
+ */
+export async function widenLeaseCsp(context, url, daemonOrigin) {
+    const widening = {};
+    if (daemonOrigin !== undefined && offLoopbackOrigin(url) !== undefined) {
+        await context.widenCsp?.(daemonOrigin, () => {
+            widening.widenedFor = daemonOrigin;
+        });
+    }
+    return widening;
+}

package/dist/portal/pool/csp-widen.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Let the zero-install reader dial the daemon from a page whose CSP does not allow it (#2016).
+ *
+ * The page keeps its own Content-Security-Policy. The rewrite adds one source, the daemon's
+ * WebSocket origin, to `connect-src`, and changes nothing else. A bypass of page CSP would let a
+ * lease pass where a real user hits a CSP block, which is a false green.
+ *
+ * The rewrite changes the page that the agent verifies, so it reports each change (`changed`, and
+ * the `onWidened` call), and the lease result says `cspWidenedFor`.
+ */
+/** The result of a rewrite: the new text, and whether it differs from the text that came in. */
+export interface CspRewrite {
+    policy: string;
+    changed: boolean;
+}
+/**
+ * Add `origin` to the `connect-src` of each policy in `policy`. A comma joins several policies,
+ * and a browser enforces all of them, so each one gets the origin. A policy with no `connect-src`
+ * and no `default-src` already allows the dial, and stays as it is.
+ */
+export declare function allowDaemonInCsp(policy: string, origin: string): CspRewrite;
+/**
+ * Apply `allowDaemonInCsp` to each `<meta http-equiv="Content-Security-Policy">` in `html`.
+ * ponytail: reads the attribute text as it is; an entity-encoded quote inside it stays encoded.
+ */
+export declare function allowDaemonInHtml(html: string, origin: string): {
+    html: string;
+    changed: boolean;
+};
+/** The part of a Playwright `Route` the rewrite uses. A real `Route` satisfies it. */
+export interface CspRoute<R extends CspResponse = CspResponse> {
+    request(): {
+        resourceType(): string;
+        frame(): {
+            parentFrame(): unknown;
+        };
+    };
+    fallback(): Promise<void>;
+    fetch(opts: {
+        maxRedirects: number;
+    }): Promise<R>;
+    fulfill(opts: {
+        response: R;
+        headers?: Record<string, string>;
+        body?: string;
+    }): Promise<void>;
+}
+/** The part of a Playwright `APIResponse` the rewrite uses. */
+export interface CspResponse {
+    headers(): Record<string, string>;
+    headersArray(): {
+        name: string;
+        value: string;
+    }[];
+    text(): Promise<string>;
+}
+/**
+ * A route handler for a lease context: on the top document, add `origin` to its CSP header and
+ * CSP meta tags, and call `onWidened` when that changed anything. Every other request goes on.
+ * `Content-Security-Policy-Report-Only` blocks nothing, so it stays as the server sent it.
+ */
+export declare function widenDocumentCsp<R extends CspResponse>(route: CspRoute<R>, origin: string, onWidened: () => void): Promise<void>;

package/dist/portal/pool/csp-widen.js

@@ -0,0 +1,132 @@
+/**
+ * Let the zero-install reader dial the daemon from a page whose CSP does not allow it (#2016).
+ *
+ * The page keeps its own Content-Security-Policy. The rewrite adds one source, the daemon's
+ * WebSocket origin, to `connect-src`, and changes nothing else. A bypass of page CSP would let a
+ * lease pass where a real user hits a CSP block, which is a false green.
+ *
+ * The rewrite changes the page that the agent verifies, so it reports each change (`changed`, and
+ * the `onWidened` call), and the lease result says `cspWidenedFor`.
+ */
+const CONNECT_SRC = 'connect-src';
+const DEFAULT_SRC = 'default-src';
+const NONE_SOURCE = "'none'";
+const CSP_HEADER = 'content-security-policy';
+const DOCUMENT = 'document';
+const tokensOf = (directive) => directive.trim().split(/\s+/);
+const nameOf = (directive) => (tokensOf(directive)[0] ?? '').toLowerCase();
+/** `name` plus its sources plus `origin`. `'none'` goes, because it is valid only alone. */
+function withOrigin(name, sources, origin) {
+    const kept = sources.filter((s) => s.toLowerCase() !== NONE_SOURCE);
+    return [name, ...kept, origin].join(' ');
+}
+/** One policy (no commas). Only the first `connect-src` counts; a browser ignores a repeat. */
+function allowInOnePolicy(policy, origin) {
+    const directives = policy.split(';');
+    const connect = directives.findIndex((d) => nameOf(d) === CONNECT_SRC);
+    if (connect !== -1) {
+        const [name = CONNECT_SRC, ...sources] = tokensOf(directives[connect] ?? '');
+        if (sources.includes(origin)) {
+            return policy;
+        }
+        const lead = /^\s*/.exec(directives[connect] ?? '')?.[0] ?? '';
+        directives[connect] = `${lead}${withOrigin(name, sources, origin)}`;
+        return directives.join(';');
+    }
+    const fallback = directives.find((d) => nameOf(d) === DEFAULT_SRC);
+    if (fallback === undefined) {
+        return policy;
+    }
+    const head = policy.replace(/[\s;]+$/, '');
+    return `${head}; ${withOrigin(CONNECT_SRC, tokensOf(fallback).slice(1), origin)}`;
+}
+/**
+ * Add `origin` to the `connect-src` of each policy in `policy`. A comma joins several policies,
+ * and a browser enforces all of them, so each one gets the origin. A policy with no `connect-src`
+ * and no `default-src` already allows the dial, and stays as it is.
+ */
+export function allowDaemonInCsp(policy, origin) {
+    const next = policy
+        .split(',')
+        .map((one) => allowInOnePolicy(one, origin))
+        .join(',');
+    return { policy: next, changed: next !== policy };
+}
+const META_TAG = /<meta\b[^>]*>/gi;
+const CSP_EQUIV = /\bhttp-equiv\s*=\s*["']?content-security-policy["']?(?=[\s/>])/i;
+const CONTENT_ATTR = /(\bcontent\s*=\s*)("([^"]*)"|'([^']*)')/i;
+/**
+ * Apply `allowDaemonInCsp` to each `<meta http-equiv="Content-Security-Policy">` in `html`.
+ * ponytail: reads the attribute text as it is; an entity-encoded quote inside it stays encoded.
+ */
+export function allowDaemonInHtml(html, origin) {
+    const next = html.replace(META_TAG, (tag) => {
+        if (!CSP_EQUIV.test(tag)) {
+            return tag;
+        }
+        return tag.replace(CONTENT_ATTR, (_all, prefix, quoted) => {
+            const quote = quoted.charAt(0);
+            const widened = allowDaemonInCsp(quoted.slice(1, -1), origin).policy;
+            return `${prefix}${quote}${widened}${quote}`;
+        });
+    });
+    return { html: next, changed: next !== html };
+}
+function isTopDocument(route) {
+    const request = route.request();
+    if (request.resourceType() !== DOCUMENT) {
+        return false;
+    }
+    try {
+        return null === request.frame().parentFrame();
+    }
+    catch {
+        // A request with no frame (a service worker's own fetch) is no page the reader runs in.
+        return false;
+    }
+}
+/**
+ * A route handler for a lease context: on the top document, add `origin` to its CSP header and
+ * CSP meta tags, and call `onWidened` when that changed anything. Every other request goes on.
+ * `Content-Security-Policy-Report-Only` blocks nothing, so it stays as the server sent it.
+ */
+export async function widenDocumentCsp(route, origin, onWidened) {
+    if (!isTopDocument(route)) {
+        await route.fallback();
+        return;
+    }
+    let response;
+    try {
+        // No redirects followed here: a redirect goes back to the browser, so the page URL stays true.
+        response = await route.fetch({ maxRedirects: 0 });
+    }
+    catch {
+        await route.fallback();
+        return;
+    }
+    const policies = response
+        .headersArray()
+        .filter((h) => h.name.toLowerCase() === CSP_HEADER)
+        .map((h) => h.value);
+    const header = allowDaemonInCsp(policies.join(', '), origin);
+    const isHtml = /html/i.test(response.headers()['content-type'] ?? '');
+    const meta = isHtml ? allowDaemonInHtml(await response.text(), origin) : undefined;
+    if (!header.changed && true !== meta?.changed) {
+        await route.fulfill({ response });
+        return;
+    }
+    const headers = { ...response.headers() };
+    if (header.changed) {
+        headers[CSP_HEADER] = header.policy;
+    }
+    if (true === meta?.changed) {
+        // The new body is plain text: the old encoding and length describe a body that is gone.
+        delete headers['content-encoding'];
+        delete headers['content-length'];
+        await route.fulfill({ response, headers, body: meta.html });
+    }
+    else {
+        await route.fulfill({ response, headers });
+    }
+    onWidened();
+}

package/dist/portal/pool/lease-page-error.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The page-error side of a lease: listen for the throws the SDK will never see, and tell the
+ * wiring when the lease is gone.
+ *
+ * An app whose module graph throws during the first navigation fires its `error` event while the
+ * page still has no Reticle SDK in it — the zero-install reader is only evaluated after `goto`
+ * resolves — so nothing on the page records it, and a blank page reported as a bare console-error
+ * count (#1966). The server's Playwright handle is attached before the navigation, so it is the
+ * one witness that cannot miss the throw. This module owns that wiring for `BrowserPool`; the
+ * journal that buffers and journals what arrives lives in `page-error-journal.ts`.
+ */
+import type { PooledPage, PooledPageError } from './pool-contract.js';
+/** The page-error hooks `BrowserPoolOptions` carries, forwarded here verbatim. */
+export interface LeasePageErrorHooks {
+    onPageError?: ((leaseId: string, error: PooledPageError) => void) | undefined;
+    onLeaseClosed?: ((leaseId: string) => void) | undefined;
+}
+/**
+ * Install the lease's uncaught-error listener. Call BEFORE the first navigation — the listener
+ * timing is the whole fix: an import-time throw lands during `goto`, and one attached after it
+ * reads a broken page as healthy. Forwarded with the lease id, because the session for this lease
+ * usually does not exist yet, so the sink buffers.
+ */
+export declare function listenForPageErrors(page: PooledPage, leaseId: string, hooks: LeasePageErrorHooks | undefined): void;
+/**
+ * Report a closed lease — manual release, reaper and crash reclaim all funnel through the pool's
+ * one release path. The wiring owns whether anything was kept FOR that lease and drops it.
+ */
+export declare function reportLeaseClosed(hooks: LeasePageErrorHooks | undefined, leaseId: string): void;

package/dist/portal/pool/lease-page-error.js

@@ -0,0 +1,18 @@
+/**
+ * Install the lease's uncaught-error listener. Call BEFORE the first navigation — the listener
+ * timing is the whole fix: an import-time throw lands during `goto`, and one attached after it
+ * reads a broken page as healthy. Forwarded with the lease id, because the session for this lease
+ * usually does not exist yet, so the sink buffers.
+ */
+export function listenForPageErrors(page, leaseId, hooks) {
+    page.onPageError?.((error) => {
+        hooks?.onPageError?.(leaseId, error);
+    });
+}
+/**
+ * Report a closed lease — manual release, reaper and crash reclaim all funnel through the pool's
+ * one release path. The wiring owns whether anything was kept FOR that lease and drops it.
+ */
+export function reportLeaseClosed(hooks, leaseId) {
+    hooks?.onLeaseClosed?.(leaseId);
+}

package/dist/portal/pool/page-error-journal.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Journal the uncaught page errors the SDK was never installed in time to see.
+ *
+ * An app whose module graph throws during the first navigation fires its `error` event while the
+ * page still has no Reticle SDK in it — the zero-install reader is only evaluated after `goto`
+ * resolves. The agent then saw a blank page and a bare console-error count, and had to re-run the
+ * app under `--enable-logging` to learn why (#1966). The pool's Playwright handle is attached
+ * before the navigation, so the server is the one witness that cannot miss the throw.
+ *
+ * The pool hands errors here with the lease id. The session for that lease usually does not exist
+ * yet, so errors buffer per lease and flush the moment the session connects
+ * (`bridge.attachSessionCreate`). One already connected means the error is journaled at once.
+ *
+ * The daemon runs for days, so both maps are told to forget: a lease that is released or reaped
+ * has its buffer dropped (`onLeaseClosed`), and a session that has ended has its dedupe memory
+ * dropped (`onSessionEnd`). Without those, every failed lease and every ended session leaves an
+ * entry behind forever.
+ *
+ * Deduplication: when the SDK IS installed it reports the same throw as `error.uncaught` — with
+ * the browser's `Uncaught ` prefix on the message, which Playwright's spelling lacks. Both
+ * spellings fold into one identity (`uncaughtIdentity`), and whichever source is seen first
+ * suppresses the other's copy. A journal write is deferred by a short window first, so an SDK
+ * event racing the page error lands inside the window and wins. The reverse race — our copy
+ * first, the SDK's right after — can still journal both; the SDK's own event is authoritative and
+ * only the redundant second copy is cost, not wrong evidence.
+ */
+import { type ReticleEvent } from '@reticlehq/core';
+import type { PooledPageError } from './pool-contract.js';
+/** The session surface the journal needs. The real `Session` satisfies this structurally. */
+export interface JournalableSession {
+    readonly id: string;
+    readonly url?: string;
+    pushEvent(event: ReticleEvent): void;
+    eventsSince(cursor: number): ReticleEvent[];
+    onEvent(listener: (event: ReticleEvent) => void): () => void;
+}
+export interface PageErrorJournal {
+    /** The pool's sink — hand it to `BrowserPoolOptions.onPageError`. */
+    onPoolPageError(leaseId: string, error: PooledPageError): void;
+    /** The bridge hook — register with `bridge.attachSessionCreate`. */
+    onSessionCreate(session: JournalableSession): void;
+    /** The pool's release hook — register with `BrowserPoolOptions.onLeaseClosed`. */
+    onLeaseClosed(leaseId: string): void;
+    /** The bridge hook — register with `bridge.attachSessionEnd`. */
+    onSessionEnd(sessionId: string): void;
+}
+/**
+ * Fold the two spellings of one throw into one identity. Chromium prefixes a window-reported
+ * uncaught error with `Uncaught ` and often the error class (`Uncaught TypeError: ...`); the
+ * Playwright `pageerror` message is the bare exception text. Everything after the first line is a
+ * stack fragment and never matches, so it is dropped.
+ */
+export declare function uncaughtIdentity(rawMessage: string): string;
+export declare function makePageErrorJournal(deps: {
+    resolveSession: (leaseId: string) => JournalableSession | undefined;
+    sleep?: (ms: number) => Promise<void>;
+}): PageErrorJournal;