@reticlehq/server 2.8.0 → 2.10.0

package/dist/tools/act-tools.js

@@ -1,3 +1,5 @@
+import { normalizeQueryArgs } from './query-shape.js';
+import { resolveTargetRef } from './resolve-target.js';
 /**
  * Action tools — reticle_act, reticle_act_sequence, reticle_act_and_wait. Split out of tools.ts to keep
  * that file under the line cap and assembled back into the tool list there via ...ACT_TOOLS; the
@@ -14,18 +16,19 @@ import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
 import { parsePredicate } from '../events/predicate-parse.js';
 import { causalSummary } from '../capsule/causal-summary.js';
 import { findContradictions } from '../events/contradictions.js';
-import { inFlightRequestLabels, waitForInFlight } from './settle-in-flight.js';
+import { inFlightRequestLabels, repeatedRequestLabels, waitForInFlight, } from './settle-in-flight.js';
 import { waitForReaction } from './react-grace.js';
 import { decideVerified } from '../honesty/verified.js';
+import { declaredExpectations } from '../events/declared.js';
 import { readsDomState } from '../honesty/already-true.js';
 import { describeWaitTarget } from '../honesty/unsettled.js';
 import { saveFailedAssertCapsule } from './act-capsule.js';
 import { buildDivergenceCapsule } from '../capsule/capsule.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { buildHonestyBlock } from '../honesty/honesty.js';
-import { buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
+import { BlindSpotKind, buildCoverageStatement, blindSpotsFromState, transportGapNote, Coverage, impeachesCapture, } from '../honesty/blind-spots.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
-import { hasUnreadWriteOutcome } from '../honesty/unread-outcome.js';
+import { unreadWriteLabels } from '../honesty/unread-outcome.js';
 import { evaluatePredicate, waitForPredicate, provenExpectedLinks, PredicateSchema, } from '../events/predicate.js';
 import { healthEnvelope, refuseIfThrottled } from '../session/session-health.js';
 import { pausedShortCircuit, pausedOutputShape, withControl, PAUSED_NO_VERDICT, } from '../session/control-envelope.js';
@@ -54,20 +57,59 @@ import { tryRealInput } from './real-input-attempt.js';
 const ACTION_TYPE_VALUES = Object.values(ActionType);
 const ACTION_TYPE_LIST = ACTION_TYPE_VALUES.join(' | ');
 const actionTypeEnum = z.enum(ACTION_TYPE_VALUES);
+/**
+ * Resolve an action's element: an explicit `ref`, or a `target` query resolved in the SAME call.
+ *
+ * Requiring a ref meant every verification paid a `reticle_query` turn first just to learn one
+ * string, and the advertised tool surface is re-sent on every turn — measured on the wire, a
+ * two-turn verification spent 10,756 of 11,235 tokens on schema and 479 on the actual answers. The
+ * lookup still happens; it just stops costing a round trip through the model.
+ *
+ * `ref` wins when both are given, because it is the more specific instruction and silently
+ * preferring the query would act on something the caller did not name.
+ */
+async function resolveActTarget(session, args) {
+    const ref = asString(args['ref']);
+    if (ref !== undefined && ref.length > 0)
+        return { kind: 'ref', ref };
+    const target = args['target'];
+    if (target === undefined) {
+        return {
+            kind: 'error',
+            message: 'pass `ref` (from reticle_query/reticle_snapshot) or `target` (e.g. { testid } or { role, name }).',
+        };
+    }
+    const q = normalizeQueryArgs(asRecord(target));
+    const out = await session.command(ReticleCommand.QUERY, {
+        by: q['by'],
+        value: q['value'],
+        name: q['name'],
+        scope: q['scope'],
+    });
+    if (!out.ok)
+        return { kind: 'error', message: out.error ?? 'target query failed' };
+    const elements = asRecord(out.result)['elements'];
+    return resolveTargetRef(Array.isArray(elements) ? elements : []);
+}
 export const ACT_TOOLS = [
     {
         name: ReticleTool.ACT,
         example: { ref: 'e42', action: 'fill', args: { value: 'hello' } },
-        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. 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). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): node_modules/@reticlehq/server/docs/usage.md §18.',
+        description: 'Act WITHOUT checking the result — if the action is supposed to cause something, use reticle_act_and_wait { until } instead and get the verdict in the same call. This tool returns immediately with a `since` cursor; observe the reaction yourself with reticle_observe. Use it for actions with no observable consequence to assert (focus, hover, scrollIntoView, a fill you are about to submit). One action against a ref: click|dblclick|hover|focus|fill|type|clear|select|check|uncheck|submit|press|scrollIntoView. 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. effect.alreadyAtValue=true (check/uncheck only) means the box already read as the requested state, so NOTHING was dispatched and the app was never told — the DOM property is not evidence the application holds that value, so assert the app\'s own state (a signal, a request, a derived control), not the box. 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). args.holdMs keeps the pointer DOWN for that long between mousedown and mouseup — the only way to drive a hold-to-confirm control (hold-to-delete, hold-to-record, long-press); effect.heldMs reports the hold actually achieved, which a throttled background tab can stretch. args.confirmDangerous is a permission gate and NOT a duration: it allows a destructive control, it does not hold one. inputModeReason explains any real→synthetic choice so it is never silent. Full model (real-input, throttled tabs, `reticle drive`): node_modules/@reticlehq/server/docs/usage.md §18.',
         inputSchema: {
             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.`),
+                .optional()
+                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`.`),
+            target: z
+                .record(z.unknown())
+                .optional()
+                .describe('Find the element and act on it in ONE call, instead of a reticle_query round trip first: { testid } | { text } | { role, name } | { label }. Refuses if it matches more than one, rather than guessing.'),
             action: actionTypeEnum.describe(`Action to perform: ${ACTION_TYPE_LIST}`),
             args: z
                 .record(z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration.'),
+                .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 — a Cmd+K), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -107,10 +149,15 @@ export const ACT_TOOLS = [
             if (paused !== undefined)
                 return paused;
             refuseIfThrottled(session, args['refuseWhenThrottled']);
+            // Resolve `target` to a ref BEFORE the action window opens, so the lookup is not attributed to
+            // the act and cannot be mistaken for something the action caused.
+            const targetRef = await resolveActTarget(session, args);
+            if ('error' === targetRef.kind)
+                throw new Error(targetRef.message);
             const since = session.elapsed();
             // The act cursor + effect are marked only once the action has actually DISPATCHED (below, on
             // each success path) — a refused act must leave nothing behind for the next observe to judge.
-            const ref = asString(args['ref']) ?? '';
+            const ref = targetRef.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
             // hover, a drag or any native:true click produced events with no actionId. Session.pushEvent
@@ -140,7 +187,7 @@ export const ACT_TOOLS = [
                     });
                 }
                 const result = await session.command(ReticleCommand.ACT, {
-                    ref: args['ref'],
+                    ref: targetRef.ref,
                     action: args['action'],
                     args: args['args'] ?? {},
                 });
@@ -192,11 +239,18 @@ export const ACT_TOOLS = [
             steps: z
                 .array(z.record(z.unknown()))
                 .describe('Ordered list of { ref, action, args? } objects. Each step is equivalent to one reticle_act call; put confirmDangerous:true in a destructive step args object.'),
+            timeout_ms: z
+                .number()
+                .optional()
+                .describe('Per-step timeout in milliseconds. Default: 8000. Each step gets this budget independently.'),
             ...sessionIdShape,
         },
         outputSchema: {
             since: z.number(),
             dispatched: z.boolean(),
+            completed: z.number(),
+            stalled_at: z.number().optional(),
+            steps: z.array(z.record(z.unknown())).optional(),
             result: z.unknown().optional(),
             session: z
                 .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
@@ -206,33 +260,84 @@ export const ACT_TOOLS = [
         },
         handler: async (deps, args) => {
             const session = deps.sessions.resolve(asString(args['sessionId']));
-            // Live-control: refuse to drive the page while the human has paused us (before any work).
             const paused = pausedShortCircuit(session);
             if (paused !== undefined)
                 return paused;
             const since = session.elapsed();
             session.beginAction(ReticleTool.ACT_SEQUENCE, asRecord(args));
             try {
-                const result = await session.command(ReticleCommand.ACT_SEQUENCE, { steps: args['steps'] });
-                if (!result.ok)
-                    throw new Error(result.error ?? 'act_sequence failed');
-                // Marked only once the sequence ran: a refused sequence must leave no cursor behind for a
-                // later observe to judge. No single action and no in-target measurement here — per-step
-                // effects live in steps[] — so the effect is cleared rather than inherited from an earlier act.
-                session.lastAct.markActed(since, undefined, undefined);
-                if (deps.recordings.active().length > 0) {
-                    deps.recordings.capture(compileSequenceStep(args, result.result));
+                const inputSteps = Array.isArray(args['steps']) ? args['steps'] : [];
+                const perStepTimeout = 'number' === typeof args['timeout_ms'] ? args['timeout_ms'] : 8000;
+                const stepResults = [];
+                let stalledAt;
+                // DIVERGENCE: live sends N individual ACT commands (for per-step timeout + progress);
+                // replay sends one batched ACT_SEQUENCE command (flows/replay.ts:294). A bug in either is
+                // invisible from the other — cover both when changing sequence semantics.
+                for (let i = 0; i < inputSteps.length; i++) {
+                    const step = asRecord(inputSteps[i]);
+                    try {
+                        const result = await session.command(ReticleCommand.ACT, { ref: step['ref'], action: step['action'], args: step['args'] ?? {} }, perStepTimeout);
+                        if (!result.ok) {
+                            stalledAt = i;
+                            stepResults.push({
+                                ref: step['ref'],
+                                action: step['action'],
+                                dispatched: false,
+                                error: result.error ?? 'step failed',
+                            });
+                            break;
+                        }
+                        const r = asRecord(result.result);
+                        const stepResult = {
+                            ref: r['ref'] ?? step['ref'],
+                            action: r['action'] ?? step['action'],
+                            dispatched: r['dispatched'] ?? true,
+                            settled: r['settled'] ?? null,
+                            settleReason: r['settleReason'] ?? null,
+                        };
+                        if (r['testid'] !== undefined)
+                            stepResult['testid'] = r['testid'];
+                        if (r['component'] !== undefined)
+                            stepResult['component'] = r['component'];
+                        if (r['role'] !== undefined)
+                            stepResult['role'] = r['role'];
+                        if (r['name'] !== undefined)
+                            stepResult['name'] = r['name'];
+                        if (r['source'] !== undefined)
+                            stepResult['source'] = r['source'];
+                        if (r['warning'] !== undefined)
+                            stepResult['warning'] = r['warning'];
+                        stepResults.push(stepResult);
+                    }
+                    catch (err) {
+                        stalledAt = i;
+                        stepResults.push({
+                            ref: step['ref'],
+                            action: step['action'],
+                            dispatched: null,
+                            timedOut: true,
+                            error: err instanceof Error ? err.message : 'step timed out',
+                        });
+                        break;
+                    }
+                }
+                const completed = stalledAt ?? inputSteps.length;
+                if (completed > 0) {
+                    session.lastAct.markActed(since, undefined, undefined);
+                }
+                if (deps.recordings.active().length > 0 && stalledAt === undefined) {
+                    deps.recordings.capture(compileSequenceStep(args, { count: inputSteps.length, steps: stepResults }));
                 }
-                const r = asRecord(result.result); // per-step settle status lives in result.steps[]
                 return withControl(session, {
                     since,
-                    dispatched: r['count'] !== undefined,
-                    result: leanActResult(result.result),
+                    dispatched: completed > 0,
+                    completed,
+                    ...(stalledAt !== undefined ? { stalled_at: stalledAt } : {}),
+                    steps: stepResults,
                     ...healthEnvelope(session),
                 });
             }
             finally {
-                // Per-step settle lives in steps[]; the sequence action records without a single settle bool.
                 session.finishAction();
             }
         },
@@ -253,12 +358,17 @@ export const ACT_TOOLS = [
         inputSchema: {
             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.`),
