@reticlehq/server 2.6.0 → 2.8.0

package/dist/tools/error-recovery.js

@@ -8,8 +8,9 @@
  * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
  * baseline stores). No clock, no IO — unit-testable in isolation.
  */
-import { TRANSPORT_LIMITS } from '@reticlehq/core';
+import { RefusalReason, TRANSPORT_LIMITS } from '@reticlehq/core';
 import { SELF_RECOVERING_MARKER } from '../session/no-session-diagnosis.js';
+import { chromiumInstallCommand, bundledPlaywrightVersion } from '../cli/chromium-hint.js';
 /** Marks where an over-long message had its middle removed. Named so tests assert it by value. */
 const ELISION = '… [elided] …';
 /**
@@ -41,17 +42,17 @@ function capMessage(message) {
  * the agent precisely what to do.
  */
 const SELF_RECOVERING = [
-    /cannot drive native input/i,
+    { match: /cannot drive native input/i, reason: RefusalReason.UNSUPPORTED },
     // The unknown-session refusal now lists the live ids inline. Appending "call reticle_sessions for
     // the current ids" to a message that just named them contradicts the shorter path it offers, and
     // a contradicted instruction is how one agent came to retry a dead id twelve times.
-    /Connected right now:/i,
+    { match: /Connected right now:/i, reason: RefusalReason.NO_SESSION },
 ];
 /** A message that already carries its own concrete next action, so nothing should be appended. */
 function isSelfRecovering(message) {
     if (message.includes(SELF_RECOVERING_MARKER))
         return true;
-    return SELF_RECOVERING.some((pattern) => pattern.test(message));
+    return SELF_RECOVERING.some((rule) => rule.match.test(message));
 }
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
 export const RECOVERY = {
@@ -129,9 +130,46 @@ export const RECOVERY = {
         'where it actually is. This is app/flow drift, which is exactly what the flow exists to catch.',
     NO_POOL: 'Reticle cannot launch its own browser here: the daemon-managed pool is absent, or Playwright ' +
         'has no Chromium installed (the message above says which). Run Reticle via `reticle mcp`, and ' +
-        'ask the human for `npx playwright install chromium` if that is what is missing. Meanwhile drive ' +
+        // Pinned to the bundled playwright: the unpinned command installs a revision this daemon never
+        // looks at, so the human runs it, it succeeds, and nothing changes.
+        'ask the human for `' +
+        chromiumInstallCommand(bundledPlaywrightVersion()) +
+        '` if that is what is missing. Meanwhile drive ' +
         'a tab the human already has open — reticle_sessions lists them.',
 };
+/**
+ * Which OWNER each recovery belongs to, for `tool_refused`.
+ *
+ * A `Record` over the recovery keys rather than a second table of patterns, and that is the point:
+ * adding a recovery without classifying it does not compile. A parallel regex list would have been
+ * correct on the day it was written and silently wrong at the next addition — the drift that has
+ * already cost this repo a published number twice, and telemetry drift is not recoverable after the
+ * fact.
+ */
+const REASON_OF = {
+    NO_SESSION: RefusalReason.NO_SESSION,
+    MULTIPLE_SESSIONS: RefusalReason.NO_SESSION,
+    UNKNOWN_SESSION: RefusalReason.NO_SESSION,
+    SCOPE_MISMATCH: RefusalReason.NO_SESSION,
+    SESSION_GONE: RefusalReason.NO_SESSION,
+    THROTTLED: RefusalReason.NOT_READY,
+    COMMAND_TIMEOUT: RefusalReason.NOT_READY,
+    NO_POOL: RefusalReason.NOT_READY,
+    TOKEN_REQUIRED: RefusalReason.NOT_READY,
+    MISSING_BASELINE: RefusalReason.NO_MATCH,
+    MISSING_RECORDING: RefusalReason.NO_MATCH,
+    STALE_REF: RefusalReason.NO_MATCH,
+    NO_SUCH_OPTION: RefusalReason.NO_MATCH,
+    FLOW_STEP_MISSING: RefusalReason.NO_MATCH,
+    UNSUPPORTED_SURFACE: RefusalReason.UNSUPPORTED,
+    NOT_EDITABLE: RefusalReason.UNSUPPORTED,
+    CONFIRM_DANGEROUS: RefusalReason.UNSUPPORTED,
+    WRONG_TARGET: RefusalReason.UNSUPPORTED,
+    BAD_ARGUMENTS: RefusalReason.BAD_ARGS,
+    INVALID_NAME: RefusalReason.BAD_ARGS,
+};
+/** Hint text back to its reason. The hints are distinct strings, so this inverts cleanly. */
+const REASON_BY_HINT = new Map(Object.entries(RECOVERY).map(([key, hint]) => [hint, REASON_OF[key]]));
 /** Ordered match rules; the first hit wins. Substrings track the thrown messages they recover. */
 const RULES = [
     { match: /no browser session connected/i, hint: RECOVERY.NO_SESSION },
@@ -211,6 +249,33 @@ export function recoveryFor(message) {
     }
     return undefined;
 }
+/**
+ * WHY a tool refused, as one of the six buckets in core's `RefusalReason`.
+ *
+ * Reads the SAME rules `buildErrorPayload` reads, in the same order, so the reason we report and the
+ * advice the agent got can never describe different things. Anything unrecognised is `other`, which
+ * is the bucket that says the classifier has a blind spot — and a growing `other` is a finding about
+ * this table rather than about anybody's app.
+ */
+export function refusalReasonFor(rawMessage) {
+    const message = zodArrayAsSentence(rawMessage);
+    // The no-session diagnosis inspected the machine and named the cause itself, so it never reaches
+    // the recovery table. It is the single largest refusal there is; missing it would gut the metric.
+    if (message.includes(SELF_RECOVERING_MARKER))
+        return RefusalReason.NO_SESSION;
+    for (const rule of SELF_RECOVERING) {
+        if (rule.match.test(message))
+            return rule.reason;
+    }
+    // Same order as buildErrorPayload: a schema rejection is the agent's own call, whatever else in
+    // the message might also match.
+    if (ARGUMENT_REJECTION.test(message))
+        return RefusalReason.BAD_ARGS;
+    if (INVALID_NAME_REJECTION.test(message))
+        return RefusalReason.BAD_ARGS;
+    const hint = recoveryFor(message);
+    return (hint === undefined ? undefined : REASON_BY_HINT.get(hint)) ?? RefusalReason.OTHER;
+}
 /**
  * A schema rejection: the call named a parameter that does not exist, or gave one the wrong type.
  *

package/dist/tools/feedback-invite.js

@@ -38,7 +38,7 @@ export const FrictionKind = {
 const REPEAT_INVITE_AT = 3;
 const LINES = {
     [FrictionKind.UNKNOWN_TOOL]: 'no such tool — reticle_feedback tells us what you expected it to do, which is how it gets built',
-    [FrictionKind.UNKNOWN_VERDICT]: 'Reticle could not tell what happened here. If you expected otherwise, reticle_feedback — an ' +
+    [FrictionKind.UNKNOWN_VERDICT]: 'Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An ' +
         'unknown verdict is our defect, not yours',
     [FrictionKind.REPEATING]: 'stuck on the same call? reticle_feedback — say what you were trying to do and it gets fixed',
     [FrictionKind.REFUSED]: 'if that diagnosis was wrong or unhelpful, reticle_feedback — error messages are a product ' +

package/dist/tools/invoke-tool.js

@@ -6,11 +6,16 @@ import { takeUpdateNudge } from '../update/update-nudge.js';
 import { takeVersionSkew } from '../version/version-nudge.js';
 import { noteToolCall } from '../daemon/daemon-usefulness.js';
 import { bugsInResult } 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 { EnvelopeKey } from './tool-kit.js';
 import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
+import { noteRefsMinted, wrongTabRefusal } from '../session/ref-provenance.js';
 import { span } from '../trace.js';
 import { frictionOf, inviteFor } from './feedback-invite.js';
 /**
@@ -29,6 +34,20 @@ const ACTION_TOOLS = new Set([
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
 ]);
+/**
+ * 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.
+ *
+ * Over-inclusion is the safe direction here and under-inclusion is not dangerous either: both ends
+ * produce a REFUSAL naming the two tabs, never a silent drive against the wrong one.
+ */
+const REF_MINTING_TOOLS = new Set([
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.EXPLORE,
+    ReticleTool.CRAWL,
+]);
 export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
@@ -133,6 +152,54 @@ function reportBugsFound(toolName, result) {
         });
     }
 }
