@reticlehq/server 3.6.0 → 3.7.0

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

@@ -10,7 +10,9 @@
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
 import { unreachableUrlIn } from '@reticlehq/core';
-import { seedStorageInto } from './storage-seed.js';
+import { seedStorageInto, targetOriginOf } from './storage-seed.js';
+import { installLeaseMarker, leaseMarkerOf } from './lease-marker-stamp.js';
+import { grantLeasePermissions, NOTIFICATION_PERMISSION_READ, NOTIFICATION_READ_TIMEOUT_MS, } from './context-permissions.js';
 /** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
 export const DEFAULT_LEASE_TTL_MS = 5 * 60_000;
 /** Default cap on how long a lease's initial navigation may take before it fails (frees the slot). */
@@ -22,6 +24,13 @@ const DEFAULT_NAV_TIMEOUT_MS = 30_000;
 const MAX_REMEMBERED_REAPED_LEASES = 64;
 /** What a headed lease is refused with where no window can be opened. */
 export const NO_HEADED_BROWSER = 'no headed browser can be opened here';
+/**
+ * What an acquire that asked for an init script is refused with when the page cannot run one.
+ *
+ * A refusal rather than a lease: the caller asked for a stub of the bindings a desktop shell
+ * injects, and a tab opened without it would throw in the app's view and read as a broken app.
+ */
+const INIT_SCRIPT_UNSUPPORTED = 'Init script failed: this page does not support init scripts, so the requested stub would not be there';
 /**
  * Owns a headless browser (and, when asked, a headed one) and leases isolated contexts out of them,
  * capped at `maxContexts` across both.
@@ -181,6 +190,15 @@ export class BrowserPool {
     #leaseIdOf(sessionId) {
         return this.#active.has(sessionId) ? sessionId : (this.#aliases.get(sessionId) ?? sessionId);
     }
+    /**
+     * Whether `sessionId` is a live lease that `owner` may let go of: one it took, or one taken by a
+     * caller with no id, which cannot be told apart from it. Another agent's lease is never this
+     * caller's to close (#1226).
+     */
+    heldBy(sessionId, owner) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        return lease !== undefined && (lease.owner === undefined || lease.owner === owner);
+    }
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId) {
         const lease = this.#active.get(this.#leaseIdOf(sessionId));
@@ -215,6 +233,28 @@ export class BrowserPool {
             return undefined;
         }
     }
+    /** The URL a lease was opened on — the one that carries its Reticle identity. */
+    leaseUrl(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.url;
+    }
+    /**
+     * Navigate a leased page through the browser. For a lease whose page has no SDK to take the
+     * command — a navigate to an image left the lease unreachable, and the next navigate answered "no
+     * connected session". False when this is not a lease or the page would not go.
+     */
+    async gotoLease(sessionId, url, timeoutMs) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease === undefined)
+            return false;
+        this.touch(sessionId);
+        try {
+            await lease.page.goto(url, timeoutMs === undefined ? {} : { timeoutMs });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Move the real pointer on a leased page, or false when this session is not a lease or cannot
      * hover. Same optional-capability contract as screenshotLease: absence must read as "could not
@@ -275,6 +315,52 @@ export class BrowserPool {
             return false;
         }
     }
