@reticlehq/server 3.7.0 → 3.8.1

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

@@ -9,11 +9,10 @@
  *
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
-import { fixturePortFor, seedFromStorageState, } from '../../portal/input/storage-fixture.js';
-import { mutationPortFor } from '../../portal/input/network-mutation.js';
+import * as production from '../../portal/production/production-activation.js';
 import { z } from 'zod';
-import { leaseNotConnectedHint } from './lease-hint.js';
-import { probeLeaseAlive, tabHidden } from './lease-readiness.js';
+import { leaseNotConnectedHint, leaseReaderFailedHint, leaseStillLoadingHint, } from './lease-hint.js';
+import { connectOrInject, moveReusedLease, notReadyReason, probeLeaseAlive, } 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';
@@ -22,12 +21,15 @@ 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, } from '@reticlehq/core';
+import { LeaseNotReadyReason, RETICLE_URL_PARAM, 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 { 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';
+export { sessionMutationPort, sessionPerturbationPort, suiteFixturePort, suiteFixtureSeed, } from './session-ports.js';
 /**
  * Everything the daemon already knows about why a leased tab might not have dialled in.
  *
@@ -51,11 +53,13 @@ import { LEASE_PERMISSIONS_ARG, hintOf, notificationReadBack, parseLeasePermissi
  */
 async function observedCspBlock(url, port) {
     const document = await observeWebDocument(url);
-    if (document === undefined)
+    if (document === undefined) {
         return undefined;
+    }
     const refusesSocket = diagnoseObservedWebCsp(document, port).some((finding) => `${finding.problem} ${finding.fix}`.includes(CONNECT_SRC));
-    if (!refusesSocket)
+    if (!refusesSocket) {
         return undefined;
+    }
     const allow = `ws://localhost:${String(port)} ws://127.0.0.1:${String(port)}`;
     return {
         problem: `its ${CONNECT_SRC} does not allow ws://localhost:${String(port)}`,
@@ -81,15 +85,6 @@ 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`).';
-/** The origin of a URL, or undefined when it does not parse. */
-function originOf(url) {
-    try {
-        return new URL(url).origin;
-    }
-    catch {
-        return undefined;
-    }
-}
 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 ` +
@@ -108,8 +103,9 @@ export function appendReticleParams(url, session, projectId, hud) {
         if (projectId !== undefined && projectId.length > 0) {
             u.searchParams.set(RETICLE_URL_PARAM.PROJECT, projectId);
         }
-        if (hud !== undefined)
+        if (hud !== undefined) {
             u.searchParams.set(RETICLE_URL_PARAM.HUD, hud);
+        }
         return u.toString();
     }
     catch {
@@ -143,8 +139,9 @@ function newLeaseId() {
  * so `lease-abc` cannot claim `lease-abcdef`.
  */
 export function resolveLeasedSessionId(sessions, leaseId) {
-    if (sessions.get(leaseId) !== undefined)
+    if (sessions.get(leaseId) !== undefined) {
         return leaseId;
+    }
     return sessions.all().find((s) => sessionParamOf(s.url) === leaseId)?.id;
 }
 /**
@@ -162,17 +159,20 @@ export function resolveLeasedSessionId(sessions, leaseId) {
  */
 export function carryReticleIdentity(fromUrl, toUrl) {
     const session = sessionParamOf(fromUrl);
-    if (session === undefined)
+    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)
+    if (sessionParamOf(toUrl) !== undefined) {
         return toUrl;
+    }
     const projectId = projectParamOf(fromUrl);
     return appendReticleParams(toUrl, session, projectId);
 }
 function projectParamOf(url) {
-    if (url === undefined)
+    if (url === undefined) {
         return undefined;
+    }
     try {
         return new URL(url).searchParams.get(RETICLE_URL_PARAM.PROJECT) ?? undefined;
     }
@@ -181,8 +181,9 @@ function projectParamOf(url) {
     }
 }
 function sessionParamOf(url) {
-    if (url === undefined)
+    if (url === undefined) {
         return undefined;
+    }
     try {
         return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
     }
@@ -190,15 +191,6 @@ function sessionParamOf(url) {
         return undefined;
     }
 }
-const LEASE_READY_ATTEMPTS = 100;
-const LEASE_READY_POLL_MS = 100;
-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
- * is immediately usable (the page navigates first, then connects a moment later — without this wait
- * an agent's very next call could race and hit "no connected session"). Returns whether it connected
- * in time. `isConnected`, `sleeper`, and `attempts` are injected so this is fast to unit-test.
- */
 /**
  * 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
@@ -224,8 +216,9 @@ export async function acquireLeasedSession(pool, sessions, url, projectId, seedS
         registeredId = resolveLeasedSessionId(sessions, lease.sessionId);
         return registeredId !== undefined;
     });
-    if (registeredId !== undefined)
+    if (registeredId !== undefined) {
         pool.alias?.(registeredId, lease.sessionId);
+    }
     const effectiveId = registeredId ?? lease.sessionId;
     if (seedStorage !== undefined) {
         const session = sessions.get(effectiveId);
@@ -238,31 +231,6 @@ export async function acquireLeasedSession(pool, sessions, url, projectId, seedS
     }
     return { sessionId: effectiveId, release: () => lease.release() };
 }
-export async function waitForLeasedSession(isConnected, sleeper = sleep, attempts = LEASE_READY_ATTEMPTS, pollMs = LEASE_READY_POLL_MS) {
-    for (let i = 0; i < attempts; i++) {
-        if (isConnected())
-            return true;
-        await sleeper(pollMs);
-    }
-    return isConnected();
-}
-/**
- * Wait for the leased tab to connect; if its app never does, hand it the zero-install reader.
- *
- * The decision is taken HERE, by the daemon, on the one fact that settles it: no HELLO arrived. A
- * timer inside the page cannot know that — an app can connect from a dynamic import that resolves
- * after `load` — and a reader injected into a page whose app was about to connect would take its
- * place and drop the app's own options. So an app that connected itself is never touched, and a page
- * that stayed silent through the whole readiness wait is the one that gets a reader.
- */
-export async function connectOrInject(lease, isConnected, wait = waitForLeasedSession) {
-    if (await wait(isConnected))
-        return { ready: true, zeroInstall: false };
-    if (true !== (await lease.injectReader?.()))
-        return { ready: false, zeroInstall: false };
-    const ready = await wait(isConnected);
-    return { ready, zeroInstall: ready };
-}
 /**
  * Named on its own because `reticle drive <url>` runs it too.
  *
@@ -280,11 +248,12 @@ 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 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 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()
-            .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard).'),
+            .optional()
+            .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard). Omit it to lease the one dev server that runs in this project folder.'),
         projectId: z
             .string()
             .optional()
@@ -307,10 +276,12 @@ export const LEASE_ACQUIRE_TOOL = {
             .optional()
             .describe('How the HUD starts on the page: shown (default), hidden, or removed.'),
         permissions: LEASE_PERMISSIONS_ARG,
+        emulate: LEASE_EMULATE_ARG,
+        production: production.PRODUCTION_LEASE_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."),
+            .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."),
     },
     outputSchema: {
         sessionId: z.string(),
@@ -331,9 +302,11 @@ export const LEASE_ACQUIRE_TOOL = {
             LeaseNotReadyReason.SDK_NEVER_DIALLED,
             LeaseNotReadyReason.SDK_STOPPED_ANSWERING,
             LeaseNotReadyReason.TAB_HIDDEN,
+            LeaseNotReadyReason.NOT_HTML_DOCUMENT,
+            LeaseNotReadyReason.READER_FAILED,
         ])
             .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. 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.'),
+            .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), unless the hint says the page was still loading, in which case it is a slow first compile and checking reticle_session { action: "list" } shortly is the next step. 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. not_html_document ⇒ the URL is not an HTML page (an `.svg`, for example), so acquire an HTML page of the app instead. reader_failed ⇒ the zero-install reader failed, for example because the tab closed during setup; the hint gives the cause. For both, the lease is already released.'),
         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.'),
@@ -347,7 +320,12 @@ export const LEASE_ACQUIRE_TOOL = {
             .boolean()
             .optional()
             .describe('True when this acquire returned an existing live lease on the same origin rather than minting a second context.'),
+        navigated: z
+            .boolean()
+            .optional()
+            .describe('Present when a reused lease was on another page. True: its tab was moved to url. False: it could not be moved, and url is the page it is on.'),
         hint: z.string().optional(),
+        production: production.PRODUCTION_LEASE_OUTPUT,
         versionSkew: z
             .string()
             .optional()
@@ -357,11 +335,14 @@ export const LEASE_ACQUIRE_TOOL = {
     },
     handler: async (deps, args) => {
         const pool = deps.pool;
-        if (pool === undefined)
+        if (pool === undefined) {
             throw new Error(POOL_UNAVAILABLE);
-        const url = asString(args['url']);
-        if (url === undefined || 0 === url.length)
-            throw new Error('reticle_lease{action:"acquire"} requires a url');
+        }
+        const given = asString(args['url']);
+        const url = given === undefined || 0 === given.length ? await deps.projectAppUrl?.() : given;
+        if (url === undefined) {
+            throw new Error('reticle_lease{action:"acquire"} requires a url: no single dev server runs in this project folder. Start the app, or pass the url it serves.');
+        }
         // Preflight the browser before spending the round trip. Without it a missing Playwright Chromium
         // only surfaces inside pool.acquire, where the launch failure is caught and reported as
         // "could not open <url> — is the app running?" — sending the caller to debug an app that is
@@ -369,14 +350,16 @@ export const LEASE_ACQUIRE_TOOL = {
         // installed" so error-recovery routes it to the NO_POOL fix (install + drive a human tab).
         if (deps.browserProbe !== undefined) {
             const refusal = chromiumPreflightRefusal(await deps.browserProbe());
-            if (refusal !== undefined)
+            if (refusal !== undefined) {
                 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']);
+        const permissions = production.leasePermissions(parseLeasePermissions(args['permissions']), args['production']);
+        const emulate = leaseEmulationOf(args['emulate']);
         // 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']);
@@ -395,6 +378,10 @@ export const LEASE_ACQUIRE_TOOL = {
             }
             validatedSeed = parsed.data;
         }
+        // Awaited only when asked: an extra tick here reorders concurrent acquires on the origin lock.
+        const activated = args['production'] === undefined
+            ? undefined
+            : await production.activationFor(deps, args['production'], url, root);
         // Sampled BEFORE acquiring: afterwards this lease is itself a session, and the point is to name
         // a tab that already existed. A human's open tab is the one they can watch, so if one is here
         // the agent should be told at the moment it is choosing — not after it has gone dark on them.
@@ -437,7 +424,12 @@ export const LEASE_ACQUIRE_TOOL = {
             const certMismatch = existing !== undefined &&
                 'boolean' === typeof certAsked &&
                 pool.ignoresHTTPSErrors(existing) !== certAsked;
-            if ((validatedSeed !== undefined || certMismatch) && existing !== undefined) {
+            // Emulation is set before the first paint, so a held lease is replaced like a seeded one.
+            if ((validatedSeed !== undefined ||
+                certMismatch ||
+                emulate !== undefined ||
+                activated !== undefined) &&
+                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);
@@ -463,16 +455,16 @@ export const LEASE_ACQUIRE_TOOL = {
                     // 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 tabUrl = () => deps.sessions.get(resolved)?.url;
+                    const moved = await moveReusedLease(tabUrl, url, () => pool.gotoLease(existing, carryReticleIdentity(tabUrl(), url)), deps.now);
                     const reusedSession = deps.sessions.get(resolved);
-                    const alive = await probeLeaseAlive(reusedSession);
-                    const reuseReason = !alive
-                        ? LeaseNotReadyReason.SDK_STOPPED_ANSWERING
-                        : tabHidden(reusedSession)
-                            ? LeaseNotReadyReason.TAB_HIDDEN
-                            : undefined;
+                    const reuseReason = false === moved?.arrived
+                        ? LeaseNotReadyReason.SDK_NEVER_DIALLED
+                        : notReadyReason(await probeLeaseAlive(reusedSession), reusedSession);
                     return {
                         sessionId: resolved,
-                        url,
+                        url: moved?.url ?? url,
+                        ...(moved === undefined ? {} : { navigated: moved.navigated }),
                         ready: reuseReason === undefined,
                         ...(reuseReason === undefined ? {} : { notReadyReason: reuseReason }),
                         reused: true,
@@ -495,25 +487,34 @@ export const LEASE_ACQUIRE_TOOL = {
             }
             const sessionId = newLeaseId();
             // Before the page can dial in: the session is stamped with its root the moment it registers.
-            if (root !== undefined)
+            if (root !== undefined) {
                 claimArtifactRoot(sessionId, root);
-            const navUrl = appendReticleParams(url, sessionId, projectId, hud);
+            }
+            const navUrl = appendReticleParams(activated?.url ?? url, sessionId, projectId, hud);
             let lease;
             try {
                 lease = await pool.acquire(navUrl, {
                     sessionId,
+                    // An agent, or `reticle drive` behind it, is waiting on this answer and cannot see a queue:
+                    // a full pool is said at once, not discovered as a 60 s silence (#1535).
+                    whenFull: 'refuse',
                     ...(headed ? { headed } : {}),
                     ...(deps.attachId === undefined ? {} : { owner: deps.attachId }),
                     ...(validatedSeed !== undefined ? { seedStorage: validatedSeed } : {}),
                     ...(initScript !== undefined ? { initScript } : {}),
                     ...(permissions !== undefined ? { permissions } : {}),
                     ...(true === args['ignoreHTTPSErrors'] ? { ignoreHTTPSErrors: true } : {}),
+                    ...(emulate === undefined ? {} : { emulate }),
                 });
             }
             catch (err) {
+                if (err instanceof PoolAtCapacityError) {
+                    throw err;
+                }
                 const refusal = permissionRefusal(err);
-                if (refusal !== undefined)
+                if (refusal !== undefined) {
                     throw refusal;
+                }
                 if (err instanceof Error && err.message.startsWith('Storage seeding failed')) {
                     throw new Error(scrubSeedFromError(err.message, validatedSeed));
                 }
@@ -525,7 +526,9 @@ export const LEASE_ACQUIRE_TOOL = {
             // 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 { ready, zeroInstall } = await connectOrInject(lease, () => {
+            const waitStartedAt = Date.now();
+            const waited = await production.guardedForProduction(pool, lease, activated);
+            const { ready, zeroInstall, stillLoading, readerFailure } = await connectOrInject(waited, () => {
                 registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
                 return registeredId !== undefined;
             });
@@ -533,8 +536,9 @@ export const LEASE_ACQUIRE_TOOL = {
             // 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
             // reaper closes the context mid-flow. See BrowserPool.alias and #157.
-            if (registeredId !== undefined)
+            if (registeredId !== undefined) {
                 pool.alias(registeredId, lease.sessionId);
+            }
             const effectiveSessionId = registeredId ?? lease.sessionId;
             const session = deps.sessions.get(effectiveSessionId);
             if (validatedSeed !== undefined && session !== undefined) {
@@ -543,16 +547,31 @@ export const LEASE_ACQUIRE_TOOL = {
                     session.setPreconditionFailure?.(failureReason);
                 }
             }
-            // The lease now exists, so any HUD a human is watching has just gone dark. Say so.
-            tellWatchers(deps, projectId, AGENT_DRIVING_ELSEWHERE);
+            // The lease now exists, so any HUD a human is watching has just gone dark. Say so. A lease whose
+            // reader failed is already released, so there is nothing to say.
+            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
             // 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 mintReason = readerFailure?.reason ??
+                notReadyReason(ready, session, LeaseNotReadyReason.SDK_NEVER_DIALLED);
             const versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
+            let notReadyHint;
+            if (!ready) {
+                if (readerFailure !== undefined) {
+                    notReadyHint = leaseReaderFailedHint(url, readerFailure);
+                }
+                else if (true === stillLoading) {
+                    notReadyHint = leaseStillLoadingHint(url, Date.now() - waitStartedAt);
+                }
+                else if (activated !== undefined) {
+                    notReadyHint = production.notActivatedHint(url);
+                }
+                else {
+                    notReadyHint = await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId));
+                }
+            }
             return {
                 sessionId: registeredId ?? lease.sessionId,
                 url,
@@ -575,10 +594,9 @@ export const LEASE_ACQUIRE_TOOL = {
                         },
                     }),
                 ...(versionSkew === undefined ? {} : { versionSkew }),
+                ...production.summary(activated),
                 ...(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),
+                ...hintOf(notReadyHint, ready ? await notificationReadBack(pool, lease.sessionId, permissions) : undefined),
             };
         }
         finally {
@@ -612,12 +630,19 @@ const LEASE_RELEASE_TOOL = {
     },
     handler: async (deps, args) => {
         const pool = deps.pool;
-        if (pool === undefined)
+        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');
         }
+        // An id that holds no lease (a typo, or one that expired) answered `released: true`.
+        if (pool.leaseUrl(sessionId) === undefined) {
+            const held = pool.leasedSessionIds();
+            throw new Error(`reticle_lease{action:"release"}: no lease '${sessionId}' is held, so nothing was released. ` +
+                (0 === held.length ? 'No lease is held now.' : `Leases held now: ${held.join(', ')}.`));
+        }
         return { released: true, leased: await releaseLease(deps, pool, sessionId) };
     },
 };
@@ -636,8 +661,9 @@ export async function releaseLease(deps, pool, 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())
+    if (0 === pool.activeCount()) {
         tellWatchers(deps, projectId, AGENT_DRIVING_HERE_AGAIN);
+    }
     return pool.activeCount();
 }
 /**
@@ -665,11 +691,13 @@ const PREFER_EXISTING_NOTE = 'a non-leased tab for this app was already connecte
  */
 function liveTabFor(deps, projectId, url) {
     const pool = deps.pool;
-    if (pool === undefined)
+    if (pool === undefined) {
         return undefined;
+    }
     const wanted = originOf(url);
-    if (wanted === undefined)
+    if (wanted === undefined) {
         return undefined;
+    }
     try {
         const candidates = deps.sessions
             .all()
@@ -693,8 +721,9 @@ function liveTabFor(deps, projectId, url) {
  */
 function tellWatchers(deps, projectId, text) {
     const pool = deps.pool;
-    if (pool === undefined)
+    if (pool === undefined) {
         return;
+    }
     try {
         const candidates = deps.sessions
             .all()
@@ -708,96 +737,3 @@ function tellWatchers(deps, projectId, text) {
     }
 }
 export const LEASE_TOOLS = [LEASE_ACQUIRE_TOOL, LEASE_RELEASE_TOOL];
-/**
- * The state a suite should boot its flows from: whatever the agent is already sitting in.
- *
- * This is the join the fixture work was building toward. A suite's flows each start from cold, so
- * fifty of them prove the login works fifty times — and the flow that LOGS OUT leaves every flow
- * after it signed out, which no navigation repairs, because the problem is not where the subject is
- * but what it holds. A seed is applied to an isolated context BEFORE the first navigation, which is
- * exactly and only when a fixture can work.
- *
- * Best-effort, deliberately. A fixture is an OPTIMISATION over running from cold, and running from
- * cold is correct: a suite that refused to start because a cookie jar could not be read would have
- * traded a slow answer for no answer. Every "no" here — no provider, no storage support, nothing
- * driven, a browser that threw, nothing worth seeding — produces the same honest `undefined`, and
- * the suite runs exactly as it did before any of this existed.
- */
-export async function suiteFixtureSeed(realInput, appUrl) {
-    if (realInput === undefined)
-        return undefined;
-    try {
-        const port = await fixturePortFor(realInput, appUrl);
-        if (port === undefined)
-            return undefined;
-        return seedFromStorageState(await port.capture(), appUrl);
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * A way to make this session's page SLOW on purpose, or nothing.
- *
- * The third of these seams, for the same reason as the other two: a feature reaching into the input
- * layer directly is a feature depending on a driver, and the boundary guard asks about it.
- *
- * Installs delays and NOTHING else. A rule that carried a status or a body would substitute a
- * response the server never sent, and an app raced against invented data produces invented races —
- * a fabricated defect handed to somebody at 3am, which is worse than finding nothing.
- */
-export async function sessionPerturbationPort(realInput, appUrl) {
-    if (realInput === undefined || appUrl === undefined)
-        return undefined;
-    const setMocks = realInput.setMocks?.bind(realInput);
-    if (setMocks === undefined)
-        return undefined;
-    if (!(await realInput.isAvailableFor(appUrl)))
-        return undefined;
-    return {
-        slow: async (rules) => {
-            await setMocks(appUrl, [...rules]);
-        },
-        /** Clearing is the undo. A page left slowed is damage the next run inherits. */
-        clear: async () => {
-            await setMocks(appUrl, []);
-        },
-    };
-}
-/**
- * Save/restore for this session's page, or nothing.
- *
- * The same job as `suiteFixtureSeed` next door, stopping one step earlier: that one captures and
- * converts, this hands back the PORT so a caller can re-apply what it captured later. It lives here
- * for the reason written above — a feature reaching into the input layer directly is a feature
- * depending on a driver, and the boundary guard asks about it. It asked.
- */
-export async function suiteFixturePort(realInput, appUrl) {
-    if (realInput === undefined || appUrl === undefined)
-        return undefined;
-    try {
-        return await fixturePortFor(realInput, appUrl);
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * A way to break this session's page, or nothing.
- *
- * Sits beside `suiteFixtureSeed` because it is the same shape of job: turning a provider capability
- * into something a feature can use, on the one side of the graph that is allowed to know about both.
- * A flow tool reaching into the input layer directly would be a feature depending on a driver, which
- * is the reach the boundary guard exists to ask about.
- */
-export async function sessionMutationPort(realInput, appUrl) {
-    if (realInput === undefined || appUrl === undefined)
-        return undefined;
-    try {
-        return await mutationPortFor(realInput, appUrl);
-    }
-    catch {
-        // A provider that cannot answer is the same answer as a provider that cannot break anything.
-        return undefined;
-    }
-}

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

@@ -0,0 +1,20 @@
+import { type AppMap, type JournalAction, type ReticleEvent } from '@reticlehq/core';
+import { type ToolDef } from './tool-kit.js';
+/** One session, as the fold reads it. */
+export interface MapSession {
+    id: string;
+    actions: readonly JournalAction[];
+    events: readonly ReticleEvent[];
+}
+/** One screen on the map, with how much of it was pressed and proven. */
+export interface MapScreen {
+    screen: string;
+    actions: number;
+    pressed: number;
+    proven: number;
+}
+/** The project's sessions folded into one graph; undefined when none pressed anything. */
+export declare function graphOfSessions(sessions: readonly MapSession[]): AppMap | undefined;
+/** Each screen with its actions counted: what is there, what was pressed, what held. */
+export declare function screensOf(map: AppMap): MapScreen[];
+export declare const MAP_TOOLS: ToolDef[];