@reticlehq/server 3.6.0 → 3.7.0

package/dist/surface/tools/lease-permissions.js

@@ -0,0 +1,73 @@
+/**
+ * The `permissions` argument of `reticle_lease { action: "acquire" }` (#1370).
+ *
+ * Granted before the first navigation of a fresh lease. On an origin that already has a live lease,
+ * acquire hands back THAT lease rather than opening a second tab, and it may be another agent's tab
+ * mid-flow — nothing at this layer knows whose it is. So its grants never change there: the same list
+ * is a plain reuse, a different one is refused with the way out (release, then acquire again).
+ */
+import { z } from 'zod';
+import { ReticleTool } from '@reticlehq/core';
+import { LeasePermissionError, NOTIFICATIONS_PERMISSION, } from '../../portal/pool/context-permissions.js';
+export const LEASE_PERMISSIONS_ARG = z
+    .array(z.string().min(1))
+    .optional()
+    .describe('Browser permissions to grant on the app origin before the first navigation, e.g. ["geolocation", "clipboard-read"]. A fresh lease starts with none granted. An origin that already has a lease keeps its grants: a different list there is refused, so release it and acquire again to change them. Names are Playwright\'s, and one it does not know is refused.');
+/** The family member these refusals come from, named the way `open-note.ts` names it. */
+const LeaseAction = { ACQUIRE: 'acquire' };
+/** How this tool's refusals name the call: built from `ReticleTool.LEASE`, not spelled out. */
+const ACQUIRE = `${ReticleTool.LEASE}{action:"${LeaseAction.ACQUIRE}"}`;
+const INVALID_PERMISSIONS = `${ACQUIRE} permissions must be a list of permission names, e.g. ["geolocation"]`;
+/** The one `Notification.permission` value that means the page can see a notifications grant. */
+const GRANTED = 'granted';
+/** The validated list, undefined when the caller passed none, or a refusal naming the right shape. */
+export function parseLeasePermissions(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = LEASE_PERMISSIONS_ARG.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(INVALID_PERMISSIONS);
+    return parsed.data;
+}
+/** A permission failure, reworded for the agent; undefined for every other error. */
+export function permissionRefusal(err) {
+    return err instanceof LeasePermissionError ? new Error(`${ACQUIRE} ${err.message}`) : undefined;
+}
+/**
+ * What to tell the agent when the page cannot see a notifications grant, else undefined.
+ *
+ * Undefined too when the page could not be asked: the grant was made, and a reading nobody took is
+ * not evidence that it failed.
+ */
+export async function notificationReadBack(pool, sessionId, permissions) {
+    if (true !== permissions?.includes(NOTIFICATIONS_PERMISSION))
+        return undefined;
+    const reading = await pool.notificationPermission(sessionId);
+    if (reading === undefined || GRANTED === reading)
+        return undefined;
+    return (`notifications was granted, but this page's Notification.permission still reads "${reading}": ` +
+        'the pooled headless browser does not support notifications, so UI gated on ' +
+        'Notification.permission will not see the grant. navigator.permissions.query({ name: "notifications" }) does report it.');
+}
+const sameSet = (a, b) => a.length === b.length &&
+    a.every((name) => b.includes(name)) &&
+    b.every((name) => a.includes(name));
+/**
+ * Refuse to reuse a held lease under a different set of grants. Nothing to refuse when the caller
+ * named no list, or the same one in any order.
+ */
+export function refuseRegrant(pool, sessionId, permissions) {
+    if (permissions === undefined)
+        return;
+    const held = pool.permissionsOf(sessionId);
+    if (held === undefined || sameSet(permissions, held))
+        return;
+    throw new Error(`${ACQUIRE} this origin's lease ${sessionId} already holds [${held.join(', ')}], and it may be ` +
+        "another agent's live tab, so its grants are not changed in place. If it is yours, release it " +
+        'and acquire again with the new list.');
+}
+/** `{ hint }` joining whichever parts are present, or nothing at all. */
+export function hintOf(...parts) {
+    const present = parts.filter((part) => part !== undefined);
+    return 0 === present.length ? {} : { hint: present.join(' ') };
+}

