@reticlehq/server 2.4.0 → 2.6.0

package/dist/tools/invoke-tool.js

@@ -1,19 +1,34 @@
 import { healthEnvelope } from '../session/session-health.js';
-import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
-import { VERIFICATION_TOOLS } from './feedback-tools.js';
 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 { verificationOf } from '../telemetry/verification-of.js';
 import { asString } from './tools-helpers.js';
 import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
+import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
+import { span } from '../trace.js';
+import { frictionOf, inviteFor } from './feedback-invite.js';
 /**
  * The live-session tools whose result MUST carry the
  * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
  * can never return a healthy-looking result from any of these. `runTool` is the single choke point
  * (mcp.ts + tool-invoker.ts) that splices health on; the guard test asserts the set is exhaustive.
  */
+/**
+ * Tools that DRIVE the page. An action with no verdict after it is the signature of the loop
+ * breaking mid-task — see `abandonedActions`. `act_and_wait` is one of these AND a verification, so
+ * it settles its own action, which is exactly right: it is the tool that does both.
+ */
+const ACTION_TOOLS = new Set([
+    ReticleTool.ACT,
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.ACT_AND_WAIT,
+]);
 export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
@@ -72,44 +87,27 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.FEEDBACK,
 ]);
 function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return 'object' === typeof value && value !== null && !Array.isArray(value);
 }
 /**
  * Emit `verification_completed` when a verification tool produced a verdict.
  *
  * Read off the RESULT here rather than emitted from `decideVerified`, which is where the verdict is
  * actually decided: that function is pure, and the repo's rules keep clocks, IO and side effects out
- * of pure logic for good reason. Reading the result also means all four verification tools are covered
- * by one site instead of four handler edits, and a fifth is covered the moment it joins the set.
+ * of pure logic for good reason. Reading the result also means all the verification tools are covered
+ * by one site instead of N handler edits, and the next one is covered the moment it joins the set.
  *
- * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
- * it verified. That is the product's entire thesis reduced to a boolean, and it is the number worth
- * putting in front of an investor — not "tools were called" but "this many greens were caught lying".
+ * The RULE itself lives in verification-of.ts, because getting it wrong is silent and it feeds the
+ * one number shown to investors — see that file for the two ways it was wrong.
  */