+/**
+ * Report a refused call, at the one place both dispatch paths cross.
+ *
+ * A refusal arrives two ways and they are the same event: the handler THROWS (the common case — no
+ * session, a stale ref, a schema rejection), or it RETURNS `{ error }`, which is this codebase's
+ * refusal convention and just as much a refusal. Both are classified by the same table the agent's
+ * recovery advice comes from, so the reason we record and the advice it got cannot describe
+ * different things.
+ *
+ * `reticle_run` is skipped for the same reason `bugsInResult` skips it: it is a WRAPPER whose
+ * handler calls `runTool` on the real tool, which already reported that refusal under the real
+ * tool's name, and then hands the same failure back out to be reported a second time as
+ * `reticle_run`. A count that doubles because of HOW a tool was reached is not a measurement.
+ */
+function reportRefusal(toolName, message) {
+    if (toolName === ReticleTool.RUN)
+        return;
+    reportToolRefused(toolName, refusalReasonFor(message));
+}
+/**
+ * Which friction this result represents, counting the invitation if there is one.
+ *
+ * Feedback is the highest-yield channel this product has, and `feedbackPrompted` is the denominator
+ * that says whether inviting mid-task works or is decoration. It read as near-empty because the
+ * count sat behind the session-bound early return, so a session-EXEMPT tool never invited and a tool
+ * that THREW never got there — and a throw is the commonest refusal there is.
+ *
+ * `reticle_run` is skipped for the same reason it is skipped for refusals and defects: the wrapper's
+ * handler calls `runTool` on the real tool, which already invited under the real tool's name, and
+ * the failure is then handed back out to be counted a second time. A doubled denominator makes the
+ * feedback rate read half.
+ */
+function frictionInviteFor(toolName, raw) {
+    if (!isPlainObject(raw) || toolName === ReticleTool.RUN)
+        return undefined;
+    const friction = frictionOf({
+        unknownTool: false,
+        verifiedUnknown: 'unknown' === raw['verified'],
+        repeatRun: getSessionMetrics().currentRun,
+        errored: resultIsError(raw),
+        // A verdict is progress. Without this, three successful act_and_wait calls in a row — the exact
+        // loop this release exists to encourage — get told they are stuck.
+        producedVerdict: 'verified' in raw,
+    });
+    if (friction !== undefined)
+        getSessionMetrics().recordFeedbackPrompt();
+    return friction;
+}
 /**
  * The single entry point both the MCP server and the programmatic invoker call instead of
  * `tool.handler` directly. Runs the handler, then — for a live-session tool returning a plain
@@ -188,11 +255,13 @@ export async function runTool(tool, deps, args) {
     // prevents: the agent learns its argument was too big, which is something it can fix.
     const oversized = firstOversizedArg(args);
     if (oversized !== undefined) {
-        return {
-            error: `argument '${oversized}' is larger than ${String(TRANSPORT_LIMITS.MAX_STRING_LENGTH)} ` +
-                'characters, which is the most Reticle moves in one call. Nothing ran. Send a smaller ' +
-                'value — a selector or an id rather than a document, or a slice of the text you need.',
-        };
+        const error = `argument '${oversized}' is larger than ${String(TRANSPORT_LIMITS.MAX_STRING_LENGTH)} ` +
+            'characters, which is the most Reticle moves in one call. Nothing ran. Send a smaller ' +
+            'value — a selector or an id rather than a document, or a slice of the text you need.';
+        // Refused before the handler was ever entered, and still a refusal the agent has to recover
+        // from. Reported here rather than at the return below, which this branch never reaches.
+        reportRefusal(tool.name, error);
+        return { error };
     }
     // An ACTION is what gets abandoned. Counted here, against verifications, so "the agent drove the
     // page and then wandered off" becomes a number instead of an impression.
@@ -217,6 +286,25 @@ export async function runTool(tool, deps, args) {
             session = undefined;
         }
     }
+    // A ref that was handed out by a DIFFERENT tab, on a call that named no session. Refused here, at
+    // the one point that knows both the ref and the tab resolution picked — the handler only learns
+    // that the ref missed, and answers that with "the DOM re-rendered", which is a confident diagnosis
+    // of the wrong thing. The other half is worse: the same ref can resolve to a different element in
+    // the guessed tab and return a green about a page nobody asked about.
+    if (session !== undefined) {
+        const wrongTab = wrongTabRefusal({
+            ref: asString(args['ref']),
+            explicitSessionId: rawSessionId,
+            chosenSessionId: session.id,
+            connected: () => deps.sessions.list(),
+        });
+        if (wrongTab !== undefined) {
+            // Refused before the handler was entered, so it is reported here — the same shape as the
+            // oversized-argument refusal above.
+            reportRefusal(tool.name, wrongTab);
+            return { error: wrongTab };
+        }
+    }
     const leaseId = session?.id ?? rawSessionId;
     if (leaseId !== undefined)
         deps.pool?.touch(leaseId);
@@ -227,6 +315,22 @@ export async function runTool(tool, deps, args) {
         // nests under it. Free when off — see trace.ts.
         raw = await span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, args));
     }
+    catch (error) {
+        // The commonest refusal shape by far, and the one nothing could see: the message is built, handed
+        // 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);
+        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
+        // is. Gated on the payload actually carrying the ask, because a recognised error gets a recovery
+        // instead and counting an invitation nobody was shown breaks the ratio in the other direction.
+        if (tool.name !== ReticleTool.RUN && buildErrorPayload(message).feedback !== undefined) {
+            getSessionMetrics().recordFeedbackPrompt();
+        }
+        throw error;
+    }
     finally {
         // In a `finally` so a THROWN call still settles: otherwise every failing tool would leak a
         // concurrency slot and peakConcurrentTools would climb forever on an unhealthy session.
@@ -243,6 +347,20 @@ export async function runTool(tool, deps, args) {
         recordVerification(tool.name, raw, Date.now() - startedAt, session?.brand);
         reportBugsFound(tool.name, raw);
     }
+    // The other half of the refusal surface. A top-level `error` string IS this codebase's refusal
+    // convention, so half the tools refuse by RETURNING one rather than throwing — and reading only the
+    // throw path would have measured half the wall and called it the whole of it, the same way `isError`
+    // once did. A call that was served clears the retry chain, so the next refusal after it is a first
+    // refusal rather than a retry of something unrelated.
+    if (resultIsError(raw))
+        reportRefusal(tool.name, raw.error);
+    else {
+        noteToolServed();
+        // Which tab these refs belong to. Recorded on the way OUT, so the next call that spends one is
+        // measured against the tab that actually produced it.
+        if (session !== undefined && REF_MINTING_TOOLS.has(tool.name))
+            noteRefsMinted(session.id);
+    }
     const prompt = isPlainObject(raw) ? takeFeedbackPrompt(tool.name) : undefined;
     // Same one-shot channel as the feedback ask: the agent is mid-task, so anything it would have to go
     // and ASK for is something it will never ask for. Spliced on ANY tool result, not just a
@@ -258,16 +376,32 @@ export async function runTool(tool, deps, args) {
     // report announced as accepted and then silently lost is the failure the awaited send existed to
     // prevent. See feedback-delivery.ts.
     const undelivered = isPlainObject(raw) ? takeFeedbackUndelivered() : undefined;
-    const result = prompt === undefined && update === undefined && skew === undefined && undelivered === undefined
+    // Invite feedback at the moment of friction, worded for what just happened. Counted, because
+    // `feedback_submitted / feedbackPrompted` is the only thing that says whether the invitation works
+    // at all rather than being decoration.
+    //
+    // This used to sit below the session-bound early return, which put it behind two conditions that
+    // exclude most friction there is. A session-EXEMPT tool never reached it, and neither did a tool
+    // that THREW — and throwing is the commonest refusal shape by a wide margin, i.e. exactly the
+    // `refused` friction the line is written for. `errored` could only ever see the handlers that
+    // RETURN an error. So the denominator was counting a small, unrepresentative slice of the
+    // invitations and reading near-empty, which looks identical to a nudge that never fires.
+    const friction = frictionInviteFor(tool.name, raw);
+    const result = prompt === undefined &&
+        update === undefined &&
+        skew === undefined &&
+        undelivered === undefined &&
+        friction === undefined
         ? raw
         : {
             ...raw,
-            ...(prompt !== undefined ? { feedback_prompt: prompt } : {}),
-            ...(update !== undefined ? { update_available: update } : {}),
-            ...(skew !== undefined ? { version_skew: skew } : {}),
+            ...(friction !== undefined ? { [EnvelopeKey.FEEDBACK_INVITE]: inviteFor(friction) } : {}),
+            ...(prompt !== undefined ? { [EnvelopeKey.FEEDBACK_PROMPT]: prompt } : {}),
+            ...(update !== undefined ? { [EnvelopeKey.UPDATE_AVAILABLE]: update } : {}),
+            ...(skew !== undefined ? { [EnvelopeKey.VERSION_SKEW]: skew } : {}),
             ...(undelivered !== undefined
                 ? {
-                    feedback_undelivered: `your earlier report did NOT send: ${undelivered}. Tell the human what you found so it is not lost.`,
+                    [EnvelopeKey.FEEDBACK_UNDELIVERED]: `your earlier report did NOT send: ${undelivered}. Tell the human what you found so it is not lost.`,
                 }
                 : {}),
         };
@@ -286,33 +420,16 @@ export async function runTool(tool, deps, args) {
     // one-time pool-lease reminder or the age cleanup nudge. Splice them regardless.
     const lease = resolved.takeSessionLease();
     if (lease !== undefined)
-        envelope['session_lease'] = lease;
+        envelope[EnvelopeKey.SESSION_LEASE] = lease;
     const warning = resolved.ageWarning();
     if (warning !== undefined)
-        envelope['session_age_warning'] = warning;
-    // Ask for a verdict when the agent has driven the page and not asked for one. 137 of the 140
-    // verdict-less sessions measured over 2026-08-10/11 never called a verdict-producing tool ONCE;
+        envelope[EnvelopeKey.SESSION_AGE_WARNING] = warning;
+    // Ask for a verdict when the agent has driven the page and not asked for one. Almost every
+    // verdict-less session in the field never called a verdict-producing tool ONCE;
     // the counter behind this already existed and was reported only to us. One-shot per abandoned
     // run, same discipline as the pool lease — a hint on every call is noise that gets tuned out.
     const unverified = getSessionMetrics().takeUnverifiedNudge();
     if (unverified !== undefined)
-        envelope['verify_next'] = unverified;
-    // Invite feedback at the moment of friction, worded for what just happened. Feedback produced
-    // ~11 of this release's fixes from 14 reports; the handshake instruction is what got those 14,
-    // and this closes the gap it leaves — the agent mid-problem, not thinking about feedback tooling.
-    // Counted so `feedback_submitted / feedbackPrompted` can tell us whether it works at all.
-    const friction = frictionOf({
-        unknownTool: false,
-        verifiedUnknown: 'unknown' === result.verified,
-        repeatRun: getSessionMetrics().currentRun,
-        errored: 'error' in result,
-        // A verdict is progress. Without this, three successful act_and_wait calls in a row — the exact
-        // loop this release exists to encourage — get told they are stuck.
-        producedVerdict: 'verified' in result,
-    });
-    if (friction !== undefined) {
-        envelope['feedback_invite'] = inviteFor(friction);
-        getSessionMetrics().recordFeedbackPrompt();
-    }
+        envelope[EnvelopeKey.VERIFY_NEXT] = unverified;
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }

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

@@ -20,6 +20,26 @@ export declare function appendReticleParams(url: string, session: string, projec
  * of an internals-leaking wall of text.
  */
 export declare function cleanNavError(err: unknown): 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;
 /**
  * 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
@@ -38,7 +58,15 @@ export declare function acquireLeasedSession(pool: {
         sessionId: string;
         release: () => Promise<void>;
     }>;
-}, hasSession: (id: string) => boolean, url: string, projectId?: string): Promise<{
+    /** Optional so a test double need not implement it; the real pool always does. */
+    alias?: (registeredId: string, leaseId: string) => void;
+}, sessions: {
+    get: (id: string) => unknown;
+    all: () => {
+        id: string;
+        url?: string;
+    }[];
+}, url: string, projectId?: string): Promise<{
     sessionId: string;
     release: () => Promise<void>;
 }>;

