@reticlehq/server 3.9.0 → 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 { LEASE_READY_TIMEOUT_MS, awaitLeaseAnswering, connectOrInject, connectWaitUntil, 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,7 +21,7 @@ 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';
@@ -30,6 +30,8 @@ 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.
@@ -87,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, or pass fresh: true to open a separate tab and keep this 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, 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}`;
-    }
-}
+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
@@ -126,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) {
@@ -249,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()
@@ -282,6 +198,8 @@ 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()
@@ -289,7 +207,7 @@ export const LEASE_ACQUIRE_TOOL = {
         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(),
@@ -301,6 +219,10 @@ export const LEASE_ACQUIRE_TOOL = {
             .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()
@@ -371,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']);
@@ -443,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
@@ -457,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.
@@ -496,9 +426,14 @@ export const LEASE_ACQUIRE_TOOL = {
                             : { 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();
@@ -521,6 +456,7 @@ export const LEASE_ACQUIRE_TOOL = {
                     ...(permissions !== undefined ? { permissions } : {}),
                     ...(true === args['ignoreHTTPSErrors'] ? { ignoreHTTPSErrors: true } : {}),
                     ...(emulate === undefined ? {} : { emulate }),
+                    ...(jsCoverage ? { jsCoverage } : {}),
                 });
             }
             catch (err) {
@@ -535,8 +471,10 @@ 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,
@@ -618,6 +556,7 @@ 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),
             };
@@ -646,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(),
@@ -661,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();
@@ -674,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.
  *
@@ -764,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;
+    }
+}

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

@@ -36,14 +36,104 @@ function strayKeysRefusal(tool, action, stray, actions) {
 /** The union of member input shapes, every field optional so one schema serves every action. */
 function unionShape(actions) {
     const shape = {};
+    const contested = contestedKeys(actions);
     for (const tool of Object.values(actions)) {
         for (const [key, schema] of Object.entries(tool.inputSchema)) {
-            // First definition wins; siblings share field names/meanings by construction.
-            shape[key] ??= schema.isOptional() ? schema : schema.optional();
+            if (key in shape) {
+                continue;
+            }
+            // First definition wins, unless members accept different values for it: see contestedKeys.
+            if (contested.has(key)) {
+                shape[key] = eitherBound(key, actions);
+            }
+            else {
+                shape[key] = schema.isOptional() ? schema : schema.optional();
+            }
         }
     }
     return shape;
 }
+/**
+ * What a field accepts, without its description: two members that word one field differently
+ * still accept the same values.
+ */
+function boundOf(schema) {
+    try {
+        const json = { ...z.toJSONSchema(schema, { unrepresentable: 'any' }) };
+        delete json['description'];
+        return JSON.stringify(json);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The fields two members accept different values for (#2144).
+ *
+ * `reticle_assert { action: "now" }` caps `timeout_ms` at one request, and `action: "wait"` takes up
+ * to 600000 and answers `resume_ms` for the rest. With the first definition winning, the merged tool
+ * kept the cap of "now", and refused every wait longer than one request: `reticle verify --expect
+ * --timeout 120000` printed `verified: unknown`.
+ */
+function contestedKeys(actions) {
+    const seen = new Map();
+    const contested = new Set();
+    for (const tool of Object.values(actions)) {
+        for (const [key, schema] of Object.entries(tool.inputSchema)) {
+            const bound = boundOf(schema);
+            if (!seen.has(key)) {
+                seen.set(key, bound);
+            }
+            else if (seen.get(key) !== bound) {
+                contested.add(key);
+            }
+        }
+    }
+    return contested;
+}
+/**
+ * A contested field accepts what any member accepts. The dispatch then checks the value against the
+ * chosen action's own schema (`contestedRefusal`), so no action gets a value it would refuse.
+ */
+function eitherBound(key, actions) {
+    const owners = Object.entries(actions).filter(([, tool]) => key in tool.inputSchema);
+    const schemas = owners.flatMap(([, tool]) => {
+        const schema = tool.inputSchema[key];
+        return schema === undefined ? [] : [schema];
+    });
+    const described = owners
+        .map(([action, tool]) => {
+        const said = tool.inputSchema[key]?.description;
+        return said === undefined ? undefined : `For action "${action}": ${said}`;
+    })
+        .filter((said) => said !== undefined)
+        .join(' ');
+    const [first, second, ...rest] = schemas;
+    if (first === undefined || second === undefined) {
+        throw new Error(`mergeTools: contested key '${key}' has fewer than two schemas`);
+    }
+    const either = z.union([first, second, ...rest]).optional();
+    return 0 === described.length ? either : either.describe(described);
+}
+/** The refusal for a contested field whose value the chosen action does not accept. */
+function contestedRefusal(tool, action, args, chosen, contested) {
+    const named = [];
+    for (const key of contested) {
+        const schema = chosen.inputSchema[key];
+        if (schema === undefined || args[key] === undefined) {
+            continue;
+        }
+        const checked = schema.safeParse(args[key]);
+        if (!checked.success) {
+            named.push(`${key} (${checked.error.issues.map((issue) => issue.message).join('; ')})`);
+        }
+    }
+    if (0 === named.length) {
+        return undefined;
+    }
+    return (`invalid ${1 === named.length ? 'parameter' : 'parameters'} for ${tool} { action: "${action}" }: ` +
+        `${named.join('; ')} — NOT applied, so any result would be an answer to a different question`);
+}
 /**
  * A member that declares `action` itself cannot be merged, and the failure was SILENT.
  *
@@ -120,6 +210,7 @@ export function mergeTools(spec) {
     if (spec.defaultAction !== undefined && !(spec.defaultAction in spec.actions)) {
         throw new Error(`mergeTools(${spec.name}): defaultAction '${spec.defaultAction}' is not one of its actions`);
     }
+    const contested = contestedKeys(spec.actions);
     return {
         name: spec.name,
         description: spec.description,
@@ -148,6 +239,12 @@ export function mergeTools(spec) {
             if (0 < stray.length && action !== undefined) {
                 return Promise.reject(new Error(strayKeysRefusal(spec.name, action, stray, spec.actions)));
             }
+            const outOfBounds = action === undefined
+                ? undefined
+                : contestedRefusal(spec.name, action, args, chosen, contested);
+            if (outOfBounds !== undefined) {
+                return Promise.reject(new Error(outOfBounds));
+            }
             return chosen.handler(deps, args, call);
         },
     };

package/dist/surface/tools/merged-name-redirect.js

@@ -1,7 +1,7 @@
 /**
  * Where a merged or retired tool's old name went.
  *
- * Twenty-two names exported from `ReticleTool` are no longer tools: `reticle_record_start` became
+ * Many names exported from `ReticleTool` are no longer tools: `reticle_record_start` became
  * `reticle_record { action: "start" }`, `reticle_diff` became `reticle_baseline { action: "diff" }`,
  * and three were retired outright. Confirmed live in a field sweep, they all answered `unknown tool`
  * — which is the wrong answer, because the capability exists and only moved. An agent trained on an
@@ -23,6 +23,10 @@ const RETIRED_NOTE = {
         tool: ReticleTool.PROJECT,
         note: 'run outcomes are persisted automatically by reticle_flow_replay; read them with reticle_project',
     },
+    [ReticleTool.EXPLORE]: {
+        tool: ReticleTool.LOOK,
+        note: 'list the controls with reticle_look { action: "page", mode: "interactive" } (reticle_snapshot { mode: "interactive" }), and read console errors with reticle_observe { action: "console" } (reticle_console)',
+    },
     [ReticleTool.WAIT_READY]: {
         tool: ReticleTool.SESSIONS,
         note: 'waiting is implicit — the first live call already blocks until the session is ready',