-function recordVerification(toolName, result, durationMs) {
-    if (!VERIFICATION_TOOLS.has(toolName))
+function recordVerification(toolName, result, durationMs, brand) {
+    const verification = verificationOf(toolName, result, durationMs, brand);
+    if (verification === undefined)
         return;
-    const verified = typeof result['verified'] === 'string' ? result['verified'] : undefined;
-    // flow_verify reports `status: pass|fail`; assert reports a boolean `pass`. Accept either shape so
-    // the whole family is covered without normalizing four tools' contracts for a metric's convenience.
-    const passed = typeof result['pass'] === 'boolean'
-        ? result['pass']
-        : result['status'] === 'pass'
-            ? true
-            : undefined;
-    if (verified === undefined && passed === undefined)
-        return; // not a verdict-bearing result
-    const metrics = getSessionMetrics();
-    metrics.recordVerification();
+    getSessionMetrics().recordVerification();
     void getTelemetry().emit(TelemetryEventKind.VERIFICATION_COMPLETED, {
         actor: TelemetryActor.AGENT,
-        verification: {
-            via: toolName,
-            verified: verified ?? (passed === true ? 'yes' : 'no'),
-            passed: passed ?? verified === 'yes',
-            falseGreenCaught: passed === true && verified === 'no',
-            durationMs,
-        },
+        verification,
     });
 }
 /**
@@ -121,7 +119,7 @@ function recordVerification(toolName, result, durationMs) {
  */
 function reportBugsFound(toolName, result) {
     const bugs = bugsInResult(toolName, result);
-    if (bugs.length === 0)
+    if (0 === bugs.length)
         return;
     const metrics = getSessionMetrics();
     for (const bug of bugs) {
@@ -141,6 +139,27 @@ function reportBugsFound(toolName, result) {
  * object that did not already include `session` — splices the health envelope on. Idempotent
  * (handlers that already add health are left untouched) and never alters non-object results.
  */
+/**
+ * The name of the first argument whose string value exceeds the transport bound, if any.
+ *
+ * One level of nesting is searched because that is where callers put payloads — `reticle_act`'s
+ * `args.value`, and the fuzz's own `huge-string` shape. Deeper recursion would cost more than it
+ * buys: the failure is a single huge string, not a deeply nested structure of small ones.
+ */
+function firstOversizedArg(args) {
+    const tooLong = (value) => 'string' === typeof value && value.length > TRANSPORT_LIMITS.MAX_STRING_LENGTH;
+    for (const [key, value] of Object.entries(args)) {
+        if (tooLong(value))
+            return key;
+        if ('object' === typeof value && null !== value && !Array.isArray(value)) {
+            for (const [inner, nested] of Object.entries(value)) {
+                if (tooLong(nested))
+                    return `${key}.${inner}`;
+            }
+        }
+    }
+    return undefined;
+}
 export async function runTool(tool, deps, args) {
     // Both dispatch paths (MCP + programmatic) pass through here — the one place "which tool is mostly
     // used" can be counted. This used to EMIT an event per call; it now increments an in-process counter
@@ -151,6 +170,34 @@ export async function runTool(tool, deps, args) {
     // Started/settled as a pair rather than a bare counter: several agents can be inside runTool at
     // once, so a single "last start" field would attribute one tool's duration to another. The returned
     // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
+    // A daemon that has served even one tool call is doing a job for somebody; see daemon-usefulness.
+    noteToolCall();
+    // An oversized argument is refused BEFORE the handler deserialises it.
+    //
+    // tool-fuzz failed CI on the invariant that matters most — `every tool answers every hostile call`
+    // — for a ~100KB string. Seen twice with different tools; the earlier one came back
+    // `-32001 sse_aborted` with the tool surface dropping 48→17, which is a RESTARTED daemon. The
+    // shape is: oversized argument → the daemon dies → the proxy answers the in-flight call with
+    // transport loss, and the next assertion is talking to a different daemon.
+    //
+    // `TRANSPORT_LIMITS.MAX_STRING_LENGTH` already bounds what crosses the bridge; a tool argument
+    // arrives over MCP stdio and never met it. Here, because this is the one place every invocation
+    // routes through, so a tool added later inherits the bound instead of having to remember it.
+    //
+    // A refusal is a normal answer. An UNANSWERED call is a hung agent, and that is the failure this
+    // 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.',
+        };
+    }
+    // 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.
+    if (ACTION_TOOLS.has(tool.name))
+        getSessionMetrics().recordAction();
     const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
     const startedAt = Date.now();
     const rawSessionId = asString(args['sessionId']);
@@ -175,7 +222,10 @@ export async function runTool(tool, deps, args) {
         deps.pool?.touch(leaseId);
     let raw;
     try {
-        raw = await tool.handler(deps, args);
+        // The one dispatch point every tool call passes through, so it is where the trace's root span
+        // belongs: with RETICLE_TRACE on, every stage that runs underneath inherits this call's id and
+        // nests under it. Free when off — see trace.ts.
+        raw = await span('tool.handler', { tool: tool.name, session: session?.id }, () => tool.handler(deps, args));
     }
     finally {
         // In a `finally` so a THROWN call still settles: otherwise every failing tool would leak a
@@ -187,7 +237,10 @@ export async function runTool(tool, deps, args) {
     // session-bound early return, because two of the four verification tools (flow_verify,
     // verify_change) are session-EXEMPT and would otherwise never carry it.
     if (isPlainObject(raw)) {
-        recordVerification(tool.name, raw, Date.now() - startedAt);
+        // The brand comes from the session's own PAGE_HEALTH report, so it is present for the four
+        // session-bound verification tools and absent for flow_verify (session-exempt) — which replays
+        // into a browser Reticle launched, where `browser` already says what happened.
+        recordVerification(tool.name, raw, Date.now() - startedAt, session?.brand);
         reportBugsFound(tool.name, raw);
     }
     const prompt = isPlainObject(raw) ? takeFeedbackPrompt(tool.name) : undefined;
@@ -195,12 +248,28 @@ export async function runTool(tool, deps, args) {
     // and ASK for is something it will never ask for. Spliced on ANY tool result, not just a
     // verification, because an out-of-date install is worth mentioning whatever the agent is doing.
     const update = isPlainObject(raw) ? takeUpdateNudge() : undefined;
-    const result = prompt === undefined && update === undefined
+    // Same one-shot channel, for the same reason. Skew was only ever reported in
+    // reticle_sessions.versionSkew and a CLI log line — two places an agent driving a flow never
+    // looks — so it could work a whole session against a mismatched pair and never learn the one fact
+    // that explains the behaviour. It rides out here on whatever tool it happens to be calling.
+    const skew = isPlainObject(raw) ? takeVersionSkew() : undefined;
+    // A feedback report that was accepted and then failed to send. Same one-shot channel, because the
+    // reporter is the only person who can act on it and they are not reading the daemon log — and a
+    // 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
         ? raw
         : {
             ...raw,
             ...(prompt !== undefined ? { feedback_prompt: prompt } : {}),
             ...(update !== undefined ? { update_available: update } : {}),
+            ...(skew !== undefined ? { 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.`,
+                }
+                : {}),
         };
     if (!bound || !isPlainObject(result))
         return result;
@@ -221,5 +290,29 @@ export async function runTool(tool, deps, args) {
     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;
+    // 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();
+    }
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }

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

@@ -0,0 +1,17 @@
+/**
+ * Why a leased tab did not dial in.
+ *
+ * The lease pool opens the app itself, which is what makes it the highest-value path in the product
+ * — it does not wait for the human's tab. Measured over a day: lease sessions had a median of 30
+ * tool calls and produced 46% of all bugs found, against a median of 1 call for everything else.
+ *
+ * When it fails it is almost always a PORT MISMATCH: the tab loads, and the app's SDK dials the port
+ * it was BUILT with, which need not be the daemon that issued the lease. Verified by driving it —
+ * against a matching daemon `acquire` returns ready:true and the session is driveable immediately;
+ * against a different one the tab connects to the OTHER daemon instead.
+ *
+ * The old hint asked "is <url> running with @reticlehq/core enabled?", which is the one thing that
+ * cannot be in doubt: the pool just navigated a real browser to it. Naming the true cause first is
+ * the difference between a two-minute fix and abandoning the best path Reticle has.
+ */
+export declare function leaseNotConnectedHint(url: string, port: number): string;

package/dist/tools/lease-hint.js

@@ -0,0 +1,24 @@
+/**
+ * Why a leased tab did not dial in.
+ *
+ * The lease pool opens the app itself, which is what makes it the highest-value path in the product
+ * — it does not wait for the human's tab. Measured over a day: lease sessions had a median of 30
+ * tool calls and produced 46% of all bugs found, against a median of 1 call for everything else.
+ *
+ * When it fails it is almost always a PORT MISMATCH: the tab loads, and the app's SDK dials the port
+ * it was BUILT with, which need not be the daemon that issued the lease. Verified by driving it —
+ * against a matching daemon `acquire` returns ready:true and the session is driveable immediately;
+ * against a different one the tab connects to the OTHER daemon instead.
+ *
+ * The old hint asked "is <url> running with @reticlehq/core enabled?", which is the one thing that
+ * cannot be in doubt: the pool just navigated a real browser to it. Naming the true cause first is
+ * the difference between a two-minute fix and abandoning the best path Reticle has.
+ */
+export function leaseNotConnectedHint(url, port) {
+    return (`the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}). The usual ` +
+        `cause is a PORT MISMATCH: the app's SDK connects to the port it was BUILT with, so a daemon on ` +
+        `a different port never hears from it — check the app's reticle port (\`.reticle.json\`, ` +
+        `RETICLE_PORT, or the build plugin's \`port\`) matches ${String(port)}, or start the daemon on ` +
+        `the port the app expects. If the app carries no Reticle SDK at all, run \`reticle init\` in it ` +
+        `first. The tab stays leased either way — release it with reticle_lease{action:"release"}.`);
+}

package/dist/tools/lease-tools.js

@@ -9,7 +9,8 @@
  * Attach-only: the pool drives a browser against an already-running dev server — it never starts one.
  */
 import { z } from 'zod';
-import { RETICLE_URL_PARAM } from '@reticlehq/core';
+import { leaseNotConnectedHint } from './lease-hint.js';
+import { RETICLE_URL_PARAM, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { asString } from './tools-helpers.js';
 const POOL_UNAVAILABLE = 'browser pool unavailable — the lease tools need the daemon-managed pool (start Reticle via `reticle mcp`).';
@@ -58,7 +59,7 @@ export function cleanNavError(err) {
 }
 /** A fresh, collision-resistant lease id. Uses crypto at the I/O boundary (not pure logic). */
 function newLeaseId() {
-    const uuid = typeof globalThis.crypto?.randomUUID === 'function'
+    const uuid = 'function' === typeof globalThis.crypto?.randomUUID
         ? globalThis.crypto.randomUUID()
         : `${String(Date.now())}-${String(performance.now())}`;
     return `lease-${uuid}`;
@@ -119,7 +120,7 @@ export const LEASE_TOOLS = [
             if (pool === undefined)
                 throw new Error(POOL_UNAVAILABLE);
             const url = asString(args['url']);
-            if (url === undefined || url.length === 0)
+            if (url === undefined || 0 === url.length)
                 throw new Error('reticle_lease{action:"acquire"} requires a url');
             const projectId = asString(args['projectId']);
             const sessionId = newLeaseId();
@@ -144,7 +145,7 @@ export const LEASE_TOOLS = [
                 ...(ready
                     ? {}
                     : {
-                        hint: `leased tab did not connect — is ${url} running with @reticlehq/core enabled?`,
+                        hint: leaseNotConnectedHint(url, deps.bridgePort ?? RETICLE_DEFAULT_PORT),
                     }),
             };
         },
@@ -166,7 +167,7 @@ export const LEASE_TOOLS = [
             if (pool === undefined)
                 throw new Error(POOL_UNAVAILABLE);
             const sessionId = asString(args['sessionId']);
-            if (sessionId === undefined || sessionId.length === 0) {
+            if (sessionId === undefined || 0 === sessionId.length) {
                 throw new Error('reticle_lease{action:"release"} requires a sessionId');
             }
             await pool.release(sessionId);

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

@@ -16,11 +16,13 @@ import type { ToolDef } from './tool-kit.js';
  * like flow_replay/flow_verify/flow_heal that return their own documented verdict shapes — are NOT
  * merged. Only sibling families whose value is the capability, not the contract, are consolidated.
  */
-export interface MergeSpec {
+interface MergeSpec {
     name: string;
     description: string;
     /** action value → the original tool whose handler serves it. */
     actions: Record<string, ToolDef>;
+    /** A concrete call, carried through to the merged def (see ToolDef.example). */
+    example?: Record<string, unknown>;
 }
 /** A merge declared by member NAME, resolved against the assembled tool list. */
 export interface MergePlan {
@@ -28,6 +30,12 @@ export interface MergePlan {
     description: string;
     /** action value → the existing tool name whose handler serves it. */
     members: Record<string, string>;
+    /**
+     * A concrete call for the merged tool. Merging discards the members' own examples — the schema is
+     * a union and theirs are per-member — so a merged tool that reaches the core surface has no
+     * example at all unless the plan states one.
+     */
+    example?: Record<string, unknown>;
 }
 /**
  * Apply the consolidation to an assembled tool list: drop each plan's members and each retired name from
@@ -40,3 +48,4 @@ export interface MergePlan {
  */
 export declare function applyMerges(tools: readonly ToolDef[], plans: readonly MergePlan[], retired?: readonly string[]): ToolDef[];
 export declare function mergeTools(spec: MergeSpec): ToolDef;
+export {};

package/dist/tools/merge-tools.js

@@ -33,17 +33,23 @@ export function applyMerges(tools, plans, retired = []) {
             actions[action] = member;
             consumed.add(memberName);
         }
-        merged.push(mergeTools({ name: plan.name, description: plan.description, actions }));
+        merged.push(mergeTools({
+            name: plan.name,
+            description: plan.description,
+            actions,
+            ...(plan.example === undefined ? {} : { example: plan.example }),
+        }));
     }
     return [...tools.filter((t) => !consumed.has(t.name)), ...merged];
 }
 export function mergeTools(spec) {
     const actionNames = Object.keys(spec.actions);
-    if (actionNames.length === 0)
+    if (0 === actionNames.length)
         throw new Error(`mergeTools(${spec.name}): no actions`);
     return {
         name: spec.name,
         description: spec.description,
+        ...(spec.example === undefined ? {} : { example: spec.example }),
         inputSchema: {
             action: z
                 .enum(actionNames)
@@ -52,7 +58,7 @@ export function mergeTools(spec) {
         },
         handler: (deps, args) => {
             const action = args['action'];
-            const chosen = typeof action === 'string' ? spec.actions[action] : undefined;
+            const chosen = 'string' === typeof action ? spec.actions[action] : undefined;
             if (chosen === undefined) {
                 return Promise.resolve({
                     error: `unknown action '${String(action)}' for ${spec.name}`,

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

@@ -0,0 +1,13 @@
+interface MergedNameRedirect {
+    /** The tool to call instead. */
+    tool: string;
+    /** The action that selects the old behaviour, when the name was merged rather than retired. */
+    action?: string;
+    /** Why there is no direct replacement, for a retired name. */
+    note?: string;
+}
+/** Where `name` went, or undefined when it is a live tool or not ours. */
+export declare function mergedNameRedirect(name: string): MergedNameRedirect | undefined;
+/** 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

@@ -0,0 +1,55 @@
+/**
+ * Where a merged or retired tool's old name went.
+ *
+ * Twenty-two names exported from `ReticleTool` are no longer tools: `reticle_record_start` became
+ * `reticle_record { action: "start" }`, `reticle_diff` became `reticle_baseline { action: "diff" }`,
+ * and three were retired outright. Confirmed live in a field sweep, they all answered `unknown tool`
+ * — which is the wrong answer, because the capability exists and only moved. An agent trained on an
+ * earlier release, or reading the merged tool's own description (which names every action), reaches
+ * for exactly these.
+ *
+ * DERIVED from `MERGE_PLANS` and `RETIRED_FROM_SURFACE` rather than written out, so the next merge is
+ * covered the day it lands instead of the day someone notices.
+ */
+import { MERGE_PLANS, RETIRED_FROM_SURFACE } from './tools.js';
+import { ReticleTool } from './tool-names.js';
+/** Retired names, and where the capability actually lives now. */
+const RETIRED_NOTE = {
+    [ReticleTool.REFRESH]: {
+        tool: ReticleTool.NAVIGATE,
+        note: 'reloading was absorbed into reticle_navigate { reload: true }',
+    },
+    [ReticleTool.RUN_RECORD]: {
+        tool: ReticleTool.PROJECT,
+        note: 'run outcomes are persisted automatically by reticle_flow_replay; read them with reticle_project',
+    },
+    [ReticleTool.WAIT_READY]: {
+        tool: ReticleTool.SESSIONS,
+        note: 'waiting is implicit — the first live call already blocks until the session is ready',
+    },
+};
+const BY_OLD_NAME = (() => {
+    const map = new Map();
+    for (const plan of MERGE_PLANS) {
+        for (const [action, oldName] of Object.entries(plan.members)) {
+            map.set(oldName, { tool: plan.name, action });
+        }
+    }
+    for (const name of RETIRED_FROM_SURFACE) {
+        const known = RETIRED_NOTE[name];
+        if (known !== undefined)
+            map.set(name, known);
+    }
+    return map;
+})();
+/** Where `name` went, or undefined when it is a live tool or not ours. */
+export function mergedNameRedirect(name) {
+    return BY_OLD_NAME.get(name);
+}
+/** The sentence handed to an agent that called `name`. */
+export function mergedNameMessage(name, redirect) {
+    return redirect.action === undefined
+        ? `${name} no longer exists — ${redirect.note ?? `use ${redirect.tool}`}.`
+        : `${name} was merged into ${redirect.tool}. Call ${redirect.tool} { action: "${redirect.action}", ... } — ` +
+            `through reticle_run if it is not advertised under this profile.`;
+}

package/dist/tools/navigate-arrival.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Wait, briefly, for the SDK to reconnect after a navigation — so `confirmed` can mean something.
+ *
+ * `window.location.assign(url)` destroys the SDK that would report on the new document, so the
+ * navigation itself cannot be confirmed from inside the page. But the SDK reconnects TO THE DAEMON,
+ * which makes the daemon the only party that can see arrival happen. Before this, it did not look,
+ * and told the agent to poll `reticle_sessions` instead — a tool call on every navigation, on the
+ * least reliable tool we ship.
+ *
+ * Bounded and best-effort by construction: a navigation to a page that is not instrumented, or not
+ * there at all, must still return promptly with `confirmed:false` rather than hanging. The clock and
+ * the sleep are injected so this is testable without waiting on a real one.
+ */
+import type { SessionManager } from '../session/session-manager.js';
+import type { NavigateArrival } from './navigate-result.js';
+/** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
+export declare const ARRIVAL_TIMEOUT_MS = 5000;
+export interface ArrivalClock {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+/**
+ * Poll until a session is present at `target`, or the budget runs out. Returns `null` on timeout —
+ * never throws, because a failure to confirm is a legitimate answer, not an error.
+ */
+export declare function awaitArrival(sessions: SessionManager, target: string, timeoutMs?: number, clock?: ArrivalClock): Promise<NavigateArrival | null>;

package/dist/tools/navigate-arrival.js

@@ -0,0 +1,60 @@
+/**
+ * Wait, briefly, for the SDK to reconnect after a navigation — so `confirmed` can mean something.
+ *
+ * `window.location.assign(url)` destroys the SDK that would report on the new document, so the
+ * navigation itself cannot be confirmed from inside the page. But the SDK reconnects TO THE DAEMON,
+ * which makes the daemon the only party that can see arrival happen. Before this, it did not look,
+ * and told the agent to poll `reticle_sessions` instead — a tool call on every navigation, on the
+ * least reliable tool we ship.
+ *
+ * Bounded and best-effort by construction: a navigation to a page that is not instrumented, or not
+ * there at all, must still return promptly with `confirmed:false` rather than hanging. The clock and
+ * the sleep are injected so this is testable without waiting on a real one.
+ */
+/** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
+export const ARRIVAL_TIMEOUT_MS = 5_000;
+const POLL_MS = 100;
+/**
+ * Compare only origin + pathname.
+ *
+ * The app is entitled to add or rewrite the query and hash on arrival — a redirect to
+ * `?redirect=%2F`, a router normalising a trailing slash, an auth guard appending a reason. Matching
+ * the whole URL string would report `confirmed:false` for a navigation that plainly succeeded, which
+ * is the same lie in the opposite direction.
+ */
+function samePage(a, b) {
+    try {
+        const x = new URL(a);
+        const y = new URL(b);
+        return x.origin === y.origin && x.pathname.replace(/\/$/, '') === y.pathname.replace(/\/$/, '');
+    }
+    catch {
+        return false;
+    }
+}
+function findArrival(sessions, target) {
+    for (const s of sessions.all()) {
+        if (samePage(s.url, target))
+            return { sessionId: s.id };
+    }
+    return null;
+}
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * Poll until a session is present at `target`, or the budget runs out. Returns `null` on timeout —
+ * never throws, because a failure to confirm is a legitimate answer, not an error.
+ */
+export async function awaitArrival(sessions, target, timeoutMs = ARRIVAL_TIMEOUT_MS, clock = REAL_CLOCK) {
+    const deadline = clock.now() + timeoutMs;
+    for (;;) {
+        const found = findArrival(sessions, target);
+        if (found !== null)
+            return found;
+        if (clock.now() >= deadline)
+            return null;
+        await clock.sleep(POLL_MS);
+    }
+}

package/dist/tools/navigate-result.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The honest envelope for a navigation nobody can confirm.
+ *
+ * `window.location.assign(url)` returns before the page moves, and the SDK that would report on the
+ * new document is destroyed by the navigation itself. So a successful NAVIGATE means the browser
+ * accepted the instruction — not that anything arrived. Driven against a dead URL it returned
+ * `{"ok":true}` while the session died, which is the worst combination available: the agent believes
+ * it navigated, is looking at nothing, and has lost Reticle.
+ *
+ * `reticle_act` already draws this line — `dispatched` (sent) versus `settled` (a frame flushed).
+ * This gives navigate the same honesty without changing what it does.
+ */
+/** The session the SDK reconnected as after the page moved, when one was observed in the window. */
+export interface NavigateArrival {
+    sessionId: string;
+}
+export declare function navigateResult(result: {
+    ok?: unknown;
+    url?: unknown;
+    reason?: unknown;
+}, 
+/**
+ * Arrival, if the daemon saw the SDK come back. `null` keeps the original honest envelope.
+ *
+ * Measured on three fixtures: `confirmed` was `false` on every navigation on every app, because
+ * nothing ever set it. A boolean that never varies teaches an agent nothing, and an agent that
+ * learns to ignore it will keep ignoring it when it starts meaning something. The daemon is the
+ * one place that CAN answer this — the SDK reconnects to it — so making it answer removes a
+ * `reticle_sessions` poll from every single navigation.
+ */
+arrival?: NavigateArrival | null): Record<string, unknown>;

package/dist/tools/navigate-result.js

@@ -0,0 +1,38 @@
+export function navigateResult(result, 
+/**
+ * Arrival, if the daemon saw the SDK come back. `null` keeps the original honest envelope.
+ *
+ * Measured on three fixtures: `confirmed` was `false` on every navigation on every app, because
+ * nothing ever set it. A boolean that never varies teaches an agent nothing, and an agent that
+ * learns to ignore it will keep ignoring it when it starts meaning something. The daemon is the
+ * one place that CAN answer this — the SDK reconnects to it — so making it answer removes a
+ * `reticle_sessions` poll from every single navigation.
+ */
+arrival = null) {
+    const ok = true === result.ok;
+    const base = {
+        ok,
+        ...('string' === typeof result.url ? { url: result.url } : {}),
+        ...('string' === typeof result.reason ? { reason: result.reason } : {}),
+    };
+    // A refusal is conclusive: the page never moved, so there is nothing unconfirmed to report.
+    if (!ok)
+        return base;
+    if (arrival !== null) {
+        return {
+            ...base,
+            confirmed: true,
+            // The SDK that reconnects after a navigation is a NEW session with a new id. Returning it here
+            // is the difference between a confirmation and a confirmation the agent can act on.
+            sessionId: arrival.sessionId,
+        };
+    }
+    return {
+        ...base,
+        confirmed: false,
+        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.',
+    };
+}