+                .optional()
+                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions. Give this OR \`target\`.`),
+            target: z
+                .record(z.unknown())
+                .optional()
+                .describe('Find the element and act on it in ONE call, instead of a reticle_query round trip first: { testid } | { text } | { role, name } | { label }. Refuses if it matches more than one, rather than guessing.'),
             action: actionTypeEnum.describe(`Action to perform: ${ACTION_TYPE_LIST}`),
             args: z
                 .record(z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control.'),
+                .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.'),
             predicate: PredicateSchema.optional().describe('Alias for `until` (the name reticle_assert / reticle_wait_for use).'),
             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: z
@@ -298,7 +408,7 @@ export const ACT_TOOLS = [
                 .describe('Reaction digest: { window_ms, summary } of what the app did (DOM/network/route/console/signal counts). The full per-event timeline is one reticle_observe { since } away.'),
             summary: z
                 .unknown()
-                .describe('Bounded causal summary: net {total,errors,headline}, consoleErrors, statePathsChanged, storageKeysChanged, stateDiffs [{path,from,to}], storageDiffs [{key,from,to}], route, signals, layoutShift, longTasks — real before→after diffs (capped), not just readings. Every list is length-capped so the verdict can never be the field a client truncates; `elided` says which lists lost entries and how many.'),
+                .describe('Bounded causal summary: net {total,errors,headline}, consoleErrors, statePathsChanged, storageKeysChanged, stateDiffs [{path,from,to}], storageDiffs [{key,from,to}], route, signals, layoutShift, longTasks — real before→after diffs (capped), not just readings. THIS IS THE ANSWER TO "what did that click do": console, network, storage and state for this action are all here, so do NOT follow an act with reticle_console + reticle_network + reticle_state to find out — call them only to go deeper into something this block already pointed at. Every list is length-capped so the verdict can never be the field a client truncates; `elided` says which lists lost entries and how many. `stateUnwatched: true` means NO subscribable store is registered, so an empty stateDiffs means unwatched, NOT unchanged — no state conclusion is available until one is registered.'),
             // Promoted out of `effect` on RED only — the file:line the failure came from, the first thing a
             // repair wants. Undeclared, it was stripped on the validating profile exactly like the structured
             // cause above was, losing the highest-value pointer on the one path (a failed verdict) that has it.
@@ -357,6 +467,11 @@ export const ACT_TOOLS = [
             // Before anything is driven: this path cannot honour a native-input request, and taking the
             // argument and ignoring it told the agent its trusted click had happened. See act-danger.
             assertNativeInputSupported(asRecord(args['args']));
+            // Resolve `target` to a ref BEFORE the action window opens, so the lookup is not attributed to
+            // the act and cannot be mistaken for something the action caused.
+            const resolved = await resolveActTarget(session, args);
+            if ('error' === resolved.kind)
+                throw new Error(resolved.message);
             const since = session.elapsed();
             // The cursor + effect are marked after the act dispatches (below) — a refused act leaves none.
             // The attribution window stays open across the settle wait below, so post-dispatch async events
@@ -372,7 +487,7 @@ export const ACT_TOOLS = [
                 : false;
             try {
                 const actResult = await session.command(ReticleCommand.ACT, {
-                    ref: args['ref'],
+                    ref: resolved.ref,
                     action: args['action'],
                     args: args['args'] ?? {},
                 });
@@ -444,6 +559,9 @@ export const ACT_TOOLS = [
                 // verdict didn't see everything — say so, never imply full coverage.
                 const spots = blindSpotsFromState(session.blindSpots());
                 const coverage = buildCoverageStatement(spots);
+                // Nothing subscribed ⇒ the state channel is dark, and the summary must say so rather than
+                // report an empty diff list that reads like a fact about the app. See CausalSummary.
+                const stateUnwatched = spots.some((s) => s.kind === BlindSpotKind.UNWATCHED_STATE && s.count > 0);
                 // 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.
@@ -475,6 +593,9 @@ export const ACT_TOOLS = [
                     // evictions that happened outside the window they impeached.
                     truncated: bufferLost,
                     coveragePartial: Coverage.PARTIAL === coverage.coverage,
+                    // Settlement no longer vetoes a declared consequence that held, so the fact is carried
+                    // here instead of only in the verdict it used to decide. Omitted when never measured.
+                    ...(settledOutcome === undefined ? {} : { settled: settledOutcome }),
                     ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
                     losses,
                 });
@@ -503,18 +624,30 @@ export const ACT_TOOLS = [
                 //
                 // `actionSince` is the window's own floor here, which is the tightest attribution there is —
                 // and it is what lets `duplicate-request` claim "one user action was performed" and mean it.
+                // What the caller DECLARED before acting, handed to the detector that would otherwise judge
+                // the window as if nobody had said what they expected. See events/declared.ts.
+                const declared = declaredExpectations(until);
                 const contradictions = findContradictions(windowEvents, {
                     action: acted,
                     prior,
                     actionSince: since,
+                    expectedFailures: declared.netFailures,
+                    // A consequence that was already true before the action proves nothing about it, so it is
+                    // not evidence the destination rendered either — `alreadyTrue` decides that, once.
+                    renderProved: verdict.pass && !alreadyTrue && declared.rendersContent,
                     ...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 outcomeUnread = unreadWriteLabels(windowEvents);
                 const decision = decideVerified({
                     pass: verdict.pass,
+                    // The caller NAMED the consequence rather than defaulting to "wait for idle". A
+                    // declaration made before the action is what this tool sells, and idle-settlement was
+                    // overriding it — see `declaredConsequence`. An explicit `{ kind: "settled" }` is not a
+                    // declaration about the app's behaviour, it IS the idle wait, so it does not count.
+                    declaredConsequence: until.kind !== PredicateKind.SETTLED,
                     ...(alreadyTrue ? { alreadyTrue } : {}),
                     // An assertion nobody could evaluate must not be reported as one the app failed.
                     ...(verdict.inconclusive === undefined ? {} : { inconclusive: verdict.inconclusive }),
@@ -525,7 +658,7 @@ export const ACT_TOOLS = [
                     honesty,
                     contradictions,
                     ...(outcomePending ? { outcomePending } : {}),
-                    ...(outcomeUnread ? { outcomeUnread } : {}),
+                    ...(outcomeUnread.length > 0 ? { 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 }),
@@ -535,6 +668,8 @@ export const ACT_TOOLS = [
                     unsettled: {
                         waitedFor: describeWaitTarget(until),
                         stillInFlight: inFlightRequestLabels(windowEvents),
+                        // The retry loop that leaves nothing outstanding — see repeatedRequestLabels.
+                        repeated: repeatedRequestLabels(windowEvents),
                     },
                 });
                 return withControl(session, {
@@ -549,7 +684,9 @@ export const ACT_TOOLS = [
                         : { source: `${actedSource.file}:${String(actedSource.line)}` }),
                     trace,
                     ...(capsuleSaved === undefined ? {} : { capsuleSaved }),
-                    summary: causalSummary(windowEvents),
+                    // The window cannot say whether anything was WATCHING state — that is a level fact the
+                    // session holds. Without it an empty `stateDiffs` reads as "the app changed nothing".
+                    summary: causalSummary(windowEvents, { stateUnwatched }),
                     // 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,

package/dist/tools/assert-verdict.js

@@ -1,13 +1,25 @@
-import { CaptureLoss } from '@reticlehq/core';
+import { BlindSpotKind, CaptureLoss, PredicateKind } from '@reticlehq/core';
 import { findContradictions } from '../events/contradictions.js';
+import { declaredExpectations } from '../events/declared.js';
 import { blindSpotsFromState, buildCoverageStatement, Coverage, impeachesCapture, transportGapNote, } 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 { unreadWriteLabels } from '../honesty/unread-outcome.js';
 import { decideVerified } from '../honesty/verified.js';
 import { describeWaitTarget } from '../honesty/unsettled.js';
-import { inFlightRequestLabels } from './settle-in-flight.js';
+import { inFlightRequestLabels, repeatedRequestLabels } from './settle-in-flight.js';
 import { gradeOfPredicate } from './assert-grade.js';
+function absenceBlindSpotNote(predicate, spots) {
+    if (predicate.kind !== 'element' || predicate.absent !== true)
+        return undefined;
+    const relevant = spots.filter((spot) => spot.count > 0 &&
+        spot.kind === BlindSpotKind.CROSS_ORIGIN_IFRAME &&
+        undefined !== predicate.query.scope);
+    if (0 === relevant.length)
+        return undefined;
+    const statement = buildCoverageStatement(relevant);
+    return `the absence assertion targeted a region Reticle could not observe (${statement.note ?? 'partial coverage'}), so a passing DOM check cannot prove absence`;
+}
 /**
  * The honesty verdict for a plain `reticle_assert`.
  *
@@ -37,6 +49,7 @@ observationLost) {
     // that implies coverage it never had, and a needless caveat costs the agent a sentence.
     const spots = blindSpotsFromState(session.blindSpots());
     const statement = buildCoverageStatement(spots);
+    const absenceBlindSpot = absenceBlindSpotNote(predicate, spots);
     // Omitted entirely when coverage is full, so an intact page pays nothing and the field's PRESENCE
     // is the warning.
     const coverage = Coverage.PARTIAL === statement.coverage
@@ -57,12 +70,18 @@ observationLost) {
     // could show it did. An assert taken over a window that predates the act attributes nothing, and the
     // rule then stays quiet.
     const actCursor = session.lastAct.cursor();
+    // The same declaration the act path reads. `reticle_assert` is the other half of the verdict
+    // surface, and an error path declared here deserves the same answer it gets there — a fix that
+    // lived only on the act path would leave the sibling caller broken.
+    const declared = declaredExpectations(predicate);
     const contradictions = findContradictions(windowEvents, {
         prior,
+        expectedFailures: declared.netFailures,
+        renderProved: pass && declared.rendersContent,
         ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
     });
-    // 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.
+    // Only a spot that IMPEACHES the capture downgrades a general verdict. Structural boundaries are
+    // reported as coverage; the narrower absence exception is computed separately above.
     const impeaching = buildCoverageStatement(spots.filter((sp) => impeachesCapture(sp.kind)));
     // A gap in the WINDOW, as opposed to a standing limit of the page. Both mean the same thing to the
     // rule — part of what happened was not seen — so both belong in `blindSpots`, which is the only
@@ -70,11 +89,16 @@ observationLost) {
     const gap = transportGapNote(windowEvents);
     const impeachingNotes = [impeaching.note, gap].filter((n) => n !== undefined);
     const outcomePending = hasAcceptedWrite(windowEvents);
-    const outcomeUnread = hasUnreadWriteOutcome(windowEvents);
+    const outcomeUnread = unreadWriteLabels(windowEvents);
     const decision = decideVerified({
         pass,
+        // Same rule as the act path: the caller named a consequence, so a settlement-only finding must
+        // not override it. A fix that lived on one half of the verdict surface would leave the other
+        // half broken, and this is the tool agents call most.
+        declaredConsequence: predicate.kind !== PredicateKind.SETTLED,
         ...(inconclusive === undefined ? {} : { inconclusive }),
         ...(true === observationLost ? { observationLost: true } : {}),
+        ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
         honesty: buildHonestyBlock({
             grade: gradeOfPredicate(predicate),
             attribution: 'window',
@@ -89,12 +113,13 @@ observationLost) {
         }),
         contradictions,
         ...(outcomePending ? { outcomePending } : {}),
-        ...(outcomeUnread ? { outcomeUnread } : {}),
+        ...(outcomeUnread.length > 0 ? { outcomeUnread } : {}),
         // Same detail the act path supplies: this route reaches UNSETTLED through an absence-derived
         // contradiction, and "the window closed before the app finished" is no more actionable here.
         unsettled: {
             waitedFor: describeWaitTarget(predicate),
             stillInFlight: inFlightRequestLabels(windowEvents),
+            repeated: repeatedRequestLabels(windowEvents),
         },
     });
     return { decision: decision, contradictions, coverage };

package/dist/tools/browser-tools.js

@@ -39,6 +39,12 @@ export const BROWSER_TOOLS = [
             // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
             if (true === args['reload']) {
                 const before = deps.sessions.resolve(asString(args['sessionId']));
+                // The verdict floor moves HERE, before the page goes away. A reload destroys the document,
+                // so every request that failed under the old one belongs to a page that no longer exists —
+                // and a later assert defaulting its window to "the last thing that happened" must not reach
+                // 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());
                 await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
                     hard: true === args['hard'],
                 });
@@ -65,6 +71,10 @@ export const BROWSER_TOOLS = [
             // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
             const session = deps.sessions.resolve(asString(args['sessionId']));
             session.beginAction(ReticleTool.NAVIGATE, { url });
+            // Same floor as the reload path above, for the same reason: going to a new URL replaces the
+            // 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());
             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.

package/dist/tools/dynamic-tools.js

@@ -65,16 +65,17 @@ export function buildDynamicTools(allTools, profile) {
         : {
             profile: {
                 ...profile,
-                // NOT "every tool is reachable via reticle_run under any profile" — measured false:
-                // `full` advertises all 46 tools DIRECTLY and carries no meta-tools at all, so
-                // reticle_run does not exist there. Saying otherwise sends the agent to a tool the
-                // profile does not have.
-                note: `The profile is read once at daemon startup: change ${TOOL_PROFILE_ENV} and restart the daemon, or it has no effect. Under this profile every unadvertised tool is reachable through reticle_run; under \`full\` there are no meta-tools because every tool is advertised directly.`,
+                // This used to say `full` carries no meta-tools because it advertised everything
+                // directly. That stopped being true when the advertised surface was capped: no surface
+                // advertises the whole registry any more, so BOTH meta-tools are on every surface and
+                // reticle_run is always the way to the tail. The old wording would now send an agent
+                // away from the only tool that can reach half the registry.
+                note: `The surface is read once at daemon startup: change ${TOOL_PROFILE_ENV} and restart the daemon, or it has no effect. No surface advertises every tool — the advertised count is capped because editors budget tools across all connected MCP servers. Every tool listed here is callable through reticle_run { tool, args } whether or not it is advertised.`,
             },
         };
     const reticleTools = {
         name: ReticleTool.TOOLS,
-        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_flow_verify (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
+        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_verify{action:"flows"} (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
         inputSchema: {
             names: z
                 .array(z.string())
@@ -86,10 +87,18 @@ export function buildDynamicTools(allTools, profile) {
                 ? args['names'].filter((n) => 'string' === typeof n)
                 : undefined;
             if (names === undefined || 0 === names.length) {
+                // The COUNT is stated, not just implied by the array length. An agent that can see 18 tools
+                // has no way to know whether that is all of them; being told the registry holds more is what
+                // turns "these are the tools" into "these are the tools I was shown".
+                const catalog = allTools.map((t) => ({
+                    name: t.name,
+                    summary: firstSentence(t.description),
+                }));
                 return Promise.resolve({
-                    tools: allTools.map((t) => ({ name: t.name, summary: firstSentence(t.description) })),
+                    total: catalog.length,
+                    tools: catalog,
                     ...profileBlock,
-                    next: 'Load params with reticle_tools { names:[…] }, then call reticle_run { tool, args }.',
+                    next: `All ${catalog.length} tools above are callable, advertised or not. Load full params with reticle_tools { names:[…] }, then call reticle_run { tool, args }.`,
                 });
             }
             return Promise.resolve({

package/dist/tools/error-recovery.js

@@ -56,10 +56,12 @@ function isSelfRecovering(message) {
 }
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
 export const RECOVERY = {
-    NO_SESSION: 'No app is connected to Reticle. Ask the human to start their app in dev with @reticlehq/browser ' +
-        'enabled, then run `reticle status` to confirm a session appears. If the app is running but no ' +
-        'session shows, the SDK is not reaching the bridge — check the dev server is up and using the ' +
-        'configured Reticle port.',
+    NO_SESSION: "No app is connected to Reticle. If nothing is serving the app, start the project's own dev " +
+        'script (from its package.json) in the BACKGROUND yourself and tell the human in one line that ' +
+        'it is running and how to stop it — never a second server, never a guessed command, never kill ' +
+        'anything. Then run `reticle status` to confirm a session appears. If the app IS running and no ' +
+        'session shows, the SDK is not reaching the bridge — check @reticlehq/browser is loaded in the ' +
+        'page and that both sides use the configured Reticle port.',
     MULTIPLE_SESSIONS: 'Several tabs are connected. Call reticle_sessions to list them, then pass an explicit sessionId to ' +
         'target the one you mean.',
     UNKNOWN_SESSION: 'That sessionId is not connected. Call reticle_sessions for the current ids and retry with a valid one.',
@@ -121,11 +123,13 @@ export const RECOVERY = {
     COMMAND_TIMEOUT: 'The page did not answer within the command window. That is a fact about the page, not a Reticle ' +
         'failure: check reticle_sessions for `throttled`/`stale` on this session — a backgrounded tab is ' +
         'throttled and may never answer, so ask the human to bring it to the front or drive your own ' +
-        'browser with reticle_lease. If the tab is in front, the page is busy or blocked (a long ' +
+        'browser with reticle_run { tool: "reticle_lease", action: "acquire", url } — reticle_lease is ' +
+        'not advertised under the default profile, so it is reached through reticle_run, not called ' +
+        'directly. If the tab is in front, the page is busy or blocked (a long ' +
         'synchronous task, an alert/confirm dialog); reticle_console usually shows what it hit. Retry ' +
         'once the cause is addressed.',
     FLOW_STEP_MISSING: 'A recorded step points at an element that is not on the page now. Either the app changed under ' +
-        'the flow — run reticle_flow_heal to re-anchor it, then reticle_flow_verify — or an earlier step ' +
+        'the flow — run reticle_flow_heal to re-anchor it, then reticle_verify{action:"flows"} — or an earlier step ' +
         'did not do what it used to, leaving the run on the wrong page: check reticle_snapshot to see ' +
         'where it actually is. This is app/flow drift, which is exactly what the flow exists to catch.',
     NO_POOL: 'Reticle cannot launch its own browser here: the daemon-managed pool is absent, or Playwright ' +