@reticlehq/server 3.6.0 → 3.7.0

package/dist/memory/recall/project-memory.js

@@ -12,9 +12,13 @@
  * question the fetch counters exist to answer and could not while nothing was reading.
  */
 import { cloudFetch } from '../cloud/cloud-sync.js';
+import { callingClientName } from '../../hooks/coding-agents.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
-import { isReadableMemoryScope, memoryReadUrl, scopedMemoryEntries, scopeOfMemoryResponse, } from '../cloud/memory-scope.js';
-/** Named so a read from the tool surface is distinguishable from the CLI's and from replay's. */
+import { isReadableMemoryScope, MemoryReadHeader, memoryReadUrl, scopedMemoryEntries, scopeOfMemoryResponse, } from '../cloud/memory-scope.js';
+/**
+ * Named so a read from the tool surface is distinguishable from the CLI's and from replay's. The
+ * reader is the MCP client that made the call when one can be named; this only when none can.
+ */
 const MCP_AGENT_ID = 'reticle-mcp';
 /** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
 export const MemoryUnavailable = {
@@ -68,10 +72,34 @@ const asKnown = (raw) => {
  * twice returns the same order — an unstable list reads as the corpus churning when it has not.
  */
 const PROVED = 'proved';
-export const rankKnown = (things) => [
-    ...things.filter((t) => PROVED === t.status),
-    ...things.filter((t) => PROVED !== t.status),
+const AGREED = 'agreed';
+/** Set aside on the dashboard or by `reticle_memory {set-aside}`: nobody stands by it any more. */
+const SET_ASIDE = 'stale';
+/** Then agreed, then what a person wrote (no flow behind it), then flow intents. */
+const RANKS = [
+    (t) => PROVED === t.status,
+    (t) => AGREED === t.status,
+    (t) => null === t.flowName,
+    () => true,
 ];
+export const rankKnown = (things) => things
+    .map((thing, at) => ({ thing, at, rank: RANKS.findIndex((fits) => fits(thing)) }))
+    .sort((a, b) => a.rank - b.rank || a.at - b.at)
+    .map((r) => r.thing);
+/**
+ * What a read can show: each statement once (a persona's intent saved on six pages pushed a
+ * person's own fact past the cap) and nothing set aside (it ranked second seconds after).
+ */
+const liveAndDistinct = (things) => {
+    const seen = new Set();
+    return rankKnown(things.filter((t) => SET_ASIDE !== t.status)).filter((t) => {
+        const key = t.statement.trim();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
 export async function readProjectMemory(fs, root, home, env, opts) {
     const cloud = await resolveProjectCloud(fs, root, home, env);
     if (null === cloud.config)
@@ -92,7 +120,7 @@ export async function readProjectMemory(fs, root, home, env, opts) {
                 authorization: `Bearer ${cloud.config.apiKey}`,
                 // What makes this read COUNT as an agent consulting the corpus rather than a human
                 // browsing — the distinction the dashboard's "times an agent consulted it" rests on.
-                'x-reticle-agent': MCP_AGENT_ID,
+                [MemoryReadHeader.AGENT]: callingClientName() ?? MCP_AGENT_ID,
             },
         });
         if (200 !== res.status)
@@ -118,14 +146,14 @@ export async function readProjectMemory(fs, root, home, env, opts) {
         // The entry-level pass is redundant against the envelope check above and kept for a server that
         // labels entries instead. `total` is counted AFTER it, so a truncated list still tells the truth
         // about how many of THIS project's statements there were.
-        const known = entries.map(asKnown).filter((k) => k !== null);
+        const known = liveAndDistinct(entries.map(asKnown).filter((k) => k !== null));
         return {
             ok: true,
             subject: opts.subject ?? null,
             // Capped for the agent's context, but `total` always reports the truth so the cap is never
             // silent — a truncated list that looks complete is how an agent concludes a project knows
             // less than it does.
-            known: rankKnown(known).slice(0, opts.limit),
+            known: known.slice(0, opts.limit),
             total: known.length,
         };
     }

package/dist/portal/bridge/bridge.d.ts

@@ -1,6 +1,7 @@
 import * as http from 'node:http';
 import { Session } from '../session/session.js';
 import { SessionManager } from '../session/session-manager.js';
+import { type HarnessRequest } from './harness-request.js';
 import { pairingTokenSource } from './pairing-token.js';
 /** A human clicked ▶ on a saved flow in the panel — replay it with no agent. Wired by the daemon. */
 type ReplayRequestHandler = (sessionId: string, flowName: string) => void;
@@ -107,12 +108,15 @@ export declare class Bridge {
      */
     attachSyncRequest(handler: () => void): void;
     /**
-     * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
-     * bridge built without one ignores the request rather than refusing it.
+     * Register a handler for the panel's Harness controls (switch, Run, Stop). Optional for the same
+     * reason as the above: a bridge built without one ignores the request rather than refusing it.
      */
-    attachHarnessRequest(handler: (enabled: boolean, session: Session) => void): void;
-    /** Register a handler for the panel's Sign in. Optional, like the above: without one it is ignored. */
-    attachSigninRequest(handler: () => void): void;
+    attachHarnessRequest(handler: (request: HarnessRequest, session: Session) => void): void;
+    /**
+     * Register a handler for the panel's Sign in, told which tab asked (its project is linked once the
+     * sign-in lands). Optional, like the above: without one it is ignored.
+     */
+    attachSigninRequest(handler: (from: Session) => void): void;
     /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler: (session: Session) => void): void;
     close(): Promise<void>;

package/dist/portal/bridge/bridge.js

@@ -8,11 +8,13 @@ import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOO
 import { Session } from '../session/session.js';
 import { SessionManager } from '../session/session-manager.js';
 import { tokensMatch } from './token-auth.js';
+import { noteWrongPathUpgrades, wrongPathReason } from './wrong-path.js';
+import { harnessRequest } from './harness-request.js';
 import { pairingTokenSource } from './pairing-token.js';
 import { log } from '../../log.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { SESSION_PARKED_REASON, sessionReplacedReason, } from '../session/facts/session-replaced.js';
-import { describeSkew, sdkFix, SkewPair } from '../../command/version/version-skew.js';
+import { describeSdkBehind, describeSkew, sdkFix, SDK_BEHIND_NARRATION, SkewPair, } from '../../command/version/version-skew.js';
 import { noteVersionSkew } from '../../command/version/version-nudge.js';
 import { protocolSkewReason } from './protocol-skew.js';
 import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
@@ -129,24 +131,6 @@ function replayRequest(event) {
     const name = event.data['text'];
     return 'string' === typeof name && name.length > 0 ? name : undefined;
 }
-/**
- * The desired harness state if this event is the panel's switch, else undefined.
- *
- * Carries `on`/`off` rather than meaning "toggle": a double-click on a flaky connection sends two,
- * and two toggles land back where they started while two `on`s are the same as one.
- */
-function harnessRequest(event) {
-    if (event.type !== EventType.HUMAN_CONTROL)
-        return undefined;
-    if (event.data['kind'] !== HumanControlKind.HARNESS)
-        return undefined;
-    const want = event.data['text'];
-    if ('on' === want)
-        return true;
-    if ('off' === want)
-        return false;
-    return undefined;
-}
 /** True when this event is the panel's Sign in. Pure boundary narrowing, like the above. */
 function isSigninRequest(event) {
     return event.type === EventType.HUMAN_CONTROL && event.data['kind'] === HumanControlKind.SIGNIN;
@@ -401,6 +385,15 @@ export class Bridge {
         this.#wss.on('error', (err) => {
             log('bridge_ws_error', { error: err.message });
         });
+        // A dial on any other path got a bare 400 from `ws` and left no trace for a diagnosis (#1242).
+        // Only a dial the origin check would have let in is the app's: a socket with no Origin is any
+        // local process, and recording it would tell the agent the app is running when it may not be.
+        noteWrongPathUpgrades(this.#wss, (path, origin) => {
+            log('bridge_wrong_path', { path, origin: origin ?? 'missing' });
+            if (origin !== undefined && this.#originAllowed(origin)) {
+                this.sessions.noteClosure(wrongPathReason(path, origin), this.#clock());
+            }
+        });
         this.#wss.on('connection', (socket) => {
             this.#onConnection(socket);
         });
@@ -483,6 +476,22 @@ export class Bridge {
                         log('hello_invalid', { ...refused });
                         this.sessions.noteClosure(WS_CLOSE_REASON.INVALID_HELLO, this.#clock(), refused);
                     }
+                    // On a LIVE session a frame that fails the schema is dropped, not answered with a close.
+                    // The SDK reads every 1008 as permanent and stops reconnecting, so one event kind from a
+                    // newer SDK ended the session for good, mid-drive, until a manual reload (#1413). What was
+                    // thrown away is evidence, so it is recorded as a transport gap in this window: a verdict
+                    // over it is downgraded rather than graded over an event nobody read. Only before hello is
+                    // a bad frame still a terminal refusal.
+                    if (undefined !== session) {
+                        log('invalid_frame_dropped', { sessionId: session.id, ...peekFrameKind(text) });
+                        session.pushEvent({
+                            t: session.elapsed(),
+                            type: EventType.TRANSPORT_OVERFLOW,
+                            sessionId: session.id,
+                            data: { dropped: 1 },
+                        });
+                        return;
+                    }
                     socket.close(...WS_CLOSE.INVALID_MESSAGE);
                     return;
                 }
@@ -664,6 +673,16 @@ export class Bridge {
                         session.versionSkew = skew;
                         noteVersionSkew(SkewPair.SDK, skew);
                     }
+                    else {
+                        // Wire-compatible but a minor or more behind: the agent hears it on its next tool call
+                        // and the person on the overlay. Not `versionSkew`, which marks the pair as broken.
+                        const behind = describeSdkBehind(parsed.sdkVersion, SERVER_VERSION, fixForThisProject);
+                        if (behind !== undefined && parsed.sdkVersion !== undefined) {
+                            log('sdk_behind', { sessionId: session.id, sdk: parsed.sdkVersion });
+                            noteVersionSkew(SkewPair.SDK_BEHIND, behind);
+                            session.pushNarration(SDK_BEHIND_NARRATION(parsed.sdkVersion, SERVER_VERSION), false);
+                        }
+                    }
                     log('session_connected', { sessionId: session.id, url: session.url });
                     // The one fact that separates a broken install from an unused one. Best-effort and wrapped:
                     // a metric must never affect whether an app can connect. See SessionSummary.appConnects.
@@ -708,7 +727,7 @@ export class Bridge {
                         this.#onHarnessRequest?.(harness, session);
                     // Signing in writes `~/.reticle`, which only the daemon may do; the panel only asks.
                     else if (isSigninRequest(parsed.event))
-                        this.#onSigninRequest?.();
+                        this.#onSigninRequest?.(session);
                     // Pass the raw frame's byte length so the buffer doesn't re-serialize every event for accounting.
                     else
                         session.pushEvent(parsed.event, Buffer.byteLength(text, 'utf8'));
@@ -845,13 +864,16 @@ export class Bridge {
         this.#onSyncRequest = handler;
     }
     /**
-     * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
-     * bridge built without one ignores the request rather than refusing it.
+     * Register a handler for the panel's Harness controls (switch, Run, Stop). Optional for the same
+     * reason as the above: a bridge built without one ignores the request rather than refusing it.
      */
     attachHarnessRequest(handler) {
         this.#onHarnessRequest = handler;
     }
-    /** Register a handler for the panel's Sign in. Optional, like the above: without one it is ignored. */
+    /**
+     * Register a handler for the panel's Sign in, told which tab asked (its project is linked once the
+     * sign-in lands). Optional, like the above: without one it is ignored.
+     */
     attachSigninRequest(handler) {
         this.#onSigninRequest = handler;
     }
@@ -869,3 +891,24 @@ export class Bridge {
         });
     }
 }
