@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,797 @@
+/**
+ * Lease tools — the agent-facing surface of the BrowserPool.
+ *
+ * `reticle_lease_acquire` opens an isolated headless context navigated to the app URL and returns
+ * the sessionId the app's SDK will register. A second acquire on the same origin reuses the live
+ * lease rather than minting another tab — that second tab used to poison default session resolution
+ * for the rest of the run. The parallel suite still mints via `acquireLeasedSession`, because ten
+ * flows on one origin need isolation on purpose.
+ *
+ * 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 { z } from 'zod';
+import { leaseNotConnectedHint } from './lease-hint.js';
+import { probeSdkMarker } from './gaps/sdk-marker-probe.js';
+import { readProjectFramework, readProjectId } from '../../command/cli/ports/resolve/cli-port.js';
+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, REDACTED_VALUE, RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT, ReticleCommand, SeedStorageSchema, scrubKnownSecrets, } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { asString } from '@reticlehq/core';
+import { chromiumHint } from '../../command/cli/doctor/browser/chromium-hint.js';
+/**
+ * Everything the daemon already knows about why a leased tab might not have dialled in.
+ *
+ * Gathered here rather than guessed in the hint, because the daemon HAD this evidence all along and
+ * printed a static differential over the top of it — telling one agent in `reticle_sessions` that
+ * the wiring was proven correct and telling it seconds later that the port was probably wrong.
+ */
+/**
+ * Async only for the marker probe, which is the piece that decides whether this app ships an SDK at
+ * all — the difference between the diagnosis a new user needs and four causes that all assume the
+ * install already happened. It is one localhost GET on a path that has already failed and is about
+ * to print a paragraph, and it can only ever add a sentence: the probe returns `undefined` on any
+ * doubt and the hint then says nothing about markers.
+ */
+async function leaseEvidence(deps, port, url) {
+    const cwd = process.cwd();
+    const projectId = readProjectId(cwd);
+    const refusal = deps.sessions.lastClosure()?.reason;
+    const framework = readProjectFramework(cwd);
+    const sdkMarker = await probeSdkMarker(url);
+    return {
+        ...(refusal === undefined ? {} : { refusal }),
+        ...(framework === undefined ? {} : { framework }),
+        ...(sdkMarker === undefined ? {} : { sdkMarker }),
+        previouslyConnected: hasAnyAppConnectedBefore(reticleStateHome(), port, projectId),
+        initialized: projectId !== undefined,
+    };
+}
+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. */
+export 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 ` +
+        'tab, which would make every later call require sessionId. Release first if you want a fresh one.');
+}
+/**
+ * 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) {
+    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);
+        }
+        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}`;
+    }
+}
+function redactExactValue(text, value) {
+    if (0 === value.length)
+        return text;
+    const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return text.replace(new RegExp(`(^|[^a-zA-Z0-9])${escaped}(?=$|[^a-zA-Z0-9])`, 'g'), `$1${REDACTED_VALUE}`);
+}
+/**
+ * Scrub known secret shapes and raw seedStorage values (cookies, localStorage, sessionStorage)
+ * from an error string before it reaches daemon logs, metrics, or MCP error responses.
+ */
+export function scrubSeedFromError(text, seed) {
+    let out = scrubKnownSecrets(text);
+    if (undefined !== seed && null !== seed && 'object' === typeof seed) {
+        const s = seed;
+        const cookies = s['cookies'];
+        if (undefined !== cookies && null !== cookies) {
+            if (Array.isArray(cookies)) {
+                for (const c of cookies) {
+                    if (undefined !== c && null !== c && 'object' === typeof c) {
+                        const val = c['value'];
+                        if (undefined !== val && 'string' === typeof val) {
+                            out = redactExactValue(out, val);
+                        }
+                    }
+                }
+            }
+            else if ('object' === typeof cookies) {
+                for (const v of Object.values(cookies)) {
+                    if ('string' === typeof v) {
+                        out = redactExactValue(out, v);
+                    }
+                }
+            }
+        }
+        const local = s['local'];
+        if (undefined !== local && null !== local && 'object' === typeof local) {
+            for (const v of Object.values(local)) {
+                if ('string' === typeof v) {
+                    out = redactExactValue(out, v);
+                }
+            }
+        }
+        const session = s['session'];
+        if (undefined !== session && null !== session && 'object' === typeof session) {
+            for (const v of Object.values(session)) {
+                if ('string' === typeof v) {
+                    out = redactExactValue(out, v);
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Turn a raw navigation failure (Playwright's `page.goto: net::ERR_… at <url>\nCall log:…`, often
+ * 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.
+ */
+export function cleanNavError(err, seed) {
+    const rawMsg = err instanceof Error ? err.message : String(err);
+    const msg = scrubSeedFromError(rawMsg, seed);
+    // Strip ANSI color codes (ESC[…m) Playwright emits — built via fromCharCode to keep the
+    // control character out of a regex literal (no-control-regex).
+    const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+    const firstLine = (msg.split('\n')[0] ?? msg).replace(ansi, '');
+    const netCode = /net::[A-Z_]+/.exec(firstLine);
+    if (netCode !== null)
+        return netCode[0];
+    if (/timeout/i.test(firstLine))
+        return 'navigation timed out';
+    return firstLine
+        .replace(/^page\.goto:\s*/, '')
+        .replace(/\s+at\s+https?:\/\/\S+.*$/, '')
+        .trim()
+        .slice(0, 100);
+}
+/**
+ * Determine if a required seedStorage application precondition failed.
+ *
+ * Checks strong signals:
+ * 1. HTTP 401/403 status on the initial navigation.
+ * 2. Cross-origin redirect when localStorage or sessionStorage was requested (skipped by origin-scoping).
+ * 3. Clear redirect to an authentication/login endpoint when the requested URL was not a login page.
+ *
+ * Normal app redirects (e.g. / → /dashboard) are valid and return undefined.
+ */
+export function evaluateSeedPrecondition(requestedUrl, actualUrl, seed, navStatus) {
+    if (401 === navStatus || 403 === navStatus) {
+        return `HTTP ${navStatus} returned on initial seeded navigation to ${requestedUrl}`;
+    }
+    if (actualUrl === undefined || '' === actualUrl.trim())
+        return undefined;
+    let reqParsed;
+    let actParsed;
+    try {
+        reqParsed = new URL(requestedUrl);
+        actParsed = new URL(actualUrl);
+    }
+    catch {
+        return undefined;
+    }
+    // Cross-origin redirect when local or session storage was requested
+    const hasStorage = (undefined !== seed.local && 0 < Object.keys(seed.local).length) ||
+        (undefined !== seed.session && 0 < Object.keys(seed.session).length);
+    if (hasStorage && reqParsed.origin !== actParsed.origin) {
+        return `seeded storage precondition not established: cross-origin redirect from ${reqParsed.origin} to ${actParsed.origin} skipped origin-scoped storage injection`;
+    }
+    // Clear redirect to an authentication/login endpoint when the requested URL was not a login page
+    const isAuthPath = (pathname) => /(?:^|\/)(?:login|signin|sign-in|auth\/login|auth\/signin|session\/new)(?:$|\/)/i.test(pathname);
+    if (!isAuthPath(reqParsed.pathname) && isAuthPath(actParsed.pathname)) {
+        return `seeded authentication precondition not established: redirected from ${reqParsed.pathname} to login page (${actParsed.pathname})`;
+    }
+    return undefined;
+}
+/** 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
+        ? globalThis.crypto.randomUUID()
+        : `${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;
+    }
+}
+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.
+ */
+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;
+    }
+}
+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
+ * leaks a pool slot and starves the rest of the suite.
+ */
+export async function acquireLeasedSession(pool, sessions, url, projectId, seedStorage) {
+    const sessionId = newLeaseId();
+    let lease;
+    try {
+        lease = await pool.acquire(appendReticleParams(url, sessionId, projectId), {
+            sessionId,
+            ...(seedStorage !== undefined ? { seedStorage } : {}),
+        });
+    }
+    catch (err) {
+        throw new Error(scrubSeedFromError(err instanceof Error ? err.message : String(err), seedStorage));
+    }
+    // Resolved, not assumed — see resolveLeasedSessionId. The parallel suite replays against whatever
+    // id comes back, so handing it the lease id for an app that named its own session sent every flow
+    // in the run at a session that does not exist.
+    let registeredId;
+    await waitForLeasedSession(() => {
+        registeredId = resolveLeasedSessionId(sessions, lease.sessionId);
+        return registeredId !== undefined;
+    });
+    if (registeredId !== undefined)
+        pool.alias?.(registeredId, lease.sessionId);
+    const effectiveId = registeredId ?? lease.sessionId;
+    if (seedStorage !== undefined) {
+        const session = sessions.get(effectiveId);
+        if (session?.setPreconditionFailure !== undefined) {
+            const failureReason = evaluateSeedPrecondition(url, session.url, seedStorage, lease.navStatus);
+            if (failureReason !== undefined) {
+                session.setPreconditionFailure(failureReason);
+            }
+        }
+    }
+    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();
+}
+/**
+ * Named on its own because `reticle drive <url>` runs it too.
+ *
+ * When a daemon already owns the bridge port, `drive` asks that daemon for a browser instead of
+ * competing for the port (see cli/drive/drive-attach.ts), and the browser it should get is exactly the one
+ * an agent gets: same pool, same isolation, same reporting. Sharing the ToolDef rather than the
+ * handler keeps that literal — the drive route dispatches through `runTool`, so it is counted like
+ * any other call instead of being a second, invisible dispatch path.
+ */
+// Serializes lease acquisitions on the same origin so concurrent callers (e.g. seeded replacements)
+// do not race and establish multiple overlapping contexts on that origin.
+const originAcquireLocks = new Map();
+export function hasOriginLock(origin) {
+    return originAcquireLocks.has(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 and embed @reticlehq/core). 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()
+            .describe('URL of the already-running app to drive (e.g. http://localhost:3000/dashboard).'),
+        projectId: z
+            .string()
+            .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 (localStorage, sessionStorage, cookies) to seed before the first navigation (e.g. to start already authenticated).'),
+    },
+    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.'),
+        notReadyReason: z
+            .enum([LeaseNotReadyReason.SDK_NEVER_DIALLED, LeaseNotReadyReason.SDK_STOPPED_ANSWERING])
+            .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.'),
+        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.'),
+        leased: z.number().describe('How many contexts are currently leased from the pool.'),
+        queued: z.number().describe('How many acquires are waiting for a free slot.'),
+        preferExisting: z
+            .object({ sessionId: z.string(), note: z.string() })
+            .optional()
+            .describe('Present when a live NON-leased tab for this app was already connected. That tab is the one a human can see; this lease is not. Release this lease and drive that sessionId unless you specifically need an isolated context.'),
+        reused: z
+            .boolean()
+            .optional()
+            .describe('True when this acquire returned an existing live lease on the same origin rather than minting a second context.'),
+        hint: z.string().optional(),
+        versionSkew: z
+            .string()
+            .optional()
+            .describe("Present when the leased tab's SDK disagrees with this daemon. ready is still true — the " +
+            'page dialled in — but CDP-backed tools (screenshot, viewport, real input, network_mock) ' +
+            'will fail until the versions match. Same sentence as reticle_sessions.versionSkew.'),
+    },
+    handler: async (deps, args) => {
+        const pool = deps.pool;
+        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');
+        // 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
+        // fine. Say the real thing at the first refusal instead. The phrasing carries "Chromium is not
+        // installed" so error-recovery routes it to the NO_POOL fix (install + drive a human tab).
+        if (deps.browserProbe !== undefined) {
+            const probe = await deps.browserProbe();
+            if (!probe.exists) {
+                throw new Error(`Chromium is not installed for Playwright — ${chromiumHint(probe)}`);
+            }
+        }
+        const projectId = asString(args['projectId']);
+        const seedStorageArg = args['seedStorage'];
+        let validatedSeed;
+        if (seedStorageArg !== undefined) {
+            const parsed = SeedStorageSchema.safeParse(seedStorageArg);
+            if (!parsed.success) {
+                const issuesMsg = scrubSeedFromError(parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', '), seedStorageArg);
+                throw new Error(`reticle_lease{action:"acquire"} seedStorage is invalid: ${issuesMsg}`);
+            }
+            validatedSeed = parsed.data;
+        }
+        // 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.
+        const alreadyOpen = liveTabFor(deps, projectId, url);
+        const origin = originOf(url);
+        const priorLock = origin !== undefined ? originAcquireLocks.get(origin) : undefined;
+        let releaseLock;
+        let lockPromise;
+        if (origin !== undefined) {
+            lockPromise = new Promise((resolve) => {
+                releaseLock = resolve;
+            });
+            originAcquireLocks.set(origin, lockPromise);
+        }
+        if (priorLock !== undefined) {
+            await priorLock.catch(() => undefined);
+        }
+        try {
+            const existing = origin === undefined ? undefined : pool.leaseIdOnOrigin?.(origin);
+            if (validatedSeed !== undefined && existing !== undefined) {
+                // Caller explicitly requested storage seeding: do not reuse an existing context on this origin,
+                // release it so the new lease starts clean with the caller-provided state.
+                await pool.release(existing);
+            }
+            else if (existing !== undefined && origin !== undefined) {
+                // Resolved, not looked up — the same resolver the mint path below uses, for the same reason
+                // it states: an app that names its own session registers under that name, so the id the pool
+                // holds is not always an id the other tools accept. A direct `sessions.get` missed exactly
+                // those apps and fell through to the release, which frees a LIVE lease and mints a second
+                // 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).
+                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.
+                    // 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);
+                    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));
+                    return {
+                        sessionId: resolved,
+                        url,
+                        ready: alive,
+                        ...(alive ? {} : { notReadyReason: LeaseNotReadyReason.SDK_STOPPED_ANSWERING }),
+                        reused: true,
+                        expiresInMs: pool.leaseTtlMs(),
+                        leased: pool.activeCount(),
+                        queued: pool.queuedCount(),
+                        hint: alreadyHeldHint(resolved, origin),
+                        ...(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.
+                await pool.release(existing);
+            }
+            const sessionId = newLeaseId();
+            const navUrl = appendReticleParams(url, sessionId, projectId);
+            let lease;
+            try {
+                lease = await pool.acquire(navUrl, {
+                    sessionId,
+                    ...(validatedSeed !== undefined ? { seedStorage: validatedSeed } : {}),
+                });
+            }
+            catch (err) {
+                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)})`);
+            }
+            // 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 ready = await waitForLeasedSession(() => {
+                registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
+                return registeredId !== 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
+            // reaper closes the context mid-flow. See BrowserPool.alias and #157.
+            if (registeredId !== undefined)
+                pool.alias(registeredId, lease.sessionId);
+            const effectiveSessionId = registeredId ?? lease.sessionId;
+            const session = deps.sessions.get(effectiveSessionId);
+            if (validatedSeed !== undefined && session !== undefined) {
+                const failureReason = evaluateSeedPrecondition(url, session.url, validatedSeed, lease.navStatus);
+                if (failureReason !== undefined) {
+                    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);
+            // 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 versionSkew = registeredId === undefined ? undefined : deps.sessions.get(registeredId)?.versionSkew;
+            return {
+                sessionId: registeredId ?? lease.sessionId,
+                url,
+                ready,
+                // 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 }),
+                expiresInMs: pool.leaseTtlMs(),
+                leased: pool.activeCount(),
+                queued: pool.queuedCount(),
+                ...(alreadyOpen === undefined
+                    ? {}
+                    : {
+                        preferExisting: {
+                            sessionId: alreadyOpen,
+                            note: PREFER_EXISTING_NOTE,
+                        },
+                    }),
+                ...(versionSkew === undefined ? {} : { versionSkew }),
+                ...(ready
+                    ? {}
+                    : { hint: await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId)) }),
+            };
+        }
+        finally {
+            releaseLock?.();
+            if (origin !== undefined && originAcquireLocks.get(origin) === lockPromise) {
+                originAcquireLocks.delete(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;
+    const evidence = await leaseEvidence(deps, bridgePort, url);
+    return leaseNotConnectedHint(url, bridgePort, {
+        ...evidence,
+        ...(dialledUrl === undefined ? {} : { 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.',
+    inputSchema: {
+        sessionId: z
+            .string()
+            .describe('The leased sessionId returned by reticle_lease{action:"acquire"}.'),
+    },
+    outputSchema: {
+        released: z.boolean(),
+        leased: z.number(),
+    },
+    handler: async (deps, args) => {
+        const pool = deps.pool;
+        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');
+        }
+        // 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() };
+    },
+};
+/**
+ * What to say when a lease was taken while a real tab was already open.
+ *
+ * Not a refusal. Leases are the highest-value path for autonomous work and an agent that genuinely
+ * needs isolation must still get one — but a human watching their own tab cannot see a lease, so
+ * when both exist the visible one is the better default and the agent should hear that here, where
+ * it is choosing, rather than discover it when somebody asks why nothing is happening.
+ */
+const PREFER_EXISTING_NOTE = 'a non-leased tab for this app was already connected — that is the one a human can see, and this lease is not. Unless you need an isolated context (a second identity, a clean profile, parallel flows), release this lease and drive that sessionId instead.';
+/**
+ * The first live non-leased session that is THIS app, if any.
+ *
+ * The watcher selector decides who to NARRATE to, and it is deliberately permissive: an unknown
+ * project still gets told, because a dark HUD is worse than a note that did not concern you. That
+ * is the right trade for a broadcast and the wrong one here, where a single `[0]` is handed back as
+ * "drive this instead". With `projectId` undefined — and it is an OPTIONAL argument that an
+ * acquiring agent has no reason to pass — every non-leased session qualified and the answer was
+ * whichever the map yielded first. Measured against a real daemon: leasing `localhost:4312`
+ * recommended a Phanpy tab on `:5173`, so an agent that complied would have driven a different
+ * application and reported a verdict about it.
+ *
+ * So this narrows by the one thing a lease always knows: the ORIGIN it is being taken against.
+ * `projectId` still narrows further when given. Nothing is recommended when nothing matches, which
+ * is the honest answer — a lease is simply correct then.
+ */
+function liveTabFor(deps, projectId, url) {
+    const pool = deps.pool;
+    if (pool === undefined)
+        return undefined;
+    const wanted = originOf(url);
+    if (wanted === undefined)
+        return undefined;
+    try {
+        const candidates = deps.sessions
+            .all()
+            .filter((session) => session.url !== undefined && originOf(session.url) === wanted)
+            .map((session) => ({ id: session.id, projectId: session.projectId }));
+        return watchersToNotify(candidates, pool.leasedSessionIds(), projectId)[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Tell the tabs a human is watching that the agent has gone somewhere they cannot see.
+ *
+ * Fire-and-forget, and deliberately never able to fail the tool: this is a courtesy to a person, and
+ * a lease that succeeded must not be reported as failed because a narration could not be posted to
+ * some unrelated tab. `pushNarration` is already fire-and-forget; the try/catch covers a session
+ * that disconnects between listing it and posting to it.
+ */
+function tellWatchers(deps, projectId, text) {
+    const pool = deps.pool;
+    if (pool === undefined)
+        return;
+    try {
+        const candidates = deps.sessions
+            .all()
+            .map((session) => ({ id: session.id, projectId: session.projectId }));
+        for (const id of watchersToNotify(candidates, pool.leasedSessionIds(), projectId)) {
+            deps.sessions.get(id)?.pushNarration(text);
+        }
+    }
+    catch {
+        // 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];
+/**
+ * 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;
+    }
+}