@reticlehq/server 2.12.0 → 2.13.0

package/dist/tools/dynamic-tools.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { runTool } from './invoke-tool.js';
 import { buildErrorPayload } from './error-recovery.js';
-import { mergedNameRedirect, mergedNameMessage } from './merged-name-redirect.js';
+import { mergedNameRedirect, mergedNameMessage, retiredToolNames } from './merged-name-redirect.js';
+import { takeVersionSkewOnto } from '../version/version-nudge.js';
 import { ReticleTool } from './tool-names.js';
 import { ADVERTISE_ALL_ENV } from './tool-surface.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
@@ -110,11 +111,18 @@ export function buildDynamicTools(allTools, profile) {
                     name: t.name,
                     summary: firstSentence(t.description),
                 }));
+                // Names that USED to be tools, against the call that replaces each. Instructions written
+                // against an earlier release are a permanent fact of the product — `reticle_crawl` is still
+                // named by guidance in the wild — and without this the catalogue is silent about them: the
+                // old name is simply absent, which reads as "no such capability" rather than "renamed".
+                // Reaching the new name then costs an error string, or never happens.
+                const retired = retiredToolNames();
                 return Promise.resolve({
                     total: catalog.length,
                     tools: catalog,
+                    retired,
                     ...profileBlock,
-                    next: `All ${catalog.length} tools above are callable, advertised or not. Load full params with reticle_tools { names:[…] }, then call reticle_run { tool, args }.`,
+                    next: `All ${catalog.length} tools above are callable, advertised or not. Load full params with reticle_tools { names:[…] }, then call reticle_run { tool, args }. \`retired\` maps names that are no longer tools to the call that replaced each.`,
                 });
             }
             // The grammar rides ONLY on a `names:[…]` reply that asked for a tool taking a predicate, so
@@ -124,9 +132,20 @@ export function buildDynamicTools(allTools, profile) {
             return Promise.resolve({
                 tools: names.map((n) => {
                     const t = byName.get(n);
-                    return t === undefined
+                    if (t !== undefined)
+                        return { name: n, description: t.description, params: paramInfo(t.inputSchema) };
+                    // `reticle_run` has answered a merged name with its replacement for a while; the tool
+                    // asked to DISCOVER tools still said "unknown tool", which is the wrong answer in the one
+                    // place an agent goes to resolve a name it is unsure of. Same redirect, same derivation.
+                    const moved = mergedNameRedirect(n);
+                    return moved === undefined
                         ? { name: n, error: 'unknown tool' }
-                        : { name: n, description: t.description, params: paramInfo(t.inputSchema) };
+                        : {
+                            name: n,
+                            error: mergedNameMessage(n, moved),
+                            tool: moved.tool,
+                            ...(moved.action === undefined ? {} : { action: moved.action }),
+                        };
                 }),
                 ...(carriesPredicate ? { predicateGrammar: predicateGrammar() } : {}),
             });
@@ -222,7 +241,7 @@ export function buildDynamicTools(allTools, profile) {
                 // is reached through here: a stale ref, a paused session, a missing pairing token all came
                 // back as the agent's arguments being wrong, which is advice that spends the retry.
                 const message = error instanceof Error ? error.message : String(error);
-                return { ...buildErrorPayload(message), tool: name };
+                return { ...takeVersionSkewOnto(buildErrorPayload(message)), tool: name };
             }
         },
     };

package/dist/tools/error-recovery.d.ts

