@reticlehq/server 3.3.0 → 3.5.0

package/dist/surface/tools/act/sequence-grade.js

@@ -27,7 +27,9 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
     const total = Math.max(plan.planned, steps.length);
     const declaring = steps.filter((step) => step.declared);
     const declared = declaring.length;
-    const missed = declaring.find((step) => true !== step.held);
+    // `held: false` on an undeclared step means it could not be performed at all — the journey broke
+    // there whether or not anything was declared about it.
+    const missed = steps.find((step) => (step.declared ? true !== step.held : false === step.held));
     // A miss decides the grade before coverage does. How much of the plan declared nothing is
     // context on a red, never a softening of it.
     if (missed !== undefined) {
@@ -39,6 +41,17 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
             because: `a declared consequence did not hold — observed ${observed}`,
         };
     }
+    // Same rule as a single action: an observed contradiction outranks a consequence that held.
+    const contradictedAt = steps.findIndex((step) => (step.contradicted ?? []).length > 0);
+    if (contradictedAt >= 0) {
+        const kinds = (steps[contradictedAt]?.contradicted ?? []).join(', ');
+        return {
+            verified: Verified.NO,
+            declared,
+            total,
+            because: `step ${String(contradictedAt + 1)}: channels disagree about this action (${kinds}) even though it went on`,
+        };
+    }
     /*
      * `unknown` rather than `no-fault`, and the distinction is load-bearing.
      *
@@ -68,6 +81,24 @@ export function gradeSequence(steps, plan = { planned: steps.length, dispatched:
                         : `nothing was dispatched, so none of the ${String(total)} step(s) ran — read the per-step \`error\` for the one that was refused, and fix that before adding an \`expect\``,
         };
     }
+    // A journey is proved at its END. Declaring only early steps checks that it started, and a yes
+    // there was the one a single act_and_wait on the last step would never have given.
+    if (steps.length < total) {
+        return {
+            verified: Verified.UNKNOWN,
+            declared,
+            total,
+            because: `only ${String(steps.length)} of ${String(total)} steps ran, so the journey never reached its end`,
+        };
+    }
+    if (true !== steps.at(-1)?.declared) {
+        return {
+            verified: Verified.UNKNOWN,
+            declared,
+            total,
+            because: `the last step, where the journey ends, declared nothing — give it an \`expect\` naming the end state (${String(declared)} of ${String(total)} steps declared one)`,
+        };
+    }
     return {
         verified: Verified.YES,
         declared,

package/dist/surface/tools/act-capsule.d.ts

@@ -28,6 +28,13 @@ interface CapsuleSaveInputs {
      */
     root?: string | undefined;
 }
+/**
+ * What the act claimed would happen, in words: `route /settings`, `POST /v1/pay → 200`,
+ * `element "Issues"`. Read off the predicate the agent declared, because the causal links only name
+ * signals and requests: a failed route, element or text claim used to be filed as "declared
+ * consequence", which tells whoever reads the capsule nothing about what was expected.
+ */
+export declare function describeExpected(predicate: unknown): string | undefined;
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
 export declare function saveFailedAssertCapsule(inputs: CapsuleSaveInputs): Promise<string | undefined>;
 export {};

package/dist/surface/tools/act-capsule.js

@@ -14,6 +14,50 @@ import { CapsuleStore, capsuleFingerprint, capsuleId, CAPSULE_VERSION, } from '.
 import { ReticleTool } from '@reticlehq/core';
 import { asRecord, asString } from '@reticlehq/core';
 import { sessionRoot } from '../../memory/project/session-root.js';
