@reticlehq/server 2.7.0 → 2.9.0

package/dist/temp-dir.js

@@ -0,0 +1,46 @@
+/**
+ * Removing a temp directory on Windows, without inventing a product failure.
+ *
+ * `rm(dir, { recursive: true, force: true })` is the obvious teardown and it is not enough on
+ * Windows. Deletion there is not immediate: a handle the OS, the indexer or a virus scanner still
+ * holds keeps the entry alive for a moment after the last close, so the directory is observed
+ * non-empty at the instant `rmdir` runs and Node throws `ENOTEMPTY`. `force` does not cover it —
+ * that suppresses "missing", not "busy".
+ *
+ * The failure lands in `afterEach`, so it is reported against the test that just PASSED, and the
+ * leftover directory then bleeds state into what runs next. On CI this presented as five failures in
+ * one file, four of them consequential and one of them the wonderfully misleading "expected length 1
+ * but got 2" — a fake production bug manufactured entirely by teardown. This repo already has that
+ * exact story written up in `project-store.test.ts` about a timed-out test's stray writes; this is the
+ * same failure arriving through the filesystem instead of through the clock.
+ *
+ * `maxRetries`/`retryDelay` exist in Node for precisely this, and are documented as Windows-oriented.
+ * They are a no-op on POSIX, where the first attempt already succeeds.
+ */
+import { rm } from 'node:fs/promises';
+/**
+ * Retries and backoff. Small and bounded: this is covering a millisecond-scale handle release, so if
+ * it has not gone in half a second the cause is not a race and a slower retry would only hide it.
+ */
+const MAX_RETRIES = 10;
+const RETRY_DELAY_MS = 50;
+/**
+ * Delete a temp directory tree, tolerating Windows' delayed handle release.
+ *
+ * Never throws: a temp directory that outlives the test is the operating system's problem, not a
+ * reason to fail a run or to report a defect the product does not have. What must not happen is the
+ * opposite — a red that says nothing about the code under test.
+ */
+export async function removeTempDir(dir) {
+    try {
+        await rm(dir, {
+            recursive: true,
+            force: true,
+            maxRetries: MAX_RETRIES,
+            retryDelay: RETRY_DELAY_MS,
+        });
+    }
+    catch {
+        // Deliberately swallowed — see above. The OS reclaims the temp directory regardless.
+    }
+}

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,15 +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, 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';
@@ -51,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()
@@ -104,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
@@ -137,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'] ?? {},
                 });
@@ -189,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() })
@@ -203,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();
             }
         },
@@ -250,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
@@ -295,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.'),
+                .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.
@@ -354,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
@@ -369,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'] ?? {},
                 });
@@ -380,9 +498,39 @@ export const ACT_TOOLS = [
                 // stops the spread below from inheriting an earlier reticle_act's action and mutation count.
                 session.lastAct.markActed(since, asString(args['action']), mutatedWithin(asRecord(actResult.result)));
                 // Honesty: floor the predicate at this act's cursor so a stale buffered event can't satisfy it.
+                const predicateStarted = session.elapsed();
                 const verdict = timeout > 0
                     ? await waitForPredicate(session, until, timeout, since)
                     : await evaluatePredicate(session, until, since);
+                // 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.
+                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 r = asRecord(actResult.result);
                 if ('boolean' === typeof r['settled'])
                     settledOutcome = r['settled'];
@@ -411,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.
@@ -442,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,
                 });
@@ -467,17 +621,33 @@ export const ACT_TOOLS = [
                 // Learning material only. Attribution is unchanged — findings still come exclusively from
                 // `windowEvents`, exactly as on the assert path.
                 const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
+                //
+                // `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 }),
@@ -488,10 +658,19 @@ 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 }),
+                    // What the wait was for and what was still outstanding when it ended. Read only by the
+                    // UNSETTLED clauses; supplied always because both of them are reachable from here and the
+                    // window is already in hand.
+                    unsettled: {
+                        waitedFor: describeWaitTarget(until),
+                        stillInFlight: inFlightRequestLabels(windowEvents),
+                        // The retry loop that leaves nothing outstanding — see repeatedRequestLabels.
+                        repeated: repeatedRequestLabels(windowEvents),
+                    },
                 });
                 return withControl(session, {
                     ...decision,
@@ -505,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-grade.d.ts

@@ -12,7 +12,7 @@
  */
 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.";
+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 (or allOf it with one) so green means the feature actually worked.";
 /**
  * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere
  * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something

package/dist/tools/assert-grade.js

@@ -12,24 +12,46 @@
  */
 import { isConsequenceKind, isPresenceKind, PredicateKind } 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) {
+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) {
     if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
-        const subs = predicate.predicates.map(walk);
+        const subs = predicate.predicates.map((p) => walk(p, negated));
         return {
             consequence: subs.some((s) => s.consequence),
             presence: subs.some((s) => s.presence),
         };
     }
+    // Under a NOT, checking content strengthens nothing, so the exemption below must not apply. The
+    // nudge warns that a healed or wrong locator can satisfy the predicate, and for an ABSENCE claim a
+    // wrong locator satisfies it trivially: "the error message is gone" is true of a selector that
+    // never matched anything in the first place. Negation makes a presence check weaker, not stronger.
     if (PredicateKind.NOT === predicate.kind)
-        return walk(predicate.predicate);
+        return walk(predicate.predicate, true);
     // 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 {
         consequence: isConsequenceKind(predicate.kind),
-        presence: isPresenceKind(predicate.kind),
+        presence: isPresenceKind(predicate.kind) && (negated || !assertsElementContent(predicate)),
     };
 }
+/**
+ * An element predicate that checks the element's CONTENT, not merely that it is there.
+ *
+ * The presence nudge exists because "a locator healed to the wrong element, or a stale render, can
+ * satisfy this while the feature is broken". That is exactly true of `{ element, role, name }` and
+ * exactly false of `{ element, role, name, value: "274.58" }`: a wrong element now has to carry the
+ * same value to pass, which is the thing the nudge is warning cannot be relied on.
+ *
+ * Kept as a nudge-level distinction rather than a new honesty grade. The grade still reads
+ * `presence`, which UNDERSTATES what was proved, and understating is the safe direction for a field
+ * whose whole job is to qualify a green. Telling an agent that a value check "only checks presence"
+ * is the direction that costs something: it argues for replacing an assertion that is already sound.
+ */
+function assertsElementContent(predicate) {
+    if (predicate.kind !== PredicateKind.ELEMENT)
+        return false;
+    return predicate.query?.value !== undefined || predicate.query?.text !== undefined;
+}
 /**
  * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere
  * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something

package/dist/tools/assert-verdict.js

@@ -1,11 +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, 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`.
  *
@@ -35,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
@@ -49,9 +64,24 @@ observationLost) {
     // 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.
+    // The last act, when it falls inside the window being judged. Without it `duplicate-request` counted
+    // `method + url` across whatever window the caller asked for, so two legitimate separate saves to one
+    // endpoint were reported as a double submit — the instrument accusing the app of something nobody
+    // 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 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
@@ -59,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',
@@ -78,7 +113,14 @@ 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 };
 }