@reticlehq/server 3.8.2 → 3.10.0

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

@@ -11,8 +11,8 @@
  */
 import * as production from '../../portal/production/production-activation.js';
 import { z } from 'zod';
-import { leaseNotConnectedHint, leaseReaderFailedHint, leaseStillLoadingHint, } from './lease-hint.js';
-import { connectOrInject, moveReusedLease, notReadyReason, probeLeaseAlive, } from './lease-readiness.js';
+import { keptLeaseAnswer, notLoadedCause, leaseNotConnectedHint, leaseReaderFailedHint, leaseStillLoadingHint, } from './lease-hint.js';
+import { LEASE_READY_TIMEOUT_MS, awaitLeaseAnswering, connectOrInject, connectWaitUntil, moveReusedLease, notReadyReason, probeLeaseAlive, reconnectHeldLease, HeldLeaseReload, } 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';
@@ -21,14 +21,17 @@ import { hasAnyAppConnectedBefore } from '../../memory/recall/prior/connection-m
 import { AGENT_DRIVING_ELSEWHERE, AGENT_DRIVING_HERE_AGAIN, watchersToNotify, } from '../../portal/session/lease-visibility.js';
 import { reticleStateHome } from '../../command/daemon/daemon.js';
 import { claimArtifactRoot, dropArtifactRootClaim } from '../../memory/project/root-claims.js';
-import { LeaseNotReadyReason, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, SeedStorageSchema, originOf, } from '@reticlehq/core';
+import { LeaseNotReadyReason, RETICLE_DEFAULT_PORT, SeedStorageSchema, originOf, } from '@reticlehq/core';
 import { HudVisibility, ReticleTool, SESSION_HEALTH } from '@reticlehq/core';
 import { HOST_STUB_NOTE } from './tool-kit.js';
 import { PoolAtCapacityError } from '../../portal/pool/browser-pool.js';
-import { asString } from '@reticlehq/core';
+import { asNumber, asString } from '@reticlehq/core';
+import { timeoutMsSchema } from './args/numeric-bounds.js';
 import { chromiumPreflightRefusal } from '../../command/cli/doctor/browser/chromium-hint.js';
 import { LEASE_PERMISSIONS_ARG, hintOf, notificationReadBack, parseLeasePermissions, permissionRefusal, refuseRegrant, } from './lease-permissions.js';
 import { LEASE_EMULATE_ARG, leaseEmulationOf } from '../../portal/input/viewport-tools.js';
+import { LEASE_DETERMINISTIC_ARG, leaseDeterminismOf } from '../../portal/pool/determinism.js';
+import { LEASE_COVERAGE_TOOL, LEASE_JS_COVERAGE_ARG } from './lease-coverage-tools.js';
 export { sessionMutationPort, sessionPerturbationPort, suiteFixturePort, suiteFixtureSeed, } from './session-ports.js';
 /**
  * Everything the daemon already knows about why a leased tab might not have dialled in.
@@ -86,38 +89,17 @@ async function leaseEvidence(deps, port, url) {
 }
 const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
 const ALREADY_HELD_LEASE = 'you already hold a lease on this origin';
+const DETERMINISTIC_NOTE = 'Time stands still on this tab. Step it with reticle_clock { stepFrames: N }, then read or capture.';
 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. 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
- * adopts them on connect. Pure; falls back to plain concatenation if the URL can't be parsed.
- */
-export function appendReticleParams(url, session, projectId, hud) {
-    try {
-        const u = new URL(url);
-        u.searchParams.set(RETICLE_URL_PARAM.SESSION, session);
-        if (projectId !== undefined && projectId.length > 0) {
-            u.searchParams.set(RETICLE_URL_PARAM.PROJECT, projectId);
-        }
-        if (hud !== undefined) {
-            u.searchParams.set(RETICLE_URL_PARAM.HUD, hud);
-        }
-        return u.toString();
-    }
-    catch {
-        const sep = url.includes('?') ? '&' : '?';
-        const proj = projectId !== undefined && projectId.length > 0
-            ? `&${RETICLE_URL_PARAM.PROJECT}=${encodeURIComponent(projectId)}`
-            : '';
-        return `${url}${sep}${RETICLE_URL_PARAM.SESSION}=${encodeURIComponent(session)}${proj}`;
-    }
+        'another identity, or pass fresh: true to open a separate tab and keep this one.');
 }