+/**
+ * The `kind` and event `type` of a frame that failed the schema, for the log: never its payload,
+ * which can carry anything the page sent. Each is a bounded string or absent.
+ */
+function peekFrameKind(text) {
+    const short = (v) => 'string' === typeof v ? v.slice(0, MAX_LOGGED_FRAME_FIELD) : undefined;
+    try {
+        const json = JSON.parse(text);
+        const kind = short(json?.kind);
+        const eventType = short(json?.event?.type);
+        return {
+            ...(kind === undefined ? {} : { kind }),
+            ...(eventType === undefined ? {} : { eventType }),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** How much of a frame's `kind` or event `type` the drop log keeps. */
+const MAX_LOGGED_FRAME_FIELD = 64;

package/dist/portal/bridge/harness-request.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What the panel's Harness controls asked for, narrowed at the boundary: the autonomous switch,
+ * Run Harness (with an optional persona), or Stop. Keyed by the control's own wire kind.
+ *
+ * The switch carries `on`/`off` rather than meaning "toggle": a double-click on a flaky connection
+ * sends two, and two toggles land back where they started while two `on`s are the same as one.
+ */
+import { HumanControlKind } from '@reticlehq/core';
+export type HarnessRequest = {
+    kind: typeof HumanControlKind.HARNESS;
+    enabled: boolean;
+} | {
+    kind: typeof HumanControlKind.HARNESS_RUN;
+    persona?: string;
+} | {
+    kind: typeof HumanControlKind.HARNESS_STOP;
+} | {
+    kind: typeof HumanControlKind.HARNESS_LINK;
+};
+export declare function harnessRequest(event: {
+    type: string;
+    data: Record<string, unknown>;
+}): HarnessRequest | undefined;

package/dist/portal/bridge/harness-request.js

@@ -0,0 +1,27 @@
+/**
+ * What the panel's Harness controls asked for, narrowed at the boundary: the autonomous switch,
+ * Run Harness (with an optional persona), or Stop. Keyed by the control's own wire kind.
+ *
+ * The switch carries `on`/`off` rather than meaning "toggle": a double-click on a flaky connection
+ * sends two, and two toggles land back where they started while two `on`s are the same as one.
+ */
+import { EventType, HumanControlKind } from '@reticlehq/core';
+export function harnessRequest(event) {
+    if (event.type !== EventType.HUMAN_CONTROL)
+        return undefined;
+    const kind = event.data['kind'];
+    const text = event.data['text'];
+    if (HumanControlKind.HARNESS_STOP === kind || HumanControlKind.HARNESS_LINK === kind)
+        return { kind };
+    if (HumanControlKind.HARNESS_RUN === kind) {
+        const persona = 'string' === typeof text ? text.trim() : '';
+        return 0 < persona.length ? { kind, persona } : { kind };
+    }
+    if (HumanControlKind.HARNESS !== kind)
+        return undefined;
+    if ('on' === text)
+        return { kind, enabled: true };
+    if ('off' === text)
+        return { kind, enabled: false };
+    return undefined;
+}

package/dist/portal/bridge/wrong-path.d.ts

@@ -0,0 +1,17 @@
+import type { WebSocketServer } from 'ws';
+/** The path an upgrade asked for: the pathname only, because a query can carry a pairing token. */
+export declare function requestedPath(url: string | undefined): string;
+/**
+ * What the no-session diagnosis says about it. The path is in it because the path is the fix. It
+ * says only what the record shows: a wrong-path upgrade is answered before any origin check, so
+ * the client could be anything, and a sentence promising the app is running would send the agent
+ * away from a dev server that really is stopped. The bridge records one only from an Origin its
+ * handshake would have accepted.
+ */
+export declare function wrongPathReason(path: string, origin: string): string;
+/**
+ * Report each upgrade `ws` turns away for its path. Wraps `shouldHandle`, which `ws` documents as
+ * the method to override and calls for every upgrade before it answers 400, so the decision itself
+ * is left to `ws` and only observed here.
+ */
+export declare function noteWrongPathUpgrades(wss: WebSocketServer, note: (path: string, origin: string | undefined) => void): void;

package/dist/portal/bridge/wrong-path.js

@@ -0,0 +1,35 @@
+import { RETICLE_WS_PATH } from '@reticlehq/core';
+/** Long enough for any real path, short enough that a junk request cannot fill the log line. */
+const MAX_PATH_SHOWN = 80;
+/** The path an upgrade asked for: the pathname only, because a query can carry a pairing token. */
+export function requestedPath(url) {
+    const path = (url ?? '').split('?', 1)[0] ?? '';
+    const shown = 0 === path.length ? '/' : path;
+    return shown.length > MAX_PATH_SHOWN ? `${shown.slice(0, MAX_PATH_SHOWN)}…` : shown;
+}
+/**
+ * What the no-session diagnosis says about it. The path is in it because the path is the fix. It
+ * says only what the record shows: a wrong-path upgrade is answered before any origin check, so
+ * the client could be anything, and a sentence promising the app is running would send the agent
+ * away from a dev server that really is stopped. The bridge records one only from an Origin its
+ * handshake would have accepted.
+ */
+export function wrongPathReason(path, origin) {
+    return (`a WebSocket upgrade from ${origin} asked for ${path} and got a 400: the bridge listens on ` +
+        `${RETICLE_WS_PATH} only. If that was your app, point the URL given to connect({ url }) at ` +
+        `the bridge path, for example ws://localhost:<port>${RETICLE_WS_PATH}.`);
+}
+/**
+ * Report each upgrade `ws` turns away for its path. Wraps `shouldHandle`, which `ws` documents as
+ * the method to override and calls for every upgrade before it answers 400, so the decision itself
+ * is left to `ws` and only observed here.
+ */
+export function noteWrongPathUpgrades(wss, note) {
+    const handles = wss.shouldHandle.bind(wss);
+    wss.shouldHandle = (req) => {
+        const handled = handles(req);
+        if (false === handled)
+            note(requestedPath(req.url), req.headers.origin);
+        return handled;
+    };
+}

package/dist/portal/input/network-mock-tools.js

@@ -70,6 +70,15 @@ export function toRules(value) {
         return rule;
     });
 }
+/**
+ * The applied result, after telling the recorder. Steps driven while a mock is active are marked
+ * on the ambient tape, so a journey proved against mocked responses is not auto-saved as a flow
+ * that would replay against the real backend (#1459).
+ */
+function mocksApplied(deps, sessionId, count) {
+    deps.recordings.markMocked(sessionId, 0 < count);
+    return { applied: true, count };
+}
 export const NETWORK_MOCK_TOOLS = [
     {
         name: ReticleTool.NETWORK_MOCK,
@@ -104,14 +113,14 @@ export const NETWORK_MOCK_TOOLS = [
             if (provider !== undefined) {
                 const applied = await provider.setMocks(session.url, rules);
                 if (applied)
-                    return { applied: true, count: rules.length };
+                    return mocksApplied(deps, session.id, rules.length);
             }
             // A lease is a Playwright-owned page — CDP intercept was always there, this tool just had no
             // route to it. Tried after the driven provider: when both exist, drive is the page the caller
             // means, and a lease is the fallback rather than a competitor.
             const leased = await deps.pool?.setMocksLease(session.id, rules);
             if (true === leased)
-                return { applied: true, count: rules.length };
+                return mocksApplied(deps, session.id, rules.length);
             return {
                 applied: false,
                 count: 0,

package/dist/portal/input/real-input.d.ts

@@ -87,6 +87,8 @@ export interface ScreenshotOpts {
      * baseline tweaks (hiding the HUD, stopping animations) would make their window flicker each second.
      */
     jpegQuality?: number;
+    /** One image pixel per CSS pixel, so a high-density display does not double a step screenshot. */
+    cssScale?: boolean;
 }
 /** The capability surface reticle_act depends on. A FAKE implementing this is injected in tests. */
 export interface RealInputProvider {

package/dist/portal/input/real-input.js

@@ -12,7 +12,7 @@
 import { takeJsCoverage } from './js-coverage.js';
 import { stampedDriveUrl } from './drive-url-stamp.js';
 import { launchChromium } from '../../launch-chromium.js';
-import { HIDE_RETICLE_CHROME_CSS, chromiumLaunchHint, gotoOptions, } from '../pool/playwright-launcher.js';
+import { chromiumLaunchHint, gotoOptions, SCREENSHOT_DETERMINISM, captureWithChromeHidden, } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
@@ -273,21 +273,24 @@ now = Date.now) {
     }
     return real(false);
 }
-/**
- * Reticle paints its own dev overlay (presenter HUD + border glow) into the page. That chrome is
- * time-varying — 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. Hide it during capture
- * (Playwright applies this stylesheet only for the shot, then reverts) so visual baselines reflect
- * the app, not Reticle. Disabling animations settles any remaining transitions for determinism.
- */
-const SCREENSHOT_DETERMINISM = { style: HIDE_RETICLE_CHROME_CSS, animations: 'disabled' };
 /**
  * Capture a PNG from a Playwright page. Shared by the CDP + launched providers so the
  * screenshot path lives in one place (mirrors performGesture). Returns the raw PNG bytes.
  */
 export async function capturePage(page, opts) {
+    // A step capture injects nothing into the page, so Reticle's own hosts are hidden another way.
+    if (true === opts.cssScale) {
+        return captureWithChromeHidden({ evaluate: (script) => page.evaluate(script) }, () => shoot(page, opts));
+    }
+    return shoot(page, opts);
+}
+async function shoot(page, opts) {
     const buf = await page.screenshot(opts.jpegQuality !== undefined
-        ? { type: 'jpeg', quality: opts.jpegQuality }
+        ? {
+            type: 'jpeg',
+            quality: opts.jpegQuality,
+            ...(true === opts.cssScale ? { scale: 'css' } : {}),
+        }
         : opts.clip !== undefined
             ? { ...SCREENSHOT_DETERMINISM, clip: opts.clip }
             : true === opts.fullPage

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

@@ -100,6 +100,12 @@ export declare class BrowserPool {
      * that would have read a computed value.
      */
     alias(registeredId: string, leaseId: string): void;
+    /**
+     * 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: string, owner: string | undefined): boolean;
     /** Mark a lease as still in use (called on agent activity) so the reaper doesn't reclaim it. */
     touch(sessionId: string): void;
     /**
@@ -117,6 +123,14 @@ export declare class BrowserPool {
      * reaper take it out from under a diff.
      */
     screenshotLease(sessionId: string, opts?: ScreenshotOptions): Promise<Uint8Array | undefined>;
+    /** The URL a lease was opened on — the one that carries its Reticle identity. */
+    leaseUrl(sessionId: string): string | undefined;
+    /**
+     * 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.
+     */
+    gotoLease(sessionId: string, url: string, timeoutMs?: number): Promise<boolean>;
     /**
      * 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
@@ -144,6 +158,28 @@ export declare class BrowserPool {
         height: number;
     }): Promise<boolean>;
     setMocksLease(sessionId: string, rules: readonly PooledMockRule[]): Promise<boolean>;
+    /** What a lease was granted when it opened, or undefined for a session that is not a lease. */
+    permissionsOf(sessionId: string): readonly string[] | undefined;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): string | undefined;
+    /**
+     * 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.
+     */
+    notificationPermission(sessionId: string): Promise<string | undefined>;
     sweepExpired(): Promise<string[]>;
     /**
      * How many leases this pool has reclaimed for going stale.
@@ -178,6 +214,16 @@ export declare class BrowserPool {
         owner?: string;
         /** In a browser with a window the person can watch. */
         headed?: boolean;
+        /**
+         * JavaScript installed before any page script runs, for this lease only. A view built for a
+         * desktop shell calls bindings the shell injects (`window.go`, `window.runtime`, a preload
+         * object) on mount; a stub here is what lets it reach its data path in a leased tab.
+         */
+        initScript?: string;
+        /** Granted on the lease's origin before the first navigation, so the first render sees them. */
+        permissions?: readonly string[];
+        /** Accept a self-signed or local-CA dev certificate for this lease's context only (#1255). */
+        ignoreHTTPSErrors?: boolean;
     }): Promise<Lease>;
     /**
      * The websocket address this lease's page reported it could not reach, if it reported one.
@@ -192,6 +238,8 @@ export declare class BrowserPool {
     lastDialogMessage(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
+    /** Whether this lease's context skips certificate checks. A context cannot change it later. */
+    ignoresHTTPSErrors(sessionId: string): boolean;
     /** Whether this lease lives in the headed browser. */
     isHeaded(sessionId: string): boolean;
 }