package/dist/surface/tools/lease-readiness.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Is a leased tab usable right now? The checks `reticle_lease` runs before it may say `ready: true`.
+ * Presence in the sessions map is not enough: the tab has to answer, and it has to be visible.
+ */
+/** The narrow slice of a session the probe needs. Anything that quacks like this works. */
+interface ProbeableSession {
+    command?: (name: string, args: Record<string, unknown>, timeoutMs: number) => Promise<unknown>;
+}
+/**
+ * Did the SDK report its tab hidden? A hidden tab answers commands while its timers and rAF are
+ * throttled, so a lease on it is `ready` by every other test and verifies nothing (#1351).
+ *
+ * Known gap: this reads the last PAGE_HEALTH, which lands just after HELLO — a check in that gap sees the
+ * default `false`. The pool foregrounding the page is what covers the gap; this catches the rest.
+ */
+export declare function tabHidden(session: unknown): boolean;
+/**
+ * Does this tab still answer?
+ *
+ * PRESENCE IS NOT LIVENESS. The sessions map still holds a tab that is attached, streaming events,
+ * and answering nothing, so `ready` read off a row in that map hands back a lease that `snapshot`,
+ * `state` and `console` then reject (#692). It has to mean the tab replied.
+ *
+ * ANY reply counts, including one that reports the command failed. The question is whether the SDK
+ * answers at all, not what it says — so an SDK too old to know the command replies
+ * `unknown command '…'`, and that is proof. Only the absence of a reply is evidence of absence:
+ * `PendingCommands.track` REJECTS on timeout and on a dropped socket, and resolves on every real
+ * answer, so the two cases are already separated for us.
+ *
+ * `CAPABILITIES` is the probe because it takes no arguments and returns a small fixed list. No new
+ * wire command is introduced: this rides an existing round trip.
+ *
+ * Fails OPEN. A registry entry with no `command` is a shape this code did not put there, and
+ * turning a lease that works into a refusal over a probe that could not run would be a worse
+ * failure than the one being fixed.
+ */
+export declare function probeLeaseAlive(session: ProbeableSession | undefined, timeoutMs?: number): Promise<boolean>;
+export {};

package/dist/surface/tools/lease-readiness.js

