@reticlehq/server 2.2.0 → 2.3.0

package/dist/tools/act-tools.js

@@ -5,45 +5,28 @@
  */
 import { z } from 'zod';
 import { compileActStep, compileSequenceStep } from '../flows/replay.js';
-import { ActionType, ActionWarning, AnchorKind, DANGEROUS_ACTION_CONFIRM_ARG, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, InputModeReason, ReticleCommand, isDangerousActionText, } from '@reticlehq/core';
+import { ActionType, ActionWarning, DEFAULT_ASSERT_TIMEOUT_MS, InputMode, InputModeReason, ReticleCommand, } from '@reticlehq/core';
 import { isPointerAction } from '../input/real-input.js';
-import { leanActResult } from './act-view.js';
+import { leanActResult, mutatedWithin } from './act-view.js';
 import { ReticleTool } from './tool-names.js';
 import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
 import { causalSummary } from '../capsule/causal-summary.js';
+import { findContradictions } from '../events/contradictions.js';
+import { decideVerified } from '../honesty/verified.js';
+import { saveFailedAssertCapsule } from './act-capsule.js';
 import { buildDivergenceCapsule } from '../capsule/capsule.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
-import { HonestyGrade, buildHonestyBlock } from '../honesty/honesty.js';
-import { buildCoverageStatement, blindSpotsFromState } from '../honesty/blind-spots.js';
-import { CapsuleStore, capsuleId } from '../capsule/capsule-store.js';
+import { buildHonestyBlock } from '../honesty/honesty.js';
+import { buildCoverageStatement, blindSpotsFromState, impeachesCapture, } from '../honesty/blind-spots.js';
+import { hasAcceptedWrite } from '../honesty/accepted-write.js';
+import { hasUnreadWriteOutcome } from '../honesty/unread-outcome.js';
+import { assertDragNotDestructive, assertNotDestructive } from './act-danger.js';
 import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '../events/predicate.js';
 import { healthEnvelope, refuseIfThrottled } from '../session/session-health.js';
 import { pausedShortCircuit, pausedOutputShape, withControl } from '../session/control-envelope.js';
 import { asString, asNumber, asRecord, sourceOf } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow } from './tool-kit.js';
-/** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
-function gradeOf(links) {
-    if (links.some((l) => l.kind === 'signal'))
-        return HonestyGrade.SIGNAL;
-    if (links.some((l) => l.kind === 'net'))
-        return HonestyGrade.NET;
-    if (links.some((l) => l.kind === 'state'))
-        return HonestyGrade.STATE;
-    return HonestyGrade.PRESENCE;
-}
-/** Narrow an INSPECT result's `box` into a positive-area ElementBox (else undefined). */
-function asBox(value) {
-    const b = asRecord(asRecord(value)['box']);
-    const x = asNumber(b['x']);
-    const y = asNumber(b['y']);
-    const w = asNumber(b['width']);
-    const h = asNumber(b['height']);
-    if (x === undefined || y === undefined || w === undefined || h === undefined)
-        return undefined;
-    if (w <= 0 || h <= 0)
-        return undefined; // zero-area (display:none) ⇒ native click would miss
-    return { x, y, width: w, height: h };
-}
+import { asActionType, asBox, gradeOf } from './act-helpers.js';
 /** Synthetic outcome with a diagnostic reason (provider configured but native input skipped). */
 function synthetic(reason) {
     return reason === undefined
@@ -73,23 +56,7 @@ async function tryRealInput(deps, session, ref, action, args) {
     if (!(await provider.isAvailableFor(session.url)))
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
     const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
-    const confirmed = inner[DANGEROUS_ACTION_CONFIRM_ARG] === true;
-    const dangerousDescriptorText = (value) => {
-        const descriptor = asRecord(value);
-        return [
-            asString(descriptor['name']) ?? '',
-            asString(descriptor['text']) ?? '',
-            asString(descriptor['value']) ?? '',
-            asString(descriptor['href']) ?? '',
-            asString(descriptor['formAction']) ?? '',
-            asString(descriptor['formText']) ?? '',
-        ].join(' ');
-    };
-    if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) &&
-        !confirmed &&
-        isDangerousActionText(dangerousDescriptorText(inspected))) {
-        throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
-    }
+    assertNotDestructive(action, inner, inspected);
     const box = asBox(inspected);
     if (box === undefined)
         return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