package/dist/tools/lease-tools.js

@@ -64,6 +64,34 @@ 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;
+}
+function sessionParamOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        return new URL(url).searchParams.get(RETICLE_URL_PARAM.SESSION) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const LEASE_READY_ATTEMPTS = 100;
 const LEASE_READY_POLL_MS = 100;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -78,11 +106,20 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
  * 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, hasSession, url, projectId) {
+export async function acquireLeasedSession(pool, sessions, url, projectId) {
     const sessionId = newLeaseId();
     const lease = await pool.acquire(appendReticleParams(url, sessionId, projectId), { sessionId });
-    await waitForLeasedSession(() => hasSession(lease.sessionId));
-    return { sessionId: lease.sessionId, release: () => lease.release() };
+    // Resolved, not assumed — see resolveLeasedSessionId. The parallel suite replays against whatever
+    // id comes back, so handing it the lease id for an app that named its own session sent every flow
+    // in the run at a session that does not exist.
+    let registeredId;
+    await waitForLeasedSession(() => {
+        registeredId = resolveLeasedSessionId(sessions, lease.sessionId);
+        return registeredId !== undefined;
+    });
+    if (registeredId !== undefined)
+        pool.alias?.(registeredId, lease.sessionId);
+    return { sessionId: registeredId ?? lease.sessionId, release: () => lease.release() };
 }
 export async function waitForLeasedSession(isConnected, sleeper = sleep, attempts = LEASE_READY_ATTEMPTS, pollMs = LEASE_READY_POLL_MS) {
     for (let i = 0; i < attempts; i++) {
@@ -111,6 +148,9 @@ export const LEASE_TOOLS = [
             ready: z
                 .boolean()
                 .describe('Whether the leased tab connected — false ⇒ the app may not embed @reticlehq/core.'),
+            expiresInMs: z
+                .number()
+                .describe('Milliseconds until this lease expires if untouched. Each tool call that targets this session resets the clock. Plan your work to finish or re-acquire before this runs out.'),
             leased: z.number().describe('How many contexts are currently leased from the pool.'),
             queued: z.number().describe('How many acquires are waiting for a free slot.'),
             hint: z.string().optional(),
@@ -135,11 +175,24 @@ export const LEASE_TOOLS = [
                 throw new Error(`could not open ${url} — is the app running there? (${cleanNavError(err)})`);
             }
             // Wait for the leased tab's SDK to connect so the returned sessionId is usable right away.
-            const ready = await waitForLeasedSession(() => deps.sessions.get(lease.sessionId) !== undefined);
+            // Resolved rather than assumed: an app that names its own session registers under that name,
+            // and the id we hand back has to be the one the agent can actually drive.
+            let registeredId;
+            const ready = await waitForLeasedSession(() => {
+                registeredId = resolveLeasedSessionId(deps.sessions, lease.sessionId);
+                return registeredId !== undefined;
+            });
+            // Tell the pool the other name this lease answers to. Every later touch and release arrives
+            // under the id we are about to hand back, and the pool is keyed by the id it navigated with;
+            // without this the touches miss, the lease ages out despite continuous activity, and the
+            // reaper closes the context mid-flow. See BrowserPool.alias and #157.
+            if (registeredId !== undefined)
+                pool.alias(registeredId, lease.sessionId);
             return {
-                sessionId: lease.sessionId,
+                sessionId: registeredId ?? lease.sessionId,
                 url,
                 ready,
+                expiresInMs: pool.leaseTtlMs(),
                 leased: pool.activeCount(),
                 queued: pool.queuedCount(),
                 ...(ready

package/dist/tools/navigate-result.js

@@ -30,7 +30,7 @@ arrival = null) {
     return {
         ...base,
         confirmed: false,
-        note: 'ok means the navigation was DISPATCHED, not that the page arrived — the SDK is torn down by ' +
+        note: 'ok means the navigation was DISPATCHED, not that the page arrived. The SDK is torn down by ' +
             'the navigation itself, so nothing here can see the new document. Call reticle_sessions to ' +
             'confirm a session reconnected at the new URL before acting; if none appears, the page did ' +
             'not load or is not instrumented.',

package/dist/tools/observe-tools.js

@@ -179,7 +179,7 @@ export const OBSERVE_TOOLS = [
             // never asked about.
             const actCursor = session.lastAct.cursor();
             const judgingTheAct = actCursor !== undefined && actCursor >= since;
-            const contradictions = findContradictions(filtered, judgingTheAct ? session.lastAct.effect() : {});
+            const contradictions = findContradictions(filtered, judgingTheAct ? { ...session.lastAct.effect(), actionSince: actCursor } : {});
             // carry session health — a throttled tab means the observed timeline may be incomplete.
             return withControl(session, {
                 ...report,

package/dist/tools/observed-nothing.js

@@ -28,6 +28,6 @@ export function noteEmptyRead(result, key, context) {
         ...result,
         // The distinction the field sweep could not make: this is a RESULT, not a failure to look.
         observed: true,
-        note: `no ${context.noun}${window} — the observation ran and found none, which is a result, not a missing reading`,
+        note: `no ${context.noun}${window}; the observation ran and found none, which is a result, not a missing reading`,
     };
 }

package/dist/tools/react-grace.d.ts

@@ -0,0 +1,48 @@
+/**
+ * "The app ignored this response" is only sayable once the app has had a chance to read it.
+ *
+ * `response-ignored` fires when a write succeeded on the server and nothing on the client moved. It
+ * is a real and valuable finding — a lost write, a response parsed into the void, a render that never
+ * happened. It is also an ACCUSATION, and it is decided by where a window happens to end.
+ *
+ * Waiting for in-flight requests before taking the verdict made that boundary dangerous in a way it
+ * was not before. Previously the write was still pending when the window closed, so it never reached
+ * the settled list and this rule could not fire at all. Now the response lands inside the window BY
+ * DESIGN — and the app's re-render happens in a later task, a few milliseconds after it. Close the
+ * window in that gap and every channel agrees that the app took a successful write and did nothing.
+ *
+ * The verdict is then `verified:"no"` on a completely correct application, produced entirely by where
+ * we chose to stop looking. For a verification tool that is the more damaging direction of error: a
+ * false green is a missed catch, but a false accusation sends someone to fix code that is not broken,
+ * and it is how the instrument stops being believed.
+ *
+ * So the response is not the end of the window — the app's REACTION to it is. The grace is paid only
+ * in the exact case that would otherwise be accused: a successful mutating write with nothing moved
+ * after it. Every other action returns without a single poll.
+ *
+ * Deliberately short. This covers a task-boundary re-render, not a slow app: if nothing has moved
+ * within the grace, "ignored" has become an honest description and the finding should stand.
+ */
+import type { SettleSource } from './settle-in-flight.js';
+/**
+ * Is this a window that would be wrongly accused if it ended right now?
+ *
+ * True only for the accusable shape: a SUCCESSFUL MUTATING request settled, and nothing has moved. A
+ * read that changed nothing is a prefetch, a failed write is a different finding entirely, and an
+ * action that already moved the UI has nothing to wait for — none of them buy a grace period.
+ */
+export declare function awaitsReaction(events: readonly {
+    type: string;
+    data: Record<string, unknown>;
+}[]): boolean;
+/**
+ * Wait, bounded by BOTH the grace and the caller's remaining budget, for the app to react to a write
+ * it has just been told succeeded.
+ *
+ * Returns whether the app moved. A `false` is not a verdict — it hands the question back to the
+ * contradiction engine, which will raise `response-ignored` exactly as it does today. The point is
+ * only that by then the app has been given its chance, so the finding means what it says.
+ */
+export declare function waitForReaction(session: SettleSource, since: number, budgetMs: number, opts: {
+    sleep(ms: number): Promise<void>;
+}): Promise<boolean>;