@@ -49,6 +49,7 @@ export declare const RECOVERY: {
      */
     readonly CONFIRM_DANGEROUS: string;
     readonly UNSUPPORTED_SURFACE: string;
+    readonly HOVER_NEEDS_POINTER: string;
     readonly TOKEN_REQUIRED: string;
     readonly SCOPE_MISMATCH: string;
     readonly SESSION_GONE: string;

package/dist/tools/error-recovery.js

@@ -143,6 +143,12 @@ export const RECOVERY = {
         'editor keeps its own document model, so writing to the DOM would look right and submit the old ' +
         'content. Drive the same outcome another way (a plain input, a command, a keyboard action) or ' +
         'assert on the result instead of typing it. Known gap, already reported: no need to file it.',
+    HOVER_NEEDS_POINTER: 'Hover needs a real pointer: a synthetic mouseover does not apply CSS :hover, and Reticle ' +
+        'refuses rather than reporting the styles as applied. Acquire a tab with ' +
+        'reticle_run { tool: "reticle_lease", action: "acquire", url } — reticle_lease is not ' +
+        'advertised under the default profile, so it is reached through reticle_run, not called ' +
+        'directly — or ask the human to drive with `reticle drive` / RETICLE_CDP_URL. This is a ' +
+        'deliberate refusal, not a defect: there is nothing to report.',
     TOKEN_REQUIRED: 'The bridge binds beyond localhost and requires a pairing token. Set the same token in the SDK ' +
         'init (@reticlehq/core) and the Reticle server config, then reconnect.',
     SCOPE_MISMATCH: 'A tab IS connected — it just belongs to a different project than the daemon is scoped to, so ' +
@@ -202,6 +208,7 @@ const REASON_OF = {
     TARGET_MISSED: RefusalReason.NO_MATCH,
     FLOW_STEP_MISSING: RefusalReason.NO_MATCH,
     UNSUPPORTED_SURFACE: RefusalReason.UNSUPPORTED,
+    HOVER_NEEDS_POINTER: RefusalReason.UNSUPPORTED,
     NOT_EDITABLE: RefusalReason.UNSUPPORTED,
     CONFIRM_DANGEROUS: RefusalReason.UNSUPPORTED,
     WRONG_TARGET: RefusalReason.UNSUPPORTED,
@@ -247,6 +254,7 @@ const RULES = [
     // broken. Order matters: contenteditable and disabled/readonly are `cannot <verb> …` messages too,
     // so they must be tested before the general wrong-target rule.
     { match: /contenteditable/i, hint: RECOVERY.UNSUPPORTED_SURFACE },
+    { match: /cannot hover without a real pointer/i, hint: RECOVERY.HOVER_NEEDS_POINTER },
     { match: /cannot \w+ a (disabled|readonly) </i, hint: RECOVERY.NOT_EDITABLE },
     // Three spellings ship — "action", "native action", "WebMCP tool" — and the rule matched one, so
     // two thirds of the same deliberate refusal still read as a possible defect.

package/dist/tools/invoke-tool.js

@@ -5,13 +5,14 @@ import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
 import { takeUpdateNudge } from '../update/update-nudge.js';
 import { takeVersionSkew } from '../version/version-nudge.js';
+import { rewriteClosedAsSkew } from '../version/version-skew.js';
 import { noteToolCall } from '../daemon/daemon-usefulness.js';
 import { bugsInResult, routeOf } from '../telemetry/bug-found.js';
 import { noteToolServed, reportToolRefused } from '../telemetry/tool-refused.js';
 import { buildErrorPayload, refusalReasonFor } from './error-recovery.js';
 import { resultIsError } from '../mcp/mcp-is-error.js';
 import { verificationOf } from '../telemetry/verification-of.js';
-import { asString } from './tools-helpers.js';
+import { asString, sessionIdFromArgs, spentRefFromArgs } from './tools-helpers.js';
 import { EnvelopeKey } from './tool-kit.js';
 import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
@@ -19,7 +20,7 @@ import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
 import { noteRefsMinted, wrongTabRefusal } from '../session/ref-provenance.js';
 import { CAPTURED_TOOLS, noteCapturedCall, noteToolDispatched, } from '../honesty/feature-capture.js';
 import { span } from '../trace.js';
-import { deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../impact/impact-recorder.js';
+import { defectForToolResult, deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../impact/impact-recorder.js';
 import { frictionOf, inviteFor } from './feedback-invite.js';
 /**
  * The live-session tools whose result MUST carry the
@@ -37,6 +38,20 @@ const ACTION_TOOLS = new Set([
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
 ]);
+/**
+ * Tools that go through Playwright CDP rather than the page SDK.
+ *
+ * Under version skew these fail with "Target page, context or browser has been closed" while every
+ * DOM tool against the same tab still works (#688). They are session-EXEMPT (own result contracts),
+ * so the bound-tool resolve above never runs for them — resolve again here so we can refuse with
+ * the skew sentence before Playwright lies about a closed page.
+ */
+const CDP_TOOLS = new Set([
+    ReticleTool.SCREENSHOT,
+    ReticleTool.VISUAL_DIFF,
+    ReticleTool.NETWORK_MOCK,
+    ReticleTool.VIEWPORT,
+]);
 /**
  * Tools whose result hands the agent refs. The tab they were minted in is remembered, so the call
  * that spends one cannot be routed to a different tab without saying so — see ref-provenance.ts.
@@ -103,6 +118,10 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.INTENT, // reads/writes .reticle/intent.json; sessionId only picks the project
     ReticleTool.CONTEXT, // folds the journal + intent ledger; must still answer when nothing is connected
     ReticleTool.PROJECT, // reads .reticle/project.json
+    // Reads the team's shared memory over HTTP; sessionId only resolves WHICH project's link file to
+    // use. It must answer with no tab connected — "what does this project know?" is a question an
+    // agent asks before it has opened anything.
+    ReticleTool.MEMORY,
     ReticleTool.RUN_EXPORT, // reads .reticle/runs/<id>.json (verification-run artifact)
     ReticleTool.SESSION, // merged lifecycle/human-channel family (tune/yield/end/resume/messages/review/narrate)
     ReticleTool.SCREENSHOT, // own contract; provider-driven, not a live-DOM-health read
@@ -287,7 +306,7 @@ export async function runTool(tool, deps, args) {
         getSessionMetrics().recordAction();
     const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
     const startedAt = Date.now();
-    const rawSessionId = asString(args['sessionId']);
+    const rawSessionId = sessionIdFromArgs(args);
     const bound = SESSION_BOUND_TOOLS.has(tool.name);
     // Resolve the session identity ONCE, up front, for a live-session tool. The lease heartbeat must
     // target the session the handler will ACTUALLY drive — which, when the agent omits sessionId, is the
@@ -296,7 +315,7 @@ export async function runTool(tool, deps, args) {
     // before the handler so a long ACT_AND_WAIT is protected for its whole duration; on failure leave it
     // to the handler to throw the canonical no-session error.
     let session;
-    if (bound) {
+    if (bound || CDP_TOOLS.has(tool.name)) {
         try {
             session = deps.sessions.resolve(rawSessionId);
         }
@@ -304,6 +323,13 @@ export async function runTool(tool, deps, args) {
             session = undefined;
         }
     }
+    // CDP tools against a skewed session: refuse with the sentence reticle_sessions already knows,
+    // before Playwright invents a closed page. ready:true leases still hit this path.
+    if (session?.versionSkew !== undefined && CDP_TOOLS.has(tool.name)) {
+        const message = session.versionSkew;
+        reportRefusal(tool.name, message);
+        throw new Error(message);
+    }
     // The read-only calls the journal never keeps, recorded HERE because this is the one dispatch
     // point every call routes through — a second recording site is a second thing to forget, and this
     // instrument exists precisely because nothing was recorded before. Recorded before the handler
@@ -348,7 +374,7 @@ export async function runTool(tool, deps, args) {
     // the guessed tab and return a green about a page nobody asked about.
     if (session !== undefined) {
         const wrongTab = wrongTabRefusal({
-            ref: asString(args['ref']),
+            ref: spentRefFromArgs(args),
             explicitSessionId: rawSessionId,
             chosenSessionId: session.id,
             connected: () => deps.sessions.list(),
@@ -375,7 +401,22 @@ export async function runTool(tool, deps, args) {
         // to the agent by the MCP boundary, and discarded. Reported here rather than at that boundary
         // because there are two of them (mcp.ts and the reticle_run hatch) and this is the one place both
         // go through — a third would otherwise be invisible from the day it was added.
-        const message = error instanceof Error ? error.message : String(error);
+        //
+        // Under version skew, Playwright's "Target page has been closed" is the wrong cause (#688): the
+        // page is still dialled in. Prefer the session's skew sentence when we already know the pair is
+        // mismatched — including for tools that are not in CDP_TOOLS (real-input fallbacks that throw).
+        let skewText = session?.versionSkew;
+        if (skewText === undefined) {
+            try {
+                skewText = deps.sessions.resolve(rawSessionId).versionSkew;
+            }
+            catch {
+                skewText = undefined;
+            }
+        }
+        const rewritten = rewriteClosedAsSkew(error, skewText);
+        const toThrow = rewritten ?? error;
+        const message = toThrow instanceof Error ? toThrow.message : String(toThrow);
         reportRefusal(tool.name, message);
         // The invitation on THIS path is the one `buildErrorPayload` attaches when it does not recognise
         // the error, and it was never counted — so the denominator excluded the commonest friction there
@@ -384,7 +425,7 @@ export async function runTool(tool, deps, args) {
         if (tool.name !== ReticleTool.RUN && buildErrorPayload(message).feedback !== undefined) {
             getSessionMetrics().recordFeedbackPrompt();
         }
-        throw error;
+        throw toThrow;
     }
     finally {
         // In a `finally` so a THROWN call still settles: otherwise every failing tool would leak a
@@ -410,11 +451,20 @@ export async function runTool(tool, deps, args) {
     // The user's own record of what Reticle did for them. Same chokepoint as everything else that
     // counts, for the same reason: a second recording site is a second thing to forget. Separate
     // store from telemetry - this one never leaves the machine.
-    recordImpact(deltaForToolResult(raw, Date.now() - startedAt, resultIsError(raw)));
+    const finishedAt = Date.now();
+    const defect = defectForToolResult(raw, finishedAt);
+    // Which project's ledger this call belongs to. Resolved from the SESSION being driven, not from
+    // wherever the daemon happens to stand: one daemon serves many projects, and recording every
+    // call against its own cwd is how one app's verdicts ended up on another account's dashboard.
+    // Falls back to the daemon root when no session can be named, which is the old behaviour.
+    const artifactRoot = session?.artifactRoot ?? deps.reticleRoot;
+    recordImpact(deltaForToolResult(raw, finishedAt - startedAt, resultIsError(raw)), { ...(defect === undefined ? {} : { defect }) }, artifactRoot);
     // ...and the tab being driven is told, so the report is live rather than a thing you reload.
     // Optional-call, not optional-chain-on-the-object: a test double is a partial Session, and a
     // courtesy push must never be the reason a tool call throws.
-    session?.pushImpact?.(impactSnapshot);
+    // Bound to THIS session's root: a tab must be shown its own project's numbers, not whichever
+    // project the daemon was started in.
+    session?.pushImpact?.(() => impactSnapshot(artifactRoot));
     if (resultIsError(raw))
         reportRefusal(tool.name, raw.error);
     else {

package/dist/tools/lease-tools.d.ts

@@ -1,14 +1,17 @@
 /**
  * Lease tools — the agent-facing surface of the BrowserPool.
  *
- * `reticle_lease_acquire` opens a fresh isolated headless context navigated to the app URL and returns
- * the sessionId the app's SDK will register (stamped via __reticle_session so the lease and the session
- * correlate 1:1). This is the "one of 10 flows" entry point: 10 agents acquire 10 leases, the pool
- * keeps them in ONE browser, capped and queued. `reticle_lease_release` frees the slot.
+ * `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 type { ToolDef } from './tool-kit.js';
+/** The origin of a URL, or undefined when it does not parse. */
+export declare function originOf(url: string): string | undefined;
 /**
  * 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.
@@ -40,6 +43,20 @@ export declare function resolveLeasedSessionId(sessions: {
         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;
 /**
  * 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
@@ -86,4 +103,13 @@ export declare function waitForLeasedSession(isConnected: () => boolean, sleeper
  * any other call instead of being a second, invisible dispatch path.
  */
 export declare const LEASE_ACQUIRE_TOOL: ToolDef;
+/**
+ * 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.
+ */
+export declare const PREFER_EXISTING_NOTE = "a non-leased tab for this app was already connected \u2014 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.";
 export declare const LEASE_TOOLS: ToolDef[];

package/dist/tools/lease-tools.js

@@ -1,10 +1,11 @@
 /**
  * Lease tools — the agent-facing surface of the BrowserPool.
  *
- * `reticle_lease_acquire` opens a fresh isolated headless context navigated to the app URL and returns
- * the sessionId the app's SDK will register (stamped via __reticle_session so the lease and the session
- * correlate 1:1). This is the "one of 10 flows" entry point: 10 agents acquire 10 leases, the pool
- * keeps them in ONE browser, capped and queued. `reticle_lease_release` frees the slot.
+ * `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.
  */
@@ -13,6 +14,7 @@ import { leaseNotConnectedHint } from './lease-hint.js';
 import { probeSdkMarker } from './sdk-marker-probe.js';
 import { readProjectFramework, readProjectId } from '../cli/cli-port.js';
 import { hasConnectedBefore } from '../session/connection-memory.js';
+import { AGENT_DRIVING_ELSEWHERE, AGENT_DRIVING_HERE_AGAIN, watchersToNotify, } from '../session/lease-visibility.js';
 import { reticleStateHome } from '../daemon/daemon.js';
 import { RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
@@ -47,6 +49,20 @@ async function leaseEvidence(deps, port, url) {
     };
 }
 const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
+/** The origin of a URL, or undefined when it does not parse. */
+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.
@@ -115,6 +131,39 @@ export function resolveLeasedSessionId(sessions, leaseId) {
         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;
@@ -173,7 +222,7 @@ export async function waitForLeasedSession(isConnected, sleeper = sleep, attempt
  */
 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). 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.',
+    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()
@@ -194,7 +243,21 @@ export const LEASE_ACQUIRE_TOOL = {
             .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;
@@ -215,6 +278,33 @@ export const LEASE_ACQUIRE_TOOL = {
             }
         }
         const projectId = asString(args['projectId']);
+        // 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);
+        const origin = originOf(url);
+        const existing = origin === undefined ? undefined : pool.leaseIdOnOrigin?.(origin);
+        if (existing !== undefined && origin !== undefined) {
+            if (deps.sessions.get(existing) !== undefined) {
+                pool.touch(existing);
+                return {
+                    sessionId: existing,
+                    url,
+                    ready: true,
+                    reused: true,
+                    expiresInMs: pool.leaseTtlMs(),
+                    leased: pool.activeCount(),
+                    queued: pool.queuedCount(),
+                    hint: alreadyHeldHint(existing, 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. 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;
@@ -240,6 +330,11 @@ export const LEASE_ACQUIRE_TOOL = {
         // reaper closes the context mid-flow. See BrowserPool.alias and #157.
         if (registeredId !== undefined)
             pool.alias(registeredId, lease.sessionId);
+        // 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,
@@ -247,6 +342,15 @@ export const LEASE_ACQUIRE_TOOL = {
             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)) }),
@@ -282,8 +386,68 @@ 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() };
     },
 };
+/**
+ * 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.
+ */
+export 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 for this project, if any.
+ *
+ * Reuses the watcher selector rather than re-deriving "which sessions belong to a human": one rule
+ * for one question, so the tab we announce to and the tab we recommend can never disagree.
+ */
+function liveTabFor(deps, projectId) {
+    const pool = deps.pool;
+    if (pool === undefined)
+        return undefined;
+    try {
+        const candidates = deps.sessions
+            .all()
+            .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];

package/dist/tools/merged-name-redirect.d.ts

@@ -8,6 +8,19 @@ interface MergedNameRedirect {
 }
 /** Where `name` went, or undefined when it is a live tool or not ours. */
 export declare function mergedNameRedirect(name: string): MergedNameRedirect | undefined;
+/**
+ * Every retired name against the call that replaces it — the tombstones, as one block.
+ *
+ * The redirect above answers an agent that already guessed the old name. This answers the one that
+ * is reading the surface to find out what exists, and is the case a redirect cannot reach: nothing
+ * in the catalogue says `reticle_crawl` became `reticle_verify { action: "crawl" }`, so instructions
+ * written against an earlier release lead either to an error string or to nothing at all.
+ *
+ * Derived from the same two declarations as `BY_OLD_NAME`, for the same reason: a hand-written
+ * migration list is one merge away from being wrong, and wrong is worse than absent here — the agent
+ * retries into it.
+ */
+export declare function retiredToolNames(): Readonly<Record<string, string>>;
 /** The sentence handed to an agent that called `name`. */
 export declare function mergedNameMessage(name: string, redirect: MergedNameRedirect): string;
 export {};

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

@@ -46,6 +46,28 @@ const BY_OLD_NAME = (() => {
 export function mergedNameRedirect(name) {
     return BY_OLD_NAME.get(name);
 }
+/**
+ * Every retired name against the call that replaces it — the tombstones, as one block.
+ *
+ * The redirect above answers an agent that already guessed the old name. This answers the one that
+ * is reading the surface to find out what exists, and is the case a redirect cannot reach: nothing
+ * in the catalogue says `reticle_crawl` became `reticle_verify { action: "crawl" }`, so instructions
+ * written against an earlier release lead either to an error string or to nothing at all.
+ *
+ * Derived from the same two declarations as `BY_OLD_NAME`, for the same reason: a hand-written
+ * migration list is one merge away from being wrong, and wrong is worse than absent here — the agent
+ * retries into it.
+ */
+export function retiredToolNames() {
+    const tombstones = {};
+    for (const [old, redirect] of BY_OLD_NAME) {
+        tombstones[old] =
+            redirect.action === undefined
+                ? `retired; ${redirect.note ?? `use ${redirect.tool}`}`
+                : `retired; use ${redirect.tool} { action: "${redirect.action}" }`;
+    }
+    return tombstones;
+}
 /** The sentence handed to an agent that called `name`. */
 export function mergedNameMessage(name, redirect) {
     return redirect.action === undefined