@@ -101,10 +68,9 @@ async function tryRealInput(deps, session, ref, action, args) {
         const targetInspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, {
             ref: toRef,
         });
-        if (!confirmed &&
-            isDangerousActionText(`${dangerousDescriptorText(inspected)} ${dangerousDescriptorText(targetInspected)}`)) {
-            throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
-        }
+        // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
+        // thing being dragged looks.
+        assertDragNotDestructive(inner, inspected, targetInspected);
         toBox = asBox(targetInspected);
         if (toBox === undefined)
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
@@ -141,18 +107,15 @@ async function tryRealInput(deps, session, ref, action, args) {
  * as a generic failure rather than "that is not an action". Validate at the boundary, per the project's
  * unknown-plus-narrowing rule, so a typo is rejected where it can still be explained.
  */
-function asActionType(value) {
-    const raw = asString(value);
-    if (raw === undefined)
-        return undefined;
-    return Object.values(ActionType).includes(raw) ? raw : undefined;
-}
 export const ACT_TOOLS = [
     {
         name: ReticleTool.ACT,
+        example: { ref: 'e42', action: 'fill', args: { value: 'hello' } },
         description: 'Execute one action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. Returns immediately with a `since` cursor — observe the reaction with reticle_observe. Carries effect:{dispatched,targetMatched,visible,enabled,focusMoved,valueChanged,domMutatedWithin,occluded,occludedBy,scrolledIntoView} to tell "action missed" from "app didn\'t react"; dispatched=landed, settled=a real frame flushed, and a settle timeout never fails the tool. Fields at their uninformative default are OMITTED so a clean action collapses to its consequence: an absent dispatched/targetMatched/visible/enabled means true, an absent occluded/scrolledIntoView/valueChanged/defaultPrevented means false, an absent focusMoved/occludedBy means null. occluded=true means the click point is covered by another element (a real user could not click it) — synthetic dispatch still delivered the event; scrolledIntoView=true means an off-viewport target was scrolled in first. inputMode is "real" (native CDP, no synthetic effect block) or "synthetic"; clicks default to the occlusion-honest synthetic path even when CDP is configured — pass args.native:true to force a trusted native click (file pickers, clipboard). inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): docs/usage.md §18.',
         inputSchema: {
-            ref: z.string().describe("Element ref from reticle_snapshot or reticle_query (e.g. 'e42')."),
+            ref: z
+                .string()
+                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions.`),
             action: z
                 .string()
                 .describe('Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView'),
@@ -200,7 +163,10 @@ export const ACT_TOOLS = [
                 return paused;
             refuseIfThrottled(session, args['refuseWhenThrottled']);
             const since = session.elapsed();
-            session.markActCursor(since); // honesty: wait_for/assert default their floor to this cursor
+            session.lastAct.markCursor(since); // honesty: wait_for/assert default their floor to this cursor
+            // Cleared up front: a throw between here and the result must not leave the PREVIOUS act's
+            // measurement standing, which would judge this window with the last one's evidence.
+            session.lastAct.markEffect(asString(args['action']), undefined);
             const ref = asString(args['ref']) ?? '';
             // Open the journal's action-attribution window BEFORE dispatching, so it covers the native path
             // too. It used to open only on the synthetic path, and the native path returned above it — so a
@@ -243,6 +209,10 @@ export const ACT_TOOLS = [
                 const r = asRecord(result.result);
                 if (typeof r['settled'] === 'boolean')
                     settledOutcome = r['settled'];
+                // Keep what only this call measured, so the observe that judges this window can ask whether
+                // anything happened INSIDE the target — the one fact that separates a dead control from a
+                // page that was merely busy with something else.
+                session.lastAct.markEffect(asString(args['action']), mutatedWithin(r));
                 return withControl(session, {
                     since,
                     inputMode: InputMode.SYNTHETIC,
@@ -288,7 +258,7 @@ export const ACT_TOOLS = [
             if (paused !== undefined)
                 return paused;
             const since = session.elapsed();
-            session.markActCursor(since); // honesty: a later wait_for/assert floors at this cursor
+            session.lastAct.markCursor(since); // honesty: a later wait_for/assert floors at this cursor
             session.beginAction(ReticleTool.ACT_SEQUENCE, asRecord(args));
             try {
                 const result = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: args['steps'] });
@@ -313,6 +283,7 @@ export const ACT_TOOLS = [
     },
     {
         name: ReticleTool.ACT_AND_WAIT,
+        example: { ref: 'e42', action: 'click', until: { kind: 'signal', name: 'todos:loaded' } },
         description: 'Act on a ref, then wait for a predicate to hold — one hop for the act->observe->assert loop. ' +
             'Omit `until` to wait for the page to settle (network + DOM idle) — use this instead of a fixed sleep. ' +
             'Returns { effect } (the action result), { verdict } (predicate pass/evidence/near-miss), ' +
@@ -320,7 +291,9 @@ export const ACT_TOOLS = [
             'cursor; pass it to reticle_observe for the full per-event timeline when the counts are not enough). ' +
             'timeout_ms 0 evaluates the predicate once without waiting.',
         inputSchema: {
-            ref: z.string().describe('Element ref from reticle_snapshot or reticle_query.'),
+            ref: z
+                .string()
+                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions.`),
             action: z
                 .string()
                 .describe('Action to perform: click | dblclick | hover | focus | fill | type | clear | select | check | uncheck | submit | press | scrollIntoView'),
@@ -378,6 +351,14 @@ export const ACT_TOOLS = [
                 .string()
                 .optional()
                 .describe('Present only on a FAILED verdict when the fail-to-pass capsule was persisted: its id, replayable as a regression flow once the bug goes green.'),
+            verified: z
+                .string()
+                .describe('THE field to gate on: "yes" | "no" | "unknown". Read this first and read `because` for the reason. "unknown" is NOT failure — it means the evidence could not decide (dirty capture, nothing asserted at a real grade, or the page never settled), which calls for a better check rather than a code change. Everything else on this result is the evidence this was derived from.'),
+            because: z.string().describe('One sentence naming the deciding evidence behind `verified`.'),
+            contradictions: z
+                .array(z.unknown())
+                .optional()
+                .describe('Channels that DISAGREE about this action — the UI advanced while its write failed, a success signal fired over a failed request, a response changed nothing, a duplicate fired, a request never settled. OMITTED when clean. Treat any entry as a finding even when the verdict is green: a passing assertion and a contradicted channel is exactly the false green this exists to catch.'),
             honesty: z
                 .unknown()
                 .describe('The verdict trust block { grade, attribution, coverage, integrity, envelope? } — a green never looks stronger than this. Gate on grade ≥ net AND integrity.clean. Fields that were not measured are OMITTED rather than reported as zero, so treat an absent `envelope` as "not sampled", never as a failure.'),
@@ -403,7 +384,12 @@ export const ACT_TOOLS = [
                 : { kind: 'settled' };
             const timeout = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
             const since = session.elapsed();
-            session.markActCursor(since);
+            // `dropped` is cumulative for the SESSION, so comparing against a pre-action reading is what
+            // asks "did the buffer lose anything while THIS action was observed?" — the question the
+            // honesty block means. Reading the raw total pinned every later verdict to `unknown` after a
+            // single early eviction (measured on the Next.js demo at dropped:51, windows intact).
+            const droppedBefore = session.bufferHealth().dropped;
+            session.lastAct.markCursor(since);
             // The attribution window stays open across the settle wait below, so post-dispatch async events
             // (the whole point of act_and_wait) attribute to this action. finishAction fires after the wait.
             session.beginAction(ReticleTool.ACT_AND_WAIT, asRecord(args));
@@ -428,7 +414,7 @@ export const ACT_TOOLS = [
                 const actedSource = sourceOf(r['source']);
                 // Remembered on the session so a LATER assertion can name a file even when its failure has no
                 // element to point at — a signal that never fired, a request that was never made.
-                session.markActSource(actedSource === undefined ? undefined : `${actedSource.file}:${String(actedSource.line)}`);
+                session.lastAct.markSource(actedSource === undefined ? undefined : `${actedSource.file}:${String(actedSource.line)}`);
                 const windowEvents = session.eventsSince(since);
                 const trace = summarizeReaction(buildReactionReport(windowEvents, session.elapsed() - since));
                 // The bounded Tier-1 causal summary — net/console/state/storage diffs the trace's counts miss.
@@ -446,48 +432,51 @@ export const ACT_TOOLS = [
                 // stronger than this block. Grade from the strongest asserted consequence; integrity from evictions.
                 // Coverage: cross-origin frames / other blind spots the SDK reported during this window mean the
                 // verdict didn't see everything — say so, never imply full coverage.
-                const coverage = buildCoverageStatement(blindSpotsFromState(session.blindSpots()));
+                const spots = blindSpotsFromState(session.blindSpots());
+                const coverage = buildCoverageStatement(spots);
+                // Only a spot that IMPEACHES the capture belongs in integrity — see impeachesCapture. A
+                // structural boundary (virtualized rows, a cross-origin frame) is reported as coverage and
+                // must not downgrade a verdict about what WAS observed.
+                const impeaching = buildCoverageStatement(spots.filter((s) => impeachesCapture(s.kind)));
                 const honesty = buildHonestyBlock({
                     grade: gradeOf(gradedLinks),
                     attribution: 'window',
-                    truncated: session.bufferHealth().dropped > 0,
+                    truncated: session.bufferHealth().dropped > droppedBefore,
                     coveragePartial: coverage.coverage === 'partial',
-                    ...(coverage.note === undefined ? {} : { blindSpots: [coverage.note] }),
+                    ...(impeaching.note === undefined ? {} : { blindSpots: [impeaching.note] }),
+                });
+                const capsuleSaved = await saveFailedAssertCapsule({
+                    deps,
+                    verdict,
+                    capsule,
+                    links,
+                    args,
+                    actResult,
+                    ...(actedSource === undefined ? {} : { actedSource }),
+                });
+                // Pass the action: an EMPTY window then reads as "the target does not react" rather than as a
+                // clean run — `settled` is satisfied by a page that did nothing, i.e. by a click that missed.
+                const acted = asString(args['action']);
+                const contradictions = findContradictions(windowEvents, {
+                    action: acted,
+                    ...session.lastAct.effect(),
+                });
+                // The single field an agent reads. Everything below it is the evidence it was derived from;
+                // this is the only one that has to be interpreted, and now it interprets itself.
+                const outcomePending = hasAcceptedWrite(windowEvents);
+                const outcomeUnread = hasUnreadWriteOutcome(windowEvents);
+                const decision = decideVerified({
+                    pass: verdict.pass,
+                    honesty,
+                    contradictions,
+                    ...(outcomePending ? { outcomePending } : {}),
+                    ...(outcomeUnread ? { outcomeUnread } : {}),
+                    // `settled` is genuinely optional: a wait that declared no predicate never measured it, and
+                    // passing `false` there would report "never settled" about something never asked to settle.
+                    ...(settledOutcome === undefined ? {} : { settled: settledOutcome }),
                 });
-                //: a red assertion is the ONE moment the evidence explaining it is in hand. Persist it as a
-                // replayable fail-to-pass capsule so the bug survives the turn — and becomes a regression flow
-                // the moment it goes green. Best-effort: capturing evidence must never fail the run that found it.
-                let capsuleSaved;
-                if (!verdict.pass && capsule !== undefined) {
-                    const id = capsuleId(deps.now(), asString(args['ref']) ?? 'assert');
-                    const expectedText = links
-                        .map((l) => ('name' in l ? `${l.kind} ${l.name}` : l.kind))
-                        .join(' AND ');
-                    const saved = await new CapsuleStore(deps.fs, deps.reticleRoot).save({
-                        version: 1,
-                        id,
-                        createdAt: deps.now(),
-                        origin: 'failed-assert',
-                        expected: expectedText.length > 0 ? expectedText : 'declared consequence',
-                        observed: capsule.firstDivergence?.observed ?? verdict.failureReason ?? 'not observed',
-                        steps: [
-                            {
-                                tool: ReticleTool.ACT,
-                                anchor: {
-                                    kind: AnchorKind.TESTID,
-                                    value: asString(asRecord(actResult.result)['testid']) ?? asString(args['ref']) ?? '',
-                                    // Carried so the saved capsule — which outlives this turn and becomes a regression
-                                    // flow when it goes green — still knows which file the failure came from.
-                                    ...(actedSource === undefined ? {} : { source: actedSource }),
-                                },
-                                action: (asString(args['action']) ?? ActionType.CLICK),
-                            },
-                        ],
-                    });
-                    if (saved)
-                        capsuleSaved = id;
-                }
                 return withControl(session, {
+                    ...decision,
                     effect: leanActResult(actResult.result),
                     verdict,
                     // Promoted out of `effect` on red only. On green nobody needs it and it is noise; on red it
@@ -499,6 +488,16 @@ export const ACT_TOOLS = [
                     trace,
                     ...(capsuleSaved === undefined ? {} : { capsuleSaved }),
                     summary: causalSummary(windowEvents),
+                    // Cross-channel disagreement, reported WITH the action that caused it.
+                    //
+                    // This is the one finding here a human structurally cannot make — they watch one channel,
+                    // the screen, so a UI that advanced while its write failed looks like success to them and
+                    // always will. It ran only inside reticle_observe, which means it was found only when the
+                    // agent already suspected something and thought to go looking. That inverts the value: the
+                    // whole point is catching what NOBODY suspected. It now travels with the action, so an
+                    // agent cannot miss it by not asking. Omitted entirely when clean, so a healthy action
+                    // pays nothing.
+                    ...(contradictions.length > 0 ? { contradictions } : {}),
                     honesty,
                     ...(capsule === undefined ? {} : { capsule }),
                     since,
@@ -511,4 +510,3 @@ export const ACT_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=act-tools.js.map

package/dist/tools/act-view.d.ts

@@ -16,4 +16,10 @@
  */
 /** Return a copy of an act command result with its `effect` block leaned. Non-objects pass through. */
 export declare function leanActResult(result: unknown): unknown;
-//# sourceMappingURL=act-view.d.ts.map
+/**
+ * DOM mutations the browser counted inside the acted element's own subtree.
+ *
+ * Nested under `effect` and OMITTED when zero (the lean-result rule drops uninformative defaults), so
+ * an absent field means zero rather than "not measured" — which is exactly the case that matters.
+ */
+export declare function mutatedWithin(result: Record<string, unknown>): number | undefined;

package/dist/tools/act-view.js

@@ -43,4 +43,16 @@ export function leanActResult(result) {
         return result;
     return { ...r, effect: leanEffect(effect) };
 }
-//# sourceMappingURL=act-view.js.map
+/**
+ * DOM mutations the browser counted inside the acted element's own subtree.
+ *
+ * Nested under `effect` and OMITTED when zero (the lean-result rule drops uninformative defaults), so
+ * an absent field means zero rather than "not measured" — which is exactly the case that matters.
+ */
+export function mutatedWithin(result) {
+    const effect = result['effect'];
+    if (typeof effect !== 'object' || effect === null)
+        return undefined;
+    const value = effect['domMutatedWithin'];
+    return typeof value === 'number' ? value : 0;
+}

package/dist/tools/assert-grade.d.ts

@@ -10,6 +10,7 @@
  *
  * Pure: no IO, no clock.
  */
+import { HonestyGrade } from '../honesty/honesty.js';
 import type { Predicate } from '../events/predicate.js';
 export declare 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 \u2014 or allOf it with one \u2014 so green means the feature actually worked.";
 /**
@@ -17,5 +18,25 @@ export declare const PRESENCE_ONLY_ADVICE = "This predicate only checks element/
  * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something
  * other than presence (route/console/settled), is not flagged.
  */
+/**
+ * Advice for an assertion pinned to a status Reticle derived rather than one a server sent.
+ */
+export declare const DERIVED_IPC_STATUS_ADVICE: string;
+/**
+ * Does this predicate pin an IPC call to a status code?
+ *
+ * The 200/500 on an IPC record is a convenience so `reticle_network { status }` keeps working across
+ * runtimes — it is not something any server sent. An assertion built on it is really an assertion
+ * about Reticle's encoding, and would silently stop meaning what it meant if that encoding changed.
+ * Recognised by the `ipc://` scheme, so a genuine HTTP status is never second-guessed.
+ */
+export declare function assertsDerivedIpcStatus(predicate: Predicate): boolean;
 export declare function isPresenceOnlyAssertion(predicate: Predicate): boolean;
-//# sourceMappingURL=assert-grade.d.ts.map
+/**
+ * The tier a predicate actually proves, for the honesty block on a verdict.
+ *
+ * A signal or a network consequence is evidence the APP produced; a state read is one step removed;
+ * presence of an element is the weakest, because a wrong or healed element can satisfy it. The
+ * verdict carries this so "it passed" is always qualified by what it passed on.
+ */
+export declare function gradeOfPredicate(predicate: Predicate): HonestyGrade;

package/dist/tools/assert-grade.js

@@ -11,6 +11,7 @@
  * Pure: no IO, no clock.
  */
 import { isConsequenceKind, isPresenceKind } from '@reticlehq/core';
+import { HonestyGrade } from '../honesty/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) {
     if (predicate.kind === 'allOf' || predicate.kind === 'anyOf') {
@@ -34,8 +35,52 @@ function walk(predicate) {
  * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something
  * other than presence (route/console/settled), is not flagged.
  */
+/**
+ * Advice for an assertion pinned to a status Reticle derived rather than one a server sent.
+ */
+export const DERIVED_IPC_STATUS_ADVICE = 'This asserts on a status code Reticle DERIVED — IPC has none. Prefer `{ ok: false }`, which ' +
+    'describes what the app did rather than how Reticle encoded it, and cannot drift if that encoding ' +
+    'changes. The `error` field carries the message the main process or Rust command actually returned.';
+/**
+ * Does this predicate pin an IPC call to a status code?
+ *
+ * The 200/500 on an IPC record is a convenience so `reticle_network { status }` keeps working across
+ * runtimes — it is not something any server sent. An assertion built on it is really an assertion
+ * about Reticle's encoding, and would silently stop meaning what it meant if that encoding changed.
+ * Recognised by the `ipc://` scheme, so a genuine HTTP status is never second-guessed.
+ */
+export function assertsDerivedIpcStatus(predicate) {
+    if (predicate.kind === 'allOf' || predicate.kind === 'anyOf') {
+        return predicate.predicates.some(assertsDerivedIpcStatus);
+    }
+    if (predicate.kind === 'not')
+        return assertsDerivedIpcStatus(predicate.predicate);
+    if (predicate.kind !== 'net')
+        return false;
+    return (predicate.status !== undefined &&
+        predicate.ok === undefined &&
+        (predicate.urlContains ?? '').startsWith('ipc://'));
+}
 export function isPresenceOnlyAssertion(predicate) {
     const kinds = walk(predicate);
     return kinds.presence && !kinds.consequence;
 }
-//# sourceMappingURL=assert-grade.js.map
+/**
+ * The tier a predicate actually proves, for the honesty block on a verdict.
+ *
+ * A signal or a network consequence is evidence the APP produced; a state read is one step removed;
+ * presence of an element is the weakest, because a wrong or healed element can satisfy it. The
+ * verdict carries this so "it passed" is always qualified by what it passed on.
+ */
+export function gradeOfPredicate(predicate) {
+    switch (predicate.kind) {
+        case 'signal':
+            return HonestyGrade.SIGNAL;
+        case 'net':
+            return HonestyGrade.NET;
+        case 'state':
+            return HonestyGrade.STATE;
+        default:
+            return HonestyGrade.PRESENCE;
+    }
+}

package/dist/tools/assert-verdict.d.ts

@@ -0,0 +1,21 @@
+import type { Predicate } from '../events/predicate.js';
+import type { Session } from '../session/session.js';
+import { type Contradiction } from '../events/contradictions.js';
+/**
+ * The honesty verdict for a plain `reticle_assert`.
+ *
+ * This is the single field an agent reads, and it was missing from the most-used verdict path.
+ * `act_and_wait` has always returned it; `reticle_assert` returned a bare `pass: true`.
+ *
+ * Measured on a shipments console: a dispatch answered 202 Accepted, the row rendered "dispatched"
+ * optimistically, an assert taken right after the click returned `pass: true` with no caveat, and the
+ * server reverted the write to "held" 1.2s later. The 202 machinery that exists precisely to report
+ * that as `verified: "unknown"` was never reached, because the tool an agent actually calls did not
+ * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
+ * different name: `request-never-settled`, also unreported.
+ */
+export declare function assertVerdict(session: Session, predicate: Predicate, pass: boolean, since: number): Promise<{
+    decision: Record<string, unknown>;
+    contradictions: Contradiction[];
+    coverage: Record<string, unknown>;
+}>;

package/dist/tools/assert-verdict.js

@@ -0,0 +1,62 @@
+import { findContradictions } from '../events/contradictions.js';
+import { blindSpotsFromState, buildCoverageStatement, impeachesCapture, } from '../honesty/blind-spots.js';
+import { buildHonestyBlock } from '../honesty/honesty.js';
+import { hasAcceptedWrite } from '../honesty/accepted-write.js';
+import { hasUnreadWriteOutcome } from '../honesty/unread-outcome.js';
+import { decideVerified } from '../honesty/verified.js';
+import { gradeOfPredicate } from './assert-grade.js';
+/**
+ * The honesty verdict for a plain `reticle_assert`.
+ *
+ * This is the single field an agent reads, and it was missing from the most-used verdict path.
+ * `act_and_wait` has always returned it; `reticle_assert` returned a bare `pass: true`.
+ *
+ * Measured on a shipments console: a dispatch answered 202 Accepted, the row rendered "dispatched"
+ * optimistically, an assert taken right after the click returned `pass: true` with no caveat, and the
+ * server reverted the write to "held" 1.2s later. The 202 machinery that exists precisely to report
+ * that as `verified: "unknown"` was never reached, because the tool an agent actually calls did not
+ * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
+ * different name: `request-never-settled`, also unreported.
+ */
+export async function assertVerdict(session, predicate, pass, since) {
+    // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked per
+    // SESSION, not per assertion window, so a cross-origin iframe seen once marks every later verdict
+    // in that session partial — including ones about a region it cannot affect. That errs toward
+    // over-warning, which is the correct direction here: the failure this guards against is a green
+    // that implies coverage it never had, and a needless caveat costs the agent a sentence.
+    const spots = blindSpotsFromState(session.blindSpots());
+    const statement = buildCoverageStatement(spots);
+    // Omitted entirely when coverage is full, so an intact page pays nothing and the field's PRESENCE
+    // is the warning.
+    const coverage = statement.coverage === 'partial'
+        ? {
+            coverage: statement.note ?? 'partial',
+            coverage_spots: statement.spots.map((sp) => ({ kind: sp.kind, count: sp.count })),
+        }
+        : {};
+    const windowEvents = await session.queryEvents({ since });
+    // Everything before the window, passed as LEARNING material only. A scale error disagrees with a
+    // value the API stated earlier in the session, which an action-scoped window can never contain —
+    // measured live, `observe` over a wide window reported `unit-mismatch` while `assert` on the same
+    // session reported none. Attribution is unchanged: findings still come only from windowEvents.
+    const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
+    const contradictions = findContradictions(windowEvents, { prior });
+    // Only a spot that IMPEACHES the capture downgrades a verdict. A structural boundary (virtualized
+    // rows, a cross-origin frame) is reported as coverage and must not impugn what WAS observed.
+    const impeaching = buildCoverageStatement(spots.filter((sp) => impeachesCapture(sp.kind)));
+    const outcomePending = hasAcceptedWrite(windowEvents);
+    const outcomeUnread = hasUnreadWriteOutcome(windowEvents);
+    const decision = decideVerified({
+        pass,
+        honesty: buildHonestyBlock({
+            grade: gradeOfPredicate(predicate),
+            attribution: 'window',
+            coveragePartial: statement.coverage === 'partial',
+            ...(impeaching.note === undefined ? {} : { blindSpots: [impeaching.note] }),
+        }),
+        contradictions,
+        ...(outcomePending ? { outcomePending } : {}),
+        ...(outcomeUnread ? { outcomeUnread } : {}),
+    });
+    return { decision: decision, contradictions, coverage };
+}

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

@@ -1,3 +1,2 @@
 import type { ToolDef } from './tools.js';
 export declare const BROWSER_TOOLS: ToolDef[];
-//# sourceMappingURL=browser-tools.d.ts.map

package/dist/tools/browser-tools.js

@@ -6,13 +6,14 @@ import { sessionIdShape, commandOrThrow } from './tool-kit.js';
 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). The SDK reconnects automatically after the page loads. Use reticle_sessions to confirm the new tab is connected before acting.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
                 .boolean()
                 .optional()
-                .describe('Reload the current page instead of navigating (replaces reticle_refresh).'),
+                .describe('Reload the current page instead of navigating (replaces the former standalone refresh tool).'),
             hard: z
                 .boolean()
                 .optional()
@@ -73,4 +74,3 @@ export const BROWSER_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=browser-tools.js.map

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

@@ -5,4 +5,3 @@ import type { ToolDef } from './tools.js';
  * live registry to that file (pretty-printed, stable key order — diffable in PRs).
  */
 export declare const CONTRACT_TOOLS: ToolDef[];
-//# sourceMappingURL=contract-tools.d.ts.map

package/dist/tools/contract-tools.js

@@ -64,4 +64,3 @@ export const CONTRACT_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=contract-tools.js.map

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

@@ -0,0 +1,9 @@
+import type { ToolDef } from './tools.js';
+interface Control {
+    ref: string;
+    label: string;
+}
+/** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
+export declare function parseControls(tree: string): Control[];
+export declare const COVERAGE_TOOLS: ToolDef[];
+export {};