+    /** What a lease was granted when it opened, or undefined for a session that is not a lease. */
+    permissionsOf(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.permissions;
+    }
+    /**
+     * Whether this lease's page runs a caller-supplied init script — a stub of the bindings a desktop
+     * shell injects. Alias-resolved like every agent-facing lookup, and false for any session that is
+     * not a lease with a stub, so a verdict can say when it was measured against a fake shell.
+     */
+    stubInstalled(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.hostStub !== undefined;
+    }
+    /**
+     * The init script this lease installed, or undefined when it runs none. Alias-resolved like
+     * `stubInstalled`. The lease tool compares it to the script a caller asks for: the same text means
+     * the held tab already is what was asked for, so it is reused rather than released and remade.
+     */
+    hostStubScript(sessionId) {
+        return this.#active.get(this.#leaseIdOf(sessionId))?.hostStubScript;
+    }
+    /**
+     * What the leased page's `Notification.permission` says, or undefined when it cannot be asked.
+     *
+     * Read back rather than inferred from the grant, because the headless shell answers `denied`
+     * after a notifications grant — see context-permissions.ts. Bounded, so a page that never answers
+     * reads as "could not ask" instead of holding the caller.
+     */
+    async notificationPermission(sessionId) {
+        const lease = this.#active.get(this.#leaseIdOf(sessionId));
+        if (lease === undefined || lease.page.evaluate === undefined)
+            return undefined;
+        let timer;
+        const gaveUp = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(undefined), NOTIFICATION_READ_TIMEOUT_MS);
+        });
+        try {
+            const value = await Promise.race([lease.page.evaluate(NOTIFICATION_PERMISSION_READ), gaveUp]);
+            return 'string' === typeof value ? value : undefined;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     async sweepExpired() {
         const now = this.#now();
         const expired = [...this.#active.entries()]
@@ -336,8 +422,21 @@ export class BrowserPool {
         let pendingDialogMessage;
         try {
             const browser = await this.#ensureBrowser(slot);
-            context = await browser.newContext();
+            context = await browser.newContext(true === opts.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : undefined);
+            if (opts.permissions !== undefined)
+                await grantLeasePermissions(context, opts.permissions, url);
             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.
+            let hostStub;
+            if (opts.initScript !== undefined) {
+                const added = await page.addInitScript?.(opts.initScript);
+                if (added === undefined || 'function' !== typeof added.dispose) {
+                    throw new Error(INIT_SCRIPT_UNSUPPORTED);
+                }
+                hostStub = added;
+            }
             // Per-page crash isolation: if THIS renderer dies, reclaim only this lease — the shared browser
             // and every other agent's context keep running. (A full browser death is handled by #onCrash.)
             page.onCrash(() => {
@@ -367,6 +466,10 @@ export class BrowserPool {
                     pendingDialogMessage = dialog.message;
                 void dialog.dismiss();
             });
+            const marker = leaseMarkerOf(url);
+            if (marker?.session === sessionId) {
+                await installLeaseMarker(page, sessionId, targetOriginOf(url), marker.project);
+            }
             let seedHandle;
             let checkSeedError;
             if (opts.seedStorage !== undefined) {
@@ -390,6 +493,9 @@ export class BrowserPool {
             // no longer the live browser, bail — the catch below closes the context and returns the slot.
             if (slot.browser !== browser)
                 throw new Error('browser crashed during navigation');
+            // 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;
@@ -414,8 +520,13 @@ export class BrowserPool {
                 url,
                 ...(opts.owner === undefined ? {} : { owner: opts.owner }),
                 touchedAt: this.#now(),
+                permissions: opts.permissions ?? [],
+                ignoresHTTPSErrors: true === opts.ignoreHTTPSErrors,
                 ...(pending === undefined ? {} : { dialFailureUrl: pending }),
                 ...(pendingDialogMessage === undefined ? {} : { lastDialogMessage: pendingDialogMessage }),
+                ...(hostStub === undefined || opts.initScript === undefined
+                    ? {}
+                    : { hostStub, hostStubScript: opts.initScript }),
             });
             return {
                 sessionId,
@@ -492,6 +603,9 @@ export class BrowserPool {
             if (leaseId === sessionId)
                 this.#aliases.delete(registered);
         }
+        // Disposed with the lease, which is what "for that lease only" means. Best-effort: a context
+        // that is already gone (a crash) makes the disposal moot, not a reason to fail the release.
+        await lease.hostStub?.dispose().catch(() => undefined);
         await lease.context.close().catch(() => undefined);
         this.#releaseSlot();
     }
@@ -597,6 +711,10 @@ export class BrowserPool {
         for (const waiter of this.#waiters.splice(0))
             waiter(); // let them re-claim + relaunch
     }
+    /** 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;
+    }
     /** Whether this lease lives in the headed browser. */
     isHeaded(sessionId) {
         return true === this.#active.get(this.#leaseIdOf(sessionId))?.headed;

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

@@ -0,0 +1,33 @@
+/**
+ * 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 } from './pool-contract.js';
+/** The permission whose grant the headless shell does not pass on to `Notification.permission`. */
+export declare const NOTIFICATIONS_PERMISSION = "notifications";
+/** Evaluated in the leased page. A string, because the pool's page surface evaluates scripts. */
+export declare const NOTIFICATION_PERMISSION_READ = "typeof Notification === 'undefined' ? 'unsupported' : Notification.permission";
+/**
+ * How long a read-back may take. Bounded because acquire waits on it, and a wedged renderer never
+ * answers an evaluation: an unbounded one would turn "this tab is stuck" into "acquire hangs".
+ */
+export declare const NOTIFICATION_READ_TIMEOUT_MS = 1500;
+/** A permission could not be granted or cleared. Its message is written for the agent. */
+export declare class LeasePermissionError extends Error {
+    readonly name = "LeasePermissionError";
+}
+/** 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>;

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

@@ -0,0 +1,33 @@
+/** 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. */
+export const NOTIFICATION_PERMISSION_READ = "typeof Notification === 'undefined' ? 'unsupported' : Notification.permission";
+/**
+ * How long a read-back may take. Bounded because acquire waits on it, and a wedged renderer never
+ * answers an evaluation: an unbounded one would turn "this tab is stuck" into "acquire hangs".
+ */
+export const NOTIFICATION_READ_TIMEOUT_MS = 1_500;
+/** Playwright prefixes its errors with the call that failed; the agent needs only the reason. */
+const PLAYWRIGHT_CALL_PREFIX = /^browserContext\.\w+:\s*/;
+/** A permission could not be granted or cleared. Its message is written for the agent. */
+export class LeasePermissionError extends Error {
+    name = 'LeasePermissionError';
+}
+function reasonOf(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return (message.split('\n')[0] ?? message).replace(PLAYWRIGHT_CALL_PREFIX, '');
+}
+/** 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)
+        return;
+    if (context.grantPermissions === undefined) {
+        throw new LeasePermissionError('this browser context cannot grant permissions');
+    }
+    try {
+        await context.grantPermissions([...permissions], { origin: new URL(url).origin });
+    }
+    catch (err) {
+        throw new LeasePermissionError(`could not grant ${permissions.join(', ')}: ${reasonOf(err)}`);
+    }
+}

package/dist/portal/pool/lease-marker-stamp.d.ts

@@ -0,0 +1,23 @@
+import type { PooledPage } from './pool-contract.js';
+interface LeaseMarkerArg {
+    session: string;
+    project?: string | undefined;
+    targetOrigin: string;
+    sessionParam: string;
+    projectParam: string;
+}
+/**
+ * Init script restoring the marker a server redirect dropped, so the SDK registers under the lease id.
+ * It runs only in pages of the lease's own browser context, so a person's tab at the same URL never
+ * carries the marker and is never adopted. It writes only in the top frame, only on the lease's own
+ * target origin (never an identity provider's or any third party's URL), and the pool installs it
+ * only when the navigated URL's marker matches this lease's id. Must stay self-contained: Playwright
+ * serialises the function source into the page.
+ */
+export declare function stampLeaseMarker(arg: LeaseMarkerArg): void;
+export declare function installLeaseMarker(page: PooledPage, leaseId: string, targetOrigin: string | undefined, project: string | undefined): Promise<void>;
+export declare function leaseMarkerOf(url: string): {
+    session: string;
+    project: string | undefined;
+} | undefined;
+export {};

package/dist/portal/pool/lease-marker-stamp.js

@@ -0,0 +1,49 @@
+import { RETICLE_URL_PARAM } from '@reticlehq/core';
+/**
+ * Init script restoring the marker a server redirect dropped, so the SDK registers under the lease id.
+ * It runs only in pages of the lease's own browser context, so a person's tab at the same URL never
+ * carries the marker and is never adopted. It writes only in the top frame, only on the lease's own
+ * target origin (never an identity provider's or any third party's URL), and the pool installs it
+ * only when the navigated URL's marker matches this lease's id. Must stay self-contained: Playwright
+ * serialises the function source into the page.
+ */
+export function stampLeaseMarker(arg) {
+    const win = globalThis.window;
+    if (win === undefined || win.top !== win || win.location.origin !== arg.targetOrigin)
+        return;
+    try {
+        const url = new URL(win.location.href);
+        if (url.searchParams.has(arg.sessionParam))
+            return;
+        url.searchParams.set(arg.sessionParam, arg.session);
+        if (arg.project !== undefined && !url.searchParams.has(arg.projectParam)) {
+            url.searchParams.set(arg.projectParam, arg.project);
+        }
+        win.history.replaceState(null, '', url.toString());
+    }
+    catch {
+        return;
+    }
+}
+export async function installLeaseMarker(page, leaseId, targetOrigin, project) {
+    if (page.addInitScript === undefined || targetOrigin === undefined)
+        return;
+    await page.addInitScript(stampLeaseMarker, {
+        session: leaseId,
+        project,
+        targetOrigin,
+        sessionParam: RETICLE_URL_PARAM.SESSION,
+        projectParam: RETICLE_URL_PARAM.PROJECT,
+    });
+}
+export function leaseMarkerOf(url) {
+    try {
+        const params = new URL(url).searchParams;
+        const session = params.get(RETICLE_URL_PARAM.SESSION) ?? '';
+        const project = params.get(RETICLE_URL_PARAM.PROJECT) ?? '';
+        return '' === session ? undefined : { session, project: '' === project ? undefined : project };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/portal/pool/playwright-launcher.d.ts

@@ -7,18 +7,40 @@
  */
 import type { Launcher } from './browser-pool.js';
 import type { ScreenshotOptions } from './pool-contract.js';
-/** Reticle's own panel, kept out of a picture of the app: it is ours, not what the app shows. */
-export declare const HIDE_RETICLE_CHROME_CSS = "[data-reticle-overlay]{display:none !important}";
 /**
- * How Playwright captures a leased tab. A live picture (JPEG) leaves Reticle's panel out, as the
- * visual captures do; a plain PNG capture is unchanged, so no existing baseline moves.
+ * Reticle paints its own UI (presenter HUD, glow, annotator marks, tour) into the page. It is
+ * time-varying, since the activity log and border state change with every command, so capturing it
+ * makes a fresh screenshot of an unchanged page differ from its baseline. Playwright applies `style`
+ * for the shot only and then reverts it, so the page under test is never changed. Disabling animations
+ * settles any remaining transitions. Shared by every capture path, driven and leased, so both hide
+ * the same set: core's `RETICLE_OVERLAY_SELECTOR`.
+ */
+export declare const SCREENSHOT_DETERMINISM: {
+    readonly style: "[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark],[data-reticle-blocker],[data-reticle-tour]{display:none !important}";
+    readonly animations: "disabled";
+};
+/**
+ * How Playwright captures a leased tab: a PNG by default, a JPEG for a live picture. Every capture
+ * hides Reticle's own UI with `SCREENSHOT_DETERMINISM`, the same as the driven path, so a lease
+ * baseline shows the app and not the HUD.
  */
 export declare function screenshotOptions(opts: ScreenshotOptions): {
     fullPage: boolean;
+    style?: string;
+    animations?: 'disabled';
     type?: 'jpeg';
     quality?: number;
-    style?: string;
+    scale?: 'css';
 };
+/**
+ * A step screenshot with Reticle's own UI out of it. The step path injects nothing into the page
+ * (no stylesheet, no fast-forwarded animation), so the HUD covered a third of every picture. Only
+ * our own hosts change, by their own inline `visibility`, for this one capture, and are put back
+ * whatever the capture did: the app's DOM, styles and events are not touched.
+ */
+export declare function captureWithChromeHidden(page: {
+    evaluate: (script: string) => Promise<unknown>;
+}, capture: () => Promise<Uint8Array>): Promise<Uint8Array>;
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
  * the rest of this file needs a real Chromium.

package/dist/portal/pool/playwright-launcher.js

@@ -6,26 +6,60 @@
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
+import { HIDE_RETICLE_CHROME_CSS, RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
 import { launchChromium } from '../../launch-chromium.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { chromiumInstallCommand, chromiumInstallDepsCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
 import { installNetworkMocks } from '../input/network-mock.js';
-/** Reticle's own panel, kept out of a picture of the app: it is ours, not what the app shows. */
-export const HIDE_RETICLE_CHROME_CSS = '[data-reticle-overlay]{display:none !important}';
 /**
- * How Playwright captures a leased tab. A live picture (JPEG) leaves Reticle's panel out, as the
- * visual captures do; a plain PNG capture is unchanged, so no existing baseline moves.
+ * Reticle paints its own UI (presenter HUD, glow, annotator marks, tour) into the page. It is
+ * time-varying, since the activity log and border state change with every command, so capturing it
+ * makes a fresh screenshot of an unchanged page differ from its baseline. Playwright applies `style`
+ * for the shot only and then reverts it, so the page under test is never changed. Disabling animations
+ * settles any remaining transitions. Shared by every capture path, driven and leased, so both hide
+ * the same set: core's `RETICLE_OVERLAY_SELECTOR`.
+ */
+export const SCREENSHOT_DETERMINISM = {
+    style: HIDE_RETICLE_CHROME_CSS,
+    animations: 'disabled',
+};
+/**
+ * How Playwright captures a leased tab: a PNG by default, a JPEG for a live picture. Every capture
+ * hides Reticle's own UI with `SCREENSHOT_DETERMINISM`, the same as the driven path, so a lease
+ * baseline shows the app and not the HUD.
  */
 export function screenshotOptions(opts) {
+    // A step screenshot is evidence about the page, so it must not change it: `animations: disabled`
+    // fast-forwards running animations to their end and fires their events in the app under test.
+    if (true === opts.cssScale && opts.jpegQuality !== undefined) {
+        return { fullPage: false, type: 'jpeg', quality: opts.jpegQuality, scale: 'css' };
+    }
+    const base = { ...SCREENSHOT_DETERMINISM, fullPage: true === opts.fullPage };
     return opts.jpegQuality === undefined
-        ? { fullPage: true === opts.fullPage }
-        : {
-            fullPage: true === opts.fullPage,
-            type: 'jpeg',
-            quality: opts.jpegQuality,
-            style: HIDE_RETICLE_CHROME_CSS,
-        };
+        ? base
+        : { ...base, type: 'jpeg', quality: opts.jpegQuality };
+}
+/** Where the hidden hosts' own visibility waits to be put back, on the page's window. */
+const SHOT_HIDDEN_KEY = '__reticleShotHidden';
+/** A string literal safe to splice into a script: JSON plus the characters that end one early. */
+const scriptLiteral = (value) => JSON.stringify(value).replace(/[<>/\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+const HIDE_CHROME_SCRIPT = `(() => { const held = []; for (const el of document.querySelectorAll(${scriptLiteral(RETICLE_OVERLAY_SELECTOR)})) { held.push([el, el.style.visibility]); el.style.visibility = 'hidden'; } window.${SHOT_HIDDEN_KEY} = held; })()`;
+const RESTORE_CHROME_SCRIPT = `(() => { for (const [el, was] of window.${SHOT_HIDDEN_KEY} ?? []) el.style.visibility = was; delete window.${SHOT_HIDDEN_KEY}; })()`;
+/**
+ * A step screenshot with Reticle's own UI out of it. The step path injects nothing into the page
+ * (no stylesheet, no fast-forwarded animation), so the HUD covered a third of every picture. Only
+ * our own hosts change, by their own inline `visibility`, for this one capture, and are put back
+ * whatever the capture did: the app's DOM, styles and events are not touched.
+ */
+export async function captureWithChromeHidden(page, capture) {
+    await page.evaluate(HIDE_CHROME_SCRIPT);
+    try {
+        return await capture();
+    }
+    finally {
+        await page.evaluate(RESTORE_CHROME_SCRIPT).catch(() => undefined);
+    }
 }
 /**
  * How a leased tab navigates. Pure, and exported, because the decision in it is worth a test while
@@ -49,8 +83,8 @@ export function gotoOptions(timeoutMs) {
 function wrapBrowser(browser) {
     return {
         isConnected: () => browser.isConnected(),
-        newContext: async () => {
-            const context = await browser.newContext();
+        newContext: async (opts) => {
+            const context = await browser.newContext(true === opts?.ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : undefined);
             return {
                 newPage: async () => {
                     const page = await context.newPage();
@@ -59,7 +93,15 @@ function wrapBrowser(browser) {
                         close: () => page.close(),
                         evaluate: (script) => page.evaluate(script),
                         // Playwright returns a Buffer; Uint8Array is what the visual store and differ take.
-                        screenshot: async (opts) => new Uint8Array(await page.screenshot(screenshotOptions(opts ?? {}))),
+                        // Same determinism as the driven path's capturePage: without it a lease baseline caught
+                        // the HUD, its activity log and the toolbar, and a HUD change read as a regression (#1355).
+                        screenshot: async (opts) => {
+                            const shoot = async () => new Uint8Array(await page.screenshot(screenshotOptions(opts ?? {})));
+                            // A step capture injects no stylesheet, so our own hosts are hidden another way.
+                            return true === opts?.cssScale
+                                ? captureWithChromeHidden({ evaluate: (script) => page.evaluate(script) }, shoot)
+                                : shoot();
+                        },
                         // Three moves, same as performGesture: a single move to the center can be a no-op if
                         // the pointer was already there, and CSS :hover needs a native hit-test to apply.
                         hover: async (x, y) => {
@@ -69,6 +111,7 @@ function wrapBrowser(browser) {
                         },
                         installMocks: (rules) => installNetworkMocks(page, [...rules]),
                         setViewport: (size) => page.setViewportSize(size),
+                        bringToFront: () => page.bringToFront(),
                         onCrash: (handler) => page.on('crash', handler),
                         onConsole: (handler) => page.on('console', (msg) => handler(msg.text())),
                         onDialog: (handler) => page.on('dialog', (dialog) => handler({ message: dialog.message(), dismiss: () => dialog.dismiss() })),
@@ -83,6 +126,8 @@ function wrapBrowser(browser) {
                     };
                 },
                 addCookies: (cookies) => context.addCookies(cookies),
+                grantPermissions: (permissions, opts) => context.grantPermissions(permissions, opts),
+                clearPermissions: () => context.clearPermissions(),
                 close: () => context.close(),
             };
         },

package/dist/portal/pool/pool-contract.d.ts

@@ -64,6 +64,11 @@ export interface PooledPage {
      * existed short of restarting the daemon), because nothing in the stack ever answered it.
      */
     onDialog?(handler: (dialog: PooledDialog) => void): void;
+    /**
+     * Make this the visible tab. OPTIONAL, like `onDialog`: a page opened beside others can start
+     * hidden, and a hidden tab throttles timers and rAF so nothing on it verifies (#1351).
+     */
+    bringToFront?(): Promise<void>;
 }
 /** A native dialog the page opened, handed to the pool so it can be dismissed instead of left blocking. */
 export interface PooledDialog {
@@ -103,11 +108,24 @@ export interface PooledContext {
     newPage(): Promise<PooledPage>;
     close(): Promise<void>;
     addCookies?(cookies: PooledCookie[]): Promise<void>;
+    /**
+     * Grant browser permissions on this context. OPTIONAL, like `addCookies`: a context that cannot
+     * grant makes a lease that asked for permissions refuse, rather than open with none granted while
+     * the caller believes otherwise.
+     */
+    grantPermissions?(permissions: string[], opts?: {
+        origin?: string;
+    }): Promise<void>;
+    /** Drop every permission granted on this context. OPTIONAL, for the same reason. */
+    clearPermissions?(): Promise<void>;
 }
 /** The launched browser. Real Playwright `Browser` satisfies this. */
 export interface PooledBrowser {
     isConnected(): boolean;
-    newContext(): Promise<PooledContext>;
+    /** `ignoreHTTPSErrors` accepts a self-signed or local-CA certificate for this context only. */
+    newContext(opts?: {
+        ignoreHTTPSErrors?: boolean;
+    }): Promise<PooledContext>;
     close(): Promise<void>;
     /** Fires when the browser process dies/crashes so the pool can relaunch on the next acquire. */
     onDisconnected(handler: () => void): void;
@@ -118,4 +136,6 @@ export type Launcher = () => Promise<PooledBrowser>;
 export interface ScreenshotOptions {
     fullPage?: boolean;
     jpegQuality?: number;
+    /** One image pixel per CSS pixel, so a high-density display does not double a step screenshot. */
+    cssScale?: boolean;
 }

package/dist/portal/session/agent-link.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What the HUD shows about the coding agent: who is attached, and this tab's latest notes to it with
+ * whether an agent's tool call has taken each one. Read from the session's own inbox history, so
+ * "Seen" is shown only for a note that was actually handed to an agent.
+ */
+import { type AgentLink } from '@reticlehq/core';
+import type { InboxMessage } from './human/live-control.js';
+export declare function agentLinkOf(history: readonly InboxMessage[]): AgentLink;

package/dist/portal/session/agent-link.js

@@ -0,0 +1,17 @@
+/**
+ * What the HUD shows about the coding agent: who is attached, and this tab's latest notes to it with
+ * whether an agent's tool call has taken each one. Read from the session's own inbox history, so
+ * "Seen" is shown only for a note that was actually handed to an agent.
+ */
+import { AGENT_NOTE_MAX, AGENT_NOTES_SHOWN } from '@reticlehq/core';
+import { connectedAgents } from '../../hooks/coding-agents.js';
+export function agentLinkOf(history) {
+    return {
+        agents: connectedAgents(),
+        notes: history.slice(-AGENT_NOTES_SHOWN).map((message) => ({
+            text: message.text.slice(0, AGENT_NOTE_MAX),
+            seen: true === message.seen,
+            ...(message.by === undefined ? {} : { by: message.by }),
+        })),
+    };
+}

package/dist/portal/session/command-payload.js

@@ -1,5 +1,5 @@
 import { CommandActor, MessageKind } from '@reticlehq/core';
-import { currentDrivenBy } from '../../hooks/driven-by.js';
+import { currentDrivenBy, harnessOutwardAllowed } from '../../hooks/driven-by.js';
 /**
  * The command a session sends its page, as wire JSON.
  *
@@ -15,5 +15,10 @@ export function commandPayload(id, sessionId, name, args) {
         name,
         args,
         ...(currentDrivenBy() === undefined ? {} : { by: CommandActor.HARNESS }),
+        // The page presses no outward control (invite, send, delete, pay…) the journey did not ask for.
+        ...outwardField(harnessOutwardAllowed()),
     });
 }
+function outwardField(allowed) {
+    return allowed === undefined ? {} : { outward: { allowed } };
+}

package/dist/portal/session/daemon-answers.d.ts

@@ -1,5 +1,4 @@
 import { log } from '../../log.js';
-import { bindSpanContext } from '../../trace.js';
 /**
  * What the daemon answers when the rules that decide a verdict ask it for something.
  *
@@ -15,6 +14,7 @@ import { bindSpanContext } from '../../trace.js';
 export declare const noteToDaemonLog: typeof log;
 /**
  * Keep a callback belonging to the call that created it, so a re-check scheduled for later still
- * traces back to the wait that asked for it instead of looking like work starting from nowhere.
+ * traces back to the wait that asked for it instead of looking like work starting from nowhere, and
+ * is still the Harness's when the Harness made the call: the HUD files it by who drove it.
  */
-export declare const keepCallerContextInDaemon: typeof bindSpanContext;
+export declare const keepCallerContextInDaemon: <A extends unknown[]>(fn: (...args: A) => void) => ((...args: A) => void);

package/dist/portal/session/daemon-answers.js

@@ -1,5 +1,6 @@
 import { log } from '../../log.js';
 import { bindSpanContext } from '../../trace.js';
+import { bindDrivenBy } from '../../hooks/driven-by.js';
 /**
  * What the daemon answers when the rules that decide a verdict ask it for something.
  *
@@ -15,6 +16,7 @@ import { bindSpanContext } from '../../trace.js';
 export const noteToDaemonLog = log;
 /**
  * Keep a callback belonging to the call that created it, so a re-check scheduled for later still
- * traces back to the wait that asked for it instead of looking like work starting from nowhere.
+ * traces back to the wait that asked for it instead of looking like work starting from nowhere, and
+ * is still the Harness's when the Harness made the call: the HUD files it by who drove it.
  */
-export const keepCallerContextInDaemon = bindSpanContext;
+export const keepCallerContextInDaemon = (fn) => bindDrivenBy(bindSpanContext(fn));

package/dist/portal/session/dev-server/dev-command.d.ts

@@ -36,3 +36,12 @@ export declare function detectDevCommand(directory: string, read?: (path: string
  * package manager, because a workspace package usually has no lockfile of its own.
  */
 export declare function detectDevCommandInProject(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[]): DevCommand | undefined;
+/**
+ * The command that wires THIS project for good: `init`, in the app's own folder, through the
+ * one-off runner the project's package manager ships.
+ *
+ * Handed to an agent whose install never ran `init` (an MCP-only route), so it has to be right first
+ * time: `init` run in a folder that is not the app stops on a missing package.json, and a runner the
+ * machine does not have is "command not found". npx whenever there is doubt — it ships with Node.
+ */
+export declare function initCommandIn(directory: string, read?: (path: string) => string | undefined, listDirs?: (path: string) => readonly string[]): string;