+export { appendReticleParams, carryReticleIdentity, resolveLeasedSessionId, } from './lease-url-identity.js';
+import { appendReticleParams, carryReticleIdentity, resolveLeasedSessionId, } from './lease-url-identity.js';
 export { cleanNavError, evaluateSeedPrecondition, scrubSeedFromError } from './lease-seed.js';
-import { evaluateSeedPrecondition, looksLikeStorageStateExport, navFailureMessage, scrubSeedFromError, } from './lease-seed.js';
+import { evaluateSeedPrecondition, looksLikeStorageStateExport, navFailureMessage, scrubSeedFromError, serverAcceptedAfterTimeout, } 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
@@ -125,84 +107,19 @@ function newLeaseId() {
         : `${String(Date.now())}-${String(performance.now())}`;
     return `lease-${uuid}`;
 }
-/**
- * The session a lease's tab actually registered as, or undefined while nothing has.
- *
- * Normally that is the lease id: `appendReticleParams` stamps `__reticle_session` on the URL and the
- * SDK adopts it. An app that passes an explicit `session` to `connect()` keeps its own name instead,
- * which is legitimate — a single-app fixture does it deliberately so a battery can address it by a
- * known id. Matching on the lease id alone could never see those tabs, so the lease reported
- * `ready: false` and a hint blaming a port mismatch while the session was connected and driveable.
- *
- * The URL marker is the evidence, and it is what makes this safe: two concurrent leases on one origin
- * carry different markers, so neither can adopt the other's tab. Parsed rather than substring-matched,
- * so `lease-abc` cannot claim `lease-abcdef`.
- */
-export function resolveLeasedSessionId(sessions, leaseId) {
-    if (sessions.get(leaseId) !== undefined) {
-        return leaseId;
-    }
-    return sessions.all().find((s) => sessionParamOf(s.url) === leaseId)?.id;
-}
-/**
- * Carry a claimed identity across a navigation.
- *
- * A LEASED tab is addressed by `__reticle_session` in its URL: that param is how the pool finds the
- * context it opened, and — since succession was tightened — it is also the ONLY thing that lets the
- * reconnecting document inherit the lease. `reticle_navigate` sent the caller's raw URL, so the very
- * first navigation stripped the marker, the tab re-announced as an ordinary anonymous session, and
- * the lease was orphaned: "no sessions are connected at all", with a browser window still open on
- * screen. A leased browser that cannot survive being navigated is not a usable one.
- *
- * A tab that claims nothing is left exactly as it was — this must never bolt Reticle's params onto
- * a human's own URL.
- */
-export function carryReticleIdentity(fromUrl, toUrl) {
-    const session = sessionParamOf(fromUrl);
-    if (session === undefined) {
-        return toUrl;
-    }
-    // Already addressed (a caller passing the stamped URL back) — appending would be a no-op at best.
-    if (sessionParamOf(toUrl) !== undefined) {
-        return toUrl;
-    }
-    const projectId = projectParamOf(fromUrl);
-    return appendReticleParams(toUrl, session, projectId);
-}
-function projectParamOf(url) {
-    if (url === undefined) {
-        return undefined;
-    }
-    try {
-        return new URL(url).searchParams.get(RETICLE_URL_PARAM.PROJECT) ?? undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function sessionParamOf(url) {
-    if (url === undefined) {
-        return undefined;
-    }
-    try {
-        return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Acquire a leased, SDK-connected context for a caller that is not the lease TOOL (the parallel suite).
  * Returns the session id plus its release; the caller must release in a finally so a crashed flow never
  * leaks a pool slot and starves the rest of the suite.
  */
-export async function acquireLeasedSession(pool, sessions, url, projectId, seedStorage) {
+export async function acquireLeasedSession(pool, sessions, url, projectId, seedStorage, ignoreHTTPSErrors) {
     const sessionId = newLeaseId();
     let lease;
     try {
         lease = await pool.acquire(appendReticleParams(url, sessionId, projectId), {
             sessionId,
             ...(seedStorage !== undefined ? { seedStorage } : {}),
+            ...(true === ignoreHTTPSErrors ? { ignoreHTTPSErrors: true } : {}),
         });
     }
     catch (err) {
@@ -248,7 +165,7 @@ export function hasOriginLock(origin) {
 }
 export const LEASE_ACQUIRE_TOOL = {
     name: ReticleTool.LEASE_ACQUIRE,
-    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 every slot is taken this is refused at once, naming the cap, rather than queued. 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, this returns THAT session rather than minting a second tab (a tab that has not connected is loaded again in its own context, so its cookies and sign-in are kept) — 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 every slot is taken this is refused at once, naming the cap, rather than queued. 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()
@@ -259,6 +176,10 @@ 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).'),
+        fresh: z
+            .boolean()
+            .optional()
+            .describe('Open a separate tab even when this connection already holds a lease on the origin, and keep that one. For parallel work that shares one MCP connection (sub-agents). Pass the returned sessionId to every later call.'),
         initScript: z
             .string()
             .optional()
@@ -277,26 +198,39 @@ export const LEASE_ACQUIRE_TOOL = {
             .describe('How the HUD starts on the page: shown (default), hidden, or removed.'),
         permissions: LEASE_PERMISSIONS_ARG,
         emulate: LEASE_EMULATE_ARG,
+        deterministic: LEASE_DETERMINISTIC_ARG,
+        jsCoverage: LEASE_JS_COVERAGE_ARG,
         production: production.PRODUCTION_LEASE_ARG,
+        timeout_ms: timeoutMsSchema
+            .optional()
+            .describe(`How long to wait for the leased tab to connect and answer before answering ready:false with notReadyReason. Default ${String(LEASE_READY_TIMEOUT_MS)}. 0 looks once without waiting.`),
         root: z
             .string()
             .optional()
-            .describe("Absolute path of the .reticle folder this lease's runs belong in — the caller's project. The project folder itself is accepted when it contains a .reticle. Without it, the page's project id decides, and a page with none lands in ~/.reticle/unmatched, which nothing syncs."),
+            .describe("Absolute path of the .reticle folder this lease's runs belong in — the caller's project. An existing project folder is accepted even when it has no .reticle yet (the first run writes it). Omitted, 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. 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.'),
+            .describe('Whether the leased tab is connected AND answered a probe under sessionId, so the next call finds it. acquire waits for this, up to timeout_ms. 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.'),
+        deterministic: z
+            .string()
+            .optional()
+            .describe('Present when this tab runs a seeded random source and a stepped clock. Its time moves only on reticle_clock { stepFrames }, so a wait for a timer or an animation never ends until you step.'),
         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.'),
+        cspWidenedFor: z
+            .string()
+            .optional()
+            .describe("Present when the lease added this origin (the daemon's WebSocket) to the page CSP connect-src, so the zero-install reader can connect. The rest of the page CSP applies as the server sent it."),
         notReadyReason: z
             .enum([
             LeaseNotReadyReason.SDK_NEVER_DIALLED,
@@ -359,7 +293,11 @@ export const LEASE_ACQUIRE_TOOL = {
         const headed = true === args['headed'];
         const hud = Object.values(HudVisibility).find((v) => v === args['hud']);
         const permissions = production.leasePermissions(parseLeasePermissions(args['permissions']), args['production']);
-        const emulate = leaseEmulationOf(args['emulate']);
+        // Determinism is set on the context, like the emulation, so it travels with it.
+        const deterministic = leaseDeterminismOf(args['deterministic']);
+        const emulated = leaseEmulationOf(args['emulate']);
+        const emulate = deterministic === undefined ? emulated : { ...(emulated ?? {}), deterministic };
+        const jsCoverage = true === args['jsCoverage'];
         // 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']);
@@ -408,14 +346,17 @@ export const LEASE_ACQUIRE_TOOL = {
             // 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);
+            // `fresh` asks for a separate tab: the held one is neither reused nor released (#1932).
+            const fresh = true === args['fresh'];
+            const heldOn = (o) => fresh || o === undefined ? undefined : pool.leaseIdOnOrigin(o, deps.attachId);
+            const heldForStub = heldOn(origin);
             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 held = heldOn(origin);
             const existing = held !== undefined && pool.isHeaded(held) === headed ? held : undefined;
             // 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
@@ -428,6 +369,7 @@ export const LEASE_ACQUIRE_TOOL = {
             if ((validatedSeed !== undefined ||
                 certMismatch ||
                 emulate !== undefined ||
+                jsCoverage ||
                 activated !== undefined) &&
                 existing !== undefined) {
                 // Seeding or a different certificate setting asked for: release its own context so the new
@@ -442,6 +384,9 @@ export const LEASE_ACQUIRE_TOOL = {
                 // context — the tab-poisoning this branch exists to prevent, reached through the branch
                 // itself. It bites when the first acquire returned `ready: false`, since the mint path only
                 // aliases once its wait has resolved, so nothing recorded the app's own name (#692).
+                // A tab that never registered is loaded again in its OWN context, and kept while it is open:
+                // releasing it and minting threw away the cookies, so a signed-in tab came back signed out (#1924).
+                const reload = await reconnectHeldLease((ms) => pool.gotoLease(existing, carryReticleIdentity(pool.leaseUrl(existing), url), ms), async () => (await pool.viewportOfLease(existing)) !== undefined, () => pool.leaseLoading(existing), () => resolveLeasedSessionId(deps.sessions, existing) !== undefined, deps.now() + (asNumber(args['timeout_ms']) ?? LEASE_READY_TIMEOUT_MS), deps.now);
                 const resolved = resolveLeasedSessionId(deps.sessions, existing);
                 if (resolved !== undefined) {
                     // The other name this lease answers to, told to the pool exactly as the mint path tells it.
@@ -475,14 +420,20 @@ export const LEASE_ACQUIRE_TOOL = {
                         // 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 } : {}),
+                        ...cspWidenedOf(pool, existing),
                         ...(alreadyOpen === undefined
                             ? {}
                             : { preferExisting: { sessionId: alreadyOpen, note: PREFER_EXISTING_NOTE } }),
                     };
                 }
-                // The lease is still held but the tab has gone — a reload dropped the session, and no session
-                // anywhere is driving it. Free the slot and mint, rather than handing back a dead id or
-                // leaving both contexts occupied.
+                if (reload === HeldLeaseReload.RELOADED || reload === HeldLeaseReload.NOT_LOADED) {
+                    const cause = reload === HeldLeaseReload.RELOADED
+                        ? await notConnectedHint(deps, url, pool.dialFailureUrl?.(existing))
+                        : await notLoadedCause(url, deps.portAccepts);
+                    return keptLeaseAnswer({ sessionId: existing, origin, url, reload }, pool, cause);
+                }
+                // The tab is gone: its page or its context was closed. Free the slot and mint, rather than
+                // handing back a dead id or leaving both contexts occupied.
                 await pool.release(existing);
             }
             const sessionId = newLeaseId();
@@ -505,6 +456,7 @@ export const LEASE_ACQUIRE_TOOL = {
                     ...(permissions !== undefined ? { permissions } : {}),
                     ...(true === args['ignoreHTTPSErrors'] ? { ignoreHTTPSErrors: true } : {}),
                     ...(emulate === undefined ? {} : { emulate }),
+                    ...(jsCoverage ? { jsCoverage } : {}),
                 });
             }
             catch (err) {
@@ -519,19 +471,27 @@ export const LEASE_ACQUIRE_TOOL = {
                     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, one that tells a slow first compile from a missing app.
-                throw new Error(navFailureMessage(url, err, validatedSeed));
+                // actionable message instead, one that tells a slow first compile from a missing app. A
+                // timeout on a port that accepted the connection is a server still compiling (#2005).
+                const accepted = await serverAcceptedAfterTimeout(url, err, validatedSeed, deps.portAccepts);
+                throw new Error(navFailureMessage(url, err, validatedSeed, accepted));
             }
             // 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,
             // and the id we hand back has to be the one the agent can actually drive.
             let registeredId;
-            const waitStartedAt = Date.now();
-            const waited = await production.guardedForProduction(pool, lease, activated);
-            const { ready, zeroInstall, stillLoading, readerFailure } = await connectOrInject(waited, () => {
+            const isRegistered = () => {
                 registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
                 return registeredId !== undefined;
-            });
+            };
+            const waitStartedAt = deps.now();
+            const deadline = waitStartedAt + (asNumber(args['timeout_ms']) ?? LEASE_READY_TIMEOUT_MS);
+            const waited = await production.guardedForProduction(pool, lease, activated);
+            const { ready: connected, zeroInstall, stillLoading, readerFailure, } = await connectOrInject(waited, isRegistered, connectWaitUntil(deadline, deps.now));
+            // Connected is a row in the sessions map. Ready is a reply from it, so the next call works.
+            const answerReason = connected
+                ? await awaitLeaseAnswering(() => (isRegistered() ? deps.sessions.get(registeredId ?? lease.sessionId) : undefined), deadline, deps.now)
+                : undefined;
             // Tell the pool the other name this lease answers to. Every later touch and release arrives
             // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
             // without this the touches miss, the lease ages out despite continuous activity, and the
@@ -541,6 +501,7 @@ export const LEASE_ACQUIRE_TOOL = {
             }
             const effectiveSessionId = registeredId ?? lease.sessionId;
             const session = deps.sessions.get(effectiveSessionId);
+            const ready = connected && answerReason === undefined;
             if (validatedSeed !== undefined && session !== undefined) {
                 const failureReason = evaluateSeedPrecondition(url, session.url, validatedSeed, lease.navStatus);
                 if (failureReason !== undefined) {
@@ -552,18 +513,17 @@ export const LEASE_ACQUIRE_TOOL = {
             if (readerFailure === undefined) {
                 tellWatchers(deps, projectId, AGENT_DRIVING_ELSEWHERE);
             }
-            // ready means the SDK dialled in — not that contracts match. Carry the skew warning on acquire
+            // ready means the SDK answers — 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 = readerFailure?.reason ??
-                notReadyReason(ready, session, LeaseNotReadyReason.SDK_NEVER_DIALLED);
+            const mintReason = readerFailure?.reason ?? (connected ? answerReason : LeaseNotReadyReason.SDK_NEVER_DIALLED);
             const versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
             let notReadyHint;
-            if (!ready) {
+            if (!connected) {
                 if (readerFailure !== undefined) {
                     notReadyHint = leaseReaderFailedHint(url, readerFailure);
                 }
                 else if (true === stillLoading) {
-                    notReadyHint = leaseStillLoadingHint(url, Date.now() - waitStartedAt);
+                    notReadyHint = leaseStillLoadingHint(url, deps.now() - waitStartedAt);
                 }
                 else if (activated !== undefined) {
                     notReadyHint = production.notActivatedHint(url);
@@ -596,6 +556,8 @@ export const LEASE_ACQUIRE_TOOL = {
                 ...(versionSkew === undefined ? {} : { versionSkew }),
                 ...production.summary(activated),
                 ...(initScript === undefined ? {} : { hostStub: HOST_STUB_NOTE }),
+                ...(deterministic === undefined ? {} : { deterministic: DETERMINISTIC_NOTE }),
+                ...cspWidenedOf(pool, lease.sessionId),
                 ...hintOf(notReadyHint, ready ? await notificationReadBack(pool, lease.sessionId, permissions) : undefined),
             };
         }
@@ -607,6 +569,11 @@ export const LEASE_ACQUIRE_TOOL = {
         }
     },
 };
+/** `cspWidenedFor` when the lease changed its page CSP: a change to the page is declared (#2016). */
+function cspWidenedOf(pool, leaseId) {
+    const origin = pool.cspWidenedFor?.(leaseId);
+    return origin === undefined ? {} : { cspWidenedFor: origin };
+}
 /** The whole not-connected diagnosis, gathered and worded. Split out so the acquire path stays flat. */
 async function notConnectedHint(deps, url, dialledUrl) {
     const bridgePort = deps.bridgePort ?? RETICLE_DEFAULT_PORT;
@@ -618,11 +585,12 @@ async function notConnectedHint(deps, url, dialledUrl) {
 }
 const LEASE_RELEASE_TOOL = {
     name: ReticleTool.LEASE_RELEASE,
-    description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
+    description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap. With no sessionId, it releases the one lease this agent holds.',
     inputSchema: {
         sessionId: z
             .string()
-            .describe('The leased sessionId returned by reticle_lease{action:"acquire"}.'),
+            .optional()
+            .describe('The leased sessionId returned by reticle_lease{action:"acquire"}. Omit it when this agent holds one lease.'),
     },
     outputSchema: {
         released: z.boolean(),
@@ -633,10 +601,7 @@ const LEASE_RELEASE_TOOL = {
         if (pool === undefined) {
             throw new Error(POOL_UNAVAILABLE);
         }
-        const sessionId = asString(args['sessionId']);
-        if (sessionId === undefined || 0 === sessionId.length) {
-            throw new Error('reticle_lease{action:"release"} requires a sessionId');
-        }
+        const sessionId = asString(args['sessionId']) ?? ownOnlyLease(deps, pool);
         // An id that holds no lease (a typo, or one that expired) answered `released: true`.
         if (pool.leaseUrl(sessionId) === undefined) {
             const held = pool.leasedSessionIds();
@@ -646,6 +611,21 @@ const LEASE_RELEASE_TOOL = {
         return { released: true, leased: await releaseLease(deps, pool, sessionId) };
     },
 };
+/**
+ * The one lease this caller holds, for a release with no sessionId. Another agent's lease is never
+ * this caller's to release (#1226), so none or several is a refusal that names what is held.
+ */
+function ownOnlyLease(deps, pool) {
+    const own = pool.leasedSessionIds().filter((id) => pool.heldBy(id, deps.attachId));
+    const [only] = own;
+    if (only !== undefined && 1 === own.length) {
+        return only;
+    }
+    const held = 0 === own.length
+        ? 'this agent holds no lease'
+        : `this agent holds ${String(own.length)} leases: ${own.join(', ')}`;
+    throw new Error(`reticle_lease{action:"release"} needs a sessionId: ${held}.`);
+}
 /**
  * Release one lease and everything that hangs off it. Returns how many leases are still held.
  *
@@ -736,4 +716,4 @@ function tellWatchers(deps, projectId, text) {
         // A HUD that missed one line is a smaller problem than a lease reported as broken.
     }
 }
-export const LEASE_TOOLS = [LEASE_ACQUIRE_TOOL, LEASE_RELEASE_TOOL];
+export const LEASE_TOOLS = [LEASE_ACQUIRE_TOOL, LEASE_RELEASE_TOOL, LEASE_COVERAGE_TOOL];

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

@@ -0,0 +1,46 @@
+/**
+ * Reticle's identity params on a lease URL: stamp them, read them back, carry them across a
+ * navigation, and match a registered session to the lease that stamped it.
+ *
+ * Split out of lease-tools.ts at the 1000-line cap. Pure: no I/O.
+ */
+import { type HudVisibility } from '@reticlehq/core';
+/**
+ * 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.
+ */
+export declare function appendReticleParams(url: string, session: string, projectId?: string, hud?: HudVisibility): string;
+/**
+ * The session a lease's tab actually registered as, or undefined while nothing has.
+ *
+ * Normally that is the lease id: `appendReticleParams` stamps `__reticle_session` on the URL and the
+ * SDK adopts it. An app that passes an explicit `session` to `connect()` keeps its own name instead,
+ * which is legitimate — a single-app fixture does it deliberately so a battery can address it by a
+ * known id. Matching on the lease id alone could never see those tabs, so the lease reported
+ * `ready: false` and a hint blaming a port mismatch while the session was connected and driveable.
+ *
+ * The URL marker is the evidence, and it is what makes this safe: two concurrent leases on one origin
+ * carry different markers, so neither can adopt the other's tab. Parsed rather than substring-matched,
+ * so `lease-abc` cannot claim `lease-abcdef`.
+ */
+export declare function resolveLeasedSessionId(sessions: {
+    get: (id: string) => unknown;
+    all: () => {
+        id: string;
+        url?: string;
+    }[];
+}, leaseId: string): string | undefined;
+/**
+ * Carry a claimed identity across a navigation.
+ *
+ * A LEASED tab is addressed by `__reticle_session` in its URL: that param is how the pool finds the
+ * context it opened, and — since succession was tightened — it is also the ONLY thing that lets the
+ * reconnecting document inherit the lease. `reticle_navigate` sent the caller's raw URL, so the very
+ * first navigation stripped the marker, the tab re-announced as an ordinary anonymous session, and
+ * the lease was orphaned: "no sessions are connected at all", with a browser window still open on
+ * screen. A leased browser that cannot survive being navigated is not a usable one.
+ *
+ * A tab that claims nothing is left exactly as it was — this must never bolt Reticle's params onto
+ * a human's own URL.
+ */
+export declare function carryReticleIdentity(fromUrl: string | undefined, toUrl: string): string;

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

@@ -0,0 +1,97 @@
+/**
+ * Reticle's identity params on a lease URL: stamp them, read them back, carry them across a
+ * navigation, and match a registered session to the lease that stamped it.
+ *
+ * Split out of lease-tools.ts at the 1000-line cap. Pure: no I/O.
+ */
+import { RETICLE_URL_PARAM } from '@reticlehq/core';
+/**
+ * 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.
+ */
+export function appendReticleParams(url, session, projectId, hud) {
+    try {
+        const u = new URL(url);
+        u.searchParams.set(RETICLE_URL_PARAM.SESSION, session);
+        if (projectId !== undefined && projectId.length > 0) {
+            u.searchParams.set(RETICLE_URL_PARAM.PROJECT, projectId);
+        }
+        if (hud !== undefined) {
+            u.searchParams.set(RETICLE_URL_PARAM.HUD, hud);
+        }
+        return u.toString();
+    }
+    catch {
+        const sep = url.includes('?') ? '&' : '?';
+        const proj = projectId !== undefined && projectId.length > 0
+            ? `&${RETICLE_URL_PARAM.PROJECT}=${encodeURIComponent(projectId)}`
+            : '';
+        return `${url}${sep}${RETICLE_URL_PARAM.SESSION}=${encodeURIComponent(session)}${proj}`;
+    }
+}
+/**
+ * The session a lease's tab actually registered as, or undefined while nothing has.
+ *
+ * Normally that is the lease id: `appendReticleParams` stamps `__reticle_session` on the URL and the
+ * SDK adopts it. An app that passes an explicit `session` to `connect()` keeps its own name instead,
+ * which is legitimate — a single-app fixture does it deliberately so a battery can address it by a
+ * known id. Matching on the lease id alone could never see those tabs, so the lease reported
+ * `ready: false` and a hint blaming a port mismatch while the session was connected and driveable.
+ *
+ * The URL marker is the evidence, and it is what makes this safe: two concurrent leases on one origin
+ * carry different markers, so neither can adopt the other's tab. Parsed rather than substring-matched,
+ * so `lease-abc` cannot claim `lease-abcdef`.
+ */
+export function resolveLeasedSessionId(sessions, leaseId) {
+    if (sessions.get(leaseId) !== undefined) {
+        return leaseId;
+    }
+    return sessions.all().find((s) => sessionParamOf(s.url) === leaseId)?.id;
+}
+/**
+ * Carry a claimed identity across a navigation.
+ *
+ * A LEASED tab is addressed by `__reticle_session` in its URL: that param is how the pool finds the
+ * context it opened, and — since succession was tightened — it is also the ONLY thing that lets the
+ * reconnecting document inherit the lease. `reticle_navigate` sent the caller's raw URL, so the very
+ * first navigation stripped the marker, the tab re-announced as an ordinary anonymous session, and
+ * the lease was orphaned: "no sessions are connected at all", with a browser window still open on
+ * screen. A leased browser that cannot survive being navigated is not a usable one.
+ *
+ * A tab that claims nothing is left exactly as it was — this must never bolt Reticle's params onto
+ * a human's own URL.
+ */
+export function carryReticleIdentity(fromUrl, toUrl) {
+    const session = sessionParamOf(fromUrl);
+    if (session === undefined) {
+        return toUrl;
+    }
+    // Already addressed (a caller passing the stamped URL back) — appending would be a no-op at best.
+    if (sessionParamOf(toUrl) !== undefined) {
+        return toUrl;
+    }
+    const projectId = projectParamOf(fromUrl);
+    return appendReticleParams(toUrl, session, projectId);
+}
+function projectParamOf(url) {
+    if (url === undefined) {
+        return undefined;
+    }
+    try {
+        return new URL(url).searchParams.get(RETICLE_URL_PARAM.PROJECT) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sessionParamOf(url) {
+    if (url === undefined) {
+        return undefined;
+    }
+    try {
+        return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}