@reticlehq/server 3.5.0 → 3.7.0

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

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

package/dist/surface/tools/live-call-text.js

@@ -42,13 +42,13 @@ const NO_TOOL_EQUIVALENT = [
         // hint used to put `action` and `url` beside `tool`, which reticle_run refuses, and a `[^}]*\}`
         // body stopped at the inner brace and left ` }` behind once the hint was corrected.
         pattern: /`?reticle_run\s*\{\s*tool:\s*\\?"reticle_lease\\?"(?:[^{}]|\{[^{}]*\})*\}`?(\s*\([^)]*\))?(\s*[-\u2014]+\s*reticle_lease is[^.]*\.)?/g,
-        instead: 'the CLI: `reticle open <url>` (a human can equivalently run `reticle drive <url>`)',
+        instead: 'the CLI: `npx @reticlehq/server open <url>` (a human can equivalently run `npx @reticlehq/server drive <url>`)',
     },
     {
         needs: [ReticleTool.LEASE],
         // The bare cross-reference, left behind once the call above is gone.
         pattern: /\breticle_lease\s*\{[^}]*\}/g,
-        instead: '`reticle open <url>`',
+        instead: '`npx @reticlehq/server open <url>`',
     },
     {
         needs: [ReticleTool.FLOW],
@@ -80,8 +80,8 @@ const NO_TOOL_EQUIVALENT = [
      * every session, and the longer two-route version cost 67 bytes there against a budget measured
      * in whole-session terms — for advice that is read once, on a first run.
      *
-     * `explore` needs ANTHROPIC_API_KEY and says so itself when it is missing, naming the fallback in
-     * the same breath ("flows are recorded by your own coding agent through the MCP tools"). That
+     * `explore` runs on the platform and says so itself when it is not linked, naming the fallback in
+     * the same breath (drive the journey yourself with the MCP tools). That
      * error is now recognised as ours, so the reader who hits it gets the next step instead of an
      * invitation to file a defect report. One hop, and every hop is honest.
      */

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

@@ -1,6 +1,34 @@
 import { z } from 'zod';
+import { allowParamValues } from '../../telemetry/argument-shape.js';
 /** The field the merged tool dispatches on. A member may not declare one of its own — see below. */
 const DISCRIMINATOR = 'action';
+/**
+ * Keys a member may receive without declaring them. `sessionId` is pinned onto the arguments by the
+ * dispatch routes (`reticle_run`, the harness toolset) whatever the member, so refusing it would
+ * refuse the routes themselves.
+ */
+const SHARED_KEYS = new Set(['sessionId']);
+/**
+ * The refusal for keys another action of this tool takes (#1536).
+ *
+ * The SDK checks unknown keys against the UNION of every action's parameters, so a key that belongs
+ * to a sibling action passed, reached a handler that does not read it, and was dropped:
+ * `verify { action: "change", names }` replayed every affected flow, and `look { action: "page",
+ * limit }` returned the whole tree. Same words as the unknown-key refusal, plus the action that
+ * does take each key, which is the correction the caller needs.
+ */
+function strayKeysRefusal(tool, action, stray, actions) {
+    const owners = stray.map((key) => {
+        const takes = Object.entries(actions)
+            .filter(([, member]) => key in member.inputSchema)
+            .map(([name]) => `"${name}"`);
+        return `\`${key}\` is a parameter of action ${takes.join(' or ')}`;
+    });
+    const declared = Object.keys(actions[action]?.inputSchema ?? {}).join(', ');
+    return (`${tool} { action: "${action}" } does not take ${stray.map((k) => `\`${k}\``).join(', ')}, ` +
+        'so it was NOT applied — a result computed without it would look like an answer. ' +
+        `${owners.join('; ')}. Action "${action}" takes: ${declared}.`);
+}
 /** The union of member input shapes, every field optional so one schema serves every action. */
 function unionShape(actions) {
     const shape = {};
@@ -82,6 +110,8 @@ export function mergeTools(spec) {
     const actionNames = Object.keys(spec.actions);
     if (0 === actionNames.length)
         throw new Error(`mergeTools(${spec.name}): no actions`);
+    // Our own action names: telemetry may report them by value rather than as `other`.
+    allowParamValues(DISCRIMINATOR, actionNames);
     refuseDiscriminatorCollision(spec.name, spec.actions);
     if (spec.defaultAction !== undefined && !(spec.defaultAction in spec.actions)) {
         throw new Error(`mergeTools(${spec.name}): defaultAction '${spec.defaultAction}' is not one of its actions`);
@@ -94,7 +124,7 @@ export function mergeTools(spec) {
             [DISCRIMINATOR]: discriminatorSchema(actionNames, spec.defaultAction),
             ...unionShape(spec.actions),
         },
-        handler: (deps, args) => {
+        handler: (deps, args, call) => {
             const named = args[DISCRIMINATOR];
             const action = 'string' === typeof named ? named : spec.defaultAction;
             const chosen = action === undefined ? undefined : spec.actions[action];
@@ -104,7 +134,17 @@ export function mergeTools(spec) {
                     expected: actionNames,
                 });
             }
-            return chosen.handler(deps, args);
+            // A key no action declares is refused before this, against the union; one that another action
+            // declares is refused here, against the action that was chosen.
+            const stray = Object.keys(args).filter((key) => DISCRIMINATOR !== key &&
+                !SHARED_KEYS.has(key) &&
+                !(key in chosen.inputSchema) &&
+                args[key] !== undefined &&
+                Object.values(spec.actions).some((member) => key in member.inputSchema));
+            if (0 < stray.length && action !== undefined) {
+                return Promise.reject(new Error(strayKeysRefusal(spec.name, action, stray, spec.actions)));
+            }
+            return chosen.handler(deps, args, call);
         },
     };
 }

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

@@ -77,6 +77,10 @@ export function mergedNameRedirect(name) {
 export function retiredToolNames() {
     const tombstones = {};
     for (const [old, redirect] of BY_OLD_NAME) {
+        // A bare call that redirects to an action on the SAME tool (`reticle_assert` → `{ action: "now" }`)
+        // is a live tool, not a retired one. Listing it here told every reader not to use it.
+        if (old === redirect.tool)
+            continue;
         tombstones[old] =
             redirect.action === undefined
                 ? `retired; ${redirect.note ?? `use ${redirect.tool}`}`

package/dist/surface/tools/next-step.d.ts

@@ -0,0 +1,29 @@
+export declare const NextText: {
+    readonly DECLARE: "Record what the user asked, once per task, verbatim: reticle_run { tool: \"reticle_intent\", args: { action: \"declare\", request: \"<their words>\" } }. It travels with every run.";
+    readonly SYNC_PROBLEM: (why: string) => string;
+    readonly FINISH_LINKED: "Done driving? reticle_session { action: \"yield\" } hands the tab back; this run syncs to the platform on its own.";
+    readonly FINISH: "Done driving? reticle_session { action: \"yield\" } hands the tab back.";
+    /**
+     * The evidence of this app is landing outside any project, so nothing will send it. A second
+     * checkout's runs and flows went to `~/.reticle/unmatched/<id>` and the agent was told nothing.
+     */
+    readonly UNMATCHED: (root: string, contenders: readonly string[], serving?: string) => string;
+    readonly REPLAY: (flows: number) => string;
+};
+/** Tests only. */
+export declare function resetNextStep(): void;
+export interface NextStepInput {
+    tool: string;
+    /** Where this app's evidence goes when no project claims it, and the folders that compete for it. */
+    unmatched?: {
+        root: string;
+        contenders: readonly string[];
+        serving?: string;
+    } | undefined;
+    /** Whether this result carries a verdict. */
+    verdict: boolean;
+    root: string | undefined;
+    now: number;
+}
+/** The line, or undefined when there is nothing the agent should be told right now. */
+export declare function nextStep(input: NextStepInput): string | undefined;