@@ -0,0 +1,57 @@
+/**
+ * Is a leased tab usable right now? The checks `reticle_lease` runs before it may say `ready: true`.
+ * Presence in the sessions map is not enough: the tab has to answer, and it has to be visible.
+ */
+import { ReticleCommand } from '@reticlehq/core';
+/**
+ * How long a liveness probe waits for the tab to say anything at all.
+ *
+ * Short on purpose. This is not "finish the work", it is "are you there" — a page executing
+ * JavaScript answers a no-argument command in single-digit milliseconds, and a wedged one is not
+ * going to answer in two seconds either.
+ */
+const LEASE_PROBE_TIMEOUT_MS = 1_500;
+/**
+ * Did the SDK report its tab hidden? A hidden tab answers commands while its timers and rAF are
+ * throttled, so a lease on it is `ready` by every other test and verifies nothing (#1351).
+ *
+ * Known gap: this reads the last PAGE_HEALTH, which lands just after HELLO — a check in that gap sees the
+ * default `false`. The pool foregrounding the page is what covers the gap; this catches the rest.
+ */
+export function tabHidden(session) {
+    return (null !== session &&
+        'object' === typeof session &&
+        true === session.info?.().hidden);
+}
+/**
+ * Does this tab still answer?
+ *
+ * PRESENCE IS NOT LIVENESS. The sessions map still holds a tab that is attached, streaming events,
+ * and answering nothing, so `ready` read off a row in that map hands back a lease that `snapshot`,
+ * `state` and `console` then reject (#692). It has to mean the tab replied.
+ *
+ * ANY reply counts, including one that reports the command failed. The question is whether the SDK
+ * answers at all, not what it says — so an SDK too old to know the command replies
+ * `unknown command '…'`, and that is proof. Only the absence of a reply is evidence of absence:
+ * `PendingCommands.track` REJECTS on timeout and on a dropped socket, and resolves on every real
+ * answer, so the two cases are already separated for us.
+ *
+ * `CAPABILITIES` is the probe because it takes no arguments and returns a small fixed list. No new
+ * wire command is introduced: this rides an existing round trip.
+ *
+ * Fails OPEN. A registry entry with no `command` is a shape this code did not put there, and
+ * turning a lease that works into a refusal over a probe that could not run would be a worse
+ * failure than the one being fixed.
+ */
+export async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_MS) {
+    const send = session?.command;
+    if (send === undefined)
+        return true;
+    try {
+        await send.call(session, ReticleCommand.CAPABILITIES, {}, timeoutMs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/surface/tools/lease-seed.d.ts

@@ -15,7 +15,27 @@ export declare function looksLikeStorageStateExport(seed: unknown): boolean;
  * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
  * of an internals-leaking wall of text.
  */
+/** What {@link cleanNavError} answers for a navigation that ran out of time. */
+export declare const NAV_TIMED_OUT = "navigation timed out";
 export declare function cleanNavError(err: unknown, seed?: SeedStorage): string;
+/** What a lease whose navigation hit a certificate error tells the caller. */
+export declare const NAV_CERT_REFUSED: string;
+/** The question a failed lease navigation asks, when nothing says the app is up. */
+export declare const NAV_FAILED_QUESTION = "is the app running there?";
+/** What a lease navigation that ran out of time tells the caller to do. */
+export declare const NAV_TIMEOUT_ADVICE: string;
+/**
+ * The sentence for a lease whose first navigation failed.
+ *
+ * A timeout and a refusal are different stories and get different sentences. A refusal
+ * (`net::ERR_CONNECTION_REFUSED` and the like) means nothing is serving there, so asking whether the
+ * app is running is the right question. A timeout proves less — only that the page was not ready in
+ * time — and its most common cause is a dev server compiling a route for the first time, which
+ * routinely outlasts the navigation budget. Asking "is the app running?" there sends the agent
+ * hunting for a dev server that is up instead of retrying, so the timeout sentence names both
+ * cases and leads with the retry.
+ */
+export declare function navFailureMessage(url: string, err: unknown, seed?: SeedStorage): string;
 /**
  * Determine if a required seedStorage application precondition failed.
  *

package/dist/surface/tools/lease-seed.js

@@ -65,6 +65,8 @@ export function looksLikeStorageStateExport(seed) {
  * with ANSI codes) into a short, clean reason — so the agent/user sees "is the app running?" instead
  * of an internals-leaking wall of text.
  */
+/** What {@link cleanNavError} answers for a navigation that ran out of time. */
+export const NAV_TIMED_OUT = 'navigation timed out';
 export function cleanNavError(err, seed) {
     const rawMsg = err instanceof Error ? err.message : String(err);
     const msg = scrubSeedFromError(rawMsg, seed);
@@ -76,13 +78,55 @@ export function cleanNavError(err, seed) {
     if (netCode !== null)
         return netCode[0];
     if (/timeout/i.test(firstLine))
-        return 'navigation timed out';
+        return NAV_TIMED_OUT;
     return firstLine
         .replace(/^page\.goto:\s*/, '')
         .replace(/\s+at\s+https?:\/\/\S+.*$/, '')
         .trim()
         .slice(0, 100);
 }
+/** Chromium's certificate failures: `net::ERR_CERT_AUTHORITY_INVALID`, `ERR_CERT_DATE_INVALID`, … */
+const CERT_ERROR = /^net::ERR_CERT_/;
+/** What a lease whose navigation hit a certificate error tells the caller. */
+export const NAV_CERT_REFUSED = 'the browser refused its TLS certificate, which a self-signed or mkcert dev certificate gets. ' +
+    'If it is your dev server, acquire again with ignoreHTTPSErrors: true to accept it for this lease';
+/** The question a failed lease navigation asks, when nothing says the app is up. */
+export const NAV_FAILED_QUESTION = 'is the app running there?';
+/** What a lease navigation that ran out of time tells the caller to do. */
+export const NAV_TIMEOUT_ADVICE = 'If the app is running, a dev server compiling a route for the first time can take longer than ' +
+    'that: retry the acquire. If it is not running, start it first.';
+/** Lead of the timeout sentence, before the budget ("within 30 s", or "in time" when unknown). */
+const NAV_TIMEOUT_LEAD = 'the page did not finish loading';
+const NAV_TIMEOUT_UNKNOWN_BUDGET = 'in time';
+/** Playwright's own wording for a navigation that ran out of time, with the budget it used. */
+const PLAYWRIGHT_TIMEOUT = /Timeout (\d+)ms exceeded/;
+/**
+ * The sentence for a lease whose first navigation failed.
+ *
+ * A timeout and a refusal are different stories and get different sentences. A refusal
+ * (`net::ERR_CONNECTION_REFUSED` and the like) means nothing is serving there, so asking whether the
+ * app is running is the right question. A timeout proves less — only that the page was not ready in
+ * time — and its most common cause is a dev server compiling a route for the first time, which
+ * routinely outlasts the navigation budget. Asking "is the app running?" there sends the agent
+ * hunting for a dev server that is up instead of retrying, so the timeout sentence names both
+ * cases and leads with the retry.
+ */
+export function navFailureMessage(url, err, seed) {
+    const reason = cleanNavError(err, seed);
+    // A certificate the browser refused is not an app that is down: the server answered, with a cert
+    // no CA here vouches for (a self-signed or mkcert dev certificate). Asking "is the app running?"
+    // sent the caller to restart a dev server that was fine (#1255).
+    if (CERT_ERROR.test(reason))
+        return `could not open ${url} — ${NAV_CERT_REFUSED} (${reason})`;
+    if (NAV_TIMED_OUT !== reason)
+        return `could not open ${url} — ${NAV_FAILED_QUESTION} (${reason})`;
+    const rawMsg = err instanceof Error ? err.message : String(err);
+    const budgetMs = PLAYWRIGHT_TIMEOUT.exec(rawMsg)?.[1];
+    const within = budgetMs === undefined
+        ? NAV_TIMEOUT_UNKNOWN_BUDGET
+        : `within ${String(Number(budgetMs) / 1000)} s`;
+    return `could not open ${url} — ${NAV_TIMEOUT_LEAD} ${within} (${reason}). ${NAV_TIMEOUT_ADVICE}`;
+}
 /**
  * Determine if a required seedStorage application precondition failed.
  *

package/dist/surface/tools/lease-tools.d.ts

@@ -15,7 +15,8 @@ import { type NetworkMutationPort } from '../../portal/input/network-mutation.js
 import type { Perturbation } from '@reticlehq/core';
 import { type SeedStorage } from '@reticlehq/core';
 import { HudVisibility } from '@reticlehq/core';
-import type { ToolDef } from './tool-kit.js';
+import { type ToolDef, type ToolDeps } from './tool-kit.js';
+import type { BrowserPool } from '../../portal/pool/browser-pool.js';
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
  * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
@@ -112,6 +113,14 @@ export declare function connectOrInject(lease: {
 }>;
 export declare function hasOriginLock(origin: string): boolean;
 export declare const LEASE_ACQUIRE_TOOL: ToolDef;
+/**
+ * Release one lease and everything that hangs off it. Returns how many leases are still held.
+ *
+ * Shared with `reticle_session { action: "end" }`: an ended session that kept its lease stayed
+ * connected until the reaper took it, and every id-less call from the next agent was refused as
+ * ambiguous in the meantime.
+ */
+export declare function releaseLease(deps: ToolDeps, pool: BrowserPool, sessionId: string): Promise<number>;
 export declare const LEASE_TOOLS: ToolDef[];
 /**
  * The state a suite should boot its flows from: whatever the agent is already sitting in.

package/dist/surface/tools/lease-tools.js

@@ -13,6 +13,7 @@ import { fixturePortFor, seedFromStorageState, } from '../../portal/input/storag
 import { mutationPortFor } from '../../portal/input/network-mutation.js';
 import { z } from 'zod';
 import { leaseNotConnectedHint } from './lease-hint.js';
+import { probeLeaseAlive, tabHidden } from './lease-readiness.js';
 import { probeSdkMarker } from './gaps/sdk-marker-probe.js';
 import { observeWebDocument } from '../../portal/session/dev-server/served-document.js';
 import { diagnoseObservedWebCsp } from '@reticlehq/init';
@@ -20,10 +21,13 @@ import { readProjectFramework, readProjectId } from '../../command/cli/ports/res
 import { hasAnyAppConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { AGENT_DRIVING_ELSEWHERE, AGENT_DRIVING_HERE_AGAIN, watchersToNotify, } from '../../portal/session/lease-visibility.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
-import { LeaseNotReadyReason, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, ReticleCommand, SeedStorageSchema, } from '@reticlehq/core';
+import { claimArtifactRoot, dropArtifactRootClaim } from '../../memory/project/root-claims.js';
+import { LeaseNotReadyReason, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, SeedStorageSchema, } from '@reticlehq/core';
 import { HudVisibility, ReticleTool, SESSION_HEALTH } from '@reticlehq/core';
+import { HOST_STUB_NOTE } from './tool-kit.js';
 import { asString } from '@reticlehq/core';
 import { chromiumPreflightRefusal } from '../../command/cli/doctor/browser/chromium-hint.js';
+import { LEASE_PERMISSIONS_ARG, hintOf, notificationReadBack, parseLeasePermissions, permissionRefusal, refuseRegrant, } from './lease-permissions.js';
 /**
  * Everything the daemon already knows about why a leased tab might not have dialled in.
  *
@@ -89,7 +93,9 @@ function originOf(url) {
 const ALREADY_HELD_LEASE = 'you already hold a lease on this origin';
 function alreadyHeldHint(sessionId, origin) {
     return (`${ALREADY_HELD_LEASE} (${origin}): ${sessionId} — reused it rather than opening a second ` +
-        'tab, which would make every later call require sessionId. Release first if you want a fresh one.');
+        'tab, which would make every later call require sessionId. It is still signed in as whoever ' +
+        'used it last (cookies and storage come with it): release it first for a fresh context or ' +
+        'another identity.');
 }
 /**
  * Append Reticle identity params (__reticle_session, optional __reticle_project) to a URL so the app's own SDK
@@ -115,7 +121,7 @@ export function appendReticleParams(url, session, projectId, hud) {
     }
 }
 export { cleanNavError, evaluateSeedPrecondition, scrubSeedFromError } from './lease-seed.js';
-import { cleanNavError, evaluateSeedPrecondition, looksLikeStorageStateExport, scrubSeedFromError, } from './lease-seed.js';
+import { evaluateSeedPrecondition, looksLikeStorageStateExport, navFailureMessage, scrubSeedFromError, } from './lease-seed.js';
 /** A fresh, collision-resistant lease id. Uses crypto at the I/O boundary (not pure logic). */
 function newLeaseId() {
     const uuid = 'function' === typeof globalThis.crypto?.randomUUID
@@ -186,46 +192,6 @@ function sessionParamOf(url) {
 }
 const LEASE_READY_ATTEMPTS = 100;
 const LEASE_READY_POLL_MS = 100;
-/**
- * How long a liveness probe waits for the tab to say anything at all.
- *
- * Short on purpose. This is not "finish the work", it is "are you there" — a page executing
- * JavaScript answers a no-argument command in single-digit milliseconds, and a wedged one is not
- * going to answer in two seconds either.
- */
-const LEASE_PROBE_TIMEOUT_MS = 1_500;
-/**
- * Does this tab still answer?
- *
- * PRESENCE IS NOT LIVENESS. The sessions map still holds a tab that is attached, streaming events,
- * and answering nothing, so `ready` read off a row in that map hands back a lease that `snapshot`,
- * `state` and `console` then reject (#692). It has to mean the tab replied.
- *
- * ANY reply counts, including one that reports the command failed. The question is whether the SDK
- * answers at all, not what it says — so an SDK too old to know the command replies
- * `unknown command '…'`, and that is proof. Only the absence of a reply is evidence of absence:
- * `PendingCommands.track` REJECTS on timeout and on a dropped socket, and resolves on every real
- * answer, so the two cases are already separated for us.
- *
- * `CAPABILITIES` is the probe because it takes no arguments and returns a small fixed list. No new
- * wire command is introduced: this rides an existing round trip.
- *
- * Fails OPEN. A registry entry with no `command` is a shape this code did not put there, and
- * turning a lease that works into a refusal over a probe that could not run would be a worse
- * failure than the one being fixed.
- */
-async function probeLeaseAlive(session, timeoutMs = LEASE_PROBE_TIMEOUT_MS) {
-    const send = session?.command;
-    if (send === undefined)
-        return true;
-    try {
-        await send.call(session, ReticleCommand.CAPABILITIES, {}, timeoutMs);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * Poll until the leased tab's SDK has actually registered on the bridge, so the sessionId we return
@@ -314,7 +280,7 @@ export function hasOriginLock(origin) {
 }
 export const LEASE_ACQUIRE_TOOL = {
     name: ReticleTool.LEASE_ACQUIRE,
-    description: 'Lease a fresh isolated headless browser context from the shared pool and navigate it to the app URL (the app must already be running; one with no Reticle SDK gets one supplied, reported as zeroInstall). If this origin is already leased and still connected, this returns THAT session rather than minting a second tab — a second acquire on the same origin poisons default session resolution. Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done. PREFER AN ALREADY-OPEN TAB: if reticle_sessions lists a non-leased session for this app, drive THAT instead — a lease is invisible to the person watching the app, whose HUD lives in their own tab, and a tab flagged hidden/throttled is often still driveable. Lease for isolation you actually need (a second identity, a clean context, parallel flows) or when driving the open tab has failed — this call answers with `preferExisting` when a live tab was available.',
+    description: 'Lease a fresh isolated browser context from the shared pool (shown or hidden as the daemon was started; `headed: true` forces a window) and navigate it to the app URL (the app must already be running; one with no Reticle SDK gets one supplied, reported as zeroInstall). If this origin is already leased and still connected, this returns THAT session rather than minting a second tab — a second acquire on the same origin poisons default session resolution. Returns the sessionId the leased tab registers — pass it to other tools. The pool keeps all leases in ONE browser and caps concurrency; if at capacity this waits for a free slot. Release with reticle_lease{action:"release"} when the flow is done. PREFER AN ALREADY-OPEN TAB: if reticle_sessions lists a non-leased session for this app, drive THAT instead — a lease is invisible to the person watching the app, whose HUD lives in their own tab, and a tab flagged hidden/throttled is often still driveable. Lease for isolation you actually need (a second identity, a clean context, parallel flows) or when driving the open tab has failed — this call answers with `preferExisting` when a live tab was available.',
     inputSchema: {
         url: z
             .string()
@@ -324,29 +290,50 @@ export const LEASE_ACQUIRE_TOOL = {
             .optional()
             .describe('Stable project id to stamp on the leased tab so the agent can scope to it.'),
         seedStorage: SeedStorageSchema.optional().describe('Initial storage state (local, session and cookies) to seed before the first navigation (e.g. `seedStorage: { local: { token: "..." } }` to start already authenticated).'),
+        initScript: z
+            .string()
+            .optional()
+            .describe("JavaScript installed in the tab BEFORE any of the page's own scripts run. Use it for TEST DOUBLES of the host bindings a desktop shell injects — Wails `window.go.*`, Tauri `window.runtime`/`__TAURI_INTERNALS__`, an Electron preload object — so a view that calls them on mount is driven against the stub instead of throwing. It stays on for this lease only, and it is disposed with the lease. Every verdict on this lease carries a note that a stub was installed, so a green is never read as one against the real shell."),
         headed: z
             .boolean()
             .optional()
             .describe('Open it in a browser window somebody can watch, instead of headless.'),
+        ignoreHTTPSErrors: z
+            .boolean()
+            .optional()
+            .describe('Accept a self-signed or mkcert certificate on an https dev server, for this lease only. Off by default.'),
         hud: z
             .enum([HudVisibility.SHOWN, HudVisibility.HIDDEN, HudVisibility.REMOVED])
             .optional()
             .describe('How the HUD starts on the page: shown (default), hidden, or removed.'),
+        permissions: LEASE_PERMISSIONS_ARG,
+        root: z
+            .string()
+            .optional()
+            .describe("Absolute path of the .reticle folder this lease's runs belong in — the caller's project. Without it, the page's project id decides, and a page with none lands in ~/.reticle/unmatched, which nothing syncs."),
     },
     outputSchema: {
         sessionId: z.string(),
         url: z.string(),
         ready: z
             .boolean()
-            .describe('Whether the leased tab is connected AND answering. On a reused lease this is probed, not assumed — a row in the session map is presence, not liveness. False ⇒ read notReadyReason.'),
+            .describe('Whether the leased tab is connected AND answering. It is NOT a claim that the app has hydrated, so an act can miss: make the first act reticle_act_and_wait with an `until`, or reticle_assert { action: "wait" }. Empty reads may mean not hydrated. False ⇒ read notReadyReason.'),
         zeroInstall: z
             .boolean()
             .optional()
             .describe('Present when this app ships no Reticle SDK and the lease supplied one. Verdicts work on the DOM, network, console and routes; there is no framework adapter, so no component state and no source file:line. Install with `npx @reticlehq/server init` for those.'),
+        hostStub: z
+            .string()
+            .optional()
+            .describe('Present when this leased tab runs an init script stubbing the bindings a desktop shell injects. Verdicts on this lease are about the app with that stub, not about the real shell.'),
         notReadyReason: z
-            .enum([LeaseNotReadyReason.SDK_NEVER_DIALLED, LeaseNotReadyReason.SDK_STOPPED_ANSWERING])
+            .enum([
+            LeaseNotReadyReason.SDK_NEVER_DIALLED,
+            LeaseNotReadyReason.SDK_STOPPED_ANSWERING,
+            LeaseNotReadyReason.TAB_HIDDEN,
+        ])
             .optional()
-            .describe('Present only when ready is false. sdk_never_dialled ⇒ nothing connected within the wait, so check the install (the app may not embed @reticlehq/core). sdk_stopped_answering ⇒ an SDK did connect and has stopped replying, so the tab is wedged and needs recovering, not reinstalling.'),
+            .describe('Present only when ready is false. sdk_never_dialled ⇒ nothing connected within the wait, so check the install (the app may not embed @reticlehq/core). sdk_stopped_answering ⇒ an SDK did connect and has stopped replying, so the tab is wedged and needs recovering, not reinstalling. tab_hidden ⇒ the SDK answers but its tab is hidden, so timers and animations are throttled and nothing on it verifies; bring the tab to the front, or release and re-acquire.'),
         expiresInMs: z
             .number()
             .describe('Milliseconds until this lease expires if untouched. Each tool call that targets this session resets the clock. Plan your work to finish or re-acquire before this runs out.'),
@@ -386,8 +373,13 @@ export const LEASE_ACQUIRE_TOOL = {
                 throw new Error(refusal);
         }
         const projectId = asString(args['projectId']);
+        const root = asString(args['root']);
         const headed = true === args['headed'];
         const hud = Object.values(HudVisibility).find((v) => v === args['hud']);
+        const permissions = parseLeasePermissions(args['permissions']);
+        // The stub of the shell bindings, when the caller supplied one. Installed by the pool before
+        // the first navigation, so it is already defined when the app's first module runs.
+        const initScript = asString(args['initScript']);
         const seedStorageArg = args['seedStorage'];
         let validatedSeed;
         if (seedStorageArg !== undefined) {
@@ -423,10 +415,31 @@ export const LEASE_ACQUIRE_TOOL = {
         try {
             // Only a lease THIS caller took: another agent's tab is never reused or released (#1226).
             // A window asked for is never answered with the headless tab on that origin, nor the reverse.
+            // A held lease that already runs the SAME stub is exactly what the caller asked for, so it is
+            // left alone and reused below — releasing it would throw away the tab, and everything loaded
+            // in it, for nothing. A lease with no stub, or with a different one, is released FIRST instead:
+            // an init script has to exist before the page's own scripts run, which a loaded page cannot
+            // do, and the resolve below then finds nothing and mints a fresh context with the stub. A
+            // lease of the other kind is left alone, exactly as it is when a window was asked for.
+            const heldForStub = origin === undefined ? undefined : pool.leaseIdOnOrigin(origin, deps.attachId);
+            if (initScript !== undefined &&
+                heldForStub !== undefined &&
+                pool.isHeaded(heldForStub) === headed &&
+                pool.hostStubScript?.(heldForStub) !== initScript) {
+                await pool.release(heldForStub);
+            }
             const held = origin === undefined ? undefined : pool.leaseIdOnOrigin(origin, deps.attachId);
             const existing = held !== undefined && pool.isHeaded(held) === headed ? held : undefined;
-            if (validatedSeed !== undefined && existing !== undefined) {
-                // Seeding asked for: release its own context so the new lease starts with the given state.
+            // A context's certificate setting is fixed when it is made, so an explicit request for the
+            // other one cannot be answered by the held lease: handing it back would keep checks off after
+            // `false`, or keep a local certificate refused after `true` (#1255). Omitted keeps the lease.
+            const certAsked = args['ignoreHTTPSErrors'];
+            const certMismatch = existing !== undefined &&
+                'boolean' === typeof certAsked &&
+                pool.ignoresHTTPSErrors(existing) !== certAsked;
+            if ((validatedSeed !== undefined || certMismatch) && existing !== undefined) {
+                // Seeding or a different certificate setting asked for: release its own context so the new
+                // lease starts with what was asked.
                 await pool.release(existing);
             }
             else if (existing !== undefined && origin !== undefined) {
@@ -443,23 +456,33 @@ export const LEASE_ACQUIRE_TOOL = {
                     // A no-op when the id resolved to itself; load-bearing when it did not, because every later
                     // touch and release arrives under the id being handed back here.
                     pool.alias(resolved, existing);
+                    refuseRegrant(pool, existing, permissions);
                     pool.touch(existing);
                     // Probed only HERE, never on the mint path below. There, the readiness wait resolved
                     // moments ago and IS the liveness evidence; on reuse the last evidence may be minutes
                     // old, or there may be none at all — `unresponsive` is set by past commands failing, and
                     // its own contract says absence means "answering, OR NOT ASKED YET". So the happy path of
                     // a first acquire pays nothing for this.
-                    const alive = await probeLeaseAlive(deps.sessions.get(resolved));
+                    const reusedSession = deps.sessions.get(resolved);
+                    const alive = await probeLeaseAlive(reusedSession);
+                    const reuseReason = !alive
+                        ? LeaseNotReadyReason.SDK_STOPPED_ANSWERING
+                        : tabHidden(reusedSession)
+                            ? LeaseNotReadyReason.TAB_HIDDEN
+                            : undefined;
                     return {
                         sessionId: resolved,
                         url,
-                        ready: alive,
-                        ...(alive ? {} : { notReadyReason: LeaseNotReadyReason.SDK_STOPPED_ANSWERING }),
+                        ready: reuseReason === undefined,
+                        ...(reuseReason === undefined ? {} : { notReadyReason: reuseReason }),
                         reused: true,
                         expiresInMs: pool.leaseTtlMs(),
                         leased: pool.activeCount(),
                         queued: pool.queuedCount(),
                         hint: alreadyHeldHint(resolved, origin),
+                        // Asked of the pool, not remembered here: the stub was installed when THIS lease was
+                        // minted, and the caller reusing it now may be seeing it for the first time.
+                        ...(true === pool.stubInstalled?.(existing) ? { hostStub: HOST_STUB_NOTE } : {}),
                         ...(alreadyOpen === undefined
                             ? {}
                             : { preferExisting: { sessionId: alreadyOpen, note: PREFER_EXISTING_NOTE } }),
@@ -471,6 +494,9 @@ export const LEASE_ACQUIRE_TOOL = {
                 await pool.release(existing);
             }
             const sessionId = newLeaseId();
+            // Before the page can dial in: the session is stamped with its root the moment it registers.
+            if (root !== undefined)
+                claimArtifactRoot(sessionId, root);
             const navUrl = appendReticleParams(url, sessionId, projectId, hud);
             let lease;
             try {
@@ -479,15 +505,21 @@ export const LEASE_ACQUIRE_TOOL = {
                     ...(headed ? { headed } : {}),
                     ...(deps.attachId === undefined ? {} : { owner: deps.attachId }),
                     ...(validatedSeed !== undefined ? { seedStorage: validatedSeed } : {}),
+                    ...(initScript !== undefined ? { initScript } : {}),
+                    ...(permissions !== undefined ? { permissions } : {}),
+                    ...(true === args['ignoreHTTPSErrors'] ? { ignoreHTTPSErrors: true } : {}),
                 });
             }
             catch (err) {
+                const refusal = permissionRefusal(err);
+                if (refusal !== undefined)
+                    throw refusal;
                 if (err instanceof Error && err.message.startsWith('Storage seeding failed')) {
                     throw new Error(scrubSeedFromError(err.message, validatedSeed));
                 }
                 // A raw page.goto failure is noisy and leaks the internal URL params — surface a clean,
-                // actionable message instead.
-                throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err, validatedSeed)})`);
+                // actionable message instead, one that tells a slow first compile from a missing app.
+                throw new Error(navFailureMessage(url, err, validatedSeed));
             }
             // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
             // Resolved rather than assumed: an app that names its own session registers under that name,
@@ -515,15 +547,21 @@ export const LEASE_ACQUIRE_TOOL = {
             tellWatchers(deps, projectId, AGENT_DRIVING_ELSEWHERE);
             // ready means the SDK dialled in — not that contracts match. Carry the skew warning on acquire
             // so the agent does not learn it only after a CDP tool invents a closed page (#688).
+            const mintReason = !ready
+                ? LeaseNotReadyReason.SDK_NEVER_DIALLED
+                : tabHidden(session)
+                    ? LeaseNotReadyReason.TAB_HIDDEN
+                    : undefined;
             const versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
             return {
                 sessionId: registeredId ?? lease.sessionId,
                 url,
-                ready,
+                ready: mintReason === undefined,
                 // The other half of the pair. `ready: false` carried two opposite situations under one
                 // word: no SDK ever dialled in (look at the install) versus one dialled in and stopped
-                // answering (recover the tab). They want different next actions, so they get names.
-                ...(ready ? {} : { notReadyReason: LeaseNotReadyReason.SDK_NEVER_DIALLED }),
+                // answering (recover the tab). They want different next actions, so they get names — and so
+                // does a third: dialled in and answering, but hidden, so nothing on it verifies (#1351).
+                ...(mintReason === undefined ? {} : { notReadyReason: mintReason }),
                 ...(zeroInstall ? { zeroInstall: true } : {}),
                 expiresInMs: pool.leaseTtlMs(),
                 leased: pool.activeCount(),
@@ -537,9 +575,10 @@ export const LEASE_ACQUIRE_TOOL = {
                         },
                     }),
                 ...(versionSkew === undefined ? {} : { versionSkew }),
-                ...(ready
-                    ? {}
-                    : { hint: await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId)) }),
+                ...(initScript === undefined ? {} : { hostStub: HOST_STUB_NOTE }),
+                ...hintOf(ready
+                    ? undefined
+                    : await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId)), ready ? await notificationReadBack(pool, lease.sessionId, permissions) : undefined),
             };
         }
         finally {
@@ -579,17 +618,28 @@ const LEASE_RELEASE_TOOL = {
         if (sessionId === undefined || 0 === sessionId.length) {
             throw new Error('reticle_lease{action:"release"} requires a sessionId');
         }
-        // Read the project BEFORE releasing: afterwards the session is gone and there is nothing to
-        // ask which project it belonged to.
-        const projectId = deps.sessions.get(sessionId)?.projectId;
-        await pool.release(sessionId);
-        // Only once the LAST lease is gone. Announcing "live again" while another lease still drives
-        // would be a lie, and a HUD that says the wrong thing is worse than one that says nothing.
-        if (0 === pool.activeCount())
-            tellWatchers(deps, projectId, AGENT_DRIVING_HERE_AGAIN);
-        return { released: true, leased: pool.activeCount() };
+        return { released: true, leased: await releaseLease(deps, pool, sessionId) };
     },
 };
+/**
+ * Release one lease and everything that hangs off it. Returns how many leases are still held.
+ *
+ * Shared with `reticle_session { action: "end" }`: an ended session that kept its lease stayed
+ * connected until the reaper took it, and every id-less call from the next agent was refused as
+ * ambiguous in the meantime.
+ */
+export async function releaseLease(deps, pool, sessionId) {
+    // Read the project BEFORE releasing: afterwards the session is gone and there is nothing to
+    // ask which project it belonged to.
+    const projectId = deps.sessions.get(sessionId)?.projectId;
+    await pool.release(sessionId);
+    dropArtifactRootClaim(sessionId);
+    // Only once the LAST lease is gone. Announcing "live again" while another lease still drives
+    // would be a lie, and a HUD that says the wrong thing is worse than one that says nothing.
+    if (0 === pool.activeCount())
+        tellWatchers(deps, projectId, AGENT_DRIVING_HERE_AGAIN);
+    return pool.activeCount();
+}
 /**
  * What to say when a lease was taken while a real tab was already open.
  *