+/**
+ * What the act claimed would happen, in words: `route /settings`, `POST /v1/pay → 200`,
+ * `element "Issues"`. Read off the predicate the agent declared, because the causal links only name
+ * signals and requests: a failed route, element or text claim used to be filed as "declared
+ * consequence", which tells whoever reads the capsule nothing about what was expected.
+ */
+export function describeExpected(predicate) {
+    const p = asRecord(predicate);
+    const kind = asString(p['kind']);
+    if (kind === undefined)
+        return undefined;
+    const all = (key, joiner) => {
+        const parts = (Array.isArray(p[key]) ? p[key] : [])
+            .map(describeExpected)
+            .filter((d) => d !== undefined);
+        return 0 === parts.length ? undefined : parts.join(joiner);
+    };
+    const q = asRecord(p['query']);
+    const named = asString(p['name']) ?? asString(q['name']) ?? asString(q['value']) ?? asString(q['testid']);
+    switch (kind) {
+        case 'route':
+            return `route ${asString(p['pathname']) ?? asString(p['contains']) ?? '?'}`;
+        case 'net': {
+            const status = 'number' === typeof p['status'] ? ` → ${String(p['status'])}` : '';
+            return `${asString(p['method']) ?? 'a'} ${asString(p['urlContains']) ?? 'request'}${status}`;
+        }
+        case 'signal':
+            return `signal ${asString(p['name']) ?? '?'}`;
+        case 'element':
+            return `${true === p['absent'] ? 'no ' : ''}element ${named === undefined ? '?' : `"${named}"`}`;
+        case 'text':
+            return `${true === p['absent'] ? 'no ' : ''}text "${asString(p['contains']) ?? '?'}"`;
+        case 'allOf':
+            return all('predicates', ' AND ');
+        case 'anyOf':
+            return all('predicates', ' OR ');
+        case 'not': {
+            const inner = describeExpected(p['predicate']);
+            return inner === undefined ? undefined : `not ${inner}`;
+        }
+        default:
+            return kind;
+    }
+}
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
 export async function saveFailedAssertCapsule(inputs) {
     const { deps, verdict, capsule, links, args, actResult, actedSource, root: given } = inputs;
@@ -47,7 +91,8 @@ export async function saveFailedAssertCapsule(inputs) {
     const body = {
         version: CAPSULE_VERSION,
         origin: 'failed-assert',
-        expected: expectedText.length > 0 ? expectedText : 'declared consequence',
+        expected: describeExpected(args['until'] ?? args['predicate']) ??
+            (expectedText.length > 0 ? expectedText : 'declared consequence'),
         observed: capsule.firstDivergence?.observed ?? verdict.failureReason ?? 'not observed',
         steps: [
             {

package/dist/surface/tools/act-sequence-tool.js

@@ -11,12 +11,12 @@
  */
 import { z } from 'zod';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
-import { compileSequenceStep } from '../../language/flows/replay.js';
+import { compileSequenceStep, pathOf } from '../../language/flows/replay.js';
 import { sequenceStepArgs } from './act/act-preflight.js';
 import { ReticleTool } from '@reticlehq/core';
 import { healthEnvelope } from '../../portal/session/session-health.js';
 import { pausedShortCircuit, pausedOutputShape, withControl, } from '../../portal/session/control-envelope.js';
-import { asRecord } from '@reticlehq/core';
+import { asRecord, isAbsenceDerived, isAdvisory } from '@reticlehq/core';
 import { sessionIdFromArgs } from './tools-helpers.js';
 import { describeStepResult, runStepWithStaleRetry } from './act/act-sequence-retry.js';
 import { assertSequenceSteps } from './act/act-preflight.js';
@@ -59,10 +59,9 @@ function effectOf(session, since) {
 const BURST_MAX_GAP_MS = 500;
 export const ACT_SEQUENCE_TOOL = {
     name: ReticleTool.ACT_SEQUENCE,
-    // The example is required for a core tool, and this one carries weight: the measured loop it
-    // replaces is literally a login form driven as three separate reticle_act calls (98 clicks and
-    // 21 fills inside looping sessions, 2026-08-10/11). Showing fill -> fill -> click is showing the
-    // exact shape an agent otherwise spends three round trips on.
+    // The example is required for a core tool, and this one carries weight: the loop it replaces is
+    // a login form driven as three separate reticle_act calls. Showing fill -> fill -> click is showing
+    // the exact shape an agent otherwise spends three round trips on.
     example: {
         steps: [
             { ref: 'e12', action: 'fill', args: { value: 'a@b.com' } },
@@ -133,6 +132,7 @@ export const ACT_SEQUENCE_TOOL = {
         if (paused !== undefined)
             return paused;
         const since = session.elapsed();
+        const pageBefore = pathOf(session.url);
         session.beginAction(ReticleTool.ACT_SEQUENCE, asRecord(args));
         try {
             const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
@@ -230,8 +230,12 @@ export const ACT_SEQUENCE_TOOL = {
                      * satisfy step four's assertion, which is a false green built out of correct parts.
                      */
                     const parsed = PredicateSchema.safeParse(step['expect']);
+                    const contradicted = (described.contradictions ?? [])
+                        .map((c) => c.kind)
+                        .filter((kind) => !isAdvisory(kind) && !isAbsenceDerived(kind));
+                    const disagreement = 0 === contradicted.length ? {} : { contradicted };
                     if (!parsed.success) {
-                        expectations.push({ declared: false });
+                        expectations.push({ declared: false, ...disagreement });
                         stepResults.push(described);
                     }
                     else {
@@ -240,6 +244,7 @@ export const ACT_SEQUENCE_TOOL = {
                         expectations.push({
                             declared: true,
                             held,
+                            ...disagreement,
                             ...(verdict.observed === undefined ? {} : { observed: verdict.observed }),
                             ...(verdict.expected === undefined ? {} : { expected: verdict.expected }),
                         });
@@ -287,7 +292,19 @@ export const ACT_SEQUENCE_TOOL = {
             // Same as captureAct: no `active()` gate, so a sequence driven with nothing open still lands
             // in the ambient tape. A stalled plan is still excluded — those steps never ran.
             if (stalledAt === undefined) {
-                deps.recordings.capture(compileSequenceStep(args, { count: inputSteps.length, steps: stepResults }));
+                // A sub-step keeps its `expect` only if it held — same rule as act_and_wait, so a flow
+                // never replays an expectation that was never once observed to hold.
+                const proved = inputSteps.map((raw, i) => {
+                    const step = asRecord(raw);
+                    const { expect: _expect, ...rest } = step;
+                    return true === expectations[i]?.held ? step : rest;
+                });
+                const recorded = compileSequenceStep({ ...args, steps: proved }, {
+                    count: inputSteps.length,
+                    steps: stepResults,
+                });
+                deps.recordings.capture(pageBefore === undefined ? recorded : { ...recorded, page: pageBefore });
+                deps.recordings.markEnded(pathOf(session.url));
             }
             /*
              * The grade, and the coverage it is never allowed to hide.

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

@@ -3,23 +3,8 @@ import { aliasParam } from './args/alias-args.js';
 import { resolveSessionWithin } from '../../portal/session/timing/resolve-within.js';
 import { WALL_CLOCK } from '../../portal/session/timing/wall-clock.js';
 import { timeoutMsSchema } from './args/numeric-bounds.js';
-import { captureAct } from '../../language/flows/replay.js';
-/**
- * The pathname of a session's live url, or undefined when it has none yet.
- *
- * Pathname rather than the whole url, because that is what `startPath` is compared against and what
- * a hash-routed app makes meaningless in the document location — see routeOfEvent.
- */
-function pathOf(url) {
-    if (url === undefined)
-        return undefined;
-    try {
-        return new URL(url).pathname;
-    }
-    catch {
-        return undefined;
-    }
-}
+import { captureAct, captureVerdictedAct, pathOf } from '../../language/flows/replay.js';
+import { durableArg, durableOutput, reloadAndRecheck, withDurability } from './act/durable.js';
 import { ActionType, ActionWarning, ReticleCommand, CaptureLoss, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, Verified, VerifiedReason, PredicateKind, } from '@reticlehq/core';
 import { leanActResult, mutatedWithin } from './act/act-view.js';
 import { ReticleTool } from '@reticlehq/core';
@@ -37,8 +22,9 @@ import { intentDebt, openSessionIntents } from '../../memory/intent/open-intents
 import { dischargeInlineIntent, inlineVerdictId, linkInlineIntent, } from '../../memory/intent/inline-intent.js';
 import { declaresState } from '@reticlehq/engine/question/predicate/predicate-asks.js';
 import { isStateUnwatched } from '@reticlehq/engine/evidence/blind-spots.js';
-import { inFlightRequestLabels, repeatedRequestLabels, waitForInFlight, } from './act/settle-in-flight.js';
-import { waitForReaction } from './act/react-grace.js';
+import { inFlightRequestLabels, repeatedRequestLabels } from './act/settle-in-flight.js';
+import { finishAfterMatch } from './act/after-match.js';
+import { noteProved } from './act/proved-controls.js';
 import { decideVerified } from '@reticlehq/engine/evidence/verified.js';
 import { honestyForVerdict } from '@reticlehq/engine/evidence/honesty.js';
 import { declaredExpectations, declaresBodyIndependentChannel, } from '@reticlehq/engine/question/declared.js';
@@ -76,8 +62,8 @@ import { readAlreadyTrue } from './act/already-true.js';
 /**
  * The action vocabulary, derived from ActionType — never retyped.
  *
- * The description used to list thirteen actions while ActionType had seventeen: blur, upload, drag
- * and webmcp were real, callable, and undocumented, because a hand-copied list drifts the moment
+ * The description used to omit callable actions such as blur, upload and drag,
+ * because a hand-copied list drifts the moment
  * someone adds an arm. Deriving both the schema and the prose from the enum makes that impossible.
  *
  * The handler already refused an unknown action with a good message; the schema now refuses it
@@ -254,6 +240,7 @@ export const ACT_TOOLS = [
                 });
             }
             finally {
+                deps.recordings.markEnded(pathOf(session.url));
                 // Close the window on every exit (settle or throw), recording the action + settle outcome.
                 session.finishAction(undefined, settledOutcome, true === settledOutcome ? session.elapsed() - since : undefined);
             }
@@ -286,7 +273,7 @@ export const ACT_TOOLS = [
                 .record(z.unknown())
                 .optional()
                 .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
-            predicate: PredicateSchema.optional().describe('Alias for `until` (the name reticle_assert / reticle_wait_for use).'),
+            predicate: PredicateSchema.optional().describe('Alias for `until`.'),
             until: PredicateSchema.optional().describe('Predicate to wait for after the action completes (same shape as reticle_assert). OMIT to wait for the page to SETTLE — network + DOM idle — the deterministic default instead of a sleep. To assert a consequence AND settle, allOf them: { kind: "allOf", predicates: [<your predicate>, { kind: "settled" }] }.'),
             timeout_ms: timeoutMsSchema
                 .optional()
@@ -296,9 +283,11 @@ export const ACT_TOOLS = [
                 .optional()
                 .describe('Throw if the tab is throttled. Default: false.'),
             intent: intentArg,
+            durable: durableArg,
             ...sessionIdShape,
         },
         outputSchema: {
+            durable: durableOutput,
             effect: z
                 .unknown()
                 .describe('The reticle_act result (dispatched, settled, inputMode, etc.).'),
@@ -433,6 +422,9 @@ export const ACT_TOOLS = [
             const { alreadyTrue, alreadyTrueHiddenMatch, alreadyTrueEvidence, baselines } = await readAlreadyTrue(session, until, since);
             // Same as the ACT handler: the route this step RAN on, before the action can move the app.
             const routeBeforeWait = pathOf(session.url);
+            // Recorded in `finally`, once the verdict is known — see captureVerdictedAct.
+            let dispatched;
+            let recordedVerdict;
             try {
                 // actCommand is the single interception point for upload+path rewrite.
                 //
@@ -450,7 +442,7 @@ export const ACT_TOOLS = [
                 if (actResult !== null) {
                     if (!actResult.ok)
                         throw new Error(actResult.error ?? 'act failed');
-                    captureAct(deps.recordings, args, actResult.result, routeBeforeWait);
+                    dispatched = { result: actResult.result };
                     // Dispatched — now this act owns the cursor and the effect. Marking its OWN measurement
                     // also stops the spread below from inheriting an earlier reticle_act's action and
                     // mutation count.
@@ -476,34 +468,12 @@ export const ACT_TOOLS = [
                     since = 0;
                 session = followed.session;
                 verdict = followed.verdict;
-                // The predicate resolves the INSTANT it holds, which on an optimistically-navigating app is
-                // while the write is still in flight — so the verdict was taken over a window the app had not
-                // finished, and came back `unknown / unsettled` asking the CALLER to re-check. A login that
-                // genuinely succeeded returned at 492ms of an 8000ms budget with every corroborating channel
-                // agreeing. Spend the rest of the budget the caller already granted.
-                //
-                // This decides nothing: it waits for the answer instead of guessing at it. A response that
-                // arrives as a FAILURE still contradicts — and now arrives INSIDE the window, where the
-                // detector can see it at all — while a request still open when the budget genuinely runs out
-                // reports unsettled exactly as before, an honest limit rather than an early exit. Costs
-                // nothing on the common path, where no request is in flight.
+                // After a match, let the app finish before the window closes — see act/after-match.ts.
                 if (verdict.pass && timeout > 0) {
-                    const sleep = {
-                        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-                    };
-                    const spent = () => timeout - (session.elapsed() - predicateStarted);
-                    await waitForInFlight(session, since, spent(), sleep);
-                    // Waiting for the response moved the hazard rather than removing it: the response now lands
-                    // inside the window BY DESIGN, and the app's re-render happens a task or two later. Close
-                    // the window in that gap and every channel agrees the app took a successful write and did
-                    // nothing — `response-ignored`, i.e. `verified:"no"` on a correct app, produced entirely by
-                    // where we stopped looking. A false accusation is the more damaging direction of error for
-                    // a verification tool: it sends someone to fix code that is not broken.
-                    //
-                    // So the response is not the end of the window; the app's REACTION to it is. Paid only in
-                    // the shape that would otherwise be accused — a successful mutating write with nothing
-                    // moved after it — and short enough that a genuinely dropped response is still reported.
-                    await waitForReaction(session, since, spent(), sleep);
+                    const left = () => timeout - (session.elapsed() - predicateStarted);
+                    const reverted = await finishAfterMatch(session, until, since, baselines, left);
+                    if (reverted !== undefined)
+                        verdict = { pass: false, failureReason: reverted, observed: reverted };
                 }
                 const r = asRecord(actResult?.result);
                 if ('boolean' === typeof r['settled'])
@@ -650,7 +620,7 @@ export const ACT_TOOLS = [
                 const outcomePending = acceptedWriteLabels(windowEvents);
                 const outcomeUnread = unreadWriteLabels(windowEvents);
                 const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
-                const decision = decideVerified({
+                const { decision, durable } = await withDurability(args['durable'], until, decideVerified({
                     pass: verdict.pass,
                     // Threaded rather than looked up: decideVerified is pure and has no session.
                     ...sessionVerdictFacts(session),
@@ -690,7 +660,9 @@ export const ACT_TOOLS = [
                         repeated: repeatedRequestLabels(windowEvents),
                     },
                     ...(namedNetIsInFlight(until, stillInFlight) ? { namedRequestInFlight: true } : {}),
-                });
+                }), (part) => reloadAndRecheck(deps, session, part, timeout));
+                recordedVerdict = String(decision.verified);
+                noteProved(session, recordedVerdict, actResult?.result);
                 // Computed once: the verdict block reports it, and the instrumentation gaps are a second
                 // reading of the same evidence rather than a new observation.
                 const actionSummary = causalSummary(windowEvents, {
@@ -818,6 +790,7 @@ export const ACT_TOOLS = [
                     // agent cannot miss it by not asking. Omitted entirely when clean, so a healthy action
                     // pays nothing.
                     ...(contradictions.length > 0 ? { contradictions } : {}),
+                    ...(durable === undefined ? {} : { durable }),
                     honesty: honestyForVerdict(String(decision.verified), honesty),
                     // Without its summary: it is byte-identical to `summary` two fields up. See wireCapsule.
                     ...(capsule === undefined ? {} : { capsule: wireCapsule(capsule) }),
@@ -828,6 +801,9 @@ export const ACT_TOOLS = [
                 });
             }
             finally {
+                if (dispatched !== undefined)
+                    captureVerdictedAct(deps.recordings, args, dispatched.result, routeBeforeWait, recordedVerdict);
+                deps.recordings.markEnded(pathOf(currentOf(deps.sessions, session).url));
                 acted.finishAction(verdictEffect, settledOutcome, true === settledOutcome ? acted.elapsed() - actedSince : undefined);
             }
         },

package/dist/surface/tools/assert/assert-grade.js

@@ -10,7 +10,7 @@
  *
  * Pure: no IO, no clock.
  */
-import { isConsequenceKind, isPresenceKind, PredicateKind } from '@reticlehq/core';
+import { compareSourceClauses, isConsequenceKind, isPresenceKind, PredicateKind, } from '@reticlehq/core';
 import { HonestyGrade, strongerGrade, weakerGrade } from '@reticlehq/engine/evidence/honesty.js';
 export const PRESENCE_ONLY_ADVICE = 'This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked.';
 function walk(predicate, negated = false) {
@@ -27,6 +27,14 @@ function walk(predicate, negated = false) {
     // never matched anything in the first place. Negation makes a presence check weaker, not stronger.
     if (PredicateKind.NOT === predicate.kind)
         return walk(predicate.predicate, true);
+    // A comparison grades as what its sides read: with a net/signal/state side it relates the page to
+    // the app's own record, which a wrong locator cannot fake; text against text is two readings of
+    // the same DOM. Its text side is always a content check, so it never counts as bare presence
+    // unless negated.
+    if (PredicateKind.COMPARE === predicate.kind) {
+        const consequence = compareSourceClauses(predicate).some((c) => isConsequenceKind(c.kind));
+        return { consequence, presence: !consequence && negated };
+    }
     // Leaf: classify against the single source of truth in core. Kinds that are neither consequence
     // nor presence (route/console/settled/animation) correctly return false for both.
     return {
@@ -109,6 +117,9 @@ export function gradeOfPredicate(predicate) {
         // verdict that proved only presence report `signal`, and a `minGrade: net` gate would trust it.
         case PredicateKind.ANY_OF:
             return combine(predicate.predicates, weakerGrade);
+        // Both sides had to be read and agree, so it proves as much as its stronger side.
+        case PredicateKind.COMPARE:
+            return combine(compareSourceClauses(predicate), strongerGrade);
         // Everything else, `not` included: an absence claim is satisfied trivially by a locator that
         // never matched anything, which is the argument `walk` already makes about negation.
         default:

package/dist/surface/tools/assert/assert-verdict.js

@@ -1,4 +1,4 @@
-import { CaptureLoss, channelsRead, PredicateKind } from '@reticlehq/core';
+import { CaptureLoss, channelsReadBy, PredicateKind } from '@reticlehq/core';
 import { sessionVerdictFacts } from '../../../portal/session/session-verdict-facts.js';
 import { gapsForAction } from '@reticlehq/engine/evidence/instrumentation-gaps.js';
 import { noteSessionGaps } from '@reticlehq/engine/evidence/gap-ledger.js';
@@ -148,7 +148,7 @@ changeUndeclared) {
         // first clause, and one this implementation could not run until the page started declaring.
         // Both halves are conditional on purpose: an SDK too old to declare sends nothing, and
         // treating that silence as an empty set would refuse every claim from every older page.
-        channelsRead: channelsRead(predicate.kind),
+        channelsRead: channelsReadBy(predicate),
         ...(session.channels === undefined ? {} : { channelsObservable: session.channels }),
         // Threaded rather than looked up: decideVerified is pure and has no session.
         ...sessionVerdictFacts(session),

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

@@ -13,7 +13,7 @@ export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
         example: { url: '/settings' },
-        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the page itself cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect: `confirmed:true` with a new `sessionId` means the page arrived and you can act immediately. `confirmed:false` means it did not arrive within that window (reported as `waitedMs`) — the page may be slow, uninstrumented, or not there. A slow SPA can take 30-60s to reattach: raise `timeout_ms` rather than polling reticle_sessions.',
+        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the old page cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect. `confirmed:true` with a `sessionId` means the requested page arrived and you can act immediately. `confirmed:false` with `landedOn` means the navigation arrived but the app landed at another URL, such as an authentication or route-guard redirect; use `landedOn` to understand where the browser actually ended up. `confirmed:false` without `landedOn` means the target was not observed within the wait window; a slow app may still be on its way, so increase `timeout_ms` when appropriate.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
@@ -38,6 +38,10 @@ export const BROWSER_TOOLS = [
             confirmed: z.boolean().optional(),
             /** The session the SDK reconnected as, when arrival was confirmed — it is a NEW id. */
             sessionId: z.string().optional(),
+            /**
+             * The URL where the navigated document landed when it differs from the requested target.
+             */
+            landedOn: z.string().optional(),
             /**
              * On confirmed:false — the budget (ms) that expired without the page coming back. Says which
              * of "Reticle stopped waiting" and "the page never came back" you are looking at.
@@ -58,6 +62,7 @@ export const BROWSER_TOOLS = [
                 // back past this point. Reported from the field as an assertion whose clauses all passed
                 // coming back `contradicted` by hundreds of 500s against resources that were already gone.
                 before.lastAct.markNavigated(before.elapsed());
+                deps.recordings.markNavigated();
                 await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
                     hard: true === args['hard'],
                 });
@@ -96,6 +101,7 @@ export const BROWSER_TOOLS = [
             // document just as thoroughly. `beginAction` attributes events to this action; it does not move
             // the window a later assert judges over, and those are two different jobs.
             session.lastAct.markNavigated(session.elapsed());
+            deps.recordings.markNavigated();
             try {
                 const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
                 // `ok` is the browser accepting the instruction, not the page arriving — see navigate-result.
@@ -104,7 +110,13 @@ export const BROWSER_TOOLS = [
                 // reticle_sessions itself. A refusal skips the wait: there is nothing to wait FOR.
                 const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
                 const arrival = true === result.ok
-                    ? await awaitArrival(deps.sessions, target, { navigatedId: session.id, priorIds }, timeoutMs)
+                    ? await awaitArrival(deps.sessions, target, {
+                        // Keep the original Session object and URL so arrival detection can distinguish
+                        // an in-progress navigation from a document that arrived somewhere else.
+                        navigatedSession: session,
+                        navigatedFrom: session.url,
+                        priorIds,
+                    }, timeoutMs)
                     : null;
                 return navigateResult(result, arrival, timeoutMs);
             }

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

@@ -10,6 +10,7 @@ import { ReticleTool } from '@reticlehq/core';
 import { asString } from '@reticlehq/core';
 import { exercisedCount } from './gaps/coverage-identity.js';
 import { commandOrThrow, sessionIdShape } from './tool-kit.js';
+import { foldAppCoverage } from '../../features/exhaust/app-coverage.js';
 /**
  * `reticle_coverage` — which interactive controls this session has driven, and which it has not.
  *
@@ -69,8 +70,17 @@ export function buildCoverageTools(toolNames) {
             name: ReticleTool.COVERAGE,
             description: 'Which interactive controls you have driven this session, and which you have NOT. Returns { total, exercised, untouched:[{ref,label}], alsoDroveGone? } over the controls currently on the page. Use it to decide whether verification is finished: an untouched list that still holds the controls your change affects means you are not done. This is about what you did not TOUCH — distinct from the `coverage` field on an action result, which reports what the layer could not SEE.',
             example: {},
-            inputSchema: { ...sessionIdShape },
+            inputSchema: {
+                app: z
+                    .boolean()
+                    .optional()
+                    .describe('Also fold into the app-wide ledger; returns `app.levels`.'),
+                ...sessionIdShape,
+            },
             outputSchema: {
+                // The app-wide ledger — see features/exhaust/ledger.ts. Loose: run-only, and the levels
+                // carry their own shape.
+                app: z.record(z.unknown()).optional(),
                 total: z.number(),
                 exercised: z.number(),
                 untouched: z.array(z.object({ ref: z.string(), label: z.string() })),
@@ -171,6 +181,22 @@ export function buildCoverageTools(toolNames) {
                     ...(regressed === undefined ? {} : { observabilityRegressed: regressed }),
                     featureUse,
                     toolHitRate,
+                    ...(true === args['app']
+                        ? {
+                            app: await foldAppCoverage({
+                                fs: deps.fs,
+                                reticleRoot: sessionRoot(deps, sessionId),
+                                seen: parseControls(tree).map((c) => c.label),
+                                session,
+                                now: deps.now,
+                                ...(deps.realInput?.takeCodeCoverage === undefined
+                                    ? {}
+                                    : {
+                                        takeCode: (url) => deps.realInput?.takeCodeCoverage?.(url) ?? Promise.resolve(undefined),
+                                    }),
+                            }),
+                        }
+                        : {}),
                 };
             },
         },

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

@@ -29,6 +29,17 @@ function unknownParamsError(toolName, unknown) {
 const TOOLS_LIST_ACTION = 'list';
 /** What to write instead — the one parameter reticle_tools declares, and the no-argument form. */
 const TOOLS_ARG_HINT = 'name the tools you want in `names`: reticle_tools { names: ["reticle_act_and_wait"] } — or call it with no arguments for the full catalog';
+/**
+ * The refusal for arguments of the wrong type, naming each offending key and what it declared.
+ * `path` is joined for a nested value (`intents.0.id`); a missing required key reads as the key.
+ */
+function invalidParamsError(toolName, issues) {
+    const named = issues.map((issue) => {
+        const where = 0 === issue.path.length ? '(arguments)' : issue.path.join('.');
+        return `${where} (${issue.message})`;
+    });
+    return `invalid ${1 === named.length ? 'parameter' : 'parameters'} for ${toolName}: ${named.join('; ')} — NOT applied, so any result would be an answer to a different question`;
+}
 /** The keys not declared by `shape`, in call order. */
 function unknownKeys(args, shape) {
     const declared = new Set(Object.keys(shape));
@@ -263,8 +274,24 @@ callable) {
                     hint: 'fix the arguments and call reticle_run again',
                 };
             }
+            // Keys are not enough: the TYPES are the other half of what a direct call's SDK validation
+            // refuses. Unchecked here, `reticle_viewport { width: "1440" }` from a client that stringifies
+            // numbers reached the handler, which read a non-number as missing and set the page to 64x64,
+            // and `reticle_intent { action: "declare", intents: "[...]" }` stored nothing and answered
+            // `{ intents: [] }` (#1118). The parsed value goes on, as it does on the direct path, so a
+            // schema's defaults and transforms apply the same way through either door.
+            const typed = z.object(target.inputSchema).safeParse(callArgs);
+            if (!typed.success) {
+                return {
+                    error: invalidParamsError(name, typed.error.issues),
+                    tool: name,
+                    params: paramInfo(target.inputSchema),
+                    ...(target.example === undefined ? {} : { example: target.example }),
+                    hint: 'fix the arguments and call reticle_run again',
+                };
+            }
             try {
-                return await runTool(target, deps, callArgs);
+                return await runTool(target, deps, typed.data);
             }
             catch (error) {
                 // The SAME payload the direct tool path builds — recovery included. Answering every failure
@@ -272,7 +299,7 @@ callable) {
                 // 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 { ...takeVersionSkewOnto(buildErrorPayload(message)), tool: name };
+                return { ...takeVersionSkewOnto(buildErrorPayload(message), deps.peerSkew), tool: name };
             }
         },
     };